跳转到内容
tool-bridge

使用 Dashboard

Dashboard 是 tool-bridge 同一公开 HTTP API 的图形界面。它适合浏览树、填写复杂表单、比较配置和完成常见管理任务；它不会绕过 SK scope，也不是独立的控制面数据库。

打开与登录

Section titled “打开与登录”

标准宿主在网关同源路径提供：

https://tb.example.com/ui/

本地 Docker quickstart 对应 http://127.0.0.1:8787/ui/。/ui 静态页面本身无需 SK，登录后浏览器才用你提供的 SK 请求受保护 API。

什么时候使用 Dashboard

Section titled “什么时候使用 Dashboard”

适合：

  • 可视化浏览节点、在线状态和 Search 结果；
  • 根据 catalog exportDetails 填写凭证与挂载配置；
  • 管理 SK、Secret 元数据、Plugin、Federation 和路径说明；
  • 查看节点详情、Feedback 和调用结果。

不适合：

  • 无人值守 CI；
  • 大批量资源变更；
  • 需要把输出稳定传给另一个程序；
  • 在不可信浏览器中管理高权限凭证。以上场景使用 CLI 或 HTTP。

权限决定你看见什么

Section titled “权限决定你看见什么”

Dashboard 不是“管理员视角”。页面、按钮、节点和列表都来自当前 SK：

  • 缺目标路径 read 时，节点不会出现在树或列表中，直接访问通常也是 404；
  • 可见但缺 call/write/admin 时，相应操作会被服务端拒绝；
  • 客户端表单校验只是快速反馈，服务端仍做权威校验；
  • Search 未由宿主启用时，搜索页不能凭空生成工具索引。

为日常浏览签发低权限 SK；只在明确管理窗口切换到管理 SK，不要让 Admin SK 长期驻留在个人浏览器。

具体 scope、deny 与不可见 404 见权限、SK 与可见性。

推荐的验收流程

Section titled “推荐的验收流程”
  1. 打开 /ui/，连接目标 BaseURL；
  2. 在树页面确认 system/status 和预期业务路径可见；
  3. 打开节点详情，比较 description、kind、工具列表和参数 schema；
  4. 用一个 read-only 工具完成测试调用；
  5. 查看同一路径的 Feedback；
  6. 用 CLI tb help <path> --json 对照同一节点。

成功证据是 Dashboard 与 CLI/HTTP 看见同一资源和错误语义，而不是页面单独“显示成功”。

管理集成与凭证

Section titled “管理集成与凭证”

内置集成表单应来自目标实例 system/catalog 的逐 export 契约。选择 export 后再填写：

  • credential：进入 SecretStore；
  • mount config：进入可回显的 providerConfig；
  • path/description：进入节点注册记录。

Secret 值是只写不读。编辑挂载时，留空通常表示保留/复用现有凭证，而不是从服务端读取明文。删除节点也不会自动删除 Secret，因为其他节点可能仍引用它。

为什么节点只能保存 authRef、调用者 SK 又不能透传上游，见密钥、出站身份与安全边界。

管理 SK

Section titled “管理 SK”

签发新 SK 时重点检查：

  • owner 是否能用于审计；
  • scope path 是否足够窄；
  • action 是否只包含必要的 read/write/call/register/admin；
  • deny 是否覆盖高风险子树；
  • Device SK 是否设置 registerPaths；
  • expiry 是否符合任务生命周期。

明文只在签发响应出现一次。立即保存；重新打开详情页只应看到元数据，不会恢复明文或 hash。紧急处置可以 disable，再评估 delete；Workers KV 部署存在吊销传播窗口，强一致要求应选择合适宿主并设计额外防线。

Section titled “Feedback、Note 与 Search”
  • Feedback 属于具体路径，使用者可查看、提交、投票；
  • Note 是管理员说明，会进入对应路径 ~help；
  • 高分 Feedback 也会进入 ~help，启用 Search 时可影响派生检索文本；
  • Search 是派生视图，节点与权限仍是权威数据。

不要把 Feedback 当审批或审计日志，也不要用 Note 保存 secret。详情见发现、反馈与协作。

常见失败

Section titled “常见失败”
现象 处理
/ui/ 404 宿主没有部署 Dashboard assets，或反向代理路径错误
页面加载但 API 401 SK 缺失、错误、过期或已禁用；重新连接正确实例
节点/菜单消失 当前 SK 没有 read，或节点已被卸载；用同一 SK 的 CLI 复核
保存表单 403 服务端判定缺 write/register/admin；不要只看按钮是否可点
Search 页面不可用 宿主没有 Search capability；使用树和 help
OAuth 回调到错误域名 canonical origin 与实际自定义域不一致
Secret 编辑后无法回显 这是只写不读的预期边界，不是丢失显示功能
深链刷新落到 404 代理必须让 /ui/* 回到同源 Dashboard，同时不能吞掉 API 路由

退出、回滚与共享机器

Section titled “退出、回滚与共享机器”

使用完高权限会话：

  1. 在 UI 中退出/断开当前身份；
  2. 清理该网关 origin 的站点数据；
  3. 若凭证可能暴露，立即 disable/rotate 对应 SK；
  4. 用另一把管理员 SK 检查吊销是否生效。

资源变更按资源类型回滚：先卸载节点，再处理独立 Plugin/allowlist，最后在确认无引用后删除 Secret。Dashboard 不应提供“连同所有相关凭证一起删除”的隐式级联。

反向代理要求

Section titled “反向代理要求”

Dashboard 与 API 最好保持同源。代理应：

  • 转发 Authorization；
  • 保留原始 host/proto，尤其是 OAuth；
  • 支持 Device WebSocket upgrade；
  • 只对 /ui/* 做 SPA fallback，不把 ~help、~mcp、system/* 或 POST 数据面吞进前端；
  • 使用 HTTPS 并保持安全响应头。

下一步

Section titled “下一步”