Nginx 正确还原客户端真实 IP 的关键是配置可信代理 IP 段（set_real_ip_from）、选择合适请求头（real_ip_header）并启用递归解析（real_ip_recursive on），同时后端服务需适配读取校验后的 IP。
要让 Nginx 正确还原客户端真实 IP，核心不是“加头”，而是“信任谁”——set_real_ip_from 就是明确告诉 Nginx：哪些 IP（或网段）发来的请求，才允许从它们带的 X-Forwarded-For 或 X-Real-IP 头里取真实 IP。
必须填对可信代理的出口 IP 段
CDN、WAF、负载均衡器、前置 Nginx 或 Kubernetes Ingress Controller 都会作为反向代理转发请求，它们的出口 IP 才是 Nginx 的直接上游。这些 IP 必须逐行写进 set_real_ip_from，不能漏、不能错、不能写成 0.0.0.0/0。
- Cloudflare 用户可直接用官方 IPv4/IPv6 网段（如
173.245.48.0/20、2405:b500::/32），共约 15 行 IPv4 + 若干 IPv6 - 腾讯云 CDN、阿里云全站加速、华为云 CDN 等，需登录控制台，在“回源节点”或“节点 IP 查询”页面导出最新 IP 段列表，按 CIDR 格式粘贴
- 自建集群中若经过 Service ClusterIP（如
10.96.0.0/12）或 NodePort 节点，这些网段也必须加入，否则日志里全是内网地址
选对 header 并开启递归解析
real_ip_header 决定从哪个 HTTP 头读原始 IP；real_ip_recursive on 决定怎么从一长串逗号分隔的 IP 中挑出最左边那个真实的用户 IP。
- 如果上游只有一层代理（比如纯 CDN 回源），
real_ip_header X-Real-IP更简洁可控；若有多层（CDN → LB → Nginx），优先用X-Forwarded-For -
real_ip_recursive on是生产环境推荐配置：它从右往左剔除所有已声明为可信的 IP，把第一个不被信任的 IP 当作真实客户端 IP - 例如请求头是
X-Forwarded-For: 203.0.113.42, 198.51.100.2, 192.0.2.1，你只信任192.0.2.0/24，开启递归后取到的就是203.0.113.42
验证是否生效的三步法
改完配置别急着 reload，先本地模拟测试再上线，避免日志失真或限流误判。
- 用 curl 模拟多级代理头：
curl -H "X-Forwarded-For: 8.8.8.8, 192.168.1.100" http://your-site/，检查 access log 中$realip_remote_addr是否为8.8.8.8 - 查看 error log，出现
ignoring invalid real IP address说明某段 XFF 解析失败，大概率是某个代理出口 IP 没写进set_real_ip_from - 确认日志格式使用的是
$realip_remote_addr而非$remote_addr；后者始终是上一跳连接 IP，不可用于溯源
后端服务也要配合读取
Nginx 只负责“解包”和“赋值”，后端应用默认仍读取 REMOTE_ADDR（即 Nginx 自身 IP）。必须显式切换为读取经 realip 模块校验后的值：
- Java Spring Boot：启用
server.forward-headers-strategy=framework，并设置TomcatServletWebServerFactory.setRemoteIpHeader("X-Real-IP") - Python Flask：用
ProxyFix(app, x_for=1, x_proto=1)，或指定trusted_hosts - Node.js Express：
app.set('trust proxy', true)，并确保 Nginx 已透传X-Forwarded-For和X-Forwarded-Proto - 通用 fallback 逻辑：优先读
HTTP_X_REAL_IP，其次取HTTP_X_FORWARDED_FOR中首个公网非私有 IP，最后才用REMOTE_ADDR
