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>
13 KiB
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. 建议下一步
- 先拍 D1-D6(尤其 D3 需问客户环境是否允许 Docker)。
- 拍板后按 W1→W2→W3→W4(MVP) 执行——纯代码/配置,不卡环境,可 headless 做完 + 单测/compose lint 验证。
- W5/W6 排进准生产窗口(需真 DB + 客户环境)。
本文为待拍板设计;现状底数见进度总览 §3 A10 / §10.2,切流细节见 docs/P0-PG升级、docs/P3-Flowable升级 runbook。