bot-verifier：NGINX 的搜索引擎索引机器人验证模块

安装

你可以在任何基于 RHEL 的发行版中安装此模块，包括但不限于：

RedHat Enterprise Linux 7、8、9 和 10
CentOS 7、8、9
AlmaLinux 8、9
Rocky Linux 8、9
Amazon Linux 2 和 Amazon Linux 2023

CentOS/RHEL 8+、Fedora Linux、Amazon Linux 2023+CentOS/RHEL 7 和 Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-bot-verifier

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-bot-verifier

在 /etc/nginx/nginx.conf 顶部添加以下内容以启用该模块：

load_module modules/ngx_http_bot_verifier_module.so;

本文档介绍 nginx-module-bot-verifier v0.0.18，发布于 2026 年 10 月 27 日。

用于通过反向/正向 DNS 查询验证搜索引擎机器人身份的 NGINX 模块。

此模块通过执行各搜索提供商推荐的 DNS 验证方法，验证声称是搜索引擎爬虫（Google、Bing、Yahoo、Baidu、Yandex）的访问者。它可防止恶意行为者通过伪造机器人 User-Agent 字符串来绕过安全措施。

它是 Aaron Bedra 所开发的原版 ngx_bot_verifier 的直接替代品。

功能特性

反向/正向 DNS 验证，遵循搜索引擎提供商的指南
异步 DNS 解析，使用 NGINX 内置的 resolver（非阻塞）
Redis 缓存，带连接池，以尽量减少 DNS 查询开销
可配置的提供商 - 在默认提供商之外添加自定义机器人提供商
故障放行设计 - 验证错误时允许请求通过，以避免阻断合法流量
真实 IP 支持，通过 ngx_http_realip_module 适用于代理后方的部署

支持的提供商

内置提供商

提供商	已验证域名
Google	`google.com`、`googlebot.com`
Bing	`search.msn.com`
Yahoo	`yahoo.com`
Baidu	`crawl.baidu.com`
Yandex	`yandex.com`、`yandex.net`、`yandex.ru`

自定义提供商

使用 bot_verifier_provider 指令添加自定义提供商：

bot_verifier_provider facebookexternalhit fbsv.net;
bot_verifier_provider applebot applebot.apple.com;

自定义提供商将在内置提供商之外额外进行验证。

概要

http {
    # 必需：配置 realip 模块以信任你的上游代理
    set_real_ip_from 10.0.0.0/8;
    set_real_ip_from 172.16.0.0/12;
    set_real_ip_from 192.168.0.0/16;
    real_ip_header X-Forwarded-For;
    real_ip_recursive on;

    # 必需：配置 resolver 以实现非阻塞 DNS 查询
    resolver 8.8.8.8 8.8.4.4 valid=300s ipv6=off;
    resolver_timeout 5s;

    server {
        location / {
            bot_verifier on;
            bot_verifier_redis_host localhost;
            bot_verifier_redis_port 6379;
            bot_verifier_redis_expiry 3600;

            # 可选：添加自定义提供商
            bot_verifier_provider applebot applebot.apple.com;
        }
    }
}

指令

bot_verifier

语法： bot_verifier on|off;

默认值： off

上下文： http、server、location

启用或禁用机器人验证。启用后，User-Agent 字符串匹配已知机器人模式的请求将通过 DNS 查询进行验证。

bot_verifier_provider

语法： bot_verifier_provider <name> <domain1> [domain2] ...;

默认值： 无

上下文： http、server、location

添加用于验证的自定义机器人提供商。name 将与 User-Agent 字符串进行匹配（不区分大小写）。这些域名用于验证反向 DNS 查询结果。

示例：

bot_verifier_provider facebookexternalhit fbsv.net;
bot_verifier_provider applebot applebot.apple.com;

域名匹配反向 DNS 主机名本身或其任意子域名：fbsv.net 匹配 fwdproxy-prn-020.fbsv.net，但不匹配 evilfbsv.net。开头和结尾的点会被忽略，且匹配不区分大小写，因此 .fbsv.net 与 fbsv.net 相同（在 0.0.18 之前，开头的点会导致该域名不匹配任何内容）。仅由点组成的域名属于配置错误。

Meta 和 WhatsApp 链接预览： Meta 的 facebookexternalhit 爬虫（Facebook、Instagram、Messenger 预览）反向解析为 fbsv.net，因此上述示例已涵盖它。WhatsApp 预览由发送者自己的设备从普通移动 IP 获取，因此无法通过 DNS 验证。不要为 WhatsApp User-Agent 添加提供商，否则每个预览都会被阻止。

自定义提供商将在内置提供商（Google、Bing、Yahoo、Baidu、Yandex）之外额外进行检查。

bot_verifier_redis_host

语法： bot_verifier_redis_host <hostname>;

默认值： localhost

上下文： http、server、location

用于缓存验证结果的 Redis 服务器主机名。

bot_verifier_redis_port

语法： bot_verifier_redis_port <port>;

默认值： 6379

上下文： http、server、location

Redis 服务器端口。

bot_verifier_redis_connection_timeout

语法： bot_verifier_redis_connection_timeout <milliseconds>;

默认值： 10

上下文： http、server、location

建立 Redis 连接的超时时间。

bot_verifier_redis_read_timeout

语法： bot_verifier_redis_read_timeout <milliseconds>;

默认值： 10

上下文： http、server、location

Redis 读取操作的超时时间。

bot_verifier_redis_expiry

语法： bot_verifier_redis_expiry <seconds>;

默认值： 3600

上下文： http、server、location

缓存验证结果的 TTL。过期后，来自同一 IP 的下一个请求将触发新的 DNS 验证。

bot_verifier_redis_database

语法： bot_verifier_redis_database <number>;

默认值： 0

上下文： http、server、location

用于存储验证结果的 Redis 数据库编号。

bot_verifier_redis_password

语法： bot_verifier_redis_password <password>;

默认值： 空

上下文： http、server、location

用于 Redis 身份验证的密码。如果 Redis 不需要身份验证，请留空。

异步 DNS 解析

当配置了 NGINX 的 resolver 指令时，模块会使用 NGINX 内置的 resolver 异步执行 DNS 查询。这是生产环境的推荐配置：

非阻塞 - DNS 查询不会阻塞 NGINX 工作进程
可扩展 - 可处理高流量，而不会出现 DNS 引起的延迟峰值
优雅超时 - 缓慢的 DNS 响应不会影响其他请求

验证流程：

对客户端 IP 进行反向 DNS 查询（PTR 记录）
验证解析出的主机名以已知提供商域名结尾
进行正向 DNS 查询（A 记录）以确认 IP 匹配
将结果缓存到 Redis

实验性本地 Web Bot Auth 观察器

一个可选的 Ed25519 观察器可以使用由运维人员审核的本地密钥注册表来报告 HTTP Message Signature 的有效性。它默认关闭，且不会改变现有的 DNS/缓存强制执行。它不执行任何网络密钥发现，也不提供授权或重放防护。请参阅有界支持的配置文件、配置和测试。质量脚手架改造是有意限定范围的；不声称获得完整的脚手架认证或公开的已验证证据。

快速封闭式开发检查：make test-l1（无需 nginx、Redis 或网络）。

仅返回翻译后的 Markdown。