生产上线检查清单

本清单适用于 Node/Docker、Cloudflare Workers 和嵌入式 SDK。它不能把 pre-launch 项目变成已承诺 SLA 的产品，但能帮助你区分“URL 可访问”与“实例具备可治理、可恢复的使用闭环”。

在每项后保留可审计、已脱敏的证据。不要把真实 Admin SK、上游 token、OAuth 响应、Cloudflare 资源 ID 或含敏感 arguments 的原始日志贴进工单。

1. 明确版本、所有者与边界

已固定镜像、npm 包或源码 commit，不使用不可追踪的 latest 作为长期部署依据；
已阅读该版本发布说明，接受 pre-launch 兼容性风险；
已记录实例 owner、值班/维护责任、域名和预期宿主；
已说明它是正式、测试还是临时环境，禁止把预览实例当作稳定生产；
已确认 Search/Context capability 来自目标路径的 ~describe，工具索引与 schema 来自对应层级的 ~help，没有从另一个环境复制静态清单。

2. 保护 trust roots 与凭证

TB_BOOTSTRAP_ADMIN_SK 通过平台 Secret 注入，明文只在密码管理器保留；
TB_SECRET_ENCRYPTION_KEY 通过平台 Secret 注入，并纳入独立灾备保管；
上游凭证进入 SecretStore，节点只保存 authRef / skRef；
providerConfig、URL、query string、日志、调用历史和 Dashboard toast 中没有 secret；
OAuth client、access token 与 refresh token 没有混在同一不受控字段；
已定义上游凭证轮换和吊销流程；
生产环境未启用 TB_ALLOW_INSECURE_BOOTSTRAP 或 TB_ALLOW_INSECURE_HTTP。

验证 SecretStore 时只检查引用存在和真实调用成功，不尝试回读明文。完整边界见密钥、出站身份与安全边界。

3. 验证唯一 HTTPS origin

正式入口使用 HTTPS；
标准 Node/Cloudflare 宿主的 TB_CANONICAL_ORIGIN 与公开 BaseURL 一致；
OAuth redirect 只使用规范 origin；
Node 反向代理保留 Authorization、原 host/proto 和 WebSocket upgrade；
Cloudflare 自定义域没有误绑到公共文档 Pages 项目；
Preview URL 不参与正式 OAuth 或被 Agent 当作长期 BaseURL；
访问日志不会记录 Authorization、SK 或敏感 body。

当前嵌入式 SDK 不暴露 canonicalOrigin 配置；它会回退到请求 origin。SDK 部署应只保留一个稳定 HTTPS origin。必须钉死 OAuth callback origin 的场景，在公开 SDK 增加正式配置前不应宣称满足此项。

4. 检查持久化与一致性

Node / Docker

/data 使用明确持久卷，SQLite 与 objects/ 位于预期目录；
容器删除、重建和主机重启后状态仍在；
备份同时覆盖数据库和对象；
已在隔离环境完成一次恢复演练；
没有把多个独立 SQLite/卷副本误当成一个集群。

Cloudflare

KV、R2、D1（若使用完整源码 Search）和 Durable Object binding 指向目标环境；
已理解 KV 认证/注册更新的最终一致窗口；
紧急 SK 禁用/吊销流程包含传播等待与复测；
D1 Search 被视为派生索引，不是节点或权限真源；
一键模板没有被误写成默认包含 D1 Search。

嵌入式 SDK

生产没有使用 MemoryStateStore；
自定义 store 的备份、一致性和故障行为已经测试；
未装配的 ObjectStore、Plugin catalog 或设备通道不会被文档虚假宣称为可用；当前公开 SDK 没有 SearchIndex 注入项，不宣称支持 ~search。

5. 分层 smoke 测试

公开健康

curl --fail https://tb.example.com/healthz

返回 2xx；
响应不包含 secret 或内部堆栈；
团队理解这不证明认证数据面可用。

Admin 数据面

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

profile 指向正确环境；
根与 builtin ~help 来自当前部署；
状态调用成功；
当前版本和构建产物符合预期。

受限身份

使用只覆盖测试子树的 SK：

tb use production-smoke
tb tree --depth 3
tb help tools/smoke
tb call tools/smoke --tool <runtime-tool-name> --args '<runtime-json>'
tb help system/sk

授权节点可发现并调用；
未授权 system/sk 返回 404；
参数来自目标路径 Help JSON，而不是本页占位符；
测试工具不会产生不可逆外部副作用。

6. 验证真实 Provider，而不只验证 builtin

至少选择一个实际业务来源完成：

SecretStore 写入或 OAuth 授权；
节点挂载；
tb help <path> 读取运行时 schema；
用受限 SK 发起安全调用；
检查上游错误归一、timeout 与 retryable；
检查日志没有泄漏 header/body 中的密钥。

根据部署使用内置集成、MCP、HTTP或Context指南。

如果使用 Federation，还要验证：空 allowlist 拒绝、HTTPS、远端专用 SK、Via 跳数和环检测。详见联邦另一棵 tool-bridge。

7. 验证 CLI、Dashboard 与 MCP 投影

CLI 人类输出可读；--json 只输出一个可解析对象；
分页命令能继续消费 opaque cursor；
Dashboard /ui 与 CLI 看到同一节点和权限；
切换 Dashboard profile 后缓存与历史不串身份；
Secret 明文不会从 Dashboard 管理面回读；
如果对外提供 /<base>/~mcp，MCP Client 只看到该 SK 可见工具；
MCP discovery 与实际调用均成功，而不只是初始化成功。

8. 验证 Search、Feedback 与设备能力

这些都是按部署装配或按身份裁剪的能力，不应默认勾选。

Search

根 ~describe 实际声明 search；
只有声明 search:semantic 时才测试 semantic mode；
受限 SK 搜索结果严格是 Admin 结果的可见子集；
删除或无权节点不会因为陈旧索引继续返回。

Feedback

read 身份能查看目标路径 Feedback；
call 身份能提交/投票；
admin 才能清理；
根路径不接受 Feedback；
团队不把最终一致的投票当作强一致控制状态。

Device

每台设备使用独立 SK、稳定 ID 和受限 registerPaths；
shell 默认 deny all，只开放明确命令；
文件挂载按需要设为只读；
WebSocket 断线、重连、替换连接和 offline 状态正常；
旧连接不能在新 generation 上完成调用。

9. 故障、回滚与恢复

已记录如何判断当前部署版本和目标资源；
已保存上一版本镜像/commit 与恢复步骤；
升级前会冻结写入并备份权威状态；
部署失败不会无界重复创建真实资源或调用真实上游；
已定义 Admin SK 丢失、加密根丢失、上游凭证泄漏的响应流程；
值班人员知道 401、不可见 404、unavailable、rate_limited 和网络错误的不同证据；
故障采集模板会删除 Authorization、SK、OAuth token 和敏感 arguments。

排障流程见故障排查与升级。

上线判定

只有以下证据同时成立，才可以把本轮部署判定为可用：

公开健康、Admin 数据面和受限数据面都成功；
至少一个真实 Provider 完成 ~help 与调用；
未授权路径以 404 隐藏；
Secret 没有进入可读配置或日志；
权威状态能够备份并恢复；
运行时 capability 与对外说明一致；
Dashboard/CLI，以及启用时的 MCP/Device/Search，均按同一身份模型工作。

任何一项失败都应记录为明确风险或阻断项，不能用“页面能打开”代替。

下一步

把 smoke 命令写成不含 secret、可重复运行的 CI；
为每类生产身份建立独立CLI profile和轮换策略；
定期按权限、SK 与可见性审计 scope；
每次升级都重新执行本清单，而不是沿用上一次结果。