一、选择生成程序
您可以通过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: 5.628 s [INFO] Finished at: 2025-09-29T12:17:35+08:00 [INFO] ------------------------------------------------------------------------
得到的可运行jar文件为./target/ip2region-maker-3.0.0.jar
Golang:
➜ ~ cd ip2region/maker/golang ➜ golang git:(master) make go build -o xdb_maker
得到的可运行二进制程序为./xdb_maker
三、生成XDB文件
将从社区“离线服务”中下载的原始文件解压会得到一个.txt和一个.csv文件，以下生成程序只需要用到 .txt 文件即可，以v4-基础版为例，文件名为 ipv4_base.txt，IPv6 的生成只需要指定 --version=ipv6 剩下的操作完全一致。
Java生成：
生成命令和对应的可选参数如下：
➜ java git:(master) java -jar ./target/ip2region-maker-3.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
--version string IP version, options: ipv4/ipv6, specify this flag so you don't get confused
--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文件的路径，指定绝对或者相对路径均可。
--version：表示原始ipv4_base.txt文件的IP版本，v4 就设置为ipv4，v6 就设置为ipv6。
--field-list：自定义字段指定，默认不需要设置，如果需要自定义字段请参考下面的自定义字段的描述。
--log-level：运行过程的输出日志级别，默认为info，跳过全部的debug输出。
我的本地机器的v4-基础版XDB生成过程如下：
java -jar ./target/ip2region-maker-3.0.0.jar --src=/home/lionsoul/ipv4_base.txt --dst=/home/lionsoul/base_full_v4.xdb --version=ipv4 --log-level=info 2025-09-29 12:32:14 INFO org.lionsoul.ip2region.MakerApp Generating xdb with src=/home/lionsoul/ipv4_base.txt, dst=/home/lionsoul/base_full_v4.xdb, logLevel=info 2025-09-29 12:32:14 INFO org.lionsoul.ip2region.xdb.Maker try to init the db header ... 2025-09-29 12:32:14 INFO org.lionsoul.ip2region.xdb.Maker try to load the segments ... 2025-09-29 12:33:18 INFO org.lionsoul.ip2region.xdb.Maker all segments loaded, length: 16961584, elapsed: 63800 ms 2025-09-29 12:33:18 INFO org.lionsoul.ip2region.xdb.Maker try to write the data block ... 2025-09-29 12:33:22 INFO org.lionsoul.ip2region.xdb.Maker try to write the segment index block ... 2025-09-29 12:34:43 INFO org.lionsoul.ip2region.xdb.Maker try to write the vector index block ... 2025-09-29 12:34:43 INFO org.lionsoul.ip2region.xdb.Maker try to write the segment index ptr ... 2025-09-29 12:34:43 INFO org.lionsoul.ip2region.xdb.Maker write done, dataBlocks: 398547, indexBlocks: (16961584, 16986028), indexPtr: (40755878, 278560256) 2025-09-29 12:34:43 INFO org.lionsoul.ip2region.MakerApp Done, elapsed: 148 s
原始文件为ipv4_base.txt，生成base_full_v4.xdb，设置日志级别为info，生成耗时为：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 --version string IP version, options: ipv4/ipv6, specify this flag so you don't get confused --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文件的路径，指定绝对或者相对路径均可。
--version：表示原始ipv4_base.txt文件的IP版本，v4 就设置为ipv4，v6 就设置为ipv6。
--field-list：自定义字段指定，默认不需要设置，如果需要自定义字段请参考下面的自定义字段的描述。
--log-level：运行过程的输出日志级别，默认为info，跳过全部的debug输出。
我的本地机器的基础版XDB生成过程如下：
./xdb_maker gen --src=/home/lionsoul/ipv4_base.txt --dst=/home/lionsoul/base_full_v4.xdb --version=ipv4 --log-level=info 2025/09/29 13:05:51 main.go:231: INFO Generating xdb with src=/home/lionsoul/ipv4_base.txt dst=/home/lionsoul/base_full_v4.xdb logLevel=info 2025/09/29 13:05:51 maker.go:119: INFO try to init the db header ... 2025/09/29 13:05:51 maker.go:159: INFO try to load the segments ... 2025/09/29 13:06:20 maker.go:187: INFO all segments loaded length=16961584 elapsed=29.343612836s 2025/09/29 13:06:20 maker.go:234: INFO try to write the data block ... 2025/09/29 13:06:24 maker.go:269: INFO try to write the segment index block ... 2025/09/29 13:07:56 maker.go:332: INFO try to write the vector index block ... 2025/09/29 13:07:56 maker.go:343: INFO try to write the segment index ptr ... 2025/09/29 13:07:56 maker.go:356: INFO write done dataBlocks=398547 indexBlocks=16961584 counter=16986028 startIndexPtr=40755878 endIndexPtr=278560256 2025/09/29 13:07:56 main.go:249: INFO make done elapsed=2m5.249004628s
原始文件为ipv4_base.txt，生成base_full_v4.xdb，日志级别设置为info，生成耗时为：3m10s。
四、自定义数据字段
例如，基础版本的原始数据的一行样本数据如下：
223.246.178.235|223.246.178.235|亚洲|中国|广东|深圳|宝安|电信|113.88311|22.55371|440306|0755|518100|Asia/Shanghai|CNY|11|CHXX0120
去掉前面的开始IP和结束IP后如下：
亚洲|中国|广东|深圳|宝安|电信|113.88311|22.55371|440306|0755|518100|Asia/Shanghai|CNY|11|CHXX0120
上述信息就是XDB定义的地域信息，这个信息会原样的写入到XDB文件的数据区域，重复的地域信息只会写入一份，不同的索引会共享同一个数据指针，这个共享实现会使得得到XDB文件比原始文件小很多，上述字段和对应的索引关系如下：
| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 |
| 亚洲 | 中国 | 广东 | 深圳 | 宝安 | 电信 | 113.88311 | 22.55371 | 440306 | 0755 | 518100 | Asia/Shanghai | CNY | 11 | CHXX0120 |
本质是上述数据通过|分割后的数组下标，例如我们想只保留 [1,2,3,4,5] 字段集合，通过设置--field-list=1-5来实现，生成指令如下：
java -jar ./target/ip2region-maker-3.0.0.jar --src=/home/lionsoul/ipv4_base.txt --dst=/home/lionsoul/base_full_v4.xdb --version=ipv4 --field-list=1-5 --log-level=info
个人中心的“数据服务”中提供的三个版本的XDB文件的大小都在(65M,270M)之间(这个会随着原始数据发生变化，仅供参考)，字段设置如下：
1. 满载版本的地域信息如下：
亚洲|中国|广东|深圳|宝安|电信|113.88311|22.55371|440306|0755|518100|Asia/Shanghai|CNY|11|CHXX0120
保留了全部有效字段，无需设置，默认就是保留了全部字段。
2. 标准定位版的地域信息如下：
中国|广东|深圳|宝安|电信
也就是只保留了到区县的定位信息，参考上述对应关系表格，字段设置为：--field-list=1-5
3. 简化定位版的地域信息如下：
中国|广东|深圳|电信
也就是只保留了到城市的定位信息，这个Ip2Region仓库免费的数据字段一致，参考上述对应关系表格，字段设置为：--field-list=1-3,5
再例如如下几个场景的字段设置：
1. 只到省份的的定位信息：--field-list=1,2或者--field-list=1-2
2. 只到城市的的定位信息+经纬度：--field-list=1-3,6-7或者--field-list=1-3,6,7
2. 到区县的定位信息+经纬度+时区：--field-list=1-4,6-7,11或者--field-list=1-4,6,7,11
