签入版本

EasyGoAdmin_Gin_NaiveVue/zh/appendix/faq.md

@@ -1,57 +1,104 @@
 # A. 常见问题汇总
 
-:::tip 概述
-本页汇总了项目各模块的常见问题及解决方案，按场景分类索引。遇到问题时可先查阅本页，再深入各章节详细文档。
+:::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)。
 :::
 
-## 环境问题
+## 启动与配置
 
-| 问题 | 解决方案 |
-|------|----------|
-| PHP 版本低于 8.2 | 升级到 PHP 8.2+，项目使用了 8.2 的强类型特性 |
-| 缺少 pdo_mysql 扩展 | `apt install php8.2-mysql` 或 `dnf install php-mysqlnd` |
-| 缺少 gd 扩展 | `apt install php8.2-gd` 或 `dnf install php-gd` |
-| Composer 下载慢 | `composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/` |
-| Redis 未安装 | 可选，改用 file 缓存：`.env` 中 `[CACHE]` 下设置 `DRIVER = file` |
-| 缺少 redis 扩展 | `pecl install redis` |
-| Oracle pdo_oci 加载失败（Windows） | 安装 Oracle Instant Client 19c + VC++ 2015-2022 Redistributable，php.ini 启用 `extension=pdo_oci`，配置系统 PATH 后重启 Apache |
-| 命令行有 pdo_oci，浏览器 phpinfo 没有 | Apache 服务启动时 PATH 未刷新，完全停止再启动 Apache 即可 |
-| Oracle Instant Client 路径含中文/空格导致加载失败 | 解压到 `C:\oracle\instantclient_19_20` 等固定路径，避免空格与中文 |
+**Q：启动即退出？**
 
-## 启动问题
+启动 fail-fast：JWT 密钥/DSN 校验失败直接退出。生产模式（app.prod=true）还拒绝默认密钥、非空万能码、未关闭的生成器。按报错提示修正配置或 APP_* 环境变量。
 
-| 问题 | 解决方案 |
-|------|----------|
-| 端口被占用 | `php think run --port 8080` |
-| 数据库连接失败 | 检查 `.env` 中的数据库配置 |
-| 401 未授权 | 检查请求头是否携带 `Authorization: Bearer <token>` |
-| 403 禁止访问 | 检查用户权限配置，确认角色已分配菜单 |
-| 502 Bad Gateway | 检查 PHP-FPM 是否启动：`systemctl status php8.2-fpm` |
+**Q：Redis 连接失败会不会挂？**
 
-## 业务问题
+不会。自动降级内存模式并告警（多实例下语义退化，生产应修复 Redis）。
 
-| 问题 | 解决方案 |
-|------|----------|
-| 唯一性校验报错 | 检查数据是否重复，确认 `uniqueFields` 配置 |
-| 枚举显示名为空 | 检查字典配置，确认 `serializeMaps` 正确 |
-| 文件上传失败 | 检查 `FILE.UPLOAD_DIR` 配置和目录权限 |
-| 导入失败 | 检查 Excel 表头是否与 `headerMap` 一致 |
-| 排序不生效 | 检查 `pageOrderBy` 配置，或前端 `orderField` 参数 |
+**Q：环境变量设置了不生效？**
 
-## 前端问题
+规则：键名大写 + 点换下划线 + `APP_` 前缀，**仅覆盖 YAML 已存在的键**，空值视为未设置。
 
-| 问题 | 解决方案 |
-|------|----------|
-| pnpm install 失败 | `rm -rf node_modules pnpm-lock.yaml && pnpm install` |
-| API 404 | 检查后端路由注册和 Vite 代理配置 |
-| 菜单不显示 | 检查菜单配置、组件路径、角色权限 |
-| 白屏 | 打开 F12 控制台查看错误 |
-| Token 频繁过期 | 检查 `JWT.ACCESS_TTL` 配置（默认 7200 秒） |
+**Q：新增配置键 make check-config 报错？**
 
-## 定时任务问题
+配置键必须与 .env.example 一致——同步更新样例文件。
 
-| 问题 | 解决方案 |
-|------|----------|
-| 任务不执行 | 检查 crontab 配置：`crontab -l` |
-| 任务重复执行 | 检查是否有多个 cron 或 daemon 在运行 |
-| 任务执行超时 | 检查 PHP `max_execution_time` 配置 |
+## 认证与权限
+
+**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)