OpenConnector 部署到 Cloudflare Workers:完整实战指南(D1 + R2/KV + Static Assets)

原创2026-10-09 20:10:221,944 阅读
文章标签:后端API网关认证鉴权MCP 服务人工智能AI Agent

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 列出了四点必须遵守的约束:

  1. 显式设置 OOMOL_CONNECT_ORIGIN:必须设置为公开 Console 的源(origin)。SaaS 回调会返回到该源对应的完成页,浏览器同步 POST 也必须携带相同 origin,反向代理必须保留它。Workers 不会从收到的请求中推断可信 SaaS origin——从 cloudflare-env.ts 的 resolvePublicOrigin 实现可见,仅当 OOMOL_CONNECT_ORIGIN 未设置时才回退到请求的 origin。
  2. 保存项目密钥前先配置加密存储:否则加密凭据无法安全落盘。
  3. 应用 D1 迁移至 0015_saas_cleanup_runtime.sql:该迁移(migrations/postgresql/0015_saas_cleanup_runtime.sql)负责清理 SaaS 运行时相关表。
  4. 部署每分钟一次的 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。

十二、部署后自查清单

  1. 远程 D1 迁移是否已应用到最新版本(0015_saas_cleanup_runtime.sql 及之后)?
  2. OOMOL_CONNECT_ORIGIN 是否与公开 Console origin 完全一致(含反斜杠结尾处理,见 resolvePublicOrigin 的 replace(/\/+$/, ""))?
  3. 每分钟 cron 是否真实触发、SaasCleanupService 与 flow trigger 维护是否按预期推进?
  4. 加密密钥是否已离线备份?是否所有操作员都知道管理员令牌的存放位置?
  5. 中转文件后端是否符合文件体积需求:超过 25 MiB 必须用 R2,并配置好 R2 lifecycle 规则?

把以上各节串联起来,就是一套完整、可验证的 OpenConnector Cloudflare 部署流程:本地开发用 .wrangler 隔离数据,远程上线前先迁移 D1,密钥外置保管,压缩交给边缘,清理交给 cron 与 TTL。这套部署同时覆盖元数据服务、连接/令牌/日志存储、临时文件中转与 Web Console 托管,让 OpenConnector 的完整运行时能力以 Cloudflare 平台资源的形式落地。

登录后查看全文
open-connector