服务注册与分布式协调 / 系统课时

使用 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 Deployment Versioning 的流量路由与版本生命周期

配置一个可识别的版本化 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。

go
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)
	}
}

预期输出

text
<TIME> starting deployment=payments-worker build=<ID>

进程会继续长轮询 Task Queue,不会在打印后自动退出。此时该 Version 已被 Temporal 识别,但一个新 Version 在成为 Current 或 Ramping 前不应直接承接正常生产流量。

渐进放量并完成切换

先确认新版本 Worker 正在轮询,再把它设置为小比例 Ramping。观察业务错误、Workflow Task 失败、非确定性错误、Schedule-to-Start 延迟和 Worker 资源使用,稳定后再逐级提高比例。

bash
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>

预期结果

text
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,还要把这类查询需求纳入下线判断。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 Worker Deployment Versioning

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通