autoskills 中的 Cloudflare Pulumi 架构模式:Workers、多环境与版本化部署实战指南

原创2026-10-09 13:34:101,923 阅读

autoskills 中的 Cloudflare Pulumi 架构模式:Workers、多环境与版本化部署实战指南

本文基于 autoskills 技能仓库中 Cloudflare 技能包下的 Pulumi 架构模式参考文档(patterns.md),系统讲解如何使用 @pulumi/cloudflare 提供程序(v6.x)以基础设施即代码(IaC)方式构建 Cloudflare Workers 生态应用:从组件资源封装、KV/D1/R2/Queue 全栈绑定、多环境隔离,到 v6.x 版本化流量切分与"构建—部署"流水线编排。读完本文,你可以直接用 Pulumi 声明式地管理 Workers 全栈资源,掌握避免配置漂移、强制更新检测失效等常见陷阱的写法。

背景:为什么用 Pulumi 管理 Cloudflare 资源

autoskills 的 Cloudflare 技能将 IaC 作为独立产品域组织,Pulumi 参考目录下的四份文档(configuration、patterns、api、gotchas)构成完整知识体系。按其 README 的读法约定,patterns.md 的定位是"构建复杂应用、遵循最佳实践"阶段的进阶文档。

该 README 同时给出了 Pulumi 管理 Cloudflare 资源的核心原则,这些原则贯穿本文所有模式:

  1. 使用 API Token(而非旧版 API Key)鉴权;
  2. accountId 存放在 stack config 中;
  3. 绑定(binding)名称必须在 IaC 与 Worker 代码间严格一致;
  4. ES Modules 使用 module: true;
  5. 通过 compatibilityDate 锁定运行时行为。

各语言 SDK 对应关系:TypeScript/JS 为 @pulumi/cloudflare,Python 为 pulumi-cloudflare,Go 为 github.com/pulumi/pulumi-cloudflare/sdk/v6/go/cloudflare,.NET 为 Pulumi.Cloudflare,当前参考文档面向 v6.x 版本。

组件资源模式(Component Resources)

当 KV、Worker、自定义域名需要作为一个整体单元创建时,可以继承 pulumi.ComponentResource 将其封装为组合资源,避免在多个 Stack 中重复编写相同的资源组合:

class WorkerApp extends pulumi.ComponentResource {
    constructor(name: string, args: WorkerAppArgs, opts?) {
        super("custom:cloudflare:WorkerApp", name, {}, opts);
        const defaultOpts = {parent: this};

        this.kv = new cloudflare.WorkersKvNamespace(`${name}-kv`, {accountId: args.accountId, title: `${name}-kv`}, defaultOpts);
        this.worker = new cloudflare.WorkerScript(`${name}-worker`, {
            accountId: args.accountId, name: `${name}-worker`, content: args.workerCode,
            module: true, kvNamespaceBindings: [{name: "KV", namespaceId: this.kv.id}],
        }, defaultOpts);
        this.domain = new cloudflare.WorkersDomain(`${name}-domain`, {
            accountId: args.accountId, hostname: args.domain, service: this.worker.name,
        }, defaultOpts);
    }
}

三个关键点:

  • 统一 parent:所有子资源通过 defaultOpts = {parent: this} 挂到组件之下,生命周期随组件销毁而销毁,依赖关系在 Pulumi 图中自动推导;
  • 依赖自动建立:kvNamespaceBindings 引用了 this.kv.id,Pulumi 通过 output 引用隐式建立 Worker 对 KV 的依赖(这一"隐式依赖"机制在 api.md 中另有专门说明);
  • 域名挂接 Worker:WorkersDomain 的 service 字段指向 this.worker.name,将自定义域名流量直接路由到该 Worker。注意按 configuration.md 的完整示例,WorkersDomain 通常需要 zoneId(DNS/域类资源需要 zoneId 而非 accountId),组件内可按需传入。

全栈 Worker 应用:KV + D1 + R2 绑定

生产级 Worker 往往同时依赖 KV 缓存、D1 数据库和 R2 存储桶。三种资源一次性声明并绑定到同一个 Worker:

const kv = new cloudflare.WorkersKvNamespace("cache", {accountId, title: "api-cache"});
const db = new cloudflare.D1Database("db", {accountId, name: "app-database"});
const bucket = new cloudflare.R2Bucket("assets", {accountId, name: "app-assets"});

const apiWorker = new cloudflare.WorkerScript("api", {
    accountId, name: "api-worker", content: fs.readFileSync("./dist/api.js", "utf8"),
    module: true, kvNamespaceBindings: [{name: "CACHE", namespaceId: kv.id}],
    d1DatabaseBindings: [{name: "DB", databaseId: db.id}],
    r2BucketBindings: [{name: "ASSETS", bucketName: bucket.name}],
});

注意每种绑定引用的 ID 来源不同,这是容易出错的地方:

绑定类型 属性 引用来源 说明
KV namespaceId kv.id 用 KV 的 id(api.md 中 import 命令也用 <namespace_id> 作标识)
D1 databaseId db.id 用 D1 的 id
R2 bucketName bucket.name 用 R2 的 name(R2 无独立 id 语义,导入格式为 <account_id>/<bucket_name>)

Worker 代码侧通过 env.CACHE、env.DB、env.ASSETS 访问对应资源;绑定名大小写敏感,Pulumi 侧声明与代码侧引用必须完全一致,否则会报 env.MY_KV is undefined(见 gotchas.md 的"Binding name mismatch"一节)。

另外,content 使用 fs.readFileSync("./dist/api.js", "utf8") 读取的是已构建产物——这是全文反复强调的前提:Pulumi 不做打包,上传什么就部署什么(详见后文"Build + Deploy"与陷阱对照)。

多环境部署(Multi-Environment Setup)

利用 pulumi.getStack() 让同一份代码在不同 stack(如 dev/staging/prod)下生成带环境标识的资源:

const stack = pulumi.getStack();
const worker = new cloudflare.WorkerScript(`worker-${stack}`, {
    accountId, name: `my-worker-${stack}`, content: code,
    plainTextBindings: [{name: "ENVIRONMENT", text: stack}],
});

这一模式的设计意图有三层:

  • 资源隔离:my-worker-${stack} 使每个环境在 Cloudflare 账户下是独立的 Worker,互不干扰,也避免环境间误更新;
  • 运行时感知:通过 plainTextBindings 把 stack 名注入 env.ENVIRONMENT,Worker 代码可据此切换行为(日志级别、下游端点等);
  • Pulumi 侧配合:accountId 等环境差异通过 Pulumi.<stack>.yaml 承载,例如 README 给出的堆栈配置:
config:
  cloudflare:accountId: "abc123..."

代码中则以 new pulumi.Config("cloudflare").require("accountId") 读取。密钥类配置应使用 pulumi config set --secret 加密存放到 state 中(gotchas.md 最佳实践第 6 条)。

基于 Queue 的异步处理

Queue 模式将"接收请求"与"处理耗时任务"拆到两个 Worker:生产者绑定队列用于投递,消费者配置消费参数并绑定输出存储:

const queue = new cloudflare.Queue("processing-queue", {accountId, name: "image-processing"});

// Producer: API receives requests
const apiWorker = new cloudflare.WorkerScript("api", {
    accountId, name: "api-worker", content: apiCode,
    queueBindings: [{name: "PROCESSING_QUEUE", queue: queue.id}],
});

// Consumer: Process async
const processorWorker = new cloudflare.WorkerScript("processor", {
    accountId, name: "processor-worker", content: processorCode,
    queueConsumers: [{queue: queue.name, maxBatchSize: 10, maxRetries: 3, maxWaitTimeMs: 5000}],
    r2BucketBindings: [{name: "OUTPUT_BUCKET", bucketName: outputBucket.name}],
});

消费端参数值得逐项理解(这些参数直接决定消费行为与成本):

  • maxBatchSize: 10 —— 单次投递批次的最大消息数,越大越省请求次数但单批处理越久;
  • maxRetries: 3 —— 失败重试次数上限,超过后消息进入死信路径;
  • maxWaitTimeMs: 5000 —— 消息最长滞留等待时间,影响端到端延迟上限。

典型场景是图像处理:API Worker 收到上传请求后向 PROCESSING_QUEUE 投递任务,processor Worker 批量消费、处理后写入 OUTPUT_BUCKET。配额方面,按 gotchas.md 的 Limits 表,Queue 每账户上限 10,000 个,免费档 1M ops/天。

微服务:Service Bindings

Worker 之间可通过 Service Bindings 以内部调用(不经过公网)相互通信,无需处理跨域与鉴权。以"API 服务调用 Auth 服务"为例:

const authWorker = new cloudflare.WorkerScript("auth", {accountId, name: "auth-service", content: authCode});
const apiWorker = new cloudflare.WorkerScript("api", {
    accountId, name: "api-service", content: apiCode,
    serviceBindings: [{name: "AUTH", service: authWorker.name}],
});

要点:

  • serviceBindings[].service 引用的是被调 Worker 的 name(authWorker.name)而非 id;
  • api-service 的 Worker 代码中通过 env.AUTH.fetch(request) 发起内部调用,请求在 Cloudflare 网络内直达 auth-service;
  • 由于 serviceBindings 依赖 authWorker 的 name,Pulumi 会自动建立部署顺序依赖。

configuration.md 给出的完整 WorkerScript 参数表还列出了 v6.x 新增的其他绑定族:secretTextBindings(加密注入)、analyticsEngineBindings、browserBinding(Browser Rendering)、aiBinding(Workers AI)、hyperdriveBindings 等,微服务组合时可据此扩展。

事件驱动架构(Event-Driven)

Queue 同样适合做事件总线:生产者只负责发布事件,多个消费者按各自职责订阅,天然解耦、可独立扩缩:

const eventQueue = new cloudflare.Queue("events", {accountId, name: "event-bus"});
const producer = new cloudflare.WorkerScript("producer", {
    accountId, name: "api-producer", content: producerCode,
    queueBindings: [{name: "EVENTS", queue: eventQueue.id}],
});
const consumer = new cloudflare.WorkerScript("consumer", {
    accountId, name: "email-consumer", content: consumerCode,
    queueConsumers: [{queue: eventQueue.name, maxBatchSize: 10}],
});

与上一节的"任务队列"模式对比可以看出同一套资源、不同语义:事件驱动关注"发生了什么"(如订单已创建 → 触发邮件、通知等多个消费者),而队列处理关注"谁来做耗时工作"。从源码结构看,两者在 Pulumi 侧的写法差异仅为 queueBindings(生产)与 queueConsumers(消费)的分属关系,一个 Queue 资源可以同时服务多个 consumer Worker,只需各自声明 queueConsumers 即可水平扩展消费能力。

v6.x 版本化部署:灰度 / 金丝雀 / 蓝绿

v6.x 提供细粒度流量切分能力,但需要三个资源协作(这是 gotchas.md 中"v6.x Worker versioning confusion"条目专门警告的点:只部署了 Worker 却收不到流量,往往就是因为缺了 Version 与 Deployment):

const worker = new cloudflare.Worker("api", {accountId, name: "api-worker"});
const v1 = new cloudflare.WorkerVersion("v1", {accountId, workerId: worker.id, content: fs.readFileSync("./dist/v1.js", "utf8"), compatibilityDate: "2025-01-01"});
const v2 = new cloudflare.WorkerVersion("v2", {accountId, workerId: worker.id, content: fs.readFileSync("./dist/v2.js", "utf8"), compatibilityDate: "2025-01-01"});

// Gradual rollout: 10% v2, 90% v1
const deployment = new cloudflare.WorkersDeployment("canary", {
    accountId, workerId: worker.id,
    versions: [{versionId: v2.id, percentage: 10}, {versionId: v1.id, percentage: 90}],
    kvNamespaceBindings: [{name: "MY_KV", namespaceId: kv.id}],
});

三资源的职责划分(与 api.md "v6.x Worker Versioning Resources"一节一致):

  1. Worker:版本容器,持有 workerId,本身不承载流量;
  2. WorkerVersion:不可变的代码 + 配置快照,可共存多个版本(v1/v2);注意 compatibilityDate 在版本级声明;
  3. WorkersDeployment:当前生效的部署,负责绑定关系(如 kvNamespaceBindings 在部署级而非版本级配置)与流量百分比切分。

上面的 versions: [{versionId: v2.id, percentage: 10}, {versionId: v1.id, percentage: 90}] 即实现了 10% 金丝雀;把 100% 切到 v2 即完成全量,回滚只需将 Deployment 指回 v1。文档同时明确使用边界:金丝雀发布、A/B 测试、蓝绿部署用三资源模式;大多数单版本应用直接使用 WorkerScript(其自带 auto-versioning),不要过度设计。

Wrangler.toml 生成:打通 IaC 与本地开发

Pulumi 不读取 wrangler.toml,而本地 wrangler dev 只认 wrangler.toml,两者天然存在配置漂移风险(gotchas.md 将其列为"wrangler.toml not consumed - Config drift"陷阱)。patterns.md 给出的方案是用 @pulumi/command 资源在部署流程中从 Pulumi 状态生成 wrangler.toml,使 Pulumi 成为唯一事实来源:

import * as command from "@pulumi/command";

const workerConfig = {
    name: "my-worker",
    compatibilityDate: "2025-01-01",
    compatibilityFlags: ["nodejs_compat"],
};

// Create resources
const kv = new cloudflare.WorkersKvNamespace("kv", {accountId, title: "my-kv"});
const db = new cloudflare.D1Database("db", {accountId, name: "my-db"});
const bucket = new cloudflare.R2Bucket("bucket", {accountId, name: "my-bucket"});

// Generate wrangler.toml after resources created
const wranglerGen = new command.local.Command("gen-wrangler", {
    create: pulumi.interpolate`cat > wrangler.toml <<EOF
name = "${workerConfig.name}"
main = "src/index.ts"
compatibility_date = "${workerConfig.compatibilityDate}"
compatibility_flags = ${JSON.stringify(workerConfig.compatibilityFlags)}

[[kv_namespaces]]
binding = "MY_KV"
id = "${kv.id}"

[[d1_databases]]
binding = "DB"
database_id = "${db.id}"
database_name = "${db.name}"

[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "${bucket.name}"
EOF`,
}, {dependsOn: [kv, db, bucket]});

// Deploy worker after wrangler.toml generated
const worker = new cloudflare.WorkerScript("worker", {
    accountId, name: workerConfig.name, content: code,
    compatibilityDate: workerConfig.compatibilityDate,
    compatibilityFlags: workerConfig.compatibilityFlags,
    kvNamespaceBindings: [{name: "MY_KV", namespaceId: kv.id}],
    d1DatabaseBindings: [{name: "DB", databaseId: db.id}],
    r2BucketBindings: [{name: "MY_BUCKET", bucketName: bucket.name}],
}, {dependsOn: [wranglerGen]});

实现要点:

  • pulumi.interpolate 回填真实 ID:heredoc 中插入的 ${kv.id}、${db.id} 是 Pulumi output 插值,在 pulumi up 时解析为云端的真实资源 ID,因此本地 wrangler dev 的绑定指向与生产完全一致;
  • 依赖链:dependsOn: [kv, db, bucket] 保证生成命令在资源创建之后执行(此时 ID 已可用),WorkerScript 再 dependsOn: [wranglerGen] 保证文件先落盘;
  • 文档标注的收益:wrangler dev 使用与生产相同的绑定;Pulumi 与本地开发之间无配置漂移;Pulumi 配置是唯一事实来源。若项目以 wrangler 为事实来源,文档也指出可以反向操作——在 Pulumi 中读取 wrangler.toml(Alternative 方向)。

Build + Deploy 模式

Pulumi 上传的正是你提供的字节内容,不会执行打包。正确做法是用 command.local.Command 先构建、再把产物读进 content:

import * as command from "@pulumi/command";
const build = new command.local.Command("build", {create: "npm run build", dir: "./worker"});
const worker = new cloudflare.WorkerScript("worker", {
    accountId, name: "my-worker",
    content: build.stdout.apply(() => fs.readFileSync("./worker/dist/index.js", "utf8")),
}, {dependsOn: [build]});

这里 build.stdout.apply(...) 的写法值得注意:apply 让内容读取延迟到构建命令真正完成之后执行,配合 dependsOn: [build] 形成"构建完成 → 读取产物 → 部署"的顺序保证。若跳过构建直接 content: fs.readFileSync("./src/index.ts") 上传原始 TypeScript/ESM 源码,Worker 会运行时报 "Cannot use import statement outside a module"——这正是 gotchas.md 中"No bundler/build step"条目的原始症状与解法。

Content SHA 模式:防止"无变更"误判

当代码改动仅涉及空白、注释,或产物哈希恰好相同时,Pulumi 可能判定"no changes"而跳过更新。一个廉价的规避手段是注入每次运行都变化的版本标记:

const version = Date.now().toString();
const worker = new cloudflare.WorkerScript("worker", {
    accountId, name: "my-worker", content: code,
    plainTextBindings: [{name: "VERSION", text: version}], // Forces deployment
});

原理:plainTextBindings 中加入了每次 pulumi up 都不同的时间戳值,资源参数必然变化,从而强制触发重新部署;同时 env.VERSION 还可作为运行时版本探针(日志中标注当前构建时点)。文档将其列为最佳实践第 5 条"Version Worker content"。若希望更精细地控制更新检测,可结合 api.md 的 Transform 模式或 output/export 机制做自定义处理。

模式选型速查与配套排查

综合 patterns.md 与配套文档,各模式的适用场景可以归纳为:

模式 适用场景 关键资源
Component Resources 多个 Stack 复用同一 Worker 组合 ComponentResource + 任意子资源
Full-Stack 单 Worker 依赖 KV/D1/R2 WorkerScript + 三类绑定
Multi-Environment dev/staging/prod 隔离 pulumi.getStack() + stack config
Queue Processing 耗时任务异步化 Queue + 生产/消费双 Worker
Service Bindings Worker 间内网调用 serviceBindings
Event-Driven 事件总线、多消费者解耦 Queue 作 event-bus
v6.x Versioned 金丝雀/蓝绿/A/B Worker + WorkerVersion + WorkersDeployment
Wrangler.toml Gen 消除 IaC 与本地开发漂移 command.local.Command + interpolate
Build + Deploy 产物构建与部署顺序 command.local.Command + dependsOn
Content SHA 强制更新、版本探针 plainTextBindings 时间戳

排查部署问题时,建议按 gotchas.md 的错误清单对号入座:API Token 权限不足(authentication error (10000),需授予 Account.Workers Scripts:Edit 等权限)、缺少 accountId(补入 Pulumi.<stack>.yaml)、D1 迁移不会随 pulumi up 自动执行(用 Command 资源 + dependsOn 显式跑 wrangler d1 execute)、pulumi import 后状态与代码不匹配(用 pulumi preview 核对)等。资源配额参考同文件的 Limits 表:Worker 脚本 10 MB(压缩后含依赖)、免费档 CPU 10ms/请求、KV 写 1000 ops/s 读 100k ops/s、D1 免费 10 个/账户各 5 GB、Queue 免费 1M ops/天。

小结

autoskills 的 Cloudflare Pulumi patterns 参考把"如何声明"与"如何编排"分离得相当清楚:单资源参数(各类绑定的属性来源、v6.x 新增绑定族)在 configuration.md 中,output/依赖/import/动态提供程序等 API 级能力在 api.md 中,而 patterns.md 提供的是把这些积木组装成可维护架构的 10 个即取即用的组合——从组件资源到灰度发布,从本地开发打通到强制更新,覆盖了用 @pulumi/cloudflare 构建生产级 Workers 全栈应用的主要工程场景。

登录后查看全文
autoskills