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 八种主流语言支持。
| 排名 | 语言 | 查询模式 | 单线程吞吐量 (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 | 👑 极致轻量 | ✅ 生产推荐 | IoT、网关、内核模块、资源受限环境 |
| 3 | Go | Read-Only Mmap | 8.0 M+ ~ 12.0 M+ | < 0.10 µs | ⚡ 高并发 | ✅ 生产推荐 | Web 服务、API 网关、微服务 |
| 4 | C# | Eager-load Once | 6.0 M+ ~ 10.5 M+ | < 0.15 µs | 🚀 优秀 | ✅ 生产推荐 | .NET 企业应用 |
| 5 | Java | Eager-load Once | 5.0 M+ ~ 8.0 M+ | < 0.20 µs | ☕ 稳健 | ✅ 生产推荐 | Spring Boot / 大数据生态 |
| 6 | Node.js | Eager-load Once | 3.0 M+ ~ 5.0 M+ | < 0.33 µs | 🔥 优异 | ✅ 生产推荐 | 全栈 JavaScript 应用 |
| 7 | PHP | Dynamic Parsed | 100 K+ ~ 2.0 M+ | < 0.90 µs | 🐘 实用 | ✅ 生产推荐 | Web 项目快速集成 |
| 8 | Python | Dynamic Parsed | 100 K+ ~ 2.2 M+ | < 0.90 µs | 🐍 标准 | ✅ 生产推荐 | 数据分析、脚本、快速原型 |
(注：基准测试基于普通 x86_64 / ARM64 处理器单线程单核内存检索测试，不同 CPU 频率及物理内存带宽下测试数值可能有所浮动，仅供技术选型参考)
更完整的 API 文档与多语言用例，请参见 QZDB 多语言 SDK 指南。
// 🐹 Go 示例 (mmap 零拷贝, Goroutine 安全)
searcher, err := qzdb.NewSearcher("qqzeng_ip_max_china.qzdb")
region, err := searcher.Find("114.114.114.114")
fmt.Println(region.Country, region.Province, region.City, region.Isp) // 中国 江苏 南京 中国电信# 🐍 Python 示例 (单例模式开箱即用)
from qzdb import QzdbSearcher
searcher = QzdbSearcher.get_instance("qqzeng_ip_max_china.qzdb")
print(searcher.find_str("114.114.114.114")) # 亚洲|CN|中国|江苏|南京|中国电信// 🦀 Rust 示例 (零分配 Zero-Copy 检索)
let searcher = QzdbSearcher::new("qqzeng_ip_max_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 格式设计的客观对比：
| 格式分类 | 检索时间复杂度 | 数据结构体积 | 核心检索树与数据机制 | 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) |
|---|---|
qzdb/ |
⚡ QZDB 极速解析引擎——C / Go / Java / Rust / C# / Node.js / PHP / Python 八语言 SDK 全覆盖 |
qqzeng-phone-6.0/ |
📱 号段归属地 v6.0——TXT 压缩 95%→DAT，全平台多语言查询 |
qqzeng-phone-redis/ |
📱 号段 Redis 缓存——高并发 Redis 导入脚本与查询接口 |
mysql/, mssql/, pgsql/ |
🗄️ 数据库入库——MySQL / SQL Server / PostgreSQL DDL 与 IP 数据批处理 |
demo/ |
📋 演示样本——IP 归属地与号段 CSV / TXT 数据一览 |
docs/ |
📄 项目文档——架构设计、接口说明与使用指南 |
qqzeng-ip-6.0/ , -2.0/ |
🗂️ IP 引擎演进——v2.0 至 v6.0 历史版本 |
qqzeng-phone-5.0/ ~ -2.0/ |
🗂️ 号段引擎演进——v2.0 至 v5.0 历史版本 |
archive/ |
🗂️ 设计归档——历史设计稿、资料与附件 |
| 格式分类 | 主要内容 | 文件大小 (以国内/全球版为例) | 查询性能 | 适用场景 |
|---|---|---|---|---|
| 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 服务、网络服务质量监测等环节起到基础支撑作用。
- 统计分析与行为决策：多维度分析区域流量数据，研判不同地域的用户访问行为，为制定网络策略提供决策依据。
- 多领域业务安全防护：广泛应用于地理位置识别、安全防护、网络管理、内容分发、电子商务等各领域企业。
算法机制与性能基准测试：QZDB 引擎采用双阶段 Patricia Trie 树 + 物理偏移只读字符串池设计，在压测环境下实现单机微秒级响应与零 GC 停顿。
| 解析引擎版本 | 数据索引结构 | 时间复杂度 | 相对检索效率 | 内存占用 | 核心技术特征 |
|---|---|---|---|---|---|
| qqzeng-ip 2.0 | 早期二进制索引 | 1.0x (基线) | ~25 MB | 二分查找，线性读取 | |
| qqzeng-ip 3.0 | 优化型二分树 | ~1.6x 提升 | ~18 MB | 局部索引缓存，结构压缩 | |
| QZDB (当前最新版) | 双阶段 Patricia Trie 树 | ~3.2x 极致提升 | < 10 MB | 16-bit 静态跳转表 + mmap 零拷贝 + 无锁并发 |
(注：全量边界核验经由全自动验证流水线校验，涵盖全部 959,162 个 CIDR 掩码段与 2,877,486 次无抽样精准测试，验证通过率 100.00%)
qqzeng-phone-6.0.dat 6.0版本
字段信息：
广东|深圳|518000|0755|440300|移动
编码：UTF8 字节序：Little-Endian
| 版本 | 格式 | 体积 | 压缩率 |
|---|---|---|---|
| 原始数据 | TXT | 30 MB | - |
| v6.0 | DAT | 1.28 MB | ▸ 95.7% |
| v3.0 | DAT | 1.95 MB | ▸ 93.5% |
| v2.0 | DAT | 2.40 MB | ▸ 92.0% |
- 解析响应：单机微秒级极速响应，适配高并发高吞吐网关与服务架构
- 资源占用：内存消耗 < 10MB，超低开销
-
架构优势：二进制 DAT 格式结合前缀节点跳转，实现接近
$\mathcal{O}(1)$ 的平滑查询复杂度
| 版本 | 文件格式 | 查询时间复杂度 | 性能与技术特征 |
|---|---|---|---|
| v6.0 (最新版) |
.db / .dat
|
超高并发微秒级响应，空间压缩率 95.7%+ | |
| v5.0 | .dat |
扁平化数据块，高并发无锁检索 | |
| v4.0 | .dat |
区间二分索引结构 | |
| v3.0 | .dat |
基础二分查找，低内存占用 | |
| v2.0 | .dat |
早期经典二进制解析格式 |
注：随着号段结构和树形节点跳转的优化，高版本号段库在单机环境下的查询耗时近乎恒定。
统计 https://www.qqzeng.com/tongji.html
qqzeng-ip 我们持续更新和完善数据库，以提供更加准确和精细，高性能的产品。
