Elasticsearch/OpenSearch-Konnektor

Übersicht

Der Elasticsearch/OpenSearch-Konnektor bietet die Funktionalität, Daten aus Elasticsearch- oder OpenSearch-Clustern abzurufen und im Fess-Index zu registrieren.

Für diese Funktion ist das Plugin fess-ds-elasticsearch erforderlich.

Unterstützte Versionen

  • Elasticsearch 7.x / 8.x

  • OpenSearch 1.x / 2.x

Voraussetzungen

  1. Die Installation des Plugins ist erforderlich

  2. Lesezugriff auf den Elasticsearch/OpenSearch-Cluster ist erforderlich

  3. Berechtigungen zum Ausführen von Abfragen sind erforderlich

Plugin-Installation

Methode 1: JAR-Datei direkt platzieren

# Von Maven Central herunterladen
wget https://repo1.maven.org/maven2/org/codelibs/fess/fess-ds-elasticsearch/X.X.X/fess-ds-elasticsearch-X.X.X.jar

# Platzieren
cp fess-ds-elasticsearch-X.X.X.jar $FESS_HOME/app/WEB-INF/lib/
# oder
cp fess-ds-elasticsearch-X.X.X.jar /usr/share/fess/app/WEB-INF/lib/

Methode 2: Über die Administrationsoberfläche installieren

  1. Öffnen Sie „System“ -> „Plugins“

  2. Laden Sie die JAR-Datei hoch

  3. Starten Sie Fess neu

Konfiguration

Konfigurieren Sie über die Administrationsoberfläche unter „Crawler“ -> „Datenspeicher“ -> „Neu erstellen“.

Grundeinstellungen

Einstellung Beispielwert
Name External Elasticsearch
Handler-Name ElasticsearchDataStore / ElasticsearchListDataStore
Aktiviert Ein

Bemerkung

ElasticsearchListDataStore ist ein erweiterter Handler von ElasticsearchDataStore, der die abgerufenen Daten als Dateiliste verarbeitet und die Indexregistrierung in mehreren Threads unterstützt. Die Anzahl der Threads kann mit dem Parameter numOfThreads angegeben werden (Standard: 1).

Parameter-Einstellungen

Einfache Verbindung:

settings.http.hosts=http://localhost:9200
index=myindex
size=100
scroll=1m

Verbindung mit Authentifizierung:

settings.http.hosts=https://elasticsearch.example.com:9200
settings.fesen.username=elastic
settings.fesen.password=changeme
index=myindex
size=100
scroll=1m

Parameterliste

Zusätzliche Verbindungsparameter

Parameter mit dem Präfix settings. werden als Einstellungen des internen Elasticsearch/OpenSearch-Clients (fesen HTTP-Client) weitergegeben. Die wichtigsten zusätzlichen Einstellungen sind folgende:

Parameter Beschreibung
settings.http.ssl.certificate_authorities Pfad zur vertrauenswürdigen CA-Zertifikatsdatei (X.509-Format) für HTTPS-Verbindungen
settings.http.compression Ob HTTP-Komprimierung aktiviert werden soll (Standard: true)
settings.http.proxy_host Hostname des Proxyservers (settings.https.proxy_host ist ebenfalls möglich)
settings.http.proxy_port Portnummer des Proxyservers (settings.https.proxy_port ist ebenfalls möglich)
settings.http.proxy_username Benutzername für Proxy-Authentifizierung (settings.https.proxy_username ist ebenfalls möglich)
settings.http.proxy_password Passwort für Proxy-Authentifizierung (settings.https.proxy_password ist ebenfalls möglich)

Skript-Einstellungen

Einfaches Mapping:

url=source.url
title=source.title
content=source.content
last_modified=source.timestamp

Zugriff auf verschachtelte Felder:

url=source.metadata.url
title=source.title
content=source.body.content
author=source.author.name
created=source.created_at
last_modified=source.updated_at

Verfügbare Felder

  • source.<field_name> - _source-Feld des Elasticsearch-Dokuments

  • id - Dokument-ID

  • index - Indexname

  • score - Suchpunktzahl

  • version - Dokumentversion

  • seqNo - Sequenznummer

  • primaryTerm - Primärterm

  • clusterAlias - Cluster-Alias (für Cross-Cluster-Suche)

  • hit - SearchHit-Objekt (für fortgeschrittene Nutzung)

Query-Konfiguration

Alle Dokumente abrufen

Standardmäßig werden alle Dokumente abgerufen. Wenn der query-Parameter nicht angegeben wird, wird match_all verwendet.

Nach bestimmten Bedingungen filtern

query={"term":{"status":"published"}}

Bereichsangabe:

query={"range":{"timestamp":{"gte":"2024-01-01","lte":"2024-12-31"}}}

Mehrere Bedingungen:

query={"bool":{"must":[{"term":{"category":"news"}},{"range":{"views":{"gte":100}}}]}}

Bemerkung

Der query-Parameter akzeptiert nur den Query-Body. Der äußere {"query":...}-Wrapper ist nicht erforderlich. Such-level-Optionen wie Sortierung können in diesem Parameter nicht angegeben werden.

Nur bestimmte Felder abrufen

Abruffelder mit fields-Parameter einschränken

settings.http.hosts=http://localhost:9200
index=myindex
fields=title,content,url,timestamp
size=100

Um alle Felder abzurufen, fields nicht angeben oder leer lassen.

Anwendungsbeispiele

Einfaches Index-Crawling

Parameter:

settings.http.hosts=http://localhost:9200
index=articles
size=100
scroll=1m

Skript:

url=source.url
title=source.title
content=source.content
created=source.created_at
last_modified=source.updated_at

Crawling von Cluster mit Authentifizierung

Parameter:

settings.http.hosts=https://es.example.com:9200
settings.fesen.username=elastic
settings.fesen.password=changeme
index=products
size=200
scroll=10m

Skript:

url="https://shop.example.com/product/" + source.product_id
title=source.name
content=source.description + " " + source.specifications
digest=source.category
last_modified=source.updated_at

Crawling aus mehreren Indizes

Parameter:

settings.http.hosts=http://localhost:9200
index=logs-2024-*
query={"term":{"level":"error"}}
size=100

Skript:

url="https://logs.example.com/view/" + id
title=source.message
content=source.stack_trace
digest=source.service + " - " + source.level
last_modified=source.timestamp

OpenSearch-Cluster crawlen

Parameter:

settings.http.hosts=https://opensearch.example.com:9200
settings.fesen.username=admin
settings.fesen.password=admin
index=documents
size=100
scroll=1m

Skript:

url=source.url
title=source.title
content=source.body
last_modified=source.modified_date

Crawling mit eingeschränkten Feldern

Parameter:

settings.http.hosts=http://localhost:9200
index=myindex
fields=id,title,content,url,timestamp
size=100

Skript:

url=source.url
title=source.title
content=source.content
last_modified=source.timestamp

Lastverteilung über mehrere Hosts

Durch Angabe mehrerer Hosts kommagetrennt in settings.http.hosts werden Anfragen auf die einzelnen Hosts verteilt.

Parameter:

settings.http.hosts=http://es1.example.com:9200,http://es2.example.com:9200,http://es3.example.com:9200
index=articles
size=100
scroll=1m

Skript:

url=source.url
title=source.title
content=source.content
last_modified=source.timestamp

Fehlerbehebung

Verbindungsfehler

Symptom: Connection refused oder No route to host

Zu überprüfen:

  1. Überprüfen Sie, ob die Host-URL korrekt ist (Protokoll, Hostname, Port)

  2. Überprüfen Sie, ob Elasticsearch/OpenSearch läuft

  3. Überprüfen Sie die Firewall-Einstellungen

  4. Bei HTTPS überprüfen Sie, ob das Zertifikat gültig ist

Authentifizierungsfehler

Symptom: 401 Unauthorized oder 403 Forbidden

Zu überprüfen:

  1. Überprüfen Sie Benutzername und Passwort

  2. Überprüfen Sie, ob der Benutzer die entsprechenden Berechtigungen hat:

    • Leseberechtigung auf den Index

    • Berechtigung zur Verwendung der Scroll-API

  3. Bei Elasticsearch Security (X-Pack) überprüfen Sie, ob es korrekt konfiguriert ist

Index nicht gefunden

Symptom: index_not_found_exception

Zu überprüfen:

  1. Überprüfen Sie den Indexnamen (einschließlich Groß-/Kleinschreibung)

  2. Überprüfen Sie, ob der Index existiert:

    GET /_cat/indices

  3. Überprüfen Sie, ob das Wildcard-Muster korrekt ist (z.B.: logs-*)

Query-Fehler

Symptom: parsing_exception oder search_phase_execution_exception

Zu überprüfen:

  1. Überprüfen Sie, ob das Query-JSON korrekt ist

  2. Überprüfen Sie, ob die Query mit der Elasticsearch/OpenSearch-Version kompatibel ist

  3. Überprüfen Sie, ob die Feldnamen korrekt sind

  4. Testen Sie die Query direkt in Elasticsearch/OpenSearch:

    POST /myindex/_search
{
  "query": {...}
}

Scroll-Timeout

Symptom: No search context found oder Scroll timeout

Lösung:

  1. Erhöhen Sie scroll:

    scroll=10m

  2. Verringern Sie size:

    size=50

  3. Überprüfen Sie die Cluster-Ressourcen

Crawling großer Datenmengen

Symptom: Crawling ist langsam oder Timeout

Lösung:

  1. Passen Sie size an (zu groß kann langsam sein):

    size=100
size=500  # Größer

  2. Schränken Sie abzurufende Felder mit fields ein

  3. Filtern Sie mit query nur benötigte Dokumente

  4. Teilen Sie in mehrere Datenspeicher auf (nach Index, Zeitbereich usw.)

Speicherüberlauf

Symptom: OutOfMemoryError

Lösung:

  1. Verringern Sie size

  2. Schränken Sie abzurufende Felder mit fields ein

  3. Erhöhen Sie die Heap-Größe von Fess

  4. Schließen Sie große Felder aus (Binärdaten usw.)

SSL/TLS-Verbindung

Bei selbstsignierten Zertifikaten

Warnung

Verwenden Sie in Produktionsumgebungen ordnungsgemäß signierte Zertifikate.

Methode 1: CA-Zertifikat über den Parameter settings.http.ssl.certificate_authorities angeben (empfohlen)

Geben Sie den Pfad zur vertrauenswürdigen CA-Zertifikatsdatei (X.509-Format) an. Diese Methode hat keinen Einfluss auf den globalen Keystore von Fess.

settings.http.hosts=https://es.example.com:9200
settings.http.ssl.certificate_authorities=/path/to/es-cert.crt
index=myindex

Methode 2: Zertifikat zum Java Keystore hinzufügen

Fügen Sie das Zertifikat zum Truststore der JVM hinzu, die Fess startet.

keytool -import -alias es-cert -file es-cert.crt -keystore $JAVA_HOME/lib/security/cacerts

Verbindung über Proxy

Wenn die Verbindung über einen Proxyserver erfolgt, geben Sie settings.http.proxy_host und settings.http.proxy_port an.

settings.http.hosts=https://es.example.com:9200
settings.http.proxy_host=proxy.example.com
settings.http.proxy_port=8080
index=myindex

Erweiterte Query-Beispiele

Query mit Aggregationen

Bemerkung

Der query-Parameter akzeptiert nur den Query-Body. Aggregationen (aggs), Sortierung und andere Such-level-Optionen können nicht angegeben werden. Es werden nur Dokumente abgerufen.

Skript-Felder

Bemerkung

Elasticsearch/OpenSearch-Skriptfelder sind nicht in _source enthalten und können daher nicht über den source.*-Präfix zugegriffen werden. Um Skriptfelder zu verwenden, greifen Sie über das hit-Objekt mittels hit.getFields() zu.

Weiterführende Informationen