# 部署指南

## 架构概览

BlueArchive Toolkit 的部署文档分为当前可用模式和目标模式：

1. **本地开发模式**：代码在本地，连接本地或远程数据库。
2. **官方资源同步生产任务**：当前可用，运行 Rust `bat-official-sync --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-official-sync
```

产物：

```text
target/release/bat-official-sync
```

### 目录约定

推荐生产状态目录：

```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-official-sync \
  --auto-discover \
  --platforms Windows,Android \
  --output /var/lib/bluearchive-toolkit/official \
  --dry-run
```

### 常驻自动更新

```bash
/opt/bluearchive-toolkit/bin/bat-official-sync \
  --auto-discover \
  --platforms Windows,Android \
  --output /var/lib/bluearchive-toolkit/official \
  --watch
```

`--watch` 是 Rust 内部持久检查模式，正常情况下默认每 1 小时执行一次检查。远端和本地一致时默认静默；有远端变化或本地文件损坏时自动下载或 repair，并输出 JSON report。下载、发现或校验失败时默认 60 秒后重试，可显式加 `--error-retry 60s` 或 `--error-retry-seconds 60` 调整。

### 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-official-sync --auto-discover --platforms Windows,Android --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` 和本文件中的健康检查命令。