nyaKazuha/BlueArchiveToolkit
1
0
Fork 0
mirror of https://github.com/Yuyi-Oak/BlueArchiveToolkit.git synced 2026-07-22 01:15:14 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: update bat runtime documentation

Browse Source
This commit is contained in:
nyaKazuha
2026-07-12 23:04:26 +08:00
parent f7255f7c04
commit bd9f50c85c
14 changed files with 195 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/guides/official-resource-test-pull.md
+69 -44
View File
@@ -20,36 +20,32 @@
查看命令参数：
```bash
cargo run -p bat-infrastructure --bin bat-official-sync -- --help
cargo run -p bat-infrastructure --bin bat -- --help
```
构建生产 binary：
```bash
cargo build --release -p bat-infrastructure --bin bat-official-sync
cargo build --release -p bat-infrastructure --bin bat
```
使用 release binary 做一次 dry-run：
```bash
target/release/bat-official-sync \
target/release/bat \
--auto-discover \
--platforms Windows,Android \
--output /var/lib/bluearchive-toolkit/official \
--dry-run
```
常驻自动更新：
```bash
target/release/bat-official-sync \
target/release/bat \
--auto-discover \
--platforms Windows,Android \
--output /var/lib/bluearchive-toolkit/official \
--watch
```
生产输出目录必须是独立状态目录。不要使用已有游戏客户端目录、官方启动器安装目录、人工维护资源目录，或开发机上的 `/home/wanye/D/BlueArchive`。
默认资源输出目录是 `./bat-resources`，默认后台状态目录是 `/tmp/bat-pid`。后台状态目录会保存 `bat.sock`、`bat.pid`、`bat-status.json` 和 `bat-daemon.log`；其中 `bat.sock` 是 live daemon 的 Unix socket JSON-RPC 控制通道，其他文件是快照和故障排查用。生产资源输出目录必须是独立目录；需要覆盖时用 `--output <资源目录>`，不要使用已有游戏客户端目录、官方启动器安装目录、人工维护资源目录，或开发机上的 `/home/wanye/D/BlueArchive`。
## 1. 当前流程
@@ -92,8 +88,7 @@ cargo run -p bat-infrastructure --example official_launcher_bootstrap -- \
```bash
cargo run -p bat-infrastructure --example official_pull_plan -- \
--auto-discover \
--platforms Windows,Android \
--output /tmp/ba-official-pull \
--output /tmp/bat-official-pull \
--dry-run
```
@@ -104,8 +99,7 @@ cargo run -p bat-infrastructure --example official_pull_plan -- \
--server-info-file r93_70_xxxxxxxxxxxxxxxxxxxx.json \
--connection-group Prod-Audit \
--app-version 1.70.0 \
--platforms Windows,Android \
--output /tmp/ba-official-pull \
--output /tmp/bat-official-pull \
--dry-run
```
@@ -116,8 +110,7 @@ cargo run -p bat-infrastructure --example official_pull_plan -- \
--server-info-path /path/to/server-info.json \
--connection-group Prod-Audit \
--app-version 1.70.0 \
--platforms Windows,Android \
--output /tmp/ba-official-pull \
--output /tmp/bat-official-pull \
--dry-run
```
@@ -135,8 +128,7 @@ cargo run -p bat-infrastructure --example official_pull_plan -- \
```bash
cargo run -p bat-infrastructure --example official_pull_plan -- \
--auto-discover \
--platforms Windows,Android \
--output /tmp/ba-official-pull
--output /tmp/bat-official-pull
```
程序会：
@@ -153,7 +145,7 @@ cargo run -p bat-infrastructure --example official_pull_plan -- \
## 5. 自动更新检查
正式自动更新入口是 `bat-official-sync`。它会保存上一次成功同步的 snapshot，下次运行时先自动发现当前官方 metadata，再和 snapshot 对比：
正式自动更新入口是 `bat`。它会保存上一次成功同步的 snapshot，下次运行时先自动发现当前官方 metadata，再和 snapshot 对比：
- 每轮都会先拉取轻量官方 metadata 和 `.hash` marker。
- URL 没变但 `.hash` / marker 内容变更时，也会判定为需要更新。
@@ -169,7 +161,7 @@ cargo run -p bat-infrastructure --example official_pull_plan -- \
- 校验报告分层输出 `official_seed_hash_verified_count`、`local_manifest_verified_count`、`addressables_marker_checked_count`、`unverified_marker_count`。
- 下载阶段复用同一套本地清单和 `.part` 续传逻辑；没有清单或校验不匹配的文件会重新下载。
状态文件默认位于 `--output` 下：
资源同步状态文件默认位于 `--output` 下：
- `official-sync-snapshot.json`：上一次成功同步的 v2 snapshot，包含 app version、connection group、bundle version、addressables root、endpoint URL、官方 seed `.hash` 内容、Addressables `catalog_*.hash` marker、launcher metadata 摘要和 `GameMainConfig` 摘要。
- `official-bootstrap-cache.json`：`--auto-discover` 的 `GameMainConfig` 解析缓存。launcher metadata 未变时复用缓存；metadata 变化时才通过官方 HTTP 按 manifest 下载必要 `resources.assets` 或旧版 game zip 到临时目录解析。
@@ -178,22 +170,16 @@ cargo run -p bat-infrastructure --example official_pull_plan -- \
先 dry-run：
```bash
cargo run -p bat-infrastructure --bin bat-official-sync -- \
cargo run -p bat-infrastructure --bin bat -- \
--auto-discover \
--platforms Windows,Android \
--output /tmp/ba-official-update \
--snapshot /tmp/ba-official-update/official-sync-snapshot.json \
--dry-run
```
如果需要在 dry-run 阶段审阅完整下载 URL，加 `--plan`：
```bash
cargo run -p bat-infrastructure --bin bat-official-sync -- \
cargo run -p bat-infrastructure --bin bat -- \
--auto-discover \
--platforms Windows,Android \
--output /tmp/ba-official-update \
--snapshot /tmp/ba-official-update/official-sync-snapshot.json \
--dry-run \
--plan
```
@@ -201,39 +187,78 @@ cargo run -p bat-infrastructure --bin bat-official-sync -- \
确认后执行真实更新：
```bash
cargo run -p bat-infrastructure --bin bat-official-sync -- \
--auto-discover \
--platforms Windows,Android \
--output /tmp/ba-official-update \
--snapshot /tmp/ba-official-update/official-sync-snapshot.json
cargo run -p bat-infrastructure --bin bat -- \
--auto-discover
```
Rust 常驻更新模式默认每 1 小时执行一次检查，符合则静默，不符合则自动拉取/repair 并输出 JSON report：
Rust 常驻更新模式默认每 1 小时执行一次检查，符合则静默，不符合则自动拉取/repair 并输出人类可读摘要；需要稳定 JSON report 时加 `--json`：
```bash
cargo run -p bat-infrastructure --bin bat-official-sync -- \
cargo run -p bat-infrastructure --bin bat -- \
--auto-discover \
--platforms Windows,Android \
--output /tmp/ba-official-update \
--snapshot /tmp/ba-official-update/official-sync-snapshot.json \
--watch
```
后台自动运行使用 `--daemon`。它会启动一个脱离终端的 watch 子进程，资源默认写入 `./bat-resources`，后台控制和状态默认写入 `/tmp/bat-pid`：
```bash
cargo run -p bat-infrastructure --bin bat -- \
--auto-discover \
--daemon
cargo run -p bat-infrastructure --bin bat -- status
cargo run -p bat-infrastructure --bin bat -- logs
cargo run -p bat-infrastructure --bin bat -- restart
cargo run -p bat-infrastructure --bin bat -- reload
cargo run -p bat-infrastructure --bin bat -- stop
```
`status`、`stop`、`logs`、`reload` 和默认形态的 `refresh` 会优先连接 `bat.sock`，通过 Unix socket JSON-RPC 和 live daemon 通信；socket 不可用时，`status`、`stop` 会回退到 PID/状态文件兼容路径。`restart` 会停止旧后台进程并按保存参数或显式参数重新启动；`reload` 在未显式传入同步参数时不会重启进程，而是唤醒或排队 watch 循环重新执行自动发现和强制刷新：空闲睡眠时立即执行，正在同步时等当前轮结束。所有命令默认输出人类可读摘要，脚本集成时加 `--json`。
如果要把后台状态目录改到其他位置，使用 `--state-dir <目录>`：
```bash
cargo run -p bat-infrastructure --bin bat -- \
--auto-discover \
--daemon \
--state-dir /tmp/bat-prod-pid
cargo run -p bat-infrastructure --bin bat -- status --state-dir /tmp/bat-prod-pid
cargo run -p bat-infrastructure --bin bat -- logs --state-dir /tmp/bat-prod-pid --tail 200
cargo run -p bat-infrastructure --bin bat -- stop --state-dir /tmp/bat-prod-pid
```
常用手动维护命令：
```bash
cargo run -p bat-infrastructure --bin bat -- refresh
cargo run -p bat-infrastructure --bin bat -- refresh --force
cargo run -p bat-infrastructure --bin bat -- verify
cargo run -p bat-infrastructure --bin bat -- repair
cargo run -p bat-infrastructure --bin bat -- doctor
cargo run -p bat-infrastructure --bin bat -- clean-stable
```
- `refresh` 执行一次同步检查；`refresh --force` 强制刷新并重新匹配当前官方资源。
- 如果后台 daemon 正在运行，并且 `refresh` 没有显式指定另一套资源目录、server-info、connection-group、app-version、platforms、snapshot、curl 或 unzip 参数，`refresh` / `refresh --force` 会通过 RPC 唤醒或排队后台进程执行；否则作为一次性前台同步运行。
- `verify` 只读验证当前官方计划、本地 manifest size+BLAKE3，以及本地已有官方 seed `.bytes/.hash` 对的 xxHash32；资源缺失、远端变化或本地损坏时返回非 0。
- `repair` 在有异常资源时尝试重新下载并修复，成功后重新写 manifest 和 snapshot。
- `doctor` 检查输出目录、后台状态目录、curl/unzip、后台 PID、RPC socket 和资源锁。
- `clean-stable` 只能在后台未运行且 RPC socket 不可连接时清理 `.part`、`.tmp`、失效 PID、失效 socket 和失效锁，不删除正式资源文件。
如需调整间隔：
```bash
cargo run -p bat-infrastructure --bin bat-official-sync -- \
cargo run -p bat-infrastructure --bin bat -- \
--auto-discover \
--platforms Windows,Android \
--output /tmp/ba-official-update \
--watch \
--interval 30m \
--error-retry 60s
```
`--interval` 是正常检查周期，默认 `1h`；watch 模式还会在每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 强制执行一次自动刷新，该轮会注入 `force=true`，并且会中断普通 interval 的 sleep。`--error-retry` 是下载、发现或校验失败后的重试周期，默认 `60s`，也可以用 `--error-retry-seconds 60`。CLI 默认启动时向 stderr 打印 `BlueArchiveToolkit` ASCII banner，并把人类可读的阶段进度日志写到 stderr，包括自动发现、server-info、marker、catalog、audit、download 和 snapshot 阶段；成功时 stdout 输出稳定 JSON report。需要纯机器输出时加 `--no-progress`，需要显式开启则用 `--progress`；只想关闭横幅但保留日志时可加 `--no-banner`。错误时 stderr 输出 JSON error，watch 模式下错误 JSON 的 `next_retry_seconds` 使用失败重试周期；如果未关闭 progress，错误 JSON 前可能已有 banner 和进度日志。普通错误 exit `1`，状态目录锁冲突 exit `75`。
默认平台是 `Windows,Android`，无需显式传 `--platforms`；只有要覆盖默认平台时才传。`--interval` 是正常检查周期，默认 `1h`；watch/daemon 模式还会在每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 强制执行一次自动刷新，该轮会注入 `force=true`，并且会中断普通 interval 的 sleep。`--error-retry` 是下载、发现或校验失败后的重试周期，默认 `60s`，也可以用 `--error-retry-seconds 60`。CLI 默认启动时向 stderr 打印 `BlueArchiveToolkit` ASCII banner，并把阶段进度日志写到 stderr，包括自动发现、server-info、marker、catalog、audit、download 和 snapshot 阶段；命令结果默认以人类可读摘要写到 stdout。需要纯机器输出时加 `--json --no-progress`，需要显式开启进度日志则用 `--progress`；只想关闭横幅但保留日志时可加 `--no-banner`。错误时 stderr 输出 JSON error，watch 模式下错误 JSON 的 `next_retry_seconds` 使用失败重试周期；如果未关闭 progress，错误 JSON 前可能已有 banner 和进度日志。普通错误 exit `1`，资源目录锁冲突 exit `75`，`verify` 或 `doctor` 发现问题也返回非 0。
生产可以直接运行 `--watch`，也可以用 systemd service、容器或 Go 进程守护它。cron/systemd timer 仍可调用单次模式，但不再是 Rust 自动更新的唯一方式。项目是否热更新、热重载或重启进程，由上层业务集成决定。生产目录应使用独立输出目录，不要指向现有客户端或人工维护的资源目录。非 dry-run 每轮会创建 `--output/.official-sync.lock`，防止并发写同一状态目录。
生产可以直接运行 `--watch`，也可以用 `--daemon` 后台运行，或者用 systemd service、容器或 Go 进程守护它。cron/systemd timer 仍可调用单次模式，但不再是 Rust 自动更新的唯一方式。项目是否热更新、热重载或重启进程，由上层业务集成决定。生产资源目录应使用独立输出目录，不要指向现有客户端或人工维护的资源目录。非 dry-run 每轮会创建 `--output/.official-sync.lock`，防止并发写同一资源目录。
需要只做探测时可以加 `--dry-run`。需要关闭本地 audit 或 repair 时可以显式使用 `--no-audit-local` 或 `--no-repair`，但生产同步默认应保持开启。
@@ -255,7 +280,7 @@ cargo run -p bat-infrastructure --bin bat-official-sync -- \
- `infrastructure/examples/official_launcher_bootstrap.rs`
- `infrastructure/examples/official_pull_plan.rs`
- `infrastructure/src/bin/bat_official_sync.rs`
- `infrastructure/examples/official_update_check.rs`（历史/开发入口；生产优先使用 `bat-official-sync`）
- `infrastructure/examples/official_update_check.rs`（历史/开发入口；生产优先使用 `bat`）
- `adapters/examples/yostar_jp_client_bootstrap.rs`
- `adapters/examples/yostar_jp_discovery.rs`
- `adapters/examples/yostar_jp_inventory.rs`
@@ -269,5 +294,5 @@ cargo test -p bat-adapters
cargo test -p bat-infrastructure
cargo test -p bat-infrastructure --example official_launcher_bootstrap -- --nocapture
cargo test -p bat-infrastructure --example official_pull_plan -- --nocapture
cargo test -p bat-infrastructure --bin bat-official-sync -- --nocapture
cargo test -p bat-infrastructure --bin bat -- --nocapture
```