Jinsi ya kurekebisha makosa ya 429 kwenye SearXNG

Kwa nini SearXNG inarejesha makosa ya 429

Instance ya SearXNG iliyopo kwenye seva yako inarejesha makosa ya 429 kwa sababu mbili zisizohusiana, na kikomo cha kasi (rate limit) unachohitaji kurekebisha mara nyingi si kile unachodhani. Sababu ya kwanza ni ya ndani: kizuizi cha SearXNG chenyewe kimeamua kuwa ombi limetoka kwa bot na kujibu Too Many Requests kwa status 429. Sababu ya pili ni ya nje (upstream): injini ya utafutaji imekataa anwani ya IP ya seva yako, jambo ambalo huwafikia watumiaji wako kama ukurasa wa matokeo wenye vitu vilivyokosekana, si kama 429.

Kesi hizi mbili hazina suluhisho moja. Kizuizi cha ndani ni chako, kwa hivyo unaweza kukibadilisha. Kuzuiliwa na injini ya nje hutokea upande wa Google, kwa hivyo hakuna kitu katika settings.yml yako kitakachokiondoa. Log inakuambia ni ipi kati ya hizo unayo ndani ya dakika moja, kwa hivyo anza hapo.

Mwongozo huu unachukulia kuwa usakinishaji wa container ulioelezwa katika instance ya SearXNG iliyopo kwenye VPS yako mwenyewe. Kila jina la mpangilio hapa chini linatoka katika nyaraka za sasa za upstream na source code, iliyokaguliwa mnamo Agosti 2026.

Soma logi kabla ya kubadilisha mipangilio

Zalisha upya tatizo huku dirisha la logi likiwa wazi.

cd ./searxng/
docker compose logs -f searxng-core

Ujumbe wa kizuizi (limiter) hutoka kwenye logger inayoitwa searx.limiter na hutaja anwani ya IP. Hitilafu ya blocklist inasomeka BLOCK 203.0.113.10: matched BLOCKLIST, na hitilafu ya allowlist inasomeka PASS 203.0.113.10: matched PASSLIST. Ikiwa kizuizi hakiwezi kufikia hifadhi yake ya kaunta, logi inasema The limiter requires Valkey, please consult the documentation, jambo linalomaanisha kuwa hakuna kinachohesabiwa kabisa.

Kila ukaguzi wa bot binafsi hurekodiwa kwenye kiwango cha debug, kwa hivyo hutauona kwa mipangilio ya kawaida. Washa debug kwa ajili ya jaribio moja katika settings.yml:

general:
  debug: true

Logi kisha huongeza mistari yenye umbo la NOT OK (http_accept_language) karibu na mtandao wa mteja, ikitaja ukaguzi ulioshindwa. Izime tena baadaye, kwa sababu nyaraka za upstream zinakushauri usitumie instance iliyopo kwenye uzalishaji (deployed) ikiwa debug imewashwa.

Hitilafu za injini (engine failures) hazionekani hivyo. Zinataja injini badala ya IP, na ya kawaida zaidi ni timeout:

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

Kuna ukurasa pia kwa ajili ya hili. Ikiwa enable_metrics imeachwa kwenye thamani yake ya awali ya true, instance yako hurekodi hitilafu za injini kwenye /stats/errors, na /preferences huorodhesha injini zipi zinajibu kwa sasa. Ikiwa /stats/errors imejaa na logi haina mistari ya searx.limiter, basi kizuizi si tatizo lako.

Funga toleo (pin) kabla ya kutatua tatizo lolote

Usanidi wa container kutoka kwa msanidi (upstream) unajumuisha faili mbili.

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

Faili ya compose huvuta docker.io/searxng/searxng:${SEARXNG_VERSION:-latest}. Variable isiyowekwa inamaanisha latest, na latest inamaanisha kuwa instance inabadilika bila wewe kujua wakati wa docker compose pull inayofuata, kwa hivyo mpangilio uliokuwa ukifanya kazi wiki iliyopita unaweza kuacha kuendana na msimbo unaousoma. Lebo (tags) za SearXNG hubeba tarehe na commit. Lebo ya mfano katika .env.example ya upstream kufikia Agosti 2026 ni 2026.3.25-541c6c3cb, kwa hivyo weka lebo halisi katika .env:

SEARXNG_VERSION=2026.3.25-541c6c3cb

Angalia lebo zilizochapishwa na ufunge (pin) toleo ambalo umelipima kikamilifu, kisha fanya utatuzi dhidi ya target isiyobadilika. Faili hiyo hiyo ya .env huhifadhi secret key yako, kwa hivyo soma jinsi faili za env na secret zinavyofanya kazi katika Docker Compose kabla ya kuweka (commit) saraka hiyo mahali popote.

Limiter inahitaji Valkey, vinginevyo haitafanya kazi

Limiter huhesabu maombi kwa kila mteja, na hesabu hizo lazima zishirikiwe kati ya michakato ya worker. Hifadhi hiyo ni Valkey, ambayo ni fork inayodumishwa ya Redis. Miongozo ya zamani ya SearXNG huita mpangilio huu redis:. Matoleo ya sasa husoma valkey:, kwa hivyo nakili jina la ufunguo kutoka kwenye nyaraka za sasa badala ya kutoka kwenye chapisho la zamani. Baadhi ya kurasa hizo ni za zamani zaidi na zinaelezea Searx badala ya SearXNG, ambayo ni codebase tofauti yenye limiter tofauti, kwa hivyo tambua ni mradi upi kati ya hiyo miwili ambao ukurasa uliandikiwa kabla ya kunakili block ya usanidi kutoka humo.

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

Faili ya compose ya upstream tayari inaendesha huduma ya searxng-valkey kwenye image ya docker.io/valkey/valkey:9-alpine, kwa hivyo jina hilo la host hutatuliwa ndani ya mtandao wa compose. Thamani hiyo hiyo inaweza kuwekwa kwa kutumia environment variable ya SEARXNG_VALKEY_URL, na URL ya Unix socket (unix:///path/to/socket.sock?db=0) hufanya kazi wakati SearXNG na Valkey vinashiriki host moja.

Kinachotokea wakati hifadhi haipo hutegemea ufunguo mwingine mmoja. Kwa public_instance: false, limiter huingiza hitilafu ya Valkey kwenye log na kuacha, kwa hivyo instance huendelea kuhudumia bila rate limiting yoyote. Kwa public_instance: true, mchakato hupiga sys.exit(1) badala yake, kwa sababu instance iliyo wazi yenye ulinzi wa bot uliovunjika hukusanya CAPTCHAs (jaribio la umma la turing lililojiendesha kikamilifu ili kutofautisha kompyuta na binadamu) kutoka kwa kila injini ndani ya siku moja. Container inayojianzisha upya kwenye loop mara tu baada ya kuweka public_instance: true ni hii, na mstari wa mwisho kabla ya kila exit hutaja Valkey.

Kile ambacho limiter huhesabu kihalisi

[
  {
    "label": "Burst, normal client",
    "max_requests": 15,
    "window": "20 seconds"
  },
  {
    "label": "Burst, flagged client",
    "max_requests": 2,
    "window": "20 seconds"
  },
  {
    "label": "Sustained, normal client",
    "max_requests": 150,
    "window": "10 minutes"
  },
  {
    "label": "Sustained, flagged client",
    "max_requests": 10,
    "window": "10 minutes"
  },
  {
    "label": "Any non-HTML format",
    "max_requests": 4,
    "window": "1 hour"
  },
  {
    "label": "Flagged requests before block",
    "max_requests": 3,
    "window": "30 days"
  }
]

Mteja wa kawaida hupata maombi 15 ndani ya dirisha la muda la sekunde 20 na 150 ndani ya dirisha la dakika 10. Pindi ombi linapotiwa alama kama la kutiliwa shaka, mteja huyo huyo hushushwa hadi 2 kwa kila dirisha la muda. Mstari wa mwisho ndio mkali zaidi: baada ya maombi 3 yaliyotiwa alama ndani ya dirisha la siku 30, anwani hiyo huelekezwa kwenye ukurasa wa kwanza badala ya kutafuta, na logi husema BLOCK: too many request from ... in SUSPICIOUS_IP_WINDOW (redirect to /).

Namba hizi ni konstanti ndani ya searx/botdetection/ip_limit.py. Sio mipangilio, na limiter.toml haitoi njia ya kuzibadilisha, kwa hivyo kuzibadilisha kunahitaji kuhariri source code. Kile ambacho /etc/searxng/limiter.toml hudhibiti ni viambishi awali vya anwani (address prefixes) vinavyotumiwa kuweka wateja katika makundi, orodha ya mawakala (proxies) wanaoaminika, ukaguzi wa hiari wa token ya kiungo, pamoja na orodha za kuruhusu (pass lists) na kuzuia (block lists).

Ombi hutiwa alama kama la kutiliwa shaka kupitia ukaguzi wa header, na kila ukaguzi una jina ambalo utaliona kwenye logi ya debug:

• http_accept: header ya Accept haina text/html.
• http_accept_encoding: header ya Accept-Encoding haitaji gzip wala deflate.
• http_accept_language: hakuna header ya Accept-Language.
• http_connection: header ya Connection imewekwa kuwa close.
• http_user_agent: User-Agent haipo au inalingana na muundo unaojulikana wa bot.
• http_sec_fetch: header ya Sec-Fetch-Mode au Sec-Fetch-Dest sio ile inayotumwa na kivinjari.

Kivinjari hutuma yote haya. Wito wa kawaida wa curl hautumi karibu yoyote kati ya hayo, kwa hivyo ombi la majaribio lililoandikwa kwa mkono hutiwa alama kwenye jaribio lake la kwanza wakati utafutaji uleule ukifanya kazi kwenye tab ya kivinjari. Hii ndiyo sababu "inafanya kazi kwenye kivinjari changu, lakini script yangu inapata 429" ni matokeo ya kawaida badala ya kuwa jambo la kushangaza.

Nyuma ya reverse proxy, limiter inawazuia watumiaji wote kwa wakati mmoja

Hii ndiyo njia ya kawaida ya kuharibu mfumo unaofanya kazi. SearXNG huchukua anwani ya mteja kutoka kwa IP ya kwanza isiyoaminika katika X-Forwarded-For, ikishindwa hutumia X-Real-IP, na ikishindwa tena hutumia anwani iliyofungua muunganisho. Kama vichwa (headers) hivyo vitaaminiwa au la, huamuliwa na trusted_proxies katika limiter.toml.

Ikiwa anwani ya proxy yako haimo kwenye orodha hiyo, vichwa hivyo hupuuzwa na kila mgeni huonekana kama anatumia anwani ya proxy. Kwa hivyo, wanashiriki kaunta moja, na tovuti nzima hufungiwa mara tu jumla inapovuka maombi 150 ndani ya dakika 10. Mtumiaji mmoja anayepakia upya ukurasa wa matokeo mara chache anaweza kusababisha wote wazuiwe.

Kuamini kupita kiasi ni hatari zaidi. Ikiwa masafa ya IP ya umma yameorodheshwa, mgeni yeyote anaweza kutuma kichwa chake cha X-Forwarded-For na kuchagua utambulisho mpya kwa kila ombi, jambo ambalo huzima limiter kwa yeyote anayejua mbinu hiyo. Orodhesha tu anwani ambayo proxy yako huunganishia. Katika Docker, hiyo kwa kawaida ni bridge network ndani ya 172.16.0.0/12, na mstari huo huja ukiwa umewekewa alama ya maoni (commented out).

[botdetection]
ipv4_prefix = 32
ipv6_prefix = 48

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

Proxy lazima itume vichwa hivyo pia. Nginx haiongezi vyovyote peke yake:

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 na Traefik huweka vichwa vya forwarded kwa ajili yako, kwa hivyo ukitumia hizo unahitaji tu sehemu ya trusted_proxies ya kazi hiyo. Faida na hasara zimefafanuliwa katika kuchagua reverse proxy kwa ajili ya huduma ya self-hosted. Ili kuthibitisha usanidi wowote, washa debug, fanya utafutaji mmoja ukiwa kwenye data ya simu, na uhakikishe kuwa mtandao unaoonekana kwenye log line ni anwani ya simu yako badala ya ile ya proxy.

Wakala wako anapata maombi manne ya API kwa saa

Pato la JSON limezimwa kwa chaguomsingi, kwa hivyo wakala anahitaji liongezwe:

search:
  formats:
    - html
    - json

Sasa soma tena safu ya chati. Ombi lolote linaloulizia umbizo lingine isipokuwa HTML huhesabiwa katika dirisha lake lenyewe: 4 maombi kwa kila 1 hour, kwa kila anwani. Wakala wa utafiti hutumia kiasi hicho katika kazi moja, na kila mwito unaofuata unarudisha 429. Kuongeza kikomo si chaguo, kwa sababu namba hiyo imewekwa ndani ya chanzo.

Suluhisho safi ni kuuambia mfumo wa kikomo (limiter) kwamba mteja huyu si mgeni. Ongeza anwani yake kwenye orodha ya kuruhusiwa (pass list) katika limiter.toml:

[botdetection.ip_lists]
block_ip = []

pass_ip = [
  '10.8.0.0/24',
]

pass_searxng_org = true

pass_ip ina kipaumbele kuliko njia nyingine yoyote, kwa hivyo mteja aliyeorodheshwa (allowlisted) anaruka pia ukaguzi wa header na mwito wa kawaida wa curl hufanya kazi. Weka masafa (range) ya anwani kuwa madogo uwezavyo, na upendelee subnet ya VPN au mtandao wa container badala ya kitu chochote kinachoweza kufikiwa hadharani. Suluhisho lingine safi ni kuuweka wakala mbali kabisa na njia ya umma: uelekeze kwenye anwani ya container katika mtandao wa ndani, ambapo proxy na limiter yake hawaoni trafiki hiyo. Kuunganisha mfumo huo kumejadiliwa katika kumpa wakala wa AI uwezo wa kutafuta wa SearXNG.

Chaguo la kuepuka ni kuelekeza wakala kwenye instance ya umma inayoendeshwa na mtu mwingine. Hiyo ndiyo njia ya haraka zaidi ya kusababisha anwani ya IP ya mtu anayejitolea kuzuiwa na injini za utafutaji za juu (upstream engines), na ndiyo sababu umbizo la JSON limezimwa kwa chaguomsingi tangu mwanzo.

Wakati injini zinapokuzuia

[
  {
    "label": "SearxEngineTooManyRequests",
    "suspended_seconds": 3600,
    "roughly": "1 hour"
  },
  {
    "label": "SearxEngineAccessDenied",
    "suspended_seconds": 86400,
    "roughly": "1 day"
  },
  {
    "label": "SearxEngineCaptcha",
    "suspended_seconds": 86400,
    "roughly": "1 day"
  },
  {
    "label": "recaptcha_SearxEngineCaptcha",
    "suspended_seconds": 604800,
    "roughly": "7 days"
  },
  {
    "label": "cf_SearxEngineCaptcha",
    "suspended_seconds": 1296000,
    "roughly": "15 days"
  }
]

Injini inapojibu kwa 429 yake yenyewe au kwa ukurasa wa CAPTCHA, SearXNG huibua exception iliyopewa jina na huacha kuitumia injini hiyo kwa muda. Jibu la maombi mengi sana huiweka kwenye kusimamishwa kwa 3600 sekunde. CAPTCHA ya kawaida au jibu la kukataliwa kwa ufikiaji huiweka kwenye kusimamishwa kwa 1 day. CAPTCHA inayotolewa kupitia Cloudflare huiweka kwenye kusimamishwa kwa 15 days, muda mrefu zaidi wa chaguo-msingi kwenye orodha, kwa sababu jibu hilo linaonyesha kuwa zuio lipo kwenye edge na kujaribu tena hakutasaidia. Ni safu ipi kati ya safu tatu za CAPTCHA uliyoifikia hubadilisha hatua inayofaa kujaribu inayofuata, na makosa ya CAPTCHA yana seti yao ya marekebisho baada ya kujua ni exception ipi iliyorekodiwa na instance yako.

Hitilafu za kawaida hutumia mipangilio tofauti. Timeout au hitilafu ya parse husimamisha injini kwa muda mfupi unaotokana na search.ban_time_on_fail, ambao kwa kawaida ni sekunde 5 na hufikia upeo wa sekunde 120 kupitia search.max_ban_time_on_fail. Kwa hivyo, injini inayochelewa hujirekebisha yenyewe ndani ya dakika chache, wakati injini iliyozuiwa haipatikani kwa saa kadhaa. Tofauti hiyo inaelezea dalili ambazo watu huripoti kama za kubahatisha: matokeo huwa mazuri, kisha matokeo ya injini moja hupotea kwa muda wote wa mchana.

Inafaa kurekebisha timeouts kabla ya kumlaumu yeyote. Thamani ya kawaida ya request_timeout ni sekunde 2.0, ambayo ni ndogo kwa VPS ndogo iliyo mbali na seva ya edge ya injini husika.

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

request_timeout ndiyo thamani ya kawaida kwa kila injini, max_request_timeout ndiyo upeo, na injini moja inaweza kuwa na timeout yake yenyewe. Kuongeza thamani hizi kunapunguza hitilafu lakini huongeza latency ya ukurasa, kwa hivyo ongeza kwa nusu sekunde na uangalie /stats/errors badala ya kuruka moja kwa moja hadi 10.

Kwa injini inayozuia anwani yako kikamilifu, iondoe. Kila utafutaji husubiri injini yake inayochelewa zaidi, kwa hivyo kuweka injini iliyosimamishwa kudumu kunapoteza muda na hakurejeshi matokeo yoyote.

use_default_settings:
  engines:
    remove:
      - google

Tekeleza mabadiliko kwa docker compose restart searxng-core, kisha fanya utafutaji kadhaa na ufungue upya /stats/errors. Ukurasa usio na hitilafu baada ya dakika tano za matumizi ya kawaida inamaanisha mabadiliko yamefanya kazi.

IP ya datacentre itachukuliwa kama bot

Anwani ya VPS yako ni ya masafa ya hosting, na injini kubwa za utafutaji huchukulia masafa hayo kama otomatiki. Baadhi ya injini hizo huweka CAPTCHA kwa kila ombi kutoka kwa anwani kama hiyo, bila kujali jinsi vichwa vya habari (headers) vilivyo sahihi au kasi ya maombi ilivyo ndogo. Hakuna mpangilio wowote katika settings.yml unaoweza kubadilisha uamuzi huo. Injini zinazoona seva yako badala ya mtu anayeandika swali ndio gharama nzima ya faragha uliyokubali kwa kufanya self-hosting, na kiasi ambacho SearXNG huficha kwa hakika ni vyema kusomwa kabla ya kudhani kuwa inaficha zaidi ya hapo.

Unachoweza kubadilisha ni injini zipi unazouliza na kama mfumo wako (instance) umeorodheshwa hadharani. Mfumo wa faragha unaotumiwa na kaya moja mara chache husababisha matatizo. Mfumo wa hadharani kwenye IP ya hosting utapata kusimamishwa kwenye injini kali zaidi, na hiyo ndiyo hali ya kawaida ya programu hiyo badala ya kuwa kosa katika usanidi wako. SearXNG inaweza kuelekeza maombi ya injini kupitia proxy kwa kutumia outgoing.proxies au outgoing.using_tor_proxy, jambo ambalo huhamishia trafiki kwenye anwani tofauti. Exit nodes na proxy za bei nafuu hupata alama mbaya zaidi kuliko masafa ya hosting, kwa hivyo tarajia hatua hiyo kufanya matokeo kuwa mabaya zaidi.

Fuatilia instance ili uwe wa kwanza kujua

SearXNG hujibu kwenye port yake hata wakati injini zote zimesimamishwa, kwa hivyo ukaguzi wa uptime unaoangalia tu status code utaonyesha kijani wakati instance haitoi matokeo yoyote. Badala yake, kagua maudhui: omba utafutaji halisi na ulinganishe neno unalotarajia katika mwili wa jibu. Uptime Kuma keyword monitoring hufanya hivyo bila kuhitaji zana za ziada. Fuatilia /stats/errors baada ya kila toleo jipya pia, kwa sababu injini hubadilisha HTML yao na parser inaweza kuvunjika bila kuhusisha rate limit.

FAQ

Kwa nini SearXNG inarejesha 429 kwa kila mgeni baada ya kuiweka nyuma ya reverse proxy?

Kwa sababu limiter inahesabu proxy kama mteja. SearXNG inasoma X-Forwarded-For pale tu anwani ya muunganisho inapoorodheshwa kwenye trusted_proxies ndani ya /etc/searxng/limiter.toml. Ikiwa haijaorodheshwa, kila mgeni anashiriki kaunta moja na wote wanavuka kikomo cha maombi 150 kwa dakika 10 kwa pamoja. Ongeza anwani ambayo proxy yako inatumia kuunganisha, ambayo katika Docker kwa kawaida ni masafa ya bridge 172.16.0.0/12, na uhakikishe kuwa proxy inatuma X-Real-IP na X-Forwarded-For. Usiorodheshe kamwe masafa usiyoyadhibiti, kwa sababu mtandao unaoaminika unaruhusu mgeni yeyote kuweka header hiyo na kuchagua utambulisho mpya kwa kila ombi.

SearXNG limiter inaruhusu maombi mangapi ya API kwa saa?

Nne kwa kila anwani ya IP kwa saa. Ombi lolote linaloulizia muundo mwingine tofauti na HTML linahesabiwa katika dirisha tofauti la saa moja, na kikomo hicho kimewekwa kwenye searx/botdetection/ip_limit.py badala ya limiter.toml, kwa hivyo hakiwezi kuongezwa kutoka kwenye configuration. Wakala au script inapitisha hilo katika kazi moja. Ongeza anwani ya mteja kwenye pass_ip ndani ya limiter.toml, au fikia instance hiyo kupitia mtandao wa ndani ambapo limiter haiwezi kuona ombi hilo.

Kwa nini matokeo yangu ya utafutaji yanarudi tupu bila hitilafu ya 429?

Injini za utafutaji zinakataa seva yako, si watumiaji wako. Fungua /stats/errors kwenye instance yako: inaorodhesha kila injini iliyoshindwa na sababu yake, na ujumbe wa CAPTCHA au access-denied unamaanisha kuwa injini hiyo imezuia anwani ya IP ya seva yako. SearXNG kisha inaisimamisha injini hiyo, kwa saa moja baada ya jibu la maombi mengi sana na kwa siku moja baada ya CAPTCHA. Hakuna mpangilio wa ndani unaoweza kuondoa uzuiaji wa nje, kwa hivyo ondoa injini zinazozuia anwani yako na uweke zile zinazojibu.

Je, nifanye enable limiter kwenye instance ya kibinafsi?

Ikiwa hakuna kitu kinachofikia instance hiyo isipokuwa wewe, iache limiter: false. Inaongeza utegemezi wa Valkey na inazuia script zako mwenyewe, na inalinda dhidi ya trafiki ambayo huna. Ifanye enable pale tu instance inapopata anwani ya umma, pamoja na public_instance: true. Jozi hiyo imekusudiwa: ikiwa na public_instance: true na bila Valkey inayofanya kazi, mchakato unajifunga na hali ya 1 badala ya kuendelea kufanya kazi bila ulinzi.