ljwx-shiti/docs/DEPLOYMENT.md

部署指南

开发环境部署

前置要求

• Docker 20.10+
• Docker Compose 2.0+
• Python 3.11+
• PostgreSQL 16 (可选，可使用 Docker)
• Redis 7 (可选，可使用 Docker)

步骤

1. 克隆仓库

git clone <repository-url>
cd ljwx-shiti

2. 配置环境变量

cp .env.example .env

编辑 .env 文件：

# 数据库
DATABASE_URL=postgresql+asyncpg://wrongbook:wrongbook@localhost:45432/wrongbook

# Redis
REDIS_URL=redis://localhost:46379/0

# MinIO
MINIO_ENDPOINT=localhost:49000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=wrongbook

# JWT
SECRET_KEY=your-secret-key-here
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7

# Claude API (可选)
ANTHROPIC_API_KEY=your-api-key-here

# RemoveHandwriting API (可选)
REMOVE_HANDWRITING_API_KEY=your-api-key-here

3. 启动基础服务

docker-compose up -d postgres redis minio

4. 运行数据库迁移

cd backend
pip install -r requirements.txt
alembic upgrade head

5. 启动后端服务

# 开发模式
uvicorn app.main:app --reload

# 或使用 Docker
docker-compose up -d backend celery

6. 访问服务

• API: http://localhost:8000
• API 文档: http://localhost:8000/docs
• MinIO 控制台: http://localhost:49001

生产环境部署

使用 Docker Compose

1. 准备生产环境配置

cp .env.example .env.production

编辑 .env.production，设置生产环境配置：

ENV=production
SECRET_KEY=<strong-random-key>
DATABASE_URL=postgresql+asyncpg://wrongbook:<password>@postgres:5432/wrongbook
# ... 其他配置

2. 创建生产环境 docker-compose 文件

# docker-compose.prod.yml
version: '3.8'

services:
  backend:
    build:
      context: .
      dockerfile: backend/Dockerfile
    ports:
      - "8000:8000"
    env_file:
      - .env.production
    depends_on:
      - postgres
      - redis
    restart: always

  celery:
    build:
      context: .
      dockerfile: backend/Dockerfile
    env_file:
      - .env.production
    depends_on:
      - postgres
      - redis
    command: celery -A app.tasks.celery_app worker --loglevel=info
    restart: always

  postgres:
    image: postgres:16-alpine
    env_file:
      - .env.production
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: always

  redis:
    image: redis:7-alpine
    restart: always

  minio:
    image: minio/minio
    command: server /data --console-address ":9001"
    env_file:
      - .env.production
    volumes:
      - miniodata:/data
    restart: always

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./infra/nginx.conf:/etc/nginx/nginx.conf
      - ./infra/ssl:/etc/nginx/ssl
    depends_on:
      - backend
    restart: always

volumes:
  pgdata:
  miniodata:

3. 启动服务

docker-compose -f docker-compose.prod.yml up -d

Nginx 配置

创建 infra/nginx.conf：

events {
    worker_connections 1024;
}

http {
    upstream backend {
        server backend:8000;
    }

    server {
        listen 80;
        server_name your-domain.com;

        # 重定向到 HTTPS
        return 301 https://$server_name$request_uri;
    }

    server {
        listen 443 ssl http2;
        server_name your-domain.com;

        ssl_certificate /etc/nginx/ssl/cert.pem;
        ssl_certificate_key /etc/nginx/ssl/key.pem;

        client_max_body_size 10M;

        location / {
            proxy_pass http://backend;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }

        location /ws {
            proxy_pass http://backend;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            proxy_set_header Host $host;
        }
    }
}

数据库备份

1. 手动备份

docker exec -t postgres pg_dump -U wrongbook wrongbook > backup.sql

2. 自动备份脚本

创建 infra/backup.sh：

#!/bin/bash

BACKUP_DIR="/backups"
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="$BACKUP_DIR/wrongbook_$DATE.sql"

docker exec -t postgres pg_dump -U wrongbook wrongbook > $BACKUP_FILE

# 压缩备份
gzip $BACKUP_FILE

# 删除 7 天前的备份
find $BACKUP_DIR -name "wrongbook_*.sql.gz" -mtime +7 -delete

echo "Backup completed: $BACKUP_FILE.gz"

3. 设置定时任务

# 每天凌晨 2 点备份
0 2 * * * /path/to/infra/backup.sh

监控

健康检查

# 检查后端服务
curl http://localhost:8000/health

# 检查数据库
docker exec postgres pg_isready -U wrongbook

# 检查 Redis
docker exec redis redis-cli ping

日志查看

# 查看后端日志
docker-compose logs -f backend

# 查看 Celery 日志
docker-compose logs -f celery

# 查看所有服务日志
docker-compose logs -f

性能优化

1. 数据库连接池

在 .env 中配置：

DB_POOL_SIZE=20
DB_MAX_OVERFLOW=10

2. Redis 缓存

启用查询缓存：

ENABLE_CACHE=true
CACHE_TTL=300

3. Celery 并发

celery -A app.tasks.celery_app worker --concurrency=4

安全建议

1. 使用强密码和密钥
2. 启用 HTTPS
3. 配置防火墙规则
4. 定期更新依赖
5. 启用日志审计
6. 限制 API 访问频率
7. 定期备份数据

故障排查

服务无法启动

# 查看日志
docker-compose logs backend

# 检查端口占用
netstat -tulpn | grep 8000

# 重启服务
docker-compose restart backend

数据库连接失败

# 检查数据库状态
docker-compose ps postgres

# 测试连接
docker exec -it postgres psql -U wrongbook -d wrongbook

Celery 任务不执行

# 检查 Celery 状态
docker-compose logs celery

# 检查 Redis 连接
docker exec redis redis-cli ping

# 重启 Celery
docker-compose restart celery

扩展部署

水平扩展

# docker-compose.scale.yml
services:
  backend:
    deploy:
      replicas: 3

  celery:
    deploy:
      replicas: 2

启动：

docker-compose -f docker-compose.prod.yml -f docker-compose.scale.yml up -d

负载均衡

使用 Nginx 配置多个后端实例：

upstream backend {
    server backend1:8000;
    server backend2:8000;
    server backend3:8000;
}

更新部署

1. 拉取最新代码

git pull origin main

2. 重新构建镜像

docker-compose build

3. 运行数据库迁移

docker-compose run backend alembic upgrade head

4. 重启服务

docker-compose up -d

回滚

1. 恢复代码

git checkout <previous-commit>

2. 回滚数据库

docker-compose run backend alembic downgrade -1

3. 重启服务

docker-compose restart