GeoIP 处理器

GeoIP 处理器 #

需要 ingest-geoip 插件

geoip 处理器根据 IP 地址查询 MaxMind GeoLite2 数据库，为文档添加地理位置信息，包括国家、城市、经纬度、时区和 ASN 等。该处理器非常适合日志分析、流量审计和用户来源可视化等场景。

语法 #

{
  "geoip": {
    "field": "ip"
  }
}

配置参数 #

参数是否必填描述
field必填包含 IP 地址的源字段名。支持 IPv4 和 IPv6
target_field可选存储地理位置信息的目标字段。默认为 geoip
database_file可选使用的 MaxMind 数据库文件名。默认为 GeoLite2-City.mmdb
properties可选要提取的属性列表。未指定时根据数据库类型使用默认属性集（见下表）
ignore_missing可选为 true 时，如果源字段缺失或为 null，则跳过处理不报错。默认为 false
first_only可选当源字段为数组时，为 true 仅返回第一个匹配结果；为 false 返回所有匹配结果的列表。默认为 true
description可选处理器的简要描述
if可选处理器运行的条件
ignore_failure可选为 true 时，处理器出错后忽略继续执行。默认为 false
on_failure可选处理器失败时运行的处理器列表
tag可选处理器的标识标签

支持的数据库 #

处理器根据数据库类型后缀自动识别数据库格式：

数据库文件名说明
GeoLite2-CityGeoLite2-City.mmdb城市级定位，含经纬度（默认）
GeoLite2-CountryGeoLite2-Country.mmdb国家级定位
GeoLite2-ASNGeoLite2-ASN.mmdb自治系统编号（ASN）信息

也可以将自定义的 .mmdb 数据库文件放入 plugins/ingest-geoip/ 目录使用。

可提取属性 #

City 数据库（默认） #

属性说明默认提取
continent_name所在大洲✅
country_iso_codeISO 国家代码✅
country_name国家名称✅
region_iso_codeISO 3166-2 地区代码（如 CN-BJ）✅
region_name地区/省份名称✅
city_name城市名称✅
location经纬度坐标（{"lat": ..., "lon": ...}）✅
timezone时区❌
ip格式化的 IP 地址❌

Country 数据库 #

属性说明默认提取
continent_name所在大洲✅
country_iso_codeISO 国家代码✅
country_name国家名称✅
ip格式化的 IP 地址❌

ASN 数据库 #

属性说明默认提取
ip格式化的 IP 地址✅
asn自治系统编号✅
organization_name组织名称✅
network网段 CIDR✅

如何使用 #

步骤 1：安装插件 #

bin/easysearch-plugin install ingest-geoip

安装后重启节点。

步骤 2：创建管道 #

以下管道使用 City 数据库为包含 IP 地址的文档添加地理位置信息：

PUT /_ingest/pipeline/geoip_pipeline
{
  "description": "根据 IP 地址添加地理位置信息",
  "processors": [
    {
      "geoip": {
        "field": "client_ip"
      }
    }
  ]
}

步骤 3：测试管道 #

POST /_ingest/pipeline/geoip_pipeline/_simulate
{
  "docs": [
    {
      "_source": {
        "client_ip": "8.8.8.8"
      }
    }
  ]
}

响应示例：

{
  "docs": [
    {
      "doc": {
        "_source": {
          "client_ip": "8.8.8.8",
          "geoip": {
            "continent_name": "North America",
            "country_iso_code": "US",
            "country_name": "United States",
            "region_iso_code": "US-CA",
            "region_name": "California",
            "city_name": "Mountain View",
            "location": {
              "lat": 37.386,
              "lon": -122.0838
            }
          }
        }
      }
    }
  ]
}

使用 ASN 数据库 #

PUT /_ingest/pipeline/geoip_asn_pipeline
{
  "description": "根据 IP 地址添加 ASN 信息",
  "processors": [
    {
      "geoip": {
        "field": "client_ip",
        "target_field": "asn_info",
        "database_file": "GeoLite2-ASN.mmdb"
      }
    }
  ]
}

选择特定属性 #

只提取国家代码和城市名称：

{
  "geoip": {
    "field": "client_ip",
    "properties": ["country_iso_code", "city_name"]
  }
}

结合多个数据库 #

同时获取城市定位和 ASN 信息：

PUT /_ingest/pipeline/geoip_full_pipeline
{
  "description": "获取完整的地理位置和 ASN 信息",
  "processors": [
    {
      "geoip": {
        "field": "client_ip",
        "target_field": "geo"
      }
    },
    {
      "geoip": {
        "field": "client_ip",
        "target_field": "asn",
        "database_file": "GeoLite2-ASN.mmdb"
      }
    }
  ]
}

注意事项 #

  • 如果 IP 地址在数据库中未找到，处理器不会添加 target_field（不会报错）
  • 查询结果会缓存在内存中（默认缓存 1000 条），可通过节点设置 ingest.geoip.cache_size 调整缓存大小
  • 数据库默认通过内存映射文件（mmap）加载；设置系统属性 es.geoip.load_db_on_heap=true 可将数据库完整加载到堆内存
©INFINI.LTD, All Rights Reserved.