后端需通过Nginx的http_realip_module模块配合set_real_ip_from、real_ip_header和real_ip_recursive指令，结合前端正确透传X-Forwarded-For，才能安全获取真实客户端IP；多层代理时须配置所有可信网段，四层场景应启用Proxy Protocol。
在负载均衡环境下，后端服务器默认拿到的是负载均衡器的 IP（即 $remote_addr），而非用户真实 IP。要让后端正确识别来访者真实源 IP，关键不是只加 proxy_set_header X-Real-IP $remote_addr，而是配合后端服务的可信来源识别与头字段解析逻辑。配置需前后端协同，否则容易被伪造或失效。
前端 Nginx（负载均衡/反向代理）侧配置
这是流量入口的第一环，负责把真实客户端 IP 以标准方式透传给后端：
- 必须设置
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for—— 这是行业通用、负载均衡器（如 CLB/NLB/SLB）默认识别并追加的字段，格式为X-Forwarded-For: 客户端IP, 代理1IP, 代理2IP，第一个值即真实 IP - 可选设置
proxy_set_header X-Real-IP $remote_addr，但注意：$remote_addr此时是上一级代理（比如 CDN 或 WAF）的出口 IP，不是最终用户 IP；若你确定本层 Nginx 是最外层代理（直连客户端），才可用它；否则应避免单独依赖该字段 - 务必设置
proxy_set_header Host $host和proxy_set_header X-Forwarded-Proto $scheme，保障协议和域名信息完整
后端 Nginx（Web 应用服务器）侧配置
仅转发头没用，后端必须明确“信任谁发来的 X-Forwarded-For”，否则会把伪造的头当真：
WebChat Voice Proxy
下载
⚠️ 已弃用 — 该技能已拆分为两个独立技能，以提升模块化程度：**webchat-https-proxy**（HTTPS/WSS 反向代理）和 **webchat-voi...**
- 启用
http_realip_module（Nginx 默认不编译此模块，需确认已安装；可通过nginx -V 2>&1 | grep http_realip检查） - 在
http或server块中添加：set_real_ip_from 100.64.0.0/10; # 阿里云 SLB 网段<br>set_real_ip_from 100.125.0.0/16; # 腾讯云 CLB 共享型网段<br>set_real_ip_from 172.16.0.0/12; # 私有云或自建 LB 内网段（按实际填写）<br>real_ip_header X-Forwarded-For;<br>real_ip_recursive on;
-
set_real_ip_from必须精确填写负载均衡器所在网段，不能写0.0.0.0/0，否则任意请求都可伪造 XFF 头绕过校验 -
real_ip_recursive on表示从右往左逐级剥离可信代理 IP，最终留下最左边的不可信来源（即真实客户端 IP）
日志与应用层获取真实 IP 的一致性
配置生效后，真实 IP 才会在日志和业务代码中统一呈现：
- 修改日志格式，用
$remote_addr将显示修正后的客户端 IP：log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"'; - PHP 中用
$_SERVER['REMOTE_ADDR']即可获取真实 IP（Nginx 已通过 realip 模块重写） - Node.js（如 Express）中需使用
req.ip并配置app.set('trust proxy', true)，或显式指定可信网段：app.set('trust proxy', '100.64.0.0/10')
安全提醒：防范 X-Forwarded-For 伪造
仅靠 header 传递不设防等于裸奔：
- 永远不要在未开启
set_real_ip_from的情况下直接读取X-Forwarded-For头的第一个值 —— 攻击者可轻易构造X-Forwarded-For: 1.1.1.1伪造源 IP - 如果前端有多层代理（如 CDN → WAF → CLB → 后端），需把所有中间代理出口网段都加入
set_real_ip_from，顺序无关，Nginx 会自动匹配并递归剥离 - 四层 TCP 场景（如 NLB + TCP 监听）不走 HTTP 头，此时应开启“客户端地址保持”或 Proxy Protocol，而非依赖 XFF
