Docker Compose 部署 Python

Docker Compose 是部署 Python 项目的理想工具，它可以通过一个简单的 YAML 文件定义和运行多容器应用。下面我将详细介绍如何使用 Docker Compose 部署 Python 项目，包括基础配置、开发与生产环境优化以及常见问题解决方案。

1. 项目准备与基础配置

1.1 项目结构准备

一个典型的 Python 项目结构如下：

my-python-app/
├── src/
│   └── app.py         # 应用入口文件
├── requirements.txt   # 项目依赖
├── Dockerfile         # 构建镜像配置
└── docker-compose.yml # 服务编排配置

1.2 创建基础 Python 应用

在src/app.py中添加一个简单的 Flask 应用示例：

from flask import Flask
app = Flask(__name__)

@app.route('/')
def hello():
    return "Python in Docker with Compose!"

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

在requirements.txt中列出项目依赖：

Flask==2.0.1

2. Docker 相关配置

2.1 创建 Dockerfile

在项目根目录创建Dockerfile，建议使用多阶段构建优化镜像大小：

# 构建阶段
FROM python:3.9-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --user -r requirements.txt

# 生产阶段
FROM python:3.9-slim
WORKDIR /app
COPY --from=builder /root/.local /root/.local
COPY . .
ENV PATH=/root/.local/bin:$PATH
EXPOSE 5000
CMD ["python", "src/app.py"]

2.2 创建 docker-compose.yml

在项目根目录创建docker-compose.yml文件：

version: "3.8"
services:
  web:
    build: .
    container_name: my-python-app
    ports:
      - "5000:5000"
    environment:
      - FLASK_ENV=development
      - TZ=Asia/Shanghai
    volumes:
      - ./src:/app/src # 开发时代码同步
      - /app/__pycache__ # 避免覆盖容器内的缓存
    restart: unless-stopped

3. 启动与验证

3.1 启动容器

运行以下命令构建并启动容器：

docker-compose up --build -d

3.2 验证运行

查看日志确认应用是否正常启动：

docker-compose logs -f

访问http://localhost:5000应该能看到"Python in Docker with Compose!"的响应。

4. 环境配置优化

4.1 开发环境配置

对于开发环境，可以启用热更新和调试支持：

services:
  web:
    # ...其他配置
    volumes:
      - ./:/app # 挂载整个项目目录
      - /app/__pycache__
    environment:
      - FLASK_ENV=development
      - FLASK_DEBUG=1
    ports:
      - "5000:5000"
      - "5678:5678" # 调试端口

4.2 生产环境配置

创建docker-compose.prod.yml用于生产环境：

version: "3.8"
services:
  web:
    build:
      context: .
      dockerfile: Dockerfile.prod
    ports:
      - "80:5000"
    environment:
      - FLASK_ENV=production
    restart: always
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 512M

对应的Dockerfile.prod:

FROM python:3.9-alpine
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 5000
CMD ["gunicorn", "--bind", "0.0.0.0:5000", "src.app:app"]

5. 高级配置选项

5.1 添加数据库服务

在docker-compose.yml中添加 PostgreSQL 服务：

services:
  # ...web配置

  db:
    image: postgres:15
    environment:
      POSTGRES_USER: myuser
      POSTGRES_PASSWORD: mypassword
      POSTGRES_DB: mydb
    volumes:
      - postgres-data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    networks:
      - app-network

volumes:
  postgres-data:

networks:
  app-network:
    driver: bridge

5.2 使用 PDM 管理依赖

对于使用 PDM 的项目，可以这样配置 Dockerfile：

ARG PYTHON_BASE=3.11
FROM python:$PYTHON_BASE

ENV PYTHONUNBUFFERED=1
ENV PDM_CHECK_UPDATE=false

RUN pip config set global.index-url https://mirrors.cloud.tencent.com/pypi/simple/ && \
    pip install -U pdm && \
    pdm config pypi.url "https://mirrors.cloud.tencent.com/pypi/simple/"

COPY pyproject.toml pdm.lock ./
RUN pdm install --check --prod --no-editable

COPY . .
ENV PATH="/project/.venv/bin:$PATH"

5.3 多服务组合部署

完整示例包含前端、后端和数据库：

version: "3.8"
services:
  frontend:
    build: ./frontend
    ports:
      - "80:80"
    depends_on:
      - backend

  backend:
    build: ./backend
    ports:
      - "5000:5000"
    environment:
      - DB_HOST=postgres
    depends_on:
      - postgres

  postgres:
    image: postgres
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

6. 常见问题与解决方案

6.1 依赖安装问题

• 问题：容器内依赖安装失败
• 解决方案：确保requirements.txt已复制到容器，并在安装前执行：

COPY requirements.txt .
RUN pip install -r requirements.txt

6.2 端口冲突

• 问题：端口已被占用
• 解决方案：修改docker-compose.yml中的端口映射：

ports:
  - "4000:5000" # 宿主机4000映射到容器5000

6.3 文件权限问题

• 问题：容器内文件权限错误
• 解决方案：在 Dockerfile 中使用非 root 用户：

RUN useradd -m myuser
USER myuser

7. 生产环境最佳实践

1. 使用轻量级基础镜像：如python:3.9-alpine而非完整版 Python 镜像

2. 多阶段构建：分离构建环境和运行环境，减少最终镜像大小

3. 环境变量管理：使用.env文件管理敏感信息：

services:
  web:
    env_file:
      - .env

4. 日志管理：配置日志轮转和外部日志收集

5. 健康检查：添加容器健康检查：

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

8. 常用命令参考

命令	描述
docker-compose up -d	启动服务(后台模式)
docker-compose down	停止并移除容器
docker-compose logs -f	查看实时日志
docker-compose ps	查看服务状态
docker-compose exec web sh	进入容器 shell
docker-compose restart web	重启指定服务

通过以上配置和最佳实践，你可以高效地使用 Docker Compose 部署 Python 项目，无论是开发环境还是生产环境。根据项目需求，可以灵活扩展数据库、缓存等其他服务。