服务注册与分布式协调 / 系统课时
排查 Non-Determinism 错误
排查 Non-Determinism 错误
Non-Determinism 表示 Worker 在重放历史时,当前 Workflow 代码生成的命令序列与已记录历史无法对应。排查重点不是“哪一行抛异常”,而是找到第一处命令分叉,再用 Replay 复现,并为存量执行保留兼容路径或旧 Worker。
学习目标
- 根据 Workflow History 找到当前代码与既有命令序列第一次不一致的位置。
- 使用 Replay 在发布前复现并验证确定性问题。
- 选择版本分支、Worker Versioning 或旧 Worker,让存量执行安全完成。
先找第一处历史与代码分叉
Temporal 会把 Workflow 执行过程中的关键决定记录进 History。Worker 处理新的 Workflow Task 时会重放这些历史事件,并重新执行 Workflow 代码;只要代码在相同历史输入下生成了不同的 Activity、Timer、Child Workflow 等命令,重放就可能失败。
因此不要从最新日志倒推全部代码。先固定失败的 Workflow ID 和 Run ID,导出对应 History,然后定位报错附近“历史已经记录了什么”和“当前代码准备发出什么”。第一处不一致通常比后续连锁错误更有价值。

识别最常见的破坏方式
最直接的原因是发布后改变了命令顺序,例如旧代码先启动 Activity A 再启动 Timer,新代码把 Timer 提前;对于仍在执行的旧 Workflow,重放到这一段时就会与历史不一致。
另一类原因是 Workflow 直接读取重放时可能变化的值,例如标准库当前时间、随机数、进程环境变量、外部文件、网络结果,或依赖不稳定遍历顺序来决定是否调度命令。Workflow 中应使用 SDK 提供的确定性时间和随机/Side Effect 机制,外部 I/O 则放进 Activity。
用 Replay 在本地复现
Replay 的价值是让同一份真实 History 在不继续推进生产 Workflow 的情况下经过当前代码。下面是 Go SDK 中常见的回放片段;它依赖项目已经定义 OrderWorkflow,并提供实现了 SDK log.Logger 接口的 logger,因此这里明确作为片段示例。
replayer := worker.NewWorkflowReplayer()
replayer.RegisterWorkflow(OrderWorkflow)
err := replayer.ReplayWorkflowHistoryFromJSONFile(logger, "history.json")
if err != nil {
return fmt.Errorf("replay failed: %w", err)
}验证方法是固定同一份 history.json:在故障版本上 Replay 应稳定复现错误;完成修复后,Replay 应返回 nil。如果仍失败,继续以新的第一处分叉为定位点,而不是一次性修改更多代码。
对受影响范围较大的发布,应抽取多份 History 覆盖不同运行阶段,因为某个版本分支可能只在特定路径、定时器阶段或长时间运行的 Workflow 上触发。Replay 通过一份样本,只能证明这一份历史兼容。
用兼容分支保住存量执行
当业务确实需要改变命令顺序,而旧 Workflow 仍会重放到这段代码时,可以用版本分支把旧 History 和新执行分开。下面的片段依赖已注册的 ChargeOrder 与 ReserveStock Activity,展示经典的 workflow.GetVersion 兼容方式。
func OrderWorkflow(ctx workflow.Context) error {
ctx = workflow.WithActivityOptions(ctx, workflow.ActivityOptions{
StartToCloseTimeout: time.Minute,
})
version := workflow.GetVersion(
ctx,
"order-sequence-v2",
workflow.DefaultVersion,
1,
)
if version == workflow.DefaultVersion {
if err := workflow.ExecuteActivity(ctx, "ChargeOrder").Get(ctx, nil); err != nil {
return err
}
return workflow.ExecuteActivity(ctx, "ReserveStock").Get(ctx, nil)
}
if err := workflow.ExecuteActivity(ctx, "ReserveStock").Get(ctx, nil); err != nil {
return err
}
return workflow.ExecuteActivity(ctx, "ChargeOrder").Get(ctx, nil)
}旧 History 在没有新版本 Marker 的情况下继续走旧顺序,新启动的执行则记录版本并走新顺序。验证时必须同时 Replay 旧 History,并新启动一条 Workflow 检查新路径;只验证其中一边,仍可能留下新的确定性问题。
如果团队已经使用 Worker Versioning 或明确的部署版本路由,也可以让旧 Workflow 继续由兼容旧代码的 Worker 处理,新执行进入新版本。关键原则不变:同一份 History 必须始终能找到与它兼容的 Workflow 代码。
什么时候应该回退旧 Worker
若刚发布后大量长流程同时报 Non-Determinism,而修复分支还没有经过足够 Replay 样本验证,最稳妥的止血通常是恢复能够重放这些 History 的旧 Worker,并停止让不兼容版本继续接管受影响执行。
只有在确认受影响 Workflow 已经完成、迁移或由兼容版本稳定接管后,才能清理旧代码路径。清理前再次用代表性的旧 History 做 Replay,并观察 Workflow Task 是否持续推进、Non-Determinism 错误是否归零;“新启动的 Workflow 正常”并不能证明存量执行已经安全。