自定义存储

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 的应用）

加密

• Always encrypt sensitive bundles using the Capgo encryption tools
• 为所有包 URL 使用 HTTPS（移动和 Electron 应用程序必备）
• Section titled “Security Considerations”

监控

• 监控访问日志以检测异常下载模式
• 设置失败的包下载警报
• 定期审查存储权限

故障排除

常见问题

包下载失败：

• 验证 URL 公开可访问且使用 HTTPS（对于移动和 Electron 应用程序必需）
• 检查 CORS 头部信息（适用于 Web 应用程序）
• 确保捆绑包格式正确

加密错误：

• 验证 ivSessionKey 与加密捆绑包匹配
• 检查使用的密钥是否正确
• 确保新捆绑包使用加密v2

S3上传失败：

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

调试命令

检查捆绑包状态：

npx @capgo/cli@latest app debug

验证捆绑包完整性：

npx @capgo/cli@latest bundle list

下一步

• 下一步 学习关于 频道
• 页面区域：Capgo 解决方案营销页面。角色：短的 UI 标签或导航项。见于：页面解决方案/白标签.astro。消息键 `solutions_white_label_visual_cell2_value` (解决方案白标签视觉单元2值)。 更新行为 自定义如何应用更新
• 设置 CI/CD 集成 页面/区域: Capgo Builder / 原生云构建产品页面。角色: 短 UI 标签或导航项。

自动化您的自定义存储工作流

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