# 石河子后端服务 - 手动启动指南

## 项目概述

- **框架**: RuoYi (若依) v3.8.8 / Spring Boot 2.5.15
- **语言**: Java 1.8 (兼容 Java 21)
- **构建工具**: Maven 3.9+
- **默认端口**: `9091`
- **主启动类**: `com.ruoyi.RuoYiApplication`

---

## 1. 环境要求

| 依赖 | 当前环境 | 备注 |
|------|----------|------|
| **JDK** | 21.0.11 (Temurin) | 路径: `C:\Program Files\Eclipse Adoptium\jdk-21.0.11.10-hotspot` |
| **Maven** | 3.9.9 | 路径: `C:\Users\franc\apache-maven-3.9.9` |
| **数据库** | Highgo DB (远程) | `39.98.44.136:6023` (local 配置) |
| **Redis** | 远程 | `124.243.245.42:5379` (local 配置) |
| **Elasticsearch** | 远程 | `124.243.245.42:9200` (local 配置) |

---

## 2. 环境变量设置

### Git Bash / WSL

```bash
export PATH="/c/Users/franc/apache-maven-3.9.9/bin:$PATH"
```

### 永久生效 (可选)

将上述 export 命令添加到 `~/.bashrc` 末尾：

```bash
echo 'export PATH="/c/Users/franc/apache-maven-3.9.9/bin:$PATH"' >> ~/.bashrc
```

### 验证安装

```bash
java -version   # 应显示 OpenJDK 21
mvn -version    # 应显示 Apache Maven 3.9.9
```

---

## 3. 构建项目

```bash
# 进入后端项目目录
cd shz-backend

# 清理并构建（跳过测试，4线程并行编译）
mvn clean install -DskipTests -T 4
```

> **构建产物**: `ruoyi-admin/target/ruoyi-admin.jar`

---

## 4. 启动服务

### 前台运行（用于调试，Ctrl+C 停止）

```bash
cd shz-backend
java -jar ruoyi-admin/target/ruoyi-admin.jar --spring.profiles.active=local
```

### 后台运行

```bash
cd shz-backend

# 创建日志目录
mkdir -p logs

# 后台启动
nohup java -jar ruoyi-admin/target/ruoyi-admin.jar \
    --spring.profiles.active=local \
    >> logs/backend.log 2>&1 &

# 跟踪日志
tail -f logs/backend.log
```

### JVM 参数调优（可选）

```bash
java -Xms2048M -Xmx2048M -jar ruoyi-admin/target/ruoyi-admin.jar \
    --spring.profiles.active=local
```

---

## 5. 验证服务

```bash
# 检查服务首页
curl http://localhost:9091/
# 返回: 欢迎使用RuoYi后台管理框架，当前版本：v3.8.8

# 检查 Swagger API 文档
curl -s -o /dev/null -w "HTTP: %{http_code}" http://localhost:9091/swagger-ui/index.html
# 返回: HTTP: 200

# 检查 Druid 监控面板
# 浏览器访问: http://localhost:9091/druid/
# 账号: ruoyi / 123456

# 查看运行中的进程
jps -l | grep ruoyi
```

---

## 6. 停止服务

```bash
# 方法一: 查找并终止（推荐）
jps -l | grep ruoyi           # 查找 PID
kill <PID>                     # 优雅关闭

# 方法二: 按端口查找
netstat -ano | findstr 9091   # Windows
lsof -i :9091                  # Linux/Mac
```

---

## 7. 可用配置 Profile

| Profile | 配置文件 | 数据库 | 端口 |
|---------|----------|--------|------|
| `dev` | [`application-dev.yml`](ruoyi-admin/src/main/resources/application-dev.yml) | 内网 `172.31.9.107:8765` | `9091` |
| `local` | [`application-local.yml`](ruoyi-admin/src/main/resources/application-local.yml) | 外网 `39.98.44.136:6023` | `9091` |

默认激活 Profile 在 [`application.yml`](ruoyi-admin/src/main/resources/application.yml) 的 `spring.profiles.active` 中配置。

---

## 8. 构建常见问题

### 编译错误: `NoSuchFieldError: JCTree$JCImport qualid`

Lombok 版本与 JDK 21 不兼容。确保 `pom.xml` 中 Lombok 版本 ≥ 1.18.32：

```xml
<lombok.version>1.18.34</lombok.version>
```

### 编译错误: `maven-compiler-plugin` 版本过低

需要 `maven-compiler-plugin` ≥ 3.11.0 才支持 JDK 21：

```xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.13.0</version>
</plugin>
```

### Maven 下载依赖缓慢

项目已配置阿里云 Maven 镜像（`maven.aliyun.com`），无需额外配置。

---

## 9. 项目结构

```
shz-backend/
├── pom.xml                    # 根 POM（依赖管理）
├── ruoyi-admin/               # Web 入口模块（Spring Boot 启动类）
│   └── src/main/resources/
│       ├── application.yml        # 主配置
│       ├── application-dev.yml    # 开发环境
│       └── application-local.yml  # 本地环境
├── ruoyi-common/              # 通用工具模块
├── ruoyi-framework/           # 核心框架模块
├── ruoyi-system/              # 系统管理模块
├── ruoyi-bussiness/           # 业务模块
├── ruoyi-quartz/              # 定时任务模块
├── ruoyi-generator/           # 代码生成模块
├── sql/                       # 数据库脚本
├── docs/                      # 项目文档
└── buildAndStart.sh           # Linux 部署脚本
```

---

## 10. 相关服务地址

| 服务 | 地址 |
|------|------|
| 后端 API | `http://localhost:9091/` |
| Swagger 文档 | `http://localhost:9091/swagger-ui/index.html` |
| Druid 监控 | `http://localhost:9091/druid/` |
| 管理后台前端 | `shz-admin/` 目录（需单独启动） |
| 微信小程序 | `shzApp/` 目录（uniapp 项目） |