Cloudflare Workers 实战：从零搭建边缘优先的个人 AI 工作台

1. 从标题到落地：cloudflare-os 到底是个什么东西

第一次看到cloudflare-os这个标题，很多人会下意识以为 Cloudflare 出了个操作系统，或者是个能装在自己电脑上的 Linux 发行版。我一开始也是这么想的，直到把仓库拉下来跑了一遍，才发现它跟传统意义上的 OS 完全是两码事。它更像是一个“跑在 Cloudflare Workers 上的个人工作台”，把 AI 对话、笔记、任务管理、文件索引这些日常高频操作，全部塞进一个由 Worker 驱动的单页应用里，前端静态资源托管在 Cloudflare 的全球边缘节点上，后端逻辑用 Workers 承载，数据落到 D1 或者 KV 里。

这个项目的核心价值在于：它把“个人数字工作台”这件事的部署成本压到了几乎为零。你不需要买服务器，不需要配 Nginx，不需要折腾 Docker，只要有一个 Cloudflare 账号，装好pnpm和wrangler，几条命令下去，一个属于你自己的、带 AI 能力的在线工作台就上线了。它解决的是那种“我想有个自己的小工具站，但不想为了它专门维护一台机器”的痛点。适合谁看？适合那些对 Cloudflare Workers 生态感兴趣、想拿一个真实项目练手的前端或全栈开发者，也适合想给自己搭一个轻量级 AI 入口、又不想被各种平台绑死的独立开发者。

我把它定位成一个“边缘优先的个人应用模板”。你既可以把它当成成品直接用，也可以把它当成一个脚手架，把里面的 AI 对话模块换成自己的业务逻辑，把笔记模块换成自己的数据源。理解了这一点，后面所有的技术选型和操作步骤就都顺了。

2. 整体架构与选型逻辑拆解

2.1 为什么是 Workers 而不是传统服务器

传统做法是买一台 VPS，装 Node，跑一个 Express 或者 Next.js 的服务端，再配个数据库。这套流程我走过无数遍，稳定是稳定，但有几个绕不开的问题：第一，机器要续费，哪怕你一个月只用几次；第二，系统要维护，安全补丁、依赖升级、证书续期，全是隐性成本；第三，冷启动和地域延迟，你在国内访问一台美西的机器，首屏体验很难做好。

Cloudflare Workers 的思路完全不同。它把你的代码编译成 V8 的 isolate，直接跑在全球几百个边缘节点上。用户请求进来，最近的节点直接执行，没有传统意义上的“服务器”概念。对于cloudflare-os这种以读为主、写操作不密集的个人应用来说，这个模型非常合适。静态资源走 Cloudflare 的 CDN，API 走 Worker，数据库用 D1（基于 SQLite 的分布式数据库）或者 KV（键值存储），整套下来没有一处需要你操心运维。

注意：Workers 有 CPU 时间限制，免费版单次请求的 CPU 时间上限是 10ms，付费版是 30s（可配置到更高）。这意味着你不能在 Worker 里跑那种重计算的同步任务，比如大文件解析或者复杂加密。cloudflare-os里所有 AI 调用都是走异步 fetch，把重活交给外部 API，这个设计是必须的，不是可选的。

2.2 pnpm 和 wrangler 的分工

pnpm在这个项目里负责依赖管理。相比 npm 和 yarn，pnpm 用硬链接加符号链接的方式组织node_modules，磁盘占用小，安装速度快，而且对 monorepo 的支持更干净。cloudflare-os的依赖树不算特别深，但如果你打算在它基础上扩展，比如加一个 UI 组件库或者状态管理库，pnpm 的优势就会体现出来。

wrangler是 Cloudflare 官方的 CLI 工具，负责本地开发、构建、部署、查看日志、管理 D1 和 KV 绑定。你可以把它理解成“Workers 世界的 npm scripts 加部署工具”。项目里通常会有wrangler.toml或wrangler.jsonc配置文件，里面定义了 Worker 的名称、入口文件、兼容性日期、环境变量、D1 绑定、KV 绑定等。部署的时候，wrangler deploy会把你的代码打包上传，Cloudflare 自动分发到边缘节点。

这里有个容易踩的坑：wrangler的版本和 Workers 运行时的兼容性日期是绑定的。如果你在wrangler.toml里写的compatibility_date太老，一些新的 API（比如fetch的某些行为、crypto的新方法）可能不可用；写得太新，又可能遇到刚发布还没稳定的特性。我的经验是，选一个比你当前日期早两到三个月的日期，既不会太旧，也避开了最新版本的潜在 bug。

2.3 AI 模块的接入方式

cloudflare-os里的 AI 能力，通常是通过 Worker 转发请求到某个大模型 API 来实现的。这里有两种常见做法：一种是在 Worker 里直接fetch外部 API，把 API Key 存在 Worker 的环境变量里；另一种是用 Cloudflare 自己的 AI Gateway 或者 Workers AI。前者灵活，可以接任何兼容 OpenAI 接口的服务；后者省事，但模型选择受限于 Cloudflare 提供的列表。

从项目标题和热词来看，cloudflare-os更倾向于第一种做法，因为它要的是一个“OS”级别的整合体验，而不是绑定某一家模型。Worker 在这里扮演的是代理和编排的角色：接收前端请求，拼装 prompt，调用模型，处理流式返回，再把结果推回前端。这个过程中，Worker 不存储对话内容（除非你显式写入 D1 或 KV），所以隐私边界比较清晰。

提示：如果你打算把 API Key 放在 Worker 环境变量里，记得用wrangler secret put命令，而不是写在wrangler.toml里。前者是加密存储，后者是明文，部署后可以在 Cloudflare 控制台看到。这个细节很多人第一次做的时候会忽略。

3. 核心细节解析与实操要点

3.1 环境准备：pnpm 安装与常见报错处理

在 Windows 上装 pnpm，最稳的方式是用 Corepack。Node.js 16.13 之后自带 Corepack，你只需要在管理员权限的终端里执行：

corepack enable corepack prepare pnpm@latest --activate

如果你看到pnpm : 无法将“pnpm”项识别为 cmdlet、函数、脚本文件或可运行程序的名称，大概率是 Corepack 没有启用，或者 pnpm 的全局 bin 目录不在 PATH 里。这时候可以先跑corepack enable，然后关掉终端重新开一个。如果还不行，用npm install -g pnpm兜底，虽然不如 Corepack 干净，但能快速解决问题。

在 Ubuntu 上，除了 Corepack，还可以用官方脚本：

curl -fsSL https://get.pnpm.io/install.sh | sh -

装完之后source ~/.bashrc或者重开终端。如果遇到pnpm安装失败或者pnpm下载失败，先检查网络能不能通到 registry，再检查 npm 的 registry 配置是不是被改成了某个内网地址。pnpm config get registry看一下，正常应该是https://registry.npmjs.org/。

对于离线环境，pnpm 支持pnpm fetch和pnpm install --offline。你可以在有网的机器上跑pnpm fetch把依赖包下载到本地的 store 里，然后把整个 store 目录拷到离线机器上，再跑pnpm install --offline。这个流程我在内网项目里用过很多次，比 npm 的离线方案顺手。

3.2 wrangler 初始化与项目结构

拿到cloudflare-os的代码之后，第一件事是确认wrangler的版本。在项目根目录跑：

pnpm dlx wrangler --version

如果项目package.json里已经声明了wrangler作为 devDependency，直接pnpm install然后pnpm exec wrangler --version就行。版本对不上的话，wrangler.toml里的一些配置项可能会报未知字段的警告。

典型的cloudflare-os项目结构大概是这样：

cloudflare-os/ ├── src/ │ ├── index.ts # Worker 入口 │ ├── routes/ # API 路由 │ ├── ai/ # AI 调用封装 │ └── db/ # D1 查询封装 ├── public/ # 静态资源 ├── wrangler.toml # Worker 配置 ├── package.json └── pnpm-lock.yaml

wrangler.toml里最关键的是这几项：

name = "cloudflare-os" main = "src/index.ts" compatibility_date = "2024-xx-xx" [vars] ENVIRONMENT = "production" [[d1_databases]] binding = "DB" database_name = "cloudflare-os-db" database_id = "xxxxxxxx" [[kv_namespaces]] binding = "KV" id = "xxxxxxxx"

compatibility_date我一般设成当前日期往前推两个月。d1_databases和kv_namespaces的database_id和id需要你先在 Cloudflare 控制台或者用wrangler d1 create和wrangler kv:namespace create创建好，再把返回的 ID 填进来。

注意：wrangler.toml里的vars是明文环境变量，适合放一些不敏感的标志位。API Key、数据库密码这类东西，一律用wrangler secret put KEY_NAME来设置。部署之后，在 Cloudflare 控制台的 Worker 设置里能看到 secret 列表，但看不到值，这是正确的行为。

3.3 D1 数据库的初始化与迁移

D1 是 Cloudflare 的 SQLite 托管服务。cloudflare-os如果涉及笔记、任务、对话历史，大概率会用 D1 来存。初始化流程是：

wrangler d1 create cloudflare-os-db

把返回的database_id填到wrangler.toml里。然后写迁移文件，比如migrations/0001_init.sql：

CREATE TABLE IF NOT EXISTS notes ( id TEXT PRIMARY KEY, content TEXT NOT NULL, created_at INTEGER NOT NULL ); CREATE TABLE IF NOT EXISTS conversations ( id TEXT PRIMARY KEY, title TEXT, messages TEXT NOT NULL, updated_at INTEGER NOT NULL );

本地开发时，用：

wrangler d1 migrations apply cloudflare-os-db --local

部署到线上时，去掉--local：

wrangler d1 migrations apply cloudflare-os-db

这里有个实操心得：D1 的本地模拟和线上行为在大多数情况下一致，但涉及AUTOINCREMENT、RETURNING子句、以及某些日期函数时，可能会有细微差别。我习惯在本地跑通之后，先在线上建一个测试库验证一遍，再切到正式库。另外，D1 的写入有每秒请求数限制，个人应用完全够用，但如果你要做批量导入，最好分批提交，每批不超过几百条。

3.4 AI 调用的流式处理

cloudflare-os的 AI 对话体验，核心在于流式返回。Worker 收到前端请求后，向模型 API 发起fetch，拿到ReadableStream，然后通过TransformStream把数据转发给前端。前端用EventSource或者fetch加ReadableStream来接收。

Worker 侧的简化代码大概是这样：

export default { async fetch(request: Request, env: Env) { const { prompt } = await request.json(); const aiResponse = await fetch('https://api.example.com/v1/chat/completions', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${env.AI_API_KEY}`, }, body: JSON.stringify({ model: 'gpt-4o-mini', messages: [{ role: 'user', content: prompt }], stream: true, }), }); return new Response(aiResponse.body, { headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive', }, }); }, };

这段代码的关键点在于：直接把上游的body透传给前端，Worker 不做缓冲。这样首字节到达时间最短，用户体验最好。但要注意，如果上游 API 返回的是 SSE 格式，前端解析的时候要按data:前缀来切分，遇到[DONE]就结束。

提示：Workers 的免费版对请求时长有限制，流式响应如果超过一定时间可能会被中断。如果你的模型响应特别慢，考虑在 Worker 里加一个超时控制，或者把长对话拆成多轮短请求。我实测下来，单次响应在 30 秒以内的流式对话，免费版基本能撑住。

4. 完整实操流程：从零到上线

4.1 第一步：克隆项目与依赖安装

假设你已经有了 Node.js 18 以上和 pnpm，第一步是拉代码：

git clone <cloudflare-os-repo-url> cd cloudflare-os pnpm install

如果pnpm install卡住或者报错，先检查.npmrc文件。有些项目会在这里配registry或者shamefully-hoist。如果pnpm-lock.yaml和package.json不一致，pnpm 会提示你跑pnpm install --no-frozen-lockfile。这个在开发阶段没问题，但部署前最好把 lockfile 固定下来，避免线上装到不同版本的依赖。

安装完成后，跑一下pnpm run dev或者pnpm exec wrangler dev，看看本地能不能起来。wrangler dev默认会在http://localhost:8787起一个本地 Worker 模拟环境，支持热重载。如果端口被占用，用--port指定别的端口。

4.2 第二步：配置 Cloudflare 账号与认证

在部署之前，需要让wrangler知道你要部署到哪个账号。跑：

pnpm exec wrangler login

这会打开浏览器，让你授权。授权完成后，wrangler whoami可以确认当前登录的账号。如果你有多个 Cloudflare 账号，用wrangler login --scopes account:read user:read之类的参数控制权限范围，或者用CLOUDFLARE_API_TOKEN环境变量来指定 token。

注意：在 CI/CD 环境里，不要用wrangler login，而是创建一个 API Token，权限至少包含Workers Scripts:Edit、D1:Edit、KV:Edit。然后把 token 存到 CI 的 secret 里，用CLOUDFLARE_API_TOKEN环境变量传给 wrangler。这个做法比账号密码安全得多。

4.3 第三步：创建 D1 和 KV 资源

按照前面 3.3 的步骤，创建 D1 数据库和 KV 命名空间。创建 KV 的命令是：

wrangler kv:namespace create "KV"

返回的id填到wrangler.toml的[[kv_namespaces]]里。如果你需要预览环境的 KV，还要加一个preview_id。

D1 和 KV 都创建好之后，跑一遍迁移：

wrangler d1 migrations apply cloudflare-os-db --local wrangler d1 migrations apply cloudflare-os-db

本地和线上各跑一次。线上跑的时候，wrangler 会提示你确认，输入y继续。

4.4 第四步：设置环境变量与 Secret

把 AI API Key 设成 secret：

wrangler secret put AI_API_KEY

终端会提示你输入值，粘贴进去回车。同样的方式设置其他敏感变量，比如DATABASE_URL（如果用外部数据库的话）。

非敏感的变量，比如AI_MODEL、MAX_TOKENS，可以放在wrangler.toml的[vars]里：

[vars] AI_MODEL = "gpt-4o-mini" MAX_TOKENS = "2048"

提示：wrangler.toml里的vars在本地开发时可以通过env对象访问，部署后也一样。但如果你在wrangler.toml里定义了同名的 secret，secret 会覆盖vars。这个优先级关系要记清楚，不然调试的时候会困惑为什么改了vars不生效。

4.5 第五步：本地验证与部署

本地跑wrangler dev，打开浏览器访问http://localhost:8787，把主要功能过一遍：AI 对话能不能流式返回，笔记能不能存进 D1，刷新之后数据还在不在。本地 D1 的数据存在.wrangler/state目录下，删掉这个目录就相当于重置本地数据库。

本地没问题之后，部署：

pnpm exec wrangler deploy

部署完成后，wrangler 会输出一个https://cloudflare-os.<your-subdomain>.workers.dev的 URL。用这个 URL 在浏览器里再验证一遍。如果自定义域名，在 Cloudflare 控制台的 Worker 设置里加 Custom Domain，或者用 Routes 把某个路径映射到这个 Worker。

4.6 第六步：绑定自定义域名与 HTTPS

Workers 默认提供workers.dev子域名，但很多人想用自己的域名。在 Cloudflare 控制台里，进入你的 Worker，点“Settings” -> “Domains & Routes” -> “Add Custom Domain”，输入你的域名，比如os.example.com。Cloudflare 会自动处理 DNS 记录和 SSL 证书，通常几分钟内生效。

如果你想把 Worker 挂在某个路径下，比如example.com/os/*，用 Routes 而不是 Custom Domain。Routes 的匹配规则支持通配符，配置在wrangler.toml里：

routes = [ { pattern = "example.com/os/*", zone_name = "example.com" } ]

这样访问example.com/os/就会打到这个 Worker 上。

5. 常见问题与排查技巧实录

5.1 pnpm 相关报错速查

5.2 wrangler 部署常见错误

wrangler deploy报Error: No account_id found，说明没有登录或者 API Token 没设对。跑wrangler whoami确认。如果是在 CI 里，检查CLOUDFLARE_API_TOKEN和CLOUDFLARE_ACCOUNT_ID两个环境变量是不是都设了。

报Error: Script startup exceeded CPU time limit，说明 Worker 的启动逻辑太重。检查src/index.ts的顶层代码，有没有在模块加载时就跑复杂计算或者同步 IO。把那些逻辑挪到fetch处理函数内部，或者改成懒加载。

报Error: D1_ERROR: no such table，说明迁移没跑或者跑到了错误的数据库。确认wrangler.toml里的database_id和你在控制台看到的一致，然后重新跑wrangler d1 migrations apply。

5.3 AI 对话不返回或中断

如果前端一直转圈，Worker 日志里看到fetch超时，先检查 API Key 有没有设对。用wrangler tail可以实时看 Worker 的日志输出，包括console.log和未捕获的异常。这个命令在调试时非常有用，比在控制台翻日志快得多。

如果流式返回中途断掉，可能是 Workers 的响应时长限制。免费版对fetch到上游的等待时间有限制，具体数值 Cloudflare 没有公开，但实测在 30 秒左右。解决办法是把长响应拆成多个短请求，或者升级到付费版。

提示：wrangler tail默认只显示当前部署的日志。如果你在本地wrangler dev，日志直接打在终端里，不需要tail。线上调试时，wrangler tail --format pretty比默认的 JSON 格式好读很多。

5.4 数据持久化与备份

D1 的数据虽然由 Cloudflare 托管，但定期备份是个好习惯。用：

wrangler d1 export cloudflare-os-db --output backup.sql

导出的 SQL 文件可以存到本地或者对象存储里。恢复的时候，用wrangler d1 execute cloudflare-os-db --file backup.sql。注意，execute是逐条执行，如果文件很大，可能会超时。大文件建议拆成多个小文件分批执行。

KV 的备份没有官方的一键导出命令，但可以用wrangler kv:key list列出所有 key，再逐个get出来。如果 KV 里存的是对话历史这类结构化数据，更好的做法是同时写一份到 D1，用 D1 做备份源。

6. 扩展思路：把 cloudflare-os 改成你自己的东西

6.1 替换 AI 模块为多模型路由

cloudflare-os默认可能只接一个模型。你可以把src/ai/里的调用逻辑改成路由模式：根据请求里的model字段，转发到不同的上游 API。比如gpt-4o-mini走一家，claude-3-haiku走另一家。Worker 里维护一个模型到 endpoint 的映射表，从环境变量里读 API Key。

这样做的好处是，你可以在前端加一个模型选择器，让用户自己选。对于个人工作台来说，不同任务用不同模型，成本和效果都能兼顾。实现上，把fetch的 URL 和 headers 动态化就行，核心的流式透传逻辑不用改。

6.2 加一个简单的 RAG 检索

如果你想让 AI 能回答关于你笔记内容的问题，可以在 Worker 里加一个轻量级的 RAG 流程。用户提问时，先用关键词从 D1 里检索相关笔记，把笔记内容拼到 prompt 的 system message 里，再发给模型。D1 支持LIKE查询和FTS5全文索引，对于几千条笔记的规模，性能完全够用。

FTS5 的迁移 SQL 大概是这样：

CREATE VIRTUAL TABLE notes_fts USING fts5(content, content='notes', content_rowid='rowid');

然后在插入笔记时同步更新 FTS 表。查询的时候用SELECT * FROM notes_fts WHERE notes_fts MATCH ?。这个方案比上向量数据库简单得多，适合个人项目。

6.3 用 Cron Triggers 做定时任务

Workers 支持 Cron Triggers，可以定时触发 Worker。你可以用它来做每日总结、定时清理过期数据、或者定时拉取某个 RSS 源更新到 D1 里。配置在wrangler.toml里：

[triggers] crons = ["0 8 * * *"]

然后在 Worker 的scheduled处理函数里写逻辑。注意，Cron Triggers 触发的 Worker 没有 HTTP 请求上下文，不能直接返回 Response，只能做后台任务。执行时间限制和普通请求一样，所以别在里面跑太重的活。

6.4 前端静态资源的优化

cloudflare-os的前端如果是用 Vite 或者类似工具构建的，构建产物放在public/或者dist/目录。Workers 可以通过[site]配置来托管静态资源：

[site] bucket = "./dist"

这样 Worker 会自动把静态资源请求和 API 请求分开处理。静态资源走 CDN 缓存，API 走 Worker 逻辑。如果你用的是 Workers Sites 的替代方案（比如 R2 加 Worker 路由），配置会稍微复杂一点，但灵活性更高。

提示：静态资源的缓存策略在wrangler.toml里可以通过[site]的entry-point和缓存规则来控制。默认情况下，Cloudflare 会对静态资源做边缘缓存，但 HTML 文件通常不缓存或者缓存时间很短。如果你更新了前端但用户看到的还是旧版本，检查一下缓存头设置。

7. 一些踩坑之后的个人体会

这个项目我前前后后折腾了大概两周，中间踩的坑主要集中在三个地方：pnpm 的环境配置、wrangler 的 secret 管理、以及 D1 的本地和线上行为差异。pnpm 的问题基本都是一次性的，配好之后就不用再管。wrangler 的 secret 管理，我建议在项目初期就把所有敏感变量用wrangler secret put设好，不要图省事写在wrangler.toml里，不然后面迁移或者分享代码的时候还要专门清理。

D1 的本地模拟虽然方便，但我在做全文检索的时候发现，本地 SQLite 的 FTS5 版本和线上 D1 的版本有细微差别，某些 tokenizer 的行为不一致。后来我养成了一个习惯：任何涉及数据库 schema 或者查询逻辑的改动，先在线上建一个测试库跑一遍，确认没问题再动正式库。这个习惯帮我省了不少回滚的麻烦。

还有一个细节是 Workers 的compatibility_date。我一开始设了一个比较新的日期，结果wrangler dev本地跑得好好的，部署到线上就报某个 API 不存在。后来查文档才发现，线上边缘节点的运行时版本更新有延迟，新日期对应的特性可能还没全量铺开。把日期往回退了两个月，问题就消失了。所以如果你遇到“本地能跑线上不行”的情况，先检查compatibility_date。

最后分享一个小技巧：wrangler dev支持--remote参数，可以让本地开发直接连线上的 D1 和 KV。这个在调试数据相关的问题时特别有用，因为你可以用本地的前端代码操作线上的真实数据，不用反复部署。但用的时候要小心，别在--remote模式下跑迁移或者删除操作，不然线上数据就没了。我一般只在只读调试的时候用这个模式。