ip_hash实现的是IP级会话保持而非用户级灰度，需配合真实IP识别、可信代理配置及兜底策略才能可靠落地。
使用 ip_hash 实现基于客户端 IP 的灰度发布，本质是利用 Nginx 的哈希负载均衡策略，将同一 IP 的请求长期固定转发到同一台后端服务器，从而为特定用户群体（按 IP 段或真实用户 IP）提供新版本服务。但要注意：它不是精准的“用户级灰度”，而是“IP 级会话保持”；真实场景中需配合 CDN、代理识别、IP 白名单等机制才能可靠落地。
理解 ip_hash 的行为边界
ip_hash 对客户端 IP 做哈希计算，确保该 IP 的所有请求落在同一台 upstream server 上。但它有几点关键限制：
- 只支持 IPv4 的前 3 段（如
192.168.1.x→ 视为同一 IP），IPv6 默认不支持（需 Nginx 1.11.0+ 并启用ip_hash的 IPv6 支持） - 无法识别真实用户 IP：若用户经过 CDN、SLB 或反向代理（如 Nginx 前置代理），
$remote_addr是代理 IP，不是用户真实 IP，必须通过$http_x_forwarded_for或$realip_remote_addr配合set_real_ip_from提取 - 不支持权重、健康检查自动剔除（一旦某台 server down，其哈希槽位的流量会报错，需搭配
down或backup手动维护） - 无法动态切流：不能按百分比灰度，也不能按请求头/参数分流，纯 IP 映射，灵活性低
基础配置：启用 ip_hash + 正确获取真实 IP
以下是一个生产可用的最小化配置示例（假设你已确认前端透传了真实 IP）：
upstream backend_gray {
ip_hash;
server 10.0.1.10:8080;
server 10.0.1.11:8080;
server 10.0.1.12:8080;
}
<p>server {
listen 80;
location / {</p><h1>若上游有 CDN 或 LB，需先还原真实客户端 IP</h1><pre class="brush:php;toolbar:false;"> set_real_ip_from 10.0.0.0/8; # 替换为你的可信代理网段
set_real_ip_from 192.168.0.0/16;
real_ip_header X-Forwarded-For;
real_ip_recursive on;
proxy_pass http://backend_gray;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}}
⚠️ 关键动作：必须明确声明 set_real_ip_from 可信代理段，并指定 real_ip_header，否则 ip_hash 哈希的是代理 IP，全量用户被分到极少数节点，失去灰度意义。
实现“可控灰度”的实用组合策略
仅靠 ip_hash 无法满足典型灰度需求（如“只让北京联通用户看到 V2”），需叠加其他手段：
-
IP 白名单 + if 切流：用
geo或map指令标记灰度 IP 段，再用if将其路由到专用 upstream -
双 upstream 分流：定义两个 upstream ——
backend_stable（默认）和backend_gray（启用ip_hash），通过map $remote_addr $upstream_group按 IP 哈希值或范围决定走哪组 -
结合 cookie 或 header 标识：首次请求根据 IP 决定是否写入
Set-Cookie: gray=on，后续优先按 cookie 路由（更稳定），ip_hash仅作 fallback -
日志标记 + 后期分析：在 access_log 中记录
$remote_addr和 upstream server，用日志分析验证灰度覆盖 IP 分布是否符合预期
避坑提醒：常见失效原因
很多团队配置完发现“灰度没生效”，大概率是以下问题：
- 没配
set_real_ip_from，Nginx 把所有请求哈希到了同一个代理 IP 上 → 全部打到一台机器 - 客户端 IP 频繁变化（如移动网络出口 NAT 池大、家庭宽带拨号重连），导致同用户被分到不同后端 → 看似“灰度不稳定”，实为 IP 不稳定
- upstream 中某台 server 宕机，Nginx 不会自动重哈希，对应 IP 流量直接 502 → 必须加
max_fails=1 fail_timeout=10s并监控告警 - 测试时用 curl 或 Postman 直连 Nginx，未模拟真实 X-Forwarded-For 头 → 本地测试永远走不到灰度逻辑
不复杂但容易忽略。真正可靠的灰度，从来不是单靠一个指令，而是 IP 识别、分流逻辑、可观测性和人工兜底的组合。
