Nginx怎样获取真实客户端IP?可信代理范围配置错了会有什么风险
很多站点把 X-Forwarded-For 中的第一个地址直接当成真实客户端 IP,但这并不等于 Nginx已经验证过该地址。客户端可以自行发送同名请求头,只有当请求来自明确可信的代理地址时,Nginx 才应按照代理链规则重新计算 $remote_addr。
正确配置的关键不是“开启某个真实 IP 参数”,而是同时匹配三件事:Nginx 实际连接到的上游地址、上游代理传递的请求头格式,以及可信代理的最小地址范围。范围填得过窄,日志中仍会出现 CDN 或负载均衡器地址;范围填得过宽,攻击者可能伪造来源 IP,进一步影响访问控制、限流、审计和应用侧安全判断。
先厘清“真实客户端 IP”的含义
一次经过多层代理的请求,通常至少存在三种地址:
- TCP 对端地址:Nginx 建立连接时实际看到的地址,也就是未处理真实 IP 前的
$remote_addr。 - 代理头中的地址:例如
X-Forwarded-For、X-Real-IP或 PROXY protocol 携带的地址。 - 应用最终使用的地址:Nginx 重写
$remote_addr后,可能通过proxy_set_header传给后端应用。
例如,访问路径可能是:

客户端 198.51.100.23
↓
CDN 203.0.113.10
↓
负载均衡器 10.20.0.5
↓
Nginx
此时 Nginx 的 TCP 对端可能是 10.20.0.5,而不是客户端的 198.51.100.23。负载均衡器可能向 Nginx 传递:
X-Forwarded-For: 198.51.100.23, 203.0.113.10
这条请求头只是代理链提供的声明。Nginx 是否采用它,要看 TCP 对端是否在 set_real_ip_from 配置的可信范围内。
set_real_ip_from 信任的是什么
set_real_ip_from 信任的是“可以代表客户端传递地址的代理”,不是终端用户的 IP 地址。
正确思路通常是:
set_real_ip_from 10.20.0.0/16; # 负载均衡器所在网段,示例
set_real_ip_from 203.0.113.0/24; # CDN 出口范围,示例
这里的地址仅用于说明配置关系,实际部署应替换为当前架构中真实的代理地址或网段。
不应因为某些客户端来自某个公网网段,就把客户端网段加入 set_real_ip_from。终端用户不是可信代理,加入后并不能让“真实 IP 更准确”,反而会扩大伪造请求头的范围。
$remote_addr 和 $realip_remote_addr 的区别
启用 Real IP 模块后:
$remote_addr:经过真实 IP 模块处理后的地址,通常是 Nginx认为的客户端地址。$realip_remote_addr:原始连接对端地址,用来确认请求实际从哪个代理或主机连接过来。
排查时必须同时记录这两个变量。只看 $remote_addr,很容易误以为 Nginx直接连接到了客户端。
Nginx如何根据代理链替换地址
Nginx HTTP 场景中,常用的三个配置项分别负责不同工作:
set_real_ip_from 代理地址或网段;
real_ip_header X-Forwarded-For;
real_ip_recursive on;
real_ip_header决定读取哪种来源
常见取值有:
X-Forwarded-For:适合多级 HTTP 反向代理,能够保存地址链。X-Real-IP:通常只携带一个地址,适合链路简单且由上游明确设置的场景。proxy_protocol:适合上游通过 PROXY protocol 传递连接信息,不能当作普通 HTTP 请求头使用。
如果上游发送的是:
X-Forwarded-For: 198.51.100.23, 203.0.113.10
但 Nginx 配置成:
real_ip_header X-Real-IP;
而上游又没有发送 X-Real-IP,那么这套真实 IP 配置就不会按预期工作。反过来,如果只想读取一个可信上游设置的 X-Real-IP,却配置成解析复杂的 X-Forwarded-For,也可能出现结果与应用侧不一致的情况。
real_ip_recursive决定如何处理多级代理
当 X-Forwarded-For 中存在多个地址时,real_ip_recursive 的作用非常关键。
假设:
X-Forwarded-For: 198.51.100.23, 203.0.113.10
并且 Nginx 实际连接到的负载均衡器地址是 10.20.0.5。
当可信范围同时包含负载均衡器和 CDN 时:
set_real_ip_from 10.20.0.0/16;
set_real_ip_from 203.0.113.0/24;
real_ip_header X-Forwarded-For;
real_ip_recursive on;
Nginx 会从地址链右侧向左查找,跳过可信代理地址,最终选择最后一个不在可信范围内的地址,也就是:

198.51.100.23
如果只配置了负载均衡器网段,没有配置 CDN 网段:
set_real_ip_from 10.20.0.0/16;
real_ip_header X-Forwarded-For;
real_ip_recursive on;
那么 203.0.113.10 会被视为链中最后一个不可信地址,Nginx 可能把 CDN 地址当成客户端地址。
在多级代理链中,通常应使用:
real_ip_recursive on;
如果只有一个明确可信的上游,且上游传递的是单个客户端地址,递归开关对结果的影响可能不明显。但不应在不了解链路的情况下依赖默认值。
一个适合多级 HTTP 代理的配置示例
以下配置用于说明逻辑,示例网段不是实际服务商地址:
http {
log_format realip_check
'$time_iso8601 '
'peer=$realip_remote_addr '
'remote=$remote_addr '
'xff="$http_x_forwarded_for" '
'x_real_ip="$http_x_real_ip" '
'request="$request" '
'status=$status';
access_log /var/log/nginx/access.log realip_check;
# 直接连接到本机的负载均衡器
set_real_ip_from 10.20.0.0/16;
# 多级链路中的 CDN 出口范围,仅为示例
set_real_ip_from 203.0.113.0/24;
real_ip_header X-Forwarded-For;
real_ip_recursive on;
server {
listen 80;
server_name example.test;
location / {
proxy_pass http://app_backend;
# 传给应用的 $remote_addr 已经经过 Real IP 处理
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $host;
}
}
}
这里需要注意:$proxy_add_x_forwarded_for 会在原有请求头后追加当前地址。如果当前 Nginx位于公网入口,且它并没有经过可信上游校验客户端传入的请求头,应先在信任边界清理外部输入,而不是无条件把客户端自带的 X-Forwarded-For 继续向后传递。
例如,公网入口负责建立第一层可信链时,可以考虑:
location / {
proxy_pass http://app_backend;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header Host $host;
}
内部代理已经完成可信链校验、并且确实需要保留已有链路时,再使用 $proxy_add_x_forwarded_for。具体选择要以“哪个节点是信任边界”为准。
最容易出现的配置不生效或冲突
只信任了内层负载均衡器
这是多级代理环境中很常见的问题。
配置可能是:
set_real_ip_from 10.20.0.0/16;
real_ip_header X-Forwarded-For;
real_ip_recursive on;
但实际链路是:
客户端 → CDN → 负载均衡器 → Nginx
Nginx 虽然信任了负载均衡器,却没有信任 CDN。结果是:
客户端 IP:198.51.100.23
CDN IP:203.0.113.10
Nginx 对端:10.20.0.5
最终 $remote_addr 可能是 203.0.113.10,而不是 198.51.100.23。
这种问题一般表现为:
- 所有用户看起来都来自少数几个 CDN 地址;
- 限流按 CDN 地址聚合,正常用户互相影响;
- 地理位置判断集中在 CDN 机房;
- 应用日志和 CDN 日志中的客户端 IP 对不上。
把可信范围写成全网段
以下配置风险很高:
set_real_ip_from 0.0.0.0/0;
set_real_ip_from ::/0;
real_ip_header X-Forwarded-For;
real_ip_recursive on;
这相当于告诉 Nginx:任何来源的请求都可以被视为可信代理。攻击者直接发送:
X-Forwarded-For: 10.0.0.8
或者:
X-Forwarded-For: 198.51.100.99
Nginx 就可能把伪造的地址写入 $remote_addr。
风险不只是访问日志不准确,还可能影响:
- 依赖
$remote_addr的allow、deny访问控制; limit_req_zone、应用限流和登录失败计数;- 黑名单、风控规则和异常检测;
- 审计日志及安全事件追踪;
- 应用框架对“客户端 IP”的进一步信任。
内网网段也不代表天然安全。例如把整个 10.0.0.0/8 设为可信,可能会把同一网络中不相关的容器、租户或其他服务都纳入信任范围。应尽量使用实际负载均衡器的地址或较小 CIDR,而不是因为地址属于私网就整体放行。
X-Real-IP与X-Forwarded-For同时存在
部分系统同时配置:
real_ip_header X-Real-IP;
又在上游传递:
X-Forwarded-For: 198.51.100.23, 203.0.113.10
此时 Nginx只会按照 real_ip_header 指定的来源工作,不会自动在两个请求头之间“选择看起来更真实的一个”。
排查时应确认:
- 直接连接 Nginx的上游实际发送了哪个请求头;
- 中间代理是否覆盖、追加或删除了该请求头;
- Nginx的
real_ip_header是否与链路格式一致; - 应用是否又用另一套规则解析原始
X-Forwarded-For。
把HTTP头配置和PROXY protocol混用
PROXY protocol不是普通的 HTTP 请求头。如果负载均衡器使用 PROXY protocol,Nginx监听端通常需要明确启用:
server {
listen 443 ssl proxy_protocol;
real_ip_header proxy_protocol;
server_name example.test;
}
这要求上游和监听端配置一致。上游只发送普通 HTTP 请求头,却在 Nginx监听端启用了 proxy_protocol,请求可能无法正常解析;上游发送 PROXY protocol,而 Nginx按 X-Forwarded-For读取,则可能完全得不到预期的客户端地址。
使用 PROXY protocol 的监听端也不应直接暴露给任意公网客户端。因为连接协议本身包含来源地址字段,监听端应只接受已知负载均衡器或代理的连接。真实 IP配置不能替代网络入口隔离。
用有效配置和日志确认问题位置
排查不要先改参数,先确认 Nginx真正加载了什么配置。
第一步:检查模块和生效配置
先查看编译参数:
nginx -V 2>&1 | grep -- '--with-http_realip_module'
如果没有看到对应模块参数,或者配置测试报出 unknown directive,应先确认当前发行版的 Nginx是否包含或加载了 Real IP 模块,不要继续猜测配置写法。
再检查完整展开后的配置:
sudo nginx -T > /tmp/nginx-effective.conf
重点搜索:
grep -nE 'set_real_ip_from|real_ip_header|real_ip_recursive|proxy_protocol' \
/tmp/nginx-effective.conf
nginx -T 比直接查看某个主配置文件更可靠,因为真实配置经常通过 include 拆分到多个目录。需要重点确认:
- 是否存在旧的
real_ip_header; set_real_ip_from是否只出现在某个没有被实际请求使用的server块;location或其他配置层级是否覆盖了预期值;- 同一监听端是否同时出现 HTTP 头和 PROXY protocol 两套方案;
- IPv4 配置是否遗漏了实际使用的 IPv6 代理地址。
修改前应保存主配置及相关 include 文件。确认语法无误后再加载:
sudo nginx -t
sudo nginx -s reload
如果服务器由 systemd 管理,也可以使用对应的服务重载命令。若测试失败,不要强制重载;若重载后业务异常,应恢复备份配置,再执行 nginx -t 和重载。真实环境中最好先在测试实例或灰度节点验证。
第二步:比较原始对端和处理后地址
临时或长期保留一份用于排查的日志格式:
log_format realip_check
'$time_iso8601 '
'peer=$realip_remote_addr '
'remote=$remote_addr '
'xff="$http_x_forwarded_for" '
'x_real_ip="$http_x_real_ip" '
'request="$request" '
'status=$status';
一次请求中应同时观察:

peer:实际连接 Nginx的地址;remote:Real IP模块处理后的地址;xff:Nginx实际收到的完整X-Forwarded-For;x_real_ip:是否存在另一个可能冲突的地址来源。
典型结果可以按下表判断:
| 测试场景 | peer | 请求头示例 | 可信范围和递归设置 | 预期 remote |
|---|---|---|---|---|
| 直接访问,伪造 XFF | 实际测试机地址 | X-Forwarded-For: 198.51.100.99 | 测试机不在可信范围 | 仍为实际测试机地址 |
| 单级负载均衡 | 10.20.0.5 | X-Forwarded-For: 198.51.100.23 | 信任 10.20.0.0/16 | 198.51.100.23 |
| CDN 加负载均衡 | 10.20.0.5 | 198.51.100.23, 203.0.113.10 | 两段代理都可信,递归开启 | 198.51.100.23 |
| 只信任负载均衡 | 10.20.0.5 | 198.51.100.23, 203.0.113.10 | 未信任 CDN | 可能为 203.0.113.10 |
| 全范围信任 | 任意地址 | X-Forwarded-For: 198.51.100.99 | 0.0.0.0/0 等 | 可能被伪造成请求头地址 |
测试应尽量在测试环境、内网源站或灰度节点进行。直接对公网生产源站发送自定义头,可能会经过 CDN再次改写,无法证明源站配置本身正确。
例如,仅用于验证“非可信来源不能覆盖地址”的请求可以是:
curl -H 'X-Forwarded-For: 198.51.100.99' \
https://test.example/
请求完成后查看 Nginx日志,而不是只看页面返回结果。如果 peer 是测试机本身,且该地址不在可信范围,remote 不应变成请求头中的 198.51.100.99。
第三步:检查传给应用的地址
Nginx日志正确,不代表应用一定正确。若反向代理配置如下:
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
应用收到的 X-Real-IP 应与 Nginx处理后的 $remote_addr一致。
如果应用框架仍然从原始 X-Forwarded-For 的第一个值读取地址,或者把所有上游都标记为可信,就可能出现:
Nginx日志:198.51.100.23
应用日志:10.0.0.8
或者:
Nginx日志:198.51.100.23
应用日志:攻击者自带的伪造地址
因此,应同时对照 Nginx访问日志、应用访问日志和上游代理日志,确认每一跳对请求头的修改规则一致。应用框架中的“信任代理数量”或“可信代理网段”也应按同一链路设置,不能简单选择“信任所有代理”。
Nginx真实 IP处理常见于网站入口、业务后台和接口服务的部署链路。A5数据提供香港、美国、日本、韩国、中国台湾、新加坡及马来西亚等地区的物理服务器,覆盖不同CPU、内存、存储与网络配置,可承载Nginx入口及其连接的应用、数据库等业务组件,为不同地区的服务部署提供相应资源基础。
配置范围和安全边界
可信范围应覆盖代理链,但不应覆盖客户端
确定范围时,可以按以下顺序核对:
- 查看 Nginx日志中的
$realip_remote_addr,确认直接连接者是谁。 - 向上游负载均衡器或 CDN确认实际出口地址范围。
- 把链路中确实会直接连接当前 Nginx的代理加入可信范围。
- 对 IPv4和IPv6分别核对,不要只配置其中一种。
- 删除不再使用的旧网段和过宽网段。
- 在日志中验证代理地址变化后,结果是否仍符合预期。
如果代理地址会变化,可信范围需要有维护机制。静态配置长期不更新,会导致真实 IP突然变成 CDN或负载均衡器地址;但为了省事把整个公网地址空间加入信任范围,则是用安全风险换取短期可用性。
真实 IP不等于真实用户身份
即使配置完全正确,客户端 IP也不一定对应一个具体个人:
- 多个用户可能通过同一个企业出口或运营商 NAT;
- 移动网络可能在请求期间更换出口;
- IPv6隐私地址可能定期变化;
- 代理、缓存和边缘网络可能代表大量终端访问源站;
- 自动化程序和正常用户都可能共享同一个出口地址。
因此,IP适合用于访问日志、粗粒度限流和网络层判断,但不应单独作为身份认证、账号归属或高风险操作授权依据。
适用范围
上述方法主要适用于 Nginx HTTP/HTTPS 反向代理场景。若使用的是 Nginx Stream 模块处理非 HTTP TCP流量,不能直接照搬 HTTP请求头配置;应根据实际协议和对应模块检查地址传递方式。
最终判断可以归纳为两条:
- 配置不生效:先看
$realip_remote_addr、实际收到的请求头和nginx -T展开的有效配置,通常能定位到上游地址、请求头名称或配置层级不一致。 - 配置有安全风险:重点检查
set_real_ip_from是否过宽、源站是否可被非可信来源直接访问,以及应用是否再次无条件信任X-Forwarded-For。
只有当“直接连接的代理地址可验证、代理链头部可解释、可信范围足够小、Nginx与应用解析规则一致”时,日志中的客户端 IP才适合被当作可信的来源信息。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/5606.html



