SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场cloudflare-durable-objects

cloudflare-durable-objects

部署与运维

查看项目

更新于 10-15 12:04

技能介绍

用途

Cloudflare Durable Objects 用于构建需要状态与协调能力的应用，例如聊天室、多人游戏、限流、会话管理、领导者选举以及有状态工作流。它提供全局唯一、具有单点协调能力的有状态对象，支持强一致性（ACID）、WebSocket 休眠、SQLite 存储与定时任务。

主要能力

  • 状态与一致性：提供全局唯一、支持单点协调的有状态对象，具备强一致性（ACID）。
  • 存储：
    • SQL API（SQLite 后端，推荐）：通过 ctx.storage.sql 访问，单实例最高 1GB，支持事务、索引、游标，deleteAll 为原子操作，迁移中使用 new_sqlite_classes。
    • Key-Value API：通过 ctx.storage 的 get/put/delete/list 进行简单键值操作，支持异步事务；KV 后端上限 128MB，SQLite 后端为 1GB。
  • WebSocket 休眠：每个 DO 实例可处理数千个 WebSocket 连接，空闲约 10 秒后自动休眠以节省时长费用，连接在边缘保持打开。
  • Alarms API：可安排 DO 在未来某个时间点被唤醒，用于批处理、清理、提醒或周期性任务；具备至少一次执行保证与自动重试（最多 6 次），可跨休眠与驱逐存活，成功执行后自动删除；每个 DO 仅能设置一个 alarm。
  • RPC 与 HTTP：RPC（推荐）可直接调用 DO 方法，类型安全、自动序列化；HTTP Fetch 采用传统请求/响应模式，WebSocket 升级场景必需。
  • 路由与 ID：支持 idFromName(name)（命名 DO，最常用）、newUniqueId()（随机唯一实例）、idFromString(idString)（从已保存 ID 重建）；获取 stub 可用 env.NAMESPACE.get(id) 或推荐写法 env.NAMESPACE.getByName(name)。支持位置提示（best-effort，仅影响首次创建）与管辖权限制（强制生效，不能与位置提示组合，适用于 GDPR/FedRAMP 合规）。
  • 迁移：创建、重命名、删除或在 Worker 间转移 DO 类需要迁移；类型包括 new_sqlite_classes/new_classes、renamed_classes、deleted_classes、transferred_classes。迁移是原子的，迁移标签必须唯一且只能追加。

使用方式

新建项目

npm create cloudflare@latest my-durable-app -- \
  --template=cloudflare/durable-objects-template --ts --git --deploy false
cd my-durable-app && bun install && npm run dev

添加到已有 Worker

  1. 安装类型：bun add -d @cloudflare/workers-types
  2. 创建 DO 类（src/counter.ts）：
import { DurableObject } from 'cloudflare:workers';

export class Counter extends DurableObject {
  async increment(): Promise<number> {
    let value: number = (await this.ctx.storage.get('value')) || 0;
    await this.ctx.storage.put('value', ++value);
    return value;
  }
}

export default Counter;  // CRITICAL
  1. 配置（wrangler.jsonc）：
{
  "durable_objects": {
    "bindings": [{ "name": "COUNTER", "class_name": "Counter" }]
  },
  "migrations": [
    { "tag": "v1", "new_sqlite_classes": ["Counter"] }
  ]
}
  1. 从 Worker 调用（src/index.ts）：
import { Counter } from './counter';

interface Env {
  COUNTER: DurableObjectNamespace<Counter>;
}

export { Counter };

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const stub = env.COUNTER.getByName('global-counter');
    return new Response(`Count: ${await stub.increment()}`);
  },
};
  1. 部署：bunx wrangler deploy

交互式命令（可选）

  • /do-setup：交互式初始化新 DO 项目，可选择存储后端与用例模式，可选 Vitest 测试，生成完整实现。
  • /do-migrate：交互式迁移助手，支持新建、重命名、删除（带安全确认）、在脚本间转移类，自动递增迁移标签。
  • /do-debug：分步调试流程，检测错误类别、执行诊断、给出修复建议并引导验证。
  • /do-patterns：模式选择向导，依据用例推荐模式并生成实现。
  • /do-optimize：性能优化助手，分析瓶颈并给出针对性优化建议。

自主智能体（可选）

  • do-debugger：自动错误检测与修复，校验 wrangler.jsonc，识别 16+ 常见错误并自动应用修复。
  • do-setup-assistant：从自然语言需求自动生成完整 DO 实现、测试与文档。
  • do-pattern-implementer：分析现有代码并按优先级实现 TTL 清理、RPC 元数据、SQL 索引等模式。

参考文档加载时机（节选）

  • state-api-reference.md：storage、sql、database、query、get/put、KV、1GB 限制
  • websocket-hibernation.md：websocket、real-time、chat、hibernation、serializeAttachment
  • alarms-api.md：alarms、scheduled tasks、cron、periodic、batch processing
  • rpc-patterns.md / rpc-metadata.md：RPC、fetch、HTTP、RpcTarget、metadata
  • stubs-routing.md：stubs、idFromName、newUniqueId、location hints、jurisdiction
  • migrations-guide.md / migration-cheatsheet.md：迁移、重命名、删除、转移、schema 变更
  • common-patterns.md：patterns、rate limiting、sessions、leader election
  • vitest-testing.md、gradual-deployments.md、typescript-config.md、advanced-sql-patterns.md、security-best-practices.md、error-codes.md、top-errors.md

关键规则

  • 所有 DO 继承 DurableObject 并且必须导出；构造函数第一行必须调用 super(ctx, env)。
  • WebSocket 休眠：应使用 ctx.acceptWebSocket(server)，使用 ws.serializeAttachment(data) 持久化元数据，并在构造函数中通过 ctx.getWebSockets() 恢复连接；不要使用 ws.accept()，也不要使用 setTimeout/setInterval（会阻止休眠）。
  • 迁移不可回退为渐进式：所有实例一次性迁移；无法在已有 KV 后端 DO 上启用 SQLite，必须新建类；迁移标签不可复用。

适用场景

聊天室、多人游戏、限流、会话管理、领导者选举、有状态工作流、批处理与定时任务、实时广播类应用。

限制与注意事项

  • 存储上限：SQLite 后端单实例 1GB，KV 后端 128MB。
  • 每个 DO 只能设置一个 alarm。
  • 位置提示为尽力而为，不保证生效，且仅影响首次创建；管辖权限制强制生效且不能与位置提示组合。
  • 删除类的迁移会立即删除且不可撤销，所有存储数据将丢失。
  • DO 类名在账号内（跨所有 Worker）唯一。
  • WebSocket 休眠约 10 秒无活动触发；构造函数应保持精简，重型工作会阻止休眠。
  • 资料未提供具体收费、价格信息。

依赖与版本（资料提供）

  • 依赖：cloudflare-worker-base（推荐）
  • 版本：wrangler@4.81.0+，@cloudflare/workers-types@4.20260408.0+
  • 官方文档：https://developers.cloudflare.com/durable-objects/