bttoxin-pipeline/DOCKER_DEPLOYMENT.md

# Docker Deployment Guide

## 部署方式对比

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

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

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

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

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

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

```bash
# 1. 首次运行需要初始化 acme.json (如果启用 HTTPS)
touch docker/traefik/acme.json
chmod 600 docker/traefik/acme.json

# 2. 启动服务 (自动构建镜像)
docker compose -f docker/compose/docker-compose.traefik.yml up -d --build
```

- **架构组件**：
  - **Traefik**: 反向代理、负载均衡、自动 HTTPS
  - **Backend**: FastAPI 应用 (API + 静态文件服务)
  - **Postgres**: 任务元数据和状态存储 (docker.m.daocloud.io 镜像)
  - **Redis**: 任务队列消息中间件 (docker.m.daocloud.io 镜像)
- **端口**：80, 443, 8080 (Traefik Dashboard)
- **访问地址**：
  - Web UI: https://bttiaw.hzau.edu.cn (配置 Hosts 或 DNS)
  - Traefik Dashboard: http://localhost:8080
  - API Health: http://localhost:8000/health (内部)

## 架构对比

### 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)
                       → Postgres (5432)
                       → Redis (6379)
```

**优点：**
- 完整微服务架构
- 数据持久化 (Postgres/Redis)
- 异步任务处理支持 (Celery ready)
- 自动服务发现与 HTTPS
- 使用国内镜像源 (DaoCloud) 优化构建速度

**缺点：**
- 资源占用较高 (需 1GB+ 内存)

## 配置文件说明

### 目录结构

```
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`:

```yaml
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：

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

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

```yaml
# 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 容器**（使用主项目的）

示例：

```yaml
# 在主项目 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:
      - frontend

networks:
  frontend:
    external: true
```

## 故障排查

### Swagger UI 无法加载 OpenAPI schema

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

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

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

```python
# 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` 中添加：

```nginx
# 启用缓存
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 中添加连接复用：

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

## 监控和日志

### 查看 Traefik 日志

```bash
docker logs -f traefik-bttoxin
```

### 查看后端日志

```bash
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