A 层搬运(整包,源=poc-final 5e09a4cc): 协议四栈/pkg 标准件 12 包/util 计费纯函数/middleware/迁移链 repository·mysql v1~v19+clickhouse/model·entity/config/service·audit·balance/app/cmd·{migrate,reconcile,cmppbench}/tools·gen-dict/_bench/test·integration/openapi·yaml/监控三件/运维资产(compose+kind+CI 两套+Makefile+runbook)/scripts 种子/前端基建(根配置+src 基建目录,views 留 B 层)
This commit is contained in:
@@ -0,0 +1,101 @@
|
||||
# 生产环境 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:取证命令
|
||||
```bash
|
||||
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** |
|
||||
Reference in New Issue
Block a user