Private Search Gateway

Dieses Projekt ist ein deterministisches, selbst gehostetes Such- und Seitenabruf-Backend für KI-Frontends. Es stellt einen SearXNG-kompatiblen Such-Endpunkt bereit, entdeckt Quellen mit einer kleinen Anzahl von Suchmaschinen, öffnet die relevantesten Seiten, extrahiert deren tatsächliche Inhalte, folgt einer begrenzten Anzahl relevanter, seiteninterner Links, bewertet Beweise lokal neu und gibt zitierte Quell-URLs sowie aus den Seiten gewonnenen Text zurück.

Es ruft keine kostenpflichtige Such-API oder ein internes Sprachmodell auf. Das Modell des Frontends erhält die abgerufenen Beweise und verfasst die Antwort. Dies hält den Dienst privat, vorhersagbar und für jedes Frontend nutzbar, das einen benutzerdefinierten SearXNG- oder JSON-Suchprovider akzeptiert.

Was läuft

• search-gateway: der einzige clientseitige Dienst, auf internem Port 8080

• searxng: Web-, Technik-, Nachrichten-, Bild- und Forschungsentdeckung

• reranker: lokales BAAI/bge-reranker-base Relevanz-Ranking

• crawl4ai: JavaScript-fähiges Crawling für schwierige Seiten

• web-runner: isolierte Crawl4AI- und Playwright-Steuerung über einen Unix-Socket

• pdf-runner: netzwerksiolierte PDF-Extraktion

• safe-egress: blockiert private Netzwerk- und Metadatenziele für Browser

• redis: Antwort-Cache und Fallback bei veralteten Ergebnissen

Der Stack gibt keine Host-Ports frei. Ein Frontend erreicht ihn über ein gemeinsames Docker-Netzwerk unter:

http://search-gateway:8080/search

Jeder Container, der an dieses gemeinsame Netzwerk angeschlossen ist, kann das Gateway aufrufen. Verwenden Sie ein dediziertes gemeinsames Netzwerk, wenn andere, nicht zugehörige Container keinen Zugriff haben sollen.

Related MCP server: wigolo

Anforderungen

• 64-Bit-Linux-VPS

• Docker Engine und Docker Compose v2.24.4 oder neuer

• Etwa 10 GB freier Speicherplatz für Images, Chromium und das Reranker-Modell

• 16 GB RAM empfohlen für den vollständigen Stack

Die angegebenen Obergrenzen belaufen sich auf insgesamt etwa 10,5 GB, exklusive Shared Memory und normalem Docker-Overhead. Es handelt sich um Limits, nicht um Reservierungen, aber sie lassen auf einem 16-GB-Host nützlichen Spielraum. Der erste Build ist langsam, da Chromium, das Crawl4AI-Image und das Reranker-Modell heruntergeladen werden.

Saubere Installation

Erstellen Sie das Docker-Netzwerk einmalig, falls es noch nicht existiert:

docker network inspect docker-stacks_app-network >/dev/null 2>&1 || \
  docker network create docker-stacks_app-network

Klonen und konfigurieren Sie das Projekt:

git clone https://github.com/ZDOSt/Research-MCP.git
cd Research-MCP
cp .env.example .env
chmod 600 .env

Generieren Sie zwei verschiedene Geheimnisse:

openssl rand -hex 32
openssl rand -hex 32

Bearbeiten Sie .env und ersetzen Sie SEARXNG_SECRET und CRAWL4AI_API_TOKEN durch diese Werte. Ändern Sie CLIENT_DOCKER_NETWORK nur, wenn Ihr Frontend ein anderes externes Docker-Netzwerk verwendet.

Validieren und starten Sie den vollständigen Stack:

docker compose config --quiet
docker compose up -d --build --wait
docker compose ps

Es werden keine ports:-Einträge benötigt. Fügen Sie keinen hinzu, es sei denn, Sie möchten das Gateway absichtlich außerhalb von Docker verfügbar machen.

Überprüfung

Führen Sie einen Health-Check vom Gateway-Container aus durch:

docker compose exec -T search-gateway python -c \
  "import urllib.request; print(urllib.request.urlopen('http://127.0.0.1:8080/healthz').read().decode())"

Führen Sie eine echte Suche von einem beliebigen Container im gemeinsamen Netzwerk aus. Ersetzen Sie your-frontend-container durch anythingllm, librechat oder einen anderen Containernamen:

docker exec your-frontend-container sh -lc \
  "wget -qO- 'http://search-gateway:8080/search?q=how+to+install+docker+compose&format=json' | head -c 1000"

Die Antwort sollte results, Quell-URLs, extrahierten content und Diagnosedaten enthalten. Such-Snippets werden nur als klar gekennzeichneter Fallback verwendet, wenn eine Website die Extraktion blockiert oder das Anfrage-Deadline erreicht ist.

Frontend-Einrichtung

Verwenden Sie die folgende Basis-URL, wo das Frontend nach einer SearXNG-URL fragt:

http://search-gateway:8080

Wenn es nach dem vollständigen Suchpfad fragt, verwenden Sie:

http://search-gateway:8080/search

AnythingLLM benötigt den vollständigen Suchpfad, auch wenn sein Feld als SearXNG API Base URL beschriftet ist. Konfigurieren Sie es als:

http://search-gateway:8080/search

Die Standardanfrage ist:

GET /search?q=your+question&format=json

Unterstützte Abfrageparameter umfassen:

• language=auto

• time_range=day|week|month|year

• categories=general,it,news,science,images

• max_results=1..8

• mode=auto|quick|balanced|deep

Wenn keine Kategorie angegeben wird, leitet das Gateway nützliche SearXNG-Kategorien aus der Anfrage ab. auto verwendet den schnellen Modus für einfache Nachfragen und den ausgewogenen Modus für technische Fragen und Empfehlungen.

Für direkte Integrationen ist auch ein umfangreicherer JSON-Endpunkt verfügbar:

POST /v1/research
Content-Type: application/json

{
  "query": "What are the recommended settings for an AW3426DW?",
  "mode": "balanced",
  "max_results": 5,
  "language": "auto",
  "categories": []
}

Aktualisierung

Vom Repository-Verzeichnis auf dem VPS aus:

git pull --ff-only
docker compose config --quiet
docker compose up -d --build --remove-orphans --wait
docker compose ps

Sie müssen für ein normales Update nicht docker compose down ausführen. Vorhandener Redis-Cache und Reranker-Downloads bleiben in benannten Volumes erhalten.

Betrieb

Nützliche Befehle:

docker compose ps
docker compose logs --tail=200 search-gateway searxng reranker
docker compose logs --tail=200 crawl4ai web-runner safe-egress pdf-runner
docker compose restart search-gateway
docker compose down
docker compose up -d --wait

docker compose down bewahrt benannte Volumes. docker compose down -v löscht den Cache und das heruntergeladene Reranker-Modell und sollte nur für einen bewussten vollständigen Reset verwendet werden.

Einschränkungen

Dies kann an gehostete Suchtools für Dokumentation, Fehlerbehebung, Produkteinstellungen, Spiele, aktuelle Informationen und allgemeine Recherchen herankommen, kann aber nicht die gleiche Abdeckung wie kommerzielle Anbieter garantieren. Schlüssellose Suchmaschinen können Rechenzentrums-IPs drosseln, einige Websites blockieren alle automatisierten Browser, und kein einzelner VPS verfügt über die proprietären Suchindizes, die von Google, Brave oder kostenpflichtigen Antwortmaschinen verwendet werden. Das Gateway kompensiert dies mit mehreren Entdeckungsanbietern, gleichzeitiger Extraktion, lokalem Re-Ranking, begrenzten Browser-Fallbacks, Caching und ehrlichen Teilergebnissen, anstatt eine Antwort zu erfinden.