复制页面选项

复制一个包含安装步骤和本插件的全套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

这个命令告诉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 配置参数

Parameter	描述	必填
`--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 文件，如果需要的话。使用 --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`	打包版本号来命名 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 加密命令选项

标题：加密命令选项

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

完整工作流程示例

示例 1：带加密的外部 URL

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

创建一个压缩包：

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

安全考虑

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

访问控制

确保您的存储 URL 可以被您的应用用户访问，但不应公开可发现
在可能的情况下使用签名 URL 或基于令牌的身份验证
为基于 Web 的应用程序实施适当的 CORS 头

加密

Always encrypt sensitive bundles using the Capgo encryption tools.
为所有包 URL 使用 HTTPS（对于移动和 Electron 应用程序必需）
监控

Monitoring

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

故障排除

常见问题

捆绑包未下载:

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

加密错误：

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

S3 上传失败：

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

调试命令

检查捆绑包状态：

npx @capgo/cli@latest app debug

校验包完整性：

npx @capgo/cli@latest bundle list

下一步

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

继续自定义存储

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