Nginx日志记录的客户端IP变成代理地址,服务器该检查哪些转发配置?
如果 Nginx access log 中的 $remote_addr 变成了 CDN、负载均衡或上一层反向代理的地址,通常不是客户端 IP 消失,而是 Nginx 只记录了与它建立 TCP 连接的最后一跳。需要重点检查上游是否传递了 X-Forwarded-For 或 PROXY protocol,以及 Nginx 是否通过 ngx_http_realip_module 正确解析这些信息。
排查顺序应当是:先确认实际请求经过哪些层,再检查转发层是否写入客户端地址,随后核对 Nginx 的 set_real_ip_from、real_ip_header 和 real_ip_recursive,最后确认 log_format、上游应用和监听端口没有使用错误的变量或协议。不能简单把 $http_x_forwarded_for 当作真实来源,因为该请求头可能被客户端自行伪造。
先确认日志里的“代理地址”来自哪一跳
Nginx 的 $remote_addr 默认表示与当前 Nginx 建立连接的对端地址。链路如果是:
客户端 → CDN → 负载均衡 → Nginx → 应用服务器
那么 Nginx 默认看到的通常是负载均衡地址,而不是客户端地址。
先查看当前日志格式,确认日志中到底记录了哪个变量:
sudo nginx -T 2>&1 | grep -nE 'log_format|access_log|remote_addr|realip_remote_addr|http_x_forwarded_for'
nginx -T 会展开主配置文件和 include 文件,适合确认实际生效的配置。输出可能包含证书路径、认证信息或其他敏感配置,只应在受控终端查看,不要直接复制到公开工单或聊天窗口。
常见变量含义如下:
| 变量 | 含义 | 是否适合直接作为真实客户端 IP |
|---|---|---|
$remote_addr | Nginx 当前识别出的客户端地址;启用 realip 后可能被改写 | 通常适合 |
$realip_remote_addr | realip 改写前的连接对端地址 | 适合确认上一跳是谁 |
$http_x_forwarded_for | 原始 HTTP 请求中的 X-Forwarded-For 内容 | 不能单独信任 |
$http_x_real_ip | 原始 HTTP 请求中的 X-Real-IP 内容 | 不能单独信任 |
$proxy_protocol_addr | PROXY protocol 提供的地址 | 仅适用于已启用该协议的链路 |
如果当前日志只有 $remote_addr,建议临时增加一份专用诊断日志,同时记录原始对端、解析后的地址和转发请求头。示例配置应放在 http 配置块中,日志路径和格式名称需要避开现有重复定义:
log_format realip_debug
'$remote_addr '
'realip_remote=$realip_remote_addr '
'proxy_protocol_addr=$proxy_protocol_addr '
'xff="$http_x_forwarded_for" '
'x_real_ip="$http_x_real_ip" '
'"$request" status=$status';
access_log /var/log/nginx/access_realip_debug.log realip_debug;
$realip_remote_addr 在较新的 Nginx 版本中可用。如果执行 nginx -t 时提示变量未知,应先检查版本,不要为了通过检查而随意替换成未经确认的变量。
第一层:确认请求实际进入了哪个 Nginx
配置看起来正确但日志仍不变化时,常见原因是修改了错误的虚拟主机、错误的端口,或者请求根本没有进入预期的 Nginx 实例。
先查看监听端口和进程:
sudo ss -lntp | grep -E ':(80|443)\b'
再查看完整生效配置中有哪些 server、listen 和 server_name:
sudo nginx -T 2>&1 | grep -nE '^[[:space:]]*listen |^[[:space:]]*server_name |^[[:space:]]*access_log'
重点核对以下内容:
- HTTPS 请求是否命中了带有正确
server_name的虚拟主机; - 访问日志是否定义在当前请求实际命中的
server或location中; - 80 端口和 443 端口是否使用了不同配置;
- 是否存在容器内 Nginx、宿主机 Nginx或其他网关同时监听不同端口;
- Nginx 是否运行在
http模式,还是仅在stream中做 TCP 转发。
如果 TLS 在上游设备终止,Nginx 接收的是 HTTP,那么可以解析 X-Forwarded-For。如果 Nginx 只做 TLS 透传或 TCP 转发,HTTP 请求头对它不可见,http 模块里的 real_ip_header X-Forwarded-For 不会解决问题,此时应检查 TCP 层的 PROXY protocol 或在真正终止 HTTP 的组件上处理客户端地址。
在多地区接入、CDN回源或多层 Nginx 部署场景中,A5idc数据提供中国香港、美国、日本、韩国、中国台湾、新加坡及马来西亚等地的物理服务器资源,可作为网站、接口服务和业务后台的源站基础。不同地区配备 CN2、国际及本地优化线路,并提供 SSD、NVMe、大内存和多IP等产品系列,便于承载日志记录、反向代理与跨区域访问架构。
第二层:确认上游是否真的转发了客户端地址
HTTP 请求头转发
如果上游是 CDN、负载均衡或另一台 Nginx,先确认它向当前服务器发送的请求中是否包含:
X-Forwarded-For: 198.51.100.24
X-Real-IP: 198.51.100.24
其中 198.51.100.24 只是文档示例地址,不代表任何真实访问来源。
如果上一层本身也是 Nginx,常见的转发配置类似:
location / {
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_pass http://backend;
}
这段配置的含义不是“自动验证真实 IP”,而是把当前 Nginx 看到的地址和已有的 X-Forwarded-For 链继续传递下去。只有在当前 Nginx 已经建立了可信边界时,才适合直接沿用完整的转发链。
如果公网客户端可以直接访问这台 Nginx,而配置又无条件保留客户端提交的 X-Forwarded-For,那么客户端可以自行发送:
X-Forwarded-For: 10.0.0.1
这并不能证明真实来源是 10.0.0.1。因此,应用的访问控制、限流和审计不能只读取未经验证的 $http_x_forwarded_for。
从外部发起一次不带伪造头的请求
在一台不属于 Nginx 服务器的测试机器上访问测试域名,不要手动添加 X-Forwarded-For:
curl -sS -o /dev/null -w 'status=%{http_code}\n' \
'https://test.example.com/health?trace=realip-check-001'
随后在 Nginx 日志中搜索 realip-check-001。这样可以把一次测试请求与日志对应起来。
结果可以这样判断:
- 日志中没有
X-Forwarded-For:优先检查 CDN、负载均衡或上一层反向代理的转发策略; - 有
X-Forwarded-For,但$remote_addr仍是负载均衡地址:继续检查 Nginx realip 模块和信任范围; $remote_addr已变成客户端地址,但应用日志仍是负载均衡地址:检查 Nginx 转发给应用的X-Real-IP、X-Forwarded-For以及应用自身的可信代理设置;$remote_addr变成了请求头中任意可控的地址:说明信任范围过宽、边界配置错误,或应用直接信任了原始请求头。
本地执行 curl -H 'X-Forwarded-For: 1.2.3.4' 只能验证服务器是否接受了一个人为构造的请求头,不能验证真实链路。它适合做安全性测试,不适合作为真实客户端 IP 的验收依据。
第三层:检查 Nginx realip 配置
确认模块是否存在
real_ip_header、set_real_ip_from 和 real_ip_recursive 依赖 realip 模块。先检查编译参数:
sudo nginx -V 2>&1 | grep -o -- '--with-http_realip_module'
如果没有输出,不代表一定不存在动态模块,还需要检查完整配置中是否有 load_module。最直接的判断方式是执行:
sudo nginx -t
如果提示 unknown directive "real_ip_header" 或类似错误,说明当前运行的 Nginx 没有加载相应模块,不能直接上线下面的配置。
典型的 HTTP 转发配置
当 Nginx 的直接上游是可信的负载均衡或 CDN,并且该设备通过 X-Forwarded-For 传递客户端地址时,配置通常类似:
http {
# 使用实际的负载均衡或 CDN 出口网段替换示例网段
set_real_ip_from 192.0.2.0/24;
set_real_ip_from 2001:db8:100::/48;
real_ip_header X-Forwarded-For;
real_ip_recursive on;
server {
listen 443 ssl;
server_name test.example.com;
access_log /var/log/nginx/access.log main;
location / {
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_pass http://backend;
}
}
}
这里最容易出错的是三个指令之间的关系:
set_real_ip_from定义哪些来源可以被信任;real_ip_header指定从哪个请求头或协议中取地址;real_ip_recursive on决定如何处理多级X-Forwarded-For链。
set_real_ip_from 应填写当前 Nginx 的直接上游地址范围,例如负载均衡的内网网段或 CDN 的官方出口网段。不要使用:
set_real_ip_from 0.0.0.0/0;
也不要为了“先让日志正常”而信任所有 IPv4 和 IPv6 地址。这样会使任意直连客户端都可能伪造日志中的来源地址,并进一步影响限流、黑名单、审计和安全策略。
real_ip_recursive 的判断方式
假设 Nginx 收到的连接对端是负载均衡,请求头为:
X-Forwarded-For: 198.51.100.24, 192.0.2.20
其中:
198.51.100.24表示客户端;192.0.2.20表示前一级 CDN;- 当前 TCP 对端是另一个已信任的负载均衡。
当所有相关代理网段都在 set_real_ip_from 中,并设置:
real_ip_recursive on;
Nginx 会从右向左检查地址,跳过可信代理地址,找到最左侧的非可信地址作为客户端地址。

如果 real_ip_recursive off,多级链路下通常只会使用请求头中更靠近当前 Nginx 的地址,容易把 CDN 或上一级负载均衡当成客户端。单层代理场景可能看不出差异,多层接入时则经常出现日志地址不一致。
配置冲突的常见位置
即使 http 块中配置正确,以下位置仍可能覆盖或改变结果:
- 某个
server中重新设置了real_ip_header; - 某个
location使用了不同的 realip 配置; - 实际命中的配置文件没有被
include; - 同一台服务器上存在多个 Nginx 实例;
access_log使用了另一个log_format;- 只修改了 80 端口配置,实际访问的是 443 端口;
- 上游应用接收的是
$proxy_protocol_addr或$http_x_real_ip,而不是$remote_addr。
因此,排查时应以 nginx -T 展开的有效配置为准,而不是只查看某个编辑过的片段文件。
第四层:区分 X-Forwarded-For 与 PROXY protocol
有些负载均衡不会通过 HTTP 请求头传递客户端地址,而是在 TCP 连接建立时发送 PROXY protocol。两者不是同一种配置。

如果负载均衡明确使用 PROXY protocol,Nginx 监听端口通常需要类似:
server {
listen 443 ssl proxy_protocol;
server_name test.example.com;
set_real_ip_from 192.0.2.0/24;
real_ip_header proxy_protocol;
real_ip_recursive on;
location / {
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass http://backend;
}
}
这里要同时满足两个条件:
- 上游设备确实发送 PROXY protocol;
- Nginx 的对应
listen端口确实启用了proxy_protocol。
如果只在 Nginx 上加了 proxy_protocol,但仍有客户端或其他设备直接连接该端口,连接可能失败,因为对方没有发送预期的 PROXY protocol 头。反过来,如果上游已经发送该协议,而 Nginx 没有启用,TLS 或 HTTP 解析也可能出现异常。
这类修改比普通 HTTP 请求头配置风险更高。上线前应确认负载均衡的监听器模式、协议版本以及实际后端端口,并准备回滚方案。不要在生产端口上同时猜测并切换多种协议。
如果链路采用 HTTP 头,应使用:
real_ip_header X-Forwarded-For;
如果链路采用 PROXY protocol,应使用:
real_ip_header proxy_protocol;
除非已经确认设备同时提供两套信息并明确了优先级,否则不要仅凭日志中出现了某个字段,就把两种模式混合配置。
根据结果分支定位问题
完成前面的检查后,可以按以下结果继续判断:
| 观察结果 | 更可能的原因 | 下一步 |
|---|---|---|
$realip_remote_addr 是负载均衡地址,$http_x_forwarded_for 为空 | 上游没有传递客户端地址,或使用了未确认的协议 | 检查上游监听器、回源策略和访问日志 |
X-Forwarded-For 有客户端地址,但 $remote_addr 仍是负载均衡地址 | realip 模块未加载、信任网段不匹配或配置未命中 | 检查模块、set_real_ip_from、虚拟主机和配置加载结果 |
$remote_addr 是 CDN 地址而不是客户端地址 | 多级链路下递归解析未启用,或 CDN 网段未加入信任范围 | 核对 real_ip_recursive on 和完整代理地址链 |
| Nginx 日志正确,应用日志错误 | proxy_set_header 未传递解析后的地址,或应用未信任 Nginx | 检查应用上游请求头和应用框架配置 |
| Nginx 日志中的地址可被自定义请求头改变 | 信任了过宽的来源范围,或日志直接记录原始头 | 收紧可信网段,改用 $remote_addr,限制源站直连 |
加入 proxy_protocol 后出现连接错误 | 上游没有发送该协议,或端口上存在非协议连接 | 恢复原监听方式,先确认负载均衡协议模式 |
| 配置修改后完全没有变化 | 修改了未加载文件、错误实例或错误 server | 使用 nginx -T 和监听端口重新确认实际路径 |
低风险修改与回滚方式
在修改前,先保存即将编辑的配置文件。下面的路径仅为示例,应替换成实际文件:
sudo cp -a /etc/nginx/conf.d/site.conf \
/etc/nginx/conf.d/site.conf.bak.$(date +%F-%H%M%S)
修改完成后先进行语法检查:
sudo nginx -t
预期结果应包含类似:
syntax is ok
test is successful
如果出现语法错误、变量未知、重复定义或证书路径错误,不要 reload,也不要继续扩大修改范围。先根据报错行号恢复配置或修正路径。
语法检查通过后,再平滑加载配置:
sudo systemctl reload nginx
没有 systemd 的环境可以使用:
sudo nginx -s reload
reload 通常不会立即中断已有连接,但仍应观察错误日志和业务请求。如果需要回滚,恢复此前备份的文件,然后再次执行检查和 reload:
sudo cp -a /etc/nginx/conf.d/site.conf.bak.YYYY-MM-DD-HHMMSS \
/etc/nginx/conf.d/site.conf
sudo nginx -t && sudo systemctl reload nginx
如果调整的是 listen ... proxy_protocol,应先与负载均衡侧协调切换窗口。回滚时也必须确认上游是否已经停止发送 PROXY protocol,否则单独恢复 Nginx 监听配置可能再次造成协议不匹配。
复测后保持观察
配置生效后,从外部测试机器发起一条不带自定义 IP 请求头的请求,并使用唯一查询参数进行关联:
curl -sS -o /dev/null -w 'status=%{http_code}\n' \
'https://test.example.com/health?trace=realip-check-002'
在诊断日志中,理想结果通常是:
$realip_remote_addr显示负载均衡或 CDN 的直接连接地址;$http_x_forwarded_for包含上游传来的地址链;$remote_addr显示经过可信规则解析后的客户端地址;- 应用收到的
X-Real-IP和X-Forwarded-For与 Nginx 的判断一致; - 直接绕过上游访问源站时,不会因为任意自定义请求头而获得可信客户端身份。
验证完成后,不建议长期保留包含完整转发头的高详细度诊断日志。可以保留 $remote_addr、$realip_remote_addr 和必要的请求标识,将原始 X-Forwarded-For 调试日志设置为临时配置或缩短保留周期。
后续还应持续观察访问日志、限流命中记录、后台审计记录和错误日志。如果 CDN 或负载均衡的出口网段发生调整,set_real_ip_from 也需要同步更新;如果源站仍可被公网直接访问,则应通过安全组、防火墙或网络边界限制来源,并避免让应用直接信任未经 Nginx 验证的客户端请求头。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/8527.html



