导读:本期聚焦于半夏创作的《Nginx回源时如何让日志准确记录X-Real-IP真实IP?》,敬请观看详情。为什么Nginx反向代理后,源站日志中的客户端IP总是显示为代理服务器地址?根本原因在于日志格式只记录了连接层的$remote_addr,没有读取X-Real-IP请求头。X-Real-IP本身只是一个非标准头,需要上游代理明确设置,源站才能拿到真实地址。本文从代理传递链路出发,演示如何用proxy_set_header将客户端IP写入X-Real-IP,并调整log_format让日志输出真实IP。同时讨论多层代理下如何防止伪造X-Real-IP,以及set_real_ip_from等安全指令的用法。还会对比X-Real-IP与X-Forwarded-For的差异,帮助你在CDN回源、负载均衡等场景中设计可靠的IP记录方案。读完你会掌握完整的配置思路,避免只改一句配置却仍然记录不到真实IP的常见坑。

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

Nginx回源时如何让日志准确记录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都从可信代理的连接层或经过验证的头中提取。这样配置出的日志才具备可靠性和审计价值。

NginxX-Real-IP真实IP修改时间:2026-10-31 03:01:42

免责声明:已尽一切努力确保本网站所含信息的准确性。网站作品多为原创整理与精心创作,观点力求客观中立。本站旨在免费分享,内容仅供个人学习、研究或参考使用。若引用了第三方作品,版权归原作者所有。如内容涉及您的权益,请联系我们进行处理Email:chomcom@qq.com。
引用或转载本作品时,请注明当前出处:https://www.ipipp.com/html/1031/71450.html,基于非商业用途的前提下,欢迎转载或二创本作品。
内容垂直聚焦
专注技术核心技术栏目,确保每篇文章深度聚焦于实用技能。从代码技巧到架构设计,为用户提供无干扰的纯技术知识沉淀,精准满足专业提升需求。
知识结构清晰
覆盖从开发到部署的全链路。AI、前端、编程、数据库、服务器、建站、系统层层递进,构建清晰学习路径,帮助用户系统化掌握开发与运维所需的核心技术。
深度技术解析
拒绝泛泛而谈,深入技术细节与实践难点。无论是数据库优化还是服务器配置,均结合真实场景与代码示例进行剖析,致力于提供可直接应用于工作的解决方案。
专业领域覆盖
精准对应开发生命周期。从前端界面到后端编程,从数据库操作到服务器运维,形成完整闭环,一站式满足全栈工程师和运维人员的技术需求。
即学即用高效
内容强调实操性,步骤清晰、代码完整。用户可根据教程直接复现和应用于自身项目,显著缩短从学习到实践的距离,快速解决开发中的具体问题。
持续更新保障
专注既定技术方向进行长期、稳定的内容输出。确保各栏目技术文章持续更新迭代,紧跟主流技术发展趋势,为用户提供经久不衰的学习价值。