Loading... # ip2region 极速离线 IP 地址定位库 # 一、概述 ## 1. 项目简介 ip2region 是一个离线 IP 地址定位库和 IP 定位数据管理框架。该项目同时支持 IPv4 和 IPv6，查询效率达到微秒级别，提供了众多主流编程语言的 xdb 数据生成和查询客户端实现。 ## 2. 核心特性 - 10 微秒级别的查询响应时间 - 支持亿级 IP 数据段 - 支持 IPv4 和 IPv6 - 提供多语言客户端实现 - 数据完全离线，无需网络请求 - 标准化的地域信息格式 ## 3. 应用场景 - 用户行为分析和地域统计 - 网络安全访问控制 - 内容分发网络节点选择 - 广告投放地域定向 - 日志分析和地域可视化 # 二、核心功能 ## 1. 离线定位库 项目同时提供了 IPv4 和 IPv6 的原始数据及对应的 xdb 格式文件，可以实现精确到城市的查询定位。 地域信息字段格式：`国家|省份|城市|ISP|iso-alpha2-code` 示例数据： - 中国：`中国|0|广东省|深圳市|电信|CN` - 美国：`美国|0|加利福尼亚|0|Google|US` ## 2. 数据管理框架 xdb 格式支持： - 亿级别的 IP 数据段行数 - 完全自定义的 region 信息 - 自动数据去重和压缩 - 相邻 IP 段自动合并 ## 3. 极速查询响应 ```mermaid graph LR A[IP 地址输入] --> B{查询方式} B -->|文件查询| C[基于 xdb 文件] B -->|向量索引缓存| D[512KiB 内存缓存] B -->|全文件缓存| E[xdb 全部加载] C --> F[10 微秒响应] D --> G[100 微秒响应] E --> F F --> H[返回地域信息] G --> H ```  三种查询方式的性能对比： - 文件查询：10 微秒级别，无内存占用 - 向量索引缓存：100 微秒级别，占用 512KiB 内存 - 全文件缓存：10 微秒级别，内存占用等同 xdb 文件大小 # 三、技术架构 ## 1. xdb 数据结构 xdb 是 ip2region 自研的高效 IP 数据存储格式，核心设计理念： ```mermaid graph TD A[xdb 文件] --> B[Header 信息] A --> C[Vector Index] A --> D[Segment Data] B --> E[版本信息] B --> F[元数据] C --> G[512KiB 索引块] D --> H[IP 段数据] D --> I[Region 信息] G --> J[快速定位] H --> K[二分查找] J --> L[查询结果] K --> L ```  ## 2. 查询流程 ### A. 基于文件的查询 1. 读取 IP 地址的前两个段 2. 通过 Vector Index 定位到数据段 3. 在数据段中二分查找精确匹配 4. 读取对应的 Region 信息 ### B. 内存加速查询 - 向量索引缓存：将 512KiB 的 Vector Index 加载到内存 - 全文件缓存：将整个 xdb 文件加载到内存 ## 3. 数据生成流程 ```mermaid graph LR A[原始 IP 数据] --> B[数据验证] B --> C[IP 段合并] C --> D[去重压缩] D --> E[Region 编码] E --> F[生成 xdb 文件] F --> G[文件校验] ```  # 四、多语言支持 ## 1. 查询客户端 ip2region 提供了丰富的编程语言客户端实现： | 编程语言 | IPv4 支持 | IPv6 支持 | |---------|----------|----------| | Golang | ✅ | ✅ | | PHP | ✅ | ✅ | | Java | ✅ | ✅ | | C | ✅ | ✅ | | Rust | ✅ | ✅ | | Python | ✅ | ✅ | | JavaScript | ✅ | ✅ | | Csharp | ✅ | ✅ | | Erlang | ✅ | ✅ | | Nginx | ✅ | ✅ | | C++ | ✅ | ✅ | | Cangjie | ✅ | ✅ | | Lua | ✅ | ✅ | ## 2. 数据生成工具 | 编程语言 | IPv4 支持 | IPv6 支持 | |---------|----------|----------| | Golang | ✅ | ✅ | | Java | ✅ | ✅ | | Python | ✅ | ❌ | | Csharp | ✅ | ❌ | | Rust | ✅ | ✅ | | C++ | ✅ | ✅ | # 五、使用示例 ## 1. Python 查询示例 ```python from xdbSearcher import XdbSearcher # 创建查询对象 db_path = "ip2region.xdb" searcher = XdbSearcher(db_path) # 文件查询 ip_str = "1.1.1.1" region = searcher.search(ip_str) print(region) # 内存缓存查询 searcher.set_vector_index() region = searcher.search(ip_str) print(region) ``` ## 2. Golang 查询示例 ```go package main import ( "fmt" "github.com/lionsoul2014/ip2region/binding/golang/xdb" ) func main() { // 创建查询对象 searcher, err := xdb.New("ip2region.xdb") if err != nil { panic(err) } // 查询 IP ipStr := "1.1.1.1" region, err := searcher.Search(ipStr) if err != nil { panic(err) } fmt.Println(region) } ``` ## 3. Java 查询示例 ```java import org.lionsoul.ip2region.xdb.Searcher; public class Main { public static void main(String[] args) throws Exception { // 创建查询对象 String dbPath = "ip2region.xdb"; Searcher searcher = Searcher.newWithFileOnly(dbPath); // 查询 IP String ipStr = "1.1.1.1"; String region = searcher.search(ipStr); System.out.println(region); } } ``` # 六、数据更新 ## 1. 数据来源 项目自带的数据源包括： - 项目自带的 ipv4_source.txt 和 ipv6_source.txt - ip2region 社区提供的数据 - Github Issues 中标记为数据源补充的内容 - 第三方商用数据源 ## 2. 手动编辑更新 可以使用项目提供的编辑工具修改原始 IP 数据： ```mermaid graph LR A[获取原始数据] --> B[编辑数据文件] B --> C[使用 maker 工具] C --> D[生成新 xdb] D --> E[验证测试] E --> F[部署使用] ```  ## 3. 自动化更新 对于有高精度和频繁更新需求的场景，可以： - 购买 Ip2Region 官方社区的商用离线数据 - 基于检测算法自行编写更新程序 # 七、性能对比 ## 1. 查询性能 | 方式 | 响应时间 | 内存占用 | 磁盘 IO | |------|---------|---------|---------| | 文件查询 | 10 微秒 | 0 | 有 | | 向量索引缓存 | 100 微秒 | 512KiB | 减少 | | 全文件缓存 | 10 微秒 | 文件大小 | 无 | ## 2. 与其他方案对比 | 特性 | ip2region | GeoLite2 | 纯在线 API | |------|-----------|----------|-----------| | 离线支持 | ✅ | ✅ | ❌ | | 查询速度 | 微秒级 | 毫秒级 | 取决于网络 | | IPv6 支持 | ✅ | ✅ | 取决于服务 | | 数据精度 | 城市级 | 城市级 | 不定 | | 使用成本 | 免费开源 | 免费需注册 | 有限额 | # 八、官方生态 ## 1. Ip2Region 官方社区 2025 年 6 月 12 日正式上线，提供： - 稳定的商用离线数据服务 - 使用文档和技术支持 - 在线查询测试工具 - 数据纠错和更新 ## 2. 技术文档 官方提供了详细的技术文档： - xdb 数据结构分析 - xdb 查询过程分析 - xdb 生成过程分析 - xdb 文件生成教程 - xdb 并发安全查询 - xdb 数据更新方法 ## 3. 技术支持 - 微信公众号：lionsoul-org - 官方网站：https://ip2region.net - GitHub：https://github.com/lionsoul2014/ip2region # 九、最佳实践 ## 1. 选择合适的查询方式 - 高并发低延迟：使用全文件缓存 - 内存受限场景：使用向量索引缓存 - 内存极低场景：使用纯文件查询 ## 2. 数据更新策略 - 低精度需求：使用项目自带数据 - 中等精度：定期从社区获取更新 - 高精度需求：购买商用数据或自建更新机制 ## 3. 并发安全 xdb 查询客户端是线程安全的，可以在多线程环境中共享使用。 ## 4. 监控和日志 建议记录查询失败率和平均响应时间，及时发现数据或性能问题。 # 十、总结 ip2region 是一个高性能、离线的 IP 地址定位解决方案，具有以下优势： - 极速查询：10 微秒级别的响应时间 - 完全离线：无需网络请求，稳定可靠 - 多语言支持：覆盖主流编程语言 - 数据可控：支持自定义数据源 - 开源免费：MIT 许可证 适合需要高性能、高可靠性的 IP 定位应用场景。 *** ## 参考资料 1. [ip2region GitHub 仓库](https://github.com/lionsoul2014/ip2region) 2. [Ip2Region 官方社区](https://ip2region.net) 3. [xdb 数据结构说明](https://ip2region.net/doc/xdb/structure) 4. [xdb 查询过程说明](https://ip2region.net/doc/xdb/search) 最后修改：2026 年 07 月 21 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏