Nginx 反向代理

概述

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

架构示意

客户端 → Nginx（80/443）
          ├─ /            → 前端静态资源（dist/）
          ├─ /api/v1/...  → FastAPI 后端（8031）
          └─ /api/file/   → 上传文件目录

基础配置

项目提供了 Nginx 配置模板 deploy/nginx.conf，按需修改即可使用：

upstream fastapi_backend {
    server 127.0.0.1:8031;
    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/frontend/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://fastapi_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;
    }

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

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

配置说明

• upstream + keepalive：长连接池减少 TCP 握手开销
• location /：try_files 支持 SPA 路由回退
• location /api/：只代理 API 请求，前端静态资源由 Nginx 直接服务
• location /api/file/：通过 alias 访问上传文件目录，只允许 GET
• client_max_body_size 50m：与后端 UPLOAD_MAX_SIZE_MB 保持一致
• proxy_read_timeout 120s：适应大数据量导出等长耗时操作

部署步骤

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

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

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

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

# 5. 检查并重载
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;
}

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

后端 FastAPI 服务未启动或端口不对。检查：curl http://127.0.0.1:8031/api/v1/captcha

413 Request Entity Too Large

上传文件超过 client_max_body_size 限制，调大该值与后端 UPLOAD_MAX_SIZE_MB 一致。

刷新页面 404

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

API 请求走到了前端

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

总结

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