OpenSEO 在 Cloudflare 上的自托管部署：一条命令搞定 D1/KV/R2 与 Cloudflare Access 登录门禁

OpenSEO 在 Cloudflare 上的自托管部署一条命令搞定 D1/KV/R2 与 Cloudflare Access 登录门禁【免费下载链接】open-seoOpen source alternative to Semrush and Ahrefs项目地址: https://gitcode.com/GitHub_Trending/op/open-seoOpenSEO开源版 Semrush/Ahrefs 替代品在 Cloudflare 自托管指南中提供了一条完全自动化的部署路径只需一条命令即可完成 D1 数据库、KV 命名空间、R2 存储桶的创建、数据库迁移、Worker 部署以及基于 Cloudflare Access 的登录门禁配置且完全可以在 Cloudflare 免费计划上运行。本文以该文档为主体骨架结合仓库内的 部署栈定义、Access 门禁实现 与 环境变量模板 等源码证据完整展开从环境准备、部署、验证、MCP 接入、协作者管理到升级、运维与拆除的每一步帮助你把 OpenSEO 部署到面向公网、支持多设备与团队使用的自托管实例。一、部署前准备三项前置条件在运行任何命令之前请确认满足以下前置条件Node.js 22.6 或更新版本 pnpm。corepack enable即可启用 pnpm。这一版本要求并非随意设定——pnpm alchemy脚本通过NODE_OPTIONS--experimental-strip-types直接运行 TypeScript见 package.json而--experimental-strip-types正是 Node 22.6 起引入的能力。部署预检脚本 会在部署前直接校验 Node 主/次版本低于 22.6 会立即报错并提示24 LTS recommended。一个已启用 R2 的 Cloudflare 账户。R2 的激活即使在其免费额度内也要求账户留有支付方式如果你从未使用过 R2需要先在 Cloudflare 控制台打开R2页面一次完成激活。一个 DataForSEO 账户用于获取DATAFORSEO_API_KEY。获取与格式说明见 DataForSEO API Key 文档。二、克隆 OpenSEO 仓库并安装依赖如果你希望拥有自己可控的仓库先在 GitHub 上 forkevery-app/open-seo然后克隆到本地git clone https://github.com/YOUR_GITHUB_USER/open-seo.git cd open-seo corepack enable pnpm install如果不需要 fork直接克隆上游仓库git clone https://github.com/every-app/open-seo.git cd open-seo corepack enable pnpm install三、登录 Cloudflare仅需一次OpenSEO 的 Cloudflare 自托管部署基于Alchemyv2 基础设施即代码框架见 alchemy.run.ts它负责按 stage 命名并编排 D1/KV/R2/Worker 等全部资源。首次使用需要两步pnpm alchemy login # 回答 yes 到 Customize OAuth scopes?并启用 access:write pnpm alchemy cloudflare bootstrap # 在你的账户上部署 alchemy 的 state-store Worker两个细节值得注意access:writescope 是部署 Access 门禁的硬性要求。pnpm alchemy cloudflare bootstrap部署的是 Alchemy 的状态存储 Worker用于保存部署的持久化状态见 alchemy.run.ts而access:write授权 Alchemy 调用 Zero Trust API 来创建 Access 应用与策略。如果你此前已登录过但没有access:writescope请运行pnpm alchemy login --configure——单纯重复登录不会重新询问 scope。预检脚本会读取~/.alchemy/profiles.json中的 OAuth 登录信息并校验 scope见 scripts/selfhost-deploy-preflight.mjs当登录方式为 oauth 且缺少access:write时会在部署前就失败并给出明确的补救命令避免浪费数分钟构建时间。当然你也可以通过设置环境变量CLOUDFLARE_API_TOKEN直接使用 API Token 登录绕过 profile 校验。四、创建.env.selfhost配置文件复制模板并填写必需项cp .env.selfhost.example .env.selfhost模板位于 .env.selfhost.example结构如下# ---------- Required ---------- DATAFORSEO_API_KEY ACCESS_ALLOWED_EMAILS # ---------- Optional — uncomment to use ---------- # GOOGLE_CLIENT_ID # GOOGLE_CLIENT_SECRET # BETTER_AUTH_SECRET # OPENROUTER_API_KEY # OPENROUTER_MODEL # POSTHOG_PUBLIC_KEY # POSTHOG_HOST # OPENSEO_TELEMETRY_DISABLED1 # TEAM_DOMAINhttps://your-team.cloudflareaccess.com # POLICY_AUDyour-access-application-audience-tag必需变量变量作用说明DATAFORSEO_API_KEYDataForSEO 平台凭证格式为login:password的 Base64 编码作为secret_text注入 Worker见 package.json 与 alchemy.run.tsACCESS_ALLOWED_EMAILS允许通过 Cloudflare Access 登录的邮箱列表逗号分隔解析逻辑见 alchemy.access.ts每个邮箱会成为 Access 策略中的一条emailinclude 规则可选变量Google Search Console 集成三个需同时配置GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET、BETTER_AUTH_SECRET详见 Google Search Console 自托管指南。SAM 应用内智能体不设置则隐藏入口OPENROUTER_API_KEY、OPENROUTER_MODEL。自建 PostHog 产品分析POSTHOG_PUBLIC_KEY、POSTHOG_HOST。关闭匿名遥测OPENSEO_TELEMETRY_DISABLED1详见运维章节。自带 Cloudflare Access 应用同时设置TEAM_DOMAINhttps://your-team.cloudflareaccess.com与POLICY_AUDyour-access-application-audience-tag后部署将不再自动创建 Access 资源ACCESS_ALLOWED_EMAILS也会被忽略。显式设置的环境变量优先级最高这是源码中明确实现的逻辑见 alchemy.run.ts。五、一键部署pnpm deploy:selfhostpnpm deploy:selfhost --yes这一条命令背后完成的工作远比字面看起来多。看 package.json 中的脚本定义node scripts/selfhost-deploy-preflight.mjs → vite build --mode selfhost → tsc --noEmit → pnpm alchemy deploy --env-file .env.selfhost --stage selfhost即先执行秒级预检Node 版本、env 文件存在性、必需变量、Cloudflare 登录与 scope再构建客户端与服务端产物、做类型检查最后由 Alchemy 以selfhoststage 完成资源编排与部署。部署栈实际创建的资源从 alchemy.run.ts 的makeResources可以确认selfhoststage 会创建以下 stage 后缀命名的资源D1 数据库open-seo-db-selfhost自动应用drizzle目录下的迁移迁移表d1_migrations与既有生产约定一致KV 命名空间 ×2open-seo-kv-selfhost通用 KV与open-seo-oauth-kv-selfhostMCP OAuth 客户端注册/授权/令牌存储见 package.jsonR2 存储桶open-seo-r2-selfhost自带 7 天过期生命周期规则自动清理dataforseo-cache/前缀下的 DataForSEO 缓存响应避免重复计费两个 Worker主 Workeropen-seo-selfhost承载应用与fetch流量与审计辅助 Workeropen-seo-selfhost-audit承载站点审计引擎SiteAuditWorkflow与AuditScratchpadDO两者共享同一套 D1/KV/R2见 alchemy.run.tsCloudflare Access 应用自建应用open-seo selfhost其 Allow 策略精确放行ACCESS_ALLOWED_EMAILS列出的邮箱实现见 alchemy.access.ts 的emailAccessGate。认证模式fail-closed 的cloudflare_access自托管部署采用AUTH_MODEcloudflare_access该值未设置时也默认如此见 alchemy.run.ts。认证模式的运行时解析在 src/lib/auth-mode.ts未知值会在控制台告警并回退到cloudflare_access绝不会悄然变成公开的 hosted 注册模式。当部署脚本检测到账户尚无 Zero Trust 团队时会自动创建一个命名取自你的 workers.dev 子域名TEAM_DOMAIN如https://your-team.cloudflareaccess.com与POLICY_AUDAccess 应用的 audience tag均无需手动复制Alchemy 会从账户读取或创建后自动注入 Worker 环境见 alchemy.run.ts。如果你的账户已配置好团队但登录状态缺少必要 scope报错信息会明确提示重新登录并启用access:write。六、验证部署结果打开部署结束时打印的 Worker URL。通过 Cloudflare Access 完成登录。登录后 OpenSEO 应正常加载。若登录失败请重新检查.env.selfhost中的ACCESS_ALLOWED_EMAILS并重新部署。更系统的排查手段包括健康检查端点https://your-worker-hostname/api/health会返回运行时配置检查与数据库状态。该端点只报告各特性的配置状态与指导信息、绝不暴露密钥值存在配置错误时返回{status:issues, ...}一切正常则返回{status:ok}实现见 src/routes/api/health.ts。服务端错误排查打开 Worker 的Logs面板或运行pnpm exec wrangler tail跟踪主 Worker 日志站点审计运行在独立 Worker 中用pnpm exec wrangler tail open-seo-selfhost-audit单独跟踪。七、通过 Cloudflare Access 接入 MCP 服务器OpenSEO 提供 MCPModel Context Protocol服务端Agent/LLM 客户端可经由同一个保护 OpenSEO Worker 的 Cloudflare Access 应用接入。MCP 客户端要求Managed OAuth默认未开启配置步骤如下打开 Cloudflare Zero Trust进入Access controls-Applications找到你的 OpenSEO 应用选择Edit进入Additional settings-OAuth打开Managed OAuth在Managed OAuth settings中允许你的 MCP 客户端所使用的重定向 URI为 CLI 与桌面 Agent如 Codex CLI、Claude Code放行localhost/ loopback 客户端它们会注册形如http://localhost:PORT/callback的回调地址为 Web 连接器添加 HTTPS 重定向 URI路径可以/*结尾若不放行客户端将无法完成动态客户端注册表现为能登录但暴露不出任何工具保存。MCP 客户端统一连接到https://YOUR_WORKER_HOSTNAME/mcp从源码结构看MCP 相关的 OAuth 客户端注册、授权与令牌都存放在独立的OAUTH_KV命名空间中见 package.json 的绑定描述并为/mcp的 API-Key 认证配置了按用户限流每 60 秒 5000 次见 alchemy.run.ts防止自托管实例被滥用。八、给团队成员开放 OpenSEO 访问把协作者的邮箱加入.env.selfhost的ACCESS_ALLOWED_EMAILS然后重新部署# 编辑 .env.selfhost追加邮箱 pnpm deploy:selfhost --yes需要留意的是在控制台里直接编辑那个 Access 策略会在下一次部署时被覆盖因为 Allow 策略的 include 规则由ACCESS_ALLOWED_EMAILS驱动见 alchemy.access.ts。若你选择自带 Access 应用设置了TEAM_DOMAINPOLICY_AUD则改由自己在 Zero Trust 中编辑 Allow 策略。所有通过 Cloudflare Access 放行的人共享同一个工作区、看到同一批项目。从旧版本升级的部署旧版为每个用户分配独立工作区会在前端显示一次性横幅点击即可把历史个人工作数据迁移进共享工作区。九、升级到最新版本git pull # 或 fork 场景git fetch upstream git merge upstream/main pnpm install pnpm deploy:selfhost --yes部署命令具有幂等性每次运行都会对资源做 reconcile对齐差异包括覆盖 Worker 环境变量——这也是为什么OPENSEO_TELEMETRY_DISABLED必须写进 env 文件而非在控制台手动设置在控制台设置会被下一次部署清掉见 alchemy.run.ts 的注释说明。十、运维遥测与日常管理OpenSEO 会收集匿名遥测用于核心使用事件统计其实现位于 src/server/lib/self-host-telemetry.ts内容仅包含聚合计数安装数、用户数、项目数、功能使用情况关联到一个随机生成的安装 IDinstallId不包含任何 URL、关键词、提示词、邮箱或 IP 派生地理位置频率安装后前两小时内每 5 分钟一次便于观察 day-0 引导进度此后每天至多一次空闲实例不发送任何数据事件字段从源码可见心跳事件self_host.heartbeat携带部署目标cloudflare/docker、数据库后端d1/postgres、版本号、设置检查状态仅枚举值绝无自由文本与 MCP 工具调用计数见 self-host-telemetry.ts退出机制在.env.selfhost中设置OPENSEO_TELEMETRY_DISABLED1并重新部署DO_NOT_TRACK1同样生效见 self-host-telemetry.ts。十一、拆除部署pnpm alchemy destroy --env-file .env.selfhost --stage selfhost该命令会删除两个 Worker、带 stage 后缀的 D1/KV/R2 资源包括你的数据以及自动创建的 Access 应用。请务必在确认不再需要实例数据后执行。十二、更深入的内容Cloudflare 自托管运维指南MCP 接入与遥测的日常运维细节旧版部署维护指南针对已退役的 Deploy 按钮或手动 Wrangler 流程创建的旧安装的维护说明Cloudflare 自托管部署主文档本文的完整母版部署栈完整定义 与 Access 门禁共享契约想深入理解资源编排与安全边界时可通读这两个文件其中也覆盖了预览部署与 hosted-prod stage 的命名约定与保留策略RetentionPolicy.retain。【免费下载链接】open-seoOpen source alternative to Semrush and Ahrefs项目地址: https://gitcode.com/GitHub_Trending/op/open-seo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考