90 lines
4.3 KiB
Markdown
90 lines
4.3 KiB
Markdown
# A. 常见问题汇总
|
||
|
||
:::tip 概述
|
||
全书 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 重装。
|