ccdi/docs/plans/backend/2026-04-14-backend-run-package-conventions-implementation.md

2026-04-14 后端运行与打包约定实施记录

1. 改动目标

• 固化本地后端继续走 ruoyi-admin.jar + 内嵌 Tomcat 启动链路
• 固化 mvn -pl ruoyi-admin -am package -DskipTests 同时产出 jar 与 war
• 固化部署脚本统一消费 ruoyi-admin.war
• 固化 bin/restart_java_backend.sh 默认跟随后端日志，并支持 FOLLOW_LOGS=false

2. 实施内容

2.1 Maven 打包链路

涉及文件：

• ruoyi-admin/pom.xml

实施内容：

• 保持 ruoyi-admin 的 <packaging>jar</packaging> 不变，确保本地运行仍使用可执行 jar
• 为 maven-war-plugin 增加 package 阶段显式执行 war 目标，确保执行 mvn -pl ruoyi-admin -am package -DskipTests 时额外生成 ruoyi-admin.war
• 保留 spring-boot-maven-plugin repackage，继续生成可执行 ruoyi-admin.jar

2.2 本地后端重启脚本

涉及文件：

• bin/restart_java_backend.sh

实施内容：

• 新增 FOLLOW_LOGS="${FOLLOW_LOGS:-true}" 默认开关
• start、restart 成功后默认执行 tail -F 持续输出后端日志
• 当外部传入 FOLLOW_LOGS=false 时，仅启动后端，不进入日志跟随

2.3 部署产物切换

涉及文件：

• deploy/deploy-to-nas.sh
• deploy/deploy.ps1
• docker/backend/Dockerfile

实施内容：

• 部署目录组装时由复制 ruoyi-admin.jar 改为复制 ruoyi-admin.war
• Docker 后端镜像改为消费 ruoyi-admin.war
• 保证部署脚本不再把 ruoyi-admin.jar 当作生产部署产物

2.4 项目约定同步

涉及文件：

• AGENTS.md

实施内容：

• 补充本地运行、双产物打包、部署使用 war、FOLLOW_LOGS 开关等仓库级约定
• 在 Build / Run / Test Commands 中补充主应用定向打包命令

3. 验证记录

3.1 脚本检查

执行：

sh docs/tests/scripts/test-restart-java-backend.sh
sh docs/tests/scripts/test-backend-package-and-deploy-conventions.sh

结果：

• 两个脚本均通过

3.2 Maven 双产物验证

执行：

mvn -pl ruoyi-admin -am package -DskipTests

结果：

• 构建成功
• 生成 ruoyi-admin/target/ruoyi-admin.jar
• 生成 ruoyi-admin/target/ruoyi-admin.war

4. 结论

• 本地开发链路继续保持 jar + 内嵌 Tomcat
• 部署链路统一切换为 war
• 后端重启脚本默认跟日志，且支持显式关闭