BlueArchiveToolkit/docs/guides/deployment.md

# 部署指南

## 架构概览

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 服务层、Glossary 和完整
   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` 的生产运行依赖。本模式只用于未来
服务层、Glossary 或 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` 和本文件中的健康检查命令。