105 lines
3.2 KiB
Markdown
105 lines
3.2 KiB
Markdown
# 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)
|