Docker部署Nginx GeoIP2 日志国家字段显示横杠问题排查

字段始终返回-的核心原因是业务侧Nginx配置缺失GeoIP2运行的三个必要环节，模块未正常工作、变量未完成赋值：

• 全局配置段未加载GeoIP2动态模块，Nginx本身未识别对应功能
• http块未指定GeoIP2 IP库路径，也未配置IP库字段到Nginx变量的映射规则，$geoip2_data_country_code、$geoip2_data_country_name两个变量未被赋值
• 日志格式未关联对应变量，即便变量有值也不会被输出到访问日志中

按以下顺序补全配置即可，所有路径请替换为你镜像内的实际路径：

1. 加载动态模块
   在nginx.conf最顶部（全局段，位于events、http块之前）添加模块加载配置：

load_module modules/ngx_http_geoip2_module.so;
# 若不需要四层流代理的GeoIP能力，下一行可省略
load_module modules/ngx_stream_geoip2_module.so;

配置完成后先执行nginx -t校验，如果提示模块不存在，在容器内执行find / -name "ngx_http_geoip2_module.so"查询实际安装路径替换即可。

2. 加载IP库并配置变量映射
   在http {}块的起始位置添加GeoIP2库加载规则，将IP查询结果映射到对应变量：

http {
    # 请替换为容器内GeoLite2-Country.mmdb文件的实际绝对路径
    geoip2 /etc/nginx/geoip/GeoLite2-Country.mmdb {
        $geoip2_data_country_code source=$remote_addr country iso_code;
        # 需要中文国家名就保留zh-CN，需要英文就替换为en
        $geoip2_data_country_name source=$remote_addr country names zh-CN;
    }

    # 原有http块的其余配置保持不变
}

注意确认mmdb文件权限可读，Nginx运行用户对该文件有访问权限，否则会出现启动报错或变量空值问题。

3. 配置带GeoIP字段的日志格式
   在http块内新增专用日志格式，将两个GeoIP变量加入输出字段：

http {
    # 接上述geoip2配置
    log_format geoip_main '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for" '
                      '$geoip2_data_country_code $geoip2_data_country_name';

    # 原有其余配置保持不变
}

随后在对应业务站点的server {}块中，将access_log指定为使用该日志格式：

server {
    listen 80;
    server_name 你的业务域名;
    access_log /var/log/nginx/access.log geoip_main;

    # 原有站点配置保持不变
}

4. 重载配置验证
   所有配置修改完成后，执行nginx -t确认语法无报错，再执行nginx -s reload重载Nginx配置，使用公网IP访问站点后查看日志，即可看到对应国家字段正常输出。

如果配置补全后字段仍然返回-，按以下顺序排查：

• 测试访问的源IP不能是内网/保留地址段，这类IP在GeoIP2库中无归属地信息，默认返回-
• 确认使用的mmdb文件是完整、未损坏的GeoLite2-Country库，不要误用城市库或版本不兼容的库文件
• 如果服务前端部署了CDN、反向代理，$remote_addr获取到的是代理节点IP而非真实用户IP，需要将geoip2配置中的source字段改为从X-Forwarded-For请求头取真实IP，同时配置可信代理IP段防止头伪造
• 确认Nginx工作进程对mmdb文件有读权限，权限不足时模块无法读取库内容，变量会返回空值

内容的提问来源于stack exchange，提问作者Kosmylo