bttoxin-pipeline/DOCKER_DEPLOYMENT.md

Docker Deployment Guide

部署方式对比

方案 1：单容器 Nginx 部署（测试/开发）

适用于：快速测试、开发环境、单机部署

docker compose -f docker/compose/docker-compose.simple.yml up -d

• 单容器包含：Nginx + FastAPI + 静态文件
• 端口：80
• 访问：http://localhost

方案 2：Traefik 多容器部署（生产/集群）

适用于：生产环境、多服务、需要自动 HTTPS、与 Traefik 主项目集成

# 1. 首次运行需要初始化 acme.json
touch docker/traefik/acme.json
chmod 600 docker/traefik/acme.json

# 2. 启动服务
docker compose -f docker/compose/docker-compose.traefik.yml up -d

• 多容器分离：Traefik (代理) + Backend (API) + Frontend (静态文件)
• 端口：80, 443, 8080 (Traefik Dashboard)
• Traefik Dashboard: http://localhost:8080
• Swagger UI: http://localhost/api/docs
• ReDoc: http://localhost/api/redoc

架构对比

Nginx 方案 (docker/compose/docker-compose.simple.yml)

用户 → Nginx (80) → FastAPI (8000)
                → 静态文件

优点：

• 简单、单容器
• 快速启动
• 资源占用少

缺点：

• 手动配置 nginx
• 扩展性差
• 无自动 HTTPS

Traefik 方案 (docker/compose/docker-compose.traefik.yml)

用户 → Traefik (80/443) → Backend Container (8000)
                       → Frontend Container (80)

优点：

• 自动服务发现
• 内置 Let's Encrypt HTTPS
• 负载均衡
• 实时监控面板
• 易于扩展到其他服务

缺点：

• 多容器、稍复杂
• 资源占用略高

配置文件说明

目录结构

docker/
├── compose/                  # Docker Compose 配置文件
│   ├── docker-compose.yml              # 主配置文件
│   ├── docker-compose.simple.yml       # 简化配置（推荐）
│   ├── docker-compose.traefik.yml      # Traefik 配置
│   └── docker-compose.test.yml         # 测试配置
├── dockerfiles/              # Dockerfile 文件
│   ├── Dockerfile                      # 主 Dockerfile
│   └── Dockerfile.traefik              # Traefik Dockerfile
├── scripts/                  # 相关脚本
│   ├── entrypoint.sh                   # 容器启动脚本
│   ├── entrypoint.backend.sh           # 后端启动脚本
│   └── switch-to-traefik.sh            # 切换到 Traefik 模式
├── nginx/                    # Nginx 配置
│   └── default.conf                   # Nginx 默认配置
├── traefik/                  # Traefik 配置
│   ├── traefik.yml                     # Traefik 主配置
│   ├── dynamic/                        # 动态配置目录（中间件等）
│   └── acme.json                       # SSL 证书存储（首次运行自动创建）
└── .dockerignore             # Docker 忽略文件

环境变量

变量	默认值	说明
JOBS_DIR	./jobs	任务结果存储目录
DEBUG	false	调试模式（启用 Swagger UI）

Swagger UI 访问

开启 Swagger UI

设置环境变量 DEBUG=true:

environment:
  - DEBUG=true

访问地址

• Swagger UI: http://localhost/api/docs
• ReDoc: http://localhost/api/redoc
• OpenAPI Schema: http://localhost/api/openapi.json

Traefik Dashboard

开发环境访问：http://localhost:8080

生产环境安全配置：

在 docker/traefik/traefik.yml 中禁用不安全的 dashboard：

api:
  dashboard: true
  insecure: false  # 改为 false

然后通过 Basic Auth 中间件保护：

# docker/traefik/dynamic/dashboard-auth.yml
http:
  middlewares:
    dashboard-auth:
      basicAuth:
        users:
          - "admin:$apr1$hash..."

迁移到主项目

如果你有一个使用 Traefik 的主项目：

1. 复制 backend 和 frontend 服务配置到主项目的 docker-compose.yml
2. 调整网络：使用主项目的 Traefik 网络
3. 共享 traefik 配置：或使用主项目的配置
4. 移除独立的 traefik 容器（使用主项目的）

示例：

# 在主项目 docker-compose.yml 中添加
services:
  bttoxin-backend:
    image: ghcr.io/prefix-dev/pixi:latest
    # ... 其他配置
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.bttoxin-backend.rule=PathPrefix(`/api/bttoxin`)"
      - "traefik.http.routers.bttoxin-backend.entrypoints=websecure"
      # ... 其他 label
    networks:
      - your-main-network

networks:
  your-main-network:
    external: true

故障排查

Swagger UI 无法加载 OpenAPI schema

症状： 访问 /api/docs 显示 "Failed to load API definition"

原因： OpenAPI schema 路径不匹配反代配置

解决： 确保 openapi_url 包含 /api 前缀：

# web/backend/main.py
app = FastAPI(
    # ...
    openapi_url="/api/openapi.json",  # 关键！
)

Traefik 无法发现容器

检查：

1. 容器必须有 traefik.enable=true label
2. 容器必须与 Traefik 在同一网络
3. 检查 Traefik 日志：docker logs traefik-bttoxin

健康检查失败

Nginx 方案： 检查 nginx/default.conf 中的 proxy_pass 配置

Traefik 方案： 检查 labels 中的 healthcheck 配置

性能优化

Nginx 优化

在 docker/nginx/default.conf 中添加：

# 启用缓存
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=api_cache:10m;

location /api/ {
    proxy_cache api_cache;
    proxy_cache_valid 200 5m;
}

Traefik 优化

在服务 labels 中添加连接复用：

labels:
  - "traefik.http.services.backend.loadbalancer.passhostheader=true"

监控和日志

查看 Traefik 日志

docker logs -f traefik-bttoxin

查看后端日志

docker logs -f bttoxin-backend

Traefik Dashboard

实时查看：

• 请求路由
• 服务健康状态
• 中间件配置
• 证书状态

生产环境建议

1. 启用 HTTPS：配置 Let's Encrypt 或使用自有证书
2. 限制 Dashboard 访问：使用 Basic Auth 或禁用
3. 设置资源限制：在 docker-compose.yml 中添加
4. 配置日志轮转：避免磁盘占满
5. 备份 acme.json：SSL 证书存储
6. 监控服务健康：使用 Prometheus + Grafana