SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

SearXNG 429 Too Many Requests 怎么解决

SearXNG 返回 429 可能来自本地限制器或上游图像请求。先查看日志,检查 API 计数器,再针对实际封禁来源修复,避免改错设置。

SearXNG 为什么返回 429 错误

自托管的 SearXNG 实例可能在两个互不相关的位置触发速率限制,而通常需要修复的速率限制并不是您以为的那一个。本地限制和上游图像请求都可能产生 429。第一种情况发生在本地:SearXNG 自身的限制器判定请求来自机器人,并以状态码 429 响应 Too Many Requests。/image 端点也会转发上游错误状态,包括 429。第二种情况发生在上游:某个搜索引擎拒绝了服务器的 IP 地址。SearXNG 会将该搜索引擎标记为无响应并暂停使用,用户仍会看到正常的结果页面,但其中缺少部分内容,而不是收到 429。

这两种情况没有共同的修复方法。限制器由您控制,因此可以修改。上游封禁发生在搜索引擎一侧,因此修改本地限制器无法解除封禁。日志通常会在约 1 分钟内告诉您属于哪种情况,因此请先查看日志。

本指南假定您使用的是 在自己的 VPS 上运行自托管 SearXNG 实例 中介绍的容器安装方式。下面的每个设置名称都来自截至 16 November 2026 核对过的当前上游文档和源代码。

在修改设置前先查看日志

在打开日志窗口的同时重现问题。在上游 compose 文件中,SearXNG 服务名为 core(其容器名为 searxng-core),docker compose 命令使用服务名:

cd ./searxng/
docker compose logs -f core

限制器消息来自名为 searx.limiter 和 searx.botdetection 的日志记录器,并会标出客户端网络。命中阻止列表时,日志内容为 BLOCK 203.0.113.10/32: matched BLOCKLIST;命中允许列表时,日志内容为 PASS 203.0.113.10/32: matched PASSLIST。每条消息后面都会列出匹配的列表项。如果限制器无法初始化计数器存储,日志会显示 The limiter requires Valkey, please consult the documentation,这表示限制器尚未安装。

每次单独的机器人检查都会以 debug 级别记录,因此默认情况下看不到这些消息。在 settings.yml 中为一次测试启用 debug:

general:
  debug: true

随后,日志会添加形如 BLOCK 203.0.113.10/32: missing HTTP header Accept-Language 的行,其中会标出客户端网络和验证失败的请求头。测试后立即关闭 debug,因为上游明确建议不要在已部署的实例中启用 debug。

引擎故障的日志完全不同。日志会标出引擎,而不是 IP 地址;详细的超时消息以 debug 级别记录,而搜索线程的 engine timeout 消息以 error 级别记录:

HTTP requests timeout (search duration : 3.1 s, timeout: 3.0 s)

此外,还有一个页面可供查看。将 enable_metrics 保持默认值 true 时,实例会在 /stats/errors 记录引擎错误,/preferences 会列出当前正在响应的引擎。/stats/errors 中的条目表示引擎故障,但缺少 searx.limiter 行并不能排除限制器阻止,因为每次单独的机器人检查都使用 searx.botdetection 级别记录。

调试前先固定版本

上游容器配置由两个文件组成。

mkdir -p ./searxng/core-config/
cd ./searxng/

curl -fsSL \
    -O https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \
    -O https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example

cp -i .env.example .env

Compose 文件会拉取 docker.io/searxng/searxng:${SEARXNG_VERSION:-latest}。未设置变量意味着 latest,而 latest 表示下一次 docker compose pull 时实例会发生变化。因此,上周正常工作的设置可能不再匹配读取该设置的代码。SearXNG 标签包含日期和提交。以 2026 年 10 月为准,上游 .env.example 中的示例标签是 2026.3.25-541c6c3cb,因此请在 .env 中设置一个实际版本:

SEARXNG_VERSION=2026.3.25-541c6c3cb

检查已发布的标签,固定你实际测试过的版本,然后针对固定目标进行调试。同一个 .env 文件可以通过 SEARXNG_SECRET 保存密钥,因此在将该目录提交到任何位置前,请阅读 了解 Docker Compose 中环境文件和密钥的工作方式。

限流器需要 Valkey,否则无法运行

限流器会按客户端统计请求次数,这些计数必须在多个工作进程之间共享。该存储由 Valkey 提供。Valkey 是 Redis 的维护分支。旧版 SearXNG 指南将此设置称为 redis:。当前版本读取 valkey:,因此应以当前文档中的键名为准,不要照抄旧文章中的名称。有些页面的内容更早,介绍的是 Searx,而不是 SearXNG。两者是不同的代码库,使用的限流器也不同。因此,在从页面复制配置块前,先确认页面针对的是两个项目中的哪一个。

use_default_settings: true
server:
  secret_key: "change-this-value"
  limiter: true
  public_instance: false
valkey:
  url: valkey://searxng-valkey:6379/0

上游 compose 文件已经运行 valkey 服务,并使用 docker.io/valkey/valkey:9-alpine 镜像,容器名称为 searxng-valkey。因此,该主机名可在 compose 网络中解析。也可以通过 SEARXNG_VALKEY_URL 环境变量设置相同的值。如果 SearXNG 和 Valkey 位于同一台主机上,则 Unix socket URL(unix:///path/to/socket.sock?db=0)也可用。

存储缺失时的行为取决于另一个键。使用 public_instance: false 时,限流器会记录 Valkey 错误并停止运行,因此实例会继续提供服务,但完全不执行限流。使用 public_instance: true 时,进程会改为调用 sys.exit(1),而不是在没有机器人防护的情况下运行公网实例。如果容器在出现 Valkey 初始化错误后不断重启,则需要修复其 Valkey 连接配置。

限流器实际统计的内容

图表SearXNG limiter: requests allowed per client network, defaults in ip_limit.py
此图表背后的数据
[
  {
    "label": "Burst, link token off",
    "max_requests": 15,
    "window": "20 seconds"
  },
  {
    "label": "Burst, flagged client",
    "max_requests": 2,
    "window": "20 seconds"
  },
  {
    "label": "Sustained, link token off",
    "max_requests": 150,
    "window": "10 minutes"
  },
  {
    "label": "Sustained, flagged client",
    "max_requests": 10,
    "window": "10 minutes"
  },
  {
    "label": "Non-HTML format in URL query",
    "max_requests": 4,
    "window": "1 hour"
  },
  {
    "label": "Flagged requests before block",
    "max_requests": 3,
    "window": "30 days"
  }
]

禁用链接令牌检查时,客户端可以在 20 秒突发窗口内发送 15 个请求,在 10 分钟窗口内发送 150 个请求。启用后,通过链接令牌检查的客户端会绕过这两个计数器;可疑客户端在每个突发窗口内只能发送 2 个请求。最后一行限制最严格:在 30 天窗口内出现 3 个被标记的请求后,该地址会被重定向到起始页,而不是执行搜索,日志中会显示 BLOCK: too many request from ... in SUSPICIOUS_IP_WINDOW (redirect to /)。通过链接令牌检查后,该客户端的可疑请求计数器会清零。

这些数值是 searx/botdetection/ip_limit.py 中的常量。它们不是配置项,limiter.toml 也不会公开这些数值,因此修改它们需要编辑源代码。/etc/searxng/limiter.toml 实际控制的是用于对客户端分组的地址前缀、受信任代理列表、可选的链接令牌检查,以及允许列表和阻止列表。

只有启用链接令牌检查时,被标记的行才会生效。启用方式可以是在 limiter.toml 中通过 link_token = true 启用,也可以由 public_instance: true 代为启用。此后,客户端在加载 URL 携带随机令牌的样式表之前,都会被视为可疑客户端。默认情况下链接令牌检查处于关闭状态,此时所有进入这些计数器的客户端都会使用正常行。

请求头检查更加严格,因为它们不会标记请求:请求只要有一项检查失败,就会立即以 429 拒绝。每项检查都是 searx/botdetection/ 中的一个模块,调试日志行会指出未通过检查的请求头:

  • http_accept:Accept 请求头不包含 text/html。
  • http_accept_encoding:Accept-Encoding 请求头既未指定 gzip,也未指定 deflate。
  • http_accept_language:请求中没有 Accept-Language 请求头。
  • http_user_agent:User-Agent 缺失,或匹配已知的机器人模式。
  • http_sec_fetch:Sec-Fetch-* 请求头不符合浏览器发送的内容。此检查仅对已知会发送这些请求头的浏览器版本发起的 HTTPS 请求执行,并会将请求重定向到起始页,而不是返回 429。在当前源代码中,只有无效的 Sec-Fetch-Mode 才会触发该重定向;无效的 Sec-Fetch-Site 或 Sec-Fetch-Dest 会以调试级别记录,但请求仍会继续处理。

浏览器会发送上述所有请求头。普通的 curl 调用几乎不会发送其中任何请求头,因此手写的测试请求第一次尝试就会被拒绝,而相同的搜索在浏览器标签页中却可以正常运行。因此,“在我的浏览器中可以运行,但脚本收到 429”是正常结果,并不神秘。

反向代理后限流器会同时阻止所有用户

这是导致正常实例失效的最常见方式。SearXNG 从 X-Forwarded-For 中第一个不受信任的 IP 获取客户端地址;如果没有,则回退到 X-Real-IP;如果仍没有,则使用建立连接的地址。是否信任这些请求头,由 limiter.toml 中的 trusted_proxies 决定。botdetection 文档称,仅设置 X-Real-IP 时会忽略 trusted_proxies;但截至 2026 年 11 月 16 日检查的 searx/botdetection/trusted_proxies.py 代码会在连接地址不受信任时同时丢弃这两个请求头。因此,只发送 X-Real-IP 不能绕过该列表。

如果代理地址不在该列表中,请求头会被忽略,每个访客都会显示为来自代理地址。这样所有访客共用一个计数器。因此,在禁用链接令牌检查时,总请求数超过 10 分钟内 150 个请求后,整个站点都会一起被阻止。启用链接令牌检查后,可疑客户端共用更严格的计数器;通过检查的客户端则绕过突发限制和长时间窗口限制。

过度信任的后果更严重。如果列出了一个公网地址范围,来自该受信任范围的访客就可以发送自己的 X-Forwarded-For 请求头,并为每个请求选择新的身份。只列出您自己的代理建立连接所使用的地址。在 Docker 中,这通常是 172.16.0.0/12 内的 bridge 网络,而该行默认处于注释状态。

[botdetection]
ipv4_prefix = 32
ipv6_prefix = 48

trusted_proxies = [
  '127.0.0.0/8',
  '::1',
  '172.16.0.0/12',
]

代理也必须发送这些请求头。Nginx 不会自行添加 X-Forwarded-Proto、X-Real-IP 或 X-Forwarded-For:

location / {
    proxy_pass http://127.0.0.1:8080;

    proxy_set_header Host              $host;
    proxy_set_header Connection        $http_connection;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
}

Caddy 和 Traefik 会为您设置转发请求头,因此使用这两者时,只需完成 trusted_proxies 部分。相关权衡见为自托管服务选择反向代理。要验证任一配置,请启用 debug,使用手机移动数据搜索一次,并确认日志行中的网络地址是手机地址,而不是代理地址。

代理的 API 限制取决于请求

默认情况下会禁用 JSON 输出,因此需要为代理添加该格式:

search:
  formats:
    - html
    - json

现在再次查看图表行。带有 URL 查询参数 format 且参数值不是 html 的 /search 请求,会在其独立窗口中计数:每个客户端网络在 1 hour 内最多 4 个请求。API 支持 POST 表单参数,但仅通过 POST 表单数据提供的非 HTML 格式不会增加此 API 计数器;其他限制器检查仍会执行。通过链接令牌检查不会绕过 API 计数器,因为该计数器首先运行。使用 ?format=json 的研究代理会在一个任务中耗尽该额度,此后的每次调用都会返回 429。这个数值在源代码中是常量,因此无法通过配置提高;但不必提高它:可以将代理的地址完全排除在计数之外。

最直接的修复方法是告知限制器,该客户端不是未知客户端。将其地址添加到 limiter.toml 中的放行列表:

[botdetection.ip_lists]
block_ip = []

pass_ip = [
  '10.8.0.0/24',
]

pass_searxng_org = true

pass_ip 的优先级高于所有其他方法,且上游在 limiter.toml 中的注释明确说明,列表中的地址可以不受限制地访问。因此,加入放行列表的客户端不受每个四请求窗口的限制,也会跳过请求头检查,并且直接调用 curl 也能正常工作。放行范围应尽可能小,优先使用 VPN 子网或容器网络,不要使用可路由的网络。让代理直接访问内部网络中的容器,并不能绕过 SearXNG 自身的限制器;应放行 SearXNG 实际看到的客户端地址。为 AI 代理提供 SearXNG 搜索能力介绍了如何完成配置。

应避免将代理指向他人运行的公共实例。通过 SearXNG 发送自动化流量,可能导致该实例被上游搜索引擎封禁。

当引擎转而阻止您时

图表How long SearXNG suspends an engine, search.suspended_times defaults
此图表背后的数据
[
  {
    "label": "SearxEngineTooManyRequests",
    "suspended_seconds": 180,
    "roughly": "3 minutes"
  },
  {
    "label": "SearxEngineAccessDenied",
    "suspended_seconds": 180,
    "roughly": "3 minutes"
  },
  {
    "label": "SearxEngineCaptcha",
    "suspended_seconds": 3600,
    "roughly": "1 hour"
  },
  {
    "label": "recaptcha_SearxEngineCaptcha",
    "suspended_seconds": 604800,
    "roughly": "7 days"
  },
  {
    "label": "cf_SearxEngineCaptcha",
    "suspended_seconds": 1296000,
    "roughly": "15 days"
  }
]

当引擎返回自己的 429 响应或 CAPTCHA 页面时,SearXNG 会引发一个命名异常,并在一段时间内停止向该引擎发送请求。访客不会看到该引擎返回的 429:搜索仍会返回正常的结果页面,只是不包含该引擎。超出请求限制的响应会将其暂停 180 秒,拒绝访问的响应也会暂停 3 minutes。普通 CAPTCHA 会暂停 1 hour。通过 Cloudflare 提供的 CAPTCHA 会暂停 15 days,这是列表中的最长默认时长。您遇到的是三个 CAPTCHA 行中的哪一种,会影响下一步值得尝试的方法;确定实例记录的是哪种异常后,CAPTCHA 错误还有专门的修复方法。

以下是 SearXNG 随附的 searx/settings.yml 中的值,核对日期为 16 November 2026。设置文档仍显示较旧且更长的值(超出请求限制为 one hour,拒绝访问和普通 CAPTCHA 为 one day),因此应以实例实际加载的文件为准,而不是以引用该文件内容的页面为准。

普通故障使用不同的设置。超时或连接失败会将引擎暂停 search.ban_time_on_fail 秒,默认值为 5,且不会超过 search.max_ban_time_on_fail,默认值为 120。解析错误会记录在 /stats/errors 中,但完全不会暂停引擎。因此,响应缓慢的引擎会在几秒内自行恢复,而返回 CAPTCHA 的引擎会消失 one hour 或更长时间。这一差异解释了用户报告的一种看似随机的现象:结果正常,但某个引擎的结果会一次消失 one hour。

在归咎于其他因素之前,应先修复超时问题。默认的 request_timeout 为 3.0 seconds;对于距离引擎最近边缘服务器较远的小型 VPS,这个值仍可能过短。

outgoing:
  request_timeout: 3.5
  max_request_timeout: 10.0
engines:
  - name: bing
    timeout: 5.0

request_timeout 是所有引擎的默认值,max_request_timeout 是上限,单个引擎还可以设置自己的 timeout。提高这些值可以减少故障,但会增加页面延迟,因此应以 half seconds 为步长调整,并监控 /stats/errors,不要直接跳到 10。

如果某个引擎确实在阻止您的地址,请移除它。被暂停的引擎会一直跳过,直到暂停到期;继续保留一个反复阻止您的引擎,只会在它重新符合条件后增加失败重试。

use_default_settings:
  engines:
    remove:
      - google

使用 docker compose restart core 应用更改,然后执行几次搜索并重新加载 /stats/errors。除了检查是否记录错误,还应确认搜索确实返回结果。

数据中心 IP 可能会被视为机器人

Google 会封锁其识别为发送自动化流量的网络,包括共享 VPN 网络。任何本地限流设置都无法解除上游封锁。搜索引擎看到的是您的服务器,而不是输入查询的用户。这正是您选择自行托管所需承担的全部隐私权衡。在假设 SearXNG 能隐藏更多信息之前,建议先阅读SearXNG 实际隐藏了多少。

您可以更改请求使用的搜索引擎,也可以决定是否将实例公开列出。SearXNG 可以通过 outgoing.proxies 或 outgoing.using_tor_proxy 将搜索引擎请求经由代理转发,从而改用其他地址发送流量。更换出口地址并不保证能够访问。Google 也会封锁部分共享 VPN 和隧道服务,因为这些服务的用户会产生自动化流量。

先监控实例,及时发现问题

即使所有引擎都处于暂停状态,SearXNG 仍会在其端口上响应。因此,只监控状态码的运行时间检查会保持正常,但实例实际上不会返回任何内容。应检查响应内容:发起一次真实搜索,并匹配响应正文中预期出现的词语。Uptime Kuma 关键词监控无需额外工具即可完成此操作。每次版本升级后也要检查 /stats/errors,因为引擎会更改 HTML,解析器可能因此失效,而且这与速率限制无关。

FAQ

为什么将 SearXNG 放在反向代理后面后,所有访问者都会收到 429?

因为限制器将代理计为客户端。只有当连接地址列在 /etc/searxng/limiter.toml 的 trusted_proxies 中时,SearXNG 才会读取 X-Forwarded-For。如果未列出,所有访问者会共用一个计数器;禁用链接令牌检查后,他们会一起超过每 10 分钟 150 个请求的限制。启用链接令牌检查后,可疑客户端会共用更严格的计数器,而通过检查的客户端则绕过突发请求和长时间窗口计数器。添加代理连接所使用的地址;在 Docker 中,这通常是网桥范围 172.16.0.0/12。同时确保代理发送 X-Real-IP 和 X-Forwarded-For。不要列出不受您控制的范围,因为从受信任范围连接的客户端可以设置该标头,并为每个请求选择新的身份。

SearXNG 限制器每小时允许多少个 API 请求?

对于 /search 请求,如果其 URL 查询参数 format 不为 html,每个客户端网络每小时允许 4 个请求。仅在 POST 表单数据中提供的非 HTML 格式不会增加该 API 计数器,但其他限制器检查仍然适用。该数值在 searx/botdetection/ip_limit.py 中设置,而不是在 limiter.toml 中设置,因此无法通过配置提高。使用 ?format=json 的代理或脚本会在一个任务中用完该额度。列在 limiter.toml 的 pass_ip 中的地址可不受限制地访问,并且完全不会计数,因此应将客户端地址添加到其中。仅通过内部网络连接并不能绕过 SearXNG 的限制器。

为什么搜索结果为空,而且没有 429 错误?

拒绝您服务器的是搜索引擎,而不是用户。在您自己的实例上打开 /stats/errors:其中会列出每个失败的搜索引擎及其原因;CAPTCHA 或访问被拒绝条目表示该搜索引擎阻止了您服务器的 IP 地址。随后,SearXNG 会暂停该搜索引擎:收到请求过多或访问被拒绝的响应后暂停 3 分钟;收到普通 CAPTCHA 后暂停 1 小时;收到 reCAPTCHA 或 Cloudflare CAPTCHA 后暂停 1 周或更长时间。本地限制器设置无法解除上游阻止,因此移除阻止您地址的搜索引擎,保留能够响应的搜索引擎。

我应该在私有实例上启用限制器吗?

如果除了您之外没有其他流量到达该实例,请保持 limiter: false。它会增加 Valkey 依赖,并阻止您自己的脚本,而它保护的是您并不存在的流量。实例获得公网地址后,应立即启用它,同时启用 public_instance: true。这两个设置需要配合使用:启用 public_instance: true 且初始化时没有可用的 Valkey 时,进程会以状态 1 退出,而不是在未受保护的情况下运行。

这篇文章对您有帮助吗?