第 3 章 · 03 Cloudflare 部署

第 3 章 · 03 Cloudflare 部署

本节摘要:本节带你把 OpenSEO 部署到自己的 Cloudflare 账号,用于面向互联网、多设备或团队使用的自托管场景,且兼容 Cloudflare 免费套餐。我们走完「Deploy to Cloudflare」一键部署、配置鉴权与密钥(POLICY_AUD、TEAM_DOMAIN、DATAFORSEO_API_KEY)、可选的 R2 缓存生命周期规则,以及通过 Cloudflare Access 接入 MCP 客户端、给团队成员授权的完整流程。读完本节,你能拥有一个带登录保护、可被团队共享、可被 Claude Code/Cursor 等 MCP 客户端连接的联网 OpenSEO 实例。

内容来源:原项目英文文档 web/content/docs/self-hosting/cloudflare.md,汉化并套用体系化模板。

学习目标

阅读完本节,你应当能够:

1. 用 Deploy to Cloudflare 按钮 完成一键部署。
2. 配置 Cloudflare Access 与三个必需密钥(POLICY_AUD、TEAM_DOMAIN、DATAFORSEO_API_KEY)。
3. 设置 R2 缓存生命周期规则,自动清理过期缓存。
4. 让 MCP 客户端通过 Cloudflare Access 接入你的实例。
5. 给 团队成员授权 访问 OpenSEO。

一、Cloudflare 部署适合什么场景

Docker 自托管是「本机/内网用」,Cloudflare 部署则是「面向互联网用」——你需要一个带登录保护、能跨设备访问、能分享给团队的 OpenSEO 实例时,选它。它跑在 Cloudflare Workers 上,可以用 Cloudflare 免费套餐,核心是借助 Cloudflare Access 做「谁能进」的鉴权,再借 R2 做 DataForSEO 响应缓存。

部署形态全景:

💡 何时选 Cloudflare 而不是 Docker:需要联网访问、多设备同步、团队共享时选 Cloudflare;只在单机本地用、不想配鉴权时选 Docker(但务必放在受保护网络后)。

二、从 GitHub 一键部署

点击仓库里的 Deploy to Cloudflare 按钮。部署表单字段很多,但你只需要做下面几步:

1. 连接你的 Git 提供商(GitHub 或 GitLab)。
2. 资源命名字段保持默认,除非你有理由改。
3. 点击 Create and Deploy。
4. 等 1~2 分钟部署完成。

⚠️ 注意:如果部署报错 Cannot provision a KV Namespace with the title "open-seo" because it already exists(因为你账号下已有同名 KV 命名空间),改用 GitHub 上的 Wrangler 手动部署指南 自己创建 Cloudflare 资源并用 CLI 部署。

三、配置鉴权与密钥

在 Cloudflare 控制台:

1. 进入 Compute → Workers & Pages → 你的 OpenSEO Worker。
2. 打开 Settings。
3. 在 Domains & Routes 里,为 workers.dev 路由启用 Cloudflare Access。
4. 保存 Cloudflare Access 显示的值。
5. 在 Variables & Secrets 里添加:

POLICY_AUD       # 来自 Access 配置
TEAM_DOMAIN      # 来自 JWKS_URL 的域名,例如 https://your-team.cloudflareaccess.com
DATAFORSEO_API_KEY   # DataForSEO API key,设置方式见自托管总览
​

💡 技巧:POLICY_AUD 是 Cloudflare Access 给你这个应用分配的「受众 ID」,TEAM_DOMAIN 是你的 Zero Trust 团队域名。两者都来自上一步 Access 配置的输出,别凭空编。

四、可选:添加 R2 生命周期规则

DataForSEO 的 API 响应缓存在 R2 的 dataforseo-cache/ 前缀下。这步可选但推荐——它会自动清理过期缓存对象:

npx wrangler r2 bucket lifecycle add open-seo dataforseo-cache-expiry dataforseo-cache/ --expire-days 7
​

如果你在部署时改过 R2 bucket 名,把命令里的 open-seo 换成你的 bucket 名。

⚠️ 注意:不加生命周期规则,dataforseo-cache/ 下的缓存对象会无限累积,日积月累会推高存储成本。一条 --expire-days 7 的规则就能让它在 7 天后自动过期。

五、验证部署

1. 再次打开你的 Worker URL。
2. 用 Cloudflare Access 登录。
3. 登录后 OpenSEO 应正常加载。

如果登录失败,回去复查那三个密钥和 Access 开关是否都正确。

六、通过 Cloudflare Access 接入 MCP 客户端

复用保护 OpenSEO Worker 的那个 Cloudflare Access 应用。MCP 客户端必须开启 Managed OAuth(默认不启用):

1. 打开 Cloudflare Zero Trust。
2. 进入 Access controls → Applications。
3. 找到你的 OpenSEO 应用,点 Edit。
4. 进入 Additional settings → OAuth。
5. 打开 Managed OAuth。
6. 在 Managed OAuth settings 里,允许你的 MCP 客户端使用的重定向 URI:
   • 允许 localhost/回环地址客户端(给 Codex CLI、Claude Code 这类 CLI/桌面 agent 用,它们注册的是 http://localhost:PORT/callback)。
   • 为 web 连接器加 HTTPS 重定向 URI(路径可以 /* 结尾)。
   • 没这一步,客户端能登录、能完成 Dynamic Client Registration,但 暴露不出任何工具。
7. 保存。

MCP 客户端应连接到:

https://YOUR_WORKER_HOSTNAME/mcp
​

⚠️ 注意:Managed OAuth 是「客户端能登录但工具列表为空」最常见的根因。如果你接上 MCP 后看到登录成功却没有 openseo.* 工具,先回到这里确认 Managed OAuth 已开、重定向 URI 已加。

七、给团队成员授权

1. 打开 Cloudflare Zero Trust。
2. 进入 Access → Applications。
3. 打开你的 OpenSEO 应用。
4. 编辑 Allow 策略。
5. 添加队友邮箱(或你公司的整个邮箱域 / 用户组)。
6. 保存。

保存后,队友打开你的 OpenSEO URL,经 Cloudflare Access 登录即可使用。OpenSEO 会为「策略允许的所有人」共享同一个工作区。

💡 技巧:团队共享工作区意味着大家看到同一份数据。如果你想给不同子团队隔离数据,目前的做法是部署多个 OpenSEO 实例、各自配不同的 Access 策略。

八、进阶指南(在 GitHub 上)

• Wrangler 手动部署:自己创建 Cloudflare 资源并用 CLI 部署,适合一键部署因 KV 命名冲突失败、或需要精细控制资源时。
• 运维(Operations):升级到最新 OpenSEO 版本、管理遥测。

💡 技巧:定期看一眼 Operations 指南,把实例更新到最新版本——自托管的好处之一是你可以决定何时升级,但太久不升级会错过安全修复与新功能。

本节要点回顾

1. 场景:面向互联网、多设备、团队共享的自托管选 Cloudflare,免费套餐即可。
2. 一键部署:连 Git → 默认命名 → Create and Deploy → 等 1~2 分钟;KV 冲突走 Wrangler 手动部署。
3. 三密钥:POLICY_AUD、TEAM_DOMAIN、DATAFORSEO_API_KEY,均在 Worker 的 Variables & Secrets 配。
4. 鉴权:为 workers.dev 路由启用 Cloudflare Access,登录后才能进。
5. R2 规则:wrangler r2 bucket lifecycle add ... --expire-days 7 自动清过期缓存,省存储。
6. MCP 接入:开启 Managed OAuth 并加重定向 URI(含 localhost 回环),否则工具列表为空。
7. 客户端连接:https://YOUR_WORKER_HOSTNAME/mcp。
8. 团队授权:在 Access 的 Allow 策略里加邮箱/邮箱域,所有人共享一个工作区。

部署闭环到此完成。下一章我们转向 SEO 方法论——工具会迭代,但「搜索意图、长尾、主题中心」这些心法不会,它们才是任何工具里做对 SEO 的根本。