QZDB (qqzeng IP Database) 是一款专为企业级高并发、云原生架构打造的下一代 IP 地理位置与号段归属地二进制搜索引擎。凭借双阶段 Patricia Trie 树算法、
mmap零拷贝以及无锁并发设计，提供单机微秒级响应与超高吞吐。
Important
🚀 为什么选择 QZDB 旗舰解析引擎？
- ⚡ 极致性能：Rust / C / Go 基于只读内存映射（mmap）实现零堆分配查询，单次解析延迟低至 < 0.08 µs (80 纳秒)。
- 🛡️ 全量无抽样验证：对全部
959,162个 CIDR 区间的边界及中心 IP 进行了2,877,486次无抽样全量核对，通过率 100.00%。 - 📦 高密存储：Trie 树前缀压路机算法，千万级全球 IP/CIDR 细化网段体积压缩率高达 95%+（仅十余兆）。
- 🌐 全语言原生 SDK：官方提供 Rust, C/C++, Go, Java, C#, Node.js, PHP, Python 八种主流语言支持。
| 产品线 | 说明与核心亮点 | 包含内容 / 支持语言 | 快速入口 |
|---|---|---|---|
| 🚀 IP 旗舰 QZDB 解析 SDK | 下一代旗舰：双阶段 Trie 树 + mmap 零分配，微秒级响应，支持 IPv4/IPv6 全字段与风控 |
🦀 Rust · 🐹 Go · ☕ Java · ⚡ C/C++ 🔷 C# · 🟩 Node · 🐍 Python · 🐘 PHP |
👉 ip-qzdb-sdk/ |
| 📦 IP 经典版解析 SDK | 经典在用：6.0 经典 .db 与 2.0 早期 .dat 格式多语言解析 SDK 与源码 |
v6.0 (.db) SDK · v2.0 (.dat) SDK | 👉 ip-classic-sdk/ |
| 📱 手机号段归属地 SDK | 50万+ 全号段：压缩率 95.7%+ 的二进制 DAT 解析及 Redis 高并发缓存方案 | v2.0 ~ v6.0 DAT SDK · Redis 导入 | 👉 phone-location-sdk/ |
| 🗄️ 关系型数据库脚本 | 海量入库 DDL：针对 IP 网段与号段优化的建表、前缀索引与批量高速入库脚本 | 🐬 MySQL · 🐘 PostgreSQL · 🪟 SQL Server | 👉 database-sql/ |
| 🗂️ IP 历史版本与工具 | 演进留档：IP 3.0~5.0 早期版本解析、Big DAT 与 Windows 离线查询工具 | v3.0~v5.0 源码 · 桌面查询工具 | 👉 ip-history-sdk/ |
| 📋 脱敏测试样本数据 | 演示样例：IP 归属地与号段 CSV / TXT / QZDB 样例数据 | 全国/全球 IP 样例 · 号段样例 | 👉 demo/ |
| 排名 | 语言 | 查询模式 | 单线程吞吐量 (Ops/sec) | 平均查询延迟 | 性能评价 | 状态 | 快速入口 |
|---|---|---|---|---|---|---|---|
| 1 | Rust | Read-Only Mmap | 10.0 M+ ~ 18.0 M+ | < 0.08 µs | 🛡️ 极速安全 | ✅ 生产推荐 | 查看源码 |
| 2 | C / C++ | Read-Only Mmap | 10.0 M+ ~ 18.0 M+ | < 0.08 µs | 👑 极致轻量 | ✅ 生产推荐 | 查看源码 |
| 3 | Go | Read-Only Mmap | 8.0 M+ ~ 12.0 M+ | < 0.10 µs | ⚡ 高并发 | ✅ 生产推荐 | 查看源码 |
| 4 | C# | Eager-load Once | 6.0 M+ ~ 10.5 M+ | < 0.15 µs | 🚀 优秀 | ✅ 生产推荐 | 查看源码 |
| 5 | Java | Eager-load Once | 5.0 M+ ~ 8.0 M+ | < 0.20 µs | ☕ 稳健 | ✅ 生产推荐 | 查看源码 |
| 6 | Node.js | Eager-load Once | 3.0 M+ ~ 5.0 M+ | < 0.33 µs | 🔥 优异 | ✅ 生产推荐 | 查看源码 |
| 7 | PHP | Dynamic Parsed | 100 K+ ~ 2.0 M+ | < 0.90 µs | 🐘 实用 | ✅ 生产推荐 | 查看源码 |
| 8 | Python | Dynamic Parsed | 100 K+ ~ 2.2 M+ | < 0.90 µs | 🐍 标准 | ✅ 生产推荐 | 查看源码 |
(注：基准测试基于普通 x86_64 / ARM64 处理器单线程单核内存检索测试，不同 CPU 频率及物理内存带宽下测试数值可能有所浮动，仅供技术选型参考)
更完整的 API 文档与多语言用例，请参见 QZDB 多语言 SDK 指南。
// 🐹 Go 示例 (mmap 零拷贝, 实例持有用法)
searcher, err := qzdb.Open("qqzeng_ip_ult_china.qzdb", 0, true)
info := searcher.Find("114.114.114.114")
fmt.Println(info.Get("country"), info.Get("province"), info.Get("city"), info.Get("isp"))# 🐍 Python 示例 (按需实例化)
from qzdb import QzdbReader
searcher = QzdbReader("qqzeng_ip_ult_china.qzdb")
print(searcher.find_str("114.114.114.114")) # 亚洲|CN|中国|江苏|南京|中国电信// 🦀 Rust 示例 (零分配 Zero-Copy 检索)
use qzdb::{from_file, QzdbReader};
let searcher = from_file("qqzeng_ip_ult_china.qzdb");
if let Some(info) = searcher.find("114.114.114.114") {
println!("{} {} {}", info.country(), info.province(), info.city());
}QZDB 引擎核心采用专门定制的 双阶段 Patricia Trie 树型检索算法：
flowchart LR
A["输入目标 IP (如 114.114.114.114)"] --> B["阶段1: Jump Table 前缀跳级 (16-bit 静态表定位)"]
B --> C["阶段2: Patricia Trie LPM 匹配 (只读内存按位遍历)"]
C --> D["阶段3: String Pool 物理偏移 (O1 无锁读取)"]
D --> E["输出结果 (中国|江苏|南京|中国电信)"]
-
第一阶段 (Jump Table 快速跳级)：
-
IPv4：默认预读
16-bit的静态前缀跳转表（$2^{16} = 65,536$ 个槽位）。根据 IP 的前两字节，直接$\mathcal{O}(1)$ 跳转定位到 Trie 树的具体子树节点，消除前 16 层的递归遍历。 -
IPv6：根据数据量大小动态估算最佳跳转位数
v6_jump_bits（通常为16~20 bit），同样实现首阶段的快速降维。
-
IPv4：默认预读
-
第二阶段 (Trie 节点匹配 & 字符串池偏移读取)：
- 在定位到的子树节点中，以最长前缀匹配 (LPM) 算法沿单侧节点向右/向左遍历。所有中间路由指针和叶子节点数据在文件中扁平化连续存放，极具 CPU 缓存友好性。
- 查询命中后，SDK 会直接根据其物理偏移量（Offset）在预载入的只读字符串池（String Pool）中以
$\mathcal{O}(1)$ 解析最终文本，全程免去临界区上锁（Lock-free）。
| 维度指标 | 复杂度 | 技术细节与优势 |
|---|---|---|
| 检索时间复杂度 | 其中 |
|
| 空间复杂度 | 极小量级 | 经过前缀压路机压缩，每个 Trie 节点仅占用 6~8 字节，千万级全球 IP 树存储开销低于 20MB。 |
| 内存开销 (Memory) | 原生编译型语言（Rust/C/Go）直接借助操作系统 mmap 进行零拷贝（Zero-copy）寻址，无堆分配与 GC 停顿。 |
为了帮助架构师进行技术选型，以下列出了 QZDB 与业界主流二进制 IP 格式设计的客观对比（详细基准报告见 docs/benchmark-comparison.md）：
| 格式分类 | 检索时间复杂度 | 数据结构体积 | 核心检索树与数据机制 | QZDB 的技术优化点 |
|---|---|---|---|---|
通用嵌套结构树格式 (.mmdb) |
(需加上反序列化开销) |
较大 (含元数据 Key-Value 冗余) |
经典二进制 Trie；叶子指向嵌套 Map/List 数据区 | QZDB 首阶段快速跳级 + 零分配。IPv4 预读 16-bit 跳过前 16 层；叶子基于 Schema 物理偏移，堆内存零分配。 |
扁平区间二分格式 (.bin) |
(基于多轮二分匹配) |
中等 (需存储完整起止 IP 范围) |
已排序起止范围二分检索；辅以前缀索引缓存 | QZDB 的 Trie 压缩与短路径检索。Trie 树结构天生善于压缩重叠段，平均检索路径大幅缩短。 |
分区向量索引格式 (.xdb) |
(局部向量二分) |
极小 (一般只索引部分核心地理字段) |
向量索引表 + 局部 B-Tree 区间检索 | QZDB 对全球超大数据集扩展更佳。采用全局 RowSchema 与双阶段树设计，能自适应承载从小体积到数行大规模全球网段数据的动态扩展。 |
专有前缀树格式 (.ipdb) |
(多次树节点跳转) |
较小 (索引节点与偏移量较为紧凑) |
前缀节点位移 Trie 检索；索引与数据区分离 | QZDB 的多语种只读字符串池与完全免锁设计。多维字段在初始化后即建立只读内存视图，多线程并发检索无锁竞争。 |
| 目录/文件 | 说明 (Description) |
|---|---|
ip-qzdb-sdk/ |
⚡ QZDB 极速解析引擎——Rust / C / Go / Java / C# / Node.js / PHP / Python 八语言 SDK 全覆盖 |
ip-classic-sdk/ |
📦 IP 数据库经典版 SDK——v6.0 (.db) 与 v2.0 (.dat) 经典在用解析源码 |
phone-location-sdk/ |
📱 手机号段归属地 SDK——v2.0 至 v6.0 全版本多语言 DAT 解析 SDK 与 Redis 方案 |
database-sql/ |
🗄️ 数据库建表与入库脚本——MySQL / PostgreSQL / SQL Server DDL 与高速导入脚本 |
ip-history-sdk/ |
🗂️ IP 历史版本与工具归档——v3.0~v5.0 历史源码、Big DAT 与桌面离线查询工具 |
demo/ |
📋 演示样本——IP 归属地与号段 CSV / TXT / QZDB 数据样例 |
docs/ |
📄 项目文档与基准——架构设计、性能基准报告与维护指南 |
| 格式分类 | 主要内容 | 文件大小 (以国内/全球版为例) | 查询性能 | 适用场景 |
|---|---|---|---|---|
| QZDB 二进制 (.qzdb) | 包含 24-bit Trie 树索引、动态元数据与多语种压缩字符串池。 | 9.5 MB (国内版) / 160 MB (全球版) | 内存映射读取，微秒级响应 | 高并发 Web 服务、防火墙网关、DNS 调度。支持 mmap 零拷贝加载。 |
| CSV 文本 (.csv / .txt) | 标准 CIDR 掩码文本，每行按大洲/国家/省/市/区/经纬度扁平展开。 | 11 MB (国内版) / 204 MB (全球版) | 取决于底层数据库性能 | 离线数仓 ETL、报表分析。支持一键批量导入 MySQL, PostgreSQL, SQL Server。 |
依据项目官方权威规范（5 版本 × 2 区域 × 3 协议），本系列提供五个核心产品版本，各版本维度池及 CSV/QZDB 列字段定义如下：
| 版本 | 维度池数 | 核心定位 | 字段构成列表 (按规范排序顺序) |
|---|---|---|---|
std 标准版 |
6 | 基础地理 + 运营商 | continent, country_code, country, province, city, isp |
pro 专业版 |
11 | 细粒度地理定位 | std 字段 + district, geo_id, longitude, latitude, timezone |
asn ASN 路由版 |
8 | 网络专项（无细粒度地理） | continent, country_code, country, isp, asn, as_name, as_domain, usage_type |
max 旗舰版 |
15 | 地理 + 路由 + 风控应用 | pro 字段 + asn, as_name, as_domain, usage_type |
ult 至尊版 |
25 | 全维度 (地理/英文/风控等) | max 字段 + 10 个英文扩展项（continent_en, country_alpha3, country_en, province_en, city_en, district_en, languages, currency_code, phone_prefix, emoji_flag） |
字段设计说明：
- 规范物理排序：各版本在导出为 CSV 或构建 QZDB 时均遵循统一的「规范顺序」内插平铺（如英文扩展项
_en紧随对应中文项，ASN 与应用场景位放置于末尾）。- 应用场景分类
usage_type：使用英文字符串存储网络应用场景分类值（如Broadband、DataCenter、VPN、Cloud、Spider、Reserved等），SDK 直接读取字符串无需位运算解码。- 老客户无缝迁移说明：旧版旗舰版（Ultimate 历史在售版为 11 维，仅地理无 ASN）的数据结构与当前的全新的
pro专业版 (11 维) 完全一致，历史购入旗舰版的用户可直接无缝对应迁移至新版的pro专业版 ；全新版本的max旗舰版 则升级为 15 维（融入了网络 ASN 自治域与应用场景分类）。
QZDB 最新版支持动态字段拓扑（Schema），各版本通过标准的 CSV 扁平网段与 QZDB 二进制树提供一致的物理交付。典型多维字段定义如下：
| 字段类别 | 标准命名 | 数据格式示例 | 技术规范与参考标准 |
|---|---|---|---|
| 空间地理层 | 大洲 / 国家 / 省份 / 城市 / 区县 |
亚洲 / 中国 / 广东 / 深圳 / 南山 |
符合国家民政部 GB/T 2260 行政区划划分；国外细化至州/邦/郡/市级 |
| 英文与出境层 | 国家英文 / 国家二位代码 |
China / CN |
符合国际标准化组织 ISO 3166-1 Alpha-2 规范 |
| 网络服务层 | 运营商 |
电信 / 联通 / 移动 / 阿里云 / AWS |
支持全球主流 ISP 节点与各大主流云服务商 IDC 网段标记 |
| 位置投影层 | 经纬度 |
113.930478,22.53332 |
基于 WGS-84 坐标系，提供高精度十进制经纬度 |
| 时间与时区层 | 时区 |
Asia/Shanghai |
符合 IANA Time Zone Database (TZDB) 标准时区名称 |
| 行政属性层 | 区域代码 |
440305 |
中国六位标准行政代码（地方识别码与行政区划代码） |
- 国内运营商线路：支持按电信、联通、移动、教育网、鹏博士、广电网等智能解析，细分到省份。
- 海外地区线路：细分到大洲、国家。
- 自定义控制策略：基于 IPTables 的高级访问控制 (ACL)，设置 Allow from / Deny from 规则。
- 多维度网络接入：支持识别阿里云、腾讯云、华为云、亚马逊/Amazon、微软/Microsoft、谷歌/Google 等主流云服务商网段。
- 内容分发与 CDN 差异化：基于用户地理位置采用差异化内容分发策略，保障就近访问以提升用户访问体验。
- 精准定点投放：依赖高精度地理位置数据库实现区域化精准定点投放，提高触达率并优化运营成本。
- 智能网络流量调度：在高效流量调度、智能 DNS 服务、网络服务质量监测等环节起到基础支撑作用。
- 统计分析与行为决策：多维度分析区域流量数据，研判不同地域的用户访问行为，为制定网络策略提供决策依据。
- 多领域业务安全防护：广泛应用于地理位置识别、安全防护、网络管理、内容分发、电子商务等各领域企业。
50万+ 手机号段（前7位）：包含归属地省市区、邮编、区号、行政代码与运营商，提供极致压缩的
.dat二进制解析 SDK 与 Redis 缓存支持。详细源码请见phone-location-sdk/。
字段信息：广东|深圳|518000|0755|440300|中国移动
编码：UTF-8 字节序：Little-Endian
| 版本 | 文件格式 | 文件体积 | 压缩率 | 查询时间复杂度 | 核心技术特征 |
|---|---|---|---|---|---|
| 原始数据 |
.txt / .csv
|
~30 MB | — | — | 原始纯文本明文 |
| v6.0 (最新版) |
.dat / .db
|
1.28 MB | ▸ 95.7% | 超高并发微秒级响应，空间极致压缩 | |
| v5.0 | .dat |
1.60 MB | ▸ 94.6% | 扁平化数据块，高并发无锁检索 | |
| v4.0 | .dat |
1.80 MB | ▸ 94.0% | 区间二分索引结构 | |
| v3.0 | .dat |
1.95 MB | ▸ 93.5% | 基础二分查找，低内存占用 | |
| v2.0 | .dat |
2.40 MB | ▸ 92.0% | 早期经典二进制解析格式 |
qqzeng-ip 持续专注于高性能地理位置与号段解析引擎的打磨，以提供更准确、更精细、极低延迟的数据基础设施产品。
