自定义存储

复制一个包含安装步骤和本插件的完整 Markdown 指南的配置提示。

Capgo 支持自定义存储解决方案来为您的应用程序包提供支持，使您能够在自己的基础设施或第三方存储服务上托管更新。这对于具有特定安全要求、合规需求或现有存储基础设施的组织来说尤其有用。

概述

Capgo 中的自定义存储通过将您的包上传到外部位置并向 Capgo 提供 URL 来工作，以便访问它。Capgo SDK 将从您的自定义存储位置下载更新，而不是从 Capgo 的默认云存储。

外部URL上传

使用自定义存储的最简单方法是将捆绑包上传到任何可公开访问的URL，并将该URL提供给Capgo。

基本外部URL上传

npx @capgo/cli@latest bundle upload --external https://your-domain.com/bundles/v1.2.3.zip

This command tells Capgo to reference the bundle at the specified URL instead of uploading it to Capgo’s cloud storage.

加密

为了安全的外部存储，您可以对您的捆绑包进行加密，并提供解密密钥：

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 provides built-in support for Amazon S3 and S3-compatible storage services. The CLI can automatically upload your bundle to S3 and configure Capgo to use the 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`	__CAPGO_KEEP_0__	是
`--s3-apisecret`	__CAPGO_KEEP_1__	是
`--s3-bucket-name`	__CAPGO_KEEP_0__	是
`--s3-endpoint`	__CAPGO_KEEP_2__	否
`--s3-port`	__CAPGO_KEEP_3__	否
`--no-s3-ssl`	__CAPGO_KEEP_4__	否

资源打包和加密

当使用自定义存储，特别是加密时，您需要正确准备您的资源包。这涉及创建一个zip文件并可选地对其进行加密。

步骤 1：创建 zip 资源包

首先，创建一个zip文件包含您的应用程序资源包：

npx @capgo/cli@latest bundle zip com.example.app --path ./dist

zip 命令将返回zip文件的校验和。您可以使用此校验和加密zip文件，如果需要。使用 --json zip 命令选项

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`	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 选项以获取结构化输出）。

默认情况下， --key 命令将使用您的本地私钥进行加密。您可以使用 --key-data 或

选项指定自定义密钥。 ivSessionKey 命令将返回

加密命令选项

选项	描述
`zipPath`	__CAPGO_KEEP_0__ (必填)
`checksum`	__CAPGO_KEEP_1__ (必填) - 使用 zip 命令获取
`--key`	__CAPGO_KEEP_2__ (可选, 默认使用本地密钥)
`--key-data`	__CAPGO_KEEP_3__ (可选)
`--json`	以 JSON 格式输出结果

完整工作流程示例

示例 1：带加密的外部 URL

构建您的应用：
终端窗口
```
npm run build
```

创建 zip 压缩包：

npx @capgo/cli@latest bundle zip com.example.app --path ./dist --bundle 1.2.3

注意此命令返回的校验和。

加密包:

npx @capgo/cli@latest bundle encrypt ./com.example.app-1.2.3.zip CHECKSUM_FROM_STEP_2

注意 ivSessionKey 从输出中

上传到您的存储: 将加密的zip文件上传到您的托管服务。

注册到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 上传

构建您的应用：
终端窗口
```
npm run build
```

直接上传到 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

构建并压缩：

npm run build
npx @capgo/cli@latest bundle zip com.example.app --path ./dist --key-v2

加密打包:

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

加密上传到 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

安全考虑

使用自定义存储时，请考虑以下安全最佳实践:

访问控制

targetLanguage
尽可能使用签名的 URL 或基于令牌的身份验证
为基于 Web 的应用程序实现正确的 CORS 头

加密

始终使用 Capgo 加密工具加密敏感的捆绑包
安全地存储加密密钥并定期轮换
为所有捆绑包 URL 使用 HTTPS（移动和 Electron 应用程序所必需）

监控

设置失败捆绑包下载的警报
定期审计存储权限
Section titled “Encryption”

故障排除

常见问题

无法下载包:

请确认 URL 公开可访问且使用 HTTPS（对于移动和 Electron 应用程序必需）
检查 Web 应用程序的 CORS 头
确保包格式正确

加密错误:

请确认加密的包 ivSessionKey 匹配加密的包
检查使用的加密密钥是否正确
确保使用 v2 加密新包

S3 上传失败：

验证您的 S3 凭据和权限
检查存储桶策略和 CORS 配置
确保指定的区域是正确的

调试命令

检查包状态：

npx @capgo/cli@latest app debug

验证包完整性：

npx @capgo/cli@latest bundle list

下一步

了解频道管理不同部署环境
探索更新行为自定义更新应用方式
设置 CI/CD 集成自动化您的自定义存储工作流