Nginx 可通过 ngx_http_geoip2_module 实现城市级访问控制:需编译安装模块、加载 GeoLite2-City.mmdb 数据库,用 map 预定义黑白名单,配合 set_real_ip_from 正确提取真实 IP,并注意数据精度与性能优化。

使用 Nginx 的 ngx_http_geoip2_module 模块,可以基于客户端真实 IP 解析出国家、省份、城市等地理信息,并结合 map 或 if 指令实现城市级访问控制。关键在于:IP 数据源要准、模块配置要稳、匹配逻辑要慎(尤其避免在 location 中滥用 if)。
一、编译安装 geoip2_module 并加载 MaxMind 数据库
该模块不随 Nginx 默认发布,需手动编译或通过包管理器安装(如 Ubuntu 22.04+ 可用 nginx-module-geoip2)。核心步骤如下:
- 下载最新版 GeoLite2 City 数据库(
GeoLite2-City.mmdb),注意必须用付费账号申请免费 License Key 才能下载;不能用已停更的 GeoLite1(.dat 格式) - 确认 Nginx 已启用该模块:
nginx -V 2>&1 | grep -o with-http-geoip2-module - 在
http块中加载数据库与基础变量:http { geoip2 /path/to/GeoLite2-City.mmdb { $geoip2_data_country_code source=$remote_addr country iso_code; $geoip2_data_country_name source=$remote_addr country names en; $geoip2_data_province_name source=$remote_addr subdivisions 0 names en; $geoip2_data_city_name source=$remote_addr city names en; $geoip2_data_latitude source=$remote_addr location latitude; $geoip2_data_longitude source=$remote_addr location longitude; } }
二、用 map 构建城市白名单/黑名单映射表
推荐用 map 指令预定义控制规则,比在 location 中写 if 更高效安全。例如只允许北京、上海、深圳用户访问后台:
- 在
http块中定义映射:map $geoip2_data_city_name $allowed_city { default 0; "Beijing" 1; "Shanghai" 1; "Shenzhen" 1; # 注意:英文名以 MaxMind 返回为准,可用日志临时打印验证 } - 在 server 或 location 中拦截非授权城市请求:
location /admin/ { if ($allowed_city = 0) { return 403 "Access denied from your city."; } # 后续正常代理或静态服务 } - 若需按中文城市名匹配(如“北京市”),需确认数据库返回值含中文(需在 geoip2 指令中指定
names zh-CN),且 Nginx 编译支持 UTF-8 字符比较
三、处理代理与真实 IP 提取问题
直接读 $remote_addr 会拿到 CDN 或反向代理 IP,导致地理定位失效。必须正确提取客户端真实 IP:
- 确保上游(如 CDN、LB)通过
X-Forwarded-For或自定义头(如X-Real-IP)透传原始 IP - 在
http块开头设置:set_real_ip_from 10.0.0.0/8; # 你自己的内网段 set_real_ip_from 192.168.0.0/16; real_ip_header X-Forwarded-For; real_ip_recursive on;
- 验证是否生效:加一条日志记录
$remote_addr和$geoip2_data_city_name,对比访问日志中的 IP 是否为真实用户出口 IP
四、调试与注意事项
城市级控制粒度细,但容易因数据不准或配置疏漏导致误拦或放行:
- MaxMind 城市识别有误差,尤其对移动网络、教育网、云主机 IP,建议搭配 IP 归属接口做二次校验(Nginx 不适合,可交由后端)
- 避免在
if中嵌套复杂逻辑;禁止在if内使用 proxy_pass —— 应改用map + error_page或交给 upstream 处理 - 高并发下频繁查 mmdb 文件可能影响性能,建议配合
geoip2_cache_size(需模块 v3.4+)缓存热数据 - 测试时用不同地区代理(如 Cloudflare WARP、手机热点切换)验证,不要仅依赖本地 IP











