From 10a31fe9dd39efc10ecc12c12d42bc23510be33c Mon Sep 17 00:00:00 2001 From: 窦凤虎 Date: Sat, 2 Sep 2023 06:26:03 +0000 Subject: Update IPLookup 使用文档 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- help/IPGEO.md | 152 +++++++++++++++++++++++++++++++++------------------------- 1 file changed, 88 insertions(+), 64 deletions(-) diff --git a/help/IPGEO.md b/help/IPGEO.md index 79acdb5..85795fc 100644 --- a/help/IPGEO.md +++ b/help/IPGEO.md @@ -1,106 +1,130 @@ -# Galaxy IPGEO 使用文档 +# IPLookup 使用文档 -Galaxy IPGEO 即数据平台下的galaxy-tool支持的IP定位功能。最终的数据格式为MaxMind DB 二进制格式（mmdb），当然我们也支持提供CSV或SQL数据库表的数据格式（只要满足schema属性约束），数据平台将会在合适时间进行转换为二进制格式。 +IPLookupV2 基于IP地址获取地理位置或ASN（自治系统号码）信息。核心功能： +- [构建GeoIP Databases 文件](https://docs.geedge.net/pages/viewpage.action?pageId=39135257) +- 通过开源解析库[MaxMind DB Reader](https://github.com/maxmind/MaxMind-DB-Reader-java)生成Reader 对象 -## 工具类信息 +## 功能设计 -因ASN与IP位置信息的差异性，将IPGEO分为两个工具类： - -- ASNLookup 针对IP映射ASN工具类 -- IPLookup 支持IP映射国家、地区、经纬度、ASN信息（支持ASNLookup部分功能） - -## 数据库 - -所属数据库默认处于dat目录下，加载文件将以mmdb结尾。不指定加载数据库情况下，默认文件名如下： +因IP知识库来源不同，默认分两种类型数据库：IP-ASN 和 IP-LOCATION。具体实现类： +- IPLookup IP地址映射为国家，地区，经纬度及ASN(内置ASNLookup类) 等。 +- ASNLookup IP地址映射AS号，组织及国家编码等。 +## 数据库信息 +GeoIP 数据库文件默认存储在 "dat目录" 中，并且在加载工具类时，如果没有指定数据库文件的路径，它将自动加载默认路径下的数据库文件。默认文件名如下： | Name | Filename | Description | | ----------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -| 公共IP定位库 | ip.mmdb
ip_v4.mmdb
Ip_v6.mmdb | 公共IP定位库，包含All，v4，v6
来自于第三方购买或其它开源数据； | -| 自定义IP定位库 | ip_private.mmdb
ip_private_v4.mmdb
ip_private_v6.mmdb | 自定义IP定位库，包含All，v4，v6
来自与用户预置的自定义数据，一般权威性较高。 | -| 公共IP映射ASN库 | asn.mmdb
asn_v4.mmdb
asn_v6.mmdb | 公共IP映射ASN库，包含All，v4，v6
来自于第三方购买或其它开源数据； | -| 自定义IP映射ASN库 | asn_private.mmdb
asn_private_v4.mmdb
asn_private_v6.mmdb | 自定义IP映射ASN库，包含All，v4，v6
来自与用户预置的自定义数据，一般权威性较高。 | - - +| 基础IP定位库 | ip.mmdb
ip_v4.mmdb
Ip_v6.mmdb | IP基础定位库，一般来源于系统内置或第三方购置；包括全局，v4格式和v6格式。
| +| 用户自定义IP定位库 | ip_private.mmdb
ip_private_v4.mmdb
ip_private_v6.mmdb | 用户自定义IP定位库，一般来源于企业或运营商内部的知识库，相对权威和可信度更高；包括全局，v4格式和v6格式。
| +| 基础ASN库 | asn.mmdb
asn_v4.mmdb
asn_v6.mmdb | 基础ASN库，一般来源于系统内置或第三方购置；包括全局，v4格式和v6格式。 | +| 用户自定义ASN库 | asn_private.mmdb
asn_private_v4.mmdb
asn_private_v6.mmdb | 自定义IP映射ASN库，一般来源于企业或运营商内部的知识库，相对权威和可信度更高；包括全局，v4格式和v6格式。 | -## 执行方案 -### 数据库加载优先级 -> 相同类型库：具有相同特征的库，来自不同数据源或类型。例如ip.mmdb 可能包含 ip_v4.mmdb 与 ip_v6.mmdb，需要指定依赖的数据源执行顺序。 +## 实现方式 -如上所述，若同时加载多个相同类型库，系统根据IP特点会优先获取V4或V6库. +### 同类型不同格式数据库的加载顺序 +支持同时加载相同类型多个格式的IP定位库，基于下图将产生的DBReader对象顺序存储到LIST集合中。例如：基础库同时加载了v4，v6和 All(包含v4和v6)三个文件，读取时将优先使用v4和v6 DBReader。 ![默认加载顺序](help/images/ip_load_priortiy.png) -### 执行顺序 +### 不同类型数据库的执行顺序 -当同时指定公共与用户自定义库时，系统优先通过自定义库进行映射匹配。执行顺序如下： +当同时指定公共与用户自定义库时，将优先使用自定义库获取IP地理位置。执行顺序如下： -![映射优先级](help/images/ip_map.png) +![映射优先级](help/images/ip_map.jpg) -## 功能说明 +## 方法说明 -**IpLookup** +**IpLookupV2** | Name | Type | Description | | ------------------------------------------------------------ | ---------------- | -------------------------------------------------- | -| IpLookup.Builder(boolean isDefaultDB) | IpLookup.Builder | | -| Builder.loadDataFile(String ipDatabasePublicFile) | IpLookup.Builder | 加载公共IP定位库 | -| Builder.loadDataFileV4(String ipDatabasePublicFileV4) | IpLookup.Builder | 加载公共IPv4定位库 | -| Builder.loadDataFileV6(String ipDatabasePublicFileV6) | IpLookup.Builder | 加载公共IPv6定位库 | -| Builder.loadDataFilePrivate(String ipDatabasePrivateFile) | IpLookup.Builder | 加载用户自定义IP定位库 | -| Builder.loadDataFilePrivateV4(String ipDatabasePrivateFileV4) | IpLookup.Builder | 加载用户自定义IPv4定位库 | -| Builder.loadDataFilePrivateV6(String ipDatabasePrivateFileV6) | IpLookup.Builder | 加载用户自定义IPv6定位库 | -| Builder.loadAsnDataFile(String asnDatabasePublicFile) | IpLookup.Builder | 加载公共ASN定位库 | -| Builder.loadAsnDataFileV4(String asnDatabasePublicFileV4) | IpLookup.Builder | 加载公共ASN IPv4定位库 | -| Builder.loadAsnDataFileV6(String asnDatabasePublicFileV6) | IpLookup.Builder | 加载公共ASN IPv6定位库 | -| Builder.loadAsnDataFilePrivate(String asnDatabasePrivateFile) | IpLookup.Builder | 加载用户自定义ASN定位库 | -| Builder.loadAsnDataFilePrivateV4(String asnDatabasePrivateFileV4) | IpLookup.Builder | 加载用户自定义ASN IPv4定位库 | -| Builder.loadAsnDataFilePrivateV6(String asnDatabasePrivateFileV6) | IpLookup.Builder | 加载用户自定义ASN IPv6定位库 | -| Builder.build() | IpLookup | 构建IPGEO对象 | -| countryLookup(String ip) | String | 返回国家 | -| cityLookupDetail(String ip) | String | 返回详情，包含城市,省(州),国家;分隔符为英文逗号"," | -| cityLookup(String ip) | String | 返回所属城市，若不存在可返回国家信息； | -| latLngLookup(String ip) | String | 返回经纬度，格式：维度,经度 ；分隔符为英文逗号"," | +| IpLookupV2.Builder(boolean isDefaultDB) | IpLookupV2.Builder |是否使用默认数据库 | +| Builder.loadDataFile(String databaseFile) | IpLookupV2.Builder | 加载基础IP定位库 | +| Builder.loadDataFileV4(String databaseFile) | IpLookupV2.Builder | 加载基础IPv4定位库 | +| Builder.loadDataFileV6(String databaseFile) | IpLookupV2.Builder | 加载基础IPv6定位库 | +| Builder.loadDataFilePrivate(String databaseFile) | IpLookupV2.Builder | 加载用户自定义IP定位库 | +| Builder.loadDataFilePrivateV4(String databaseFile) | IpLookupV2.Builder | 加载用户自定义IPv4定位库 | +| Builder.loadDataFilePrivateV6(String databaseFile) | IpLookupV2.Builder | 加载用户自定义IPv6定位库 | +| Builder.loadAsnDataFile(String databaseFile) | IpLookupV2.Builder | 加载基础ASN库 | +| Builder.loadAsnDataFileV4(String databaseFile) | IpLookupV2.Builder | 加载基础IPv4 ASN库 | +| Builder.loadAsnDataFileV6(String databaseFile) | IpLookupV2.Builder | 加载基础IPv6 ASN库 | +| Builder.loadAsnDataFilePrivate(String databaseFile) | IpLookupV2.Builder | 加载用户自定义ASN库 | +| Builder.loadAsnDataFilePrivateV4(String databaseFile) | IpLookupV2.Builder | 加载用户自定义IPv4 ASN库 | +| Builder.loadAsnDataFilePrivateV6(String databaseFile) | IpLookupV2.Builder | 加载用户自定义IPv6 ASN库 | +| Builder.loadDataFile(Inputstream databaseStream) | IpLookupV2.Builder | 加载基础IP定位库 | +| Builder.loadDataFileV4(Inputstream databaseStream) | IpLookupV2.Builder | 加载基础IPv4定位库 | +| Builder.loadDataFileV6(Inputstream databaseStream) | IpLookupV2.Builder | 加载基础IPv6定位库 | +| Builder.loadDataFilePrivate(Inputstream databaseStream) | IpLookupV2.Builder | 加载用户自定义IP定位库 | +| Builder.loadDataFilePrivateV4(Inputstream databaseStream) | IpLookupV2.Builder | 加载用户自定义IPv4定位库 | +| Builder.loadDataFilePrivateV6(Inputstream databaseStream) | IpLookupV2.Builder | 加载用户自定义IPv6定位库 | +| Builder.loadAsnDataFile(Inputstream databaseStream) | IpLookupV2.Builder | 加载基础ASN库 | +| Builder.loadAsnDataFileV4(Inputstream databaseStream) | IpLookupV2.Builder | 加载基础IPv4 ASN库 | +| Builder.loadAsnDataFileV6(Inputstream databaseStream) | IpLookupV2.Builder | 加载基础IPv6 ASN库 | +| Builder.loadAsnDataFilePrivate(Inputstream databaseStream) | IpLookupV2.Builder | 加载用户自定义ASN库 | +| Builder.loadAsnDataFilePrivateV4(Inputstream databaseStream) | IpLookupV2.Builder | 加载用户自定义IPv4 ASN库 | +| Builder.loadAsnDataFilePrivateV6(Inputstream databaseStream) | IpLookupV2.Builder | 加载用户自定义IPv6 ASN库 | +| Builder.build() | IpLookupV2 | 构建IPLookupV2对象 | +| countryLookup(String ip) | String | 返回国家/区域 | +| provinceLookup(String ip) | String | 返回省/洲 | +| cityLookup(String ip) | String | 返回城市 | +| administrativeAreaLookupDetail(String ip) | String | 返回到区/县的四级定位信息 | +| ispLookup(String ip) | String | 返回运营商 | +| organizationLookup(String ip) | String | 返回组织 | +| cityLookupDetail(String ip) | String | 返回到城市的3级定位信息，包含城市,省(州),国家;分隔符为英文句号"." | +| locationLookupDetail(String ip) | String | 返回地理位置信息明细，支持7级 | +| infoLookupToCSV(String ip) | String | 返回地理位置信息明细，支持7级,csv格式 | +| infoLookupToJSON(String ip) | String | 返回地理位置信息明细，支持7级,json格式 | +| infoLookup(String ip) | String | 返回地理位置信息明细，支持7级,Response 对象 | +| latLngLookup(String ip) | String | 返回经纬度，格式：维度,经度 ；分隔符为英文句号"." | | cityLatLngLookup(String ip) | String | 返回 cityLookup+latLngLookup信息； | -| asnLookup(String ip) | String | 返回ASN号，调用AsnLookup工具类 | -| asnLookupDetail(String ip) | String | 返回ASN号及ISP信息，调用AsnLookup工具类 | +| asnLookup(String ip) | String | 返回ASN，调用AsnLookup工具类 | +| asnLookupOrganization(String ip) | String | 返回所属AS组织，调用AsnLookup工具类 | +| asnLookupDetail(String ip) | String | 返回ASN及ISP信息，调用AsnLookup工具类 | **AsnLookup** | Name | Type | Description | | ------------------------------------------------------------ | ----------------- | ---------------------------- | | AsnLookup.Builder(boolean isDefaultDB) | AsnLookup.Builder | | -| Builder.loadDataFile(String asnDatabasePublicFile) | AsnLookup.Builder | 加载公共IP定位库 | -| Builder.loadDataFileV4(String asnDatabasePublicFileV4) | AsnLookup.Builder | 加载公共ASN IPv4定位库 | -| Builder.loadDataFileV6(String asnDatabasePublicFileV6) | AsnLookup.Builder | 加载公共ASN IPv6定位库 | -| Builder.loadDataFilePrivate(String asnDatabasePrivateFile) | AsnLookup.Builder | 加载用户自定义ASN 定位库 | -| Builder.loadDataFilePrivateV4(String asnDatabasePrivateFileV4) | AsnLookup.Builder | 加载用户自定义ASN IPv4定位库 | -| Builder.loadDataFilePrivateV6(String asnDatabasePrivateFileV6) | AsnLookup.Builder | 加载用户自定义ASN IPv6定位库 | -| Builder.build() | AsnLookup | 构建IPGEO对象 | -| asnLookup(String ip) | String | 返回ASN号 | -| asnLookupDetail(String ip) | String | 返回ASN号及ISP信息 | +| Builder.loadDataFile(String databaseFile) | AsnLookup.Builder | 加载基础ASN库 | +| Builder.loadDataFileV4(String databaseFile) | AsnLookup.Builder | 加载基础V4 ASN库 | +| Builder.loadDataFileV6(String databaseFile) | AsnLookup.Builder | 加载基础V6 ASN库 | +| Builder.loadDataFilePrivate(String databaseFile) | AsnLookup.Builder | 加载用户自定义ASN库 | +| Builder.loadDataFilePrivateV4(String databaseFile) | AsnLookup.Builder | 加载用户自定义V4 ASN库 | +| Builder.loadDataFilePrivateV6(String databaseFile) | AsnLookup.Builder | 加载用户自定义V6 ASN库 | +| Builder.loadDataFile(Inputstream databaseStream) | AsnLookup.Builder | 加载基础ASN库 | +| Builder.loadDataFileV4(Inputstream databaseStream) | AsnLookup.Builder | 加载基础V4 ASN库 | +| Builder.loadDataFileV6(Inputstream databaseStream) | AsnLookup.Builder | 加载基础V6 ASN库 | +| Builder.loadDataFilePrivate(Inputstream databaseStream) | AsnLookup.Builder | 加载用户自定义ASN库 | +| Builder.loadDataFilePrivateV4(Inputstream databaseStream) | AsnLookup.Builder | 加载用户自定义V4 ASN库 | +| Builder.loadDataFilePrivateV6(Inputstream databaseStream) | AsnLookup.Builder | 加载用户自定义V6 ASN库 | +| Builder.build() | AsnLookup | 构建AsnLookup对象 | +| asnLookup(String ip) | String | 返回ASN | +| asnLookupOrganization(String ip) | String | 返回AS 组织 | +| asnLookupDetail(String ip) | String | 返回ASN及ISP信息 | ## 实现举例 ```java - IpLookupV2 ipLookup = new IpLookupV2.Builder(false) - .loadDataFileV4(new FileInputStream(new File("dat/ip_v4_built_in.mmdb"))) - .loadDataFilePrivateV4(new FileInputStream(new File("dat/ip_v4_user_defined.mmdb"))) - .loadDataFileV6(new FileInputStream(new File("dat/ip_v6_built_in.mmdb"))) - .loadDataFilePrivateV6(new FileInputStream(new File("dat/ip_v6_user_defined.mmdb"))) - .loadAsnDataFile(new FileInputStream(new File("dat/asn_v4.mmdb"))) - .loadAsnDataFileV6(new FileInputStream(new File("dat/asn_v6.mmdb"))) - .build(); + IpLookupV2 ipLookup = ipLookupV2 = new IpLookupV2.Builder(false) + .loadDataFileV4(new FileInputStream(new File("dat/ip_v4_built_in.mmdb"))) + .loadDataFilePrivateV4(new FileInputStream(new File("dat/ip_v4_user_defined.mmdb"))) + .loadDataFileV6(new FileInputStream(new File("dat/ip_v6_built_in.mmdb"))) + .loadDataFilePrivateV6(new FileInputStream(new File("dat/ip_v6_user_defined.mmdb"))) + .loadAsnDataFile(new FileInputStream(new File("dat/asn_v4.mmdb"))) + .loadAsnDataFileV6(new FileInputStream(new File("dat/asn_v6.mmdb"))) + .build(); logger.info(ipLookup.countryLookup("192.168.50.21")); logger.info(ipLookup.cityLookupDetail("192.168.50.21")); logger.info(ipLookup.latLngLookup("192.168.50.21")); - logger.info(ipLookup.cityLookupDetail("120.221.155.223")); + logger.info(ipLookup.infoLookupToJSON("120.221.155.223")); logger.info(ipLookup.countryLookup("2001:4860:4860::8888")); logger.info(ipLookup.asnLookup("120.221.155.223")); logger.info(ipLookup.asnLookup("2001:4860:4860::8888")); -- cgit v1.2.3