ymuski/geo-checker

geo-checker

镜像概述和主要用途

geo-checker是一个基于openresty（nginx）的Docker镜像，集成了geoip2模块、geoipupdate工具和cron服务。该镜像主要用于提供IP地理位置查询服务，能够根据IP地址返回对应的国家代码和名称，并通过geoipupdate结合cron实现GeoIP数据库的自动更新，确保地理信息的准确性。

核心功能和特性

• 集成geoip2模块：基于nginx的geoip2模块，实现IP地址的地理位置解析
• 自动更新数据库：内置geoipupdate工具和cron服务，定期从MaxMind更新GeoIP数据库
• 多IP获取方式：支持通过请求头（X-Custom-Real-Ip、X-Real-Ip、CF-Connecting-IP，优先级从高到低）或URL路径（如/ip/1.1.1.1）指定查询IP
• 丰富响应格式：返回JSON格式的响应体（包含IP、国家代码iso2Code、国家名称name）和自定义响应头（X-Real-IP、X-Geo-Country-Code、X-Geo-Country-Name）

使用场景和适用范围

• 需要快速获取IP地理位置信息的微服务或应用
• 需自动维护和更新GeoIP数据库的场景
• 作为反向代理后端，为前端服务提供IP地理信息支持
• 开发和测试环境中验证IP地理解析功能

使用方法和配置说明

环境准备

1. 从maxmind.com获取GeoIP凭证（AccountID和LicenseKey）
2. 设置环境变量：

   shell
   export GEOIP_ACCOUNTID="你的AccountID"       # 从maxmind获取的AccountID
   export GEOIP_LICENSEKEY="你的LicenseKey"   # 从maxmind获取的LicenseKey
   export GEOIP_EDITIONID="GeoLite2-Country"  # 数据库类型，可选"GeoLite2-Country"或"GeoIP2-Country"
   

Docker运行命令

后台模式

shell
docker run -d \
  -v /tmp/geoip/:/usr/share/geoip/ \  # 挂载目录存储GeoIP数据库（持久化）
  -e GEOIP_ACCOUNTID=$GEOIP_ACCOUNTID \
  -e GEOIP_LICENSEKEY=$GEOIP_LICENSEKEY \
  -e GEOIP_EDITIONID=$GEOIP_EDITIONID \
  --name geo-checker \
  -p 8080:80 \                         # 映射端口（容器内80端口）
  ymuski/geo-checker:latest

交互模式

shell
docker run --rm -it \                  # --rm：退出后删除容器；-it：交互模式
  -v ${PWD}/tmp/geoip/:/usr/share/geoip/ \  # 当前目录下的tmp/geoip目录作为数据库存储
  -e GEOIP_ACCOUNTID=$GEOIP_ACCOUNTID \
  -e GEOIP_LICENSEKEY=$GEOIP_LICENSEKEY \
  -e GEOIP_EDITIONID=$GEOIP_EDITIONID \
  --name geo-checker \
  -p 8080:80 \
  ymuski/geo-checker

测试方法

可通过curl命令测试服务，支持以下IP指定方式（优先级从高到低）：

1. X-Custom-Real-Ip请求头（最高优先级）：

   shell
   curl localhost:8080 -H "X-Custom-Real-Ip: 1.1.1.1"
   

2. X-Real-Ip请求头：

   shell
   curl localhost:8080 -H "X-Real-Ip: 1.1.1.1"
   

3. CF-Connecting-IP请求头：

   shell
   curl localhost:8080 -H "CF-Connecting-IP: 1.1.1.1"
   

4. URL路径参数：

   shell
   curl localhost:8080/ip/1.1.1.1
   

响应格式

响应体（JSON）

json
{"IP":"1.1.1.1","iso2Code":"AU","name":"Australia"}

响应头

X-Real-IP: 1.1.1.1                # 查询的IP地址
X-Geo-Country-Code: AU            # 国家代码（ISO 3166-1 alpha-2）
X-Geo-Country-Name: Australia     # 国家名称

镜像构建和拉取

• 构建镜像：

  shell
  docker build -t ymuski/geo-checker .
  

• 拉取镜像：

  shell
  docker pull ymuski/geo-checker
  

注意事项

作为反向代理时的配置

• 普通nginx作为反向代理：

  nginx
  location / {
      proxy_set_header X-Real-IP $remote_addr;  # 传递客户端真实IP
      proxy_pass http://127.0.0.1:8080;         # 代理到geo-checker服务
  }
  

• Cloudflare + nginx作为反向代理：

  nginx
  location / {
      proxy_pass http://127.0.0.1:8080;  # Cloudflare会自动设置CF-Connecting-IP头
  }
  

数据库持久化

建议通过-v参数挂载本地目录到/usr/share/geoip/，避免容器重启后GeoIP数据库丢失，减少重复下载。