70 lines
2.7 KiB
Markdown
70 lines
2.7 KiB
Markdown
# 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)
|