콘텐츠로 건너뛰기
Capgo

명령

사용법

모든 명령어는 Capacitor 프로젝트가 올바르게 설정된 앱 폴더에서 실행되어야 합니다.

Capacitor 웹 앱을 위한 크로스 플랫폼 네이티브 런타임

초기화

npx @capgo/cli@latest init [apikey]

이 메서드는 단계별로 온보딩을 도와줍니다.

앱을 Capgo에 추가하고, 업데이트를 검증하는 코드를 앱에 추가하며, 앱을 빌드하고, Capgo에 업로드한 후 업데이트가 제대로 작동하는지 확인하는 것을 도와줍니다.

로그인

npx @capgo/cli login [apikey]

이 메서드는 apikey를 기억하는데 사용됩니다.

선택적으로 다음을 제공할 수 있습니다:

--local 로컬 저장소에 apikey를 저장하고 git에서 무시합니다.

진단

npx @capgo/cli doctor

Capgo 패키지가 최신 상태인지 확인하는 명령어입니다.

이 명령어는 버그 리포트에도 유용합니다.

앱

추가

npx @capgo/cli app add [appId]

[appId] 앱 ID의 형식 comtestapp은 여기에서 설명됩니다.

💡 제공되지 않은 모든 옵션은 설정에서 추측됩니다.

선택적으로 다음을 제공할 수 있습니다:

  • --icon [/path/to/my/icon] Capgo 웹 앱에 표시될 사용자 정의 아이콘
  • --name [test] 목록에 표시될 사용자 정의 이름
  • --apikey [key] 계정에 연결할 API 키
  • --retention [retention] 앱 번들의 보관 기간(일), 기본값 0 = 무제한

appId와 AppName을 위한 capacitorconfigjson 예시, 아이콘은 resources 폴더에서 추측됩니다.

{
  "appId": "eeforgrcapacitor_go",
  "appName": "Capgo",
  "webDir": "dist"
}

[나머지 번역은 동일한 형식으로 계속됩니다…]* --keep [numberToKeep] 유지하고자 하는 패키지 수 (기본값 4)

예를 들어: 1001부터 10011까지 10개의 버전이 있고 npx @capgo/cli cleanup [appId] --bundle=1000을 사용하면 1001부터 1006까지 제거되고 1007부터 10011까지 유지됩니다

총 20개의 버전이 있고 번들 번호를 지정하지 않고 다음과 같이 실행하면: npx @capgo/cli cleanup [appId] --keep=2 18개의 버전이 제거되고 마지막 2개가 유지됩니다

이 명령은 확인을 요청하며, 유지되고 제거될 항목의 테이블을 보여줍니다

Encrypt

Warning: 이 명령은 더 이상 사용되지 않으며 다음 주요 릴리스에서 제거될 예정입니다. 새로운 암호화 시스템을 사용해 주세요 npx @capgo/cli bundle encrypt [path/to/zip]

이 명령은 외부 소스에 코드를 저장하거나 테스트 목적으로 사용할 때 사용됩니다

선택적으로 다음을 제공할 수 있습니다:

--key [/path/to/my/private_key] 개인 키의 경로 --key-data [privateKey] 인라인으로 사용하려는 개인 키 데이터 이 명령은 ivSessionKey를 출력하고 암호화된 zip을 생성하여 업로드 명령이나 복호화 명령과 함께 사용할 수 있습니다

Encrypt V2

npx @capgo/cli bundle encryptV2 [path/to/zip] [checksum]

이 명령은 외부 소스에 코드를 저장하거나 테스트 목적으로 사용할 때 사용됩니다 체크섬은 번들의 sha256(—key-v2로 생성)이며, 복호화 후 파일의 무결성을 확인하는 데 사용됩니다 개인 키로 암호화되어 번들과 함께 전송됩니다 암호화 v2에서 체크섬은 번들의 “서명”이 되도록 업그레이드되었습니다

선택적으로 다음을 제공할 수 있습니다:

--key [/path/to/my/private_key] 개인 키의 경로 --key-data [privateKey] 인라인으로 사용하려는 개인 키 데이터 --json 정보를 json으로 출력 이 명령은 ivSessionKey를 출력하고 암호화된 zip을 생성하여 업로드 명령이나 복호화 명령과 함께 사용할 수 있습니다

Decrypt

npx @capgo/cli bundle decrypt [path/to/zip] [ivSessionKey]

선택적으로 다음을 제공할 수 있습니다:

--key [/path/to/my/private_key] 개인 키의 경로

--key-data [privateKey] 인라인으로 사용하려는 개인 키 데이터 이 명령은 주로 테스트 목적으로 사용되며, zip을 복호화하고 콘솔에 복호화된 세션 키를 base64로 출력합니다

Decrypt V2

npx @capgo/cli bundle decryptV2 [path/to/zip] [ivSessionKey]

선택적으로 다음을 제공할 수 있습니다:

--key [/path/to/my/private_key] 개인 키의 경로 --key-data [privateKey] 인라인으로 사용하려는 개인 키 데이터 이 명령은 주로 테스트 목적으로 사용되며, zip을 복호화하고 콘솔에 복호화된 세션 키를 base64로 출력합니다 --checksum [checksum] 파일의 체크섬으로, 복호화 후 체크섬을 확인합니다

Zip

npx @capgo/cli bundle zip [appId]

[appId]는 앱 ID이며, 형식은 여기에서 설명됩니다

선택적으로 다음을 제공할 수 있습니다:

  • --path [/path/to/my/bundle] 특정 폴더를 업로드
  • --bundle [100] 파일 이름의 번들 버전 번호를 설정
  • --name [myapp] 파일 이름을 재정의
  • --json 정보를 json으로 출력
  • --no-code-check 코드 검사를 무시하고 번들을 전송
  • --key-v2 새로운 암호화 시스템을 사용 새로운 암호화 시스템은 파일의 무결성을 확인하기 위해 더 나은 체크섬을 사용하므로 필수입니다

Compatibility

npx @capgo/cli bundle compatibility [appId] -c [channelId]

[appId]는 앱 ID이며, 형식은 여기에서 설명됩니다 [channelId] 새 채널의 이름

선택적으로 다음을 제공할 수 있습니다:

  • --apikey [key] 계정에 연결할 API 키
  • --text 테이블에서 이모지 대신 텍스트 사용
  • --channel [channel] 호환성을 확인할 채널
  • --package-json <packageJson> packagejson의 경로 모노레포에 유용
  • --node_modules <nodeModules> node_modules 경로 목록 모노레포에 유용 (쉼표로 구분 예: //node_modules,/node_modules)

Channel

Add

npx @capgo/cli channel add [channelId] [appId]

[channelId] 새로운 채널의 이름 [appId] 앱 ID 형식 comtestapp은 여기에서 설명됩니다

Delete

npx @capgo/cli channel delete [channelId] [appId]

[channelId] 삭제하려는 채널의 이름 [appId] 앱 ID 형식 comtestapp은 여기에서 설명됩니다

List

npx @capgo/cli channel list [appId]

[appId] 앱 ID 형식 comtestapp은 여기에서 설명됩니다

선택적으로 다음을 제공할 수 있습니다:

  • --apikey [key] 계정에 연결할 API 키

Set

npx @capgo/cli channel set [channelId] [appId]

[appId]는 앱 ID이며, 형식은 여기에서 설명됩니다

선택적으로 다음을 제공할 수 있습니다:

  • --bundle [123] 클라우드에 이미 전송된 앱 번들을 채널에 연결
  • --latest packagejson:version에서 번들 버전을 가져옴, --bundle과 함께 사용할 수 없음
  • --state [ normal | default ] 채널 상태를 설정, normal 또는 default가 될 수 있음 하나의 채널은 반드시 default여야 함
  • --downgrade 채널이 디바이스에 다운그레이드 버전을 전송하도록 허용
  • --no-downgrade 채널이 디바이스에 다운그레이드 버전을 전송하지 못하도록 함
  • --upgrade 채널이 디바이스에 업그레이드(메이저) 버전을 전송하도록 허용
  • --no-upgrade 채널이 디바이스에 업그레이드(메이저) 버전을 전송하지 못하도록 함
  • --ios 채널이 iOS 디바이스에 버전을 전송하도록 허용
  • --no-ios 채널이 iOS 디바이스에 버전을 전송하지 못하도록 함
  • --android 채널이 안드로이드 디바이스에 버전을 전송하도록 허용
  • --no-android 채널이 안드로이드 디바이스에 버전을 전송하지 못하도록 함
  • --self-assign 디바이스가 이 채널에 자체 할당하도록 허용
  • --no-self-assign 디바이스가 이 채널에 자체 할당하지 못하도록 함
  • --disable-auto-update STRATEGY 이 채널에 대한 자동 업데이트 전략을 비활성화 가능한 옵션: major, minor, metadata, none
  • --apikey [key] 계정에 연결할 API 키

업데이트 비활성화 전략

너무 오래된 버전에 대한 업데이트를 비활성화하는 방법이 몇 가지 있습니다
Capgo는 네이티브 코드를 업데이트할 수 없으므로 이전 네이티브 코드가 있는 버전에서 업데이트된 네이티브 코드가 있는 버전으로의 업데이트는 불가능해야 합니다 이를 달성하는 방법이 몇 가지 있습니다

첫째, major 전략 000 -> 100 업데이트를 방지합니다 메이저는 강조 표시된 숫자입니다 (100 및 000)
둘째, minor 전략 000 -> 110 또는 110에서 120으로의 업데이트를 방지합니다 주의하세요 이 전략은 010 -> 110 업데이트는 방지하지 않습니다

셋째, patch 전략은 매우 엄격한 모드로 Capgo에 추가되었습니다 완전히 이해하지 않는 한 사용하지 않는 것이 좋습니다 업데이트를 허용하기 위해서는 다음 조건을 충족해야 합니다:

  • 새 버전과 이전 버전의 메이저가 동일해야 함
  • 새 버전과 이전 버전의 마이너가 동일해야 함
  • 새 버전의 패치가 이전 버전의 패치보다 커야 함

다음은 업데이트가 허용되거나 거부되는 시나리오의 예입니다

  • 00311 -> 00314 ✅
  • 000 -> 00314 ✅
  • 00316 -> 00314 ❌
  • 01312 -> 00314 ❌
  • 10312 -> 00314 ❌

마지막으로 가장 복잡한 전략인 metadata 전략
먼저 활성화한 후에는 채널에 필요한 메타데이터가 없기 때문에 업데이트가 실패할 것입니다
채널에 메타데이터가 없는 경우 다음과 같은 메시지가 표시됩니다:

Cannot find metadata

이와 같은 것이 보이면 실패하는 채널의 현재 번들로 가서 메타데이터를 설정해야 합니다
먼저 어떤 채널이 실패하는지 확인하세요 misconfigured 열을 보면 알 수 있습니다 webp” alt=“Misconfigured table”/>

실패한 채널로 이동하여 Bundle number를 클릭하세요. 이렇게 하면 번들 페이지로 이동합니다

Locate failing channel

거기서 Minimal update version 필드를 채우세요. 이는 semver 형식이어야 합니다
입력한 값이 semver가 아니면 오류가 발생하지만, 모든 것이 정상적으로 진행되면 다음과 같은 화면이 표시됩니다:

Set min version

업데이트할 때마다 이 데이터를 수동으로 설정하고 싶지 않을 것입니다. 다행히도 CLI는 이 메타데이터 없이 업데이트를 보내는 것을 방지합니다

CLI fail no metadata

metadata 옵션을 사용할 때 번들을 올바르게 업로드하려면 유효한 semver와 함께 --min-update-version을 전달해야 합니다. 다음과 같이:

CLI upload with metadata

--min-update-version이 호환성을 설정하는 유일한 방법은 아닙니다 --auto-min-update-version도 있습니다. 작동 방식은 다음과 같습니다

먼저, 현재 채널에 업로드된 버전을 확인합니다. bundle compatibility 명령과 동일한 방식으로 호환성을 확인합니다 둘째, 새 버전이 100% 호환되면 채널의 최신 버전에서 min_update_version을 재사용합니다 그렇지 않으면 새로 업로드된 버전의 번들 번호로 min_update_version을 설정합니다

이 옵션을 사용할 때는 항상 min_update_version에 대한 정보를 얻을 수 있습니다. 다음과 같이 보일 것입니다:

Min update version

새 버전이 호환되지 않으면 다음과 같이 보일 것입니다

Min update version not compatible

종단 간 암호화 (신뢰 불필요)

Capgo는 종단 간 암호화를 지원합니다. 이는 번들(코드)이 클라우드로 전송되기 전에 암호화되고 기기에서 복호화된다는 의미입니다. 이를 위해 RSA 키 쌍을 생성해야 하며, 다음 명령을 사용하여 생성할 수 있습니다

암호화 시스템은 RSA와 AES의 조합입니다. RSA 키는 AES 키를 암호화하는 데 사용되고, AES 키는 파일을 암호화하는 데 사용됩니다

암호화 시스템에 대한 자세한 내용은 아래를 참조하세요

How crypto works

암호화 스키마

앱용 키 생성하기

npx @capgo/cli key create

선택적으로 다음을 사용할 수 있습니다: --force로 기존 키를 덮어쓸 수 있습니다. 이 명령은 앱에 키 쌍을 생성하고 개인 키를 안전한 곳에 저장하도록 요청합니다. 개인 키를 git에 커밋하거나 다른 사람과 공유하지 않는 것이 좋습니다

로컬 테스트 후에는 구성 파일에서 키를 제거하고 key save로 CI 단계에 추가하세요

앱 구성에 키 저장하기

npx @capgo/cli key save

선택적으로 다음을 사용할 수 있습니다:

--key [/path/to/my/private_key] 개인 키의 경로

--key-data [privateKey] 인라인으로 사용하려는 경우 개인 키 데이터. 이 명령은 권장 사항을 따랐고 앱과 구성에 키를 커밋하지 않은 경우 유용합니다

CI 통합

작업을 자동화하기 위해 GitHub 액션을 사용하여 서버에 푸시하는 것을 권장합니다

GitHub 액션 튜토리얼

데모 앱

GitHub - Cap-go/demo-app

API 키로 CI 환경 변수를 구성하는 것을 잊지 마세요