Nginx Stream 层精准定位ngx_stream_geoip_module
1.模块定位
- 工作层次：Stream (TCP/UDP) 代理层，在握手前即可根据客户端 IP 查询 MaxMind GeoIP/GeoLite 数据库。
- 功能摘要：自动生成
$geoip_*变量（国家、州、省、市、经纬度、组织等），与map / limit_conn / access / proxy_pass等指令联动，实现按地域的流量引导、限速、灰度、风控。官方手册详述所有字段。(nginx.org)
2.准备与编译
| 步骤 | 关键命令 / 说明 |
|---|---|
| 1. 安装依赖 | apt install libgeoip-dev（或 yum install geoip-devel） |
| 2. 编译 Nginx | ./configure --with-stream --with-stream_geoip_module ... |
| 3. 下载数据库 | 注册 MaxMind 账户 → geoipupdate 自动拉取 GeoIP.dat / GeoLiteCity.dat 等二进制库；建议月度计划任务刷新。(dev.maxmind.com) |
| 4. 校验 IPv6 | GeoIP Legacy 数据库提供 *.dat.gz 的 IPv6 扩展版；IPv4 将作为 IPv4-mapped IPv6 (::ffff:a.b.c.d) 进行查表。(nginx.org) |
注意：MaxMind 早已宣布 GeoIP Legacy 停更，官方主推 GeoIP2 MMDB 格式；Nginx 现行 OSS 仍内置 Legacy 模块，但长期建议迁移到第三方 ngx_stream_geoip2_module 或 HTTP 的官方 GeoIP2 动态模块。(github.com)
3.核心指令与变量
| 指令 | 常用变量 | 典型用途 |
|---|---|---|
geoip_country | $geoip_country_code / $geoip_country_name | 基于国别智能选源、黑白名单 |
geoip_city | $geoip_city_continent_code / $geoip_city / $geoip_latitude / $geoip_longitude | 同城就近接入、LBS、日志埋点 |
geoip_org | $geoip_org | 根据 ISP/组织做 QoS 或限流 |
变量命名规则：所有字段前缀一致，易于在日志或 Lua 内部引用。
4.实战配置模板
# ① 加载 GeoIP 数据库
stream {geoip_country /usr/share/GeoIP/GeoIP.dat;geoip_city /usr/share/GeoIP/GeoLiteCity.dat;# ② 根据洲别映射到最近数据中心map $geoip_city_continent_code $nearest_dc {default dc-global.example.com;EU eu.example.com;NA na.example.com;AS as.example.com;}# ③ TCP 负载均衡示例 (MQTT)upstream mqtt_pool {server eu.backend.local:1883 backup;server na.backend.local:1883 backup;server as.backend.local:1883 backup;}server {listen 1883 reuseport;proxy_pass $nearest_dc;# ④ 国别风控：禁止受制裁国家if ($geoip_country_code = "KP") { return 444; }# ⑤ 按城市限速：非北京流量降至 1 MiB/sif ($geoip_city != "Beijing") { set $limit_rate 1m; }access_log /var/log/nginx/mqtt_geo.log'$remote_addr $geoip_country_code $geoip_city $status';}
}
5.维护与更新
-
数据库自动更新
0 4 * * 3 /usr/bin/geoipupdate -f /etc/GeoIP.conf -v nginx -s reload -
监控字段变更：MaxMind 偶尔校正行政分区；2025-05-28 曾离线修复小批量坐标错误，需关注 Release Notes RSS 并及时刷新。(dev.maxmind.com)
-
评估精度：GeoLite ≈ 95% 国别、60-75% 城市；对金融合规或精准广告场景应考虑付费 GeoIP Enterprise / Insights。(dev.maxmind.com)
6.性能与最佳实践
| 建议 | 背景 |
|---|---|
专库专用：仅加载所需的几个 .dat，多文件会拉长主进程启动时间。 | |
| 懒加载变量：变量未被引用不会触发查表，可放心定义备用。 | |
变更 “listen” 即时生效：GeoIP 查表在 worker 进程内存完成，reload 不丢连接。 | |
多层防护：结合 stream_geo_access / iptables，GeoIP 做精细决策，前端防火墙做粗粒度 IP 拒绝，双层保障。 |
7.迁移展望：拥抱 GeoIP2
由于 GeoIP Legacy 官方停更，推荐：
# 使用第三方动态模块
./configure \--add-dynamic-module=/path/to/ngx_stream_geoip2_module# 在配置中改为
geoip2 /usr/share/GeoIP/GeoIP2-City.mmdb {auto_reload 60m;$geoip2_country_code country iso_code;$geoip2_city city names en;
}
GeoIP2 提供 JSON-Like 字段、自动热加载、与 IPv6 完整兼容，是未来首选方案。
8.结语
ngx_stream_geoip_module 让 Nginx 在 传输层 即可感知客户端地理属性，为跨区域多活、合规风控和精准限流提供了高效、零开销的基础设施。尽管 Legacy 库已进入维护尾声，但在闭源或内网场景仍具备快速落地价值；前瞻性项目可尽早评估 GeoIP2 方案，实现 更准确的数据 + 自动热更新 + 长期社区支持。