SuperAPI AI 工具集

cloudflare-durable-objects

部署与运维

查看项目

更新于 10-15 22:39

技能介绍

用途:Cloudflare Durable Objects 将计算与强一致、事务性存储结合,每个对象拥有全局唯一名称,可用于跨全球客户端的协调场景。本资料是一份开发手册,介绍其核心概念与用法。

主要能力:DurableObjectState(this.ctx)提供 id、storage、blockConcurrencyWhile、WebSocket 休眠相关方法及 abort;DurableObjectId 支持 idFromName 确定性 ID 与 newUniqueId 随机 ID。存储支持 SQLite 后端(推荐)与 KV:SQL 提供 exec、cursor.one/toArray、事务 transactionSync、databaseSize;KV 提供同步 kv.put/get/delete/list 与异步 put/get/list/deleteAll,批量最多 128 键,未 await 的多次写入会原子合并。Alarms 每个对象可设单个定时任务,异常时按指数退避重试(初始 2 秒,最多 6 次)。WebSocket 休眠可在对象休眠时保持连接,支持 acceptWebSocket、getWebSockets、serializeAttachment(上限 2048 字节)与 setWebSocketAutoResponse。RPC 可直接调用对象方法(兼容日期需 >= 2024-04-03)。

使用方式:定义继承 DurableObject 的类,在 Worker 入口通过 env.BINDING.idFromName/get 获取 stub 调用;在 wrangler.jsonc 配置 durable_objects.bindings 与 migrations(new_sqlite_classes),用 npx wrangler deploy 部署,wrangler tail 查看日志。构造函数中可用 blockConcurrencyWhile 建表(超时 30 秒)。

适用场景:需要强一致状态、协调、实时 WebSocket 房间、定时后台任务的无服务器应用。

限制:休眠后内存状态丢失,须从存储或 attachment 恢复;休眠需无待定定时器、无进行中 fetch、使用休眠 WebSocket API 且无活跃请求。已部署类无法再启用 SQLite。SQL 行/值上限 2 MB,KV 值 128 KiB。免费与付费在类数量、存储、CPU、请求与计费上不同,具体数值见资料。禁止在存储外保存状态、用标准 WebSocket API 实现休眠、在 sql.exec 中执行事务控制语句,waitUntil 在 DO 中无效。