From 2ff99ae9e31e83d414fb51ed3b6c9057de78c90a Mon Sep 17 00:00:00 2001 From: Yuyi-Oak <1722157266@qq.com> Date: Tue, 14 Jul 2026 00:10:39 +0800 Subject: [PATCH] feat: publish official resources atomically Fixes #9 Fixes #11 --- CHANGELOG.md | 2 + CURRENT_STATUS.md | 9 +- README.md | 8 +- docs/architecture/README.md | 7 +- .../architecture/official-resource-backend.md | 16 +- docs/guides/deployment.md | 28 +- docs/guides/official-resource-test-pull.md | 28 +- infrastructure/src/bin/bat_official_sync.rs | 507 +++++++++++++++++- infrastructure/src/official_update.rs | 487 ++++++++++++++++- .../official_game_main_config_bootstrap.rs | 26 + 10 files changed, 1055 insertions(+), 63 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 278fddb..ab5e1b5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,8 @@ - 官方同步正式入口统一为 `bat`，新增 `--daemon` 后台模式和基于 `bat.sock` 的 Unix socket JSON-RPC 控制面，管理命令覆盖 `status`、`stop`、`restart`、`reload`、`refresh`、`logs`、`verify`、`repair`、`doctor`、`clean-stable` - 新增 daemon 控制锁 `bat-control.lock`、daemon 与前台同资源目录写入互斥，以及失效/损坏 PID 和锁文件恢复逻辑 - 新增官方同步路径安全边界：拒绝危险输出目录和 snapshot 路径逃逸，下载目标、manifest、daemon PID/status/log/control 文件不跟随 symlink，daemon 状态文件默认使用 `0600` 权限 +- 新增官方资源原子发布布局：非 dry-run 下载先进入 `.staging/`，校验和 manifest/snapshot 写入完成后发布到 `versions/`，再原子切换 `current` symlink +- 新增 daemon 可观测性：`bat-events.jsonl` 结构化 JSONL 日志、日志轮转、status 中的当前下载进度、最后成功时间、下次检查时间和最后错误摘要 - 新增官方资源同步生产部署模板：release binary symlink 路径、systemd unit、运行用户、日志位置、升级和回滚流程 - 新增官方资源下载校验：官方 URL 拒绝、`.part` 续传、重试、本地 size+BLAKE3、官方 seed `.hash` 校验 - 新增 Addressables 当前真实形态 fixture/golden 测试 diff --git a/CURRENT_STATUS.md b/CURRENT_STATUS.md index a3084f4..eb48cd5 100644 --- a/CURRENT_STATUS.md +++ b/CURRENT_STATUS.md @@ -17,13 +17,14 @@ Rust 侧官方日服资源链路已经从实验验证推进到正式入口： 1. 首次运行可以通过 `--auto-discover` 从官方 HTTP metadata 解析 `GameMainConfig`，自动获得 `app-version`、`connection-group` 和 `server-info`。 2. 不安装、不启动、不依赖已安装官方启动器。 3. 默认平台为 `Windows + Android`。 -4. 能生成官方全量 pull plan，执行真实下载，维护 `official-download-manifest.json`。 +4. 能生成官方全量 pull plan，执行真实下载，维护 release 内的 `official-download-manifest.json`。 5. 下载后使用本地 manifest 的 size + BLAKE3 校验复用文件；所有 `.zip` 在下载验收、复用、本地 audit/verify 时做 ZIP 结构校验；官方 seed `.hash` 使用 `xxHash32(seed=0)` 强校验。 6. 支持 `.part` 断点续传、失败后 clean retry、本地 manifest audit/repair。 -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，`bat-control.lock` 串行化控制命令；正常检查默认每 1 小时一次；远端和本地一致时默认静默，失败后默认 60 秒快速重试；CLI 默认向 stdout 输出人类可读摘要，向 stderr 输出 ASCII banner 和 progress log，需要机器输出时使用 `--json --no-progress`。 +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，`bat-events.jsonl` 记录带轮转的结构化事件日志，`bat-control.lock` 串行化控制命令；正常检查默认每 1 小时一次；远端和本地一致时默认静默，失败后默认 60 秒快速重试；CLI 默认向 stdout 输出人类可读摘要，向 stderr 输出 ASCII banner 和 progress log，需要机器输出时使用 `--json --no-progress`。 8. 远端 snapshot 未变化但输出目录为空时，会按首次运行执行全量拉取；官方 seed `.hash` 校验失败时会清理对应 manifest 条目，避免失败产物被后续本地 audit 误判为可复用。 -9. 默认资源目录是 `./bat-resources`，默认后台状态目录是 `/tmp/bat-pid`；该目录包含 `bat.sock`、`bat.pid`、`bat-status.json`、`bat-daemon.log` 和短生命周期 `bat-control.lock`；非 dry-run 使用 `--output/.official-sync.lock` 防止并发写同一资源目录，live daemon 会阻止前台写命令直接修改它正在管理的同一目录。 +9. 默认资源目录是 `./bat-resources`，默认后台状态目录是 `/tmp/bat-pid`；资源目录是发布根目录，包含 `current` symlink、`versions/` 和 `.staging/`，非 dry-run 会先写 staging，校验完成后发布 versioned 目录并原子切换 `current`；后台状态目录包含 `bat.sock`、`bat.pid`、`bat-status.json`、`bat-daemon.log`、`bat-events.jsonl` 和短生命周期 `bat-control.lock`；非 dry-run 使用 `--output/.official-sync.lock` 防止并发写同一资源目录，live daemon 会阻止前台写命令直接修改它正在管理的同一目录。 10. 官方同步会拒绝危险输出目录、路径逃逸和现有 symlink 路径组件；下载目标、`.part`、manifest、snapshot、PID、status、log 和控制锁文件不会跟随 symlink，daemon 状态类文件默认以 `0600` 权限创建。 +11. `bat status` 会显示最后成功时间、下次检查时间、最后错误摘要、当前阶段、当前下载 URL 进度、结构化日志路径和轮转日志路径。 仍需明确：这不是完整产品完成。Go CLI 最小入口、完整 AssetBundle 解析、Patch、翻译系统、API Server 和 Web 仍是后续工作；真实官方网络全量下载 smoke test 尚未记录在仓库文档中。 @@ -242,7 +243,7 @@ cargo run -p bat-infrastructure --bin bat -- \ 2. 不要指向已有游戏客户端目录。 3. 不要指向 `/home/wanye/D/BlueArchive` 这类开发或人工维护资源目录。 4. `--auto-discover` 可以下载官方 metadata，并按官方 manifest 临时获取 `resources.assets` 以解析 `GameMainConfig`；旧 ZIP manifest 才会下载临时 game zip。该流程不会安装或启动官方 launcher。 -5. 推荐生产形态是 systemd 直接托管前台 `bat --watch`，unit 模板位于 `deployments/systemd/bluearchive-toolkit-official-sync.service`，稳定 binary 路径为 `/opt/bluearchive-toolkit/bin/bat`，资源目录为 `/var/lib/bluearchive-toolkit/official`，日志通过 `journalctl -u bluearchive-toolkit-official-sync.service` 查看；不使用 systemd 时也可用 `bat --daemon` 自托管，daemon 状态和 `bat-daemon.log` 建议放在 `/var/lib/bluearchive-toolkit/daemon-state`。定时检查逻辑已经在 Rust 内部，正常检查默认 1 小时，失败重试默认 60 秒，每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 会强制执行一次自动刷新。 +5. 推荐生产形态是 systemd 直接托管前台 `bat --watch`，unit 模板位于 `deployments/systemd/bluearchive-toolkit-official-sync.service`，稳定 binary 路径为 `/opt/bluearchive-toolkit/bin/bat`，资源发布根目录为 `/var/lib/bluearchive-toolkit/official`，生产读取方读取 `/var/lib/bluearchive-toolkit/official/current`，日志通过 `journalctl -u bluearchive-toolkit-official-sync.service` 查看；不使用 systemd 时也可用 `bat --daemon` 自托管，daemon 状态、`bat-daemon.log` 和 `bat-events.jsonl` 建议放在 `/var/lib/bluearchive-toolkit/daemon-state`。定时检查逻辑已经在 Rust 内部，正常检查默认 1 小时，失败重试默认 60 秒，每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 会强制执行一次自动刷新。 详细运行说明见 `docs/guides/deployment.md` 和 `docs/guides/official-resource-test-pull.md`。 diff --git a/README.md b/README.md index 7c84925..cb21978 100644 --- a/README.md +++ b/README.md @@ -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`：官方资源自动发现、全量拉取、本地 manifest audit/repair、`.part` 断点续传、ZIP 结构校验、官方 seed `.hash` 校验、snapshot/cache、`--watch` 常驻更新、`--daemon` 后台运行，以及 Unix socket JSON-RPC 后台控制命令 `status/stop/restart/reload/refresh/logs/verify/repair/doctor/clean-stable`。 +- `bat`：官方资源自动发现、全量拉取、原子发布到 `current -> versions/`、本地 manifest audit/repair、`.part` 断点续传、ZIP 结构校验、官方 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。 - 文档路线图、当前状态、缺口清单、官方资源运行指南。 @@ -78,7 +78,7 @@ cargo run -p bat-infrastructure --bin bat -- \ --error-retry 60s ``` -后台自动运行可以把 `--watch` 换成 `--daemon`。默认资源目录是 `./bat-resources`，默认后台状态目录是 `/tmp/bat-pid`。daemon 会在状态目录下创建 `bat.sock` 作为 Unix socket JSON-RPC 控制通道，同时写入 `bat.pid`、`bat-status.json`、`bat-daemon.log` 和短生命周期的 `bat-control.lock`；前三者用于快照和故障排查，`bat-control.lock` 用于串行化 `status/stop/restart/reload/logs/refresh` 等控制命令： +后台自动运行可以把 `--watch` 换成 `--daemon`。默认资源目录是 `./bat-resources`，默认后台状态目录是 `/tmp/bat-pid`。daemon 会在状态目录下创建 `bat.sock` 作为 Unix socket JSON-RPC 控制通道，同时写入 `bat.pid`、`bat-status.json`、`bat-daemon.log`、`bat-events.jsonl` 和短生命周期的 `bat-control.lock`；`bat-events.jsonl` 是带轮转的结构化 JSONL 事件日志，`bat-status.json` 保存最后成功时间、下次检查时间、最后错误摘要和当前下载进度，`bat-control.lock` 用于串行化 `status/stop/restart/reload/logs/refresh` 等控制命令： ```bash cargo run -p bat-infrastructure --bin bat -- \ @@ -96,6 +96,8 @@ cargo run -p bat-infrastructure --bin bat -- stop `bat` 会拒绝危险输出目录、路径逃逸和现有 symlink 路径组件；下载目标、`.part`、manifest、snapshot、PID、status、log 和控制锁文件不会跟随 symlink，daemon 状态类文件默认以 `0600` 权限创建。 +非 dry-run 同步不会把新文件直接写进生产可读目录。资源会先下载到 `/.staging/`，完成 manifest、BLAKE3、ZIP 和官方 `.hash` 校验后移动到 `/versions/`，再原子切换 `/current` symlink；生产读取方应只读取 `/current`。 + 资源操作命令默认输出人类可读摘要，并在没有显式 metadata 参数时默认走官方自动发现。脚本或上层程序需要稳定结构化输出时加 `--json`： ```bash @@ -107,7 +109,7 @@ cargo run -p bat-infrastructure --bin bat -- doctor cargo run -p bat-infrastructure --bin bat -- clean-stable ``` -`verify` 会以只读方式检查当前官方计划、本地 download manifest 的 size+BLAKE3、ZIP 结构，以及本地已有官方 seed `.bytes/.hash` 对的 xxHash32；发现缺失、远端变化或本地损坏会返回非 0。`repair` 会在异常资源存在时复用当前同步链路重新下载必要文件。`clean-stable` 只清理 `.part`、临时状态文件、失效或损坏的 PID/锁/socket，不删除正式资源。 +`verify` 会以只读方式检查当前官方计划、`current` 指向的 active release 中 download manifest 的 size+BLAKE3、ZIP 结构，以及本地已有官方 seed `.bytes/.hash` 对的 xxHash32；发现缺失、远端变化或本地损坏会返回非 0。`repair` 会在异常资源存在时复用当前同步链路重新下载必要文件。`clean-stable` 只清理 `.part`、临时状态文件、失效或损坏的 PID/锁/socket，不删除正式资源。 CLI 默认启动时会向 stderr 打印 `BlueArchiveToolkit` ASCII banner，并继续把阶段进度日志写到 stderr，例如自动发现、拉取 catalog、audit、下载第 N/总数个 URL 等；命令结果默认以人类可读摘要写到 stdout。需要给上层程序保留稳定结构化输出时加 `--json --no-progress`，只想关闭横幅但保留日志时可加 `--no-banner`。 diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 4aa0f80..3bee5f7 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -106,9 +106,9 @@ cas/ ``` 官方 metadata → GameMainConfig → server-info → discovery endpoints ↓ -seed catalog → inventory → pull plan → downloader → output directory +seed catalog → inventory → pull plan → staging → versions/ ↓ -official-sync-snapshot.json + official-download-manifest.json +current symlink → official-sync-snapshot.json + official-download-manifest.json ``` **已具备特性**： @@ -118,7 +118,8 @@ official-sync-snapshot.json + official-download-manifest.json - `--auto-discover` 自动获取 `app-version`、`connection-group` 和 `server-info`。 - `--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。 +- 非 dry-run 同步先写 `.staging/`，校验完成后发布 `versions/` 并原子切换 `current` symlink。 +- `--daemon` 使用状态目录下的 `bat.sock` 作为 Unix socket JSON-RPC live control plane；PID、状态和日志文件是快照与 fallback，`bat-events.jsonl` 是结构化轮转日志。 - `status`、`logs`、`reload`、`stop` 和默认形态的 `refresh` 优先通过 RPC 管理后台进程；控制命令通过 `bat-control.lock` 串行化；`restart` 负责重启或替换启动参数；live daemon 会阻止前台写命令直接修改同一资源目录；`doctor` 做运行时诊断；`clean-stable` 清理临时文件和失效/损坏状态。 - 远端 marker 无变化且本地 manifest clean 时不下载。 - 本地文件损坏时 repair。 diff --git a/docs/architecture/official-resource-backend.md b/docs/architecture/official-resource-backend.md index f5efc39..ec1daa0 100644 --- a/docs/architecture/official-resource-backend.md +++ b/docs/architecture/official-resource-backend.md @@ -120,15 +120,15 @@ 工作方式： 1. 检查 URL 是否属于官方 host。 -2. 把 URL 映射到本地输出路径。 -3. 读取输出目录下的 `official-download-manifest.json`。 +2. 把 URL 映射到当前工作根目录下的本地输出路径；在自动更新服务中，读侧根目录是 `current` 指向的 versioned 目录，写侧根目录是 staging。 +3. 读取工作根目录下的 `official-download-manifest.json`。 4. 已存在目标文件只有在本地清单中的相对路径、size、BLAKE3 都匹配时才跳过；`.zip` 文件还必须通过 ZIP central directory / local header 结构校验。 5. 缺少清单、清单不匹配、ZIP 结构无效或文件损坏时重新下载。 6. `TableCatalog.bytes`、`BundlePackingInfo.bytes`、`MediaCatalog.bytes` 总是刷新并用官方 `.hash` 强校验；该 `.hash` 是 `xxHash32(seed=0)` 的十进制文本。 7. `catalog_*.hash` 当前只作为 Addressables catalog 变更标记，不作为 zip/JSON 内容校验算法；Unity Addressables/SBP builder 对 JSON/bin catalog 使用 `HashingMethods.Calculate` 生成 `Hash128` 文本，运行时用它判断 remote catalog cache 是否过期，它不能套用 seed catalog 的 `xxHash32` 规则。 8. 官方 seed `.hash` 校验失败会让当前下载失败，并移除对应 data/hash URL 的本地 manifest 条目，避免失败产物在下一轮被本地 BLAKE3 audit 误判为健康缓存。 9. 存在 `.part` 临时文件时通过 `curl --continue-at -` 尝试断点续传。 -10. 新下载写入 `.part`，成功并通过必要校验后原子 rename 到最终路径；断点续传后的 `.zip` 如果结构无效，会删除 `.part` 并重新全量下载。 +10. 新下载写入 `.part`，成功并通过必要校验后原子 rename 到 staging 内最终路径；断点续传后的 `.zip` 如果结构无效，会删除 `.part` 并重新全量下载。 11. 成功下载后更新本地下载清单。 12. 记录最终文件大小、本次传输字节数、官方 hash 校验数和执行状态。 13. 非官方 URL 直接拒绝。 @@ -190,10 +190,12 @@ 6. 每轮都会基于最新 seed catalog 构建当前 pull plan，并检查输出目录是否已有当前 plan 的 manifest 条目或目标文件。 7. 如果远端 snapshot 未变化但输出目录没有任何当前 plan 的本地资源，仍按首次运行处理并执行全量拉取。 8. 远端无变化且本地已有资源时执行 download manifest audit，检查路径、size、BLAKE3 和 ZIP 结构。 -9. 远端变化、本地 audit 发现 repair_needed，或首次空目录运行时，下载并校验官方 URL。 -10. 下载成功后写回新的 snapshot。 +9. 远端变化、本地 audit 发现 repair_needed，首次空目录运行，或缺少 `current` 原子发布指针时，进入下载/发布流程。 +10. 下载先写入 `/.staging/`；若已有 active release，会先 seed staging 以复用已验证文件。 +11. 下载、manifest、本地 BLAKE3、ZIP 和官方 `.hash` 校验完成后写入新的 snapshot。 +12. 将 staging rename 为 `/versions/`，再原子替换 `/current` symlink 指向该 versioned 目录。 -该入口不安装、不执行官方启动器，也不读取生产外的本地客户端目录。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；`bat-control.lock` 串行化控制命令，并在 stale/corrupt 时由下一次控制命令或 `clean-stable` 恢复。PID、status、log 和控制锁文件创建时使用私有权限，读取和写入时不跟随 symlink。`status`、`stop`、`logs`、`reload` 和默认形态的 `refresh` 优先走 RPC；`reload` 会唤醒或排队 watch 循环重新自动发现并强制刷新，`restart` 才负责重启进程或替换启动参数。后台 daemon 管理某个资源目录时，前台 `run/watch/refresh/repair` 不允许直接写入同一目录；默认形态 `refresh` 会通过 RPC 触发后台刷新。正常情况下默认每 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 调单次模式只是可选集成方式。项目是否热更新、热重载或重启进程，由上层业务集成决定。 +该入口不安装、不执行官方启动器，也不读取生产外的本地客户端目录。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；`bat-events.jsonl` 是带轮转的结构化 JSONL 事件日志；`bat-control.lock` 串行化控制命令，并在 stale/corrupt 时由下一次控制命令或 `clean-stable` 恢复。`bat-status.json` 和 `status` 子命令包含最后成功时间、下次检查时间、最后错误摘要、当前阶段和当前下载 URL 进度。PID、status、log 和控制锁文件创建时使用私有权限，读取和写入时不跟随 symlink。`status`、`stop`、`logs`、`reload` 和默认形态的 `refresh` 优先走 RPC；`reload` 会唤醒或排队 watch 循环重新自动发现并强制刷新，`restart` 才负责重启进程或替换启动参数。后台 daemon 管理某个资源目录时，前台 `run/watch/refresh/repair` 不允许直接写入同一目录；默认形态 `refresh` 会通过 RPC 触发后台刷新。正常情况下默认每 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 调单次模式只是可选集成方式。项目是否热更新、热重载或重启进程，由上层业务集成决定。 对应实现主要在： @@ -231,7 +233,7 @@ Linux 生产路径： - pull plan 会同时包含 discovery URLs 和 content URLs - 全量样本下是 `2` 个 discovery URL + `5` 个内容 URL = `7` 个 URL - `OfficialUpdateService` 能持久化 v2 snapshot，并在远端 marker 内容变化时触发下载决策 -- `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` 防止并发写资源目录，控制命令使用 `bat-control.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` 防止并发写资源目录，控制命令使用 `bat-control.lock` 防止并发状态修改，资源发布使用 `.staging`、`versions` 和 `current` 原子切换，daemon 写 `bat-events.jsonl` 结构化日志并在 `status` 中暴露下载进度和调度状态 - `OfficialUpdateService` 能读写 `official-bootstrap-cache.json`，并支持默认开启的 `audit_local` / `repair` CLI 行为 - 下载层能在本地文件 size/BLAKE3/path、ZIP 结构或 manifest 不匹配时重新下载 - 官方 seed `.hash` mismatch 会导致下载失败，而不是降级为本地 BLAKE3 猜测 diff --git a/docs/guides/deployment.md b/docs/guides/deployment.md index 1f8ffb6..4bf2187 100644 --- a/docs/guides/deployment.md +++ b/docs/guides/deployment.md @@ -173,11 +173,13 @@ sudo install -d -o bat -g bat -m 0750 \ `/var/lib/bluearchive-toolkit/official/` 会保存： -- `official-sync-snapshot.json` +- `current`：指向当前可读 release 的 symlink +- `versions//official-sync-snapshot.json` +- `versions//official-download-manifest.json` +- `versions//...` 下载得到的官方资源文件 +- `.staging/`：下载和校验中的临时 release - `official-bootstrap-cache.json` -- `official-download-manifest.json` - `.official-sync.lock` -- 下载得到的官方资源文件 不要把输出目录设为： @@ -228,11 +230,11 @@ sudo -u bat /opt/bluearchive-toolkit/bin/bat doctor \ --state-dir /run/bluearchive-toolkit ``` -`--watch` 是 Rust 内部持久检查模式，正常情况下默认每 1 小时执行一次检查，并且每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 会强制执行一次自动刷新。固定时间刷新会中断普通 interval 的 sleep，该轮注入 `force=true`；如果失败，会按失败重试周期继续重试。远端和本地一致时默认静默；有远端变化或本地文件损坏时自动下载或 repair，并输出人类可读摘要。下载、发现或校验失败时默认 60 秒后重试，可显式加 `BAT_ERROR_RETRY=60s` 或调整 service `ExecStart`。默认平台是 `Windows,Android`，无需显式传 `--platforms`；需要覆盖时用 systemd drop-in 重写 `ExecStart`。默认资源目录是 `./bat-resources`，生产 service 显式使用 `/var/lib/bluearchive-toolkit/official`。 +`--watch` 是 Rust 内部持久检查模式，正常情况下默认每 1 小时执行一次检查，并且每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 会强制执行一次自动刷新。固定时间刷新会中断普通 interval 的 sleep，该轮注入 `force=true`；如果失败，会按失败重试周期继续重试。远端和本地一致时默认静默；有远端变化或本地文件损坏时自动下载或 repair，并输出人类可读摘要。下载、发现或校验失败时默认 60 秒后重试，可显式加 `BAT_ERROR_RETRY=60s` 或调整 service `ExecStart`。默认平台是 `Windows,Android`，无需显式传 `--platforms`；需要覆盖时用 systemd drop-in 重写 `ExecStart`。默认资源目录是 `./bat-resources`，生产 service 显式使用 `/var/lib/bluearchive-toolkit/official`。生产读取方应读取 `/var/lib/bluearchive-toolkit/official/current`；同步中的文件只会进入 `.staging/`，校验完成后才发布为 `versions/` 并切换 `current`。 ### 可选模式：CLI 自托管 `--daemon` -不使用 systemd 时，可以直接后台运行。生产中不要使用默认 `/tmp/bat-pid`，建议使用持久状态目录，这样 `bat-daemon.log` 不会随 reboot 或 tmp 清理丢失： +不使用 systemd 时，可以直接后台运行。生产中不要使用默认 `/tmp/bat-pid`，建议使用持久状态目录，这样 `bat-daemon.log` 和 `bat-events.jsonl` 不会随 reboot 或 tmp 清理丢失： ```bash sudo -u bat /opt/bluearchive-toolkit/bin/bat \ @@ -248,7 +250,7 @@ sudo -u bat /opt/bluearchive-toolkit/bin/bat reload --state-dir /var/lib/bluearc sudo -u bat /opt/bluearchive-toolkit/bin/bat stop --state-dir /var/lib/bluearchive-toolkit/daemon-state ``` -`--daemon` 会在 `--state-dir` 下创建 `bat.sock`、`bat.pid`、`bat-status.json`、`bat-daemon.log` 和短生命周期的 `bat-control.lock`。`bat.sock` 是 Unix socket JSON-RPC 控制通道；`status`、`stop`、`logs`、`reload` 和默认形态的 `refresh` 会优先连接 live daemon。PID、状态和日志文件保留为快照、诊断和 socket 不可用时的兼容路径；`bat-control.lock` 串行化控制命令，并能在 stale/corrupt 时由下一次控制命令或 `clean-stable` 恢复。`reload` 默认不会重启进程，而是让 watch 循环重新自动发现并强制刷新：空闲睡眠时立即唤醒，正在同步时排队到当前轮结束后执行；需要替换启动参数或 binary 时用 `restart`。 +`--daemon` 会在 `--state-dir` 下创建 `bat.sock`、`bat.pid`、`bat-status.json`、`bat-daemon.log`、`bat-events.jsonl` 和短生命周期的 `bat-control.lock`。`bat.sock` 是 Unix socket JSON-RPC 控制通道；`status`、`stop`、`logs`、`reload` 和默认形态的 `refresh` 会优先连接 live daemon。PID、状态和日志文件保留为快照、诊断和 socket 不可用时的兼容路径；`bat-events.jsonl` 是带轮转的结构化 JSONL 事件日志；`bat-status.json` 会暴露最后成功时间、下次检查时间、最后错误摘要和当前下载进度；`bat-control.lock` 串行化控制命令，并能在 stale/corrupt 时由下一次控制命令或 `clean-stable` 恢复。`reload` 默认不会重启进程，而是让 watch 循环重新自动发现并强制刷新：空闲睡眠时立即唤醒，正在同步时排队到当前轮结束后执行；需要替换启动参数或 binary 时用 `restart`。 不要同时运行 systemd `--watch` 和 standalone `--daemon` 指向同一个 `--output`。二者都会被资源锁和 live daemon 互斥保护，但生产运维上应保持单一 owner。 @@ -257,14 +259,18 @@ sudo -u bat /opt/bluearchive-toolkit/bin/bat stop --state-dir /var/lib/bluearchi systemd 模式： - 进程日志：`journalctl -u bluearchive-toolkit-official-sync.service` -- 资源状态：`/var/lib/bluearchive-toolkit/official/official-sync-snapshot.json` -- 下载 manifest：`/var/lib/bluearchive-toolkit/official/official-download-manifest.json` +- 当前可读 release：`/var/lib/bluearchive-toolkit/official/current` +- 资源状态：`/var/lib/bluearchive-toolkit/official/current/official-sync-snapshot.json` +- 下载 manifest：`/var/lib/bluearchive-toolkit/official/current/official-download-manifest.json` +- 历史 release：`/var/lib/bluearchive-toolkit/official/versions/` +- 同步 staging：`/var/lib/bluearchive-toolkit/official/.staging/` - 资源写锁：`/var/lib/bluearchive-toolkit/official/.official-sync.lock` - 运行期目录：`/run/bluearchive-toolkit/` standalone `--daemon` 模式： - 进程日志：`/bat-daemon.log` +- 结构化事件日志：`/bat-events.jsonl` - RPC socket：`/bat.sock` - PID 文件：`/bat.pid` - daemon 状态：`/bat-status.json` @@ -327,14 +333,14 @@ sudo systemctl start bluearchive-toolkit-official-sync.service journalctl -u bluearchive-toolkit-official-sync.service -n 100 --no-pager ``` -当前官方资源同步的本地状态位于 `/var/lib/bluearchive-toolkit/official`。普通 binary 回滚不需要回滚资源目录；如果要测试可能改动 manifest/schema 的版本，先备份资源状态文件： +当前官方资源同步的本地状态位于 `/var/lib/bluearchive-toolkit/official`，生产读取入口是 `/var/lib/bluearchive-toolkit/official/current`。普通 binary 回滚不需要回滚资源目录；如果要测试可能改动 manifest/schema 的版本，先备份当前 release 状态文件和 bootstrap cache： ```bash sudo -u bat tar -C /var/lib/bluearchive-toolkit/official \ -czf /var/lib/bluearchive-toolkit/official-state-backup.tgz \ - official-sync-snapshot.json \ official-bootstrap-cache.json \ - official-download-manifest.json + current/official-sync-snapshot.json \ + current/official-download-manifest.json ``` 如果业务层需要热更新、热重载或发布新资源，应该由上层服务在观察到 `--json` report 或 snapshot 变化后决定。Rust 同步进程只负责拉取、校验和维护本地状态。 diff --git a/docs/guides/official-resource-test-pull.md b/docs/guides/official-resource-test-pull.md index a65b24a..fc6fb0c 100644 --- a/docs/guides/official-resource-test-pull.md +++ b/docs/guides/official-resource-test-pull.md @@ -45,7 +45,7 @@ target/release/bat \ --watch ``` -默认资源输出目录是 `./bat-resources`，默认后台状态目录是 `/tmp/bat-pid`。后台状态目录会保存 `bat.sock`、`bat.pid`、`bat-status.json`、`bat-daemon.log` 和短生命周期的 `bat-control.lock`；其中 `bat.sock` 是 live daemon 的 Unix socket JSON-RPC 控制通道，`bat-control.lock` 串行化 `status/stop/restart/reload/logs/refresh` 等控制命令，其他文件是快照和故障排查用。生产资源输出目录必须是独立目录；需要覆盖时用 `--output <资源目录>`，不要使用已有游戏客户端目录、官方启动器安装目录、人工维护资源目录，或开发机上的 `/home/wanye/D/BlueArchive`。 +默认资源输出目录是 `./bat-resources`，默认后台状态目录是 `/tmp/bat-pid`。资源输出目录是发布根目录：非 dry-run 同步先写 `/.staging/`，校验完成后移动到 `/versions/`，再原子切换 `/current` symlink；生产读取方应读取 `current`。后台状态目录会保存 `bat.sock`、`bat.pid`、`bat-status.json`、`bat-daemon.log`、`bat-events.jsonl` 和短生命周期的 `bat-control.lock`；其中 `bat.sock` 是 live daemon 的 Unix socket JSON-RPC 控制通道，`bat-events.jsonl` 是带轮转的结构化 JSONL 事件日志，`bat-status.json` 保存最后成功时间、下次检查时间、最后错误摘要和当前下载进度，`bat-control.lock` 串行化 `status/stop/restart/reload/logs/refresh` 等控制命令。生产资源输出目录必须是独立目录；需要覆盖时用 `--output <资源目录>`，不要使用已有游戏客户端目录、官方启动器安装目录、人工维护资源目录，或开发机上的 `/home/wanye/D/BlueArchive`。 同步流程会拒绝危险输出目录、路径逃逸和现有 symlink 路径组件；下载目标、`.part`、manifest、snapshot、PID、status、log 和控制锁文件不会跟随 symlink，daemon 状态类文件默认以 `0600` 权限创建。 @@ -57,7 +57,7 @@ Linux 生产运行时链路只走官方日服 HTTP 资源，不安装、不启 2. 请求官方 `server-info`。 3. 生成 Windows + Android 的官方资源 discovery 端点。 4. 拉取 seed catalog，生成完整官方 pull plan。 -5. dry-run 只输出 URL；非 dry-run 下载全部官方 URL。 +5. dry-run 只输出 URL；非 dry-run 下载全部官方 URL 到 staging，验收完成后原子发布到 `current`。 `--auto-discover` 会下载官方 metadata，并按官方 manifest 临时获取 `resources.assets` 解析 `GameMainConfig`；旧 ZIP manifest 才会下载临时 game zip。该流程不会安装官方启动器，也不会执行官方启动器进程。`--launcher-bootstrap` 只是旧命名兼容别名，新流程不要再推荐使用。 @@ -137,13 +137,13 @@ cargo run -p bat-infrastructure --example official_pull_plan -- \ - 只接受官方 URL - 下载完整官方资源集合 -- 下载成功后在输出目录维护 `official-download-manifest.json` +- 下载成功后在 release 目录维护 `official-download-manifest.json` - 已存在目标文件只有在本地下载清单中的 size 和 BLAKE3 校验通过时才会跳过；`.zip` 文件还必须通过 ZIP central directory / local header 结构校验 - `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`，成功并通过必要校验后再替换为最终文件；如果断点续传后的 `.zip` 结构校验失败，会删除 `.part` 并重新全量下载 -- 把结果写入 `--output` +- 把结果发布到 `--output/current` ## 5. 自动更新检查 @@ -151,23 +151,23 @@ cargo run -p bat-infrastructure --example official_pull_plan -- \ - 每轮都会先拉取轻量官方 metadata 和 `.hash` marker。 - URL 没变但 `.hash` / marker 内容变更时，也会判定为需要更新。 -- 即使远端 snapshot 未变化，只要输出目录没有任何当前 pull plan 的本地 manifest 条目或目标文件，也会按首次运行处理并执行全量拉取。 -- 远端无变化时，默认执行本地 `official-download-manifest.json` audit。 +- 即使远端 snapshot 未变化，只要 active release 没有任何当前 pull plan 的本地 manifest 条目或目标文件，也会按首次运行处理并执行全量拉取。 +- 远端无变化时，默认执行 active release 中的 `official-download-manifest.json` audit。 - 本地文件缺失、路径不一致、size 不一致、BLAKE3 不一致或 ZIP 结构无效时，默认进入 repair 并重下必要文件。 - 官方 seed `.hash` 校验失败会让本轮失败，并清理对应本地 manifest 条目；下一轮会继续把这类文件视为需要 repair，而不是把失败产物当作健康缓存复用。 - 远端和本地都一致：单次模式输出 `update_status=up_to_date`，watch 模式默认静默并等待下次检查。 -- 有远端变化或本地 repair：生成 pull plan，下载完整官方资源，成功后更新 snapshot。 +- 有远端变化或本地 repair：生成 pull plan，下载完整官方资源到 staging，成功后更新 snapshot 并原子发布到 `current`。 - `--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`。 - 下载阶段复用同一套本地清单、ZIP 结构校验和 `.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。 +- `/current/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 到临时目录解析。 +- `/current/official-download-manifest.json`：本地下载强校验清单，记录 URL、相对路径、size 和 BLAKE3。 先 dry-run： @@ -215,7 +215,7 @@ 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/状态文件兼容路径。控制命令会通过 `bat-control.lock` 做跨进程互斥，失效或损坏的控制锁会在下次控制命令或 `clean-stable` 时恢复。`restart` 会停止旧后台进程并按保存参数或显式参数重新启动；`reload` 在未显式传入同步参数时不会重启进程，而是唤醒或排队 watch 循环重新执行自动发现和强制刷新：空闲睡眠时立即执行，正在同步时等当前轮结束。所有命令默认输出人类可读摘要，脚本集成时加 `--json`。 +`status`、`stop`、`logs`、`reload` 和默认形态的 `refresh` 会优先连接 `bat.sock`，通过 Unix socket JSON-RPC 和 live daemon 通信；socket 不可用时，`status`、`stop` 会回退到 PID/状态文件兼容路径。`status` 会显示最后成功时间、下次检查时间、最后错误摘要、当前阶段、当前下载 URL 进度、文本日志路径、结构化日志路径和轮转日志路径。控制命令会通过 `bat-control.lock` 做跨进程互斥，失效或损坏的控制锁会在下次控制命令或 `clean-stable` 时恢复。`restart` 会停止旧后台进程并按保存参数或显式参数重新启动；`reload` 在未显式传入同步参数时不会重启进程，而是唤醒或排队 watch 循环重新执行自动发现和强制刷新：空闲睡眠时立即执行，正在同步时等当前轮结束。所有命令默认输出人类可读摘要，脚本集成时加 `--json`。 如果要把后台状态目录改到其他位置，使用 `--state-dir <目录>`： @@ -258,9 +258,9 @@ 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 阶段；命令结果默认以人类可读摘要写到 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 阶段；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 自动更新的唯一方式。项目是否热更新、热重载或重启进程，由上层业务集成决定。生产资源目录应使用独立输出目录，不要指向现有客户端或人工维护的资源目录。非 dry-run 每轮会创建 `--output/.official-sync.lock`，防止并发写同一资源目录；live daemon 还会阻止前台写命令直接修改它正在管理的同一目录。 +生产可以直接运行 `--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`，但生产同步默认应保持开启。 diff --git a/infrastructure/src/bin/bat_official_sync.rs b/infrastructure/src/bin/bat_official_sync.rs index 5effd27..e4aa12a 100644 --- a/infrastructure/src/bin/bat_official_sync.rs +++ b/infrastructure/src/bin/bat_official_sync.rs @@ -1,9 +1,9 @@ use bat_adapters::official::yostar_jp::PatchPlatform; use bat_infrastructure::{ - open_append_file, read_file_no_symlink, validate_output_root, validate_runtime_state_dir, - write_file_atomic, OfficialServerInfoSource, OfficialUpdateConfig, OfficialUpdateProgress, - OfficialUpdateReport, OfficialUpdateService, OfficialUpdateStatus, OfficialVerificationSummary, - PRIVATE_FILE_MODE, + lexical_absolute, open_append_file, read_file_no_symlink, validate_output_root, + validate_runtime_state_dir, write_file_atomic, OfficialServerInfoSource, OfficialUpdateConfig, + OfficialUpdateProgress, OfficialUpdateReport, OfficialUpdateService, OfficialUpdateStatus, + OfficialVerificationSummary, PRIVATE_FILE_MODE, }; use serde::{Deserialize, Serialize}; use std::env; @@ -27,9 +27,13 @@ const DEFAULT_DAEMON_STATE_DIR: &str = "/tmp/bat-pid"; const DAEMON_PID_FILE: &str = "bat.pid"; const DAEMON_STATUS_FILE: &str = "bat-status.json"; const DAEMON_LOG_FILE: &str = "bat-daemon.log"; +const DAEMON_STRUCTURED_LOG_FILE: &str = "bat-events.jsonl"; const DAEMON_SOCKET_FILE: &str = "bat.sock"; const DAEMON_CONTROL_LOCK_FILE: &str = "bat-control.lock"; const DAEMON_STATUS_VERSION: u32 = 1; +const STRUCTURED_LOG_MAX_BYTES: u64 = 5 * 1024 * 1024; +const STRUCTURED_LOG_ROTATE_KEEP: usize = 3; +const OFFICIAL_CURRENT_LINK: &str = "current"; const SECONDS_PER_DAY: u64 = 24 * 60 * 60; const BEIJING_UTC_OFFSET_SECONDS: u64 = 8 * 60 * 60; const DAILY_FORCED_REFRESH_LOCAL_SECONDS: [u64; 3] = [3 * 60 * 60, 16 * 60 * 60, 18 * 60 * 60]; @@ -244,6 +248,9 @@ fn run_watch(options: CliOptions) -> anyhow::Result<()> { let service = OfficialUpdateService::new(); let mut logger = ProgressLogger::new(options.progress); let daemon_state_dir = options.state_dir.clone(); + if options.daemon_child { + logger.attach_structured_log(daemon_structured_log_path(&daemon_state_dir)); + } let daemon_control = if options.daemon_child { Some(new_daemon_control()) } else { @@ -315,13 +322,23 @@ fn run_watch(options: CliOptions) -> anyhow::Result<()> { last_update_status: None, last_error: None, next_retry_seconds: None, + last_success_unix_seconds: None, + next_check_unix_seconds: None, pending_scheduled_force, next_forced_refresh_at, }, ); match service.run_with_progress_and_cancellation( &iteration_config, - |event| logger.log(event), + |event| { + record_daemon_progress( + options.daemon_child, + &daemon_state_dir, + &mut logger, + &event, + ); + logger.log(event); + }, || daemon_control_stop_requested(daemon_control.as_ref()), ) { Ok(report) => { @@ -342,6 +359,8 @@ fn run_watch(options: CliOptions) -> anyhow::Result<()> { last_update_status: Some(report.update_status.as_str().to_string()), last_error: None, next_retry_seconds: Some(sleep_for.as_secs()), + last_success_unix_seconds: Some(unix_seconds_now()), + next_check_unix_seconds: Some(unix_seconds_after(sleep_for)), pending_scheduled_force, next_forced_refresh_at, }, @@ -369,6 +388,8 @@ fn run_watch(options: CliOptions) -> anyhow::Result<()> { last_update_status: None, last_error: Some(localize_error_message(&error.to_string())), next_retry_seconds: Some(sleep_for.as_secs()), + last_success_unix_seconds: None, + next_check_unix_seconds: Some(unix_seconds_after(sleep_for)), pending_scheduled_force, next_forced_refresh_at, }, @@ -431,6 +452,8 @@ fn run_watch(options: CliOptions) -> anyhow::Result<()> { last_update_status: None, last_error: None, next_retry_seconds: None, + last_success_unix_seconds: None, + next_check_unix_seconds: None, pending_scheduled_force, next_forced_refresh_at, }, @@ -450,22 +473,46 @@ struct DaemonStatusFile { resource_output_root: PathBuf, state_dir: PathBuf, log_path: PathBuf, + #[serde(default)] + structured_log_path: Option, started_unix_seconds: u64, updated_unix_seconds: u64, + #[serde(default)] + last_success_unix_seconds: Option, + #[serde(default)] + next_check_unix_seconds: Option, last_update_status: Option, last_error: Option, next_retry_seconds: Option, + #[serde(default)] + current_stage: Option, + #[serde(default)] + current_message: Option, + #[serde(default)] + download_progress: Option, pending_scheduled_force: bool, next_forced_refresh_unix_seconds: Option, command: Vec, } +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +struct DaemonDownloadProgress { + index: usize, + total: usize, + url: String, + status: Option, + bytes: Option, + transferred_bytes: Option, +} + #[derive(Debug)] struct DaemonStatusUpdate<'a> { state: &'a str, last_update_status: Option, last_error: Option, next_retry_seconds: Option, + last_success_unix_seconds: Option, + next_check_unix_seconds: Option, pending_scheduled_force: bool, next_forced_refresh_at: SystemTime, } @@ -557,6 +604,8 @@ fn record_daemon_status( update.last_update_status, update.last_error, update.next_retry_seconds, + update.last_success_unix_seconds, + update.next_check_unix_seconds, update.pending_scheduled_force, update.next_forced_refresh_at, ) { @@ -564,6 +613,21 @@ fn record_daemon_status( } } +fn record_daemon_progress( + enabled: bool, + state_dir: &Path, + logger: &mut ProgressLogger, + event: &OfficialUpdateProgress, +) { + if !enabled { + return; + } + + if let Err(error) = update_daemon_progress(state_dir, event) { + logger.log_text("daemon", format!("更新后台进度失败：{error}")); + } +} + #[derive(Debug)] struct DaemonRpcServer { socket_path: PathBuf, @@ -1216,6 +1280,7 @@ struct DaemonStartReport { pid_path: PathBuf, status_path: PathBuf, log_path: PathBuf, + structured_log_path: PathBuf, socket_path: PathBuf, } @@ -1234,12 +1299,19 @@ struct DaemonStatusReport { stale_pid_file: bool, stale_socket: bool, log_path: Option, + structured_log_path: Option, + rotated_structured_log_paths: Vec, started_unix_seconds: Option, updated_unix_seconds: Option, + last_success_unix_seconds: Option, + next_check_unix_seconds: Option, daemon_state: Option, last_update_status: Option, last_error: Option, next_retry_seconds: Option, + current_stage: Option, + current_message: Option, + download_progress: Option, pending_scheduled_force: Option, next_forced_refresh_unix_seconds: Option, command: Option>, @@ -1289,6 +1361,7 @@ fn start_daemon_with_args( let pid_path = daemon_pid_path(&state_dir); let status_path = daemon_status_path(&state_dir); let log_path = daemon_log_path(&state_dir); + let structured_log_path = daemon_structured_log_path(&state_dir); let socket_path = daemon_socket_path(&state_dir); match classify_pid_lock_file(&pid_path)? { @@ -1339,11 +1412,17 @@ fn start_daemon_with_args( resource_output_root: resource_output_root.clone(), state_dir: state_dir.clone(), log_path: log_path.clone(), + structured_log_path: Some(structured_log_path.clone()), started_unix_seconds: unix_seconds_now(), updated_unix_seconds: unix_seconds_now(), + last_success_unix_seconds: None, + next_check_unix_seconds: None, last_update_status: None, last_error: None, next_retry_seconds: None, + current_stage: None, + current_message: None, + download_progress: None, pending_scheduled_force: false, next_forced_refresh_unix_seconds: None, command, @@ -1359,6 +1438,7 @@ fn start_daemon_with_args( pid_path, status_path, log_path, + structured_log_path, socket_path, }) } @@ -1504,6 +1584,12 @@ fn build_daemon_status_report(state_dir: &Path) -> anyhow::Result anyhow::Result anyhow::Result anyhow::Result<()> { print_json_field(value, "stale_pid_file", "失效 PID"); print_json_field(value, "stale_socket", "失效 socket"); print_json_field(value, "last_update_status", "上次同步"); + print_json_field(value, "last_success_unix_seconds", "最后成功时间"); print_json_field(value, "last_error", "上次错误"); print_json_field(value, "next_retry_seconds", "下次重试秒数"); + print_json_field(value, "next_check_unix_seconds", "下次检查时间"); + print_json_field(value, "current_stage", "当前阶段"); + print_json_field(value, "current_message", "当前消息"); + print_json_field(value, "download_progress", "下载进度"); print_json_field(value, "resource_output_root", "资源目录"); print_json_field(value, "state_dir", "状态目录"); print_json_field(value, "socket_path", "socket"); print_json_field(value, "log_path", "日志"); + print_json_field(value, "structured_log_path", "结构化日志"); + print_json_field(value, "rotated_structured_log_paths", "轮转日志"); return Ok(()); } if value.get("command").and_then(serde_json::Value::as_str) == Some("logs") { @@ -1868,6 +1978,14 @@ fn print_list(label: &str, values: &[String], limit: usize) { } } +fn format_daemon_download_progress(progress: &DaemonDownloadProgress) -> String { + let status = progress.status.as_deref().unwrap_or("running"); + format!( + "{}/{} {} {}", + progress.index, progress.total, status, progress.url + ) +} + fn print_verification_summary(summary: &OfficialVerificationSummary) { println!(" 校验摘要:"); for line in verification_summary_lines(summary) { @@ -1946,6 +2064,11 @@ impl HumanReport for OfficialUpdateReport { print_field("本地审计", format_bool(self.audit_local)); print_field("自动修复", format_bool(self.repair)); print_field("dry-run", format_bool(self.dry_run)); + print_path_field("输出根目录", &self.output_root); + print_path_field("active release", &self.active_resource_root); + print_path_field("current", &self.current_path); + print_optional_path_field("staging", self.staging_path.as_ref()); + print_optional_path_field("published", self.published_version_path.as_ref()); print_path_field("snapshot", &self.snapshot_path); print_path_field("manifest", &self.download_manifest); print_optional_path_field("写入 snapshot", self.snapshot_written.as_ref()); @@ -1990,6 +2113,7 @@ impl HumanReport for DaemonStartReport { print_path_field("状态目录", &self.state_dir); print_path_field("socket", &self.socket_path); print_path_field("日志", &self.log_path); + print_path_field("结构化日志", &self.structured_log_path); Ok(()) } } @@ -2006,12 +2130,26 @@ impl HumanReport for DaemonStatusReport { print_field("失效 PID", format_bool(self.stale_pid_file)); print_field("失效 socket", format_bool(self.stale_socket)); print_optional_field("上次同步", self.last_update_status.as_deref()); + print_optional_field("最后成功时间", self.last_success_unix_seconds); print_optional_field("上次错误", self.last_error.as_deref()); print_optional_field("下次重试秒数", self.next_retry_seconds); + print_optional_field("下次检查时间", self.next_check_unix_seconds); + print_optional_field("当前阶段", self.current_stage.as_deref()); + print_optional_field("当前消息", self.current_message.as_deref()); + if let Some(progress) = self.download_progress.as_ref() { + print_field("下载进度", format_daemon_download_progress(progress)); + } print_optional_path_field("资源目录", self.resource_output_root.as_ref()); print_path_field("状态目录", &self.state_dir); print_path_field("socket", &self.socket_path); print_optional_path_field("日志", self.log_path.as_ref()); + print_optional_path_field("结构化日志", self.structured_log_path.as_ref()); + let rotated = self + .rotated_structured_log_paths + .iter() + .map(|path| path.display().to_string()) + .collect::>(); + print_list("轮转日志", &rotated, 5); Ok(()) } } @@ -2051,6 +2189,7 @@ impl HumanReport for VerifyCommandReport { print_field("状态", self.status); print_field("健康", format_bool(self.healthy)); print_field("远端状态", &self.remote_update_status); + print_path_field("校验资源目录", &self.verified_resource_root); print_optional_field("计划 URL 数", self.planned_url_count); print_field("计划异常数", self.expected_plan_failure_count); print_field("本地 manifest 项", self.local_manifest_entry_count); @@ -2166,6 +2305,7 @@ struct VerifyCommandReport { message: &'static str, healthy: bool, remote_update_status: String, + verified_resource_root: PathBuf, planned_url_count: Option, expected_plan_failure_count: usize, local_manifest_entry_count: usize, @@ -2189,8 +2329,9 @@ fn run_verify_command(options: &CliOptions) -> anyhow::Result { let mut logger = ProgressLogger::new(options.progress); let update_report = OfficialUpdateService::new().run_with_progress(&config, |event| logger.log(event))?; + let verified_resource_root = active_official_resource_root(&config.output_root)?; let verification = bat_infrastructure::OfficialResourcePullService::with_curl_command( - &config.output_root, + &verified_resource_root, &config.curl_command, ) .verify_local_download_manifest() @@ -2229,6 +2370,7 @@ fn run_verify_command(options: &CliOptions) -> anyhow::Result { }, healthy, remote_update_status: update_report.update_status.as_str().to_string(), + verified_resource_root, planned_url_count: update_report.download_url_count, expected_plan_failure_count: update_report.local_manifest_repair_needed_count, local_manifest_entry_count: verification.items.len(), @@ -2693,6 +2835,8 @@ fn update_daemon_status( last_update_status: Option, last_error: Option, next_retry_seconds: Option, + last_success_unix_seconds: Option, + next_check_unix_seconds: Option, pending_scheduled_force: bool, next_forced_refresh_at: SystemTime, ) -> anyhow::Result<()> { @@ -2704,11 +2848,17 @@ fn update_daemon_status( resource_output_root: OfficialUpdateConfig::default().output_root, state_dir: state_dir.to_path_buf(), log_path: daemon_log_path(state_dir), + structured_log_path: Some(daemon_structured_log_path(state_dir)), started_unix_seconds: unix_seconds_now(), updated_unix_seconds: unix_seconds_now(), + last_success_unix_seconds: None, + next_check_unix_seconds: None, last_update_status: None, last_error: None, next_retry_seconds: None, + current_stage: None, + current_message: None, + download_progress: None, pending_scheduled_force: false, next_forced_refresh_unix_seconds: None, command: env::args().collect(), @@ -2719,11 +2869,44 @@ fn update_daemon_status( status.last_update_status = last_update_status; status.last_error = last_error; status.next_retry_seconds = next_retry_seconds; + if last_success_unix_seconds.is_some() { + status.last_success_unix_seconds = last_success_unix_seconds; + } + status.next_check_unix_seconds = next_check_unix_seconds; + if state != "running" { + status.current_stage = None; + status.current_message = None; + status.download_progress = None; + } status.pending_scheduled_force = pending_scheduled_force; status.next_forced_refresh_unix_seconds = system_time_to_unix_seconds(next_forced_refresh_at); write_daemon_status_file(&status_path, &status) } +fn update_daemon_progress(state_dir: &Path, event: &OfficialUpdateProgress) -> anyhow::Result<()> { + let status_path = daemon_status_path(state_dir); + let Some(mut status) = read_daemon_status_file(&status_path)? else { + return Ok(()); + }; + status.pid = std::process::id(); + status.updated_unix_seconds = unix_seconds_now(); + status.current_stage = Some(event.stage.to_string()); + status.current_message = Some(event.message.clone()); + status.download_progress = match (event.download_index, event.download_total) { + (Some(index), Some(total)) => Some(DaemonDownloadProgress { + index, + total, + url: event.download_url.clone().unwrap_or_default(), + status: event.download_status.clone(), + bytes: event.download_bytes, + transferred_bytes: event.download_transferred_bytes, + }), + _ if event.stage != "download" => None, + _ => status.download_progress, + }; + write_daemon_status_file(&status_path, &status) +} + fn update_daemon_state_only(state_dir: &Path, state: &str) -> anyhow::Result<()> { let status_path = daemon_status_path(state_dir); let Some(mut status) = read_daemon_status_file(&status_path)? else { @@ -2757,6 +2940,25 @@ fn daemon_log_path(output_root: &Path) -> PathBuf { output_root.join(DAEMON_LOG_FILE) } +fn daemon_structured_log_path(output_root: &Path) -> PathBuf { + output_root.join(DAEMON_STRUCTURED_LOG_FILE) +} + +fn rotated_structured_log_path(path: &Path, index: usize) -> PathBuf { + let file_name = path + .file_name() + .and_then(|value| value.to_str()) + .unwrap_or(DAEMON_STRUCTURED_LOG_FILE); + path.with_file_name(format!("{file_name}.{index}")) +} + +fn rotated_structured_log_paths(path: &Path) -> Vec { + (1..=STRUCTURED_LOG_ROTATE_KEEP) + .map(|index| rotated_structured_log_path(path, index)) + .filter(|path| path_exists_no_follow(path).unwrap_or(false)) + .collect() +} + fn daemon_socket_path(output_root: &Path) -> PathBuf { output_root.join(DAEMON_SOCKET_FILE) } @@ -2765,6 +2967,30 @@ fn daemon_control_lock_path(output_root: &Path) -> PathBuf { output_root.join(DAEMON_CONTROL_LOCK_FILE) } +fn active_official_resource_root(output_root: &Path) -> anyhow::Result { + let current_path = output_root.join(OFFICIAL_CURRENT_LINK); + let metadata = match fs::symlink_metadata(¤t_path) { + Ok(metadata) => metadata, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => { + return Ok(output_root.to_path_buf()); + } + Err(error) => return Err(error.into()), + }; + if !metadata.file_type().is_symlink() { + return Err(anyhow::anyhow!( + "current 已存在但不是 symlink：{}", + current_path.display() + )); + } + let target = fs::read_link(¤t_path)?; + let target = if target.is_absolute() { + target + } else { + output_root.join(target) + }; + lexical_absolute(&target).map_err(anyhow::Error::msg) +} + fn daemon_child_args(options: &CliOptions) -> Vec { let mut args = Vec::new(); let config = &options.config; @@ -2882,6 +3108,10 @@ fn unix_seconds_now() -> u64 { .as_secs() } +fn unix_seconds_after(duration: Duration) -> u64 { + unix_seconds_now().saturating_add(duration.as_secs()) +} + fn system_time_to_unix_seconds(time: SystemTime) -> Option { time.duration_since(UNIX_EPOCH) .ok() @@ -3026,6 +3256,7 @@ fn duration_until(deadline: SystemTime, now: SystemTime) -> Duration { struct ProgressLogger { enabled: bool, started_at: Instant, + structured: Option, } impl ProgressLogger { @@ -3033,23 +3264,175 @@ impl ProgressLogger { Self { enabled, started_at: Instant::now(), + structured: None, } } + fn attach_structured_log(&mut self, path: PathBuf) { + self.structured = Some(RotatingStructuredLogger::new( + path, + STRUCTURED_LOG_MAX_BYTES, + STRUCTURED_LOG_ROTATE_KEEP, + )); + } + fn log(&mut self, event: OfficialUpdateProgress) { - self.log_text(event.stage, event.message); + self.log_event(&event); } fn log_text(&mut self, stage: &str, message: impl AsRef) { + self.log_text_inner(stage, message.as_ref()); + } + + fn log_event(&mut self, event: &OfficialUpdateProgress) { + if self.enabled { + eprintln!( + "[+{} 信息] [{}] {}", + format_duration(self.started_at.elapsed()), + localized_stage(event.stage), + event.message + ); + } + if let Some(structured) = self.structured.as_mut() { + let _ = structured.write_event(self.started_at.elapsed(), event); + } + } + + fn log_text_inner(&mut self, stage: &str, message: &str) { if !self.enabled { + if let Some(structured) = self.structured.as_mut() { + let event = OfficialUpdateProgress::new(stage_to_static(stage), message); + let _ = structured.write_event(self.started_at.elapsed(), &event); + } return; } eprintln!( "[+{} 信息] [{}] {}", format_duration(self.started_at.elapsed()), localized_stage(stage), - message.as_ref() + message ); + if let Some(structured) = self.structured.as_mut() { + let event = OfficialUpdateProgress::new(stage_to_static(stage), message); + let _ = structured.write_event(self.started_at.elapsed(), &event); + } + } +} + +#[derive(Debug, Clone)] +struct RotatingStructuredLogger { + path: PathBuf, + max_bytes: u64, + keep: usize, +} + +impl RotatingStructuredLogger { + fn new(path: PathBuf, max_bytes: u64, keep: usize) -> Self { + Self { + path, + max_bytes, + keep, + } + } + + fn write_event( + &mut self, + elapsed: Duration, + event: &OfficialUpdateProgress, + ) -> anyhow::Result<()> { + let payload = serde_json::json!({ + "timestamp_unix_seconds": unix_seconds_now(), + "elapsed_ms": elapsed.as_millis(), + "level": "info", + "stage": event.stage, + "stage_label": localized_stage(event.stage), + "message": event.message.as_str(), + "download": event.download_index.map(|index| serde_json::json!({ + "index": index, + "total": event.download_total.unwrap_or(index), + "url": event.download_url.as_deref(), + "status": event.download_status.as_deref(), + "bytes": event.download_bytes, + "transferred_bytes": event.download_transferred_bytes, + })), + }); + let mut line = serde_json::to_vec(&payload)?; + line.push(b'\n'); + self.rotate_if_needed(line.len() as u64)?; + let mut file = open_append_file(&self.path, PRIVATE_FILE_MODE, "结构化日志") + .map_err(anyhow::Error::msg)?; + file.write_all(&line)?; + file.flush()?; + Ok(()) + } + + fn rotate_if_needed(&self, incoming_bytes: u64) -> anyhow::Result<()> { + let current_len = match fs::symlink_metadata(&self.path) { + Ok(metadata) if metadata.file_type().is_symlink() => { + return Err(anyhow::anyhow!( + "结构化日志不能是 symlink：{}", + self.path.display() + )) + } + Ok(metadata) if metadata.is_file() => metadata.len(), + Ok(_) => { + return Err(anyhow::anyhow!( + "结构化日志已存在但不是普通文件：{}", + self.path.display() + )) + } + Err(error) if error.kind() == std::io::ErrorKind::NotFound => 0, + Err(error) => return Err(error.into()), + }; + if current_len.saturating_add(incoming_bytes) <= self.max_bytes { + return Ok(()); + } + + for index in (1..=self.keep).rev() { + let from = if index == 1 { + self.path.clone() + } else { + rotated_structured_log_path(&self.path, index - 1) + }; + let to = rotated_structured_log_path(&self.path, index); + if !path_exists_no_follow(&from)? { + continue; + } + if path_exists_no_follow(&to)? { + fs::remove_file(&to)?; + } + fs::rename(&from, &to)?; + } + Ok(()) + } +} + +fn stage_to_static(stage: &str) -> &'static str { + match stage { + "start" => "start", + "lock" => "lock", + "bootstrap" => "bootstrap", + "launcher" => "launcher", + "bootstrap-cache" => "bootstrap-cache", + "game-main-config" => "game-main-config", + "metadata" => "metadata", + "server-info" => "server-info", + "discovery" => "discovery", + "markers" => "markers", + "marker" => "marker", + "catalog" => "catalog", + "local-state" => "local-state", + "audit" => "audit", + "decision" => "decision", + "plan" => "plan", + "download" => "download", + "snapshot" => "snapshot", + "publish" => "publish", + "finish" => "finish", + "watch" => "watch", + "daemon" => "daemon", + "dry-run" => "dry-run", + _ => "log", } } @@ -3075,6 +3458,7 @@ fn localized_stage(stage: &str) -> &str { "audit" => "审计", "dry-run" => "试运行", "download" => "下载", + "publish" => "发布", "resource" => "资源", "finish" => "完成", "watch" => "常驻", @@ -3477,8 +3861,10 @@ fn print_usage(binary: &str) { eprintln!(); eprintln!("Sync:"); eprintln!(" --platforms Platforms, e.g. Windows,Android"); - eprintln!(" --output Resource output dir (default: ./bat-resources)"); - eprintln!(" --snapshot Snapshot path (default: /official-sync-snapshot.json)"); + eprintln!( + " --output Resource publish root (default: ./bat-resources)" + ); + eprintln!(" --snapshot Override snapshot path (default: /current/official-sync-snapshot.json)"); eprintln!(" --curl curl executable (default: curl)"); eprintln!(" --unzip unzip executable (default: unzip)"); eprintln!(" --dry-run Do not write sync state"); @@ -3506,8 +3892,8 @@ fn print_usage(binary: &str) { eprintln!(); eprintln!("Defaults:"); eprintln!(" platforms: Windows,Android"); - eprintln!(" resource output: ./bat-resources"); - eprintln!(" daemon state: /tmp/bat-pid (bat.sock, bat.pid, bat-status.json, bat-daemon.log)"); + eprintln!(" resource output: ./bat-resources (current -> versions/, .staging/)"); + eprintln!(" daemon state: /tmp/bat-pid (bat.sock, bat.pid, bat-status.json, bat-daemon.log, bat-events.jsonl)"); eprintln!(" forced refresh: {DAILY_FORCED_REFRESH_LABEL}"); } @@ -3877,6 +4263,23 @@ mod tests { ); } + #[cfg(unix)] + #[test] + fn active_official_resource_root_uses_current_symlink() { + use std::os::unix::fs::symlink; + + let temp = tempfile::TempDir::new().unwrap(); + let output = temp.path().join("resources"); + let version = output.join("versions").join("v1"); + fs::create_dir_all(&version).unwrap(); + symlink(Path::new("versions").join("v1"), output.join("current")).unwrap(); + + assert_eq!( + active_official_resource_root(&output).unwrap(), + lexical_absolute(&version).unwrap() + ); + } + #[cfg(unix)] #[test] fn daemon_rpc_rejects_socket_symlink() { @@ -4028,6 +4431,80 @@ mod tests { assert_eq!(fs::read(&outside).unwrap(), b"outside"); } + #[test] + fn daemon_status_tracks_progress_success_and_next_check() { + let temp = tempfile::TempDir::new().unwrap(); + let state_dir = temp.path().join("state"); + let output_root = temp.path().join("resources"); + fs::create_dir_all(&state_dir).unwrap(); + fs::create_dir_all(&output_root).unwrap(); + write_daemon_status_file( + &daemon_status_path(&state_dir), + &test_daemon_status_file(&state_dir, &output_root), + ) + .unwrap(); + + let mut event = OfficialUpdateProgress::new("download", "(2/19) 开始 fixture"); + event.download_index = Some(2); + event.download_total = Some(19); + event.download_url = Some("https://prod-clientpatch.bluearchiveyostar.com/file.zip".into()); + update_daemon_progress(&state_dir, &event).unwrap(); + + let report = build_daemon_status_report(&state_dir).unwrap(); + assert_eq!(report.current_stage.as_deref(), Some("download")); + assert_eq!(report.download_progress.as_ref().unwrap().index, 2); + assert_eq!(report.download_progress.as_ref().unwrap().total, 19); + + let next_check = unix_seconds_after(Duration::from_secs(30)); + update_daemon_status( + &state_dir, + "sleeping", + Some("downloaded".to_string()), + None, + Some(30), + Some(123456), + Some(next_check), + false, + SystemTime::now() + Duration::from_secs(3600), + ) + .unwrap(); + let report = build_daemon_status_report(&state_dir).unwrap(); + assert_eq!(report.last_success_unix_seconds, Some(123456)); + assert_eq!(report.next_check_unix_seconds, Some(next_check)); + assert!(report.current_stage.is_none()); + assert!(report.download_progress.is_none()); + } + + #[test] + fn structured_logger_writes_jsonl_and_rotates() { + let temp = tempfile::TempDir::new().unwrap(); + let path = temp.path().join("bat-events.jsonl"); + let mut logger = RotatingStructuredLogger::new(path.clone(), 180, 2); + let mut event = OfficialUpdateProgress::new("download", "下载进度 fixture"); + event.download_index = Some(1); + event.download_total = Some(2); + event.download_url = Some("https://prod-clientpatch.bluearchiveyostar.com/a.zip".into()); + + for _ in 0..8 { + logger + .write_event(Duration::from_millis(42), &event) + .unwrap(); + } + + assert!(path.exists()); + assert!(rotated_structured_log_path(&path, 1).exists()); + let line = fs::read_to_string(&path) + .unwrap() + .lines() + .next() + .unwrap() + .to_string(); + let value: serde_json::Value = serde_json::from_str(&line).unwrap(); + assert_eq!(value["stage"], "download"); + assert_eq!(value["download"]["index"], 1); + assert_eq!(value["download"]["total"], 2); + } + #[cfg(unix)] #[test] fn read_pid_file_rejects_symlink() { @@ -4295,11 +4772,17 @@ mod tests { resource_output_root: output_root.to_path_buf(), state_dir: state_dir.to_path_buf(), log_path: daemon_log_path(state_dir), + structured_log_path: Some(daemon_structured_log_path(state_dir)), started_unix_seconds: unix_seconds_now(), updated_unix_seconds: unix_seconds_now(), + last_success_unix_seconds: Some(unix_seconds_now()), + next_check_unix_seconds: Some(unix_seconds_after(Duration::from_secs(60))), last_update_status: Some("up_to_date".to_string()), last_error: None, next_retry_seconds: Some(60), + current_stage: None, + current_message: None, + download_progress: None, pending_scheduled_force: false, next_forced_refresh_unix_seconds: None, command: vec!["bat".to_string(), "--daemon-child".to_string()], diff --git a/infrastructure/src/official_update.rs b/infrastructure/src/official_update.rs index fcc2948..c65ada2 100644 --- a/infrastructure/src/official_update.rs +++ b/infrastructure/src/official_update.rs @@ -31,11 +31,17 @@ use std::io::Write; #[cfg(unix)] use std::os::unix::fs::OpenOptionsExt; use std::path::{Path, PathBuf}; +use std::time::{SystemTime, UNIX_EPOCH}; /// Current official update snapshot schema version. pub const OFFICIAL_UPDATE_SNAPSHOT_VERSION: u32 = 2; /// Current official bootstrap cache schema version. pub const OFFICIAL_BOOTSTRAP_CACHE_VERSION: u32 = 1; +const OFFICIAL_CURRENT_LINK: &str = "current"; +const OFFICIAL_VERSIONS_DIR: &str = "versions"; +const OFFICIAL_STAGING_DIR: &str = ".staging"; +const OFFICIAL_DOWNLOAD_MANIFEST_FILE: &str = "official-download-manifest.json"; +const OFFICIAL_SYNC_SNAPSHOT_FILE: &str = "official-sync-snapshot.json"; /// Server-info input for an official update run. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] @@ -379,6 +385,16 @@ pub struct OfficialUpdateReport { pub addressables_root: String, /// Platform set used by the run. pub platforms: Vec, + /// Managed publish root containing `current`, `versions`, and staging. + pub output_root: PathBuf, + /// Active resource root used for local audit before this run. + pub active_resource_root: PathBuf, + /// Atomic `current` pointer path. + pub current_path: PathBuf, + /// Versioned release directory after a successful publish. + pub published_version_path: Option, + /// Staging directory used during download before publish. + pub staging_path: Option, /// Sync snapshot path. pub snapshot_path: PathBuf, /// Whether a previous snapshot existed. @@ -446,6 +462,18 @@ pub struct OfficialUpdateProgress { pub stage: &'static str, /// Human-readable status line. pub message: String, + /// One-based download index when the event represents URL download work. + pub download_index: Option, + /// Total URL count for the current download plan. + pub download_total: Option, + /// Current official URL for download progress. + pub download_url: Option, + /// Stable pull status label when a URL finished. + pub download_status: Option, + /// Final local byte count for the URL when known. + pub download_bytes: Option, + /// Bytes transferred in this run for the URL when known. + pub download_transferred_bytes: Option, } impl OfficialUpdateProgress { @@ -454,8 +482,192 @@ impl OfficialUpdateProgress { Self { stage, message: message.into(), + download_index: None, + download_total: None, + download_url: None, + download_status: None, + download_bytes: None, + download_transferred_bytes: None, } } + + fn with_download_progress(mut self, event: &OfficialResourcePullProgress) -> Self { + self.download_index = Some(event.index); + self.download_total = Some(event.total); + self.download_url = Some(event.url.clone()); + self.download_status = event.status.map(|status| status.as_str().to_string()); + self.download_bytes = event.bytes; + self.download_transferred_bytes = event.transferred_bytes; + self + } +} + +#[derive(Debug, Clone)] +struct OfficialPublishLayout { + root: PathBuf, + current_path: PathBuf, + versions_dir: PathBuf, + staging_dir: PathBuf, +} + +#[derive(Debug, Clone)] +struct OfficialPublishPlan { + id: String, + staging_path: PathBuf, + version_path: PathBuf, +} + +impl OfficialPublishLayout { + fn new(root: &Path) -> Self { + Self { + root: root.to_path_buf(), + current_path: root.join(OFFICIAL_CURRENT_LINK), + versions_dir: root.join(OFFICIAL_VERSIONS_DIR), + staging_dir: root.join(OFFICIAL_STAGING_DIR), + } + } + + fn active_resource_root(&self) -> Result { + if let Some(current_target) = self.current_target()? { + return Ok(current_target); + } + + // Legacy fallback for directories produced before atomic publishing. + // The next non-dry-run update will seed staging from this tree and + // publish it under `versions/` before switching `current`. + Ok(self.root.clone()) + } + + fn current_target(&self) -> Result, String> { + let metadata = match fs::symlink_metadata(&self.current_path) { + Ok(metadata) => metadata, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None), + Err(error) => { + return Err(format!( + "读取 current 指针失败 {}：{error}", + self.current_path.display() + )) + } + }; + + if !metadata.file_type().is_symlink() { + return Err(format!( + "current 必须是指向 versioned 目录的 symlink：{}", + self.current_path.display() + )); + } + + let target = fs::read_link(&self.current_path).map_err(|error| { + format!( + "读取 current symlink 目标失败 {}：{error}", + self.current_path.display() + ) + })?; + let target = if target.is_absolute() { + target + } else { + self.root.join(target) + }; + ensure_path_within_root(&self.root, &target)?; + ensure_safe_directory_path(&target, "current versioned 目录")?; + Ok(Some(target)) + } + + fn has_current_pointer(&self) -> Result { + Ok(self.current_target()?.is_some()) + } + + fn plan(&self, snapshot: &OfficialUpdateSnapshot) -> OfficialPublishPlan { + let id = publish_id(snapshot); + OfficialPublishPlan { + staging_path: self.staging_dir.join(&id), + version_path: self.versions_dir.join(&id), + id, + } + } + + fn prepare_staging(&self, plan: &OfficialPublishPlan) -> Result<(), String> { + validate_output_root(&self.root)?; + ensure_safe_directory_path(&self.staging_dir, "官方资源 staging 根目录")?; + fs::create_dir_all(&self.staging_dir).map_err(|error| { + format!( + "创建官方资源 staging 根目录失败 {}：{error}", + self.staging_dir.display() + ) + })?; + ensure_safe_directory_path(&self.staging_dir, "官方资源 staging 根目录")?; + + if path_exists_no_follow(&plan.staging_path)? { + ensure_safe_directory_path(&plan.staging_path, "官方资源 staging 目录")?; + fs::remove_dir_all(&plan.staging_path).map_err(|error| { + format!( + "清理官方资源 staging 目录失败 {}：{error}", + plan.staging_path.display() + ) + })?; + } + + if path_exists_no_follow(&plan.version_path)? { + return Err(format!( + "versioned 目录已存在，拒绝覆盖：{}", + plan.version_path.display() + )); + } + + fs::create_dir_all(&plan.staging_path).map_err(|error| { + format!( + "创建官方资源 staging 目录失败 {}：{error}", + plan.staging_path.display() + ) + })?; + ensure_safe_directory_path(&plan.staging_path, "官方资源 staging 目录") + } + + fn seed_staging_from_active( + &self, + active_root: &Path, + staging_root: &Path, + ) -> Result<(), String> { + if active_root == self.root && !self.legacy_manifest_exists()? { + return Ok(()); + } + if !path_exists_no_follow(active_root)? { + return Ok(()); + } + copy_tree_no_symlink(active_root, staging_root, active_root == self.root) + } + + fn legacy_manifest_exists(&self) -> Result { + path_exists_no_follow(&self.root.join(OFFICIAL_DOWNLOAD_MANIFEST_FILE)) + } + + fn publish(&self, plan: &OfficialPublishPlan) -> Result { + ensure_safe_directory_path(&self.versions_dir, "官方资源 versions 根目录")?; + fs::create_dir_all(&self.versions_dir).map_err(|error| { + format!( + "创建官方资源 versions 根目录失败 {}：{error}", + self.versions_dir.display() + ) + })?; + ensure_safe_directory_path(&self.versions_dir, "官方资源 versions 根目录")?; + ensure_safe_directory_path(&plan.staging_path, "官方资源 staging 目录")?; + if path_exists_no_follow(&plan.version_path)? { + return Err(format!( + "versioned 目录已存在，拒绝覆盖：{}", + plan.version_path.display() + )); + } + + fs::rename(&plan.staging_path, &plan.version_path).map_err(|error| { + format!( + "发布官方资源版本目录失败 {} -> {}：{error}", + plan.staging_path.display(), + plan.version_path.display() + ) + })?; + switch_current_symlink(&self.root, &self.current_path, &plan.id)?; + Ok(plan.version_path.clone()) + } } /// Official update runner. @@ -517,16 +729,24 @@ impl OfficialUpdateService { }; check_shutdown_requested(&mut should_cancel)?; + let publish_layout = OfficialPublishLayout::new(&config.output_root); + let active_resource_root = publish_layout + .active_resource_root() + .map_err(anyhow::Error::msg)?; + let has_current_pointer = publish_layout + .has_current_pointer() + .map_err(anyhow::Error::msg)?; + let default_platforms = default_official_platforms(); let platforms = config .platforms .as_deref() .unwrap_or(default_platforms.as_slice()); let fetcher = OfficialResourcePullService::with_curl_command( - &config.output_root, + &active_resource_root, &config.curl_command, ); - let snapshot_path = config.effective_snapshot_path(); + let snapshot_path = snapshot_path_for(config, &active_resource_root); let bootstrap_cache_path = config.bootstrap_cache_path(); let bootstrap = if config.auto_discover { @@ -750,7 +970,9 @@ impl OfficialUpdateService { .map(|audit| !audit.is_clean()) .unwrap_or(false); let initial_pull_needed = !has_local_resources; - let should_download = remote_should_download || repair_needed || initial_pull_needed; + let publish_required = !has_current_pointer; + let should_download = + remote_should_download || repair_needed || initial_pull_needed || publish_required; progress(OfficialUpdateProgress::new( "audit", format!( @@ -765,6 +987,12 @@ impl OfficialUpdateService { should_download, repair_needed, initial_pull_needed ), )); + if publish_required { + progress(OfficialUpdateProgress::new( + "publish", + "尚未存在 current 原子发布指针；本轮会发布 versioned 目录并切换 current", + )); + } check_shutdown_requested(&mut should_cancel)?; let mut report = OfficialUpdateReport { update_status: if should_download { @@ -777,6 +1005,11 @@ impl OfficialUpdateService { bundle_version: current_snapshot.bundle_version.clone(), addressables_root: current_snapshot.addressables_root.clone(), platforms: platforms.to_vec(), + output_root: config.output_root.clone(), + active_resource_root: active_resource_root.clone(), + current_path: publish_layout.current_path.clone(), + published_version_path: None, + staging_path: None, snapshot_path: snapshot_path.clone(), previous_snapshot_present: previous_snapshot.is_some(), decision: format!("{:?}", sync_plan.decision), @@ -850,11 +1083,35 @@ impl OfficialUpdateService { check_shutdown_requested(&mut should_cancel)?; let download_url_count = pull_plan.all_urls().map_err(anyhow::Error::msg)?.len(); + let publish_plan = publish_layout.plan(¤t_update_snapshot); + progress(OfficialUpdateProgress::new( + "publish", + format!( + "准备 staging={} versioned={}", + publish_plan.staging_path.display(), + publish_plan.version_path.display() + ), + )); + publish_layout + .prepare_staging(&publish_plan) + .map_err(anyhow::Error::msg)?; + publish_layout + .seed_staging_from_active(&active_resource_root, &publish_plan.staging_path) + .map_err(anyhow::Error::msg)?; + let staging_fetcher = OfficialResourcePullService::with_curl_command( + &publish_plan.staging_path, + &config.curl_command, + ); + let staging_snapshot_path = snapshot_path_for(config, &publish_plan.staging_path); + report.staging_path = Some(publish_plan.staging_path.clone()); + report.snapshot_path = staging_snapshot_path.clone(); + report.download_manifest = staging_fetcher.download_manifest_path(); + progress(OfficialUpdateProgress::new( "download", format!("下载或复用 {download_url_count} 个官方 URL"), )); - let pull_report = fetcher + let pull_report = staging_fetcher .pull_with_progress_and_cancellation( &pull_plan, |event| { @@ -878,16 +1135,37 @@ impl OfficialUpdateService { "执行最终本地 manifest 审计", )); check_shutdown_requested(&mut should_cancel)?; - let final_audit = fetcher + let final_audit = staging_fetcher .audit_local_manifest(&pull_plan) .map_err(anyhow::Error::msg)?; progress(OfficialUpdateProgress::new( "snapshot", - format!("写入快照 {}", snapshot_path.display()), + format!("写入快照 {}", staging_snapshot_path.display()), )); - write_snapshot(&snapshot_path, ¤t_update_snapshot)?; + if config.snapshot_path.is_none() { + write_snapshot(&staging_snapshot_path, ¤t_update_snapshot)?; + } + + progress(OfficialUpdateProgress::new( + "publish", + format!( + "校验完成，发布 versioned 目录并切换 current -> {}", + publish_plan.version_path.display() + ), + )); + let published_version_path = publish_layout + .publish(&publish_plan) + .map_err(anyhow::Error::msg)?; + let final_snapshot_path = snapshot_path_for(config, &published_version_path); + if config.snapshot_path.is_some() { + write_snapshot(&final_snapshot_path, ¤t_update_snapshot)?; + } report.update_status = OfficialUpdateStatus::Downloaded; + report.active_resource_root = published_version_path.clone(); + report.published_version_path = Some(published_version_path.clone()); + report.snapshot_path = final_snapshot_path.clone(); + report.download_manifest = published_version_path.join(OFFICIAL_DOWNLOAD_MANIFEST_FILE); report.resource_count = Some(pull_report.items.len()); report.downloaded_count = pull_report.downloaded_count(); report.resumed_count = pull_report.resumed_count(); @@ -903,7 +1181,7 @@ impl OfficialUpdateService { pull_report.official_hash_verified_count(), final_audit.zip_structure_verified_count(), ); - report.snapshot_written = Some(snapshot_path); + report.snapshot_written = Some(final_snapshot_path); progress(OfficialUpdateProgress::new( "finish", @@ -1079,7 +1357,8 @@ fn progress_from_pull_event(event: OfficialResourcePullProgress) -> OfficialUpda OfficialResourcePullProgressKind::Started => OfficialUpdateProgress::new( "download", format!("({}/{}) 开始 {}", event.index, event.total, event.url), - ), + ) + .with_download_progress(&event), OfficialResourcePullProgressKind::Finished => { let status = event.status.map(localized_pull_status).unwrap_or("未知"); OfficialUpdateProgress::new( @@ -1094,6 +1373,7 @@ fn progress_from_pull_event(event: OfficialResourcePullProgress) -> OfficialUpda event.url ), ) + .with_download_progress(&event) } } } @@ -1143,6 +1423,195 @@ fn validate_update_paths(config: &OfficialUpdateConfig) -> Result<(), String> { Ok(()) } +fn snapshot_path_for(config: &OfficialUpdateConfig, resource_root: &Path) -> PathBuf { + config + .snapshot_path + .clone() + .unwrap_or_else(|| resource_root.join(OFFICIAL_SYNC_SNAPSHOT_FILE)) +} + +fn path_exists_no_follow(path: &Path) -> Result { + match fs::symlink_metadata(path) { + Ok(metadata) if metadata.file_type().is_symlink() => { + Err(format!("路径不能是 symlink：{}", path.display())) + } + Ok(_) => Ok(true), + Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(false), + Err(error) => Err(format!("检查路径失败 {}：{error}", path.display())), + } +} + +fn copy_tree_no_symlink( + source: &Path, + destination: &Path, + skip_publish_management_entries: bool, +) -> Result<(), String> { + ensure_safe_directory_path(source, "官方资源发布源目录")?; + ensure_safe_directory_path(destination, "官方资源 staging 目录")?; + fs::create_dir_all(destination).map_err(|error| { + format!( + "创建官方资源 staging 子目录失败 {}：{error}", + destination.display() + ) + })?; + + for entry in fs::read_dir(source) + .map_err(|error| format!("读取官方资源发布源目录失败 {}：{error}", source.display()))? + { + let entry = entry.map_err(|error| { + format!("读取官方资源发布源目录项失败 {}：{error}", source.display()) + })?; + let source_path = entry.path(); + let file_name = entry.file_name(); + if skip_publish_management_entries { + if let Some(name) = file_name.to_str() { + if matches!( + name, + OFFICIAL_STAGING_DIR + | OFFICIAL_VERSIONS_DIR + | OFFICIAL_CURRENT_LINK + | ".official-sync.lock" + ) { + continue; + } + } + } + if destination.starts_with(&source_path) { + continue; + } + let destination_path = destination.join(file_name); + let metadata = fs::symlink_metadata(&source_path).map_err(|error| { + format!( + "读取官方资源发布源元数据失败 {}：{error}", + source_path.display() + ) + })?; + if metadata.file_type().is_symlink() { + return Err(format!( + "官方资源发布源不能包含 symlink：{}", + source_path.display() + )); + } + if metadata.is_dir() { + copy_tree_no_symlink(&source_path, &destination_path, false)?; + } else if metadata.is_file() { + if let Some(name) = source_path.file_name().and_then(|value| value.to_str()) { + if name.ends_with(".part") || name.ends_with(".tmp") { + continue; + } + } + if let Err(_error) = fs::hard_link(&source_path, &destination_path) { + fs::copy(&source_path, &destination_path).map_err(|copy_error| { + format!( + "复制官方资源到 staging 失败 {} -> {}：{copy_error}", + source_path.display(), + destination_path.display() + ) + })?; + } + } else { + return Err(format!( + "官方资源发布源包含非普通文件：{}", + source_path.display() + )); + } + } + Ok(()) +} + +#[cfg(unix)] +fn switch_current_symlink( + root: &Path, + current_path: &Path, + publish_id: &str, +) -> Result<(), String> { + use std::os::unix::fs::symlink; + + let temporary = root.join(format!(".current.{}.tmp", std::process::id())); + if path_exists_no_follow(&temporary)? { + fs::remove_file(&temporary).map_err(|error| { + format!("清理临时 current 指针失败 {}：{error}", temporary.display()) + })?; + } + let relative_target = Path::new(OFFICIAL_VERSIONS_DIR).join(publish_id); + symlink(&relative_target, &temporary).map_err(|error| { + format!( + "创建临时 current 指针失败 {} -> {}：{error}", + temporary.display(), + relative_target.display() + ) + })?; + + if let Ok(metadata) = fs::symlink_metadata(current_path) { + if !metadata.file_type().is_symlink() { + let _ = fs::remove_file(&temporary); + return Err(format!( + "current 已存在但不是 symlink：{}", + current_path.display() + )); + } + } + + fs::rename(&temporary, current_path).map_err(|error| { + format!( + "切换 current 指针失败 {} -> {}：{error}", + temporary.display(), + current_path.display() + ) + }) +} + +#[cfg(not(unix))] +fn switch_current_symlink( + _root: &Path, + _current_path: &Path, + _publish_id: &str, +) -> Result<(), String> { + Err("原子 current symlink 发布目前只支持 Unix/Linux 平台".to_string()) +} + +fn publish_id(snapshot: &OfficialUpdateSnapshot) -> String { + let bundle = snapshot + .bundle_version + .as_deref() + .map(sanitize_publish_segment) + .unwrap_or_else(|| "no-bundle".to_string()); + format!( + "{}-{}-{}-{}-{}", + sanitize_publish_segment(&snapshot.app_version), + bundle, + snapshot.addressables_marker_checked_count(), + unix_seconds_now(), + std::process::id() + ) +} + +fn sanitize_publish_segment(value: &str) -> String { + let sanitized = value + .chars() + .map(|ch| { + if ch.is_control() || matches!(ch, '/' | '\\' | ':' | '*' | '?' | '"' | '<' | '>' | '|') + { + '_' + } else { + ch + } + }) + .collect::(); + if sanitized.is_empty() { + "unknown".to_string() + } else { + sanitized + } +} + +fn unix_seconds_now() -> u64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap_or_default() + .as_secs() +} + /// Reads an official update snapshot from disk, accepting legacy v1 snapshots. pub fn read_snapshot(path: &Path) -> anyhow::Result> { let Some(data) = read_file_no_symlink(path, "官方更新快照").map_err(anyhow::Error::msg)? diff --git a/infrastructure/tests/official_game_main_config_bootstrap.rs b/infrastructure/tests/official_game_main_config_bootstrap.rs index be10b0a..b466fa0 100644 --- a/infrastructure/tests/official_game_main_config_bootstrap.rs +++ b/infrastructure/tests/official_game_main_config_bootstrap.rs @@ -229,6 +229,27 @@ fn official_update_first_run_pulls_without_pre_audit() { assert!(events .iter() .any(|event| { event.stage == "decision" && event.message.contains("首次拉取=true") })); + + let published = report.published_version_path.as_ref().unwrap(); + assert!(published.exists()); + assert!(report + .staging_path + .as_ref() + .is_some_and(|path| !path.exists())); + assert!(config.output_root.join("current").exists()); + assert!(fs::symlink_metadata(config.output_root.join("current")) + .unwrap() + .file_type() + .is_symlink()); + assert_eq!( + config + .output_root + .join("official-download-manifest.json") + .exists(), + false + ); + assert!(published.join("official-download-manifest.json").exists()); + assert!(published.join("official-sync-snapshot.json").exists()); } #[test] @@ -262,6 +283,11 @@ fn official_update_second_run_audits_existing_resources_before_reuse() { assert!(events.iter().any(|event| { event.stage == "decision" && event.message.contains("首次拉取=false") })); + assert!(config.output_root.join("current").exists()); + assert!(fs::symlink_metadata(config.output_root.join("current")) + .unwrap() + .file_type() + .is_symlink()); } struct TestHarness {