渐进式发布

复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。

渐进式发布会让通道的 稳定回退版本 保持不变，同时将独立的 发布目标 推送给受控的设备子集。大多数生产用户仍使用稳定版。只有发布批次会收到候选版本，直到你 完成发布 或 回滚发布.

Capgo channel 中的渐进式发布控制 — 本指南中介绍的 **渐进式发布** channel 的 Information 标签页中的区块会显示 **发布目标** 以及 **稳定回退版本**、百分比控件和发布操作。

渐进式发布的全流程解析

每个 channel 可以同时拥有两个 bundle 链接：

控制台标签	API / CLI	接收对象
稳定回退版本	稳定版 bundle (`version` 开启 Channels POST)	该频道中处于不会灰度发布分组内的所有设备。
发布目标	发布目标 (`rolloutVersion` / `rollout_version`)	只有被 Capgo 随机选入该灰度发布队列的设备，在发布处于已启用且未暂停的状态时，才会收到更新。

每次检查更新时的执行逻辑

设备会向 Capgo 请求其对应 channel 的更新。
如果灰度发布已禁用，或者没有设置目标，Capgo 将提供 稳定回退版本.
如果灰度发布已 已启用 以及 已暂停，已在分组中的设备将保持 发布目标；其他设备将接收 稳定回退版本.
如果发布处于 已启用 且未暂停，Capgo 会检查该设备是否在发布分组中：
- 在分组中 → 发布目标。
- 不在分组中 → 稳定的回退方案。

Capgo 会为每个符合条件的设备做出随机决策，然后使用设备 ID 和 rollout ID 的哈希值进行缓存。这使得该分组具有粘性，在配置的缓存期间保持不变，而不会在每次检查更新时重新分配。

启用渐进式发布

在进行 rollout 之前，需要先有一个稳定的回退方案。在 dashboard 中，请在选择 rollout 目标之前先分配好 stable bundle。通过公开 Channels API，现有的 channel 可以提供 version 以及 rolloutVersion 在同一个 POST 请求中接收。

开始发布：

设置 发布目标 （或上传/分配 bundle — 请参阅上传并分配 bundle).
选择 设备百分比 并点击 应用百分比.
点击 启用发布.

在启用 rollout 之前，配置目标和百分比不会改变设备的接收状态。

百分比变更

在控制台中，修改百分比并点击 应用百分比 以保存设置。在可能的情况下，Capgo 会保留现有的决策：

提高百分比 — 已选中的设备保持选中状态；仅向之前未选中的设备中随机添加一部分。
降低百分比 — 已选中的群体中会有一部分随机设备回退到稳定的 fallback 版本。
将百分比设置为 0% — 未选择任何新设备。已在运行已启用 rollout 目标的设备会继续接收该目标，直到你禁用、回滚或更改目标。
暂停发布 — 阻止新设备进入，而已在运行已启用目标的设备会继续留在该目标上。
禁用发布 — 不再解析 rollout 目标；更新检查会使用稳定的 fallback。

上传并分配 bundle

在 channels 上配合配置了 progressive rollout 后，新的上传和 bundle 链接会进入 发布目标 默认情况下。 稳定回退版本 除非你明确选择替换，否则保持不变。

当你向已配置 rollout 的频道上传或关联 bundle 时，控制台会显示标题 此频道使用渐进式发布 以及横幅：

此频道上的新上传和 bundle 链接默认会进入 rollout 目标。除非你选择替换，否则 Stable 保持不变。

选择 bundle 的投放目标：

控制台选项	使用场景
自动（推荐）	默认值。与以下相同：发布目标配置渐进式发布时；与以下相同：替换稳定版未配置时。匹配 API `target: "auto"` 且 CLI 在没有 `--stable` 或 `--rollout`.
发布目标	发布候选版本时；稳定版回退保持不变。
替换稳定版	有意替换生产环境稳定版（紧急出口）。

提示 配置渐进式发布后，Auto 会自动使用 rollout 适用于 API target: "auto" 以及未通过测试的 CLI 上传 --stable 或 --rollout.

默认上传路由

Channel 状态	默认上传 / 分配	稳定回退版本	发布目标
否已配置渐进式发布	到达指定频道	设置为上传	不适用
已配置渐进式发布	到达指定频道	未变更	设置为上传

CLI 与 API 路径

您发布 bundle 的方式	稳定回退版本	发布目标	备注
`bundle upload --channel <name>` （无需额外参数）	发布渠道保持不变；设置未进行灰度发布时	设置在发布渠道上	与控制台默认设置一致。
`bundle upload --channel <name> --rollout <percent>`	未变更	设置；灰度发布已启用在该百分比下	一键上传并启用。
`bundle upload --channel <name> --stable`	已替换	未变更	紧急出口 —— 有意进行的稳定版本替换。
`bundle upload` 配合否 `--channel`	未变更	未变更	仅注册；关联至 `channel set` 或 API。
控制台链接对话框 → 自动（推荐）	在发布渠道上未变更	设置在发布渠道上	默认选项。
控制台链接对话框 → 发布目标	未变更	设置	明确的发布目标。
控制台链接对话框 → 替换稳定版	已替换	未变更	备用方案。
PUT `/bundle/` 配合 `target: "auto"`	在发布渠道上未变更	设置在发布渠道上	API 默认值。
PUT `/bundle/` 配合 `target: "rollout"`	未变更	设置	明确的发布目标。
PUT `/bundle/` 配合 `target: "stable"`	已替换	未变更	备用方案。
`channel set --bundle <version>`	已替换	未变更	明确的稳定版本覆盖。
`channel set --rollout-bundle <version>` (+ `--rollout-percentage`, `--rollout-enable`)	未变更	设置或已更改	无需上传即可配置目标。
Channels POST `version`	已替换设置时	未变更	显式稳定版本覆盖。
Channels POST `rolloutVersion`	未变更	已设置或已更改设置时	通过代码进行目标分配。

CLI 示例

在已配置 rollout 的 channel 上进行默认上传（rollout 目标；stable 保持不变）：

bunx @capgo/cli@latest bundle upload com.example.app \
  --path ./dist \
  --channel production

上传、设置 rollout 目标并开启 5% 灰度：

bunx @capgo/cli@latest bundle upload com.example.app \
  --path ./dist \
  --channel production \
  --rollout 5

显式替换 stable 版本：

bunx @capgo/cli@latest bundle upload com.example.app \
  --path ./dist \
  --channel production \
  --stable

不进行关联直接上传，随后配置 rollout：

bunx @capgo/cli@latest bundle upload com.example.app --path ./dist -b 1.3.0

bunx @capgo/cli@latest channel set production com.example.app \
  --rollout-bundle 1.3.0 \
  --rollout-percentage 5 \
  --rollout-enable

使用明确的目标进行 API 分配 (auto | stable | rollout):

curl -X PUT \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "com.example.app",
    "version_id": 456,
    "channel_id": 789,
    "target": "rollout"
  }' \
  https://api.capgo.app/bundle/

在不重新选择已选设备的情况下增加曝光率：

bunx @capgo/cli@latest channel set production com.example.app \
  --rollout-percentage 25

使用 --rollout-percentage-bps 当您需要比整数百分比更精细的步进时（例如 50 = 0.5%).

请参阅 channel CLI 参考以及 CLI bundle 引用针对每个发布选项。控制台 UX 已在 capgo.app#3313 中上线.

渐进式发布板块 (dashboard)

打开一个 App → 通道 → 选择 Channel → 信息 → 渐进式发布.

该部分显示 发布目标 以及 稳定回退版本 用于这两个 bundle 链接。使用 更改发布目标 来选择不同的候选 bundle。修改百分比后，点击 应用百分比 即可保存。

控制权	功能说明	已在群组中的设备	符合条件的新设备
更改发布目标	集合 `rolloutVersion`. 修改它会启动新的 rollout ID 和新的 cohort。向 channel（默认）上传或分配 bundle 也会设置 rollout 目标。	保持之前的目标，直到用户再次检查更新并符合新的决策规则。	根据相对于新目标的百分比进行筛选。
应用百分比	保存您输入的百分比。	增加时保持不变；减少时可能会随机剔除一部分用户。	根据上述百分比规则进行添加或排除。
启用发布	针对配置的目标和百分比开启 rollout 发布。	在下次检查更新前不会立即生效。	可能会在下次检查时被选中。
暂停发布	停止新设备进入。	保持在发布目标版本。	接收稳定的回退版本在下次检查时。
恢复发布	清除暂停状态。	保持不变。	下次检查时可能会被再次选中。
禁用发布	停止解析发布目标；Capgo 将为所有人使用稳定的回退版本。	切换至稳定回退版本在下次检查时。	接收稳定的回退版本。
完成发布 (API: `promoteToStable`; CLI: `--rollout-promote`)	将当前 rollout 版本设为新的稳定回退版本，然后清除 rollout 状态。已确认：完成渐进式 rollout？ — 目标版本将对所有人变为稳定版，替换之前的稳定回退版本，并重置百分比。	设为稳定回退版本对所有人。	接收已完成的 bundle 作为稳定版本。
回滚发布 (API: `rollback`; CLI: `--rollout-rollback`)	清除目标，禁用 rollout，将百分比重置为 0%，并将设备恢复至稳定的 fallback 版本。	返回稳定 fallback 在下次检查时。	接收稳定 fallback。

请一次仅执行一个终端操作（完成发布 以及 回滚发布 无法在单个 API 调用中组合使用）：

# Stop adding devices while you investigate
bunx @capgo/cli@latest channel set production com.example.app --rollout-pause

# Allow new devices to enter again
bunx @capgo/cli@latest channel set production com.example.app --rollout-resume

# Complete rollout — candidate becomes stable for everyone
bunx @capgo/cli@latest channel set production com.example.app --rollout-promote

# Rollback rollout — discard candidate and return to stable
bunx @capgo/cli@latest channel set production com.example.app --rollout-rollback

请保留 rollout 目标 bundle，直到你 完成发布 或 回滚发布。作为稳定回退 (stable fallback) 或 rollout 目标绑定的 bundle 将无法被删除。

安全工作流

Progressive rollout 旨在让你无需一次性切换整个 channel，即可在生产环境中进行验证。推荐的操作流程：

确认 stable fallback 运行正常。 这应该是你愿意向大多数用户提供的版本。
上传候选版本 至已配置 rollout 的 channel (bundle upload --channel <name> 落地于 发布目标 并离开 稳定回退版本 自动完成) 或使用 --rollout <small-percent> 在同一步骤中开启曝光。
从小规模开始 — 1–5% 的比例足以获取初步信号。点击 应用百分比，然后 启用发布如果希望在失败率激增时让 Capgo 停止发布，请开启自动暂停。
扩大范围前先进行监控。 使用 Observe 查看版本健康状况、日志洞察错误模式，并通过 channel 历史记录 标签页查看配置变更。将 rollout 目标与稳定回退版本进行对比；在用户群表现稳定前，请勿提高发布比例。
逐步增加比例 — 编辑百分比，点击 应用百分比，并逐步提升（例如 5% → 25% → 50% → 100%）。当你增加比例时，Capgo 会保留已在当前 cohort 中的设备。
确认无误后完成发布 — 确认 完成渐进式发布？ 使该候选版本成为所有人的稳定回退版本。
如果出现问题，请先暂停发布 — 在你排查问题时停止新设备接入。已使用错误版本的设备将保持现状，直到你 回滚发布 或 禁用发布.

自动暂停策略

Capgo 每五分钟评估一次已启用的发布，并在失败信号超过你设定的阈值时采取行动。它会统计所选 channel 和时间窗口内该发布目标的安装量与失败量，然后使用 Wilson 置信区间下界来判断，而不是只看原始失败率。

自动暂停默认关闭。请在 channel 的以下字段中配置：信息或 channel set:

失败率阈值 以基点计算 (500 = 5%)。必须设置阈值才能触发策略。
窗口分钟 (默认: 60)。
置信度 介于 0 以及 1 (默认: 0.95).
可选的最小尝试次数和失败次数，以避免因样本量过小而误触发。
冷却时间 分钟（默认：60），以防止重复操作。
操作: pause, rollback，或 notify.

pause 停止新的 rollout 曝光， rollback 清除目标并回退至稳定版本，且 notify 发送 rollout 警报，但不改变 rollout 发布状态。

bunx @capgo/cli@latest channel set production com.example.app \
  --auto-pause-enabled \
  --auto-pause-failure-rate-bps 500 \
  --auto-pause-window-minutes 60 \
  --auto-pause-confidence 0.95 \
  --auto-pause-min-attempts 100 \
  --auto-pause-min-failures 5 \
  --auto-pause-action pause \
  --auto-pause-cooldown-minutes 120

API 与 dashboard 入口

Dashboard： app → 通道 → channel → 信息 → 渐进式发布
Channels API： 公开 Channels API 用于发布字段、提升和回滚
Bundle 分配 API： PUT /bundle/ 配合 target: auto, stable，或 rollout

有关常规 channel 路由和设备优先级，请参阅通道. 若需在渐进式发布之外进行紧急 bundle 恢复，请参阅回滚 live update.