快速开始常见问题

端口被占用

现象

Port 8580 is already in use
Port 3000 is already in use

解决方案

# macOS/Linux 查看端口占用
lsof -i :8580
lsof -i :3000

# 结束占用进程
kill -9 <PID>

# 或修改配置文件中的端口

数据库连接失败

现象

Communications link failure
Access denied for user 'root'@'localhost'

解决方案

1. 确认 MySQL 服务已启动：

# Docker
docker ps | grep forge-mysql

# 本地安装
brew services list | grep mysql   # macOS
systemctl status mysql             # Linux

2. 检查配置文件：确认 application-dev.yml 中用户名和密码正确

3. 确认数据库已创建：

docker exec -it forge-mysql mysql -uroot -proot123 -e "SHOW DATABASES;"

Redis 连接失败

现象

Unable to connect to Redis
Connection refused

解决方案

1. 确认 Redis 已启动：

docker ps | grep forge-redis
redis-cli PING  # 期望返回 PONG

2. 检查配置：确认 application-dev.yml 中 Redis 地址和端口正确

Maven 构建失败

现象

Could not resolve dependencies
BUILD FAILURE

解决方案

1. 检查 JDK 版本：

java -version  # 确保是 17

2. 配置国内镜像：编辑 ~/.m2/settings.xml 添加阿里云镜像

3. 清理本地缓存：

rm -rf ~/.m2/repository
cd forge && mvn clean install -DskipTests

Node.js / pnpm 问题

现象

node: bad option
pnpm: command not found

解决方案

# 确认 Node.js 版本 >= 20
node -v

# 确认 pnpm 已安装
pnpm -v

# 如果未安装 pnpm
npm install -g pnpm

# 清理并重装依赖
cd forge-admin-ui
rm -rf node_modules pnpm-lock.yaml
pnpm install

网页加载空白

现象

浏览器打开 http://localhost:3000 后显示空白页面。

解决方案

1. 确认后端服务已启动（http://localhost:8580）
2. 打开浏览器开发者工具（F12），查看控制台报错
3. 检查 Network 标签中的 API 请求是否正常