BlueArchiveToolkit/docs/guides/bat-api-local-live-smoke.md

bat-api 同机 live 联调

目的

该 runbook 验证生产拓扑的本地形态：Rust bat 与 Go bat-api 在同一主机上运行，二者通过同一个 bat.sock Unix socket 和同一个已发布资源文件系统协作。

测试使用仓库内完整 release fixture，并把所有 daemon、HTTP 服务、release 目录和报告写入一个新的 /tmp 隔离目录。它不访问官方网络，不读取现有客户端目录，也不写入开发机生产资源目录。

命令

make bat-api-local-live-smoke

脚本会按需构建 bat 和 bat-api，然后在同一临时目录中：

1. 创建版本化 release、official-version-state.json 和 current symlink。
2. 启动真实 Rust bat --daemon，验证 live bat.sock RPC。
3. 启动 Go bat-api，通过 RPC 发现 resource_root 和 manifest；Go 不读取 daemon 状态文件。
4. 验证 /healthz、/readyz、/v1/bootstrap、server-info 和 launcher resource bootstrap。
5. 验证 CDN GET、HEAD、Range、ETag、Last-Modified、缓存头、未索引路径和编码 dot-segment 越界路径。
6. 切换 current 到下一个已发布版本，确认 API 索引跟随 RPC 返回的版本变化。
7. 清空已发布版本，确认旧索引不会继续分发，/readyz 返回 503。
8. 停止并重启 Rust daemon，确认 RPC 断开时 API 返回未 ready，重连后恢复 ready。

成功时脚本输出 LOCAL_BAT_API_LIVE_SMOKE_OK，并打印类似以下报告路径：

/tmp/bat-api-local-live-<UTC timestamp>/report/SMOKE_REPORT.md

报告目录不提交 Git；需要审阅时应保存该次命令输出和报告目录位置。

生产边界

• Rust bat 负责官方发现、下载、校验、发布、版本状态和 bat.sock RPC。
• Go bat-api 只通过 RPC 发现已发布 resource_root 和 manifest，并提供 HTTP bootstrap/CDN 读服务。
• 生产中两者必须使用同一主机、同一容器或同一共享文件系统；bat.sock 不应暴露到公网。
• --resource-root / BAT_API_RESOURCE_ROOT 只用于 fixture 或应急只读诊断，不能替代生产 RPC 发现。
• make official-smoke 是独立的官方网络全量拉取 runbook；本文件的本地 fixture smoke 不证明官方网络可达或官方全量资源下载成功。