FT363-INTERFACE/doc/分离打包操作步骤.md

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 输出目录属性

<properties>
    <!-- 分离打包的输出目录：target/dist -->
    <outDir>${project.build.directory}/dist</outDir>
    <!-- 说明：使用 ${project.build.directory} 保证路径在当前模块下（Windows/Linux 通用）。 -->
 </properties>

原因：统一控制产物输出到 target/dist，便于部署与运维。

2.2 禁用 Spring Boot fat jar

<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

<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

<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）

• 在项目根目录执行：

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 目录执行）：

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）、日志目录与数据目录外置等扩展，请在此基础上追加部署规范。