自定义存储

Capgo 支持为你的 app bundle 使用自定义存储方案，让你可以把更新托管在自有基础设施或第三方存储服务上。对于有特定安全要求、合规需求或现有存储基础设施的组织来说，这尤其有用。

概览

Capgo 的自定义存储工作原理是：将你的 bundle 上传到外部位置，并把访问该位置的 URL 提供给 Capgo。随后，Capgo SDK 会直接从你的自定义存储位置下载更新，而不是使用 Capgo 的默认云存储。

提示

自定义存储非常适合：

• 有严格数据驻留要求的组织
• 已有 CDN 或存储基础设施的团队
• 需要额外安全层的应用
• 大体积 bundle 的成本优化

外部 URL 上传

使用自定义存储最简单的方法是将 bundle 上传到任何可公开访问的 URL，并将该 URL 提供给 Capgo。

基础外部 URL 上传

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

该命令让 Capgo 引用指定 URL 上的 bundle，而不是将其上传到 Capgo 的云存储。

支持加密

若要使用安全的外部存储，您可以加密 bundle 并提供解密密钥：

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 可自动将您的 bundle 上传到 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 bucket 所在的 AWS region	是
--s3-apikey	S3 访问密钥 ID	是
--s3-apisecret	S3 密钥访问密钥 (Secret Access Key)	是
--s3-bucket-name	S3 bucket 名称	是
--s3-endpoint	自定义 S3 endpoint URL	否
--s3-port	S3 endpoint 端口	否
--no-s3-ssl	禁用 S3 upload 的 SSL	否

Bundle 准备与加密

使用自定义存储（尤其是涉及加密时），需要正确准备你的 bundle。这包括创建一个 zip 文件，并根据需要对其进行加密。

步骤 1：创建 Zip Bundle

首先，为你的 app bundle 创建一个 zip 文件：

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

zip 命令会返回该 zip 文件的校验和（checksum）。如果需要，你可以使用该校验和来加密 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() 调用和 index 文件的检查
--key-v2	使用 v2 加密
--package-json	Monorepo 中 package.json 的路径 (以逗号分隔)

步骤 2：加密 Bundle（可选）

为提升安全性，请在上传前加密 zip bundle：

# 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 该参数为必填项，应为 zip 文件的校验和。你可以从 zip 命令的输出中获取校验和（使用 --json 选项获取结构化输出）。

默认情况下，encrypt 命令会使用你本地的私有签名密钥。你可以使用 --key 或 --key-data 选项来指定自定义密钥。

encrypt 命令会返回 ivSessionKey 上传或解密所需的内容。

加密命令选项

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

注意

encrypt 命令将输出一个 ivSessionKey that you’ll need to provide when uploading with the --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. 加密该 bundle：

   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. 加密该 bundle：

   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 或基于 token 的身份验证
• 为 Web 应用实现正确的 CORS 响应头

加密

• 务必使用 Capgo 加密工具对敏感 bundle 进行加密
• 安全存储加密密钥并定期轮换
• 所有 bundle URL 均须使用 HTTPS（移动端和 Electron 应用必选）

监控

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

故障排除

常见问题

Bundle 下载失败：

• 请确认 URL 可公开访问并使用 HTTPS（移动端和 Electron 应用必选）
• 检查 Web 应用的 CORS 响应头
• 确保 Bundle 格式正确

解密错误：

• 请检查 ivSessionKey 与加密的 bundle 匹配
• 请检查 Bundle 是否使用了正确的密钥进行加密
• 确保新 bundle 使用 encryption v2

S3 upload 失败：

• 验证 S3 凭据和权限
• 检查 bucket 策略和 CORS 配置
• 确保指定的 region 正确

调试命令

检查 bundle 状态：

npx @capgo/cli@latest app debug

验证 bundle 完整性：

npx @capgo/cli@latest bundle list

下一步

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

从自定义存储继续

如果你正在使用 自定义存储 来规划安全与合规，请结合 加密 了解 Encryption 的实现细节， 合规性 了解合规部分的实现细节， Capgo 安全扫描器 了解 Capgo Security Scanner 的产品工作流， Capgo 安全 用于 Capgo 安全的产品工作流，以及 Capgo 信任中心 用于 Capgo 信任中心的产品工作流。