mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-07-22 06:56:44 +08:00
nyaKazuha
25c2c4d40f
Emit runtime download progress and validation summaries for official sync. Add repeatable real-network full pull smoke runbook and script. Fixes #4 Fixes #6
100 lines
3.4 KiB
Markdown
100 lines
3.4 KiB
Markdown
# 官方全量拉取 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` 中包含下载总体进度、单文件进度和校验结果日志。
|