1

2026-06-25 13:39:46 +08:00
parent feaa9cf747
commit 3052847fd7
2 changed files with 213 additions and 1 deletions
--- a/pom.xml
+++ b/pom.xml
@@ -33,6 +33,7 @@
        <mybatis-plus.version>3.5.1</mybatis-plus.version>
        <qiniu.version>7.19.0</qiniu.version>
        <aliyun.oss.version>2.5.0</aliyun.oss.version>
+        <lombok.version>1.18.34</lombok.version>
        <qcloud.cos.version>5.5.9</qcloud.cos.version>
    </properties>

@@ -129,6 +130,13 @@
                <version>${velocity.version}</version>
            </dependency>

+            <!-- Lombok (强制升级以兼容 Java 21) -->
+            <dependency>
+                <groupId>org.projectlombok</groupId>
+                <artifactId>lombok</artifactId>
+                <version>${lombok.version}</version>
+            </dependency>
+
            <!-- 阿里JSON解析器 -->
            <dependency>
                <groupId>com.alibaba.fastjson2</groupId>
@@ -228,7 +236,7 @@
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
-                <version>3.1</version>
+                <version>3.13.0</version>
                <configuration>
                    <source>${java.version}</source>
                    <target>${java.version}</target>
--- a/启动指南.md
+++ b/启动指南.md
@@ -0,0 +1,204 @@
+# 石河子后端服务 - 手动启动指南
+
+## 项目概述
+
+- **框架**: 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 项目） |