# AI-Crawler-Blocklist
AI-Crawler-Blocklist 发布来自官方运营者发布源的 AI 爬虫黑名单及可直接部署的防火墙代码片段。它将经过验证的 IP 范围、user-agent 规则、robots.txt 控制和观察列表区分开来，以便站点运营者能够选择合适的限制级别，而不会混淆信号质量。
## 链接
| 资源 | URL |
| --- | --- |
| 生成的构建产物 | [`dist/`](./dist) |
| 源策略 | [`docs/source-policy.md`](./docs/source-policy.md) |
| 防火墙部署说明 | [`docs/firewalls.md`](./docs/firewalls.md) |
| 运行模式 | [`docs/modes.md`](./docs/modes.md) |
| 源健康报告 | [`dist/sources-report.md`](./dist/sources-report.md) |
| 机器可读元数据 | [`dist/metadata.json`](./dist/metadata.json) |
## 概述
AI-Crawler-Blocklist 专为出版商、应用运营者、基础设施团队和安全工程师设计，他们需要针对 AI 训练爬虫、AI 搜索机器人、助手抓取器及相关索引系统实施可重复的控制策略。
该仓库使用来自 `config/sources.json` 的精选源定义，验证源策略，在可用时获取官方 IP 订阅源，规范化 CIDR，并在 `dist/` 目录下输出特定平台的配置。源失败信息会被记录在元数据中，而不是导致整个构建失败，这确保了计划内的更新任务能够持续运行，同时保留了源健康状况的可见性。
## 系统行为
```
config/sources.json
|
v
scripts/normalize_sources.py -> confidence, enforcement, source policy
|
v
scripts/fetch_sources.py -> official JSON/text/embedded JSON/static prefixes
|
v
scripts/build.py -> deterministic dist artifacts
|
v
dist/metadata.json + firewall snippets + robots.txt + plain lists
```
限制级别取决于源质量：
| 类别 | 源质量 | 输出行为 |
| --- | --- | --- |
| `verified-drop` | 官方特定爬虫的 IP/CIDR 订阅源 | 适用于 IP 强制阻断 |
| `ua-only` | 有记录的 user-agent，无经验证的 IP 订阅源 | 仅限 user-agent 阻断规则 |
| `robots-only` | robots token，例如 `Google-Extended` | 仅限 robots.txt 输出 |
| `static-watch` | 宽泛的静态范围，CN/观察列表，平台范围，弱信号 | 观察、质询或速率限制 |
## 功能
- 针对官方 AI 爬虫 IP 订阅源的已验证 IPv4/IPv6 列表。
- User-agent 列表、regex 列表、nginx map、Apache SetEnvIf 规则和 Cloudflare 表达式。
- 用于退出训练、所有 AI 机器人、CN/观察机器人以及对搜索安全的 AI 退出训练的 robots.txt 代码片段。
- iptables/ipset、nftables、pf/pfSense、Caddy、HAProxy 和 Traefik 输出。
- 通过 `CRAWLERSCOPE_GENERATED_AT` 支持固定时间戳的确定性构建。
- 包含计数、源健康度、置信度、限制策略和失败源的机器可读元数据。
- 定时的 GitHub Actions 更新工作流和每日发布工作流。
## 快速开始
```
git clone https://github.com/ipanalytics/AI-Crawler-Blocklist.git
cd AI-Crawler-Blocklist
make install-dev
make build
make validate
make test
```
对于要求 `uv` 必须将所有状态保留在工作树内的沙箱环境：
```
UV_CACHE_DIR=.uv-cache UV_PYTHON_INSTALL_DIR=.uv-python \
uv run --python 3.12 python scripts/build.py
```
## 安装
生成的文件旨在直接通过 GitHub raw URL 使用，或者作为外部依赖纳入您自己的配置管理中。
```
curl -fsSL https://raw.githubusercontent.com/ipanalytics/AI-Crawler-Blocklist/main/dist/metadata.json
```
建议在生产环境的受控发布中固定到特定的发布标签：
```
curl -fsSL https://github.com/ipanalytics/AI-Crawler-Blocklist/releases/latest/download/ai-crawler-blocklist-dist.tar.gz \
-o ai-crawler-blocklist-dist.tar.gz
```
## 使用示例
### robots.txt
```
curl -fsSL https://raw.githubusercontent.com/ipanalytics/AI-Crawler-Blocklist/main/dist/robots-ai-all-block.txt \
-o /var/www/html/robots.txt
```
### nginx
```
curl -fsSL https://raw.githubusercontent.com/ipanalytics/AI-Crawler-Blocklist/main/dist/nginx-ai-map.conf \
-o /etc/nginx/snippets/nginx-ai-map.conf
```
```
include /etc/nginx/snippets/nginx-ai-map.conf;
server {
if ($ai_crawler) {
return 403;
}
}
```
```
nginx -t && systemctl reload nginx
```
### Apache
```
curl -fsSL https://raw.githubusercontent.com/ipanalytics/AI-Crawler-Blocklist/main/dist/apache-ai-setenvif.conf \
-o /etc/apache2/conf-available/ai-crawlers.conf
a2enconf ai-crawlers
apachectl configtest && systemctl reload apache2
```
### Cloudflare WAF
```
curl -fsSL https://raw.githubusercontent.com/ipanalytics/AI-Crawler-Blocklist/main/dist/cloudflare-ai-expression.txt
```
在 WAF 自定义规则中使用该表达式。该输出基于 UA，专为部署前的审查而设计。
### iptables
```
curl -fsSL https://raw.githubusercontent.com/ipanalytics/AI-Crawler-Blocklist/main/dist/iptables-ai.sh \
-o /usr/local/sbin/update-ai-iptables.sh
chmod +x /usr/local/sbin/update-ai-iptables.sh
/usr/local/sbin/update-ai-iptables.sh
```
生成的脚本使用 `ipset` 进行基于集合的匹配。
### nftables
```
curl -fsSL https://raw.githubusercontent.com/ipanalytics/AI-Crawler-Blocklist/main/dist/nftables-ai.nft \
-o /etc/nftables.d/ai-crawlers.nft
nft -f /etc/nftables.d/ai-crawlers.nft
```
### Caddy
```
curl -fsSL https://raw.githubusercontent.com/ipanalytics/AI-Crawler-Blocklist/main/dist/caddy-ai-block.caddy \
-o /etc/caddy/snippets/ai-crawlers.caddy
caddy validate --config /etc/caddy/Caddyfile && systemctl reload caddy
```
### HAProxy
```
curl -fsSL https://raw.githubusercontent.com/ipanalytics/AI-Crawler-Blocklist/main/dist/haproxy-ai-acl.cfg \
-o /etc/haproxy/ai-crawlers.cfg
haproxy -c -f /etc/haproxy/haproxy.cfg && systemctl reload haproxy
```
## 输出
| 产物 | 用途 |
| --- | --- |
| `dist/ai-ips-verified-v4.txt` | 已验证的官方 IPv4 CIDR |
| `dist/ai-ips-verified-v6.txt` | 已验证的官方 IPv6 CIDR |
| `dist/ai-ips-verified-all.txt` | 合并后的已验证 CIDR |
| `dist/ai-ips-high-confidence-v4.txt` | IPv4 质询/速率限制候选 |
| `dist/ai-ips-high-confidence-v6.txt` | IPv6 质询/速率限制候选 |
| `dist/ai-user-agents.txt` | 纯 AI 爬虫 UA token |
| `dist/ai-user-agents-regex.txt` | 转义的 UA regex token |
| `dist/ai-cn-user-agents-watch.txt` | CN/观察 UA 列表 |
| `dist/robots-ai-all-block.txt` | 针对 AI 机器人和仅限 robots token 的 robots.txt 规则 |
| `dist/cloudflare-ai-expression.txt` | Cloudflare WAF 表达式 |
| `dist/metadata.json` | 源健康度和计数 |
| `dist/sources-report.md` | 人类可读的源报告 |
特定平台文件
| 产物 | 平台 |
| --- | --- |
| `dist/nginx-ai-map.conf` | nginx |
| `dist/nginx-ai-deny.conf` | nginx |
| `dist/apache-ai-setenvif.conf` | Apache |
| `dist/iptables-ai.sh` | iptables/ipset |
| `dist/nftables-ai.nft` | nftables |
| `dist/pf-ai-table.conf` | pf / pfSense |
| `dist/caddy-ai-block.caddy` | Caddy |
| `dist/haproxy-ai-acl.cfg` | HAProxy |
| `dist/traefik-ai-middleware.yml` | Traefik |
## 数据格式
所有生成的文本文件都包含一个标头，其中包含项目名称、生成时间戳、源仓库、策略和审查说明。
`dist/metadata.json` 是当前构建状态的可操作事实来源：
```
{
"generated_at": "2026-06-17T00:00:00Z",
"project": "AI-Crawler-Blocklist",
"policy": "official/operator-published sources only",
"counts": {
"verified_ipv4_prefixes": 2261,
"verified_ipv6_prefixes": 1,
"user_agent_patterns": 24,
"robots_tokens": 26
},
"failed_sources": []
}
```
源定义位于 `config/sources.json` 中。规范化程序在构建时会添加 `confidence`、`enforcement`、`ipPolicy` 和 `includeInAiOutputs`。
## 运维说明
- 使用 `verified-drop` 产物进行严格的 IP 限制。
- 在 IP 范围不可用的情况下，使用 UA 文件进行应用层控制。
- 使用观察列表进行日志记录、质询、bot 评分调整或速率限制。
- 将 `Google-Extended` 和 `Applebot-Extended` 视为 robots.txt 控制。
- 在将更改滚动发布到生产环境之前，请检查 `dist/metadata.json` 和 `dist/sources-report.md`。
## 项目范围
该项目涵盖 AI 爬虫、AI 搜索机器人、助手抓取器、训练/索引机器人以及与 AI 相关的存档源（例如 CCBot）。除非策略明确分类，否则通用的搜索爬虫、SEO 工具、正常运行时间探针、广告验证爬虫、社交预览机器人和安全扫描程序不属于生成的 AI 输出集合。
## 用例
- 出版商的 AI 爬取控制。
- 为已知的 AI user agent 生成 WAF 规则。
- 用于官方爬虫订阅源的已验证 IP 强制阻断列表。
- 利用访问日志丰富机器人分析数据。
- 将受控变更的爬虫策略分发到基础设施自动化中。
## 限制
- User-agent 字符串可能会被伪造。
- robots.txt 依赖于爬虫的自觉遵守。
- 某些助手抓取器是由用户触发的，可能会影响产品曝光度。
- 宽泛的云或平台 IP 范围应属于观察/质询工作流，而不是默认的严格阻断。
## 目录结构
```
.
├── config/ # source definitions, policy, output manifest, schema
├── dist/ # generated blocklists and platform artifacts
├── docs/ # operator documentation
├── scripts/ # build, fetch, normalize, validate, render
├── templates/ # Jinja templates for generated configs
├── tests/ # source policy, parsing, output, workflow tests
└── .github/workflows/ # update, PR validation, daily release
```
## 部署
更新工作流每六小时重新构建一次 `dist/`，并在生成的产物有差异时提交更改。发布工作流每天发布一次版本，包含当前的 `dist/` 存档以及元数据和源报告。
生产环境部署应固定到特定的发布标签，或通过内部的配置管理系统镜像 `dist/`。直接使用 raw URL 适用于简单的主机和实验环境。
## 许可证
MIT。详见 [`LICENSE`](./LICENSE)。
## 免责声明
本项目提供防御性的网络和应用层控制数据。运营者有责任在阻断流量之前，在其自身环境中测试限制措施的影响。