常见报错索引

本文档按关键词索引 Forge Admin 常见报错信息及解决方案。

端口占用

Port 8580 was already in use

原因：8580 端口被其他进程占用。

解决：

# 查找占用进程
lsof -i:8580

# 终止进程
kill -9 <PID>

# 或修改端口
server:
  port: 8581

Web server failed to start. Port 3000 was already in use

原因：Vite 开发服务器端口被占用。

解决：

# 查找并终止
lsof -i:3000 | kill -9 <PID>

# 或修改 .env.development
VITE_HTTP_PORT=5174

---

数据库连接

Communications link failure

原因：无法连接 MySQL 数据库。

解决：

1. 确认 MySQL 服务已启动：mysql -u root -p
2. 检查 spring.datasource.url 地址与端口
3. 确认防火墙未拦截 3306 端口

Access denied for user 'root'@'localhost'

原因：数据库用户名或密码错误。

解决：检查 application-dev.yml 中的 username 和 password 配置。

Unknown database 'forge_admin'

原因：数据库不存在。

解决：

CREATE DATABASE forge_admin DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

---

Redis 连接

Unable to connect to Redis

原因：Redis 服务未启动或配置错误。

解决：

# 检查 Redis 是否运行
redis-cli ping
# 应返回 PONG

---

Token 无效

未能读取到有效 token

原因：请求未携带 Token 或 Token 格式错误。

解决：

1. 确认请求头包含 Authorization: {token}
2. 确认 Token 未过期
3. 重新登录获取新 Token

token 已过期

原因：Token 超过有效期（默认 30 天）。

解决：重新登录。

token 已被顶下线

原因：同一账号在另一处登录，且 is-share: false。

解决：如需允许多端登录，设置 sa-token.is-share: true。

---

权限不足

无权限：system:user:list

原因：当前用户角色缺少 system:user:list 权限。

解决：

1. 进入「角色管理」编辑当前用户角色
2. 在菜单权限中勾选对应功能
3. 保存后重新登录

无权限访问此资源

原因：接口被 @SaCheckPermission 保护，当前用户无对应权限。

解决：确认权限标识与角色分配的权限一致。

---

启动异常

Bean creation exception

原因：Spring 容器初始化 Bean 失败。

解决：

1. 查看完整异常堆栈
2. 常见原因：缺少配置项、依赖冲突、数据库未初始化
3. 检查 application.yml 配置是否完整

Flyway migration failed

原因：数据库版本迁移脚本执行失败。

解决：

# 查看迁移状态
SELECT * FROM flyway_schema_history;

# 手动修复后重试
# 如需重新执行，删除对应记录后重启

---

前端构建

Module not found: Can't resolve 'naive-ui'

原因：前端依赖未安装。

解决：

pnpm install

Proxy error: Could not proxy request

原因：Vite 代理目标（后端）未启动。

解决：先启动后端 Admin 服务（8580），再启动前端。

💡 未找到你的报错？请查阅 FAQ 或提交 Gitee Issues。