ip2region 极速离线 IP 地址定位库

博主： admin
发布时间：2026 年 07 月 21 日
2 次浏览
暂无评论
5586字数
分类：工具箱数据库查询 IP地址

# ip2region 极速离线 IP 地址定位库

# 一、概述

## 1. 简介
### A. 是什么
ip2region 是一个离线 IP 地址定位库和 IP 定位数据管理框架。该项目支持 IPv4 和 IPv6 双协议，查询效率达到微秒级（10-microsecond），并提供多主流编程语言的 xdb 数据生成和查询客户端实现。

### B. 为什么使用
- 离线查询，无需外部 API 依赖，降低运营成本
- 查询速度极快，单次查询响应时间在 10 微秒级别
- 支持 IPv4 和 IPv6 双协议
- 数据可自定义，满足业务特定需求
- 跨平台支持，提供 13 种编程语言的客户端实现

### C. 适用场景
- 网站访问者地域分析
- 广告投放精准定位
- 安全防护区域限制
- 用户行为地域统计
- CDN 节点智能调度

## 2. 核心特性
### A. 离线定位库
项目提供 IPv4 原始数据（data/ipv4_source.txt）和 IPv6 原始数据（data/ipv6_source.txt），以及对应的 xdb 文件（data/ip2region_v4.xdb 和 data/ip2region_v6.xdb），实现城市级别的定位查询。

字段格式：国家|省份|城市|运营商|ISO-alpha2 代码

中国地区信息全部为中文，非中国地区信息全部为英文。

### B. 数据管理框架
xdb 格式支持数亿级 IP 数据段，区域信息支持完全自定义。内置数据的区域信息固定为：国家|省份|城市|运营商|ISO-alpha2-Code。可根据特定业务需求向区域追加数据，例如：GPS 信息、国际标准区域代码、邮政编码等。

### C. 数据去重与压缩
xdb 格式生成程序自动处理输入的原始数据，检查并完成相邻 IP 段的合并，对相同区域信息进行去重和压缩。

### D. 高速查询响应
即使完全基于 xdb 文件查询，单次查询响应时间也在 10 微秒级别。可通过以下两种方式开启内存加速查询：
- vIndex 索引缓存：使用固定的 512KiB 内存缓存向量索引数据，减少一次磁盘 IO 操作，保持平均查询效率在 100 微秒以内
- 全量 xdb 文件缓存：将整个 xdb 文件加载到内存，内存占用等于 xdb 文件大小，无磁盘 IO 操作，保持 10 微秒级查询效率

### E. 统一查询接口
xdb 提供版本兼容的查询实现。统一 API 可同时提供 IPv4 和 IPv6 数据查询，并返回统一数据格式。

# 二、xdb 查询

## 1. 支持的语言
项目提供以下查询客户端实现：

| 语言 | 描述 | IPv4 支持 | IPv6 支持 |
|------|------|----------|----------|
| Golang | Go 语言查询客户端 | ✅ | ✅ |
| PHP | PHP 查询客户端 | ✅ | ✅ |
| Java | Java 查询客户端 | ✅ | ✅ |
| C | C 语言查询客户端（std=c99） | ✅ | ✅ |
| Lua_c | Lua C 扩展查询客户端 | ✅ | ✅ |
| Lua | Lua 查询客户端 | ✅ | ✅ |
| Rust | Rust 查询客户端 | ✅ | ✅ |
| Python | Python 查询客户端 | ✅ | ✅ |
| Javascript | JavaScript 查询客户端 | ✅ | ✅ |
| Csharp | C# 查询客户端 | ✅ | ✅ |
| Erlang | Erlang 查询客户端 | ✅ | ✅ |
| Nginx | Nginx 扩展查询客户端 | ✅ | ✅ |
| C++ | C++ 查询客户端 | ✅ | ✅ |
| Cangjie | 仓颉语言查询客户端 | ✅ | ✅ |

社区开发者通过第三方仓库贡献的工具链实现：

| 语言 | 描述 |
|------|------|
| ip2region-composer | PHP Composer 管理客户端 |
| ip2region-ts | Node.js Addon 管理客户端 |
| ruby-ip2region | Ruby xdb 查询客户端实现 |
| Ip2regionTool | ip2region 数据转换工具 |

## 2. 查询示例

### Python 示例
```python
from xdb_searcher import XdbSearcher

# 创建查询对象
searcher = XdbSearcher("../data/ip2region.xdb")

# 查询 IP
region = searcher.search("202.96.128.166")
print(region)

# 关闭查询对象
searcher.close()
```

### Java 示例
```java
import org.lionsoul.ip2region.xdb.Searcher;

// 创建查询对象
Searcher searcher = Searcher.newWithFileOnly("../data/ip2region.xdb");

// 查询 IP
String region = searcher.search("202.96.128.166");
System.out.println(region);

// 关闭查询对象
searcher.close();
```

# 三、xdb 生成

## 1. 支持的语言
项目提供以下生成程序实现：

| 语言 | 描述 | IPv4 支持 | IPv6 支持 |
|------|------|----------|----------|
| Golang | Go xdb 生成程序 | ✅ | ✅ |
| Java | Java xdb 生成程序 | ✅ | ✅ |
| Python | Python xdb 生成程序 | ✅ | ❌ |
| Csharp | C# xdb 生成程序 | ✅ | ❌ |
| Rust | Rust xdb 生成程序 | ✅ | ✅ |
| C++ | C++ xdb 生成程序 | ✅ | ✅ |

## 2. 生成流程

```mermaid
graph LR
    A[原始 IP 数据] --> B[数据预处理]
    B --> C[IP 段合并]
    C --> D[区域去重]
    D --> E[生成 xdb 索引]
    E --> F[写入 xdb 文件]
```

![xdb 生成流程](https://static.op123.ren/static/a1/b2c3d4e5f6a7.svg)

## 3. 生成命令示例

### Go 语言生成
```bash
cd maker/golang
go run go_maker.go ../data/ip2region.xdb ../data/ip2region.data
```

### Java 生成
```bash
cd maker/java
java -jar java-maker.jar ../data/ip2region.xdb ../data/ip2region.data
```

# 四、xdb 数据更新

## 1. 数据来源
ip2region 项目的核心在于研究 IP 数据存储和快速查询的设计与实现。项目包含的原始数据 ./data/ipv4_source.txt 和 ./data/ipv6_source.txt 不定期更新。对于数据准确性和更新频率要求较高的场景，建议从 Ip2Region 社区或第三方供应商购买商业离线数据。

### 手动编辑更新
可基于 ip2region 提供的原始 IP 数据（./data/ipv4_source.txt 和 ./data/ipv6_source.txt），使用 ip2region 提供的编辑工具自行修改数据。

当前数据来源包括：
- ip2region 社区提供的数据
- 标记为 [Data_Updates] 的项目 Issues
- 其他自定义数据：如客户提供的数据、通过 GPS 和 WIFI 定位获取的数据、或其他平台的合法合规数据

## 2. 编辑工具

| 语言 | 描述 | IPv4 支持 | IPv6 支持 |
|------|------|----------|----------|
| Golang | Go IP 原始数据编辑器 | ✅ | ✅ |
| C++ | C++ IP 原始数据编辑器 | ✅ | ✅ |

## 3. 自动更新算法
若希望通过自己的 API 或数据源更新数据，可参考基于"探测算法"共享在以下视频中的更新算法编写自己的更新程序：
- 数据更新实现视频分享 - part1
- 数据更新实现视频分享 - part2

# 五、技术架构

## 1. xdb 数据结构

```mermaid
graph TD
    A[xdb 文件] --> B[Header 区域]
    A --> C[Vector Index 区域]
    A --> D[Segment 区域]

B --> B1[版本信息]
    B --> B2[元数据]

C --> C1[向量索引块]
    C --> C2[二分查找索引]

D --> D1[IP 段数据]
    D --> D2[区域信息]
```

![xdb 数据结构](https://static.op123.ren/static/b2/c3d4e5f6a7b8.svg)

### 核心组件说明
- Header 区域：存储版本信息和元数据
- Vector Index 区域：向量索引块，支持快速定位
- Segment 区域：存储实际的 IP 段数据和区域信息

## 2. 查询流程

```mermaid
sequenceDiagram
    participant C as 客户端
    participant S as XdbSearcher
    participant F as xdb 文件
    participant M as 内存缓存

C->>S: 查询 IP 地址
    S->>M: 检查索引缓存

alt 索引已缓存
        M-->>S: 返回索引数据
    else 索引未缓存
        S->>F: 读取索引
        F-->>S: 索引数据
        S->>M: 缓存索引
    end

S->>F: 读取段数据
    F-->>S: 区域信息
    S-->>C: 返回查询结果
```

![查询流程时序图](https://static.op123.ren/static/c3/d4e5f6a7b8c9.svg)

### 查询优化
- vIndex 缓存：缓存向量索引，减少磁盘 IO
- 全量缓存：加载整个 xdb 到内存，消除磁盘 IO
- 二分查找：高效定位 IP 段

# 六、性能对比

## 1. 查询性能

| 查询模式 | 响应时间 | 内存占用 | 磁盘 IO |
|---------|---------|---------|---------|
| 纯文件查询 | 10-50 微秒 | 最小 | 2 次 |
| vIndex 缓存 | 10-20 微秒 | 512 KiB | 1 次 |
| 全量缓存 | 5-10 微秒 | 文件大小 | 0 次 |

## 2. 数据规模

| 数据类型 | 记录数 | xdb 文件大小 |
|---------|-------|-------------|
| IPv4 | 约 500 万条 | 约 10 MB |
| IPv6 | 约 800 万条 | 约 25 MB |

# 七、官方社区

Ip2Region 官方社区于 2025/06/12 正式上线。一方面提供稳定的商业离线数据服务，另一方面加强核心代码之外的 IP 工具链和数据服务，如使用文档、查询测试、数据修正等。

访问 Ip2Region 官方社区获取更多信息和服务。

# 八、技术资源

## 1. xdb 技术文档

- xdb 数据结构分析：ip2region xdb - 数据结构描述
- xdb 查询过程分析：ip2region xdb - 查询过程描述
- xdb 生成过程分析：ip2region xdb - 生成过程描述
- xdb 文件生成教程：ip2region xdb - 文件生成教程
- xdb 并发安全查询：ip2region xdb - 并发安全查询
- xdb 数据更新方法：ip2region 数据更新和 xdb 数据编辑器使用

## 2. 技术信息博客
- 微信公众号 - lionsoul-org，作者活跃的技术分享渠道
- Ip2Region 官方社区

***

## 参考资料

1. [ip2region GitHub 仓库](https://github.com/lionsoul2014/ip2region)

最后修改：2026 年 07 月 21 日

如果觉得我的文章对你有用，请随意赞赏

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

评论 *

私密评论

名称 *

🎲

邮箱 *

地址

kkk
老师可以加个联系方式吗
张
很不错。除了那个qemu-tools
angux
会考虑关停服务么。。如果不考虑可以支持你
zm
ishare2 config 这一步过不去，卡在了“Unabl...
sheldon
得劲的很

ip2region 极速离线 IP 地址定位库

admin • 2026 年 07 月 21 日

# ip2region 极速离线 IP 地址定位库

# 一、概述

### C. 适用场景
- 网站访问者地域分析
- 广告投放精准定位
- 安全防护区域限制
- 用户行为地域统计
- CDN 节点智能调度

字段格式：国家|省份|城市|运营商|ISO-alpha2 代码

中国地区信息全部为中文，非中国地区信息全部为英文。

### C. 数据去重与压缩
xdb 格式生成程序自动处理输入的原始数据，检查并完成相邻 IP 段的合并，对相同区域信息进行去重和压缩。

### E. 统一查询接口
xdb 提供版本兼容的查询实现。统一 API 可同时提供 IPv4 和 IPv6 数据查询，并返回统一数据格式。

# 二、xdb 查询

## 1. 支持的语言
项目提供以下查询客户端实现：

社区开发者通过第三方仓库贡献的工具链实现：

## 2. 查询示例

### Python 示例
```python
from xdb_searcher import XdbSearcher

# 创建查询对象
searcher = XdbSearcher("../data/ip2region.xdb")

# 查询 IP
region = searcher.search("202.96.128.166")
print(region)

# 关闭查询对象
searcher.close()
```

### Java 示例
```java
import org.lionsoul.ip2region.xdb.Searcher;

// 创建查询对象
Searcher searcher = Searcher.newWithFileOnly("../data/ip2region.xdb");

// 查询 IP
String region = searcher.search("202.96.128.166");
System.out.println(region);

// 关闭查询对象
searcher.close();
```

# 三、xdb 生成

## 1. 支持的语言
项目提供以下生成程序实现：

## 2. 生成流程

```mermaid
graph LR
    A[原始 IP 数据] --> B[数据预处理]
    B --> C[IP 段合并]
    C --> D[区域去重]
    D --> E[生成 xdb 索引]
    E --> F[写入 xdb 文件]
```

![xdb 生成流程](https://static.op123.ren/static/a1/b2c3d4e5f6a7.svg)

## 3. 生成命令示例

### Go 语言生成
```bash
cd maker/golang
go run go_maker.go ../data/ip2region.xdb ../data/ip2region.data
```

### Java 生成
```bash
cd maker/java
java -jar java-maker.jar ../data/ip2region.xdb ../data/ip2region.data
```

# 四、xdb 数据更新

### 手动编辑更新
可基于 ip2region 提供的原始 IP 数据（./data/ipv4_source.txt 和 ./data/ipv6_source.txt），使用 ip2region 提供的编辑工具自行修改数据。

## 2. 编辑工具

| 语言 | 描述 | IPv4 支持 | IPv6 支持 |
|------|------|----------|----------|
| Golang | Go IP 原始数据编辑器 | ✅ | ✅ |
| C++ | C++ IP 原始数据编辑器 | ✅ | ✅ |

# 五、技术架构

## 1. xdb 数据结构

```mermaid
graph TD
    A[xdb 文件] --> B[Header 区域]
    A --> C[Vector Index 区域]
    A --> D[Segment 区域]

B --> B1[版本信息]
    B --> B2[元数据]

C --> C1[向量索引块]
    C --> C2[二分查找索引]

D --> D1[IP 段数据]
    D --> D2[区域信息]
```

![xdb 数据结构](https://static.op123.ren/static/b2/c3d4e5f6a7b8.svg)

### 核心组件说明
- Header 区域：存储版本信息和元数据
- Vector Index 区域：向量索引块，支持快速定位
- Segment 区域：存储实际的 IP 段数据和区域信息

## 2. 查询流程

```mermaid
sequenceDiagram
    participant C as 客户端
    participant S as XdbSearcher
    participant F as xdb 文件
    participant M as 内存缓存

C->>S: 查询 IP 地址
    S->>M: 检查索引缓存

alt 索引已缓存
        M-->>S: 返回索引数据
    else 索引未缓存
        S->>F: 读取索引
        F-->>S: 索引数据
        S->>M: 缓存索引
    end

S->>F: 读取段数据
    F-->>S: 区域信息
    S-->>C: 返回查询结果
```

![查询流程时序图](https://static.op123.ren/static/c3/d4e5f6a7b8c9.svg)

### 查询优化
- vIndex 缓存：缓存向量索引，减少磁盘 IO
- 全量缓存：加载整个 xdb 到内存，消除磁盘 IO
- 二分查找：高效定位 IP 段

# 六、性能对比

## 1. 查询性能

## 2. 数据规模

| 数据类型 | 记录数 | xdb 文件大小 |
|---------|-------|-------------|
| IPv4 | 约 500 万条 | 约 10 MB |
| IPv6 | 约 800 万条 | 约 25 MB |

# 七、官方社区

访问 Ip2Region 官方社区获取更多信息和服务。

# 八、技术资源

## 1. xdb 技术文档

## 2. 技术信息博客
- 微信公众号 - lionsoul-org，作者活跃的技术分享渠道
- Ip2Region 官方社区

***

## 参考资料

1. [ip2region GitHub 仓库](https://github.com/lionsoul2014/ip2region)

ip2region 极速离线 IP 地址定位库

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

搭建国内LabHub

CentOS 7.9 编译并使用rpm方式升级openssh9.6p1（包括后续更新9.8p1等）

一天从 redis 大 key 开始

安装eve-ng

重装ensp

部署wireguard

修改typecho插件hansome的右下角

Whosthere 局域网发现工具技术分析

Better Shot macOS 截图工具技术分析

categraf升级至0.3.38

ip2region 极速离线 IP 地址定位库

发表评论 取消回复 使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

ip2region 极速离线 IP 地址定位库

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款