docs: update bat runtime documentation

This commit is contained in:
2026-07-12 23:04:26 +08:00
parent f7255f7c04
commit bd9f50c85c
14 changed files with 195 additions and 115 deletions
@@ -178,7 +178,7 @@
### 3.7 自动更新闭环
`OfficialUpdateService` 是当前 Rust 侧的自动更新核心,正式命令入口是 `bat-official-sync`
`OfficialUpdateService` 是当前 Rust 侧的自动更新核心,正式命令入口是 `bat`
流程是:
@@ -193,7 +193,7 @@
9. 远端变化、本地 audit 发现 repair_needed,或首次空目录运行时,下载并校验官方 URL。
10. 下载成功后写回新的 snapshot。
该入口不安装、不执行官方启动器,也不读取生产外的本地客户端目录。Rust 正式 binary 支持 `--watch` 常驻模式正常情况下默认每 1 小时执行一次检查;每天北京时间(UTC+8)`03:00``16:00``18:00` 会中断普通 sleep 并强制执行一次自动刷新,该轮注入 `force=true`。远端和本地一致时静默等待下次检查,不一致时自动下载或 repair。下载、发现或校验失败时不等待完整正常周期,默认 60 秒后重试;如果固定时间强制刷新失败,会保留 pending force 并按失败重试周期继续重试,可用 `--error-retry``--error-retry-seconds` 调整。单次运行仍保留为核心幂等路径,systemd service、容器或 Go 进程可以只负责守护该常驻进程;cron/systemd timer 调单次模式只是可选集成方式。项目是否热更新、热重载或重启进程,由上层业务集成决定。
该入口不安装、不执行官方启动器,也不读取生产外的本地客户端目录。Rust 正式 binary `bat` 支持单次运行、`--watch` 常驻模式`--daemon` 后台模式,以及 `status``stop``restart``reload``logs``refresh``verify``repair``doctor``clean-stable` 管理命令。`--daemon` 会在后台状态目录下创建 `bat.sock`,使用 Unix socket JSON-RPC 作为 live control plane`bat.pid``bat-status.json``bat-daemon.log` 是快照、诊断和兼容 fallback。`status``stop``logs``reload` 和默认形态的 `refresh` 优先走 RPC`reload` 会唤醒或排队 watch 循环重新自动发现并强制刷新,`restart` 才负责重启进程或替换启动参数。正常情况下默认每 1 小时执行一次检查;每天北京时间(UTC+8)`03:00``16:00``18:00` 会中断普通 sleep 并强制执行一次自动刷新,该轮注入 `force=true`。远端和本地一致时静默等待下次检查,不一致时自动下载或 repair。下载、发现或校验失败时不等待完整正常周期,默认 60 秒后重试;如果固定时间强制刷新失败,会保留 pending force 并按失败重试周期继续重试,可用 `--error-retry``--error-retry-seconds` 调整。默认资源输出目录是 `./bat-resources`,默认后台状态目录是 `/tmp/bat-pid`,二者通过 `--output``--state-dir` 分别配置。单次运行仍保留为核心幂等路径,systemd service、容器或 Go 进程可以只负责守护该常驻进程;cron/systemd timer 调单次模式只是可选集成方式。项目是否热更新、热重载或重启进程,由上层业务集成决定。
对应实现主要在:
@@ -209,7 +209,7 @@ Linux 生产路径:
1. 显式执行 `--auto-discover`,或提供已审计的官方 metadata snapshot。
2. `official_pull_plan` 依据官方 `server-info`、catalog 和 verified platforms 生成全量拉取计划。
3. `bat-official-sync` 对比上次 snapshot 和远端 `.hash` marker;远端无变化时 audit 本地清单,有变化或本地损坏时下载、校验并落盘官方资源。
3. `bat` 对比上次 snapshot 和远端 `.hash` marker;远端无变化时 audit 本地清单,有变化或本地损坏时下载、校验并落盘官方资源。
开发/审计辅助路径:
@@ -231,7 +231,7 @@ Linux 生产路径:
- pull plan 会同时包含 discovery URLs 和 content URLs
- 全量样本下是 `2` 个 discovery URL + `5` 个内容 URL = `7` 个 URL
- `OfficialUpdateService` 能持久化 v2 snapshot,并在远端 marker 内容变化时触发下载决策
- `bat-official-sync` 默认向 stderr 输出 `BlueArchiveToolkit` ASCII banner 和人类可读 progress log成功 JSON report 保持 stdout支持 `--no-progress` 关闭人类输出,支持 `--no-banner` 只关闭横幅,支持 `--watch --interval 1h --error-retry 60s` 常驻运行,非 dry-run 使用 `.official-sync.lock` 防止并发写状态目录
- `bat` 默认向 stderr 输出 `BlueArchiveToolkit` ASCII banner 和 progress logstdout 默认输出人类可读摘要;支持 `--json` 输出稳定 JSON支持 `--no-progress` 关闭进度日志,支持 `--no-banner` 只关闭横幅,支持 `--watch --interval 1h --error-retry 60s` 常驻运行,支持 `--daemon` Unix socket JSON-RPC 控制、`status``stop``restart``reload``logs``refresh --force``verify``repair``doctor``clean-stable`非 dry-run 使用 `.official-sync.lock` 防止并发写资源目录
- `OfficialUpdateService` 能读写 `official-bootstrap-cache.json`,并支持默认开启的 `audit_local` / `repair` CLI 行为
- 下载层能在本地文件 size/BLAKE3/path 或 manifest 不匹配时重新下载
- 官方 seed `.hash` mismatch 会导致下载失败,而不是降级为本地 BLAKE3 猜测
@@ -243,8 +243,8 @@ Linux 生产路径:
- `cargo test -p bat-adapters -- --nocapture`
- `cargo test -p bat-ffi -- --nocapture`
- `cargo test -p bat-infrastructure -- --nocapture`
- `cargo test -p bat-infrastructure --bin bat-official-sync -- --nocapture`
- `cargo run -p bat-infrastructure --bin bat-official-sync -- --help`
- `cargo test -p bat-infrastructure --bin bat -- --nocapture`
- `cargo run -p bat-infrastructure --bin bat -- --help`
## 6. 审核重点