split_clients模块通过MurmurHash2对变量做确定性哈希并映射百分比区间，实现无状态、低开销的稳定分流；仅支持整型百分比，需reload生效，不支持动态权重调整。
nginx 的 split_clients 模块可用于按请求特征（如 IP、User-Agent、URL 参数等）做确定性哈希分流，实现稳定可控的百分比灰度发布或 A/B 测试。它不依赖 upstream 或 proxy，纯内存计算，性能开销极低。
核心原理：哈希 + 范围映射
split_clients 对指定变量（如 $remote_addr）做 MurmurHash2 计算，得到 0–999999 之间的整数，再根据配置的百分比区间决定命中哪个值。整个过程无状态、可复现——同一请求每次都会分到同一组。
- 哈希结果固定，不随 worker 进程或重启变化
- 不支持动态权重调整，配置 reload 后才生效
- 仅支持整型百分比（如
10%、0.5%不合法），内部按万分比（0–9999）映射
基础配置示例：按客户端 IP 分流 90%/10%
以下配置将 90% 的真实用户流量导向主站，10% 导向灰度环境：
split_clients "$remote_addr" $group {
90% "prod";
* "gray";
}
<p>server {
location / {
proxy<em>pass <a href="https://www.php.cn/link/65b5b8d1f89bf53a5713bc3afdd83e9e">https://www.php.cn/link/65b5b8d1f89bf53a5713bc3afdd83e9e</a></em>$group;
proxy_set_header Host $host;
}
}说明：
-
"$remote_addr"是输入变量，也可换为$arg_uid（URL 中 uid=xxx）、$http_user_agent等 -
$group是生成的变量名，后续可在proxy_pass、set、if中使用 -
*表示兜底，覆盖剩余所有比例（此处即 10%） - 后端需提前定义
upstream backend_prod { ... }和upstream backend_gray { ... }
进阶用法：多级分流与组合特征
单靠 IP 可能导致内网用户全进同一组。可通过拼接变量提升散列均匀性：
set $split_key "$remote_addr|$request_uri|$arg_v";
split_clients "$split_key" $ab_test {
5% "v2";
1% "canary";
* "v1";
}注意点：
- 拼接符建议用非常规字符（如
|、^），避免变量值本身含分隔符导致哈希偏差 - 若
$arg_v为空，"192.168.1.1|/api/user|"仍为有效字符串，不影响哈希 - 避免使用高动态变量（如
$request_time、$msec），会导致同一请求多次哈希结果不同
验证与调试技巧
分流是否生效？加响应头直观确认：
location / {
add_header X-Route-Group $group;
proxy_pass https://www.php.cn/link/65b5b8d1f89bf53a5713bc3afdd83e9e_$group;
}用 curl 快速验证一致性：
curl -H "X-Real-IP: 192.168.1.100" http://test.com/ -I | grep X-Route-Group # 多次执行应始终返回相同 group
其他建议：
- 上线前用脚本模拟万级 IP 哈希分布，检查各组实际占比是否接近配置值
- 若需精确控制（如 1.7%），可手动换算：写
170表示 1.7%（因内部精度为 0.01%，即 1/10000） - 配合
map指令可实现更灵活的条件路由（例如只对特定 path 或 header 启用分流）
不复杂但容易忽略：分流逻辑在 server 或 http 块顶层定义，不能嵌套在 if 或 location 内；变量名必须以 $ 开头且全局唯一；reload nginx 后规则立即生效，无需重启。
