Files
eip4-platform/docs/plans/2026-06-25-A10-生产上线工程化-design.md
zhengwr fa3c92b698 chore(A10 W1): 收敛重复 bootstrap,db/migration 成平台表 DDL 单一真相
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>
2026-06-25 15:16:35 +08:00

13 KiB
Raw Blame History

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。