排查ip_hash失效的核心是确认$remote_addr是否为真实客户端ip；若其被代理覆盖为内网地址（如10.0.0.5），则哈希必然失真，需通过set_real_ip_from、real_ip_header及递归解析还原，并验证日志中$remote_addr与$realip_remote_addr是否一致。
排查 ip_hash 路径映射失效，核心是确认 Nginx 实际用于哈希计算的 IP 是否为真实客户端 IP。不是看配置有没有写 ip_hash，而是看它“算的是谁的 IP”。常见失效场景中，90% 以上问题出在 $remote_addr 被中间代理覆盖为内网地址（如 10.0.0.5），而非用户真实公网或内网 IP。
检查 $remote_addr 是否已还原为真实 IP
这是最关键的一步。ip_hash 只认 $remote_addr，不读 X-Forwarded-For 或其他头字段。若该变量仍是上一跳代理的 IP，哈希必然失真。
- 在
http或server块顶部（location之前）添加日志格式验证：
log_format debug '$remote_addr | $http_x_forwarded_for | $realip_remote_addr - "$request" $status';
- 重启 Nginx 后访问并查看 access.log，对比三者：
– 若$remote_addr和$realip_remote_addr相同且为公网 IP（如203.208.60.12），说明 real_ip_module 已生效；
– 若$remote_addr是内网段（如10.10.20.3）而$realip_remote_addr才是真实 IP，说明set_real_ip_from或real_ip_header配置有误或未加载；
– 若两者都是内网 IP，且$http_x_forwarded_for中有多个逗号分隔的地址，说明上游未透传或 Nginx 未启用递归解析。
确认 real_ip_module 配置位置与参数正确
该模块必须在请求进入 upstream 之前完成还原，因此配置不能放在 location 内，也不能遗漏关键指令。
-
set_real_ip_from必须精确填写你实际使用的可信代理段（如 CDN、WAF、SLB 或前置 Nginx 的回源 IP 段），不能写0.0.0.0/0或凭空猜测； -
real_ip_header要与上游实际发送的头一致：Cloudflare 用CF-Connecting-IP，腾讯云 WAF 用X-Real-IP或开启“获取真实 IP”后仍走X-Forwarded-For； - 必须启用
real_ip_recursive on，否则遇到多层代理时会取到中间某跳不可信 IP，而非最左真实 IP。
验证 upstream 中 ip_hash 是否处于有效上下文
语法和位置错误会导致 ip_hash 被静默忽略，Nginx 不报错但实际走轮询。
-
ip_hash必须顶格写在upstream块第一行，前面不能有空格或注释； - 不能与
hash、least_conn、weight、backup等指令共存，否则配置校验失败或启动报错； - upstream 列表不能动态变更：临时
down一台 server 或 reload 时增删节点，都会导致哈希环整体偏移，大量用户 session 断连——这不是配置失效，而是机制限制。
排除后端或客户端侧干扰
有时问题不在 Nginx 本身，而在链路下游或上游行为异常。
- 检查所有中间代理是否真正透传
X-Forwarded-For：首层代理应设proxy_set_header X-Forwarded-For $remote_addr，后续每层必须用$proxy_add_x_forwarded_for追加，严禁覆盖； - 后端应用若自行解析
X-Forwarded-For且未校验代理信任链，可能读错 IP，造成会话混乱——此时即使 Nginx 哈希正确，业务层也感知不到； - 企业 NAT 环境下，若出口设备未携带原始内网 IP（如防火墙不支持 XFF 或仅填公网出口 IP），则 real_ip_module 无源可溯，需改用 cookie hash 或集中式 session。
