Index-Verwaltung

Übersicht

Von Fess verwaltete Daten werden als OpenSearch-Indizes verwaltet. Backup und Wiederherstellung von Suchindizes sind für den stabilen Systembetrieb unerlässlich. Dieser Abschnitt beschreibt Backup-, Wiederherstellungs- und Migrationsverfahren für Indizes mithilfe der OpenSearch-Snapshot-Funktion.

Bemerkung

Fess verfügt neben dem in diesem Abschnitt beschriebenen Index-Backup über OpenSearch-Snapshots auch über eine Funktion zum Export/Import von Konfigurationsdaten (Crawl-Einstellungen, Benutzerinformationen, Systemeinstellungen usw.) über die Verwaltungsoberfläche. Wenn Sie nur Konfigurationsdaten sichern oder migrieren möchten, siehe Sicherung. OpenSearch-Snapshots eignen sich für den physischen Backup eines gesamten Index einschließlich der Suchdokumente.

Index-Struktur

Fess verwendet folgende Indizes:

Indexname	Beschreibung
`fess.{Zeitstempel}`	Index für Suchdokumente. Wird beim Index-Neuaufbau im Format `fess.{yyyyMMddHHmmssSSS}` (Zeitstempel mit Millisekundengenauigkeit) erstellt und über die Aliase `fess.search` (für Suche) und `fess.update` (für Aktualisierungen) referenziert.
`fess_config.*`	Systemkonfigurationsdaten (bestehend aus mehreren Sub-Indizes wie `fess_config.web_config`, `fess_config.scheduled_job`, `fess_config.data_config` usw.)
`fess_user.*`	Benutzerinformationen (`fess_user.user`, `fess_user.role`, `fess_user.group`)
`fess_log.*`	Such- und Klickprotokolle sowie weitere Protokolle (`fess_log.search_log`, `fess_log.click_log`, `fess_log.favorite_log`, `fess_log.user_info`, `fess_log.notification_queue`)
`fess_crawler.*`	Temporäre Indizes, die während der Crawl-Verarbeitung verwendet werden (`fess_crawler.queue`, `fess_crawler.data`, `fess_crawler.filter`). Da diese nach Abschluss des Crawlings nicht mehr benötigt werden, müssen sie normalerweise nicht in das Backup einbezogen werden.
`configsync`	Inhalt der Wörterbuchdateien (Synonyme, Stoppwörter, Mappings usw.). Wird vom OpenSearch-Plugin configsync verwaltet, das ihn als Dateien unter `config/dictionary` von OpenSearch ausschreibt. Der Index für Suchdokumente und die Suggest-Indizes verweisen auf diese Dateien; nehmen Sie diesen Index daher immer in die Sicherung auf.

Warnung

Ein Snapshot enthält nur Indizes, nicht die Wörterbuchdateien unter config/dictionary von OpenSearch. Wurde der Index configsync nicht gesichert, fehlen die Wörterbuchdateien bei der Wiederherstellung in ein neues OpenSearch, und fess.{Zeitstempel} sowie fess_suggest_analyzer können wegen IOException while reading ..._path: file not readable nicht geöffnet werden (der Clusterstatus wird red).

Index-Backup und -Wiederherstellung

Mit der OpenSearch-Snapshot-Funktion können Sie Index-Backup und -Wiederherstellung durchführen.

Konfiguration des Snapshot-Repositorys

Konfigurieren Sie zunächst ein Repository zum Speichern der Backup-Daten.

Bei Dateisystem-Repository:

Fügen Sie den Repository-Pfad zur OpenSearch-Konfigurationsdatei (opensearch.yml) hinzu.

Starten Sie OpenSearch neu.
Registrieren Sie das Repository.

Bemerkung

Standardmäßig verbindet sich Fess mit OpenSearch auf Port 9200 (SEARCH_ENGINE_HTTP_URL in bin/fess.in.sh bei der ZIP-Version bzw. in der Umgebungskonfigurationsdatei /etc/sysconfig/fess (RPM) oder /etc/default/fess (DEB) bei den Paketen). Passen Sie die Portnummer an, wenn Ihr OpenSearch auf einem anderen Port lauscht.

Bei AWS-S3-Repository:

Wenn Sie S3 als Backup-Ziel verwenden möchten, installieren und konfigurieren Sie das Plugin repository-s3.

curl -X PUT "localhost:9200/_snapshot/fess_s3_backup" -H 'Content-Type: application/json' -d'
{
  "type": "s3",
  "settings": {
    "bucket": "my-fess-backup-bucket",
    "region": "ap-northeast-1",
    "base_path": "fess-snapshots"
  }
}'

Snapshot-Erstellung (Backup)

Backup aller Indizes

Alle Indizes sichern.

curl -X PUT "localhost:9200/_snapshot/fess_backup/snapshot_1?wait_for_completion=true" -H 'Content-Type: application/json' -d'
{
  "indices": "*",
  "ignore_unavailable": true,
  "include_global_state": false
}'

Backup bestimmter Indizes

Nur bestimmte Indizes sichern. Das folgende Beispiel bezieht sich auf die Fess-bezogenen Indizes (Indizes, die mit fess beginnen) und den Index configsync, der die Wörterbuchdateien enthält. Ohne configsync lassen sich die Wörterbuchdateien nicht wiederherstellen.

curl -X PUT "localhost:9200/_snapshot/fess_backup/snapshot_fess_only?wait_for_completion=true" -H 'Content-Type: application/json' -d'
{
  "indices": "fess*,configsync",
  "ignore_unavailable": true,
  "include_global_state": false
}'

Regelmäßiges automatisches Backup

Mit cron oder ähnlichen Tools können Sie regelmäßige Backups einrichten.

#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
curl -X PUT "localhost:9200/_snapshot/fess_backup/snapshot_${DATE}?wait_for_completion=true" -H 'Content-Type: application/json' -d'
{
  "indices": "*",
  "ignore_unavailable": true,
  "include_global_state": false
}'

Snapshot-Überprüfung

Liste der erstellten Snapshots anzeigen.

Details zu einem bestimmten Snapshot anzeigen.

Wiederherstellung aus Snapshot

Wiederherstellung aller Indizes

Stellen Sie zuerst den Index configsync wieder her und schreiben Sie die Wörterbuchdateien aus; stellen Sie danach die Fess-Indizes (fess*) wieder her. Führen Sie die Wiederherstellung bei gestopptem Fess aus.

Eine Wiederherstellung aller Indizes auf einmal mit "indices": "*" ist nicht möglich. OpenSearch legt Indizes wie configsync beim Start selbst an, daher schlägt die Wiederherstellung auch auf einem neuen OpenSearch mit cannot restore index [configsync] because an open index with same name already exists in the cluster fehl. Nur fess* wiederherzustellen genügt ebenfalls nicht: Ohne die Wörterbuchdateien können fess.{Zeitstempel} und fess_suggest_analyzer nicht geöffnet werden, der Cluster wird red, und ein dagegen gestartetes Fess startet nicht (jede Seite liefert 404).

Löschen Sie den leeren Index configsync, den das configsync-Plugin beim Start angelegt hat, und stellen Sie configsync aus dem Snapshot wieder her.

curl -X DELETE "localhost:9200/configsync"

curl -X POST "localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true" -H 'Content-Type: application/json' -d'
{
  "indices": "configsync",
  "include_global_state": false
}'

Starten Sie OpenSearch neu (in einem Cluster mit mehreren Knoten alle Knoten). Sobald der Index configsync verfügbar ist, schreiben Sie die wiederhergestellten Wörterbücher nach config/dictionary von OpenSearch aus.

Bemerkung

Mit dem configsync-Plugin 3.8.0 und älter schreibt _configsync/flush nur die Dateien aus, die registriert wurden, nachdem der Knoten zuletzt einen Schreibvorgang (planmäßig oder _configsync/flush) gestartet hat. Die wiederhergestellten configsync-Dateien tragen den Zeitpunkt, zu dem sie auf dem Cluster registriert wurden, von dem der Snapshot stammt. Sobald der erste planmäßige Schreibvorgang etwa eine Minute nach dem Start von OpenSearch gelaufen ist, schreibt _configsync/flush ohne Neustart daher keine Wörterbuchdateien aus, und der Cluster wird nach Schritt 3 red. Ein Neustart setzt diesen Zeitpunkt zurück, sodass _configsync/flush nach dem Neustart alle Wörterbuchdateien ausschreibt. Für jede ausgeschriebene Datei protokolliert OpenSearch Updated {Dateipfad} von ConfigSyncService.

Stellen Sie die Fess-Indizes wieder her.

curl -X POST "localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true" -H 'Content-Type: application/json' -d'
{
  "indices": "fess*",
  "ignore_unavailable": true,
  "include_global_state": false
}'

Vergewissern Sie sich, dass der Clusterstatus green ist (yellow, wenn Replikate nicht zugewiesen werden können), und starten Sie dann Fess.

Bemerkung

Wenn Sie in einem laufenden Cluster unter denselben Indexnamen wiederherstellen, schlägt die Wiederherstellung für jeden geöffneten Index fehl. Schließen Sie die Zielindizes (_close) vor Schritt 3.

Wiederherstellung bestimmter Indizes

Der Index für Suchdokumente hat einen Namen im Format fess.{yyyyMMddHHmmssSSS}. Prüfen Sie den tatsächlichen Indexnamen z. B. über _cat/indices, bevor Sie die Wiederherstellung durchführen.

curl -X POST "localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true" -H 'Content-Type: application/json' -d'
{
  "indices": "fess.20250101000000000",
  "ignore_unavailable": true,
  "include_global_state": false
}'

Wiederherstellung mit umbenennen des Index

Beim Wiederherstellen kann der Indexname geändert werden.

curl -X POST "localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true" -H 'Content-Type: application/json' -d'
{
  "indices": "fess.20250101000000000",
  "rename_pattern": "fess\\.(.+)",
  "rename_replacement": "restored_fess.$1",
  "ignore_unavailable": true,
  "include_global_state": false
}'

Bemerkung

Wenn Sie den Index für Suchdokumente (fess.{Zeitstempel}) wiederhergestellt haben, stellen Sie unbedingt sicher, dass die Aliase fess.search und fess.update auf den wiederhergestellten Index zeigen. Da Snapshots auch Alias-Informationen enthalten, werden Aliase bei einer Wiederherstellung aller Indizes mit unverändertem Namen normalerweise ebenfalls wiederhergestellt. Wenn Sie den Indexnamen jedoch über rename_pattern geändert haben oder zu einem anderen Cluster migrieren, werden die Aliase möglicherweise nicht korrekt gesetzt. Setzen Sie die Aliase in diesem Fall manuell neu (ersetzen Sie den Indexnamen durch den tatsächlichen Namen):

curl -X POST "localhost:9200/_aliases" -H 'Content-Type: application/json' -d'
{
  "actions": [
    { "add": { "index": "restored_fess.20250101000000000", "alias": "fess.search" } },
    { "add": { "index": "restored_fess.20250101000000000", "alias": "fess.update" } }
  ]
}'

Snapshot-Löschung

Alte Snapshots können gelöscht werden, um Speicherplatz zu sparen.

Backup von Konfigurationsdateien

Sichern Sie zusätzlich zu den OpenSearch-Indizes auch die folgenden Konfigurationsdateien. Der Speicherort der Konfigurationsdateien hängt von der Installationsmethode ab.

Zu sichernde Dateien

Datei/Verzeichnis	Installationsmethode	Beschreibung
`app/WEB-INF/conf/system.properties`	ZIP	Systemkonfiguration (allgemeine Einstellungen)
`/etc/fess/system.properties`	RPM/DEB	Systemkonfiguration (allgemeine Einstellungen)
`app/WEB-INF/classes/fess_config.properties`	ZIP	Detaillierte Fess-Konfiguration
`/etc/fess/fess_config.properties`	RPM/DEB	Detaillierte Fess-Konfiguration
`app/WEB-INF/classes/log4j2.xml`	ZIP	Protokollkonfiguration
`/usr/share/fess/app/WEB-INF/classes/log4j2.xml`	RPM/DEB	Protokollkonfiguration
`app/WEB-INF/classes/fess_indices/`	ZIP	Index-Definitionsdateien
`/usr/share/fess/app/WEB-INF/classes/fess_indices/`	RPM/DEB	Index-Definitionsdateien
`app/WEB-INF/thumbnails/`	ZIP	Vorschaubilder (bei Bedarf)
`/var/lib/fess/thumbnails/`	RPM/DEB	Vorschaubilder (bei Bedarf)

Bemerkung

Bei der RPM/DEB-Paketversion befinden sich im Verzeichnis /etc/fess/ neben fess_config.properties auch Konfigurationsdateien wie fess_env_crawler.properties und weitere fess_env_*.properties-Dateien sowie tika.xml. Es wird empfohlen, das gesamte Verzeichnis /etc/fess/ zu sichern. Die Datei system.properties wird als /etc/fess/system.properties erstellt bzw. aktualisiert, wenn Einstellungen unter „System > Allgemein“ in der Verwaltungsoberfläche gespeichert werden.

Beispiel für das Backup von Konfigurationsdateien

Das folgende Beispiel zeigt das Backup von Konfigurationsdateien bei der RPM/DEB-Paketversion.

#!/bin/bash
BACKUP_DIR="/backup/fess/$(date +%Y%m%d_%H%M%S)"
mkdir -p ${BACKUP_DIR}

# Konfigurationsdateien kopieren (einschließlich system.properties, fess_config.properties usw.)
cp -r /etc/fess/ ${BACKUP_DIR}/

# Index-Definitionsdateien und Protokollkonfiguration
cp -r /usr/share/fess/app/WEB-INF/classes/fess_indices/ ${BACKUP_DIR}/
cp /usr/share/fess/app/WEB-INF/classes/log4j2.xml ${BACKUP_DIR}/

# Optional: Vorschaubilder
# cp -r /var/lib/fess/thumbnails/ ${BACKUP_DIR}/

echo "Backup completed: ${BACKUP_DIR}"

Datenmigration

Migrationsverfahren in eine andere Umgebung

Backup in der Quellumgebung erstellen
- Erstellen Sie einen OpenSearch-Snapshot.
- Sichern Sie die Konfigurationsdateien.
Zielumgebung vorbereiten
- Installieren Sie Fess in der neuen Umgebung.
- Starten Sie OpenSearch.
Konfigurationsdateien wiederherstellen
- Kopieren Sie die gesicherten Konfigurationsdateien in die neue Umgebung.
- Passen Sie Pfade, Hostnamen usw. bei Bedarf an.
Indizes wiederherstellen
- Konfigurieren Sie das Snapshot-Repository.
- Stellen Sie gemäß „Wiederherstellung aller Indizes“ zuerst configsync wieder her und schreiben Sie die Wörterbuchdateien aus; stellen Sie danach die Fess-Indizes wieder her.
- Vergewissern Sie sich nach der Wiederherstellung, dass die Aliase fess.search und fess.update auf den wiederhergestellten Index zeigen.
- Vergewissern Sie sich, dass der Clusterstatus green (oder yellow) ist. Wird Fess bei Clusterstatus red gestartet, schlägt der Start fehl.
Funktionstest
- Starten Sie Fess.
- Öffnen Sie die Verwaltungsoberfläche und überprüfen Sie die Einstellungen.
- Überprüfen Sie, ob die Suchfunktion ordnungsgemäß funktioniert.

Hinweise beim Versionsupgrade

Beachten Sie beim Migrieren von Daten zwischen verschiedenen Versionen von Fess folgende Punkte:

Bei unterschiedlichen OpenSearch-Hauptversionen können Kompatibilitätsprobleme auftreten.
Wenn sich die Index-Struktur geändert hat, kann eine Neuindizierung erforderlich sein.
Wenn Sie Konfigurationsdaten über eine Änderung der Index-Struktur hinweg migrieren möchten, erwägen Sie die Verwendung der Backup-Funktion der Verwaltungsoberfläche (Sicherung) für einen logischen Export/Import anstelle von OpenSearch-Snapshots.
Weitere Einzelheiten finden Sie im Upgrade-Leitfaden der jeweiligen Version.

Fehlerbehebung

Snapshot-Erstellung schlägt fehl

Überprüfen Sie die Berechtigungen für den Repository-Pfad.
Überprüfen Sie, ob ausreichend Speicherplatz vorhanden ist.
Prüfen Sie die OpenSearch-Protokolldateien auf Fehlermeldungen.

Wiederherstellung schlägt fehl

Überprüfen Sie, ob bereits ein Index mit demselben Namen vorhanden ist. In OpenSearch kann keine Wiederherstellung auf einen geöffneten Index mit demselben Namen durchgeführt werden. Schließen Sie den betreffenden Index vor der Wiederherstellung (_close) oder löschen Sie ihn, oder stellen Sie ihn über rename_pattern unter einem anderen Namen wieder her.
Überprüfen Sie, ob die OpenSearch-Version kompatibel ist.
Überprüfen Sie, ob der Snapshot beschädigt ist.

Cluster ist nach der Wiederherstellung red

Wenn der Clusterstatus nach der Wiederherstellung von fess* red ist und Folgendes auftritt, fehlen die Wörterbuchdateien.

_cluster/allocation/explain meldet IOException while reading mappings_path: file not readable (oder keywords_path usw.)
Beim Start von Fess zeigt fess.log Failed to initialize Lasta Di (eine NullPointerException in init von SuggestHelper), und jede Seite liefert 404

Weder _cluster/reroute?retry_failed=true noch das Bereitstellen der Wörterbuchdateien behebt das: Ein Shard, dessen Wiederherstellung fehlgeschlagen ist, wird erst wieder zugewiesen, wenn sein Index geschlossen oder gelöscht und erneut wiederhergestellt wird. Gehen Sie wie folgt vor.

Folgen Sie den Schritten 1 und 2 unter „Wiederherstellung aller Indizes“, um configsync wiederherzustellen, OpenSearch neu zu starten und die Wörterbuchdateien auszuschreiben.

Listen Sie die Indizes mit Status red auf.

Schließen Sie die Indizes mit Status red und stellen Sie sie erneut aus dem Snapshot wieder her (ersetzen Sie die Indexnamen durch die tatsächlichen).

curl -X POST "localhost:9200/fess.20250101000000000,fess_suggest_analyzer/_close"

curl -X POST "localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true" -H 'Content-Type: application/json' -d'
{
  "indices": "fess.20250101000000000,fess_suggest_analyzer",
  "include_global_state": false
}'

Nach der Wiederherstellung ist keine Suche möglich

Überprüfen Sie, ob der Index ordnungsgemäß wiederhergestellt wurde: curl -X GET "localhost:9200/_cat/indices?v"
Überprüfen Sie, ob die Aliase fess.search und fess.update auf den wiederhergestellten Index zeigen: curl -X GET "localhost:9200/_cat/aliases?v". Falls die Aliase nicht gesetzt sind, setzen Sie sie über die _aliases-API neu.
Prüfen Sie die Fess-Protokolldateien auf Fehler.
Überprüfen Sie, ob die Konfigurationsdateien korrekt wiederhergestellt wurden.

Referenzinformationen

Für detaillierte Informationen siehe die offizielle OpenSearch-Dokumentation.

Index-Verwaltung

Übersicht

Index-Struktur

Index-Backup und -Wiederherstellung

Konfiguration des Snapshot-Repositorys

Snapshot-Erstellung (Backup)

Backup aller Indizes

Backup bestimmter Indizes

Regelmäßiges automatisches Backup

Snapshot-Überprüfung

Wiederherstellung aus Snapshot

Wiederherstellung aller Indizes

Wiederherstellung bestimmter Indizes

Wiederherstellung mit umbenennen des Index

Snapshot-Löschung

Backup von Konfigurationsdateien

Zu sichernde Dateien

Beispiel für das Backup von Konfigurationsdateien

Datenmigration

Migrationsverfahren in eine andere Umgebung

Hinweise beim Versionsupgrade

Fehlerbehebung

Snapshot-Erstellung schlägt fehl

Wiederherstellung schlägt fehl

Cluster ist nach der Wiederherstellung red

Nach der Wiederherstellung ist keine Suche möglich

Verwandte Themen

Referenzinformationen