Docker Compose 部署 Django 必须解决三大连通问题:1. Django 容器通过 service 名(如 'db')连接 MySQL,不可用 localhost;2. Nginx 反向代理需匹配 ALLOWED_HOSTS(如 'nginx' 或域名);3. collectstatic 必须构建时执行且 STATIC_ROOT 与 Nginx alias 路径严格一致。

Docker Compose 部署 Django 不是“一键启动”就完事,而是必须解决三个硬性连通问题:Django 容器能否正确连接 MySQL、Nginx 能否反向代理到 Gunicorn、静态文件能否被 Nginx 正确命中。漏掉任一环,docker-compose up -d 启动后就是 502、404 或 Connection refused。
DB_HOST 必须写 service 名,不能写 localhost 或 127.0.0.1
Docker 默认为每个 service 分配独立网络命名空间,localhost 在 Django 容器里指向它自己,不是 MySQL 容器。MySQL service 名定义为 db,Django 的 DATABASES['default']['HOST'] 就必须设为 'db'。
- 错误写法:
'HOST': 'localhost'或'HOST': '127.0.0.1'→ 连接拒绝 - 正确写法:
'HOST': 'db',且docker-compose.yml中对应 service 名必须一致 - 如果用了 healthcheck,建议在
db下加:healthcheck: test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p$$MYSQL_ROOT_PASSWORD"](注意密码变量需双 $ 转义)
ALLOWED_HOSTS 和 DEBUG 必须由环境变量注入,不能硬编码
DEBUG=False 硬写在 settings.py 里,容器一启就拒收所有请求;ALLOWED_HOSTS=['localhost'] 更是无效——容器内没有 localhost 可访问,外网访问时 host 是域名或 IP。
- 用
django-environ解析环境变量:DEBUG = env.bool('DEBUG', default=False),ALLOWED_HOSTS = env.list('ALLOWED_HOSTS', default=['nginx']) -
docker-compose.yml中显式传入:environment: - DEBUG=False - ALLOWED_HOSTS=nginx,myapp.com - 若 Nginx 和 Django 同属一个自定义网络(推荐),
ALLOWED_HOSTS至少包含'nginx';对外暴露时再加真实域名
collectstatic 必须在构建或启动阶段执行,且 STATIC_ROOT 路径要与 Nginx 配置对齐
Nginx 不走 Django 的 URL 路由,它只认文件系统路径。如果镜像里没运行 python manage.py collectstatic --noinput,/static/ 下就是空的,返回 404 是必然结果。
将测试、lint、构建和文档流程编码为命名的Python会话,以便人类和代理每次运行相同的workflow。
- 推荐在
Dockerfile构建阶段执行:RUN python manage.py collectstatic --noinput(放在COPY . .之后、CMD之前) -
STATIC_ROOT必须设为绝对路径,例如/app/staticfiles,并在 Nginx 配置中严格匹配:alias /app/staticfiles/; - 不要用
volume挂载static/源码目录——权限不同步、路径不一致、容易覆盖构建产物
depends_on 不等于服务就绪,数据库初始化要靠 wait-for-it.sh 或健康检查兜底
depends_on 只控制容器启动顺序,不等待 MySQL 进程真正接受 TCP 连接。Gunicorn 启动太快,会因 DB 未 ready 而崩溃退出,然后反复重启。
- 给
webservice 加depends_on: db是基础,但不够 - 更可靠的做法:在
web的entrypoint.sh中调用wait-for-it.sh db:3306 --timeout=60 --strict -- python manage.py migrate - 或者在
db中启用healthcheck,再在web中用condition: service_healthy
最易被忽略的是 Nginx 和 Django 之间的 Host 头传递与 ALLOWED_HOSTS 的动态组合——比如 Nginx 配置了 proxy_set_header Host $host;,而 Django 却只允许 'nginx',这时请求头里的 Host: myapp.com 就会被拦截。这个细节不出错,整个链路才真正跑得通。
Python免费学习笔记(深入):立即使用
在学习笔记中,你将探索 Python 的核心概念和高级技巧!










