# 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 脚本检查

执行：

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

结果：

- 两个脚本均通过

### 3.2 Maven 双产物验证

执行：

```bash
mvn -pl ruoyi-admin -am package -DskipTests
```

结果：

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

## 4. 结论

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