docs: define production sync deployment

Fixes #15

CHANGELOG.md

@@ -18,6 +18,7 @@
 - 新增 Rust 官方同步 binary，当前正式入口为 `bat`，支持 one-shot、`--watch`、默认 1 小时间隔、人类可读默认输出和 `--json` 结构化 report
 - 官方同步正式入口统一为 `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 和锁文件恢复逻辑
+- 新增官方资源同步生产部署模板：release binary symlink 路径、systemd unit、运行用户、日志位置、升级和回滚流程
 - 新增官方资源下载校验：官方 URL 拒绝、`.part` 续传、重试、本地 size+BLAKE3、官方 seed `.hash` 校验
 - 新增 Addressables 当前真实形态 fixture/golden 测试
 - 新增 SQLite Resource Repository 和粗粒度 FFI JSON 接口

CURRENT_STATUS.md

@@ -241,9 +241,9 @@ 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 service、容器或 Go 进程可以负责守护 `bat --watch`，也可以用 `bat --daemon` 启动后台模式；`--daemon` 的管理命令优先走 `/tmp/bat-pid/bat.sock` Unix socket JSON-RPC；定时检查逻辑已经在 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`，日志通过 `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` 会强制执行一次自动刷新。
 
-详细运行说明见 `docs/guides/official-resource-test-pull.md`。
+详细运行说明见 `docs/guides/deployment.md` 和 `docs/guides/official-resource-test-pull.md`。
 
 ---
 

DOCS_INDEX.md

@@ -24,6 +24,7 @@
 - `docs/api/README.md`：API 设计入口。
 - `docs/guides/development.md`：开发指南。
 - `docs/guides/deployment.md`：部署指南。
+- `deployments/systemd/`：官方资源同步生产 systemd unit 和环境文件示例。
 - `docs/guides/official-resource-test-pull.md`：官方资源拉取与自动更新用户指南。
 - `docs/reports/current-stage-prepush.md`：当前阶段说明与推送前核查记录。
 - `docs/reports/current-status-handoff.md`：给下一次对话使用的当前进度交接说明。

PROJECT_PLAN.md

@@ -387,7 +387,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 5. 继续扩展 Addressables parser 的真实 catalog 变体覆盖和错误诊断。
 6. 开始 AssetBundle UnityFS header/block/directory 解析。
 7. 为 CLI 和 CAS 增加 `doctor cas` 诊断入口。
-8. 为 `bat --watch` / `bat --daemon` 持续补充发布型构建、systemd service 示例和运维检查清单；后台 live control plane 已改为 Unix socket JSON-RPC。
+8. 为 `bat --watch` / `bat --daemon` 持续补充发布型构建、systemd service 示例和运维检查清单；后台 live control plane 已改为 Unix socket JSON-RPC；基础生产部署模板、日志路径、权限用户、升级/回滚流程已补齐。
 
 ---
 

deployments/systemd/bluearchive-toolkit-official-sync.service

@@ -0,0 +1,39 @@
+[Unit]
+Description=BlueArchiveToolkit official resource sync
+Documentation=https://github.com/Yuyi-Oak/BlueArchiveToolkit
+Wants=network-online.target
+After=network-online.target
+
+[Service]
+Type=simple
+User=bat
+Group=bat
+WorkingDirectory=/var/lib/bluearchive-toolkit
+Environment=BAT_OUTPUT_ROOT=/var/lib/bluearchive-toolkit/official
+Environment=BAT_INTERVAL=1h
+Environment=BAT_ERROR_RETRY=60s
+EnvironmentFile=-/etc/bluearchive-toolkit/official-sync.env
+ExecStart=/opt/bluearchive-toolkit/bin/bat --auto-discover --output ${BAT_OUTPUT_ROOT} --watch --interval ${BAT_INTERVAL} --error-retry ${BAT_ERROR_RETRY} --no-banner
+Restart=on-failure
+RestartSec=30
+TimeoutStopSec=60
+KillSignal=SIGTERM
+StandardOutput=journal
+StandardError=journal
+StateDirectory=bluearchive-toolkit
+StateDirectoryMode=0750
+RuntimeDirectory=bluearchive-toolkit
+RuntimeDirectoryMode=0750
+LogsDirectory=bluearchive-toolkit
+LogsDirectoryMode=0750
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectHome=true
+ProtectSystem=strict
+ReadWritePaths=/var/lib/bluearchive-toolkit /run/bluearchive-toolkit /var/log/bluearchive-toolkit
+RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
+LockPersonality=true
+MemoryDenyWriteExecute=true
+
+[Install]
+WantedBy=multi-user.target

deployments/systemd/official-sync.env.example

@@ -0,0 +1,11 @@
+# Optional overrides for bluearchive-toolkit-official-sync.service.
+#
+# Install as:
+#   sudo install -o root -g root -m 0644 deployments/systemd/official-sync.env.example /etc/bluearchive-toolkit/official-sync.env
+#
+# Paths are intentionally independent from any official launcher or game client
+# install directory. Do not point BAT_OUTPUT_ROOT at an existing game directory.
+
+BAT_OUTPUT_ROOT=/var/lib/bluearchive-toolkit/official
+BAT_INTERVAL=1h
+BAT_ERROR_RETRY=60s

docs/guides/deployment.md

@@ -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 \
+sudo install -o root -g root -m 0644 \
-  --auto-discover \
+  deployments/systemd/bluearchive-toolkit-official-sync.service \
-  --output /var/lib/bluearchive-toolkit/official \
+  /etc/systemd/system/bluearchive-toolkit-official-sync.service
-  --watch
+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
+sudo -u bat /opt/bluearchive-toolkit/bin/bat status --state-dir /var/lib/bluearchive-toolkit/daemon-state
-/opt/bluearchive-toolkit/bin/bat logs --state-dir /run/bluearchive-toolkit --tail 200
+sudo -u bat /opt/bluearchive-toolkit/bin/bat logs --state-dir /var/lib/bluearchive-toolkit/daemon-state --tail 200
-/opt/bluearchive-toolkit/bin/bat restart --state-dir /run/bluearchive-toolkit
+sudo -u bat /opt/bluearchive-toolkit/bin/bat restart --state-dir /var/lib/bluearchive-toolkit/daemon-state
-/opt/bluearchive-toolkit/bin/bat reload --state-dir /run/bluearchive-toolkit
+sudo -u bat /opt/bluearchive-toolkit/bin/bat reload --state-dir /var/lib/bluearchive-toolkit/daemon-state
-/opt/bluearchive-toolkit/bin/bat stop --state-dir /run/bluearchive-toolkit
+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
+sudo -u bat /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
+sudo -u bat /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
+sudo -u bat /opt/bluearchive-toolkit/bin/bat verify --output /var/lib/bluearchive-toolkit/official
-/opt/bluearchive-toolkit/bin/bat repair --output /var/lib/bluearchive-toolkit/official
+sudo -u bat /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
+sudo -u bat /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 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
+```bash
-[Unit]
+NEW_VERSION="<new-version-or-git-sha>"
-Description=BlueArchiveToolkit official resource sync
+cargo build --release -p bat-infrastructure --bin bat
-After=network-online.target
+sudo install -d -o root -g root -m 0755 \
-Wants=network-online.target
+  /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]
+sudo systemctl stop bluearchive-toolkit-official-sync.service
-Type=simple
+sudo ln -sfn \
-User=bat
+  /opt/bluearchive-toolkit/releases/"${NEW_VERSION}"/bat \
-Group=bat
+  /opt/bluearchive-toolkit/bin/bat
-ExecStart=/opt/bluearchive-toolkit/bin/bat --auto-discover --output /var/lib/bluearchive-toolkit/official --watch --error-retry 60s
+sudo systemctl start bluearchive-toolkit-official-sync.service
-Restart=on-failure
+systemctl status bluearchive-toolkit-official-sync.service
-RestartSec=30
+journalctl -u bluearchive-toolkit-official-sync.service -n 100 --no-pager
-StateDirectory=bluearchive-toolkit
+```
-NoNewPrivileges=true
 
-[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 同步进程只负责拉取、校验和维护本地状态。