Jak hostować SearXNG samodzielnie w 2026 roku: Search API, limity zapytań i TLS

Większość instrukcji instalacji SearXNG kończy się na pierwszym załadowaniu strony. To zbyt wcześnie: silniki mogą blokować IP serwera albo formaty mogą pomijać json dla klientów API. Przydatny test produkcyjny jest bardziej wymagający — wyślij zapytania zarówno w HTML, jak i JSON, potwierdź, że kilka silników dostarcza wyniki, oraz wywołaj skonfigurowany limiter z poziomu klienta testowego.

Rola SearXNG jest prosta: to metawyszukiwarka skoncentrowana na prywatności oraz search API. Jego zakres operacyjny obejmuje więcej niż sam proces webowy, dlatego przed pojawieniem się prawdziwych danych trzeba jawnie określić zależność, przechowywany stan i publiczną trasę.

Najpierw zdefiniuj kryteria sukcesu dla SearXNG

Nie pozwól, aby obraz SearXNG przypadkowo narzucił architekturę produkcyjną. Obraz dostarcza proces działający na porcie 8080, ale storage, routing i wymagania zewnętrzne nadal potrzebują świadomie zaplanowanych cykli życia. Kontrakt sieciowy SearXNG obejmuje Redis lub Valkey, gdy włączone są funkcje limitera i wykrywania botów. Prywatne endpointy trzymaj w internal DNS, zezwalaj tylko na wymagane połączenia wychodzące i nadaj SearXNG ograniczone uprawnienia service credential.

Deployment jest gotowy do dokładniejszych testów, gdy potrafi wysłać zapytania zarówno w HTML, jak i JSON, potwierdzić, że kilka silników dostarcza wyniki, oraz wywołać skonfigurowany limiter z poziomu klienta testowego. Śledź transakcję w logach i monitoruj latency upstream engines, jednoczesne zapytania, parsowanie wyników oraz bany nakładane na IP serwera. Te obserwacje pokażą, czy obecna topologia izoluje właściwy komponent.

Oddziel kontenery, które można wymieniać, od trwałych danych

Przygotuj dla SearXNG manifest odzyskiwania: settings.yml, konfigurację limitera i wszystkie lokalne pluginy. Zamontuj /etc/searxng przed bootstrapem, zapisz nieszkodliwe dane przykładowe i wymień kontener, aby potwierdzić, że ta ścieżka rzeczywiście jest persistent. Sprawdź teraz ownership i wolne miejsce, ponieważ zamontowana, ale niezapisywalna ścieżka w praktyce zachowuje się tak, jakby persistence w ogóle nie było.

Twórz backupy w failure domain oddzielonym od działającego serwera. Odtwórz SearXNG z przypiętego obrazu i sprawdź, czy wracają custom engines, formaty, reguły limitera i ustawienia proxy oraz czy znane zapytanie zwraca wyniki z wielu silników. Przewodnik po persistent volumes pomoże przełożyć to ćwiczenie na politykę snapshotów i retencji.

Zamknij tymczasowy dostęp konfiguracyjny

Dane uwierzytelniające używane podczas bootstrapu są tymczasowe, ale model zaufania pozostaje na stałe. W przypadku SearXNG zwróć uwagę, aby nie wdrożyć przykładowego secret_key ani nie wyłączyć kontroli rate limitów na publicznym endpoincie. Zachowaj nie-domyślny secret key, włącz mechanizmy ochrony przed nadużyciami i udostępniaj JSON tylko wtedy, gdy wymaga tego agent lub aplikacja.

Traktuj SEARXNG_SECRET zgodnie z jego rolą w SearXNG: przechowuj wrażliwe wartości poza Gitem, udokumentuj skutki rotacji i nigdy nie zastępuj produkcyjnej wartości publicznym przykładem. Uruchamiaj obraz bez niepotrzebnych capabilities systemu Linux i wystawiaj wyłącznie publiczną trasę aplikacji. Zapewnij widoczność aktywności administratorów, ale nie zapisuj wartości sekretów.

Zapisz poprawny deployment SearXNG

Przekształć smoke test SearXNG w powtarzalną komendę release albo krótką runbook. Wynik musi potwierdzać następujący rezultat: wyślij zapytania zarówno w HTML, jak i JSON, potwierdź, że kilka silników dostarcza wyniki, oraz wywołaj skonfigurowany limiter z poziomu klienta testowego. Zapisz razem z wynikiem wersję aplikacji, digest kontenera, hostname trasy i identyfikator danych testowych.

Uruchom tę samą kontrolę po standardowej wymianie kontenera oraz po odtworzeniu settings.yml, konfiguracji limitera i wszystkich lokalnych pluginów w innym miejscu. Restore zakończył się powodzeniem, gdy wracają custom engines, formaty, reguły limitera i ustawienia proxy oraz gdy znane zapytanie zwraca wyniki z wielu silników. Porównaj timing i zużycie związane z latency upstream engines, jednoczesnymi zapytaniami, parsowaniem wyników oraz banami nakładanymi na IP serwera; duża zmiana zasługuje na analizę, nawet jeśli końcowa akcja nadal przechodzi.

Następnie przeprowadź bezpieczny test awarii: tymczasowo odbierz testowej tożsamości dostęp do Redis lub Valkey, gdy włączone są funkcje limitera i wykrywania botów. Potwierdź, że SearXNG sygnalizuje błąd i wraca do normalnego działania bez destrukcyjnych ręcznych zmian. Zachowaj tylko niezbędny, zredagowany fragment logu. Ten czteroczęściowy gate obejmuje uruchamianie, persistence, odtwarzanie i obsługę awarii.

Uruchom pierwszą instancję zbliżoną do produkcyjnej

Traktuj kontener jako wymienny runtime, a nie jako miejsce przechowywania źródła prawdy.

docker run -d \
  --name searxng \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v searxng-data:/etc/searxng \
  -e SEARXNG_SECRET=replace-with-a-long-random-value \
  searxng/searxng:latest

Dodaj sprawdzone ustawienia połączenia z Redis lub Valkey, gdy włączone są funkcje limitera i wykrywania botów; dla prywatnych usług używaj prywatnych nazw. Przed wystawieniem usługi sprawdź użytkownika kontenera, zapisywalne ścieżki i nasłuchujący listener. Wykonaj pełną akcję — wyślij zapytania zarówno w HTML, jak i JSON, potwierdź, że kilka silników dostarcza wyniki, oraz wywołaj skonfigurowany limiter z poziomu klienta testowego — i zachowaj dokładne odwołanie do obrazu, który zwrócił wynik.

Nie pozwól, aby sukces proxy maskował awarię aplikacji

Udostępnij dla SearXNG jeden hostname HTTPS, a surowy port 8080 pozostaw prywatny. Ustaw server base_url i trusted proxy headers dla HTTPS. Dzięki temu przeglądarki i klienci API nie poznają dwóch konkurencyjnych adresów.

Z czystego klienta uruchom sprawdzoną transakcję i przeanalizuj pierwsze żądanie, które kończy się błędem. Użyj przewodnika po custom domain, gdy problem dotyczy DNS lub TLS. Traktuj komunikat „silniki blokują IP serwera albo formaty pomijają json dla klientów API” jako osobną diagnozę aplikacji dopiero po potwierdzeniu, że routing działa prawidłowo.

Logi, które odpowiadają na następne pytanie

Pierwszą przydatną metryką operacyjną dla SearXNG jest to, czy potrafi wysłać zapytania zarówno w HTML, jak i JSON, potwierdzić, że kilka silników dostarcza wyniki, oraz wywołać skonfigurowany limiter z poziomu klienta testowego. Połącz ją z sygnałami przeciążenia dotyczącymi latency upstream engines, jednoczesnych zapytań, parsowania wyników i banów nakładanych na IP serwera. Probe sprawdzający wyłącznie proces nie powinien wywoływać kosztownych zależności ani restartować kontenera tylko dlatego, że upstream jest chwilowo niedostępny.

Traktuj aktualizacje jak zmiany danych, ponieważ składnia settings, definicje silników i działanie limitera mogą się zmieniać, dlatego konfigurację i zmiany obrazu wdrażaj w ramach jednego review. Przypinaj wersje, przeprowadzaj próby na odtworzonym stanie i zachowuj poprzedni obraz, dopóki rollback pozostaje możliwy. Gdy silniki blokują IP serwera albo formaty pomijają json dla klientów API, zachowaj logi z okresu przed restartem; zwykle zawierają komunikat wskazujący przyczynę.

Podłącz SearXNG do cyklu życia Dockup

Warstwa platformowa dla SearXNG składa się z portu 8080, ingressu, TLS, konfiguracji runtime, storage oraz osiągalności zależności. Dockup może odtworzyć te elementy dla własnej infrastruktury lub serwera podłączonego przez klienta.

Następnie operator kończy konfigurację warstwy produktu: ustawia server base_url i trusted proxy headers dla HTTPS; egzekwuje tę regułę dostępu — zachowaj nie-domyślny secret key, włącz mechanizmy ochrony przed nadużyciami i udostępniaj JSON tylko wtedy, gdy wymaga tego agent lub aplikacja; oraz uruchamia „wyślij zapytania zarówno w HTML, jak i JSON, potwierdź, że kilka silników dostarcza wyniki, oraz wywołaj skonfigurowany limiter z poziomu klienta testowego”. Zapisanie tego testu razem z deploymentem pozwala uniknąć mylenia automatycznego provisioningu z gotowością aplikacji.

Najczęściej zadawane pytania

Czego SearXNG potrzebuje do wdrożenia produkcyjnego?

Skieruj kontener SearXNG działający na porcie 8080 przez jeden origin HTTPS. Wymaganiem sieciowym dla obsługi limitera i wykrywania botów jest Redis lub Valkey. Nie uznawaj SearXNG za gotowy, dopóki nie możesz wysłać zapytań zarówno w HTML, jak i JSON, potwierdzić, że kilka silników dostarcza wyniki, oraz wywołać skonfigurowanego limitera z poziomu klienta testowego.

Które dane SearXNG powinny znaleźć się w backupie?

Utrwal /etc/searxng i uwzględnij settings.yml, konfigurację limitera oraz wszystkie lokalne pluginy w tym samym manifeście odzyskiwania. Czysty restore SearXNG kończy się powodzeniem tylko wtedy, gdy wracają custom engines, formaty, reguły limitera i ustawienia proxy oraz gdy znane zapytanie zwraca wyniki z wielu silników.

Czy SearXNG wymaga HTTPS za reverse proxy?

Używaj HTTPS dla publicznego origina SearXNG, a port 8080 pozostaw na trasie wewnętrznej. Zastosuj poprawnie ustawienie SearXNG: ustaw server base_url i trusted proxy headers dla HTTPS. W przypadku SearXNG HTTPS chroni dane uwierzytelniające lub treści użytkowników podczas przesyłania i zapewnia spójne działanie klienta zależne od origina.

Jak testować aktualizację SearXNG?

Odtwórz bieżący stan SearXNG w odizolowanym deploymencie, zastosuj wersję kandydującą i powtórz transakcję akceptacyjną. Zwróć szczególną uwagę na to, że składnia settings, definicje silników i działanie limitera mogą się zmieniać, dlatego konfigurację i zmiany obrazu wdrażaj w ramach jednego review. Zachowaj poprzedni obraz SearXNG, dopóki nie poznasz granic migracji danych i rollbacku.