5 分钟本地启动

这条路径使用 Node/Docker 宿主：状态写入 SQLite，对象写入 /data 下的文件存储。它适合第一次试用、单机自托管和内网验证，不需要 Cloudflare 账户。

如果你已经有一个可访问的网关，可以跳到从 ~help 到调用。如果你需要多副本、高可用或严格的生产恢复目标，本页只能作为起点，还需要阅读部署 Node / Docker和生产上线检查清单。

前置条件

• Docker；
• Node.js 22 或更高版本，用来生成随机 trust roots；
• 一个能运行 shell 命令的本机终端；
• 本机 8787 端口未被占用。

1. 生成两项 trust roots

网关首次引导需要一把 Admin SK；SecretStore 还需要一把 32 字节加密密钥。下面的命令只把值放进当前 shell 进程：

export TB_ADMIN_SK="$(node -e "console.log('tbk_'+require('crypto').randomBytes(32).toString('base64url'))")"
export TB_ENCRYPTION_KEY="$(node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))")"

立即把 TB_ADMIN_SK 和 TB_ENCRYPTION_KEY 分别保存到密码管理器或独立灾备 Secret。网关引导后只持久化 SK 的 hash，无法把明文读回来；丢失加密根则无法解密已保存的上游凭证。

不要提交密钥

不要把这两个值写进 Dockerfile、Compose 文件、仓库、截图或可共享的 shell 日志。生产环境应通过平台的 Secret 机制注入。

2. 启动网关

docker run -d --name tool-bridge \
  -p 127.0.0.1:8787:8787 \
  -v tool-bridge-data:/data \
  -e TB_BOOTSTRAP_ADMIN_SK="$TB_ADMIN_SK" \
  -e TB_SECRET_ENCRYPTION_KEY="$TB_ENCRYPTION_KEY" \
  ghcr.io/tokenrollai/tool-bridge:latest

这个示例只把端口绑定到本机回环地址，避免局域网中的其他设备直接访问。命名卷 tool-bridge-data 保存 SQLite 与对象数据，删除或重建容器时不会自动丢失。

latest 便于第一次试用。准备保留状态或用于共享环境时，请固定明确的镜像版本，并在升级前阅读发布说明和备份卷。

查看启动状态：

docker ps --filter name=tool-bridge
docker logs tool-bridge
curl --fail http://127.0.0.1:8787/healthz

成功证据

• 容器状态为 running；
• /healthz 返回 2xx；
• 日志中没有“缺少 Admin SK”或 SQLite/卷权限错误。

/healthz 是公开健康信息，它不证明 Admin SK 已被接受。下一步还要验证认证数据面。

3. 安装 CLI 并登录

npm install -g @tool-bridge/cli
tb login --base-url http://127.0.0.1:8787

按提示输入刚才保存的 Admin SK。tb login 会请求根 ~help，在 SK 被明确以 401 拒绝时停止，然后把 BaseURL 与 SK 保存到本地 profile；其他 HTTP 状态并不等于数据面已经通过验收，所以下面仍要运行 whoami/help/call。配置文件默认位于 ~/.config/tool-bridge/config.json（设置了 XDG_CONFIG_HOME 时跟随它），CLI 会将文件权限收紧为仅当前用户可读。

当前交互输入会回显 SK。它能避免 secret 进入 argv 和 shell history，但共享终端、录屏或旁观环境仍不适合输入 Admin SK。

不要把真实 SK 直接写进可共享的命令行。自动化环境可以通过受保护的 TB_SK 环境变量提供受限 SK；日常交互优先使用 profile。

验证登录目标：

tb whoami
tb status

4. 发现并完成第一次调用

tb tree --depth 2
tb help system/status
tb call system/status --tool get

三个命令分别完成：

1. 浏览当前 SK 可见的树；
2. 从运行时读取 system/status 当前工具、说明和参数契约；
3. 使用信封调用该节点的 get 工具。

成功证据

• tb tree 能看到 system/status；
• tb help system/status 展示 get 工具；
• tb call 返回网关状态而不是 401、404 或 permission_denied。

你也可以直接验证 HTTP：

curl \
  -H "Authorization: Bearer $TB_ADMIN_SK" \
  http://127.0.0.1:8787/~help

curl -X POST \
  -H "Authorization: Bearer $TB_ADMIN_SK" \
  -H "Content-Type: application/json" \
  -d '{"tool":"get","arguments":{}}' \
  http://127.0.0.1:8787/system/status

~help 默认返回 Markdown；Accept: text/plain 返回紧凑 Help DSL；Accept: application/json 返回结构化 Help JSON。builtin/Context 的命令 schema 可在节点级帮助中读取；MCP、HTTP、Plugin 或 SDK Tool 的节点级帮助只返回工具索引，完整 JSON Schema 要继续请求 /<node>/<tool>/~help。客户端不应从本页示例猜测参数。

5. 打开 Dashboard

浏览器访问 http://127.0.0.1:8787/ui，输入相同 BaseURL 和 SK。Dashboard 使用与 CLI 相同的公开 HTTP API，并不是绕过权限的管理通道。

在共享电脑上不要保留 Admin profile；浏览器本地状态也应按敏感凭证处理。完整说明见使用 Dashboard。

常见失败

容器立即退出

docker logs tool-bridge

最常见原因是 TB_BOOTSTRAP_ADMIN_SK 缺失、密钥格式错误或 /data 无法写入。不要用 TB_ALLOW_INSECURE_BOOTSTRAP=true 修复共享环境；该开关只允许一次性本地开发随机生成并打印 Admin SK。

8787 端口已占用

把宿主端口改为另一个本机端口，例如 -p 127.0.0.1:8790:8787，并在 tb login 中使用 http://127.0.0.1:8790。

/healthz 成功但 tb login 失败

检查是否输入了本轮保存的完整 Admin SK、BaseURL 是否多写了 /ui，以及容器是否复用了已有卷。已有状态不会因为换一个 TB_BOOTSTRAP_ADMIN_SK 就重置；bootstrap secret 不是每次启动时覆盖管理员的后门。

tb help 返回 404

对受限身份而言，404 可能表示路径不存在，也可能表示没有该路径的 read 权限。这是防止枚举树结构的设计。先用 tb tree 检查可见范围，再阅读权限、SK 与可见性。

停止与清理

停止并删除容器，但保留数据卷：

docker rm -f tool-bridge

只有确认不再需要任何本地状态时，才删除卷：

docker volume rm tool-bridge-data

删除卷会永久移除 SQLite、节点记录、SK hash、SecretStore 数据与对象文件，无法撤销。

下一步

• 阅读从 ~help 到调用，建立 discover-first 使用方式；
• 按权限、SK 与可见性创建第一把受限 SK；
• 接入一项真实的内置集成或 MCP Server；
• 准备长期运行时进入部署 Node / Docker。