Some checks failed
ci / build-test-parity (push) Has been cancelled
- 从工作区根 docs/(非 git,未版本化)合并全部文档进版本控制,消除文档两头分裂
- 新增 README(状态总览+模块完成度+全文档索引)、项目进度与路线-总览-2026-06-17(A兼容/B新功能+关键路径+待拍板决策)
- 被取代的冲突状态/审计快照归入 归档/;对最易误导的两份("16视图已交付"实现交付报告、06-13架构快照)加"已归档"横幅
- 现行权威:engineclass移植backlog(46视图) + 用户管理Delta移植(方法论/交接) + 组件设计体系 + 通用模板收口 + 客户沟通
- 诚实口径:纵向模块仅用户管理 parity,横向引擎地基较全,余 153 定制视图(47 framework+106 业务)多为通用页已产·delta 未移植
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
253 lines
13 KiB
Markdown
253 lines
13 KiB
Markdown
# Flowable 5.13-SNAPSHOT → 6.8.1 升级 Runbook v1(P3 演练产出)
|
||
|
||
> 2026-06-11 | 性质:P3 阶段交付物(决策会红线:任何不可逆变更须有已验证可恢复备份/演练耗时/实测回退点/客户书面批准)
|
||
> 演练环境:客户库测试副本(192.168.20.68:5435,Activiti 5.13-SNAPSHOT,ACT_* 表集)→ 本地 PG 15(端口 5433,库 eip4flow_rehearsal)
|
||
> **与 PG 升级分窗执行**(决策会已拍板);客户生产执行排切流期停机窗口
|
||
|
||
---
|
||
|
||
## 一、兼容性结论(2026-06-11 实测,全绿)
|
||
|
||
| 检查项 | 结果 | 影响 |
|
||
|--------|------|------|
|
||
| 客户库实际引擎版本 | **5.13-SNAPSHOT**(非 5.14) | 触发坑 6.1,需版本串规范化 |
|
||
| 5.13 直升 6.x | **不可行**(触发 TENANT_ID_ 缺列 DDL 错误) | 强制两步路径:先 5.23,再 6.8.1(坑 6.2)|
|
||
| 流程定义总数 | **1,515 个**(演练实测) | 全量就地保留,0 丢失 |
|
||
| 运行中执行实例 | **9,386**(前后完全一致) | 就地升级已 PoC 实证 |
|
||
| 待办任务 | **9,324**(前后完全一致) | 全量保留 |
|
||
| 历史流程实例 | **26,761**(前后完全一致) | 全量保留 |
|
||
| engineVersion=v5 标记 | **1,515 / 1,515**(100%) | 全部经 v5 兼容层运行 |
|
||
| 自定义扩展点 | 零 `activiti:class`;3 个表达式 handler bean(见§五 6.3)| handler bean 须移植到 platform-flow-gateway |
|
||
| schema 版本最终态 | **6.8.1.0** | 符合预期 |
|
||
|
||
---
|
||
|
||
## 二、执行步骤(演练实测 + 生产外推)
|
||
|
||
### 步骤总表
|
||
|
||
| # | 步骤 | 演练耗时 | 生产外推 | 回退点 |
|
||
|---|------|----------|----------|--------|
|
||
| 0 | 客户书面批准 + 业务停写公告;Flowable 服务停止(本窗口只动 Flowable,PG 已在分窗完成) | — | — | — |
|
||
| 1 | 源库物理冷备(pg_basebackup 或文件级)——**回退点 A** | — | 取决于库大小;ACT_* 表集约 6.3 GB | 全程可回 A |
|
||
| 2 | 运行 `01_precheck.sh`:连通性 + 表清单 + 前置行数快照 | **1s** | ≈1 min | — |
|
||
| 3 | 运行 `02_normalize.sh`:`schema.version` 5.13-SNAPSHOT → 5.13(坑 6.1)| **0s** | <1s | 幂等;失败→回 A |
|
||
| 4 | 运行 `03_upgrade_v5.sh`:Flowable 5.23 就地升级 | **2s** | ≈10 s(本地)| 失败→回 A |
|
||
| 5 | 运行 `04_upgrade_v6.sh`:Flowable 6.8.1 兼容层升级 | **18s** | ≈20 s(本地)| 失败→回 A |
|
||
| 6 | 运行 `05_postcheck.sh`:行数对账 + engineVer 抽查 + schema.version 断言 | **0s** | ≈5 s | 不符→回 A |
|
||
| 7 | platform-flow-gateway 已含 3 个 handler bean + `setBeans` 注册,启动服务验证 | — | ≈业务发布时间 | 配置回切 |
|
||
| 8 | 观察期 ≥1 周;旧 Activiti 库只读保留 ≥1 月后下线 | — | — | 数据回查 |
|
||
|
||
**演练一键链总耗时(不含数据导入):21s**
|
||
**演练完整链(含重拉 5.13 副本):84s**
|
||
|
||
### 一键链调用方式
|
||
|
||
```bash
|
||
# 演练(本地副本,跳过备份确认)
|
||
./tools/flowable-upgrade/flowable_upgrade.sh \
|
||
--host localhost --port 5433 --db eip4flow_rehearsal \
|
||
--assume-backed-up
|
||
|
||
# 生产(加 --pass 口令;不加 --assume-backed-up → 交互确认备份)
|
||
./tools/flowable-upgrade/flowable_upgrade.sh \
|
||
--host <prod-host> --port <prod-port> --db <prod-db> --schema eip3 \
|
||
--user <user> --pass <pass>
|
||
|
||
# 单步重跑(如只重跑后置校验)
|
||
./tools/flowable-upgrade/flowable_upgrade.sh --db eip4flow_rehearsal 5
|
||
```
|
||
|
||
---
|
||
|
||
## 三、数据迁移口径与耗时模型
|
||
|
||
### 3.1 演练数据规模(2026-06-11 实测)
|
||
|
||
| 表 | 口径 | 行数 | 演练导入 |
|
||
|----|------|------|----------|
|
||
| act_re_procdef | 全量 | 1,515 | ✓ |
|
||
| act_ru_execution | 全量 | 9,386 | ✓ |
|
||
| act_ru_task | 全量 | 9,324 | ✓ |
|
||
| act_ru_variable | 全量 | 470,195 | ✓ |
|
||
| act_hi_procinst | 全量 | 26,761 | ✓ |
|
||
| act_hi_actinst | 全量 | 1,096,979 | ✓ |
|
||
| act_hi_taskinst | 全量 | 56,769 | ✓ |
|
||
| act_hi_varinst | **schema-only** | — | 仅建表,不拉数据(2.3 GB) |
|
||
| act_hi_comment | **schema-only** | — | 仅建表(119 MB)|
|
||
| act_hi_identitylink | **schema-only** | — | 仅建表(176 MB)|
|
||
| act_hi_varinst_archive | **schema-only** | — | 仅建表(3.0 GB)|
|
||
| act_ge_bytearray | **过滤拷贝** | 91,189(过滤后) | 流程定义资源 + 运行时变量引用 |
|
||
|
||
### 3.2 act_ge_bytearray 生产口径说明(重要)
|
||
|
||
> **演练口径**:过滤拷贝(`deployment_id_ IS NOT NULL OR id_ IN act_ru_variable.bytearray_id_`),91,189 行,约 ≈200 MB(估算)。
|
||
> **生产全量**:1,189 行(实测客户库),但文件体积 **1,182 MB(~1.2 GB)**,因为每行含 BPMN/图片/表单二进制大文件。
|
||
>
|
||
> **差额说明**:演练过滤口径(91,189 行)vs 生产全量(1,189 行)的"行数大"原因是:演练过滤包含了运行时变量引用的大量序列化变量对象(act_ru_variable.bytearray_id_ 引用),生产全量反而行数少但每行更大(全是 BPMN 定义资源文件)。生产升级时 **建议全量拷贝 act_ge_bytearray**(1,189 行 / 1.2 GB),工具链已支持:过滤逻辑在 `rehearsal/bytearray_copy.py` 中参数化,生产可按需调整为全量(去除 WHERE 子句)。
|
||
>
|
||
> **生产 bytearray 拷贝时间外推**:1.2 GB / ~10 MB/s(网络口径)≈ **2 分钟**。
|
||
|
||
### 3.3 演练导入耗时(本地 PG 15,网络至 192.168.20.68)
|
||
|
||
| 阶段 | 耗时 |
|
||
|------|------|
|
||
| schema 建表(全量 + schema-only) | 10s |
|
||
| 运行时数据导入(pg_dump pipe) | 39s |
|
||
| bytearray 过滤拷贝(91,189 行) | 13s |
|
||
| 副本行数核对 | 1s |
|
||
| **import_5x 小计** | **63s** |
|
||
|
||
---
|
||
|
||
## 四、三坑检查清单(每次生产执行必过)
|
||
|
||
> 来源:eip4-poc WS4 实测(flowable-poc / flowable5-poc,2026-06-10)+ 本次演练确认
|
||
|
||
**坑 6.1:版本串 5.13-SNAPSHOT 不被升级链识别**
|
||
|
||
- 现象:Flowable 5.23 启动报 `"unknown version from database"`,整链中断
|
||
- 根因:`act_ge_property.schema.version = 5.13-SNAPSHOT` 不在升级范围
|
||
- 对策:`UPDATE act_ge_property SET value_='5.13' WHERE name_='schema.version'`(`02_normalize.sh` 已自动执行,幂等)
|
||
- 状态:演练已验证 ✅
|
||
|
||
**坑 6.2:5.13 不能直跳 6.x(两步升级强制)**
|
||
|
||
- 现象:直接用 6.8.1 连 5.13 库,因缺 `TENANT_ID_` 列 DDL 报错回滚
|
||
- 根因:v5→v6 迁移脚本假设已达 Flowable 5.15+
|
||
- 对策:强制两步:`03_upgrade_v5.sh`(→5.23)→ `04_upgrade_v6.sh`(→6.8.1)
|
||
- 状态:演练已验证 ✅,1,515 定义 / 9,386 执行 / 9,324 任务 / 26,761 历史全量保留
|
||
|
||
**坑 6.3:表达式 handler bean 移植面(3 个类)**
|
||
|
||
- 现象:Flowable 服务启动后,BPMN 候选人表达式 `${candidateUsersHandler.getUsers(...)}` 解析失败
|
||
- 根因:3 个 bean 定义在 `com.dsasp.server.wf`,Flowable 独立服务须显式注册
|
||
- 引用量:`candidateUsersHandler` ×4,761 处、`wfContextService` ×175 处、`multiInstanceUsersHandler` ×33 处(全量 1,515 个 BPMN)
|
||
- 对策:3 个 handler 类移植到 `platform-flow-gateway`,通过 `ProcessEngineConfiguration.setBeans(Map)` 注册(PoC 桩已验证注册机制有效)
|
||
- 状态:**P3 待实施**(platform-flow-gateway 模块)
|
||
|
||
**执行前检查清单**:
|
||
|
||
```
|
||
□ 升级前:物理冷备已完成并验证可恢复(回退点 A)
|
||
□ 升级前:Flowable 服务已停止(本窗口只动 Flowable schema,不动 PG)
|
||
□ 01_precheck:schema.version=5.13-SNAPSHOT 确认 + 17 张运行时表齐全 + 前置行数快照
|
||
□ 02_normalize:schema.version: 5.13-SNAPSHOT → 5.13(坑6.1)
|
||
□ 03_upgrade_v5:Flowable 5.23 完整升级 + schema.version 达 5.23.0.0
|
||
□ 04_upgrade_v6:Flowable 6.8.1 兼容层升级 + schema.version 达 6.8.1.0
|
||
□ 05_postcheck:全 12 张表行数对账一致 + 1,515 个定义 engineVer=v5 就位
|
||
□ platform-flow-gateway 已含 3 个 handler bean + setBeans 注册(坑6.3)
|
||
□ 启动服务:验证流程发起/待办查询/审批正常
|
||
```
|
||
|
||
---
|
||
|
||
## 五、与 PG 升级的分窗纪律(决策会已拍板)
|
||
|
||
| 升级类型 | 停机窗口 | 依赖关系 |
|
||
|----------|----------|----------|
|
||
| PG 9.4 → 15(见《PG升级Runbook-v1》) | **窗口 1** | 独立,先行或后行均可 |
|
||
| Flowable 5.13-SNAPSHOT → 6.8.1(本 Runbook)| **窗口 2**(与 PG 升级分开)| 不依赖 PG 版本(PG15 和 PG9.4 均支持本链路)|
|
||
|
||
**分窗原因**:两次升级各有独立回退路径(回退点 A 各自独立);合并窗口会导致回退时无法区分失败根因;决策会拍板此为红线纪律。
|
||
|
||
**执行顺序建议**:先完成 PG 升级(含数据对账验证稳定后),再开 Flowable 升级窗口。Flowable 升级链自身耗时极短(演练实测 21s),可在极短窗口内完成。
|
||
|
||
---
|
||
|
||
## 六、运行中实例就地升级 PoC 实证
|
||
|
||
> 结论:运行中实例(9,309 个流程实例,9,324 个待办任务)在 6.8.1 + v5 兼容层下**全量就地保留**,无需手动迁移。
|
||
|
||
| 验证项 | PoC 数据 | 演练数据 |
|
||
|--------|----------|----------|
|
||
| 升级前运行中执行 | 9,386 | 9,386 |
|
||
| 升级后运行中执行 | 9,386 ✅ | 9,386 ✅ |
|
||
| 升级前待办任务 | 9,324 | 9,324 |
|
||
| 升级后待办任务 | 9,324 ✅ | 9,324 ✅ |
|
||
| engineVersion=v5 定义 | 1,509 | 1,515 |
|
||
| 待办样例 engineVer | v5 ✅ | v5 ✅ |
|
||
| 历史实例保留 | 26,761 ✅ | 26,761 ✅ |
|
||
|
||
(定义数从 1,509 → 1,515 是客户库正常增长,两个时间点之差)
|
||
|
||
v5 兼容层机制:Flowable 6.x 在 `act_re_procdef.engine_version_='v5'` 时,通过内嵌的 `flowable5-compatibility` 模块使用 v5 引擎执行该定义对应的实例。5 个 scriptTask 兼容性详见 P3-1 报告(platform-flow-gateway 验证)。
|
||
|
||
---
|
||
|
||
## 七、风险与待办
|
||
|
||
| 项 | 状态 | 优先级 |
|
||
|----|------|--------|
|
||
| platform-flow-gateway 移植 3 个 handler bean(坑6.3)| **P3 待实施** | P0(不移植则全部流程无法运行)|
|
||
| 生产 act_ge_bytearray 全量拷贝(1.2 GB)vs 演练过滤口径 | **待确认口径**(建议全量;工具已参数化)| P1 |
|
||
| 生产 act_hi_* 巨型历史表是否迁移(varinst 2.3 GB + archive 3.0 GB)| **与客户确认**(不迁则历史查询受限)| P2 |
|
||
| JDK 版本钉住 openjdk@17 | 工具链已 `export JAVA_HOME` 强制;生产服务器须确认 JDK≥17 | P1 |
|
||
| 与 PG 升级分窗执行 | 已拍板;本 Runbook 与《PG升级Runbook-v1》分开管理 | 纪律红线 |
|
||
| 生产完整演练(含客户生产数据规模) | 本 Runbook 为本地副本演练;生产前须在客户侧专用环境完整演练后升为 v2 | v2 触发 |
|
||
|
||
---
|
||
|
||
## 附录 A:对账脚本
|
||
|
||
```bash
|
||
# 前置快照(升级前运行,输出到 snapshot_pre.tsv)
|
||
./tools/flowable-upgrade/flowable_upgrade.sh --db <db> 1 # 步骤 1 = 前置校验(含快照)
|
||
|
||
# 后置对账(升级后运行)
|
||
./tools/flowable-upgrade/flowable_upgrade.sh --db <db> 5 # 步骤 5 = 后置校验(含对账)
|
||
|
||
# 手动 SQL 对账(在目标库执行)
|
||
SELECT
|
||
'act_re_procdef', count(*) FROM eip3.act_re_procdef UNION ALL
|
||
'act_ru_execution', count(*) FROM eip3.act_ru_execution UNION ALL
|
||
'act_ru_task', count(*) FROM eip3.act_ru_task UNION ALL
|
||
'act_hi_procinst', count(*) FROM eip3.act_hi_procinst;
|
||
|
||
-- engineVer 抽查
|
||
SELECT count(*) FROM eip3.act_re_procdef WHERE engine_version_ = 'v5';
|
||
|
||
-- schema.version 确认
|
||
SELECT name_, value_ FROM eip3.act_ge_property WHERE name_ = 'schema.version';
|
||
```
|
||
|
||
## 附录 B:演练完整耗时记录(2026-06-11 本地实测)
|
||
|
||
| 阶段 | 耗时 |
|
||
|------|------|
|
||
| 重拉 5.13 副本(含 bytearray 过滤)| **63s** |
|
||
| ① 前置校验(含快照)| **1s** |
|
||
| ② 版本串规范化 | **0s** |
|
||
| ③ Flowable 5.23 升级 | **2s** |
|
||
| ④ Flowable 6.8.1 兼容层升级 | **18s** |
|
||
| ⑤ 后置校验(含对账)| **0s** |
|
||
| **一键链小计(不含导入)** | **21s** |
|
||
| **全程(导入+链)** | **84s** |
|
||
|
||
> 生产外推(本地服务器口径,无网络瓶颈):一键链约 1–3 分钟(含 bytearray 全量 1.2 GB 拷贝约 2 min)。生产停机窗口公式:`备份验证 + 副本就绪确认 + 一键链 + 业务验证 + 50% 缓冲 ≈ 30 分钟`(极保守上界)。
|
||
|
||
## 附录 C:工具目录结构
|
||
|
||
```
|
||
tools/flowable-upgrade/
|
||
flowable_upgrade.sh # 一键链主控(参数化 host/port/db/schema)
|
||
lib/
|
||
common.sh # 公共配置/函数/计时
|
||
01_precheck.sh # ① 前置校验(幂等只读)
|
||
02_normalize.sh # ② 版本串规范化(幂等)
|
||
03_upgrade_v5.sh # ③ Flowable 5.23 升级(幂等)
|
||
04_upgrade_v6.sh # ④ Flowable 6.8.1 兼容层升级(幂等)
|
||
05_postcheck.sh # ⑤ 后置校验(幂等只读)
|
||
rehearsal/
|
||
rehearse.sh # 完整重演(重拉副本 + 一键链)
|
||
import_5x.sh # 5.13 副本导入(参数化,客户库只读)
|
||
bytearray_copy.py # bytearray 过滤拷贝(参数化)
|
||
sql/
|
||
snapshot.sql # 行数快照 SQL
|
||
.work/ # 运行时产物(快照/日志/计时,gitignore)
|
||
```
|
||
|
||
---
|
||
|
||
*本 Runbook 基于 2026-06-11 本地演练(eip4flow_rehearsal)产出;生产执行前须在客户侧专用环境完整验证并升为 v2。*
|