99 lines
4.0 KiB
Markdown
99 lines
4.0 KiB
Markdown
# 2.8 常见问题 FAQ
|
||
|
||
:::tip 概述
|
||
本节收录环境搭建与首次运行阶段最常遇到的问题。更多排障条目见 [附录 A 常见问题汇总](../appendix/faq) 与 [11.10 故障排查手册](../deploy/troubleshooting)。
|
||
:::
|
||
|
||
## 环境与编译
|
||
|
||
### Q：`go build` 报 `go.mod requires go >= 1.27.2`
|
||
|
||
go.mod 声明的版本高于本机 Go 版本。升级 Go 到 1.27.2+，或使用 go env 切换已安装的高版本。
|
||
|
||
### Q：依赖下载缓慢或失败
|
||
|
||
```sh
|
||
go env -w GOPROXY=https://goproxy.cn,direct
|
||
go mod tidy
|
||
```
|
||
|
||
### Q：前端 `pnpm install` 报引擎不匹配
|
||
|
||
检查 Node 版本（要求 18+）。部分依赖对 pnpm 版本敏感，可升级 pnpm 后重装：
|
||
|
||
```sh
|
||
npm install -g pnpm@latest
|
||
pnpm install
|
||
```
|
||
|
||
## 数据库
|
||
|
||
### Q：连接 MySQL 报错 `Unknown database`
|
||
|
||
库名是 `easygoadmin.goframe.elevue`（含点号），确认已建库且拼写一致；建库语句见 [2.4 数据库初始化](./database-init)。
|
||
|
||
### Q：切换数据库类型后启动报驱动错误
|
||
|
||
确认 `database.default.type` 与 `link` 前缀一致（如 `type: "pgsql"` 且 `link: "pgsql:..."`）。五驱动已预注册，无需改代码。
|
||
|
||
### Q：导入脚本后缺少唯一索引
|
||
|
||
`document/` 各方言脚本中 MySQL 版为规范基准，后四份待人工校对。以 MySQL 版核对 `uk_*` 唯一索引清单（应有 13 个），缺失需人工补齐——唯一索引是并发唯一性的最终保证。
|
||
|
||
## 启动与运行
|
||
|
||
### Q：启动报端口占用
|
||
|
||
```sh
|
||
netstat -ano | findstr ":8000" | findstr LISTENING
|
||
taskkill /F /PID <pid>
|
||
```
|
||
|
||
或修改 `manifest/config/config.yaml` 的 `server.address`。
|
||
|
||
### Q：启动日志出现 `IdentityLoader`/`LogSink` 告警
|
||
|
||
中间件依赖未接线（不阻断启动）。通常原因：`internal/cmd` 缺少对 `internal/logic` 的空白导入，或 init 注册被误删。表现为：不加载角色权限 / 跳过租户校验 / 操作日志不落库。
|
||
|
||
### Q：日志提示 Redis 连接失败并降级
|
||
|
||
服务以进程内存缓存运行（`UsingMemory()=true`）。限流计数、任务执行锁、在线用户、JWT 黑名单、验证码全部退化单机语义。检查 Redis 地址/密码，确认后可通过 `/api/cache/info` 验证 `mode` 是否恢复为 `redis`。
|
||
|
||
### Q：接口返回 `{"code":401}`
|
||
|
||
令牌缺失、过期或已被拉黑。重新登录获取新令牌；带 refresh_token 走 `POST /api/oauth2/token` 轮换。注意登录响应字段是 `access_token`（下划线）。
|
||
|
||
### Q：接口返回 `{"code":403}`
|
||
|
||
权限不足：确认 gmeta `permission` 标签对应节点已在「菜单管理」存在，且已在「角色管理」为当前角色勾选。超管（ROLE_SUPER_ADMIN）不受限。
|
||
|
||
### Q：接口返回 `{"code":429}`
|
||
|
||
触发限流（默认普通接口 120 次/分钟/IP/路径；登录/验证码/令牌兑换 10 次/分钟/IP）。等待窗口过期或调整 `rateLimit.*` 配置。
|
||
|
||
### Q：写操作被拒绝并提示"演示环境，禁止操作!"
|
||
|
||
`app.demo: true` 时拦截全部写操作（读操作与公开白名单放行）。本地开发改回 `false` 并重启。
|
||
|
||
### Q：验证码图片不显示
|
||
|
||
检查 `/api/captcha` 是否 200；字体文件 `resource/static/fonts/Vera.ttf` 缺失会降级 SVG 渲染（仍可用）；若被限流（认证入口 10 次/分钟）等待窗口过期。
|
||
|
||
### Q：登录报"验证码错误"
|
||
|
||
开发环境可在验证码栏直接填配置中的 `captcha.bypassCode`（默认 618618）免校验；生产环境该值应留空。注意验证码为一次性校验（命中即删）。
|
||
|
||
## 前端
|
||
|
||
### Q：登录成功但刷新页面回到登录页
|
||
|
||
确认后端返回的令牌字段读取的是 `data.access_token`；检查浏览器 localStorage 是否被拦截清除；确认系统时间正常（令牌 exp 校验）。
|
||
|
||
### Q：页面菜单为空
|
||
|
||
菜单按角色权限动态生成。在「角色管理 → 权限」为角色勾选菜单节点；超管返回全量菜单。也可能是 `getUser` 接口 401——检查令牌。
|
||
|
||
### Q：接口 404
|
||
|
||
本项目全部路由统一 `/api` 前缀且**无 `/v1` 版本段**。`/api/v1/user/page` 形式会 404，正确为 `/api/user/page`。
|