DjangoDocker部署教程：Dockerfile与Gunicorn配置

本文详解如何为 Django 项目构建安全、轻量且生产就绪的 Docker 镜像，聚焦多阶段构建的最佳实践：第一阶段精准安装依赖并执行 collectstatic，第二阶段仅携带运行时所需代码与包，彻底剥离开发工具；强调必须使用 Gunicorn 替代 runserver，正确绑定 0.0.0.0:8000 以适配容器网络，并通过 PYTHONUNBUFFERED=1 确保日志实时可查；同时直击常见痛点——模块导入失败、静态文件缺失、环境变量注入疏漏，手把手帮你避开部署雷区，让 Django 真正跑得稳、看得清、连得上。

怎么写一个最小可用的 Django Dockerfile

核心是别把开发依赖打进生产镜像，也别让 manage.py 直接跑在容器里。Django 本身不自带生产级 HTTP 服务，必须用 gunicorn 或 uWSGI 转发请求。

推荐用多阶段构建，第一阶段装依赖并收集静态文件，第二阶段只复制编译好的 Python 包和代码：

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

FROM python:3.11-slim
WORKDIR /app
COPY --from=0 /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
COPY . .
RUN python manage.py collectstatic --noinput

EXPOSE 8000
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "4", "myproject.wsgi:application"]

• requirements.txt 里要区分 django 和 gunicorn，别漏掉 gunicorn
• collectstatic 必须在第二阶段前运行，否则 Nginx 找不到 static/ 文件
• 别用 python manage.py runserver，它不是为生产设计，没并发、没超时控制、会暴露调试信息

为什么 Gunicorn 的 --bind 不能写成 127.0.0.1:8000

容器内进程默认绑定到 0.0.0.0，写成 127.0.0.1 会导致外部（比如 Nginx 容器或宿主机）连不上——Docker 网络里，127.0.0.1 指的是当前容器自己，不是宿主机。

• 正确写法是 --bind 0.0.0.0:8000 或简写为 --bind :8000
• 如果加了 --reload，Gunicorn 会监听文件变化，但 Docker 镜像里代码是只读的，这个参数只对本地开发有用，上线必须删掉
• --workers 数建议设为 CPU 核数 × 2 + 1，单核机器就用 3，别盲目堆高

Docker 启动时提示 ModuleNotFoundError: No module named 'myproject.wsgi'

这是路径或模块名错了，不是包没装。Gunicorn 启动时会在当前目录下找 Python 包，而 myproject.wsgi 是相对导入路径，要求 myproject/ 是一个合法包（含 __init__.py），且当前工作目录是它的父目录。

• 确认 myproject/__init__.py 存在（哪怕为空）
• CMD 前加 WORKDIR /app，确保 /app 下有 myproject/ 目录
• 检查 manage.py 里的 os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')，模块名必须和目录名一致
• 别在 settings.py 里用绝对路径拼 BASE_DIR，Docker 里 __file__ 的位置和本地不同

要不要在 Dockerfile 里用 ENV PYTHONUNBUFFERED=1

要用，而且是必须项。Python 默认会缓冲 stdout/stderr，Docker 日志采集器（如 docker logs）看不到实时输出，线上出错时只能干等或进容器 tail -f。

• 加上 ENV PYTHONUNBUFFERED=1 后，所有 print、logging 都立即刷到 stdout
• 顺带加 ENV PYTHONDONTWRITEBYTECODE=1，避免容器里生成 __pycache__，减小镜像体积、避免权限问题
• 这两个环境变量不影响功能，只改日志行为，不加不会报错，但会让排障变慢

最麻烦的其实是数据库连接和密钥管理——Docker 里不能硬编码 DATABASE_URL 或 SECRET_KEY，得靠 docker run -e 或 docker-compose.yml 注入，这部分一旦漏掉，服务起来也连不上库。

理论要掌握，实操不能落！以上关于《DjangoDocker部署教程：Dockerfile与Gunicorn配置》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！