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. 项目结构优化

建议采用以下目录结构：

my_django_project/
├── app/                # Django 应用代码
│   ├── __init__.py
│   ├── settings.py
│   └── ...
├── requirements.txt    # Python 依赖
├── Dockerfile          # 构建镜像
└── 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

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

关键点说明：

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

2. 配置 docker-compose.yml

version: '3.8'
services:
  web:
    build: .
    command: gunicorn app.wsgi:application --bind 0.0.0.0:8000
    volumes:
      - .:/app
    ports:
      - "8000:8000"
    environment:
      - DEBUG=1
      - DJANGO_SETTINGS_MODULE=app.settings
    depends_on:
      - db
  db:
    image: postgres:15-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=django
      - POSTGRES_PASSWORD=django
      - POSTGRES_DB=django_db
volumes:
  postgres_data:

配置解析：

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

3. 构建与运行

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

常见问题处理：

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

四、生产环境优化建议

1. 安全加固

• 使用非 root 用户运行容器：在 Dockerfile 中添加：

  RUN useradd -m django && chown -R django /app
  USER django

• 限制容器权限：通过 --cap-drop=ALL 减少内核能力。

2. 性能优化

• 静态文件处理：生产环境建议使用 Nginx 反向代理 + WhiteNoise。
• ASGI 服务器：替换 Gunicorn 为 Uvicorn（异步支持）：

  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 服务添加健康检查：

  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U django -d django_db"]
    interval: 5s
    timeout: 5s
    retries: 5

• 修改 Web 服务的启动命令为等待数据库就绪：

  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 命令：

  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 项目提供了高效、可靠的运行方案，掌握此技能可显著提升开发效率与系统稳定性。