Nginx 反向代理基础配置

反向代理是 Nginx 最常见的用法：浏览器只访问 Nginx，由 Nginx 把请求转发给后端服务，再把响应返回给浏览器。后端端口不必对外暴露，统一入口还能做负载均衡、HTTPS 卸载和访问控制，出问题时先看 Nginx 这一层，往往就能定位大半故障。

一、最小可用配置

假设后端跑在本机 8080 端口，域名是 example.com：

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 会变成后端地址，后端按域名路由或生成重定向地址就会出错，所以要透传原始 Host。X-Real-IP 和 X-Forwarded-For 把真实客户端 IP 交给后端，否则后端日志里永远是 Nginx 本机地址。X-Forwarded-Proto 告诉后端原始请求是 http 还是 https，避免 https 请求被后端又重定向回 http，造成循环跳转。

二、多个后端与超时

upstream app_backend {
    server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
    server 127.0.0.1:8081;
    keepalive 32;
}
server {
    listen 80;
    server_name example.com;
    location / {
        proxy_pass http://app_backend;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Connection "";
        proxy_connect_timeout 5s;
        proxy_read_timeout 60s;
    }
}

upstream 默认按轮询分发，max_fails 可以把连续失败的节点暂时摘掉。超时要按业务调：连接超时太长，挂掉的后端会拖慢所有请求；读取超时太短，慢查询或大文件导出还没算完就被掐断，用户看到的就是 504。

三、动静分离与 WebSocket

location /static/ {
    alias /var/www/static/;
    expires 7d;
}
location /ws/ {
    proxy_pass http://app_backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

用 alias 时，location 和目录路径结尾的斜杠必须同时保留或同时去掉，缺一个就会拼错路径，直接 404。WebSocket 则必须透传 Upgrade 头，否则握手失败。

四、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/ssl/example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/example.com.key;
    location / {
        proxy_pass http://app_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

五、常见坑

一是 proxy_pass 结尾斜杠会改变路径拼接。location 为 /api/ 时，proxy_pass 后面不带斜杠，会把 /api/user 原样转发；后面带斜杠时，会把 /api/ 替换掉，只转发 /user，改之前先确认后端期望收到哪条路径。二是 location 匹配顺序：精确匹配优先，正则按文件顺序生效，普通前缀只在没有正则命中时按最长前缀生效，正则写错顺序一定会抢错。三是 proxy_pass 里用变量选后端时，必须先配 resolver，否则启动可能报错。四是改完先跑 nginx -t 检查语法，再用 nginx -s reload 平滑重载，不要直接重启，以免配置错误导致服务起不来。五是排查要分层：curl -I 看状态码和响应头，确认请求到了哪一层；再看 Nginx 的 error.log，最后看后端日志确认它实际收到的路径和请求头。

总结：反向代理的核心就是三件事，转发到正确后端、关键请求头原样透传、超时和路径规则符合后端预期。把上面这份配置当作起点，再按需加上限流和缓存，就能覆盖绝大多数中小项目的线上需求。