145 lines
5.9 KiB
Markdown
145 lines
5.9 KiB
Markdown
# RuoYi 项目分离打包（Thin JAR）操作步骤（Windows/Maven）
|
||
|
||
本文档说明如何将 `ruoyi-admin` 模块配置为“分离打包（thin jar）”，即将应用 jar 与第三方依赖分离：应用 jar 位于 `dist` 目录，依赖位于 `dist/lib` 目录。这样首次部署上传完整包，后续升级只需替换应用 jar 即可，部署效率更高。
|
||
|
||
## 1. 背景与目标
|
||
- 背景：Spring Boot 默认使用 `spring-boot-maven-plugin` 的 `repackage` 打出“fat jar”，依赖被打入 `BOOT-INF/lib`，包体较大。
|
||
- 目标：禁用 `repackage`，通过 `maven-dependency-plugin` 将依赖复制到外部 `lib` 目录；借助 `maven-jar-plugin` 在 Manifest 写入 `Class-Path` 指向 `lib/`，让 `java -jar` 能直接加载外部依赖。
|
||
|
||
## 2. 关键配置改动（已完成）
|
||
修改文件：`ruoyi-admin/pom.xml`
|
||
|
||
### 2.1 输出目录属性
|
||
```xml
|
||
<properties>
|
||
<!-- 分离打包的输出目录：target/dist -->
|
||
<outDir>${project.build.directory}/dist</outDir>
|
||
<!-- 说明：使用 ${project.build.directory} 保证路径在当前模块下（Windows/Linux 通用）。 -->
|
||
</properties>
|
||
```
|
||
原因：统一控制产物输出到 `target/dist`，便于部署与运维。
|
||
|
||
### 2.2 禁用 Spring Boot fat jar
|
||
```xml
|
||
<plugin>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-maven-plugin</artifactId>
|
||
<version>2.1.1.RELEASE</version>
|
||
<configuration>
|
||
<fork>true</fork> <!-- devtools 热部署保持可用 -->
|
||
<skip>true</skip> <!-- 跳过 repackage，避免生成 fat jar -->
|
||
</configuration>
|
||
</plugin>
|
||
```
|
||
原因：避免将依赖打入应用包，转为外部依赖的运行方式。
|
||
|
||
### 2.3 复制运行时依赖到 `dist/lib`
|
||
```xml
|
||
<plugin>
|
||
<groupId>org.apache.maven.plugins</groupId>
|
||
<artifactId>maven-dependency-plugin</artifactId>
|
||
<executions>
|
||
<execution>
|
||
<id>copy-dependencies</id>
|
||
<phase>package</phase>
|
||
<goals>
|
||
<goal>copy-dependencies</goal>
|
||
</goals>
|
||
<configuration>
|
||
<outputDirectory>${outDir}/lib</outputDirectory>
|
||
<excludeTransitive>false</excludeTransitive>
|
||
<stripVersion>false</stripVersion>
|
||
<includeScope>runtime</includeScope>
|
||
</configuration>
|
||
</execution>
|
||
</executions>
|
||
</plugin>
|
||
```
|
||
原因：仅复制运行期所需依赖至 `dist/lib`，与应用 jar 解耦，后续升级更轻量。
|
||
|
||
### 2.4 生成“瘦身 jar”并写入 Manifest
|
||
```xml
|
||
<plugin>
|
||
<groupId>org.apache.maven.plugins</groupId>
|
||
<artifactId>maven-jar-plugin</artifactId>
|
||
<version>3.3.0</version>
|
||
<configuration>
|
||
<outputDirectory>${outDir}</outputDirectory>
|
||
<archive>
|
||
<manifest>
|
||
<mainClass>com.ruoyi.RuoYiApplication</mainClass>
|
||
<addClasspath>true</addClasspath>
|
||
<classpathPrefix>lib/</classpathPrefix>
|
||
</manifest>
|
||
</archive>
|
||
</configuration>
|
||
</plugin>
|
||
```
|
||
原因：
|
||
- 指定 `Main-Class` 确保 `java -jar` 可直接启动。
|
||
- 写入 `Class-Path` 指向 `lib/`，JVM 自动加载外部依赖，无需手动 `-cp`。
|
||
- 输出到 `dist`，形成 `dist/ruoyi-admin.jar` 与 `dist/lib/*` 的部署结构。
|
||
|
||
## 3. 打包步骤（Windows）
|
||
- 在项目根目录执行：
|
||
```powershell
|
||
mvn clean package -pl ruoyi-admin -am
|
||
```
|
||
- 参数解释：
|
||
- `-pl ruoyi-admin`：仅打包入口模块；
|
||
- `-am`：自动构建其依赖模块。
|
||
|
||
完成后产物位于：
|
||
- 应用包：`ruoyi-admin/target/dist/ruoyi-admin.jar`
|
||
- 依赖库：`ruoyi-admin/target/dist/lib/*`
|
||
|
||
## 4. 运行与部署
|
||
- 本地启动（在 `dist` 目录执行）：
|
||
```powershell
|
||
cd ruoyi-admin\target\dist
|
||
java -jar ruoyi-admin.jar
|
||
```
|
||
- 常用参数：
|
||
- 指定端口：`java -jar ruoyi-admin.jar --server.port=8011`
|
||
- 指定环境：`java -jar ruoyi-admin.jar --spring.profiles.active=prod`
|
||
- JVM 内存：`java -Xms512m -Xmx1024m -jar ruoyi-admin.jar`
|
||
|
||
- 部署建议：将整个 `dist` 目录复制到服务器。例如 `/opt/ruoyi-admin/dist`，保持结构：
|
||
```
|
||
dist/
|
||
├─ ruoyi-admin.jar
|
||
└─ lib/
|
||
├─ spring-*.jar
|
||
├─ mybatis-*.jar
|
||
└─ ...
|
||
```
|
||
|
||
## 5. 升级与回滚
|
||
- 升级：若仅业务代码变更（依赖不变），直接替换 `ruoyi-admin.jar`，无需动 `lib/`。
|
||
- 依赖变更：同时替换 `lib/` 中对应的 jar。
|
||
- 回滚：保留上一个版本的 `dist` 备份，出现问题时整体替换目录。
|
||
|
||
## 6. 常见问题与排查
|
||
- 启动报错“找不到或无法加载主类”：
|
||
- 检查 Manifest 是否包含 `Main-Class: com.ruoyi.RuoYiApplication`。
|
||
- 确认 jar 输出在 `dist`（非默认 `target`）。
|
||
- `ClassNotFoundException`：
|
||
- 确认 `lib/` 目录存在并非空；Manifest 中 `Class-Path` 正确写入 `lib/` 前缀。
|
||
- 端口占用：
|
||
- 使用 `--server.port=XXXX` 指定新端口或释放占用端口。
|
||
- SQLServer 驱动：
|
||
- 该驱动会被复制到 `lib/`，无需额外操作；配置按 `application.yml` 正常生效。
|
||
|
||
## 7. 可选增强（资源分离）
|
||
若静态资源或 MyBatis XML 较多，可将资源也分离到外部目录（进一步缩小应用 jar 大小）。
|
||
- 做法：使用 `maven-resources-plugin` 将 `src/main/resources` 中的资源复制到 `dist/resources`；
|
||
- 运行时通过 `--spring.config.additional-location` 或自定义类路径加载资源；
|
||
- 注意：此举需要评估资源加载路径与框架期望，默认不启用以避免影响现有行为。
|
||
|
||
## 8. 验证清单
|
||
- 打包成功，存在 `dist/ruoyi-admin.jar` 与 `dist/lib/*`。
|
||
- 直接运行 `java -jar ruoyi-admin.jar` 正常启动（端口默认 `application.yml` 配置）。
|
||
- 在只替换 `ruoyi-admin.jar` 的情况下，功能正常且无需重新上传依赖。
|
||
|
||
---
|
||
维护者备注：本文档面向 Windows 环境与 Maven 构建；若需 Linux 服务化（systemd）、日志目录与数据目录外置等扩展，请在此基础上追加部署规范。 |