基于 Docker 与 Nginx 反向代理的 Django + Vue 前后端分离生产部署实践

举报
yd_246313749 发表于 2026/11/17 11:31:04 2026/11/17
【摘要】 在现代 Web 应用开发中,Django(后端 REST API)+ Vue(前端 SPA)的前后端分离架构被广泛采用。本文将结合生产环境实践,完整梳理如何通过 Docker Compose 编排容器,并利用 Nginx 作为统一网关与反向代理,实现高可用、易维护的生产级部署方案。 一、整体架构概览在生产环境中,不建议直接暴露 Django 自带的开发服务器(runserver),也不建议由...

在现代 Web 应用开发中,Django(后端 REST API)+ Vue(前端 SPA)的前后端分离架构被广泛采用。本文将结合生产环境实践,完整梳理如何通过 Docker Compose 编排容器,并利用 Nginx 作为统一网关与反向代理,实现高可用、易维护的生产级部署方案。

一、整体架构概览

在生产环境中,不建议直接暴露 Django 自带的开发服务器(runserver),也不建议由前端容器单独对外提供端口。标准架构如下:

  1. 统一入口层(Nginx):监听 80/443 端口,承担三大职责:
    • 静态托管 Vue 打包生成的 dist 单页应用(SPA)资源;
    • 直接服务 Django 通过 collectstatic 收集的后台静态文件(/static/)及用户上传文件(/media/);
    • 将 /api/、/admin/ 等动态请求反向代理至后端应用服务器。
  2. 后端应用层(Gunicorn / uWSGI + Django):容器内运行 Gunicorn 多 Worker 进程,专注于业务逻辑与数据库交互,通过 Docker 内部网络与 Nginx 通信。
  3. 数据与缓存层(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 Router history 模式下用户直接刷新子路径返回 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)方式直接高效读取文件。

四、生产环境常见踩坑与排查

  1. 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。
  2. 静态与媒体文件权限问题:
    • 当宿主机与容器内 UID 不一致时,Nginx worker 进程(通常为 nginx 或 www-data)可能无权读取 media_vol 中的上传文件,导致 403 Forbidden。建议在 Dockerfile 中统一非 root 运行用户的 UID,或确保目录具备可读权限(chmod 755)。
  3. 零停机配置重载(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 结合健康检查实现最小化影响的服务滚动更新。

总结

通过 Docker Compose 将数据库、Django/Gunicorn 与 Nginx 解耦编排,并辅以精细化的 Nginx 缓存、代理头透传和健康检查机制,能够显著提升前后端分离项目的交付效率与线上稳定性。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。