基于 Docker 与 Nginx 反向代理的 Django + Vue 前后端分离生产部署实践
【摘要】 在现代 Web 应用开发中,Django(后端 REST API)+ Vue(前端 SPA)的前后端分离架构被广泛采用。本文将结合生产环境实践,完整梳理如何通过 Docker Compose 编排容器,并利用 Nginx 作为统一网关与反向代理,实现高可用、易维护的生产级部署方案。 一、整体架构概览在生产环境中,不建议直接暴露 Django 自带的开发服务器(runserver),也不建议由...
在现代 Web 应用开发中,Django(后端 REST API)+ Vue(前端 SPA)的前后端分离架构被广泛采用。本文将结合生产环境实践,完整梳理如何通过 Docker Compose 编排容器,并利用 Nginx 作为统一网关与反向代理,实现高可用、易维护的生产级部署方案。
一、整体架构概览
在生产环境中,不建议直接暴露 Django 自带的开发服务器(runserver),也不建议由前端容器单独对外提供端口。标准架构如下:
- 统一入口层(Nginx):监听
80/443端口,承担三大职责:- 静态托管 Vue 打包生成的
dist单页应用(SPA)资源; - 直接服务 Django 通过
collectstatic收集的后台静态文件(/static/)及用户上传文件(/media/); - 将
/api/、/admin/等动态请求反向代理至后端应用服务器。
- 静态托管 Vue 打包生成的
- 后端应用层(Gunicorn / uWSGI + Django):容器内运行 Gunicorn 多 Worker 进程,专注于业务逻辑与数据库交互,通过 Docker 内部网络与 Nginx 通信。
- 数据与缓存层(PostgreSQL / Redis):通过独立容器挂载持久化卷(Volume),与业务容器通过内部桥接网络隔离,不直接对公网暴露端口。
二、Nginx 核心配置要点
一份健壮的 Nginx 配置需要兼顾 SPA 路由回退、静态资源性能与代理请求头透传:
server {
listen 80;
server_name example.com;
# 开启 Gzip 压缩,显著减小 JS/CSS 传输体积
gzip on;
gzip_min_length 1k;
gzip_comp_level 6;
gzip_types text/plain application/javascript application/x-javascript text/css application/xml text/javascript application/json;
gzip_vary on;
# 1. Vue SPA 前端静态资源与 History 模式路由回退
location / {
root /usr/share/nginx/html/dist;
index index.html;
try_files $uri $uri/ /index.html;
}
# 2. Django 静态文件与媒体文件 alias 映射
location /static/ {
alias /app/staticfiles/;
expires 30d;
add_header Cache-Control "public, immutable";
}
location /media/ {
alias /app/media/;
expires 7d;
}
# 3. 反向代理后端 API 至 Gunicorn
location ~ ^/(api|admin)/ {
proxy_pass http://backend:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 60s;
}
}
关键点解析:
try_files $uri $uri/ /index.html;:解决 Vue Routerhistory模式下用户直接刷新子路径返回 404 的问题。alias与root的区别:/static/使用alias /app/staticfiles/;时,末尾斜杠必须与location对齐,Nginx 会直接替换路径前缀。X-Forwarded-Proto:在 HTTPS 终止于 Nginx 时,Django 需要依赖该请求头判断原始协议是否为 HTTPS。
三、Docker Compose 容器化编排与健康检查
通过 docker-compose.yml 统一管理服务依赖与健康检查,确保数据库与后端就绪后再由 Nginx 接入流量:
version: "3.9"
services:
db:
image: postgres:15-alpine
restart: unless-stopped
environment:
POSTGRES_DB: app_db
POSTGRES_USER: app_user
POSTGRES_PASSWORD: ${DB_PASSWORD}
volumes:
- pg_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app_user -d app_db"]
interval: 10s
timeout: 5s
retries: 5
backend:
build: ./backend
restart: unless-stopped
command: >
sh -c "python manage.py migrate --noinput &&
python manage.py collectstatic --noinput &&
gunicorn config.wsgi:application --bind 0.0.0.0:8000 --workers 4 --timeout 60"
volumes:
- static_vol:/app/staticfiles
- media_vol:/app/media
depends_on:
db:
condition: service_healthy
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/api/health/"]
interval: 15s
timeout: 5s
retries: 3
nginx:
image: nginx:1.25-alpine
restart: unless-stopped
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
- ./frontend/dist:/usr/share/nginx/html/dist:ro
- static_vol:/app/staticfiles:ro
- media_vol:/app/media:ro
depends_on:
backend:
condition: service_healthy
volumes:
pg_data:
static_vol:
media_vol:
使用共享具名卷 static_vol 和 media_vol,既能让后端容器在启动时完成 collectstatic,又能让 Nginx 以只读(:ro)方式直接高效读取文件。
四、生产环境常见踩坑与排查
- CORS 跨域与 CSRF 校验失败:
- 同域部署下通过 Nginx 统一代理
/api/可天然规避浏览器跨域限制;若存在多域名访问,需在 Django 中配置django-cors-headers并严格限制CORS_ALLOWED_ORIGINS。 - Django 4.0+ 对 HTTPS 来源的 POST 请求会强制校验
CSRF_TRUSTED_ORIGINS,同时需配置SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https'),否则会出现403 CSRF verification failed。
- 同域部署下通过 Nginx 统一代理
- 静态与媒体文件权限问题:
- 当宿主机与容器内 UID 不一致时,Nginx worker 进程(通常为
nginx或www-data)可能无权读取media_vol中的上传文件,导致 403 Forbidden。建议在 Dockerfile 中统一非 root 运行用户的 UID,或确保目录具备可读权限(chmod 755)。
- 当宿主机与容器内 UID 不一致时,Nginx worker 进程(通常为
- 零停机配置重载(Zero-Downtime Reload):
- 修改 Nginx 配置或更新前端
dist包时,切忌直接docker compose restart nginx,这会中断正在处理的连接。应先执行语法校验再平滑重载:docker compose exec nginx nginx -t && docker compose exec nginx nginx -s reload - 后端代码更新时,可使用
docker compose up -d --no-deps --build backend结合健康检查实现最小化影响的服务滚动更新。
- 修改 Nginx 配置或更新前端
总结
通过 Docker Compose 将数据库、Django/Gunicorn 与 Nginx 解耦编排,并辅以精细化的 Nginx 缓存、代理头透传和健康检查机制,能够显著提升前后端分离项目的交付效率与线上稳定性。
【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱:
cloudbbs@huaweicloud.com
- 点赞
- 收藏
- 关注作者
评论(0)