nginx可通过map模块构造自定义哈希键（如$final_key），再在upstream中用hash $final_key consistent实现基于用户id、header等特征的稳定一致性哈希分发。
Nginx 的 hash 指令本身不直接支持“自定义负载均衡键”的编程式构造（比如拼接多个变量），但它可以通过巧妙组合内置变量和 map 模块，实现基于请求特征（如用户 ID、API 路径、Header 等）的稳定哈希分发。核心在于：先用 map 构建你想要的键，再在 upstream 块中对这个键做 hash。
1. 使用 map 提前构造哈希键
map 是 Nginx 中用于条件映射的关键模块，必须在 http 块中定义。它能从请求变量（如 $arg_uid、$http_x_user_id、$request_uri）中提取、拼接、过滤，生成一个确定性字符串作为哈希输入。
例如，优先用请求头 X-User-ID， fallback 到 URL 参数 uid，再 fallback 到客户端 IP：
http {
map $http_x_user_id $balancer_key {
"" $arg_uid;
default $http_x_user_id;
}
map $balancer_key $final_key {
"" $remote_addr;
default $balancer_key;
}
}
这样 $final_key 就是你最终用于哈希的“自定义键”——它可能是用户 ID、参数值或 IP，且逻辑清晰、可维护。
2. 在 upstream 中对自定义键做 hash
在 upstream 块中启用 hash 指令，并指定刚才构造的变量。Nginx 会自动对该变量的字符串值进行一致性哈希（默认使用 siphash24），确保相同键始终路由到同一台后端：
upstream backend_cluster {
hash $final_key consistent;
server 10.0.1.10:8080;
server 10.0.1.11:8080;
server 10.0.1.12:8080;
}
-
consistent参数启用一致性哈希，增减节点时仅少量键重分布，适合缓存场景 - 若省略
consistent，则为普通取模哈希（节点变动时大部分请求重散列） - 键值为空字符串时，Nginx 默认哈希到第一个 server；上面
map已兜底，可避免意外空值
3. 常见自定义键示例
根据业务需求灵活组合变量：
-
按用户会话：
$cookie_sessionid或$arg_token -
按 API 资源：
$request_uri（注意含查询参数）或$uri（不含 query） -
按租户标识：
$http_x_tenant_id或$host -
多字段组合（需用
map拼接）：$http_x_user_id:$uri（注意冒号是分隔符，避免冲突）
⚠️ 注意：$args 包含所有查询参数但顺序不固定（取决于客户端），不建议直接哈希；优先用 $arg_xxx 显式取特定参数。
4. 验证与调试技巧
上线前建议验证键生成是否符合预期：
- 临时加
add_header X-Balancer-Key "$final_key";到 location，用 curl 查看响应头 - 用
log_format记录$final_key和$upstream_addr，确认相同键总打到同一台 - 测试增减一台后端，观察
consistent是否减少抖动（对比不加该参数的情况）
不复杂但容易忽略：键的稳定性决定负载均衡效果。只要 map 输出确定、无随机成分，哈希结果就可靠。
