Django部署教程：Docker与Gunicorn配置详解

本文详解如何为Django项目构建安全、轻量且生产就绪的Docker镜像，强调必须摒弃开发模式（如runserver）、采用多阶段构建分离依赖与运行环境，并正确配置Gunicorn以实现高并发与外部可访问性；同时涵盖关键避坑点：绑定地址必须用0.0.0.0而非127.0.0.1、静态文件需在第二阶段前完成收集、模块路径与工作目录需严格匹配、务必启用PYTHONUNBUFFERED=1确保日志实时可见，以及敏感配置（数据库、密钥）必须通过环境变量动态注入——每一步都直击线上部署中最易出错的核心环节，助你避开90%的Docker化踩坑陷阱。

怎么写一个最小可用的 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 注入，这部分一旦漏掉，服务起来也连不上库。

到这里，我们也就讲完了《Django部署教程：Docker与Gunicorn配置详解》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！