生产问题排查 Runbook

一句话：Runbook 就是线上出问题时的操作手册，让你不靠临场发挥，也能按步骤定位、止血、恢复和复盘。

本篇学完你会什么：知道生产故障发生后先做什么、后做什么，如何判断影响范围，怎么止血，怎么记录，以及复盘应该写哪些内容。

1. Runbook 是什么

Runbook 可以理解成：

线上系统出事时的说明书。

它不是长篇大论，而是告诉你：

先看哪里
怎么判断严重程度
谁来处理
怎么止血
怎么恢复
怎么记录

没有 Runbook 时，故障现场容易变成：

有人看日志
有人重启服务
有人改配置
有人问是不是数据库
最后没人知道到底做了什么

有 Runbook，至少能让大家按同一个顺序行动。

2. 出问题时先别急着改代码

故障发生时，最容易犯的错是马上改代码。

正确顺序是：

确认影响
止血
定位原因
恢复服务
复盘和修复根因

为什么先确认影响？

因为不同影响范围，处理优先级不一样：

影响	优先级	例子
全站不可用	最高	首页、登录、核心接口都挂
核心功能不可用	很高	无法下单、无法登录
部分功能异常	中高	某个报表打不开
单个用户问题	中	某个账号数据异常
展示小问题	低	文案、样式、小图标

线上处理最重要的是恢复用户可用，而不是第一时间证明谁写错了。

3. 故障处理四步法

第一步：确认

问清楚：

什么时候开始的？
影响哪些用户？
影响哪些接口或页面？
错误是一直发生还是偶发？
最近有没有发布？

马上看：

健康检查
错误率
响应时间
请求量
最近发布记录

第二步：止血

可选动作：

动作	适合
回滚上一版	新发布导致故障
关闭功能开关	新功能异常
扩容	流量突增
限流	被刷或成本失控
切备用服务	依赖不可用
暂停任务	后台任务压垮数据库

止血不是最终修复，但能先减少损失。

第三步：定位

按链路查：

前端页面 -> API 网关/Nginx -> 后端接口 -> 数据库/Redis -> 第三方服务

每一步看：

有没有请求到达？
状态码是什么？
耗时在哪里变长？
日志有没有 request_id？
错误是不是集中在某个接口？

第四步：恢复和记录

恢复后要确认：

错误率回落
响应时间正常
核心接口可用
用户反馈停止增加
监控稳定一段时间

同时记录：

发生时间
发现方式
影响范围
处理动作
恢复时间
初步原因
后续改进

4. 常见场景排查表

现象	先看	常见原因
全站 502	Nginx、后端进程	服务没启动、端口错、容器挂了
登录大量失败	auth 日志、Redis、数据库	token 配置、密码校验、限流误伤
接口 500 增多	错误日志、最近发布	未处理异常、字段为空、依赖失败
列表页很慢	SQL、分页、N+1	没索引、查询太大、关系懒加载
数据不对	最近任务、迁移、操作日志	脚本写错、缓存没失效
AI 接口慢	模型服务、向量库、top_k	外部模型慢、检索参数过大
磁盘满	日志目录、上传目录	日志未清理、文件上传过多

5. 如何止血

止血动作要优先选择“可逆、影响小”的。

推荐顺序：

关闭新功能开关。
回滚最近发布。
降低流量入口或开启限流。
暂停高风险后台任务。
扩容或重启有问题的服务。
必要时进入维护公告。

不要一上来就：

直接改生产数据库
直接删除数据
直接改线上代码
直接清空缓存但不知道影响

高风险操作前，至少要有：

备份
操作人
复核人
回退方案
记录

6. 复盘怎么写

复盘不是追责文档，而是让系统下次更稳。

一个简单模板：

标题：2026-06-30 用户列表接口响应变慢

影响范围：
管理后台用户列表，约 30 分钟 P95 超过 3 秒。

时间线：
10:00 发布新版本
10:08 告警触发
10:12 开始排查
10:20 回滚
10:28 指标恢复

原因：
新代码在列表循环中访问 relationship，触发 N+1 查询。

处理：
回滚上一版，随后使用 selectinload 修复。

改进：
增加列表接口性能测试。
增加慢查询告警。
代码 review 检查 relationship 加载方式。

复盘重点是：

怎么更早发现
怎么更快止血
怎么避免再次发生

7. 常见错误

错误	后果	修正
故障时多人同时乱改	问题扩大	指定一个负责人协调
只盯代码不看监控	定位慢	先看指标和日志
没有记录操作	复盘困难	每个动作记录时间和结果
止血太晚	用户影响扩大	先恢复再深挖
复盘只写“已修复”	下次还会发生	写根因和改进项
高风险操作无备份	数据不可恢复	先备份，后操作

8. 检查清单

[ ] 有核心服务健康检查地址
[ ] 有日志查询入口
[ ] 有监控面板入口
[ ] 有最近发布记录
[ ] 有回滚步骤
[ ] 有数据库备份和恢复方式
[ ] 有常见故障排查表
[ ] 故障处理有人负责协调
[ ] 处理动作会记录时间和结果
[ ] 故障后会复盘

9. 小结

名词	大白话
Runbook	故障处理说明书
止血	先让影响不要继续扩大
回滚	回到上一版可用状态
影响范围	哪些用户和功能受影响
时间线	故障从发生到恢复的记录
复盘	找到根因和下次改进

上一篇建议：先看《接口契约、版本管理和文档》。

下一步建议：把这几篇阶段二文章和项目实战路线结合起来，给自己的项目补一份上线检查表。