添加与切换存储后端

存储后端是一个不可变的 endpoint、bucket 与 region 身份。Store 对象、上传会话和平台 Context 在创建时固定 backendId；切换 active 只影响新建，不会迁移旧数据。

1. 查看已有后端

tb storage list
tb storage get <backend-id>

Dashboard 的存储后端页提供同样的列表、详情、测试、激活与凭证轮换。响应不回显访问密钥或内部凭证引用。

2. 添加一个 S3 兼容服务

准备受保护的 JSON 文件，结构如下：

{
  "name": "archive",
  "connection": {
    "endpoint": "https://s3.example.com",
    "bucket": "tool-bridge-objects",
    "region": "us-east-1",
    "accessKeyId": "<access-key-id>",
    "secretAccessKey": "<secret-access-key>"
  }
}

真实凭证通过文件或 stdin 输入，不进入 argv 或仓库。

tb storage add --file ./storage.json
tb storage test <backend-id> --revision <backend-revision>

测试会执行真实 PUT / HEAD / GET / DELETE、条件写和清理，消耗对象服务资源。只有通过全部能力检查且清理成功的后端才能激活；能建桶或 health 返回 200 不足以证明兼容。

自定义 endpoint 默认要求安全 HTTPS origin。仅由本机安装 defaults 固定的 exact origin 能使用受信任私网例外，公开管理表单不能扩大这条边界。

3. 激活后核对新旧对象

重新读取最新 backend revision 与全局 active revision，然后执行：

tb storage activate <backend-id> \
  --revision <backend-revision> \
  --active-revision <active-revision>

验证一次新上传，再读取切换前的对象。旧对象应继续通过原 backendId 访问；不要删除仍有对象、session、Context 或 active 引用的后端。

4. 为 Context 选择后端

tb ctx mount ctx/handbook \
  --provider storage \
  --backend-id <backend-id> \
  --prefix handbook/

不传 --backend-id 时固定挂载当时的 active。之后切换 active 不会改变这个 Context。直接 --provider s3 的独立连接也不受 active 指针接管。

5. 只轮换凭证

准备只含 accessKeyId 与 secretAccessKey 的受保护 JSON：

tb storage update <backend-id> \
  --revision <backend-revision> \
  --file ./new-credentials.json

新凭证先经真实探测，再发布新 generation；endpoint、bucket 与 region 不变。需要换桶时新增后端，不把轮换凭证当数据迁移。

当前传输范围

标准 Node S3 adapter 使用流式 relay，Store 上传是 single PUT，平台 Context 不披露可选 direct-upload。当前没有 multipart、断点续传或自动跨后端搬迁。客户端中的通用 direct 分支不代表当前部署具有预签名 PUT 能力。