nginx 集成 geoip2 可解析 ip 地理信息并注入日志、header 或后端变量，关键在于准确解析、低延迟注入与安全可用；需源码编译支持模块，配置 mmdb 数据库与变量映射，合理注入上下文，并保障更新、ipv6、性能及隐私合规。
利用 Nginx 网关集成 GeoIP2 模块，可基于真实 IP 解析出国家、省份、城市、经纬度、ISP、时区等地理信息，并在请求处理阶段直接注入到日志、Header 或后端变量中，为流量画像提供结构化地域标签。关键不在“装模块”，而在“准确解析+低延迟注入+安全可用”。
一、编译安装支持 GeoIP2 的 Nginx（非动态模块）
官方 nginx 未内置 libmaxminddb 支持，需源码编译：
1. 安装依赖：libmaxminddb（≥1.3.0）、cmake、gcc；
2. 下载 nginx 源码及 ngx_http_geoip2_module；
3. configure 时添加：
--add-module=/path/to/ngx_http_geoip2_module \
--with-compat
4. make && make install；
注意：不建议用 apt/yum 安装的预编译包，多数不含 geoip2 支持。
二、配置 GeoIP2 数据库与变量映射
下载 MaxMind GeoLite2 City/ASN 免费数据库（需注册账号获取 License Key），解压后配置如下：
在 nginx.conf http 块中添加：
geoip2 /usr/share/GeoIP/GeoLite2-City.mmdb {
$geoip2_data_country_code source=$remote_addr country iso_code;
$geoip2_data_city_name source=$remote_addr city name;
$geoip2_data_latitude source=$remote_addr location latitude;
$geoip2_data_longitude source=$remote_addr location longitude;
$geoip2_data_asn_number source=$remote_addr autonomous_system_number;
}
✅ 关键点：
• 使用 source=$remote_addr 确保解析原始客户端 IP（若经代理，需先用 real_ip 模块还原）；
• 变量名可自定义，但必须以 $ 开头且命名规范；
• 多个数据库（如 City + ASN）可分别声明，避免单文件过大影响性能。
三、将地理标签注入流量上下文
获得变量后，按需注入到不同环节：
-
写入 access_log：在 log_format 中引用变量，例如：
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" "$http_user_agent" '
'$geoip2_data_country_code $geoip2_data_city_name $geoip2_data_latitude $geoip2_data_longitude'; -
透传给后端服务：用 proxy_set_header 注入 Header：
proxy_set_header X-Geo-Country $geoip2_data_country_code;
proxy_set_header X-Geo-City $geoip2_data_city_name;
proxy_set_header X-Geo-Coords "$geoip2_data_latitude,$geoip2_data_longitude"; -
用于条件路由或限流：结合 map 或 if（谨慎使用）做地域策略，例如只允许中国 IP 访问管理接口：
if ($geoip2_data_country_code != "CN") { return 403; }（生产环境推荐用 map + error_page 替代裸 if）
四、保障准确性与稳定性
GeoIP2 不是 100% 精准，需主动应对误差场景：
- IP 归属滞后：CDN 节点、NAT 网关、移动基站出口 IP 经常变更，建议每 4 周自动更新 mmdb 文件（MaxMind 提供 weekly 更新）；
- IPv6 支持：确认所用 mmdb 文件含 IPv6 数据（GeoLite2-City.mmdb 默认支持），且 nginx 编译时开启 IPv6；
- 性能开销：单次查询耗时约 0.02–0.05ms，高并发下建议启用 shared memory cache（模块默认已启用，无需额外配置）；
- 隐私合规：部分区域（如欧盟）将城市级定位视为个人数据，记录前应评估 GDPR/PIPL 合规性，敏感字段可脱敏（如仅保留国家码）。
