Docker 单机部署指南：快速实现 Django 项目容器化运行

2025年11月1日 互联网

Docker 单机部署指南：快速实现 Django 项目容器化运行

一、Docker 单机部署的核心优势与适用场景

Docker 的单机部署模式为开发者提供了轻量级、隔离性强的运行环境，尤其适合以下场景：

  1. 开发环境标准化：通过 Dockerfile 定义依赖，确保团队成员使用完全一致的开发环境，避免因环境差异导致的“在我机器上能运行”问题。
  2. 资源高效利用：相比虚拟机，Docker 容器共享宿主内核，启动速度快（秒级），资源占用低（通常仅增加 5-10% 开销）。
  3. 快速迭代与测试：容器镜像可快速构建和销毁，适合 CI/CD 流程中的自动化测试与部署。
  4. 多版本共存：单机可同时运行不同版本的 Django 项目（如 3.2 和 4.2），互不干扰。

以 Django 项目为例，传统部署需手动安装 Python、数据库、Redis 等依赖，而 Docker 只需一个 docker-compose.yml 文件即可定义完整服务栈。

二、Django 项目容器化前的关键准备

1. 项目结构优化

建议采用以下目录结构：

  1. my_django_project/
  2. ├── app/                # Django 应用代码
  3. │   ├── __init__.py
  4. │   ├── settings.py
  5. │   └── ...
  6. ├── requirements.txt    # Python 依赖
  7. ├── Dockerfile          # 构建镜像
  8. └── docker-compose.yml  # 服务编排

2. 依赖管理规范

  • Python 依赖：使用 pip freeze > requirements.txt 生成精确依赖列表，避免使用 latest 版本。
  • 系统依赖：在 Dockerfile 中通过 RUN apt-get install 安装编译工具（如 gcc、python3-dev）。
  • 静态文件处理：配置 STATIC_ROOT 和 STATICFILES_DIRS，建议使用 WhiteNoise 简化生产环境部署。

三、Docker 部署 Django 的完整流程

1. 编写 Dockerfile

  1. # 使用官方 Python 镜像作为基础
  2. FROM python:3.11-slim
  4. # 设置环境变量
  5. ENV PYTHONDONTWRITEBYTECODE 1
  6. ENV PYTHONUNBUFFERED 1
  8. # 安装系统依赖
  9. RUN apt-get update && \
  10.     apt-get install -y --no-install-recommends \
  11.     build-essential \
  12.     libpq-dev \
  13.     && rm -rf /var/lib/apt/lists/*
  15. # 创建工作目录并设置权限
  16. WORKDIR /app
  17. COPY requirements.txt .
  19. # 安装 Python 依赖
  20. RUN pip install --no-cache-dir -r requirements.txt
  22. # 复制项目代码
  23. COPY . .
  25. # 暴露端口（可选，仅用于文档说明）
  26. EXPOSE 8000
  28. # 定义启动命令
  29. CMD ["gunicorn", "--bind", "0.0.0.0:8000", "app.wsgi"]

关键点说明：

  • 使用 python:3.11-slim 减少镜像体积（约 120MB vs 常规版的 900MB）。
  • PYTHONDONTWRITEBYTECODE 禁止生成 .pyc 文件，避免权限问题。
  • 多阶段构建可进一步优化（如分离构建环境和运行环境），此处简化示例。

2. 配置 docker-compose.yml

  1. version: '3.8'
  3. services:
  4.   web:
  5.     build: .
  6.     command: gunicorn app.wsgi:application --bind 0.0.0.0:8000
  7.     volumes:
  8.       - .:/app
  9.     ports:
  10.       - "8000:8000"
  11.     environment:
  12.       - DEBUG=1
  13.       - DJANGO_SETTINGS_MODULE=app.settings
  14.     depends_on:
  15.       - db
  17.   db:
  18.     image: postgres:15-alpine
  19.     volumes:
  20.       - postgres_data:/var/lib/postgresql/data
  21.     environment:
  22.       - POSTGRES_USER=django
  23.       - POSTGRES_PASSWORD=django
  24.       - POSTGRES_DB=django_db
  26. volumes:
  27.   postgres_data:

配置解析：

  • 服务分离：将 Web 应用和数据库拆分为独立服务，符合微服务理念。
  • 数据持久化：通过 volumes 挂载数据库数据，避免容器删除后数据丢失。
  • 环境变量：通过 environment 传递敏感配置（生产环境建议使用 .env 文件）。

3. 构建与运行

  1. # 构建镜像（首次运行或代码变更后）
  2. docker-compose build
  4. # 启动服务
  5. docker-compose up -d
  7. # 查看日志
  8. docker-compose logs -f
  10. # 停止服务
  11. docker-compose down

常见问题处理：

  • 端口冲突：若 8000 端口被占用，修改 ports 为 "8001:8000"。
  • 依赖安装失败：检查 requirements.txt 格式，确保无 BOM 头（Windows 用户需注意）。
  • 数据库连接失败：确认 db 服务已启动，且 Django 的 DATABASES 配置中 HOST 为 db（而非 localhost）。

四、生产环境优化建议

1. 安全加固

  • 使用非 root 用户运行容器：在 Dockerfile 中添加： 
    1. RUN useradd -m django && chown -R django /app
    2. USER django
  • 限制容器权限：通过 --cap-drop=ALL 减少内核能力。

2. 性能优化

  • 静态文件处理：生产环境建议使用 Nginx 反向代理 + WhiteNoise。
  • ASGI 服务器：替换 Gunicorn 为 Uvicorn（异步支持）： 
    1. command: uvicorn app.asgi:application --host 0.0.0.0 --port 8000
  • 进程管理：使用 supervisord 同时运行 Celery 等后台任务。

3. 监控与日志

  • 集成 Prometheus + Grafana 监控容器指标。
  • 日志集中管理：通过 logging 配置将日志输出到 stdout，由 Docker 收集。

五、常见问题与解决方案

1. 数据库迁移失败

现象：django.db.utils.OperationalError: could not connect to server
原因：Django 启动时数据库未就绪。
解决：

  • 在 docker-compose.yml 中为 db 服务添加健康检查： 
    1. healthcheck:
    2.   test: ["CMD-SHELL", "pg_isready -U django -d django_db"]
    3.   interval: 5s
    4.   timeout: 5s
    5.   retries: 5
  • 修改 Web 服务的启动命令为等待数据库就绪： 
    1. command: sh -c "while ! nc -z db 5432; do sleep 1; done && python manage.py migrate && gunicorn app.wsgi:application --bind 0.0.0.0:8000"

2. 静态文件 404

现象：开发环境正常，生产环境静态文件无法加载。
解决：

  • 确认 STATIC_ROOT 配置正确（如 /app/staticfiles）。
  • 运行 collectstatic 命令： 
    1. command: sh -c "python manage.py collectstatic --noinput && gunicorn app.wsgi:application --bind 0.0.0.0:8000"

六、总结与扩展

通过 Docker 部署 Django 项目，开发者可获得以下收益：

  1. 环境一致性：从开发到生产全程使用相同容器镜像。
  2. 部署效率：单命令完成服务启动，支持横向扩展（通过 docker-compose scale）。
  3. 隔离性：避免项目间依赖冲突。

下一步建议：

  • 学习 Kubernetes 实现多机部署。
  • 探索 CI/CD 流水线集成（如 GitHub Actions + Docker Hub）。
  • 研究服务网格（如 Istio）管理微服务通信。

Docker 的单机部署模式为 Django 项目提供了高效、可靠的运行方案，掌握此技能可显著提升开发效率与系统稳定性。

最新文章