# 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 两边对齐 |

## 排查工具箱

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

## 上线事故处置顺序

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

## 相关

- [2.8 常见问题 FAQ](/zh/quickstart/faq.html)
- [3.12 常见问题与排错](/zh/guide/faq.html)