Runbook 版本化

在 git 随代码版本化 runbook 使其随系统演化和可审查。

为什么

Confluence 中 runbook 无版本 — 某人更新时旧版消失，若更新错（命令笔误、删步）无人见改了什么或回滚。git 中 runbook 有版本：每改是带作者、消息和审查者可查 diff 的提交。系统变时 runbook 在同 PR 变，故代码审查抓 runbook 腐（"你改了服务名但没更新 runbook"）。事件中 runbook 坏时可 git blame 见改了什么何时，需要时回滚。这与我们版本化代码同因：无版本 runbook 不可审查、不可回滚、静默腐 — 版本化 runbook 可审计、可审查、耦合于它描述的系统。

何时使用

runbook 写时。上线前移 git（如服务仓 runbooks/）。

如何做

1. runbook 存 git，服务仓或专用 runbook 仓
   - runbooks/checkout-slo-burn.md 在 checkout 服务仓
   - 或中央 runbook 仓若服务多

2. 要求 runbook 更新与系统变同 PR
   - "服务改名？同 PR 更新 runbooks/*.md。"
   - 代码审查：若变更坏 runbook，runbook 更新须在 PR
   - 这把 runbook 新鲜耦合于系统变

3. 用前置元存元数据
   ---
   owner: @team-payments
   alert: CheckoutSLOBurnRateFast
   last_reviewed: 2026-01-15
   ---
   - 机可读；审计脚本读此

4. 代码审查审 runbook 变更
   - runbook 变更是代码变更；审查者查命令仍工作
   - "你把步 2 从 --take-over 改 --promote — 在 staging 测了吗？"

5. 用 git blame 做事件取证
   - "runbook 说 --take-over 但命令是 --promote — 何时变的？"
   - git blame runbook/db-failover.md → "Alice，2025-12-01，'update for new CLI version'"
   - 若变更致事件 → 回滚并修

示例

# 服务仓结构：
checkout-service/
  src/
  runbooks/
    checkout-slo-burn.md      # 随服务版本化
    checkout-db-failover.md
  deploy/
  ...

# 改服务名的 PR（要求 runbook 更新）：
git diff：
  src/config.yaml：    service_name: checkout → checkout-api
  runbooks/checkout-slo-burn.md：
    - kubectl get pods -n checkout
    + kubectl get pods -n checkout-api
# 代码审查："runbook 同 PR 更新 ✅ — 命令匹配新名"

# 事件取证（runbook 说错命令）：
$ git blame runbooks/db-failover.md
a1b2c3d (Alice 2025-12-01)   kubectl postgres failover --take-over primary
# → Alice 3 月前改此；CLI 标志现是 --promote
# → 回滚此行，修为 --promote，runbook 审计加测试

# 审计脚本读前置元：
$ yq '.last_reviewed' runbooks/checkout-slo-burn.md
2026-01-15  # <90 天，新鲜 ✅

常见问题

⚠runbook 在 Confluence — 无版本、不可审查、静默腐；坏时无法见改了什么或回滚。
⚠runbook 在异于代码的仓 — 系统变和 runbook 更新在不同 PR，故代码审查抓不到耦合。
⚠无前置元 — 审计脚本找不到 owner 或 last_reviewed，故新鲜跟踪手动且不发生。
⚠runbook 变更不代码审查 — 命令笔误静默发布并在最坏时坏 runbook。

最佳实践

✓runbook 存 git 服务仓（或中央 runbook 仓）带前置元（owner、alert、last_reviewed）。
✓要求 runbook 更新与系统变同 PR；代码审查拒绝坏 runbook 而不更新的变更。
✓像代码变更审 runbook 变更 — 命令笔误是 bug；要求审查者确认命令仍工作。
✓用 git blame 做事件取证；runbook 坏时见改了什么何时，若变更致事件则回滚。