企业官网建设流程全解析

Cloudflare Durable Objects 设计模式实战：从限流、分片到实时协作的完整实现指南

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

导读

本文基于本仓库skills/.curated/cloudflare-deploy/references/durable-objects/patterns.md的权威内容，系统梳理 Cloudflare Durable Objects（DO）在生产环境中高频使用的设计模式：分布式限流、分布式锁、高吞吐分片、WebSocket 实时协作、会话管理、Alarm 事件调度等。你将学会按业务诉求选择正确模式与 ID 策略、在 RPC 与 fetch() 两种调用方式之间做决策，并掌握如何在 WebSocket Hibernation（休眠）与单 Alarm 限制下写出状态可靠、可水平扩展的 Worker 应用。

本文为“知识型”技能参考文档，所有代码示例可直接用于基于cloudflare:workers的 TypeScript Worker 项目。配套深度资料见同目录的 README、API、Configuration 与 Gotchas。

一、模式选型：先想清楚“你需要什么”

Durable Objects 的核心价值在于：每个实例全局唯一、自带强一致性的本地存储、由平台自动放置到首个请求附近，并且单线程串行处理请求（天然消除竞态条件）。但单实例能力有限（约 1K req/s 吞吐上限、每实例仅 1 个 Alarm），因此几乎所有生产模式都围绕“把合适的工作分给合适的 DO 实例”展开。

patterns.md 开篇用一张决策表回答了“什么时候用哪种模式”：

选型逻辑很清晰：需要“协调”的场景（限流、锁、会话）用确定性的idFromName()，让同一标识符永远落在同一个 DO 实例上；需要“分摊吞吐”的场景（分片）用随机或哈希 ID，把负载均匀打散到多个实例。这一决策树与 README 的 Decision Trees 中的“What do you need?”分支完全一致。

二、调用方式：RPC 还是 fetch()？

在动手写模式之前，先决定 Worker 如何调用 DO 实例的方法。patterns.md 给出了明确对比：

• RPC（推荐，新项目默认）：要求compatibility_date ≥ 2024-04-03，类型安全、调用简单，直接在 stub 上调用 DO 的类方法。
• fetch()（传统方式）：走 HTTP 语义，适合需要请求头/状态码、需要把请求代理给 DO、或兼容旧项目的场景。

两种调用方式的等价写法如下：

const count = await stub.increment(); // RPC：直接调用方法 const count = await (await stub.fetch(req)).json(); // fetch()：构造 Request 并解析响应

从 README 的决策树可以看到更细的取舍规则：

├─ 新项目 + compat ≥2024-04-03 → RPC（类型安全、更简单） ├─ 需要 HTTP 语义（请求头、状态码） → fetch() ├─ 需要把请求代理给 DO → fetch() └─ 兼容旧项目 → fetch()

提示：如果你的compatibility_date低于 2024-04-03，RPC 调用会报 “RPC Method Not Found” 错误。这是 Gotchas 文档 中列出的常见错误之一，解决办法是升级compatibility_date或退回 fetch()。

三、高吞吐模式：Sharding 分片

单实例 DO 的吞吐软上限约为1K req/s，这是 Gotchas 文档的限制表中反复强调的约束。当业务需要更高吞吐时，必须把请求分片到多个 DO 实例。

3.1 分片实现

patterns.md 给出的典型实现：在 Worker 入口处根据业务键（如用户 ID）计算哈希，再取模映射到 N 个分片之一，最后转发给对应 DO：

export default { async fetch(req: Request, env: Env): Promise<Response> { const userId = new URL(req.url).searchParams.get("user"); const hash = hashCode(userId) % 100; // 100 个分片 const id = env.COUNTER.idFromName(`shard:${hash}`); return env.COUNTER.get(id).fetch(req); } }; function hashCode(str: string): number { let hash = 0; for (let i = 0; i < str.length; i++) hash = ((hash << 5) - hash) + str.charCodeAt(i); return Math.abs(hash); }

3.2 三个关键决策

patterns.md 明确列出了分片设计时必须回答的三个问题：

1. 分片数量：典型范围 10～1000。文档建议从 100 开始，先测量再调整。分片数越大，单实例压力越小，但实例数量和管理成本也越高。
2. 分片键：用户 ID、IP、会话等。必须能均匀分布，因此要用哈希而不是直接取模——真实业务键往往有倾斜（如热门用户），哈希可打散热点。
3. 聚合方式：分片后跨实例的统计、排行等数据需要聚合，可引入Coordinator DO（协调者实例）或外部系统（D1、R2）完成汇总。

分片与 ID 策略的关系在 API 文档的 ID Generation 一节中有印证：idFromName()用于确定性的命名协调（限流、锁），newUniqueId()生成随机 ID 用于分片高吞吐负载，idFromString()则用于从既有 ID 还原实例。patterns.md 的分片示例使用idFromName(shard:${hash})，既保证同一用户始终命中同一分片，又通过哈希把用户均匀铺到 100 个分片。

注意：当单实例出现 “Durable Object Overloaded（503 错误）”时，Gotchas 文档给出的标准解法就是分片，印证了 1K req/s 软上限的存在。

四、Rate Limiting：基于 SQLite 的按用户/IP 限流

由于 DO 单线程串行处理请求，同一 DO 内的限流判断天然无竞态。patterns.md 用 SQLite 存储请求记录并实现滑动窗口限流：

async checkLimit(key: string, limit: number, windowMs: number): Promise<boolean> { const req = this.ctx.storage.sql.exec( "SELECT COUNT(*) as count FROM requests WHERE key = ? AND timestamp > ?", key, Date.now() - windowMs ).one(); if (req.count >= limit) return false; this.ctx.storage.sql.exec( "INSERT INTO requests (key, timestamp) VALUES (?, ?)", key, Date.now() ); return true; }

要点解读：

• 窗口判断：timestamp > Date.now() - windowMs统计的是窗口内的请求数，实现滑动窗口语义；limit与windowMs共同决定限流阈值。
• 原子性：由于 DO 单线程，同一实例上的 SELECT + INSERT 不会被其他请求打断（但注意：如果存在await屈服点，仍可能交错，详见下文“竞态”讨论）。
• 落库原因：DO 会休眠/驱逐，内存计数不可靠，请求记录必须持久化到存储中（Gotchas 文档明确指出休眠会清空内存状态）。

选型上，限流场景用idFromName(identifier)，identifier 通常就是用户 ID 或 IP——这保证了同一用户的请求永远落在同一个 DO 实例上，从而共享同一份计数。

五、Distributed Lock：用 Alarm 兜底的互斥锁

多实例并发操作同一资源时，可以用 DO 实现分布式锁。patterns.md 的实现非常精妙——用 Alarm 作为锁的自动超时释放机制：

private held = false; async acquire(timeoutMs = 5000): Promise<boolean> { if (this.held) return false; this.held = true; await this.ctx.storage.setAlarm(Date.now() + timeoutMs); // 超时自动释放 return true; } async release() { this.held = false; await this.ctx.storage.deleteAlarm(); // 手动释放并取消 Alarm } async alarm() { this.held = false; } // 超时自动释放

设计亮点：

• 非重入：acquire()在held已为 true 时直接返回 false，保证互斥。
• 防死锁：持锁方崩溃或失联时，Alarm 会在timeoutMs后触发alarm()自动释放锁，避免永久锁死。这正是 README 的 Rules 中 “One alarm per DO” 约束下的正确用法——锁本身只占 1 个 Alarm。
• 可靠性：Alarm 是持久化调度（API 文档的 Alarms 一节说明 Alarm 在 DO 被驱逐/重启后依然生效，失败还会自动重试），因此超时释放机制不会因实例驱逐而失效。

需要注意的是，this.held是内存状态，DO 休眠会清空它；对于关键场景，锁的持有状态最好同时写入存储（如 SQLite），并以 Alarm 作为兜底。

六、Hibernation-Aware：让 WebSocket 协作“休眠后不丢状态”

WebSocket Hibernation 是 DO 的招牌能力：连接保持打开但实例进入休眠，零计算、零成本。代价是休眠时内存被清空。因此凡是在休眠后还需要使用的数据，都必须显式持久化。patterns.md 给出了标准解法——用serializeAttachment()保存连接元数据，用存储保存业务状态：

async fetch(req: Request): Promise<Response> { const [client, server] = Object.values(new WebSocketPair()); const userId = new URL(req.url).searchParams.get("user"); server.serializeAttachment({ userId }); // 休眠后仍可恢复 this.ctx.acceptWebSocket(server, ["room:lobby"]); server.send(JSON.stringify({ type: "init", state: this.ctx.storage.kv.get("state") })); return new Response(null, { status: 101, webSocket: client }); } async webSocketMessage(ws: WebSocket, msg: string) { const { userId } = ws.deserializeAttachment(); // 唤醒后恢复元数据 const state = this.ctx.storage.kv.get("state") || {}; state[userId] = JSON.parse(msg); this.ctx.storage.kv.put("state", state); for (const c of this.ctx.getWebSockets("room:lobby")) c.send(msg); }

关键 API 与语义（与 API 文档的 WebSocket Hibernation 一节一致）：

• ctx.acceptWebSocket(server, tags?)：接收 WebSocket 并启用休眠，第二个参数是分组标签（如"room:lobby"），用于定向广播。
• serializeAttachment() / deserializeAttachment()：连接级元数据的持久化通道，休眠后依然存活；数据必须可 JSON 序列化且尽量小（Gotchas 文档的 Hibernation Caveats 明确提示 attachment 有大小约束）。
• ctx.getWebSockets(tag?)：按标签获取连接列表，实现“房间内广播”。
• ctx.storage.kv.get/put：业务状态（如文档内容、在线用户列表）必须落存储，因为休眠会清空内存。

反模式警示：Gotchas 文档 给出了一个经典反例——把userCount存在类的私有字段里，休眠唤醒后计数归零。正确做法是读写this.ctx.storage.kv。

七、Real-time Collaboration：实时协作与重连处理

7.1 广播核心逻辑

在协作场景（如多人编辑、聊天室）中，DO 的角色是“房间”：接收消息、持久化、向房间内所有其他连接广播：

async webSocketMessage(ws: WebSocket, msg: string) { const data = JSON.parse(msg); this.ctx.storage.kv.put("doc", data.content); // 先持久化 for (const c of this.ctx.getWebSockets()) if (c !== ws) c.send(msg); // 再广播（跳过发送者） }

配合前面的idFromName(room)策略，每个房间一个 DO 实例，天然实现房间隔离与广播。

7.2 客户端：指数退避重连

网络抖动时客户端应自动重连，并采用指数退避避免重连风暴：

class ResilientWS { private delay = 1000; connect(url: string) { const ws = new WebSocket(url); ws.onclose = () => setTimeout(() => { this.connect(url); this.delay = Math.min(this.delay * 2, 30000); // 1s → 2s → 4s … 封顶 30s }, this.delay); } }

退避逻辑：初始 1 秒，每次失败翻倍，最多 30 秒封顶。

7.3 服务端：断开清理

服务端在webSocketClose中做清理——更新在线状态并广播用户离开事件：

async webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean) { const { userId } = ws.deserializeAttachment(); this.ctx.storage.sql.exec("UPDATE users SET online = false WHERE id = ?", userId); for (const c of this.ctx.getWebSockets()) c.send(JSON.stringify({ type: "user_left", userId })); }

（API 文档还列出了可选的webSocketError处理器，用于连接异常时的兜底处理。）

八、Session Management：带过期清理的会话存储

会话天然适合 DO：idFromName(sessionId)保证同一会话永远路由到同一实例。patterns.md 用 SQLite 表 + Alarm 实现“创建会话 → 校验会话 → 到期批量清理”的完整闭环：

async createSession(userId: string, data: object): Promise<string> { const id = crypto.randomUUID(), exp = Date.now() + 86400000; // 默认 24h 过期 this.ctx.storage.sql.exec( "INSERT INTO sessions VALUES (?, ?, ?, ?)", id, userId, JSON.stringify(data), exp ); await this.ctx.storage.setAlarm(exp); // 到期触发清理 return id; } async getSession(id: string): Promise<object | null> { const row = this.ctx.storage.sql.exec( "SELECT data FROM sessions WHERE id = ? AND expires_at > ?", id, Date.now() ).one(); return row ? JSON.parse(row.data) : null; } async alarm() { this.ctx.storage.sql.exec("DELETE FROM sessions WHERE expires_at <= ?", Date.now()); }

要点：

• 校验与过期一体：getSession在 SQL 层同时过滤expires_at > now，过期会话直接查不到，无需额外判断。
• 清理策略：Alarm 触发时批量删除所有已过期会话，避免逐条清理。
• 模式局限性：这个实现每个会话一个 DO，适合会话量可控的场景；如果会话量极大，可退化为“会话数据存 D1/KV，DO 只做协调”的混合方案。

九、Multiple Events：单 Alarm 调度多个事件（队列模式）

DO 每实例只能有一个 Alarm（这是 README 的 Rules 与 API 文档反复强调的硬限制）。需要调度多个定时任务时，patterns.md 给出了“事件队列”模式：把事件写进存储，用最早事件的时间设置 Alarm，Alarm 触发时处理所有到期事件并重排下一个 Alarm：

async scheduleEvent(id: string, runAt: number) { await this.ctx.storage.put(`event:${id}`, { id, runAt }); const curr = await this.ctx.storage.getAlarm(); if (!curr || runAt < curr) await this.ctx.storage.setAlarm(runAt); // 只在更早时更新 Alarm } async alarm() { const events = await this.ctx.storage.list({ prefix: "event:" }), now = Date.now(); let next = null; for (const [key, ev] of events) { if (ev.runAt <= now) { await this.processEvent(ev); // 处理到期事件 await this.ctx.storage.delete(key); // 处理后删除 } else if (!next || ev.runAt < next) next = ev.runAt; // 记录最近的下一个事件 } if (next) await this.ctx.storage.setAlarm(next); // 重新排定 Alarm }

设计要点：

• “只提前、不延后”的 Alarm 更新策略：只有新事件的runAt早于当前 Alarm 时才调用setAlarm()（它会覆盖已有 Alarm），避免频繁改写。
• 滚动调度：每次alarm()处理完到期事件后，用剩余事件中最早的runAt重新设置 Alarm，实现“一个 Alarm 驱动 N 个任务”。
• 可靠性：API 文档说明 Alarm 在 DO 驱逐后依然可靠、失败自动重试，但不保证恰好一次，因此processEvent需要幂等设计。

十、Graceful Cleanup：用 waitUntil 延迟清理

当响应已经可以返回、但还有收尾工作（清理旧数据、写日志）需要完成后，用ctx.waitUntil()把异步任务挂到请求生命周期之外：

async myMethod() { const response = { success: true }; this.ctx.waitUntil( this.ctx.storage.sql.exec("DELETE FROM old_data WHERE timestamp < ?", cutoff) ); return response; // 响应立即返回，清理在后台完成 }

这与 API 文档的 Concurrency Control 中的分工一致：

• waitUntil()：响应发送后的后台工作（清理、日志、非关键任务）。
• blockConcurrencyWhile()：初始化、迁移、关键状态建立时的临界区——它会阻塞其他所有请求直到回调完成，避免初始化期间的竞态。这是 Gotchas 文档 针对“单线程下仍有竞态”问题的官方解法之一（await是屈服点，异步操作之间可能交错执行）。

十一、Best Practices：五大维度速查

patterns.md 在文末给出了生产环境的最佳实践清单，这里逐条展开：

补充两条易被忽略的硬性约束（详见 Gotchas 限制表）：

• 存储配额：单 DO 的 SQLite 存储上限 10 GB；KV 单条键值上限 2 MB。
• CPU 时间：单请求默认 30s，可在 wrangler.jsonc 中通过limits.cpu_ms调到最高 300s。

十二、快速落地：从配置到部署

以上模式都依赖正确的 wrangler 配置。最小可用配置（来自 Configuration 文档）：

{ "name": "my-worker", "main": "src/index.ts", "compatibility_date": "2025-01-01", // ≥2024-04-03 才能用 RPC "durable_objects": { "bindings": [ { "name": "MY_DO", "class_name": "MyDO" } ] }, "migrations": [ { "tag": "v1", "new_sqlite_classes": ["MyDO"] } // 优先 SQLite 后端 ] }

开发与部署命令（Configuration 文档的 Commands 一节）：

npx wrangler dev # 本地开发（含 DO） npx wrangler dev --remote # 联调生产 DO npx wrangler deploy # 部署并自动应用迁移 npx wrangler deploy --dry-run # 仅校验迁移，不真正部署 npx wrangler durable-objects list # 列出命名空间 npx wrangler durable-objects info <namespace> <id> # 检查指定 DO

两个部署前必读的迁移规则：

1. 迁移无回滚：一旦部署无法回退，务必先--dry-run验证（Configuration 与 Gotchas 均有明确警告）。
2. deleted_classes会立即销毁全部数据且不可逆：需要移动数据时改用transferred_classes。

十三、深入阅读

本文是durable-objects参考目录中 patterns 的完整展开，同目录及关联目录提供更底层的内容：

• durable-objects/README.md — DO 核心概念、生命周期状态、规则与决策树
• durable-objects/api.md — DurableObjectState 上下文方法、Alarm 与 WebSocket Hibernation 完整 API
• durable-objects/configuration.md — wrangler.jsonc 绑定、迁移、环境隔离、jurisdiction 配置
• durable-objects/gotchas.md — 常见错误、限制对照表、Hibernation 注意事项
• do-storage/README.md — SQLite/KV 存储 API、事务与 PITR 深入指南

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills