mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-07-22 05:16:44 +08:00
docs: update bat runtime documentation
This commit is contained in:
+41
-12
@@ -5,8 +5,8 @@
|
||||
BlueArchive Toolkit 的部署文档分为当前可用模式和目标模式：
|
||||
|
||||
1. **本地开发模式**：代码在本地，连接本地或远程数据库。
|
||||
2. **官方资源同步生产任务**：当前可用，运行 Rust `bat-official-sync --watch`。
|
||||
3. **完整单机/分布式部署**：目标模式，等待 API Server、数据库迁移和 Web 实现后补齐。
|
||||
2. **官方资源同步生产任务**：当前可用，运行 Rust `bat --watch`。
|
||||
3. **完整单机/分布式部署**：尚未提供。API Server、数据库迁移和 Web 未实现前，不把它作为可执行部署方案。
|
||||
|
||||
---
|
||||
|
||||
@@ -105,13 +105,13 @@ REDIS_PORT=6379
|
||||
### 构建
|
||||
|
||||
```bash
|
||||
cargo build --release -p bat-infrastructure --bin bat-official-sync
|
||||
cargo build --release -p bat-infrastructure --bin bat
|
||||
```
|
||||
|
||||
产物：
|
||||
|
||||
```text
|
||||
target/release/bat-official-sync
|
||||
target/release/bat
|
||||
```
|
||||
|
||||
### 目录约定
|
||||
@@ -140,9 +140,8 @@ target/release/bat-official-sync
|
||||
### 一次性检查
|
||||
|
||||
```bash
|
||||
/opt/bluearchive-toolkit/bin/bat-official-sync \
|
||||
/opt/bluearchive-toolkit/bin/bat \
|
||||
--auto-discover \
|
||||
--platforms Windows,Android \
|
||||
--output /var/lib/bluearchive-toolkit/official \
|
||||
--dry-run
|
||||
```
|
||||
@@ -150,14 +149,44 @@ target/release/bat-official-sync
|
||||
### 常驻自动更新
|
||||
|
||||
```bash
|
||||
/opt/bluearchive-toolkit/bin/bat-official-sync \
|
||||
/opt/bluearchive-toolkit/bin/bat \
|
||||
--auto-discover \
|
||||
--platforms Windows,Android \
|
||||
--output /var/lib/bluearchive-toolkit/official \
|
||||
--watch
|
||||
```
|
||||
|
||||
`--watch` 是 Rust 内部持久检查模式，正常情况下默认每 1 小时执行一次检查，并且每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 会强制执行一次自动刷新。固定时间刷新会中断普通 interval 的 sleep，该轮注入 `force=true`；如果失败，会按失败重试周期继续重试。远端和本地一致时默认静默；有远端变化或本地文件损坏时自动下载或 repair，并输出 JSON report。下载、发现或校验失败时默认 60 秒后重试，可显式加 `--error-retry 60s` 或 `--error-retry-seconds 60` 调整。默认 ASCII banner 和进度日志写到 stderr，成功 JSON report 写到 stdout；如果由上层服务严格解析 stderr/stdout，可加 `--no-progress`，只想关闭横幅可加 `--no-banner`。
|
||||
`--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 \
|
||||
--auto-discover \
|
||||
--output /var/lib/bluearchive-toolkit/official \
|
||||
--state-dir /run/bluearchive-toolkit \
|
||||
--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
|
||||
```
|
||||
|
||||
`--daemon` 会在 `--state-dir` 下创建 `bat.sock`、`bat.pid`、`bat-status.json` 和 `bat-daemon.log`。`bat.sock` 是 Unix socket JSON-RPC 控制通道；`status`、`stop`、`logs`、`reload` 和默认形态的 `refresh` 会优先连接 live daemon。PID、状态和日志文件保留为快照、诊断和 socket 不可用时的兼容路径。`reload` 默认不会重启进程，而是让 watch 循环重新自动发现并强制刷新：空闲睡眠时立即唤醒，正在同步时排队到当前轮结束后执行；需要替换启动参数或 binary 时用 `restart`。
|
||||
|
||||
生产维护时可以用以下单次命令：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
如果后台 daemon 正在运行，并且 `refresh` 没有显式指定另一套同步参数，`refresh` / `refresh --force` 会通过 RPC 唤醒或排队后台进程；带 `--output`、server-info、connection-group、app-version、platforms、snapshot、curl 或 unzip 等显式参数时，`refresh` 会作为一次性前台同步运行。`verify` 发现远端变化、本地缺失或校验失败时返回非 0；`repair` 会走官方同步链路重新下载必要文件；`clean-stable` 只清理 `.part`、`.tmp`、失效 PID、失效 socket 和失效锁，不删除正式资源。
|
||||
|
||||
### systemd service 示例
|
||||
|
||||
@@ -173,7 +202,7 @@ Wants=network-online.target
|
||||
Type=simple
|
||||
User=bat
|
||||
Group=bat
|
||||
ExecStart=/opt/bluearchive-toolkit/bin/bat-official-sync --auto-discover --platforms Windows,Android --output /var/lib/bluearchive-toolkit/official --watch --error-retry 60s
|
||||
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
|
||||
@@ -183,13 +212,13 @@ NoNewPrivileges=true
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
如果业务层需要热更新、热重载或发布新资源，应该由上层服务在观察到 JSON report 或 snapshot 变化后决定。Rust 同步进程只负责拉取、校验和维护本地状态。
|
||||
如果业务层需要热更新、热重载或发布新资源，应该由上层服务在观察到 `--json` report 或 snapshot 变化后决定。Rust 同步进程只负责拉取、校验和维护本地状态。
|
||||
|
||||
---
|
||||
|
||||
## 模式 4：完整生产环境部署
|
||||
|
||||
待补充（API Server、数据库迁移和 Web 实现后）
|
||||
当前不可用。API Server、数据库迁移、Web 管理后台和发布编排尚未实现；不要按完整服务端产品部署本仓库。
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user