← 文章 / 科技资讯
vercel 8天前 · 2026-11-14 01:16:10 · 11 阅读

Workflow SDK 5:为生产环境而生

Workflow SDK 最初发布时的目标很简单:写普通的异步 JavaScript,其余交给 SDK 处理——它会让你的代码在崩溃、部署和长时间等待中持续运行。

workflows/welcome-user.ts
1import { sleep } from "workflow";2
3export async function welcomeUser(email) {4  "use workflow";5
6  const user = await createUser(email);7  await sendWelcomeEmail(user);8
9  // 等待期间即使发生崩溃或部署也能存活10  await sleep("3d");11  await sendCheckInEmail(user);12}

一个基础的持久化 workflow

去年,我们正式发布了这个功能,并带着 Vercel 一贯的顶级开发者体验。随后我们持续观察客户用它构建了什么。

在超过 40 亿次 step 执行和 7 亿次 run 之后,两种清晰的使用模式浮现出来。

  • 第一种是自动化:传统的工作流场景,比如数据迁移、订单处理、后台任务编排、订阅管理,以及 ETL 和数据管道。

  • 第二种是 agent 和 harness:Agent 运行成本高、耗时长,天然也需要持久化能力。

随着这些工作负载不断成熟,Workflow 也在同步演进。我们的优先级始终是安全性、可靠性和性能。

下面介绍 Workflow SDK 5 如何在这三方面做到更好。

Copy link to heading更安全的 workflow

Workflow 的事件日志会保存 step 的入参和返回值,以便 run 在崩溃或部署后能够恢复。这些数据可能包含敏感的客户信息、模型上下文、凭证以及工具调用结果。持久化这类数据必须有强有力的保护。

Workflow SDK 会对每个 payload 进行端到端加密,在数据离开你的代码之前就完成加密。Workflow 和 step 的输入输出、hook payload 以及流式数据都使用 AES-256-GCM 加密,且每次 run 使用独立密钥。启用加密后,任何 Workflow SDK 后端(包括 Vercel)都只能看到并存储密文。明文只会在你的部署环境或经过授权的可观测性工具中解密。

Copy link to heading在 Vercel 上零配置加密

在 Vercel 上,加密功能无需额外配置,也无需修改代码。每次运行使用的密钥源自限定于创建该次运行的 deployment 范围的密钥,因此某次运行只能解密自身的数据。你的工作流代码无需改动:

workflows/onboard-customer.ts
1export async function onboardCustomer(2  customer: Customer,3) {4  "use workflow";5
6  // 客户记录被加密存储7  // 在事件日志中8  const account = await createAccount(customer);9  await sendWelcomeEmail(account.email);10  return account.id;11}12
13async function createAccount(14  customer: Customer,15) {16  "use step";17
18  // ...在此处解密后传入,19  // 位于你的 deployment 内部20  return db.accounts.create(customer);21}

在不改变应用逻辑的前提下,Workflow 和 step 的 payload 均已加密。

由于 Vercel 默认管理密钥,可观测性得以维持。名称、耗时和状态始终可见;当你需要查看 payload 时,可在 dashboard 或 CLI 中解密。解密操作在你的浏览器或终端执行,遵循与项目环境变量相同的权限策略,且所有请求都会记录在团队的审计日志中。

# Payloads 显示为 🔒 Encryptednpx workflow inspect run <run-id>
# 若具备访问权限,可在本地解密npx workflow inspect run <run-id> --decrypt

检查加密 payload,并在具备授权访问的情况下本地解密。

Copy link to heading在自托管 Worlds 上进行加密

加密在 SDK 中实现,因此也可在自托管 Worlds 上保护 payload,防止其到达存储、队列或流之前泄露。

自定义 World 启用加密的方式是实现 getEncryptionKeyForRun() 并集成你的密钥管理。每次调用时,为同一次运行返回相同的 32 字节密钥,以便 SDK 能够加密新 payload 并在 replay 期间解密它们:

world.ts
1import type { World } from "@workflow/world";2
3type RunKeyProvider =4  World["getEncryptionKeyForRun"];5
6export const getEncryptionKeyForRun:7  RunKeyProvider = async (run) => {8    const runId =9      typeof run === "string" ? run : run.runId;10
11    // 每次:同一个 run 返回相同的 32 字节密钥,12    // 这样重放时才能解密13    return keyStore.getRunKey(runId);14  };

在自定义 World 中为每个 run 提供稳定的 32 字节加密密钥。

复制标题链接v5 的更多安全改进

跨 run 写入也做了封印处理。当代码恢复其他 run 的 hook、在其他 deployment 中启动 run,或写入从其他 run 转发过来的 stream 时,载荷会用目标 run 的公钥加密。写入方可以为该 run 加密,但读不到它已有的载荷。

你还可以限制敏感数据的存储时长。将 payload retention 设置为 experimental_retention: 0 后,run 一完成或失败,输入、输出和 stream 内容就会立即删除。run 的元数据在可观测性面板中仍然可见。

复制标题链接重新设计的 trace 查看器

重新设计的 trace 查看器让 run 更容易浏览,支持 span 搜索、缩放、小地图,以及开发时的本地检查。

Vercel 上真实 trace 查看器的交互式演示。点击 span 并按住 Alt 可查看时间差。

Run 属性是 v5 的新功能。它可以为 run 附加可搜索的上下文信息(比如订单 ID),然后据此查找 run。属性是明文存储的,所以不要放敏感信息。

复制标题链接覆盖每个区域的 Workflow

在 Workflow SDK 4 中,所有 run 都位于 iad1。即使项目部署到多个区域,每个 run 的事件日志、队列和 stream 也只存在一个区域里,其他区域的 step 记录进度时都得发起跨区域请求。

在 v5 中,我们将 Workflow 基础设施部署到了每个 Vercel Function 区域。每次运行都有自己所在的区域:其状态、队列分派和数据流都从运行发起的区域提供,避免了热路径上的跨区域往返。

默认情况下,运行会在启动它的函数所在区域开始。部署到多个区域后,每次运行都会保持在触发它的用户附近,无需额外配置:

app/api/checkout/route.ts
1import { start } from "workflow/api";2import { processOrder } from "@/workflows/process-order";3
4export async function POST(request: Request) {5  const order = await request.json();6
7  // 在提供此请求的区域中运行8  const run = await start(9    processOrder,10    [order],11  );12  return Response.json({ runId: run.runId });13}

在各自请求所在的区域启动订单工作流。

若要将运行放在其他位置,请向 start() 传递 region 参数。这样可以让工作流在数据库所在地运行,或者将客户数据保留在其必须所在的区域:

app/api/checkout/route.ts
1// 将此客户的运行数据保留在法兰克福2const run = await start(3  processOrder,4  [order],5  { region: "fra1" },6);

将订单工作流数据存储到法兰克福。

region 选项决定运行数据存储的位置。你的步骤运行在你应用部署的区域,因此若希望它们在该区域执行,请也将应用部署到那里。现有的 v4 运行仍保留在 iad1。

复制标题链接基础设施可靠性

区域隔离还能提高可靠性。某一区域的中断不会阻碍健康区域中新运行的启动。对于配置了 Vercel Function 故障转移 的项目,步骤可以在备用区域执行,同时继续使用该运行原本所属的主区域来管理状态。该状态会固定在主区域,不会在故障转移过程中迁移。

借助匿名遥测数据以及与众多客户的紧密合作,我们发现并修复了 Workflow 运行时中的数十个罕见 bug 和竞态条件。Workflow SDK 还能从更多类型的间歇性网络错误中自动恢复。 因此在 Workflow SDK 5 中,我们几乎没有观察到任何因平台或运行时 bug 导致的运行失败或卡住的情况。

Copy link to headingAgent 就绪的性能

在 Workflow SDK 4 中,每次步骤调用都要经过一次队列跳转来启动步骤,再经过一次来继续工作流。这对慢速后台自动化任务来说还可以接受,但会给开发者如今构建的 AI 工作负载带来额外延迟。

Agent 循环和 harness 可能包含数千个顺序事件、高吞吐量的 token 流、工具链和动态子 Agent。在这种规模下,每个步骤周边的网络和 CPU 开销就成了瓶颈。

在 Workflow SDK 5 中,我们重写了引擎的很大一部分,以尽量减少额外的队列跳转、不必要的网络请求和 CPU 开销。在所有测量的工作负载中,延迟和开销改善了 1.6 倍到 25 倍,同时保持了相同的开发者体验,也没有引入重大的破坏性变更。

下面的基准测试比较了 Vercel 上的 v5.2.0 和 v4.8.12。选择一项指标来查看 v5 与 v4 的对比,然后播放或拖动进度条查看讲解,了解每项基准测试的具体内容。

Workflow SDK 5 包含数百项性能优化来实现这一目标。以下是这些数字背后的一些主要改动:

更少的队列跳转

在 v4 中,每个步骤都要通过队列交还执行权。在 v5 中,一次调用可以内联执行多个步骤(包括并行步骤),直到遇到等待、hook 或临近超时才让出执行权。

运行时还避免了不必要的持久化往返,并将步骤创建合并到执行过程中。更少的队列和网络请求意味着更少的 CPU 开销和更低的运行时开销。在一个五步基准测试中,p75 步骤间开销从 618 ms 降到了 109 ms。

增量重放

在一个 1,020 步的基准测试中,v4 的 p75 开销会随着事件日志的增长而增加:重放完整事件历史所需的时间与其大小成正比。在最后采样的区间里,开销达到了 1,748 ms,而在 v5.2.0 上仅为 70 ms。完成全部 1,020 步的中位时间从 21.0 分钟降到了 3.0 分钟。

各步骤间的延迟差距很小。图示为 p75 分位数的步间开销,数值越低越好。所有条形图共用 0–1,800 ms 的刻度。

WebSocket 流式传输

持久化机制不应导致流式响应落后于其生产者。在 Vercel World 上,v5.2.0 采用 WebSocket 处理写入

评论 (0)