Cloudflare 一键部署

Deploy Button 是最快的 Cloudflare 路径。它把模板复制到你的 GitHub 账户，在你的 Cloudflare 账户中创建资源，并部署一个带 Dashboard 和设备通道的 tool-bridge Worker。

它适合快速试用、轻量边缘网关和不需要修改 monorepo 源码的团队。它不适合需要 D1 Search 或完整源码 gateway 内置 catalog bundle 的场景；这类需求应使用从源码部署到 Cloudflare。

前置条件

GitHub 账户；
Cloudflare 账户，并有创建 Workers、KV、R2 和 Durable Objects 的权限；
本机 Node.js 22+，用于生成随机 secret；
一个密码管理器；
可选：自定义域名已经托管在 Cloudflare。

1. 在本地生成两项 secret

分别运行下面两条命令，不要复用文档示例值：

node -e "console.log('tbk_'+require('crypto').randomBytes(32).toString('base64url'))"
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

第一项是 TB_BOOTSTRAP_ADMIN_SK，第二项是 TB_SECRET_ENCRYPTION_KEY。立即把两者分别保存到密码管理器或独立灾备 Secret：前者不会从网关恢复，后者丢失后无法解密已有 SecretStore。部署表单会把两者作为加密 Worker Secret，而不是明文 vars 注入。

新 Worker 如果没有 Admin secret 会 fail closed。不要先部署一个无信任根实例，再试图从日志“找回管理员密码”。

2. 启动 Deploy Button

从 tool-bridge GitHub 首页点击 Deploy to Cloudflare。在 Cloudflare 流程中：

选择或创建目标 GitHub 仓库；
选择 Cloudflare 账户；
把两项本地生成值分别填入 TB_BOOTSTRAP_ADMIN_SK 和 TB_SECRET_ENCRYPTION_KEY；
确认模板请求创建的资源；
等待首次构建与部署完成。

当前模板资源：

资源	binding	用途
Workers KV	`TB_KV`	节点树配置、SK hash、Plugin manifest 等状态
R2 bucket	`TB_R2`	Context 对象与大型 `$ref` 内容
Durable Object	`TB_DEVICE`	每个设备的 WebSocket 会话与 hibernation 状态
Static Assets	`ASSETS`	`/ui` Dashboard

这张表只描述当前一键模板，不应用来推断完整源码 gateway 或未来版本。精确资源始终以生成仓库的 wrangler.jsonc 和部署计划为准。

3. 验证首次部署

从部署结果复制 https://<worker>.workers.dev URL。先验证公开健康端点：

curl --fail https://<worker>.workers.dev/healthz

再用保存的 Admin SK 验证认证数据面：

export TB_BASE_URL="https://<worker>.workers.dev"
export TB_SK="<从密码管理器读取的 Admin SK>"

curl --fail \
  -H "Authorization: Bearer $TB_SK" \
  "$TB_BASE_URL/~help"

安装 CLI 并保存 profile：

npm install -g @tool-bridge/cli
tb login --base-url "$TB_BASE_URL" --profile cloudflare
tb use cloudflare
tb tree --depth 2
tb help system/status
tb call system/status --tool get

tb login 会提示输入 SK，避免把明文永久写进命令历史。上面的临时 TB_SK 仅用于说明 curl；共享终端应避免明文 export，并在使用后清理 shell 环境。

Dashboard 位于 https://<worker>.workers.dev/ui。

成功证据

/healthz 返回 2xx；
带 Admin SK 的根 ~help 成功；
CLI 能读取 system/status 并调用 get；
/ui 加载后看到与 CLI 一致的节点；
请求根 ~describe 检测实际 capability；当前一键模板没有 D1 时，该入口不声明 Search，可能直接返回 404。

4. 绑定自定义域名

在生成仓库的 Wrangler 配置中添加 Custom Domain route，并把唯一规范 origin 设为：

TB_CANONICAL_ORIGIN=https://tb.example.com

模板默认保留 workers.dev hostname，但关闭 per-version Preview URL，避免多个动态 origin 参与 OAuth。使用自定义域后：

确认 DNS 与 Worker route 生效；
只把正式 HTTPS origin 配入 OAuth provider redirect；
用正式域名重新创建或更新本地 CLI profile；
分别验证 /healthz、/~help、/ui 和真实 Provider；
确认日志与错误中不出现 Admin SK、OAuth token 或敏感 arguments。

不要把自定义域名误绑到公共文档 Pages 项目；本页部署的是 tool-bridge 网关 Worker。

5. 可选的 R2 直签链接

默认情况下，大型 $ref 内容可以经网关 ~ref 中转。需要直接生成 R2 presigned URL 时，可在生成仓库配置非敏感 vars：

TB_R2_S3_ENDPOINT：账户对应的 R2 S3 endpoint；
TB_R2_BUCKET：实际 bucket 名。

签名凭证进入网关 SecretStore 的保留引用 r2-presign，或使用对应的 Worker Secret。不要把 access key 写进 vars 或 wrangler.jsonc。

是否需要直签取决于数据大小、下载路径和安全策略。未配置时中转路径仍应可用，不要为了“配置完整”无条件扩大凭证面。

一致性与安全边界

Workers KV 的认证和注册读取存在最终一致窗口；紧急吊销或更新后要等待传播并验证；
Admin SK 和加密根只通过 Worker Secret 注入，不进入仓库；
上游 token 使用 SecretStore，节点只保存 authRef；
远端 federation allowlist 为空时拒绝所有目标；
HTTP 上游默认只允许 HTTPS；不要在生产设置 TB_ALLOW_INSECURE_HTTP=true；
/healthz 成功不代表 SK、KV 状态和数据面可用。

常见失败

首次构建因缺 Secret 失败

重新检查 Deploy 表单是否同时提供两项 trust roots。不要把 secret 改成普通 vars 来绕过构建。

根 `~help` 返回 401

确认使用的是部署前保存的 Admin SK，而不是加密密钥。已有 Worker 的 bootstrap 状态不会被后续随意替换。

`~search` 返回 404

一键模板当前没有 D1 Search，这是预期能力差异。请求根 ~describe 复核；需要 Search 时迁移到源码部署并再次以运行时结果验收。

自定义域下 OAuth 回调失败

核对 route、TB_CANONICAL_ORIGIN 与 provider redirect URI 是否完全一致，并避免使用动态预览 origin。

设备频繁离线

确认设备使用稳定 ID、网络允许 WebSocket，并检查 Durable Object 与设备端重连日志。不要把普通 HTTP 请求超时误用作长连接生命周期。

下一步

签发第一把受限 SK；
按生产上线检查清单验证权限、密钥和恢复边界；
需要 D1 Search 或源码定制时改用从源码部署到 Cloudflare。