BlueArchiveToolkit/docs/guides/deployment.md

部署指南

架构概览

BlueArchive Toolkit 支持多种部署模式：

1. 本地开发模式：代码在本地，连接远程数据库
2. 单机部署：所有组件运行在一台服务器
3. 分布式部署：多实例 API Server + 独立数据库服务器

---

模式 1：本地开发 + 远程数据库

适用场景：本地开发，数据库部署在有公网 IP 的远程服务器

步骤

1. 在远程服务器上部署数据库

# 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. 配置防火墙

# 开放 PostgreSQL 端口
sudo ufw allow 5432/tcp

# 开放 Redis 端口
sudo ufw allow 6379/tcp

# 查看状态
sudo ufw status

3. 本地连接配置

在本地项目根目录创建 .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. 测试连接

# 测试 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：本地数据库（开发）

适用场景：完全本地开发，不需要远程服务器

# 启动本地数据库
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：生产环境部署

待补充（Phase 6 实现 API Server 后）

---

数据库备份

手动备份

# 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

自动备份

启动备份服务：

docker compose -f deployments/docker-compose.remote-db.yml --profile backup up -d

备份文件位置：deployments/backups/

---

监控

查看日志

# 数据库日志
docker logs bat-postgres

# Redis 日志
docker logs bat-redis

健康检查

# 检查容器状态
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. 调整数据库参数

---

更多问题请查看 故障排查指南（待创建）