Nginx需通过RealIP模块三要素协同获取真实客户端IP：必须配置可信CDN回源网段（set_real_ip_from）、指定代理头字段（real_ip_header X-Forwarded-For或X-Real-IP）、启用递归解析（real_ip_recursive on），缺一不可，且严禁使用0.0.0.0/0导致安全风险。
要让 Nginx 从特定 CDN 的代理头正确提取客户端真实 IP，关键不是“读哪个头”，而是明确“信谁、从哪取、怎么验”。RealIP 模块本身不自动生效，必须三要素协同：可信来源（set_real_ip_from）、指定头部（real_ip_header）、递归解析逻辑（real_ip_recursive on）。
确认并配置可信 CDN 回源网段
CDN 厂商（如 Cloudflare、阿里云全站加速、腾讯云 CDN）都会公开其回源 IP 段。Nginx 必须只信任这些地址发来的 X-Forwarded-For 或 X-Real-IP，否则攻击者可伪造请求头绕过校验。
- 去对应 CDN 控制台或官方文档查最新回源网段（例如 Cloudflare 当前为
173.245.48.0/20、103.21.244.0/22等） - 在
http或server块中逐条写入，每段一行：set_real_ip_from 173.245.48.0/20;set_real_ip_from 103.21.244.0/22; - 严禁使用
0.0.0.0/0—— 这等于完全信任任意来源，存在严重安全风险
选择并声明代理传递的 IP 头字段
绝大多数 CDN 默认使用标准的 X-Forwarded-For（XFF），它天然支持多级代理链路；少数私有网关可能只设 X-Real-IP。优先选 XFF，除非明确知道 CDN 只填一个头。
- 在同级或外层
http块中添加：real_ip_header X-Forwarded-For; - 若 CDN 文档明确只设置
X-Real-IP（如部分企业内网网关），则改为：real_ip_header X-Real-IP; - 注意：
real_ip_header单独存在无效，必须配合至少一条set_real_ip_from才触发 realip 模块解析
启用递归解析应对多层转发
用户请求路径可能是「浏览器 → CDN → SLB → Nginx」，此时 XFF 头内容类似 203.0.113.1, 198.51.100.2, 10.10.1.5（最左是客户端，往右是各级代理）。默认行为只取第一个可信段前的 IP，容易误判。
- 加上：
real_ip_recursive on; - 启用后，Nginx 会从右往左检查 XFF 中每个 IP 是否属于
set_real_ip_from列表，跳过所有可信代理 IP，直到遇到第一个不在列表中的 IP —— 那就是真实客户端 IP - 即使只有一层 CDN，也建议始终开启，避免未来架构扩展时出问题
验证与日志输出是否生效
配置完后，需验证真实 IP 是否真正进入 Nginx 内部变量，并能被日志或后端应用使用。
- 修改日志格式，用
$realip_remote_addr替代$remote_addr：log_format main '$realip_remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"'; - 临时加调试日志行对比：
log_format debug '$http_x_forwarded_for — $realip_remote_addr — $remote_addr'; - 检查上游是否确实传递了 XFF 头：比如前置 Nginx 代理需配
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;，避免头丢失或重复追加导致格式异常
