3.2 KiB
A. 常见问题汇总
:::tip 说明 全项目高频问题的总入口，按主题分组并给出深入链接。分章 FAQ：2.8 快速入门、3.12 模块开发、10.8 生成器、11.10 故障排查。 :::
启动与配置
Q：启动即退出？
启动 fail-fast：JWT 密钥/DSN 校验失败直接退出。生产模式（app.prod=true）还拒绝默认密钥、非空万能码、未关闭的生成器。按报错提示修正配置或 APP_* 环境变量。
Q：Redis 连接失败会不会挂？
不会。自动降级内存模式并告警（多实例下语义退化，生产应修复 Redis）。
Q：环境变量设置了不生效？
规则：键名大写 + 点换下划线 + APP_ 前缀，仅覆盖 YAML 已存在的键，空值视为未设置。
Q：新增配置键 make check-config 报错？
配置键必须与 .env.example 一致——同步更新样例文件。
认证与权限
Q：Token 合法但 401？
在黑名单（已登出/被强制下线），或 IdentityLoader 未接线导致身份扩展为空。
Q：接口 403？
角色未授权该权限码，或菜单节点与 RouteSpec 拼写不一致。改授权后权限缓存最长 300 秒生效，重新登录立即生效。
Q：新授权/改菜单不生效？
前端路由是登录时生成的——重新登录刷新菜单与权限。
数据访问
Q：查到已删除数据？
绕过了 Ctx(ctx)（用了 Raw 或裸 DB）。一切查询走仓储 Ctx 入口。
Q：物理删除被拦截？
设计行为。业务删除用软删除；特殊场景 hooks.WithPhysicalDelete(ctx) 显式放行。
Q：租户数据串了？
新租户级表必须同步登记 hooks.tenantTables 白名单（9 张），且表含 tenant_id 列。
Q：Update 后字段变零值？
Update 是全量表单语义——未提交字段按零值落库，前端须回传全部业务字段。
文件
Q：上传成功但访问 404？
两段式：上传只进 temp，保存记录时才转正。另核对 file.domainUrl 与 nginx root 同构（不含 upload 段）。
Q：富文本图片失效？
正文引用的文件被清理；占位符还原依赖 domainUrl 配置正确。
生成器
Q：生成后手写内容丢了？
overwrite=true 会覆盖全部产物。有手写内容的模块用 overwrite=false。
Q：枚举没生成字典？
列注释须为标准枚举形态：1-在用 2-停用。
前端
Q：登录后白屏？
菜单 component 路径与 views 文件不符（懒加载失败）。
Q：刷新 404？
Nginx history 回退缺失：try_files $uri $uri/ /index.html。
Q：按钮不显示？
v-perm 码与菜单节点不一致，或角色未勾选该节点。
性能与监控
Q：接口突然变慢？
排查顺序：/metrics（路由维度）→ 服务监控页 → SQL debug → 限流是否误伤 → Redis 是否降级。
Q：日志文件过大？
校准 job.logRetentionDays（LogClean 清理）与 zap 轮转；关闭 operationLog.logQuery 缓解查询类刷量。