mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-07-22 04:06:44 +08:00
feat: add official full pull smoke
Emit runtime download progress and validation summaries for official sync. Add repeatable real-network full pull smoke runbook and script. Fixes #4 Fixes #6
This commit is contained in:
@@ -89,7 +89,7 @@ git check-ignore -v Cargo.lock CLAUDE.md
|
||||
CAS V1 和 Rust 官方同步闭环完成后，下一阶段优先推进：
|
||||
|
||||
1. Go CLI 的 `doctor` 和基础命令框架。
|
||||
2. 真实官方网络全量下载 smoke 记录。
|
||||
2. 按 `docs/guides/official-full-pull-smoke.md` 执行真实官方网络全量下载 smoke，并保留隔离目录报告。
|
||||
3. 官方同步结果接入 CAS + ResourceRepository。
|
||||
4. AssetBundle UnityFS 解析。
|
||||
|
||||
@@ -99,6 +99,7 @@ CAS V1 和 Rust 官方同步闭环完成后，下一阶段优先推进：
|
||||
2. `CURRENT_STATUS.md`
|
||||
3. `docs/reports/CURRENT_GAPS.md`
|
||||
4. `docs/guides/official-resource-test-pull.md`
|
||||
5. `docs/architecture/official-resource-backend.md`
|
||||
6. `docs/architecture/adr/0001-engine-and-application-boundaries.md`
|
||||
7. `docs/architecture/adr/0002-cas-v1-design-boundary.md`
|
||||
5. `docs/guides/official-full-pull-smoke.md`
|
||||
6. `docs/architecture/official-resource-backend.md`
|
||||
7. `docs/architecture/adr/0001-engine-and-application-boundaries.md`
|
||||
8. `docs/architecture/adr/0002-cas-v1-design-boundary.md`
|
||||
|
||||
@@ -0,0 +1,99 @@
|
||||
# 官方全量拉取 Smoke Runbook
|
||||
|
||||
本文档固定真实官方网络全量拉取 smoke 的可重复命令。该流程会访问官方日服 HTTP 资源并下载完整 Windows + Android 资源集合，输出目录必须是隔离目录。
|
||||
|
||||
## 目标
|
||||
|
||||
验证当前 `bat` 能在真实官方网络环境下完成：
|
||||
|
||||
1. `--auto-discover --dry-run --plan`
|
||||
2. 首次全量拉取并发布到 `current`
|
||||
3. 第二次运行返回 `up_to_date`
|
||||
4. 人工破坏 active release 中一个资源文件
|
||||
5. `repair` 检出并重新下载损坏文件
|
||||
6. `verify` 在 repair 后通过
|
||||
|
||||
## 一条命令
|
||||
|
||||
默认写入 `/tmp/bat-official-smoke-<UTC timestamp>/`：
|
||||
|
||||
```bash
|
||||
scripts/official-full-pull-smoke.sh
|
||||
```
|
||||
|
||||
也可以通过 Makefile 执行：
|
||||
|
||||
```bash
|
||||
make official-smoke
|
||||
```
|
||||
|
||||
脚本默认会先构建 release binary：
|
||||
|
||||
```bash
|
||||
cargo build --release -p bat-infrastructure --bin bat
|
||||
```
|
||||
|
||||
## 输出
|
||||
|
||||
默认目录结构：
|
||||
|
||||
```text
|
||||
/tmp/bat-official-smoke-<timestamp>/
|
||||
resources/
|
||||
current -> versions/<id>
|
||||
versions/<id>/
|
||||
.staging/
|
||||
state/
|
||||
report/
|
||||
01-dry-run-plan.command.txt
|
||||
01-dry-run-plan.stdout.json
|
||||
01-dry-run-plan.stderr.log
|
||||
02-first-full-pull.command.txt
|
||||
02-first-full-pull.stdout.json
|
||||
02-first-full-pull.stderr.log
|
||||
03-second-up-to-date.command.txt
|
||||
03-second-up-to-date.stdout.json
|
||||
03-second-up-to-date.stderr.log
|
||||
04-repair-after-damage.command.txt
|
||||
04-repair-after-damage.stdout.json
|
||||
04-repair-after-damage.stderr.log
|
||||
05-verify-after-repair.command.txt
|
||||
05-verify-after-repair.stdout.json
|
||||
05-verify-after-repair.stderr.log
|
||||
damaged-file.txt
|
||||
damaged-file.before.txt
|
||||
SMOKE_REPORT.md
|
||||
```
|
||||
|
||||
`damaged-file.before.txt` 只记录被破坏文件的路径、大小和 sha256，不复制原始资源文件。`SMOKE_REPORT.md` 记录本次 smoke 的实际输出目录、active release、文件数量、release 大小和被破坏的文件。大型资源文件不进入 Git。
|
||||
|
||||
脚本会在关键步骤后自动检查：
|
||||
|
||||
- 首次全量拉取 stderr log 包含总体下载进度、单文件进度和校验结果。
|
||||
- 二次运行 stdout JSON 包含 `update_status=up_to_date`。
|
||||
- repair stdout JSON 包含 `command=repair` 和 `status=completed`。
|
||||
- repair stderr log 包含总体下载进度、单文件进度和校验结果。
|
||||
- repair 后 verify stdout JSON 包含 `healthy=true`。
|
||||
|
||||
## 环境变量
|
||||
|
||||
- `BAT_SMOKE_ROOT`：覆盖默认根目录。
|
||||
- `BAT_SMOKE_OUTPUT`：覆盖资源发布根目录。
|
||||
- `BAT_SMOKE_STATE_DIR`：覆盖 daemon/status 目录。
|
||||
- `BAT_SMOKE_REPORT_DIR`：覆盖报告目录。
|
||||
- `BAT_BIN`：使用已有 `bat` binary。
|
||||
- `BAT_SMOKE_SKIP_BUILD=1`：跳过 release 构建。
|
||||
- `BAT_SMOKE_ALLOW_NON_TMP=1`：允许 `BAT_SMOKE_OUTPUT` 指向非 `/tmp` 路径。只可用于确认隔离的测试目录。
|
||||
|
||||
## 安全边界
|
||||
|
||||
脚本默认拒绝非 `/tmp` 输出目录，且拒绝复用非空输出目录。不要把输出目录指向已有客户端、官方启动器安装目录、生产资源目录或开发机人工维护资源目录。
|
||||
|
||||
## 成功判定
|
||||
|
||||
脚本全部步骤退出码为 0 即表示 smoke 通过。重点检查：
|
||||
|
||||
- `03-second-up-to-date.stdout.json` 中 `update_status` 为 `up_to_date`。
|
||||
- `04-repair-after-damage.stdout.json` 中 repair 完成，且有重新下载或修复行为。
|
||||
- `05-verify-after-repair.stdout.json` 中 `healthy` 为 `true`。
|
||||
- `02-first-full-pull.stderr.log` 和 `04-repair-after-damage.stderr.log` 中包含下载总体进度、单文件进度和校验结果日志。
|
||||
@@ -258,13 +258,26 @@ cargo run -p bat-infrastructure --bin bat -- \
|
||||
--error-retry 60s
|
||||
```
|
||||
|
||||
默认平台是 `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 和 publish 阶段；daemon 还会写 `bat-events.jsonl` 结构化日志并按大小轮转。命令结果默认以人类可读摘要写到 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。
|
||||
默认平台是 `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 和 publish 阶段；download 阶段会输出总体下载进度和单文件开始/完成状态，audit 阶段会输出官方 `.hash`、本地 BLAKE3、需修复项和 ZIP 结构校验结果摘要。daemon 还会写 `bat-events.jsonl` 结构化日志并按大小轮转。命令结果默认以人类可读摘要写到 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`，也可以用 `--daemon` 后台运行，或者用 systemd service、容器或 Go 进程守护它。cron/systemd timer 仍可调用单次模式，但不再是 Rust 自动更新的唯一方式。项目是否热更新、热重载或重启进程，由上层业务集成决定。生产资源目录应使用独立输出目录，不要指向现有客户端或人工维护的资源目录；上层读取资源时应读取 `--output/current`，不要读取 `.staging` 或 `versions` 中未切换的目录。非 dry-run 每轮会创建 `--output/.official-sync.lock`，防止并发写同一资源目录；live daemon 还会阻止前台写命令直接修改它正在管理的同一目录。
|
||||
|
||||
需要只做探测时可以加 `--dry-run`。需要关闭本地 audit 或 repair 时可以显式使用 `--no-audit-local` 或 `--no-repair`，但生产同步默认应保持开启。
|
||||
|
||||
## 6. 例外输入
|
||||
## 6. 真实全量 smoke
|
||||
|
||||
真实官方网络全量拉取 smoke 已固化为 runbook 和脚本：
|
||||
|
||||
```bash
|
||||
scripts/official-full-pull-smoke.sh
|
||||
|
||||
# 或
|
||||
make official-smoke
|
||||
```
|
||||
|
||||
默认输出在 `/tmp/bat-official-smoke-<UTC timestamp>/`，脚本会执行 dry-run plan、首次全量拉取、二次 `up_to_date`、本地文件破坏后的 `repair`、repair 后 `verify`，并检查 stderr progress log 中存在总体下载进度、单文件进度和校验结果摘要。完整说明见 `docs/guides/official-full-pull-smoke.md`。
|
||||
|
||||
## 7. 例外输入
|
||||
|
||||
可接受的 `server-info` 输入是：
|
||||
|
||||
@@ -275,7 +288,7 @@ cargo run -p bat-infrastructure --bin bat -- \
|
||||
|
||||
如果没有显式 `server-info` 输入，必须手动加 `--auto-discover` 才会走官方 metadata / `GameMainConfig` 辅助发现链路。不要在 Linux 生产任务里依赖已安装启动器或本地客户端目录。
|
||||
|
||||
## 7. 代码入口
|
||||
## 8. 代码入口
|
||||
|
||||
当前可用的用户入口：
|
||||
|
||||
|
||||
Reference in New Issue
Block a user