IP地理位置REST API

![geoip-api ci构建]([] ![docker拉取量]([] !GitHub发布日期 !GitHub最后提交 !apache许可证

♻️ 这是@shopping24原始仓库的官方维护分支，由@tboeghk维护。

本项目提供一个简单的REST Web服务，用于返回给定IP地址的地理位置信息。该服务从Maxminds GeoLite2（免费）或GeoIP2 City（商业）数据库加载位置信息。

您可以在微服务架构中使用此项目，当多个服务需要请求地理位置数据时尤为适用。该服务可与Logstash http过滤器插件配合使用，以丰富日志数据。

• 运行容器
• 使用API
• Kubernetes与Docker-Compose示例

💨 运行容器

Docker Hub上提供的Docker镜像捆绑了最新的GeoLite2城市数据库。容器每周构建一次，包含最新版本的数据库。

$ docker run -p 8080:8080 ghcr.io/observabilitystack/geoip-api:latest

$ docker run -p 8080:8080 observabilitystack/geoip-api:latest

可用标签与仓库

💡 尽管在生产环境中不推荐使用latest标签运行容器，但对于geoip-api，我们强烈建议使用latest以获取最新的地理位置数据。

• 镜像同时在Docker Hub和GitHub Container Registry提供。
• 镜像标签格式为yyyy-VV（年份和周数）。
• 最新容器标记为latest。
• 支持amd64和arm64架构。
• 数据和代码每周更新。

使用自定义（商业）数据库

☝️ 在生产环境中，强烈建议使用商业版Maxmind GeoIP2 City数据库，因其具有更高的精度和数据质量。

您可以将mmdb格式的数据库挂载到容器中。数据库位置可通过以下变量自定义：

示例

examples文件夹包含在Docker-Compose或Kubernetes中运行geoip-api的示例。

🤓 使用API

查询API的推荐方式是通过简单的HTTP GET请求。将待解析的IP地址作为路径参数提供。

$ curl -s http://localhost:8080/8.8.8.8
{
  "country": "US",
  "latitude": "37.751",
  "longitude": "-97.822",
  "continent": "NA",
  "timezone": "America/Chicago",
  "accuracyRadius": 1000,
  "asn": 15169,
  "asnOrganization": "GOOGLE",
  "asnNetwork": "8.8.8.0/24"
}
$ curl -s "http://localhost:8080/$(curl -s [***]"
{
  "country": "DE",
  "stateprov": "Free and Hanseatic City of Hamburg",
  "stateprovCode": "HH",
  "city": "Hamburg",
  "latitude": "53.5742",
  "longitude": "10.0497",
  "continent": "EU",
  "timezone": "Europe/Berlin",
  "asn": 15943,
  "asnOrganization": "wilhelm.tel GmbH"
}

附加数据链接

Geoip-API在Link头中返回指向详细滥用和RIPE信息的链接。ripe-asn信息可直接获取。abuse链接需要注册并获取API密钥才能访问。

curl  "http://localhost:8080/$(curl -s [***]"
HTTP/1.1 200
Link: <[***]>; rel="abuse",
      <[***]>; rel="ripe-asn"

{
  "country": "DE",
  "stateprov": "Land Berlin",
  "stateprovCode": "BE",
  "city": "Berlin",
  "latitude": "52.5196",
  "longitude": "13.4069",
  "continent": "EU",
  "timezone": "Europe/Berlin",
  "accuracyRadius": 200,
  "asn": 8881,
  "asnOrganization": "1&1 Versatel Deutschland GmbH",
  "asnNetwork": "104.151.0.0/17"
}

通过HTTP头查询

X-Geoip-Address头是查询API的另一种方式（如Nginx-Geoip示例中使用）。在此方式中，待解析的地址作为头值提供，地理位置信息也通过头值返回，返回码始终为204。

$ curl -sI -H "X-Geoip-Address: $(curl -s [***]" "http://localhost:8080/"
HTTP/1.1 204
X-Geoip-Country: DE
X-Geoip-StateProv: Free and Hanseatic City of Hamburg
X-Geoip-City: Hamburg
X-Geoip-Latitude: 53.6042
X-Geoip-Longitude: 10.0596
X-Geoip-Continent: EU
X-Geoip-Timezone: Europe/Berlin

通过POST查询多个IP

curl --location 'http://localhost:8080/' \
--header 'Content-Type: application/json' \
--data '[
    "8.8.8.8",
    "8.8.4.4"
]'

{
  "8.8.4.4": {
    "country":"US",
    "latitude":"37.751",
    "longitude":"-97.822",
    "continent":"NA",
    "timezone":"America/Chicago",
    "accuracyRadius":1000,
    "asn":15169,
    "asnOrganization":"GOOGLE",
    "asnNetwork":"8.8.4.0/24"
  },
  "8.8.8.8": {
    "country":"US",
    "latitude":"37.751",
    "longitude":"-97.822",
    "continent":"NA",
    "timezone":"America/Chicago",
    "accuracyRadius":1000,
    "asn":15169,
    "asnOrganization":"GOOGLE",
    "asnNetwork":"8.8.8.0/24"
  }
}

一次最多支持100个地址。

结果为JSON对象，按请求的IP地址索引。

若请求的地址无法解析，响应中将缺少该条目。

📦 构建项目

项目通过多阶段Docker构建。需要有效的Maxmind许可证密钥以下载Geoip2数据库。

$ export MAXMIND_LICENSE_KEY=...
$ docker build \
    --build-arg MAXMIND_LICENSE_KEY=${MAXMIND_LICENSE_KEY} \
    --build-arg VERSION=$(date +%Y-%V) \
    -t geoip-api:latest .

若要构建（或测试）多平台镜像，使用Docker Buildx扩展：

$ docker buildx create --use --name multi-platform
$ docker buildx build \
    --platform linux/amd64,linux/arm64 \
    --build-arg MAXMIND_LICENSE_KEY=${MAXMIND_LICENSE_KEY} \
    -t geoip-api:latest-native -f Dockerfile.native .

👋 贡献

我们期待您的评论、问题和拉取请求！

⚖️ 许可证

本项目采用Apache License, Version 2许可证。

本产品包含MaxMind创建的GeoLite2数据，可从[***]