根本原因是代理层未透传标识、应用层未解析、握手HTTP头被忽略；需三步解决：Nginx配置透传X-Forwarded-For及Upgrade头，后端框架主动读取代理头，链路验证headers中X-Forwarded-For值是否为真实客户端IP。
WebSocket 在反向代理后拿不到真实客户端 IP，根本原因不是协议本身不支持，而是代理层未正确透传标识、应用层未主动解析、且 WebSocket 握手阶段的 HTTP 头容易被忽略。解决需覆盖 Nginx 配置、后端框架适配、以及链路验证三步。
确保 Nginx 正确透传 X-Forwarded-For 和升级头
Nginx 必须在 WebSocket 的 location 块中显式设置代理头，并启用 HTTP/1.1 协议升级机制：
-
必须包含这三行：
proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade、proxy_set_header Connection "upgrade" -
X-Forwarded-For 不能遗漏：添加
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for，确保原始 IP 被追加而非覆盖 -
推荐补充：
proxy_set_header X-Real-IP $remote_addr和proxy_set_header X-Forwarded-Proto $scheme，便于后端多维度校验
后端框架需主动读取代理头（非自动生效）
Docker 容器内运行的应用默认只认 TCP 层的 remote_addr，不会自动解析 X-Forwarded-For。不同框架处理方式不同：
WebSocket 8.18.2
下载
WebSocket 8.18.2 是该协议规范的一个重要迭代版本，主要优化了连接稳定性与数据传输效率。它通过全双工通信机制，允许客户端与服务器在单一长连接上实时交换数据，大幅降低传统 HTTP 轮询的开销。该版本增强了心跳保活、自动重连及二进制帧传输能力，适用于即时通讯、在线游戏及金融行情推送等低延迟场景，为开发者提供更可靠的实时网络交互基础。
-
Spring Boot（Tomcat）：在
server.xml中配置RemoteIpValve，指定remoteIpHeader="X-Forwarded-For"和可信代理网段 -
FastAPI：需手动从
websocket.headers.get("x-forwarded-for")提取，并按逗号分割取最左 IP；不能依赖websocket.client.host -
Node.js（Express + ws）：握手时通过
req.headers["x-forwarded-for"]获取，注意检查是否为字符串且含逗号分隔
验证 X-Forwarded-For 是否真正到达后端
很多问题卡在“以为配置了，其实没生效”。建议用以下方式快速定位断点：
- 在 WebSocket 握手请求中打印全部 headers，确认
x-forwarded-for字段存在且值为客户端公网 IP（如"123.45.67.89"或"123.45.67.89, 10.0.1.100"） - 若值为空或为内网地址（如
10.x.x.1），说明 Nginx 未透传，或上游有中间设备（如 Cloudflare、防火墙 NAT）覆盖了该头 - 若值是多个 IP，取第一个（最左侧）作为真实客户端 IP；但前提是第一层代理（如 CDN 或负载均衡）已清洗伪造头，否则需结合
set_real_ip_from信任网段做校验
特殊场景：Cloudflare 或企业级防火墙穿透
当流量经过 Cloudflare、WAF 或 NAT 网关时，X-Forwarded-For 可能被重写或清空：
- Cloudflare 默认会添加
CF-Connecting-IP头，可作为备用字段，但仅限其直连场景 - 若使用 Cloudflare，Nginx 必须配置
set_real_ip_from加入 CF 全球可信 IP 段，并设real_ip_header CF-Connecting-IP - 企业防火墙常做端口映射（如公网
36.x.x.x:18000 → 内网 10.x.x.180:8000），此时需在防火墙策略中开启 XFF 透传，否则 Nginx 收到的永远是防火墙出口 IP
