# 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 --port --db --schema eip3 \ --user --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 1 # 步骤 1 = 前置校验(含快照) # 后置对账(升级后运行) ./tools/flowable-upgrade/flowable_upgrade.sh --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。*