autoskills 中的 Cloudflare Pulumi 架构模式:Workers、多环境与版本化部署实战指南
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 资源的核心原则,这些原则贯穿本文所有模式:
- 使用 API Token(而非旧版 API Key)鉴权;
accountId存放在 stack config 中;- 绑定(binding)名称必须在 IaC 与 Worker 代码间严格一致;
- ES Modules 使用
module: true; - 通过
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"一节一致):
Worker:版本容器,持有workerId,本身不承载流量;WorkerVersion:不可变的代码 + 配置快照,可共存多个版本(v1/v2);注意compatibilityDate在版本级声明;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 全栈应用的主要工程场景。