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

253 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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。*