incident-postmortem

事故复盘

引导团队在生产事故后撰写一份结构化、无指责的复盘。产出的文档用于建立共识、在不追责的前提下识别根因，并形成具体的行动项以防止再次发生。

无指责原则

出问题的是系统，不是人。目标是理解事故是如何发生的——而不是谁造成的。避免使用“X 忘了”“Y 本应知道”这类表述。应使用“系统没有”“流程缺少”“告警没有触发”。

适用场景

• 生产中断或服务降级已恢复
• 发生了重大的险兆事件（若发现得更晚，本会构成事故）
• 出现了面向用户的错误、数据丢失或 SLA 违约
• 团队希望在上下文淡忘前记录经验教训

不适用： 在预发布环境发现的小缺陷、计划内维护窗口，或没有学习价值的事故。

输入要求

在撰写复盘前收集以下细节。缺失的内容要主动询问：

事故元数据

• 事故标题（简短、描述性）
• 检测日期和时间（含时区）
• 解决日期和时间
• 严重程度/影响级别（P1–P4 或等效分级）
• 事故指挥官/值班负责人

影响

• 受影响的服务和系统
• 面向用户的影响（错误、变慢、完全中断）
• 受影响的预估用户数
• 数据丢失或损坏（是/否，范围）
• SLA/SLO 违约（是/否，超出多少）

时间线事件

需要重建的关键时刻：

• 首个症状出现
• 告警触发（或被人工发现）
• 值班人员被呼叫/事故宣告
• 开始排查
• 定位根因
• 应用缓解措施
• 确认完全恢复
• 发送客户沟通（如有）

促成因素

询问团队：“是什么让情况比本应发生的更糟？”——而不是“谁失败了”。示例：

• 告警阈值过高/告警未触发
• 运行手册缺失或过时
• 部署缺少用于回滚的特性开关
• 监控未覆盖该故障模式
• 值班交接遗漏了上下文

流程

步骤 1 — 收集元数据

如果用户未提供完整的事故细节，请逐节询问。在拿到以下内容前不要开始撰写：标题、时间、严重程度、受影响服务，以及至少一份粗略的时间线。

步骤 2 — 重建时间线

与用户协作构建精确的时间顺序时间线。对每个事件：

• 准确时间（优先使用 UTC）
• 发生了什么（系统事件或人工操作）
• 谁观察到或执行了该操作
• 如可用，附上日志/告警/Slack 消息链接

标注空白：“我们不知道 14:32 到 14:47 之间发生了什么——值得检查日志。”

步骤 3 — 根因分析

迭代使用 5 Whys：

Why did users see 500 errors?
→ The API pods were crash-looping.

Why were they crash-looping?
→ Memory limit was exceeded.

Why was the limit exceeded?
→ A new query was loading full result sets into memory.

Why wasn't this caught before deploy?
→ Load tests only covered the p50 case, not high-cardinality accounts.

Why did load tests only cover p50?
→ We had no test fixtures for large accounts.

当你找到一个可修复的系统/流程缺口时停止。最后一个“为什么”应指向一个行动项。

区分：

• 根因 —— 最深的系统性缺口（一两个）
• 促成因素 —— 使情况恶化但并非根因的条件

步骤 4 — 影响量化

帮助用户做到精确：

• 持续时间：从检测到解决（不是从症状开始到解决——将两者分开）
• 峰值错误率与正常基线
• 受影响流量占比
• 收入/业务影响（如已知）

步骤 5 — 行动项

针对每个根因和促成因素，至少生成一个行动项：

#	行动	负责人	截止日期	优先级
1	为超过 10k 条记录的账户添加负载测试夹具	@eng-team	2026-07-01	高
2	将内存告警阈值从 90% 下调至 75%	@platform	2026-06-23	高
3	为内存 OOM Pod 添加运行手册	@on-call-rotation	2026-06-30	中

行动项必须有负责人（具体的人，而不是团队）和截止日期。像“改进监控”这样的模糊行动不可接受——将其拆分为具体的交付物。

第 6 步 — 编写文档

使用下面的模板撰写完整的复盘报告。保存到 docs/postmortems/YYYY-MM-DD-<slug>.md。

输出模板

# Post-Mortem: [Incident Title]

**Date:** YYYY-MM-DD  
**Severity:** P[1-4]  
**Duration:** X hours Y minutes (HH:MM UTC – HH:MM UTC)  
**Incident Commander:** @name  
**Status:** Resolved

---

## Summary

[2–3 sentences. What happened, what was the user impact, how was it resolved. Written for someone who wasn't involved.]

## Impact

| Dimension | Value |
|-----------|-------|
| Affected services | [list] |
| User-facing impact | [errors / degraded / full outage] |
| Users affected | [estimated number or %] |
| Peak error rate | [X% vs Y% baseline] |
| Data loss | [none / describe scope] |
| SLA breach | [yes/no — by how much] |

## Timeline

All times UTC.

| Time | Event |
|------|-------|
| HH:MM | [First symptom / alert fired] |
| HH:MM | [On-call paged] |
| HH:MM | [Incident declared] |
| HH:MM | [Root cause identified] |
| HH:MM | [Mitigation applied] |
| HH:MM | [Full resolution confirmed] |
| HH:MM | [Customer communication sent] |

## Root Cause

[1–2 paragraphs. The deepest systemic gap that, if fixed, would have prevented the incident. Written in blameless language. Reference the 5 Whys chain if helpful.]

## Contributing Factors

- [Factor 1 — condition that made the incident worse]
- [Factor 2]
- [Factor 3]

## What Went Well

- [Thing that worked — good alert, fast response, clear runbook]
- [Another positive]

## What Could Have Gone Better

- [Gap in process, tooling, or coverage — no blame language]
- [Another gap]

## Action Items

| # | Action | Owner | Due Date | Priority |
|---|--------|-------|----------|----------|
| 1 | [Specific deliverable] | @person | YYYY-MM-DD | High/Medium/Low |
| 2 | | | | |

## Lessons Learned

[Optional. 2–4 bullet points capturing non-obvious insights worth sharing with the broader team.]

常见错误

错误	修正
“Bob 忘了检查配置”	“部署检查清单未包含配置校验”
根本原因是“人为失误”	继续追问 Why — 人为失误永远只是症状
行动项没有负责人	每一项都需要指定具体个人，而不是一个团队
时间线凭记忆重建	撰写前先查看日志、告警、Slack、PagerDuty
把“改进监控”当作行动项	明确说明：哪个服务、哪个指标、什么阈值、何时完成
事后数周才写复盘	在 48–72 小时内撰写，趁上下文还清晰