SuperAPI AI 工具集

cloudflare-durable-objects

部署与运维

查看项目

更新于 10-16 03:14

技能介绍

用途:Cloudflare Durable Objects 用于构建有状态的服务端逻辑,适合实时应用、WebSocket 服务器、协调与持久状态场景,例如聊天室、多人游戏。资料标注状态为 Production Ready。

主要能力:提供两类存储后端——SQLite(推荐,10GB,支持 SQL 查询、原子操作、PITR)与 KV(128MB,仅键值)。WebSocket 休眠 API 支持每个实例数千连接,空闲约 10 秒后休眠以节省成本,消息到达自动唤醒,消息大小上限 32 MiB(2025 年 10 月由 1 MiB 提升)。Alarms API 可让 DO 在指定未来时间被唤醒,用于批处理、清理、提醒和周期任务,至少执行一次并自动重试(最多 6 次,指数退避)。支持 RPC 方法直调与 HTTP fetch 两种调用方式;提供 idFromName / getByName、newUniqueId、idFromString 获取实例,支持 locationHint(尽力而为)与 jurisdiction(严格,如 'eu'、'fedramp')。

使用方式:可用 npm create cloudflare@latest my-durable-app -- --template=cloudflare/durable-objects-template --ts 脚手架新建项目,或在现有 Worker 中添加。DO 类需从 Worker 导出,构造函数第一行调用 super(ctx, env),用 ctx.blockConcurrencyWhile() 做存储初始化。新类须在 wrangler 配置的 migrations 中使用 new_sqlite_classes 声明。启用休眠须用 ctx.acceptWebSocket(server) 而非 ws.accept(),并用 server.serializeAttachment() 持久化每连接元数据,在构造函数中用 ctx.getWebSockets().forEach() 恢复。

限制:内存状态在休眠时丢失,须持久化到存储;禁止 setTimeout/setInterval,应改用 alarms;迁移是原子操作,不支持渐进发布,且不能对已有 KV 后端 DO 启用 SQLite;locationHint 仅为尽力而为;KV 存储上限 128MB,SQLite 上限 10GB。资料中部分内容被截断,官方文档链接为 https://developers.cloudflare.com/durable-objects/。