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

# 工程本地启动指导

## 📋 目录

-   [环境要求](#环境要求)
-   [环境安装指导](#环境安装指导)
    -   [macOS 环境安装](#macos-环境安装)
    -   [Windows 环境安装](#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 (如未安装)

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

#### 2. 安装 JDK 17

```bash
# 方法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

```bash
# 方法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. 配置环境变量

```bash
# 编辑 ~/.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

```bash
# 使用 Homebrew
brew install node@20

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

### Windows 环境安装

#### 1. 安装 JDK 17

**步骤 1**: 下载 JDK

-   访问 [Oracle JDK 下载页面](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html)
-   下载 Windows x64 版本的 JDK 17
-   或者访问 [OpenJDK](https://adoptium.net/) 下载免费版本

**步骤 2**: 安装 JDK

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

**步骤 3**: 配置环境变量

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

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

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

#### 2. 安装 Maven 3.8.8

**步骤 1**: 下载 Maven

-   访问 [Maven 下载页面](https://archive.apache.org/dist/maven/maven-3/3.8.8/binaries/)
-   下载 `apache-maven-3.8.8-bin.zip`

**步骤 2**: 解压安装

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

**步骤 3**: 配置环境变量

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

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

#### 3. 安装 Node.js

-   访问 [Node.js 官网](https://nodejs.org/)
-   下载 Windows 安装包 (推荐 LTS 版本)
-   运行安装包，按默认选项安装

#### 4. 验证安装

打开 Command Prompt 或 PowerShell，执行：

```cmd
java -version
mvn -version
node -version
npm -version
```

---

## 🗄 数据库配置

### MySQL 配置

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

```sql
CREATE DATABASE hzdyjs_xg CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

3. 导入数据库脚本

```bash
# 导入完整数据库
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 服务：

```bash
# macOS
brew services start redis

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

# 或直接运行
redis-server
```

---

## 🚀 后端启动

### ⚠️ 重要说明

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

### 启动顺序

#### 1. 启动监控服务

```bash
cd backend
./start-monitor.sh
```

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

#### 2. 启动任务调度服务

```bash
./start-job.sh
```

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

#### 3. 启动主应用服务

```bash
./hot-start.sh
```

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

### 启动验证

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

-   **监控服务**: http://localhost:9090
-   **任务调度服务**: http://localhost:8081
-   **主应用服务**: http://localhost:8080

### Windows 环境启动

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

```cmd
# 在 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. 安装依赖

```bash
cd web
npm install
```

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

#### 2. 启动开发服务器

```bash
npm run dev
```

### 日常启动

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

```bash
cd web
npm run dev
```

### 启动成功验证

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

### 其他可用命令

```bash
# 构建生产版本
npm run build

# 代码格式检查
npm run lint

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

# 类型检查
npm run type-check
```

---

## ❓ 常见问题

### Java 相关

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

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

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

**Q: Maven 编译失败**

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

# 检查 Maven 配置
mvn -version
```

### Node.js 相关

**Q: `npm install` 失败或速度慢**

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

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

**Q: 端口冲突**

```bash
# 检查端口占用
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 验证

**祝您启动顺利！🎉**