dev 运行环境固化为 JDK 21 + 守卫启动脚本(防误用 JDK 26 致 Groovy 崩)

QA 全量巡检发现:dev 平台默认跑 homebrew openjdk(现为 26),致保真层服务流的
Groovy 4.0.27 在运行时解析 JDK 26 类(major 70)崩(GroovyBugError),35+ 命名查询流 500。
根因与 F2-13「报表 500」同族(那次修了编译目标 release=21,但运行时 JDK 仍可能是 26)。

- scripts/run-dev.sh:一键启动 platform/flowable,强制定位并校验 JDK 21(brew openjdk@21),
  非 21 拒启;轮询等端口释放再起,防多实例/旧 JDK 残留。
- README:新增「运行环境必读:必须 JDK 21」,纠正过时的 openjdk@17 示例。
- 架构设计.md:运行时 JDK 17 → 21,补「不可用 JDK 26 / 升 JDK 须同步升 Groovy、目标 25」红线。

实测:platform(8093)+ flowable(8089)均切到 openjdk@21,登录/待办/服务流查询正常;
此前 JDK 26 下 500 的 PM_LABORCOMPANY_SEARCH_LISTINFO 等恢复返数据。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-13 20:09:49 +08:00
parent e6054a376b
commit d3986031d2
3 changed files with 110 additions and 2 deletions

View File

@@ -29,12 +29,33 @@ EIP4 平台正式工程(路线 A'):双层制模块化单体——**保真层供
> eip4dev 刷新:`bash tools/local-devdb/build_devdb.sh --drop-target`(约 6 分钟)
> 详见:`tools/local-devdb/本地开发库构建报告.md`
## ⚠️ 运行环境(必读):必须 JDK 21,不可用 JDK 26
**保真层老引擎的服务流脚本运行时走 JSR-223 调 Groovy 4.0.27(`pom.xml` 钉定)。**
**Groovy 4.0.27 不认 JDK 26 的字节码(class major version 70),会在编译脚本时抛
`GroovyBugError: Unsupported class file major version 70`,导致大批服务流查询
(`*_SEARCH_LISTINFO`/`*_SZWJ` 等)直接 500。** 项目 `maven.compiler.release=21`、
生产环境=JDK 21(LTS),故本地开发也**必须用 JDK 21**。
⚠️ homebrew 默认的 `openjdk` 现在是 **26**——不显式指定 `JAVA_HOME` 会误用 26。
请先 `brew install openjdk@21`,并始终用 JDK 21 启动。**推荐用守卫脚本(自动定位并强制 21):**
```bash
# 一键启动(强制 JDK 21,自动关停旧实例;默认 platform+flowable 都起)
bash scripts/run-dev.sh both # 或 platform / flowable
EIP4_PROFILE=local bash scripts/run-dev.sh platform # 换 profile
# 将来升 JDK:目标是下个 LTS=25(非 LTS 的 26 不用),且须同步升 Groovy + 跑对拍回归。
```
## 常用命令
```bash
export JAVA_HOME=/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home
# 所有 mvn/java 命令都须用 JDK 21(见上「运行环境」)
export JAVA_HOME=/opt/homebrew/opt/openjdk@21 # 必须 21;openjdk@21/bin/java 应报 21.x
mvn test # 全模块测试(含 ArchUnit)
# 启动:推荐 scripts/run-dev.sh(带 JDK 21 守卫);以下 mvn 方式同样要求 JAVA_HOME=21
# dev profile — 日常开发(真实数据副本 eip4dev,端口 8093)
mvn spring-boot:run -pl platform-app -Dspring-boot.run.profiles=dev