Nginx 工程实践 -- 4. 转发头与真实客户端 IP
反向代理后面的后端服务,看到的连接地址是 Nginx,通常是 127.0.0.1。如果什么都不做,访问日志丢失来源、按 IP 限流失效、地域和风控判断失真、后端生成绝对链接时还可能拿到内网地址。本篇把转发头怎么写、变量怎么选、以及怎么把真实 IP "还原"回来讲清楚。
flowchart LR
C["客户端"] -->|"XFF: 客户端"| CDN["CDN"]
CDN -->|"XFF 追加"| N["Nginx
real_ip_recursive on"]
N -->|"XFF 追加
$proxy_add_x_forwarded_for"| B["后端"]
一、为什么需要转发头
Nginx 与后端建立的是新的 TCP 连接,后端拿到的是 Nginx 的地址。后果很直接:
- 访问日志里所有请求都来自同一个 IP;
- 限流、封禁、验证码触发等基于 IP 的策略全部失效;
- 风控、地域统计、灰度分流失去依据;
- 后端重定向或生成绝对 URL 时,可能返回内网地址。
解决方式分两层:转发头(把信息"告知"后端)和 realip(把地址"改写"回真实值)。
二、四个关键转发头
1 | |
2.1 Host
proxy_set_header 的默认值是 Host $proxy_host;,也就是 proxy_pass 里写的名字(可能是 upstream 名或后端地址),通常不是客户端想要的域名。
| 变量 | 含义 |
|---|---|
$host | 请求行里的主机名,去掉端口;没有则取当前 server_name 的第一个;小写 |
$http_host | 客户端原始 Host 头,可能带端口,原样保留 |
$server_name | 当前 server 块的 server_name |
$proxy_host | proxy_pass 的目标名,默认值 |
选择建议:后端按域名做虚拟主机或生成链接时用 $host;需要原样透传时用 $http_host;不确定就用 $host。
2.2 X-Real-IP
1 | |
只放一个地址,实现简单,但不能穿越多级代理(会被上游覆盖)。
2.3 X-Forwarded-For
1 | |
$proxy_add_x_forwarded_for = 原请求里的 XFF + , + $remote_addr,是追加而不是覆盖。多级代理时它会形成一条链,后端可以逐跳解析。
2.4 X-Forwarded-Proto / X-Forwarded-Host / X-Forwarded-Port
1 | |
后端据此判断客户端最初用的是 http 还是 https,避免把 https 请求重定向回 http、或生成错误协议的绝对 URL。
三、变量速查
| 变量 | 来源 |
|---|---|
$remote_addr | 与 Nginx 建立 TCP 连接的地址 |
$http_x_forwarded_for | 客户端原始 XFF,可能被伪造 |
$proxy_add_x_forwarded_for | 原 XFF + 当前 $remote_addr(追加) |
$scheme | 本跳协议(http/https) |
$server_port | 本跳监听端口 |
四、Forwarded(RFC 7239)
HTTP 标准定义了 Forwarded: for=...;host=...;proto=...,比 X-Forwarded-* 更规范。但 Nginx 原生不会生成 Forwarded 头,需要第三方模块或自行拼装;X-Forwarded-* 仍是事实标准,绝大多数后端都支持。
五、多层链路下怎么取"入口 IP"
1 | |
经过 CDN 时,CDN 会把客户端地址追加进 XFF;Nginx 再追加 CDN 的出口地址。于是后端收到的 XFF 类似:
1 | |
两种取法:
- 取最左(
$http_x_forwarded_for的第一个):实现简单,但客户端可以在请求里自带 XFF 伪造,不可信; - 从可信层数往左数:只信任已知会写 XFF 的上游,跳过固定层数后取第一个,安全性更高。这正是
real_ip_recursive做的事。
六、用 realip 还原真实地址
转发头只是"告知",ngx_http_realip_module 会把 $remote_addr 改写为头里的地址,让后续所有依赖它的逻辑(访问控制、限流、日志、geo、allow/deny)都基于真实 IP 生效。
1 | |
三个指令:
| 指令 | 默认 | 说明 |
|---|---|---|
set_real_ip_from | — | 声明可信来源地址或网段;只有来自这些地址的请求才会被改写 |
real_ip_header | X-Real-IP | 从哪个头取替换地址;用 XFF 就写 X-Forwarded-For |
real_ip_recursive | off | on 时从右往左跳过所有可信地址,取第一个不可信地址 |
off 时,如果直连地址可信,就用头里的最后一个地址;on 时,一直向左找,直到遇到不可信的地址,也就是"入口客户端"。多数代理场景需要 on。
改写后仍可用 $realip_remote_addr、$realip_remote_port 保留改写前的地址。
注意:
ngx_http_realip_module默认不参与编译,需要--with-http_realip_module。Debian/Ubuntu 的发行版包通常已包含,自建 Nginx 时要显式打开。
七、完整配置模板
1 | |
八、排错
| 现象 | 原因 / 处理 |
|---|---|
后端日志全是 127.0.0.1 | 没配 realip,或 set_real_ip_from 没包含真实来源网段 |
Host 变成了 upstream 名或 IP | 用了默认的 $proxy_host,改成 $host |
| XFF 只剩一个地址 | 上游覆盖了 XFF;或后端只取第一个值 |
| 后端拿到内网 IP | XFF 第一跳是 CDN/LB,需要 real_ip_recursive on |
| 改写后地址没变 | set_real_ip_from 未覆盖该来源;或模块未编译 |
验证方式:后端打印 Host、X-Real-IP、X-Forwarded-For,用 curl -H "X-Forwarded-For: 1.2.3.4" 模拟客户端自带的伪造链,确认改写逻辑符合预期。
参考链接
- Nginx 官方文档:ngx_http_proxy_module ——
proxy_set_header及内置变量; - Nginx 官方文档:ngx_http_realip_module ——
set_real_ip_from/real_ip_header/real_ip_recursive; - RFC 7239:Forwarded HTTP Extension;
- Nginx 官方文档:嵌入式变量。
小结
转发头解决"告知",realip 解决"改写"。Host 用 $host,X-Forwarded-For 用 $proxy_add_x_forwarded_for,X-Forwarded-Proto 用 $scheme;多级链路里用 set_real_ip_from + real_ip_recursive on 才能拿到入口地址。别让后端只凭 XFF 的第一个值做安全判断——它可被伪造。
