# Nginx 反向代理

## 概述

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

:::tip 架构示意
```
客户端 → Nginx（80/443）
          ├─ /            → 前端静态资源（dist/）
          ├─ /api/v1/...  → Flask 后端（8021）
          └─ /api/file/   → 上传文件目录
```
:::

## 基础配置

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

```nginx
upstream flask_backend {
    server 127.0.0.1:8021;
    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://flask_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; }
}
```

:::tip 配置说明
- `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`：适应大数据量导出等长耗时操作
:::

## 部署步骤

```bash
# 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 配置

```nginx
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 自动续期
:::

## 常用命令

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

## 常见问题

### 502 Bad Gateway

后端 Flask 服务未启动或端口不对。检查：`curl http://127.0.0.1:8021/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/` 反向代理到 Flask 后端、`/api/file/` 访问上传文件。关键配置包括 `try_files` 支持 SPA 路由、`client_max_body_size` 匹配上传限制、Gzip 压缩和静态资源缓存。