mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-07-22 04:06:44 +08:00
docs: update bat runtime documentation
This commit is contained in:
@@ -4,14 +4,14 @@
|
||||
|
||||
BlueArchive Toolkit 采用 **Monorepo + 多语言混合** 架构，旨在构建一个可持续维护十年以上的工业级开源项目。
|
||||
|
||||
当前文档描述目标架构和已经落地的关键边界。实际实现状态以根目录 `CURRENT_STATUS.md` 和 `PROJECT_PLAN.md` 为准。
|
||||
当前文档描述目标架构和已经落地的关键边界。它不是部署手册；当前可部署能力只有 Rust 官方资源同步任务。API Server、Web、Provider 编排和完整 Go CLI 仍未实现，实际实现状态以根目录 `CURRENT_STATUS.md` 和 `PROJECT_PLAN.md` 为准。
|
||||
|
||||
当前已经可用的官方资源入口包括：
|
||||
|
||||
- `infrastructure/src/bin/bat_official_sync.rs`：Linux 官方资源同步正式入口，支持 one-shot 和 `--watch` 常驻更新。
|
||||
- `infrastructure/src/bin/bat_official_sync.rs`：Linux 官方资源同步正式入口，构建为 `bat`，支持 one-shot、`--watch`、`--daemon`、`status`、`stop`、`restart`、`reload`、`refresh`、`logs`、`verify`、`repair`、`doctor` 和 `clean-stable`。
|
||||
- `infrastructure/src/official_update.rs`：官方自动更新核心服务，负责 auto-discover、snapshot、marker diff、本地 audit/repair。
|
||||
- `infrastructure/examples/official_pull_plan.rs`：开发/审计用 pull plan 入口。
|
||||
- `infrastructure/examples/official_update_check.rs`：历史/开发入口，生产优先使用 `bat-official-sync`。
|
||||
- `infrastructure/examples/official_update_check.rs`：历史/开发入口，生产优先使用 `bat`。
|
||||
- `infrastructure/examples/official_launcher_bootstrap.rs`：显式开发/审计辅助路径，用于核查官方 launcher metadata，不是生产运行依赖。
|
||||
- `docs/guides/official-resource-test-pull.md`
|
||||
|
||||
@@ -99,7 +99,7 @@ cas/
|
||||
|
||||
- `OfficialUpdateService`：auto-discover、snapshot、marker diff、本地 manifest audit/repair。
|
||||
- `OfficialResourcePullService`：官方 URL 校验、`.part` 断点续传、重试、下载 manifest、官方 seed `.hash` 校验。
|
||||
- `bat-official-sync`：正式 binary，支持 one-shot 和 `--watch`。
|
||||
- `bat`：正式 binary，支持 one-shot、`--watch`、`--daemon`、`status`、`stop`、`restart`、`reload`、`refresh`、`logs`、`verify`、`repair`、`doctor` 和 `clean-stable`。
|
||||
|
||||
**当前数据流**：
|
||||
|
||||
@@ -116,7 +116,10 @@ official-sync-snapshot.json + official-download-manifest.json
|
||||
- 不安装、不执行官方 launcher。
|
||||
- 默认平台 `Windows + Android`。
|
||||
- `--auto-discover` 自动获取 `app-version`、`connection-group` 和 `server-info`。
|
||||
- `--watch` 常驻检查，正常检查默认 1 小时，失败重试默认 60 秒，每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 强制刷新一次。
|
||||
- `--watch` / `--daemon` 常驻检查，正常检查默认 1 小时，失败重试默认 60 秒，每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 强制刷新一次。
|
||||
- `refresh --force` 可手动强制刷新；`verify` 只读校验当前官方计划、本地 manifest 和官方 seed hash；`repair` 尝试修复异常资源。
|
||||
- `--daemon` 使用状态目录下的 `bat.sock` 作为 Unix socket JSON-RPC live control plane；PID、状态和日志文件是快照与 fallback。
|
||||
- `status`、`logs`、`reload`、`stop` 和默认形态的 `refresh` 优先通过 RPC 管理后台进程；`restart` 负责重启或替换启动参数；`doctor` 做运行时诊断；`clean-stable` 清理临时文件和失效状态。
|
||||
- 远端 marker 无变化且本地 manifest clean 时不下载。
|
||||
- 本地文件损坏时 repair。
|
||||
- 官方 seed `.hash` 强校验；Addressables `catalog_*.hash` 作为变更 marker。
|
||||
@@ -124,7 +127,7 @@ official-sync-snapshot.json + official-download-manifest.json
|
||||
**后续 Go 职责**：
|
||||
|
||||
- 提供最小稳定 CLI。
|
||||
- 包装或调用 Rust 同步入口，转发 JSON report。
|
||||
- 包装或调用 Rust 同步入口，需要机器输出时使用 `--json` 并转发结构化 report。
|
||||
- 编排 API Server、任务队列、Provider 和用户配置。
|
||||
|
||||
---
|
||||
|
||||
@@ -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 log，stdout 默认输出人类可读摘要；支持 `--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. 审核重点
|
||||
|
||||
|
||||
Reference in New Issue
Block a user