AI 蜘蛛屏蔽（aiBotBlock）使用文档

作者：kuakeba.cn | 版本：1.0.0 | 适用于 Zsens Admin 3.0+（PHP 8.2+）

一、插件简介

随着各家的 AI 训练与检索蜘蛛大量抓取，站点上来自 GPTBot、ClaudeBot、Bytespider 这类 UA 的请求越来越多。AI 蜘蛛本身是为了让 AI 更好地回答用户的问题，却持续消耗带宽、CPU 与数据库资源，在配置不高的服务器上表现尤其明显。

本插件按 User-Agent 做子串匹配（忽略大小写），在请求最开始（模板渲染之前）完成判定，命中拦截列表直接返回：

• 不进入主题模板渲染流程
• 不查询业务数据库（拦截判定只读取 runtime 编译配置文件）
• 对正常访客与搜索引擎收录几乎没有影响

二、主要功能

1. 内置 31 条 UA 拦截关键词：GPTBot、ChatGPT-User、OAI-SearchBot、Google-Extended、Google-CloudVertexBot、ClaudeBot、Claude-Web、Claude-SearchBot、anthropic-ai、cohere-ai、MistralAI-User、Bytespider、PetalBot、Applebot-Extended、CCBot、Meta-ExternalAgent、Meta-ExternalFetcher、PerplexityBot、Perplexity-User、YouBot、Amazonbot、Diffbot、DataForSeoBot、ImagesiftBot、AI2Bot、Timpibot、Webzio-Extended、omgilibot、FacebookBot、facebookexternalhit、img2dataset。列表可在后台增删
2. 白名单独立维护：内置 Googlebot、Bingbot、Baiduspider、YisouSpider、Sogou web spider、Sogou Orion spider、360Spider、DuckDuckBot、YandexBot。白名单在拦截列表之前判断，命中直接放行；两个列表均可在后台增删
3. 响应状态码与内容为两项独立设置：状态码 403 或 200；内容为内置拦截页（内容固定）/ 空白页 / 自定义模板
4. 自定义模板变量替换：{code} 状态码、{status} 状态短语、{site} 站点地址、{url} 请求网址、{ip} 访客 IP、{ua} 浏览器标识、{time} 当前时间
5. 可拦截空 User-Agent 请求（默认关闭）
6. 拦截日志：记录时间、IP、命中的关键词、请求网址、完整 User-Agent；分页浏览（每页 50/100/200/500 可选）；后台显示今日与累计条数；可一键清空
7. 预览效果：一键以当前配置输出真实响应，直观查看状态码与内容
8. 后台单页双标签：拦截设置 / 拦截日志，顶部显示当前配置的条目统计
9. 卸载清理选项：卸载时可选择一并删除拦截日志表
10. 零外部依赖：全部本地资源，无外站引用、无第三方库

三、安装步骤

1. 将 aiBotBlock 目录放入 plugins/ 下
2. 进入后台 应用中心，找到「AI 蜘蛛屏蔽」，点击 安装（自动创建拦截日志表，并重建插件启动缓存使中间件生效）
3. 后台左侧菜单「AI蜘蛛屏蔽」进入设置页

若通过复制文件方式更新插件（而非应用中心升级），请执行一次 php think plugin:boot 重建启动缓存，否则中间件清单不会刷新。

四、配置说明（后台 → AI蜘蛛屏蔽 → 拦截设置）

保存设置后立即生效（配置会编译到 runtime 文件，拦截请求不查数据库）。

五、工作原理

1. 插件通过 plugins/aiBotBlock/middleware.php 声明拦截中间件，系统编译到 runtime/plugin_boot.php 并在 app/middleware.php 中前置合并到全局中间件队列最前（早于 Session 初始化、站点开关、页面缓存等核心中间件）
2. 每个请求最先经过拦截中间件：读取 runtime 编译配置（文件包含，无数据库查询）
3. 判定顺序：后台/安装/验证码路径放行 → 空 UA 判定 → 白名单放行 → 拦截关键词命中
4. 命中即记录日志（一次 insert）并直接返回设定状态码与内容；请求不会到达路由、控制器与模板渲染
5. 未命中照常执行后续流程，正常访客与搜索引擎（白名单）零影响

六、拦截日志页说明

后台「AI蜘蛛屏蔽」第二标签页 拦截日志：

• 顶部显示 今日拦截 与 累计拦截 条数（与设置页顶部统计卡片一致）
• 日志列：时间 / IP / 命中关键词（红色标记）/ 请求网址 / 完整 User-Agent
• 每页条数 50 / 100 / 200 / 500 按钮切换，按时间倒序分页浏览
• 一键清空：删除全部日志（二次确认，不可恢复）
• 日志记录的是实际命中的关键词快照，之后修改关键词列表不影响旧日志

七、适用范围与限制

本插件的判定依据是请求的 User-Agent 字符串。User-Agent 由客户端自行发送，可以被伪造或省略，因此本插件无法拦截伪造 UA 的请求，也不能替代服务器层（Nginx / 防火墙 / CDN）的访问控制。如需更强硬的封禁，建议在 Nginx 层配合 $httpuseragent 规则或 CDN WAF 使用。

八、常见问题

Q：如何验证插件生效？

命令行执行 curl -A "GPTBot" -i http://你的域名/，返回设定状态码与拦截页即生效；再执行 curl -A "Googlebot" -i http://你的域名/ 应正常放行。

Q：拦截后蜘蛛还会再来吗？

多数蜘蛛识别到 403/无内容后会降低抓取频率；Bytespider 类蜘蛛可能持续尝试，日志中可观察其频率。

Q：白名单和拦截关键词同时命中怎么办？

白名单优先，直接放行。例如某 UA 同时包含 ClaudeBot 与 Googlebot，会放行。

Q：如何临时停用？

拦截设置中将「启用拦截」选为停用并保存；配置与日志均保留。

Q：卸载会删除什么？

默认仅卸载插件并保留拦截日志表；若开启「卸载时清除数据」，将一并删除拦截日志表。