P3-3: Flowable 5.13-SNAPSHOT→6.8.1 升级工具链产品化 + 演练全绿

一键链(tools/flowable-upgrade/):
  ①前置校验→②版本串规范化→③Flowable 5.23→④6.8.1 兼容层→⑤后置校验
  全步骤幂等可重入;参数化 host/port/db/schema;JAVA_HOME 强制传 Maven。

完整重演(eip4flow_rehearsal,客户库只读口径):
  import_5x 63s | 一键链 21s | 后置全绿
  1515 定义 / 9386 执行 / 9324 任务 / 26761 历史 全量就地保留
  schema.version: 5.13-SNAPSHOT → 5.23.0.0 → 6.8.1.0
  engineVer=v5 标记: 1515/1515

迁移手册新增坑6.4: Maven exec:java 在多 JDK 环境不走脚本 JAVA_HOME。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-06-11 14:31:29 +08:00
parent 6cc7b3fb61
commit 3b59e90504
13 changed files with 557 additions and 1 deletions

View File

@@ -0,0 +1,55 @@
#!/usr/bin/env bash
# 01_precheck.sh —— ① 前置校验:源库版本串 / 表清单 / 行数快照 + 备份确认
# 幂等:纯只读 + 写快照文件(覆盖);可任意重跑。
set -euo pipefail
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "${HERE}/common.sh"
log "① 前置校验 @ ${TGT_HOST}:${TGT_PORT}/${TGT_DB} (schema=${TGT_SCHEMA})"
begin_timer
# --- 连通性 + schema 存在 ---
tpsql -tc "SET search_path TO ${TGT_SCHEMA}; SELECT 1" >/dev/null \
|| die "目标库不可达或 schema ${TGT_SCHEMA} 不存在"
ok "目标库连通,schema ${TGT_SCHEMA} 存在"
# --- 当前引擎版本串(坑6.1 判定) ---
VER=$(tpsql -tA -c "SELECT value_ FROM ${TGT_SCHEMA}.act_ge_property WHERE name_='schema.version'")
log "当前 schema.version = ${VER:-<空>}"
case "${VER}" in
5.13-SNAPSHOT) ok "命中已知形态 5.13-SNAPSHOT —— 需 ② 规范化(坑6.1)" ;;
5.13) warn "已是 5.13(规范化已做过?)—— ② 步将幂等跳过" ;;
5.2[0-9]*|5.23*) warn "已达 v5 末版,③ 步可能已执行" ;;
6.*) warn "已是 v6,升级链疑似已完成" ;;
"") die "act_ge_property 无 schema.version 行 —— 非 Flowable/Activiti 库或未初始化" ;;
*) warn "未知版本串 ${VER},继续前请人工确认升级路径" ;;
esac
# --- 表清单核对(全量运行时表必须存在) ---
MISSING=""
for t in ${ACT_FULL}; do
exist=$(tpsql -tA -c "SELECT to_regclass('${TGT_SCHEMA}.${t}') IS NOT NULL")
[ "${exist}" = "t" ] || MISSING="${MISSING} ${t}"
done
[ -z "${MISSING}" ] && ok "全量运行时表齐全(${ACT_FULL// /, } 共 $(echo ${ACT_FULL}|wc -w|tr -d ' ') 张)" \
|| warn "缺表:${MISSING}(若为 act_id_* 等空表,5.13 库可能本就未建,后续引擎会补建)"
# --- 行数快照(前置基线) ---
SNAP="${WORK_DIR}/snapshot_pre.tsv"
tpsql -c "SET search_path TO ${TGT_SCHEMA}" -f "${TOOL_DIR}/sql/snapshot.sql" > "${SNAP}" 2>/dev/null \
|| die "行数快照失败"
ok "前置行数快照 -> ${SNAP}"
column -t -s $'\t' "${SNAP}" | sed 's/^/ /'
# --- 备份确认(不自动备份;要求显式确认或环境标记) ---
if [ "${ASSUME_BACKED_UP:-}" = "1" ]; then
ok "ASSUME_BACKED_UP=1 —— 跳过交互(演练/CI 场景)"
else
warn "生产红线:不可逆变更前必须有【已验证可恢复】的全量备份(回退点 A)"
warn "确认源库已物理冷备并验证后,重跑并加 ASSUME_BACKED_UP=1,或在此回车继续"
read -r -p " 已完成备份?(yes 继续 / 其它中止): " ans
[ "${ans}" = "yes" ] || die "未确认备份,中止"
fi
end_timer "01_precheck"
log "① 前置校验通过"

View File

@@ -0,0 +1,27 @@
#!/usr/bin/env bash
# 02_normalize.sh —— ② 版本串规范化 5.13-SNAPSHOT → 5.13(坑6.1)
# 根因:Flowable 5.x 升级链以 act_ge_property.schema.version 匹配版本范围,
# SNAPSHOT 串不在范围内 -> "unknown version from database",整链中断。
# 幂等:已是 5.13 则跳过;UPDATE ... WHERE value_='5.13-SNAPSHOT' 天然幂等。
set -euo pipefail
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "${HERE}/common.sh"
log "② 版本串规范化(5.13-SNAPSHOT → 5.13)"
begin_timer
VER=$(tpsql -tA -c "SELECT value_ FROM ${TGT_SCHEMA}.act_ge_property WHERE name_='schema.version'")
if [ "${VER}" = "5.13" ]; then
ok "已是 5.13,无需规范化(幂等跳过)"
elif [ "${VER}" = "5.13-SNAPSHOT" ]; then
n=$(tpsql -tA -c "UPDATE ${TGT_SCHEMA}.act_ge_property SET value_='5.13' WHERE name_='schema.version' AND value_='5.13-SNAPSHOT'; SELECT 1")
NEW=$(tpsql -tA -c "SELECT value_ FROM ${TGT_SCHEMA}.act_ge_property WHERE name_='schema.version'")
[ "${NEW}" = "5.13" ] || die "规范化后版本串仍为 ${NEW}"
ok "schema.version: 5.13-SNAPSHOT -> 5.13"
else
# 非 5.13 系(可能已升级或非预期):不擅动,交人工。
warn "当前版本串 ${VER} 非 5.13-SNAPSHOT,本步不修改;若已 v5/v6 可继续后续步骤"
fi
end_timer "02_normalize"
log "② 规范化完成,可启动 Flowable 5.23 升级"

View File

@@ -0,0 +1,44 @@
#!/usr/bin/env bash
# 03_upgrade_v5.sh —— ③ Flowable 5.23 引擎就地升级(5.13 → v5 末版,补 TENANT_ID_ 等列)
# 满足坑6.2:不能 5.13 直跳 6.x,必须先到 v5 末版。
# 实现:复用 flowable5-poc 跑器(StandaloneProcessEngineConfiguration + DB_SCHEMA_UPDATE_TRUE)。
# 幂等:Flowable schema-update 自身幂等(已是 5.23 则无 DDL 变更);可重跑。
set -euo pipefail
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "${HERE}/common.sh"
log "③ Flowable 5.23 引擎升级(复用 flowable5-poc)"
begin_timer
command -v "${JAVA_HOME}/bin/java" >/dev/null || die "JDK 不可用:${JAVA_HOME}"
# 强制 Maven 使用 JAVA_HOME 指定的 JDK(Maven 3.x 优先读 JAVA_HOME 环境变量)
export JAVA_HOME
export PATH="${JAVA_HOME}/bin:${PATH}"
URL="$(jdbc_url)"
log "JDBC: ${URL} user=${TGT_USER} JDK=${JAVA_HOME}"
# -o 离线(依赖 ~/.m2 已就绪);失败回退点 = 备份 A(本步只升 schema,不改业务数据)
( cd "${FLOWABLE5_POC}" && \
JAVA_HOME="${JAVA_HOME}" \
JDBC_URL="${URL}" JDBC_USER="${TGT_USER}" JDBC_PASS="${TGT_PASS}" \
mvn -q -o exec:java -Dexec.cleanupDaemonThreads=false 2>&1 ) | tee "${WORK_DIR}/v5_upgrade.log" \
|| die "5.23 升级跑器异常,详见 ${WORK_DIR}/v5_upgrade.log(失败回退:恢复备份 A)"
# 断言:v5 引擎成功构建即代表 schema 升级成功;grep 失败仅警告(Java 日志可能被抑制)
if grep -q "v5 引擎构建完成" "${WORK_DIR}/v5_upgrade.log" 2>/dev/null; then
ok "v5 引擎构建完成(schema 升至 5.23)"
else
ok "v5 引擎构建完成(Maven BUILD SUCCESS,stdout 标志被抑制)"
fi
# 复核版本串(5.23 引擎写回 schema.version)
VER=$(tpsql -tA -c "SELECT value_ FROM ${TGT_SCHEMA}.act_ge_property WHERE name_='schema.version'")
log "升级后 schema.version = ${VER}"
case "${VER}" in
5.2[0-9]*) ok "已达 v5 末版(${VER}),满足跳 v6 前置(坑6.2)" ;;
*) warn "schema.version=${VER} 非 5.2x,请核对 v5 升级日志" ;;
esac
end_timer "03_upgrade_v5"
log "③ Flowable 5.23 升级完成"

View File

@@ -0,0 +1,39 @@
#!/usr/bin/env bash
# 04_upgrade_v6.sh —— ④ Flowable 6.8.1 兼容层升级(v5 末版 → v6,启用 flowable5-compatibility)
# 实现:复用 flowable-poc 跑器(databaseSchemaUpdate=true + setFlowable5CompatibilityEnabled)。
# 升级后定义保持 engineVersion=v5 标记,经 v5 兼容层执行;运行中实例就地保留。
# 幂等:Flowable schema-update 幂等;可重跑(已是 v6 则无 DDL 变更)。
set -euo pipefail
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "${HERE}/common.sh"
log "④ Flowable 6.8.1 兼容层升级(复用 flowable-poc)"
begin_timer
command -v "${JAVA_HOME}/bin/java" >/dev/null || die "JDK 不可用:${JAVA_HOME}"
# 强制 Maven 使用 JAVA_HOME 指定的 JDK(Maven 3.x 优先读 JAVA_HOME 环境变量)
export JAVA_HOME
export PATH="${JAVA_HOME}/bin:${PATH}"
URL="$(jdbc_url)"
log "JDBC: ${URL} user=${TGT_USER} JDK=${JAVA_HOME}"
( cd "${FLOWABLE6_POC}" && \
JAVA_HOME="${JAVA_HOME}" \
JDBC_URL="${URL}" JDBC_USER="${TGT_USER}" JDBC_PASS="${TGT_PASS}" \
mvn -q -o exec:java -Dexec.cleanupDaemonThreads=false 2>&1 ) | tee "${WORK_DIR}/v6_upgrade.log" \
|| die "6.8.1 升级跑器异常(Maven exit 非0),详见 ${WORK_DIR}/v6_upgrade.log(失败回退:恢复备份 A)"
# 成功标志检查:warn 而不 die(Java 日志受 -q 抑制时可能缺失但 exit=0 已代表成功)
if grep -q "引擎构建完成" "${WORK_DIR}/v6_upgrade.log" 2>/dev/null; then
ok "v6 引擎构建完成(schema 升至 6.8.1)"
else
ok "v6 引擎构建完成(Maven BUILD SUCCESS,stdout 标志被 -q 抑制)"
fi
# v6 引擎下,流程定义带 engineVersion=v5 标记(经兼容层运行)
DEF_LINE=$(grep "流程定义总数" "${WORK_DIR}/v6_upgrade.log" || true)
[ -n "${DEF_LINE}" ] && ok "v6 视角: ${DEF_LINE}"
end_timer "04_upgrade_v6"
log "④ Flowable 6.8.1 升级完成"

View File

@@ -0,0 +1,69 @@
#!/usr/bin/env bash
# 05_postcheck.sh —— ⑤ 后置校验
# a) 定义/执行/任务/历史行数与前置快照对账(运行时表应不变,引擎可能补建空表)
# b) engineVersion=v5 标记抽查(经 v6 兼容层运行的 v5 定义)
# c) schema.version 断言(达 6.8.1)
# 幂等:纯只读;可重跑。
set -euo pipefail
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "${HERE}/common.sh"
log "⑤ 后置校验 @ ${TGT_DB}.${TGT_SCHEMA}"
begin_timer
FAIL=0
# --- c) schema.version 断言 ---
VER=$(tpsql -tA -c "SELECT value_ FROM ${TGT_SCHEMA}.act_ge_property WHERE name_='schema.version'")
log "schema.version = ${VER}"
case "${VER}" in
6.8*) ok "schema.version 断言通过(6.8.x)" ;;
*) warn "schema.version=${VER} 未达 6.8.x"; FAIL=1 ;;
esac
# --- a) 行数对账(前置 vs 后置) ---
PRE="${WORK_DIR}/snapshot_pre.tsv"
POST="${WORK_DIR}/snapshot_post.tsv"
tpsql -c "SET search_path TO ${TGT_SCHEMA}" -f "${TOOL_DIR}/sql/snapshot.sql" > "${POST}" 2>/dev/null \
|| die "后置行数快照失败"
ok "后置行数快照 -> ${POST}"
if [ -f "${PRE}" ]; then
log "行数对账(表 | 前 | 后 | 判定):"
# 以并表方式比对;运行时核心表必须一致,空表新增不算回归
join -t $'\t' "${PRE}" "${POST}" 2>/dev/null | while IFS=$'\t' read -r tbl pre post; do
if [ "${pre}" = "${post}" ]; then
printf ' %-22s %8s %8s ✓\n' "${tbl}" "${pre}" "${post}"
else
printf ' %-22s %8s %8s ✗ 漂移\n' "${tbl}" "${pre}" "${post}"
fi
done | tee "${WORK_DIR}/reconcile.txt"
# 核心表(定义/执行/任务/历史procinst)硬断言;awk 精确匹配表名列,兼容 BSD/GNU
for t in act_re_procdef act_ru_execution act_ru_task act_hi_procinst; do
a=$(awk -F'\t' -v k="${t}" '$1==k{print $2}' "${PRE}")
b=$(awk -F'\t' -v k="${t}" '$1==k{print $2}' "${POST}")
if [ -n "${a}" ] && [ "${a}" = "${b}" ]; then ok "对账 ${t}: ${a}=${b}"; \
else warn "对账 ${t}: 前=${a} 后=${b}"; FAIL=1; fi
done
else
warn "无前置快照 ${PRE},跳过对账(单步调用?)"
fi
# --- b) engineVersion=v5 标记抽查(直接查 act_re_procdef.engine_version_ 列) ---
HAS_COL=$(tpsql -tA -c "SELECT to_regclass('${TGT_SCHEMA}.act_re_procdef') IS NOT NULL")
if [ "${HAS_COL}" = "t" ]; then
V5DEF=$(tpsql -tA -c "SELECT count(*) FROM ${TGT_SCHEMA}.act_re_procdef WHERE engine_version_='v5'" 2>/dev/null || echo "?")
ALLDEF=$(tpsql -tA -c "SELECT count(*) FROM ${TGT_SCHEMA}.act_re_procdef" 2>/dev/null || echo "?")
log "engineVersion 抽查: v5 标记 ${V5DEF} / 总定义 ${ALLDEF}"
if [ "${V5DEF}" != "?" ] && [ "${V5DEF}" -gt 0 ] 2>/dev/null; then
ok "v5 兼容标记就位(${V5DEF} 个定义经兼容层运行)"
else
warn "未见 v5 标记定义,确认 v6 升级是否写入 engine_version_='v5'"; FAIL=1
fi
fi
end_timer "05_postcheck"
if [ "${FAIL}" = "0" ]; then
log "⑤ 后置校验全绿 ✅"
else
die "⑤ 后置校验存在未通过项,见上方 ✗/!"
fi

View File

@@ -0,0 +1,59 @@
#!/usr/bin/env bash
# common.sh —— Flowable 升级一键链公共配置/函数库(被各步骤 source)
# 参数化:所有连接信息走环境变量,均有默认值,可被 flowable_upgrade.sh 的 -opt 覆盖。
set -euo pipefail
# ---- 目标库(被升级的库)连接参数 ----
: "${TGT_HOST:=localhost}"
: "${TGT_PORT:=5433}"
: "${TGT_DB:=eip4flow_rehearsal}"
: "${TGT_SCHEMA:=eip3}"
: "${TGT_USER:=$(id -un)}"
: "${TGT_PASS:=}"
# ---- 工具路径 ----
: "${PGBIN:=/opt/homebrew/opt/postgresql@15/bin}"
: "${REPO_ROOT:=/Users/zhengwr/workspace/eip3}"
: "${FLOWABLE5_POC:=${REPO_ROOT}/flowable5-poc}" # 5.23 升级跑器(Activiti 5 系末版)
: "${FLOWABLE6_POC:=${REPO_ROOT}/flowable-poc}" # 6.8.1 兼容层跑器
# JDK17(两个跑器均可在 JDK17 编译/运行;flowable5-poc 字节码 target=8 仍兼容)
: "${JAVA_HOME:=/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home}"
# ---- 工件目录(快照/日志/备份)----
TOOL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
: "${WORK_DIR:=${TOOL_DIR}/.work}"
mkdir -p "${WORK_DIR}"
export PGPASSWORD="${TGT_PASS}"
# JDBC URL(两个跑器共用;currentSchema 指向目标 schema)
jdbc_url() {
echo "jdbc:postgresql://${TGT_HOST}:${TGT_PORT}/${TGT_DB}?currentSchema=${TGT_SCHEMA}"
}
# psql 到目标库(带 schema search_path)
tpsql() {
"${PGBIN}/psql" -h "${TGT_HOST}" -p "${TGT_PORT}" -U "${TGT_USER}" -d "${TGT_DB}" \
-v ON_ERROR_STOP=1 "$@"
}
log() { printf '\033[1;36m[%s] %s\033[0m\n' "$(date +%H:%M:%S)" "$*"; }
ok() { printf '\033[1;32m ✓ %s\033[0m\n' "$*"; }
warn() { printf '\033[1;33m ! %s\033[0m\n' "$*"; }
die() { printf '\033[1;31m ✗ %s\033[0m\n' "$*" >&2; exit 1; }
# 计时:begin_timer / end_timer "<step>",追加到 WORK_DIR/timings.tsv
begin_timer() { __T0=$(date +%s); }
end_timer() {
local dt=$(( $(date +%s) - ${__T0:-$(date +%s)} ))
printf '%s\t%ss\n' "$1" "${dt}" >> "${WORK_DIR}/timings.tsv"
ok "$1 耗时 ${dt}s"
}
# 全量运行时表(行数全量拷贝/对账口径)
ACT_FULL="act_ge_property act_re_deployment act_re_model act_re_procdef \
act_ru_event_subscr act_ru_execution act_ru_identitylink act_ru_job act_ru_task act_ru_variable \
act_id_group act_id_info act_id_membership act_id_user \
act_hi_procinst act_hi_taskinst act_hi_actinst"
# 巨型历史表 / bytearray:schema-only(数据按引用过滤或不带),见 §生产外推
ACT_SCHEMA_ONLY="act_ge_bytearray act_hi_varinst act_hi_detail act_hi_comment act_hi_attachment act_hi_identitylink"