回滚与交付版本

本文面向运维人员，说明当一次交付出问题时如何把目标服恢复到期望状态。回滚是高风险写操作，全部入口都走审批；不要在目标服上手工覆写文件来代替回滚。

前置阅读：配置、文件与交付。回滚的粒度、生效方式与观察窗语义都与该页一致。

1. 先判断该回滚什么

出问题后第一步不是点回滚，而是分清粒度：

情况	该用的动作
只有少数几台配错 / 异常	子集回滚（只回滚选中目标，见 §4）
整批都有问题	整单回滚（见 §3）
回滚里有目标失败，其余成功	回滚重试（只重试失败目标，见 §5）
故障根因在配置而非文件	注意：子集回滚不回退配置版本，需整单回滚

为什么优先子集：事故现场常见「某个小区那几台配错了」，而整单回滚会把没问题的几十台一起打回——二次事故风险往往大于原始故障。

2. 先到「交付历史」找到这张单

已经结束的单（走完、整单回滚、被取消）都归档在侧栏「交付 → 交付历史」——排障时从这里进，进行中的单仍在「变更单」页。

1. 页眉必须先选具体命名空间。 交付历史的读取范围与页眉左侧的环境 / 命名空间选择器同源；停在「全部命名空间」时页面只给引导、不渲染列表与详情——因为详情里有整单回滚这类写操作，全局范围下没有明确目标。
2. 在列表里按标题搜索、按状态过滤。「已完成」表示全部批次都生效，「已回滚」表示整单已退回原版本。
3. 打开一条单，详情四个页签对应「出过什么事」的四个角度：
   • 执行回放：按时间推进看这一单是怎么走的。
   • 变更内容：这单到底改了什么（配置版本 / 文件差异）。
   • 交付编排：批次怎么分、每批几台。
   • 进度时间线：逐条事件，含实时推送与回退到 5 秒轮询的状态。
4. 详情下方是批次状态与单服状态两张表，单服状态带独立的「回滚状态」列（待回滚 / 回滚中 / 已回滚 / 回滚失败）——判断「哪几台还没回来」就看它。
5. 要接着操作时用「在变更单中打开」跳到对应变更单；整单回滚与结束回滚就在本页详情底部。

3. 整单回滚

整批都出问题时用整单回滚：所有目标退回上一状态，并一并回退配置版本（这是它和子集回滚的关键差别）。

1. 在「交付历史」或变更单里打开这条单，点「整单回滚」。只有已完成 / 已暂停 / 已取消的单能发起；还在推进的单请先暂停或紧急终止（见 §7），等它落到可回滚状态。
2. 确认弹窗是高摩擦的：先看回滚预检——要么「全部目标均可文件回滚」，要么列出「N 台因备份缺失不可文件回滚」及其 serverId（这些在回滚中会直接判失败）；显示「预检不可用」时先去单服状态墙核对备份标记，不要当成全部可回滚。确认预检无误后再填回滚原因、按提示手输「回滚」二字。
3. 发起后走审批。执行期间详情顶部显示回滚横幅与进度（已回滚 / 回滚失败 / 未回滚），不要重复发起。
4. 完成后逐台核对批次与单服状态；回滚动作记录会新增一条（操作人、时间、原因、台数、是否回退了配置版本）。仍有残留失败目标时按 §5 重试，处理完再用「人工结束回滚」收单。

4. 子集（目标级）回滚

1. 打开该单的目标列表——在「交付历史」详情里是「单服状态」，在进行中的变更单里是目标列表；先按批筛选，再勾选需要回滚的目标。
2. 发起「回滚选中目标」（MCP 客户端可用 beacon.delivery.order.rollback 并传 serverIds）。
3. 确认弹窗内先看预检：
   • 会列出备份缺失、因而无法文件回滚的目标数与 serverId 清单。
   • 显示「预检不可用」时不要当成「全部可回滚」：要么预检没跑成功，要么选中集合里有当前页之外的台——子集预检只对已读到的行给结论，跨页勾选就会整体标为不可用。
4. 填写原因、按提示手输「回滚」确认、走审批后执行。全程写审计与回滚动作记录。

必须知道的四点语义：

• 子集回滚只还原文件，不回退配置版本。界面与回滚记录都会明示「配置未回退」。若故障根因是配置错误，子集回滚不会修复它。
• 变更单主状态不变：已 completed 的单仍是 completed，回滚结果落在目标级回滚态（rollback_status）。
• 勾满全部可回滚目标 ≠ 整单回滚：判定按「可回滚目标数」而非总台数；但若你确实勾满了全部可回滚目标，效果等价于整单回滚（含配置版本回退）。
• 每个目标的结果与失败原因都在状态墙上，可逐台核对。

5. 回滚失败后重试

旧口径下「回滚里还有失败目标」只能「结束回滚」，把残留失败当既成事实收单。现在 rolling_back 的单可以直接重试：

1. 先看目标级 rollback_status / rollback_error，区分两类原因：
   • 备份缺失 —— 这台重试也没用，需要人工处理或接受现状。
   • 下发失败（网络、Agent 忙、临时错误）—— 值得重试。
2. 单仍停在 rolling_back 且仍有失败目标时，再次发起回滚即重试（原因必填、走审批、幂等键独立）。
3. 不要改单状态、也不要手工覆写目标服文件来「绕过」回滚。
4. 重试不会再回退配置版本（配置回退只能发生一次）。
5. 确认剩余失败确实无法回滚后，才用「结束回滚」收单。

6. 查「这台现在跑的是哪个版本」

事故里最常问的两个问题，现在都能在界面上答：

① 这台现在跑的是哪一单交付的版本？

• 目标列表逐行、以及服务器健康详情，都能看到当前交付版本：单号 / 标题 / 生效时间。
• 该服被回滚后会自动回退显示上一单；从未交付过则显示「无交付记录」。
• 因此排障时不必再翻审计流拼时间线。

② 这次事故回滚过几次、谁发起的、为什么、打到哪几台？

• 变更单详情的回滚动作记录：每次整单回滚 / 子集回滚 / 重试各一条，含操作人、时间、原因、台数、是否回退了配置版本、以及逐台结果。
• 记录与审计同事务且互指：从审计条目里的 recordId 能跳到对应动作，反之亦然。
• 「结束回滚」是收单动作、不落动作记录（只写审计）——查不到它属正常，不是记录丢失。

7. 紧急终止：在途目标会被收口为失败

点「紧急终止」（cancel）可对 rolling / paused 的单发起，reason 必填。终止后的状态语义必须分清：

目标原状态	终止后	含义
从未开始（pending）	skipped	确实没动盘
已推送 / 生效中（pushing / pushed / activating）	failed	已经动过盘，原因固定为「变更单已紧急终止，目标未确认生效」
已成功（activated）	不变	保持成功

⚠️ 终止不等于安全。看到一批 failed 不要以为「交付失败了」，那是终止收口。这些目标已经动过盘，必须检查并按需回滚。

8. 回滚安全性：备份与校验

• 同单重推不会覆盖或清空既有备份（增量合并）。因此「再推一次」在回滚安全性上是安全的，不会毁掉之前的回滚点。
• 还原前会校验文件大小与哈希，不符直接判 failed，而不是写坏文件。
• 备份缺失的目标无法做文件回滚——这正是子集回滚预检要列出来的东西。

9. 回滚后验收

• 所有目标都落到终态，failed / skipped 均有解释。
• 逐台核对回滚结果与失败原因（状态墙）。
• 确认「配置是否回退」符合预期（子集回滚不回退配置）。
• 交付版本展示已回退到上一单（或被正确标记为无记录）。
• 回滚动作记录与审计可互相印证。
• 观察窗内健康、TPS、玩家数恢复。

详细症状分流见 排障手册。