W1 引入 db/migration/V1-V3 后,平台表 DDL 在迁移与各模块 bootstrap-*.sql 重复
(评审揪出的"易漂移")。本次收敛,db/migration 成唯一真相:
- 删 3 份重复 bootstrap:bootstrap-page-schema(=V1)/bootstrap-datastatus(=V2)/
bootstrap-ai-agent(=V3)。三者无运行态 classpath 消费者(已全仓核实)。
- AiAgentDdlTest(platform-ai,原读 bootstrap-ai-agent.sql)删除,等价覆盖迁入
platform-app 新增 PlatformMigrationDdlGuardTest:① 守 V3 声明全部 AI 平台表/索引;
② 守 SchemaImportCli.CREATE_DDL ≡ V1(独立 CLI 兜底 DDL 防漂移)。
- SchemaImportCli.CREATE_DDL 由包私有改 public 供上述 guard 比对;两处过时注释改指 V1。
- ci.sh 平台表预灌改指 db/migration/V1(注:app 启动 Flyway 已幂等建表,此预灌仅冗余兜底)。
- docs 对齐:AI_AGENT_AUTO_DEVELOPMENT(spring.sql.init→Flyway)、docs/sql/SYS_PAGE_SCHEMA
/SYS_AI_AGENT 头注释(待办→已落地)、A10 design 残留收敛标完成、deploy/README 残留项标完成。
边界:platform-parity 的 bootstrap-{sys,privilege,auth,xservice,multidim,flow}.sql 是
eip3 schema 对拍测试 fixture,非平台表副本,原样保留。
验证:全 reactor mvn clean install 绿;PlatformMigrationDdlGuardTest 2/2;独立 code-reviewer
评审 GO(零 CRITICAL/HIGH/MEDIUM,含 guard substring 逻辑对真实 V1 仿真核实)。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
115 lines
13 KiB
Markdown
115 lines
13 KiB
Markdown
# A10 生产上线工程化 · design(2026-06-25)
|
||
|
||
> 目标读者:拍板人 + 执行者。本文是**待拍板设计**,不是已实现记录。对应进度总览 §3 A10(🔴 未起步)、§5 P2#9、§10.2「生产交付能力缺口」。
|
||
> 定位:把「dev 能跑」推进到「客户环境可交付、可回滚、可观测」。**纯设计产出,不依赖运行环境**;落地需用户环境(真 DB / 容器宿主 / Gitea runner)。
|
||
|
||
> **🛠️ 实施进度(2026-06-25,本地 PG+Docker 真验)**:**W1 Flyway 已实现 + 真验**——`platform-app` 加 flyway-core + flyway-database-postgresql(10.10.0),`db/migration/V1-V3`(sys_page_schema/sys_datastatus/sys_ai_*,DDL 从既有幂等 bootstrap 迁入),`application.yml` 启 Flyway(baseline-on-migrate + baseline-version=0),dev/local 的 spring.sql.init 收敛移除(app 运行态 provisioning 单一走 Flyway)。`FlywayMigrationLocalIT` 对真实 PostgreSQL 15.18 验两场景全绿:① 全新 schema→V1-V3 建全表+幂等;② 既有非空 schema(已有 sys_page_schema+数据)→baseline V0→V1-V3 幂等应用、既有行不破坏(=客户库接管场景)。**docker build 两镜像真验通过**(daemon 已起:platform-app 727MB/flowable 641MB)。**残留(收敛 follow-up)**:platform-ai/metadata/flow-gateway 的 bootstrap-*.sql 仍在(ci.sh/AiAgentDdlTest/parity fixture 用),与 db/migration 形成文档级重复——全收敛(删 bootstrap、ci.sh/测试改指 db/migration)待后续;app 运行态已单源。
|
||
>
|
||
> **W2+W3+W4 MVP 骨架已落地**(按推荐默认 D1 nginx 单源 / D3 compose+systemd 双轨 / D4 env / D6 客户 PG)——`platform-app/Dockerfile`、`flowable-service/Dockerfile`、`deploy/{nginx.conf,docker-compose.yml,.env.example,README.md,systemd/*.service}`。验证:`docker compose config` 通过(4 服务 + 变量插值);**`docker build` 待有 daemon 的 dev/CI 真验**(本机 daemon 未起)。验证过程揪出并修:flowable-service 双数据源(FLOWABLE_JDBC_*/BIZ_JDBC_*)env 漏传已补。**W1 Flyway 未做(下一批次)→ 当前 compose 假定 DB 已置备,尚不能从零自举平台表**。W5/W6 需准生产。
|
||
|
||
## 0. 一句话
|
||
|
||
EIP4 当前只有 **dev 形态**(手工 `run-dev.sh` 起两个 fat jar + 前端 vite proxy)。生产化缺四块成体系交付物:**① Flyway 平台表迁移 ② 容器化/编排(compose+Dockerfile+nginx)③ 单源托管与切流回滚 ④ 数据迁移 runbook 执行 + 性能/灰度基线**。可观测性(actuator+logback)与安全基线(prod profile/JWT/CI)本月已补,是 A10 的前置已就位。
|
||
|
||
## 1. 现状底数(2026-06-25 实测)
|
||
|
||
**运行进程(2 个 Spring Boot fat jar + 外部依赖)**
|
||
| 进程 | 端口(dev/base) | 角色 |
|
||
|---|---|---|
|
||
| `platform-app` | 8093 / 8084 | 主应用:保真层引擎 + 现代层 REST + 前端 schema 服务 |
|
||
| `flowable-service` | 8089 | 工作流引擎(Flowable)独立进程 |
|
||
| PostgreSQL | 5435(共享测试库) | 数据(客户库 eip3 schema + EIP4 平台表) |
|
||
| 前端 | vite 5173 dev proxy→8093 | amis SPA,prod 需静态托管 |
|
||
|
||
**已就位前置**:prod profile(`application-prod.yml`,JWT/DB 强制 env、fail-safe 安全链)、actuator `/actuator/health`(liveness/readiness)、logback 滚动日志、CI(`.gitea/workflows/ci.yml` + parity-nightly,待 runner 激活)。
|
||
|
||
**缺口(实测)**
|
||
- **Flyway 零落地**:平台表 DDL/数据散落 —— `docs/sql/*.sql`(7) + 各模块 `src/main/resources/bootstrap/*.sql`(`bootstrap-page-schema`/`bootstrap-datastatus`/`bootstrap-ai-agent`),且 **`bootstrap-ai-agent.sql` 在 platform-ai 与 platform-app 各一份**(易漂移)。无版本化、无执行顺序保证、无幂等台账。
|
||
- **无 `Dockerfile` / `docker-compose` / `nginx.conf`**:四服务编排、切流/回滚仅停在文档。
|
||
- **前端无生产托管**:dev 靠 vite proxy;prod 无 nginx/伴服方案。
|
||
- **数据迁移 runbook 备而未执行**:`docs/P0-PG升级/PG升级Runbook-v1.md`、`docs/P3-Flowable升级/Flowable升级Runbook-v1.md` 写好未跑。
|
||
- **无性能/并发基线、无灰度机制**。
|
||
|
||
> **关键边界(务必先共识)**:保真层跑在**客户既有 eip3 库**之上,EIP4 只**新增**平台表(`SYS_PAGE_SCHEMA`/`SYS_*_AI`/datastatus 等),**不迁移/不改客户业务表 schema**。故 Flyway 只管「EIP4 新增表」,客户库 schema 由保真层原样消费。这条决定 Flyway 范围与切流模型。
|
||
|
||
## 2. 目标生产拓扑
|
||
|
||
```
|
||
┌──────────── nginx (单源) ────────────┐
|
||
client → │ / → web dist (静态 SPA) │
|
||
│ /api/** → platform-app:8084 │
|
||
│ /flowable/** → flowable-service:8089 (按需)
|
||
└───────────────────────────────────────┘
|
||
│ │
|
||
platform-app flowable-service
|
||
(prod profile) (prod profile)
|
||
└────────┬───────────┘
|
||
PostgreSQL(客户库 eip3 schema + EIP4 平台表)
|
||
```
|
||
四容器:`nginx` / `platform-app` / `flowable-service` / `postgres`(生产 PG 多为客户既有实例,compose 里的 pg 仅自测/演示用)。
|
||
|
||
## 3. 工作分解(建议顺序 + 体量)
|
||
|
||
| ID | 工作 | 体量 | 依赖 | 产出 |
|
||
|---|---|---|---|---|
|
||
| **W1** | **Flyway 收敛平台表** | M | — | 引入 flyway-core;把散落 EIP4 平台表 DDL/种子整理为 `db/migration/V{n}__*.sql`(仅 EIP4 新增表,排除 parity 测试种子 + 客户库);去重 `bootstrap-ai-agent`;platform-app 启动跑 migrate(`flyway.baseline-on-migrate=true` 接管既有库)。**幂等 + 版本台账 + 执行顺序确定**。 |
|
||
| **W2** | **容器化** | M | W1 | 两个多阶段 `Dockerfile`(temurin-jre-21 运行层 + 非 root + actuator HEALTHCHECK);前端 `npm run build` → 静态产物;`.dockerignore`。 |
|
||
| **W3** | **单源托管 + 反代** | S-M | W2 | `deploy/nginx.conf`:serve web dist + `/api`→platform-app、`/flowable`→flowable-service;gzip/缓存/SPA history fallback。**消除 dev 的 vite proxy 依赖**。 |
|
||
| **W4** | **compose 编排 + 配置** | M | W2,W3 | `deploy/docker-compose.yml`(4 服务 + healthcheck + depends_on + 网络);`.env.example`(`EIP4_AUTH_JWT_SECRET`/`EIP4_DB_*`/`SERVER_PORT` 等,prod profile 已强制无默认);`SPRING_PROFILES_ACTIVE=prod`。 |
|
||
| **W5** | **数据迁移 runbook 执行** | M-L | W1 | 把 PG升级 / Flowable升级 两 runbook 在准生产真跑一遍并补「执行记录 + 回退验证」;产「客户环境部署 checklist」。**需真 DB/环境**。 |
|
||
| **W6** | **性能/并发基线 + 灰度** | L | W4,W5 | 关键只读路径压测基线(连接池/statement_timeout 已配,需实测);切流灰度=nginx upstream 权重(老 eip3 Vaadin ↔ 新 eip4 只读双跑),对接已有切流文档;回滚演练。 |
|
||
|
||
**最小可交付(MVP 切片)**:W1+W2+W3+W4 = 「一条 `docker compose up` 起全栈、Flyway 自动建平台表、nginx 单源访问」。W5/W6 需准生产环境,独立排期。
|
||
|
||
## 3.1 W1 Flyway 详细执行规格(ready-to-run,2026-06-25 勘探后细化)
|
||
|
||
> **状态(2026-06-25 更新)**:✅ **已实现 + 对本地真实 PG 验证通过 + 整栈 docker compose 真起 + 残留全收敛**。
|
||
> - 真验:`FlywayMigrationLocalIT`(库级两场景)+ 整栈 `docker compose up` 内置空 PG:platform-app 在 prod profile 启动时 Flyway 自建 eip3 schema 落 9 张 sys_* 表、readiness UP、nginx 单源反代生效(见 `deploy/README.md` 验证状态)。
|
||
> - 残留收敛(已完成):删 3 份与 db/migration 重复的 bootstrap(page-schema/datastatus/ai-agent);`ci.sh` 改指 `db/migration/V1`;`AiAgentDdlTest` 迁入 platform-app 改守 V3;新增 `SchemaImportCli.CREATE_DDL`↔V1 防漂移 guard(`PlatformMigrationDdlGuardTest`)。db/migration 现为平台表 DDL 唯一真相(SchemaImportCli 内联 DDL 为独立 CLI 兜底,经 guard 钉死不漂移)。
|
||
> **已做前置(2026-06-25)**:`bootstrap-ai-agent.sql` 两份去重——删 platform-app 副本,单一真相归 `platform-ai/src/main/resources/bootstrap/bootstrap-ai-agent.sql`(platform-app 经依赖传递消费;原同 classpath 路径双副本=解析歧义,已消除)。
|
||
|
||
**为何需 PG 才能安全做**:迁移 SQL 是 PG 专有(`::jsonb`/`::xml`/`ON CONFLICT`),H2 跑不了;本机 Docker daemon 未起→testcontainers 也用不了。盲发自动 migrate 进客户库启动路径=高爆炸半径,必须先在 dev PG 验过 `flyway migrate` + 回退。
|
||
|
||
**迁移清单(EIP4 新增平台表,从既有【幂等】bootstrap 原样迁入)**
|
||
| 迁移 | 源(现状) | 表 |
|
||
|---|---|---|
|
||
| `V1__sys_page_schema.sql` | `platform-metadata/.../bootstrap/bootstrap-page-schema.sql` | sys_page_schema |
|
||
| `V2__sys_datastatus.sql` | `platform-flow-gateway/.../bootstrap/bootstrap-datastatus.sql` | sys_datastatus(+种子) |
|
||
| `V3__sys_ai_agent.sql` | `platform-ai/.../bootstrap/bootstrap-ai-agent.sql` | sys_ai_task/draft/change_set/run/feature_package/revision/audit_log |
|
||
| (排除) | `platform-parity/.../bootstrap/*`(对拍测试种子) / `docs/sql/*`(admin 页数据 upsert,评估后单列) / 客户 eip3 schema | — |
|
||
|
||
**配置(baseline 策略)**:`flyway-core` 加 platform-app;`spring.flyway`:`baseline-on-migrate=true`、`baseline-version=0`(客户库非空→baseline 于 V0=不动既有,再跑 V1+;迁移幂等→既有平台表也安全)、`locations=classpath:db/migration`。**先 gated**:`enabled: ${EIP4_FLYWAY_ENABLED:false}`,dev 验过再开,prod 经 env 显式启用。
|
||
|
||
**跨模块处理(ai-agent)**:sys_ai_* DDL 由 platform-ai 拥有并被 `AiAgentDdlTest` 测试。`V3` 迁移在 platform-app/db/migration,内容与 platform-ai 副本须一致——A10 W1 落地时二选一:① V3 引用/复制 platform-ai 副本并加防漂移测试;② 用 Flyway `locations` 叠加 `classpath:bootstrap`(但 bootstrap 非 V__ 命名,需重命名)。建议①。
|
||
|
||
**收敛 spring.sql.init**:W1 验过后,dev/local 的 `spring.sql.init.schema-locations` 改指 `classpath:db/migration/*.sql`(与 Flyway 同源),并删散落 bootstrap → 真单一真相。**收敛前 dev 行为不变**(spring.sql.init 仍跑现有 bootstrap,Flyway gated off,零回归)。
|
||
|
||
**验证门(接 PG 后)**:dev PG 跑 `flyway migrate`→`info`/`validate` 全绿 → 既有库 baseline 不破坏既有数据 → 回退演练 → 再 prod 开 `EIP4_FLYWAY_ENABLED=true`(W5 准生产)。
|
||
|
||
## 4. 待拍板决策点
|
||
|
||
| # | 决策 | 选项 | 建议 |
|
||
|---|---|---|---|
|
||
| **D1** | 单源托管形态 | (a) 独立 nginx 容器 serve dist+反代 / (b) platform-app Spring 伴服 dist+/api(少一进程) | **(a) nginx**:标准、解耦、支持灰度 upstream 权重(W6 需要);伴服把前端耦进 Java 发布节奏,不利切流。 |
|
||
| **D2** | Flyway 范围 | (a) 仅 EIP4 新增平台表 / (b) 含客户库 schema | **(a)**:客户库是既有 eip3 schema,保真层原样消费,EIP4 无权也无需迁移;`baseline-on-migrate` 接管既有库。 |
|
||
| **D3** | 是否容器化 | (a) Docker/compose / (b) systemd + 裸 jar(部分私有化客户禁 Docker) | **(a) 为主 + 文档化 (b) 兜底**:compose 标准化交付,同时给「裸 jar + systemd unit」附录供禁 Docker 客户。**需确认客户环境是否允许 Docker**。 |
|
||
| **D4** | 密钥/配置管理 | (a) 环境变量/.env / (b) Vault/KMS | **(a) v1**:prod profile 已强制 env 注入、缺失即 fail-fast;Vault 待客户安全要求再上。 |
|
||
| **D5** | 灰度/切流机制 | (a) nginx upstream 权重双跑(eip3↔eip4 只读)/ (b) 全量切换 | **(a)**:契合「只读先切流」既定路线 + 已有切流 runbook;可逐页/逐比例放量、秒级回滚。 |
|
||
| **D6** | 生产 PG | (a) 复用客户既有 PG / (b) compose 内置 PG | **(a) 生产 / (b) 仅自测演示**:生产 PG 是客户资产,compose 的 pg 仅 demo。 |
|
||
|
||
## 5. 风险
|
||
|
||
- **保真层与客户库耦合**:W1 `baseline-on-migrate` 必须在客户库真跑验证,错配会污染客户既有表(W5 准生产演练前置)。
|
||
- **冻结的 amis-fork / 端口契约漂移**(8084/8093/8094):nginx 反代须钉死 prod 端口(8084),与 dev(8093)/fivering(8094) 区隔,写进 .env。
|
||
- **Flowable 独立进程的事务/状态一致性**:切流灰度下 eip3/eip4 双写工作流状态需隔离(只读切流期 flowable 仅新系统写)。
|
||
- **CI 激活依赖 Gitea runner**:W 完成后的回归靠 CI,但 runner 未注册前不自动跑(基建前置)。
|
||
|
||
## 6. 建议下一步
|
||
|
||
1. **先拍 D1-D6**(尤其 D3 需问客户环境是否允许 Docker)。
|
||
2. 拍板后按 **W1→W2→W3→W4(MVP)** 执行——纯代码/配置,**不卡环境,可 headless 做完 + 单测/compose lint 验证**。
|
||
3. **W5/W6** 排进准生产窗口(需真 DB + 客户环境)。
|
||
|
||
---
|
||
*本文为待拍板设计;现状底数见进度总览 §3 A10 / §10.2,切流细节见 `docs/P0-PG升级`、`docs/P3-Flowable升级` runbook。*
|