Cloudflare Workers + Durable Objects + D1 全链路深度拆解：当边缘计算长出真正的大脑——有状态分布式系统的工程范式革命
背景引入：Serverless 的阿喀琉斯之踵与边缘计算的觉醒
在 Serverless 概念诞生的第一天，我们就被告知：函数即服务（FaaS）将彻底改变后端开发的游戏规则。没有服务器需要管理，没有集群需要监控，没有容量规划需要操心——上传一段代码，平台负责将其分发到全球数百个节点，用户从最近的节点读取，延迟从 200ms 降到 20ms。多美好。
然而，当第一批吃螃蟹的团队真正把业务迁移到 Serverless 架构后，他们发现了一个尴尬的悖论：现实世界中的业务几乎都是有状态的。一个用户会话需要记住登录态；一个购物车需要记住选中的商品；一个在线协作工具需要实时同步多人的操作；一个实时聊天需要维护消息流。这些需求在传统架构中理所当然，在 Serverless 的世界里却成了"不可能三角"——你既要享受无服务器的低运维成本，又要保持有状态业务的一致性，还要在全球分布的环境中保持低延迟。
Cloudflare 的答案是：既然 Serverless 函数天生无状态，那就给它们一个配套的有状态单元。这个单元叫 Durable Objects——一个运行在边缘节点上的、带有强一致性的、全球唯一的对象实例。它和 Workers 函数一起，构成了边缘计算时代"计算 + 状态"的完整解。
加上边缘原生的 SQLite 数据库 D1、全球对象存储 R2、以及 2026 年重磅推出的基于 QuePaxa 共识算法的 Meerkat 全球协调服务，Cloudflare 已经构建了一套完整的边缘有状态计算栈。本文将从架构原理、代码实战、生产踩坑三个维度，对这套技术栈进行全链路深度拆解。
一、Workers 运行时：边缘计算的执行引擎
1.1 V8 沙箱与 Zero-Cold-Start 的秘密
Cloudflare Workers 的运行时基于 V8 引擎——和 Chrome 浏览器用的是同一个。这意味着每个 Worker 实例都在一个独立的 V8 隔离环境中运行，而不是像传统容器那样共享操作系统层。
这个设计带来了几个关键优势：
进程级隔离的安全模型：每个 Worker 之间完全隔离，一个 Worker 的崩溃不会影响其他 Worker。这比传统的容器共享内核模型要安全得多。
Zero-Cold-Start 的实现机制：这是最容易让初学者困惑的地方——Cloudflare 声称 Workers "没有冷启动"，这是真的吗？
答案是：部分是真的。传统 Serverless（如 AWS Lambda）在函数首次调用时需要初始化运行时环境（启动容器、加载语言运行时、初始化依赖），这个过程可能需要数百毫秒到数秒。Cloudflare Workers 通过以下机制消除了这种冷启动延迟：
// Worker 的入口点——这个文件会被提前编译成 V8 快照
// 当请求到达时，直接从快照恢复执行上下文，无需重新初始化
export default {
async fetch(request, env, ctx) {
// env 是环境变量绑定，在 Workers 中通过 Wrangler 注入
// ctx 是 Worker 的执行上下文，包含 waitUntil 等生命周期控制方法
const url = new URL(request.url);
// 路由分发
if (url.pathname.startsWith('/api/')) {
return handleAPI(request, env);
}
return new Response('Hello from Edge!', {
headers: { 'Content-Type': 'text/plain' }
});
}
};
// 请求处理器
async function handleAPI(request, env) {
// Workers 支持标准的 Fetch API
const data = await request.json();
// 访问 D1 数据库
const db = env.DB; // 通过环境绑定访问 D1
const result = await db
.prepare('SELECT * FROM users WHERE id = ?')
.bind(data.userId)
.first();
return Response.json(result);
}
Worker 的启动实际上是预热的：Cloudflare 在全球每个数据中心都维护着 V8 隔离环境的"热池"。当你部署 Worker 时，平台会预先编译代码、生成快照，并将这些快照分发到所有节点。当请求到达时，平台只需要从热池中取出一个空闲的 V8 隔离环境，从快照恢复执行上下文，即可立即处理请求——这个过程在微秒级完成。
1.2 CPU 时间限制与内存模型
理解 Workers 的资源模型是写出生产可用代码的前提。Workers 有两个关键限制：
CPU 时间限制：每个请求的 CPU 使用时间上限为 50ms（付费计划可扩展到 30 秒）。注意：这里的"CPU 时间"是实际计算时间，不包括 I/O 等待时间。也就是说，如果你的 Worker 花 200ms 等待数据库返回结果，这 200ms 不计入 CPU 限制；但如果你在 CPU 上做复杂的加密计算，花了 50ms，Worker 就会被终止。
这个设计背后的逻辑是：Workers 是 I/O 密集型的工作负载，不适合 CPU 密集型任务。如果你的业务需要大量计算（比如视频转码、复杂加密），应该在 Workers 中调用专门的处理服务（Cloudflare Images、WASM Workers 等），而不是在 Workers 本身完成计算。
内存限制：每个 Worker 的内存上限为 128MB（付费计划可扩展）。这个数字看起来很小，但对于处理 HTTP 请求来说是完全足够的——一个典型的 JSON 序列化/反序列化操作只需要几 MB 内存。
// 内存友好的数据处理模式
export default {
async fetch(request, env, ctx) {
// ❌ 错误示范：将整个大文件加载到内存
// const body = await request.arrayBuffer();
// const data = JSON.parse(new TextDecoder().decode(body));
// ✅ 正确示范：使用流式处理，内存占用恒定
const stream = request.body;
const decoder = new TextDecoder();
let buffer = '';
// 使用 for await...of 流式读取，不会一次性占用大量内存
for await (const chunk of stream) {
buffer += decoder.decode(chunk, { stream: true });
// 处理每一块数据
processChunk(buffer);
buffer = ''; // 释放已处理的数据
}
return new Response('OK');
}
};
function processChunk(data) {
// 处理逻辑
}
1.3 事件驱动的生命周期：waitUntil 与 PassThrough
Workers 的执行模型是基于事件的。一个请求的处理流程如下：
- 请求到达 → Workers 启动事件循环
fetch事件处理器被调用- 关键：当
fetch处理器返回Response后，Worker 可以继续在后台执行异步任务——只要这些任务被包装在ctx.waitUntil()中
export default {
async fetch(request, env, ctx) {
const startTime = Date.now();
// 记录日志到 KV——这是一个异步操作
// ❌ 错误：如果在返回 Response 后直接 await，会导致 Worker 被提前终止
// await env.KV.put('request_log', JSON.stringify({...}));
// ✅ 正确：使用 waitUntil 在后台执行，不阻塞响应
ctx.waitUntil(
env.KV.put('request_log', JSON.stringify({
url: request.url,
timestamp: startTime,
duration: Date.now() - startTime
}))
);
// 业务逻辑
const result = await processRequest(request, env);
// 返回 Response 后，Worker 不会立即终止
// ctx.waitUntil 中的任务会继续执行
return Response.json(result);
}
};
waitUntil 的实际应用场景包括：
- 日志异步写入：不阻塞主响应流程
- WebSocket 保持连接：在响应返回后继续维护 WebSocket 连接
- 邮件/通知发送：在后台发送通知邮件
- 缓存预热：在响应用户请求后，在后台预加载相关数据到缓存
二、Durable Objects：边缘节点上的有状态大脑
2.1 从无状态到有状态：设计理念的范式转换
如果说 Workers 是边缘计算的执行引擎，那么 Durable Objects 就是它的"大脑"——一个带有持久状态的、全球唯一的对象实例。
Durable Objects 的核心设计哲学是：每个 Durable Object 实例都有且仅有一个活跃副本。这个副本运行在离它最近的 Cloudflare 数据中心，当请求到达时，平台会自动将请求路由到该实例所在的节点。
这个设计解决了分布式系统中最棘手的问题之一：分布式锁与一致性问题。在传统的分布式架构中，多个服务实例可能同时访问同一个资源，需要借助 Redis、ZooKeeper 或 etcd 等外部系统来实现分布式锁。而 Durable Objects 的单实例特性天然保证了串行化访问——所有对同一个 Durable Object 的请求都会被路由到同一个节点，按到达顺序依次处理，无需额外的锁机制。
// 定义一个 Durable Object 类
// 每个 Durable Object 实例都是这个类的一个实例
export class GameRoom implements DurableObject {
private state: DurableObjectState;
private players: Map<string, WebSocket> = new Map();
private gameState: any = {};
constructor(state: DurableObjectState, env: Env) {
this.state = state;
}
// 每次请求到达时调用
async fetch(request: Request): Promise<Response> {
const url = new URL(request.url);
switch (url.pathname) {
case '/join':
return this.handleJoin(request);
case '/move':
return this.handleMove(request);
case '/state':
return this.handleGetState();
default:
return new Response('Not Found', { status: 404 });
}
}
private async handleJoin(request: Request): Promise<Response> {
const { playerId, wsUrl } = await request.json();
// 建立 WebSocket 连接
const playerSocket = new WebSocket(wsUrl);
this.players.set(playerId, playerSocket);
// 持久化游戏状态——数据会自动持久化到磁盘
await this.state.storage.put('players', Array.from(this.players.keys()));
// 广播玩家加入事件
this.broadcast({ type: 'player_joined', playerId });
return new Response(JSON.stringify({
playerId,
currentState: this.gameState
}));
}
private async handleMove(request: Request): Promise<Response> {
const move = await request.json();
// 验证并应用移动
this.applyMove(move);
// 持久化状态
await this.state.storage.put('gameState', this.gameState);
// 广播状态更新
this.broadcast({ type: 'state_update', state: this.gameState });
return new Response('OK');
}
private broadcast(message: any) {
const msgStr = JSON.stringify(message);
for (const ws of this.players.values()) {
ws.send(msgStr);
}
}
private applyMove(move: any) {
// 游戏逻辑...
this.gameState.lastMove = move;
}
private async handleGetState(): Promise<Response> {
return Response.json(this.gameState);
}
}
2.2 存储 API：同步与异步的权衡
Durable Objects 提供了两种存储 API：同步和异步。
同步 API（推荐用于高频读写）：
export class MyObject implements DurableObject {
async fetch(request: Request): Promise<Response> {
// 同步读取——立即返回，不涉及网络往返
const value = this.state.storage.get('key');
// 同步写入——批量操作，减少网络往返
await this.state.storage.put({
key1: 'value1',
key2: 'value2',
key3: 'value3'
});
// 同步删除
await this.state.storage.delete('old_key');
return new Response('OK');
}
}
异步 API（适合大批量操作）：
export class MyObject implements DurableObject {
async fetch(request: Request): Promise<Response> {
// 异步列出所有键
const keys = await this.state.storage.list();
// 支持前缀过滤
const userKeys = await this.state.storage.list({ prefix: 'user_' });
// 获取键的数量
const count = await this.state.storage.listKeys();
// 清空所有数据
await this.state.storage.deleteAll();
return new Response(JSON.stringify(Array.from(keys.keys())));
}
}
关键性能提示：
- 批量操作优先：每次
put操作都有网络往返，如果需要写入多个键，使用对象形式批量写入比多次调用put更高效。 - 避免频繁的小对象读写：Durable Objects 的存储基于 SQLite，每次写入都会触发 SQLite 的 WAL 机制，频繁的小对象读写会导致性能问题。
- 使用
get而非list获取单个值：如果你只需要一个键的值，直接get比list({ prefix: 'xxx' })然后过滤更高效。
2.3 事务：ACID 的边缘化
Durable Objects 支持事务操作，这使得状态更新具有原子性保证：
export class AccountObject implements DurableObject {
async fetch(request: Request): Promise<Response> {
const { from, to, amount } = await request.json();
// 使用事务保证原子性
// rollback() 会撤销所有在事务块中的修改
const txn = this.state.storage.transaction(async () => {
const fromBalance = await this.state.storage.get(`balance:${from}`) || 0;
const toBalance = await this.state.storage.get(`balance:${to}`) || 0;
if (fromBalance < amount) {
throw new Error('Insufficient balance');
}
await this.state.storage.put(`balance:${from}`, fromBalance - amount);
await this.state.storage.put(`balance:${to}`, toBalance + amount);
return { success: true };
});
try {
const result = await txn();
return Response.json(result);
} catch (e) {
// 事务失败，自动回滚
return Response.json({ error: e.message }, { status: 400 });
}
}
}
2.4 生命周期：冷启动与热启动
Durable Objects 实例有两种状态：热状态和冷状态。
当一个 Durable Object 实例被频繁访问时，它会保持在"热状态"——实例对象保留在内存中，所有状态变量无需重新加载。这种状态下的请求处理延迟极低，通常在亚毫秒级。
当一个 Durable Object 实例长时间没有被访问（默认 30 秒），它会进入"冷状态"——实例对象从内存中卸载，状态数据保留在磁盘上。当新的请求到达时，Cloudflare 会在最近的节点上重新激活实例，从磁盘加载状态数据。这个过程就是 Durable Objects 的"冷启动"。
冷启动的延迟通常在 5-20ms 之间，虽然比热状态的亚毫秒级慢，但对于大多数应用场景来说是可以接受的。关键是要理解：Durable Objects 的冷启动是不可避免的，但可以通过设计来缓解其影响。
export class CacheObject implements DurableObject {
private state: DurableObjectState;
private cache: Map<string, any> = new Map();
private isLoaded = false;
constructor(state: DurableObjectState, env: Env) {
this.state = state;
}
async fetch(request: Request): Promise<Response> {
// 在首次访问时加载缓存数据
if (!this.isLoaded) {
const cached = await this.state.storage.get('cache');
if (cached) {
this.cache = new Map(Object.entries(cached));
}
this.isLoaded = true;
}
// 业务逻辑...
return Response.json({ cacheSize: this.cache.size });
}
// 定期持久化，防止冷启动丢失未刷新的数据
async alarm() {
// Durable Objects 支持定时 alarm
await this.state.storage.put('cache', Object.fromEntries(this.cache));
}
}
2.5 类 Alarm 系统：定时任务与过期清理
Durable Objects 内置了 Alarm 系统，允许你在实例内部安排定时任务。这在实现缓存过期、会话清理、定时同步等场景时非常有用：
export class SessionManager implements DurableObject {
private state: DurableObjectState;
private sessions: Map<string, { expires: number }> = new Map();
constructor(state: DurableObjectState, env: Env) {
this.state = state;
// 设置 Alarm 调度器
// 每 5 分钟执行一次清理任务
this.state.storage.setAlarm(Date.now() + 5 * 60 * 1000);
}
async fetch(request: Request): Promise<Response> {
const url = new URL(request.url);
if (url.pathname === '/session') {
const { sessionId } = await request.json();
const session = this.sessions.get(sessionId);
if (!session || session.expires < Date.now()) {
return Response.json({ error: 'Session expired' }, { status: 401 });
}
return Response.json({ valid: true });
}
return new Response('Not Found', { status: 404 });
}
// Alarm 回调
async alarm(): Promise<void> {
// 清理过期的会话
const now = Date.now();
for (const [id, session] of this.sessions.entries()) {
if (session.expires < now) {
this.sessions.delete(id);
}
}
// 持久化清理后的状态
await this.state.storage.put('sessions',
Array.from(this.sessions.entries())
);
// 设置下一次 Alarm
this.state.storage.setAlarm(Date.now() + 5 * 60 * 1000);
}
}
三、D1：边缘原生的 SQLite 数据库
3.1 架构解析：SQLite 为什么会出现在边缘
D1 的本质是 SQLite on the Edge。Cloudflare 将 SQLite 的整个存储引擎编译为 WebAssembly，运行在 V8 隔离环境中。每个 D1 数据库的副本会自动同步到全球所有 Cloudflare 数据中心。
这个设计的精妙之处在于：SQLite 是世界上部署最广泛的数据库引擎，几乎所有开发者都熟悉它。无需学习新的查询语言，无需改变已有的 SQL 习惯，你可以直接用标准的 SELECT、INSERT、UPDATE、DELETE 操作边缘数据。
-- D1 使用标准 SQL，但有一些限制：
-- 1. 不支持 TRIGGER（触发器）
-- 2. 不支持 VIEW 的更新操作
-- 3. 部分 ALTER TABLE 操作受限
-- 创建表
CREATE TABLE IF NOT EXISTS users (
id TEXT PRIMARY KEY,
email TEXT UNIQUE NOT NULL,
name TEXT,
created_at INTEGER DEFAULT (unixepoch()),
updated_at INTEGER
);
-- 创建索引
CREATE INDEX IF NOT EXISTS idx_users_email ON users(email);
-- D1 支持 CTE（公用表表达式）
WITH recent_users AS (
SELECT * FROM users
WHERE created_at > unixepoch() - 86400
)
SELECT
u.*,
COUNT(p.id) as post_count
FROM recent_users u
LEFT JOIN posts p ON p.user_id = u.id
GROUP BY u.id
ORDER BY post_count DESC
LIMIT 10;
3.2 零冷启动的读写性能
D1 最大的技术亮点是它的零冷启动读取。由于 D1 的数据是存储在 V8 隔离环境的内存映射文件中的，当请求到达时，不需要像传统数据库那样建立连接、解析查询计划、执行查询——数据已经在内存中了，可以直接读取。
这使得 D1 的读取延迟通常在亚毫秒级，比传统的数据库连接快 10-100 倍。
// Workers 中访问 D1
export default {
async fetch(request, env, ctx) {
const db = env.DB; // 通过环境绑定获取 D1 数据库实例
// 基础查询
const { results } = await db
.prepare('SELECT * FROM users WHERE id = ?')
.bind('user_123')
.all();
// 单行查询（更高效）
const user = await db
.prepare('SELECT * FROM users WHERE email = ?')
.bind('user@example.com')
.first();
// 插入数据
await db
.prepare('INSERT INTO users (id, email, name) VALUES (?, ?, ?)')
.bind('user_456', 'new@example.com', 'New User')
.run();
// 事务操作
const batchResult = await db.batch([
db.prepare('INSERT INTO posts (id, user_id, title) VALUES (?, ?, ?)'),
db.prepare('UPDATE users SET updated_at = unixepoch() WHERE id = ?')
]);
return Response.json({
user,
count: results.length
});
}
}
3.3 Drizzle ORM：类型安全的边缘数据库操作
虽然可以直接使用 D1 的原生 API，但引入一个 ORM 可以带来更好的类型安全和开发体验。在 2026 年的生态中，Drizzle 已经成为了 Cloudflare 官方推荐的 D1 ORM 选择。
与 Prisma 相比，Drizzle 对 D1 的支持更加"原生"——它直接与 env.DB 绑定，无需任何中间层，性能损耗几乎为零。
// drizzle.config.ts
import { defineConfig } from 'drizzle-kit';
export default defineConfig({
schema: './src/schema.ts',
out: './drizzle',
dialect: 'sqlite',
dbCredentials: {
// 本地开发时使用 wrangler dev 提供的本地数据库
url: 'file:dev.sqlite',
},
});
// src/schema.ts
import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
export const users = sqliteTable('users', {
id: text('id').primaryKey(),
email: text('email').unique().notNull(),
name: text('name'),
createdAt: integer('created_at', { mode: 'timestamp' })
.$defaultFn(() => new Date()),
updatedAt: integer('updated_at', { mode: 'timestamp' })
});
export const posts = sqliteTable('posts', {
id: text('id').primaryKey(),
userId: text('user_id')
.references(() => users.id)
.notNull(),
title: text('title').notNull(),
content: text('content'),
published: integer('published', { mode: 'boolean' }).default(false),
createdAt: integer('created_at', { mode: 'timestamp' })
.$defaultFn(() => new Date()),
});
// src/db.ts
import { drizzle } from 'drizzle-orm/d1';
import { eq, desc, sql } from 'drizzle-orm';
import { users, posts } from './schema';
// 创建 Drizzle 实例
export function createDB(db: D1Database) {
return drizzle(db, { schema: { users, posts } });
}
// src/index.ts
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext) {
const db = createDB(env.DB);
// 类型安全的查询
const allUsers = await db.select().from(users).all();
// 条件查询
const activePosts = await db
.select({
userId: posts.userId,
title: posts.title,
userName: users.name
})
.from(posts)
.innerJoin(users, eq(posts.userId, users.id))
.where(eq(posts.published, true))
.orderBy(desc(posts.createdAt))
.limit(20)
.all();
// 插入
const inserted = await db.insert(users).values({
id: crypto.randomUUID(),
email: 'test@example.com',
name: 'Test User'
}).returning().get();
return Response.json({
users: allUsers.length,
posts: activePosts,
inserted
});
}
};
3.4 迁移管理：从开发到生产的版本控制
D1 的迁移系统允许你像管理代码版本一样管理数据库 schema：
# 1. 初始化迁移目录
npx wrangler d1 migrations create init_schema
# 2. 编辑生成的迁移文件
# drizzle/0000_init_schema.sql:
# CREATE TABLE IF NOT EXISTS users (...);
# CREATE INDEX IF NOT EXISTS idx_users_email ON users(email);
# 3. 本地开发环境应用迁移
npx wrangler d1 migrations apply dev_db --local
# 4. 生产环境应用迁移
npx wrangler d1 migrations apply production_db --remote
# 5. 查看数据库状态
npx wrangler d1 execute production_db --remote --command="SELECT * FROM users LIMIT 5;"
四、架构实战：从设计到部署的全链路
4.1 典型架构：聊天服务的边缘化
让我们通过一个具体的例子来理解这套技术栈如何协同工作：一个实时聊天服务。
传统架构的问题：
- 需要维护 WebSocket 服务器集群
- 需要 Redis 存储会话状态
- 需要数据库存储聊天记录
- 需要处理多区域部署的复杂性
- 跨区域延迟高达 200-500ms
基于 Cloudflare 的架构：
客户端 → Cloudflare 全球网络 → 最近的边缘节点
↓
Workers（路由层）
↓
Durable Objects（房间状态管理）
↓
D1（历史消息持久化）+ R2（文件存储）
// src/chat-room.ts - Durable Object：房间状态管理
export class ChatRoom implements DurableObject {
private state: DurableObjectState;
private connections: Map<string, WebSocket> = new Map();
private messageHistory: Array<{
id: string;
userId: string;
userName: string;
content: string;
timestamp: number;
}> = [];
constructor(state: DurableObjectState, env: Env) {
this.state = state;
}
async fetch(request: Request): Promise<Response> {
// WebSocket 升级请求
if (request.headers.get('Upgrade') === 'websocket') {
return this.handleWebSocket(request);
}
const url = new URL(request.url);
switch (url.pathname) {
case '/history':
return this.getHistory();
case '/users':
return this.getUsers();
default:
return new Response('Not Found', { status: 404 });
}
}
private async handleWebSocket(request: Request): Promise<Response> {
const { 0: client, 1: server } = new WebSocketPair();
const userId = crypto.randomUUID();
this.connections.set(userId, server);
// 加载历史消息
const stored = await this.state.storage.get('messageHistory');
if (stored) {
this.messageHistory = JSON.parse(stored as string);
}
server.accept();
server.addEventListener('message', async (event) => {
const message = JSON.parse(event.data as string);
if (message.type === 'chat') {
const chatMessage = {
id: crypto.randomUUID(),
userId,
userName: message.userName,
content: message.content,
timestamp: Date.now()
};
this.messageHistory.push(chatMessage);
// 保留最近 100 条消息在内存
if (this.messageHistory.length > 100) {
this.messageHistory = this.messageHistory.slice(-100);
}
// 持久化到 D1（在后台异步执行）
this.state.waitUntil(this.persistMessage(chatMessage));
// 广播给所有连接
this.broadcast(chatMessage);
}
});
server.addEventListener('close', () => {
this.connections.delete(userId);
this.broadcast({
type: 'user_left',
userId,
timestamp: Date.now()
});
});
// 发送欢迎消息
server.send(JSON.stringify({
type: 'connected',
userId,
history: this.messageHistory.slice(-50),
users: Array.from(this.connections.keys())
}));
return new Response(null, { status: 101, webSocket: client });
}
private async persistMessage(message: any) {
// 注意：这里需要访问 D1，但 Durable Object 没有直接的环境绑定
// 需要通过 Workers 中转或使用绑定
// 实际生产中建议使用 Cloudflare Queues 或直接写入
}
private broadcast(message: any) {
const msgStr = JSON.stringify(message);
for (const ws of this.connections.values()) {
ws.send(msgStr);
}
}
private getHistory(): Response {
return Response.json(this.messageHistory.slice(-100));
}
private getUsers(): Response {
return Response.json({
count: this.connections.size,
ids: Array.from(this.connections.keys())
});
}
}
// src/index.ts - Workers：路由层
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext) {
const url = new URL(request.url);
if (url.pathname.startsWith('/room/')) {
const roomId = url.pathname.split('/')[2];
// 获取或创建房间的 Durable Object
const roomIdObj = env.CHAT_ROOM.idFromName(roomId);
const room = env.CHAT_ROOM.get(roomIdObj);
// 将请求转发到 Durable Object
return room.fetch(request);
}
// 健康检查
if (url.pathname === '/health') {
return Response.json({ status: 'ok', timestamp: Date.now() });
}
return new Response('Chat API', {
headers: { 'Content-Type': 'text/plain' }
});
}
};
// wrangler.toml 配置
// name = "chat-service"
// main = "src/index.ts"
//compatibility_date = "2024-01-01"
//
// [[d1_databases]]
// binding = "DB"
// database_name = "chat-db"
// database_id = "your-database-id"
//
// [[migrations]]
// dir = "drizzle"
//
4.2 Cloudflare OS 与 Meerkat：2026 年的架构升级
2026 年，Cloudflare 推出了两个重磅功能：Cloudflare OS 和 Meerkat。
Cloudflare OS 的核心理念是：让每个人都运行着属于自己的应用代码副本。这意味着 SaaS 模式将从"千人一面"变为"千人千面"——如果你想给一个 SaaS 产品加个功能，不再需要给开发者提需求，而是可以直接让 AI agent 帮你改你自己运行的那份代码副本。
Meerkat 是 Cloudflare 的全球一致性协调服务，基于 QuePaxa 共识算法。与 Raft 等传统共识算法不同，QuePaxa 允许无领导者的写入操作，同时保持强一致性。这意味着在多节点协作场景中，不需要等待 leader 选举，可以直接在任何节点写入数据，大大提高了可用性和延迟表现。
// Meerkat 的使用场景：跨 Durable Object 的全局协调
export class GlobalLock implements DurableObject {
private state: DurableObjectState;
constructor(state: DurableObjectState, env: Env) {
this.state = state;
}
async fetch(request: Request): Promise<Response> {
const { action, resource } = await request.json();
if (action === 'acquire') {
// 使用 Meerkat 实现分布式锁
// 传统的 Redis SETNX 方案在边缘场景下不可靠
// Meerkat 提供了全局一致的锁服务
const lockKey = `lock:${resource}`;
const currentHolder = await this.state.storage.get(lockKey);
if (currentHolder) {
return Response.json({
acquired: false,
holder: currentHolder
});
}
const myId = this.state.id.toString();
await this.state.storage.put(lockKey, myId);
return Response.json({ acquired: true, holder: myId });
}
return new Response('Unknown action', { status: 400 });
}
}
五、性能优化：让边缘系统跑得更快
5.1 读取优化：缓存层设计
在边缘计算中，合理的缓存设计可以带来 10-100 倍的性能提升：
// Workers 中的多层缓存策略
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext) {
const url = new URL(request.url);
const cacheKey = url.pathname;
// 第一层：Workers Cache API（分布式内存缓存）
const cache = caches.default;
const cached = await cache.match(cacheKey);
if (cached) {
// 返回缓存，添加一个自定义头标识缓存命中
return new Response(cached.body, {
headers: {
...Object.fromEntries(cached.headers),
'X-Cache': 'HIT'
}
});
}
// 第二层：从 Durable Objects 读取热点数据
const doId = env.DATA_CACHE.idFromName('hot_data');
const doStub = env.DATA_CACHE.get(doId);
const hotData = await doStub.fetch('/data');
// 第三层：从 D1 读取持久化数据
const db = env.DB;
const results = await db
.prepare('SELECT * FROM articles WHERE published = 1 ORDER BY created_at DESC LIMIT 20')
.all();
const response = Response.json(results);
// 将结果写入 Workers Cache（CDN 边缘缓存）
ctx.waitUntil(
cache.put(cacheKey, response.clone())
);
// 添加缓存控制头
response.headers.set('Cache-Control', 'public, max-age=60, stale-while-revalidate=300');
response.headers.set('X-Cache', 'MISS');
return response;
}
};
5.2 写入优化：批量与异步
写入操作通常是性能的瓶颈，以下是几种优化策略：
// 策略一：批量写入
export class BatchWriter implements DurableObject {
private state: DurableObjectState;
private writeBuffer: Array<any> = [];
private flushTimer: number | null = null;
constructor(state: DurableObjectState, env: Env) {
this.state = state;
}
async fetch(request: Request): Promise<Response> {
const { data } = await request.json();
// 立即响应，不等待实际写入
this.writeBuffer.push(data);
// 设置定时刷新（5秒后或达到 100 条时触发）
if (!this.flushTimer) {
this.flushTimer = Date.now() + 5000;
}
if (this.writeBuffer.length >= 100) {
await this.flush();
}
return Response.json({ queued: true, queueLength: this.writeBuffer.length });
}
private async flush() {
if (this.writeBuffer.length === 0) return;
const dataToWrite = this.writeBuffer.splice(0, this.writeBuffer.length);
this.flushTimer = null;
// 批量写入 D1
// 使用 INSERT ... VALUES (...), (...), (...) 语法
const values = dataToWrite
.map(d => `('${d.id}', '${d.content}', ${d.timestamp})`)
.join(',');
await this.state.storage.put('pending_writes', dataToWrite);
}
}
// 策略二：使用 Cloudflare Queues 解耦写入
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext) {
const data = await request.json();
// 立即将消息放入队列，不阻塞响应
await env.WRITE_QUEUE.send({
type: 'log_event',
data,
timestamp: Date.now()
});
return Response.json({ queued: true });
}
};
5.3 连接优化：WebSocket 的边缘化
WebSocket 在边缘计算中的最大挑战是连接保持。传统的 WebSocket 服务器需要维护大量的长连接，而 Durable Objects 天然解决了这个问题——每个房间对应一个 Durable Object 实例，所有连接都在同一个实例中管理。
// 优化：连接心跳与自动重连
export class PersistentWebSocket implements DurableObject {
private state: DurableObjectState;
private ws: WebSocket | null = null;
private reconnectAttempts = 0;
private maxReconnectAttempts = 5;
constructor(state: DurableObjectState, env: Env) {
this.state = state;
}
async fetch(request: Request): Promise<Response> {
if (request.headers.get('Upgrade') === 'websocket') {
const { 0: client, 1: server } = new WebSocketPair();
server.accept();
this.ws = server;
// 设置心跳
this.startHeartbeat();
// 处理消息
server.addEventListener('message', (event) => {
this.handleMessage(event.data as string);
});
server.addEventListener('close', () => {
this.handleDisconnect();
});
return new Response(null, { status: 101, webSocket: client });
}
return new Response('Expected WebSocket', { status: 400 });
}
private startHeartbeat() {
// 每 30 秒发送一次心跳
this.state.storage.setAlarm(Date.now() + 30000);
}
async alarm() {
// 检查连接状态
if (this.ws && this.ws.readyState === WebSocket.OPEN) {
this.ws.send(JSON.stringify({ type: 'ping' }));
}
this.startHeartbeat();
}
private handleMessage(data: string) {
const message = JSON.parse(data);
if (message.type === 'pong') {
this.reconnectAttempts = 0;
}
}
private handleDisconnect() {
// 尝试自动重连
if (this.reconnectAttempts < this.maxReconnectAttempts) {
this.reconnectAttempts++;
setTimeout(() => this.attemptReconnect(), 1000 * this.reconnectAttempts);
}
}
private async attemptReconnect() {
// 从存储中恢复必要的状态
const stored = await this.state.storage.get('connectionConfig');
if (stored) {
// 重新建立 WebSocket 连接
// ...
}
}
}
六、生产踩坑清单：15 条经验总结
架构设计阶段
Durable Object 实例数量的规划：每个 Durable Object 实例都是唯一的，实例数量直接决定了并发处理能力。对于高并发场景，需要设计合理的实例分片策略——例如按用户 ID 分片，确保同一用户的所有请求路由到同一个实例。
数据大小的限制：单个 Durable Object 的存储上限为 50MB（免费版）或 500MB（付费版）。如果需要存储更大的数据（如文件），应该使用 R2 对象存储，只在 Durable Objects 中存储元数据。
跨区域数据同步的延迟：Durable Objects 的状态数据会异步同步到全球所有节点，但同步有延迟（通常在秒级）。如果业务对一致性要求极高，需要设计幂等操作或使用 Meerkat 进行全局协调。
D1 的写入限制：D1 的写入是单线程的（基于 SQLite），每秒写入次数有限。对于高频写入场景，建议使用 Durable Objects 的内存缓存 + 批量写入策略。
开发调试阶段
Wrangler 本地模拟的局限性：
wrangler dev提供的本地开发环境并不能完全模拟边缘行为，特别是网络延迟和全球分布特性。建议在本地完成基本调试后，尽早部署到 staging 环境进行真实测试。Durable Object 的日志：Durable Object 的日志不会直接显示在
wrangler dev的终端中，需要通过console.log查看。生产环境中可以使用 Cloudflare Logpush 将日志导出到日志分析服务。WebSocket 的连接超时：Cloudflare Workers 的 WebSocket 连接在 100 秒无活动后会自动断开。需要在客户端实现心跳机制和自动重连逻辑。
CORS 配置：Workers 默认不设置 CORS 头。如果你的 API 需要被前端页面调用，需要显式设置 CORS 头：
const corsHeaders = {
'Access-Control-Allow-Origin': '*',
'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
'Access-Control-Allow-Headers': 'Content-Type, Authorization'
};
if (request.method === 'OPTIONS') {
return new Response(null, { headers: corsHeaders });
}
性能优化阶段
- 避免在循环中进行异步操作：在 Workers 中，应该使用
Promise.all()批量处理异步操作，而不是在 for 循环中逐个 await：
// ❌ 错误：逐个等待
for (const id of ids) {
const result = await db.prepare('SELECT * FROM users WHERE id = ?').bind(id).first();
results.push(result);
}
// ✅ 正确：批量并发
const results = await Promise.all(
ids.map(id => db.prepare('SELECT * FROM users WHERE id = ?').bind(id).first())
);
- 使用流式响应处理大文件：对于需要返回大文件的 API，使用流式响应而不是一次性加载到内存：
export default {
async fetch(request, env, ctx) {
const file = await env.ASSETS.get('large-file.zip');
if (file) {
return new Response(file.body, {
headers: {
'Content-Type': 'application/zip',
'Content-Disposition': 'attachment; filename="large-file.zip"'
}
});
}
return new Response('Not Found', { status: 404 });
}
};
- D1 查询的性能陷阱：LIKE 查询和正则表达式在 D1 中的性能较差，应该尽量使用索引优化查询：
-- ✅ 正确：使用索引列的等值查询
SELECT * FROM users WHERE email = 'test@example.com';
-- ❌ 错误：模糊查询无法使用索引
SELECT * FROM users WHERE email LIKE '%@example.com%';
生产运维阶段
监控与告警：Cloudflare 提供了 Workers Metrics 和 Durable Objects Metrics，需要配置告警规则来监控错误率、CPU 使用率、延迟等关键指标。
版本回滚策略：使用 Wrangler 部署时会自动创建版本，可以随时回滚到之前的版本：
# 查看部署历史
npx wrangler versions list
# 回滚到指定版本
npx wrangler versions rollback --version-id <version-id>
- 密钥管理：敏感信息（如数据库密码、API 密钥）不要硬编码在代码中，应该使用 Cloudflare Workers Secrets：
# 添加密钥
npx wrangler secret put DATABASE_PASSWORD
# 输入密钥值
# 在代码中访问
const password = env.DATABASE_PASSWORD;
- 成本控制：Cloudflare Workers 的计费基于请求次数和 CPU 时间。在设计架构时，应该尽量减少不必要的请求（例如使用缓存），并优化代码以减少 CPU 时间消耗。
总结：边缘有状态计算的未来
Cloudflare Workers + Durable Objects + D1 的组合，代表了一种全新的后端架构范式：开发者不再需要关心服务器的运维、集群的扩展、数据的分片——这些全部由平台自动处理。开发者只需要专注于业务逻辑本身。
2026 年的几个关键升级进一步强化了这套架构的能力：
- Cloudflare OS 开创了"千人千面"SaaS 的新范式，让每个用户都可以运行自己定制化的应用副本
- Meerkat 的 QuePaxa 共识算法解决了边缘节点之间的全局协调问题，使得跨 Durable Object 的分布式操作成为可能
- D1 的持续优化使得边缘数据库的性能和功能都在快速迭代
对于开发者来说，这套技术栈的学习曲线并不陡峭——Workers 使用标准 JavaScript/TypeScript，D1 使用标准 SQL，Durable Objects 使用面向对象的 TypeScript 编程模型。如果你已经熟悉现代 Web 开发，这套技术栈的上手成本几乎为零。
但真正让这套架构发挥威力的，是对其设计理念的深刻理解：边缘计算不是将数据中心搬到用户附近，而是重新思考"状态"在分布式系统中的位置。当你不再需要维护中心化的数据库集群，当状态可以随着计算一起下沉到全球每个角落，我们看待系统架构的方式也将发生根本性的转变。
这种转变才刚刚开始。