Cloudflare OS实战：用Workers、Durable Objects、R2构建分布式应用-北京尧图网络

最近我把一个原本跑在自建服务器上的个人网盘重写了一遍整条链路搬到了 Cloudflare 的边缘平台上。代码量少了一大截运维基本归零延迟体验反而更稳了。圈子里有人把这种玩法直呼为 cloudflare-os一开始我还以为是哪个发行版起了个花名等我把 Workers、Durable Objects、R2、KV、Queues 这些服务拼起来之后才意识到这个叫法还真不是夸张——它确实能拼出一台完整逻辑的分布式操作系统只是你摸不到机箱只能摸到 API。这篇文章不是 Cloudflare 的官方产品说明就是一个把 Cloudflare 当 OS 用了小半年的工程笔记。文章会先讲清楚这套边缘计算机由哪些部件构成再带你把一个文件云盘 Demo 从零部署到线上最后重点说我在真实使用中踩到的坑、算过的账、以及决定什么时候该用它、什么时候不该硬上。适合正在做独立项目、玩过静态托管、又想往无服务器状态化应用方向走一步的开发者参考。1. cloudflare-os 是什么不是产品名而是一层被抽象掉的服务端架构先泼一盆冷水Cloudflare 官方没有发行过一个叫 cloudflare-os 的系统控制台里面也找不到安装操作系统的入口。这个说法实际上是开发者使用之后的直觉——当我把这家平台上的几类核心服务组合到一起时它在接口层面提供的完整度已经逼近了操作系统的抽象边界。把这个思路展开一下把 Cloudflare 当成一台放在云里的逻辑计算机。它的 CPU 是 Workers无服务器函数运行时只不过函数遍布在全球各地的边缘节点请求会就近执行。它的内存是 Durable Objects 加上 KV一个负责确定性的有状态协调一个负责全球复制的快速存取。它的磁盘是 R2S3 兼容的对象存储重点是没有出站流量费。再把 CDN 看作协处理器Pages 看作应用外壳Queues 看作进程间的消息队列Service Bindings 看作函数调用栈。所有组件之间通过 binding 互相调用开发者完全不关心服务跑在哪里、副本有几个、流量怎么切从使用者的视角看你手里就是一台有计算、有存储、有通信、有调度的云原生计算机。1.1 传统 OS 组件和 Cloudflare 服务的对应表我整理了一下自己常用的映射关系不一定严谨但作为设计框架非常实用传统系统组件Cloudflare 服务实际操作体验CPU / 用户进程Workers按请求计费全球节点就近执行不用关心进程调度内存 / 共享状态Durable Objects平台保证单实例一致性适合放 WebSocket 长连接和共享状态高速缓存KV全球复制的最终一致键值存储适合读多写少的配置和索引磁盘 / 文件系统R2S3 兼容对象存储REST API 直接读写适合放文件本体进程间通信Service Bindings / QueuesWorker 调 Worker或者通过队列做异步解耦显示器 / 桌面Pages CDN静态资源全球分发边缘渲染内核安全策略WAF / Access / 防火墙规则安全能力内置在边缘不用自己在服务器上配 iptables这张表是我架构设计时最常用的思维脚手架。遇到一个新需求第一步不是想我要买几台服务器而是先想这个需求到底属于 CPU、内存、磁盘还是通信然后才去选对应的服务。一旦习惯了这套框架你会发现自己已经很难回头去手动维护服务器了。1.2 这种抽象为什么值得认真对待过去搭应用基础设施的复杂度是逃不掉的跑几个实例、做负载均衡、数据库主从同步、对象存储迁移、备份策略……每一样都可能变成一个深夜问题。而 Cloudflare 这套伪 OS把大量分布式系统难题在平台层消化掉了向外暴露的是相对简单的 API。以我最看重的两点为例。第一伸缩粒度足够细。Workers 费按请求计流量大了自动扩容流量降为零时没有闲置成本。第二有状态能力被正式纳入了无服务器模型。Durable Objects 允许我用普通代码写一个只有一个实例的逻辑节点这打破了无服务器应用都是无状态的固有印象实时协作、在线广播这类需求处理起来自然了很多。当然这个抽象也会让人付出代价你不能随意控制底层比如固定的 IP、自定义内核参数、复杂的容器网络这些都不存在。所以在决定用 cloudflare-os 这套思路之前先想一下你是在做一个应用还是在做基础设施。如果是后者这套方案会显得有点拧巴如果是前者下面这套玩法几乎就是量身定做的。2. 先想清楚业务怎么拆我给云盘 Demo 定的模块边界在动手写代码之前我习惯先把业务拆成几个OS 资源。这次我做的 Demo 叫随手存定位是一个带实时同步功能的个人文件云盘用户可以把小文件上传到云端生成短链接分享给朋友同时在网页上能看到所有在线编辑状态的实时变化。需求拆下来大概是这几块文件本体存储和下载文件元数据、短链接映射、用户配置的保存HTTP API 网关负责路由、鉴权和参数校验实时状态推送比如谁正在编辑哪个文件下载完成通知前端静态界面和资源托管。逐项映射到 Cloudflare 生态需求模块技术选型选型理由文件存储R2有对象存储的一切优点没有出站流量费适合个人分享场景元数据索引KV读写延迟低全球复制适合存储短链接这类读多写少的数据API 网关Workers全球边缘路由请求进来立刻处理不用管服务器实时状态Durable Objects WebSocket用 DO 维护所有活跃连接广播状态变更前端托管Pages构建完成后直接推到边缘和 Worker 在同一套网络里2.1 为什么不用传统方案有人可能会问这么小的项目扔到一台 VPS 上装个 Nginx 加 SQLite不是更简单吗确实以前我大概率也会这么做。但这次选择 cloudflare-os 架构核心原因是想验证一个假设当一台逻辑计算机分布在全球时应用代码需不需要因此改变。实践下来的答案是变化比想象中小得多。对开发者来说代码关心的只是 Worker 如何处理请求、DO 如何存储状态、R2 如何管理对象至于请求落在东京还是法兰克福那是平台自动路由的事。我把机器从一台 VPS 换成了无限分布的抽象机服务架构基本不变但可用性和运维成本发生了质的改变。2.2 模块之间怎么通信模块划分好后通信方式也顺带定了。文件上传请求由 Worker 接收先做身份校验然后把文件二进制直接 PUT 到 R2再把短链接信息写入 KV。实时同步模块单独开一个 WebSocket 端点由 Durable Object 维护连接表任何人上传成功之后调用 DO 的一个方法广播通知在线网页立即刷新文件列表。这种拆法让每个模块的边界都特别清晰调试时也容易定位问题文件传不上是 R2 的 bucket 配置问题链接打不开是 KV 的 key 写错实时通知没收到是 DO 的连接没建立成功。逐项排查基本不会互相污染。3. 从零起跑把随手存的骨架部署到边缘现在进入实操环节。我会按我当时的开发顺序完整走一遍初始化、配置、写代码、部署的过程。3.1 环境初始化和依赖安装我用的工具是官方 CLI也就是 Wrangler。先安装并创建一个新项目npm install -g wrangler wrangler login npm create cloudflarelatest -- cloud-os-demo cd cloud-os-demo初始化过程中会让你选模板。我直接选了 TypeScript 的空模板这样核心业务代码类型安全后面维护起来舒服很多。项目结构大概是这样的cloud-os-demo/ ├── src/ │ ├── index.ts # Worker 入口路由按 URL 分发 │ ├── storage.ts # R2 和 KV 的操作封装 │ ├── realtime.ts # Durable Object 实现 │ └── types.ts # 公共类型定义 ├── wrangler.toml # 配置文件绑定各类资源 └── package.json3.2 在 wrangler.toml 里绑定存储资源这是 cloudflare-os 架构里设备驱动的一步。Workers 要访问 R2 和 KV必须在配置里显式声明绑定关系。控制台也可以操作但我更习惯用代码配置管理这样整个环境可以从 Git 恢复。name cloud-os-demo main src/index.ts compatibility_date 2024-11-01 [[kv_namespaces]] binding FILE_INDEX id 你的KV命名空间ID [[r2_buckets]] binding FILES bucket_name cloud-os-files [durable_objects] bindings [ { name SYNC_OBJECT, class_name SyncRoom } ] [[migrations]] tag v1 new_sqlite_classes [SyncRoom]这里有两个容易踩的细节。第一KV 和 R2 必须先到 Cloudflare 控制台或命令行创建好拿到 ID 再填进来凭空在 toml 里写名字不会自动创建。第二DO 类必须同时写进durable_objects和migrations两个地方否则部署时它会告诉你找不到这个类我第一次就漏了。3.3 Worker 入口路由、上传、下载、短链接我推荐的思路是入口文件只负责 URL 路由逻辑全部拆到独立模块。这样每个函数都短排查问题的时候思维负担小。下面是我当时写的核心入口做了一定简化import { handleUpload, handleDownload, handleList, handleShortlink } from ./storage; export default { async fetch(request: Request, env: Env): PromiseResponse { const url new URL(request.url); if (url.pathname.startsWith(/upload) request.method PUT) { return handleUpload(request, env); } if (url.pathname.startsWith(/download/)) { return handleDownload(request, env); } if (url.pathname.startsWith(/list)) { return handleList(request, env); } if (url.pathname.startsWith(/s/)) { return handleShortlink(request, env); } return new Response(Not Found, { status: 404 }); } };上传函数的核心逻辑是这样export async function handleUpload(request: Request, env: Env): PromiseResponse { const auth request.headers.get(Authorization); if (!isValidToken(auth)) { return new Response(Unauthorized, { status: 401 }); } const filename decodeURIComponent(new URL(request.url).pathname.split(/)[2]); const object await env.FILES.put(filename, request.body, { httpMetadata: { contentType: request.headers.get(Content-Type) || application/octet-stream, }, }); const shortId crypto.randomUUID().slice(0, 8); await env.FILE_INDEX.put(shortId, JSON.stringify({ filename, size: object.size, etag: object.httpEtag, createdAt: new Date().toISOString(), })); return Response.json({ shortId, filename, size: object.size }); }这里我特意做了两件事。第一文件本体只进 R2KV 里只放短链接和元数据避免把 KV 当成大文件仓库去用。第二所有写操作都显式返回了对象的大小和 ETag前端拿到后可以直接展示上传成功 2.4MB这类反馈不需要后端再查一次。下载函数就反过来先查 KV 拿元数据再读 R2 流式返回export async function handleDownload(request: Request, env: Env): PromiseResponse { const shortId new URL(request.url).pathname.split(/)[2]; const meta await env.FILE_INDEX.get(shortId); if (!meta) { return new Response(Link not found, { status: 404 }); } const { filename } JSON.parse(meta); const object await env.FILES.get(filename); if (!object) { return new Response(File missing, { status: 404 }); } const headers new Headers(); object.writeHttpMetadata(headers); headers.set(etag, object.httpEtag); return new Response(object.body, { headers }); }R2 的writeHttpMetadata是神器它会把对象创建时存进去的 Content-Type、Content-Length、Cache-Control 这些元数据自动写进响应头省掉了一堆手工拼 Headers 的活。3.4 本地测试和部署上线的完整命令序列配置和代码都写好之后我习惯先用本地模式跑一遍npx wrangler dev --port 8787这个命令会启动一个本地边缘模拟环境KV、R2 都会在本地有一份临时实现可以反复做上传下载测试完全免费、完全隔离。确认无误后部署就一行命令的事npx wrangler deploy部署完成后你会拿到一个*.workers.dev子域名直接把 curl 打到这个域名上验证即可curl -X PUT -H Authorization: Bearer test-token --data-binary demo.txt https://你的worker域名/upload/demo.txt curl https://你的worker域名/s/短链接ID到这一步一个可以被全球访问的文件云盘骨架就已经跑通了。剩下的是实时在线层这是 cloudflare-os 架构里和其他传统托管方案拉开差距的地方。4. 让云盘活起来用 Durable Object 管实时状态和长连接很多网盘只能被动存取文件我希望它有一个在线协作感当一个文件被上传或者被删除时所有打开着网页的人应该立刻看到变化。实现这个效果最直接的技术就是 WebSocket 长连接而连接状态放哪里恰恰是架构的分水岭。4.1 为什么全局变量是死路DO 才是正解很多人第一次写 Worker 时都试过在全局作用域放变量然后在不同请求间共享。这在 worker 上下文里是不靠谱的因为一个 Worker 可能有很多隔离实例在同时跑不同实例之间全局变量完全不相通。就算在同一台物理机上平台也不会保证你的所有请求都命中同一个实例。Durable Object 解决的就是这个问题。它的核心模型是每个 DO 都有唯一的名字平台保证同名 DO 全局永远只有一个活跃实例所有路由到它的请求都回到同一个对象。这样我的代码完全可以放心地在对象属性里保存连接列表这就是分布式系统里的共享内存。4.2 实现一个带心跳的广播房间下面这段代码是实时同步的核心我简化为一个同步房间import { DurableObject } from cloudflare:workers; type ClientState { name: string; ws: WebSocket; }; export class SyncRoom extends DurableObject { private clients new Mapstring, ClientState(); async fetch(request: Request): PromiseResponse { const url new URL(request.url); if (url.pathname /connect) { const pair new WebSocketPair(); const [client, server] Object.values(pair); this.ctx.acceptWebSocket(server); this.clients.set(crypto.randomUUID(), { name: anonymous, ws: server }); server.send(JSON.stringify({ type: welcome, count: this.clients.size })); return new Response(null, { status: 101, webSocket: client }); } if (url.pathname /broadcast) { const payload await request.json(); for (const { ws } of this.clients.values()) { ws.send(JSON.stringify({ type: event, ...payload })); } return Response.json({ ok: true }); } return new Response(Not Found, { status: 404 }); } async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promisevoid { const parsed JSON.parse(message as string); if (parsed.type heartbeat) { ws.send(JSON.stringify({ type: pong })); return; } for (const { ws: other } of this.clients.values()) { if (other ! ws) { other.send(JSON.stringify({ type: chat, data: parsed.data })); } } } async webSocketClose(ws: WebSocket): Promisevoid { this.clients.delete([...this.clients].find(([, c]) c.ws ws)?.[0] || ); } }这里有个很关键的细节我没用this.ctx.moveIn这类的复杂 API而是直接利用fetch返回101升级 WebSocket 协议同时用ctx.acceptWebSocket(server)把连接托管给 Cloudflare 运行时。这样连接断线、重连、心跳都由平台帮忙处理基础部分我只需要维护业务状态。4.3 把 DO 接进 Worker 路由DO 写完后还需要在 Worker 入口加一行路由让请求能转发到 DO 实例if (url.pathname.startsWith(/rt/)) { const roomId url.pathname.split(/)[2] || default; const id env.SYNC_OBJECT.idFromName(roomId); const stub env.SYNC_OBJECT.get(id); return stub.fetch(request); }idFromName是 DO 的寻址方式。同一个房间名字永远路由到同一个实例不同房间名字会创建不同实例。现在每次上传文件成功时只需要用一个普通的 HTTP 请求打到/rt/default/broadcast所有在线连接都会收到有新文件的消息前端收到后就可以自动刷新列表。5. 别急着把流量切过来我先说清这套架构的真实边界把项目往生产推或者准备长期使用之前有四个维度你必须心里有数。这不是劝退而是我在真实流量下遇到的问题提前知道能让你的切换过程顺滑很多。5.1 KV 不是实时数据库它是最终一致的KV 最大的特点是全球复制、读取轻快但它不是强一致性数据库。一个 key 写入之后理论上可能需要一些时间才能在所有边缘节点看到新值。对短链接分享这种读多写少的场景这个特性完全不是问题但如果你把 KV 当会话状态来用写入后立刻回读并依赖那个值做鉴权就会踩到漂移的坑。我的经验是凡是写完必须马上读到的数据要么放进 Durable Object 属性里要么放进 R2 的对象元数据里KV 只放允许最终一致的数据。代码结构设计时数据的性质决定存储位置不要所有数据一股脑塞 KV。5.2 R2 适合存整文件不适合做随机小片写R2 是对象存储它的接口语义是整个对象 PUT 一次、GET 一次。我的网盘场景里每次上传都是完整文件所以非常合适但如果你想拿 R2 当数据库频繁改写一个大对象的一小段R2 会逼你先读回整个对象再整体覆盖这既浪费流量也带来并发覆盖的风险。真要做随机写建议把大文件拆成多个 5MB 以上的对象块用 KV 存块索引或者干脆把需要随机读写的结构化数据放到 DO 的存储里。R2 的边界就是对象粒度的读写别拿它跟本地文件系统的 seek 能力比。5.3 Worker 的执行时间不是无限大的虽然 Workers 可以跑复杂逻辑但它终归是一个请求处理模型。我刚迁移项目时把一段对图片做重处理的逻辑放在了请求链路里结果在边缘节点上执行到一半就因为 CPU 超时被平台掐断。后来我把重活改成了 Queues 异步处理上传请求只负责快速落盘处理完成后再通过队列回调更新状态整体体验就顺了。这个教训很通用只要是超过一两秒的同步计算都该从 Worker 请求路径里挪出来。对于极重负载的 CPU 任务Cloudflare 这边合理的做法依然是拆小、异步、交给 Queues 或者专门的 ETO 调用而不是指望一次请求把所有活都干完。5.4 计费账单要按操作次数而不是按流量算Cloudflare 这套生态的计费逻辑很不同。以 R2 为例它不收取出站流量费这让我这种分享场景特别舒服但它对 A 类操作写入和 B 类操作读取分别计量而且设置了一个很低的免费阈值。个人项目跑到后期文件一多光是每天的健康检查、列表刷新产生的读操作就可能把免费额度吃光。我给自己的方案是给所有列表接口加上 CDN 缓存头让浏览器和边缘节点自动缓存响应后台任务减少无意义的探测请求列表接口用游标分页一次只取 20 条。账单压力立马降了下来。网上很多吐槽Cloudflare 咋还收费了的情况大概率是没意识到操作次数和缓存策略对成本的影响。5.5 本地跑得好好的上云就出问题多半是绑定环境不对还有一个让我折腾过一下午的问题同一个 Worker本地wrangler dev测试一切正常一部署到线上部分接口返回 500。排查了半天发现是我本地环境变量里多写了一个PREVIEW_BRANCH的绑定生产环境没有这个变量代码里又没做空值判断导致取配置时抛了异常。从此我给自己定了个规矩代码里读任何绑定值之前一律先做默认值兜底。无论是env.FILE_INDEX、env.FILES还是自定义变量都假设它可能在某个环境里不存在然后写一个安全的取值函数。这条习惯救了我好几次至少不会让生产环境因一个缺失变量直接白屏。6. 什么时候值得用 cloudflare-os 这套思路什么时候该绕开到这一步我不打算给你一份标准答案因为技术选型本来就跟具体场景绑定。但我可以把我的判断标准拿出来供你参考。6.1 适合用的情况如果你的项目满足下面任意一条我都觉得可以认真考虑用这套架构项目规模是个人工具、小团队内部系统不想为基础设施运维投入精力应用天然是全球访问的希望用户基本能就近获取内容而不是统一绕回一个地区机房需求里有实时协作、在线推送这类长连接共享状态但不想单独维护 WebSocket 网关集群对成本敏感希望低频使用时不花钱波动流量来了又能自动扛住想要 DDoS 防护、WAF 规则、SSL 证书这些安全能力开箱即用而不是自己一个个装。6.2 不适合硬上的情况反过来也有几类问题我劝你先别套 cloudflare-os强依赖固定 IP 的出站任务比如你要从某个白名单 API 拉数据对方只认固定 IP这套边缘架构很难满足需要托管大规模的机器学习模型推断或者使用 GPU 进行长时间计算这超出了 Workers 的模型边界有海量的随机小文件写入和强事务需求比如传统 OLTP 数据库的核心业务把状态全塞进 DO 或 KV 反而会放大架构难度对供应商锁定极度敏感希望所有代码能一键迁移到自建机房那无服务器绑定越深迁移成本越高。Cloudflare 生态锁定的不只是代码还有你设计架构时的思维习惯。6.3 我自己的实践收束如果开始用这套架构建议先把代码和资源分开对待坚持用wrangler.toml管理绑定把整个环境配置放进 Git所有业务逻辑保持模块化让核心代码只依赖接口而不依赖具体平台的 SDK最后再给每个模块补上监控和日志埋点。做完这几个基础动作之后你会发现 cloudflare-os 这种形态并不神秘它无非是把一台逻辑计算机拆成了网络、计算、存储、状态这几层然后把每一层的选型权交给了开发者。第一次跑通全家桶时我最深的感触反而不是它有多省事而是原来运维这两个字真的可以被平台抽象到刷新一下浏览器就能完成的程度。如果你正在折腾个人项目这套方案值得给自己一周时间亲手试一次。

Cloudflare OS实战：用Workers、Durable Objects、R2构建分布式应用

相关推荐

iPhone笔记误删恢复：7种实用方法与技术解析

系统数据库深度解析：权限体系、元数据管理与故障排查实战

系统数据库权限、元数据与故障排查实战指南

更多资讯

职业院校数字媒体实训室建设方案与实施经验

鼠标驱动下载与安装全流程：从型号识别到故障排查

impeccable 实战：用 CLI 与浏览器扩展治理 AI 生成前端代码的设计质量

cloudflare-os 深度解析：基于 Workers 的 AI Agent 编排框架实战

Cloudflare Workers 上跑 AI 应用：cloudflare-os 架构拆解与实操指南

cloudflare-os 实战：用 Workers 搭建边缘 AI Agent 的工程化模板

今日更新

微信个人号API开发案例：图片/语音/视频消息怎么下载解析存到本地？

Python股票自动交易系统源码解析：从行情获取到风控的完整链路

视酷酷信IM源码部署指南：Java 17+MySQL 8.0.33实战配置

本周精选

防幻觉智能体架构：电源硬件设计中的大模型编排与工具化实践

OpenGL面试核心考点：渲染管线、矩阵变换与性能排查全解析

全国计算机二级C语言真题PDF高效刷题指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？