🔍 ip2region：离线IP定位查询库 10微秒查询 IPv4/IPv6双通

ip2region是19.3k Stars离线IP定位库,10微秒级查询,IPv4/IPv6城市级定位全支持,xdb仅10MB含全量数据,15+语言SDK即装即用,国内数据原生中文,电商/广告/风控/日志分析首选,离线零成本比收费API更稳定安全，文末附详细使用教程

🎤 引言

做电商、风控、广告投放、日志分析的同学,肯定被"根据IP定位用户地理位置"这个需求折磨过。

要么接收费 API,每月烧钱;要么接 MaxMind GeoIP,国内数据一塌糊涂;要么自己维护一份 IP 库,每天更新累死。

今天安利的 ip2region 就是来解决这个痛点的 —— 离线 IP 定位库,10 微秒级查询,一次部署终身免费用。

GitHub 上 19.3k Stars / 3k Forks,最新版本 v3.17.0(2026-07-10),Apache 2.0 开源协议,支持 IPv4 + IPv6 双协议,提供 15+ 主流语言的 SDK,国内数据中文、国外数据英文,城市级精度,拿来直接用就行。

⭐ 核心功能

1. 离线 IP 定位(核心能力)

项目本身提供:

IPv4 源数据:data/ipv4_source.txt
IPv6 源数据:data/ipv6_source.txt
预编译 xdb 文件:约 10MB,包含全部 IPv4/IPv6 定位数据

定位字段格式:国家|省份|城市|ISP|iso-alpha2-code

举个例子:

223.104.60.0|223.104.60.127|中国|广东省|深圳市|移动|CN
77.97.180.0|77.97.180.255|United Kingdom|England|Yateley||GB

国内数据中文,海外数据英文,iso 标准两字母国码,规规矩矩。

2. xdb 数据引擎

xdb 是项目自研的二进制索引格式,特点:

查询速度快:10 微秒级别(0.00001 秒),实测 QPS 可达百万
文件体积小:IPv4 + IPv6 合在一起约 10MB
多语言通用:各语言绑定统一用 xdb 格式,一份数据全平台通用

3. 数据管理框架

如果你手上有更好的数据源,可以用项目提供的工具自建 xdb:

# Golang 版编辑器
cd maker/golang
make && make query

# C++ 版编辑器
cd maker/cpp
make && ./ip2region

项目还提供了配套视频教程,手把手教你怎么写自动更新程序,跟官方数据保持同步。

4. 官方社区(2025-06-12 成立)

官方社区提供稳定的商业离线数据服务,同时维护文档、测试工具和数据校正。

📥 安装与使用

安装 xdb 数据文件

# 下载预编译 xdb(IPv4+IPv6)
wget https://github.com/lionsoul2014/ip2region/raw/master/data/ip2region.xdb

# 或下载最新版 v3.17.0
wget https://github.com/lionsoul2014/ip2region/releases/download/v3.17.0/ip2region_v4.xdb
wget https://github.com/lionsoul2014/ip2region/releases/download/v3.17.0/ip2region_v6.xdb

文件放到项目目录即可,约 10MB。

Python 使用

pip install ip2region

from ip2region import Ip2Region

# 方式1:文件模式(推荐,内存占用小)
region = Ip2Region('data/ip2region_v4.xdb')
result = region.binary_search('101.69.193.254')
print(result)  # 中国|广东省|广州市|移动|CN

# 方式2:B-tree 模式
result = region.btree_search('223.73.12.45')
print(result)  # 中国|上海市|上海市|电信|CN

# 方式3:内存模式(最快,约 50MB 内存占用)
region = Ip2Region('data/ip2region_v4.xdb', with_vector_index=True)
result = region.memory_search('8.8.8.8')
print(result)  # United States|California||Google|CN

region.close()

Java 使用

// Maven 引入
// <dependency>
//     <groupId>org.lionsoul</groupId>
//     <artifactId>ip2region</artifactId>
//     <version>1.0.0</version>
// </dependency>

import org.lionsoul.ip2region.*;

Ip2Region searcher = new Ip2Region("data/ip2region_v4.xdb");

// 城市级查询
DataBlock block = searcher.binarySearch("101.69.193.254");
if (block != null) {
    System.out.println(block.getRegion());
    // 中国|广东省|广州市|移动|CN
}

Go 使用

package main

import (
    "fmt"
    "github.com/lionsoul2014/ip2region/v2/binding/golang/ip2region"
)

func main() {
    searcher, _ := ip2region.New("data/ip2region_v4.xdb")
    defer searcher.Close()

    // BinarySearch / BtreeSearch / MemorySearch 三种模式
    info, _ := searcher.BinarySearch("223.73.12.45")
    fmt.Println(info.Region)
    // 中国|上海市|上海市|电信|CN
}

Nginx 模块使用

Nginx 用户可以直接装官方模块,查 IP 归属地直接在内层处理,省去后端调用的开销:

# 克隆并编译 Nginx 模块
git clone https://github.com/lionsoul2014/ip2region.git
cd ip2region/nginx && ./configure && make && make install

# nginx.conf 配置
http {
    ip2region_ipdb_path /path/to/ip2region_v4.xdb;

    server {
        location / {
            # 变量方式调用
            set $ip_region "";
            ip2region_lookup $remote_addr into $ip_region;
            add_header X-IP-Region $ip_region;
        }
    }
}

JavaScript / Node.js 使用

npm install ip2region

const { Ip2Region } = require('ip2region');

const searcher = new Ip2Region('./data/ip2region_v4.xdb');

// 三种缓存模式对比
// file: ~31μs/op, ~32,000 QPS (内存受限)
// vectorIndex: ~22μs/op, ~45,000 QPS (推荐)
// content: ~1.3μs/op, ~750,000 QPS (高并发)

const result = searcher.search('101.69.193.254', 'vectorIndex');
console.log(result.region);  // 中国|广东省|广州市|移动|CN

Rust 使用

use ip2region::{Ip2Region, Config};

fn main() {
    let searcher = Ip2Region::from_file("data/ip2region_v4.xdb").unwrap();
    let result = searcher.search("223.73.12.45");
    println!("{}", result.region);
    // 中国|上海市|上海市|电信|CN
}

🎯 适用场景

风控/反欺诈:根据IP定位用户真实位置,识别 VPN/代理/虚拟机
电商个性化:显示用户所在地区的价格/库存/配送信息
广告投放:按地域定向投放,提高广告转化率
日志分析:百万日志 IP 归属地清洗,离线跑不花钱
CDN 调度:基于用户地理位置就近分配边缘节点
合规审计:记录用户访问地域,满足数据本地化要求
内网安全:识别员工 VPN 出口 IP,判断是否在办公网

🔍 对比/替代方案

方案	数据精度	更新频率	费用	国内数据	查询速度
ip2region	城市级	不定期免费	免费	✅ 中文	10μs
MaxMind GeoLite2	国家/城市	每周	免费(公益)	❌ 差	毫秒级
MaxMind GeoIP2	城市级	每月/每周	收费	❌ 一般	毫秒级
纯真 IP 库	城市级	手动维护	免费	✅ 好	依赖实现
收费 IP API	城市级	实时	按次计费	✅ 好	API 延迟

关键差异

vs 收费 IP 库:ip2region 完全免费,数据更新频率略低,但胜在离线不花钱
vs 纯真 IP 库:纯真数据好但维护靠社区,ip2region 有完整工具链+xdb 格式,多语言 SDK 统一
vs MaxMind:MaxMind 国内数据差(国外准),ip2region 国内数据原生中文且本地化更好
数据格式:ip2region 五字段设计(国家|省份|城市|ISP|iso2)比大多数竞品丰富

⚠️ 注意事项

数据更新频率:官方源数据更新不及时(免费版),对数据时效性要求高的场景(如识别最新 IP 段)建议购买官方商业数据或自行对接上游数据源更新。
IPv6 覆盖率:IPv6 在国内还在逐步普及,部分省份 IPv6 定位数据可能不如 IPv4 准确。
精度局限:定位精度最高到城市级别,无法做到街道级,需要精确定位的场景(如 fraud detection)建议叠加其他数据源。
代理/VPN 失效:用户使用 VPN 或代理时,IP 定位结果为出口节点而非真实位置,建议配合设备指纹等其他信号。
文件路径:各语言 SDK 需要正确传入 xdb 文件路径,建议用绝对路径避免工作目录问题。
并发安全:Ip2Region 查询服务(如 Java Ip2Region Service)支持并发安全,基础 Search 类需要自己加锁或每次 new 一个实例。
版本差异:v3.11.0+ 统一了 API 设计,IPv4/IPv6 可以同时输入查询,旧代码升级时注意 API 变化。

✅ 总结

ip2region 是那种"接上就能用,用了就不想换"的工具。

优点:

离线查询,零 API 费用,一次部署终身免费
10 微秒级查询,实测 QPS 可达百万+,性能完全不是问题
IPv4 + IPv6 双支持,15+ 语言 SDK 覆盖主流技术栈
国内数据原生中文,城市级精度,电商/风控/日志场景够用
xdb 格式轻量(~10MB),方便打包进 Docker 镜像或 CDN 边缘节点

缺点:

免费版数据更新不及时,有精准度要求时建议上商业版
不支持街道级定位,精确定位场景需要叠加其他方案
Nginx 模块配置稍复杂,新手有门槛

推荐指数 ⭐⭐⭐⭐(4/5)
适合:需要 IP 定位但不想烧钱、追求查询性能、喜欢离线部署的开发者/团队。
不适用:对数据时效性要求极高(实时黑名单)、需要街道级精度的场景。

仓库:github.com/lionsoul2014/ip2region
最新版本:v3.17.0 (Jul 10, 2026)
官方社区:Ip2Region Community
安装:pip install ip2region 或对应语言包一行命令搞定