CZDB格式解析与应用：离线IP归属地查询的工程实践

做日志分析或者业务风控的时候，IP归属地查询基本是绕不开的一步。我最早接触纯真社区版IP库的时候，文件还是老牌dat格式，后来它升级成了带SQLite数据库底层的CZDB格式，查询方式也随之变化。很多朋友下载了CZDB文件之后，发现没有现成的解析程序，又不愿意每次去调在线接口，于是问题集中在两个地方：CZDB到底怎么解析，使用文档和下载地址又该从哪里找。这篇文章把我实际用过的解析思路、核心代码和踩坑记录一起整理出来，适合做日志分析、广告归因、业务风控这类需要离线IP归属地查询的开发者参考，也希望让刚接触IP库的新手少走点弯路。

1. 纯真社区版IP库与CZDB格式是怎么回事

1.1 从dat到CZDB，为什么会有这次升级

老用户应该都知道，纯真IP库过去主要是dat文件。dat格式本质上是一种自定义的二进制结构，头部有偏移表，后面跟着记录区，每条记录里又分国家/地区、省份、城市好几个字符串段。它最大的问题是：结构不透明，解析代码基本要靠逆向；字段边界模糊，很多解析器要自己处理字符串截断；而且它主要面向IPv4，IPv6时代就显得力不从心。

CZDB可以理解成新一代的存储方案。虽然从开发者的使用习惯来说，它变成了一个SQLite数据库文件，但核心目标没有变：离线、快速、精确地查询IP归属地。换成SQLite之后，表结构一目了然，字段名也规范了，不用再通过魔数去猜偏移量。而且SQLite是标准文件格式，Python、Java、Go这些语言都有官方或成熟的驱动，解析门槛一下就降下来了。

这里要强调一个容易被忽略的细节：CZDB虽然是SQLite文件，但它不是拿来就直接做SQL查询就能得到归属地结果的。因为IP数据是按“区间段”存储的，一个区间对应一条归属地记录。你输入一个IP，实际上是去查“这个IP落在哪一个预定义的区间里”。如果没有按这个思路去解析，拿到文件仍然是一头雾水。

1.2 解析程序到底解的是什么

弄明白数据组织方式之后，“解析程序”要做的事就清楚了：读取CZDB文件，把用户输入的IP地址转成整数，然后在存储的区间列表里找到覆盖这个整数的区间，最后返回区间里记录的归属地信息。

这个逻辑听起来简单，但实际写起来有几个容易出问题的地方。最核心的是IP地址与整数之间的转换。IPv4是32位整数，IPv4地址本质上就是这32位每隔8位用点号分隔后的十进制写法。IPv6则是128位整数，转换时需要考虑冒号分段和压缩写法。另一个核心点是区间匹配，数据表中每一行都有起始IP和结束IP，如果查询的IP落在某个区间内，才算是命中。

搞清楚了这两点，剩下的实现就顺理成章了。接下来我先把CZDB的底层结构讲透，再给出一套可以直接照着写的解析代码。

2. 动手前先搞清楚CZDB的底层结构

2.1 SQLite封装：先看清表结构再写代码

CZDB用SQLite封装之后，好处是可以直接用任意SQLite工具打开查看。我在第一次拿到文件时习惯做两件事：看元信息，看表结构。

查看表结构的SQL很简单：

SELECT name, sql FROM sqlite_master WHERE type='table';

查看元信息的SQL可以这样写：

SELECT * FROM meta;

不同版本的CZDB，表名和字段名可能不完全一样，我在这里说一套常见结构，具体以你下载的版本和官方文档为准。通常会有这样几张表：

• meta：保存数据库版本、数据更新时间、校验信息等。
• ipv4_range：存放IPv4区间数据，字段一般包括起始整数、结束整数、国家、省份、城市、运营商等。
• ipv6_range：存放IPv6区间数据，字段结构和IPv4表类似。

字段的命名可能是start/end，也可能是start_ip/end_ip。无论叫什么名字，含义都是一样的：这条记录覆盖的是从start到end这个闭区间内的所有IP地址。

这里想提醒一句：写解析程序前，一定要先跑一遍表结构查询，然后根据实际字段名来写SQL。不要迷信网上任何一篇教程里的固定字段名，包括我文章里写的这些。我之前有一次把旧版dat的解析代码迁到CZDB上，只改了一个表路径，结果怎么查都是空，后来才发现新版本的字段名悄悄加了后缀。排错排了半天，最后看sqlite_master才找出根本原因。

2.2 IP区间匹配的数学模型

要正确查询IP归属地，得先把IP地址变成整数。

IPv4转整数的公式是：

ip_int = 第一段 * 2^24 + 第二段 * 2^16 + 第三段 * 2^8 + 第四段

举个常见的例子，192.168.1.1转成整数就是192*16777216 + 168*65536 + 1*256 + 1 = 3232235777。网络通信本身也是用这个整数形式处理地址的，所以这个转换在语义上完全对得上。

IPv6转换就会复杂一些，因为它是128位整数。好在Python标准库里的ipaddress模块已经把这个转换封装好了，不需要手写解析冒号分段逻辑。

有了整数形式的IP之后，区间匹配就是一个经典的“排序区间查找”问题。如果把所有区间按起始IP排好序，那么给定一个整数IP，只需要查找最后一个起始IP小于等于它的区间，再检查这个区间的结束IP是否大于等于目标IP。如果满足，就说明目标IP落在这个区间里。

这个查找逻辑用二分法实现非常高效。二分查找就像在电话簿里找某个姓氏：先翻到中间一页，看看目标姓氏在前半本还是后半本，每次都把搜索范围缩小一半。几十万条IP区间记录，最多十几次比较就能定位到目标。

3. 从零写一个CZDB解析程序

3.1 下载、校验和准备工作

在写代码之前，先把CZDB文件准备好。下载地址我有意放在文章后半部分详细说，这里只强调一个原则：尽量从官方渠道或可信镜像获取，下载后第一时间记录文件的SHA256哈希值。因为IP库数据如果被篡改，查询结果可能是错到离谱的，比如把某地IP全部归到另一个地区，业务上很容易出问题。

拿到文件之后，准备一个Python环境。Python 3.8以上版本就足够，不需要额外安装第三方库，sqlite3和ipaddress都是标准库，直接就能用。这一点是我推荐Python写这类工具的原因，依赖少，部署简单。

打开数据库连接的时候，有一步容易被忽略：设置超时和多线程访问选项。如果解析程序会被放到Web服务里并发调用，连接池和只读模式最好提前安排好。我的习惯是用sqlite3.connect(file_path)建立连接之后，立刻执行PRAGMA query_only = ON;，防止误操作写入数据。

3.2 核心查询逻辑实现

下面的代码是我常用的一个简化版实现。为了方便阅读，IP区间表先不写死字段名，而是用动态方式读取列名，这样不同版本的CZDB也能跑起来。

import sqlite3 import ipaddress from dataclasses import dataclass @dataclass class IPRecord: country: str province: str city: str isp: str = "" class CZDBParser: def __init__(self, db_path: str): self.conn = sqlite3.connect(db_path) self.conn.execute("PRAGMA query_only = ON;") self.db_path = db_path self._detect_tables() def _detect_tables(self): rows = self.conn.execute( "SELECT name FROM sqlite_master WHERE type='table'" ).fetchall() table_names = [row[0] for row in rows] self.meta_table = "meta" if "meta" in table_names else None if "ipv4_range" in table_names: self.ipv4_table = "ipv4_range" elif "ipv4" in table_names: self.ipv4_table = "ipv4" else: raise RuntimeError("未找到IPv4表，请检查CZDB表结构") if "ipv6_range" in table_names: self.ipv6_table = "ipv6_range" elif "ipv6" in table_names: self.ipv6_table = "ipv6" else: self.ipv6_table = None def _query_one(self, table: str, ip_int: int): if table is None: return None rows = self.conn.execute( f"SELECT * FROM {table} WHERE start_ip <= ? AND end_ip >= ? LIMIT 1", (ip_int, ip_int), ).fetchall() if not rows: return None row = rows[0] columns = [d[0] for d in self.conn.execute(f"SELECT * FROM {table} LIMIT 0").description] data = dict(zip(columns, row)) return IPRecord( country=data.get("country", ""), province=data.get("province", ""), city=data.get("city", ""), isp=data.get("isp", ""), ) def lookup(self, ip_str: str): text = ip_str.strip() if ":" in text: ip_int = int(ipaddress.IPv6Address(text)) return self._query_one(self.ipv6_table, ip_int) ip_int = int(ipaddress.IPv4Address(text)) return self._query_one(self.ipv4_table, ip_int) if __name__ == "__main__": parser = CZDBParser("czdb.db") result = parser.lookup("8.8.8.8") print(result) if result: print("省份:", result.province, "城市:", result.city)

这里直接用SQL做区间匹配，代码很简洁，但要注意一点：WHERE start_ip <= ? AND end_ip >= ?这种写法，在表数据量很大且没有合适索引的情况下，会退化成全表扫描。如果是查询频率不高的内部工具，完全够用。如果需要高并发或者单次查询必须控制在毫秒级，我建议用下一小节里的优化方案。

3.3 批量查询与性能优化

我个人在实际项目里踩过性能坑。有一次需要把几百万条访问日志的IP全部转成归属地，如果用上面的SQL一条一条查，日志分析跑了大半天还没结束。后来我把方案改成了“加载到内存+内置二分查找”，效果立竿见影。

优化的核心思路很简单：启动时把整张表的start_ip、end_ip和归属地字段读进内存，按start_ip排序，然后自己实现一个二分查找，完全绕开SQLite的查询开销。

import bisect def load_ranges(conn, table): columns = [d[0] for d in conn.execute(f"SELECT * FROM {table} LIMIT 0").description] rows = conn.execute( f"SELECT start_ip, end_ip, country, province, city, isp FROM {table} ORDER BY start_ip" ).fetchall() return rows, columns def binary_lookup(ranges, ip_int): starts = [row[0] for row in ranges] pos = bisect.bisect_right(starts, ip_int) - 1 if pos < 0: return None row = ranges[pos] start_ip, end_ip = row[0], row[1] if start_ip <= ip_int <= end_ip: return row return None

这里的bisect_right找到的是最后一个start_ip小于等于目标IP的位置，然后再检查目标IP是否不超过end_ip。如果区间之间有缝隙，这个写法能正确返回没有命中；如果区间是紧密排列的，也能正常命中。

内存占用方面，几百万条(整数, 整数, 字符串, 字符串, 字符串, 字符串)记录，大概会有两三百MB内存占用，单机部署一般没什么问题。真正的大批量场景还可以再优化：按省分成多个小表，或者把常用IP段提前缓存到本地字典里。但基本原则是，能用二分就尽量不要全表扫，能用内存就不要频繁查数据库。

值得注意的一个取舍是：全内存加载适合读取频率高、启动时愿意付出加载时间的服务。如果查询本身很少，内存又是敏感资源，那用SQL里的索引方案更稳妥。在SQLite里对IP起始列建一个索引：

CREATE INDEX idx_ipv4_start ON ipv4_range(start_ip);

然后查询时SQLite就会优先根据start_ip定位到可能的区间，再把end_ip作为过滤条件，速度虽然不如内存二分，但远好于没有索引的全表扫描。

4. 使用文档与下载地址的获取策略

4.1 找官方下载地址的几个判断标准

标题里带“下载地址”三个字，说明这是很多人的实际痛点。但我不建议在文章里给一个固定的直链，因为纯真社区版IP库的更新频率很高，链接和文件版本经常变化，给直链反而容易误导人。

我的做法是去官方网站，找到社区版下载入口。判断入口是否官方的标准有三个：

1. 页面会明确标注数据更新时间和版本号。
2. 下载文件一般带有版本说明或者校验信息。
3. 页面结构通常是产品主页而不是个人网盘。

如果是从第三方博客或资源站转载的链接，下载后一定要做两件事：对比官方页面上公布的文件大小，以及用官方给的文件指纹做校验。缺少这两个信息的第三方源，即使能下载，也建议谨慎使用。毕竟IP归属地数据影响的是业务判断，出错带来的损失远不止几兆流量的成本。

还有一点经验：官方社区版通常是免费使用的，但文档里会写明使用范围、更新频率和一些限制条件。如果需要商用和更高频次更新，可以关注专业版渠道。社区版更新周期一般是每周一次，足够覆盖大多数开发调试和中小规模业务场景。

4.2 使用文档重点看哪些内容

下载CZDB的同时，官方通常会在线提供使用文档，或者随压缩包附带说明文件。打开文档之后，我最关注的永远是下面几块内容：

• 数据库表结构说明。重点看字段名，尤其是一张表里可能有多个版本子表的情况。
• 数据更新方式。是直接覆盖旧文件，还是需要手动合并增量。
• 查询示例代码。官方示例代码一般只展示最核心的调用，不会把性能优化细节写进去，但结构和字段名非常可靠。
• 版权和免责声明。这关系到你能把结果用在什么场景里，比如能不能放到对外API里。

曾经有一回，我没看文档就按旧版字段名写SQL，查出来的省份全部错位。后来认真读了文档才发现，新版把城市字段从city_name简化为city，而我用的旧解析器读的是city_name，于是整列数据直接落空。文档虽然读起来枯燥，但在这种场景下真的能救你一命。

4.3 把解析程序集成到现有业务系统里

有了解析程序和对应文档之后，集成到业务系统时要考虑的问题就不止“能查出来”这么简单了。

先做一个统一查询接口，输入IP字符串，输出结构化对象，而不是直接返回一个列表。结构化的好处是，后续不管是接HTTP服务、写日志分析，还是做实时风控，都能复用同一套代码。上面的IPRecord就是一种统一结构。

然后再加一层缓存。IP归属地的最大特点是相对稳定，同一个IP短时间内的查询结果基本不会变。可以在程序内部加一个简单的LRU缓存，容量控制在几万条。这样批量任务里遇到大量重复IP时，能省掉不少重复查询时间。

最后是数据版本管理。CZDB更新之后，不要急着覆盖线上文件。先把新文件下载到测试目录，跑一批已知IP做对比，确认变化符合预期再切换。IP库偶尔会调整行政区划，比如某个城市改名，或者运营商归属变化，这类调整需要业务侧同步适配。

5. 常见问题与排查技巧实录

5.1 打不开数据库文件

最直观的报错就是sqlite3.DatabaseError: file is not a database。这种情况绝大多数是下载文件损坏或者文件根本不完整。排查的时候先检查文件大小是否符合官方页面发布的大小，然后计算SHA256哈希和官方对比。

还有一种可能就是CZDB用的SQLite版本比Python自带的更新，但通常不会出现兼容不了的问题。如果这种错误出现在老旧设备上，可以先试着用其他SQLite工具打开一下，确认文件本身没问题，再把问题定位到程序侧。

5.2 查询结果为空或明显不对

如果查询公网IP返回空，先检查写法。最容易犯的错是拿字符串直接比较，比如WHERE start_ip <= '8.8.8.8' AND end_ip >= '8.8.8.8'。字符串比较是按字典顺序进行的，会出现8.8.8.8小于10.0.0.0这种反直觉结果。正确的做法永远是把IP转成整数再比较。

如果结果不对，比如原本属于甲省的IP查出来变成乙省，优先考虑是不是加载了旧版本库，或者数据文件版本不完整。还有一个常见原因是区间之间没有完全覆盖，某些新分配的公网IPv4段还没进入社区版库，这是正常现象，换最新更新版本即可。

另外要留意的是，CZDB里记录的是注册归属，有些大分段被分给其他地市的机房后，查询结果可能和你直觉上的“实际物理位置”不一致。这个不算bug，是IP库数据模型的边界。

5.3 IPv4与IPv6混用的坑

IPv6查询最大的坑是“IPv4映射地址”。比如::ffff:8.8.8.8这种写法，本质上是把IPv4地址包装成IPv6形式。如果直接拿它去查IPv6表，很可能查不到任何记录。正确的处理方式是先判断它是否为IPv4映射地址，如果是，就提取出后面的IPv4部分再查IPv4表。

import ipaddress raw = "::ffff:8.8.8.8" addr = ipaddress.ip_address(raw) if isinstance(addr, ipaddress.IPv6Address) and addr.ipv4_mapped: real_ip = addr.ipv4_mapped.exploded print("实际IPv4地址:", real_ip)

这个问题在日志场景里特别常见。很多网络设备记录日志时，会习惯把IPv4地址统一包装成IPv6格式，导致后续统计时IPv4归属全部失效。只要在解析入口做了上面这样一层归一化，就能把大多数脏数据拦下来。

IPv6本身也有压缩写法，比如2001:db8::1省略了中间的0段，直接交给ipaddress库处理就行，不建议自己写字符串正则去拆，容易漏掉边界情况。

5.4 查询慢、内存占用高的排查思路

先分清瓶颈在数据库还是业务代码。单条查询慢，多半是表上没索引。批量查询慢，多半是SQL往返次数太多。我处理批量场景的推荐顺序是：

1. 先看数据量。如果是百万级以下，直接把区间表加载进内存做二分。
2. 如果内存紧张，建索引然后保持SQL查询。
3. 如果查询请求有热点特征，在接口层加缓存。

内存占用高的另一个原因是字符串字段过多。把不需要的字段排除掉，只保留国家、省份、城市、运营商，能省不少空间。如果还想再省，可以把省份城市替换成短代码，查询后再映射成中文名称，不过这会增加一层维护成本，数据行数不大的时候没必要。

6. 过来人的几点小建议

文章写到这儿，核心的东西都讲完了。最后说几条我个人在实际项目里沉淀下来的小经验。

第一，解析公式一定要先跑通再上量。拿到CZDB之后，不要急着写完整工程，先打开数据库看表结构，再用一两个已知IP验证查询结果。我一般会拿本机公网IP和一个海外IP各测一次，确认IPv4和IPv6的查询路径都正常，再继续封装。

第二，分支场景一定要测。包括私网IP、保留地址、IPv4映射地址、压缩写法的IPv6地址。这些边界数据不处理好，上线之后很容易被线上日志里的脏数据打爆。

第三，程序要做到“库文件换一下就能跑”。把表名、字段名、文件路径都作为配置项，从元信息里动态读取，而不是硬编码在代码里。这样每次IP库更新时，只需要替换CZDB文件，解析程序基本不需要改动。

CZDB这个格式的出现，让IP归属地解析从“逆向二进制”的活变成了“标准SQLite查询”的活，门槛降低了不是一点半点。掌握好区间匹配和二分查找这两个核心点，再配合一套稳健的适配层，基本上所有离线IP查询场景都能覆盖。希望这篇总结能帮你少踩几个坑，把时间花在更有价值的业务实现上。