渐进式发布

复制一个包含安装步骤和本插件的源码指南的可复制命令。

渐进式发布会保留一个渠道的 稳定fallback 在发布一个单独的 rollout 目标 向控制设备的子集进行 大多数生产用户保持稳定。只有 rollout 队列中的设备才能接收候选者，直到您 完成 rollout 或.

渐进式发布控制在一个Capgo频道 — 回滚 rollout **进展式 rollout 控制在一个 __CAPGO_KEEP_0__ 频道** The **进展式 rollout** 频道的信息板块显示 **rollout 目标和**，控制百分比和滚动操作。

如何进行渐进式发布的端到端工作

每个频道可以同时有两个捆绑链接：

控制台标签	API / CLI	谁接收到它
稳定fallback	稳定捆绑（`version` 在频道POST)	频道上的每台设备不在在发布版群中
发布目标	发布目标（`rolloutVersion` / `rollout_version`)	仅在发布版群中Capgo随机选择的设备，启用并且未暂停

每次更新检查发生什么

设备询问Capgo是否有更新
如果发布 已禁用, 或者没有目标,Capgo服务于 稳定fallback.
如果发布是启用并且暂停设备已经在队列中，保持发布目标 ；其他人接收发布目标 稳定fallback.
如果发布是启用并且没有暂停,Capgo检查该设备是否属于滚动发布的分组:
- 在分组中 →发布目标。
- 不在分组中 →稳定fallback。

Capgo为每个符合条件的设备生成随机决定，然后使用设备ID和发布ID的哈希值缓存它。这使得分组粘性在配置的缓存持续时间内而不是每次更新检查时重新发布。

启用发布

发布需要一个稳定的fallback。在控制台中，先在发布目标前分配稳定的包。 Public Channels API一个现有的频道可以提供 version 和 rolloutVersion 在同一个POST请求中。

开始交付：

设置 发布目标 (或上传/分配一个包 — 见上传和分配包).
选择 percentage 和点击 应用百分比.
点击 启用发布.

直到您启用发布，配置目标和百分比不会改变接收设备。

百分比变化

在控制台中编辑百分比并点击 应用百分比 以保存它。 Capgo 在可以的情况下保留现有的决策：

增加百分比 — 已选设备保持选中状态；仅随机添加未选中的设备的子集。
减少百分比 — 已选设备子集中的随机设备返回到稳定fallback。
设置百分比为0% — 不会选择新的设备。已启用滚动目标的设备继续接收该目标，直到您禁用、回滚或更改目标。
暂停滚动 — 停止新设备进入，已运行启用目标的设备继续接收该目标。
禁用滚动 — 停止解析滚动目标；更新检查使用稳定fallback。

上传并分配包

在频道上使用配置了渐进式发布，新上传和包链接默认都会指向 发布目标 。 稳定版本 不会改变，除非您明确选择替换它。

当您上传或链接一个包到一个配置了发布的频道时，控制台会显示标题和提示: 本频道使用渐进式发布 新上传和包链接在本频道默认都会指向发布目标。稳定版本不会改变，除非您选择替换它。

Live Update

选择 bundle 应该落地的位置：

控制台选择	何时使用
自动（推荐）	默认。与滚动目标当进度滚动配置时，相同于替换稳定当它不是。匹配API `target: "auto"` 并且CLI上传没有 `--stable` 或 `--rollout`.
滚动目标	发布候选版本; 稳定版本保持不变。
替换稳定	故意替换生产稳定（逃生门）

提示 自动使用滚动更新 应用于 API target: "auto" 并且应用于 CLI 上传的文件 --stable 或 --rollout.

应用于 HTML 文本片段

应用于 __CAPGO_KEEP_0__	默认上传路由	稳定fallback	进展式发布目标
否已配置进展式发布	落地于频道	设置为上传	实时更新
已配置进展式发布	落地于频道	未变更	设置为上传

CLI 和 API 路径

如何部署包	稳定fallback	发布目标	注意
`bundle upload --channel <name>` (无额外标志)	在发布渠道上保持不变; 设置当没有发布时	设置在发布渠道上	与控制台默认值匹配。
`bundle upload --channel <name> --rollout <percent>`	未改变	设置在达到该百分比时启用一步上传+启用替换	逃生门 — 有意的稳定替换
`bundle upload --channel <name> --stable`	而不是	未改变	无
`bundle upload` 逐步发布启用 `--channel`	未改变	Unchanged	仅注册; 链接到 `channel set` 或 API。
控制台链接对话框 → 自动（推荐）	在发布渠道中保持不变	设置在发布渠道中保持不变	默认选择
控制台链接对话框 → 发布目标	Unchanged	设置	明确的发布目标
控制台链接对话框 → 替换稳定	已替换	未变更	逃生门.
PUT `/bundle/` 与 `target: "auto"`	未变更的发布渠道	设置在发布渠道上	API 默认值。
PUT `/bundle/` 与 `target: "rollout"`	未变	设置	context: 与Capgo UI更长的字符串（父键 `compare_capawesome_step2_text`）相关的HTML文本片段。页面/区域：Capgo营销网站。角色：长营销或法律段落。见于：页面alternatives/capawesome.astro。保留Capgo产品/品牌和开发者术语的原始形式。消息键 `compare_capawesome_step2_text`（Compare Capawesome Step2 Text）。
PUT `/bundle/` 与 `target: "stable"`	明确的发布目标。	未变	替换了的内容。
`channel set --bundle <version>`	明确的发布目标。	Unchanged	显式稳定覆盖
`channel set --rollout-bundle <version>` (+ `--rollout-percentage`, `--rollout-enable`)	Unchanged	设置或更改	配置目标不上传
Channels POST `version`	替换设置时	Unchanged	显式稳定覆盖
Channels POST `rolloutVersion`	Unchanged	设置或更改当设置	程序化目标分配。

CLI示例

默认上传到一个配置了回滚的频道（回滚目标；稳定未变）:

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

上传、设置回滚目标并在5％时启用:

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 \
  --stable

不链接上传，之后配置滚动发布：

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 When you need more detailed steps than whole percentages (for example) 50 = 0.5%).

See the CLI reference and CLI reference For every rollout option. Console UX is available in capgo.app#3313.

渐进式发布部分

Channels Channels __CAPGO_KEEP_0__ 信息 → 渐进式发布.

该部分显示 发布目标 和 稳定fallback 用于两个捆绑包链接。使用 更改发布目标 来选择一个不同的候选捆绑包。编辑百分比后，点击 应用百分比 保存它。

控制	它做了什么	已经加入的设备	新符合条件的设备
改变发布目标	集合 `rolloutVersion`改变它会启动一个新的发布ID和一个新的集合。上传或分配一个包到通道（默认）也会设置发布目标。	保持之前的目标直到他们再次检查并符合新的决策规则。	根据新目标的百分比选择
应用百分比	保存您输入的百分比	在增加时保留；在减少时可能会随机丢弃。	根据上述百分比规则添加或排除
启用发布	启用发布后，会将配置的目标和百分比的内容分发给目标设备。	下次更新检查后才会立即生效。	下次检查时可能会被选中。
暂停发布	停止新设备进入发布阶段。	继续发布到相同的目标。	下次检查时接收稳定的fallback。恢复发布
清除暂停状态。	未改变。	下次检查时可能会被选中。	下次检查时可能再次被选中。
关闭发布	停止解析发布目标；Capgo使用稳定fallback为所有人。	切换到稳定fallback 下次检查时	接收稳定fallback。
发布完成 (API: `promoteToStable`; CLI: `--rollout-promote`)	将发布目标设置为新的稳定fallback，然后清除发布状态。确认由发布完成进展？ ——目标变为稳定，所有人，之前的稳定fallback被替换，百分比重置。	成为稳定fallback 为所有人。	接收完成的捆绑包作为稳定。
回滚发布 (API: `rollback`; CLI: `--rollout-rollback`)	清除目标，禁用发布，重置百分比为 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

或 全局发布 安全工作流程 回滚发布发布目标包裹将被保护直到你

发布目标包裹将被保护直到你

渐进式发布是为了让您在生产环境中验证而不需要一次性切换整个频道。实用的顺序:

确认稳定fallback是健康的。 它应该是您愿意继续为大多数用户提供的版本。
上传候选版本 到发布配置的频道（bundle upload --channel <name> 落地于 发布目标 并离开 稳定fallback 单独）或使用 --rollout <small-percent> 来启用在同一步骤中暴露
开始小规模 — 1–5% 就足够作为首次信号。点击 应用百分比,然后 启用滚动启用自动暂停，如果你想在失败率飙升时让Capgo停止暴露。
监控之前不要扩大。 使用观察版本健康错误模式渠道历史配置变更的标签页。比较滚动目标与稳定fallback;不要增加百分比，直到小组看起来健康。
逐渐增加 —— 编辑百分比，点击 应用百分比,并逐步增加（例如5% → 25% → 50% → 100%）。Capgo在增加时保留小组中已有的设备。
完成滚动部署时感到自信 —— 确认 完成渐进式滚动部署? 这样候选者就成为每个人稳定的fallback。
如果出现问题，请先暂停滚动部署 —— 停止新暴露，调查期间设备仍在坏版本上 回滚发布 或 回滚发布.

自动暂停策略

Capgo 每五分钟可以评估一个启用的滚动部署，并在其失败信号超过阈值时采取行动。它测量滚动部署目标在所选频道和时间窗口中的安装和失败次数，然后使用威尔逊置信度下限，而不是单独的失败率。

自动暂停默认禁用。配置这些字段在频道的“信息” 信息失败率阈值 channel set:

（= 5%）。阈值是策略触发所需的。 时间窗口500 分钟（默认：60）。
置信度 之间
Confidence between 0 和 1 (default: 0.95).
避免基于样本数量过小的操作的最小尝试次数和失败次数。
冷却分钟（默认值：60），防止重复操作。
动作: pause, rollback或 notify.

pause 停止新发布的曝光 rollback 清除目标并返回稳定fallback，并 notify 发送发布警报而不改变发布分发。

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 和控制台入口点

控制台： 应用 → 频道 → 频道 → 信息 → 渐进式发布
频道 API： 公共频道 API 用于发布、推广和回滚
分配包 API： PUT /bundle/ 与 target: auto, stable, 或 rollout