Ip2region介绍

Ip2region 是什么

ip2region v2.0 - 是一个离线IP地址定位库和IP定位数据管理框架，10微秒级别的查询效率，提供了众多主流编程语言的 xdb 数据生成和查询客户端实现。

Ip2region 特性

1、标准化的数据格式

每个 ip 数据段的 region 信息都固定了格式：国家|区域|省份|城市|ISP，只有中国的数据绝大部分精确到了城市，其他国家部分数据只能定位到国家，后前的选项全部是0。

2、数据去重和压缩

xdb 格式生成程序会自动去重和压缩部分数据，默认的全部 IP 数据，生成的 ip2region.xdb 数据库是 11MiB，随着数据的详细度增加数据库的大小也慢慢增大。

3、极速查询响应

即使是完全基于 xdb 文件的查询，单次查询响应时间在十微秒级别，可通过如下两种方式开启内存加速查询：

1. vIndex 索引缓存 ：使用固定的 512KiB 的内存空间缓存 vector index 数据，减少一次 IO 磁盘操作，保持平均查询效率稳定在10-20微秒之间。
2. xdb 整个文件缓存：将整个 xdb 文件全部加载到内存，内存占用等同于 xdb 文件大小，无磁盘 IO 操作，保持微秒级别的查询效率。

4、IP 数据管理框架

v2.0 格式的 xdb 支持亿级别的 IP 数据段行数，region 信息也可以完全自定义，例如：你可以在 region 中追加特定业务需求的数据，例如：GPS信息/国际统一地域信息编码/邮编等。也就是你完全可以使用 ip2region 来管理你自己的 IP 定位数据。

xdb数据查询

API 介绍，使用文档和测试程序请参考对应 searcher 查询客户端下的 ReadMe 介绍，全部查询 binding 实现情况如下：

Ok?	状态	编程语言	描述	贡献者
✅	已完成	golang	golang xdb 查询客户端实现	Lion
✅	已完成	php	php xdb 查询客户端实现	Lion
✅	已完成	java	java xdb 查询客户端实现	Lion
✅	已完成	lua	纯 lua xdb 查询客户端实现	Lion
✅	已完成	c	ANSC c xdb 查询客户端实现	Lion
✅	已完成	lua_c	lua c 扩展 xdb 查询客户端实现	Lion
	待开始	rust	rust xdb 查询客户端实现	Lion
✅	已完成	python	python xdb 查询客户端实现	厉害的花花
✅	已完成	nodejs	nodejs xdb 查询客户端实现	Wu Jian Ping
✅	已完成	csharp	csharp xdb 查询客户端实现	Alen Lee
	待开始	php_ext	php c 扩展 xdb 查询客户端实现	待确定
	待开始	nginx	nginx 扩展 xdb 查询客户端实现	待确定

ip2region python 查询客户端实现

使用方式

完全基于文件的查询

from xdbSearcher import XdbSearcher

def searchWithFile():
    # 1. 创建查询对象
    dbPath = "./ip2region.xdb"
    searcher = XdbSearcher(dbfile=dbPath)
    
    # 2. 执行查询
    ip = "1.2.3.4"
    region_str = searcher.searchByIPStr(ip)
    print(region_str)
    
    # 3. 关闭searcher
    searcher.close()

缓存 VectorIndex 索引

我们可以提前从 xdb 文件中加载出来 VectorIndex 数据，然后全局缓存，每次创建 Searcher 对象的时候使用全局的 VectorIndex 缓存可以减少一次固定的 IO 操作，从而加速查询，减少 IO 压力。

from xdbSearcher import XdbSearcher

def searchWithVectorIndex():
     # 1. 预先加载整个 xdb
    dbPath = "../../data/ip2region.xdb"
    vi = XdbSearcher.loadVectorIndexFromFile(dbfile=dbPath)

    # 2. 使用上面的缓存创建查询对象, 同时也要加载 xdb 文件
    searcher = XdbSearcher(dbfile=dbPath, vectorIndex=vi)
    
    # 3. 执行查询
    ip = "1.2.3.4"
    region_str = searcher.search(ip)
    print(region_str)

    # 4. 关闭searcher
    searcher.close()

缓存整个 xdb 数据

我们也可以预先加载整个 ip2region.xdb 的数据到内存，然后基于这个数据创建查询对象来实现完全基于文件的查询，类似之前的 memory search。

from xdbSearcher import XdbSearcher

def searchWithContent():
    # 1. 预先加载整个 xdb
    dbPath = "../../data/ip2region.xdb";
    cb = XdbSearcher.loadContentFromFile(dbfile=dbPath)
    
    # 2. 仅需要使用上面的全文件缓存创建查询对象, 不需要传源 xdb 文件
    searcher = XdbSearcher(contentBuff=cb)
    
    # 3. 执行查询
    ip = "1.2.3.4"
    region_str = searcher.search(ip)
    print(region_str)

    # 4. 关闭searcher
    searcher.close()

查询测试

通过 search_test.py 脚本来进行查询测试：

➜  python git:(python_dev) ✗ python3 ./search_test.py
python3 search_test.py [command options]
options:
 --db string             ip2region binary xdb file path
 --cache-policy string   cache policy: file/vectorIndex/content

例如：使用默认的 data/ip2region.xdb 进行查询测试：

➜  python git:(python_dev) ✗ python3 ./search_test.py --db=../../data/ip2region.xdb --cache-policy=content
ip2region xdb searcher test program, cachePolicy: content
type 'quit' to exit
ip2region>> 1.2.3.4
region :美国|0|华盛顿|0|谷歌 , took 0.0689 ms
ip2region>> quit
searcher test program exited, thanks for trying

输入 ip 即可进行查询测试。也可以分别设置 cache-policy 为 file/vectorIndex/content 来测试三种不同缓存实现的效率。

bench 测试

通过 bench_test.py 脚本来进行自动 bench 测试，一方面确保 xdb 文件没有错误，另一方面通过大量的查询测试平均查询性能：

➜  python3 ./bench_test.py
python bench_test.py [command options]
options:
 --db string             ip2region binary xdb file path
 --src string            source ip text file path
 --cache-policy string   cache policy: file/vectorIndex/content

例如：通过默认的 data/ip2region.xdb 和 data/ip.merge.txt 来进行 bench 测试：

➜  python3 ./bench_test.py --db=../../data/ip2region.xdb --src=../../data/ip.merge.txt --cache-policy=content
Bench finished, [cachePolicy: content, total: 3417955, took: 34.93 s, cost: 0.0094 ms/op]

可以通过设置 cache-policy 参数来分别测试 file/vectorIndex/content 三种不同的缓存实现的的性能。 @Note：请注意 bench 使用的 src 文件需要是生成对应的 xdb 文件的相同的源文件。

xdb 数据生成

API 介绍，使用文档和测试程序请参考对应 maker 生成程序下的 ReadMe 介绍，全部生成 maker 实现情况如下：

Ok?	状态	编程语言	描述	贡献者
✅	已完成	golang	golang xdb 生成程序实现	Lion
✅	已完成	java	java xdb 生成程序实现	Lion
	待开始	c	ANSC c xdb 生成程序实现	Lion
✅	已完成	python	python xdb 生成程序实现	leolin49
✅	已完成	csharp	csharp xdb 生成程序实现	Alan Lee

ip2region xdb python 生成实现

脚本执行

# 切换到python maker 根目录
> python main.py
ip2region xdb maker
main.py [command] [command options]
Command:
  gen      generate the binary db file

xdb 数据生成

通过 python main.py gen 命令生成 ip2region.xdb 二进制文件:

➜  python main.py gen
main.py gen [command options]
options:
 --src string    source ip text file path
 --dst string    destination binary xdb file path

例如，使用默认的 data/ip.merge.txt 作为源数据，生成一个 ip2region.xdb 到当前目录：

➜  python main.py gen --src=../../data/ip.merge.txt --dst=./ip2region.xdb
# 会看到一堆输出，最终会看到类似如下输出表示运行结束
...
2022-07-13 19:58:00,540-root-238-INFO - write done, dataBlocks: 13804, indexBlocks: (683591, 720221), indexPtr: (982904, 11065984)
2022-07-13 19:58:00,540-root-63-INFO - Done, elapsed: 3m3s

xdb 数据查询 和 bench 测试

基于xdb 格式的查询功能和测试见 ip2region binding

并发查询必读

全部查询客户端的 search 接口都 不是 并发安全的实现，不同进程/线程/协程需要通过创建不同的查询对象来安全使用，并发量很大的情况下，基于文件查询的方式可能会导致打开文件数过多的错误，请修改内核的最大允许打开文件数(fs.file-max=一个更高的值)，或者将整个xdb加载到内存进行安全并发使用。

相关备注

1、使用声明

ip2region 重点在于研究 IP 定位数据的存储设计和各种语言的查询实现，并没有原始 IP 数据的支撑，本项目不保证及时的数据更新，没有也不会有商用版本，你可以使用自定义的数据导入 ip2region 进行管理。

2、数据更新

基于检测算法的数据更新方式视频分享：数据更新实现视频分享 - part1，数据更新实现视频分享 - part2

3、数据结构

1. xdb 数据结构分析：“ip2region xdb 数据结构和查询过程详解“
2. xdb 查询过程分析：“ip2region xdb 数据结构和查询过程详解”
3. xdb 生成过程分析：“ip2region xdb 二进制数据生成过程详解”

参考文献

• https://github.com/zoujingli/ip2region