Files
eip4-platform/docs/P3-Flowable升级/Flowable升级Runbook-v1.md
zhengwr 1b69f8b481
Some checks failed
ci / build-test-parity (push) Has been cancelled
docs: 统一项目文档进 eip4-platform/docs + 新增进度路线总览
- 从工作区根 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>
2026-06-17 14:53:29 +08:00

13 KiB
Raw Blame History

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

一键链调用方式

# 演练(本地副本,跳过备份确认)
./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:对账脚本

# 前置快照(升级前运行,输出到 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。