进阶 celld.dev 2026-10-11 10:08:47 · 44 阅读

第19章 Cloudflare Workflows:持久化函数与事件序列开发指南

文档:Workflows

Workflow 是一种持久化函数,按命名步骤、休眠和事件序列运行。celld 将每个实例作为一个 cell 运行。API 详情请参阅 Cloudflare Workflows 文档。

示例

下面的 Workflow 示例会抓取一个文档,并将持久化步骤的结果存储下来。

index.js

import { WorkflowEntrypoint } from "cloudflare:workers";

export class ReportBuilder extends WorkflowEntrypoint { async run(event, step) { // 已完成的步骤在 Workflow 恢复时会直接返回其存储的结果。 return await step.do("build report", async () => { const response = await fetch(event.payload.url); if (!response.ok) throw new Error(`source answered ${response.status}`); const text = await response.text(); return { bytes: text.length, lines: text.split("\n").length }; }); } }

export default { async fetch(request, env) { const url = new URL(request.url); const id = url.searchParams.get("id");

if (url.pathname === "/create") { const instance = await env.REPORTS.create({ params: { url: url.searchParams.get("url") ?? "https://example.com" }, }); return Response.json({ id: instance.id }); }

if (url.pathname === "/status" && id) { const instance = await env.REPORTS.get(id); return Response.json(await instance.status()); }

return new Response("Use /create?url=URL or /status?id=ID.", { status: 404, }); }, };

wrangler.jsonc

{ "name": "workflow", "main": "index.js", "compatibility_date": "2026-08-18", "workflows": [ { "binding": "REPORTS", "name": "report-builder", "class_name": "ReportBuilder" } ] }

API

类继承 WorkflowEntrypoint 并实现 run(event, step)。event.payload 存放参数,返回值会成为 status() 输出中的 output 字段。

step.do(name, callback) 运行一个持久化步骤,失败时会自动重试回调。 step.sleep(name, duration) 和 step.sleepUntil(name, timestamp) 会让实例暂停到指定时间点。 step.waitForEvent(name, options) 会让实例暂停,直到收到匹配的事件。 env.MY_WORKFLOW 的 create()、createBatch() 和 get(id) 用于创建或获取实例,deleteBatch() 可批量删除实例。 实例提供 status()、sendEvent()、pause()、resume()、restart()、terminate() 和 delete() 方法。

重放(Replay)

实例每取得一次进展,celld 都会从第一行重新调用 run()。已完成的步骤会直接返回其存储的结果,不会再次执行回调。因此,步骤回调之外的所有代码在每次重放时都会重新运行。按照 Workflows 的规则要求,把每个子请求、每个副作用、以及每个需要保持稳定的值都放进 step.do() 回调里。如果某个步骤的结果在节点故障前没有提交,该步骤会重新运行,所以步骤回调必须能容忍重复执行。

run() 可以 await 非步骤的工作,但重放无法恢复这样的 await。如果这类工作让 run() 挂起超过 60 秒,且期间没有任何步骤在运行或等待,celld 会将该实例标记为失败。

休眠、事件与重试

step.waitForEvent() 默认 24 小时超时。在实例到达等待步骤之前到达的事件会被缓存。休眠、等待和待重试都会各自存储截止时间,因此崩溃或缓慢的重放不会移动截止时间。status() 对这三种情况都会报告为 waiting。

处于等待状态的实例不占用 isolate。当下一个截止时间超出 near-alarm 驻留窗口时,其 cell 会休眠。该窗口默认为一小时,可通过 CELLD_ALARM_RESIDENT_MS 调整。

调用 step.do() 时如果不传 retries 对象,则使用 Cloudflare 的默认重试配置:重试 5 次,延迟 10 秒,指数退避,单次尝试超时 10 分钟。

celld 不限制并发实例的数量,实际由 Fleet 内存和驻留 cell 上限约束。

与 Cloudflare 的差异

celld 默认保留成功或失败的实例 30 天,retention 选项中的每个时长最多为 30 天。 locationHint 接受 Cloudflare 的取值,但 cell 位置由 fleet 归属决定。 非步骤工作的挂起时间不能超过 60 秒。 步骤结果、事件负载和 workflow 参数各有 1 MiB 的大小限制。 不支持 Rollback、敏感步骤结果和 ReadableStream 类型的步骤结果。 workflows 入口不能带有 schedules、limits,也不能通过 script_name 指向其他脚本。 不支持 Workflows REST API 和 wrangler workflows 命令,请通过 binding 来操作实例。

Cloudflare 兼容性页面列出了运行时 API 和不支持的服务。

本篇用到的工具

评论 (0)