커스텀 스토리지

Capgo는 앱 번들을 위한 커스텀 스토리지 솔루션을 지원하여, 자체 인프라나 제3자 스토리지 서비스에 업데이트를 호스팅할 수 있습니다. 이는 특정 보안 요구 사항, 컴플라이언스 준수 또는 기존 스토리지 인프라를 보유한 기업에 특히 유용합니다.

개요

Capgo의 커스텀 스토리지는 번들을 외부 위치에 업로드하고 Capgo에 해당 URL을 제공하는 방식으로 작동합니다. 그러면 Capgo SDK가 Capgo의 기본 클라우드 스토리지 대신 커스텀 스토리지 위치에서 직접 업데이트를 다운로드합니다.

팁

커스텀 스토리지는 다음 경우에 이상적입니다:

• 엄격한 데이터 레지던시 요구사항이 있는 조직
• 기존 CDN 또는 스토리지 인프라를 보유한 팀
• 추가적인 보안 계층이 필요한 애플리케이션
• 대용량 번들 사이즈에 대한 비용 최적화

외부 URL 업로드

커스텀 스토리지의 가장 간단한 사용 방법은 번들을 공개 URL에 업로드한 뒤, 해당 URL을 Capgo에 제공하는 것입니다.

기본 외부 URL 업로드

npx @capgo/cli@latest bundle upload --external https://your-domain.com/bundles/v1.2.3.zip

이 명령은 Capgo가 번들을 Capgo의 클라우드 스토리지에 업로드하는 대신 지정된 URL의 번들을 참조하도록 합니다.

암호화 적용

외부 스토리지를 안전하게 사용하려면 번들을 암호화하고 복호화 키를 제공할 수 있습니다:

npx @capgo/cli@latest bundle upload --external https://your-domain.com/bundles/v1.2.3.zip --iv-session-key YOUR_IV_SESSION_KEY

S3 연동

Capgo는 Amazon S3 및 S3 호환 스토리지 서비스를 기본으로 지원합니다. CLI은 번들을 S3에 자동으로 업로드하고 Capgo가 S3 URL을 사용하도록 설정할 수 있습니다.

S3 업로드 옵션

npx @capgo/cli@latest bundle upload \
  --s3-region us-east-1 \
  --s3-apikey YOUR_ACCESS_KEY \
  --s3-apisecret YOUR_SECRET_KEY \
  --s3-bucket-name your-bucket-name

S3 설정 완료

S3 호환 서비스 또는 커스텀 엔드포인트의 경우:

npx @capgo/cli@latest bundle upload \
  --s3-region us-east-1 \
  --s3-apikey YOUR_ACCESS_KEY \
  --s3-apisecret YOUR_SECRET_KEY \
  --s3-endpoint https://s3.your-provider.com \
  --s3-bucket-name your-bucket-name \
  --s3-port 443 \
  --no-s3-ssl  # Only if your endpoint doesn't support SSL

S3 설정 파라미터

파라미터	설명	필수
--s3-region	S3 버킷의 AWS 리전	지원
--s3-apikey	S3 액세스 키 ID	지원
--s3-apisecret	S3 secret access key	지원
--s3-bucket-name	S3 버킷 이름	지원
--s3-endpoint	커스텀 S3 엔드포인트 URL	아니요
--s3-port	S3 엔드포인트 포트	아니요
--no-s3-ssl	S3 upload 시 SSL 비활성화	아니요

Bundle 준비 및 암호화

커스텀 스토리지, 특히 암호화를 사용하는 경우 번들을 적절히 준비해야 합니다. 여기에는 zip 파일을 생성하고 선택적으로 암호화하는 과정이 포함됩니다.

1단계: Zip Bundle 생성

먼저, 앱 번들을 zip 파일로 만듭니다:

npx @capgo/cli@latest bundle zip com.example.app --path ./dist

zip 명령어를 실행하면 zip 파일의 checksum이 반환됩니다. 필요에 따라 이 checksum을 사용하여 zip 파일을 암호화할 수 있습니다. checksum을 포함한 구조화된 출력을 받으려면 --json 옵션을 사용하세요.

Zip 명령어 옵션

npx @capgo/cli@latest bundle zip [appId] \
  --path ./dist \
  --bundle 1.2.3 \
  --name myapp-v1.2.3 \
  --json \
  --no-code-check \
  --key-v2 \
  --package-json ../../package.json,./package.json

옵션	설명
--path	압축할 폴더 경로 (capacitor.config의 webDir이 기본값)
--bundle	zip 파일명에 사용할 Bundle 버전 번호
--name	zip 파일의 사용자 지정 이름
--json	JSON 형식으로 결과 출력 (checksum 포함)
--no-code-check	notifyAppReady() 호출 및 index 파일 확인 건너뛰기
--key-v2	encryption v2 사용
--package-json	모노레포용 package.json 파일 경로 (쉼표로 구분)

2단계: Bundle 암호화 (선택 사항)

보안을 강화하려면 업로드 전에 zip 번들을 암호화하세요:

# Using default local key
npx @capgo/cli@latest bundle encrypt ./myapp.zip CHECKSUM

# Using custom key file
npx @capgo/cli@latest bundle encrypt ./myapp.zip CHECKSUM --key ./path/to/.capgo_key_v2

# Using key data directly
npx @capgo/cli@latest bundle encrypt ./myapp.zip CHECKSUM --key-data "PRIVATE_KEY_CONTENT"

이 CHECKSUM parameter는 필수이며 zip 파일의 체크섬이어야 합니다. zip 명령의 출력 결과에서 체크섬을 가져올 수 있습니다 (구조화된 출력을 위해 --json 옵션을 사용하세요).

기본적으로 encrypt 명령은 로컬 개인 서명 키를 사용합니다. 다음 --key 또는 --key-data options.

encrypt 명령은 다음을 반환합니다: ivSessionKey 업로드 또는 복호화에 필요합니다.

암호화 명령 옵션

옵션	설명
zipPath	암호화할 zip 파일 경로 (필수)
checksum	zip 파일의 체크섬 (필수) - zip 명령어에서 확인
--key	개인 서명 키의 사용자 지정 경로 (선택 사항, 기본적으로 로컬 키 사용)
--key-data	개인 서명 키 데이터 직접 입력 (선택 사항)
--json	결과를 JSON 형식으로 출력

주의

encrypt 명령은 다음을 출력합니다 ivSessionKey 를 사용하여 upload할 때 제공해야 하는 --iv-session-key 옵션입니다.

전체 워크플로우 예시

예제 1: 암호화된 외부 URL

1. 앱 빌드:

   npm run build

2. zip bundle 생성:

   npx @capgo/cli@latest bundle zip com.example.app --path ./dist --bundle 1.2.3

   이 명령어가 반환하는 checksum을 기록해 두세요.

3. 번들 암호화:

   npx @capgo/cli@latest bundle encrypt ./com.example.app-1.2.3.zip CHECKSUM_FROM_STEP_2

   다음 내용을 ivSessionKey 출력 결과에서 확인하세요.

4. 스토리지에 업로드: 암호화된 zip 파일을 호스팅 서비스에 업로드하세요.

5. Capgo에 등록:

   npx @capgo/cli@latest bundle upload \
     --external https://your-cdn.com/bundles/com.example.app-1.2.3.zip \
     --iv-session-key IV_SESSION_KEY_FROM_STEP_3

예시 2: S3 직접 업로드

1. 앱 빌드:

   npm run build

2. S3로 직접 업로드:

   npx @capgo/cli@latest bundle upload \
     --s3-region us-west-2 \
     --s3-apikey YOUR_ACCESS_KEY \
     --s3-apisecret YOUR_SECRET_KEY \
     --s3-bucket-name your-app-bundles \
     --channel Production

예제 3: 암호화된 S3

1. 빌드 및 압축:

   npm run build
   npx @capgo/cli@latest bundle zip com.example.app --path ./dist --key-v2

2. 번들 암호화:

   npx @capgo/cli@latest bundle encrypt ./com.example.app.zip CHECKSUM

3. 암호화하여 S3에 업로드:

   npx @capgo/cli@latest bundle upload \
     --s3-region us-west-2 \
     --s3-apikey YOUR_ACCESS_KEY \
     --s3-apisecret YOUR_SECRET_KEY \
     --s3-bucket-name your-app-bundles \
     --iv-session-key IV_SESSION_KEY_FROM_STEP_2 \
     --channel Production

보안 고려 사항

커스텀 스토리지 사용 시 다음 보안 모범 사례를 고려하세요:

접근 제어

• 스토리지 URL이 앱 사용자에게는 접근 가능하되, 공개적으로 검색되지 않도록 설정하세요
• 가능한 경우 서명된 URL 또는 토큰 기반 인증을 사용하세요
• 웹 기반 앱에는 적절한 CORS 헤더를 구현하세요

암호화

• 민감한 번들은 항상 Capgo 암호화 도구를 사용하여 암호화하세요
• 암호화 키를 안전하게 보관하고 정기적으로 교체하세요
• 모든 번들 URL에 HTTPS를 사용하세요 (모바일 및 Electron 앱 필수)

모니터링

• 액세스 로그를 모니터링하여 비정상적인 다운로드 패턴을 감지하세요
• 번들 다운로드 실패에 대한 알림을 설정하세요
• 스토리지 권한을 정기적으로 감사하세요

문제 해결

자주 발생하는 문제

Bundle 다운로드 실패:

• URL이 공개적으로 접근 가능한지, HTTPS를 사용하는지 확인하세요 (모바일 및 Electron 앱 필수)
• 웹 앱의 경우 CORS 헤더를 확인하세요
• Bundle 형식이 올바른지 확인하세요

암호화 오류:

• 다음 사항을 확인하세요: ivSessionKey 암호화된 bundle과 일치하는지
• Bundle이 올바른 키로 암호화되었는지 확인하세요
• 새 번들에 encryption v2가 사용되는지 확인하세요

S3 upload 실패:

• S3 자격 증명 및 권한을 확인하세요
• 버킷 정책 및 CORS 설정을 확인하세요
• 지정된 리전이 올바른지 확인하세요

디버그 명령어

번들 상태 확인:

npx @capgo/cli@latest app debug

번들 무결성 확인:

npx @capgo/cli@latest bundle list

다음 단계

• 자세히 알아보기 채널 다양한 배포 환경을 관리하려면
• 둘러보기 업데이트 동작 업데이트 적용 방식을 커스텀하려면
• 설정하기 CI/CD 통합 커스텀 스토리지 워크플로우를 자동화하려면

Custom Storage 다음 단계

사용 중이라면 커스텀 스토리지 보안 및 컴플라이언스 계획을 세우려면, 다음 항목과 연결하세요: 암호화 암호화 구현 상세 정보: 컴플라이언스 컴플라이언스 구현 상세 정보: Capgo 보안 스캐너 Capgo Security Scanner 제품 워크플로우: Capgo 보안 Capgo Security 제품 워크플로우 및 Capgo 신뢰 센터 Capgo Trust Center 제품 워크플로우: