自定义存储

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-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 文件的校验和。 您可以使用此校验和加密 zip 文件，如果需要。 使用 --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	打包版本号以命名压缩文件
--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"

The CHECKSUM 此参数是必需的，应为您的 zip 文件的校验和。您可以从 zip 命令输出中获取校验和（使用 --json 加密命令默认会使用您的本地私钥。您可以使用

或 --key 选项指定自定义密钥。 --key-data Paths to package.json files for monorepos (comma separated) __CAPGO_KEEP_0__

The encrypt command will return the ivSessionKey needed for upload or decryption.

加密命令选项

选项	描述
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 集成 为您的自定义存储工作流程自动化

继续自定义存储

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