在Nginx反向代理或CDN回源架构中,源站服务器默认的日志记录通常只包含$remote_addr,这个变量保存的是与Nginx建立TCP连接的对端地址。当请求经过一层或多层代理时,$remote_addr就会变成最近一级代理的IP,而不是最初客户端的真实IP。比如客户端访问CDN节点,CDN回源到Nginx源站,Nginx日志中记录的往往是CDN节点的IP。生产环境排查攻击来源、统计用户地域时,这种日志会带来严重干扰。要解决这个问题,业界普遍使用X-Real-IP请求头来传递真实客户端IP,但传递和记录两个环节都必须配置正确,否则仍然拿不到期望的结果。

为什么Nginx日志默认记录不到真实IP
Nginx核心变量$remote_addr表示建立TCP连接的对端地址,它只反映当前这一跳是谁发起的连接。在简单的客户端直连Nginx场景中,$remote_addr就是客户端IP,日志没有问题。但只要前面有任何代理,无论是自建的反向代理、负载均衡器还是CDN边缘节点,$remote_addr就会被替换成该代理的IP。比如客户端IP是203.0.113.10,经过一台192.168.1.5的Nginx代理,再回源到源站,源站日志中的$remote_addr只会是192.168.1.5,203.0.113.10这个真实地址已经丢失。
要找回真实IP,需要在代理链路上逐层传递原始地址。X-Real-IP就是早期出现的一种约定:上游代理在转发请求时,把客户端的真实IP写进名为X-Real-IP的HTTP请求头,源站读取这个头就能获得真实IP。这个头不是RFC标准,但被Nginx、Apache以及许多CDN厂商广泛支持。Nginx并不会自动设置或解析X-Real-IP,必须通过配置显式完成。同时,即便代理正确设置了X-Real-IP,如果源站日志格式仍然只输出$remote_addr,真实IP也不会出现在日志里,因为Nginx不会主动把任意请求头写入日志文件。
理解了这个基础之后,问题就变成两个独立动作:第一,在中间代理上把真实IP塞进X-Real-IP头;第二,在源站日志格式中引用这个头对应的变量。两个步骤缺一不可,这也是很多配置只做了第一步却依然看不到效果的原因。
传递X-Real-IP的正确配置
在Nginx反向代理配置中,可以用proxy_set_header指令把客户端IP写入X-Real-IP头。该指令需要放在location或server上下文中,且必须与proxy_pass位于同一层级,否则可能无法生效。最基本的配置写法如下,上游代理会把当前连接的对端地址$remote_addr作为X-Real-IP的值发送给后端源站。
server {
listen 80;
server_name ipipp.com;
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_pass http://backend;
}
}
这里使用$remote_addr是因为在当前代理这一跳中,它正是客户端或上一级代理的真实IP。如果存在多级代理,每一级都应该执行类似的覆盖操作,最终源站拿到的就是原始客户端IP。需要注意的是,proxy_set_header默认会继承,如果在server级别设置了,location级别不覆盖则沿用。但如果某个location中重新定义了proxy_set_header,它会覆盖继承值,建议在需要传递头的地方都显式写出完整集合。
除了X-Real-IP,实践中往往会同时传递X-Forwarded-For。后者用于记录完整的代理链,而X-Real-IP只保存最后一个客户端IP。两者配合可以更灵活地追溯来源。不过X-Real-IP的实现更简单,日志可读性也更强,特别适合只有一级代理或明确需要单一真实IP的场景。
调整日志格式输出真实IP
源站Nginx默认的log_format通常使用combined或main,其中第一个字段是$remote_addr。要让日志显示X-Real-IP头中的真实地址,需要把该头对应的变量$http_x_real_ip加入日志格式。Nginx会把任意HTTP头转换成小写并用下划线替换连字符,因此X-Real-IP对应的变量就是$http_x_real_ip。
下面是一个调整后的日志格式示例,末尾追加了$http_x_real_ip字段。该字段在日志中会显示为空字符串(短横线或空值)如果没有该头,但这不影响有头场景下的记录。
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_real_ip"';
access_log /var/log/nginx/access.log main;
经过这样的配置,源站日志中每一行的最后一个字段就会输出X-Real-IP的值。不过这里有一个细节:如果客户端或上游直接伪造了X-Real-IP头,$http_x_real_ip也会原样记录,可能误导分析。因此更稳妥的做法是先利用Nginx的realip模块从可信代理的头中提取真实IP,然后把$remote_addr替换成真实IP,这样日志无需修改格式,继续使用$remote_addr即可。
realip模块的典型配置是使用set_real_ip_from指定可信代理的IP段,再用real_ip_header告诉Nginx从哪个头中解析真实IP。配置完成后,$remote_addr会变成真实客户端IP,而原始代理IP可以通过其他变量获取。这种方式把安全校验和日志标准化统一处理,推荐在生产环境使用。
防止伪造X-Real-IP与多层代理安全加固
X-Real-IP头的最大风险在于它非常容易被伪造。任何客户端都可以在请求中自行携带一个X-Real-IP头,而Nginx默认不会过滤,代理转发时如果不覆盖,后端拿到的$http_x_real_ip就可能是伪造值。例如攻击者直接发送X-Real-IP: 127.0.0.1,源站日志就会错误记录为本地地址,干扰审计和封禁策略。
避免这个问题的方法是不信任任何未经校验的请求头。在代理层必须始终用proxy_set_header X-Real-IP $remote_addr覆盖原有头,这样无论客户端是否伪造,最终值都来自可信的连接层。同时,在源站侧还可以使用安全指令进一步收紧来源,只接受指定IP段的代理传递过来的头。以下配置演示了如何启用realip模块并限制可信代理范围。
set_real_ip_from 10.0.0.0/8; set_real_ip_from 172.16.0.0/12; set_real_ip_from 192.168.0.0/16; real_ip_header X-Real-IP; real_ip_recursive on;
这段配置告诉Nginx:只有来自10.0.0.0/8、172.16.0.0/12和192.168.0.0/16这些私有网段的请求,才允许使用X-Real-IP头替换$remote_addr。real_ip_recursive on在多级代理时特别有用,它会从右向左递归解析头中的IP列表,直到找到第一个不在可信范围内的地址,避免内部代理地址混入真实IP。这样即使客户端伪造了X-Real-IP,由于连接来自不可信地址,头会被忽略,$remote_addr保持原始TCP连接地址。
与X-Real-IP相比,X-Forwarded-For更适合记录完整代理链,但也更容易被伪造和解析出错。X-Forwarded-For的值是一个逗号分隔的IP列表,最左边通常是客户端原始IP,后面依次是各代理IP。Nginx通过$proxy_add_x_forwarded_for可以正确追加,但解析时需要额外的拆分逻辑。如果只需要记录单一真实IP,X-Real-IP配合realip模块已经足够;如果需要完整的链路追踪,则建议同时传递X-Forwarded-For,并在源站做同样的可信代理校验。总体思路是:不信任任何未经校验的头部信息,所有真实IP都从可信代理的连接层或经过验证的头中提取。这样配置出的日志才具备可靠性和审计价值。