================================================================================ EasyGoAdmin 后端开发者文档 · 13 开发 FAQ 与排障 ================================================================================ 按主题分组的常见问题，结论均可回溯到代码位置（括号内为文件）。 -------------------------------------------------------------------------------- A. 接口与路由 -------------------------------------------------------------------------------- Q1: 为什么接口 404？项目文档里不是说有 /v1 吗？ A: 实际路由无 /v1 版本段（api/v1 只是包名）。全部 gmeta path 直接以 /api 开头（如 GET /api/user/page）。新增接口后必须：重启服务；若为新模块还需 router.go 中 Bind(controller.CXxx)（internal/router/router.go）。 确认路由是否注册可开 server.dumpRouterMap 或查 GET /api.json。 Q2: 返回 403 "没有该操作权限"？ A: gmeta permission 非空且当前用户 Perms 不含该节点（Bind 包装层判定）。 处理：角色管理 → 勾选对应菜单下权限节点 → 保存（会清身份缓存）。 超管（ROLE_SUPER_ADMIN）不受限。permission 留空 = 登录即可。 Q3: 返回 401 但 token 刚签发？ A: 依次排查：① Authorization 头格式（Bearer + 空格）；② jwt.secret 是否 多实例/重启后不一致；③ 令牌是否已入黑名单（登出/轮换/强退， blacklist:token:{jti}）；④ access 已过期（默认 2h）应先走 /api/oauth2/token 刷新。 Q4: 演示环境提示“演示环境，禁止操作!”？ A: app.demo=true 时写操作全部拒绝（middleware/demo.go）。生产改 false。 Q5: 偶发 429 “请求过于频繁”？ A: 固定窗口限流：普通 /api 120 次/分钟/IP/路径；登录/验证码/令牌兑换 10 次/分钟/IP（rateLimit.*）。反向代理后如全部请求变成同一 IP， 检查 api.proxyIps 是否包含代理地址（否则 XFF 不被信任）。 Q6: 在线调试文档在哪里？ A: GET /swagger（本地 Redoc，不依赖境外 CDN）；GET /api.json（OpenAPI JSON， 含全部补注册的闭包路由）。 -------------------------------------------------------------------------------- B. 认证与权限 -------------------------------------------------------------------------------- Q7: 验证码总是失败？ A: ① 校验为一次性（命中即删），前端须每次先取 /api/captcha；② Redis 不可用 降级内存后多实例不共享（验证码与请求可能落在不同实例）；③ 开发可用 captcha.bypassCode 万能码，生产必须留空。 Q8: 修改了角色权限但用户仍被拒绝（或仍放行）？ A: 身份缓存 user:identity:{uid} TTL 300s。保存角色权限/分配角色会主动清缓存 （role/user 模块）；手工改库不会——等 5 分钟或删除对应缓存键。 Q9: 忘记密码/重置密码？ A: 超管走 PUT /api/user/resetPwd；本人走 PUT /api/index/updatePassword （需旧密码）。密码存储 bcrypt(password+salt)；旧 md5 数据登录会被 IsBcrypt 拒绝，需重置。 Q10: 登录报“该用户名存在于多个租户，请携带租户编码登录”？ A: 未指定 tenantCode 时全局查 username，多租户同名优先平台租户(tenant_id=0)， 仍歧义则要求携带 tenantCode（logic/auth.go findUser）。 -------------------------------------------------------------------------------- C. 数据与租户 -------------------------------------------------------------------------------- Q11: Update 报 1062 Duplicate entry（如 uk_tenant_mobile）？ A: 唯一预检范围必须等于唯一索引范围。索引含 tenant_id + del_flag，预检须按 “被改行的现租户”检查（user 模块已按行现租户实现；spec 用 UniqueRule{Field, Group:"tenant_id"}）。注意：直接 UPDATE 全表数据/迁移 后预检与索引不一致是最常见根因。 Q12: 租户用户看到了别的租户数据？ A: 排查是否绕过 dao.Ctx 直连 g.DB()（钩子条件不生效）；排查该表是否登记进 hooks.tenantTables（新增租户级表必须手工加入，共 9 张）。 Q13: 超管新增数据落到哪个租户？ A: 未显式指定时 hooks.insertHook 填 tenant.defaultId（默认 1）；显式传 0 可创建平台共享行。业务取归属租户用 consts.GetTenantID（超管=默认租户）。 Q14: 数据被“删除”了但数据库里还有？ A: 删除接口全部是软删（del_flag=1，deleteHook 改写）。物理清除走 LogClean 仅限三张日志表；业务表恢复需手工 UPDATE del_flag=0。 Q15: 新加了表/列，代码里读不到？ A: gf gen dao -c hack/config.yaml 刷新 dao/entity/do → go build → 重启。 service 接口文件手工维护，勿运行 gf gen service。 -------------------------------------------------------------------------------- D. 文件与富文本 -------------------------------------------------------------------------------- Q16: 上传成功但页面图片 404？ A: ① 库中存相对 uploadDir 路径，展示必须经 GetFileUrl（基座 readTransform 自动处理，手写查询勿直接输出原值）；② file.domainUrl 与实际可访问地址 一致性；③ 静态服务根为 resource/（SetServerRoot），确认 uploadDir 位于 resource/upload 或已做目录映射。 Q17: 富文本图片路径是 [IMG_URL]/...？ A: 这是持久化契约（存库格式），读取侧必须经 Detail/List（基座自动 ExpandContentFields）或手工调用 ExpandContentFields；禁止业务直接读 content 原值给第三方。 Q18: temp 目录越来越大？ A: CleanTemp 由 cmd.go 的 gcron 每日 03:30 触发，删除 temp 下超过 file.tempExpireDays（默认 7 天）的日期目录；确认配置非 0 且服务在运行。 Q19: 上传被拒绝（类型/大小）？ A: 扩展名白名单 file.fileExt / file.imageExt；大小 file.maxSize（MB）； 图片另做魔数嗅探。.svg 可上传但响应强制 attachment+nosniff（防 XSS）。 -------------------------------------------------------------------------------- E. 定时任务 -------------------------------------------------------------------------------- Q20: 任务到点不执行？ A: ① 任务 status 必须=1（运行中）；② cron 为 gcron 6 段（秒 分 时 日 月 周）， 可用 # 前缀写标准 5 段（"# */5 * * * *"）；③ 调度器启动延时 2s 且仅 DaemonInit 一次——改库后需 Resume/Status 或重启；④ 查 GET /api/job/daemonStatus 与 /api/server/info 的 Scheduler （mounted vs expected 差值=挂载失败）。 Q21: 任务执行失败（任务日志 exception）？ A: url 为 http(s)：检查可达性、params 是否为合法 JSON（作为 POST body）、 30s 超时；url 为本地方法名：须在 internal/task 注册且进程已加载 （RegisterJobHandler 重复注册会 panic）。多实例下策略 2/3 依赖 Redis 锁。 Q22: 如何新增内置任务？ A: 见 09 章第 8 节：task 包新文件 + init 注册 + 任务表配置 url=注册名 + go build 重启。 -------------------------------------------------------------------------------- F. 缓存与降级 -------------------------------------------------------------------------------- Q23: Redis 挂了会怎样？ A: utility/cache 自动降级进程内存（启动探测 + 运行期自动切换，Warning 日志）。 功能可用，但限流计数/任务锁/在线用户/黑名单/验证码退化为单机语义， 多实例部署会不一致。/api/cache/info 与 /api/server/info 可查当前模式。 Q24: 字典改了文案没生效？ A: DictGetText 进程内缓存 300s；可调 GET /api/dict/refreshCache 主动刷新 （清 dict:item:{code} 键），或等自然过期。 -------------------------------------------------------------------------------- G. 代码生成器 -------------------------------------------------------------------------------- Q25: 生成器把我的手工修改覆盖了？ A: generator.overwrite=true 时生成即覆盖。恢复手段：git 还原；或改回 false 仅补缺失文件。批量覆盖前务必备份。 Q26: 生成后编译报错/路由没生效？ A: ① go build ./...（生成的 go 文件需编译）；② 确认 router.go 已插入 Bind 行（生成器自动写入，幂等）；③ 重启服务；④ 菜单/权限已建， 需给角色勾选权限节点。 Q27: 非 MySQL 库生成效果差？ A: 表注释/枚举解析依赖 information_schema（MySQL）。建议在 MySQL 上执行 生成，或人工补齐注释后重新生成。 -------------------------------------------------------------------------------- H. 数据库迁移 -------------------------------------------------------------------------------- Q28: 迁移报“目标库已存在同名表”？ A: 非 -drop-target-first 模式下同名表拦截（建表为 IF NOT EXISTS，数据会 追加，必须前置拦截）。加 -drop-target-first 会清空目标库全部表，慎用。 Q29: 迁移报“表 xxx 无主键，无法分页搬运”？ A: 搬运按主键游标分页，无主键表先补主键。 Q30: pgsql 迁移后插入主键冲突？ A: 序列修复（setval MAX(id)+1）在迁移末段执行；若手工导数据未走迁移器， 需手工修序。mssql 用 DBCC CHECKIDENT；mysql/sqlite/oracle 自动续接。 -------------------------------------------------------------------------------- I. 工程与质量 -------------------------------------------------------------------------------- Q31: 标准命令有哪些？ A: go build ./... ｜ go test ./... ｜ go vet ./... && gofmt -l . ｜ gf gen dao -c hack/config.yaml ｜ make run/build/test/vet/fmt。 Q32: 接口回归怎么比对？ A: hack/golden/ 与 hack/after* 存有响应黄金样本；比对时带录制参数 （如 pageSize=3）对齐动态值后再 DIFF。 Q33: 日志在哪里？ A: 控制台 + log/ 目录（logger.path）。操作日志通道满丢弃会有 “操作日志通道已满”Warning；中间件依赖缺失启动时有 Warning 提示。 Q34: Windows 重启服务的快捷方式？ A: 见 document/启动命令.txt：按端口找 PID → taskkill → 编译 → 启动。 Q35: 用户列表数据权限（data_scope）不生效/过滤范围不对？ A: 逐项排查（机制见 03 章第 6 节）： 1) 角色 data_scope 值是否正确（SELECT data_scope FROM goframe_role）； 2) 用户是否挂了多角色（多角色取最宽松——任一角色为"全部"即不过滤）； 3) 身份缓存陈旧：DEL easygoadmin:user:identity:{uid} 或重登 （正常经角色/用户编辑接口变更会主动清）； 4) 直接改库 dept_id 不经 API 不清缓存（最长 300s 延迟）； 5) 未分配部门（dept_id=0）挂部门档会降级为"仅本人"——属安全兜底设计； 6) 超管/ROLE_SUPER_ADMIN 永远绕过，测试过滤效果需用普通账号； 7) 模块未声明 DataScope 挂点则完全不过滤（当前仅 user 模块接线）。