qqzeng-ip — 高性能 IP 地理位置与网络画像数据库引擎

单文件整合全球 1,250 万+ IPv4/IPv6 双栈网段 · mmap 零拷贝纳秒级检索 · 8 大主流语言统一 API 规范与跨语言一致性验证。

🔗 快捷导航：在线查询体验 (25维画像) · 版本选型与字段对照 · 多格式性能评测 · 8语言性能白皮书 · SDK API 规范 · 商业授权与选购

目录

1. 核心架构亮点
2. 一分钟版本选型指南
3. QZDB 版本规格、文件大小与字段区别
4. 性能测试与多格式横向对比
5. 30 秒快速安装与集成
6. 多语言代码示例
7. 仓库目录结构导航
8. 质量门禁与跨语言一致性验证
9. 开源许可证与商业授权边界

一、核心架构亮点

qqzeng-ip 提供以新一代二进制格式 .qzdb 为核心的 IP 地理位置、运营商、自治域（ASN）与网络应用场景（IDC 机房 / 家宽 / 移动基站 / 云厂商）解析引擎，同时完整维护存量系统广泛使用的经典 6.0（.db）、2.0（.dat） 与 手机号段归属地 SDK。

二、一分钟版本选型指南

根据您的业务场景、网络协议要求与系统架构，按以下对照表直接锁定对应引擎与版本：

三、QZDB 版本规格、文件大小与字段区别

.qzdb 单文件同时涵盖 IPv4 与 IPv6 全量网段。五大版本的字段体系遵循严格的递增包含关系：

标准版 STD (6维)  ⊂  专业版 PRO (11维)  ⊂  旗舰版 MAX (15维)  ⊂  至尊版 ULT (25维)
└─ 自治域版 ASN (8维)：独立网络专项版 = 基础国家级地理 (4维) + 网络与风控 (4维)

1. 全球双栈版（IPv4 + IPv6 全量）文件大小对比

2. 国内精华双栈版（中国本土业务专用）文件大小对比

3. 五大版本字段区别一览表

四、性能测试与多格式横向对比

基准环境与口径声明：实测硬件为 Apple M4 Max（14 核，macOS），遵循 docs/PERFORMANCE.md 统一契约（splitmix64 固定种子、FNV-1a 指纹对账）。

• 口径 A（整型随机·保守承诺值）：50 万随机散布 IP 整型查询（省级 8.6MB 库；在 122MB 全球库上受 CPU L3 缓存物理规律影响，吞吐约为小库的 1/3）。
• 口径 B（热点 / 16 线程并发）：重复查询命中缓存或 16 线程无锁并发吞吐。
• 口径 C（字符串直查 find_str）：含 IP 字符串解析 + 走树 + UTF-8 结果拼装全链路（CI 门禁口径）。

1. 同源数据下六大二进制格式横向评测

将同源 IP 数据集分别编译为 .qzdb、经典 .db (6.0 / 3.0)、经典 .dat (2.0)、ip2region (.xdb) 与 MaxMind (.mmdb) 同机对比：

单核随机查询吞吐对比 (Apple M4 Max，单位：万次/秒)：
QZDB (.qzdb, Go/C)        ████████████████████████████████████████████████ 9,730 万/s (~10 ns)
QZDB (.qzdb, Java/C#)     ████████████████████████ 4,810 万/s (~21 ns)
qqzeng-ip 6.0 (.db)       ███████████████ 3,000 万/s (10.6 ns)
qqzeng-ip 3.0 (.db)       ████████ 1,555 万/s (17.5 ns)
qqzeng-ip 2.0 (.dat)      █████ 950 万/s (29.9 ns)
ip2region (.xdb Content)  ███▌ 690 万/s (45~70 ns)
MaxMind (.mmdb Memory)    ▊ 138 万/s (668 ns)
MaxMind (.mmdb mmap)      ▍ 71 万/s (1,410 ns)

📖 完整 BenchmarkDotNet 多轮实测报表（单次纳秒、百万次毫秒、亿级吞吐）见 docs/BENCHMARK_COMPARISON.md。

2. QZDB 8 大主流语言 SDK 性能榜单

# 口径 C：8 语言全量 CI 门禁基准（含 FNV-1a 指纹对账）
cd ip-qzdb-sdk && python3 tools/perf_gate.py

# 口径 A / B：各语言统一契约基准（支持 random / hot / seq 分布与多线程并发）
cd ip-qzdb-sdk && BENCH_OPS=2000000 ./c/bench_contract

五、30 秒快速安装与集成

全部主流语言均已发布官方稳定包，支持包管理器一行命令引入或单文件/单目录零依赖源码拷贝：

六、多语言代码示例

💡 生产环境提示：请在服务启动时创建一次 QzdbReader 实例并全局长期复用（内部全只读，天然支持多线程无锁并发查询）。仓库 demo/qqzeng-ip-ult.qzdb 提供了 25 维双栈演示样本库（360 行抽样），可直接运行以下示例（以库内真实存在的 118.115.99.0 与 2600:5800:2a8e:: 验证）。

Python

from qzdb import QzdbReader

with QzdbReader("demo/qqzeng-ip-ult.qzdb") as reader:
    # 1. 查询返回竖线分隔字符串
    print(reader.find_str("118.115.99.0"))
    # 输出: 亚洲|Asia|CN|CHN|中国|China|四川|Sichuan|成都|Chengdu|双流|Shuangliu|510116|103.923730|30.574440|Asia/Shanghai|zh-CN|CNY|86|🇨🇳|中国电信|4134|CHINANET BACKBONE|chinatelecom.com.cn|Broadband

    # 2. 查询返回强类型 GeoInfo 对象（同时支持 IPv4 与 IPv6）
    loc = reader.find("2600:5800:2a8e::")
    if loc is not None:
        print(loc.country_code, loc.province, loc.city, loc.isp, loc.get("usage_type"))
        # 输出: US 北卡罗来纳州 夏洛特 Charter Broadband

Go

package main

import (
    "fmt"
    "log"
    "github.com/zengzhan/qqzeng-ip/ip-qzdb-sdk/go/qzdb"
)

func main() {
    reader, err := qzdb.Open("demo/qqzeng-ip-ult.qzdb", 0, true)
    if err != nil {
        log.Fatal(err)
    }
    defer reader.Close()

    if info, err := reader.Find("118.115.99.0"); err == nil && info != nil {
        fmt.Println(info.Get("country"), info.Get("province"), info.Get("city"), info.Get("isp"))
        // 输出: 中国 四川 成都 中国电信
    }
}

Java

import com.qqzeng.qzdb.GeoInfo;
import com.qqzeng.qzdb.QzdbReader;
import java.io.File;

try (QzdbReader reader = new QzdbReader.Builder(new File("demo/qqzeng-ip-ult.qzdb")).build()) {
    reader.find("118.115.99.0").ifPresent(loc -> {
        System.out.printf("%s %s %s (%s)%n",
            loc.getCountry(), loc.getProvince(), loc.getCity(), loc.get("usage_type"));
        // 输出: 中国 四川 成都 (Broadband)
    });
}

Rust

use qzdb::QzdbReader;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let reader = QzdbReader::from_file("demo/qqzeng-ip-ult.qzdb")?;
    if let Some(loc) = reader.find("118.115.99.0") {
        println!("{} {} {} [ASN: {}]", loc.country(), loc.city(), loc.isp(), loc.get("asn"));
        // 输出: 中国 成都 中国电信 [ASN: 4134]
    }
    Ok(())
}

using QQZeng.Qzdb;

using var reader = QzdbReader.Open("demo/qqzeng-ip-ult.qzdb");
GeoInfo? loc = reader.Find("118.115.99.0");
if (loc != null)
{
    Console.WriteLine($"{loc.Country} {loc.Province} {loc.City} - {loc.Isp}");
    // 输出: 中国 四川 成都 - 中国电信
}

#include <stdio.h>
#include "qzdb_reader.h"

int main(void) {
    qzdb_reader_t reader;
    if (qzdb_init(&reader, "demo/qqzeng-ip-ult.qzdb") != QZDB_OK) {
        return 1;
    }
    char buf[QZDB_VALUE_BUF_SIZE];
    if (qzdb_find_str(&reader, "118.115.99.0", buf, sizeof(buf)) == QZDB_OK) {
        printf("%s\n", buf);
        // 输出: 亚洲|Asia|CN|CHN|中国|China|四川|Sichuan|成都|Chengdu|双流|Shuangliu|510116|103.923730|30.574440|Asia/Shanghai|zh-CN|CNY|86|🇨🇳|中国电信|4134|CHINANET BACKBONE|chinatelecom.com.cn|Broadband
    }
    qzdb_close(&reader);
    return 0;
}

const { Builder } = require('@qqzengip/qzdb');

const reader = new Builder('demo/qqzeng-ip-ult.qzdb').build();
try {
    const loc = reader.find('118.115.99.0');
    if (loc) {
        console.log(loc.get('country'), loc.get('city'), loc.get('isp'));
        // 输出: 中国 成都 中国电信
    }
} finally {
    reader.close();
}

<?php
require_once __DIR__ . '/vendor/autoload.php';
use Qqzeng\Ip\QzdbBuilder;

$reader = QzdbBuilder::path('demo/qqzeng-ip-ult.qzdb')->build();
$loc = $reader->find('118.115.99.0');
if ($loc !== null) {
    echo $loc->get('country') . ' ' . $loc->get('city') . ' ' . $loc->get('isp') . PHP_EOL;
    // 输出: 中国 成都 中国电信
}
$reader->close();

七、仓库目录结构导航

八、质量门禁与跨语言一致性验证

公开仓库 CI 执行自动化门禁校验（CI 门禁与本地一键复现命令严格对应）：

• 编译与内存安全验证：
  • C SDK：使用 -std=c11 -Wall -Wextra -Werror 严格编译链接，并在 AddressSanitizer (ASan) 与 UndefinedBehaviorSanitizer (UBSan) 下对公开 demo 库执行全量查询（0 内存泄漏、0 未定义行为）。
  • 其余语言 SDK：Rust (cargo check + cargo package)、Java (release 17 / JDK 21 编译)、C# (.NET 10 Release 构建)、Go (go build / go vet)、Node.js (node --check)、Python (py_compile)、PHP (php -l + composer validate + 7.4~8.5 跨版本类加载) 均执行编译或语法合法性门禁。
• 27 组基准向量校验：基于公开 golden_vectors.json（期望值源自 demo CSV 独立数据源，覆盖 IPv4/IPv6、全部 12 类 usage_type 及负向边界），对 Python 参考实现执行字段级精准校验。
• 样本逐字节对拍（跨语言一致性）：基于公开 demo/qqzeng-ip-ult.qzdb（360 行真实网段），提取全部起始/结束 IP 及 14 类边界异常值（共 374 条），以 Python SDK 为基准，验证 C、Node.js、Go、PHP 与参考实现输出逐字节完全一致（无效输入在 C 的错误码与 Python 的空串之间由脚本显式归一化；Rust/Java/.NET 当前仅纳入编译门禁）。
• 单一事实来源与反假绿防护：全仓 Markdown 相对链接零断链检查、安装清单版本号一致性校验、25 维全要素 Schema 与 CSV 表头对齐校验，以及对拍脚本 --require 缺失工具链拦截自测。

检查项与 CI 步骤对照表

ℹ️ 内部开发仓发版说明：在包含千万级网段的完整商业库上，内部流水线会执行 L3 黄金向量（4,102 条全量对账）与跨版本 L4 性能基准门禁。跨语言向量验证用于保证解析算法在不同语言实现之间的一致性（Consistency），数据本身的物理准确性由采集团队定期核验。

九、开源许可证与商业授权边界

• 开源协议（SDK 代码）：本仓库包含的全部 8 语言 SDK 源码、构建测试脚本与示例代码均遵循 MIT License 开源，允许任何个人与企业免费引入、二次分发与商业化集成。
• 商业授权（数据产品）：生产环境所需的千万级网段全量数据库文件（.qzdb / .db / .dat / .csv）为独立知识产权商业数据产品，不随开源仓库分发（仓库仅内置 360 行抽样 demo 供工程验证）。商业数据由 qqzeng.com 官方按月持续发版维护并按实体授权，不限服务器数量、不限部署节点数、不限调用频次。授权模式与选型详见 官方服务中心。