nyaKazuha/BlueArchiveToolkit
1
0
Fork 0
mirror of https://github.com/Yuyi-Oak/BlueArchiveToolkit.git synced 2026-09-18 07:24:55 +08:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity
Files
94483ff14dd1aa24d7046d9741472cef918b44bf
BlueArchiveToolkit/docs/guides/deployment.md
T

528 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 部署指南
## 架构概览
BlueArchive Toolkit 的部署文档分为当前可用模式和目标模式：
1. **本地开发模式**：当前 Rust `bat` 和 Go `bat-api` 不依赖 PostgreSQL/Redis；
本地资源状态使用文件和 SQLite。
2. **官方资源同步生产任务**：当前可用，运行 Rust `bat --watch` 或 RPC/daemon 模式。
3. **bat-api 资源 bootstrap / 分发服务**：当前可用，和 Rust `bat` 在同一服务器/容器环境运行，经 `bat.sock` RPC 获取当前 `resource_root`。
4. **可选数据库开发环境**：PostgreSQL/Redis 只服务于未来的 Go 服务层、完整 Web 协作后台和
Provider 扩展，不是当前 `bat` / `bat-api` 的生产运行依赖；当前 Translation Memory V1
使用 `<output>/translation-memory.sqlite`。
5. **完整单机/分布式部署**：尚未提供。完整游戏业务 API、数据库迁移和 Web 未实现前，不把它作为可执行部署方案。
---
## 模式 1：本地开发（当前推荐）
当前实现不要求启动 PostgreSQL 或 Redis。建议先运行 Rust/Go 自身的门禁：
```bash
cargo check --workspace --locked
make test-go-api
make build-go-api
make check-docs
```
只有在开发未来 Go 服务层或目标数据库适配时，才需要启动可选的本地数据库：
```bash
docker compose -f deployments/docker-compose.dev.yml --profile local-db up -d
```
本地数据库端口默认只绑定 `127.0.0.1`，不应改为 `0.0.0.0`。
---
## 模式 2：可选数据库开发环境（目标能力）
PostgreSQL 和 Redis 不是当前 `bat` / `bat-api` 的生产运行依赖。本模式只用于未来
服务层、Web 协作视图或 Provider 扩展的开发验证，不能作为当前
资源同步或资源分发的部署前置条件。
### 远程开发连接
远程开发默认使用私网地址、VPN 或 SSH tunnel。不要为开发方便把 PostgreSQL
`5432` 或 Redis `6379` 暴露到公网；尤其不得把 Redis 公网暴露作为推荐方案。
在远程主机上启动可选数据库后，优先通过 SSH tunnel 连接：
```bash
ssh -N \
-L 15432:127.0.0.1:5432 \
-L 16379:127.0.0.1:6379 \
user@db-host
```
本地开发进程只连接 tunnel 的回环端口：
```env
DB_HOST=127.0.0.1
DB_PORT=15432
REDIS_HOST=127.0.0.1
REDIS_PORT=16379
```
如果使用 VPN 或私网直连，应限制数据库服务仅监听明确的私网接口和允许的来源
网段，并继续使用认证与 TLS。不要添加面向全网的 `5432` / `6379` 防火墙放行规则。
远程主机上的可选 Compose 服务：
```bash
docker compose -f deployments/docker-compose.remote-db.yml up -d
docker compose -f deployments/docker-compose.remote-db.yml ps
```
该 Compose 配置默认仅在远程主机回环地址发布端口，远程访问应通过 SSH tunnel、
VPN 或受控私网，不通过公网端口直连。
---
## 模式 3：官方资源同步生产任务
当前可部署的生产同步任务是 Rust 官方资源同步 binary。`bat-api` 资源 bootstrap / 分发服务见模式 4；完整游戏业务 API 和 Web 尚未实现，不能按完整服务端产品部署。
### 构建 release binary
```bash
cargo build --release -p bat-infrastructure --bin bat
```
产物：
```text
target/release/bat
```
生产不直接从 Git 工作区运行 binary。推荐把每次发布放进独立 release 目录，再用稳定 symlink 暴露当前版本：
```text
/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/` 会保存：
- `current`：指向当前可读 release 的 symlink
- `versions/<id>/official-sync-snapshot.json`
- `versions/<id>/official-download-manifest.json`
- `versions/<id>/...` 下载得到的官方资源文件
- `.staging/<id>`：下载和校验中的临时 release
- `official-bootstrap-cache.json`
- `.official-sync.lock`
不要把输出目录设为：
- 已安装游戏客户端目录
- 官方启动器安装目录
- 开发机现有资源目录，例如 `/home/wanye/D/BlueArchive`
- Git 工作区目录
### 首次 dry-run
```bash
sudo -u bat /opt/bluearchive-toolkit/bin/bat \
--auto-discover \
--output /var/lib/bluearchive-toolkit/official \
--dry-run \
--no-progress
```
### 推荐模式：纯同步时 systemd 托管 `--watch`
只需要远程长期同步资源、暂不部署 `bat-api` 时，推荐让 systemd 直接托管前台 `--watch` 进程，而不是在 systemd 里再启动 `--daemon`。原因：
- systemd 能直接追踪主进程、退出码、重启次数和 stop 信号。
- 日志进入 journald，用 `journalctl` 管理，不依赖 `bat-daemon.log`。
- Rust 内部已经负责 1 小时间隔、北京时间固定强制刷新和失败快速重试，systemd 不需要 timer。
- `bat --daemon` 的 Unix socket RPC 适合 shell/container 场景，也适合给同环境运行的 `bat-api` 提供 release 发现；纯同步 systemd 场景下用 `systemctl`、`journalctl`、`bat verify/doctor` 运维即可。
安装 unit 和可选环境文件：
```bash
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
```
检查状态和日志：
```bash
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 \
--localized-output /var/lib/bluearchive-toolkit/localized \
--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`，默认汉化产物目录是 `./bat-localized`；生产 service 显式使用 `/var/lib/bluearchive-toolkit/official` 和 `/var/lib/bluearchive-toolkit/localized`，两者不能相同或互相嵌套。生产读取方应读取 `/var/lib/bluearchive-toolkit/official/current`；同步中的原版文件只会进入 `.staging/<id>`，校验完成后才发布为 `versions/<id>` 并切换 `current`。官方同步报告 `localized_release_status=not_localized` 表示汉化资源尚未发布；后续 Patch 发布才切换 `/var/lib/bluearchive-toolkit/localized/current`。
### 可选模式：CLI 自托管 `--daemon`
不使用 systemd 时，可以直接后台运行。生产中不要使用默认 `/tmp/bat-pid`，建议使用持久状态目录，这样 `bat-daemon.log` 和 `bat-events.jsonl` 不会随 reboot 或 tmp 清理丢失：
```bash
sudo -u bat /opt/bluearchive-toolkit/bin/bat \
--auto-discover \
--output /var/lib/bluearchive-toolkit/official \
--localized-output /var/lib/bluearchive-toolkit/localized \
--state-dir /var/lib/bluearchive-toolkit/daemon-state \
--daemon
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-events.jsonl` 和短生命周期的 `bat-control.lock`。`bat.sock` 是 Unix socket JSON-RPC 控制通道；`status`、`stop`、`restart`、`logs`、`reload`、默认形态的 `refresh` 和默认形态的 `repair` 会优先连接 live daemon。PID、状态和日志文件保留为快照、诊断和 socket 不可用时的兼容路径；`bat-events.jsonl` 是带轮转的结构化 JSONL 事件日志；`bat-status.json` 会暴露最后成功时间、下次检查时间、最后错误摘要和当前下载进度；`bat-control.lock` 串行化控制命令，并能在 stale/corrupt 时由下一次控制命令或 `clean-stable` 恢复。`restart` 会通过 Rust lifecycle controller 复用 CLI restart 路径替换后台进程；`reload` 默认不会重启进程，而是让 watch 循环重新自动发现并强制刷新：空闲睡眠时立即唤醒，正在同步时排队到当前轮结束后执行；需要替换启动参数或 binary 时用 `restart`。
不要同时运行 systemd `--watch` 和 standalone `--daemon` 指向同一个 `--output`。二者都会被资源锁和 live daemon 互斥保护，但生产运维上应保持单一 owner。
如果同一台服务器还要运行 `bat-api`，必须让 Rust `bat` 以能提供 `bat.sock` 的 RPC 形态运行，并让 `bat-api` 通过该 socket 获取当前 `resource_root`。这种部署见模式 4；不要把 `BAT_API_RESOURCE_ROOT` 当作生产主配置。
### 日志和状态路径
systemd 模式：
- 进程日志：`journalctl -u bluearchive-toolkit-official-sync.service`
- 当前可读 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`
- 解析缓存：`/var/lib/bluearchive-toolkit/official/current/official-parse-cache.json`
- 历史 release：`/var/lib/bluearchive-toolkit/official/versions/<id>`
- 同步 staging：`/var/lib/bluearchive-toolkit/official/.staging/<id>`
- 资源写锁：`/var/lib/bluearchive-toolkit/official/.official-sync.lock`
- 汉化 release（Patch 发布后）：`/var/lib/bluearchive-toolkit/localized/current`
- 运行期目录：`/run/bluearchive-toolkit/`
standalone `--daemon` 模式：
- 进程日志：`<state-dir>/bat-daemon.log`
- 结构化事件日志：`<state-dir>/bat-events.jsonl`
- RPC socket：`<state-dir>/bat.sock`
- PID 文件：`<state-dir>/bat.pid`
- daemon 状态：`<state-dir>/bat-status.json`
- 控制锁：`<state-dir>/bat-control.lock`
### 生产维护命令
```bash
sudo -u bat /opt/bluearchive-toolkit/bin/bat refresh --output /var/lib/bluearchive-toolkit/official --localized-output /var/lib/bluearchive-toolkit/localized
sudo -u bat /opt/bluearchive-toolkit/bin/bat refresh --force --output /var/lib/bluearchive-toolkit/official --localized-output /var/lib/bluearchive-toolkit/localized
sudo -u bat /opt/bluearchive-toolkit/bin/bat verify --output /var/lib/bluearchive-toolkit/official --localized-output /var/lib/bluearchive-toolkit/localized
sudo -u bat /opt/bluearchive-toolkit/bin/bat repair --output /var/lib/bluearchive-toolkit/official --localized-output /var/lib/bluearchive-toolkit/localized
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 唤醒或排队后台进程；默认形态的 `repair` 会通过 `resource.repair` RPC 入队本地 manifest 审计+修复任务并返回 `task_id`。带 `--output`、server-info、connection-group、app-version、platforms、snapshot、curl、unzip 或其它显式同步参数时，`refresh` / `repair` 会作为一次性前台命令运行，但不能写入 live daemon 正在管理的同一资源目录，否则会返回 locked。`verify` 发现远端变化、本地缺失或校验失败时返回非 0；`clean-stable` 只清理 `.part`、`.tmp`、失效或损坏的 PID/socket/锁，不删除正式资源。
### 升级
升级只替换 `/opt/bluearchive-toolkit/bin/bat` symlink，不直接覆盖旧 binary：
```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
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
```
升级后执行：
```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`，生产读取入口是 `/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-bootstrap-cache.json \
current/official-sync-snapshot.json \
current/official-download-manifest.json
```
如果业务层需要热更新、热重载或发布新资源，应该由上层服务在观察到 `--json` report 或 snapshot 变化后决定。Rust 同步进程只负责拉取、校验和维护本地状态。
---
## 模式 4：bat-api 资源 bootstrap / 分发服务
适用场景：真实 Rust `bat` 长期运行在生产主机，并且同一主机/容器环境内运行 Go `bat-api`，给客户端、补丁器或上层工具提供启动前资源入口和 CDN path 只读分发。
核心约束：
1. `bat-api` 与 Rust `bat` 同环境部署，至少要能访问同一个 Unix socket 和同一个已发布资源文件系统。
2. 当前资源目录由 `bat.sock` RPC 返回的 `resource_root` 决定；生产不要在 `bat-api` 配置里写死 `BAT_API_RESOURCE_ROOT`。
3. `BAT_API_RESOURCE_ROOT` 只用于本地 fixture、临时只读诊断或 RPC 不可用时的应急验证。
4. `bat.sock` 只在服务器本机使用，不通过公网暴露；对外只发布 HTTP `bat-api`，生产建议放在反向代理和 TLS 后面。
5. 本地开发环境不需要官方全量下载；使用 Go 单测、fixture release 和 `make bat-api-local-live-smoke`。该 smoke 在本地 `/tmp` 隔离目录启动真实 Rust daemon，不连接远程服务器。
### 构建和安装 bat-api
```bash
make build-go-api
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 \
bin/bat-api \
/opt/bluearchive-toolkit/releases/"${VERSION}"/bat-api
sudo ln -sfn \
/opt/bluearchive-toolkit/releases/"${VERSION}"/bat-api \
/opt/bluearchive-toolkit/bin/bat-api
/opt/bluearchive-toolkit/bin/bat-api --help
```
如果 Rust `bat` 和 Go `bat-api` 使用同一个 release 目录发布，也可以把二者放在同一个 `<version-or-git-sha>` 目录下，分别通过 `/opt/bluearchive-toolkit/bin/bat` 和 `/opt/bluearchive-toolkit/bin/bat-api` 暴露稳定 symlink。
### bat 侧前置条件
`bat-api` 依赖 live RPC，而不是直接读取 daemon 状态文件。部署 `bat-api` 前，部署所在生产主机上应已有 socket 形态的 Rust `bat`：
```bash
sudo -u bat /opt/bluearchive-toolkit/bin/bat \
--auto-discover \
--output /var/lib/bluearchive-toolkit/official \
--localized-output /var/lib/bluearchive-toolkit/localized \
--state-dir /var/lib/bluearchive-toolkit/daemon-state \
--daemon
sudo -u bat /opt/bluearchive-toolkit/bin/bat status \
--state-dir /var/lib/bluearchive-toolkit/daemon-state
```
确认 socket 存在：
```bash
sudo -u bat test -S /var/lib/bluearchive-toolkit/daemon-state/bat.sock
```
不要同时再运行一个 `--watch` service 指向 `/var/lib/bluearchive-toolkit/official`。如果当前服务器已经部署了 `bluearchive-toolkit-official-sync.service` 的纯同步 `--watch` 模式，需要先切换为 socket/RPC 形态，再启用 `bat-api`。
### 安装 bat-api systemd unit
```bash
sudo install -o root -g root -m 0644 \
deployments/systemd/bluearchive-toolkit-bat-api.service \
/etc/systemd/system/bluearchive-toolkit-bat-api.service
sudo install -o root -g root -m 0644 \
deployments/systemd/bat-api.env.example \
/etc/bluearchive-toolkit/bat-api.env
sudo systemctl daemon-reload
sudo systemctl enable --now bluearchive-toolkit-bat-api.service
```
默认配置只监听本机：
```env
BAT_API_LISTEN=127.0.0.1:18080
BAT_API_PUBLIC_BASE_URL=http://127.0.0.1:18080
BAT_API_SOCKET=/var/lib/bluearchive-toolkit/daemon-state/bat.sock
BAT_API_REFRESH_INTERVAL=1m
BAT_API_ACCESS_LOG=true
BAT_API_RATE_LIMIT_RPS=30
BAT_API_RATE_LIMIT_BURST=120
```
生产反向代理公开后，把 `BAT_API_PUBLIC_BASE_URL` 改成客户端实际访问的 HTTPS 根，例如：
```env
BAT_API_PUBLIC_BASE_URL=https://assets.example.com
```
面对玩家分发时还应通过 secret manager 或 systemd credential 注入：
```env
BAT_API_AUTH_TOKEN=<secret>
BAT_API_AUTH_QUERY_PARAM=bat_token
BAT_API_AUTH_EXEMPT_PATHS=/healthz,/readyz
BAT_API_MAX_RESOURCE_LIMIT=1000
```
反代必须强制 HTTPS，并在转发到 `bat-api` 前清洗客户端提交的 `X-Forwarded-For` / `X-Real-IP`。只有确认反代会覆盖这些 header 时，才设置：
```env
BAT_API_TRUST_PROXY_HEADERS=true
```
否则保持默认 `false`，`bat-api` 会按 TCP peer IP 做限流和日志归因。应用层访问日志只记录 path，不记录 query string，避免 query token 进入日志。动态 JSON 响应使用 `Cache-Control: no-store`；CDN 字节路径仍使用长期 immutable 缓存。
不要在生产 env 里设置 `BAT_API_RESOURCE_ROOT`。`bat-api` 会按 `BAT_API_REFRESH_INTERVAL` 周期通过 RPC 重新读取 `catalog.status` / `resource.manifest`，从而跟随 Rust `bat` 切换 `current -> versions/<id>`。
### 健康检查
```bash
systemctl status bluearchive-toolkit-bat-api.service
journalctl -u bluearchive-toolkit-bat-api.service -f
curl -fsS http://127.0.0.1:18080/healthz
curl -fsS http://127.0.0.1:18080/readyz
curl -fsS http://127.0.0.1:18080/v1/bootstrap
curl -fsS http://127.0.0.1:18080/v1/launcher/bootstrap
curl -fsS http://127.0.0.1:18080/api-launcher-jp.yo-star.com/api/launcher/game/config
curl -fsS http://127.0.0.1:18080/openapi.yaml
curl -fsS http://127.0.0.1:18080/admin/
```
`/healthz` 是 liveness，固定返回服务存活状态，并包含最近一次 RPC refresh 的开始时间、成功时间、耗时、warning 和错误摘要。`/readyz` 是 readiness，当前没有可分发 release 时返回 `503`。`rpc_available=true` 且 `ready=true` 表示 `bat-api` 已经通过 RPC 发现可分发 release；`ready=false` 时，先检查 `bat.sock`、Rust `bat status`、`resource_root` 是否存在，以及 `official-download-manifest.json` 中的文件是否仍在磁盘上。
`/v1/launcher/bootstrap` 和 `/api-launcher-jp.yo-star.com/api/launcher/...` 只用于 launcher 资源 metadata / GameMainConfig 引导兼容。它们从 Rust `bat` 的已发布 snapshot/RPC 派生响应，显式标记不是完整 package update manifest；生产排障时应确认这些响应中的 `scope=resource_bootstrap_only`、`resource_bootstrap_url`、server-info URL 和 client-patch base 是否指向当前 `BAT_API_PUBLIC_BASE_URL`。
### 本地开发限制
开发机不能本地全量运行 `bat` 时，不需要伪造生产资源目录。Go 侧改动用单测和 fixture 验证：
```bash
make test-go-api
make build-go-api
BAT_API_SKIP_ENV_FILE=1 go run ./cmd/bat-api \
--listen 127.0.0.1:18080 \
--public-base-url http://127.0.0.1:18080 \
--resource-root internal/api/testdata/release \
--refresh-interval 0
```
这条本地命令只验证 HTTP 形态、server-info 改写、CDN path、Range/缓存语义和管理接口；同机 live 联调使用 `make bat-api-local-live-smoke`，真实官方网络下载则使用独立的 `make official-smoke`。
---
## 模式 5：完整生产环境部署
完整游戏业务生产环境当前不可用。`bat-api` 资源 bootstrap/分发服务和 Rust
官方资源同步任务已经可以按模式 3/4 部署；数据库迁移、Web 管理后台、发布编排
以及完整游戏业务 API 尚未实现，因此不要按完整服务端产品部署本仓库。
---
## 可选数据库环境的备份与监控
以下内容只适用于未来服务层使用的可选 PostgreSQL/Redis 环境，不属于当前
`bat` / `bat-api` 生产部署步骤。
### 备份
备份应在数据库主机或受控私网内执行，也可以通过 SSH 在远程主机上运行容器内工具：
```bash
ssh user@db-host \
'docker exec bat-postgres pg_dump -U bat_user bluearchive_toolkit' \
> backup.sql
docker compose -f deployments/docker-compose.remote-db.yml --profile backup up -d
```
Redis 备份使用数据库主机或容器内的受控备份工具。不要在脚本或文档中使用带公网
主机名的 `redis-cli -h ... -p 6379` 连接，也不要把密码放进公开命令行参数或提交文件。
### 监控
```bash
ssh user@db-host 'docker compose -f deployments/docker-compose.remote-db.yml ps'
ssh user@db-host 'docker logs bat-postgres'
ssh user@db-host 'docker logs bat-redis'
```
### 故障排查
当前 `bat` / `bat-api` 无需数据库连接；资源同步故障应先检查 `bat.sock`、发布目录、
SQLite 索引和 Rust daemon 状态。未来服务层出现数据库连接问题时，按以下顺序检查：
1. 私网、VPN 或 SSH tunnel 是否可用；
2. 本地连接端口是否为 tunnel 映射或受控私网端口；
3. 数据库认证、TLS 和允许网段配置；
4. 数据库容器是否运行。
---
更多当前状态请查看 `CURRENT_STATUS.md`、`docs/reports/CURRENT_GAPS.md` 和本文件中的健康检查命令。
View Git Blame Copy Permalink