mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-09-18 08:14:55 +08:00
docs: update current document status
This commit is contained in:
+72
-121
@@ -4,98 +4,78 @@
|
||||
|
||||
BlueArchive Toolkit 的部署文档分为当前可用模式和目标模式：
|
||||
|
||||
1. **本地开发模式**：代码在本地，连接本地或远程数据库。
|
||||
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. **完整单机/分布式部署**：尚未提供。完整游戏业务 API、数据库迁移和 Web 未实现前，不把它作为可执行部署方案。
|
||||
4. **可选数据库开发环境**：PostgreSQL/Redis 只服务于未来的 Go 服务层、Translation
|
||||
Memory、Glossary 和完整 Provider 扩展，不是当前 `bat` / `bat-api` 的生产运行依赖。
|
||||
5. **完整单机/分布式部署**：尚未提供。完整游戏业务 API、数据库迁移和 Web 未实现前，不把它作为可执行部署方案。
|
||||
|
||||
---
|
||||
|
||||
## 模式 1：本地开发 + 远程数据库
|
||||
## 模式 1：本地开发（当前推荐）
|
||||
|
||||
适用场景：本地开发，数据库部署在有公网 IP 的远程服务器
|
||||
|
||||
### 步骤
|
||||
|
||||
#### 1. 在远程服务器上部署数据库
|
||||
当前实现不要求启动 PostgreSQL 或 Redis。建议先运行 Rust/Go 自身的门禁：
|
||||
|
||||
```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
|
||||
cargo check --workspace --locked
|
||||
make test-go-api
|
||||
make build-go-api
|
||||
make check-docs
|
||||
```
|
||||
|
||||
#### 2. 配置防火墙
|
||||
只有在开发未来 Go 服务层或目标数据库适配时，才需要启动可选的本地数据库：
|
||||
|
||||
```bash
|
||||
# 开放 PostgreSQL 端口
|
||||
sudo ufw allow 5432/tcp
|
||||
|
||||
# 开放 Redis 端口
|
||||
sudo ufw allow 6379/tcp
|
||||
|
||||
# 查看状态
|
||||
sudo ufw status
|
||||
docker compose -f deployments/docker-compose.dev.yml --profile local-db up -d
|
||||
```
|
||||
|
||||
#### 3. 本地连接配置
|
||||
本地数据库端口默认只绑定 `127.0.0.1`，不应改为 `0.0.0.0`。
|
||||
|
||||
在本地项目根目录创建 `.env`：
|
||||
---
|
||||
|
||||
## 模式 2：可选数据库开发环境（目标能力）
|
||||
|
||||
PostgreSQL 和 Redis 不是当前 `bat` / `bat-api` 的生产运行依赖。本模式只用于未来
|
||||
服务层、Translation Memory、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=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
|
||||
DB_HOST=127.0.0.1
|
||||
DB_PORT=15432
|
||||
REDIS_HOST=127.0.0.1
|
||||
REDIS_PORT=16379
|
||||
```
|
||||
|
||||
#### 4. 测试连接
|
||||
如果使用 VPN 或私网直连，应限制数据库服务仅监听明确的私网接口和允许的来源
|
||||
网段，并继续使用认证与 TLS。不要添加面向全网的 `5432` / `6379` 防火墙放行规则。
|
||||
|
||||
远程主机上的可选 Compose 服务：
|
||||
|
||||
```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
|
||||
docker compose -f deployments/docker-compose.remote-db.yml up -d
|
||||
docker compose -f deployments/docker-compose.remote-db.yml ps
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 模式 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
|
||||
```
|
||||
该 Compose 配置默认仅在远程主机回环地址发布端口，远程访问应通过 SSH tunnel、
|
||||
VPN 或受控私网，不通过公网端口直连。
|
||||
|
||||
---
|
||||
|
||||
@@ -504,71 +484,42 @@ BAT_API_SKIP_ENV_FILE=1 go run ./cmd/bat-api \
|
||||
|
||||
---
|
||||
|
||||
## 数据库备份
|
||||
## 可选数据库环境的备份与监控
|
||||
|
||||
### 手动备份
|
||||
以下内容只适用于未来服务层使用的可选 PostgreSQL/Redis 环境，不属于当前
|
||||
`bat` / `bat-api` 生产部署步骤。
|
||||
|
||||
### 备份
|
||||
|
||||
备份应在数据库主机或受控私网内执行，也可以通过 SSH 在远程主机上运行容器内工具：
|
||||
|
||||
```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
|
||||
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
|
||||
```
|
||||
|
||||
备份文件位置：`deployments/backups/`
|
||||
Redis 备份使用数据库主机或容器内的受控备份工具。不要在脚本或文档中使用带公网
|
||||
主机名的 `redis-cli -h ... -p 6379` 连接，也不要把密码放进公开命令行参数或提交文件。
|
||||
|
||||
---
|
||||
|
||||
## 监控
|
||||
|
||||
### 查看日志
|
||||
### 监控
|
||||
|
||||
```bash
|
||||
# 数据库日志
|
||||
docker logs bat-postgres
|
||||
|
||||
# Redis 日志
|
||||
docker logs bat-redis
|
||||
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'
|
||||
```
|
||||
|
||||
### 健康检查
|
||||
### 故障排查
|
||||
|
||||
```bash
|
||||
# 检查容器状态
|
||||
docker compose -f deployments/docker-compose.remote-db.yml ps
|
||||
当前 `bat` / `bat-api` 无需数据库连接；资源同步故障应先检查 `bat.sock`、发布目录、
|
||||
SQLite 索引和 Rust daemon 状态。未来服务层出现数据库连接问题时，按以下顺序检查：
|
||||
|
||||
# 检查 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. 调整数据库参数
|
||||
1. 私网、VPN 或 SSH tunnel 是否可用；
|
||||
2. 本地连接端口是否为 tunnel 映射或受控私网端口；
|
||||
3. 数据库认证、TLS 和允许网段配置；
|
||||
4. 数据库容器是否运行。
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user