自定义存储

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

概述

Custom storage in Capgo works by uploading your bundle to an external location and providing Capgo with the URL to access it. The Capgo SDK will then download updates directly from your custom storage location instead of Capgo’s default cloud storage.

自定义存储适用于：

具有严格数据居住要求的组织

• 具有现有 CDN 或存储基础设施的团队
• 需要额外安全层的应用程序
• 大型包大小的成本优化
• 外部 URL 上传

External URL Upload

您可以通过将您的打包文件上传到任何公开可访问的 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-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 打包

首先，创建一个压缩文件包：

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

压缩命令将返回压缩文件的校验和。您可以使用此校验和来加密压缩文件，如果需要的话。使用 --json 选项以获取结构化输出，包括校验和。

压缩命令选项

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 文件
--name	自定义 zip 文件名称
--json	以 JSON 格式输出结果（包括校验和）
--no-code-check	跳过检查 notifyAppReady() 调用和索引文件
--key-v2	使用加密 v2
--package-json	多包项目的 package.json 文件路径（逗号分隔）

步骤 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 __CAPGO_KEEP_0__需要是您的zip文件的校验和。您可以从zip命令输出中获取校验和（使用__CAPGO_KEEP_1__选项）。 --json 加密命令的默认行为是使用您的本地私钥进行加密。您可以使用__CAPGO_KEEP_2__或__CAPGO_KEEP_3__选项指定自定义密钥。

或 --key 加密命令将返回__CAPGO_KEEP_4__，用于上传或解密。 --key-data 加密命令选项

加密命令选项 ivSessionKey 选项

描述

加密命令选项	加密命令选项
zipPath	加密命令选项
checksum	压缩文件的校验和 (必填) - 从 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 或基于令牌的身份验证
• 为基于 Web 的应用程序实现适当的 CORS 头
• 加密

始终使用 __CAPGO_KEEP_0__ 加密工具加密敏感的捆绑包

• Always encrypt sensitive bundles using the Capgo encryption tools
• 安全存储加密密钥并定期轮换
• 为所有捆绑包 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

下一步

• 了解关于 频道 管理不同部署环境
• Explore 更新行为 自定义更新应用方式
• 设置 CI/CD 集成 自动化自定义存储流程

从自定义存储继续

自定义存储 来规划安全性和合规性，连接它 Custom Storage 加密 加密的实现细节 合规 合规的实现细节 Capgo 安全扫描器 Capgo 安全扫描器的产品工作流程 Capgo 安全 Capgo 安全的产品工作流程 Capgo 信任中心 Capgo 信任中心的产品工作流程