arbal/geoip-service

geoip-service镜像说明

镜像概述

geoip-service是一个高性能的内存型HTTP微服务，用于查询MaxMind GeoIP2和GeoLite2数据库，实现IP地址到地理位置的映射。它具备极高的并发处理能力，无缓存时每秒可处理3万+请求，缓存开启后可达11万+请求，且无缓存时内存占用小于100MB，适用于各类需要IP地理定位的场景。

核心功能

1. 快速地理定位：支持基于MaxMind数据库的城市和国家级别IP定位查询；
2. 高并发处理：经测试可应对高流量场景，性能表现优异；
3. 灵活缓存策略：可配置缓存时间，提升重复查询的响应速度；
4. Docker友好：支持Docker部署，方便集成到容器化环境中；
5. 多参数配置：可自定义监听端口、数据库路径、输出格式等参数。

使用场景

1. 网站访问者地理位置统计与分析；
2. 基于用户IP的内容个性化推荐（如区域化内容展示）；
3. 网络安全领域的IP来源追踪与风险评估；
4. 日志分析中补充IP对应的地理信息；
5. 企业内部系统的IP定位需求（如员工访问位置监控）。

配置说明

前提条件

需提前下载MaxMind数据库文件：

• 免费版：GeoLite2数据库（选择"MaxMind DB binary, gzipped"版本并解压）；
• 付费版：GeoIP2下载数据库（需验证兼容性）。

Docker部署示例

拉取镜像

bash
docker pull arbal/geoip-service

基本运行（挂载数据库文件）

假设本地数据库文件路径为/local/GeoLite2-City.mmdb：

bash
docker run --rm -v /local/GeoLite2-City.mmdb:/data/geodb.mmdb arbal/geoip-service

映射端口到主机

将容器的5000端口映射到主机的3000端口：

bash
docker run --rm -p 127.0.0.1:3000:5000 -v /local/GeoLite2-City.mmdb:/data/geodb.mmdb arbal/geoip-service

自定义参数

指定数据库路径、开启格式化输出：

bash
docker run --rm -p 127.0.0.1:3000:5000 -v /local/GeoLite2-City.mmdb:/data/geodb.mmdb arbal/geoip-service app -db="/data/geodb.mmdb" -pretty=true

服务参数说明

Usage of geoip-service:
  -db="GeoLite2-City.mmdb": MaxMind数据库文件路径
  -listen=":5000": 监听地址和端口（如127.0.0.1:5000）
  -lookup="city": 查询类型（city或country，取决于数据库类型）
  -pretty=false: 是否格式化输出JSON结果
  -threads=4: 线程数（默认等于CPU核心数）
  -cache=0: 缓存时间（秒，0表示禁用缓存）

使用方法

服务启动后，通过HTTP请求查询IP地址：

GET http://localhost:5000/1.2.3.4

成功时返回包含地理信息的JSON数据，失败时返回错误信息（如无效IP）。建议开启连接保持（keepalive）以提升高吞吐量场景下的性能。

Credits

基于https://github.com/oschwald/geoip2-golang%E5%BA%93%E5%AE%9E%E7%8E%B0%EF%BC%8C%E7%A1%AE%E4%BF%9D%E4%BA%86%E6%9F%A5%E8%AF%A2%E7%9A%84%E9%AB%98%E6%95%88%E6%80%A7%E3%80%82