跳转到内容
tool-bridge

从源码部署到 Cloudflare

源码部署使用 tool-bridge monorepo 中的完整 gateway 入口。与一键模板相比，它会装配完整内置 integration catalog，并为工具 Search 创建 D1；适合需要完整能力、源码定制或可审计 CI 的团队。

如果你只想用最少步骤得到轻量 Worker，并且不需要 D1 Search，先看Cloudflare 一键部署。如果你没有 Cloudflare 账户，Node/Docker 更适合作为第一次验证环境。

完整源码形态包含什么

Section titled “完整源码形态包含什么”
资源 主要用途
Workers KV 树配置、SK hash、Plugin manifest 等权威状态
R2 Context 对象与大型 $ref 内容
D1 工具 Search 的 FTS/索引派生状态
Durable Objects 设备 WebSocket 会话与 hibernation
Static Assets Dashboard /ui

D1 SearchIndex 是派生索引，不是权限或节点的权威数据。Search 响应仍会重新读取节点并按请求身份 hydrate、裁剪。

资源形状以当前 checkout 的 packages/gateway/wrangler.jsonc 与 CLI 部署计划为准；运行时 Search capability 以根 ~describe 为准。本表不能替代目标实例验收。

前置条件

Section titled “前置条件”
  • Node.js 22+ 与 pnpm 11+；
  • Git；
  • 有权创建 Workers、KV、R2、D1 与 Durable Objects 的 Cloudflare 账户；
  • 已完成 Wrangler 支持的 Cloudflare 登录或 API token 配置；
  • 本机密码管理器；
  • 可选：已托管在 Cloudflare 的自定义域。

1. 获取源码并安装 CLI

Section titled “1. 获取源码并安装 CLI”
Terminal window
git clone https://github.com/TokenRollAI/tool-bridge
cd tool-bridge
corepack enable
pnpm install
npm install -g @tool-bridge/cli

部署前确认当前 checkout 是你要发布的 commit，并阅读该版本发布说明。pre-launch 期间不要默认从任意分支直接覆盖保留状态的共享实例。

2. 运行初始化向导

Section titled “2. 运行初始化向导”
Terminal window
tb init cloudflare --repo .

向导负责：

  1. 发现 Cloudflare 登录状态并选择账户；
  2. 为新 Worker 生成 Admin SK 与 SecretStore 加密根；
  3. 幂等创建 KV、R2 与 D1，准备 Durable Object/Assets 配置；
  4. 构建 Dashboard 和 gateway；
  5. 部署 Worker；
  6. 验证根 ~help；
  7. 把目标保存到本机 tb profile。

Admin SK 只显示一次，请立即保存到密码管理器。tb init 不接受用普通 --sk 参数向新 Worker注入 Admin SK；对已存在的同名 Worker，它要求使用指定 profile 验证，避免误覆盖未知实例。

当前向导会自动生成 TB_SECRET_ENCRYPTION_KEY，通过临时的 0600 secrets file 注入 Worker，但不会把加密根显示或返回给操作者。它会留在现有 Cloudflare Worker Secret 中；如果你的恢复目标要求把加密根独立托管、跨账户重建或迁移，当前向导本身没有完成 escrow，不能在生产检查表中把这一项标为已完成。迁移前应评估重新录入上游凭证或使用项目后续提供的受支持恢复流程。

精确选项以当前安装版本为准：

Terminal window
tb init cloudflare --help

指定账户、域名与资源前缀

Section titled “指定账户、域名与资源前缀”
Terminal window
tb init cloudflare \
  --repo . \
  --account-id <cloudflare-account-id> \
  --domain tb.example.com \
  --name-prefix team-a \
  --profile production \
  --yes

--yes 只确认创建资源和部署，不会让缺失的 Cloudflare 权限、Secret 或已有 Worker 身份验证自动通过。

3. 理解账户特定写回

Section titled “3. 理解账户特定写回”

公共仓库中的 Wrangler 配置是账户中立模板：真实 account ID、域名、KV/D1/R2 资源 ID 和登录态不应提交。Provision 会为当前 checkout 回填实际部署目标。

部署后检查工作树，区分：

  • 你有意维护的 fork/环境配置；
  • provision 产生的账户特定值；
  • 不应推回公共上游的本机状态和凭证。

不要把 Cloudflare account ID、资源 ID、Admin SK、加密密钥或 Wrangler 登录文件提交到公共仓库。团队若需要 GitOps，应在私有环境仓库或平台 Secret 中明确管理，而不是修改上游的账户中立模板。

4. 部署后验证

Section titled “4. 部署后验证”

切换到向导创建的 profile：

Terminal window
tb use production
tb use
tb whoami
tb status
tb tree --depth 2
tb help system/status
tb call system/status --tool get

用保存的 Admin SK 请求根 ~describe，确认 capabilities 包含 search 后，再执行：

Terminal window
curl \
  -H "Authorization: Bearer $TB_SK" \
  -H "Accept: application/json" \
  https://tb.example.com/~describe
Terminal window
tb search status

Search 可能在还没有足够业务工具时结果很少，但 capability、分页和权限语义应正常。然后创建一把受限 SK，验证授权子树可见、未授权管理路径返回 404。

成功证据

Section titled “成功证据”
  • /healthz 与带 Admin SK 的 /~help 分别成功；
  • 无参数 tb use 标出预期 profile，tb whoami 显示预期 BaseURL 与认证状态；Cloudflare account 另用 pnpm exec wrangler whoami --json 核对；
  • 根 ~describe 声明实际装配的 Search capability；
  • /ui 能加载当前部署的 Dashboard，而不是旧资产；
  • 一次真实 integration 调用成功；
  • 受限 SK 的 allow/deny/404 符合预期；
  • 如使用设备，WebSocket 连接、断线恢复与离线状态正常。

5. 非交互与 CI

Section titled “5. 非交互与 CI”

CI 运行时显式提供账户、profile、checkout 和 --yes：

Terminal window
tb init cloudflare \
  --repo . \
  --account-id "$CLOUDFLARE_ACCOUNT_ID" \
  --profile production \
  --yes

CI 必须从受保护 Secret 获得 Cloudflare API token/account ID，并处理已有 Worker 的身份验证。不要在日志打印 Admin SK、加密根、TB_SK 或完整命令环境。

在自动部署前至少执行仓库规定的验证和 build。verify 与 build 是不同闸门；不能因为单测通过就跳过实际 gateway/Dashboard 产物构建。

生产 CI 还应：

  • 并发串行化同一环境的部署；
  • 绑定明确 commit 和包版本；
  • 保存不含 secret 的资源计划和 smoke 结果；
  • 失败时停止重复重试，避免连续创建或修改真实资源；
  • 部署后用受限测试 SK 验证，而不只使用 Admin。

自定义域与 OAuth

Section titled “自定义域与 OAuth”

提供 --domain tb.example.com 时，provision 会配置自定义域和 canonical origin。验收时确认：

  • 唯一正式 origin 是 https://tb.example.com；
  • OAuth provider redirect 与该 origin 完全一致；
  • 预览 URL 不被用作生产 OAuth 回调；
  • CLI、Dashboard 和 Agent profile 都指向同一个 BaseURL；
  • 反复初始化不会意外创建另一个同名身份根。

安全与一致性边界

Section titled “安全与一致性边界”
  • Workers KV 的认证和注册读取有最终一致窗口；更新/吊销后要等待传播并复测；
  • D1 Search 是派生状态，不能用搜索结果作为权限真源；
  • SecretStore 凭证只通过 authRef 使用，不进入 providerConfig；
  • remote allowlist 为空时拒绝所有 federation；
  • 上游默认 HTTPS，生产不启用 insecure HTTP；
  • Cloudflare 真实资源验证会产生副作用和潜在费用，自动化需要限制重复执行。

常见失败

Section titled “常见失败”

向导找不到或选错账户

Section titled “向导找不到或选错账户”

检查 Wrangler 登录身份与 API token 权限；多账户环境显式传 --account-id。不要把默认账户选择留给无交互 CI。

发现同名 Worker 但无法继续

Section titled “发现同名 Worker 但无法继续”

向导会要求用对应 profile 验证现有实例。这是防止覆盖未知 Admin trust root 的保护。找回正确 profile/管理员身份，或使用不同 name prefix；不要试图通过新 bootstrap secret 接管已有状态。

Section titled “部署成功但没有 Search”

先读取根 ~describe，再检查实际部署是否使用完整 deployEntry、D1 binding 是否存在、Dashboard/gateway 是否来自当前 build。不要从 Worker URL 可访问推断 bundle 正确。

OAuth 回调或 R2 直签使用错误 origin

Section titled “OAuth 回调或 R2 直签使用错误 origin”

核对自定义域、TB_CANONICAL_ORIGIN、R2 endpoint/bucket 与 SecretStore 凭证。账户 ID 和 endpoint 是环境事实，不应从其他部署复制。

下一步

Section titled “下一步”