Docker 部署最佳实践

本文将分享 WovenMind 在 Docker 部署过程中的经验和最佳实践。

架构设计

WovenMind 采用微服务架构，包含以下服务：

┌─────────────────────────────────────────────┐
│           Nginx (反向代理)                   │
│           端口: 80/443                       │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│        Frontend (Vue 3 + Nginx)             │
│        端口: 80                              │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│        Backend (FastAPI + Python)           │
│        端口: 8000 (可扩展多副本)             │
└─────────────────────────────────────────────┘
                    ↓
┌──────────────────┬──────────────────────────┐
│  PostgreSQL      │      Redis               │
│  + pgvector      │      (缓存)              │
│  端口: 5432      │      端口: 6379          │
└──────────────────┴──────────────────────────┘

Docker Compose 配置

开发环境

version: '3.8'

services:
  postgres:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: wovenmind
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    ports:
      - "6379:6379"

  backend:
    build: .
    environment:
      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/wovenmind
      REDIS_URL: redis://redis:6379/0
    depends_on:
      - postgres
      - redis
    ports:
      - "8000:8000"

  frontend:
    build: ./frontend
    ports:
      - "80:80"
    depends_on:
      - backend

volumes:
  postgres_data:
  redis_data:

生产环境优化

生产环境配置需要考虑：

1. 资源限制

services:
  backend:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 1G

2. 健康检查

services:
  backend:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

3. 多副本部署

services:
  backend:
    deploy:
      replicas: 2
      update_config:
        parallelism: 1
        delay: 10s

多阶段构建优化

后端 Dockerfile

# 构建阶段
FROM python:3.13-slim as builder

WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN pip install uv && uv sync --frozen

# 运行阶段
FROM python:3.13-slim

WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY app ./app

ENV PATH="/app/.venv/bin:$PATH"
CMD ["python", "main.py"]

前端 Dockerfile

# 构建阶段
FROM node:22-alpine as builder

WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# 运行阶段
FROM nginx:alpine

COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

数据持久化

卷管理

volumes:
  postgres_data:
    driver: local
  redis_data:
    driver: local

备份策略

# 自动备份脚本
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
docker exec wovenmind-postgres-1 pg_dump -U postgres wovenmind > backup_${DATE}.sql

网络配置

内部网络

networks:
  backend_network:
    driver: bridge
    internal: true
  frontend_network:
    driver: bridge

服务隔离

services:
  postgres:
    networks:
      - backend_network
  backend:
    networks:
      - backend_network
      - frontend_network
  frontend:
    networks:
      - frontend_network

监控和日志

日志配置

services:
  backend:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

监控集成

可以集成 Prometheus 和 Grafana 进行监控：

services:
  prometheus:
    image: prom/prometheus
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - "9090:9090"

安全最佳实践

1. 使用非 root 用户
2. 最小化镜像大小
3. 定期更新基础镜像
4. 扫描镜像漏洞
5. 使用 secrets 管理敏感信息

故障排查

常见问题

1. 容器启动失败
   • 检查日志：docker-compose logs backend
   • 检查配置：环境变量、端口冲突
2. 网络连接问题
   • 检查网络配置
   • 验证服务间连接
3. 性能问题
   • 监控资源使用
   • 优化配置参数

Docker 部署为 WovenMind 提供了灵活、可扩展的运行环境。通过遵循这些最佳实践，可以确保应用的稳定运行和高效管理。