自定义存储

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	Disable S3 上传的 SSL	No

准备和加密的捆绑包

当使用自定义存储，特别是加密时，您需要正确准备您的捆绑包。 这涉及创建一个 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"

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

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

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. __CAPGO_KEEP_0__

   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. [Encrypt the bundle:]

   npx @capgo/cli@latest bundle encrypt ./com.example.app.zip CHECKSUM

3. [Upload to S3 with encryption:]

   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

[Security Considerations]

[When using custom storage, consider these security best practices:]

[Access Control]

• 确保您的存储 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_KEEP_0__ 自动化自定义存储流程

继续自定义存储

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