故障复盘 Postmortem：5 段式模板

读完这篇你会

• 用 5 段式模板结构化复盘一次线上故障
• 把复盘沉淀成可执行的检查项（不是抱怨贴）
• 建立团队 / 个人可复用的复盘库

适用版本

Compatible with: dsh 0.1.1-rc.2（基于 SRE 行业最佳实践 + 本地故障案例整理）

为什么 DSH 生态需要 postmortem

DSH 的插件生态处于早期：插件数量快速增长 + 多 profile + 沙箱 + 双 manifest + Cordis — 任何一层出错都会变成「我这个会话怎么不动了」。没有复盘库的生态会反复踩同一类坑。

postmortem 不是「认错书」，是把一次故障的根因 + 处置 + 后续防御结构化记录，让团队下次遇到相似症状能 5 分钟内定位。

5 段式模板

每篇 postmortem 五个固定 section（h3 即可，h2 留给标题）：

1. 摘要（Summary）

两句话讲清：什么坏了 + 影响范围 + 持续时间。

示例：2026-08-15 14:32–14:47 UTC，webprofile 下modlens 插件间歇性无法读取 PNG（影响约 30% 用户，15 分钟）。根因：sharp` 原生模块在 Node 22.23 升级后 ABI 不兼容。

2. 时间线（Timeline）

UTC 时间戳 + 关键事件：

• 14:32 — 用户 A 首次报告，agent 反馈 "image read failed"
• 14:35 — 第二个 / 第三个用户同症状；判定为共同依赖问题
• 14:38 — 查 dsh --profile web --dump-resources 发现 sharp.so 加载失败
• 14:42 — 回滚到上一个稳定版本（modlens 0.4.2）
• 14:47 — 受影响用户全部恢复

3. 根因（Root cause）

技术解释，不要写「人为失误」或「运气不好」——根因必须是机制：

[email protected] 依赖 Node 22 的 N-API v8；Node 22.23 升级到 N-API v9 后，预编译的 sharp.so 拒绝加载（错误码 ERR_DLOPEN_FAILED）。modlens 0.4.3 直接依赖 [email protected]，未声明 Node ABI 范围。

4. 处置与防御（Mitigation）

立即行动 + 长期防御：

立即（24h 内）：

• 回滚 modlens 到 0.4.2
• 在 README 加 Node 22.23 已知不兼容声明
• 联系 sharp 维护者跟进

长期（1 个月内）：

• 在 dsh.bundle schema 加 node_abi_range 字段，CLI 安装时校验
• CI 加 matrix 测试（Node 22.20 / 22.23 / 22.24）
• modlens 升级到依赖 [email protected]+（已修 ABI 兼容）

5. 教训（Lessons）

可迁移到其他插件 / 其他团队的部分：

• 依赖原生模块的插件必须声明 ABI 范围——不只是 README 写一句，bundle manifest 必须有结构化字段让 CLI 卡死
• 回滚能力比修复能力更重要——0.4.2 在 5 分钟内可回滚，比排查 + 修代码 10 分钟短
• 用户报告是真实的「探针」——3 个用户同症状 = 共同依赖问题，不要等第 4 个

不要写什么

• 不要写「我们学到了 X」这种空洞总结——必须可执行
• 不要写责任归属（除非涉及合规）——postmortem 是 blameless 的
• 不要在 24h 内急着发布——先冷静，先修，先观察 48h

怎么沉淀为可复用检查项

每篇 postmortem 末尾加「衍生任务」：

## 衍生任务
- [ ] [dsh-cli#482](https://...) — bundle schema 加 node_abi_range 字段
- [ ] [modlens#91](https://...) — 升级 sharp 到 0.33+
- [ ] [deepseek-plugin.org#55](https://...) — 教程「安装常见问题」加 ABI 兼容小节

任务挂在各仓库的 issue 里，不挂在 postmortem 里——postmortem 只记录「为什么有这个任务」，任务进度在 issue 跟踪。

FAQ

postmortem 应该多久写一次？

每次线上影响 ≥5% 用户的故障后 24h 内写完。低于阈值的进「故障日志」周报，不开正式 postmortem。

故障还在发生中能写 postmortem 吗？

不能。先止血 → 观察 48h 确认稳定 → 再写。带病写 postmortem 容易遗漏根因。