Cloudflare Durable Objects 是什么

一句话版 · 打比方 · 原理图 · 能跑的示例 · 本仓库 apps/bot 里怎么用的

1. 打个比方：银行柜台 vs 自助取款机

2. 原理：请求是怎么流到 DO 的

四个关键事实

3. 最小示例：全球唯一计数器

三个文件：DO 类、Worker 入口、wrangler 配置。

src/index.ts

// DO 类：继承 DurableObject，方法可被 Worker 直接 RPC 调用
import { DurableObject } from "cloudflare:workers";

export class Counter extends DurableObject<Env> {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    // 首次启动建表；blockConcurrencyWhile 保证建好前不处理任何请求
    ctx.blockConcurrencyWhile(async () => {
      ctx.storage.sql.exec(
        "CREATE TABLE IF NOT EXISTS kv (k TEXT PRIMARY KEY, v INTEGER)"
      );
    });
  }

  increment(): number {
    // 单线程：读-改-写之间不会被别的请求打断，不需要加锁
    const row = this.ctx.storage.sql
      .exec<{ v: number }>("SELECT v FROM kv WHERE k = 'count'")
      .toArray()[0];
    const next = (row?.v ?? 0) + 1;
    this.ctx.storage.sql.exec(
      "INSERT OR REPLACE INTO kv (k, v) VALUES ('count', ?)", next
    );
    return next;
  }
}

// Worker 入口：无状态，负责把请求转给对应名字的 DO
export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    const name = new URL(req.url).searchParams.get("name") ?? "global";
    const stub = env.COUNTER.getByName(name);   // 按名字拿「遥控器」
    const n = await stub.increment();           // 像调本地方法一样 RPC
    return new Response(`${name}: ${n}`);
  },
};

wrangler.jsonc

{
  "name": "counter-demo",
  "main": "src/index.ts",
  "compatibility_date": "2026-10-01",
  "durable_objects": {
    "bindings": [{ "name": "COUNTER", "class_name": "Counter" }]
  },
  // 声明新 DO 类；用 SQLite 后端。migrations 只增不改
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Counter"] }]
}

效果：东京、伦敦、纽约同时狂刷 ?name=global，数字严格 1、2、3… 不重不漏；换 ?name=alice 就是另一个独立计数器。

4. 另外两个杀手级能力

export class Room extends DurableObject<Env> {
  async fetch(req: Request) {
    const [client, server] = Object.values(new WebSocketPair());
    this.ctx.acceptWebSocket(server);              // 可休眠的 WS
    return new Response(null, { status: 101, webSocket: client });
  }
  webSocketMessage(ws: WebSocket, msg: string) {   // 收到消息 → 广播
    for (const peer of this.ctx.getWebSockets()) peer.send(msg);
  }
}

5. 什么时候用 / 不用

设计心法：「一个 DO = 一个实体」，用实体 ID 做名字。想要水平扩展，就是开更多 DO，而不是让一个 DO 更大。

6. 本仓库里的真实例子：apps/bot 的 BotOwner

Berth Bot 就是按这个心法设计的（ADR-0188）：DO 名 = 用户的 user_id，这个用户的所有 bot / 线程 / Run / 凭证都存在这一个 DO 的 SQLite 里。

分工很清晰：Worker 管会话校验和白名单（无状态），DO 管某一个用户的全部状态（有状态、单线程、强一致）。

7. 常见坑