ip2region 完整指南微秒级离线 IPv4/IPv6 IP 定位库与 xdb 数据管理框架【免费下载链接】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/ip2regionip2region 是一个离线 IP 归属地定位库同时也是一套可承载上亿行 IP 数据段的管理框架适合需要在内网、低延迟或隐私敏感环境中识别 IPv4/IPv6 城市级归属的团队。它的核心卖点有三个数字单次查询 10 微秒级、向量索引缓存固定512KiB、xdb格式支持256×256 段分组的固定加速索引。下文以 Go 语言为主线先跑通查询再拆文件结构最后讲数据生成与维护。从仓库里拿出两个 xdb 文件10 行代码完成首次定位仓库的 data/ 目录直接提供了四个即用文件ipv4_source.txt、ipv6_source.txt原始文本数据和ip2region_v4.xdb、ip2region_v6.xdb编译好的二进制。内置数据的区域字段固定为国家|省份|城市|运营商|ISO两位国家码中国区域全中文海外区域全英文。最短的可用路径是 Go 客户端的统一服务自 3.11.0 起并发安全、自动识别 v4/v6源码见 binding/golang/service/ip2region.go// 1. 分别创建 v4/v6 配置缓存策略 xdb 路径 searcher 池大小 v4, _ : service.NewV4Config(service.VIndexCache, data/ip2region_v4.xdb, 20) v6, _ : service.NewV6Config(service.VIndexCache, data/ip2region_v6.xdb, 20) // 2. 用两个配置创建统一查询服务某一版传 nil 即禁用该版本 ip2r, _ : service.NewIp2Region(v4, v6) defer ip2r.Close() // 默认最多等 10 秒让 searcher 归还 // 3. 直接查IP 版本内部自动识别 region, _ : ip2r.Search(113.92.157.29) // - 中国|广东省|深圳市|电信|CN region, _ ip2r.Search(240e:3b7:3272:d8d0:db09:c067:8d59:539e) // - 中国|广东省|深圳市|电信|CN不想写代码的话编译后的命令行工具提供交互式查询在binding/golang下执行make生成xdb_searcher./xdb_searcher search --v4-db../../data/ip2region_v4.xdb --v6-db../../data/ip2region_v6.xdb ip2region 1.2.3.4 {region: Australia|Queensland|Brisbane|0|AU, took: 50.216µs}--v4-cache-policy/--v6-cache-policy默认vectorIndex可选file/vectorIndex/content三档这正好引出下一章这三档怎么取舍。三种缓存模式怎么选file、vectorIndex、content构造层binding/golang/xdb/searcher.go提供了三个构造函数一一对应三种缓存形态。Searcher结构体同时持有vectorIndex []byte和contentBuff []byte每次Search都会重置ioCount并累计磁盘读次数你可以用GetIOCount()直观验证下表模式构造函数常驻内存磁盘 IO 构成典型耗时适用场景file 纯文件NewWithFileOnly(version, dbPath)约 0向量索引 1 次 二分 k 次 数据 1 次100µs 上下内存紧张、低频查询vectorIndexNewWithVectorIndex(version, dbPath, vIndex)固定 512KiB二分 k 次 数据 1 次平均 100µs 以内默认推荐content 整文件NewWithBuffer(version, cBuff)等于 xdb 文件大小0 次10µs 级追求极致延迟k 是二分查找步数段数量在百万级时约 10~20 步。建议默认选 vectorIndex512KiB 的开销在任何机器上都可忽略却省掉每次查询 1 次必读的索引 IO追求 P99 延迟稳定在 10µs 级时用 content 模式代价是内存与文件大小 1:1v4 xdb 大约 7MB 量级v6 稍大均可接受避免在文件 IO 成为瓶颈的场景容器挂载卷、网络盘用 file 模式。v4、v6 两个配置相互独立可以各配不同策略searcher 池数量按你的并发量设置且运行期固定池空时借出操作会阻塞等待。注意BufferCache时池大小会被忽略——实现直接走单实例内存 searcher见 binding/golang/service/config.go 中cachePolicy BufferCache分支因为整文件缓存版本天然并发安全。拆一下 xdb 文件布局256 字节头与 512KiB 向量索引理解三种缓存模式的前提是知道 xdb 长什么样。文件由四段顺序排布maker/golang/xdb/maker.go 顶部的注释第 6~51 行给出了官方布局图---------------------------------------------------------------- | header space | speed up index | data payload | block index | ---------------------------------------------------------------- | 256 bytes | 512 KiB (fixed) | dynamic size | dynamic size | ----------------------------------------------------------------头部区固定 256 字节常量HeaderInfoLength定义于 binding/golang/xdb/header.go实际占用的字段如下表解析逻辑就在同文件的NewHeader函数偏移长度字段含义02BVersion结构版本号IPv6 支持前固定 2支持后为 3Structure3022BIndexPolicy索引算法编码当前为 VectorIndex44BCreatedAt生成时 Unix 时间戳84BStartIndexPtr段索引区起始指针124BEndIndexPtr段索引区结束指针162BIPVersion4 或 6182BRuntimePtrBytes运行时指针字节数v2 结构恒为 4向量索引区紧随其后大小由三个常量乘出来VectorIndexRows 256、VectorIndexCols 256、VectorIndexSize 8即256 × 256 × 8 524288字节。它是一张 256×256 的超级块表IP 的前两个字节共 65536 种组合各对应一个超级块每块 8 字节记录该分组内段索引的起始指针与结束指针。段索引区中每条记录是起始IP 结束IP 数据长度 数据指针长度由 binding/golang/xdb/version.go 的SegmentIndexSize决定IPv4 为 14 字节4424IPv6 为 38 字节161624。数据负载区存区域字符串每条是2 字节长度 内容。生成器 maker/golang/xdb/maker.go 中的regionPool map[string]uint32说明相同区域字符串只落盘一份各段索引通过dataPtr共享引用——这是 xdb 体积远小于源文本的原因也是上亿段可容纳的关键。一次 10 微秒的查询到底走了几步searcher.go 的Search方法第 111 行起把整个路径写成三步全程无递归、无锁向量索引定位取 IP 字节ipBytes[0]、ipBytes[1]算出偏移idx b0*256*8 b1*8一次取出 8 字节拿到sPtr/ePtr。指针为 0 表示源数据无此分组直接返回段索引内二分在[sPtr, ePtr]区间内按SegmentIndexSize步进二分比较起止 IP命中后读出dataLen/dataPtr读区域数据按dataPtr一次读出区域字符串返回。每一步都经过read()抽象若contentBuff ! nil则从内存拷贝IO 计数不增否则Seek Read磁盘并累加ioCount。这就解释了上表的 IO 差异——同一份算法只是第 1 步和若干二分步是否落盘的区别。边界行为值得记住IP 未命中返回空字符串非错误v4 searcher 收到 16 字节 IP 会返回invalid ip address(IPv4 expected)错误第 127 行的长度校验解析失败如非法字符串返回parse ip错误。所以业务侧用if region 判未命中、用err判真实故障即可。查询客户端与生成工具的多语言矩阵各语言 binding 的 API 设计高度对齐同样是 file / vectorIndex / buffer 三档 相同的空串语义下表汇总仓库内置实现细节看各目录 README查询客户端binding/IPv4IPv6生成器maker/IPv4IPv6Golang✔✔Golang✔✔Java✔✔Java✔✔C (c99)✔✔C✔✔C✔✔Rust✔✔Rust✔✔Python✔✘Python✔✔C#✔✘PHP✔✔JavaScript✔✔Lua / Lua_c✔✔C#✔✔Erlang✔✔Nginx 模块✔✔仓颉 Cangjie✔✔两个使用要点用一句话带过即可C 客户端binding/c/xdb_searcher.c用xdb_region_buffer_t管理区域内存每次查询后必须调用xdb_region_buffer_free因为未清理的残留内存会让下一次xdb_search直接报错生成工具链除gen外还提供bench校验与edit维护子命令Docker 镜像见 maker/golang/Dockerfile适合在隔离环境跑生成与验证。用 maker 生成自己的 xdb 文件并用 bench 强制验证区域字段完全可自定义把 GPS 坐标、邮编等业务数据追加进源文本用--field-list按字段索引重组支持3-6这样的区间语法xdb 会原样承载。生成命令maker/golang下make得到xdb_maker./xdb_maker gen --src../../data/ipv4_source.txt \ --dst./ip2region_v4.xdb \ --versionipv4 \ --field-list0,1,2,3-6,7 # 省略则取全部字段生成后务必跑一遍 bench原因在下一章 FAQ 里说明./xdb_maker bench --db./ip2region_v4.xdb \ --src../../data/ipv4_source.txt \ --versionipv4 # 输出 Bench finished 即通过Cost 为单次平均耗时--src参数与生成时用的源文件必须一致因为 bench 是逐段比对xdb 查询结果 vs 源文本区域信息源文件不一致时比对本身就是无效基准通过与否都不作数。出错时 bench 默认立即终止想跳过错误看全量失败统计加--ignore-errortrue。维护 IP 数据edit 子命令与检测式更新两条路仓库自带源数据只更新不定期高频准确数据建议采购官方社区或第三方商业离线数据自行维护走两条路径手工编辑。edit子命令加载整份源文本进内存v4 全量约 68 万段加载在 1 秒内提供 4 个交互命令./xdb_maker edit --src../../data/ipv4_source.txt --versionipv4 editor put 36.132.128.0|36.132.147.255|中国|黑龙江省|哈尔滨市|移动|CN # - Ok, with 1 deletes and 2 additions自动完成原段的拆分与替换 editor put_file ../../data/sample/ip.test.txt # 批量允许段重叠自动分析合并 editor save # 写回源文件put_file允许输入段与现有段重叠且不要求连续编辑器负责切割补全这正是它比手工改文本安全的地方。save之后用上面的gen重新生成 xdb再bench验证闭环完成。检测式自动更新。如果你有海量真实访问日志可以回收IP → 实际归属反馈可参考官方数据更新文档与视频讲的 Detection Algorithm用现有数据做基准、比对真实反馈、识别漂移段后走put_file增量修正——这条路只适合持续采集反馈数据的业务方。四步落地路线与四个高频坑推荐的上线路径把data/ip2region_v4.xdb、data/ip2region_v6.xdb随部署产物分发用service.Ip2RegionVIndexCache接入searcher 数量对齐你的并发水位服务启动时调用xdb.VerifyFromFile(dbPath)各校验一次实现读头部 stat确认文件不超过指针上限2^(8×RuntimePtrBytes)-1不要把校验放进每次创建 Searcher 的路径——高并发下重复开文件、读头会直接抬高查询响应时间用bench对 xdb 与源数据做一次全量比对确认交付版本一致后续数据更新固定走edit → save → gen → bench四步每步都有产物可复核。四个高频坑坑现象原因并发共用一个 file/vectorIndex 模式 Searcher结果错乱源码注释明确Not thread safeioCount/游标是共享可变状态改用service.Ip2Region池化或每 goroutine 独立实例content 模式例外单实例即安全bench 报错或结果对不上误判 xdb 损坏十有八九是--src与生成时的源文件不一致先核对源文件版本v4 服务查 v6 IP 报invalid ip address误以为 IP 非法长度校验不匹配v4/v6 必须用各自 xdb 与对应配置每次新建连接都 Verify高并发下延迟抖动校验是启动期一次性动作运行期重复做属于用启动开销换零收益按这个顺序做完你就拿到了一个查询路径只有 3 步、内存开销可控、数据可持续维护的离线定位底座。【免费下载链接】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），仅供参考