一、选择生成程序
您可以通过Github/maker或者Gitee/maker找到全部生成程序实现，然后选择您熟悉的语言的客户端去操作，建议您优先选择使用Golang或者Java版本的实现，首先新的特性和优化细节都会先在这个两个版本中实现，其次使用过程中有任何问题会得到比较的快速响应支持。
1. Java：Github-xdb-java-maker或者Gitee-xdb-java-maker
2. Golang：Github-xdb-golang-maker或者Gitee-xdb-golang-maker
二、编译生成程序
仓库中每一个maker实现都有详细的编译文档，这里仅以Java和Golang为例进行编译过程的描述供参考：
1. Clone 代码：
➜ ~ git clone git@gitee.com:lionsoul/ip2region.git Cloning into 'ip2region'... remote: Enumerating objects: 5184, done. remote: Counting objects: 100% (83/83), done. remote: Compressing objects: 100% (53/53), done. remote: Total 5184 (delta 23), reused 14 (delta 5), pack-reused 5101 (from 1) Receiving objects: 100% (5184/5184), 68.13 MiB | 2.05 MiB/s, done. Resolving deltas: 100% (2792/2792), done. // 或者通过 Github: // git clone git@github.com:lionsoul2014/ip2region.git
2. 编译 maker
Java:
➜ ~ cd ip2region/maker/java ➜ java git:(master) mvn clean compile package ... [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 3.246 s [INFO] Finished at: 2025-06-15T16:58:36+08:00 [INFO] ------------------------------------------------------------------------
得到的可运行jar文件为./target/ip2region-maker-1.0.0.jar
Golang:
➜ ~ cd ip2region/maker/golang ➜ golang git:(master) make go build -o xdb_maker
得到的可运行二进制程序为./xdb_maker
三、生成XDB文件
将从社区“离线服务”中下载的原始文件解压会得到一个.txt和一个.csv文件（忽略不可用的 .dat 文件），以下生成程序只需要用到 .txt 文件即可，以基础版本为例，文件名为 ipv4_base.txt。
Java生成：
生成命令和对应的可选参数如下：
➜ java git:(master) java -jar target/ip2region-maker-1.0.0.jar
ip2region xdb maker
java -jar ip2region-maker-{version}.jar [command options]
options:
--src string source ip text file path
--dst string destination binary xdb file path
--field-list string field index list imploded with ',' eg: 0,1,2,3-6,7
--log-level string set the log level, options: debug/info/warn/error
--src：表示上述解压得到的原始ipv4_base.txt文件，指定绝对或者相对路径均可。
--dst：表示生成的目标xdb文件的路径，指定绝对或者相对路径均可。
--field-list：自定义字段指定，基础版指定为：2-16，高级版指定为：2-17，专业版本指定为：2-18；详细描述请参考下面的自定义字段的描述。
--log-level：运行过程的输出日志级别，这里建议直接指定为info，跳过全部的debug输出，不然整个生成过程会运行很长时间，且大部分时间耗费在日志输出。
我的本地机器的基础版XDB生成过程如下：
➜ java git:(master) ✗ java -jar target/ip2region-maker-1.0.0.jar --src=/home/lionsoul/Downloads/ipv4/ipv4_base.txt --dst=/home/lionsoul/ip2region_base_full.xdb --field-list=2-16 --log-level=info 2025-06-16 19:17:25 INFO org.lionsoul.ip2region.MakerTest Generating xdb with src=/home/lionsoul/Downloads/ipv4/ipv4_base.txt, dst=/home/lionsoul/ip2region_base_full.xdb, logLevel=info 2025-06-16 19:17:25 INFO org.lionsoul.ip2region.xdb.Maker try to init the db header ... 2025-06-16 19:17:25 INFO org.lionsoul.ip2region.xdb.Maker try to load the segments ... 2025-06-16 19:18:18 INFO org.lionsoul.ip2region.xdb.Maker all segments loaded, length: 22966396, elapsed: 53182 ms 2025-06-16 19:18:18 INFO org.lionsoul.ip2region.xdb.Maker try to write the data block ... 2025-06-16 19:18:24 INFO org.lionsoul.ip2region.xdb.Maker try to write the segment index block ... 2025-06-16 19:19:54 INFO org.lionsoul.ip2region.xdb.Maker try to write the vector index block ... 2025-06-16 19:19:54 INFO org.lionsoul.ip2region.xdb.Maker try to write the segment index ptr ... 2025-06-16 19:19:54 INFO org.lionsoul.ip2region.xdb.Maker write done, dataBlocks: 642725, indexBlocks: (22966396, 22990215), indexPtr: (66630841, 388493837) 2025-06-16 19:19:54 INFO org.lionsoul.ip2region.MakerTest Done, elapsed: 148 s
原始文件为ipv4_base.txt，生成ip2region_base_full.xdb，设置日志级别为error，生成耗时为：148s。
Golang生成：
生成命令和对应的可选参数如下：
➜ golang git:(master) ✗ ./xdb_maker gen ./xdb_maker gen [command options] options: --src string source ip text file path --dst string destination binary xdb file path --field-list string field index list imploded with ',' eg: 0,1,2,3-6,7 --log-level string set the log level, options: debug/info/warn/error
--src：表示上述解压得到的原始ipv4_base.txt文件，指定绝对或者相对路径均可。
--dst：表示生成的目标xdb文件的路径，指定绝对或者相对路径均可。
--field-list：自定义字段指定，基础版指定为：2-16，高级版指定为：2-17，专业版本指定为：2-18；详细描述请参考下面的自定义字段的描述。
--log-level：运行过程的输出日志级别，这里建议直接指定为info，跳过全部的debug输出，不然整个生成过程会运行很长时间，且大部分时间耗费在日志输出。
我的本地机器的基础版XDB生成过程如下：
➜ golang git:(master) ✗ ./xdb_maker gen --src=/home/lionsoul/Downloads/ipv4/ipv4_base.txt --dst=/home/lionsoul/ip2region_base_full.xdb --field-list=2-16 --log-level=info 2025/06/16 23:12:54 main.go:213: INFO Generating xdb with src=/home/lionsoul/Downloads/ipv4/ipv4_base.txt dst=/home/lionsoul/ip2region_base_full.xdb logLevel=info 2025/06/16 23:12:54 maker.go:110: INFO try to init the db header ... 2025/06/16 23:12:54 maker.go:166: INFO try to load the segments ... 2025/06/16 23:13:33 maker.go:194: INFO all segments loaded length=22966396 elapsed=38.814030113s 2025/06/16 23:13:33 maker.go:241: INFO try to write the data block ... 2025/06/16 23:13:39 maker.go:271: INFO try to write the segment index block ... 2025/06/16 23:16:05 maker.go:320: INFO try to write the vector index block ... 2025/06/16 23:16:05 maker.go:331: INFO try to write the segment index ptr ... 2025/06/16 23:16:05 maker.go:344: INFO write done dataBlocks=642725 indexBlocks=22966396 counter=22990215 startIndexPtr=66630841 endIndexPtr=388493837 2025/06/16 23:16:05 main.go:231: INFO make done elapsed=3m10.830918338s
原始文件为ipv4_base.txt，生成ip2region_base_full.xdb，日志级别设置为info，生成耗时为：3m10s。
四、自定义数据字段
下载的商用离线数据如果使用原始的.txt文件直接生成XDB文件会有3G+，这个文件尺寸非常的不友好。原始txt数据里的开始IP整形|结束IP整形这两个字段对于XDB后续的使用毫无意义，重点是会导致地域信息无法被缓存压缩，这就要求我们不得不自定义数据字段了，例如，基础版本的原始数据的一行样本数据如下：
223.246.178.235|223.246.178.235|3757486827|3757486827|亚洲|中国|广东|深圳|宝安|电信|113.88311|22.55371|440306|0755|518100|Asia/Shanghai|CNY|11|CHXX0120
去掉前面的开始IP和结束IP后如下：
3757486827|3757486827|亚洲|中国|广东|深圳|宝安|电信|113.88311|22.55371|440306|0755|518100|Asia/Shanghai|CNY|11|CHXX0120
上述信息就是XDB定义的地域信息，这个信息会原样的写入到XDB文件的数据区域，重复的地域信息只会写入一份，不同的索引会共享同一个数据指针，这个共享实现会使得得到XDB文件比原始文件小很多，但是前面的两个大整数字段“3757486827|3757486827”会直接导致这种共享失效。上述字段和对应的索引关系如下：
| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 |
| 3757486827 | 3757486827 | 亚洲 | 中国 | 广东 | 深圳 | 宝安 | 电信 | 113.88311 | 22.55371 | 440306 | 0755 | 518100 | Asia/Shanghai | CNY | 11 | CHXX0120 |
本质是上述数据通过|分割后的数组下标，例如我们想去掉前面两个字段，保留剩下的字段可以通过设置--field-list=2-16来实现，生成指令如下：
java -jar target/ip2region-maker-1.0.0.jar --src=/home/lionsoul/Downloads/ipv4/ipv4_base.txt --dst=/home/lionsoul/ipv4_base_full.xdb --field-list=2-16 --log-level=error
我手头上的这个数据通过这个方式得到的XDB文件只有320MiB左右，只有原始数据的1/10左右。
个人中心的“数据服务”中提供的三个版本的XDB文件的大小都在[300MiB,380MiB]之间(这个会随着原始数据发生变化，仅供参考)，字段设置如下：
1. 满载版本的地域信息如下：
亚洲|中国|广东|深圳|宝安|电信|113.88311|22.55371|440306|0755|518100|Asia/Shanghai|CNY|11|CHXX0120
也就是只保留了全部有效字段，参考上述对应关系表格，字段设置为：--field-list=2-16
2. 标准定位版的地域信息如下：
中国|广东|深圳|宝安|电信
也就是只保留了到区县的定位信息，参考上述对应关系表格，字段设置为：--field-list=3-7
3. 简化定位版的地域信息如下：
中国|广东|深圳|电信
也就是只保留了到城市的定位信息，这个Ip2Region仓库免费的数据字段一致，参考上述对应关系表格，字段设置为：--field-list=3-5,7
再例如如下几个场景的字段设置：
1. 只到省份的的定位信息：--field-list=3,4或者--field-list=3-4
2. 只到城市的的定位信息+经纬度：--field-list=3-5,8-9或者--field-list=3-5,8,9
2. 到区县的定位信息+经纬度+时区：--field-list=3-6,8-9,13或者--field-list=3-6,8,9,13
