ip_hash不支持IPv6，仅兼容IPv4；替代方案是使用hash $remote_addr consistent指令，可同时处理IPv4/IPv6地址，并配合real_ip模块确保真实IP识别。
ip_hash 是 Nginx 的负载均衡策略，用于基于客户端 IP 做一致性哈希，确保同一 IP 的请求始终转发到同一后端。但在 IPv6 环境下，Nginx 原生 ip_hash 仅支持 IPv4 地址哈希，不识别 IPv6 地址结构，直接启用会导致配置校验失败或运行时报错（如 invalid number of IPv6 addresses in ip_hash 或 nginx: [emerg] invalid parameter "ip_hash"）。
根本原因不是“子网掩码匹配报错”，而是 ip_hash 指令本身不支持 IPv6 —— 它只解析点分十进制格式的 IPv4 地址，遇到冒号分隔的 IPv6 地址会解析失败，甚至被误判为语法错误。
✅ 正确理解：ip_hash 与 IPv6 不兼容
- Nginx 官方文档明确说明：
ip_hash仅适用于 IPv4（见 NGINX ip_hash docs）。 - 即使你写成
ip_hash;且上游有 IPv6 客户端访问，Nginx 也不会对 IPv6 做哈希；更常见的是——若启用了ip_hash又存在 IPv6 请求头（如$remote_addr是 IPv6），某些旧版本（<1.19.0）可能因内部地址解析异常而报错或 fallback 失效。
✅ 替代方案：用 hash 指令实现 IPv4 + IPv6 兼容的源地址哈希
Nginx 从 1.11.0 起支持 hash 指令，可对任意字符串（包括 IPv6 地址）做哈希，是 ip_hash 的通用替代：
upstream backend {
# 使用 hash + $remote_addr，自动兼容 IPv4 和 IPv6
hash $remote_addr consistent;
server 10.0.1.10:8080;
server 10.0.1.11:8080;
}?
consistent参数启用一致性哈希（推荐），避免后端增减时大量请求重散列。
补充建议（提升鲁棒性）：
- 若前端有反向代理（如 CDN、LB），确保
$remote_addr是真实客户端 IP：
启用real_ip模块并配置set_real_ip_from和real_ip_header，否则$remote_addr可能是代理 IPv4 地址，导致 IPv6 客户端全部哈希到同一后端。 - 对于 IPv6 地址，Nginx 默认保留完整格式（如
2001:db8::1），hash能正常处理；无需截取前缀或掩码。 - 不要尝试用
map手动截 IPv6 前 64 位再哈希——既无必要，还可能破坏分布均匀性。
❌ 不推荐的“修复”方式
- 修改 Nginx 源码添加 IPv6
ip_hash支持（维护成本高，不可升级） - 用
geo+map提取 IPv6 网段再哈希（逻辑复杂、易出错、不一致） - 强制所有客户端走 IPv4（违背 IPv6 部署初衷，且不可控）
✅ 快速验证是否生效
- 测试 IPv6 请求能否被正确哈希：
curl -g -6 http://[2001:db8::1]/test # 观察后端日志中目标 server curl -g -6 http://[2001:db8::2]/test # 同一 client IP 多次请求应命中同一台
- 检查 Nginx 配置语法：
nginx -t # 应提示 success，不再报 ip_hash 相关错误
Nginx 的 hash 指令是官方推荐的 IPv6 兼容方案，简洁、可靠、无需额外模块。只要确保 $remote_addr 准确反映客户端真实 IP，就能平滑替代 ip_hash。
