在单机直连的年代，Nginx日志里的remote_addr就是客户端的真实IP，拿来统计、封禁都没问题。但一旦链路中出现CDN、负载均衡、NAT网关，或者客户端走HTTP/3（QUIC）协议接入，日志里记录的就变成了上一跳设备的地址。更麻烦的是，NAT穿透场景下同一个公网IP背后可能挂着成百上千个用户，一旦拿错IP，风控和审计都会出大问题。本文围绕这几个场景，把Nginx日志中真实IP的获取方案讲透。
一、remote_addr为什么会失真：先搞清楚链路结构
remote_addr记录的是与Nginx直接建立TCP（或QUIC）连接的对端地址，这是内核层面的信息，理论上不可伪造。问题在于，与Nginx直接通信的往往不是最终用户，而是中间的代理设备。比如典型的三层结构：客户端先连CDN边缘节点，CDN再回源到自家负载均衡，负载均衡最后把请求转给Nginx。这时候Nginx看到的remote_addr是负载均衡的内网IP，日志的价值大打折扣。
NAT穿透带来的麻烦更进一步。运营商级NAT（CGNAT）会让大量用户共享少量公网IP，如果中间某一层把连接信息抹掉了，即使你拿到了公网IP，也无法区分具体用户。所以业界通用做法是让代理层通过HTTP头传递真实IP，最常见的两个头是X-Forwarded-For和X-Real-IP。X-Forwarded-For是一个逐跳追加的列表，格式为客户端IP依次加上每一层代理的IP；X-Real-IP则通常由第一层代理写入，只保留最终客户端地址。
需要注意的是，这两个头都是可以伪造的。如果客户端直连你的Nginx并自己带上一个假的X-Forwarded-For，而你不加判断地信任这个头，攻击者就可以随意污染你的日志，绕过基于IP的风控。所以正确姿势是：只信任来自已知代理IP的转发头，直连请求一律以remote_addr为准。
二、用realip模块还原真实IP并写入日志
Nginx内置的ngx_http_realip_module可以按需把remote_addr重写为可信代理传来的地址，这样后续的日志、限流、access控制全部自动生效，不需要在每个地方单独读头。核心指令有三个：set_real_ip_from指定信任的代理网段，real_ip_header指定从哪个头取值，real_ip_recursive控制多级代理时的回溯行为。
http {
# 日志格式中直接使用还原后的 remote_addr
log_format main '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" '
'fwd="$http_x_forwarded_for" proto="$server_protocol"';
server {
listen 443 ssl;
listen 443 quic reuseport; # 同时监听 HTTP/3 (QUIC)
# 只信任来自这些网段的代理
set_real_ip_from 10.0.0.0/8;
set_real_ip_from 192.168.1.0/24;
set_real_ip_from 203.0.113.0/24; # CDN 回源网段
real_ip_header X-Forwarded-For;
real_ip_recursive on; # 多级代理时从右往左剔除可信IP
access_log /var/log/nginx/access.log main;
}
}real_ip_recursive的语义值得展开说一下。关闭时，Nginx取X-Forwarded-For的最后一个IP；开启时，会从列表末尾开始，把属于set_real_ip_from信任网段的IP逐个剔除，剩下的第一个不可信IP才是真实客户端。举个例子，头内容为1.2.3.4, 10.0.0.8, 10.0.0.9，信任网段是10.0.0.0/8，那么还原结果就是1.2.3.4。这个机制同时兼顾了多级代理和防伪造：伪造者插入的假IP位于列表左侧，但如果客户端直连（来源IP不可信），整个头都会被忽略。
日志层面建议同时保留$http_x_forwarded_for原始值和还原后的$remote_addr，排查争议时可以对照链路，确认每一跳是否正确追加了地址。
三、HTTP/3与QUIC回源时的特殊处理
HTTP/3基于QUIC运行在UDP之上，与TCP的处理路径有明显差异。Nginx从1.25.0开始正式支持HTTP/3，监听QUIC端口后，客户端直连场景下remote_addr同样准确。真正的问题出在回源链路：大多数CDN的边缘节点对外提供HTTP/3服务，但回源到源站时仍然使用HTTP/1.1或HTTP/2 over TCP。这意味着源站Nginx看到的协议和客户端使用的协议不一致，$server_protocol记录的是回源协议而非客户端协议。
如果需要知道客户端到底用的是h3还是h2，只能依赖CDN回源时透传的头，例如X-Forwarded-Proto或部分厂商自定义的协议头。在日志格式里加上$http_x_forwarded_proto字段即可留存这个信息。另外，QUIC连接迁移特性允许客户端在切换网络（比如从Wi-Fi切到蜂窝）时保持连接不变，Connection ID不变但源端口可能变化，这会导致同一用户的请求看起来来自不同的五元组。如果你在日志里用$connection或四元组做会话聚合，需要注意这一点，更稳妥的做法是按QUIC Connection ID或会话Cookie聚合。
还有一种做法是在Nginx前启用QUIC反向代理层（或使用支持QUIC的负载均衡），代理与源站之间通过PROXY protocol v2传递连接信息。PROXY protocol在TCP层传输原始客户端地址，不依赖HTTP头，天然免疫头伪造，也支持传递UDP/QUIC场景的地址信息。
四、NAT穿透场景与PROXY protocol方案
当Nginx前面是L4负载均衡或端口映射网关时，代理工作在四层，根本没有机会修改HTTP头。此时经典方案是PROXY protocol：代理在TCP连接建立后先发送一行明文头，包含客户端真实IP、端口和代理自身地址，Nginx解析后将其作为remote_addr使用。
server {
listen 80 proxy_protocol; # 声明该端口流量带 PROXY protocol 头
set_real_ip_from 10.0.0.0/8; # 仍然只信任代理网段
log_format pp '$remote_addr:$remote_port -> $server_addr '
'proxy=$proxy_protocol_addr:$proxy_protocol_port '
'"$request" $status';
access_log /var/log/nginx/pp_access.log pp;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header X-Real-IP $proxy_protocol_addr;
}
}配置时最容易踩的坑是两端不一致：上游开启了PROXY protocol而Nginx没配proxy_protocol参数，那行明文头会被当成HTTP请求的第一行，Nginx返回400错误；反过来Nginx等头、上游不发，请求会挂起直到超时。启用前务必在测试环境验证，或者按端口灰度切换。PROXY protocol v2是二进制格式，除了地址还能传递TLV扩展信息，比如是否经过加密、后端协议类型等，对QUIC和NAT场景更友好。
关于NAT穿透本身还要提醒一点：如果你的业务涉及P2P打洞，Nginx只是旁路的信令或日志服务，真正要记录的是STUN服务器观察到的映射地址（公网IP加端口）。这套数据可以通过应用层接口写入Nginx无法覆盖的独立日志，不要试图在Nginx日志里还原它，层次不同，信息本来就不在那里。
五、验证与故障排查清单
配置完成后不要急着上线，先用curl模拟多级代理验证日志输出：
# 模拟带伪造头的直连请求，日志应记录你的真实IP curl -H 'X-Forwarded-For: 8.8.8.8' https://ipipp.com/test # 通过可信代理访问，日志应还原为代理前的真实地址 curl --proxy http://10.0.0.8:3128 https://ipipp.com/test
排查时按顺序检查这几项：第一，确认set_real_ip_from覆盖了所有可信代理的实际出口IP，云厂商的负载均衡网段可能不在你预期的范围内；第二，检查real_ip_recursive与X-Forwarded-For追加顺序是否匹配，CDN追加在最左还是最右直接影响还原逻辑；第三，HTTP/3请求用浏览器开发者工具的Protocol列确认是否真的走了h3，避免把回源协议当成客户端协议来排查；第四，UDP 443端口是否在防火墙和Nginx的quic监听上都已放行。
最后给一个稳定性建议：真实IP的还原逻辑直接影响风控与封禁，任何上游架构变更（更换CDN、扩容负载均衡网段）都要同步更新set_real_ip_from，并把它纳入变更检查清单。日志里多留存一份原始转发头，等于给未来的自己留下排障的证据链。