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
+1 -1
View File
@@ -44,7 +44,7 @@ cargo clippy --workspace -- -D warnings
1. 当前没有 Go 产品入口,因此 Go build/test/check/fmt/lint 会在空 Go 阶段明确跳过。
2. 如果后续新增 Go package,必须让 `go test ./...``go vet ./...` 纳入硬性验证。
3. 当前 `golangci-lint` 可选;当 Go 代码进入主要开发阶段后,应纳入 CI。
4. 官方同步相关修改必须额外运行 `cargo test -p bat-infrastructure --bin bat-official-sync -- --nocapture`
4. 官方同步相关修改必须额外运行 `cargo test -p bat-infrastructure --bin bat -- --nocapture`
---
+41 -12
View File
@@ -5,8 +5,8 @@
BlueArchive Toolkit 的部署文档分为当前可用模式和目标模式:
1. **本地开发模式**:代码在本地,连接本地或远程数据库。
2. **官方资源同步生产任务**:当前可用,运行 Rust `bat-official-sync --watch`
3. **完整单机/分布式部署**目标模式,等待 API Server、数据库迁移和 Web 实现后补齐
2. **官方资源同步生产任务**:当前可用,运行 Rust `bat --watch`
3. **完整单机/分布式部署**尚未提供。API Server、数据库迁移和 Web 实现前,不把它作为可执行部署方案
---
@@ -105,13 +105,13 @@ REDIS_PORT=6379
### 构建
```bash
cargo build --release -p bat-infrastructure --bin bat-official-sync
cargo build --release -p bat-infrastructure --bin bat
```
产物:
```text
target/release/bat-official-sync
target/release/bat
```
### 目录约定
@@ -140,9 +140,8 @@ target/release/bat-official-sync
### 一次性检查
```bash
/opt/bluearchive-toolkit/bin/bat-official-sync \
/opt/bluearchive-toolkit/bin/bat \
--auto-discover \
--platforms Windows,Android \
--output /var/lib/bluearchive-toolkit/official \
--dry-run
```
@@ -150,14 +149,44 @@ target/release/bat-official-sync
### 常驻自动更新
```bash
/opt/bluearchive-toolkit/bin/bat-official-sync \
/opt/bluearchive-toolkit/bin/bat \
--auto-discover \
--platforms Windows,Android \
--output /var/lib/bluearchive-toolkit/official \
--watch
```
`--watch` 是 Rust 内部持久检查模式,正常情况下默认每 1 小时执行一次检查,并且每天北京时间(UTC+8)`03:00``16:00``18:00` 会强制执行一次自动刷新。固定时间刷新会中断普通 interval 的 sleep,该轮注入 `force=true`;如果失败,会按失败重试周期继续重试。远端和本地一致时默认静默;有远端变化或本地文件损坏时自动下载或 repair,并输出 JSON report。下载、发现或校验失败时默认 60 秒后重试,可显式加 `--error-retry 60s``--error-retry-seconds 60` 调整。默认 ASCII banner 和进度日志写到 stderr成功 JSON report 写到 stdout;如果由上层服务严格解析 stderr/stdout,可加 `--no-progress`,只想关闭横幅可加 `--no-banner`
`--watch` 是 Rust 内部持久检查模式,正常情况下默认每 1 小时执行一次检查,并且每天北京时间(UTC+8)`03:00``16:00``18:00` 会强制执行一次自动刷新。固定时间刷新会中断普通 interval 的 sleep,该轮注入 `force=true`;如果失败,会按失败重试周期继续重试。远端和本地一致时默认静默;有远端变化或本地文件损坏时自动下载或 repair,并输出人类可读摘要。下载、发现或校验失败时默认 60 秒后重试,可显式加 `--error-retry 60s``--error-retry-seconds 60` 调整。默认平台是 `Windows,Android`,无需显式传 `--platforms`;需要覆盖时再传。默认资源目录是 `./bat-resources`,生产建议显式传 `--output /var/lib/bluearchive-toolkit/official`。默认 ASCII banner 和进度日志写到 stderr命令结果写到 stdout;如果由上层服务严格解析结构化输出,可加 `--json --no-progress`,只想关闭横幅可加 `--no-banner`
不使用 systemd 时,也可以直接后台运行:
```bash
/opt/bluearchive-toolkit/bin/bat \
--auto-discover \
--output /var/lib/bluearchive-toolkit/official \
--state-dir /run/bluearchive-toolkit \
--daemon
/opt/bluearchive-toolkit/bin/bat status --state-dir /run/bluearchive-toolkit
/opt/bluearchive-toolkit/bin/bat logs --state-dir /run/bluearchive-toolkit --tail 200
/opt/bluearchive-toolkit/bin/bat restart --state-dir /run/bluearchive-toolkit
/opt/bluearchive-toolkit/bin/bat reload --state-dir /run/bluearchive-toolkit
/opt/bluearchive-toolkit/bin/bat stop --state-dir /run/bluearchive-toolkit
```
`--daemon` 会在 `--state-dir` 下创建 `bat.sock``bat.pid``bat-status.json``bat-daemon.log``bat.sock` 是 Unix socket JSON-RPC 控制通道;`status``stop``logs``reload` 和默认形态的 `refresh` 会优先连接 live daemon。PID、状态和日志文件保留为快照、诊断和 socket 不可用时的兼容路径。`reload` 默认不会重启进程,而是让 watch 循环重新自动发现并强制刷新:空闲睡眠时立即唤醒,正在同步时排队到当前轮结束后执行;需要替换启动参数或 binary 时用 `restart`
生产维护时可以用以下单次命令:
```bash
/opt/bluearchive-toolkit/bin/bat refresh --output /var/lib/bluearchive-toolkit/official
/opt/bluearchive-toolkit/bin/bat refresh --force --output /var/lib/bluearchive-toolkit/official
/opt/bluearchive-toolkit/bin/bat verify --output /var/lib/bluearchive-toolkit/official
/opt/bluearchive-toolkit/bin/bat repair --output /var/lib/bluearchive-toolkit/official
/opt/bluearchive-toolkit/bin/bat doctor --output /var/lib/bluearchive-toolkit/official --state-dir /run/bluearchive-toolkit
/opt/bluearchive-toolkit/bin/bat clean-stable --output /var/lib/bluearchive-toolkit/official --state-dir /run/bluearchive-toolkit
```
如果后台 daemon 正在运行,并且 `refresh` 没有显式指定另一套同步参数,`refresh` / `refresh --force` 会通过 RPC 唤醒或排队后台进程;带 `--output`、server-info、connection-group、app-version、platforms、snapshot、curl 或 unzip 等显式参数时,`refresh` 会作为一次性前台同步运行。`verify` 发现远端变化、本地缺失或校验失败时返回非 0;`repair` 会走官方同步链路重新下载必要文件;`clean-stable` 只清理 `.part``.tmp`、失效 PID、失效 socket 和失效锁,不删除正式资源。
### systemd service 示例
@@ -173,7 +202,7 @@ Wants=network-online.target
Type=simple
User=bat
Group=bat
ExecStart=/opt/bluearchive-toolkit/bin/bat-official-sync --auto-discover --platforms Windows,Android --output /var/lib/bluearchive-toolkit/official --watch --error-retry 60s
ExecStart=/opt/bluearchive-toolkit/bin/bat --auto-discover --output /var/lib/bluearchive-toolkit/official --watch --error-retry 60s
Restart=on-failure
RestartSec=30
StateDirectory=bluearchive-toolkit
@@ -183,13 +212,13 @@ NoNewPrivileges=true
WantedBy=multi-user.target
```
如果业务层需要热更新、热重载或发布新资源,应该由上层服务在观察到 JSON report 或 snapshot 变化后决定。Rust 同步进程只负责拉取、校验和维护本地状态。
如果业务层需要热更新、热重载或发布新资源,应该由上层服务在观察到 `--json` report 或 snapshot 变化后决定。Rust 同步进程只负责拉取、校验和维护本地状态。
---
## 模式 4:完整生产环境部署
待补充(API Server、数据库迁移Web 实现后)
当前不可用。API Server、数据库迁移Web 管理后台和发布编排尚未实现;不要按完整服务端产品部署本仓库。
---
+4 -6
View File
@@ -110,7 +110,7 @@ git push origin feature/your-feature-name
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 test -p bat-infrastructure --bin bat -- --nocapture
```
Go CLI 尚未实现时,`go test ./...` 可能没有产品级 package 可运行;Makefile 会在空 Go 阶段清晰跳过。
@@ -128,20 +128,18 @@ cargo test --workspace
查看参数:
```bash
cargo run -p bat-infrastructure --bin bat-official-sync -- --help
cargo run -p bat-infrastructure --bin bat -- --help
```
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-dev \
--dry-run
```
开发环境真实下载必须使用 `/tmp` 或其他隔离目录,不要写入现有资源目录。
开发环境真实下载默认写入 `./bat-resources`;如果要覆盖,必须使用 `/tmp` 或其他隔离目录,不要写入现有资源目录。
### 基准测试
+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 errorwatch 模式下错误 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 errorwatch 模式下错误 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
```