Files
go-sms-V2/docs/runbook/incident-response.md

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:根因确认

  1. 变更回溯:git log $(git describe --tags --abbrev=0 HEAD~1)..HEAD --oneline 对照故障时间
  2. 复现:staging 同参重放(Day48 全链路环境复用)
  3. 修复:先写回归单测钉死 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. 防复发

  1. 季度演练:杀 MySQL 主库/灌满 Kafka/通道超时,验证告警 5min 触达+回滚 15min 完成
  2. 错误码预算:新错误路径先注册 ISC 码+字典同步(现 51 码)
  3. 发版检查单:门禁全绿→迁移向前兼容(只加不改删,回滚代码不回滚 schema)→回滚点确认→告警规则刷新→值守到位
  4. 复盘模板:时间线/根因/为什么没拦住(测试?监控?评审?)/改进项挂账进开发日历

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 Alertmanager→钉钉/企微:5xx 突增(P0)/P99>500ms(P1)/Kafka lag>1w(P1)/通道速率异常(P0 资损) ✅ Day53 落地:监控栈+规则+webhook sink 真机验通;Kafka lag/通道速率两指标导出挂账 Day55/56;生产切换钉钉/企微须加 dingtalk 侧车 1d P0
6.3 Gitea release 流水线:tag→测试→镜像(git describe)→staging 冒烟→生产滚动;一键回滚 2d P0
6.4 前端错误上报:request.ts 拦截器+window.onerror → POST /fe-errors 落库(url/ua/trace_id) ✅ Day53 落地:v12 迁移+双端点+FE 三路采集(keepalive/去重/防递归) 1d P0