@@ -102,7 +102,7 @@ REDIS_PORT=6379
当前可部署的生产任务是 Rust 官方资源同步 binary。API Server 和 Web 尚未实现，不能按完整服务端产品部署。
### 构建
### 构建 release binary
``` bash
cargo build --release -p bat-infrastructure --bin bat
@@ -114,15 +114,64 @@ cargo build --release -p bat-infrastructure --bin bat
target/release/bat
```
### 目录约定
推荐生产状态目录：
生产不直接从 Git 工作区运行 binary。推荐把每次发布放进独立 release 目录，再用稳定 symlink 暴露当前版本：
``` text
/var/lib /bluearchive-toolkit/official/
/opt /bluearchive-toolkit/releases/<version-or-git-sha>/bat
/opt/bluearchive-toolkit/bin/bat -> /opt/bluearchive-toolkit/releases/<version-or-git-sha>/bat
```
该目录会保存 ：
示例安装命令 ：
``` bash
VERSION = " $( git rev-parse --short HEAD) "
sudo install -d -o root -g root -m 0755 \
/opt/bluearchive-toolkit/releases/" ${ VERSION } " \
/opt/bluearchive-toolkit/bin
sudo install -o root -g root -m 0755 \
target/release/bat \
/opt/bluearchive-toolkit/releases/" ${ VERSION } " /bat
sudo ln -sfn \
/opt/bluearchive-toolkit/releases/" ${ VERSION } " /bat \
/opt/bluearchive-toolkit/bin/bat
/opt/bluearchive-toolkit/bin/bat --help
```
### 用户和目录
生产建议使用固定系统用户运行，不使用 root 长期运行同步进程：
``` bash
getent group bat >/dev/null || sudo groupadd --system bat
id -u bat >/dev/null 2>& 1 || sudo useradd --system \
--gid bat \
--home-dir /var/lib/bluearchive-toolkit \
--shell /usr/sbin/nologin \
bat
```
如果用户或组已存在，保留现有对象即可。推荐目录：
``` text
/opt/bluearchive-toolkit/ # root 拥有，存 release binary 和当前 symlink
/etc/bluearchive-toolkit/ # root 拥有，存 service 配置
/var/lib/bluearchive-toolkit/official/ # bat 拥有，官方资源和同步状态
/var/lib/bluearchive-toolkit/daemon-state/ # bat 拥有，仅用于 standalone --daemon 持久状态
/run/bluearchive-toolkit/ # systemd 创建，运行期状态
/var/log/bluearchive-toolkit/ # systemd 创建，当前推荐用 journald
```
创建目录：
``` bash
sudo install -d -o root -g root -m 0755 /etc/bluearchive-toolkit
sudo install -d -o bat -g bat -m 0750 \
/var/lib/bluearchive-toolkit \
/var/lib/bluearchive-toolkit/official \
/var/lib/bluearchive-toolkit/daemon-state
```
`/var/lib/bluearchive-toolkit/official/` 会保存：
- `official-sync-snapshot.json`
- `official-bootstrap-cache.json`
@@ -137,79 +186,155 @@ target/release/bat
- 开发机现有资源目录，例如 `/home/wanye/D/BlueArchive`
- Git 工作区目录
### 一次性检查
### 首次 dry-run
``` bash
/opt/bluearchive-toolkit/bin/bat \
sudo -u bat /opt/bluearchive-toolkit/bin/bat \
--auto-discover \
--output /var/lib/bluearchive-toolkit/official \
--dry-run
--dry-run \
--no-progress
```
### 常驻自动更新
### 推荐模式：systemd 托管 `--watch`
生产推荐让 systemd 直接托管前台 `--watch` 进程，而不是在 systemd 里再启动 `--daemon` 。原因：
- systemd 能直接追踪主进程、退出码、重启次数和 stop 信号。
- 日志进入 journald，用 `journalctl` 管理，不依赖 `bat-daemon.log` 。
- Rust 内部已经负责 1 小时间隔、北京时间固定强制刷新和失败快速重试，systemd 不需要 timer。
- `bat --daemon` 的 Unix socket RPC 适合没有进程管理器的 shell/container 场景；systemd 场景下用 `systemctl` 、`journalctl` 、`bat verify/doctor` 运维即可。
安装 unit 和可选环境文件：
``` bash
/opt/bluearchive-toolkit/bin/bat \
--auto-discover \
--output /var/lib /bluearchive-toolkit/ official \
--watch
sudo install -o root -g root -m 0644 \
deployments/systemd/bluearchive-toolkit-official-sync.service \
/etc/systemd/system /bluearchive-toolkit- official-sync.service
sudo install -o root -g root -m 0644 \
deployments/systemd/official-sync.env.example \
/etc/bluearchive-toolkit/official-sync.env
sudo systemctl daemon-reload
sudo systemctl enable --now bluearchive-toolkit-official-sync.service
```
`--watch` 是 Rust 内部持久检查模式，正常情况下默认每 1 小时执行一次检查，并且每天北京时间（UTC+8）`03:00` 、`16:00` 、`18:00` 会强制执行一次自动刷新。固定时间刷新会中断普通 interval 的 sleep，该轮注入 `force=true` ；如果失败，会按失败重试周期继续重试。远端和本地一致时默认静默；有远端变化或本地文件损坏时自动下载或 repair，并输出人类可读摘要。下载、发现或校验失败时默认 60 秒后重试，可显式加 `--error-retry 60s` 或 `--error-retry-seconds 60` 调整。默认平台是 `Windows,Android` ，无需显式传 `--platforms` ；需要覆盖时再传。默认资源目录是 `./bat-resources` ，生产建议显式传 `--output /var/lib/bluearchive-toolkit/official` 。默认 ASCII banner 和进度日志写到 stderr，命令结果写到 stdout；如果由上层服务严格解析结构化输出，可加 `--json --no-progress` ，只想关闭横幅可加 `--no-banner` 。
不使用 systemd 时，也可以直接后台运行：
检查状态和日志：
``` bash
/opt/ bluearchive-toolkit/bin/bat \
systemctl status bluearchive-toolkit-official-sync.service
journalctl -u bluearchive-toolkit-official-sync.service -f
sudo -u bat /opt/bluearchive-toolkit/bin/bat doctor \
--output /var/lib/bluearchive-toolkit/official \
--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` 。
### 可选模式：CLI 自托管 `--daemon`
不使用 systemd 时，可以直接后台运行。生产中不要使用默认 `/tmp/bat-pid` ，建议使用持久状态目录，这样 `bat-daemon.log` 不会随 reboot 或 tmp 清理丢失：
``` bash
sudo -u bat /opt/bluearchive-toolkit/bin/bat \
--auto-discover \
--output /var/lib/bluearchive-toolkit/official \
--state-dir /run /bluearchive-toolkit \
--state-dir /var/lib /bluearchive-toolkit/daemon-state \
--daemon
/opt/bluearchive-toolkit/bin/bat status --state-dir /run /bluearchive-toolkit
/opt/bluearchive-toolkit/bin/bat logs --state-dir /run /bluearchive-toolkit --tail 200
/opt/bluearchive-toolkit/bin/bat restart --state-dir /run /bluearchive-toolkit
/opt/bluearchive-toolkit/bin/bat reload --state-dir /run /bluearchive-toolkit
/opt/bluearchive-toolkit/bin/bat stop --state-dir /run /bluearchive-toolkit
sudo -u bat /opt/bluearchive-toolkit/bin/bat status --state-dir /var/lib /bluearchive-toolkit/daemon-state
sudo -u bat /opt/bluearchive-toolkit/bin/bat logs --state-dir /var/lib /bluearchive-toolkit/daemon-state --tail 200
sudo -u bat /opt/bluearchive-toolkit/bin/bat restart --state-dir /var/lib /bluearchive-toolkit/daemon-state
sudo -u bat /opt/bluearchive-toolkit/bin/bat reload --state-dir /var/lib /bluearchive-toolkit/daemon-state
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` 。
生产维护时可以用以下单次命令：
不要同时运行 systemd `--watch` 和 standalone `--daemon` 指向同一个 `--output` 。二者都会被资源锁和 live daemon 互斥保护，但生产运维上应保持单一 owner。
### 日志和状态路径
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`
- 资源写锁：`/var/lib/bluearchive-toolkit/official/.official-sync.lock`
- 运行期目录：`/run/bluearchive-toolkit/`
standalone `--daemon` 模式：
- 进程日志：`<state-dir>/bat-daemon.log`
- RPC socket： `<state-dir>/bat.sock`
- PID 文件：`<state-dir>/bat.pid`
- daemon 状态：`<state-dir>/bat-status.json`
- 控制锁：`<state-dir>/bat-control.lock`
### 生产维护命令
``` bash
/opt/bluearchive-toolkit/bin/bat refresh --output /var/lib/bluearchive-toolkit/official
/opt/bluearchive-toolkit/bin/bat refresh --force --output /var/lib/bluearchive-toolkit/official
/opt/bluearchive-toolkit/bin/bat verify --output /var/lib/bluearchive-toolkit/official
/opt/bluearchive-toolkit/bin/bat repair --output /var/lib/bluearchive-toolkit/official
/opt/bluearchive-toolkit/bin/bat doctor --output /var/lib/bluearchive-toolkit/official --state-dir /run/bluearchive-toolkit
/opt/bluearchive-toolkit/bin/bat clean-stable --output /var/lib/bluearchive-toolkit/official --state-dir /run/bluearchive-toolkit
sudo -u bat /opt/bluearchive-toolkit/bin/bat refresh --output /var/lib/bluearchive-toolkit/official
sudo -u bat /opt/bluearchive-toolkit/bin/bat refresh --force --output /var/lib/bluearchive-toolkit/official
sudo -u bat /opt/bluearchive-toolkit/bin/bat verify --output /var/lib/bluearchive-toolkit/official
sudo -u bat /opt/bluearchive-toolkit/bin/bat repair --output /var/lib/bluearchive-toolkit/official
sudo -u bat /opt/bluearchive-toolkit/bin/bat doctor --output /var/lib/bluearchive-toolkit/official --state-dir /run/bluearchive-toolkit
sudo -u bat /opt/bluearchive-toolkit/bin/bat clean-stable --output /var/lib/bluearchive-toolkit/official --state-dir /run/bluearchive-toolkit
```
如果后台 daemon 正在运行，并且 `refresh` 没有显式指定另一套同步参数，`refresh` / `refresh --force` 会通过 RPC 唤醒或排队后台进程；带 `--output` 、server-info、connection-group、app-version、platforms、snapshot、curl 或 unzip 等显式参数时，`refresh` 会作为一次性前台同步运行，但不能写入 live daemon 正在管理的同一资源目录，否则会返回 locked。`verify` 发现远端变化、本地缺失或校验失败时返回非 0；`repair` 会走官方同步链路重新下载必要文件，但同样不能和 live daemon 并行写同一资源目录；`clean-stable` 只清理 `.part` 、`.tmp` 、失效或损坏的 PID/socket/锁，不删除正式资源。
### systemd service 示例
### 升级
systemd 只负责进程守护，不负责定时逻辑 ：
升级只替换 `/opt/bluearchive-toolkit/bin/bat` symlink，不直接覆盖旧 binary ：
``` ini
[Unit]
Description = BlueArchiveToolkit official resource sync
After = network-online.target
Wants = network-online.target
``` bash
NEW_VERSION = "<new-version-or-git-sha>"
cargo build --release -p bat-infrastructure --bin bat
sudo install -d -o root -g root -m 0755 \
/opt/bluearchive-toolkit/releases/" ${ NEW_VERSION } "
sudo install -o root -g root -m 0755 \
target/release/bat \
/opt/bluearchive-toolkit/releases/" ${ NEW_VERSION } " /bat
[Service]
Type = simple
User = bat
Group = bat
ExecStart = /opt/bluearchive-toolkit/bin/bat --auto-discover --output /var/lib/ bluearchive-toolkit/ official --watch --error-retry 60s
Restart = on-failure
RestartSec = 30
StateDirectory = bluearchive-toolkit
NoNewPrivileges = true
sudo systemctl stop bluearchive-toolkit-official-sync.service
sudo ln -sfn \
/opt/bluearchive-toolkit/releases/" ${ NEW_VERSION } " /bat \
/opt/bluearchive-toolkit/bin/bat
sudo systemctl start bluearchive-toolkit- official-sync.service
systemctl status bluearchive-toolkit-official-sync.service
journalctl -u bluearchive-toolkit-official-sync.service -n 100 --no-pager
```
[Install]
WantedBy = multi-user.target
升级后执行：
``` bash
sudo -u bat /opt/bluearchive-toolkit/bin/bat doctor \
--output /var/lib/bluearchive-toolkit/official \
--state-dir /run/bluearchive-toolkit
```
### 回滚
回滚同样只切 symlink，不删除资源目录和 manifest：
``` bash
PREVIOUS_VERSION = "<previous-version-or-git-sha>"
sudo systemctl stop bluearchive-toolkit-official-sync.service
sudo ln -sfn \
/opt/bluearchive-toolkit/releases/" ${ PREVIOUS_VERSION } " /bat \
/opt/bluearchive-toolkit/bin/bat
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 的版本，先备份资源状态文件：
``` 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
```
如果业务层需要热更新、热重载或发布新资源，应该由上层服务在观察到 `--json` report 或 snapshot 变化后决定。Rust 同步进程只负责拉取、校验和维护本地状态。
