如何通过Nginx split_clients模块按UserID取模进行高效流量分配演示？

本文共计1250个文字，预计阅读时间需要5分钟。

很多人以为`split_clients`能像编程语言一样写`uid % 100`，实际上不行。Nginx的`split_clients`只接受变量（如`$arg_uid`、`$cookie_uid`）作为输入，并对其做内部哈希（MurmurHash2），再按百分比区间分配。所谓的取模效果其实是哈希后映射到离散整数来模拟的——本质上是哈希后截断或取余，而非真正的取模运算。

常见错误现象：split_clients $uid $bucket { ... } 直接报错，因为 $uid 未定义；或者用了 $uid 但没在 upstream 里透传，导致所有请求都落到同一组。

• 确保客户端把 UserID 以参数或 Cookie 形式带上，例如 /api?uid=123456 或 Cookie: uid=123456
• 优先用 $arg_uid（URL 参数）而非自定义变量，避免重写阶段未赋值
• 如果 UserID 是数字字符串（如 "789"），哈希结果稳定；但若含字母或符号，同样 UID 在不同 Nginx 版本下哈希值可能微异（MurmurHash2 实现细节差异）

配置 split_clients 实现 10% / 90% 流量切分的最小可行写法

下面这段配置能真正跑通，且满足“基于 UserID 分流”这一核心诉求：

split_clients "$arg_uid" $bucket { 10% "v2"; * "v1"; } <p>upstream backend_v1 { server 10.0.1.10:8080; } upstream backend_v2 { server 10.0.1.20:8080; }</p><p>server { location /api/ { proxy<em>pass <a href="https://www.php.cn/link/65b5b8d1f89bf53a5713bc3afdd83e9e">https://www.php.cn/link/65b5b8d1f89bf53a5713bc3afdd83e9e</a></em>$bucket; proxy_set_header X-Uid $arg_uid; } }

注意几个关键点：

• "$arg_uid" 必须加双引号，否则空值或含空格时会解析失败
• 10% 是累积概率，不是独立区间；* 表示 fallback，必须存在
• $bucket 是纯字符串变量，不能参与算术运算，所以无法直接做 uid % 10 == 0 这类逻辑
• 如果想实现“每 10 个用户分 1 个到灰度”，实际效果≈哈希后落在前 10% 桶里，不是严格数学取模，但线上足够用

想严格按 uid % N 分流？得用 map + geoip 模块组合替代 split_clients

当业务要求必须满足 uid % 100 == 0 才进灰度，split_clients 就力不从心了。此时要换思路：用 map 把 UID 字符串转成整数，再用 Lua 或外部服务计算余数——但 Nginx 原生不支持字符串转整、也不支持取模运算。

一个轻量折中方案（无 Lua）：

map $arg_uid $uid_mod_100 { default 0; "~^([0-9]+)$" $1; } <h1>然后用 split_clients 对 $uid_mod_100 哈希？不行——它仍是字符串</h1><h1>所以真正能落地的做法是：</h1><p>geo $uid_mod_100 $mod_bucket { default 0; 0 1; 1 0;</p><h1>……手动列 100 行？显然不可维护</h1><p>}

结论很实在：真要严格取模，别硬刚原生模块。要么上 nginx-lua（用 ngx.var.arg_uid % 100），要么把分流逻辑下沉到应用层，Nginx 只做 header 透传。

• split_clients 的设计目标就是「快速、无状态、一致性哈希分流」，不是通用计算引擎
• 线上压测发现：开启 split_clients 后 QPS 下降不到 1%，而嵌入 Lua 可能多出 5%~10% 开销
• 如果 UID 是 UUID 或长字符串，哈希分布更均匀；短数字 UID（如 1~1000）容易出现倾斜

调试时看不到 $bucket 值？加 log_format 和 access_log 定位

配置写完却分不到 v2，大概率是 $arg_uid 没取到。Nginx 不报错，只静默走 fallback（* 分支），非常隐蔽。

最有效的排查方式：

log_format debug '$remote_addr - $remote_user [$time_local] ' '"$request" $status $body_bytes_sent ' '"$http_referer" "$http_user_agent" ' 'uid="$arg_uid" bucket="$bucket"'; <p>access_log /var/log/nginx/debug.log debug;</p>

然后 curl 测试：curl "http://example.com/api/?uid=9999"，立刻看日志里 uid="9999" bucket="v2" 是否出现。

• 如果 uid=""，说明参数名不对（比如前端传的是 user_id 而非 uid）
• 如果 bucket=""，说明 split_clients 块没加载（检查是否在 http 块顶层，不在 server 内）
• 如果用 HTTPS，确认没在 proxy_pass 前被 rewrite 清掉参数

这个模块的坑不在语法，而在变量生命周期和上下文可见性——$arg_xxx 只在当前请求的 rewrite 阶段之后才稳定可用。