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 tidyQ：前端 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。