Nginx的ngx_http_realip_module用于从X-Forwarded-For等请求头提取真实客户端IP并替换$remote_addr；需配置set_real_ip_from指定可信代理、real_ip_header指定头字段，并确保模块已启用且配置生效。
Nginx 的 ngx_http_realip_module（RealIP 模块）用于在反向代理场景下，从请求头（如 X-Forwarded-For 或 X-Real-IP）中提取客户端真实 IP，并替换掉 $remote_addr 变量的值，从而让日志、限流、访问控制等模块能基于真实 IP 工作。
确认 RealIP 模块已启用
该模块默认编译进大多数官方 Nginx 包（包括 nginx.org 官方源和主流发行版包），但需确认是否启用：
- 运行
nginx -V 2>&1 | grep -o with-http-realip-module，若输出含该字符串，说明已编译支持； - 若使用自定义编译，需确保配置时加了
--with-http-realip-module； - OpenResty 默认包含此模块，无需额外操作。
基本配置：设置可信代理与真实 IP 来源头
RealIP 不会盲目信任所有请求头，必须明确指定哪些上游代理是“可信的”，否则不执行替换。典型配置如下：
set_real_ip_from 10.0.0.1; # 你的负载均衡器或上一级代理 IP set_real_ip_from 192.168.1.0/24; # 可信内网网段 real_ip_header X-Forwarded-For; # 从该请求头取真实 IP（多个 IP 时取最左非可信项） # real_ip_recursive on; # 可选：启用递归解析（见下文说明）
关键点说明：
-
set_real_ip_from必须写在http、server或location块中，且需在real_ip_header之前； -
real_ip_header支持X-Forwarded-For、X-Real-IP或自定义头名； - 若代理只传一个 IP（如直接设
X-Real-IP: 203.0.113.5），用X-Real-IP更简洁可靠； - 若用
X-Forwarded-For，且有多层代理（如 CDN → Nginx → 应用），需配合real_ip_recursive on向右查找第一个非可信 IP。
验证是否生效
替换后，$remote_addr 即为真实客户端 IP，可用于日志或条件判断：
- 在
log_format中加入$remote_addr，查看日志是否显示用户真实 IP 而非代理 IP； - 临时加一条
return 200 "Client: $remote_addr\n";到 location 中，curl 测试； - 注意：仅当请求来自
set_real_ip_from列出的可信地址时，替换才发生；直连请求不受影响。
常见陷阱与建议
避免因配置不当导致 IP 伪造或丢失：
- 不要把公网 IP 段（如
0.0.0.0/0）设为可信，否则攻击者可伪造X-Forwarded-For； - 若前端有 CDN（如 Cloudflare），需将 CDN 的 IP 段加入
set_real_ip_from，并使用其推荐头（如CF-Connecting-IP）配合real_ip_header； - 确保上游代理确实设置了对应头（例如 Nginx 作为代理时，需配
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;）； - 修改配置后务必
nginx -t && nginx -s reload，否则不生效。
RealIP 模块本身轻量，逻辑清晰，关键是准确识别可信代理边界并匹配头字段。配对正确后，$remote_addr 就是你要的真实客户端 IP。
