ip_hash不支持ipv6映射地址,因其实现仅识别ipv4点分十进制格式;遇到::ffff:192.168.1.100等地址会解析失败,导致配置报错或回退轮询,会话无法保持;应改用hash $remote_addr consistent配合real_ip_module或map预处理。

会受影响,而且影响是根本性的。
IPv6 映射的 IPv4 地址(例如 ::ffff:192.168.1.100)本质上仍是 IPv6 格式,而 Nginx 原生 ip_hash 指令完全不支持 IPv6——它只识别点分十进制的 IPv4 地址(如 192.168.1.100),遇到冒号分隔的地址格式(包括 IPv4 映射地址)会直接解析失败。
Nginx 不会把 ::ffff:192.168.1.100 当作 IPv4 处理,也不会提取其中的 IPv4 部分做哈希。结果通常是:
- 配置校验阶段报错:
nginx: [emerg] invalid parameter "ip_hash"或类似提示 - 运行时若配置侥幸通过,该请求会被跳过
ip_hash逻辑,fallback 到默认轮询(round-robin),导致会话不保持 - 日志中
$upstream_addr显示的后端不固定,且无规律
这是因为 ip_hash 的实现硬编码了 IPv4 解析逻辑,没有地址族判断和自动降级机制。
要正确处理这类混合地址,必须改用通用哈希指令:
- 使用
hash $remote_addr consistent;(Nginx ≥1.11.0) - 配合
real_ip_module正确还原真实客户端地址(尤其在有 CDN 或反向代理时) - 若需兼容 IPv4 映射地址,可在
map中预处理$remote_addr,例如提取::ffff:后的 IPv4 段,再参与哈希
简单来说:ip_hash 对 ::ffff:x.x.x.x 无效,不是精度问题,而是协议不识别。











