OpenConnector 部署到 Cloudflare Workers:完整实战指南(D1 + R2/KV + Static Assets)
OpenConnector 部署到 Cloudflare Workers:完整实战指南(D1 + R2/KV + Static Assets)
本指南以 OpenConnector 官方部署文档 docs/cloudflare.md 为核心骨架,系统讲解如何把 OpenConnector 元数据与运行时状态网关部署到 Cloudflare Workers 平台:从架构组件、前置条件、本地预览到远程上线的每一步命令,再到运行时行为、响应压缩与配置项的全景剖析。读完本文,你将能够独立完成 OpenConnector 的 Cloudflare 端到端部署,理解 D1、R2、Workers KV、Static Assets 四类资源的协作方式,并掌握 SaaS OAuth 部署与 cron 触发清理的关键陷阱。
一、部署架构:四类 Cloudflare 资源各司其职
OpenConnector 将 Cloudflare Workers 作为**元数据(metadata)与运行时状态(runtime-state)**的部署目标。根据 docs/cloudflare.md 与示例配置 wrangler.example.jsonc,整个 Worker 运行时由四类资源构成:
| 资源 | 职责 |
|---|---|
| Workers | 承载 HTTP 运行时,处理所有请求 |
| D1 | 存放 connections、OAuth 配置/状态、runtime tokens、run logs、Action 幂等记录 |
| R2 或 Workers KV | 存放临时中转文件(transit files),二选一 |
| Static Assets | 托管 Web Console 前端 |
从 wrangler.example.jsonc 可以看到,入口文件为 src/server/cloudflare.ts,使用 nodejs_compat 兼容标志,D1 通过 DB 绑定接入且 migrations_dir 指向仓库根目录下的 migrations 目录(0010 之后的迁移与 PostgreSQL 版同源,见 migrations/postgresql/0015_saas_cleanup_runtime.sql 等文件)。
Web 控制台静态资源通过 ASSETS 绑定挂载,且配置了 "run_worker_first":/api/*、/v1/*、/mcp*、/oauth/*、/docs*、/openapi.json、/health 等路径优先由 Worker 处理,其余路径回退到单页应用(SPA)托管。这正是 src/server/cloudflare.ts 中 fetch 处理器逻辑的来源:当 Worker 返回 404 且请求路径命中控制台外壳(isConsoleShellPath)时,把请求转交给 env.ASSETS.fetch(request)。
定时任务与清理
示例配置中的 "triggers": { "crons": <a href="https://link.gitcode.com/i/5306d5f76ebc117646ad28b542a7567a" target="_blank">"* * * * *"] }(每分钟触发一次)对应 [src/server/cloudflare.ts 导出的 scheduled 处理器:它实例化 SaasCleanupService 执行 SaaS 连接清理,并检查是否存在待维护的 flow triggers(listFlowTriggersForMaintenance),有则调用 triggerMaintenance.run()。HTTP 流量不会替代 cron——文档明确强调"HTTP traffic does not replace cron"。
二、SaaS OAuth 部署的四个要点
若你的部署面向 SaaS 多租户场景(而非单一本地账号),docs/cloudflare.md 列出了四点必须遵守的约束:
- 显式设置
OOMOL_CONNECT_ORIGIN:必须设置为公开 Console 的源(origin)。SaaS 回调会返回到该源对应的完成页,浏览器同步 POST 也必须携带相同 origin,反向代理必须保留它。Workers 不会从收到的请求中推断可信 SaaS origin——从 cloudflare-env.ts 的resolvePublicOrigin实现可见,仅当OOMOL_CONNECT_ORIGIN未设置时才回退到请求的 origin。 - 保存项目密钥前先配置加密存储:否则加密凭据无法安全落盘。
- 应用 D1 迁移至
0015_saas_cleanup_runtime.sql:该迁移(migrations/postgresql/0015_saas_cleanup_runtime.sql)负责清理 SaaS 运行时相关表。 - 部署每分钟一次的 cron 触发器:从示例配置复制
triggers.crons,部署后要实际验证定时调用与清理进度。
相关深层资料见 docs/saas-oauth.md 与 docs/saas-maintenance.md(离线 D1 维护章节)。文档同时提醒:临时 reset Worker 具备自动批量/重试测试覆盖,但真实 D1 reset 仍是专门的测试库验收步骤,不能仅凭本地测试适配器断言其行为。
三、前置条件
- 一个开通 Workers、D1 以及 R2 或 Workers KV 权限的 Cloudflare 账号;
- 可通过
npx wrangler使用的 Wrangler CLI; - Node.js 22 或更新版本(根目录 package.json 的 devDependencies 中
wrangler为^4.131.2,工作区使用"type": "module")。
四、创建本地配置
npm install
cp wrangler.example.jsonc wrangler.local.jsonc
wrangler.local.jsonc 已被 git 忽略(不会提交),远程部署前需要填入你自己的 Cloudflare 资源 ID。注意 package.json 中的 postinstall 脚本会执行 scripts/ensure-generated.ts 生成必要文件,安装后即可直接使用。
五、使用 Wrangler 登录
如果尚未登录 Cloudflare 账号:
npx wrangler login
六、创建 Cloudflare 资源
1. 创建 D1 数据库
npx wrangler d1 create open-connector
2. 选择中转文件后端(R2 或 KV,二选一)
选项 A:R2(默认,支持超过 25 MiB 的大文件)
npx wrangler r2 bucket create open-connector-transit-files
选项 B:Workers KV(轻量部署,单值上限 25 MiB)
npx wrangler kv namespace create open-connector-transit-files
3. 回填本地配置
把返回的 D1 database_id、R2 bucket 名或 KV namespace id 写入 wrangler.local.jsonc。切换 KV 后端时:注释掉 r2_buckets 块,取消注释 kv_namespaces 块,并把 TRANSIT_FILES_BACKEND 设为 "kv"(示例配置中已用注释标明 Option A / Option B 的切换方式)。两个后端共用 TRANSIT_FILES 这个 binding 名称,同一时刻只能启用一个——Wrangler 会拒绝同名重复绑定。
所有读取 Worker 配置的 Wrangler 命令都应携带 --config wrangler.local.jsonc。
从运行时视角看后端选择的分流逻辑位于 src/server/cloudflare.ts:当 env.TRANSIT_FILES_BACKEND === "kv" 时构造 KVTransitFileService,否则构造 R2TransitFileService;两者的构造选项统一为 publicOrigin、ttlSeconds、maxBytes 三项。
七、本地 Worker 预览(Local Preview)
本地预览的 D1、R2、KV 数据存放在被忽略的 .wrangler 目录下,与远程 Cloudflare 资源完全隔离。
注意:wrangler secret put 设置的远程密钥不会出现在本地预览中。 要在本地测试管理端认证、凭据加密、OAuth 客户端配置以及已完成 Action 的幂等响应,需要先在被忽略的 .env 文件中添加本地值:
OOMOL_CONNECT_ADMIN_TOKEN=replace-with-a-local-admin-token
OOMOL_CONNECT_ENCRYPTION_KEY=replace-with-a-local-encryption-key
然后将迁移应用到 Wrangler 本地 D1 状态,再启动 Worker:
npx wrangler d1 migrations apply open-connector --local --config wrangler.local.jsonc
npm run dev:cloudflare
npm run dev:cloudflare(见 package.json)会依次执行:生成 catalog(generate:catalog)、构建 Web Console(build:web)、复制 catalog 资源(copy-catalog-assets.ts),最后运行 wrangler dev --config wrangler.local.jsonc。本地预览使用与 Node 运行时相同的生成式 provider Action 执行器注册表(源码见 src/server/cloudflare.ts 的 ProviderLoader(executorModules),其中 executorModules 来自 providers/registry.cloudflare.generated.ts)。
检查本地 Worker 并打开 Web Console:
curl http://localhost:8787/health
健康端点应返回 {"ok":true}。
八、远程部署(Remote Deployment)
1. 先应用 D1 迁移
首次部署前以及每次升级前,都必须把全部待迁移应用到远程 D1 数据库。注意 npm run deploy:cloudflare 不会自动执行 D1 迁移:
npx wrangler d1 migrations apply open-connector --remote --config wrangler.local.jsonc
2. 生成两个独立的随机值
openssl rand -base64 32
(运行两次,分别得到加密密钥与管理员令牌。)
3. 妥善保管加密密钥
把加密密钥存入密码管理器或外部密钥保险库。一旦丢失或未经先重新加密现有 D1 记录就替换密钥,加密的凭据、OAuth 客户端配置以及已完成 Action 的幂等响应将无法恢复。 管理员令牌应提供给需要 Web Console 或管理 API 的操作人员。
4. 写入远程密钥
在 Wrangler 提示时粘贴生成的值:
npx wrangler secret put OOMOL_CONNECT_ADMIN_TOKEN --config wrangler.local.jsonc
npx wrangler secret put OOMOL_CONNECT_ENCRYPTION_KEY --config wrangler.local.jsonc
5. 部署
npm run deploy:cloudflare
该命令执行 generate:catalog && build:web && copy-catalog-assets 后运行 wrangler deploy --config wrangler.local.jsonc --minify。复制出的 wrangler.local.jsonc 已把构建后的 Web Console 资源映射到 Worker 使用的 ASSETS binding。
--minify 在超过上传体积限制时至关重要:通过 wrangler dev inspector 对运行中 isolate 的堆快照可见,脚本源码会以单个字符串形式在 isolate 整个生命周期内驻留内存;13.8 MiB 的压缩脚本约消耗未压缩版(28.7 MiB)一半的 isolate 内存,而每个 Worker isolate 只有 128 MB。
6. 验证部署
使用 Wrangler 输出的 Worker URL 检查部署后的运行时,并在浏览器中打开同一 URL、输入管理员令牌进入 Web Console:
curl https://open-connector.example.workers.dev/health
健康端点应返回 {"ok":true}(把示例 URL 替换为你实际的 Worker URL 或自定义域名)。
九、运行时行为(Runtime Behavior)
部署后的 Cloudflare 运行时负责服务:
- catalog 元数据;
/api与/v1元数据端点;- connections(连接);
- runtime tokens(运行时令牌);
- OAuth 配置与状态;
- 由 R2 bucket 或 KV namespace 承载的中转文件;
- 生成的 provider Action 执行器注册表。
中转文件的过期清理
- R2:若希望自动清理未读取的过期中转文件,为 transit bucket 配置一条 R2 lifecycle 规则(R2 服务端自身在读取时也会做过期判断,见 r2-transit-files.ts 的
isExpired:Date.now() - Date.parse(metadata.createdAt) > ttlMs时删除并返回 404)。 - Workers KV:每次写入时按配置的 TTL 设置
expirationTtl,到期自动删除,无需清理任务(见 kv-transit-files.ts)。
KV 的硬性钳制
KV 对两个配置项有平台级钳制(实现于 kv-transit-files.ts):
OOMOL_CONNECT_TRANSIT_FILE_TTL_SECONDS:最小值钳制到 60 秒(Workers KV 拒绝低于 60 秒的expirationTtl,见源码常量KV_MIN_TTL_SECONDS = 60);OOMOL_CONNECT_TRANSIT_FILE_MAX_BYTES:最大值钳制到 25 MiB(KV_MAX_VALUE_BYTES = 25 * 1024 * 1024)。
另外,KV 是最终一致存储,读取端对"部分 miss"(部分键已传播、部分未传播)不会主动删除——因为删除一个瞬态 miss 会变成永久数据丢失,过期清理完全交给原生 TTL 处理(kv-transit-files.ts)。
十、响应压缩(Response Compression)
Cloudflare 会在出口(egress)侧协商并应用响应压缩,因此 Worker 本身不执行应用级压缩,而是交给边缘处理。其关键机制是:Workers 构建响应时 encodeBody 设为 "automatic",运行时自己编码 body 以满足 Content-Encoding 头——如果应用层已压缩过 body,运行时会对已压缩内容再编码一次,导致客户端收到无法解码的双重压缩。
这也是 src/server/cloudflare.ts 中 compressApiResponses: false 的原因:Cloudflare 的 Response 默认 encodeBody: "automatic",Hono 的 compress() 中间件重建 Response 时无法传递 encodeBody: "manual",gzip-in-gzip 或"gzip 字节但无 Content-Encoding 头"都会让 Dashboard 的 JSON 解析失败。Node 部署没有边缘层,仍然在应用内压缩。
关于可压缩内容类型,Cloudflare 的默认压缩列表(application/json 等)覆盖了 /api 与 /v1 元数据响应——客户端声明支持即会被压缩。压缩的额外前提是:HTTP 状态码为 200 且 body 至少 48 字节(gzip)/ 50 字节(Brotli、Zstandard),最小响应无论内容类型都不压缩。列表包含 text/x-markdown 但不包含 text/markdown,而 /api/actions/:actionId/agent.md 返回的正是 text/markdown,因此 agent 指南保持不压缩——它们很小(典型 Action 约 1.5 KiB,catalog 中最大约 20 KiB),通常无需处理;若你的部署重度提供 agent 指南,可以添加一条匹配 text/markdown 的 Compression Rule。
十一、配置(Configuration)
Cloudflare 运行时与 Node 运行时共用相同的环境变量名:origin、认证令牌、Action 策略、中转文件限制、凭据加密等。根据 docs/cloudflare.md 与 cloudflare-env.ts 中 CloudflareEnv 接口的定义,Cloudflare 部署相关的环境变量包括:
| 环境变量 | 说明 |
|---|---|
OOMOL_CONNECT_ORIGIN |
显式公开 origin;未设置时回退到请求 origin |
OOMOL_CONNECT_ADMIN_TOKEN |
管理端令牌(Web Console / 管理 API) |
OOMOL_CONNECT_RUNTIME_TOKEN |
运行时令牌 |
OOMOL_CONNECT_ENCRYPTION_KEY |
凭据/幂等响应加密密钥 |
OOMOL_CONNECT_ALLOWED_ACTIONS / OOMOL_CONNECT_BLOCKED_ACTIONS |
Action 允许/封禁策略 |
OOMOL_CONNECT_ALLOWED_PROXIES / OOMOL_CONNECT_BLOCKED_PROXIES |
代理允许/封禁策略 |
OOMOL_CONNECT_ALLOWED_TRIGGERS / OOMOL_CONNECT_BLOCKED_TRIGGERS |
触发器允许/封禁策略 |
OOMOL_CONNECT_ALLOWED_CUSTOM_OAUTH |
自定义 OAuth 白名单 |
OOMOL_CONNECT_ALLOW_PRIVATE_NETWORK |
是否允许访问私有网络 |
OOMOL_CONNECT_EGRESS_TRUSTED_HOSTS |
出站可信主机列表 |
OOMOL_CONNECT_TRANSIT_FILE_TTL_SECONDS |
中转文件 TTL(秒),KV 下钳制下限 60 |
OOMOL_CONNECT_TRANSIT_FILE_MAX_BYTES |
中转文件上限字节数,KV 下钳制上限 25 MiB |
OOMOL_CONNECT_RUN_LIMIT |
单次运行的记录条数限制(默认值见 DEFAULT_RUN_LIMIT) |
TRANSIT_FILES_BACKEND |
中转后端标识:"r2" 或 "kv" |
以下变量是本地 Node 专属设置,在 Workers 上无效:PORT、HOST、OOMOL_CONNECT_DATA_DIR、OOMOL_CONNECT_CATALOG_LAZY_SCHEMAS、OOMOL_CONNECT_CATALOG_SCHEMA_CACHE_FILES。
全部运行时环境变量的完整说明见 docs/configuration.md。
十二、部署后自查清单
- 远程 D1 迁移是否已应用到最新版本(
0015_saas_cleanup_runtime.sql及之后)? OOMOL_CONNECT_ORIGIN是否与公开 Console origin 完全一致(含反斜杠结尾处理,见resolvePublicOrigin的replace(/\/+$/, ""))?- 每分钟 cron 是否真实触发、
SaasCleanupService与 flow trigger 维护是否按预期推进? - 加密密钥是否已离线备份?是否所有操作员都知道管理员令牌的存放位置?
- 中转文件后端是否符合文件体积需求:超过 25 MiB 必须用 R2,并配置好 R2 lifecycle 规则?
把以上各节串联起来,就是一套完整、可验证的 OpenConnector Cloudflare 部署流程:本地开发用 .wrangler 隔离数据,远程上线前先迁移 D1,密钥外置保管,压缩交给边缘,清理交给 cron 与 TTL。这套部署同时覆盖元数据服务、连接/令牌/日志存储、临时文件中转与 Web Console 托管,让 OpenConnector 的完整运行时能力以 Cloudflare 平台资源的形式落地。