如何利用Nginx ngx_stream_map_module灵活处理四层流映射变量？

Nginx的stream模块自1.9.0版本引入后，四层代理能力逐渐完善，而ngx_stream_map_module作为其中的一个重要子模块，允许我们在stream上下文中创建基于源变量的动态映射关系。很多人在配置TCP或UDP代理时，习惯使用if指令来做条件判断，例如根据客户端地址选择不同的上游服务器组，但if指令在某些情况下会带来性能上的隐忧，尤其是当请求量较大时，每次判断都会消耗一定CPU资源。相比之下，map指令在Nginx启动或配置重载时就会构建好一张哈希表，运行时只需要查表即可，效率远超if。这篇文章就来详细剖析ngx_stream_map_module的工作机制和实际用法。

模块概览与加载方式

ngx_stream_map_module并不是Nginx核心模块，但大多数通过源码编译安装的Nginx都会默认启用它，只要在configure阶段没有显式指定--without-stream_map_module。如果你使用的是官方二进制包或者常见的Linux发行版仓库中的Nginx，一般也不需要额外安装，因为stream和stream_map模块常常被打包在一起。要确认模块是否存在，可以执行nginx -V命令查看编译参数，若输出中包含--with-stream=dynamic或者--with-stream_map_module字样，就说明该模块已经可用。

需要注意的是，stream模块本身默认不会加载stream.conf中的配置，除非在主配置文件nginx.conf的events块之后显式包含stream块。典型的写法是在nginx.conf中添加如下片段，然后通过include指令引入独立的stream配置文件：

stream {
    include /etc/nginx/stream_conf.d/*.conf;
}

一旦stream块被激活，ngx_stream_map_module提供的map指令就可以在stream块内部使用了。map指令只能出现在stream上下文中，不能直接写在server或upstream块里，但map定义的变量可以在后续的server、upstream以及proxy_pass等指令中引用。

map指令的语法与变量映射机制

map指令的基本语法和HTTP模块中的map指令几乎一致，格式为：

map 源变量 目标变量 {
    匹配值1  结果值1;
    匹配值2  结果值2;
    ...
    default  默认结果;
}

其中源变量可以是任意已经定义的内置变量，比如$remote_addr（客户端IP地址）、$ssl_preread_server_name（通过SSL预读获取的SNI域名）等。目标变量则是我们新创建的变量，后续可以在同一个stream块内的其他指令中通过$目标变量名的方式引用。匹配值支持精确字符串、前缀匹配（使用*通配符）、后缀匹配（使用~*或~进行正则匹配）等。如果所有匹配项都不命中，则使用default指定的默认值；如果没有写default，那么目标变量会被设置为空字符串。

这里有一个关键点需要理解：map指令并不会在每次请求到达时重新求值匹配规则，它会在配置加载阶段编译成一张内部哈希表或查找树。当stream连接建立时，Nginx会读取源变量的当前值，然后直接查表得到目标变量的值并缓存起来，后续使用该变量时无需重复计算。这种机制保证了在高并发场景下的低延迟和稳定性。

举一个根据客户端IP网段分配不同后端服务器的例子：

stream {
    map $remote_addr $backend_pool {
        ~^192\.168\.1\.   pool_a;
        ~^10\.0\.0\.      pool_b;
        default           pool_default;
    }

    upstream pool_a {
        server 10.1.1.10:3306;
    }
    upstream pool_b {
        server 10.1.1.20:3306;
    }
    upstream pool_default {
        server 10.1.1.30:3306;
    }

    server {
        listen 3306;
        proxy_pass $backend_pool;
        proxy_connect_timeout 3s;
    }
}

上面的配置中，来自192.168.1.0/24网段的连接会被转发到pool_a，来自10.0.0.0/24网段的连接被转发到pool_b，其他地址则走pool_default。注意proxy_pass后面使用了变量$backend_pool，这使得Nginx会在运行时解析该变量对应的上游组名，从而实现了动态路由。如果proxy_pass后面直接写upstream名字（不带变量），Nginx会在配置加载时就固定绑定，无法实现按连接选择。

结合SSL预读实现SNI分流

在四层代理中处理TLS流量时，一个非常常见的需求是根据客户端发送的SNI（Server Name Indication）域名将连接导向不同的后端服务。由于stream模块本身不解析TLS内容，我们需要借助ngx_stream_ssl_preread_module在TCP握手阶段提取SNI信息。这个模块会读取ClientHello中的server_name扩展，并把结果赋值给$ssl_preread_server_name变量。然后我们就可以把该变量作为map的源变量。

stream {
    map $ssl_preread_server_name $target_backend {
        default                  default_backend;
        ~^api\.example\.com$     api_backend;
        ~^admin\.example\.com$   admin_backend;
        ~^cdn\.example\.com$     cdn_backend;
    }

    upstream api_backend {
        server 192.168.0.10:443;
    }
    upstream admin_backend {
        server 192.168.0.11:443;
    }
    upstream cdn_backend {
        server 192.168.0.12:443;
    }
    upstream default_backend {
        server 192.168.0.99:443;
    }

    server {
        listen 443;
        ssl_preread on;
        proxy_pass $target_backend;
        proxy_protocol on;
    }
}

这个方案非常适合做TLS流量的透明代理，不需要在Nginx上配置任何证书，所有的加解密都发生在后端服务器上。使用map进行SNI匹配时，建议尽量使用精确匹配或者前缀匹配，避免过度依赖正则表达式，因为正则匹配在编译期会生成更复杂的数据结构，虽然性能影响不大，但在规则非常多的情况下仍有一定开销。此外，SNI信息是明文传输的，如果恶意客户端发送不存在的域名，default分支可以兜底处理，防止连接被意外丢弃。

需要注意的是，ssl_preread_on指令必须在server块中显式开启，否则$ssl_preread_server_name变量永远为空，map的结果也会一直是default值。同时，如果客户端不支持SNI（例如老旧的TLS客户端），那么该变量也为空，map会使用default分支，这在设计配置时要考虑周全。

map与其他模块的组合使用场景

除了简单的后端选择，ngx_stream_map_module还能和geo模块、limit_conn模块、access模块等配合，实现更复杂的策略。例如，我们可以先使用geo模块根据IP地址判断地理位置，然后通过map将地理位置代码转换为不同的连接数限制值。

stream {
    geo $country_code {
        default        XX;
        1.2.3.0/24     CN;
        8.8.8.0/24     US;
    }

    map $country_code $conn_limit {
        CN             50;
        US             100;
        default        20;
    }

    limit_conn_zone $binary_remote_addr zone=per_ip:10m;

    server {
        listen 8080;
        limit_conn per_ip $conn_limit;
        proxy_pass backend;
    }
}

这里key是客户端IP的二进制形式，zone定义了共享内存区域，limit_conn指令的第二个参数可以接受变量，于是每个国家来源的IP会获得不同的最大并发连接数。这种灵活的组合使得四层代理的访问控制力度可以做到非常精细，而且全部基于高效的查找表实现，并不会因为规则增多而降低吞吐量。

另一个实用场景是协议探测。通过ngx_stream_preread_module可以读取连接的前几个字节，把协议类型存储到$preread_protocol变量中，再用map把协议映射到不同的处理逻辑。比如检测到HTTP流量就转发到HTTP代理池，检测到MySQL流量就转发到数据库代理池。这在多协议复用一个端口时非常有用。

需要提醒的是，map中使用的源变量必须在stream连接处理的早期阶段就已经被赋值。对于需要额外模块才能获得的变量（例如$ssl_preread_server_name或$preread_buffer），必须确保对应的预读模块已编译进Nginx，并且在server块中开启相应指令。否则变量取不到值，map就失去了意义。

最后，虽然map指令功能强大，但也不建议用它来替代所有的if判断。map适合处理静态的、基于变量值的映射关系，而一些需要根据运行时复杂条件（比如多个变量的组合运算）来决定行为的场景，仍然需要借助if或脚本模块。合理划分静态映射与动态逻辑的边界，才能让Nginx配置既清晰又高效。

Nginx流模块ngx_stream_map_modulemap指令修改时间：2026-10-05 03:04:53