流程正在运行代码升级了怎么办版本、兼容与实例迁移周一星河设备有三百份维保开通申请等待运营审核。周二产品经理提出新要求所有新申请必须在运营批准后再等待财务确认才能进入 READY。开发人员改了 Workflow 代码部署了新 Worker新增申请看起来运行正常。到了周三周一提交的旧申请却卡住了。旧实例的历史记录要求它在批准后直接完成新代码却要求它等待一条此前从未定义过的付款 Signal。即便没有立即报错业务团队也会问客户提交时承诺的规则为何被发布动作悄悄改变长期运行的流程和普通 Web 请求最大的升级差异在这里发布时仍有大量执行实例停在代码中途。代码不是只服务“现在创建的请求”还必须解释“过去已经开始、未来仍会继续”的历史。前一篇验证新 Worker 可以恢复相同代码的旧历史本篇进一步验证兼容升级先用 V1 Worker 创建并暂停旧实例停止它换成包含 V1 与 V2 路径的 V2 Worker再让旧实例继续同时创建一个 V2 新实例。实验还用 Temporal Python SDK 的 Replayer 回放旧历史检查新代码能否解释它。所有结果来自本地测试服务器不代表生产发布系统已经完成全链路验收。一、先把“版本”拆成四个独立问题团队常说“流程版本从 1 升到 2”但一个整数可能被拿来指四件不同的事。第一是 Workflow 编排代码版本Signal、Timer、Activity 的顺序及分支是否改变旧历史能否在新 Worker 上重放。第二是业务规则版本运营批准条件、套餐价格、签署时限、财务核对方式按哪一版执行。第三是事件契约版本付款回执 JSON 里新增字段、删除字段或改变含义后旧生产者与新消费者能否互通。第四是数据库结构版本原来的列如何在发布与回滚期间被新旧进程读取。四者发布节奏不同不能把一个 deploy_version 当作通用答案。例如新的财务确认规则只适用于周二之后的申请可以在实例创建时固定 process_version2让旧申请仍按 v1 走这解决的是业务含义。但如果开发者顺手把旧分支中 Activity 的顺序也调换就可能产生编排重放问题。又如付款事件新增 material_version 字段新入口需要理解它而仍在运行的老实例可能收到旧格式事件这是消息契约问题。数据库新增 paid_at 列并要求非空则发布第一秒就可能让旧 Worker 写库失败这是结构迁移问题。图 1 把四条轴画开便于在评审会上逐项提问。图 1教学兼容性图。一次发布需要分别检查四个维度不以一个版本号替代所有设计。Temporal 官方 Python 版本文档说明运行很久的实例遇到不兼容的 Workflow 代码变更时需要采用版本策略。当前官方主要介绍 Worker Versioning 和 Patching 两种机制前者通过部署版本管理旧新 Worker后者通过历史里的 patch 标记让同一 Workflow 定义兼容不同历史。本篇实验没有配置生产级 Worker Versioning也没有调用 patched它只演示保留旧路径、在创建时固定流程版本以及对旧历史做回放验证。把教学实验与平台完整机制区分开才不会误以为“加一个 if”就解决所有升级问题。二、一个正在等待的申请该遵循哪版规则我们给案例定一条可解释的产品规则V1 申请在运营批准后完成当前最小流程V2 申请必须再等财务确认。更复杂的真实开通还需材料完整、合同签署和远端服务动作这里压缩路径只为了把升级冲突暴露出来。申请 UUID 继续作为 application_idWorkflow ID 使用 xinghe-demo/UUID业务系统仍保存 business_key 与 material_version。这个独立实验不连接第 03 篇 PostgreSQL也不把业务页面状态同步进去。因而文中的 READY 只是实验 Workflow 的结果不能直接等同于完整 AcmeFlow 项目的“签署、收款、ERP 均满足后可开通”。在 V1 定义里run 接收 process_version 但只执行等待批准的旧命令序列。这样旧实例启动时的参数、Workflow 类型和审批 Signal 名称被记录。V2 定义保留相同的旧路径先等待 approve若 process_version 是 1就返回 V1 结果若是 2再等待 confirm_payment。旧实例即使在 V2 Worker 上被重新加载也会遇到与旧历史兼容的前半段并沿着冻结的版本走。V2 新实例则会进入财务等待。关键不是条件语句语法而是版本必须在实例创建时固定、旧分支语义不能被“最新版规则”偷偷覆盖。V2 代码里最重要的不是变量名而是旧分支仍在原位置结束新分支才增加等待awaitworkflow.wait_condition(lambda:self.approved)ifprocess_version1:return{application_id:application_id,path:v1,state:READY}ifprocess_version!2:raiseValueError(unsupported process version)awaitworkflow.wait_condition(lambda:self.paid)return{application_id:application_id,path:v2,state:READY}图 2教学分流图。代码版本升级之后两代业务实例仍可能同时存在。是否允许旧实例被迁移到 V2需要业务方明确决定而不能由部署脚本代替。对于一份已经审核通过、客户已按旧条款签约的申请追加新付款条件可能改变合同承诺对于还没开始审核的申请企业也许希望补充核查。迁移政策应该按阶段、材料版本、合同与付款事实划分而不是“一切未完成实例全部升级”。如果决定迁移就要记录迁移命令、审批人、目标规则版本、已经完成的外部副作用以及客户是否需要重新确认。迁移是业务动作不只是把一列 version 改成 2。三、实验如何真正穿过一次代码升级代码文件 upgrade_demo.py包含两个 Python 类OpeningV1 与 OpeningV2向 Temporal 注册为同一个 Workflow 类型 VersionedOpening。运行开始时V1 Worker 轮询教学任务队列创建旧实例并通过查询确认它已到 WAITING_APPROVAL。然后退出 V1 Worker 上下文启动只注册 V2 定义的新 Worker。在这个新 Worker 存活期间创建一份 process_version2 的新申请分别给旧新实例发批准 Signal。旧实例立即返回 V1 READY新实例仍处于 WAITING_PAYMENT直到收到财务确认才返回 V2 READY。最后脚本获取旧实例历史用 V2 定义运行 Replayer并断言没有重放失败。这个顺序比只做“V2 函数单元测试”有价值。单测可以证明新分支在空白环境下返回正确结果却不知道周一的旧历史是否能被新代码解释。实验里先创建旧历史再让新 Worker 接手旧历史是升级动作真正要兼容的对象。代码设置 max_cached_workflows0降低本地测试服务器中黏性缓存对观察的干扰它不是推荐给所有生产 Worker 的默认配置。两份申请都使用完整 UUID避免把可读编号当唯一实例身份。脚本输出中的 UUID 每次不同而 V1、V2 的路径与结果断言保持稳定。图 3发布步骤示意。下线旧代码的条件是旧实例与历史兼容责任已结束而不是新代码冒烟成功。本机实际运行使用 temporalio 1.33.0 与 SDK 的 time-skipping 测试服务器。输出显示旧实例在发布前等待批准发布后旧结果走 v1新结果走 v2旧历史有十二个事件V2 Replayer 对这份历史返回通过。脚本还故意提供一份错误升级定义在旧审批等待点之前插入 Timer。对同一旧历史回放时得到 NondeterminismError证明发布门确实能抓住至少这一种不兼容修改。这个结果仍只覆盖这一条旧历史没有覆盖驳回、取消、超时、Activity 重试、多次 Signal 或真实数据库迁移。因此 README 要求实际项目选取多种历史样本而不能把“一个实例回放通过”写成所有旧实例都安全。四、为什么重放测试需要成为发布门Workflow 的重放失败可能在发布后数小时才显现旧实例一直等待人工直到审批 Signal 到达才唤醒此时才被新 Worker 执行。若团队只在部署后运行新实例冒烟测试问题会被时间延迟隐藏。比较稳妥的做法是在发布前收集有代表性的历史等待审批的、已收到付款但未签署的、正在重试 Activity 的、已经部分补偿的以及即将超时的。对历史进行脱敏后在 CI 中用将要发布的 Worker 定义执行回放任何非确定性错误都应阻断上线或启动兼容方案。Temporal Python 官方测试文档给出 Replayer 的使用方式。选择样本不能只按“最近十条”。长流程最危险的往往是很早以前创建、处在旧规则边缘的实例。团队应统计活跃实例按流程版本、当前阶段、等待时长、是否已有外部副作用的分布再按这些维度抽样。更理想的情况是保留匿名化的典型历史作为回归资产新增分支、调整 Activity 顺序或清理旧代码时自动回放。回放通过仍不等于发布就万无一失因为新事件契约、数据库迁移和真实外部接口可能另有问题它是必要的一道门不是全部门。图 4兼容矩阵。技术重放通过之外消息、数据库和业务版本都要有证据。还有一个容易混淆的概念读取旧历史与“让旧业务规则继续有效”不是一回事。某些修改可能在技术上可重放却改变了规则。例如把 V1 的审批通过阈值从一百万元改成五十万元旧实例的代码分支仍能运行但等待中的审批从业务上被重新解释。流程参数或规则版本应指向可追溯的决定依据必要时保存决策表版本和当时关键输入而不是每次从可变配置中心读取当前阈值。技术确定性约束只是下限业务承诺与审计一致性还要单独检查。五、平台版本机制与本篇 if 分支各适合什么最小实验把 V1、V2 路径同时放在新代码里适合让读者看清“旧实例继续走旧路”的原则。在长期维护的大系统里无限叠加 if process_version n 会使单个 Workflow 难以理解也可能错误地在共同前半段改变命令顺序。Temporal 的 Worker Versioning 能把新旧 Worker 部署与正在运行的实例关联起来让不同版本代码处理各自历史Patching 则通过显式历史标记处理同一 Workflow 定义的演进。需要哪种方式取决于实例寿命、部署管理、分支规模与团队能否持续维护旧 Worker。当前官方 Python 版本说明明确记录两种方向并提示早期实验性 Worker Versioning 机制的淘汰时间不要复制过时教程里的旧 API。如果改动只是 Activity 内部的 HTTP 超时或日志格式且 Activity 的输入、输出语义不变可能无需改 Workflow 编排版本。但“只改 Activity”也不自动安全改变对 ERP 的幂等键算法、把 UNKNOWN 误判为失败、或者改变返回结构都会影响业务结果和后续分支。升级评审应问具体问题旧历史里记录的 Activity 结果新代码是否还能解析正在重试的旧 Activity 请求是否会被新代码用不同键再次发送哪些实例已对远端产生副作用能否回滚这些比争论版本号应该写成字符串还是整数更关键。图 5教学发布门。旧历史兼容与新实例行为分别验证线上仍需灰度监控。六、数据库与事件契约应该怎样配合发布假设 V2 需要在申请表增加 finance_confirmed_at直接发布一个 NOT NULL 新列会使尚未写这个字段的 V1 Worker 失败。较平稳的策略是先扩展数据库增加可空列或兼容默认值让旧代码仍能运行再发布能读写新列的版本补齐旧数据并观察确认旧版本退出后再收缩约束。这个“先扩展、后迁移、再收缩”的过程要有明确的时间窗和回滚点。若旧实例还在写旧事件格式接入层也应同时识别两个 schema_version而不是在午夜切换后立刻把旧消息判为脏数据。事件兼容尤其容易在重试时暴露。一条周一由合同系统发出的 v1 签署消息可能周三才从队列死信重放此时消费者已经升级到 v2。如果 v2 解析器把缺失 material_version 自动填成“当前版本”可能把针对旧材料的签署错误地绑定到新材料。更安全的选择是从可信关联信息恢复旧版本、在无法确定时隔离到人工队列或者明确拒绝并保留原始事件以供调查。不能为了让解析通过而猜出一个会推进业务状态的值。消息格式升级是业务事实解释权的升级。数据库回滚也应考虑已经产生的新数据。新代码把 V2 财务事实写进新列后退回 V1 应用版本旧代码是否会忽略这些事实、重新发起开通若会就不能把“镜像回滚成功”当成业务回滚成功。发布记录至少包括新版本开始处理的实例清单、外部操作清单、数据转换脚本、可安全回退的时间范围和超过范围后的人工处置办法。尤其是与 ERP、CRM、付款系统交互的流程数据库可以回滚远端服务记录却未必能撤销。七、旧实例处理的三种选择第一种是保留旧路径让 V1 实例自然结束。它最易向业务解释但要继续维护旧代码、旧事件格式及必要的 Worker。若一份申请最长只运行几天这通常很合理。第二种是显式迁移旧实例由授权命令记录从 V1 到 V2 的决定先核对已完成的审批、付款、ERP 动作再制定从新版本哪个位置继续迁移后必须能解释旧审批是否仍有效。第三种是人工处置对长期卡住、材料不完整或结果未知的少量实例停止自动推进交给专人对账、终止或重建。三种选择可以同时存在按实例阶段分类。直接更新 application.process_version 字段并让旧实例突然进入 V2是最危险的“捷径”。数据库字段改变了Temporal 历史中的命令与已完成外部动作却没有改变。已经创建 ERP 记录的实例如果误回到“创建 ERP”步骤可能重复开通已经签署 V1 合同的实例如果按 V2 解释可能违反客户预期。迁移方案必须处理事件历史与外部事实而不是只处理一个状态值。图 6 列出了保留、迁移、人工处理各自的条件。图 6实例迁移决策示意。改变版本字段不等于完成业务迁移。八、故障实验一行 Timer 为什么会挡住旧实例为了检验回放门不是“永远返回通过”的摆设示例中增加了 BreakingOpening。它保持同一个 Workflow 类型名却在旧代码原本等待批准的地方先安排一个新的 Timer。新实例从头创建时这段代码当然可能运行问题在于旧实例的历史没有这个 Timer 命令。Replayer 把已完成的 V1 历史交给 BreakingOpening检测到新命令与历史事件不一致抛出 NondeterminismError。本机日志可见 Timer machine 无法处理旧历史末尾的完成事件。这个负向检查与 V2 兼容路径的正向检查共同构成发布门同一份旧历史对保留旧路径的代码应通过对破坏命令顺序的代码应失败。错误发布在真实系统中未必表现得这么及时。某份申请可能等待财务一个月错误代码已上线二十九天新创建的申请都顺利完成直到第三十天旧实例收到账款确认才触发重放失败。因此故障演练应主动唤醒和回放代表性旧实例历史不要靠自然流量碰运气。历史样本也应覆盖不同位置尚未开始 Activity、已完成第一个 Activity、等待第三方回执、定时器即将触发、进入人工补救。每个位置经历过的命令不同一份历史的通过结论不能向所有位置外推。也不要因为负向实验抛错就推断“任何增加等待步骤都不允许”。问题是如何在旧历史与新实例之间提供兼容规则。可以用明确的 process_version 分支保留旧路径像本篇这样只给 v2 新实例增加付款等待也可以按官方 Patching 机制在历史中记录标记还可以借助 Worker Versioning 让旧实例继续由旧 Worker 执行。哪种方案可行取决于当前实例集合和平台部署能力。真正不能接受的是没有盘点旧实例、没有回放测试就把旧历史不能解释的新代码直接覆盖在唯一 Worker 上。九、一份可审核的升级决策记录应该写什么业务变更说明要写清适用对象从哪一天或哪条创建命令开始哪些申请进入 V2旧申请是否仍按 V1处于哪个阶段的旧申请可以申请迁移。规则依据要附上可核对的材料合同版本、财务政策编号、审批权限矩阵和异常处置责任人。技术记录则要写出 Workflow 定义的变更点、Activity 输入输出是否变化、事件 schema 如何兼容、数据库何时扩展和收缩以及历史回放使用了哪些样本。最后要注明上线期间若出现旧实例卡住谁有权暂停、对账和回滚。这样的记录不必长得像一本设计书但要让事故发生时的值班人员知道不能随意改哪一项。一个容易落地的实践是给发布设三道可见门。第一道检查新实例的正向路径V2 确实需要运营与财务两个事实不能仅凭其中一个返回 READY。第二道检查旧实例与旧历史V1 在新 Worker 上继续完成、回放通过负向样本能被门禁识别。第三道检查跨系统事实针对已有 ERP 服务记录和权益的实例升级不能改变 external_ref也不能把已经成功的动作重新安排。若第三道门尚无自动化可以在发布记录中列出人工抽查与回退条件。把门设在部署之前远比出故障后解释“CI 绿了”有用。回滚策略也要区分代码与业务。V2 Worker 如果只处理了新建申请、还没向外部系统发动作回退到保留 V1/V2 双分支的兼容版本可能相对直接若 V2 已经生成财务任务、收到了新格式消息并创建 ERP 记录回滚镜像并不会撤回这些业务事实。此时应暂停新实例入口保证已有实例由兼容 Worker 继续处理必要时人工对账而不是试图让旧代码忽略已经发生的动作。流程发布本质上是对正在运行的业务承诺做切换版本管理必须能追溯这种切换。十、交付验收应落到每个实例验收人员不应只看“发布成功”四个字。抽一份发布前创建的 V1 申请确认它的申请 UUID、资料版本和合同依据未变在新 Worker 上发送原本允许的审批命令检查结果仍按 V1再抽一份发布后创建的 V2 申请批准后确认它仍等待付款没有提前 READY最后提供旧历史回放结果和故意破坏命令序列时的失败记录。这四种证据分别证明旧承诺得到履行、新规则真正生效、兼容门能抓错误。它们缺一不可而且都要能追到同一个业务标识避免拿别的申请截图代替。如果客户在升级窗口修改了材料验收还要检查审批绑定。V1 申请的材料从 v1 改成 v2不因为流程版本仍是 V1 就允许旧审批覆盖新材料process_version 决定流程规则适用范围material_version 决定审批所依据的数据两者不能互相替代。如果付款回执也针对旧合同版本新的流程代码更不能因为已收到 PAYMENT_CONFIRMED 字样就自动标记 ready。版本问题最终都要回到同一个业务问题我们能否证明当前推进依据的事实与当时人和系统认可的那份事实一致。十一、什么时候才可以删掉 V1代码库里留着旧分支会让人不舒服于是有人提出“现在所有新申请都走 V2可以删 V1 了”。这个判断少看了正在运行的实例。删除旧路径之前至少要确认没有仍需 V1 代码推进的活跃实例包括被暂停、待人工、待回调和待重试的实例确认故障恢复或历史回放窗口内不会要求重新解释旧历史确认相关业务审计不依赖运行时重新计算旧结果。对于已经完成的历史保留多久、能否归档、是否必须继续支持回放也要遵循平台留存策略与企业规定。仅统计最近一天创建的实例毫无意义。如果团队使用 Patching清理过程还要遵循官方定义的阶段先用 patched 在新旧代码间建立可回放分支在旧执行消失后使用 deprecate_patch 过渡最后才移除标记。不能看到新分支稳定运行三天就直接删除补丁。若采用 Worker Versioning旧 Worker 的下线条件也必须来自与之关联的执行是否结束以及异常恢复期间是否还需要它。不同版本机制的操作细节应按当前官方文档实施本篇代码没有实现这些生产配置读者不应把 process_version if 分支当成这些机制的完整替身。还应做一次“删除前反向演练”在测试环境从旧备份或脱敏历史中恢复一份典型 V1 实例用计划发布的无 V1 代码版本回放。若仍有实例需要旧路径演练会在真正删除之前暴露问题。若全部通过也要确认事件入口不会再次投递针对旧版本的回调数据库里与旧版本相关的解释字段已妥善保留。删除代码、删除数据、拒绝旧消息是三个不同动作应分别有负责人和生效条件。一次发布可以只清理其中一个不必为了“干净”同时做完。最后版本数量本身可以成为设计反馈。若每周新增一条 Vn 分支且永远无法删掉可能说明流程寿命、规则变更节奏与单一 Workflow 定义不匹配。可以考虑把业务决策数据外移并在实例启动时绑定不可变规则快照或者把变化较大的子流程拆成有独立版本的组件但拆分也会增加关联和运维复杂度。先通过活跃实例分布、历史体量和维护成本确认问题再改变架构。版本策略的目标是稳定履约不是追求代码里永远只有最新版。业务负责人参与清理评审同样重要。工程团队可能认为“旧实例已经完成”但客服仍有需要补发确认函的客户财务仍可能收到迟到对账记录合同系统也可能重推旧回执。若后续处理依赖旧规则的解释能力至少要把规则依据与处理手册保留下来让入口能识别旧消息并给出明确去向。技术上可以删除一段执行代码不代表企业可以忘记它曾经对客户作出的承诺。把历史规则、关联键和责任人一起归档旧版本才算真正退出。十二、Workflow Thinking发布其实是一次业务切换当客户问“为什么我昨天提交的申请和今天提交的申请审核标准不同”团队应能指出生效日期、流程版本、合同与材料版本并说明该申请按哪条规则处理。如果解释只能停留在“昨天部署了新代码”说明产品规则与运行实例还没有建立可追溯关系。版本设计的目标不是积累大量分支而是让变更的适用范围清楚、旧承诺得到履行、异常实例有负责的人。一个好的发布决策记录应该把技术兼容结果与业务影响写在同一页。本篇实验有两项可核对的成果旧实例在新 Worker 上继续走 V1 路径新实例等待新增的付款确认V2 定义成功回放旧历史。这些结果来自真实 Temporal SDK 测试服务器和实际脚本输出。它们没有验证生产 Worker Versioning 的路由策略也没有验证数据库迁移、事件网关灰度或多租户权限。接入真实系统时应在发布前盘点活跃实例与外部副作用发布中同时观察旧新路径发布后待旧实例退出并过了必要的保留窗口才删除兼容代码。下一篇进入 ERP 与 CRM 接口边界继续处理版本之外的另一种麻烦请求已在远端成功本地却不知道。