Nginx 反向代理配置避坑指南(proxy_pass 斜杠、502排查、CORS、文件上传)

# 在运行中的容器里验证
docker exec nginx-container nginx -t

# CI/CD 场景：用临时容器验证，不依赖运行中的服务
docker run --rm \
  -v $(pwd)/nginx.conf:/etc/nginx/nginx.conf:ro \
  nginx:1.26.2-alpine nginx -t

docker exec nginx-container nginx -t && docker exec nginx-container nginx -s reload

# 写法 A：无斜杠
location /api/ {
    proxy_pass http://backend;
}

# 写法 B：有斜杠
location /api/ {
    proxy_pass http://backend/;
}

# 后端路由：GET /users → 用有斜杠版本
location /api/ {
    proxy_pass http://backend/;
}

# 后端路由：GET /api/users → 用无斜杠版本
location /api/ {
    proxy_pass http://backend;
}

# 错误：后端收到 /api/users，但路由只有 /users，导致 404
location /api/ {
    proxy_pass http://backend;  # 应改为 http://backend/
}

# 基础连通性测试
docker exec -it nginx-container curl -v http://backend:3000/health

# 测试完整请求（带 Host 头）
docker exec -it nginx-container curl -v \
  -H "Host: example.com" \
  http://backend:3000/api/users

proxy_connect_timeout 10s;   # 与 upstream 建立 TCP 连接的超时
proxy_send_timeout 60s;      # 向 upstream 发送请求的超时
proxy_read_timeout 60s;      # 等待 upstream 响应的超时（504 的主要来源）

# 默认值：仅在 error 和 timeout 时重试
proxy_next_upstream error timeout;

# 错误配置示例：把后端正常业务错误也当节点故障处理
# proxy_next_upstream error timeout http_404 http_500;
# 会导致一次用户请求触发多次后端调用

upstream backend {
    server backend:3000;
    keepalive 32;  # 每个 worker 进程保持的最大空闲长连接数
}

server {
    location /api/ {
        proxy_pass http://backend;
        proxy_http_version 1.1;          # keepalive 要求 HTTP/1.1
        proxy_set_header Connection "";  # 清除 Connection: close，启用长连接
    }
}

location /api/ {
    proxy_pass http://backend;
    proxy_set_header Host $http_host;                        # 原始 Host（含端口）
    proxy_set_header X-Real-IP $remote_addr;                 # 直连客户端 IP
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;  # IP 链
    proxy_set_header X-Forwarded-Proto $scheme;              # 原始协议 http/https
}

# 声明信任的上游 IP 段（CDN/SLB 的 IP 段）
set_real_ip_from 103.21.244.0/22;
set_real_ip_from 103.22.200.0/22;

# 从哪个请求头中提取真实 IP
real_ip_header X-Forwarded-For;

# 递归查找，跳过信任 IP 段，找到第一个非信任 IP
real_ip_recursive on;

# 全局配置（http 块）
http {
    client_max_body_size 100m;
}

# 或仅对上传路由生效
location /upload/ {
    client_max_body_size 500m;
    client_body_timeout 300s;    # 客户端上传请求体的超时（慢速上传场景）
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;
    proxy_pass http://backend;
}

# 默认 buffer 只有 8k/16k，大文件上传会频繁写临时文件
client_body_buffer_size 1m;

# 分级临时目录，避免单目录文件过多影响性能
client_body_temp_path /tmp/nginx_upload 1 2;

location /api/ {
    # OPTIONS 预检请求单独处理
    if ($request_method = OPTIONS) {
        add_header Access-Control-Allow-Origin $http_origin;
        add_header Access-Control-Allow-Methods 'GET, POST, PUT, DELETE, PATCH, OPTIONS';
        add_header Access-Control-Allow-Headers 'Authorization, Content-Type, X-Requested-With';
        add_header Access-Control-Allow-Credentials true;
        add_header Access-Control-Max-Age 86400;
        add_header Content-Length 0;
        add_header Content-Type text/plain;
        return 204;
    }

    # 正常请求添加 CORS 头
    add_header Access-Control-Allow-Origin $http_origin always;  # always 不能漏
    add_header Access-Control-Allow-Credentials true always;

    proxy_pass http://backend;
}

# 错误配置：浏览器会直接报错拒绝
add_header Access-Control-Allow-Origin *;
add_header Access-Control-Allow-Credentials true;

set $cors_origin "";
if ($http_origin ~* ^https?://(example\.com|app\.example\.com|staging\.example\.com)$) {
    set $cors_origin $http_origin;
}
add_header Access-Control-Allow-Origin $cors_origin always;
add_header Access-Control-Allow-Credentials true always;

add_header Access-Control-Allow-Origin $http_origin;        # 错误
add_header Access-Control-Allow-Origin $http_origin always; # 正确

# 预期：/api/v2/files/photo.jpg 走第一个 location
location /api/v2/files/ {
    proxy_pass http://file-service/;
}

# 实际：正则优先级更高，.jpg 请求走这里
location ~* \.(jpg|png|gif|webp)$ {
    expires 6M;
    add_header Cache-Control "public";
}

location ^~ /api/v2/files/ {
    proxy_pass http://file-service/;
}

# 推荐：用数字前缀明确控制加载顺序
00-default.conf
10-app-main.conf
20-app-admin.conf

location /static/ {
    root /data;
}
# 请求 /static/img/logo.png
# 实际查找路径：/data/static/img/logo.png
#               ^^^^^ ^^^^^^^^
#               root  location路径也包含在内

location /static/ {
    alias /data/assets/;   # 末尾斜杠必须有
}
# 请求 /static/img/logo.png
# 实际查找路径：/data/assets/img/logo.png
#               ^^^^^^^^^^^^ 只有 alias 路径，location 路径被替换

location / {
    root /usr/share/nginx/html;
    try_files $uri $uri/ /index.html;
}

# 验证配置语法（必须先做）
docker exec nginx-container nginx -t

# 优雅重载配置
docker exec nginx-container nginx -t && \
  docker exec nginx-container nginx -s reload

# 查看当前已生效的完整配置（含 include 展开）
docker exec nginx-container nginx -T

# 实时查看错误日志
docker exec nginx-container tail -f /var/log/nginx/error.log

# 从容器内测试 upstream 连通性（排查 502 第一步）
docker exec nginx-container curl -v http://backend:3000/health

# 测试带 Host 头的请求
docker exec nginx-container curl -v \
  -H "Host: example.com" \
  http://backend:3000/api/users

# 测试 CORS 预检请求
curl -v -X OPTIONS \
  -H "Origin: https://example.com" \
  -H "Access-Control-Request-Method: POST" \
  http://your-nginx/api/users