From 191c2baf60a3c7802448daef9e405abe21c19bc1 Mon Sep 17 00:00:00 2001 From: zhengwr Date: Thu, 25 Jun 2026 13:53:12 +0800 Subject: [PATCH] =?UTF-8?q?docs(A10):=20=E7=94=9F=E4=BA=A7=E4=B8=8A?= =?UTF-8?q?=E7=BA=BF=E5=B7=A5=E7=A8=8B=E5=8C=96=20design(=E5=BE=85?= =?UTF-8?q?=E6=8B=8D=E6=9D=BF=20D1-D6=20+=20W1-W6)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 钉在现状的工程化设计:现状底数(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) --- .../2026-06-25-A10-生产上线工程化-design.md | 85 +++++++++++++++++++ docs/项目进度与路线-总览-2026-06-21.md | 4 +- 2 files changed, 87 insertions(+), 2 deletions(-) create mode 100644 docs/plans/2026-06-25-A10-生产上线工程化-design.md diff --git a/docs/plans/2026-06-25-A10-生产上线工程化-design.md b/docs/plans/2026-06-25-A10-生产上线工程化-design.md new file mode 100644 index 0000000..a2ef096 --- /dev/null +++ b/docs/plans/2026-06-25-A10-生产上线工程化-design.md @@ -0,0 +1,85 @@ +# 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。* diff --git a/docs/项目进度与路线-总览-2026-06-21.md b/docs/项目进度与路线-总览-2026-06-21.md index 60670e5..8320e5a 100644 --- a/docs/项目进度与路线-总览-2026-06-21.md +++ b/docs/项目进度与路线-总览-2026-06-21.md @@ -65,7 +65,7 @@ EIP3(Vaadin / 老引擎)→ EIP4(amis 前端 + 保真层 + 转换器)迁 | **A7** | 定时任务/调度 | 🔴 | 调度运行时未起步;但「定时任务·设置提醒人」保真端点 `ScheduleJobNotifyController` 已交付(c9e4d35,拆 SENDINFO JSON 为 amis input-table 可编辑回写) | | **A8** | RBAC/数据权限 parity | 🟡 | 菜单/用户/角色/部门/数据权限 5 块管理后台已建(CRUD + amis 页);用户管理达 parity,其余仍 demo 级未逐功能对照验收 | | **A9** | 个人设置/工作日历 | 🟠 | 工作日历视图已移植;个人设置(改密/年历)未起步 | -| **A10** | 部署上线工程化 | 🔴 | 仍 dev(web 5173 + 后端 8093);生产构建 / 数据迁移 runbook 执行 / 性能并发 / 灰度未做(PG/Flowable Runbook 已备未执行切流) | +| **A10** | 部署上线工程化 | 🔴(已出 design 待拍板) | 仍 dev(web 5173 + 后端 8093);生产构建 / 数据迁移 runbook 执行 / 性能并发 / 灰度未做(PG/Flowable Runbook 已备未执行切流)。**2026-06-25 已出工程化 design**(`plans/2026-06-25-A10-生产上线工程化-design.md`:现状底数 + 目标拓扑 + W1-W6 分解 + D1-D6 待拍板;MVP=W1 Flyway+W2 容器化+W3 nginx 单源+W4 compose 不卡环境可做) | --- @@ -126,7 +126,7 @@ EIP3(Vaadin / 老引擎)→ EIP4(amis 前端 + 保真层 + 转换器)迁 |---|---| | 进度权威(本文) | `项目进度与路线-总览-2026-06-21.md`(A/B 矩阵 + 下一步 + 待拍板) | | 架构基线 | `架构设计.md`、`迁移手册.md` | -| 方向 / 特性 design | `plans/2026-06-19-EIP4开发平台-架构方向-design.md`(D1-D7)、`plans/2026-06-20-人走五环建新功能-NocoBase式-design.md` | +| 方向 / 特性 design | `plans/2026-06-19-EIP4开发平台-架构方向-design.md`(D1-D7)、`plans/2026-06-20-人走五环建新功能-NocoBase式-design.md`、`plans/2026-06-25-A10-生产上线工程化-design.md`(待拍板 D1-D6 + W1-W6) | | 活路线图 | `plans/2026-06-19-EIP4开发平台-落地执行路线图.md`(M0-M8,状态随里程碑回写) | | AI 契约 | `AI_AGENT_AUTO_DEVELOPMENT.md`(对外口径红线)、`AI_AGENT_PAGE_BLUEPRINT_CONTRACT.md`、`AI_AGENT_REPAIR_CONTRACT.md`、`AI_AGENT_Nocobase_ADOPTION_PLAN.md` + `skills/` | | 决策红线来源 | `决策与盘点/EIP3架构决策会纪要.md`(对外口径红线:严禁承诺 AI 全自动开发)、`决策与盘点/EIP3架构决策报告.md` |