# 部署指南 ## 架构概览 BlueArchive Toolkit 的部署文档分为当前可用模式和目标模式： 1. **本地开发模式**：代码在本地，连接本地或远程数据库。 2. **官方资源同步生产任务**：当前可用，运行 Rust `bat --watch`。 3. **完整单机/分布式部署**：尚未提供。API Server、数据库迁移和 Web 未实现前，不把它作为可执行部署方案。 --- ## 模式 1：本地开发 + 远程数据库 适用场景：本地开发，数据库部署在有公网 IP 的远程服务器 ### 步骤 #### 1. 在远程服务器上部署数据库 ```bash # SSH 登录到服务器 ssh user@your.server.com # 创建部署目录 mkdir -p ~/bat/deployments cd ~/bat/deployments # 上传配置文件（在本地执行） scp -r deployments/* user@your.server.com:~/bat/deployments/ # 配置环境变量 cp .env.example .env nano .env # 设置强密码 # 启动数据库 docker compose -f docker-compose.remote-db.yml up -d # 查看状态 docker compose -f docker-compose.remote-db.yml ps ``` #### 2. 配置防火墙 ```bash # 开放 PostgreSQL 端口 sudo ufw allow 5432/tcp # 开放 Redis 端口 sudo ufw allow 6379/tcp # 查看状态 sudo ufw status ``` #### 3. 本地连接配置 在本地项目根目录创建 `.env`： ```env DB_HOST=your.server.ip.address DB_PORT=5432 DB_USER=bat_user DB_PASSWORD=your_secure_password DB_NAME=bluearchive_toolkit REDIS_HOST=your.server.ip.address REDIS_PORT=6379 REDIS_PASSWORD=your_redis_password ``` #### 4. 测试连接 ```bash # 测试 PostgreSQL 连接 psql -h your.server.ip.address -U bat_user -d bluearchive_toolkit # 测试 Redis 连接 redis-cli -h your.server.ip.address -p 6379 -a your_redis_password ping ``` --- ## 模式 2：本地数据库（开发） 适用场景：完全本地开发，不需要远程服务器 ```bash # 启动本地数据库 docker compose -f deployments/docker-compose.dev.yml --profile local-db up -d # 配置 .env DB_HOST=localhost DB_PORT=5432 REDIS_HOST=localhost REDIS_PORT=6379 ``` --- ## 模式 3：官方资源同步生产任务 当前可部署的生产任务是 Rust 官方资源同步 binary。API Server 和 Web 尚未实现，不能按完整服务端产品部署。 ### 构建 ```bash cargo build --release -p bat-infrastructure --bin bat ``` 产物： ```text target/release/bat ``` ### 目录约定 推荐生产状态目录： ```text /var/lib/bluearchive-toolkit/official/ ``` 该目录会保存： - `official-sync-snapshot.json` - `official-bootstrap-cache.json` - `official-download-manifest.json` - `.official-sync.lock` - 下载得到的官方资源文件 不要把输出目录设为： - 已安装游戏客户端目录 - 官方启动器安装目录 - 开发机现有资源目录，例如 `/home/wanye/D/BlueArchive` - Git 工作区目录 ### 一次性检查 ```bash /opt/bluearchive-toolkit/bin/bat \ --auto-discover \ --output /var/lib/bluearchive-toolkit/official \ --dry-run ``` ### 常驻自动更新 ```bash /opt/bluearchive-toolkit/bin/bat \ --auto-discover \ --output /var/lib/bluearchive-toolkit/official \ --watch ``` `--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-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`。 生产维护时可以用以下单次命令： ```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` 会作为一次性前台同步运行，但不能写入 live daemon 正在管理的同一资源目录，否则会返回 locked。`verify` 发现远端变化、本地缺失或校验失败时返回非 0；`repair` 会走官方同步链路重新下载必要文件，但同样不能和 live daemon 并行写同一资源目录；`clean-stable` 只清理 `.part`、`.tmp`、失效或损坏的 PID/socket/锁，不删除正式资源。 ### systemd service 示例 systemd 只负责进程守护，不负责定时逻辑： ```ini [Unit] Description=BlueArchiveToolkit official resource sync After=network-online.target Wants=network-online.target [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 [Install] WantedBy=multi-user.target ``` 如果业务层需要热更新、热重载或发布新资源，应该由上层服务在观察到 `--json` report 或 snapshot 变化后决定。Rust 同步进程只负责拉取、校验和维护本地状态。 --- ## 模式 4：完整生产环境部署 当前不可用。API Server、数据库迁移、Web 管理后台和发布编排尚未实现；不要按完整服务端产品部署本仓库。 --- ## 数据库备份 ### 手动备份 ```bash # PostgreSQL pg_dump -h your.server.com -U bat_user -d bluearchive_toolkit > backup.sql # Redis redis-cli -h your.server.com -p 6379 -a password BGSAVE ``` ### 自动备份 启动备份服务： ```bash docker compose -f deployments/docker-compose.remote-db.yml --profile backup up -d ``` 备份文件位置：`deployments/backups/` --- ## 监控 ### 查看日志 ```bash # 数据库日志 docker logs bat-postgres # Redis 日志 docker logs bat-redis ``` ### 健康检查 ```bash # 检查容器状态 docker compose -f deployments/docker-compose.remote-db.yml ps # 检查 PostgreSQL docker exec bat-postgres pg_isready -U bat_user # 检查 Redis docker exec bat-redis redis-cli ping ``` --- ## 故障排查 ### 无法连接数据库 1. 检查防火墙是否开放端口 2. 检查 `pg_hba.conf` 配置 3. 检查密码是否正确 4. 检查数据库是否启动 ### 性能问题 1. 查看数据库连接数 2. 检查慢查询日志 3. 优化索引 4. 调整数据库参数 --- 更多当前状态请查看 `CURRENT_STATUS.md`、`docs/reports/CURRENT_GAPS.md` 和本文件中的健康检查命令。