ip2region 完整指南3 步搞定离线 IP 定位到城市级【免费下载链接】ip2regionIp2region is an offline IP-to-Region localization library and IP data management framework with both IPv4 and IPv6 supports, 10-microsecond level query efficiency, xdb search client for many programming languages项目地址: https://gitcode.com/GitHub_Trending/ip/ip2region你有没有过这种经历系统里存了一堆用户 IP想看看他们来自哪里结果每次都要调第三方在线接口——网络一抖就超时调用量一大还要计费更麻烦的是服务一停日志里的位置信息就再也没法补查。ip2region 是一款免费的离线 IP 定位库把全国乃至全球的城市级 IP 数据压缩进一个本地文件查询不需要联网单次响应在微秒级。这篇文章带你从零走到落地。它到底是什么把 ip2region 理解成一本随身携带的电话簿在线查询服务像是打电话给 114 查号每次都要等对方接而 ip2region 是把整本电话簿复印在你桌上翻到哪页自己查不用问任何人。它干两件事一是提供ip2region_v4.xdb和ip2region_v6.xdb两个数据文件直接查 IP 归属的国家|省份|城市|运营商二是提供一整套数据管理工具让你能改数据、重新打包把 GPS 坐标、邮编这类自定义字段塞进查询结果里。查询客户端覆盖了 Golang、Java、Python、C、PHP、Rust、C#、Lua、Erlang、Nginx 扩展等十几种语言在 binding/ 目录下各有一版实现和文档。第一次查询3 步手动跑通先亲手查一个 IP感受一下它快不快。第一步拿到代码和数据git clone https://gitcode.com/GitHub_Trending/ip/ip2region第二步用仓库里现成的 Python 查询测试程序启动交互查询Python 版在 binding/python/cd ip2region/binding/python python search_test.py --db ../../data/ip2region_v4.xdb第三步在提示符后面输入一个 IP比如113.92.157.29回车。你会看到类似这样的输出{region: 中国|广东省|深圳市|中国联通, ioCount: 3, took: 87 μs}took这一列就是单次查询耗时这里的单位是微秒。输入quit退出。如果你更常用 Golangbinding/golang/main.go 是一个功能一样的交互程序go run main.go search即可启动输入框同时支持 IPv4 和 IPv6。数据文件放在 data/ 目录v4 文件约 11MBv6 约 37MB源数据ipv4_source.txt里有 51 万多个 IP 段ipv6_source.txt约 67 万个。它凭什么这么快你可能会问五百万多条 IP 段就算全装进内存线性扫一遍也不止微秒级。答案在它的查询结构里。xdb 文件的设计可以类比你查字典你不可能从第一页翻起找省这个字你会先翻到目录按首字母定位到大概页码再在几页里找到它。xdb 内部同样存了一张目录——向量索引它按 IP 数值切分成定长块查询时先用这个索引算出目标 IP 落在哪个块再在那个块内做一次二分定位所以典型查询只需要两三次随机读。正因为有这层索引ip2region 给了你三档缓存策略你可以按需选择file完全不缓存每次查询都读文件仍然在百微秒级适合内存紧张或查询量小的场景vectorIndex只把那张目录512KiB 内存装进内存省掉一次磁盘定位平均查询压到 100 微秒内是默认推荐档content把整个 xdb 文件读进内存查询稳定在 10 微秒级代价是内存占用等于文件大小v4 约 11MB很划算。切换策略只是一个参数的事比如 Python 测试程序的--cache-policy就接受这三个值Golang 里对应service.NoCache/service.VIndexCache/service.BufferCache。一个端到端案例给访问日志补上城市信息假设你的 Nginx 访问日志长这样2026-09-07 10:15:32 218.17.37.165 GET /index.html 200你想在日志报表里看到每个访客来自哪个城市。链路其实很短日志进来后提取出点分十进制的 IP 字段把它交给查询服务Golang 的并发安全查询服务几行就能建起来摘自 binding/golang/ 文档v4Config, _ : service.NewV4Config(service.VIndexCache, ip2region_v4.xdb, 20) v6Config, _ : service.NewV6Config(service.VIndexCache, ip2region_v6.xdb, 20) ip2region, _ : service.NewIp2Region(v4Config, v6Config) region, err : ip2region.Search(218.17.37.165)Search返回中国|北京市|北京市|中国移动这样的字符串你的代码按|切分把省份和城市拼回日志行即可。这个案例里有几个细节值得注意。返回值是国家|省份|城市|运营商|ISO 国家码的固定格式国内数据用中文、国外数据用英文解析时按位置取而不是按内容匹配会更稳。Search对 IPv4 和 IPv6 都能处理服务内部自动识别版本你不需要写两遍逻辑。查不到该 IP 时返回空字符串记得在报表里留个未知分支。常见坑与性能取舍并发问题。单个基于文件的查询对象不是并发安全的多线程共用一个会出脏数据。两种正规解法用前面那种带查询池的Ip2Region查询服务按你的并发数设置池大小比如 20或者用content策略的内存查询器它本身就并发安全。别图省事自己加锁包一个池化方案吞吐更高。别在热路径上验文件。各语言 API 都提供Verify校验 xdb 文件完整性但它有开销官方注释明确建议只在部署时校验一次不要每次查询前都调。缓存策略别一步到位。内存有限就先跑vectorIndex512KiB 的代价换来比纯文件查询更稳定的延迟等 QPS 真的高到磁盘 IO 成为瓶颈再升content。升级路径是平滑的只改一个参数。数据会过期。仓库里的源数据不定期更新对准确性要求高的业务建议接入 data/README_zh.md 里说明的更新渠道或者用 maker/ 下的生成工具自己维护数据源数据是纯文本起始IP|结束IP|国家|省份|城市|ISP|国家码改完重新打包成 xdb 即可Golang、Java、Python、C#、Rust 都有打包器它还会自动合并相邻的相同 IP 段、去重压缩所以你的自定义数据不用手动整理格式。下一步去哪想看懂 xdb 文件长什么样查一下 v4 文件头或直接读各语言查询客户端的源码结构都在 binding/ 里想生成或修改数据看 maker/golang/ 的 README里面有编辑器和打包流程的完整说明想给 Nginx 直接加geo指令级的定位能力binding/nginx/ 提供了模块实现和测试想给自己的项目挑客户端翻 binding/ 下对应语言的 README每份都带完整 API 说明和测试程序照着抄就行。装好数据、选对缓存策略你的项目就获得了一个不依赖网络、微秒级响应的定位能力。剩下的只是把日志、风控、报表这些入口接上去的事。【免费下载链接】ip2regionIp2region is an offline IP-to-Region localization library and IP data management framework with both IPv4 and IPv6 supports, 10-microsecond level query efficiency, xdb search client for many programming languages项目地址: https://gitcode.com/GitHub_Trending/ip/ip2region创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考