chore: establish development baseline

deployments/.env.example

@@ -0,0 +1,121 @@
+# BlueArchive Toolkit 环境变量配置
+# 复制为 .env 并填写实际值
+
+# ============================================================================
+# 数据库配置
+# ============================================================================
+
+# 数据库类型选择：local (本地 Docker) 或 remote (远程服务器)
+DB_MODE=remote
+
+# PostgreSQL 配置
+# 本地模式：使用 localhost:5432
+# 远程模式：填写远程服务器的公网 IP 和端口
+DB_HOST=your.remote.server.com  # 远程服务器地址（或 localhost 用于本地）
+DB_PORT=5432
+DB_USER=bat_user
+DB_PASSWORD=your_secure_password_here
+DB_NAME=bluearchive_toolkit
+
+# 数据库连接池配置
+DB_MAX_CONNECTIONS=50
+DB_MIN_CONNECTIONS=10
+DB_CONNECTION_TIMEOUT=30  # 秒
+
+# SSL 模式（远程连接推荐使用 require 或 verify-full）
+# 可选值：disable, allow, prefer, require, verify-ca, verify-full
+DB_SSL_MODE=prefer
+
+# ============================================================================
+# Redis 配置
+# ============================================================================
+
+# Redis 配置
+# 本地模式：使用 localhost:6379
+# 远程模式：填写远程服务器的公网 IP 和端口
+REDIS_HOST=your.remote.server.com  # 远程服务器地址（或 localhost 用于本地）
+REDIS_PORT=6379
+REDIS_PASSWORD=your_redis_password_here
+REDIS_DB=0
+
+# Redis 连接池配置
+REDIS_MAX_CONNECTIONS=100
+REDIS_CONNECTION_TIMEOUT=5  # 秒
+
+# ============================================================================
+# API Server 配置
+# ============================================================================
+
+API_PORT=8080
+API_HOST=0.0.0.0
+
+# JWT 配置
+JWT_SECRET=your_jwt_secret_key_here_change_in_production
+JWT_EXPIRY=24h  # Token 过期时间
+
+# ============================================================================
+# 日志配置
+# ============================================================================
+
+# 日志级别：debug, info, warn, error
+LOG_LEVEL=info
+
+# 日志格式：json 或 text
+LOG_FORMAT=json
+
+# ============================================================================
+# CAS 存储配置
+# ============================================================================
+
+# CAS 存储路径（本地文件系统）
+CAS_STORAGE_PATH=/var/lib/bat/cas
+
+# CAS 垃圾回收配置
+CAS_GC_ENABLED=true
+CAS_GC_INTERVAL=24h  # 垃圾回收间隔
+
+# ============================================================================
+# 资源同步配置
+# ============================================================================
+
+# 下载并发数
+SYNC_WORKERS=4
+
+# 重试次数
+SYNC_RETRY_COUNT=3
+
+# 限速（KB/s，0 表示不限速）
+SYNC_RATE_LIMIT=0
+
+# 下载超时（秒）
+SYNC_TIMEOUT=300
+
+# ============================================================================
+# 翻译服务配置
+# ============================================================================
+
+# DeepL API
+DEEPL_API_KEY=your_deepl_api_key_here
+DEEPL_API_URL=https://api-free.deepl.com/v2/translate
+
+# OpenAI API
+OPENAI_API_KEY=your_openai_api_key_here
+OPENAI_API_URL=https://api.openai.com/v1
+OPENAI_MODEL=gpt-4
+
+# Anthropic API
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+ANTHROPIC_API_URL=https://api.anthropic.com
+ANTHROPIC_MODEL=claude-3-5-sonnet-20241022
+
+# ============================================================================
+# 远程数据库服务器部署配置（用于在裸金属服务器上部署数据库）
+# ============================================================================
+
+# 如果你需要在远程服务器上部署数据库，使用以下配置
+# 在远程服务器上运行：
+# docker compose -f deployments/docker-compose.remote-db.yml up -d
+
+REMOTE_DB_POSTGRES_USER=bat_user
+REMOTE_DB_POSTGRES_PASSWORD=your_very_secure_password_here
+REMOTE_DB_REDIS_PASSWORD=your_very_secure_redis_password_here

deployments/backup-script.sh

@@ -0,0 +1,37 @@
+#!/bin/sh
+# PostgreSQL 自动备份脚本
+
+set -e
+
+BACKUP_DIR="/backups"
+DATE=$(date +%Y%m%d_%H%M%S)
+BACKUP_FILE="$BACKUP_DIR/backup_$DATE.sql.gz"
+
+echo "开始备份 PostgreSQL 数据库：$DATE"
+
+# 创建备份目录
+mkdir -p $BACKUP_DIR
+
+# 执行备份
+PGPASSWORD=$POSTGRES_PASSWORD pg_dump \
+  -h $POSTGRES_HOST \
+  -U $POSTGRES_USER \
+  -d $POSTGRES_DB \
+  --no-owner \
+  --no-acl \
+  | gzip > $BACKUP_FILE
+
+# 检查备份是否成功
+if [ -f "$BACKUP_FILE" ]; then
+  BACKUP_SIZE=$(du -h "$BACKUP_FILE" | cut -f1)
+  echo "备份完成：$BACKUP_FILE (大小: $BACKUP_SIZE)"
+else
+  echo "备份失败！"
+  exit 1
+fi
+
+# 删除 30 天前的备份
+find $BACKUP_DIR -name "backup_*.sql.gz" -mtime +30 -delete
+echo "已清理 30 天前的备份文件"
+
+echo "备份任务完成"

deployments/docker-compose.dev.yml

@@ -0,0 +1,86 @@
+# 开发环境 Docker Compose 配置
+# 数据库服务为可选，通过 profile 控制
+#
+# 使用方式：
+# 1. 使用本地数据库：docker compose -f deployments/docker-compose.dev.yml --profile local-db up -d
+# 2. 使用远程数据库：不启动此文件，直接在 .env 中配置远程数据库连接信息
+
+version: '3.9'
+
+services:
+  # PostgreSQL 数据库（可选 - 仅用于本地开发）
+  postgres:
+    image: postgres:16-alpine
+    container_name: bat-postgres-dev
+    profiles: ["local-db"]  # 只有指定 --profile local-db 才启动
+    environment:
+      POSTGRES_DB: bluearchive_toolkit
+      POSTGRES_USER: bat_user
+      POSTGRES_PASSWORD: bat_dev_password
+      POSTGRES_INITDB_ARGS: "-E UTF8 --locale=C"
+    ports:
+      - "0.0.0.0:5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+      - ./postgres-init:/docker-entrypoint-initdb.d
+      - ./pg_hba.conf:/var/lib/postgresql/data/pg_hba.conf
+    command: postgres -c hba_file=/var/lib/postgresql/data/pg_hba.conf
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U bat_user -d bluearchive_toolkit"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - bat-dev
+    restart: unless-stopped
+
+  # Redis 缓存（可选 - 仅用于本地开发）
+  redis:
+    image: redis:7-alpine
+    container_name: bat-redis-dev
+    profiles: ["local-db"]  # 只有指定 --profile local-db 才启动
+    command: redis-server /usr/local/etc/redis/redis.conf
+    ports:
+      - "0.0.0.0:6379:6379"
+    volumes:
+      - redis_data:/data
+      - ./redis.conf:/usr/local/etc/redis/redis.conf
+    healthcheck:
+      test: ["CMD", "redis-cli", "--raw", "incr", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - bat-dev
+    restart: unless-stopped
+
+  # pgAdmin (可选的数据库管理工具，仅用于本地数据库)
+  pgadmin:
+    image: dpage/pgadmin4:latest
+    container_name: bat-pgadmin-dev
+    profiles: ["local-db", "tools"]
+    environment:
+      PGADMIN_DEFAULT_EMAIL: admin@bat.local
+      PGADMIN_DEFAULT_PASSWORD: admin
+      PGADMIN_CONFIG_SERVER_MODE: 'False'
+    ports:
+      - "5050:80"
+    volumes:
+      - pgadmin_data:/var/lib/pgadmin
+    depends_on:
+      - postgres
+    networks:
+      - bat-dev
+    restart: unless-stopped
+
+volumes:
+  postgres_data:
+    driver: local
+  redis_data:
+    driver: local
+  pgadmin_data:
+    driver: local
+
+networks:
+  bat-dev:
+    driver: bridge

deployments/docker-compose.remote-db.yml

@@ -0,0 +1,92 @@
+# 远程数据库服务器 Docker Compose 配置
+# 用于在裸金属服务器上部署 PostgreSQL 和 Redis
+#
+# 部署步骤：
+# 1. 将此文件和相关配置上传到远程服务器
+# 2. 复制 .env.example 为 .env 并配置密码
+# 3. 运行：docker compose -f docker-compose.remote-db.yml up -d
+# 4. 确保防火墙开放 5432 和 6379 端口
+
+version: '3.9'
+
+services:
+  # PostgreSQL 数据库
+  postgres:
+    image: postgres:16-alpine
+    container_name: bat-postgres
+    environment:
+      POSTGRES_DB: bluearchive_toolkit
+      POSTGRES_USER: ${REMOTE_DB_POSTGRES_USER}
+      POSTGRES_PASSWORD: ${REMOTE_DB_POSTGRES_PASSWORD}
+      POSTGRES_INITDB_ARGS: "-E UTF8 --locale=C"
+    ports:
+      - "0.0.0.0:5432:5432"  # 监听所有网络接口
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+      - ./postgres-init:/docker-entrypoint-initdb.d
+      - ./pg_hba.conf:/var/lib/postgresql/data/pg_hba.conf
+    command: postgres -c hba_file=/var/lib/postgresql/data/pg_hba.conf -c max_connections=200 -c shared_buffers=512MB
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${REMOTE_DB_POSTGRES_USER} -d bluearchive_toolkit"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    restart: always
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "100m"
+        max-file: "10"
+
+  # Redis 缓存
+  redis:
+    image: redis:7-alpine
+    container_name: bat-redis
+    command: redis-server /usr/local/etc/redis/redis.conf
+    ports:
+      - "0.0.0.0:6379:6379"  # 监听所有网络接口
+    volumes:
+      - redis_data:/data
+      - ./redis-remote.conf:/usr/local/etc/redis/redis.conf
+    healthcheck:
+      test: ["CMD", "redis-cli", "-a", "${REMOTE_DB_REDIS_PASSWORD}", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    restart: always
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "100m"
+        max-file: "10"
+
+  # 数据库备份服务（可选）
+  backup:
+    image: postgres:16-alpine
+    container_name: bat-backup
+    profiles: ["backup"]
+    environment:
+      POSTGRES_HOST: postgres
+      POSTGRES_DB: bluearchive_toolkit
+      POSTGRES_USER: ${REMOTE_DB_POSTGRES_USER}
+      POSTGRES_PASSWORD: ${REMOTE_DB_POSTGRES_PASSWORD}
+    volumes:
+      - ./backups:/backups
+      - ./backup-script.sh:/backup-script.sh
+    entrypoint: /bin/sh -c "while true; do sh /backup-script.sh; sleep 86400; done"
+    depends_on:
+      - postgres
+    restart: unless-stopped
+
+volumes:
+  postgres_data:
+    driver: local
+  redis_data:
+    driver: local
+
+# 安全提示：
+# 1. 使用强密码
+# 2. 配置防火墙规则，只允许信任的 IP 访问
+# 3. 启用 SSL/TLS 连接
+# 4. 定期备份数据
+# 5. 监控资源使用和访问日志

deployments/docker-compose.yml

@@ -0,0 +1,77 @@
+# 生产环境 Docker Compose 配置
+# 包含完整的应用服务
+
+version: '3.9'
+
+services:
+  # PostgreSQL 数据库
+  postgres:
+    image: postgres:16-alpine
+    container_name: bat-postgres
+    environment:
+      POSTGRES_DB: bluearchive_toolkit
+      POSTGRES_USER: ${DB_USER:-bat_user}
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+      POSTGRES_INITDB_ARGS: "-E UTF8 --locale=C"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-bat_user} -d bluearchive_toolkit"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - bat-network
+    restart: unless-stopped
+
+  # Redis 缓存
+  redis:
+    image: redis:7-alpine
+    container_name: bat-redis
+    command: redis-server --appendonly yes --requirepass ${REDIS_PASSWORD}
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "--raw", "incr", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - bat-network
+    restart: unless-stopped
+
+  # API Server (待实现)
+  # api:
+  #   build:
+  #     context: .
+  #     dockerfile: deployments/Dockerfile.api
+  #   container_name: bat-api
+  #   ports:
+  #     - "${API_PORT:-8080}:8080"
+  #   environment:
+  #     DB_HOST: postgres
+  #     DB_PORT: 5432
+  #     DB_NAME: bluearchive_toolkit
+  #     DB_USER: ${DB_USER}
+  #     DB_PASSWORD: ${DB_PASSWORD}
+  #     REDIS_HOST: redis
+  #     REDIS_PORT: 6379
+  #     REDIS_PASSWORD: ${REDIS_PASSWORD}
+  #   depends_on:
+  #     postgres:
+  #       condition: service_healthy
+  #     redis:
+  #       condition: service_healthy
+  #   networks:
+  #     - bat-network
+  #   restart: unless-stopped
+
+volumes:
+  postgres_data:
+    driver: local
+  redis_data:
+    driver: local
+
+networks:
+  bat-network:
+    driver: bridge

deployments/pg_hba.conf

@@ -0,0 +1,21 @@
+# PostgreSQL Client Authentication Configuration File
+# 允许远程连接
+
+# TYPE  DATABASE        USER            ADDRESS                 METHOD
+
+# 本地连接
+local   all             all                                     trust
+
+# IPv4 本地连接
+host    all             all             127.0.0.1/32            scram-sha-256
+
+# IPv6 本地连接
+host    all             all             ::1/128                 scram-sha-256
+
+# 允许来自任何 IP 的连接（开发环境）
+# 生产环境应该限制为具体 IP 或网段
+host    all             all             0.0.0.0/0               scram-sha-256
+host    all             all             ::/0                    scram-sha-256
+
+# Docker 网络
+host    all             all             172.16.0.0/12           scram-sha-256

deployments/postgres-init/01-init.sql

@@ -0,0 +1,37 @@
+-- BlueArchive Toolkit 数据库初始化脚本
+-- 此脚本在 PostgreSQL 容器首次启动时自动执行
+
+-- 创建扩展
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+CREATE EXTENSION IF NOT EXISTS "pg_trgm";  -- 用于模糊搜索
+
+-- 创建 schema
+CREATE SCHEMA IF NOT EXISTS bat;
+
+-- 设置默认 schema
+SET search_path TO bat, public;
+
+-- 创建基础表（详细表结构将在 migrations 中定义）
+
+-- 版本信息表
+CREATE TABLE IF NOT EXISTS bat.schema_version (
+    version VARCHAR(50) PRIMARY KEY,
+    applied_at TIMESTAMP DEFAULT NOW(),
+    description TEXT
+);
+
+-- 插入初始版本
+INSERT INTO bat.schema_version (version, description)
+VALUES ('0.1.0', '初始化数据库结构')
+ON CONFLICT (version) DO NOTHING;
+
+-- 授权
+GRANT ALL PRIVILEGES ON SCHEMA bat TO bat_user;
+GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA bat TO bat_user;
+GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA bat TO bat_user;
+
+-- 完成
+DO $$
+BEGIN
+    RAISE NOTICE '数据库初始化完成！';
+END $$;

deployments/postgres.conf

@@ -0,0 +1,41 @@
+# PostgreSQL 自定义配置
+# 支持远程连接和性能优化
+
+# 监听所有网络接口
+listen_addresses = '*'
+
+# 最大连接数
+max_connections = 100
+
+# 共享内存缓冲区
+shared_buffers = 256MB
+
+# 工作内存
+work_mem = 16MB
+
+# 维护工作内存
+maintenance_work_mem = 64MB
+
+# 有效缓存大小
+effective_cache_size = 1GB
+
+# 日志设置
+logging_collector = on
+log_directory = 'pg_log'
+log_filename = 'postgresql-%Y-%m-%d_%H%M%S.log'
+log_statement = 'all'
+log_duration = on
+log_line_prefix = '%t [%p]: [%l-1] user=%u,db=%d,app=%a,client=%h '
+
+# 慢查询日志
+log_min_duration_statement = 1000  # 记录超过 1 秒的查询
+
+# 连接日志
+log_connections = on
+log_disconnections = on
+
+# 时区
+timezone = 'UTC'
+
+# 字符集
+client_encoding = 'UTF8'

deployments/redis-remote.conf

@@ -0,0 +1,63 @@
+# Redis 远程服务器配置
+# 用于生产环境的 Redis 配置
+
+# 绑定所有网络接口（允许远程连接）
+bind 0.0.0.0
+
+# 保护模式关闭（允许远程连接，但必须配置密码）
+protected-mode yes
+
+# 端口
+port 6379
+
+# 密码认证（必须配置！）
+requirepass ${REMOTE_DB_REDIS_PASSWORD}
+
+# 持久化配置
+appendonly yes
+appendfilename "appendonly.aof"
+
+# AOF 同步策略
+appendfsync everysec
+
+# RDB 快照
+save 900 1
+save 300 10
+save 60 10000
+
+# 数据库文件名
+dbfilename dump.rdb
+
+# 工作目录
+dir /data
+
+# 最大内存（根据服务器配置调整）
+maxmemory 2gb
+maxmemory-policy allkeys-lru
+
+# 日志级别
+loglevel notice
+logfile ""
+
+# 慢查询日志
+slowlog-log-slower-than 10000
+slowlog-max-len 128
+
+# 客户端连接配置
+timeout 300
+tcp-keepalive 300
+maxclients 10000
+
+# 安全配置
+# 禁用危险命令
+rename-command FLUSHDB ""
+rename-command FLUSHALL ""
+rename-command CONFIG ""
+
+# 开启 RDB 和 AOF 压缩
+rdbcompression yes
+rdbchecksum yes
+
+# AOF 重写配置
+auto-aof-rewrite-percentage 100
+auto-aof-rewrite-min-size 64mb

deployments/redis.conf

@@ -0,0 +1,43 @@
+# Redis 自定义配置
+# 支持远程连接和持久化
+
+# 绑定所有网络接口
+bind 0.0.0.0
+
+# 保护模式关闭（允许远程连接）
+protected-mode no
+
+# 端口
+port 6379
+
+# 密码认证
+requirepass bat_dev_redis
+
+# 持久化配置
+appendonly yes
+appendfilename "appendonly.aof"
+
+# AOF 同步策略
+appendfsync everysec
+
+# RDB 快照
+save 900 1
+save 300 10
+save 60 10000
+
+# 数据库文件名
+dbfilename dump.rdb
+
+# 工作目录
+dir /data
+
+# 最大内存
+maxmemory 512mb
+maxmemory-policy allkeys-lru
+
+# 日志级别
+loglevel notice
+
+# 慢查询日志
+slowlog-log-slower-than 10000
+slowlog-max-len 128