- 从工作区根 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>
13 KiB
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。