# 回滚 Runbook

更新日期：2026-03-24

## 适用范围

- 当前仓库的本地/单节点发布回滚
- 配置错误、发布态校验失败、健康检查失败、认证主链路异常等需要快速回退的场景

## 触发条件

- `/health/ready` 连续失败
- 发布后 `auth/capabilities`、登录、后台关键页面出现回归
- 新版本被 release 模式配置校验拒绝启动
- 5xx、认证失败、权限异常等核心指标显著恶化

## 前置要求

- 保留上一版稳定配置与制品路径
- 发布前已完成数据库备份
- 当前环境可通过 `UMS_CONFIG_PATH` 切换配置
- 健康检查与认证探针可访问：
  - `GET /health`
  - `GET /health/ready`
  - `GET /api/v1/auth/capabilities`

## 标准步骤

1. 立即冻结当前发布，停止继续变更。
2. 保存候选版本 stdout/stderr、配置文件、探针失败结果。
3. 停止候选实例。
4. 将 `UMS_CONFIG_PATH` 指向上一版稳定配置，并启动上一版稳定制品。
5. 验证回滚后的实例：
   - `/health` 返回成功
   - `/health/ready` 返回成功
   - `/api/v1/auth/capabilities` 返回符合预期
   - 如涉及前端链路，执行 `cd frontend/admin && npm.cmd run e2e:full:win`
6. 记录回滚原因、影响范围、恢复时间和后续修复动作。

## 数据边界

- 如果问题仅是配置或应用层回归，应优先执行配置/制品回滚。
- 如果怀疑数据损坏，不应直接做 schema downgrade；应先执行备份恢复流程并评估数据影响。
- 当前仓库已经完成的是本地配置/制品回滚演练，不等于历史版本之间的数据库降级兼容性证明。

## 本地演练

- 演练脚本：
  - [`scripts/ops/drill-local-rollback.ps1`](/D:/project/scripts/ops/drill-local-rollback.ps1)
- 最新演练证据：
  - [`docs/evidence/ops/2026-03-24/rollback/20260324-084928/ROLLBACK_DRILL.md`](/D:/project/docs/evidence/ops/2026-03-24/rollback/20260324-084928/ROLLBACK_DRILL.md)

## 关联材料

- 备份恢复演练：
  - [`docs/evidence/ops/2026-03-24/backup-restore/20260324-072353/BACKUP_RESTORE_DRILL.md`](/D:/project/docs/evidence/ops/2026-03-24/backup-restore/20260324-072353/BACKUP_RESTORE_DRILL.md)
- 配置与环境隔离演练：
  - [`docs/evidence/ops/2026-03-24/config-isolation/20260324-084915/CONFIG_ENV_ISOLATION_DRILL.md`](/D:/project/docs/evidence/ops/2026-03-24/config-isolation/20260324-084915/CONFIG_ENV_ISOLATION_DRILL.md)