mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-07-22 04:35:16 +08:00
274 lines
11 KiB
Markdown
274 lines
11 KiB
Markdown
# 官方资源拉取用户指南
|
||
|
||
本文档描述当前可用的官方日服资源拉取流程。
|
||
|
||
默认平台：
|
||
|
||
- `Windows`
|
||
- `Android`
|
||
|
||
不包含：
|
||
|
||
- `iOS`
|
||
- `macOS`
|
||
- `bluearchive.cafe` 或其他镜像域名
|
||
- 任何本地客户端目录
|
||
- 任何已安装的官方启动器或 Windows 客户端
|
||
|
||
## 0. 快速入口
|
||
|
||
查看命令参数：
|
||
|
||
```bash
|
||
cargo run -p bat-infrastructure --bin bat-official-sync -- --help
|
||
```
|
||
|
||
构建生产 binary：
|
||
|
||
```bash
|
||
cargo build --release -p bat-infrastructure --bin bat-official-sync
|
||
```
|
||
|
||
使用 release binary 做一次 dry-run：
|
||
|
||
```bash
|
||
target/release/bat-official-sync \
|
||
--auto-discover \
|
||
--platforms Windows,Android \
|
||
--output /var/lib/bluearchive-toolkit/official \
|
||
--dry-run
|
||
```
|
||
|
||
常驻自动更新：
|
||
|
||
```bash
|
||
target/release/bat-official-sync \
|
||
--auto-discover \
|
||
--platforms Windows,Android \
|
||
--output /var/lib/bluearchive-toolkit/official \
|
||
--watch
|
||
```
|
||
|
||
生产输出目录必须是独立状态目录。不要使用已有游戏客户端目录、官方启动器安装目录、人工维护资源目录，或开发机上的 `/home/wanye/D/BlueArchive`。
|
||
|
||
## 1. 当前流程
|
||
|
||
Linux 生产运行时链路只走官方日服 HTTP 资源，不安装、不启动、不依赖官方启动器二进制：
|
||
|
||
1. 显式执行 `--auto-discover`，通过官方 HTTP metadata 自动发现 `app-version`、`server-info` URL 和默认 `connection-group`。
|
||
2. 请求官方 `server-info`。
|
||
3. 生成 Windows + Android 的官方资源 discovery 端点。
|
||
4. 拉取 seed catalog，生成完整官方 pull plan。
|
||
5. dry-run 只输出 URL；非 dry-run 下载全部官方 URL。
|
||
|
||
`--auto-discover` 会下载官方 metadata，并按官方 manifest 临时获取 `resources.assets` 解析 `GameMainConfig`；旧 ZIP manifest 才会下载临时 game zip。该流程不会安装官方启动器，也不会执行官方启动器进程。`--launcher-bootstrap` 只是旧命名兼容别名，新流程不要再推荐使用。
|
||
|
||
## 2. 可选 metadata 审计
|
||
|
||
如需单独审计官方 metadata API 和官方 ZIP 链路，可以手动运行：
|
||
|
||
```bash
|
||
cargo run -p bat-infrastructure --example official_launcher_bootstrap -- \
|
||
--launcher-version 1.7.2 \
|
||
--manifest
|
||
```
|
||
|
||
这一步会输出：
|
||
|
||
- `game_latest_version`
|
||
- `game_latest_file_path`
|
||
- `primary_cdn`
|
||
- `backup_cdn`
|
||
- `manifest_url`
|
||
- `manifest_source`
|
||
- `manifest_file_count`
|
||
|
||
所有 URL 都应来自官方域名。
|
||
|
||
## 3. 先做 dry-run
|
||
|
||
推荐开发和生产自动化的默认流程是显式打开 `--auto-discover`：
|
||
|
||
```bash
|
||
cargo run -p bat-infrastructure --example official_pull_plan -- \
|
||
--auto-discover \
|
||
--platforms Windows,Android \
|
||
--output /tmp/ba-official-pull \
|
||
--dry-run
|
||
```
|
||
|
||
如果你要复现某次已审计的 metadata snapshot，也可以显式传入官方 `server-info` 文件名：
|
||
|
||
```bash
|
||
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 \
|
||
--dry-run
|
||
```
|
||
|
||
如果你已经把官方 `server-info` JSON 存成只读本地文件，也可以使用：
|
||
|
||
```bash
|
||
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 \
|
||
--dry-run
|
||
```
|
||
|
||
检查输出时，重点看：
|
||
|
||
- `platforms=[Windows, Android]`
|
||
- `discovery_url_count` 大于 0
|
||
- `content_url_count` 大于 0
|
||
- 不出现 `bluearchive.cafe`
|
||
|
||
## 4. 执行真实拉取
|
||
|
||
确认 dry-run 正常后，去掉 `--dry-run`：
|
||
|
||
```bash
|
||
cargo run -p bat-infrastructure --example official_pull_plan -- \
|
||
--auto-discover \
|
||
--platforms Windows,Android \
|
||
--output /tmp/ba-official-pull
|
||
```
|
||
|
||
程序会：
|
||
|
||
- 只接受官方 URL
|
||
- 下载完整官方资源集合
|
||
- 下载成功后在输出目录维护 `official-download-manifest.json`
|
||
- 已存在目标文件只有在本地下载清单中的 size 和 BLAKE3 校验通过时才会跳过
|
||
- `TableCatalog.bytes`、`BundlePackingInfo.bytes`、`MediaCatalog.bytes` 会用官方 `.hash` 做强校验；该 `.hash` 是 `xxHash32(seed=0)` 的十进制文本
|
||
- `catalog_*.hash` 是 Unity Addressables/SBP 写出的 catalog 变更标记，来源是 `HashingMethods.Calculate(json/bin catalog)` 生成的 `Hash128` 文本；它不是 seed catalog 的 `xxHash32` 规则，目前不作为 zip/JSON 内容强校验
|
||
- 存在 `.part` 临时文件时会尝试断点续传
|
||
- 新下载先写 `.part`，成功后再替换为最终文件
|
||
- 把结果写入 `--output`
|
||
|
||
## 5. 自动更新检查
|
||
|
||
正式自动更新入口是 `bat-official-sync`。它会保存上一次成功同步的 snapshot，下次运行时先自动发现当前官方 metadata，再和 snapshot 对比：
|
||
|
||
- 每轮都会先拉取轻量官方 metadata 和 `.hash` marker。
|
||
- URL 没变但 `.hash` / marker 内容变更时，也会判定为需要更新。
|
||
- 即使远端 snapshot 未变化，只要输出目录没有任何当前 pull plan 的本地 manifest 条目或目标文件，也会按首次运行处理并执行全量拉取。
|
||
- 远端无变化时，默认执行本地 `official-download-manifest.json` audit。
|
||
- 本地文件缺失、路径不一致、size 不一致或 BLAKE3 不一致时，默认进入 repair 并重下必要文件。
|
||
- 官方 seed `.hash` 校验失败会让本轮失败，并清理对应本地 manifest 条目；下一轮会继续把这类文件视为需要 repair，而不是把失败产物当作健康缓存复用。
|
||
- 远端和本地都一致：单次模式输出 `update_status=up_to_date`，watch 模式默认静默并等待下次检查。
|
||
- 有远端变化或本地 repair：生成 pull plan，下载完整官方资源，成功后更新 snapshot。
|
||
- `--dry-run`：只报告本次是否会下载，不写 snapshot；如果 cache miss，也不会写入新的 bootstrap cache。
|
||
- `--dry-run --plan`：除更新判断外，还会解析 seed catalog 并打印完整下载 URL。
|
||
- 真实更新会输出 `downloaded_count`、`resumed_count`、`skipped_count`、`transferred_bytes`、`official_seed_hash_verified_count`。
|
||
- 校验报告分层输出 `official_seed_hash_verified_count`、`local_manifest_verified_count`、`addressables_marker_checked_count`、`unverified_marker_count`。
|
||
- 下载阶段复用同一套本地清单和 `.part` 续传逻辑；没有清单或校验不匹配的文件会重新下载。
|
||
|
||
状态文件默认位于 `--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 到临时目录解析。
|
||
- `official-download-manifest.json`：本地下载强校验清单，记录 URL、相对路径、size 和 BLAKE3。
|
||
|
||
先 dry-run：
|
||
|
||
```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 \
|
||
--dry-run
|
||
```
|
||
|
||
如果需要在 dry-run 阶段审阅完整下载 URL，加 `--plan`：
|
||
|
||
```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 \
|
||
--dry-run \
|
||
--plan
|
||
```
|
||
|
||
确认后执行真实更新：
|
||
|
||
```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
|
||
```
|
||
|
||
Rust 常驻更新模式默认每 1 小时执行一次检查，符合则静默，不符合则自动拉取/repair 并输出 JSON report：
|
||
|
||
```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 \
|
||
--watch
|
||
```
|
||
|
||
如需调整间隔：
|
||
|
||
```bash
|
||
cargo run -p bat-infrastructure --bin bat-official-sync -- \
|
||
--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`。
|
||
|
||
生产可以直接运行 `--watch`，也可以用 systemd service、容器或 Go 进程守护它。cron/systemd timer 仍可调用单次模式，但不再是 Rust 自动更新的唯一方式。项目是否热更新、热重载或重启进程，由上层业务集成决定。生产目录应使用独立输出目录，不要指向现有客户端或人工维护的资源目录。非 dry-run 每轮会创建 `--output/.official-sync.lock`，防止并发写同一状态目录。
|
||
|
||
需要只做探测时可以加 `--dry-run`。需要关闭本地 audit 或 repair 时可以显式使用 `--no-audit-local` 或 `--no-repair`，但生产同步默认应保持开启。
|
||
|
||
## 6. 例外输入
|
||
|
||
可接受的 `server-info` 输入是：
|
||
|
||
- `--auto-discover`
|
||
- `--server-info-url <官方 URL>`
|
||
- `--server-info-file <官方文件名>`
|
||
- `--server-info-path <本地官方 JSON>`
|
||
|
||
如果没有显式 `server-info` 输入，必须手动加 `--auto-discover` 才会走官方 metadata / `GameMainConfig` 辅助发现链路。不要在 Linux 生产任务里依赖已安装启动器或本地客户端目录。
|
||
|
||
## 7. 代码入口
|
||
|
||
当前可用的用户入口：
|
||
|
||
- `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`）
|
||
- `adapters/examples/yostar_jp_client_bootstrap.rs`
|
||
- `adapters/examples/yostar_jp_discovery.rs`
|
||
- `adapters/examples/yostar_jp_inventory.rs`
|
||
|
||
## 8. 验证
|
||
|
||
推荐验证命令：
|
||
|
||
```bash
|
||
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
|
||
```
|