Files
eip4-platform/docs/plans/2026-06-25-A10-生产上线工程化-design.md
zhengwr 191c2baf60 docs(A10): 生产上线工程化 design(待拍板 D1-D6 + W1-W6)
钉在现状的工程化设计:现状底数(2 SB 进程 platform-app/flowable-service + PG + 前端;散落 bootstrap SQL 含 bootstrap-ai-agent 两份;无 docker/nginx;PG/Flowable runbook 备而未执行)+ 目标四服务拓扑 + W1-W6 分解(Flyway 收敛/容器化/nginx 单源/compose/runbook 执行/性能灰度)+ D1-D6 待拍板(单源形态/Flyway 范围/是否容器化/密钥/灰度/生产 PG)。关键边界:保真层跑客户既有 eip3 库,EIP4 只新增平台表,Flyway 仅管新增表 baseline-on-migrate。MVP=W1-W4 不卡环境可 headless 做。§3 A10 + §7 nav 已挂。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-25 13:53:12 +08:00

86 lines
8.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# A10 生产上线工程化 · design(2026-06-25)
> 目标读者:拍板人 + 执行者。本文是**待拍板设计**,不是已实现记录。对应进度总览 §3 A10(🔴 未起步)、§5 P2#9、§10.2「生产交付能力缺口」。
> 定位:把「dev 能跑」推进到「客户环境可交付、可回滚、可观测」。**纯设计产出,不依赖运行环境**;落地需用户环境(真 DB / 容器宿主 / Gitea runner)。
## 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 需准生产环境,独立排期。
## 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。*