mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-07-22 00:55:15 +08:00
docs: update bat runtime documentation
This commit is contained in:
+2
-1
@@ -15,7 +15,8 @@
|
||||
- 创建架构文档和开发指南
|
||||
- 完成 CAS V1：原子写入、BLAKE3 校验、SQLite 引用计数、GC、并发写入测试和损坏检测
|
||||
- 新增官方日服资源同步链路：auto-discover、pull plan、snapshot、marker diff、本地 manifest audit/repair
|
||||
- 新增 `bat-official-sync` Rust binary，支持 one-shot、`--watch`、默认 1 小时间隔和 JSON report
|
||||
- 新增 Rust 官方同步 binary，当前正式入口为 `bat`，支持 one-shot、`--watch`、默认 1 小时间隔、人类可读默认输出和 `--json` 结构化 report
|
||||
- 官方同步正式入口统一为 `bat`，新增 `--daemon` 后台模式和基于 `bat.sock` 的 Unix socket JSON-RPC 控制面，管理命令覆盖 `status`、`stop`、`restart`、`reload`、`refresh`、`logs`、`verify`、`repair`、`doctor`、`clean-stable`
|
||||
- 新增官方资源下载校验：官方 URL 拒绝、`.part` 续传、重试、本地 size+BLAKE3、官方 seed `.hash` 校验
|
||||
- 新增 Addressables 当前真实形态 fixture/golden 测试
|
||||
- 新增 SQLite Resource Repository 和粗粒度 FFI JSON 接口
|
||||
|
||||
+9
-10
@@ -20,9 +20,9 @@ Rust 侧官方日服资源链路已经从实验验证推进到正式入口：
|
||||
4. 能生成官方全量 pull plan，执行真实下载，维护 `official-download-manifest.json`。
|
||||
5. 下载后使用本地 manifest 的 size + BLAKE3 校验复用文件；官方 seed `.hash` 使用 `xxHash32(seed=0)` 强校验。
|
||||
6. 支持 `.part` 断点续传、失败后 clean retry、本地 manifest audit/repair。
|
||||
7. `bat-official-sync --watch` 可常驻运行，正常检查默认每 1 小时一次；远端和本地一致时默认静默，失败后默认 60 秒快速重试；CLI 默认向 stderr 输出 ASCII banner 和人类可读 progress log。
|
||||
7. `bat --watch` 可常驻运行，`bat --daemon` 可后台运行并用 `bat status` / `bat stop` / `bat restart` / `bat reload` / `bat logs` 管理；daemon 使用 `bat.sock` Unix socket JSON-RPC 作为 live 控制通道，PID/状态/日志文件作为快照和 fallback；正常检查默认每 1 小时一次；远端和本地一致时默认静默，失败后默认 60 秒快速重试；CLI 默认向 stdout 输出人类可读摘要，向 stderr 输出 ASCII banner 和 progress log，需要机器输出时使用 `--json --no-progress`。
|
||||
8. 远端 snapshot 未变化但输出目录为空时，会按首次运行执行全量拉取；官方 seed `.hash` 校验失败时会清理对应 manifest 条目，避免失败产物被后续本地 audit 误判为可复用。
|
||||
9. 非 dry-run 使用 `--output/.official-sync.lock` 防止并发写同一状态目录。
|
||||
9. 默认资源目录是 `./bat-resources`，默认后台状态目录是 `/tmp/bat-pid`；该目录包含 `bat.sock`、`bat.pid`、`bat-status.json` 和 `bat-daemon.log`；非 dry-run 使用 `--output/.official-sync.lock` 防止并发写同一资源目录。
|
||||
|
||||
仍需明确：这不是完整产品完成。Go CLI 最小入口、完整 AssetBundle 解析、Patch、翻译系统、API Server 和 Web 仍是后续工作；真实官方网络全量下载 smoke test 尚未记录在仓库文档中。
|
||||
|
||||
@@ -125,9 +125,9 @@ Rust 侧官方日服资源链路已经从实验验证推进到正式入口：
|
||||
- `InMemoryResourceRepository`。
|
||||
- `SqliteResourceRepository`。
|
||||
- 官方 pull plan 构建。
|
||||
- `OfficialResourcePullService`：官方 URL 拒绝策略、目标路径映射、下载 manifest、`.part` 续传、重试、官方 seed `.hash` 校验。
|
||||
- `OfficialResourcePullService`：官方 URL 拒绝策略、目标路径映射、下载 manifest、`.part` 续传、重试、官方 seed `.hash` 校验、本地全量 verify。
|
||||
- `OfficialUpdateService`：官方 metadata auto-discover、bootstrap cache、snapshot diff、marker diff、本地 audit/repair。
|
||||
- `bat-official-sync`：正式 CLI binary，支持 one-shot 和 `--watch`。
|
||||
- `bat`：正式 CLI binary，支持 one-shot、`--watch`、`--daemon`、`status`、`stop`、`restart`、`reload`、`refresh`、`logs`、`verify`、`repair`、`doctor` 和 `clean-stable`。
|
||||
|
||||
待完成：
|
||||
|
||||
@@ -203,8 +203,8 @@ Rust 侧官方日服资源链路已经从实验验证推进到正式入口：
|
||||
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
|
||||
git diff --cached --check
|
||||
```
|
||||
|
||||
@@ -229,9 +229,8 @@ git status --short
|
||||
当前唯一可作为 Linux 生产资源同步任务运行的入口是 Rust binary：
|
||||
|
||||
```bash
|
||||
cargo run -p bat-infrastructure --bin bat-official-sync -- \
|
||||
cargo run -p bat-infrastructure --bin bat -- \
|
||||
--auto-discover \
|
||||
--platforms Windows,Android \
|
||||
--output /var/lib/bluearchive-toolkit/official \
|
||||
--watch
|
||||
```
|
||||
@@ -242,7 +241,7 @@ cargo run -p bat-infrastructure --bin bat-official-sync -- \
|
||||
2. 不要指向已有游戏客户端目录。
|
||||
3. 不要指向 `/home/wanye/D/BlueArchive` 这类开发或人工维护资源目录。
|
||||
4. `--auto-discover` 可以下载官方 metadata，并按官方 manifest 临时获取 `resources.assets` 以解析 `GameMainConfig`；旧 ZIP manifest 才会下载临时 game zip。该流程不会安装或启动官方 launcher。
|
||||
5. systemd service、容器或 Go 进程可以负责守护 `bat-official-sync --watch`，但定时检查逻辑已经在 Rust 内部；正常检查默认 1 小时，失败重试默认 60 秒，每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 会强制执行一次自动刷新。
|
||||
5. systemd service、容器或 Go 进程可以负责守护 `bat --watch`，也可以用 `bat --daemon` 启动后台模式；`--daemon` 的管理命令优先走 `/tmp/bat-pid/bat.sock` Unix socket JSON-RPC；定时检查逻辑已经在 Rust 内部，正常检查默认 1 小时，失败重试默认 60 秒，每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 会强制执行一次自动刷新。
|
||||
|
||||
详细运行说明见 `docs/guides/official-resource-test-pull.md`。
|
||||
|
||||
@@ -266,7 +265,7 @@ cargo run -p bat-infrastructure --bin bat-official-sync -- \
|
||||
立即任务：
|
||||
|
||||
1. 实现 Go CLI 最小框架和 `doctor`。
|
||||
2. 为 `bat-official-sync` 增加发布型构建/安装说明和服务化验证。
|
||||
2. 为 `bat` 增加发布型构建/安装说明和服务化验证。
|
||||
3. 补端到端 smoke：dry-run、真实下载到隔离目录、二次运行静默 up-to-date、本地损坏后 repair。
|
||||
4. 开始 AssetBundle parser 的 UnityFS header/block/directory。
|
||||
|
||||
|
||||
+1
-1
@@ -90,7 +90,7 @@
|
||||
- Unity/Manifest/Client 适配器框架。
|
||||
- CAS V1：原子写入、BLAKE3 校验、引用计数、GC、并发测试和损坏检测。
|
||||
- 文档整理和路线图重制。
|
||||
- Rust 官方资源同步闭环：`bat-official-sync`、`--auto-discover`、`--watch`、北京时间固定强制刷新、snapshot、manifest audit/repair、官方 seed `.hash` 校验。
|
||||
- Rust 官方资源同步闭环：`bat`、`--auto-discover`、`--watch`、`--daemon`、Unix socket JSON-RPC 后台控制、`status`、`stop`、`restart`、`reload`、`refresh`、`logs`、`verify`、`repair`、`doctor`、`clean-stable`、北京时间固定强制刷新、snapshot、manifest audit/repair、官方 seed `.hash` 校验。
|
||||
- Addressables 当前真实形态 fixture/golden 覆盖。
|
||||
- SQLite Resource Repository 和粗粒度 FFI JSON 接口。
|
||||
|
||||
|
||||
+8
-8
@@ -31,8 +31,8 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
|
||||
3. `bat-adapters` 已实现 Unity、Manifest、Client 集成的框架和注册表。
|
||||
4. `bat-cas-engine` 已完成 CAS V1：原子写入、BLAKE3 Hash、SQLite 引用计数、GC、并发测试、损坏检测。
|
||||
5. `bat-infrastructure` 已改为 CAS 仓储适配层，不再重复实现对象存储。
|
||||
6. `bat-infrastructure` 已提供官方资源 pull/update 服务，正式入口是 `bat-official-sync`。
|
||||
7. `bat-official-sync` 支持 `--auto-discover`、`--watch`、默认 1 小时间隔、本地 manifest audit/repair、官方 seed `.hash` 校验和 snapshot/cache。
|
||||
6. `bat-infrastructure` 已提供官方资源 pull/update 服务，正式入口是 Rust binary `bat`。
|
||||
7. `bat` 支持 `--auto-discover`、`--watch`、`--daemon`、默认 1 小时间隔、本地 manifest audit/repair、官方 seed `.hash` 校验、snapshot/cache，以及基于 Unix socket JSON-RPC 的 `status/stop/restart/reload/refresh/logs/verify/repair/doctor/clean-stable` 运维命令。
|
||||
8. `bat-ffi` 已提供 Manifest inspect 和官方 sync plan 的粗粒度 JSON API。
|
||||
9. 文档已整理：根目录保留入口文档，历史报告进入 `docs/reports/historical/`，误嵌套的 `docs/docs` 已合并。
|
||||
|
||||
@@ -52,8 +52,8 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
|
||||
1. `cargo test -p bat-adapters -- --nocapture` 通过。
|
||||
2. `cargo test -p bat-ffi -- --nocapture` 通过。
|
||||
3. `cargo test -p bat-infrastructure -- --nocapture` 通过。
|
||||
4. `cargo test -p bat-infrastructure --bin bat-official-sync -- --nocapture` 通过。
|
||||
5. `cargo run -p bat-infrastructure --bin bat-official-sync -- --help` 可用。
|
||||
4. `cargo test -p bat-infrastructure --bin bat -- --nocapture` 通过。
|
||||
5. `cargo run -p bat-infrastructure --bin bat -- --help` 可用。
|
||||
6. `go test ./...` 当前无 Go 产品 package；`Makefile` 已调整为在 Go 未实现阶段明确跳过。
|
||||
|
||||
---
|
||||
@@ -173,7 +173,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
|
||||
1. Addressables Catalog 真实字段解析：**部分完成**。当前已覆盖 path、hash、size、address、dependencies、metadata 和真实形态 fixture/golden；仍需继续覆盖更多官方 catalog 结构变体。
|
||||
2. 资源版本、区域、渠道、远端 URL、Hash、大小、依赖关系模型：**部分完成**。`Resource` 和官方 endpoint/snapshot 模型已扩展；仍需冻结 Go CLI/API 可见模型。
|
||||
3. Rust 官方下载器：**已完成当前生产入口需要的核心能力**。包含官方 URL 校验、`.part` 续传、重试、本地 manifest size+BLAKE3 校验、官方 seed `.hash` 校验和 repair。
|
||||
4. Rust 自动更新入口：**已完成当前生产入口**。`bat-official-sync` 支持 snapshot、marker diff、bootstrap cache、one-shot、`--watch` 和默认 1 小时间隔。
|
||||
4. Rust 自动更新入口：**已完成当前生产入口**。`bat` 支持 snapshot、marker diff、bootstrap cache、one-shot、`--watch`、`--daemon`、默认 1 小时间隔、北京时间固定强制刷新，以及 Unix socket JSON-RPC 后台运维命令返回。
|
||||
5. Go CLI：**未完成**。需要实现 `bat doctor`、`bat sync --help`、Rust 官方同步命令包装和 JSON/human 输出。
|
||||
6. 用户级 `sync`、`manifest inspect`、`cache status`：**未完成**。Rust FFI 已提供 Manifest inspect 和 sync plan JSON 边界，但 Go CLI 尚未串联。
|
||||
7. 下载结果写入 CAS + ResourceRepository：**部分完成**。CAS 和 SQLite ResourceRepository 已存在，官方同步入口尚未把完整下载结果作为用户级流程自动导入。
|
||||
@@ -381,13 +381,13 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
|
||||
## 6. 近期 10 个具体任务
|
||||
|
||||
1. 落地 Go CLI 的最小生产入口：`bat doctor`、`bat sync --help`、`bat official sync --help`。
|
||||
2. 让 Go CLI 能调用 `bat-official-sync` 或 FFI/进程边界，并稳定转发 JSON report。
|
||||
2. 让 Go CLI 能调用 Rust `bat --json` 官方同步入口或 FFI/进程边界，并稳定转发结构化 report。
|
||||
3. 记录一次真实官方网络 smoke：dry-run、首次下载、二次 up-to-date、本地损坏 repair。
|
||||
4. 将官方同步下载结果接入 CAS + `SqliteResourceRepository` 的用户级流程。
|
||||
5. 继续扩展 Addressables parser 的真实 catalog 变体覆盖和错误诊断。
|
||||
6. 开始 AssetBundle UnityFS header/block/directory 解析。
|
||||
7. 为 CLI 和 CAS 增加 `doctor cas` 诊断入口。
|
||||
8. 为 `bat-official-sync --watch` 增加发布型构建、systemd service 示例和运维检查清单。
|
||||
8. 为 `bat --watch` / `bat --daemon` 持续补充发布型构建、systemd service 示例和运维检查清单；后台 live control plane 已改为 Unix socket JSON-RPC。
|
||||
|
||||
---
|
||||
|
||||
@@ -417,7 +417,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
|
||||
1. Rust 提供稳定引擎能力，不承担 CLI 编排，但负责完整资源拉取和更新检查的核心逻辑。
|
||||
2. Go 负责用户命令、最小稳定 CLI、服务编排、网络和 Provider。
|
||||
3. 跨边界优先进程或 SDK，FFI 只作为可选的粗粒度、安全、可测试 API。
|
||||
4. Rust 不需要被强制写成 Go 调用库；当前 `bat-official-sync --watch` 是允许长期运行的 Rust 生产任务。
|
||||
4. Rust 不需要被强制写成 Go 调用库；当前 `bat --watch` / `bat --daemon` 是允许长期运行的 Rust 生产任务。
|
||||
|
||||
### 官方资源真实下载风险
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@
|
||||
- `bat-adapters` Unity、Manifest、Client 集成框架，以及当前真实形态 Addressables catalog 解析覆盖。
|
||||
- `bat-cas-engine` CAS V1：原子写入、BLAKE3 校验、引用计数、GC、并发写入测试、损坏检测。
|
||||
- `bat-infrastructure` CAS 适配层、SQLite Resource Repository、官方资源 pull/update 服务。
|
||||
- `bat-official-sync`：官方资源自动发现、全量拉取、本地 manifest audit/repair、`.part` 断点续传、官方 seed `.hash` 校验、snapshot/cache、`--watch` 常驻更新。
|
||||
- `bat`：官方资源自动发现、全量拉取、本地 manifest audit/repair、`.part` 断点续传、官方 seed `.hash` 校验、snapshot/cache、`--watch` 常驻更新、`--daemon` 后台运行，以及 Unix socket JSON-RPC 后台控制命令 `status/stop/restart/reload/refresh/logs/verify/repair/doctor/clean-stable`。
|
||||
- `bat-ffi` 粗粒度 JSON 接口：Manifest inspect 和官方 sync plan。
|
||||
- 文档路线图、当前状态、缺口清单、官方资源运行指南。
|
||||
|
||||
@@ -52,39 +52,64 @@
|
||||
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
|
||||
```
|
||||
|
||||
查看官方同步命令：
|
||||
|
||||
```bash
|
||||
cargo run -p bat-infrastructure --bin bat-official-sync -- --help
|
||||
cargo run -p bat-infrastructure --bin bat -- --help
|
||||
```
|
||||
|
||||
只做官方资源更新判断，不写同步状态：
|
||||
|
||||
```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 \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
常驻自动更新，正常情况下默认每 1 小时检查一次；每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 会强制执行一次自动刷新。远端和本地一致时静默。下载或发现失败时默认 60 秒后重试，可用 `--error-retry 60s` 调整：
|
||||
|
||||
```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 \
|
||||
--error-retry 60s
|
||||
```
|
||||
|
||||
CLI 默认启动时会向 stderr 打印 `BlueArchiveToolkit` ASCII banner，并继续把人类可读的阶段进度日志写到 stderr，例如自动发现、拉取 catalog、audit、下载第 N/总数个 URL 等；成功后的稳定 JSON report 仍写到 stdout。需要给上层程序保留纯机器输出时可加 `--no-progress`，只想关闭横幅但保留日志时可加 `--no-banner`。
|
||||
后台自动运行可以把 `--watch` 换成 `--daemon`。默认资源目录是 `./bat-resources`，默认后台状态目录是 `/tmp/bat-pid`。daemon 会在状态目录下创建 `bat.sock` 作为 Unix socket JSON-RPC 控制通道，同时写入 `bat.pid`、`bat-status.json` 和 `bat-daemon.log` 作为快照和故障排查文件：
|
||||
|
||||
生产输出目录必须使用独立状态目录，不要指向已有客户端目录，也不要指向 `/home/wanye/D/BlueArchive` 这类人工维护或开发资源目录。
|
||||
```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` 会优先连接 live RPC socket；socket 不可用时，状态和停止命令会回退到 PID/状态文件兼容路径。`reload` 不再强制重启进程，而是让后台 watch 循环重新自动发现并执行强制刷新：空闲睡眠时立即唤醒，正在同步时排队到当前轮结束后执行。确实需要替换启动参数时使用 `restart` 或给 `reload` 显式传入同步参数。
|
||||
|
||||
资源操作命令默认输出人类可读摘要，并在没有显式 metadata 参数时默认走官方自动发现。脚本或上层程序需要稳定结构化输出时加 `--json`：
|
||||
|
||||
```bash
|
||||
cargo run -p bat-infrastructure --bin bat -- refresh
|
||||
cargo run -p bat-infrastructure --bin bat -- refresh --force --json
|
||||
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
|
||||
```
|
||||
|
||||
`verify` 会以只读方式检查当前官方计划、本地 download manifest 的 size+BLAKE3，以及本地已有官方 seed `.bytes/.hash` 对的 xxHash32；发现缺失、远端变化或本地损坏会返回非 0。`repair` 会在异常资源存在时复用当前同步链路重新下载必要文件。`clean-stable` 只清理 `.part`、临时状态文件和失效锁/PID，不删除正式资源。
|
||||
|
||||
CLI 默认启动时会向 stderr 打印 `BlueArchiveToolkit` ASCII banner，并继续把阶段进度日志写到 stderr，例如自动发现、拉取 catalog、audit、下载第 N/总数个 URL 等；命令结果默认以人类可读摘要写到 stdout。需要给上层程序保留稳定结构化输出时加 `--json --no-progress`，只想关闭横幅但保留日志时可加 `--no-banner`。
|
||||
|
||||
生产资源输出目录必须使用独立目录，不要指向已有客户端目录，也不要指向 `/home/wanye/D/BlueArchive` 这类人工维护或开发资源目录。需要覆盖默认位置时，用 `--output <资源目录>`；需要覆盖后台状态目录时，用 `--state-dir <状态目录>`。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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. 审核重点
|
||||
|
||||
|
||||
@@ -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
@@ -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 管理后台和发布编排尚未实现；不要按完整服务端产品部署本仓库。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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` 或其他隔离目录，不要写入现有资源目录。
|
||||
|
||||
### 基准测试
|
||||
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
@@ -184,7 +184,7 @@
|
||||
|
||||
- `bat doctor` 可运行。
|
||||
- `bat --help` 命令结构稳定。
|
||||
- 命令支持配置文件和 JSON 输出。
|
||||
- 命令支持默认人类可读输出和 `--json` 机器输出。
|
||||
|
||||
### G-009：API Server 和 OpenAPI 尚未实现
|
||||
|
||||
@@ -330,7 +330,7 @@
|
||||
|
||||
影响：
|
||||
|
||||
- 无法用文档证明当前 `bat-official-sync` 在真实官方网络环境下完成首次下载、二次静默 up-to-date 和本地损坏 repair。
|
||||
- 无法用文档证明当前 `bat` 在真实官方网络环境下完成首次下载、二次静默 up-to-date 和本地损坏 repair。
|
||||
|
||||
验收：
|
||||
|
||||
|
||||
@@ -15,7 +15,7 @@
|
||||
2. 自动发现官方 `app-version`、`connection-group`、`server-info`。
|
||||
3. 拉取 Windows + Android 官方资源集合。
|
||||
4. 保存 snapshot，按远端 marker 和本地 manifest 判断是否需要更新。
|
||||
5. 支持 `bat-official-sync --watch` 常驻检查，默认每 1 小时运行一次。
|
||||
5. 支持 `bat --watch` 常驻检查，默认每 1 小时运行一次。
|
||||
6. 通过文档明确生产目录不能指向已有客户端或开发资源目录。
|
||||
|
||||
## 2. 当前实现状态
|
||||
@@ -27,7 +27,7 @@
|
||||
- `AddressablesCatalogDriver` 对当前真实形态 fixture/golden 的解析。
|
||||
- `OfficialResourcePullService` 的官方 URL 拒绝、`.part` 续传、重试、本地 manifest、官方 seed `.hash` 校验。
|
||||
- `OfficialUpdateService` 的 auto-discover、bootstrap cache、v2 snapshot、remote marker diff、本地 audit/repair。
|
||||
- `bat-official-sync` one-shot 和 `--watch`。
|
||||
- `bat` one-shot 和 `--watch`。
|
||||
- `bat-ffi` 的 Manifest inspect 和 sync plan JSON API。
|
||||
- `SqliteResourceRepository`。
|
||||
|
||||
@@ -47,8 +47,8 @@
|
||||
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
|
||||
git diff --cached --check
|
||||
```
|
||||
|
||||
@@ -67,6 +67,6 @@ git status --short
|
||||
## 5. 下一步
|
||||
|
||||
1. 实现 Go CLI：`bat doctor`、`bat sync --help`、`bat official sync --help`。
|
||||
2. 为 `bat-official-sync` 做真实官方网络 smoke，输出目录必须隔离。
|
||||
2. 为 `bat` 做真实官方网络 smoke，输出目录必须隔离。
|
||||
3. 将官方同步下载结果接入 CAS + `SqliteResourceRepository`。
|
||||
4. 开始 AssetBundle UnityFS header/block/directory 解析。
|
||||
|
||||
@@ -13,7 +13,7 @@
|
||||
|
||||
- 当前分支为 `experiment`。
|
||||
- `bat-cas-engine` 的 CAS V1 已完成。
|
||||
- `bat-official-sync` 是当前官方资源同步正式入口。
|
||||
- `bat` 是当前官方资源同步正式入口。
|
||||
- Linux 生产链路不安装、不启动、不依赖官方启动器。
|
||||
- `--auto-discover` 通过官方 HTTP metadata 和临时目录解析 `GameMainConfig`。
|
||||
- 默认平台是 `Windows + Android`。
|
||||
@@ -47,7 +47,7 @@
|
||||
1. 读取 `README.md`、`CURRENT_STATUS.md`、`PROJECT_PLAN.md`。
|
||||
2. 读取 `docs/guides/official-resource-test-pull.md` 和 `docs/architecture/official-resource-backend.md`。
|
||||
3. 实现 `cmd/bat` 和最小命令树。
|
||||
4. 将 `bat-official-sync` 的 JSON report 作为 Go CLI 输出的稳定来源。
|
||||
4. Go CLI 调用 `bat` 时显式传 `--json`，把该结构化 report 作为稳定机器输出来源。
|
||||
|
||||
## 5. 相关入口
|
||||
|
||||
|
||||
Reference in New Issue
Block a user