Loading... # ip2region 离线 IP 地址定位库技术分析 # 一、项目概述 ## 1. 简介 ### A. 是什么 ip2region 是一个离线 IP 地址定位库和 IP 定位数据管理框架，同时支持 IPv4 和 IPv6，10 微秒级别的查询效率，提供了众多主流编程语言的 xdb 数据生成和查询客户端实现。 ### B. 为什么值得关注 - 极致性能：单次查询响应时间在十微秒级别 - 完全离线：无需外部 API 调用，降低延迟和成本 - 多语言支持：涵盖 Golang、PHP、Java、C、Lua、Rust、Python、JavaScript、Csharp 等主流编程语言 - 数据可控：支持自定义 region 信息，可管理自有 IP 定位数据 ### C. 适用场景 - 用户地理位置统计和分析 - 访问控制和地域限制 - 广告定向投放 - 安全防护和反欺诈 - 离线环境的 IP 定位需求 ## 2. 核心特性 ### A. 离线定位库 项目提供了一份 IPv4（data/ipv4_source.txt）和 IPv6（data/ipv6_source.txt）的原始数据和对应的 xdb 文件（data/ip2region_v4.xdb 和 data/ip2region_v6.xdb）用于实现精确到城市的查询定位功能。 ### B. 数据管理框架 xdb 支持亿级别的 IP 数据段行数，region 信息支持完全自定义。自带数据的 region 信息固定格式为：国家|省份|城市|ISP。可以在 region 中追加特定业务需求的数据，例如 GPS 信息、国际统一地域信息编码、邮编等。 ### C. 数据去重和压缩 xdb 格式生成程序会自动处理输入的原始数据，检查并且完成相连 IP 段的合并以及相同地域信息的去重和压缩。 # 二、技术架构 ## 1. 系统组成 ip2region 由三个核心部分组成： ### A. 原始数据源 - IPv4 原始数据：ipv4_source.txt - IPv6 原始数据：ipv6_source.txt - 数据格式：起始 IP、结束 IP、地域信息 ### B. xdb 数据文件 - 二进制格式的高效索引文件 - 支持 IPv4 和 IPv6 - 经过去重和压缩处理 ### C. 查询客户端 - 多语言实现的查询 API - 统一的查询接口 - 支持内存加速查询 ## 2. 工作原理 ```mermaid graph TB A[IP 地址输入] --> B[查询客户端] B --> C{xdb 查询引擎} C --> D[Vector Index 缓存] C --> E[XDB 文件] D --> F[内存加速] E --> G[磁盘 IO] F --> H[地域信息] G --> H H --> I[返回结果] ```  ## 3. 查询优化策略 ### A. vIndex 索引缓存 使用固定的 512KiB 的内存空间缓存 vector index 数据，减少一次 IO 磁盘操作，保持平均查询效率稳定在 100 微秒之内。 ### B. xdb 整个文件缓存 将整个 xdb 文件全部加载到内存，内存占用等同于 xdb 文件大小，无磁盘 IO 操作，保持 10 微秒级别的查询效率。 ```mermaid graph LR A[查询策略] --> B[vIndex 缓存] A --> C[文件缓存] B --> D[512KiB 内存] B --> E[100 微秒级] C --> F[xdb 文件大小] C --> G[10 微秒级] ```  # 三、xdb 数据结构 ## 1. 数据格式设计 xdb 格式是 ip2region 的核心创新，通过精巧的数据结构设计实现了极高效的查询性能。 ### A. 存储结构 - Vector Index：向量索引，用于快速定位数据块 - Data Segment：数据段，存储 IP 范围和地域信息 - Region Info：地域信息，采用压缩存储 ### B. 查询流程 ```mermaid sequenceDiagram participant C as 客户端 participant V as Vector Index participant S as Data Segment participant R as Region Info C->>V: 输入 IP 地址 V->>V: 计算 IP 索引 V->>S: 定位数据段 S->>R: 读取地域信息 R-->>C: 返回定位结果 ```  ## 2. 数据生成流程 ### A. 输入数据处理 - 读取原始 IP 数据 - 验证数据格式 - 合并连续 IP 段 ### B. 去重和压缩 - 相同地域信息去重 - IP 段合并优化 - 区域信息压缩 ### C. 索引构建 - 生成 Vector Index - 构建 Data Segment - 写入 xdb 文件 # 四、多语言支持 ## 1. 查询客户端实现 ip2region 提供了丰富的编程语言绑定，覆盖了主流的开发场景： | 编程语言 | 描述 | IPv4 支持 | IPv6 支持 | |---------|------|----------|----------| | Golang | golang xdb 查询客户端 | 支持 | 支持 | | PHP | php xdb 查询客户端 | 支持 | 支持 | | Java | java xdb 查询客户端 | 支持 | 支持 | | C | POSIX C xdb 查询客户端 | 支持 | 支持 | | Lua_c | lua c 扩展 xdb 查询客户端 | 支持 | 支持 | | Lua | lua xdb 查询客户端 | 支持 | 支持 | | Rust | rust xdb 查询客户端 | 支持 | 支持 | | Python | python xdb 查询客户端 | 支持 | 支持 | | Javascript | javascript xdb 查询客户端 | 支持 | 支持 | | Csharp | csharp xdb 查询客户端 | 支持 | 支持 | | Erlang | erlang xdb 查询客户端 | 支持 | 不支持 | | Nginx | nginx 扩展 xdb 查询客户端 | 支持 | 不支持 | | C++ | C++ xdb 查询客户端 | 支持 | 支持 | ## 2. 数据生成工具 | 编程语言 | 描述 | IPv4 支持 | IPv6 支持 | |---------|------|----------|----------| | Golang | golang xdb 生成程序 | 支持 | 支持 | | Java | java xdb 生成程序 | 支持 | 支持 | | Python | python xdb 生成程序 | 支持 | 不支持 | | Csharp | csharp xdb 生成程序 | 支持 | 不支持 | | Rust | rust xdb 生成程序 | 支持 | 支持 | | C++ | C++ xdb 生成程序 | 支持 | 支持 | # 五、使用示例 ## 1. Python 查询示例 ```python from xdbSearcher import XdbSearcher # 创建查询对象 db_path = "ip2region.xdb" searcher = XdbSearcher(db_path) # 查询 IP 地址 ip = "202.96.128.86" region = searcher.search(ip) print(region) # 输出：中国|0|上海|电信 # 使用缓存加速 searcher_with_cache = XdbSearcher(db_path, vector_index=True) region = searcher_with_cache.search(ip) # 关闭查询对象 searcher.close() ``` ## 2. Golang 查询示例 ```go package main import ( "fmt" "github.com/lionsoul2014/ip2region/xdb" ) func main() { // 创建查询对象 searcher, err := xdb.New("./ip2region.xdb") if err != nil { panic(err) } defer searcher.Close() // 查询 IP 地址 ip := "202.96.128.86" region, err := searcher.SearchByStr(ip) if err != nil { panic(err) } fmt.Println(region) // 输出：中国|0|上海|电信 } ``` # 六、数据更新机制 ## 1. 数据源管理 ip2region 项目的核心在于研究 IP 数据的存储和快速查询的设计和实现，项目自带的原始数据不会再提供更新。 ### A. 数据源获取途径 - ip2region 社区提供的数据（关注官方公众号） - ip2region Github/Gitee 中带有数据源补充标签的 Issue - 其他自定义数据：客户提供的数据、GPS 和 WIFI 定位数据、其他平台的合法合规数据 ### B. 手动编辑更新 基于 ip2region 自带的原始 IP 数据，使用提供的编辑工具来修改数据。 | 编程语言 | 描述 | IPv4 支持 | IPv6 支持 | |---------|------|----------|----------| | Golang | golang IP 原始数据编辑器 | 支持 | 支持 | | Java | java IP 原始数据编辑器 | 支持 | 不支持 | | C++ | C++ IP 原始数据编辑器 | 支持 | 支持 | ## 2. 自动更新机制 如果通过自己的 API 或数据源来更新数据，可以参考基于检测算法的更新算法来编写更新程序。 # 七、性能分析 ## 1. 查询性能指标 - 基于文件的查询：十微秒级别 - vIndex 缓存查询：100 微秒级别 - 全文件内存缓存：10 微秒级别 ## 2. 内存占用 - vIndex 缓存模式：固定 512KiB - 全文件缓存模式：等同于 xdb 文件大小（通常数 MB 到数十 MB） ## 3. 并发安全 xdb 格式设计支持并发安全查询，读操作无需加锁。 # 八、应用场景 ## 1. Web 应用 - 用户访问统计和分析 - 地域化内容展示 - 访问控制和限制 ## 2. 移动应用 - 位置服务增强 - 内容推荐优化 - 用户行为分析 ## 3. 网络安全 - 异常访问检测 - 地域欺诈防护 - 访问来源追踪 # 九、社区生态 ## 1. 官方社区 Ip2Region 官方社区于 2025 年 6 月 12 日正式上线，提供稳定的商用离线数据服务。 ### A. 社区服务 - 商用离线数据服务 - 使用文档和查询测试 - 数据纠错和反馈 ### B. 技术支持 - 微信公众号：lionsoul-org - GitHub 仓库：lionsoul2014/ip2region - 官方社区网站 ## 2. 技术文档 项目提供了丰富的技术文档，包括： - xdb 数据结构分析 - xdb 查询过程分析 - xdb 生成过程分析 - xdb 文件生成教程 - xdb 并发安全查询 - xdb 数据更新方法 # 十、技术特点总结 ## 1. 核心优势 - 极致性能：10 微秒级查询响应 - 完全离线：无外部依赖 - 多语言支持：覆盖主流编程语言 - 数据可控：支持自定义地域信息 ## 2. 技术创新 - xdb 数据格式：高效的数据结构和索引设计 - 内存优化：灵活的缓存策略 - 数据压缩：智能的 IP 段合并和去重 ## 3. 适用性 - 高并发场景：并发安全查询 - 低延迟要求：微秒级响应 - 离线环境：无需网络连接 - 多语言项目：跨平台支持 *** ## 参考资料 1. [ip2region GitHub 仓库](https://github.com/lionsoul2014/ip2region) 最后修改：2026 年 01 月 27 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏