# 11.10 故障排查手册

:::tip 概述
按故障类别速查：启动失败 / 认证授权 / 数据异常 / 性能 / 缓存 / 定时任务 / 文件上传。每类给出症状→定位→处理。
:::

## 启动类

| 症状 | 定位 | 处理 |
|------|------|------|
| 启动即退出 | 端口占用 / 配置缺失 / Go 版本 | netstat 查端口；从部署目录运行；核对 go 版本 |
| 数据库连接失败 | link 串/网络/账号 | telnet 端口；核对 database.default |
| Redis 告警降级 | 地址/密码/网络 | 修复后自动恢复（运行期探测）；/api/cache/info 验证 |
| IdentityLoader 告警 | 依赖接线缺失 | 查 internal/cmd 空白导入与 logic init |
| panic 堆栈 | 看日志堆栈 | 定位代码 bug；errorStack=false 时看服务端日志 |

## 认证授权类

| 症状 | 定位 | 处理 |
|------|------|------|
| 全部 401 | jwt.secret 变更 / 时钟 | 改密钥后需重新登录；核对服务器时间 |
| 登录后单接口 401 | 令牌过期/黑名单 | 刷新令牌；查是否被强退拉黑 |
| 403 | 权限链四环 | gmeta permission ↔ 菜单节点 ↔ 角色勾选 ↔ 身份缓存（DEL identity 键） |
| 权限改了不生效 | 身份缓存 300s | SavePermission 应主动清；查清理链；等过期 |
| 租户 1005/1006 | 租户过期/禁用 | 改租户状态/过期；等 60s 或 DEL tenant:info |

## 数据类

| 症状 | 定位 | 处理 |
|------|------|------|
| 租户串数据 | tenantTables 漏登记 | 补登记 + 复查查询是否绕过 dao.Ctx |
| 已删除数据可见 | 绕过 dao.Ctx / 手写条件 | 修复为 dao.Ctx 唯一入口 |
| 唯一冲突 1062 裸报错 | 无预检（设计内兜底） | 补 UniqueFields（Group=索引范围） |
| 新字段不返回 | entity/Req/Res/ToData 四处 | 逐一核对（见 3.3 加字段工作流） |
| 字典文本不显示 | SerializeMaps/Text 字段 | spec 声明 + 结构体 {Field}Text |

## 性能类

| 症状 | 定位 | 处理 |
|------|------|------|
| 接口慢 | 慢查询 / N+1 | debug 开 SQL 日志；查 userExpandNames 类批查是否缺失 |
| 内存增长 | 泄漏 | /api/server/info heapObjects/goroutines 趋势 |
| 并发瓶颈 | 连接池 | DB 池/Redis 池参数核算 |
| 磁盘满 | 日志/上传/备份 | LogClean 是否运行；upload 清理；扩容 |
| 大表超时 | city 全表查询 | 改级联路径（parent_code 索引） |

## 缓存类

| 症状 | 定位 | 处理 |
|------|------|------|
| mode=memory | Redis 不可用 | 修复 Redis；多实例期间限流/锁退化单机 |
| 键值陈旧 | TTL/失效点 | 对照 4.8 键全集；DEL 指定键 |
| 多实例不一致 | Redis 未共享 | 确认 mode=redis |
| 命中率低 | TTL 过短 | /api/cache/info hitRate；调 TTL |

## 定时任务类

| 症状 | 定位 | 处理 |
|------|------|------|
| 任务不执行 | 未发布/cron 无效/未挂载 | status=1？daemonStatus？Scheduler.mounted vs expected |
| 重复执行 | 锁失效 | Redis 可用性（job:lock 依赖）；execute_policy 核对 |
| 执行失败 | 看 job_log exception | HTTP 超时（30s）/handler panic/数据库错误 |
| 任务日志堆积 | LogClean 未跑 | 检查 LogClean 任务与 retentionDays |

## 文件上传类

| 症状 | 定位 | 处理 |
|------|------|------|
| 上传 413/拒绝 | maxSize/白名单/嗅探 | 对照 file.* 配置 |
| 图片 404 | domainUrl/转正失败 | 库中相对路径 vs GetFileUrl；查 temp 是否被清 |
| 富文本图片不显示 | 读取绕过基座 | 走 Detail/List（自动 Expand） |
| temp 堆积 | CleanTemp 未生效 | gcron 注册/tempExpireDays>0 |

## 排障通用路径

```text
1. /api/health          服务活着吗
2. /api/cache/info      缓存模式与健康
3. /api/server/info     全景体检（DB/磁盘/调度器）
4. 启动日志             告警项逐一确认
5. /api.json            接口与文档一致性
6. 操作/登录日志        异常行为追溯
```