Sửa lỗi CAPTCHA từ engine trong SearXNG

Ý nghĩa của lỗi CAPTCHA trong SearXNG

Lỗi CAPTCHA trong SearXNG xuất phát từ các engine mà instance của bạn truy vấn. Server của bạn yêu cầu một engine trả kết quả, nhưng engine trả về một trang challenge thay vì kết quả. SearXNG ghi nhận lỗi đối với engine đó vì không có dữ liệu nào trong phản hồi để parse. Instance của bạn vẫn hoạt động bình thường. Một máy chủ mà bạn không kiểm soát đã quyết định rằng request của bạn không giống request do người dùng thực hiện.

Sự thật này quyết định mọi cách xử lý bên dưới. Quyết định được đưa ra trên phần cứng của chính engine đó, vì vậy không thiết lập nào trong settings.yml có thể ghi đè quyết định này. Bạn có thể thay đổi địa chỉ mà request sử dụng để đi ra ngoài, các engine được truy vấn, và cách instance phản ứng khi một engine bắt đầu từ chối request.

Hai lỗi trông giống nhau và cách phân biệt

Lỗi đầu tiên là instance của bạn trả HTTP 429 (quá nhiều request) cho chính browser của bạn. Đây là limiter của SearXNG, lớp phát hiện bot nằm trước search endpoint. Nó chạy trên máy chủ của bạn và bạn có thể tự cấu hình. limiter trả 429 cho chính người dùng của bạn là một vấn đề riêng với các thiết lập riêng, nên không có hướng dẫn nào dưới đây áp dụng cho vấn đề đó.

Lỗi thứ hai nằm ở upstream. Trang kết quả vẫn tải bình thường, nhưng một hoặc nhiều engine không xuất hiện trong kết quả hoặc có thông báo lỗi. Instance của bạn không từ chối request nào. Một engine đã từ chối server của bạn.

• Trang không tải được hoặc search endpoint trả 429: kiểm tra limiter.
• Trang tải được nhưng kết quả quá ít, hoặc một engine bị đánh dấu lỗi: kiểm tra upstream và tiếp tục đọc.

Cả hai lỗi có thể xảy ra trên cùng một instance và tác động lẫn nhau, vì limiter được cấu hình quá lỏng sẽ cho phép lưu lượng đi vào, làm tăng rate của các query gửi ra ngoài. Hãy chẩn đoán từng lỗi một.

Vì sao engine SearXNG trả về lỗi CAPTCHA trên VPS nhưng không lỗi trên laptop?

Vì địa chỉ gửi request khác nhau. Kết nối tại nhà của bạn dùng địa chỉ thuộc dải của ISP dành cho người dùng cá nhân, được chia sẻ theo thời gian với nhiều người dùng thông thường. VPS dùng địa chỉ thuộc dải của datacentre. Các dải này được công khai, nên bất kỳ ai cũng có thể tra cứu địa chỉ nào thuộc nhà cung cấp hosting. Engine muốn ngăn scraper thường bắt đầu bằng cách xem các request từ dải hosting là đáng ngờ, vì chỉ có rất ít request trong các dải này đến từ người dùng thật đang dùng trình duyệt.

Một số yếu tố khác cũng làm tăng mức độ đáng ngờ của địa chỉ. Instance của bạn gửi một request đến mỗi engine cho mỗi lần tìm kiếm của người dùng. Vì vậy, chỉ một số ít người dùng cũng có thể tạo ra rate từ một địa chỉ mà một cá nhân không thể tạo ra. Theo thiết kế, SearXNG không duy trì session với engine và không gửi cookie có thời hạn dài. Do đó, mọi request đều đến mà không có lịch sử trước đó. Địa chỉ này cũng có thể mang theo lịch sử mà bạn không tạo ra, vì nhà cung cấp tái sử dụng địa chỉ và tenant trước đó có thể đã dùng địa chỉ này để scraping trong nhiều tháng.

Engine không phải lúc nào cũng từ chối theo cách dễ nhận biết. Engine có thể trả về 403, 429, hoặc HTTP 200 kèm một trang challenge trong response body. Trường hợp cuối dễ gây nhầm lẫn, vì kiểm tra status code cho thấy engine vẫn hoạt động, trong khi SearXNG không tìm thấy kết quả nào trong response. Vì vậy, hãy đọc error report của chính instance thay vì dùng curl đến engine rồi chỉ xem status line.

Đọc thông tin instance báo cáo trước khi thay đổi bất cứ thứ gì

Mỗi cách khắc phục dưới đây đều bắt đầu bằng tên engine đang lỗi và lý do instance đã ghi nhận cho engine đó. SearXNG cung cấp cả hai thông tin này. Trang /stats liệt kê các engine cùng số lần lỗi và độ tin cậy. /stats/errors trả về thông tin chi tiết về lỗi dưới dạng JSON, dễ lưu lại và so sánh vào tuần sau hơn. Hãy mở các trang này bằng trình duyệt bạn thường dùng cho instance.

Log của container ghi lại các sự kiện tương tự ngay khi chúng xảy ra. Tên service ở đây là tên được dùng trong compose file đi kèm tài liệu của container. Nếu tên của bạn khác, hãy dùng tên đó.

docker compose logs -f core

Chạy một lượt tìm kiếm bị lỗi trong khi đang theo dõi log. Bạn sẽ thấy một entry của engine bị lỗi xuất hiện khi lượt tìm kiếm chạy. Ghi lại tên engine và chuỗi lý do chính xác mà instance in ra. Không sao chép tên engine từ một bài blog, kể cả bài này. Danh sách engine gặp vấn đề với các địa chỉ datacenter thay đổi theo từng tháng. Engine bị lỗi trên instance của bạn có thể vẫn hoạt động bình thường trên instance của tác giả bài viết bạn đang đọc.

Nếu trang kết quả hoàn toàn không hiển thị lỗi nhưng có ít kết quả, hãy kiểm tra display_error_messages của engine đó. Giá trị mặc định là true. Instance đã tắt tùy chọn này sẽ ẩn chính thông báo bạn cần.

Cách SearXNG retry và tạm ngưng engine bị lỗi

SearXNG không liên tục gửi request đến một engine đã từ chối request. Engine bị lỗi sẽ bị tạm ngưng. Trong thời gian đó, engine bị bỏ qua hoàn toàn. Vì vậy, một engine bị hỏng sẽ trở thành engine âm thầm biến mất.

Có 2 lớp kiểm soát việc này. Cả 2 đều nằm trong search: ở settings.yml. Hãy đối chiếu các tên key này với tài liệu settings của đúng version bạn đang chạy trước khi dán cấu hình, vì chúng đã thay đổi giữa các release. Theo tài liệu ngày 2 September 2026, giá trị mặc định là:

search:
  ban_time_on_fail: 5
  max_ban_time_on_fail: 120
  suspended_times:
    SearxEngineAccessDenied: 86400
    SearxEngineCaptcha: 86400
    SearxEngineTooManyRequests: 3600
    cf_SearxEngineCaptcha: 1296000
    cf_SearxEngineAccessDenied: 86400
    recaptcha_SearxEngineCaptcha: 604800

Lớp đầu tiên xử lý các lỗi thông thường như timeout. Thời gian ban bắt đầu ở ban_time_on_fail giây và tăng sau mỗi lần lỗi liên tiếp, tối đa max_ban_time_on_fail. Mặc định, giới hạn là 2 phút. Vì vậy, một engine chập chờn sẽ tự hoạt động lại trong vài phút sau khi sự cố kết thúc.

Lớp thứ hai xử lý các lỗi được đề cập trong hướng dẫn này. Khi SearXNG nhận diện response là challenge hoặc refusal thay vì lỗi chung, nó áp dụng entry tương ứng từ suspended_times. Các giá trị này lớn hơn nhiều. 86400 giây là 1 ngày. 604800 giây là 1 tuần. 1296000 giây là 15 ngày. Các key có tiền tố cf_ được áp dụng khi challenge được nhận diện là challenge của Cloudflare. recaptcha_ được áp dụng khi challenge được nhận diện là reCAPTCHA.

Điều này giải thích triệu chứng gây mất nhiều thời gian nhất. Bạn tìm ra nguyên nhân, khắc phục nó, nhưng engine vẫn không trả về kết quả trong nhiều giờ. Engine vẫn đang bị tạm ngưng. Trạng thái tạm ngưng được giữ trong process đang chạy, nên restart container sẽ xóa trạng thái này. Lần search tiếp theo sẽ thử lại engine. Restart thông thường là đủ trong trường hợp này. Trước khi bắt đầu rebuild image không cần thiết, bạn nên biết khi nào restart là đủ và khi nào cần recreate container. Nếu engine lại lỗi ngay sau khi restart, cách khắc phục của bạn chưa có tác dụng.

Có một setting áp dụng riêng cho từng engine cần đặc biệt lưu ý. retry_on_http_error retry request khi engine trả về các status code mà bạn liệt kê. Với engine đang block bạn, việc retry sẽ gửi thêm network traffic đến hệ thống đã xác định server của bạn là bot. Hãy để setting này ở nguyên giá trị mặc định, trừ khi bạn đang xử lý một engine thực sự hoạt động không ổn định.

Tài liệu upstream về SSH tunnel và những gì nó không khắc phục được

Được kiểm tra vào ngày 2 September 2026, tài liệu quản trị SearXNG giải quyết vấn đề này bằng một tunnel thủ công. Bạn mở một SOCKS proxy thông qua server, cấu hình browser trên desktop sử dụng proxy đó, rồi tự trả lời challenge trong khi engine nhìn thấy địa chỉ của server.

ssh -q -N -D 8080 user@example.org

-D 8080 mở một SOCKS server cục bộ trên port 8080 và chuyển tiếp traffic qua kết nối SSH. -N không chạy command từ xa, còn -q giữ cho output im lặng, nên một tunnel hoạt động bình thường sẽ không in gì và không kết thúc. Kiểm tra tunnel từ một terminal thứ hai:

curl -x socks://127.0.0.1:8080 http://ipecho.net/plain
curl http://ipecho.net/plain

Command đầu tiên phải in ra địa chỉ của server, còn command thứ hai phải in ra địa chỉ desktop của bạn. Nếu hai kết quả giống nhau, request không đi qua tunnel. Sau đó, cấu hình network settings của browser để dùng SOCKS5 proxy tại 127.0.0.1 port 8080, mở cùng address checker trong browser để xác nhận nó báo địa chỉ của server, rồi truy cập engine đang yêu cầu bạn trả lời challenge. Trả lời challenge tại đó.

Bây giờ cần nói rõ các giới hạn. Có 4 yếu tố giới hạn phương pháp này. Cookie do engine cấp sẽ nằm trong browser trên desktop của bạn, còn SearXNG không có quyền truy cập cookie của browser. Vì vậy, thứ duy nhất có thể giúp instance của bạn là thông tin engine ghi nhận cho chính địa chỉ đó. Thông tin này sẽ hết hạn theo lịch do engine quyết định và không công bố. Quy trình không có phần nào được tự động hóa, nên lần sau bạn vẫn phải trực tiếp thao tác. Nếu instance được người khác sử dụng, query rate đã kích hoạt challenge vẫn tiếp tục, nên challenge sẽ xuất hiện lại.

Hãy dùng cách này để giúp một instance hoạt động trong hôm nay. Không nên xây dựng cả instance dựa trên nó.

Cách khắc phục lâu dài: tắt hoặc giảm trọng số các engine gây lỗi

Cách bền vững và ít tốn kém nhất là ngừng truy vấn một engine không thể phục vụ server của bạn. settings.yml bắt đầu bằng use_default_settings: true trong container image. Vì vậy, một mục trong engines: có name tương ứng sẽ chỉ ghi đè những key bạn khai báo và giữ nguyên các phần còn lại của định nghĩa mặc định.

use_default_settings: true

engines:
  - name: <engine name from your stats page>
    disabled: true
  - name: <another engine name>
    weight: 0.3

disabled: true tắt engine theo mặc định nhưng vẫn giữ engine trên trang tùy chọn. Người dùng cần engine này vẫn có thể tự bật lại cho các tìm kiếm của họ. inactive: true xóa engine hoàn toàn khỏi phần cài đặt người dùng. Đây là lựa chọn phù hợp với engine sẽ không bao giờ hoạt động từ địa chỉ của bạn. weight có tác dụng khác: tham số này điều chỉnh mức độ kết quả của engine được tính đến khi SearXNG gộp và xếp hạng kết quả. Vì vậy, trọng số nhỏ hơn 1 giúp giữ lại một engine hoạt động không ổn định mà không để nó chiếm các vị trí đầu tiên.

Sau khi chỉnh sửa, hãy restart container, thực hiện vài lượt tìm kiếm rồi kiểm tra lại /stats. Một trang thống kê sạch với sáu engine hoạt động hữu ích hơn một trang đầy lỗi với hai mươi engine.

Giải pháp bền vững: gửi request đi qua proxy

SearXNG có thể gửi các request đến engine qua proxy. Khi đó, địa chỉ mà engine nhìn thấy sẽ thay đổi. Đặt proxy dùng chung trong outgoing:, hoặc đặt riêng cho từng engine nếu chỉ một engine gặp vấn đề.

outgoing:
  request_timeout: 2.0
  extra_proxy_timeout: 10.0
  proxies:
    all://:
      - socks5h://user:password@proxy:1080

engines:
  - name: <engine name>
    proxies:
      http: socks5h://user:password@proxy:1080
      https: socks5h://user:password@proxy:1080

Ưu tiên socks5h:// thay vì socks5:// nếu bạn muốn proxy phân giải hostname. h khiến hostname được gửi đến proxy thay vì được phân giải trên server của bạn. Đồng thời, hãy tăng thời gian timeout. request_timeout mặc định là 2.0 giây. Proxy thêm một round trip vào mỗi request, nên những engine trước đây trả lời kịp thời có thể bắt đầu fail do timeout. extra_proxy_timeout được thiết kế cho trường hợp này và cộng thêm số giây khi đang dùng proxy.

Chi phí khi dùng proxy:

• Nhà vận hành proxy biết instance của bạn truy vấn những engine nào và vào thời điểm nào. TLS (transport layer security) giữ search terms không xuất hiện trong log của họ vì query nằm bên trong request đã được mã hóa. Tuy nhiên, họ vẫn xem được dạng và thời điểm của network traffic.
• Địa chỉ exit dùng chung sẽ được chia sẻ với những người khác cũng trả tiền cho địa chỉ đó. Nếu họ scrape, reputation của họ sẽ trở thành reputation của bạn, đôi khi nhanh hơn cả thời điểm block mà bạn đang cố tránh.
• Các pool residential proxy giá rẻ thường được xây dựng từ thiết bị của người dùng mà chủ sở hữu không hề biết hoặc không đồng ý cho chúng chuyển tiếp traffic. Hãy biết rõ bạn đang mua gì.
• using_tor_proxy: true định tuyến qua Tor, nhưng địa chỉ của exit node được công khai đầy đủ. Engine vốn chặn các dải địa chỉ datacentre thường cũng chặn exit node ít nhất nghiêm ngặt như vậy.
• Search giờ đây phụ thuộc vào một service bên ngoài server của bạn. Service đó có thể fail theo lịch riêng và khiến kết quả của bạn biến mất theo.

Proxy chuyển block sang nơi khác thay vì loại bỏ block. Ngoài ra, câu chuyện privacy của instance giờ bao gồm cả một bên thứ ba. Nếu privacy là lý do chính khiến bạn self-host, hãy cân nhắc điều đó với những gì instance self-host thực sự ẩn được và những gì không thể ẩn trước khi đăng ký bất kỳ dịch vụ nào.

Cách khắc phục bền vững: chủ động chạy một bộ engine nhỏ hơn

Lựa chọn mà hầu hết mọi người bỏ qua là chấp nhận dùng ít engine hơn. Giá trị của SearXNG nằm ở việc hợp nhất kết quả. Một tập hợp 6 engine phản hồi ổn định luôn tốt hơn 20 engine, trong đó một nửa bị tạm ngưng suốt nhiều ngày. Hãy theo dõi /stats trong một tuần và giữ lại những engine có lịch sử hoạt động ổn định từ địa chỉ của bạn.

Các engine yêu cầu xác thực bằng API key hoạt động khác, vì engine biết bạn là ai và áp dụng quota thay vì phải đoán bạn có phải người dùng hay không. Đổi lại, bạn cần một account, phải lưu key trong file cấu hình và thường phải trả phí. Với 1 hoặc 2 engine quan trọng với bạn, đây thường là cách ít rắc rối nhất.

Hãy quyết định dựa trên các tool khác mà bạn đang dùng. Một engine bị tạm ngưng sẽ không xuất hiện với bất kỳ thành phần nào đọc kết quả qua API, vì JSON API mà Open WebUI và các tool tương tự truy vấn chỉ trả về ít kết quả hơn thay vì trả về lỗi mà tool của bạn có thể phát hiện. Nếu có quy trình tự động phụ thuộc vào instance của bạn, hãy định kỳ gọi /stats/errors theo lịch thay vì chờ ai đó phàn nàn rằng chất lượng câu trả lời đã giảm.

Có đáng để cố xử lý việc này không?

Hãy trả lời bằng cách đếm số người dùng. Một instance chỉ dành cho một người sẽ gửi một số ít truy vấn mỗi ngày từ một địa chỉ, với tần suất mà nhiều search engine không bao giờ yêu cầu xác minh. Khi một engine yêu cầu xác minh, cách xử lý rất đơn giản: bỏ engine đó và bạn hầu như không nhận thấy nó đã biến mất. Đây là trải nghiệm thông thường khi chạy SearXNG cho nhu cầu cá nhân trên một VPS nhỏ, và bạn không cần tunnel hay proxy.

Một instance công khai hoặc dùng chung là một máy khác chạy cùng phần mềm. Tần suất truy vấn là yếu tố kích hoạt, và nó tăng theo từng người dùng bạn thêm vào, nên các yêu cầu xác minh sẽ xuất hiện nhanh hơn khả năng xử lý của mọi cấu hình. Hãy bắt đầu với một bộ engine nhỏ hơn, đồng thời nhớ rằng mọi proxy bạn thêm vào lúc này sẽ chuyển các truy vấn của người khác qua account của bạn.

Các client tự động nằm ở giữa nhưng có xu hướng gần với trường hợp khó hơn. Một agent thực hiện nhiều truy vấn để trả lời một câu hỏi sẽ tạo ra các đợt truy vấn mà con người không tạo ra, vì vậy một instance được dùng cho coding agent và công cụ nghiên cứu sẽ gặp yêu cầu xác minh sớm hơn instance được sử dụng thủ công. Nếu đây là nhu cầu của bạn, hãy chọn bộ engine dựa trên độ tin cậy thay vì độ rộng, và để agent làm việc với những kết quả mà nó thực sự lấy được.

Quy tắc chung là: hãy cố xử lý một engine khi đó là lý do bạn self-host, và bỏ nó khi không phải như vậy.

FAQ

Tại sao engine SearXNG vẫn không trả về kết quả sau khi tôi sửa lỗi?

Vì engine vẫn đang bị tạm ngưng. Khi SearXNG nhận diện challenge hoặc phản hồi từ chối của một engine, nó sẽ ngừng truy vấn engine đó trong khoảng thời gian được đặt tại search.suspended_times. Tùy loại từ chối, thời gian mặc định có thể từ một giờ đến mười lăm ngày. Trạng thái tạm ngưng được giữ trong process đang chạy, nên restart container sẽ xóa trạng thái này và lần tìm kiếm tiếp theo sẽ thử lại engine. Nếu engine tiếp tục fail ngay sau khi restart, bản sửa của bạn chưa có tác dụng.

Lỗi CAPTCHA của engine có giống lỗi 429 mà instance của tôi trả về không?

Hai lỗi này đi theo hai hướng ngược nhau. Lỗi 429 từ instance của bạn đến browser là do limiter của SearXNG quyết định request trông giống request tự động; bạn có thể tự cấu hình limiter này. Lỗi CAPTCHA hoặc lỗi block là do engine upstream từ chối server của bạn, dựa trên quyết định của hệ thống mà bạn không kiểm soát. Nếu trang kết quả vẫn tải được nhưng chỉ thiếu một số engine, bạn đang gặp trường hợp thứ hai.

VPN hoặc proxy trên server có khắc phục được CAPTCHA của engine không?

Đôi khi có, nhưng phải đánh đổi. Định tuyến request đi qua outgoing.proxies sẽ thay đổi địa chỉ mà engine nhìn thấy, có thể gỡ block gắn với dải địa chỉ của datacentre của bạn. Operator của proxy sẽ biết bạn truy vấn những engine nào và vào thời điểm nào. Địa chỉ exit dùng chung cũng có thể mang theo reputation của các customer khác. Ngoài ra, độ trễ tăng thêm có thể gây timeout nếu bạn không tăng request_timeout và extra_proxy_timeout. Tor có thể dùng thông qua using_tor_proxy, nhưng địa chỉ exit của Tor được công khai và thường xuyên bị challenge.

Tôi có thể để SearXNG tự động giải CAPTCHA không?

Không có setting nào cho việc này. Phương pháp được project hướng dẫn là thao tác thủ công: dùng SSH SOCKS tunnel, browser của bạn và tự xử lý challenge. Bất kỳ giải pháp nào bạn xây dựng để tự động trả lời challenge đều đi ngược policy của engine và sẽ âm thầm hỏng mỗi khi challenge thay đổi. Khi đó, bạn phải duy trì một scraper thay vì vận hành một search instance. Cách có hiệu quả lâu dài là xóa các engine đang block địa chỉ của bạn.