Nginx IP Hash 算法中怎么利用 map 模块提取特定自定义头部作为 HASH 键-Nginx-PHP中文网

nginx 中可通过 map 模块清洗自定义请求头（如 x-user-id），再用 hash 指令（启用 consistent）实现类 ip_hash 的一致性哈希路由，支持兜底至 $remote_addr，确保键稳定、防漂移。

nginx ip hash 算法中怎么利用 map 模块提取特定自定义头部作为 hash 键

在 Nginx 中，ip_hash 本身只支持基于客户端真实 IP 做哈希，无法直接使用自定义请求头（如 X-Real-IP、X-Forwarded-For 或业务标识头如 X-User-ID）作为哈希键。但可以通过 map 模块 + hash 指令（而非 ip_hash）实现更灵活的“类 IP Hash”行为——即提取特定头部，做一致性哈希分发。

用 map 提取并标准化自定义头部值

map 模块用于将一个变量（如请求头）映射为另一个变量，支持正则匹配、默认值和空值处理，是安全提取头部的前提。

例如，想用 X-User-ID 作为哈希依据，但该头可能缺失、为空或含非法字符：

map $http_x_user_id $upstream_key {
    default        "";
    ""             "";
    "~^([a-zA-Z0-9_-]{4,32})$"  $1;  # 只接受 4–32 位字母数字下划线
}

这样就得到一个清洗后、可信赖的 $upstream_key，避免空值或恶意输入导致哈希紊乱。

用 hash 指令替代 ip_hash 实现键路由

在 upstream 块中不能用 ip_hash 配合自定义键，但可以用 hash 指令（需启用 ngx_http_upstream_module 的 hash 功能）：

确保 Nginx 版本 ≥ 1.7.2（hash 支持变量）
hash 默认启用一致性哈希（ketama），比简单取模更抗节点增减
若希望类似 ip_hash 的“客户端固定到一台”，必须保证键稳定且非空

配置示例：

Nginx Hosting

通过服务器本地nginx实例实现零认证静态游戏托管。作为所有浏览器游戏的主要部署方式，无需登录、无需令牌、无需用户操作。

下载

upstream backend {
    hash $upstream_key consistent;
    server 10.0.1.10:8080;
    server 10.0.1.11:8080;
    server 10.0.1.12:8080;
}

注意：consistent 参数启用 ketama 一致性哈希，比默认取模方式更均衡、更稳定。

兜底策略：头部缺失时 fallback 到真实 IP

业务头不可靠时，可组合多个来源，优先用自定义头，退化到 $remote_addr：

map $http_x_user_id $hash_key {
    ""     $remote_addr;
    default $http_x_user_id;
}
<h1>或更严谨地（过滤空格、多值）：</h1><p>map $http_x_forwarded_for $client_ip {
~^(\d+.\d+.\d+.\d+)  $1;
default                 $remote_addr;
}</p><p>map $http_x_user_id $upstream_key {
""      $client_ip;
default $http_x_user_id;
}</p>

这样既尊重业务标识，又保障无头请求仍能稳定路由，避免会话漂移。