jmalcloud/STARTUP_GUIDE.md

🚀 JmalCloud 前后端启动指南

完整的前后端集成项目启动说明

📋 项目结构确认

✅ 前后端代码完整性检查

后端代码 (根目录)：

• ✅ src/main/ - Java源代码
• ✅ src/test/ - 测试代码
• ✅ pom.xml - Maven配置
• ✅ target/ - 编译输出

前端代码 (frontend/ 目录)：

• ✅ src/ - Vue.js源代码
• ✅ package.json - NPM配置
• ✅ vue.config.js - Vue CLI配置
• ✅ public/ - 静态资源

⚙️ 环境要求

后端要求

• ☑️ Java: 21+ (推荐)
• ☑️ Maven: 3.6+
• ☑️ MongoDB: 4.4+ (需要运行中)

前端要求

• ☑️ Node.js: ^16 或 ^18 (package.json指定)
• ☑️ npm: 自带或yarn
• ☑️ Vue CLI: 自动安装

🚀 启动方式

方式1：开发环境快速启动 ⭐️ 推荐

# 一键启动前后端 (后台运行)
./dev-start.sh

特点：

• ✅ 最简单快速
• ✅ 后台运行，不占用终端
• ✅ 适合日常开发

访问地址：

• 🌐 前端：http://localhost:9528
• 🔌 后端：http://localhost:8088

方式2：完整交互式启动

# 完整的启动过程，带环境检查
./start-full-project.sh

特点：

• ✅ 完整的环境检查
• ✅ 详细的启动日志
• ✅ 交互式选项
• ✅ 自动健康检查

方式3：手动分别启动

启动后端：

# 设置环境变量
export MONGODB_URI="mongodb://localhost:27017/jmalcloud"

# 启动Spring Boot
mvn spring-boot:run -Dspring-boot.run.profiles=dev

启动前端：

cd frontend/

# 安装依赖 (首次运行)
npm install

# 设置环境变量
export NODE_OPTIONS="--openssl-legacy-provider"
export VUE_APP_BASE_API="/api"
export API="http://localhost:8088"

# 启动Vue开发服务器
npm run dev

🛑 停止服务

# 停止所有服务
./stop-full-project.sh

📊 服务管理

查看运行状态

# 检查端口占用
lsof -ti:8088  # 后端
lsof -ti:9528  # 前端

# 检查进程
ps aux | grep spring-boot
ps aux | grep vue-cli-service

查看日志

# 实时查看日志
tail -f backend.log   # 后端日志
tail -f frontend.log  # 前端日志

# 或同时查看
tail -f backend.log frontend.log

🔧 常见问题解决

1. Node.js版本问题

如果Node.js版本不匹配：

# 使用nvm管理Node.js版本
nvm install 18
nvm use 18

# 或设置兼容选项
export NODE_OPTIONS="--openssl-legacy-provider"

2. 端口冲突

修改端口配置：

# 修改后端端口
export SERVER_PORT=8089

# 修改前端端口
export PORT=9529

3. MongoDB连接失败

# 启动MongoDB
brew services start mongodb-community  # macOS
# 或
systemctl start mongod  # Linux

# 检查连接
mongosh --eval "db.adminCommand('ping')"

4. Maven构建失败

# 清理并重新构建
mvn clean compile

# 跳过测试
mvn spring-boot:run -DskipTests

5. 前端依赖安装失败

cd frontend/

# 清理缓存
npm cache clean --force
rm -rf node_modules package-lock.json

# 重新安装
npm install

🎯 开发建议

推荐的开发流程

1. 首次启动：使用 ./start-full-project.sh 进行完整检查
2. 日常开发：使用 ./dev-start.sh 快速启动
3. 调试问题：查看对应的日志文件
4. 停止服务：使用 ./stop-full-project.sh 完整停止

默认访问地址

服务	地址	说明
前端主页	http://localhost:9528	Vue.js开发服务器
后端API	http://localhost:8088	Spring Boot应用
健康检查	http://localhost:8088/public/health	后端状态检查
API文档	http://localhost:8088/swagger-ui/	接口文档

登录信息

• 用户名：admin
• 密码：123456

📁 项目文件说明

文件	说明	用途
start-full-project.sh	完整启动脚本	生产级启动，含环境检查
dev-start.sh	开发快速启动	日常开发使用
stop-full-project.sh	停止脚本	清理所有服务和端口
backend.log	后端日志	Spring Boot运行日志
frontend.log	前端日志	Vue CLI开发服务器日志

💡 提示

1. 首次运行建议使用 ./start-full-project.sh 进行环境检查
2. 前端首次启动会自动安装依赖，请耐心等待
3. 后端首次启动需要编译，大约需要1-2分钟
4. MongoDB必须先启动，否则后端会连接失败
5. 端口占用时脚本会自动清理旧进程

🆘 获得帮助

如果遇到问题：

1. 检查对应的日志文件
2. 确认环境要求是否满足
3. 尝试手动启动排查问题
4. 使用停止脚本清理环境后重试