# A. 常见问题汇总

:::tip 说明
全项目高频问题的总入口，按主题分组并给出深入链接。分章 FAQ：[2.8 快速入门](/zh/quickstart/faq.html)、[3.12 模块开发](/zh/guide/faq.html)、[10.8 生成器](/zh/generator/faq.html)、[11.10 故障排查](/zh/deploy/troubleshooting.html)。
:::

## 启动与配置

**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 缓解查询类刷量。

## 相关

- [11.10 故障排查手册](/zh/deploy/troubleshooting.html)
- [K. 术语表](/zh/appendix/glossary.html)