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 |
排障通用路径
