11.10 故障排查手册

:::tip 概述排查总纲：先看启动日志与告警，再按层定位（网络 → 认证 → 业务 → 数据）。trace_id 是单请求排障的金钥匙。 :::

启动类

现象	定位
启动即退出（配置校验失败）	按提示修 config.yaml / APP_*；prod 模式检查四条红线（密钥/万能码/生成器）
Redis 降级告警	Redis 不可用/密码错；内存降级是可用但语义退化的状态，尽快修复
WireCheck 告警	某模块未接线（IdentityLoader/TenantLoader/LogSink）；按裁剪意图判断是否预期
端口占用	server.address 改端口或释放进程
Oracle 构建缺失	oracle 需 `-tags oracle` 构建，检查部署产物构建参数

请求类

现象	定位
全部 404	路由未注册（新模块忘 Bind？未重启？）；反代路径错
401	Token 过期/在黑名单（刚登出或被强退）；客户端 Authorization 头缺失
403	角色未授权该权限码；菜单节点与 RouteSpec 拼写不一致
429	限流命中（authLimit 更严）；确认是否遭刷或配额过小
500	看日志中的 panic 栈（response 中间件已恢复并记录）
响应缺 CORS 头	部署是否绕过了应用直连（CORS 由应用中间件登记）

数据类

现象	定位
查到已删数据	绕过了 Ctx（用了 Raw/裸 DB）
跨租户可见	表未登记 hooks.tenantTables；或平台级身份判定
写入缺审计字段	全局钩子未生效（db.Init 是否正常）
物理删除被拦	设计行为；特殊场景 WithPhysicalDelete 放行
事务内读到旧数据	未用回调入参 ctx

文件类

现象	定位
上传成功 404	temp 未随表单保存转正；或 domainUrl/nginx root 不同构
图片裂图	http/https 混合内容；IMG_URL 还原依赖 domainUrl
大文件失败	maxSize 与 nginx client_max_body_size 两边对齐

排查工具箱

X-Request-Id（响应头）→ grep 日志文件 → 单请求全链路
/health           → 存活判断
/swagger 或 /api.json → 接口与权限码核对（生产关闭则用测试环境）
/metrics          → 错误率/耗时分布
监控页            → 主机/缓存/在线会话
database.debug    → 临时开 SQL 日志（定位后关）

上线事故处置顺序

① 评估影响面（可用性/数据/安全）
② 止血优先：回滚 or 临时配置（关功能/收紧限流）
③ trace_id / 日志定位根因
④ 修复 → 验证 → 复盘归档

2.7 KiB Raw Blame History Unescape Escape

11.10 故障排查手册

启动类

请求类

数据类

文件类

排查工具箱

上线事故处置顺序

相关

2.7 KiB

Raw Blame History