NGINX `ngx_stream_geo_module` 模块详解与实战

• 模块名称：ngx_stream_geo_module
• 引入版本：NGINX 1.11.3
• 作用：根据客户端 IP（支持 IPv4/IPv6、CIDR、IP 范围）设置自定义变量值；常用于流模块（stream）上下文中，实现基于 IP 的分流、限流与访问控制。
• 性能特性：变量仅在首次使用时按需解析，声明大量网段也不会影响连接性能。

geo [$address_variable] $target_variable { [ranges;] [default value;] [delete network;] [include file;] address1[/mask] value1; address2-start–address2-end value2; ... } 

• **addressvariable∗∗（可选）：指定用于匹配的IP来源变量，默认取‘address_variable**（可选）：指定用于匹配的 IP 来源变量，默认取 `addressv​ariable∗∗（可选）：指定用于匹配的IP来源变量，默认取‘remote_addr`；
• $target_variable：模块输出变量名；
• ranges：启用 IP 范围（start-end）匹配，必须放在块内第一行；
• default：当客户端 IP 未命中任何规则时，赋予的默认值；
• delete：从已有网段中删除指定条目；
• include：包含外部配置文件，方便管理大规模 IP 列表；
• address/mask：CIDR 网段或单个 IP；
• start–end：仅在 ranges; 模式下使用，指定 IP 范围。

以下示例中，根据客户端 IP 设置变量 $geo 的值，随后可在 stream 模块中引用该变量进行 Upstream 选择或限流：

stream { # 定义 geo 变量 geo $geo { default 0; 127.0.0.1 2; 192.168.1.0/24 1; 10.1.0.0/16 1; ::1 2; 2001:0db8::/32 1; } # 根据 $geo 值路由到不同 upstream upstream backend_a { server 10.0.0.1:1234; } upstream backend_b { server 10.0.0.2:1234; } server { listen 1234; proxy_pass $geo == 1 ? backend_a : backend_b; } } 

• 默认值 default 0;：若客户端 IP 不在任何列举网段内，变量 $geo 为 0；
• IPv4/IPv6 支持：除了普通的 IPv4/CIDR，也可以写 IPv6 地址或网段。

在某些场景下，需要针对代理转发后获取的真实客户端 IP（如 $proxy_protocol_addr、$arg_remote_addr）做判断，可以这样指定：

geo $arg_remote_addr $geo_client { default 0; 203.0.113.0/24 1; } 

当 IP 列表较大时，可将其拆分到外部文件，方便维护和自动化更新：

geo $country { default ZZ; include conf/geo_us.conf; # US 网段 include conf/geo_cn.conf; # CN 网段 delete 127.0.0.0/16; # 排除本地网段 } 

conf/geo_us.conf 示例：

3.0.0.0/8 US; 4.0.0.0/8 US; 

对于不规则的非连续 CIDR 或更灵活的 IP 范围匹配，可以开启 ranges 模式：

geo $country { ranges; default ZZ; 127.0.0.1-127.0.0.1 RU; 127.0.0.2-127.0.0.255 US; 10.1.0.0-10.1.255.255 RU; } 

• ranges; 必须是块内的第一行；
• 范围匹配按升序排列，可提升加载速度。

• 按需计算
  • 变量只在首次使用时解析；未使用的 geo 块不会带来开销。
• 网段顺序
  • 推荐将最常用或最精确的网段放在前面，加快匹配速度。
• 范围模式排序
  • 在 ranges 模式下，必须按 IP 升序排列；否则可能报错或影响性能。
• 内存占用
  • 大量网段配置会占用一定内存，建议结合 include 拆分文件并定期清理无效条目。
• IPv4/IPv6 协同
  • IPv4 和 IPv6 条目可混用，但要确保 default 后的值与匹配规则一致。

ngx_stream_geo_module 为 NGINX Stream 模块注入了强大的基于 IP 的动态路由与访问控制能力。无论是简单的白名单/黑名单，还是复杂的地域路由、限流需求，都能通过灵活的 geo 块配置高效实现。通过合理利用 default、include、delete 与 ranges 等参数，结合生产环境的维护与监控策略，可以在保证性能的同时实现精细化管理。希望本文的示例与经验能帮助你快速上手并优化你的 NGINX 流式服务架构。

原文链接：https://blog.csdn.net/weixin_43114209/article/details/147547432?ops_request_misc=%257B%2522request%255Fid%2522%253A%2522f3da1fffa615de5c92290eb397a4b265%2522%252C%2522scm%2522%253A%252220140713.130102334.pc%255Fblog.%2522%257D&request_id=f3da1fffa615de5c92290eb397a4b265&biz_id=0&utm_medium=distribute.pc_search_result.none-task-blog-2~blog~first_rank_ecpm_v1~times_rank-20-147547432-null-null.nonecase&utm_term=GEO