自定义存储

Capgo 支持自定义存储解决方案来为您的应用程序包提供更新，允许您在自己的基础架构或第三方存储服务上托管更新。这对于具有特定安全要求、合规需求或现有存储基础架构的组织来说尤其有用。

概述

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 将被指向指定 URL 的捆绑包，而不是上传到 Capgo 的云存储中。

带加密

为了安全的外部存储，您可以对捆绑包进行加密，并提供解密密钥：

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 配置参数	Required
--s3-region	您的S3存储桶所在的AWS区域	是
--s3-apikey	S3访问密钥ID	是
--s3-apisecret	S3密钥访问密钥	是
--s3-bucket-name	您的S3存储桶名称	是
--s3-endpoint	自定义S3端点URL	否
--s3-port	S3端点端口	否
--no-s3-ssl	S3 上传时禁用 SSL	否

准备和加密捆绑包

当使用自定义存储，特别是加密时，您需要正确准备您的捆绑包。这涉及创建一个 zip 文件并可选地加密它。

步骤 1：创建 zip 捆绑包

首先，创建一个 zip 文件的应用捆绑包：

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

如果需要加密 zip 文件，请使用 zip 命令返回的校验和。 --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 格式输出结果（包括校验和）
--no-code-check	跳过检查 notifyAppReady() 调用和索引文件
--key-v2	使用加密 v2
--package-json	__CAPGO_KEEP_0__

步骤 2：加密捆绑包（可选）

为了增强安全性，请在上传之前加密您的 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"

The CHECKSUM 参数是必需的，应为您的 zip 文件的校验和。您可以从 zip 命令输出中获取校验和（使用 --json 选项以获取结构化输出）。

默认情况下，加密命令将使用您的本地私钥。您可以使用 --key 或 --key-data options.

加密命令将返回 ivSessionKey 用于上传或解密所需的

加密命令选项

选项	描述
zipPath	加密的 zip 文件路径（必填）
checksum	zip 文件的校验和（必填）- 从 zip 命令获取
--key	自定义私钥路径（可选，使用本地密钥默认）
--key-data	私钥数据直接（可选）
--json	输出结果以 JSON 格式

注意

加密命令将输出一个 ivSessionKey 您需要在上传时提供的 --iv-session-key 选项。

完整工作流程示例

示例 1：带加密的外部 URL

1. 构建您的应用：

   npm run build

2. 创建一个 zip 压缩包：

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

   注意这个命令返回的校验和。

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 或基于令牌的身份验证
• 为基于 Web 的应用程序实现适当的 CORS 头

加密

• 始终使用 Capgo 加密工具加密敏感包
• 安全存储加密密钥并定期轮换
• 为所有包 URL 使用 HTTPS（移动和 Electron 应用程序所必需）

监控

• 监控访问日志以检测异常下载模式
• 设置失败的捆绑下载警报
• 定期审计您的存储权限

故障排除

常见问题

捆绑包未下载：

• 验证 URL 公开可访问且使用 HTTPS（对于移动和 Electron 应用程序必需）
• 检查 Web 应用程序的 CORS 头
• 确保捆绑包格式正确

加密错误：

• 确认 ivSessionKey 确认加密的包是否与加密包匹配
• 检查包是否使用正确的密钥进行加密
• 确保新包使用加密 v2

S3 上传失败：

• 确认您的 S3 凭据和权限
• 检查桶策略和 CORS 配置
• 确保指定的区域是正确的

调试命令

检查包状态：

npx @capgo/cli@latest app debug

校验捆绑包完整性：

npx @capgo/cli@latest bundle list

下一步操作

• 了解更多 频道 用于管理不同部署环境
• 探索 更新行为 自定义更新应用方式
• 设置 CI/CD 集成 自动化您的自定义存储工作流