7.4 KiB
7.4 KiB
生产环境 Bug 快速定位与修复手册(Incident Response Runbook)
版本:v1.0(2026-09-11,Tory 裁决立项) · 适用:go-sms 生产环境(gateway/前端/中间件) 原则:回滚优先于修复;一个 trace_id 讲完整个故事;变更即嫌疑。 关联:开发日历 Day51+ 运维基建排期;Day43 修复循环(vite proxy 500)为首发案例。
0. 响应分级与 SLA
| 级别 | 定义 | 止血 SLA | 修复 SLA | 通知 |
|---|---|---|---|---|
| P0 | 全站不可用/资损(发错/超发/重复扣费) | ≤5min 回滚/降级 | ≤2h hotfix | 电话+强提醒 |
| P1 | 核心降级(下发延迟/某通道全失败/消费堆积) | ≤15min 灰度摘除 | ≤24h | 群机器人 |
| P2 | 局部异常有绕行 | 不止血 | 随下版本 | 每日汇总 |
| P3 | 体验/文案 | — | 排期 | — |
1. 可观测性资产清单(定位工具箱)
| 能力 | 落点 | 用法 |
|---|---|---|
| zap JSON 日志+trace_id | internal/middleware/logger.go(status/latency/client_ip) |
按用户/IP/时间窗过滤 trace_id |
| OTel→Jaeger | internal/middleware/tracer.go(OTLP :14318) |
trace_id 查瀑布图(慢在哪段:MySQL/Redis/Kafka/上游) |
| Prometheus | internal/middleware/metrics.go(GET /metrics) |
5xx 率/QPS/P99 曲线定时间窗 |
| 错误码字典 | ISC:xxx + x-isc-dict(FE dict.ts 同步) |
用户截图码→grep 后端码点 |
| panic 兜底 | internal/middleware/recovery.go |
panic 留日志不崩进程 |
| 健康检查 | GET /health |
探针/发布验证 |
| 审计三表 | SystemOperateLog / SystemLoginLog / SystemErrorCode | 还原操作现场 |
| 慢 SQL | GORM SLOW SQL ≥200ms | DB 层瓶颈 |
| 死信队列 | Kafka *.DLQ | 丢消息排查 |
| 兜底自愈 | 48h Scanner / 锁 watchdog | 已知设计兜底,非紧急 |
| 告警通道(Day53) | Prometheus(宿主 19090)+Alertmanager(19093)→ webhook /api/v1/alerts/sink |
规则:5xx 突增 P0/P99 P1/余额对账差额 P0(R1);grep alerts_sink_alert_received 分级 error/warn |
| 前端错误上报(Day53) | fe_error_log 表+POST /fe-errors;FE 三路采集 | 前端层故障感知(DecisionTree 步骤 2 首查);GET /fe-errors?trace_id= 排障 |
| 资金域四指标(Day54·R1) | go_sms_balance_reconcile_diff{account}(对账差额,P0 规则已挂 for 1m)/_mode(1=redis/0=mysql)/_fallback_total(Redis 基础设施错回退计数)/_flowlog_pending(异步流水积压) |
预扣异常定界:diff>0→§3 数据修复;fallback 涨→Redis 可用性;pending 持续涨→MySQL 写入瓶颈;diff error 日志 grep balance_reconcile_diff_detected 带 runbook 指向 |
基建缺口(上线前补齐,见 §6):告警通道(Alertmanager)、前端错误上报(两项 P0 已于 Day53 落地);日志聚合(Loki)、发布/回滚流水线。
2. 定位 SOP(发现→根因 ≤30min)
步骤 1:定级止血(≤5min)
P0 首选回滚镜像/降级开关,而非现场改代码。止血动作记录时间线。
步骤 2:决策树分流
用户报错
├─ 有 ISC 码 → grep errors/codes.go 定码点 → trace_id 查日志+Jaeger
├─ HTTP 500 无响应体 → 查 gateway 日志有无该请求:
│ · 无 → 代理/CDN/前端层(看 fe-errors 上报;Day43 案例:vite proxy 死端口)
│ · 有 → trace_id 对应日志+span
├─ 慢/超时 → Jaeger 瀑布图定位红段(DB/Redis/Kafka/CMPP 上游)
├─ 数据不一致 → 审计表还原操作序列 + DLQ 查丢消息
└─ 状态机卡死 → message_task.status/audit_status 快照 + Scanner 日志
步骤 3:取证命令
kubectl logs <pod> --since=30m | grep <trace_id> # 单实例
logcli query '{app="gateway"} |= "<trace_id>"' # Loki 跨实例(基建后)
# Jaeger UI 粘贴 trace_id → span 树;MySQL 慢日志+SHOW PROCESSLIST
步骤 4:根因确认
- 变更回溯:
git log $(git describe --tags --abbrev=0 HEAD~1)..HEAD --oneline对照故障时间 - 复现:staging 同参重放(Day48 全链路环境复用)
- 修复:先写回归单测钉死 Bug(如 submit_test.go 400/402 例),再改代码
3. 修复流程
P0/P1 hotfix(≤2h 上线)
生产 tag → hotfix/vN.x 分支 → 修复+回归单测(CI 不豁免)
→ CR 一人预授权放行(24h 内补评审) → 发布 → /health+核心 API 验证
→ 回合并 develop + CHANGELOG 补记
数据修复专项(最高危)
- 订正 SQL:SELECT 快照留档→影响行数预估→双人复核→事务执行→审计留痕
- 批量订正写幂等脚本入
scripts/fixes/(编号+日期),禁手工裸 SQL - 退费复用 48h Scanner refund 流水模式(BalanceAfter 回填),对账可解释
4. 防复发
- 季度演练:杀 MySQL 主库/灌满 Kafka/通道超时,验证告警 5min 触达+回滚 15min 完成
- 错误码预算:新错误路径先注册 ISC 码+字典同步(现 51 码)
- 发版检查单:门禁全绿→迁移向前兼容(只加不改删,回滚代码不回滚 schema)→回滚点确认→告警规则刷新→值守到位
- 复盘模板:时间线/根因/为什么没拦住(测试?监控?评审?)/改进项挂账进开发日历
5. 历史案例索引
| 日期 | 案例 | 根因 | 教训 |
|---|---|---|---|
| 2026-09-11 | batch estimate 500(一轮 W3) | vite proxy 指死端口 8081(历史 env 覆盖残留) | proxy/env 仅启动生效,改后必重启;前端代理层故障后端零感知→催生 §6.4 |
| 2026-09-11 | real 模式 login 500(二轮前) | 同上,旧 vite 进程内存残留配置 | 同上;配置变更须纳入发布检查单 |
| 2026-09-11 | go-sms-kafka 重启循环 1271 次(Day47 开工前处置) | 容器脱离 go-sms-dev_default 网络→KRaft QUORUM_VOTERS(1@kafka:29093)DNS 解析失败→broker 永不就绪;且与外部 hwsms-kafka 抢宿主 19092 | 同端口双实例=隐性单点+冲突源;容器脱离网络属"僵尸态",compose 状态与 runtime 漂移要 docker inspect NetworkSettings 核对;已停用(docker update --restart=no+stop)并注释 compose 服务;2026-09-12 容器更名统一:僵尸尸体删除腾名,hwsms-kafka→go-sms-kafka(手动容器,显式别名 kafka/宿主 19092/网关 127.0.0.1:19092 连接均不变,rename 后 TCP/DNS/重启安全已验证);2026-09-13 遗留清零:①kind 集群删旧建新 hwsms-dev→go-sms-dev(清 CrashLoop 2147 次废弃 hwsms-gateway deployment,清早期 hwsms→go-sms 更名挂账,context=kind-go-sms-dev,与 deployments/ namespace 对齐);②kafka 迁网 hwsms-dev_default→go-sms-dev_default(先 connect 带别名后 disconnect 零空窗;旧网已删;healthy/restarts=0/host 网络容器 topic list 验证过);③容器内 CLI 连 19092 不通=advertised 宿主观设计,勿误判故障 |
6. 上线前基建补齐清单(6 工作日,排期见开发日历)
| # | 项 | 工作量 | 优先级 |
|---|---|---|---|
| 6.1 | Loki+Promtail+Grafana 日志聚合(索引 trace_id/code/status) | 2d | P1 |
| 6.2 | 1d | P0 | |
| 6.3 | Gitea release 流水线:tag→测试→镜像(git describe)→staging 冒烟→生产滚动;一键回滚 | 2d | P0 |
| 6.4 | 1d | P0 |