服务注册与分布式协调 / 系统课时
使用 Worker Deployment Versioning
使用 Worker Deployment Versioning
本课把 Worker 发布变成可控制的版本路由:用 Worker Deployment Versioning 注册新旧版本、渐进放量、切换 Current、回滚并等待旧版本排空,确保运行中的 Workflow 在升级期间继续由兼容代码处理。
学习目标
- 理解 Worker Deployment、Deployment Version、Current 与 Ramping 的关系
- 为 Worker 声明稳定的 Deployment Name、不可复用的 Build ID 和 Workflow Versioning Behavior
- 用小流量放量、回滚和 Draining/Drained 状态安全完成版本交接
把代码版本变成可路由对象
一个 Worker Deployment 表示长期存在的服务身份,例如 payments-worker;一次发布对应一个 Worker Deployment Version,由 Deployment Name 与 Build ID 共同标识。Build ID 应来自不可变构建标识,例如 Git 提交或镜像摘要,不能把同一个 Build ID 重新指向另一份代码。
Deployment 中通常有一个 Current Version,也可以同时有一个 Ramping Version。Ramping 接收指定比例的新 Workflow;其余新 Workflow 进入 Current。这样新旧 Worker 可以并行运行。Worker Versioning 应采用 blue-green 或 rainbow 一类并存式发布,不要用原地滚动替换把旧版本提前清掉。
Workflow 还要选择 Versioning Behavior。Pinned 会让一次执行始终留在启动时的 Deployment Version,适合能够保留旧 Worker 直到执行结束的场景;Auto-Upgrade 会随路由目标升级,因此 Workflow 代码仍必须保持 Replay 安全,必要时继续使用 Patching 等兼容手段。若 Workflow 的寿命远长于版本保留周期,就不要无期限依赖 Pinned,应设计 Auto-Upgrade 或明确的 Continue-As-New 升级边界。

配置一个可识别的版本化 Worker
下面的 Go 程序连接默认本地 Temporal 地址,注册一个 Workflow 与 Activity,并把 Worker 注册为 payments-worker Deployment 的某个 Build ID。运行前要有可连接的 Temporal Service,并把 TEMPORAL_WORKER_BUILD_ID 设置为本次不可变构建标识。自托管环境至少应满足 Server 1.29.1、Temporal CLI 1.4.1 与 Go SDK 1.35.0。
package main
import (
"context"
"log"
"os"
"time"
"go.temporal.io/sdk/client"
"go.temporal.io/sdk/worker"
"go.temporal.io/sdk/workflow"
)
func PaymentWorkflow(ctx workflow.Context, amount int) error {
// Workflow 只保存确定性编排逻辑,外部副作用交给 Activity。
ctx = workflow.WithActivityOptions(ctx, workflow.ActivityOptions{
StartToCloseTimeout: time.Minute,
})
var receipt string
return workflow.ExecuteActivity(ctx, ChargeCard, amount).Get(ctx, &receipt)
}
func ChargeCard(context.Context, int) (string, error) {
return "charged", nil
}
func main() {
c, err := client.Dial(client.Options{})
if err != nil {
log.Fatal(err)
}
defer c.Close()
// Build ID 必须对应不可变构建,发布后不要复用到另一份代码。
buildID := os.Getenv("TEMPORAL_WORKER_BUILD_ID")
if buildID == "" {
log.Fatal("TEMPORAL_WORKER_BUILD_ID is required")
}
w := worker.New(c, "payments", worker.Options{
DeploymentOptions: worker.DeploymentOptions{
UseVersioning: true,
Version: worker.WorkerDeploymentVersion{
DeploymentName: "payments-worker",
BuildID: buildID,
},
DefaultVersioningBehavior: workflow.VersioningBehaviorUnspecified,
},
})
// 显式给 Workflow Type 选择 Pinned,避免用全局默认掩盖版本策略。
w.RegisterWorkflowWithOptions(PaymentWorkflow, workflow.RegisterOptions{
VersioningBehavior: workflow.VersioningBehaviorPinned,
})
w.RegisterActivity(ChargeCard)
log.Printf("starting deployment=payments-worker build=%s", buildID)
if err := w.Run(worker.InterruptCh()); err != nil {
log.Fatal(err)
}
}预期输出
<TIME> starting deployment=payments-worker build=<ID>进程会继续长轮询 Task Queue,不会在打印后自动退出。此时该 Version 已被 Temporal 识别,但一个新 Version 在成为 Current 或 Ramping 前不应直接承接正常生产流量。
渐进放量并完成切换
先确认新版本 Worker 正在轮询,再把它设置为小比例 Ramping。观察业务错误、Workflow Task 失败、非确定性错误、Schedule-to-Start 延迟和 Worker 资源使用,稳定后再逐级提高比例。
temporal worker deployment set-ramping-version \
--deployment-name payments-worker \
--build-id <ID> \
--percentage 5 \
--yes
temporal worker deployment describe-version \
--deployment-name payments-worker \
--build-id <ID>预期结果
Worker Deployment Version:
Version payments-worker.<ID>
RampPercentage 5完整输出还会包含创建时间、路由变更时间、Task Queue 等信息;关键是同一个 Deployment 下的该 Build ID 已显示 RampPercentage 为 5。不要只看 Pod/进程“已启动”,因为 Worker 存活不等于版本路由已经生效。
验证通过后可以把比例逐步提升;最终使用 temporal worker deployment set-current-version --deployment-name payments-worker --build-id <ID> 将它设为 Current。切换完成后,新启动的 Workflow 默认进入新的 Current,旧的 Pinned Workflow 仍由它们原先的版本处理。
回滚与旧版本下线
如果问题发生在 Ramping 阶段,先把坏版本的 ramp 降到 0,或用 --delete 移除 Ramping Version;如果坏版本已经成为 Current,就把 Current 指回上一个健康 Build ID。这个操作可以快速阻止新的 Workflow 和需要升级的流量继续落到坏版本,但不会自动迁走已经 Pinned 到坏版本的执行。
因此回滚时不要立刻把坏版本 Worker 缩到 0。先确认是否仍有 Pinned Workflow 依赖它;需要迁移这些执行时,应使用经过 Replay 与兼容性验证的恢复方案,而不是靠“切回 Current”假定它们会自动换版本。
旧 Version 离开 Current/Ramping 后,如果仍有打开的 Pinned Workflow,会进入 Draining;等这些执行结束后变为 Drained。到 Drained 再停止旧 Worker 最稳妥。若系统仍会对已关闭的 Pinned Workflow 发 Query,还要把这类查询需求纳入下线判断。