hzdyjs/工程本地启动指导.md

工程本地启动指导

📋 目录

• 环境要求
• 环境安装指导
  • macOS 环境安装
  • Windows 环境安装
• 数据库配置
• 后端启动
• 前端启动
• 常见问题

---

🔧 环境要求

必需环境

• JDK: 17 (推荐使用 Oracle JDK 或 OpenJDK)
• Maven: 3.8.8+
• Node.js: 20.15.x+ (推荐 20.15.0)
• npm: 10.7.x+
• MySQL: 5.7+ 或 8.0+（本机可不安装，使用阿里云的环境）
• Redis: 5.0+ （本机可不安装，使用阿里云的环境）

推荐配置

• 操作系统: macOS 12+, Windows 10+, Ubuntu 20.04+
• 内存: 8GB+ (推荐 16GB)
• 磁盘: 20GB+ 可用空间

---

🛠 环境安装指导

macOS 环境安装

1. 安装 Homebrew (如未安装)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. 安装 JDK 17

# 方法1: 使用 Homebrew
brew install openjdk@17

# 创建软链接
sudo ln -sfn /usr/local/opt/openjdk@17/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-17.jdk

# 方法2: 下载 Oracle JDK
# 访问: https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html
# 下载 macOS x64 版本并安装

3. 安装 Maven 3.8.8

# 方法1: 使用 Homebrew
brew install maven@3.8

# 方法2: 手动安装
cd ~/Downloads
wget https://archive.apache.org/dist/maven/maven-3/3.8.8/binaries/apache-maven-3.8.8-bin.tar.gz
tar -xzf apache-maven-3.8.8-bin.tar.gz
sudo mv apache-maven-3.8.8 /opt/maven

4. 配置环境变量

# 编辑 ~/.zshrc 或 ~/.bash_profile
vim ~/.zshrc

# 添加以下内容
export JAVA_HOME=/Library/Java/JavaVirtualMachines/openjdk-17.jdk/Contents/Home
export MAVEN_HOME=/opt/maven
export PATH=$JAVA_HOME/bin:$MAVEN_HOME/bin:$PATH

# 使配置生效
source ~/.zshrc

5. 安装 Node.js 和 npm

# 使用 Homebrew
brew install node@20

# 或者下载官方安装包
# 访问: https://nodejs.org/

Windows 环境安装

1. 安装 JDK 17

步骤 1: 下载 JDK

• 访问 Oracle JDK 下载页面
• 下载 Windows x64 版本的 JDK 17
• 或者访问 OpenJDK 下载免费版本

步骤 2: 安装 JDK

• 运行下载的安装包
• 选择安装路径 (推荐: C:\Program Files\Java\jdk-17)
• 完成安装

步骤 3: 配置环境变量

# 打开系统属性 -> 高级 -> 环境变量

# 新建系统变量
变量名: JAVA_HOME
变量值: C:\Program Files\Java\jdk-17

# 编辑 Path 变量，添加
%JAVA_HOME%\bin

2. 安装 Maven 3.8.8

步骤 1: 下载 Maven

• 访问 Maven 下载页面
• 下载 apache-maven-3.8.8-bin.zip

步骤 2: 解压安装

• 解压到 C:\Program Files\Apache\maven-3.8.8

步骤 3: 配置环境变量

# 新建系统变量
变量名: MAVEN_HOME
变量值: C:\Program Files\Apache\maven-3.8.8

# 编辑 Path 变量，添加
%MAVEN_HOME%\bin

3. 安装 Node.js

• 访问 Node.js 官网
• 下载 Windows 安装包 (推荐 LTS 版本)
• 运行安装包，按默认选项安装

4. 验证安装

打开 Command Prompt 或 PowerShell，执行：

java -version
mvn -version
node -version
npm -version

---

🗄 数据库配置

MySQL 配置

1. 启动 MySQL 服务
2. 创建数据库

CREATE DATABASE hzdyjs_xg CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

3. 导入数据库脚本

# 导入完整数据库
mysql -u root -p hzdyjs_xg < docs/设计文档/database/hzdyjs_xg.sql

# 或按模块导入
mysql -u root -p hzdyjs_xg < docs/设计文档/database/05-system-management-module.sql
mysql -u root -p hzdyjs_xg < docs/设计文档/database/03-logistics-module.sql
# ... 其他模块

Redis 配置

启动 Redis 服务：

# macOS
brew services start redis

# Windows (如使用 WSL)
sudo service redis-server start

# 或直接运行
redis-server

---

🚀 后端启动

⚠️ 重要说明

后端服务必须按照以下顺序启动，每个服务启动成功后再启动下一个！

启动顺序

1. 启动监控服务

cd backend
./start-monitor.sh

等待提示: 看到 "监控服务启动成功" 或类似日志后，再进行下一步

2. 启动任务调度服务

./start-job.sh

等待提示: 看到 "任务调度服务启动成功" 或类似日志后，再进行下一步

3. 启动主应用服务

./hot-start.sh

等待提示: 看到 "主应用启动成功" 或访问 http://localhost:8080 正常返回

启动验证

服务启动成功后，可通过以下方式验证：

• 监控服务: http://localhost:9090
• 任务调度服务: http://localhost:8081
• 主应用服务: http://localhost:8080
• API 接口文档: http://localhost:8080/swagger-ui/index.html ⭐

Windows 环境启动

如果在 Windows 环境下，可以使用以下方式：

# 在 Git Bash 或 WSL 中执行
cd backend
bash start-monitor.sh
bash start-job.sh
bash hot-start.sh

# 或者直接运行 Java 命令
java -jar ruoyi-extend/ruoyi-monitor-admin/target/ruoyi-monitor-admin.jar
java -jar ruoyi-extend/ruoyi-snailjob-server/target/ruoyi-snailjob-server.jar
java -jar ruoyi-admin/target/ruoyi-admin.jar

---

🎨 前端启动

首次启动

1. 安装依赖

cd web
npm install

注意: 首次启动时必须先执行 npm install 安装项目依赖

2. 启动开发服务器

npm run dev

日常启动

如果已经安装过依赖，后续启动只需：

cd web
npm run dev

启动成功验证

• 浏览器自动打开或手动访问: http://localhost
• 能够看到登录页面表示启动成功

其他可用命令

# 构建生产版本
npm run build

# 代码格式检查
npm run lint

# 代码格式修复
npm run lint:fix

# 类型检查
npm run type-check

---

❓ 常见问题

Java 相关

Q: java -version 显示版本不对或找不到命令

# 检查 JAVA_HOME 是否正确设置
echo $JAVA_HOME  # macOS/Linux
echo %JAVA_HOME% # Windows

# 重新设置环境变量后重启终端

Q: Maven 编译失败

# 清理并重新编译
mvn clean install -DskipTests

# 检查 Maven 配置
mvn -version

Node.js 相关

Q: npm install 失败或速度慢

# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com

# 或使用 cnpm
npm install -g cnpm --registry=https://registry.npmmirror.com
cnpm install

Q: 端口冲突

# 检查端口占用
lsof -i :80  # macOS/Linux
netstat -ano | findstr :80  # Windows

# 修改启动端口
npm run dev -- --port 3001

数据库相关

Q: 连接数据库失败

• 检查 MySQL 服务是否启动
• 确认数据库用户名密码正确
• 检查 application.yml 中的数据库配置

Q: Redis 连接失败

• 检查 Redis 服务是否启动
• 确认 Redis 端口 (默认 6379) 是否开放

服务启动相关

Q: 后端服务启动失败

• 检查端口是否被占用 (8080, 8081, 9090)
• 查看启动日志确认具体错误
• 确保按顺序启动服务

Q: 前端无法访问后端接口

• 检查后端服务是否正常启动
• 确认前端代理配置 (vite.config.ts)
• 检查跨域配置

---

📞 技术支持

如果在启动过程中遇到问题，请：

1. 查看日志: 检查控制台输出的错误信息
2. 检查环境: 确认所有环境变量配置正确
3. 重启服务: 按照正确顺序重新启动
4. 查阅文档: 参考 docs/ 目录下的相关文档

---

🎯 快速启动检查清单

环境准备

• JDK 17 安装并配置
• Maven 3.8.8 安装并配置
• Node.js 和 npm 安装
• MySQL 数据库启动并创建 （本机可不安装、使用阿里云测试环境）
• Redis 服务启动（本机可不安装、使用阿里云测试环境）

启动流程

• 导入数据库脚本
• 按顺序启动后端服务 (monitor → job → main)
• 进入 web 目录执行 npm install (首次)
• 执行 npm run dev 启动前端
• 访问 http://localhost 验证

祝您启动顺利！🎉