Nginx 反向代理

概述

Nginx 作为反向代理服务器，承担静态资源服务、API 请求转发、HTTPS 终端等职责。生产环境推荐使用 Nginx 作为前端入口，将 API 请求代理到后端 Django 服务。

:::tip 架构示意

客户端 -> Nginx（80/443）
          ├─ /            -> 前端静态资源（dist/）
          ├─ /api/...     -> Django 后端（8000）
          ├─ /static/     -> Django 静态文件
          └─ /uploads/    -> 上传文件目录

:::

基础配置

upstream django_backend {
    server 127.0.0.1:8000;
    keepalive 16;
}

server {
    listen 80;
    server_name your-domain.com;

    charset utf-8;
    client_max_body_size 50m;

    # 安全头
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;

    # Gzip 压缩
    gzip on;
    gzip_min_length 1k;
    gzip_comp_level 6;
    gzip_types text/plain text/css application/json application/javascript text/xml image/svg+xml;
    gzip_vary on;

    # 前端静态资源
    root /data/apps/DjangoAdmin_Django_AntdVue/ui/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /assets/ {
        expires 30d;
        add_header Cache-Control "public, immutable";
        access_log off;
    }

    # API 反向代理
    location /api/ {
        proxy_pass http://django_backend/api/;
        proxy_http_version 1.1;
        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_set_header Connection "";
        proxy_connect_timeout 60s;
        proxy_read_timeout 120s;
        proxy_send_timeout 60s;
    }

    # Django 静态文件
    location /static/ {
        alias /data/apps/DjangoAdmin_Django_AntdVue/public/static/;
        expires 30d;
        access_log off;
    }

    # 上传文件访问
    location /uploads/ {
        alias /data/apps/DjangoAdmin_Django_AntdVue/public/uploads/;
        expires 7d;
        access_log off;
        limit_except GET { deny all; }
    }

    # 禁止访问隐藏文件
    location ~ /\. { deny all; }
}

:::tip 配置说明

upstream + keepalive：长连接池减少 TCP 握手开销
location /：try_files 支持 SPA 路由回退
location /api/：只代理 API 请求，前端静态资源由 Nginx 直接服务
location /static/：Django 静态文件（collectstatic 收集的文件）
location /uploads/：用户上传文件，只允许 GET
client_max_body_size 50m：上传文件大小限制
proxy_read_timeout 120s：适应大数据量导出等长耗时操作 :::

部署步骤

# 1. 前端构建
cd ui && pnpm build

# 2. 拷贝构建产物
mkdir -p /data/apps/DjangoAdmin_Django_AntdVue/ui/dist
cp -r ui/dist /data/apps/DjangoAdmin_Django_AntdVue/ui/

# 3. 收集 Django 静态文件
python manage.py collectstatic

# 4. 拷贝 Nginx 配置
cp deploy/nginx.conf /etc/nginx/conf.d/djangoadmin.conf

# 5. 修改配置中的实际值（server_name、root 等）

# 6. 检查并重载
nginx -t && nginx -s reload

HTTPS 配置

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate     /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;

    # HSTS（强制 HTTPS）
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # ... 其他 location 配置同上 ...
}

# HTTP 自动跳转 HTTPS
server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

:::warning SSL 证书安全

证书文件权限设为 600，仅 Nginx 用户可读
禁用 TLSv1.0/1.1，仅保留 TLSv1.2+
推荐 Let's Encrypt 免费证书 + certbot 自动续期 :::

常用命令

nginx -t                # 检查配置语法
nginx -s reload         # 重新加载（不停服）
nginx -s stop           # 停止
nginx -v                # 查看版本

常见问题

502 Bad Gateway

后端 Django 服务未启动或端口不对。检查：curl http://127.0.0.1:8000/

413 Request Entity Too Large

上传文件超过 client_max_body_size 限制，调大该值。

刷新页面 404

缺少 try_files $uri $uri/ /index.html，SPA 路由需要回退到 index.html。

API 请求走到了前端

location /api/ 必须在 location / 之前定义，Nginx 按优先级匹配。

静态文件 404

确保已执行 python manage.py collectstatic 收集静态文件，且 Nginx 配置中的 location /static/ 路径正确。

总结

Nginx 反向代理是生产部署的标准配置：/ 服务前端静态资源、/api/ 反向代理到 Django 后端、/static/ 服务 Django 静态文件、/uploads/ 访问上传文件。关键配置包括 try_files 支持 SPA 路由、client_max_body_size 匹配上传限制、Gzip 压缩和静态资源缓存。

5.2 KiB Raw Blame History Unescape Escape