Nginx 反向代理实战:proxy_set_header 到底改了哪些头

举报
yd_257742204 发表于 2026/11/16 06:06:50 2026/11/16
【摘要】 从默认的 Host 与 Connection 处理讲起,覆盖真实 IP、跳转 scheme、WebSocket 升级、Cookie 域路径四个高频坑,附可抄的最小模板。

Nginx 反向代理实战:proxy_set_header 到底改了哪些头

反向代理跑起来容易,跑对很难。很多「后端拿不到真实 IP」「登录后一直跳回登录页」「跳转地址变成 http」的问题,根源都是 Nginx 转发时对请求头的默认处理。这篇把默认行为和必须显式覆盖的点讲清楚。

一、默认只转发两个头

Nginx 的 proxy 模块有个容易被忽略的默认:

proxy_set_header Host       $proxy_host;
proxy_set_header Connection close;

$proxy_host 是 upstream 里写的那个名字,不是客户端请求的域名。所以后端看到的 Host 会是 127.0.0.1:8080 这类值。而客户端带来的其他头(Accept、User-Agent、Cookie 等)默认是透传的,Authorization 也透传。

想让后端按原始域名做路由或生成绝对链接,必须显式写:

proxy_set_header Host $host;

$host 的取值顺序是:请求行里的 Host、SNI 里的主机名、匹配到的 server_name,最后才是 $server_name。如果前面还有一层 CDN 或负载均衡,$host 拿到的是那一层转过来的 Host,一般仍然是对的。

二、真实客户端 IP 的三段式

$remote_addr 拿到的永远是直连对端,也就是上一跳代理的地址。要拿到真实客户端 IP,必须同时做两件事:

proxy_set_header X-Real-IP        $remote_addr;
proxy_set_header X-Forwarded-For  $proxy_add_x_forwarded_for;

但 $proxy_add_x_forwarded_for 的行为是把现有的 XFF 追加一个逗号再拼上 $remote_addr,也就是说客户端自己伪造的 XFF 会被原样保留在最前面。后端如果直接取 XFF 的第一个地址,任何人都能伪造。

正确做法是在最外层(用户直接连到的那一层)用 proxy_set_header X-Forwarded-For $remote_addr; 覆盖而不是追加,内层再改用追加。或者在 Nginx 里就用 realip 模块收敛:

set_real_ip_from 10.0.0.0/8;
real_ip_header   X-Forwarded-For;
real_ip_recursive on;

real_ip_recursive on 会从 XFF 末尾往前找第一个不在信任网段里的地址,这样伪造的头部就不起作用了。

三、跳转变成 http 的原因

后端生成 302 时的 Location 通常是相对路径,但框架一旦拼绝对地址就会用请求的 scheme。Nginx 到后端一般是明文 HTTP,于是 https 站点跳转后掉回 http。

修法有两种,选一种即可:

proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Port  $server_port;

或者直接告诉后端原始 scheme:

proxy_set_header X-Forwarded-Ssl on;

关键是后端要真的读这个头(Spring 的 server.forward-headers-strategy=framework、Django 的 SECURE_PROXY_SSL_HEADER、Rails 的 config.force_ssl 配合 request.headers["X-Forwarded-Proto"])。只加 Nginx 侧不配后端等于没配。

四、WebSocket 的两个必需项

普通 proxy_pass 是 HTTP/1.0 语义的短连接,升级请求会被掐掉,表现是握手 101 之后立刻断开。必须成对写:

proxy_http_version 1.1;
proxy_set_header Upgrade    $http_upgrade;
proxy_set_header Connection $connection_upgrade;

$connection_upgrade 需要在 http 块里定义映射:

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

注意默认的 Connection close 会覆盖客户端的 Connection: Upgrade,这是 WebSocket 接不通最常见的原因。

五、Cookie 域与路径

后端在 example.com/app 下发了 Path=/app 的 Cookie,但反代挂在 / 上,浏览器就不会把它带给其他路径,表现为登录后换页面就掉登录。要么后端改 Cookie 路径,要么用 proxy_cookie_path 改写:

proxy_cookie_path /app/ /;
proxy_cookie_domain backend.internal example.com;

Cookie 的 Secure 属性同理:http 下发的 Cookie 不会在 https 之外发送,但反过来 https 页面收 http 的 Cookie 是允许的,所以混用会埋下「某个子路径永远登录不上」的坑。

六、一个可用的最小模板

location / {
    proxy_pass http://backend;
    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 X-Forwarded-Host  $host;
    proxy_set_header Upgrade           $http_upgrade;
    proxy_set_header Connection        $connection_upgrade;

    proxy_read_timeout 60s;
    proxy_send_timeout 60s;
    proxy_buffering    off;
}

proxy_buffering off 对流式响应(SSE、下载进度)是必须的,否则 Nginx 会攒满缓冲区才吐给客户端,表现为「接口很慢但后端日志显示秒回」。

七、三条自检

  1. 后端打印收到的全部请求头,用一个 curl 带自定义 XFF 打一发,确认前端没有把伪造值透传。
  2. 在 https 页面点一个会 302 的接口,看 Location 的 scheme 是否还是 https。
  3. 握手 WebSocket 后看 Nginx 的 access log,$connection_requests 是否大于 1,只有 1 说明升级没成。

改完 Nginx 配置先 nginx -t 再用 nginx -s reload,别直接 restart,reload 对正在进行的请求是平滑的。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。