命令

用法

所有命令都应该在您的应用文件夹中运行,并且已正确初始化 Capacitor 项目。

Capacitor 跨平台 Web 应用原生运行时

Init

npx @capgo/cli@latest init [apikey]

此方法用于逐步引导您。

它将把您的应用添加到 Capgo。它将添加代码到您的应用以验证更新。同样,它将构建您的应用。此外,它将上传您的应用到 Capgo。并且它将帮助您检查更新是否有效。

npx @capgo/cli login [apikey]

此方法用于为您记住 apikey。

可选地,您可以提供:

--local 这将在本地仓库中存储您的 apikey 并将其添加到 git ignore。

Doctor

npx @capgo/cli doctor

用于检查您的 Capgo 包是否是最新版本的命令。

此命令对于错误报告也很有用。

App

Add

npx @capgo/cli app add [appId]

[appId] 您的应用 ID,格式 com.test.app 在这里有说明。

💡 如果未提供,所有选项将从您的配置中推断。

可选地,您可以提供:

--icon [/path/to/my/icon] 在 Capgo Web 应用中显示自定义图标。
--name [test] 在列表中显示自定义名称。
--apikey [key] 用于链接到您账户的 API 密钥。
--retention [retention] 应用 bundle 的保留期(天),默认为 0 = 无限。

capacitor.config.json 的示例,用于 appId 和 AppName,图标在 resources 文件夹中推断

{
  "appId": "ee.forgr.capacitor_go",
  "appName": "Capgo",
  "webDir": "dist"
}

Set

npx @capgo/cli app set [appId]

[appId] 是您的应用 ID,格式在这里有说明。

可选地,您可以提供:

--icon [/path/to/my/icon] 在 Capgo Web 应用中显示自定义图标。
--name [test] 在列表中显示自定义名称。
--retention [retention] 应用 bundle 的保留期(天),默认为 0 = 无限。
--apikey [key] 用于链接到您账户的 API 密钥。

List

npx @capgo/cli app list [appId]

[appId] 您的应用 ID,格式 com.test.app 在这里有说明。

可选地,您可以提供:

--apikey [key] 用于链接到您账户的 API 密钥。

Delete

npx @capgo/cli app delete [appId]

[appId] 您的应用 ID,格式 com.test.app 在这里有说明。

可选地,您可以提供:

--apikey [key] 用于链接到您账户的 API 密钥。
--bundle 带版本号将仅删除此版本。

Debug

npx @capgo/cli app debug [appId]

[appId] 您的应用 ID,格式 com.test.app 在这里有说明。

可选地,您可以提供:

--apikey [key] 用于链接到您账户的 API 密钥。
--device 带您想要调试的特定设备

Setting

npx @capgo/cli app setting [path]

编辑 Capacitor 配置。

[path] - 您想要更改的设置路径。例如,要更改 appId,提供 appId。如果您希望在 capacitor-updater 中禁用自动更新,提供 plugins.CapacitorUpdater.autoUpdate

您必须提供 --string 或 --bool 之一!

选项:

--string <string> - 将设置设为字符串
--bool <true | false> - 将设置设为布尔值

Bundle

Upload

npx @capgo/cli bundle upload [appId]

[appId] 是您的应用 ID,格式在这里有说明。

可选地,您可以提供:

--apikey <apikey> 用于链接到您账户的 API 密钥。
--path <path> 要上传的文件夹路径。
--channel <channel> 要链接到的频道。
--external <url> 链接到外部 URL 而不是上传到 Capgo Cloud。
--iv-session-key <key> 为外部 bundle URL 设置 IV 和会话密钥。
--s3-endpoint <s3Endpoint> S3 端点的 URL。不适用于部分上传或外部选项。
--s3-region <region> 您的 S3 存储桶的区域。
--s3-apikey <apikey> 您的 S3 端点的 API 密钥。
--s3-apisecret <apisecret> 您的 S3 端点的 API 密钥。
--s3-bucket-name <bucketName> 您的 AWS S3 存储桶的名称。
--s3-port <port> 您的 S3 端点的端口。
--no-s3-ssl 禁用 S3 上传的 SSL。
--key <key> 公共签名密钥的自定义路径(v1 系统)。
--key-data <keyData> 公共签名密钥(v1 系统)。
--key-v2 <key> 私有签名密钥的自定义路径(v2 系统)。
--key-data-v2 <keyData> 私有签名密钥(v2 系统)。
--bundle-url 将 bundle URL 打印到 stdout。
--no-key 忽略签名密钥并发送明文更新。
--no-code-check 忽略检查源代码中是否调用了 notifyAppReady() 以及根文件夹中是否存在索引。
--display-iv-session 在控制台中显示用于加密更新的 IV 和会话密钥。
--bundle <bundle> 要上传的 bundle 的版本号。
--min-update-version <minUpdateVersion> 更新到此版本所需的最低版本。仅在频道中禁用自动更新设置为 metadata 时使用。
--auto-min-update-version 根据原生包设置最小更新版本。
--ignore-metadata-check 上传时忽略元数据(node_modules)检查。
--ignore-checksum-check 上传时忽略校验和检查。
--timeout <timeout> 上传过程的超时时间(秒)。
--delta 与完整 bundle 一起上传差异文件(旧标志 - 与 --partial 相同)。
--tus 使用 tus 协议上传 bundle。
--multipart 使用 multipart 协议将数据上传到 S3,已弃用,请改用 TUS。
--encrypted-checksum <encryptedChecksum> 加密的校验和(签名)。仅在上传外部 bundle 时使用。
--package-json <packageJson> package.json 的路径。对单体仓库有用。
--auto-set-bundle 在 capacitor.config.json 中设置 bundle。
--node-modules <nodeModules> node_modules 的路径列表。对单体仓库有用(逗号分隔,例如:../../node_modules,./node_modules)

⭐️ 外部选项有助于解锁 2 种情况:注重隐私的企业,不向第三方发送代码,以及大于 200 MB 的应用。通过此设置,Capgo 仅存储 zip 的链接并将链接发送到所有应用。

👀 Capgo Cloud 从不查看链接中的内容(用于外部选项),或存储时的代码。

🔑 您可以通过使用加密添加第二层安全性,然后 Capgo 将无法查看或修改任何内容,它变成”无需信任”。

package.json 的版本示例

{
  "version": "1.0.2"
}

⛔ 版本应该大于 “0.0.0”。

💡 每次发送时不要忘记更新版本号,出于安全原因,版本号不能被覆盖或在删除后重复使用。

List

npx @capgo/cli bundle list [appId]

[appId] 您的应用 ID,格式 com.test.app 在这里有说明。

可选地,您可以提供:

--apikey [key] 用于链接到您账户的 API 密钥。

Delete

npx @capgo/cli bundle delete [appId]

[appId] 您的应用 ID,格式 com.test.app 在这里有说明。

可选地,您可以提供:

--apikey [key] 用于链接到您账户的 API 密钥。
--bundle 带版本号将仅删除此版本。

Cleanup

在主版本的 SemVer 范围内到 Cloud

npx @capgo/cli bundle cleanup [appId] --bundle=[majorVersion] --keep=[numberToKeep]

[appId] 您的应用 ID,格式 com.test.app 在这里有说明。

可选地,您可以提供:

--apikey [key] 用于链接到您账户的 API 密钥。
--bundle [majorVersion] 您希望删除之前包的版本,它将保留最后一个 + numberToKeep。
--keep [numberToKeep] 您希望保留的包数量(默认 4)。

例如:如果您有从 10.0.1 到 10.0.11 的 10 个版本,并且您使用 npx @capgo/cli cleanup [appId] --bundle=10.0.0,它将删除 10.0.1 到 10.0.6。将保留 10.0.7 到 10.0.11。

如果您总共有 20 个版本,并且您不提供 bundle 号,像这样:npx @capgo/cli cleanup [appId] --keep=2,它将删除 18 个版本,并保留最后 2 个。

此命令将要求确认,它显示一个表格,说明它将保留什么和删除什么。

Encrypt

警告: 此命令已弃用,将在下一个主要版本中删除。请使用新的加密系统。 npx @capgo/cli bundle encrypt [path/to/zip]

此命令在您使用外部源存储代码或用于测试目的时使用。

可选地,您可以提供:

--key [/path/to/my/private_key] 您的私钥的路径。 --key-data [privateKey] 私钥数据,如果您想要内联使用。该命令将打印您的 ivSessionKey 并生成一个加密的 zip,以与 upload 命令或 decrypt 命令一起使用。

Encrypt V2

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

此命令在您使用外部源存储代码或用于测试目的时使用。校验和是 bundle 的 sha256(由 —key-v2 生成),用于在解密后验证文件的完整性。它将使用私钥加密并与 bundle 一起发送。在加密 v2 中,校验和升级为 bundle 的”签名”。

可选地,您可以提供:

--key [/path/to/my/private_key] 您的私钥的路径。 --key-data [privateKey] 私钥数据,如果您想要内联使用。 --json 以 json 格式输出信息。该命令将打印您的 ivSessionKey 并生成一个加密的 zip,以与 upload 命令或 decrypt 命令一起使用。

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 [1.0.0] 设置文件名的 bundle 版本号。
--name [myapp] 覆盖文件名。
--json 以 json 格式输出信息。
--no-code-check 忽略代码检查并无论如何发送 bundle。
--key-v2 使用新的加密系统。这是必需的,因为新的加密系统使用更好的校验和来验证文件的完整性。

Compatibility

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

[appId] 是您的应用 ID,格式在这里有说明。 [channelId] 您的新频道的名称。

可选地,您可以提供:

--apikey [key] 用于链接到您账户的 API 密钥。
--text 在表格中使用文本而不是表情符号
--channel [channel] 要检查兼容性的频道。
--package-json <packageJson> package.json 的路径。对单体仓库有用
--node-modules <nodeModules> node_modules 的路径列表。对单体仓库有用(逗号分隔,例如:../../node_modules,./node_modules)

Channel

Add

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

[channelId] 您的新频道的名称。[appId] 您的应用 ID,格式 com.test.app 在这里有说明。

Delete

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

[channelId] 您想要删除的频道的名称。[appId] 您的应用 ID,格式 com.test.app 在这里有说明。

List

npx @capgo/cli channel list [appId]

[appId] 您的应用 ID,格式 com.test.app 在这里有说明。

可选地,您可以提供:

--apikey [key] 用于链接到您账户的 API 密钥。

Set

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

[appId] 是您的应用 ID,格式在这里有说明。

可选地,您可以提供:

--bundle [1.2.3] 您已发送到云的应用 bundle,将其链接到频道。
--latest 从 package.json:version 获取 bundle 版本,不能与 --bundle 一起使用。
--state [ normal | default ] 设置频道状态,可以是 normal 或 default。一个频道需要是 default。
--downgrade 允许频道向设备发送降级版本。
--no-downgrade 不允许频道向设备发送降级版本。
--upgrade 允许频道向设备发送升级(主要)版本。
--no-upgrade 不允许频道向设备发送升级(主要)版本。
--ios 允许频道向 iOS 设备发送版本。
--no-ios 不允许频道向 iOS 设备发送版本。
--android 允许频道向 Android 设备发送版本。
--no-android 不允许频道向 Android 设备发送版本。
--self-assign 允许设备自行分配到此频道。
--no-self-assign 不允许设备自行分配到此频道。
--disable-auto-update STRATEGY 为此频道禁用自动更新策略。可能的选项有:major、minor、metadata、none。
--apikey [key] 用于链接到您账户的 API 密钥。

禁用更新策略

有几种方法可以处理禁用过旧版本的更新。
Capgo 无法更新原生代码,因此从具有旧原生代码的版本更新到具有更新原生代码的版本应该是不可能的。有几种方法可以实现这一点。

首先是 major 策略。它防止从 0.0.0 -> 1.0.0 的更新。主版本是突出显示的数字(1.0.0 和 0.0.0)。
其次是 minor 策略。它防止从 0.0.0 -> 1.1.0 或从 1.1.0 到 1.2.0 的更新。注意此策略不会防止从 0.1.0 -> 1.1.0 的更新

第三是 patch 策略。它作为一种非常严格的模式添加到 capgo 中。除非您完全理解其工作原理,否则不建议使用。为了接受更新,必须满足以下条件:

新版本和旧版本之间的主版本相同
新版本和旧版本之间的次版本相同
新版本的补丁大于旧版本的补丁

以下是允许或拒绝更新的场景示例

0.0.311 -> 0.0.314 ✅
0.0.0 -> 0.0.314 ✅
0.0.316 -> 0.0.314 ❌
0.1.312 -> 0.0.314 ❌
1.0.312 -> 0.0.314 ❌

最后是最复杂的策略。metadata 策略。
首先您需要知道,在您启用它后,更新最初将会失败,因为频道缺少所需的元数据。
如果频道缺少元数据,您将看到类似这样的消息:

如果您看到类似的内容,您就知道必须转到失败频道的当前 bundle 并设置元数据。
首先,找出哪个频道失败了。您可以通过查看 misconfigured 列来做到这一点

然后转到失败的频道并点击 Bundle number。这应该会带您到 bundle 页面。

到达那里后,填写 Minimal update version 字段。这应该是一个 semver。
如果您传递的值不是 semver,您将收到错误,但如果一切顺利,您应该会看到类似这样的内容:

现在,您可能不希望每次更新时都手动设置此数据。幸运的是,CLI 将阻止您在没有此元数据的情况下发送更新

要在使用 metadata 选项时正确上传 bundle,您需要传递带有有效 semver 的 --min-update-version。类似这样:

--min-update-version 不是进行兼容性检查的唯一方法。还存在 --auto-min-update-version。它的工作方式如下。

首先,它查看当前上传到频道的版本。它像 bundle compatibility 命令一样检查兼容性。其次,如果新版本 100% 兼容,它会重用频道中最新版本的 min_update_version。如果不兼容,则将 min_update_version 设置为新上传版本的 bundle 号。

使用此选项时,您将始终获得有关 min_update_version 的信息。它看起来像这样:

如果新版本不兼容,它应该看起来像这样

端到端加密(无需信任)

Capgo 支持端到端加密,这意味着您的 bundle(代码)在发送到云之前被加密,并在设备上解密。为此,您需要生成一个 RSA 密钥对,您可以使用以下命令生成它。

加密系统是 RSA 和 AES 的组合,RSA 密钥用于加密 AES 密钥,AES 密钥用于加密文件。

有关加密系统的更多信息,请参见下文。

加密架构

为您的应用创建密钥

npx @capgo/cli key create

可选地,您可以提供:--force 来覆盖现有密钥。此命令将为您在应用中创建一个密钥对,并要求您将私钥保存在安全的地方。建议不要将私钥提交到 git,也不要与任何人分享。

在本地测试后,从配置文件中删除密钥,并使用 key save 在 CI 步骤中添加它

在应用配置中保存密钥

npx @capgo/cli key save

可选地,您可以提供:

--key [/path/to/my/public_key] 您的公钥文件的路径。

--key-data [publicKey] 公钥数据,如果您想要内联使用。如果您遵循了建议并没有在应用配置中提交密钥,则此命令很有用。

CI 集成

为了自动化您的工作,我建议您让 GitHub action 完成推送到我们服务器的工作

GitHub action 教程

我们的演示应用

GitHub - Cap-go/demo-app

不要忘记使用您的 API 密钥配置 CI 环境变量

命令

用法

Init

Login

Doctor

App

Add

Set

List

Delete

Debug

Setting

Bundle

Upload

List

Delete

Cleanup

Encrypt

Encrypt V2

Decrypt

Decrypt V2

Zip

Compatibility

Channel

Add

Delete

List

Set

禁用更新策略

端到端加密(无需信任)

为您的应用创建密钥

在应用配置中保存密钥

CI 集成

我们的演示应用