纯真IP库插件

172717180
预计阅读 14 分钟
简洁而强大的 WordPress IP归属地查询插件，支持子比主题，为网站提供准确的访客IP定位功能，依托纯真IP地理位置数据库（CZ88.net），结合众包数据与智能建模技术，保障IP定位的精准性与可靠性。

功能特性

核心功能

  • 双格式支持：支持纯真 CZDB 新格式和传统 QQWry.Dat 格式，适配不同数据源需求
  • IPv4 + IPv6：同时支持 IPv4 和 IPv6 地址查询，覆盖各类网络环境
  • 多级后备：查询优先级：主题API → 纯真IP库 → 在线API，确保查询成功率
  • 缓存优化：使用 WordPress Transients 缓存，自动过期，减少数据库查询，提升网站性能
  • 风险识别辅助：可结合纯真IP库的网络风险相关数据（如代理、VPN、爬虫识别），为IP查询提供更多维度参考（需配合商业版功能）

子比主题集成

  • 自动拦截主题的 IP 查询请求，无缝替换为纯真IP库查询结果
  • 评论自动显示 IP 归属地，提升网站互动透明度
  • 与主题风格无缝融合，无需额外调整样式

后台管理

  • 实时显示数据库状态（大小、更新时间），直观了解IP库情况
  • 一键更新 IP 库，同步纯真社区最新数据
  • 缓存管理（查看数量、一键清除），灵活控制缓存状态
  • 灵活的配置选项，适配不同网站需求
  • IP 查询测试工具，快速验证查询功能有效性

自动化

  • 插件激活自动设置每日定时更新任务，确保IP库数据时效性
  • 插件停用自动清理定时任务，避免占用服务器资源
  • 完整错误日志记录，便于排查问题

系统要求

  • WordPress 4.6+
  • PHP 5.6+（推荐 PHP 7.4+），确保插件正常运行
  • 子比主题（可选，用于深度集成，适配zibll主题的权限结构与显示风格）

安装

方法一：WordPress 后台上传

  1. 下载插件压缩包
  2. 进入 WordPress 后台 → 插件 → 安装插件 → 上传插件
  3. 上传并激活插件

方法二：手动安装

  1. 将插件文件夹上传到 `/wp-content/plugins/` 目录
  2. 在 WordPress 后台激活插件

方法三：FTP/SFTP 上传

# 将插件文件夹上传到服务器 scp -r qqwry-ip-plugin/ user@yourserver:/www/wwwroot/your-site/wp-content/plugins/

配置

1. 基本配置

进入 `设置 → 纯真IP`，配置以下选项：
选项
说明
API Key
纯真官网（https://www.cz88.net/）API Key，留空使用默认值，获取后可解锁更多精准数据
查询优先级
主题API优先 / 纯真IP库优先 / 仅使用纯真IP库，可根据网站需求选择
在线API后备
当本地查询失败时使用在线API，提升查询成功率
IP来源标记
在评论区显示查询数据来源，增强透明度

2. 获取 API Key（可选）

  1. 访问 纯真官网（中国IP地理位置数据库首创者，拥有数十年IP数据耕耘经验）
  2. 注册并登录账号
  3. 在用户中心获取 API Key
  4. 在插件设置中填入，即可使用更精准的IP数据及拓展功能

3. 手动更新IP库

插件支持多个下载源，可根据网络情况选择：
  • 纯真官网（需要API Key，数据最精准，同步最新众包修正数据）
  • GitHub（metowolf/qqwry，注：该网页目前解析失败，可作为后备源，若无法下载请切换其他源）
  • 国内镜像站（适配国内服务器，下载速度更快）

使用方法

全局函数

// 查询IP归属地 $location = qqwry_get_ip_location(‘114.114.114.114’); // 返回格式 array( ‘ip’ => ‘114.114.114.114’, ‘nation’ => ‘中国’, ‘province’ => ‘江苏省’, ‘city’ => ‘南京市’, ‘district’ => ”, ‘isp’ => ‘腾讯云’, ‘sdk’ => ‘czdb’ // czdb / theme / online );

过滤器

// 自定义IP查询结果 add_filter(‘zib_get_geographical_position_by_ip_custom’, function($result, $ip) { // 自定义处理逻辑 return $result; }, 10, 2);

评论IP归属地

插件会自动处理评论的IP归属地查询，无需额外配置，激活后即可在评论区显示访客IP归属地信息。

文件结构

qqwry-ip-plugin/ ├── qqwry-ip-plugin.php # 主插件文件 ├── src/ # CZDB 解析库源码 │ ├── DbSearcher.php │ ├── Entity/ │ │ ├── DataBlock.php │ │ ├── DecryptedBlock.php │ │ ├── HeaderBlock.php │ │ ├── HyperHeaderBlock.php │ │ └── IndexBlock.php │ └── Utils/ │ ├── ByteUtil.php │ ├── Decryptor.php │ └── HyperHeaderDecoder.php ├── data/ # IP数据库存放目录 │ ├── cz88_public_v4.czdb # IPv4 数据库 │ ├── cz88_public_v6.czdb # IPv6 数据库 │ └── error.log # 错误日志 └── README.md # 本文件

数据库说明

CZDB 格式（推荐）

  • 新一代纯真社区版 IP 数据库，由数十万纯真社区用户贡献数据并反馈纠错
  • 文件名：`cz88_public_v4.czdb`（IPv4）、`cz88_public_v6.czdb`（IPv6）
  • 需要 API Key 解密，解锁完整精准数据
  • 数据更精准，支持更多字段，结合神经网络自动学习建模与大数据修正，适配IP位置迁移与用途变化

QQWry.Dat 格式（后备）

  • 传统纯真 IP 数据库格式，兼容性强
  • 文件名：`QQWry.Dat`
  • 无需解密，适配各类服务器环境
  • 作为 CZDB 格式的后备方案，确保查询功能不中断

缓存机制

插件使用 WordPress Transients API 缓存查询结果，减少重复查询，提升网站性能：
参数
值
缓存前缀
`qqwry_cache_`
过期时间
24 小时（`DAY_IN_SECONDS`）
最大条目
10000 条

手动清除缓存

在后台管理页面点击「清除IP缓存」按钮，即可手动清理所有缓存数据。

定时任务

插件激活后会自动创建每日定时任务，同步更新IP库数据：
// 任务钩子 add_action(‘qqwry_update_database_cron’, function() { // 更新IP库 });

注意事项

  • WordPress 自带的定时任务依赖网站访问流量触发，若网站访问量较低，可能导致任务执行延迟
  • 如需确保定时任务稳定执行，可安装 WP-Cron Control 插件，该插件可手动控制cron任务执行，避免并发执行问题，具体配置方法如下：
    • 安装并激活 WP-Cron Control 插件
    • 进入插件设置页面，启用插件并设置秘钥参数
    • 配置系统定时任务，调用命令示例： `php wp-cron-control.php http://你的网站域名 你的秘钥` 或 `wget -q “http://你的网站域名/wp-cron.php?doing_wp_cron&你的秘钥”`
    • 定时任务间隔建议设置为5-15分钟，确保任务及时执行

错误排查

无法查询IP

  1. 检查 IP 数据库是否已安装（查看 data 目录下是否有对应数据库文件）
  2. 查看 `data/error.log` 错误日志，获取具体错误信息
  3. 确认 PHP 权限（确保服务器可读写 data 目录）
  4. 尝试手动更新 IP 库，更换下载源后重试

更新IP库失败

  1. 检查服务器能否访问外网，确保可连接纯真官网、GitHub等下载源
  2. 确认 API Key 正确（从纯真官网用户中心获取，避免填写错误）
  3. 查看错误日志获取详细信息，定位问题原因
  4. 尝试使用其他下载源（如国内镜像站），避开解析失败的源（如metowolf/qqwry）

数据库文件损坏

  1. 删除 `data/` 目录下的所有数据库文件
  2. 点击后台「更新IP库」按钮，重新下载数据库文件

更新日志

v2.1 (2026-05-18)

  • ✅ 安全加固：CSRF 防护、动态 API Key，提升插件安全性
  • ✅ 性能优化：Transients 缓存替代 Option 缓存，减少数据库压力
  • ✅ 可靠性提升：完善错误日志、增加SSL验证、支持多下载源，提升稳定性
  • ✅ 新增功能：定时自动更新，同步纯真社区最新IP数据
  • ✅ 代码质量：规范常量定义、优化文件句柄管理，提升可维护性

v2.0

  • 初始版本，适配子比主题
  • 支持 CZDB 和 QQWry 两种IP数据库格式
  • 实现核心IP归属地查询功能及评论区显示

获取帮助

许可证

本插件采用 MIT 许可证，开源免费，可自由修改、分发。

致谢

  • 纯真社区 – 提供IP数据库支持，数十年耕耘打造精准全球IP地址数据库，依托众包采样与智能建模提升数据质量
  • metowolf/qqwry – 提供QQWry.dat数据源（注：当前网页解析失败，建议作为后备数据源）
  • 小武站（https://1z345.cn） – 提供插件相关教程与资源支持

相关阅读推荐

© 版权声明
本网站部分文件及内容来自互联网，版权归原作者所有。转载需授权，侵权必究。部分内容受《网络出版服务管理规定》保护，未经许可禁止商业使用。
THE END
知识分享
# WordPress 插件# 安装配置# IP 查询# 纯真 IP 库
喜欢就支持一下吧
点赞7180支持作者 分享
评论标题 共1条
头像
欢迎您留下宝贵的见解！
提交
头像

昵称

取消
昵称

请填写用户信息：

  • 昵称
  • 邮箱
表情
[aoman][baiyan][bishi][bizui][cahan][ciya][dabing][daku][deyi][doge][fadai][fanu][fendou][ganga][guzhang][haixiu][hanxiao][zuohengheng][zhuakuang][zhouma][zhemo][zhayanjian][zaijian][yun][youhengheng][yiwen][yinxian][xu][xieyanxiao][xiaoku][xiaojiujie][xia][wunai][wozuimei][weixiao][weiqu][tuosai][tu][touxiao][tiaopi][shui][se][saorao][qiudale][qinqin][qiaoda][piezui][penxue][nanguo][liulei][liuhan][lenghan][leiben][kun][kuaikule][ku][koubi][kelian][keai][jingya][jingxi][jingkong][jie][huaixiao][haqian][aini][OK][qiang][quantou][shengli][woshou][gouyin][baoquan][aixin][bangbangtang][xiaoyanger][xigua][hexie][pijiu][lanqiu][juhua][hecai][haobang][caidao][baojin][chi][dan][kulou][shuai][shouqiang][yangtuo][youling]
代码

请输入代码：

确认
图片
快捷回复
文章写得特别走心，逻辑清晰，收获满满。
内容干货十足，讲解通俗易懂，非常受用。
感谢作者用心整理，观点独到，值得细细品读。
写得很全面，细节到位，已经收藏慢慢学习。
见解很有深度，看完受益匪浅，强力推荐。
排版整洁内容优质，难得的好文章，支持一下。
刚好看到这篇文章，解决了我不少疑惑。
文笔流畅条理分明，看得很舒服，点赞支持。
干货满满不废话，都是实用内容，感谢分享。
难得一见的优质好文，值得反复阅读琢磨。
观点客观理性分析，看完有很大启发。
内容详实有价值，感谢无私分享辛苦创作。
紧跟热点分析到位，看得很有共鸣。
整理得非常用心，知识点齐全，收藏备用。
优质原创好文，期待作者后续更多更新。
    只看作者
    • 小唐的头像-小武站小唐徽章-站长-小武站等级-LV9-小武站作者TA的网站0[ID:1]
      文章写得特别走心，逻辑清晰，收获满满。
      05/18 17:58福建省西天尾回复