A. 常见问题汇总
概述
全书 FAQ 汇总（按主题分组），结论均可回溯到代码位置。分章详细版见各章 FAQ（2.8 / 3.11 / 10.9 / 11.10）。
A. 接口与路由
Q：接口 404？ 实际路由无 /v1 版本段（api/v1 只是包名）。全部 gmeta path 直接以 /api 开头。新增接口后必须重启；新模块还需 router.go 的 Bind 注册。确认注册可开 server.dumpRouterMap 或查 GET /api.json。
Q：返回 403？ gmeta permission 非空且当前用户 Perms 不含该节点。处理：角色管理勾选权限节点并保存（清身份缓存）。超管不受限；permission 留空 = 登录即可。
Q：401 但 token 刚签发？ 依次排查：① Authorization 头格式（Bearer+空格）；② jwt.secret 多实例/重启后是否一致；③ 令牌是否已入黑名单（登出/轮换/强退）；④ access 已过期（默认 2h）应先 refresh。
Q：偶发 429？ 固定窗口限流：普通 120/分钟/IP/路径；认证入口 10/分钟/IP。反代后全站同一 IP → 检查 api.proxyIps 是否含代理地址。
Q：在线调试文档在哪？GET /swagger（本地 Redoc）；GET /api.json（含全部补注册闭包路由）。
B. 认证与权限
Q：验证码总是失败？ ① 一次性校验（命中即删），每次先取 /api/captcha；② Redis 降级内存后多实例不共享；③ 开发用 bypassCode，生产必须留空。
Q：改了角色权限但用户仍被拒/仍放行？ 身份缓存 user:identity:{uid} TTL 300s。API 路径主动清；手工改库不会——等 5 分钟或 DEL 缓存键。
Q：重置密码？ 超管 PUT /api/user/resetPwd；本人 PUT /api/index/updatePassword（需旧密码）。旧 md5 数据登录被 IsBcrypt 拒绝，需重置升级。
Q：登录报"该用户名存在于多个租户"？ 未指定 tenantCode 时全局查 username，多租户同名优先平台租户，仍歧义则携带 tenantCode 登录（logic/auth.go findUser）。
C. 数据与租户
Q：Update 报 1062（uk_tenant_mobile 等）？ 唯一预检范围必须等于唯一索引范围（含 tenant_id 的索引须按"被改行现租户"检查，spec 用 Group:"tenant_id"）。
Q：租户看到别家数据？ 排查绕过 dao.Ctx 直连 g.DB()；排查该表是否登记 hooks.tenantTables（新增租户级表必须手工加入）。
Q：超管新增数据落到哪个租户？ 未显式指定时 hooks.insertHook 填 tenant.defaultId（默认 1）；显式传 0 建平台共享行。业务取归属用 consts.GetTenantID。
Q：删除了但库里还有？ 删除全是软删（del_flag=1）。物理清除仅 LogClean 三张日志表；业务表恢复需 UPDATE del_flag=0。
Q：新加表/列代码读不到？ gf gen dao -c hack/config.yaml 刷新 → go build → 重启。service 接口手工维护。
D. 文件与富文本
Q：上传成功但图片 404？ ① 展示必须经 GetFileUrl（基座 readTransform 自动处理）；② file.domainUrl 与可访问地址一致性；③ 静态服务根为 resource/。
Q：富文本路径是 [IMG_URL]/...？ 持久化契约（存库格式）。读取走 Detail/List（自动 Expand）；禁止直接读 content 原值给第三方。
Q：temp 目录越来越大？ CleanTemp 每日 03:30 清理超过 file.tempExpireDays（默认 7 天）的日期目录；确认配置非 0 且服务在运行。
E. 定时任务与缓存
Q：任务不执行？ status=1？cron 有效？daemonStatus 挂载？Scheduler.mounted vs expected 差值排查。
Q：Redis 挂了系统还能用吗？ 能——自动降级进程内存（mode=memory）。但限流计数/任务锁/黑名单/在线用户/验证码/字典缓存全部退化单机语义。生产 Redis 必须可用。
Q：字典改了文案没生效？ Redis 层调 /api/dict/refreshCache；进程内 {field}Text 层等 300s 自然过期。
F. 工程
Q：go build 版本报错？ go.mod 声明 go 1.27.2，升级本机 Go。
Q：生成器不建字典？ 注释格式须 字段：1-x 2-y；非 MySQL 内省不到注释。
Q：gf gen service 能跑吗？ 不能——service 接口手工维护，整体运行会覆盖。
Q：前端 pnpm install 失败？ Node 18+；切换 pnpm 镜像源；升级 pnpm 重装。