Incident Retrospective

postmortem-writer

基于 Google SRE 和行业最佳实践的 Blameless Postmortem 撰写流程。通过结构化的 SOP 引导你完成从事故信息收集、时间线梳理、5 Whys 根因分析到改进措施制定的完整复盘过程，输出专业的事故复盘文档。

核心理念：Blameless（无责文化） — 关注系统和流程的改进，而不是追责个人。

Quick Start

交互式复盘（推荐）：直接描述你的事故情况，Agent 将按照 SOP 流程引导你逐步完成复盘。

一键生成文档：如果你已经有完整的事故信息，可以用脚本快速生成格式化的复盘文档：

python3 scripts/generate_postmortem.py --interactive

或提供 JSON 输入直接生成：

python3 scripts/generate_postmortem.py --input incident.json --output postmortem.md

SOP 流程：六步完成专业复盘

第一步：事故概况收集

收集以下基本信息，构建事故全貌：

严重等级分级标准：

第二步：时间线梳理

按时间顺序记录事故全过程，精确到分钟。每个事件需标注类别：

时间线示例：

14:25  ACTION   部署 payment-service v2.3.1 到生产环境
14:32  TRIGGER  支付成功率从 99.8% 开始下降
14:35  DETECT   监控告警：支付成功率 < 95%
14:38  DETECT   客服接到用户反馈支付失败
14:42  ACTION   值班 SRE 开始排查，定位到 payment-service
14:55  ACTION   尝试重启 payment-service pod（无效）
15:10  ACTION   分析日志发现数据库连接池耗尽
15:25  ACTION   回滚 payment-service 到 v2.3.0
15:30  RESOLVE  支付成功率恢复至 99.5%
16:45  RESOLVE  积压订单全部处理完毕，确认完全恢复

关键度量指标（梳理时间线时同步记录）：

• TTD (Time to Detect)：从故障发生到被发现的时间
• TTR (Time to Resolve)：从故障发现到恢复的时间
• TTN (Time to Notify)：从故障发现到通知相关方的时间
• 影响用户数 / 影响请求数 / 经济损失估算

第三步：5 Whys 根因分析

5 Whys 是一种通过反复追问"为什么"来穿透表面原因、找到根本原因的分析方法。

执行规则：

1. 从直接原因开始，每次追问"为什么会发生这个？"
2. 至少问 5 层，直到触及可改进的系统/流程层面
3. 每一层的回答必须基于事实和证据，不是猜测
4. 如果一个"为什么"有多个原因，分支展开分别分析
5. 最终的根因应该指向系统或流程缺陷，而不是某个人的失误

分析示例：

现象：支付服务 P99 延迟飙升至 30s

Why 1: 为什么延迟飙升？
  数据库连接池被耗尽，请求排队等待连接

Why 2: 为什么连接池被耗尽？
  新版本引入了一个未关闭数据库连接的 bug

Why 3: 为什么这个 bug 没在上线前被发现？
  单元测试没有覆盖数据库连接释放的场景

Why 4: 为什么没有这类测试？
  没有针对资源泄漏的测试规范和 checklist

Why 5: 为什么没有这个规范？
  团队缺少针对资源管理的 code review checklist 和自动化检测

根因：缺少资源泄漏（连接池/文件句柄等）的自动化检测机制和 code review 规范

常见根因分类：

第四步：改进措施制定（Action Items）

每条改进措施必须满足 SMART 原则：

改进措施分类：

第五步：经验教训总结

从三个维度总结：

1. 做得好的地方（Keep Doing）

• 哪些响应环节做得好？为什么有效？
• 有什么值得沉淀为标准流程的？

2. 做得不好的地方（Stop Doing / Improve）

• 哪些环节拖慢了恢复速度？
• 有什么不必要的操作浪费了时间？

3. 运气因素（Lucky / Unlucky）

• 有什么是"碰巧"避免了更大影响的？
• 有什么是"碰巧"加剧了影响的？
• 这些运气因素揭示了什么潜在风险？

第六步：生成复盘文档

使用脚本生成格式化的 Markdown 文档：

python3 scripts/generate_postmortem.py --interactive

也可以将前几步收集的信息整理为 JSON 后直接生成：

python3 scripts/generate_postmortem.py --input incident.json --output postmortem.md

Blameless 无责文化原则

在整个复盘过程中，严格遵守以下原则：

1. 关注系统，不追责个人 — "张三部署了有 bug 的代码"应改为"部署流程缺少自动化回归测试"
2. 人犯错是正常的 — 如果一个人的失误就能导致重大故障，说明系统缺少防护机制
3. 鼓励透明 — 越是坦诚地分享错误细节，越能找到真正的改进点
4. 用数据说话 — 时间线和根因分析必须基于日志、监控数据、配置记录等客观证据
5. 面向未来 — 复盘的目的是"下次怎么做更好"，而不是"这次谁做错了"

文档中的措辞检查清单：

脚本参数说明

generate_postmortem.py

JSON 输入格式

{
  "title": "支付服务 P99 延迟飙升至 30s",
  "severity": "P1",
  "start_time": "2024-03-15T14:32:00+08:00",
  "end_time": "2024-03-15T16:45:00+08:00",
  "impact": "华东区约 30% 用户支付失败，影响约 5000 笔交易",
  "responders": ["张三 (SRE on-call)", "李四 (支付团队)"],
  "timeline": [
    {"time": "14:25", "type": "ACTION", "desc": "部署 payment-service v2.3.1"},
    {"time": "14:32", "type": "TRIGGER", "desc": "支付成功率开始下降"},
    {"time": "14:35", "type": "DETECT", "desc": "监控告警触发"},
    {"time": "15:25", "type": "ACTION", "desc": "回滚到 v2.3.0"},
    {"time": "15:30", "type": "RESOLVE", "desc": "服务恢复"}
  ],
  "five_whys": [
    {"level": 1, "question": "为什么延迟飙升？", "answer": "数据库连接池耗尽"},
    {"level": 2, "question": "为什么连接池耗尽？", "answer": "新版本未正确释放连接"},
    {"level": 3, "question": "为什么没在上线前发现？", "answer": "测试未覆盖连接释放"},
    {"level": 4, "question": "为什么没有这类测试？", "answer": "无资源泄漏测试规范"},
    {"level": 5, "question": "为什么没有规范？", "answer": "缺少资源管理 checklist"}
  ],
  "root_cause": "缺少资源泄漏自动化检测机制和 code review 规范",
  "root_cause_category": "流程缺陷",
  "action_items": [
    {
      "type": "mitigate",
      "desc": "为连接池添加泄漏检测和自动回收机制",
      "owner": "李四",
      "due": "2024-03-25",
      "priority": "P0"
    },
    {
      "type": "detect",
      "desc": "添加连接池使用率监控和告警",
      "owner": "张三",
      "due": "2024-03-22",
      "priority": "P0"
    }
  ],
  "lessons": {
    "keep_doing": ["告警后 3 分钟内 SRE 响应", "回滚决策果断"],
    "improve": ["部署后需要自动化的 smoke test", "告警升级机制需优化"],
    "lucky": ["故障发生在下午非高峰时段，否则影响更大"]
  }
}

参考资料

• Google SRE Book - Postmortem Culture
• Etsy: Blameless PostMortems and a Just Culture
• PagerDuty Postmortem Guide
• The Infinite Hows (replacing 5 Whys)