自定义存储

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

概述

Capgo 中的自定义存储通过将包上传到外部位置并向 Capgo 提供 URL 来工作，以便访问它。Capgo SDK 将从自定义存储位置下载更新，而不是从 Capgo 的默认云存储中下载。

提示

Custom storage is ideal for:

• Organizations with strict data residency requirements
• Teams with existing CDN or storage infrastructure
• Applications requiring additional security layers
• Cost optimization for large bundle sizes

External URL Upload

The simplest way to use custom storage is by uploading your bundle to any publicly accessible URL and providing that URL to Capgo.

Basic External URL Upload

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配置

或自定义端点：

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	No

打包准备和加密

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

步骤 1：创建 zip 打包

首先，创建一个 zip 文件的应用程序打包：

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

zip 命令将返回 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	打包版本号来命名压缩文件
--name	自定义压缩文件名
--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"

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

默认情况下，加密命令将使用您的本地私钥。您可以使用 --key 或 --key-data 选项指定自定义密钥。

加密命令将返回 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 应用程序所必需）

监控

• 设置失败包下载的警报
• 设置失败包下载的警报
• 定期审查存储权限

Troubleshooting

常见问题

Bundle 未下载：

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

加密错误：

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

S3 上传失败：

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

调试命令

检查打包状态：

npx @capgo/cli@latest app debug

验证打包完整性：

npx @capgo/cli@latest bundle list

下一步

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

继续从自定义存储

如果您正在使用 自定义存储 来规划安全性和合规性，连接它与 加密 加密的实现细节在 合规 合规的实现细节在 Capgo 安全扫描器 Capgo 安全扫描器的产品工作流, Capgo 安全 为产品工作流程在 Capgo 安全中 Capgo 信任中心 为产品工作流程在 Capgo 信任中心中