Nginx 反向代理常用配置：五种典型场景与注意事项

Nginx 反向代理是生产环境最常见的架构之一：它把客户端请求转发给上游服务，同时承担负载均衡、SSL 卸载和协议适配等职责。下面归纳五种典型场景的常用配置，并列出容易踩坑的注意事项。

一、最基本的反向代理

server {

    listen 80;

    server_name example.com;

    location / {

        proxy_pass http://127.0.0.1:8080;

        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;

    }

}

把 Host、真实 IP、协议等信息原样透传给后端，是排查问题的基础。

二、按路径拆分到不同后端

server {

    listen 80;

    server_name api.example.com;

    location /user/ {

        proxy_pass http://user-svc:8081/;

        proxy_set_header Host $host;

    }

    location /order/ {

        proxy_pass http://order-svc:8082/;

        proxy_set_header Host $host;

    }

}

注意 proxy_pass 末尾是否带 /：带 / 时，匹配到的 location 前缀会被去掉再拼接到 upstream，不带 / 时原样转发。

三、负载均衡（轮询 / 加权 / IP 哈希）

upstream backend {

    server 10.0.0.1:8080 weight=3;

    server 10.0.0.2:8080 weight=1;

    server 10.0.0.3:8080 backup;

}

server {

    listen 80;

    location / {

        proxy_pass http://backend;

        proxy_next_upstream error timeout http_502 http_503;

    }

}

需要会话保持时可用 ip_hash;，但要注意 NAT 或代理链会导致同一 IP 对应多用户。

四、WebSocket 升级

location /ws/ {

    proxy_pass http://ws-backend;

    proxy_http_version 1.1;

    proxy_set_header Upgrade $http_upgrade;

    proxy_set_header Connection "upgrade";

    proxy_read_timeout 86400s;

}

WebSocket 必须把 HTTP 版本设为 1.1 并透传 Upgrade/Connection 头，否则会退化成普通 HTTP。

五、HTTPS 终止 + 强制跳转

server {

    listen 80;

    server_name example.com;

    return 301 https://$host$request_uri;

}

server {

    listen 443 ssl;

    server_name example.com;

    ssl_certificate /etc/nginx/cert.pem;

    ssl_certificate_key /etc/nginx/key.pem;

    ssl_protocols TLSv1.2 TLSv1.3;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    location / {

        proxy_pass http://backend;

        proxy_set_header X-Forwarded-Proto https;

    }

}

注意事项总结：

1. proxy_connect_timeout、proxy_send_timeout、proxy_read_timeout 要按后端实际响应时间调整，默认 60s 在大文件上传或长轮询场景经常不够。

2. client_max_body_size 默认 1m，上传附件场景一定要调大。

3. proxy_buffering 开启后可提升性能，但对需要流式返回的接口（如日志、SSE）应设为 off。

4. 日志里记录 $upstream_response_time 和 $request_time，方便定位瓶颈在 Nginx 还是后端。

做好以上五点，反向代理就能覆盖绝大多数生产场景。