CzdbSearcher - .NET CZDB IP地理位置库

CzdbSearcher 是一个用于 CZDB（纯真）数据库的 .NET IP 地理位置查询库，支持内存和 B-Tree 两种查询算法，兼容 IPv4 和 IPv6。

安装

通过 NuGet 安装：

dotnet add package CzdbSearcher

或在 Visual Studio 的包管理器控制台中：

Install-Package CzdbSearcher

或直接在 .csproj 文件中添加：

<PackageReference Include="CzdbSearcher" Version="1.0.0" />

功能特点

• 支持 IPv4 和 IPv6 查询
• 多种查询算法：内存模式、B-Tree 模式
• 内存模式线程安全，适合高并发
• 高性能，查询速度快
• API 简单易用

数据库与密钥

数据库文件和解密密钥可在 www.cz88.net 获取。

快速开始

using CzdbSearcher;

// 创建查询实例
using var searcher = new DbSearcher("path/to/database.czdb", QueryType.Memory, "your-key");

// 查询 IP 地址
string result = searcher.Search("8.8.8.8");
Console.WriteLine(result); // 输出: 国家-省份-城市-区 运营商。⚠️： 商业版格式会不一样

使用示例

基本用法

using CzdbSearcher;
using CzdbSearcher.Exceptions;

try
{
    using var searcher = new DbSearcher("database.czdb", QueryType.Memory, "your-decryption-key");
    string region = searcher.Search("192.168.1.1");
    if (region != null)
    {
        Console.WriteLine($"IP位置: {region}");
    }
    else
    {
        Console.WriteLine("数据库中未找到该IP");
    }
}
catch (IpFormatException ex)
{
    Console.WriteLine($"IP格式错误: {ex.Message}");
}
catch (Exception ex)
{
    Console.WriteLine($"错误: {ex.Message}");
}

使用流方式加载数据库

using CzdbSearcher;

using var fileStream = File.OpenRead("database.czdb");
using var searcher = new DbSearcher(fileStream, QueryType.Memory, "your-key");
string result = searcher.Search("8.8.8.8");

IPv6 查询

using var searcher = new DbSearcher("ipv6-database.czdb", QueryType.Memory, "your-key");
string result = searcher.Search("2001:4860:4860::8888");
Console.WriteLine(result);

查询类型说明

• Memory（内存模式）：线程安全，性能高，适合高并发，内存占用较高。
• BTree（B-Tree模式）：内存占用低，非线程安全，适合资源有限场景。

线程安全说明

• 仅 Memory 模式线程安全。
• BTree 模式多线程需为每个线程创建独立实例。

资源管理

建议使用 using 语句自动释放资源：

using var searcher = new DbSearcher("database.czdb", QueryType.Memory, "key");

命令行测试

本库自带命令行测试程序：

# 交互模式
 dotnet run --project CzdbSearcher.ConsoleApp/CzdbSearcher.ConsoleApp.csproj -- -d database.czdb -t Memory -k your-key

# 基准测试模式
 dotnet run --project CzdbSearcher.ConsoleApp/CzdbSearcher.ConsoleApp.csproj -- -d database.czdb -t Memory -k your-key -b -i ip-ranges.txt

命令行参数说明

• -d, --dbFilePath：数据库文件路径（必填）
• -t, --queryType：查询类型（Memory 或 BTree，必填）
• -k, --key：解密密钥（必填）
• -b, --benchmark：启用基准测试
• -i, --ipFilePath：基准测试用IP段文件路径

基准测试文件格式

每行一个IP段，格式如下：

start_ip\tend_ip
192.168.1.1\t192.168.1.255
10.0.0.1\t10.0.0.255

性能建议

• 内存模式适合高QPS场景
• BTree模式适合内存受限环境
• 数据库越大，内存模式优势越明显
• 并发访问建议使用内存模式

错误处理

本库会抛出特定异常，便于定位问题：

try
{
    var result = searcher.Search("invalid-ip");
}
catch (IpFormatException ex)
{
    // 处理IP格式错误
}
catch (ArgumentException ex)
{
    // 处理IP与数据库类型不符
}
catch (Exception ex)
{
    // 处理其他错误（如文件不存在、解密失败等）
}

API 参考

DbSearcher 类

构造函数

DbSearcher(string dbFile, QueryType queryType, string key)
DbSearcher(Stream stream, QueryType queryType, string key) // 仅支持内存模式

属性

DbType DbType { get; }      // IPv4 或 IPv6
QueryType QueryType { get; } // Memory 或 BTree

方法

string Search(string ip)     // 查询IP位置
void Dispose()              // 释放资源
void Close()                // Dispose别名

枚举类型

public enum DbType
{
    IPv4,
    IPv6
}

public enum QueryType
{
    Memory,
    BTree
}

环境要求

• .NET Standard 2.0 及以上
• 支持 .NET Framework 4.6.1+、.NET Core 2.0+、.NET 5+
• 控制台测试程序需 .NET 6.0 或更高

注意： 核心库支持 .NET Standard 2.0，控制台测试程序需 .NET 6.0 及以上。

许可证

本项目基于 Apache License 2.0 开源，详见 LICENSE 文件。

贡献

欢迎提交 PR 或 Issue 参与贡献！

支持与反馈

如有问题请通过 GitHub Issues 反馈。

相关项目

• Java 版本
• C 版本
• PHP 版本
• Python 版本