2.8 常见问题 FAQ

概述

本节收录环境搭建与首次运行阶段最常遇到的问题。更多排障条目见 附录 A 常见问题汇总 与 11.10 故障排查手册。

环境与编译

Q：go build 报 go.mod requires go >= 1.27.2

go.mod 声明的版本高于本机 Go 版本。升级 Go 到 1.27.2+，或使用 go env 切换已安装的高版本。

Q：依赖下载缓慢或失败

go env -w GOPROXY=https://goproxy.cn,direct
go mod tidy

Q：前端 pnpm install 报引擎不匹配

检查 Node 版本（要求 18+）。部分依赖对 pnpm 版本敏感，可升级 pnpm 后重装：

npm install -g pnpm@latest
pnpm install

数据库

Q：连接 MySQL 报错 Unknown database

库名是 easygoadmin.goframe.elevue（含点号），确认已建库且拼写一致；建库语句见 2.4 数据库初始化。

Q：切换数据库类型后启动报驱动错误

确认 database.default.type 与 link 前缀一致（如 type: "pgsql" 且 link: "pgsql:..."）。五驱动已预注册，无需改代码。

Q：导入脚本后缺少唯一索引

document/ 各方言脚本中 MySQL 版为规范基准，后四份待人工校对。以 MySQL 版核对 uk_* 唯一索引清单（应有 13 个），缺失需人工补齐——唯一索引是并发唯一性的最终保证。

启动与运行

Q：启动报端口占用

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。