59 lines
2.4 KiB
Markdown
59 lines
2.4 KiB
Markdown
# 回滚 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)
|