自定义存储

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	No
--s3-port	S3端点的端口	No
--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	zip文件的路径（默认为capacitor.config中的webDir）
--bundle	打包版本号来命名zip文件
--name	自定义zip文件名称
--json	以 JSON 格式输出结果（包括校验和）
--no-code-check	跳过检查 notifyAppReady() 调用和索引文件
--key-v2	使用加密 v2
--package-json	多包项目的 package.json 文件路径（用逗号分隔）

步骤 2：加密 Bundle（可选）

为了增强安全性，请在上传之前加密您的 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 选项以获取结构化输出）

By default, the encrypt command will use your local private signing key. You can specify a custom key using the --key 或 --key-data 您可以使用

The encrypt command will return the ivSessionKey 所需的

Encryption Command Options

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

注意

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

完整工作流程示例

示例 1：带加密的外部 URL

1. 构建您的应用：

   npm run build

2. 创建一个压缩包：

   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 或基于令牌的身份验证时可行
• 实现适当的 CORS 头部信息（适用于基于 Web 的应用）

加密

• 始终使用 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

下一步

• 下一步 了解 频道
• 区域/页面：Capgo 解决方案营销页面。角色：短 UI 标签或导航项。见于：页面 solutions/white-label.astro。消息键 `solutions_white_label_visual_cell2_value` (解决方案白标视觉单元2值)。 更新行为 自定义更新应用方式
• 设置 CI/CD 集成 自定义存储工作流程的自动化

继续自定义存储

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