blog.dopana

返回

Durable Objects(DO)是 Cloudflare Workers 的有状态协同解决方案。每个 DO 拥有全球唯一的运行实例 —— 状态持久存在,并具备强一致性保证。

Durable Object(全球唯一实例)持久化存储无状态 Workers(全球边缘节点)RAM(内存状态)RAM(内存状态)"所有相同 ID 的请求路由至单一实例""强一致性(杜绝竞态条件)""状态持续驻留"Worker 东京Worker 伦敦Worker 美国ID: 'user-room-42'活跃连接与状态数据"SQLite / KV Storage"

Workers vs Durable Objects#

客户端与浏览器Durable Objects(每个 ID 对应单一协调实例)Durable Objects(每个 ID 对应单一协调实例)Chat Room DO (ID: room-456)Chat Room DO (ID: room-456)Chat Room DO (ID: room-123)Chat Room DO (ID: room-123)Cloudflare 全球边缘(无状态 Workers)Cloudflare 全球边缘(无状态 Workers)"边缘连接""边缘连接""HTTP 请求""路由至 ID: room-123""路由至 ID: room-123""路由至 ID: room-456"用户 A (WebSocket)用户 B (WebSocket)用户 C (HTTP REST)Worker(边缘节点 1)Worker(边缘节点 2)内存状态 & 活跃 WebSocket"内置 SQLite / KV 存储"定时器 / Alarms内存状态"SQLite 存储"
WorkersDurable Objects
无状态(Stateless)有状态(Stateful)
多个请求产生多个实例每个 ID 对应全球唯一实例
内存不保留状态在内存 + 存储中持久保留状态
无限自动水平扩展通过分片(Sharding 多 DO)扩展
分布在 330+ 个数据中心在单一位置执行(支持热迁移)
------

聊天室 — 基础示例#

12345678GET /?room=general&name=Alice (Upgrade: WebSocket)stub.fetch(request) [idFromName("general")]server.accept(), 保存会话 "Alice"101 Switching Protocols (WebSocket 已连接)广播 "Alice joined the chat"WS 消息: "Hello room!"broadcast("Alice: Hello room!", sender=Alice)WS 消息: "Alice: Hello room!"初始化 WebSocket 连接实时消息广播用户 Alice用户 Bob无状态 Worker 路由ChatRoom [Durable Object]用户 Alice用户 Bob无状态 Worker 路由ChatRoom [Durable Object]

SQLite Storage — 内置存储引擎#

每个 Durable Object 均拥有独立的 SQLite 存储:

"/increment""/get""/reset"其他请求: GET /increment /get /reseturl.pathnamestorage.get('count')storage.put('count', count + 1)storage.get('count')storage.put('count', 0)404 Not Found返回 JSON count

使用 storage.sql 执行 SQL 查询#

直接在 Durable Objects 中执行原生 SQL:

"GET""POST""PUT""DELETE"其他HTTP 请求表不存在则创建: CREATETABLE IF NOT EXISTS todos(...)HTTP 方法SELECT * FROM todosORDER BY id DESCINSERT INTO todos (title)VALUES (?)UPDATE todos SET completed= ? WHERE id = ?DELETE FROM todos WHEREid = ?405 Method Not AllowedJSON: todos 列表201 Created: 新创建的 todoJSON: &{ success: true &}JSON: &{ success: true &}

Alarms — DO 定时任务与调度#

123456GET /?delay=5000setAlarm(futureTimestamp){"message": "Alarm set for 5000ms"}触发 alarm() 处理器POST https://hooks.example.com/notify { event: 'alarm_fired' }setAlarm(nextHourTimestamp) [设置下次循环定时]1. 注册定时器 / 闹钟2. 超时唤醒执行(唤醒 DO)用户 / 客户端Reminder DOctx.storage [Alarm 队列]外部 Webhook用户 / 客户端Reminder DOctx.storage [Alarm 队列]外部 Webhook

多人在线游戏服务器#

"join""move""shoot"WebSocket 消息事件msg.type1. 将玩家会话加入 Map2. 初始化状态: x=0, y=03. 广播: type: 'players'1. 更新坐标: player.x += dx,player.y += dy2. 广播: type: 'move'1. 计算子弹方向与角度2. 广播: type: 'shoot'WebSocket 断开事件1. 从 Map 和状态中移除玩家2. 广播: type: 'leave'向房间内所有连接玩家广播更新后的状态

迁移管理 — 跨版本迁移 DO#

Durable Objects 支持零停机在不同类和架构间进行迁移:

// wrangler.jsonc
{
  "durable_objects": {
    "bindings": [
      {
        "name": "COUNTER",
        "class_name": "Counter",
        "migration": "new_tag"
      }
    ]
  }
}
typescript

迁移类型:

  • new_tag — 新类标签
  • new_classes — 添加多个类
  • rename — 类重命名
  • transfer — 命名空间之间的数据迁移

设计模式 — 分片(Sharding)#

每个 Durable Object 实例在同一时刻仅运行于单个物理位置。为了实现横向扩展,通常通过 Key 进行分片:

"userId: 0 - 999""userId: 1000 - 1999""userId: 2000 - 2999""userId: N - N+999"请求: userIdshardId = floor(userId / 1000)分片路由DO 实例: shard-0DO 实例: shard-1DO 实例: shard-2DO 实例: shard-N

总结#

Durable Objects 完美解决了无服务器架构中的状态管理难题:

  • 实时通信:WebSocket 连接结合全球强一致性内存状态
  • 游戏服务器:低延迟多人在线状态协同
  • 分布式协同:全局分布式锁、选主、速率限制
  • 内置 SQLite:无需维护外部数据库即可进行全功能关系型查询

架构设计建议:无状态请求由 Workers 处理,需要一致性状态协同的场景交由 Durable Objects。通过 Key 进行分片以实现无限水平扩展。

参考文献#