Cloudflare Edge

给本地工作站一个稳定的公网入口。

ChatGPT 在公网，本地 Herdr 工作站通常藏在 NAT、防火墙或公司网络之后。herdr-mcp 不要求你给开发机开放入站端口，而是让工作站主动建立一条出站连接到 Cloudflare Edge。

ChatGPT
   │ HTTPS / OAuth / MCP
   ▼
Cloudflare Worker + Durable Object
   ▲
   │ authenticated WSS
   │
herdr-link
   │
   ▼
local herdr-mcp runtime
   │
   ▼
Herdr / Git / shell

这篇文档讲 Edge 为什么这样部署、怎样用 workers.dev 零域名 bootstrap、什么时候应优先把 Custom Domain 作为正式入口，以及旧 Tunnel 架构怎样安全迁移。

先记住三个原则#

1. 新安装先用 `workers.dev` bootstrap；有 active zone 时在客户端接入前优先 Custom Domain#

没有域名也能完整安装。Cloudflare Account 已有合适 active zone 时，推荐在 ChatGPT Connector/OAuth 固化前使用专用 Custom Domain；Cloudflare 会自动创建对应 DNS 记录和证书，不需要手工 DNS 配置。

2. 工作站只建立出站连接#

公网不能直接访问本机 127.0.0.1:8772。Edge 通过已经认证的 workstation link 把请求送回正确机器。

3. 公网 identity 要稳定#

ChatGPT Connector、OAuth issuer 和 MCP resource 都依赖 public origin。第一次验证成功以后，不要把 Worker 名称或 Custom Domain 当成随手可改的临时变量。

Edge 负责什么#

Cloudflare 层主要承担：

稳定 HTTPS MCP endpoint；
OAuth discovery / authorization / token；
workstation identity 路由；
持久 WSS link 的连接管理；
runtime online/offline 与 generation/version 状态；
MCP request/response relay；
可选的短时私有 R2 通用 artifact 中继（/artifacts，仅 Worker binding）。

Edge 不保存你的 Git 仓库，也不代替本机 Herdr。代码、shell 和 Agent 仍在工作站执行。R2 桶只是临时通用 artifact 中继，不是素材库。

Bootstrap 部署：workers.dev#

普通第一台设备安装直接使用已安装 runtime：

herdr-mcp worker bootstrap

用户电脑不需要仓库 checkout、Node.js、npm、下载 Wrangler、本地编译 Worker 或生成 wrangler.user.toml。Release CI 会从已经通过 Edge gate 的源码一次性构建 herdr-edge-<version>.mjs。bootstrap 下载精确匹配的 release manifest 与 bundle，要求 release source commit 与当前 runtime 一致，校验大小、SHA-256 和 GitHub artifact attestation，然后直接通过 Cloudflare Worker API 上传。

生成 Worker name#

bootstrap 会在 runtime 内部从本机电脑名派生有界 DNS-label Worker name。workers.dev Worker name 与 canonical dev_<ULID> 设备身份继续分离，因此第一台设备 enrollment 不需要第二次 Worker 部署。

配置 public origin#

首次部署完成后，Cloudflare 会给出类似：

https://<worker>.<account-subdomain>.workers.dev

MCP endpoint：

https://<worker>.<account-subdomain>.workers.dev/mcp

bootstrap 阶段主要用这个 hostname 证明 Worker 代码健康。如果准备使用 Custom Domain，此时不要先注册最终 ChatGPT Connector；OAuth issuer / HERDR_MCP_BASE_URL 必须在客户端接入前与最终 canonical origin 保持一致。

https://<worker>.<account-subdomain>.workers.dev

不要给 base URL 加 /mcp。

部署#

herdr-mcp worker bootstrap 会直接创建/更新 Worker script、Durable Object bindings 与首次 migrations、非秘密变量、workers.dev 暴露、cron trigger、bootstrap secrets、第一台 canonical device enrollment 和 production Link readiness。核心路径不包含 R2 binding，也不要求 R2 subscription 或支付方式。可选私有 artifact relay 在核心安装健康后作为独立 operator 操作处理。

对于已有 fleet，不要重新执行 first-Worker bootstrap。使用 herdr-mcp worker update，或者正常运行交互式 herdr-mcp update，让它在 Runtime 更新成功后继续 reconcile Edge。已有 fleet 的更新会先下载与目标 Release 精确匹配的 Edge bundle，并校验 digest 和 GitHub attestation，然后才临时取得 Cloudflare 授权；mutation 前还会读取当前 Worker health identity 与 Cloudflare settings，只更新已证明身份的那个 script。已有 Durable Objects 与 secrets 保持不变，已知的可选 ARTIFACT_BUCKET binding 会原样带上，配置中的 public OAuth origin（包括 Custom Domain）保持不变，routes/DNS、设备与 Connectors 都不会修改；遇到未知的自定义 binding 会 fail-closed，不会静默丢配置。只有精确冻结的 epoch-2 rollback identity 会在 fleet 管理 preflight 中被识别，以便已经 enrollment 的旧 Worker 原地 reconcile；任意/未知 Runtime execution contract 仍是显式 migration 边界，并且 Link/install admission window 不会因此放宽。update auto 不会弹出 Cloudflare 授权；Edge 仍需 reconcile 时只报告下一步 herdr-mcp worker update。

部署 Worker 成功只代表公网代码存在。下一步先确定最终 public origin，再验证 workstation link。

仓库里的 wrangler.user.example.toml 与 Wrangler 命令继续保留给维护者、Edge 贡献者和深度恢复场景，不再属于普通安装路径。

在 OAuth/MCP 客户端接入前确定最终公网入口#

所选 Cloudflare Account 已有 active zone 时，推荐用 herdr-mcp.example.com 这类专用 Custom Domain 作为 production identity。Cloudflare 官方建议 production Worker 使用 Route 或 Custom Domain，而不是长期依赖 workers.dev；Herdr Worker 本身就是该 hostname 的 origin，因此这里应使用 Custom Domain，不是套在其它 origin 前面的普通 Worker Route。

Wrangler 示例：

[[routes]]
pattern = "herdr-mcp.example.com"
custom_domain = true

把 OAUTH_ISSUER 设置为 https://herdr-mcp.example.com，重新部署，并在创建 ChatGPT Connector 前验证该 Custom Domain 的 /health、未认证 /mcp、OAuth discovery。Cloudflare 会自动创建 DNS 记录与证书。这个 hostname 必须属于 active Cloudflare zone，并且不能与已有 CNAME 或不兼容的 Worker/DNS 用途冲突。

如果没有合适 zone 或用户不想使用域名，则继续把 workers.dev 固化为 canonical public origin；这是完整支持的配置，不是安装失败。

Workstation Link#

herdr-link 在工作站主动向 Edge 建立认证 WSS。

workstation ── outbound WSS ──► Edge

它负责：

证明 workstation identity；
保持持久连接；
接收发往该工作站的 MCP 请求；
把请求路由给当前 active runtime generation；
heartbeat 上报 runtime generation/version。

因此 Edge 可以稳定存在，而本机 runtime 可以单独重启或 A/B 切代。

如果 OAuth 正常、Worker /health 也能打开，但工具调用报告 workstation offline，应该查 link，而不是重新安装 Connector。

当前 Edge 会先给最近在线过的 workstation 一小段纯内存 reconnect grace；如果 validated Link 没有回来，MCP 错误会明确带上 retryable、delivery_state、retry_after_ms 和有界只读 recovery policy，让 Agent 不需要猜“能不能重放”。本机 Link 自己负责 reconnect/backoff 与 prolonged-offline recycle；这条恢复链不依赖浏览器扩展状态，也不会为了请求恢复额外制造 request-led Durable Object write/alarm。精确的 replay 规则见故障排查。

第一次验收顺序#

不要一上来就在 ChatGPT 里排所有问题。按层验证：

1. local runtime
2. herdr-link
3. Edge health
4. OAuth metadata/token
5. public MCP initialize/tools/list
6. real herdr_inspect
7. ChatGPT new conversation

这能快速区分“Edge 代码部署失败”和“工作站没有接上”。

完整诊断见故障排查。

为什么不用 Cloudflare Tunnel 直连本机 MCP#

早期最直觉的方案是：

ChatGPT → Tunnel → local MCP

它能工作，但把公网 endpoint 和某个本机 runtime 进程绑得太紧：

runtime restart 会直接影响公网连接；
OAuth identity 和机器生命周期容易耦合；
多 workstation 路由困难；
A/B runtime 切换不自然。

现在推荐：

ChatGPT → stable Edge ← persistent link ← workstation

Cloudflare Tunnel 直连只保留为遗留迁移场景，不是新安装主路径。

什么时候使用 Custom Domain#

如果账户已经有合适的 active Cloudflare zone，并且能为 Herdr 分配一个专用 hostname，默认优先使用 Custom Domain：

https://herdr.example.com

Custom Domain 的价值主要是：

public identity 更容易长期保持；
OAuth issuer 归你自己的域名治理；
团队环境名称更清楚；
将来更换 Edge implementation 时，可以尽量保留外部 URL。
某些网络环境过滤 workers.dev 时，用户自己的 Cloudflare hostname 仍可能保持直连。

它仍然不是 Herdr 技术前置条件。不要把“必须先有域名”重新变成首次安装门槛。

Custom Domain 操作#

仓库提供独立控制器：

bin/herdr-cloudflare-domain preflight
bin/herdr-cloudflare-domain status
bin/herdr-cloudflare-domain attach
bin/herdr-cloudflare-domain watch
bin/herdr-cloudflare-domain detach

推荐流程：

workers.dev 上先跑通
        ↓
preflight Custom Domain
        ↓
attach
        ↓
验证 health / OAuth / MCP / workstation
        ↓
稳定观察

代码部署和域名切换分开做。 一个新版本 Worker 是否正确，不应该依赖 DNS cutover 才能验证。

从旧 CNAME / Tunnel 迁移#

只有已有旧架构时才需要这一节。

旧形态可能是：

herdr.example.com
  ↓ CNAME
Cloudflare Tunnel
  ↓
local runtime

同一 hostname 上已有冲突 DNS 记录时，不能简单再 attach Worker Custom Domain。

安全迁移原则：

新 Worker 在独立 workers.dev origin 已完全健康；
记录旧 DNS / Tunnel rollback evidence；
旧 Tunnel 在 cutover 期间继续在线；
移除唯一冲突记录；
attach Worker Custom Domain；
验证 public health、workstation、OAuth、当前 MCP contract 和一次真实只读 tool call；
稳定后才退出旧 Tunnel；
任一步失败，恢复旧入口。

仓库提供事务化 helper：

bin/herdr-custom-domain-cutover preflight
bin/herdr-custom-domain-cutover run

这里最大的安全要求仍然是：不对投递状态未知的 DNS/domain mutation 盲重试，而是重新读取 Cloudflare 的真实状态。

Cloudflare API 凭据#

部署 credential 与 ChatGPT OAuth 完全不同。

项目 helper：

bin/herdr-cloudflare-token --zone example.com --dry-run
bin/herdr-cloudflare-token --zone example.com
bin/herdr-cloudflare-token --zone example.com --verify-only

目标是长期只保留最小权限。详见 Cloudflare Edge 凭据。

旧 DNS cutover 如果确实需要 DNS Write，应使用单独、短生命周期的凭据，不要把 DNS 管理权限永久叠加到日常 Worker deployment token。

GitHub Actions 与自动部署#

仓库的 production Edge workflow 负责在 main 相关部署面变化后：

安装依赖；
构建并运行 Edge / contract regression；
通过 production Environment gate；
用 Wrangler 部署生产 Worker；
做发布后 health 验证。

CI credential 应放在 GitHub Environment/Secrets 中，不写进仓库。

普通 Worker code deploy 不应该修改：

Custom Domain；
OAuth issuer；
workstation identity；
DNS；
ChatGPT Connector URL。

这些边界保持独立，才能让“发布代码”和“切生产入口”分别回滚。

Edge 与 Runtime A/B 是两层发布#

Public plane
Cloudflare Edge / OAuth / Connector URL

Local plane
herdr-link → runtime generation A/B

大部分 runtime 修复只需要在本机 generation 层发布，不应该修改 public Edge identity。

反过来，Edge relay/OAuth 实现更新也不意味着要同时重启本机 Herdr。

详见 Runtime A/B。

安全边界#

工作站没有公网入站端口；
Link 使用认证 WSS；
ChatGPT 使用 OAuth，不获取本机 static bearer；
Cloudflare API secret 不进入 Git；
OAuth signing material 不进入 Git；
deployment credential 使用最小权限；
Worker deployment 和 Custom Domain/DNS mutation 分开；
Edge 只负责远程控制面，真实代码和执行留在工作站。

场景	推荐
第一次安装 / 自用	`workers.dev`
长期个人入口	`workers.dev` 或稳定 Custom Domain
团队正式环境	Custom Domain + Environment secrets
已有旧 Tunnel/CNAME	先并行验证 Worker，再事务化 cutover
只是本机 Cursor/curl	不需要 Cloudflare Edge

Cloudflare Edge

先记住三个原则#

1. 新安装先用 `workers.dev` bootstrap；有 active zone 时在客户端接入前优先 Custom Domain#

2. 工作站只建立出站连接#

3. 公网 identity 要稳定#

Edge 负责什么#

Bootstrap 部署：workers.dev#

生成 Worker name#

配置 public origin#

部署#

在 OAuth/MCP 客户端接入前确定最终公网入口#

Workstation Link#

第一次验收顺序#

为什么不用 Cloudflare Tunnel 直连本机 MCP#

什么时候使用 Custom Domain#

Custom Domain 操作#

从旧 CNAME / Tunnel 迁移#

Cloudflare API 凭据#

GitHub Actions 与自动部署#

Edge 与 Runtime A/B 是两层发布#

安全边界#

推荐部署选择#

搜索 herdr-mcp

Cloudflare Edge

先记住三个原则#

1. 新安装先用 workers.dev bootstrap；有 active zone 时在客户端接入前优先 Custom Domain#

2. 工作站只建立出站连接#

3. 公网 identity 要稳定#

Edge 负责什么#

Bootstrap 部署：workers.dev#

生成 Worker name#

配置 public origin#

部署#

在 OAuth/MCP 客户端接入前确定最终公网入口#

Workstation Link#

第一次验收顺序#

为什么不用 Cloudflare Tunnel 直连本机 MCP#

什么时候使用 Custom Domain#

Custom Domain 操作#

从旧 CNAME / Tunnel 迁移#

Cloudflare API 凭据#

GitHub Actions 与自动部署#

Edge 与 Runtime A/B 是两层发布#

安全边界#

推荐部署选择#

1. 新安装先用 `workers.dev` bootstrap；有 active zone 时在客户端接入前优先 Custom Domain#