一、教程说明纯真IP库已全面升级为CZDB 加密格式淘汰老旧 qqwry.dat支持 IPv4/IPv6 离线、本地、内网无网络查询。本文为零基础通用教程包含下载、授权、环境搭建、单IP查询、批量IP解析、常见报错、商用合规说明。适用人群学生、新手开发者、本地数据分析、内网离线项目学习。二、重要合规规则必看纯真社区免费版仅允许个人学习、本地测试、内网离线使用禁止用于小程序、网站、后台服务、对外接口、商用项目商用必须购买官方商业授权版否则侵权免费版使用必须标注来源数据来源纯真IP库 cz88.net三、下载纯真CZDB IP库官方唯一渠道1. 进入官网官网地址纯真网络中国历史最悠久的IP地理位置库注册并登录手机号账号未登录无法下载。2. 进入社区版离线库顶部菜单离线库 → 纯真社区版IP库免费地址https://www.cz88.net/geo-public3. 完成免费授权审核二选一即可快速通过方式1个人页面标注「纯真IP库来源」并截图提交方式2发布一篇简单使用教程博文截图提交审核一般几分钟通过。4. 下载文件 保存密钥审核通过后页面出现下载cz88_public_v4.czdbIPv4库最常用复制页面专属解密密钥非常重要丢了无法解析数据库建议单独新建文件夹存放czdb文件 密钥 代码。四、环境准备Python最简支持 Windows / Mac / Linux / 内网离线环境。安装依赖pip install msgpack pycryptodome下载官方 Python SDKgit clone https://github.com/tagphi/czdb_searcher_python五、核心两种查询模式必须弄懂BTREE推荐本地/内网按需读取磁盘内存占用小适合个人工具、离线批量解析MEMORY服务端用全库载入内存速度极快适合高并发后端服务六、单IP离线查询完整可运行代码把 czdb 文件和代码放在同一文件夹填入自己密钥即可直接运行。from czdb.db_searcher import DbSearcher # 请替换为你自己的信息 DB_PATH cz88_public_v4.czdb KEY 你的纯真官网密钥 MODE BTREE # # 初始化查询器 searcher DbSearcher(DB_PATH, MODE, KEY) # 测试IP ip 114.114.114.114 res searcher.search(ip) print(IP地址, ip) print(归属地, res) searcher.close()输出示例中国–江苏–南京 电信七、进阶批量IP查询并导出CSV超实用适合批量分析日志、统计访问地区纯离线运行。from czdb.db_searcher import DbSearcher import csv DB_PATH cz88_public_v4.czdb KEY 你的密钥 MODE BTREE # 待查询IP列表 ip_list [ 114.114.114.114, 8.8.8.8, 223.5.5.5 ] searcher DbSearcher(DB_PATH, MODE, KEY) result_list [] for ip in ip_list: addr searcher.search(ip) or 未知地区 result_list.append([ip, addr]) print(ip, , addr) # 导出CSV with open(IP查询结果.csv, w, newline, encodingutf-8-sig) as f: writer csv.writer(f) writer.writerow([IP地址,归属地]) writer.writerows(result_list) searcher.close() print(批量查询完成已导出 CSV)八、内网离线部署方案无外网可用外网机器下载czdb文件、密钥、Python SDK、依赖包整体拷贝到内网电脑/服务器内网离线安装依赖代码读取本地 czdb 文件全程断网可用九、常见报错解决1. Padding 解密错误密钥复制不全、空格、czdb文件损坏 → 重新下载库 重新复制密钥2. 文件找不到路径中文/空格错误 → 改用绝对路径、纯英文目录3. 返回 None / 未知内网IP、保留IP、IPv6未匹配、IP带端口 → 过滤干净纯IP再查询4. 内存占用高本地测试不要用 MEMORY统一使用 BTREE 模式十、数据返回格式说明固定格式国家–省份–城市–区县 运营商国内IP精准到城市运营商海外IP仅国家运营商局域网/内网IP返回 未知十一、学习与项目使用建议学习、练手、数据分析、内网工具免费社区版完全够用小程序、线上项目、对外接口、商用必须购买纯真商业授权版线上项目严禁前端解析IP库、严禁前端保存密钥必须后端统一查询十二、新旧版本区别避坑旧版 qqwry.dat已停止官方维护无IPv6存在侵权风险不推荐新版 CZDB加密、更新稳定、支持双栈、官方正规、适合学习开发数据来源纯真 IP 库 cz88.net」