自定义存储

Capgo supports custom storage solutions for your app bundles, allowing you to host your updates on your own infrastructure or third-party storage services. This is particularly useful for organizations with specific security requirements, compliance needs, or existing storage infrastructure.

概述

Custom storage in Capgo works by uploading your bundle to an external location and providing Capgo with the URL to access it. The Capgo SDK will then download updates directly from your custom storage location instead of Capgo’s default cloud storage.

提示

提示

• 自定义存储适用于:
• 遵守严格数据居住要求的组织
• 已有的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 选项来获取结构化输出，包括校验和。

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：加密包裹（可选）

为了增强安全性，请在上传之前加密您的 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

加密命令选项

描述	要加密的 zip 文件路径（必填）
zipPath	zip 文件的校验和（必填）- 从 zip 命令获取
checksum	自定义私钥路径（可选，使用本地私钥默认）
--key	__CAPGO_KEEP_0__
--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 或基于令牌的身份验证
• 为基于 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

下一步

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

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

标题：继续自定义存储 如果您正在使用 自定义存储 来规划安全性和合规性，连接它与 加密 遵守性 遵守性 Capgo 安全扫描器 Capgo 安全扫描器 Capgo 安全中心 Capgo 信任中心 Capgo Trust Center for the product workflow in Capgo Trust Center.