diff --git a/de/15.8/install/upgrade.rst b/de/15.8/install/upgrade.rst index 760db784..56115b39 100644 --- a/de/15.8/install/upgrade.rst +++ b/de/15.8/install/upgrade.rst @@ -21,6 +21,13 @@ Dieses Upgrade-Verfahren unterstützt Upgrades zwischen folgenden Versionen: - Fess 14.x → Fess 15.8 - Fess 15.x → Fess 15.8 +.. important:: + + |Fess| 14.x unterstützt OpenSearch der 2.x-Reihe, |Fess| 15.8 unterstützt OpenSearch 3.8.0. + Da die OpenSearch-Plugins für |Fess| exakt mit der OpenSearch-Version übereinstimmen müssen, + ist beim Upgrade von 14.x auch ein Major-Version-Upgrade von OpenSearch zwingend erforderlich. + Siehe :ref:`upgrade-opensearch`. + .. note:: Bei Upgrades von älteren Versionen (13.x oder früher) kann ein stufenweises Upgrade erforderlich sein. @@ -35,7 +42,7 @@ Vorbereitung vor dem Upgrade Überprüfen Sie die Kompatibilität zwischen der Zielversion und der aktuellen Version des Upgrades. - `Release Notes `__ -- `Upgrade-Leitfaden `__ +- :doc:`prerequisites` - Systemvoraussetzungen für |Fess| 15.8 (Java- und OpenSearch-Version) Planung der Ausfallzeit ------------------------ @@ -62,19 +69,33 @@ Backup der Konfigurationsdaten Melden Sie sich in der Verwaltungsseite an und klicken Sie auf „Systeminformationen" → „Sicherung". Auf der Sicherungsseite werden die folgenden Konfigurationsdaten als einzelne Einträge aufgelistet. - Klicken Sie auf jeden Link, um die jeweilige Datei herunterzuladen (keine einzelne ZIP-Datei, sondern eine individuelle Datei pro Eintrag). - - - ``fess_basic_config.bulk`` - Grundkonfiguration (allgemeine Einstellungen) - - ``fess_config.bulk`` - Crawl-Einstellungen, Scheduler, Labels, Key-Matches und weitere Konfigurationsdaten + Klicken Sie auf die jeweilige Zeile, um sie herunterzuladen (keine einzelne ZIP-Datei, sondern eine + individuelle Datei pro Eintrag. Eine Sammel-Download-Funktion gibt es nicht, laden Sie die + benötigten Einträge daher einzeln herunter). + + - ``fess_basic_config.bulk`` - Konfigurationsindizes (Crawl-Einstellungen, Scheduler, Labels, + Key-Matches, Rollen, Web-/Datei-Authentifizierung usw., 19 Indizes) + - ``fess_config.bulk`` - zusätzlich zu den oben genannten 19 Indizes Laufzeitdaten wie + Crawl-Informationen, fehlgeschlagene URLs, Job-Protokolle und Thumbnail-Warteschlange, + insgesamt 25 Indizes - ``fess_user.bulk`` - Benutzer, Rollen und Gruppen - - ``system.properties`` - Systemeinstellungen - - ``fess.json`` / ``doc.json`` - Indexeinstellungen (Mappings) + - ``system.properties`` - Systemeinstellungen einschließlich der allgemeinen Einstellungen + - ``fess.json`` - Indexeinstellungen (Anzahl der Shards, ``index.knn`` usw.) + - ``doc.json`` - Dokumenten-Mapping (Felddefinitionen) + + .. note:: + + ``fess_config.bulk`` enthält bereits alle Daten aus ``fess_basic_config.bulk``. Als + Konfigurationssicherung vor dem Upgrade genügen daher ``fess_basic_config.bulk``, + ``fess_user.bulk`` und ``system.properties``. .. note:: Protokolldaten wie Suchanfragenprotokolle und Klickprotokolle (``search_log.ndjson``, ``click_log.ndjson``, ``favorite_log.ndjson``, ``user_info.ndjson``) können ebenfalls von derselben Seite heruntergeladen werden. - Falls nur die Konfiguration gesichert wird, ist dies nicht erforderlich. + Falls nur die Konfiguration gesichert wird, ist dies nicht erforderlich. Diese ``*.ndjson``-Dateien + können außerdem nicht über die Sicherungsseite hochgeladen und wiederhergestellt werden + (siehe „Rollback-Verfahren"). 2. **Backup der Konfigurationsdateien** @@ -82,11 +103,26 @@ Backup der Konfigurationsdaten $ cp /path/to/fess/app/WEB-INF/conf/system.properties /backup/ $ cp /path/to/fess/app/WEB-INF/classes/fess_config.properties /backup/ + $ cp /path/to/fess/bin/fess.in.sh /backup/ - RPM/DEB-Version:: + RPM-Version:: + + $ sudo cp /etc/fess/system.properties /backup/ + $ sudo cp /etc/fess/fess_config.properties /backup/ + $ sudo cp /etc/sysconfig/fess /backup/ + + DEB-Version:: $ sudo cp /etc/fess/system.properties /backup/ $ sudo cp /etc/fess/fess_config.properties /backup/ + $ sudo cp /etc/default/fess /backup/ + + .. note:: + + ``/etc/sysconfig/fess`` (RPM-Version) und ``/etc/default/fess`` (DEB-Version) sind + Umgebungsvariablen-Dateien, in denen u. a. ``FESS_PORT``, ``FESS_HEAP_SIZE``, + ``SEARCH_ENGINE_HTTP_URL`` und ``FESS_DICTIONARY_PATH`` festgelegt werden. + Bei der TAR.GZ/ZIP-Version befinden sich die entsprechenden Einstellungen in ``bin/fess.in.sh``. 3. **Angepasste Konfigurationsdateien** @@ -94,6 +130,14 @@ Backup der Konfigurationsdaten $ cp /path/to/fess/app/WEB-INF/classes/log4j2.xml /backup/ + .. note:: + + ``app/WEB-INF/classes/log4j2.xml`` enthält die Protokollkonfiguration für den |Fess|-Hauptprozess + (Web). Untergeordnete Prozesse wie der Crawler verwenden eigene Dateien + (u. a. ``app/WEB-INF/env/crawler/resources/log4j2.xml`` für ``crawler``, ``suggest``, + ``thumbnail`` und ``chunk`` — insgesamt vier). Wenn Sie diese angepasst haben, sichern Sie + sie ebenfalls. + Backup der Indexdaten ---------------------- @@ -151,23 +195,44 @@ Die OpenSearch-Daten werden in Docker-Volumes gespeichert. ``compose-opensearch3 $ docker volume ls -Stoppen Sie die Container und erstellen Sie dann ein Backup der Volumes:: +Stoppen Sie die Container und erstellen Sie dann ein Backup der Volumes. Geben Sie bei ``-v`` in +``docker run`` den tatsächlichen Volume-Namen inklusive Präfix an:: $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop - $ docker run --rm -v search01_data:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-data-backup.tar.gz /data - $ docker run --rm -v search01_dictionary:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-dictionary-backup.tar.gz /data + $ PROJECT=$(basename "$(pwd)") + $ docker run --rm -v ${PROJECT}_search01_data:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-data-backup.tar.gz /data + $ docker run --rm -v ${PROJECT}_search01_dictionary:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-dictionary-backup.tar.gz /data $ docker compose -f compose.yaml -f compose-opensearch3.yaml start +.. warning:: + + Wenn Sie bei ``-v`` den Namen ``search01_data`` ohne Präfix angeben, greift Docker nicht auf das + vorhandene Volume zu, sondern legt ein neues, leeres Volume mit demselben Namen an. Der Befehl + liefert dabei keinen Fehler, sondern erzeugt ein leeres Archiv, sodass es so aussieht, als wäre + das Backup erfolgreich erstellt worden. + +.. note:: + + Der |Fess|-Hauptcontainer (``fess01``) besitzt kein eigenes Volume, daher sind ausschließlich die + beiden oben genannten Volumes zu sichern. Über die Verwaltungsseite geänderte allgemeine + Einstellungen sowie über die Verwaltungsseite installierte Plugins werden jedoch nur innerhalb des + Containers gespeichert und gehen beim Neuerstellen des Containers verloren. Sorgen Sie mit + ``FESS_JAVA_OPTS`` bzw. ``FESS_PLUGINS`` in der Compose-Datei für deren dauerhafte Persistenz. + Schritt 2: Stopp der aktuellen Version ======================================= Stoppen Sie Fess und OpenSearch. -TAR.GZ/ZIP-Version:: +Die TAR.GZ/ZIP-Version enthält kein Skript zum Stoppen. Wenn Sie ``bin/fess`` mit der Option ``-p`` +gestartet haben, stoppen Sie den Prozess anhand der PID-Datei:: - $ kill + $ kill $(cat /path/to/fess/fess.pid) $ kill +Wenn Sie ohne ``-p`` gestartet haben, ermitteln Sie die Prozess-ID und beenden Sie den Prozess mit +``kill`` (mit ``-d`` allein wird keine PID-Datei erstellt). + RPM/DEB-Version (systemd):: $ sudo systemctl stop fess.service @@ -187,15 +252,42 @@ TAR.GZ/ZIP-Version 1. Neue Version herunterladen und entpacken:: - $ wget https://github.com/codelibs/fess/releases/download/fess-15.8.0/fess-15.8.0.tar.gz - $ tar -xzf fess-15.8.0.tar.gz + $ wget https://github.com/codelibs/fess/releases/download/fess-15.8.0/fess-15.8.0.zip + $ unzip fess-15.8.0.zip + + .. note:: + + Die Archivversion von |Fess| wird ausschließlich im ZIP-Format bereitgestellt + (``fess-15.8.0.tar.gz`` steht nicht zur Verfügung). 2. Konfiguration der alten Version kopieren:: $ cp /path/to/old-fess/app/WEB-INF/conf/system.properties /path/to/fess-15.8.0/app/WEB-INF/conf/ + $ cp /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.8.0/app/WEB-INF/classes/ $ cp /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.8.0/bin/ -3. Überprüfen Sie Konfigurationsdifferenzen und passen Sie diese bei Bedarf an +3. Falls Sie Anpassungen vorgenommen haben, kopieren Sie zusätzlich Folgendes:: + + # Protokollkonfiguration + $ cp /path/to/old-fess/app/WEB-INF/classes/log4j2.xml /path/to/fess-15.8.0/app/WEB-INF/classes/ + # Installierte Plugins + $ cp -r /path/to/old-fess/app/WEB-INF/plugin/. /path/to/fess-15.8.0/app/WEB-INF/plugin/ + # Theme + $ cp -r /path/to/old-fess/app/themes/. /path/to/fess-15.8.0/app/themes/ + + .. warning:: + + Kopieren Sie JSPs, die Sie über „Design" in der Verwaltungsseite bearbeitet haben + (``app/WEB-INF/view/``), nicht unverändert. Wenn sich die Struktur der JSPs in der neuen + Version geändert hat, wird die Seite nicht mehr korrekt angezeigt. Wenden Sie Ihre Änderungen + stattdessen erneut auf die JSPs der neuen Version an. + +4. Wenn Sie das eingebettete OpenSearch verwenden (Start von ``bin/fess`` ohne gesetzte + ``SEARCH_ENGINE_HTTP_URL``), kopieren Sie zusätzlich die Indexdaten:: + + $ cp -r /path/to/old-fess/es/data/. /path/to/fess-15.8.0/es/data/ + +5. Überprüfen Sie Konfigurationsdifferenzen und passen Sie diese bei Bedarf an RPM/DEB-Version --------------- @@ -210,8 +302,20 @@ Installieren Sie das Paket der neuen Version:: .. note:: - Konfigurationsdateien (``/etc/fess/*``) werden automatisch beibehalten. - Bei neuen Konfigurationsoptionen ist jedoch eine manuelle Anpassung erforderlich. + Bei der RPM-Version sind die Konfigurationsdateien unter ``/etc/fess/*`` als + ``%config(noreplace)`` registriert und bleiben daher auch beim Upgrade erhalten (die neuen + Standarddateien werden zusätzlich als ``.rpmnew`` abgelegt). Bei neuen Konfigurationsoptionen ist + dennoch eine manuelle Anpassung erforderlich. + +.. warning:: + + Bei der DEB-Version sind die Dateien unter ``/etc/fess/*`` nicht als Conffile registriert (als + Conffile sind nur ``/etc/default/fess``, ``/etc/init.d/fess`` und + ``/usr/lib/systemd/system/fess.service`` eingetragen). Beim Ausführen von ``dpkg -i`` werden daher + Dateien wie ``/etc/fess/fess_config.properties`` durch die Dateien der neuen Version überschrieben. + Spielen Sie die in Schritt 1 gesicherte Konfiguration nach dem Upgrade erneut ein. + ``/etc/fess/system.properties`` wird zur Laufzeit erzeugt und ist nicht Teil des Pakets, sodass + diese Datei nicht überschrieben wird. Docker-Version -------------- @@ -225,10 +329,13 @@ Docker-Version $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull -Schritt 4: Upgrade von OpenSearch (falls erforderlich) -======================================================= +.. _upgrade-opensearch: + +Schritt 4: Upgrade von OpenSearch +================================= -Bei Upgrade von OpenSearch befolgen Sie bitte folgende Schritte. +|Fess| 15.8 unterstützt OpenSearch 3.8.0. Wenn das verbundene OpenSearch älter ist, aktualisieren +Sie es anhand der folgenden Schritte. .. note:: @@ -236,24 +343,43 @@ Bei Upgrade von OpenSearch befolgen Sie bitte folgende Schritte. Bei der Docker-Version werden OpenSearch und die Plugins durch das Herunterladen der neuen Images in Schritt 3 gemeinsam aktualisiert, sodass dieser Schritt nicht erforderlich ist. +.. important:: + + |Fess| 15.8 nimmt unabhängig davon, ob die Chunk-Vektor-Suche (semantische Suche) genutzt wird, + immer ``index.knn`` in die Einstellungen des Suchindex und ``content_chunk_vector`` (Typ + ``knn_vector``) in das Mapping auf. Daher ist das **k-NN-Plugin im verbundenen OpenSearch + zwingend erforderlich**. + + - Es ist in der Standarddistribution von OpenSearch sowie im Docker-Image bereits enthalten. + - **In der Minimal-Distribution ist es nicht enthalten, wodurch die Neuerstellung des Index + fehlschlägt und |Fess| nicht starten kann.** + - In den Indexeinstellungen wird außerdem stets ``knn.derived_source.enabled`` übermittelt. Bei + älteren OpenSearch-Versionen, die diese Option nicht kennen, schlägt die Indexerstellung + unabhängig vom k-NN-Plugin fehl. + + Details finden Sie im Abschnitt „Voraussetzungen" von :doc:`../config/search-semantic`. + .. warning:: Führen Sie Major-Version-Upgrades von OpenSearch vorsichtig durch. Es können Index-Kompatibilitätsprobleme auftreten. + |Fess| 14.x setzt auf OpenSearch der 2.x-Reihe, daher trifft dies bei einem Upgrade von 14.x + immer zu. 1. Installieren Sie die neue Version von OpenSearch 2. Plugins neu installieren:: - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.7.0 - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.7.0 - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-minhash:3.7.0 - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-configsync:3.7.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.8.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.8.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-minhash:3.8.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-configsync:3.8.0 .. note:: Die Versionen dieser Plugins müssen mit der verwendeten OpenSearch-Version übereinstimmen. - Fess 15.8 ist kompatibel mit OpenSearch 3.7.0. Bei Versionsabweichungen schlägt die Plugin-Installation fehl. + |Fess| 15.8 ist kompatibel mit OpenSearch 3.8.0. Bei Versionsabweichungen schlägt die + Plugin-Installation fehl. 3. OpenSearch starten:: @@ -265,7 +391,12 @@ Schritt 5: Start der neuen Version TAR.GZ/ZIP-Version:: $ cd /path/to/fess-15.8.0 - $ ./bin/fess -d + $ ./bin/fess -d -p /path/to/fess-15.8.0/fess.pid + +.. note:: + + Mit ``-p`` wird eine PID-Datei erstellt, mit der Sie den Prozess beim nächsten Stoppen über + ``kill $(cat /path/to/fess-15.8.0/fess.pid)`` beenden können. RPM/DEB-Version:: @@ -281,10 +412,26 @@ Schritt 6: Funktionsprüfung 1. **Überprüfung der Protokolle** - Stellen Sie sicher, dass keine Fehler vorliegen:: + Stellen Sie sicher, dass keine Fehler vorliegen. + + TAR.GZ/ZIP-Version:: $ tail -f /path/to/fess/logs/fess.log + RPM/DEB-Version:: + + $ sudo tail -f /var/log/fess/fess.log + + Docker-Version:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01 + + .. note:: + + Im selben Protokollverzeichnis werden außerdem ``fess-crawler.log`` (Crawl-Verarbeitung), + ``audit.log`` (Authentifizierung und Verwaltungsvorgänge) sowie ``searchlog.log`` + (Suchanfragen) ausgegeben. + 2. **Zugriff auf die Weboberfläche** Greifen Sie mit dem Browser auf http://localhost:8080/ zu. @@ -320,6 +467,40 @@ Bei Major-Version-Upgrades wird die Neuerstellung des Index empfohlen. 3. Warten Sie, bis der Crawl abgeschlossen ist 4. Überprüfen Sie die Suchergebnisse +.. warning:: + + Da bei der Neuindizierung der Index mit dem neuen Mapping neu erstellt wird, schlägt dieser + Vorgang bei OpenSearch ohne k-NN-Plugin fehl. Beachten Sie die Hinweise in Schritt 4. + +Migrationsaufgaben speziell für 15.8 +==================================== + +Wenn Sie von 15.7 oder früher auf 15.8 aktualisieren, sind je nach genutzten Funktionen die +folgenden Arbeiten erforderlich. + +Falls Sie die semantische Suche genutzt haben +--------------------------------------------- + +Das Plugin ``fess-webapp-semantic-search``, das bis 15.7 die semantische Suche bereitstellte, wurde +in 15.8 in den Kern integriert und ist daher nicht mehr erforderlich (veraltet). Sie müssen das +Plugin entfernen, ``-Dfess.semantic_search.*`` sowie ``-Drank.fusion.searchers=default,semantic`` +löschen und die alte Ingest-Pipeline lösen (detach). Das Vorgehen ist unter +:ref:`semantic-search-migration` (:doc:`../config/search-semantic`) beschrieben. + +Falls Sie den KI-Suchmodus (RAG-Chat) genutzt haben +--------------------------------------------------- + +Ab 15.8 wurde die Funktion des KI-Suchmodus (RAG-Chat) in separate Plugins wie ``fess-llm-ollama``, +``fess-llm-openai`` und ``fess-llm-gemini`` ausgelagert. Installieren Sie das zu Ihrem verwendeten +Anbieter passende Plugin über die Verwaltungsseite unter „System" → „Plugins". + +Aktualisierung der Plugin-Versionen +----------------------------------- + +Die unter ``app/WEB-INF/plugin/`` installierten Plugins müssen durch die zur |Fess|-Version +passenden Versionen ersetzt werden. Wenn Sie bei der Docker-Version ``FESS_PLUGINS`` angeben, +aktualisieren Sie den Versionsanteil entsprechend, z. B. ``fess-ds-wikipedia:15.8.0``. + Rollback-Verfahren ================== @@ -360,11 +541,45 @@ Oder Wiederherstellung des Verzeichnisses aus dem Backup:: $ sudo tar xzf /backup/opensearch-data-backup.tar.gz -C / $ sudo systemctl start opensearch +Setzen Sie bei der Docker-Version zunächst die Compose-Dateien der alten Version wieder ein und +stellen Sie dann den Inhalt der Volumes wieder her:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + $ PROJECT=$(basename "$(pwd)") + $ docker run --rm -v ${PROJECT}_search01_data:/data -v $(pwd):/backup ubuntu \ + sh -c "rm -rf /data/* && tar xzf /backup/search01-data-backup.tar.gz -C /" + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +.. note:: + + Die über die Verwaltungsseite heruntergeladenen Konfigurationsdaten können nach dem Start von + |Fess| über die Upload-Funktion auf der Seite „Systeminformationen" → „Sicherung" erneut + importiert und wiederhergestellt werden. Hochgeladen werden können ausschließlich ``*.bulk``, + ``*.properties``-Dateien, die mit ``system`` beginnen, ``*.xml``-Dateien, die mit ``gsa`` + beginnen, sowie ``*.json``-Dateien, die mit ``fess`` oder ``doc`` beginnen — jeweils eine Datei + pro Vorgang. ``*.ndjson``-Dateien wie Suchprotokolle werden nicht akzeptiert und führen zu einem + Fehler. + +.. warning:: + + Das Hochladen von ``fess.json`` und ``doc.json`` überschreibt die in |Fess| enthaltenen + Indexdefinitionsdateien selbst. Wenn Sie nach einem Upgrade die ``fess.json`` oder ``doc.json`` + einer älteren Version hochladen, gehen die Indexeinstellungen und das Mapping der neuen Version + verloren. Laden Sie diese Dateien nur zum Zweck eines Rollbacks hoch. + +.. note:: + + Eine hochgeladene ``system.properties`` wird nur in den Arbeitsspeicher geladen und nicht in eine + Datei geschrieben. Der Inhalt von ``system.properties`` geht daher bei einem Neustart von |Fess| + verloren. Um eine zuverlässige Wiederherstellung zu gewährleisten, platzieren Sie die gesicherte + Datei vor dem Start direkt am vorgesehenen Ort (TAR.GZ/ZIP-Version: ``app/WEB-INF/conf/``, + RPM/DEB-Version: ``/etc/fess/``). + .. note:: - Die über die Verwaltungsseite heruntergeladenen Konfigurationsdaten (``*.bulk``-Dateien) können nach dem Start von - Fess über die Upload-Funktion auf der Seite „Systeminformationen" → „Sicherung" erneut importiert und - wiederhergestellt werden. + Der Import wird asynchron ausgeführt, und auf dem Bildschirm wird lediglich angezeigt, dass er + gestartet wurde. Ob der Import tatsächlich erfolgreich war, überprüfen Sie anhand von + ``fess.log``. Schritt 4: Start und Überprüfung des Dienstes ---------------------------------------------- @@ -391,19 +606,37 @@ A: Ein Upgrade von Fess erfordert einen Dienststopp. Um die Ausfallzeit zu minim F: Muss auch OpenSearch aktualisiert werden? --------------------------------------------- -A: Je nach Fess-Version ist eine bestimmte Version von OpenSearch erforderlich. -Fess 15.8 ist kompatibel mit OpenSearch 3.7.0. -Da Fess-spezifische OpenSearch-Plugins wie ``opensearch-analysis-fess`` exakt mit der OpenSearch-Version -übereinstimmen müssen, aktualisieren Sie beim Upgrade von OpenSearch die Plugins auf die entsprechende -Version (3.7.0). +A: Für jede |Fess|-Version ist eine bestimmte OpenSearch-Version vorgesehen. +|Fess| 15.8 unterstützt OpenSearch 3.8.0. +Da die |Fess|-spezifischen OpenSearch-Plugins wie ``opensearch-analysis-fess`` exakt mit der +OpenSearch-Version übereinstimmen müssen, aktualisieren Sie beim Upgrade von OpenSearch die Plugins +auf die entsprechende Version (3.8.0). + +|Fess| 15.8 setzt außerdem zwingend das k-NN-Plugin voraus und sendet in den Indexeinstellungen +stets ``knn.derived_source.enabled``. Mit einem älteren OpenSearch schlägt die Erstellung neuer +Indizes fehl, sodass ein Upgrade von OpenSearch faktisch erforderlich ist. Details finden Sie in +Schritt 4. F: Muss der Index neu erstellt werden? --------------------------------------- -A: Bei Minor-Version-Upgrades normalerweise nicht erforderlich, bei Major-Version-Upgrades wird jedoch eine Neuerstellung empfohlen. -Wenn Sie außerdem von 15.7 oder früher auf 15.8 oder höher aktualisieren und die Chunk-Vektor-Suche -(semantische Suche) neu aktivieren möchten, ist eine Neuindizierung erforderlich, da der bestehende -Index das neue Mapping nicht übernimmt. Siehe :doc:`../config/search-semantic` für Details. +A: Bei einem Minor-Version-Upgrade von |Fess| (15.x → 15.8) ist dies normalerweise nicht +erforderlich, sofern Sie die Chunk-Vektor-Suche nicht nutzen. Der bestehende Index kann unverändert +weiterverwendet werden, und da Optionen wie ``content_chunker.enabled`` standardmäßig deaktiviert +sind, ändert sich das Verhalten nicht. + +In folgenden Fällen ist eine Neuerstellung bzw. Neuindizierung erforderlich: + +- **Wenn Sie die Chunk-Vektor-Suche (semantische Suche) neu aktivieren**: Da das neue Mapping bei + bestehenden Indizes nicht übernommen wird, ist eine Neuindizierung zwingend erforderlich. Details + finden Sie unter :ref:`semantic-search-migration` (:doc:`../config/search-semantic`). +- **Beim Upgrade von 14.x**: Da OpenSearch dabei ein Major-Version-Upgrade von 2.x auf 3.x + durchläuft, wird die Neuerstellung des Index empfohlen. + +.. warning:: + + Vorgänge, die einen Index neu anlegen (einschließlich der Neuindizierung), schlagen bei + OpenSearch ohne k-NN-Plugin fehl. Beachten Sie die Hinweise in Schritt 4. F: Nach dem Upgrade werden keine Suchergebnisse angezeigt ---------------------------------------------------------- diff --git a/en/15.8/install/upgrade.rst b/en/15.8/install/upgrade.rst index 593c2dca..e7033570 100644 --- a/en/15.8/install/upgrade.rst +++ b/en/15.8/install/upgrade.rst @@ -21,6 +21,13 @@ This upgrade procedure supports upgrades between the following versions: - Fess 14.x → Fess 15.8 - Fess 15.x → Fess 15.8 +.. important:: + + |Fess| 14.x supports the OpenSearch 2.x series, while |Fess| 15.8 supports OpenSearch 3.8.0. + Because the OpenSearch plugins for |Fess| must exactly match the OpenSearch version, upgrading + from 14.x also requires a major version upgrade of OpenSearch. + See :ref:`upgrade-opensearch` for details. + .. note:: When upgrading from older versions (13.x or earlier), a phased upgrade may be necessary. @@ -35,7 +42,7 @@ Verify Version Compatibility Verify the compatibility between the upgrade target version and the current version. - `Release Notes `__ -- `Upgrade Guide `__ +- :doc:`prerequisites` - |Fess| 15.8 system requirements (Java and OpenSearch versions) Plan Downtime ------------- @@ -62,19 +69,31 @@ Configuration Data Backup Log in to the admin screen and click "System Info" → "Backup". The backup page lists the following configuration data as individual items. - Click each link to download it (these are individual files per item, not a single ZIP): + Click each row to download it (these are individual files per item, not a single ZIP; there is + no bulk-download feature, so download the items you need one at a time). - - ``fess_basic_config.bulk`` - Basic configuration (general settings) - - ``fess_config.bulk`` - Crawl settings, scheduler, labels, key matches, and other configuration + - ``fess_basic_config.bulk`` - Configuration indices (19 indices covering crawl settings, + scheduler, labels, key matches, roles, web/file authentication, and so on) + - ``fess_config.bulk`` - The same 19 indices plus runtime data such as crawling information, + failure URLs, job logs, and the thumbnail queue (25 indices in total) - ``fess_user.bulk`` - Users, roles, and groups - - ``system.properties`` - System settings - - ``fess.json`` / ``doc.json`` - Index settings (mappings) + - ``system.properties`` - System settings, including general configuration + - ``fess.json`` - Index settings (shard count, ``index.knn``, and so on) + - ``doc.json`` - Document mapping (field definitions) + + .. note:: + + ``fess_config.bulk`` already includes everything in ``fess_basic_config.bulk``. For a + configuration backup before upgrading, ``fess_basic_config.bulk``, ``fess_user.bulk``, and + ``system.properties`` are sufficient. .. note:: Log data such as search logs and click logs (``search_log.ndjson``, ``click_log.ndjson``, ``favorite_log.ndjson``, ``user_info.ndjson``) can also be downloaded from the same page. - They are not needed if you only want to back up the configuration. + They are not needed if you only want to back up the configuration. Note that these + ``*.ndjson`` files cannot be restored by uploading them on the backup page (see "Rollback + Procedure"). 2. **Configuration File Backup** @@ -82,11 +101,26 @@ Configuration Data Backup $ cp /path/to/fess/app/WEB-INF/conf/system.properties /backup/ $ cp /path/to/fess/app/WEB-INF/classes/fess_config.properties /backup/ + $ cp /path/to/fess/bin/fess.in.sh /backup/ - RPM/DEB version:: + RPM version:: $ sudo cp /etc/fess/system.properties /backup/ $ sudo cp /etc/fess/fess_config.properties /backup/ + $ sudo cp /etc/sysconfig/fess /backup/ + + DEB version:: + + $ sudo cp /etc/fess/system.properties /backup/ + $ sudo cp /etc/fess/fess_config.properties /backup/ + $ sudo cp /etc/default/fess /backup/ + + .. note:: + + ``/etc/sysconfig/fess`` (RPM version) and ``/etc/default/fess`` (DEB version) are + environment variable files that set values such as ``FESS_PORT``, ``FESS_HEAP_SIZE``, + ``SEARCH_ENGINE_HTTP_URL``, and ``FESS_DICTIONARY_PATH``. For the TAR.GZ/ZIP version, the + equivalent settings are in ``bin/fess.in.sh``. 3. **Customized Configuration Files** @@ -94,6 +128,14 @@ Configuration Data Backup $ cp /path/to/fess/app/WEB-INF/classes/log4j2.xml /backup/ + .. note:: + + ``app/WEB-INF/classes/log4j2.xml`` is the log configuration for the |Fess| main (web) + process. Child processes such as the crawler use separate files (for example, + ``app/WEB-INF/env/crawler/resources/log4j2.xml``, one each for ``crawler``, ``suggest``, + ``thumbnail``, and ``chunk`` — four in total), so back those up too if you have customized + them. + Index Data Backup ----------------- @@ -151,23 +193,44 @@ OpenSearch data is stored in Docker volumes. ``compose-opensearch3.yaml`` define $ docker volume ls -Stop the containers, then back up the volumes:: +Stop the containers, then back up the volumes. Specify the actual volume name, including the +prefix, for ``-v`` in ``docker run``:: $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop - $ docker run --rm -v search01_data:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-data-backup.tar.gz /data - $ docker run --rm -v search01_dictionary:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-dictionary-backup.tar.gz /data + $ PROJECT=$(basename "$(pwd)") + $ docker run --rm -v ${PROJECT}_search01_data:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-data-backup.tar.gz /data + $ docker run --rm -v ${PROJECT}_search01_dictionary:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-dictionary-backup.tar.gz /data $ docker compose -f compose.yaml -f compose-opensearch3.yaml start +.. warning:: + + If you specify ``-v`` with the unprefixed name ``search01_data``, Docker does not reference the + existing volume — it creates a new, empty volume with the same name instead. The command does + not report an error, and an archive with empty contents is created, so it can look as though + the backup succeeded. + +.. note:: + + The |Fess| main container (``fess01``) has no dedicated volume of its own, so the two volumes + above are the only backup targets. However, general settings changed from the admin UI and + plugins installed from the admin UI are stored only inside the container and are lost when the + container is recreated. Persist these instead by specifying them via ``FESS_JAVA_OPTS`` or + ``FESS_PLUGINS`` in the Compose file. + Step 2: Stop Current Version ============================= Stop Fess and OpenSearch. -TAR.GZ/ZIP version:: +The TAR.GZ/ZIP version does not include a stop script. If you started ``bin/fess`` with the +``-p`` option, stop it using the PID file:: - $ kill + $ kill $(cat /path/to/fess/fess.pid) $ kill +If you started it without ``-p``, find the process ID and ``kill`` it manually (``-d`` alone does +not create a PID file). + RPM/DEB version (systemd):: $ sudo systemctl stop fess.service @@ -187,15 +250,41 @@ TAR.GZ/ZIP Version 1. Download and extract the new version:: - $ wget https://github.com/codelibs/fess/releases/download/fess-15.8.0/fess-15.8.0.tar.gz - $ tar -xzf fess-15.8.0.tar.gz + $ wget https://github.com/codelibs/fess/releases/download/fess-15.8.0/fess-15.8.0.zip + $ unzip fess-15.8.0.zip + + .. note:: + + |Fess| archives are distributed only in ZIP format (``fess-15.8.0.tar.gz`` is not + provided). 2. Copy configuration from the old version:: $ cp /path/to/old-fess/app/WEB-INF/conf/system.properties /path/to/fess-15.8.0/app/WEB-INF/conf/ + $ cp /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.8.0/app/WEB-INF/classes/ $ cp /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.8.0/bin/ -3. Verify configuration differences and adjust as necessary +3. If you have customizations, also copy the following:: + + # Log configuration + $ cp /path/to/old-fess/app/WEB-INF/classes/log4j2.xml /path/to/fess-15.8.0/app/WEB-INF/classes/ + # Installed plugins + $ cp -r /path/to/old-fess/app/WEB-INF/plugin/. /path/to/fess-15.8.0/app/WEB-INF/plugin/ + # Theme + $ cp -r /path/to/old-fess/app/themes/. /path/to/fess-15.8.0/app/themes/ + + .. warning:: + + Do not copy JSPs (``app/WEB-INF/view/``) edited via "Design" in the admin UI as-is. If + their structure differs from the JSPs in the new version, pages may not render correctly. + Reapply your changes to the new version's JSPs instead. + +4. If you are using the embedded OpenSearch (starting ``bin/fess`` without setting + ``SEARCH_ENGINE_HTTP_URL``), also copy the index data:: + + $ cp -r /path/to/old-fess/es/data/. /path/to/fess-15.8.0/es/data/ + +5. Verify configuration differences and adjust as necessary RPM/DEB Version --------------- @@ -210,8 +299,19 @@ Install the new version package:: .. note:: - Configuration files (``/etc/fess/*``) are automatically retained. - However, if new configuration options have been added, manual adjustment may be necessary. + For the RPM version, the configuration files under ``/etc/fess/*`` are registered as + ``%config(noreplace)``, so they are retained across upgrades (the new default files are placed + alongside them with a ``.rpmnew`` suffix). If new configuration options have been added, + manual adjustment may be necessary. + +.. warning:: + + For the DEB version, ``/etc/fess/*`` is not registered as a conffile (the only conffiles are + ``/etc/default/fess``, ``/etc/init.d/fess``, and ``/usr/lib/systemd/system/fess.service``). + As a result, running ``dpkg -i`` overwrites files such as ``/etc/fess/fess_config.properties`` + with the new version's files. Reapply the configuration you backed up in Step 1 after + upgrading. Note that ``/etc/fess/system.properties`` is a runtime-generated file not included + in the package, so it is not overwritten. Docker Version -------------- @@ -225,10 +325,13 @@ Docker Version $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull -Step 4: Upgrade OpenSearch (If Necessary) -========================================== +.. _upgrade-opensearch: -If you are also upgrading OpenSearch, follow these procedures. +Step 4: Upgrade OpenSearch +========================== + +|Fess| 15.8 supports OpenSearch 3.8.0. If the OpenSearch you connect to is older than that, +upgrade it using the following procedure. .. note:: @@ -236,24 +339,42 @@ If you are also upgrading OpenSearch, follow these procedures. installation. For the Docker version, pulling the new image in Step 3 updates OpenSearch and its plugins together, so this step is not required. +.. important:: + + Regardless of whether you use chunk-vector search (semantic search), |Fess| 15.8 always + includes ``index.knn`` in the search index settings and ``content_chunk_vector`` (a + ``knn_vector`` type) in the mapping. Because of this, the OpenSearch you connect to **must + have the k-NN plugin installed**. + + - It is bundled with the standard OpenSearch distribution and the Docker version's image. + - **It is not included in the minimal distribution, so creating a new index fails and |Fess| + cannot start.** + - The index settings also always send ``knn.derived_source.enabled``. An older OpenSearch + that does not recognize this setting fails to create the index regardless of whether the + k-NN plugin is present. + + See "Prerequisites" in :doc:`../config/search-semantic` for details. + .. warning:: Be careful when performing major version upgrades of OpenSearch. Index compatibility issues may occur. + |Fess| 14.x uses the OpenSearch 2.x series, so upgrading from 14.x always falls into this + case. 1. Install the new version of OpenSearch 2. Reinstall plugins:: - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.7.0 - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.7.0 - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-minhash:3.7.0 - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-configsync:3.7.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.8.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.8.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-minhash:3.8.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-configsync:3.8.0 .. note:: - The version of these plugins must match the version of OpenSearch you use. Fess 15.8 supports - OpenSearch 3.7.0. Installation fails if the versions do not match. + The version of these plugins must match the version of OpenSearch you use. |Fess| 15.8 + supports OpenSearch 3.8.0. Installation fails if the versions do not match. 3. Start OpenSearch:: @@ -265,7 +386,12 @@ Step 5: Start New Version TAR.GZ/ZIP version:: $ cd /path/to/fess-15.8.0 - $ ./bin/fess -d + $ ./bin/fess -d -p /path/to/fess-15.8.0/fess.pid + +.. note:: + + Specifying ``-p`` creates a PID file, which lets you stop |Fess| the next time with + ``kill $(cat /path/to/fess-15.8.0/fess.pid)``. RPM/DEB version:: @@ -281,10 +407,26 @@ Step 6: Verify Operation 1. **Check Logs** - Verify there are no errors:: + Verify there are no errors. + + TAR.GZ/ZIP version:: $ tail -f /path/to/fess/logs/fess.log + RPM/DEB version:: + + $ sudo tail -f /var/log/fess/fess.log + + Docker version:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01 + + .. note:: + + The same log directory also contains ``fess-crawler.log`` for crawl processing, + ``audit.log`` for authentication and admin operations, and ``searchlog.log`` for search + requests. + 2. **Access Web Interface** Access http://localhost:8080/ in a browser. @@ -320,6 +462,40 @@ For major version upgrades, it is recommended to recreate the index. 3. Wait for crawl to complete 4. Verify search results +.. warning:: + + Re-indexing rebuilds the index with the new mapping, so it fails on an OpenSearch without the + k-NN plugin. Review the notes in Step 4. + +15.8-Specific Migration Tasks +============================= + +If you are upgrading from 15.7 or earlier to 15.8, the following tasks may be required depending +on which features you use. + +If You Were Using Semantic Search +--------------------------------- + +The ``fess-webapp-semantic-search`` plugin, which provided semantic search in 15.7 and earlier, +is no longer needed (deprecated) because this functionality is now integrated into the core in +15.8. You need to remove the plugin, remove ``-Dfess.semantic_search.*`` and +``-Drank.fusion.searchers=default,semantic``, and detach the old ingest pipeline. For the +procedure, see :ref:`semantic-search-migration` (in :doc:`../config/search-semantic`). + +If You Were Using AI Search Mode (RAG) +-------------------------------------- + +Starting with 15.8, AI search mode (RAG) functionality has been split out into plugins such as +``fess-llm-ollama``, ``fess-llm-openai``, and ``fess-llm-gemini``. Install the plugin that +corresponds to the provider you use from "System" → "Plugins" in the admin UI. + +Updating Plugin Versions +------------------------ + +Plugins installed under ``app/WEB-INF/plugin/`` need to be replaced with versions matching your +|Fess| version. If you specify ``FESS_PLUGINS`` in the Docker version, update the version part, +for example to ``fess-ds-wikipedia:15.8.0``. + Rollback Procedure ================== @@ -360,10 +536,41 @@ Or restore directory from backup:: $ sudo tar xzf /backup/opensearch-data-backup.tar.gz -C / $ sudo systemctl start opensearch +For the Docker version, revert to the old version's Compose files, then restore the volume +contents:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + $ PROJECT=$(basename "$(pwd)") + $ docker run --rm -v ${PROJECT}_search01_data:/data -v $(pwd):/backup ubuntu \ + sh -c "rm -rf /data/* && tar xzf /backup/search01-data-backup.tar.gz -C /" + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + .. note:: - Configuration data downloaded from the admin screen (``*.bulk`` files) can be re-imported - after starting Fess via the upload feature on the "System Info" → "Backup" page. + Configuration data downloaded from the admin screen can be re-imported after starting |Fess| + via the upload feature on the "System Info" → "Backup" page. You can upload ``*.bulk`` files, + ``*.properties`` files starting with ``system``, ``*.xml`` files starting with ``gsa``, + ``*.json`` files starting with ``fess``, and ``*.json`` files starting with ``doc`` — one file + per operation. ``*.ndjson`` files such as search logs are not accepted and result in an error. + +.. warning:: + + Uploading ``fess.json`` or ``doc.json`` overwrites the index definition files bundled with + |Fess| itself. If you upload the ``fess.json`` or ``doc.json`` from an older version after + upgrading, you lose the new version's index settings and mapping. Do not upload these files + except for rollback purposes. + +.. note:: + + The uploaded ``system.properties`` is loaded into memory only and is not written back to a + file, so its contents are lost when |Fess| is restarted. To restore it reliably, place the + backed-up file directly in its proper location before starting |Fess| (``app/WEB-INF/conf/`` + for the TAR.GZ/ZIP version, ``/etc/fess/`` for the RPM/DEB version). + +.. note:: + + The import runs asynchronously; the screen only shows that it has started. Check + ``fess.log`` to confirm whether it actually succeeded. Step 4: Start and Verify Service --------------------------------- @@ -390,17 +597,35 @@ A: Upgrading Fess requires service shutdown. To minimize downtime, consider the Q: Do I need to upgrade OpenSearch too? ---------------------------------------- -A: Each version of Fess requires a specific version of OpenSearch. Fess 15.8 requires OpenSearch 3.7.0. -The Fess OpenSearch plugins such as ``opensearch-analysis-fess`` must exactly match the OpenSearch version, -so if you upgrade OpenSearch, also update the plugins to the corresponding version (3.7.0). +A: Each version of |Fess| requires a specific version of OpenSearch. +|Fess| 15.8 requires OpenSearch 3.8.0. +The |Fess| OpenSearch plugins such as ``opensearch-analysis-fess`` must exactly match the +OpenSearch version, so if you upgrade OpenSearch, also update the plugins to the corresponding +version (3.8.0). + +Also, |Fess| 15.8 requires the k-NN plugin and always sends ``knn.derived_source.enabled`` in the +index settings. With an older OpenSearch, creating a new index fails, so upgrading OpenSearch is +effectively required. See Step 4 for details. Q: Do I need to recreate the index? ------------------------------------ -A: For minor version upgrades, it is usually not necessary, but for major version upgrades, recreation is recommended. -Also, if you are upgrading from 15.7 or earlier to 15.8 or later and want to newly enable -chunk-vector search (semantic search), re-indexing is required, since the existing index does not -pick up the new mapping. See :doc:`../config/search-semantic` for details. +A: For a |Fess| minor version upgrade (15.x → 15.8) where you do not use chunk-vector search, it +is usually not necessary. The existing index can continue to be used as-is, and settings such as +``content_chunker.enabled`` remain disabled by default, so behavior does not change. + +Recreation and re-indexing are required in the following cases: + +- **Newly enabling chunk-vector search (semantic search)**: The existing index does not pick up + the new mapping, so re-indexing is required. See :ref:`semantic-search-migration` (in + :doc:`../config/search-semantic`) for details. +- **Upgrading from 14.x**: Because OpenSearch undergoes a major version upgrade from 2.x to 3.x, + recreating the index is recommended. + +.. warning:: + + Operations that create a new index (including re-indexing) fail on an OpenSearch without the + k-NN plugin. Review the notes in Step 4. Q: Search results are not displayed after upgrade -------------------------------------------------- diff --git a/es/15.8/install/upgrade.rst b/es/15.8/install/upgrade.rst index f97d7a85..f69fb705 100644 --- a/es/15.8/install/upgrade.rst +++ b/es/15.8/install/upgrade.rst @@ -21,6 +21,13 @@ Estos procedimientos de actualización son compatibles con actualizaciones entre - Fess 14.x → Fess 15.8 - Fess 15.x → Fess 15.8 +.. important:: + + |Fess| 14.x es compatible con la serie OpenSearch 2.x, mientras que |Fess| 15.8 es compatible + con OpenSearch 3.8.0. Los plugins de OpenSearch para |Fess| deben coincidir exactamente con la + versión de OpenSearch, por lo que si actualiza desde la versión 14.x también es obligatorio + actualizar la versión principal de OpenSearch. Consulte :ref:`upgrade-opensearch`. + .. note:: Si actualiza desde versiones más antiguas (13.x o anteriores), puede ser necesaria una actualización gradual. @@ -35,7 +42,7 @@ Verificación de Compatibilidad de Versiones Verifique la compatibilidad entre la versión de destino de actualización y la versión actual. - `Notas de Lanzamiento `__ -- `Guía de Actualización `__ +- :doc:`prerequisites` - Entorno de ejecución de |Fess| 15.8 (versiones de Java y OpenSearch) Planificación del Tiempo de Inactividad ---------------------------------------- @@ -62,19 +69,31 @@ Respaldo de Datos de Configuración Inicie sesión en la pantalla de administración y haga clic en "Información del sistema" → "Copia de seguridad". En la página de Copia de seguridad se listan los siguientes datos de configuración como elementos individuales. - Haga clic en cada enlace para descargarlos (son archivos individuales por elemento, no un único archivo ZIP). + Haga clic en cada fila para descargarlos (son archivos individuales por elemento, no un único archivo ZIP. + No existe una función de descarga masiva, por lo que debe descargar los elementos necesarios uno por uno). - - ``fess_basic_config.bulk`` - Configuración básica (ajustes generales) - - ``fess_config.bulk`` - Ajustes de rastreo, programador, etiquetas, coincidencias de clave y otra configuración + - ``fess_basic_config.bulk`` - Índices de configuración (ajustes de rastreo, programador, etiquetas, + coincidencias de clave, roles, autenticación web/de archivos, entre 19 índices) + - ``fess_config.bulk`` - Además de los 19 índices anteriores, incluye 25 índices con datos de + ejecución, como información de rastreo, URL con errores, registros de tareas y colas de miniaturas - ``fess_user.bulk`` - Usuarios, roles y grupos - - ``system.properties`` - Configuración del sistema - - ``fess.json`` / ``doc.json`` - Configuración del índice (mappings) + - ``system.properties`` - Configuración del sistema, incluidos los ajustes generales + - ``fess.json`` - Configuración del índice (número de shards, ``index.knn``, etc.) + - ``doc.json`` - Mapeo de documentos (definiciones de campos) + + .. note:: + + ``fess_config.bulk`` incluye el contenido de ``fess_basic_config.bulk``. Como respaldo de + configuración antes de la actualización, basta con ``fess_basic_config.bulk``, ``fess_user.bulk`` + y ``system.properties``. .. note:: Los datos de registro como los registros de búsqueda y clics (``search_log.ndjson``, ``click_log.ndjson``, ``favorite_log.ndjson``, ``user_info.ndjson``) también pueden descargarse desde la misma página. - No son necesarios si solo desea hacer un respaldo de la configuración. + No son necesarios si solo desea hacer un respaldo de la configuración. Tenga en cuenta que estos + archivos ``*.ndjson`` no se pueden restaurar cargándolos desde la página de copia de seguridad + (consulte "Procedimientos de Reversión"). 2. **Respaldo de archivos de configuración** @@ -82,11 +101,26 @@ Respaldo de Datos de Configuración $ cp /path/to/fess/app/WEB-INF/conf/system.properties /backup/ $ cp /path/to/fess/app/WEB-INF/classes/fess_config.properties /backup/ + $ cp /path/to/fess/bin/fess.in.sh /backup/ - Versión RPM/DEB:: + Versión RPM:: $ sudo cp /etc/fess/system.properties /backup/ $ sudo cp /etc/fess/fess_config.properties /backup/ + $ sudo cp /etc/sysconfig/fess /backup/ + + Versión DEB:: + + $ sudo cp /etc/fess/system.properties /backup/ + $ sudo cp /etc/fess/fess_config.properties /backup/ + $ sudo cp /etc/default/fess /backup/ + + .. note:: + + ``/etc/sysconfig/fess`` (versión RPM) y ``/etc/default/fess`` (versión DEB) son archivos de + variables de entorno que especifican ``FESS_PORT``, ``FESS_HEAP_SIZE``, ``SEARCH_ENGINE_HTTP_URL``, + ``FESS_DICTIONARY_PATH`` y otros valores. En la versión TAR.GZ/ZIP, la configuración + equivalente se encuentra en ``bin/fess.in.sh``. 3. **Archivos de configuración personalizados** @@ -94,6 +128,14 @@ Respaldo de Datos de Configuración $ cp /path/to/fess/app/WEB-INF/classes/log4j2.xml /backup/ + .. note:: + + ``app/WEB-INF/classes/log4j2.xml`` es la configuración de registro del proceso principal + (Web) de |Fess|. Los procesos hijos, como el rastreador, usan archivos independientes + (``app/WEB-INF/env/crawler/resources/log4j2.xml``, entre otros: ``crawler``, ``suggest``, + ``thumbnail`` y ``chunk``, 4 en total). Si los ha modificado, incluya también estos + archivos en el respaldo. + Respaldo de Datos de Índice ----------------------------- @@ -153,23 +195,44 @@ de diccionario. $ docker volume ls -Detenga los contenedores y luego haga un respaldo de los volúmenes:: +Detenga los contenedores y luego haga un respaldo de los volúmenes. En el ``-v`` de ``docker run``, +especifique el nombre real del volumen, incluido el prefijo:: $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop - $ docker run --rm -v search01_data:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-data-backup.tar.gz /data - $ docker run --rm -v search01_dictionary:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-dictionary-backup.tar.gz /data + $ PROJECT=$(basename "$(pwd)") + $ docker run --rm -v ${PROJECT}_search01_data:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-data-backup.tar.gz /data + $ docker run --rm -v ${PROJECT}_search01_dictionary:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-dictionary-backup.tar.gz /data $ docker compose -f compose.yaml -f compose-opensearch3.yaml start +.. warning:: + + Si especifica ``search01_data`` sin el prefijo en ``-v``, Docker no hará referencia al volumen + existente, sino que creará uno nuevo y vacío con el mismo nombre. El comando no producirá ningún + error, pero generará un archivo comprimido vacío, por lo que puede parecer que el respaldo se + realizó correctamente cuando en realidad no contiene datos. + +.. note:: + + El contenedor principal de |Fess| (``fess01``) no tiene un volumen dedicado, por lo que los + únicos elementos que deben respaldarse son los dos anteriores. Sin embargo, los ajustes + generales modificados desde la pantalla de administración y los plugins instalados desde ella + se almacenan únicamente dentro del contenedor y se perderán si este se recrea. Persístalos + especificándolos mediante ``FESS_JAVA_OPTS`` o ``FESS_PLUGINS`` en el archivo Compose. + Paso 2: Detención de la Versión Actual ======================================== Detenga Fess y OpenSearch. -Versión TAR.GZ/ZIP:: +La versión TAR.GZ/ZIP no incluye un script para detener el servicio. Si inició ``bin/fess`` con +la opción ``-p``, deténgalo usando el archivo PID:: - $ kill + $ kill $(cat /path/to/fess/fess.pid) $ kill +Si lo inició sin especificar ``-p``, verifique el ID del proceso y ejecute ``kill`` manualmente +(con ``-d`` solo no se crea ningún archivo PID). + Versión RPM/DEB (systemd):: $ sudo systemctl stop fess.service @@ -189,15 +252,42 @@ Versión TAR.GZ/ZIP 1. Descargue y extraiga la nueva versión:: - $ wget https://github.com/codelibs/fess/releases/download/fess-15.8.0/fess-15.8.0.tar.gz - $ tar -xzf fess-15.8.0.tar.gz + $ wget https://github.com/codelibs/fess/releases/download/fess-15.8.0/fess-15.8.0.zip + $ unzip fess-15.8.0.zip + + .. note:: + + La versión archivo de |Fess| se distribuye únicamente en formato ZIP + (no se ofrece ``fess-15.8.0.tar.gz``). 2. Copie la configuración de la versión antigua:: $ cp /path/to/old-fess/app/WEB-INF/conf/system.properties /path/to/fess-15.8.0/app/WEB-INF/conf/ + $ cp /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.8.0/app/WEB-INF/classes/ $ cp /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.8.0/bin/ -3. Verifique las diferencias de configuración y ajuste según sea necesario +3. Si tiene personalizaciones, copie también lo siguiente:: + + # Configuración de registro + $ cp /path/to/old-fess/app/WEB-INF/classes/log4j2.xml /path/to/fess-15.8.0/app/WEB-INF/classes/ + # Plugins instalados + $ cp -r /path/to/old-fess/app/WEB-INF/plugin/. /path/to/fess-15.8.0/app/WEB-INF/plugin/ + # Tema + $ cp -r /path/to/old-fess/app/themes/. /path/to/fess-15.8.0/app/themes/ + + .. warning:: + + No copie directamente los JSP editados desde "Diseño" en la pantalla de administración + (``app/WEB-INF/view/``). Si la estructura de los JSP cambió en la nueva versión, la pantalla + podría dejar de mostrarse correctamente. Vuelva a aplicar sus cambios sobre los JSP de la + nueva versión. + +4. Si utiliza OpenSearch integrado (una configuración en la que ``bin/fess`` se inicia sin + establecer ``SEARCH_ENGINE_HTTP_URL``), copie también los datos del índice:: + + $ cp -r /path/to/old-fess/es/data/. /path/to/fess-15.8.0/es/data/ + +5. Verifique las diferencias de configuración y ajuste según sea necesario Versión RPM/DEB --------------- @@ -212,8 +302,19 @@ Instale el paquete de la nueva versión:: .. note:: - Los archivos de configuración (``/etc/fess/*``) se conservan automáticamente. - Sin embargo, si se han agregado nuevas opciones de configuración, es necesario ajustarlas manualmente. + En la versión RPM, los archivos de configuración de ``/etc/fess/*`` están registrados como + ``%config(noreplace)``, por lo que se conservan durante la actualización (los nuevos archivos + predeterminados se colocan junto a ellos con la extensión ``.rpmnew``). Si se han agregado + nuevas opciones de configuración, es necesario ajustarlas manualmente. + +.. warning:: + + En la versión DEB, ``/etc/fess/*`` no está registrado como conffile (los únicos conffile son + ``/etc/default/fess``, ``/etc/init.d/fess`` y ``/usr/lib/systemd/system/fess.service``). Por lo + tanto, al ejecutar ``dpkg -i``, archivos como ``/etc/fess/fess_config.properties`` se sobrescriben + con los de la nueva versión. Vuelva a aplicar la configuración que respaldó en el Paso 1 después + de la actualización. Tenga en cuenta que ``/etc/fess/system.properties`` es un archivo generado + en tiempo de ejecución que no forma parte del paquete, por lo que no se sobrescribe. Versión Docker -------------- @@ -227,10 +328,13 @@ Versión Docker $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull -Paso 4: Actualización de OpenSearch (Si es Necesario) -====================================================== +.. _upgrade-opensearch: + +Paso 4: Actualización de OpenSearch +==================================== -Si también actualiza OpenSearch, siga estos procedimientos. +|Fess| 15.8 es compatible con OpenSearch 3.8.0. Si el OpenSearch al que se conecta es una versión +anterior, actualícelo siguiendo estos procedimientos. .. note:: @@ -238,24 +342,42 @@ Si también actualiza OpenSearch, siga estos procedimientos. TAR.GZ/ZIP y RPM/DEB. En la versión Docker, al obtener las nuevas imágenes en el Paso 3, OpenSearch y los plugins se actualizan conjuntamente, por lo que este paso no es necesario. +.. important:: + + |Fess| 15.8 incluye siempre ``index.knn`` en la configuración del índice de búsqueda y + ``content_chunk_vector`` (de tipo ``knn_vector``) en el mapeo, independientemente de si se + utiliza la búsqueda por vector de chunks (búsqueda semántica). Por lo tanto, el OpenSearch al + que se conecta **debe tener instalado el plugin k-NN**. + + - Viene incluido en la distribución estándar de OpenSearch y en la imagen de la versión Docker. + - **No está incluido en la distribución minimal, por lo que la creación del índice fallará y + |Fess| no podrá iniciarse.** + - La configuración del índice también envía siempre ``knn.derived_source.enabled``. En un + OpenSearch antiguo que no reconozca esta opción, la creación del índice fallará + independientemente de si el plugin k-NN está instalado. + + Para más detalles, consulte los "Requisitos previos" de :doc:`../config/search-semantic`. + .. warning:: Realice con cuidado las actualizaciones de versión principal de OpenSearch. Pueden surgir problemas de compatibilidad del índice. + |Fess| 14.x utiliza la serie OpenSearch 2.x, por lo que una actualización desde 14.x siempre + corresponde a este caso. 1. Instale la nueva versión de OpenSearch 2. Reinstale los plugins:: - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.7.0 - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.7.0 - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-minhash:3.7.0 - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-configsync:3.7.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.8.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.8.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-minhash:3.8.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-configsync:3.8.0 .. note:: La versión de estos plugins debe coincidir con la versión de OpenSearch que se utiliza. - Fess 15.8 es compatible con OpenSearch 3.7.0. Si las versiones no coinciden, + |Fess| 15.8 es compatible con OpenSearch 3.8.0. Si las versiones no coinciden, la instalación de los plugins fallará. 3. Inicie OpenSearch:: @@ -268,7 +390,12 @@ Paso 5: Inicio de la Nueva Versión Versión TAR.GZ/ZIP:: $ cd /path/to/fess-15.8.0 - $ ./bin/fess -d + $ ./bin/fess -d -p /path/to/fess-15.8.0/fess.pid + +.. note:: + + Si especifica ``-p``, se crea un archivo PID que permite detener el servicio la próxima vez + con ``kill $(cat /path/to/fess-15.8.0/fess.pid)``. Versión RPM/DEB:: @@ -284,10 +411,26 @@ Paso 6: Verificación de Funcionamiento 1. **Verificación de registros** - Verifique que no haya errores:: + Verifique que no haya errores. + + Versión TAR.GZ/ZIP:: $ tail -f /path/to/fess/logs/fess.log + Versión RPM/DEB:: + + $ sudo tail -f /var/log/fess/fess.log + + Versión Docker:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01 + + .. note:: + + En el mismo directorio de registros también se generan ``fess-crawler.log`` (procesamiento + de rastreo), ``audit.log`` (autenticación y operaciones de administración) y + ``searchlog.log`` (solicitudes de búsqueda). + 2. **Acceso a la interfaz Web** Acceda a http://localhost:8080/ desde el navegador. @@ -324,6 +467,42 @@ Para actualizaciones de versión principal, se recomienda recrear el índice. 3. Espere hasta que se complete el rastreo 4. Verifique los resultados de búsqueda +.. warning:: + + Dado que la reindexación reconstruye el índice con el nuevo mapeo, fallará en un OpenSearch + sin el plugin k-NN. Consulte las notas del Paso 4. + +Migración Específica de 15.8 +============================== + +Si actualiza desde la versión 15.7 o anterior a la 15.8, es posible que deba realizar las +siguientes tareas según las funciones que utilice. + +Si Utilizaba la Búsqueda Semántica +------------------------------------ + +El plugin ``fess-webapp-semantic-search``, que proporcionaba la búsqueda semántica en las +versiones 15.7 y anteriores, ya no es necesario (y queda obsoleto) porque se integró en el +núcleo en la versión 15.8. Debe eliminar el plugin, eliminar ``-Dfess.semantic_search.*`` y +``-Drank.fusion.searchers=default,semantic``, y separar el antiguo ingest pipeline. Consulte +:ref:`semantic-search-migration` (:doc:`../config/search-semantic`) para conocer el +procedimiento. + +Si Utilizaba el Modo de Búsqueda con IA (Chat RAG) +----------------------------------------------------- + +A partir de la versión 15.8, la función del modo de búsqueda con IA (chat RAG) se separó en +plugins independientes, como ``fess-llm-ollama``, ``fess-llm-openai`` y ``fess-llm-gemini``. +Instale el plugin correspondiente al proveedor que utilice desde "Sistema" → "Plugin" en la +pantalla de administración. + +Actualización de la Versión de los Plugins +--------------------------------------------- + +Los plugins instalados en ``app/WEB-INF/plugin/`` deben reemplazarse por los correspondientes a +la versión de |Fess|. Si utiliza ``FESS_PLUGINS`` en la versión Docker, actualice la parte de +la versión, por ejemplo a ``fess-ds-wikipedia:15.8.0``. + Procedimientos de Reversión ============================= @@ -364,11 +543,43 @@ O restaure el directorio desde el respaldo:: $ sudo tar xzf /backup/opensearch-data-backup.tar.gz -C / $ sudo systemctl start opensearch +En la versión Docker, vuelva al archivo Compose de la versión anterior y restaure el contenido +de los volúmenes:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + $ PROJECT=$(basename "$(pwd)") + $ docker run --rm -v ${PROJECT}_search01_data:/data -v $(pwd):/backup ubuntu \ + sh -c "rm -rf /data/* && tar xzf /backup/search01-data-backup.tar.gz -C /" + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + .. note:: - Los datos de configuración descargados desde la pantalla de administración (archivos ``*.bulk``) pueden - reimportarse desde la función de carga en la página "Información del sistema" → "Copia de seguridad" - después de iniciar Fess. + Los datos de configuración descargados desde la pantalla de administración pueden reimportarse + desde la función de carga en la página "Información del sistema" → "Copia de seguridad" después + de iniciar |Fess|. Solo se pueden cargar archivos ``*.bulk``, archivos ``*.properties`` que + comiencen con ``system``, archivos ``*.xml`` que comiencen con ``gsa``, archivos ``*.json`` que + comiencen con ``fess`` y archivos ``*.json`` que comiencen con ``doc``, y solo un archivo por + operación. Los archivos ``*.ndjson``, como los registros de búsqueda, no se aceptan y producen + un error. + +.. warning:: + + Cargar ``fess.json`` y ``doc.json`` sobrescribe los propios archivos de definición de índice + incluidos con |Fess|. Si después de la actualización carga la versión antigua de ``fess.json`` + o ``doc.json``, se perderán la configuración y el mapeo del índice de la nueva versión. No los + cargue salvo con fines de reversión. + +.. note:: + + El archivo ``system.properties`` cargado se lee únicamente en memoria y no se escribe en disco. + Por lo tanto, su contenido se pierde al reiniciar |Fess|. Para restaurarlo de forma fiable, + coloque directamente el archivo respaldado en su ubicación correspondiente (``app/WEB-INF/conf/`` + en la versión TAR.GZ/ZIP, ``/etc/fess/`` en la versión RPM/DEB) antes de iniciar el servicio. + +.. note:: + + La importación se ejecuta de forma asíncrona y la pantalla solo muestra que se inició el + proceso. Para confirmar si realmente se completó con éxito, consulte ``fess.log``. Paso 4: Inicio y Verificación del Servicio ------------------------------------------- @@ -395,20 +606,37 @@ R: La actualización de Fess requiere la detención del servicio. Para minimizar P: ¿Es necesario actualizar también OpenSearch? ------------------------------------------------ -R: Cada versión de Fess requiere una versión específica de OpenSearch. -Fess 15.8 es compatible con OpenSearch 3.7.0. -Los plugins de OpenSearch para Fess, como ``opensearch-analysis-fess``, deben coincidir exactamente con +R: Cada versión de |Fess| requiere una versión específica de OpenSearch. +|Fess| 15.8 es compatible con OpenSearch 3.8.0. +Los plugins de OpenSearch para |Fess|, como ``opensearch-analysis-fess``, deben coincidir exactamente con la versión de OpenSearch; por lo tanto, si actualiza OpenSearch, actualice también los plugins a la -versión correspondiente (3.7.0). +versión correspondiente (3.8.0). + +Tenga en cuenta que |Fess| 15.8 requiere el plugin k-NN y siempre envía +``knn.derived_source.enabled`` en la configuración del índice. Con un OpenSearch antiguo, la +creación de nuevos índices fallará, por lo que en la práctica es necesario actualizar OpenSearch. +Para más detalles, consulte el Paso 4. P: ¿Es necesario recrear el índice? ------------------------------------ -R: Generalmente no es necesario para actualizaciones de versión menor, pero se recomienda la recreación para actualizaciones de versión principal. -Además, si está actualizando desde la versión 15.7 o anterior a la 15.8 o posterior y desea -habilitar recién la búsqueda por vector de chunks (búsqueda semántica), es necesaria la -reindexación, ya que el índice existente no adopta el nuevo mapeo. Consulte -:doc:`../config/search-semantic` para más detalles. +R: Para una actualización de versión menor de |Fess| (15.x → 15.8) en la que no se utilice la +búsqueda por vector de chunks, generalmente no es necesario. El índice existente puede seguir +utilizándose tal cual, y como ``content_chunker.enabled`` y otras opciones similares están +deshabilitadas de forma predeterminada, el comportamiento no cambia. + +En los siguientes casos sí es necesario recrear el índice y reindexar: + +- **Si habilita recién la búsqueda por vector de chunks (búsqueda semántica)**: el índice + existente no adopta el nuevo mapeo, por lo que la reindexación es obligatoria. Para más + detalles, consulte :ref:`semantic-search-migration` (:doc:`../config/search-semantic`). +- **Si actualiza desde 14.x**: dado que OpenSearch pasa de la serie 2.x a la 3.x (actualización + de versión principal), se recomienda recrear el índice. + +.. warning:: + + Las operaciones que crean un índice nuevo (incluida la reindexación) fallarán en un OpenSearch + sin el plugin k-NN. Consulte las notas del Paso 4. P: Después de la actualización, no se muestran los resultados de búsqueda -------------------------------------------------------------------------- diff --git a/fr/15.8/install/upgrade.rst b/fr/15.8/install/upgrade.rst index 5e7efb88..98a72028 100644 --- a/fr/15.8/install/upgrade.rst +++ b/fr/15.8/install/upgrade.rst @@ -21,6 +21,13 @@ Cette procédure de mise à niveau est compatible avec les mises à niveau entre - Fess 14.x → Fess 15.8 - Fess 15.x → Fess 15.8 +.. important:: + + |Fess| 14.x est compatible avec la série OpenSearch 2.x, tandis que |Fess| 15.8 est compatible + avec OpenSearch 3.8.0. Les plugins OpenSearch pour |Fess| doivent correspondre exactement à la + version d'OpenSearch ; une mise à niveau depuis la 14.x implique donc obligatoirement une mise + à niveau majeure d'OpenSearch également. Voir :ref:`upgrade-opensearch`. + .. note:: Pour une mise à niveau depuis des versions plus anciennes (13.x ou antérieures), une mise à niveau progressive peut être nécessaire. @@ -35,7 +42,7 @@ Vérification de la compatibilité des versions Vérifiez la compatibilité entre la version de destination et la version actuelle. - `Notes de version `__ -- `Guide de mise à niveau `__ +- :doc:`prerequisites` - Configuration requise pour |Fess| 15.8 (versions de Java et d'OpenSearch) Planification du temps d'arrêt ------------------------------- @@ -62,19 +69,33 @@ Sauvegarde des données de configuration Connectez-vous à l'écran d'administration et cliquez sur « Informations système » → « Sauvegarde ». La page de sauvegarde affiche une liste des données de configuration suivantes, article par article. - Cliquez sur chaque lien pour télécharger (il ne s'agit pas d'un fichier ZIP unique, mais de fichiers individuels par article). - - - ``fess_basic_config.bulk`` - Configuration de base (paramètres généraux) - - ``fess_config.bulk`` - Informations de configuration : paramètres d'exploration, planificateur, étiquettes, correspondances de clés, etc. + Cliquez sur chaque ligne pour télécharger (il ne s'agit pas d'un fichier ZIP unique, mais de + fichiers individuels par article. Il n'existe pas de fonction de téléchargement groupé ; + téléchargez donc les articles nécessaires un par un). + + - ``fess_basic_config.bulk`` - Index de configuration (paramètres d'exploration, planificateur, + étiquettes, correspondances de clés, rôles, authentification Web/fichiers, etc. ; 19 index) + - ``fess_config.bulk`` - En plus des 19 index ci-dessus, données d'exécution telles que les + informations d'exploration, les URL en échec, les journaux de tâches, la file d'attente des + miniatures, etc. (25 index) - ``fess_user.bulk`` - Utilisateurs, rôles, groupes - - ``system.properties`` - Paramètres système - - ``fess.json`` / ``doc.json`` - Paramètres d'index (mappage) + - ``system.properties`` - Paramètres système, y compris les paramètres généraux + - ``fess.json`` - Paramètres d'index (nombre de shards, ``index.knn``, etc.) + - ``doc.json`` - Mappage des documents (définitions des champs) + + .. note:: + + ``fess_config.bulk`` inclut ``fess_basic_config.bulk``. Pour la sauvegarde de configuration + avant la mise à niveau, ``fess_basic_config.bulk``, ``fess_user.bulk`` et + ``system.properties`` suffisent. .. note:: Les données de journaux tels que les journaux de recherche et les journaux de clics (``search_log.ndjson``, ``click_log.ndjson``, ``favorite_log.ndjson``, ``user_info.ndjson``) peuvent également être téléchargées depuis la même page. - Elles ne sont pas nécessaires si vous ne sauvegardez que la configuration. + Elles ne sont pas nécessaires si vous ne sauvegardez que la configuration. Notez que ces + fichiers ``*.ndjson`` ne peuvent pas être restaurés en les téléversant depuis la page de + sauvegarde (voir « Procédure de retour arrière »). 2. **Sauvegarde des fichiers de configuration** @@ -82,11 +103,26 @@ Sauvegarde des données de configuration $ cp /path/to/fess/app/WEB-INF/conf/system.properties /backup/ $ cp /path/to/fess/app/WEB-INF/classes/fess_config.properties /backup/ + $ cp /path/to/fess/bin/fess.in.sh /backup/ - Version RPM/DEB :: + Version RPM :: + + $ sudo cp /etc/fess/system.properties /backup/ + $ sudo cp /etc/fess/fess_config.properties /backup/ + $ sudo cp /etc/sysconfig/fess /backup/ + + Version DEB :: $ sudo cp /etc/fess/system.properties /backup/ $ sudo cp /etc/fess/fess_config.properties /backup/ + $ sudo cp /etc/default/fess /backup/ + + .. note:: + + ``/etc/sysconfig/fess`` (version RPM) et ``/etc/default/fess`` (version DEB) sont des + fichiers de variables d'environnement qui définissent notamment ``FESS_PORT``, + ``FESS_HEAP_SIZE``, ``SEARCH_ENGINE_HTTP_URL`` et ``FESS_DICTIONARY_PATH``. + Pour la version TAR.GZ/ZIP, les réglages équivalents se trouvent dans ``bin/fess.in.sh``. 3. **Fichiers de configuration personnalisés** @@ -94,6 +130,14 @@ Sauvegarde des données de configuration $ cp /path/to/fess/app/WEB-INF/classes/log4j2.xml /backup/ + .. note:: + + ``app/WEB-INF/classes/log4j2.xml`` correspond à la configuration des journaux du processus + principal (Web) de |Fess|. Les processus enfants tels que le crawler utilisent des fichiers + distincts (par exemple ``app/WEB-INF/env/crawler/resources/log4j2.xml``, pour les quatre + processus ``crawler``, ``suggest``, ``thumbnail`` et ``chunk``) ; si vous les avez + personnalisés, pensez à les sauvegarder également. + Sauvegarde des données d'index ------------------------------- @@ -152,23 +196,44 @@ pour les fichiers de dictionnaire. $ docker volume ls -Arrêtez les conteneurs, puis sauvegardez les volumes :: +Arrêtez les conteneurs, puis sauvegardez les volumes. Pour l'option ``-v`` de ``docker run``, +indiquez le nom réel du volume, préfixe inclus :: $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop - $ docker run --rm -v search01_data:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-data-backup.tar.gz /data - $ docker run --rm -v search01_dictionary:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-dictionary-backup.tar.gz /data + $ PROJECT=$(basename "$(pwd)") + $ docker run --rm -v ${PROJECT}_search01_data:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-data-backup.tar.gz /data + $ docker run --rm -v ${PROJECT}_search01_dictionary:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-dictionary-backup.tar.gz /data $ docker compose -f compose.yaml -f compose-opensearch3.yaml start +.. warning:: + + Si vous indiquez ``search01_data`` sans préfixe pour ``-v``, Docker ne référence pas le volume + existant : il en crée un nouveau, vide, portant le même nom. La commande ne renvoie aucune + erreur mais produit une archive vide, ce qui peut donner l'illusion que la sauvegarde a réussi. + +.. note:: + + Le conteneur principal de |Fess| (``fess01``) n'a pas de volume dédié ; seuls les deux volumes + ci-dessus doivent donc être sauvegardés. Notez toutefois que les paramètres généraux modifiés + depuis l'écran d'administration, ainsi que les plugins installés depuis l'écran + d'administration, ne sont stockés que dans le conteneur et seraient perdus si celui-ci était + recréé. Pour les rendre persistants, spécifiez-les via ``FESS_JAVA_OPTS`` ou ``FESS_PLUGINS`` + dans le fichier Compose. + Étape 2 : Arrêt de la version actuelle ========================================= Arrêtez Fess et OpenSearch. -Version TAR.GZ/ZIP :: +La version TAR.GZ/ZIP ne fournit pas de script d'arrêt. Si vous aviez démarré ``bin/fess`` avec +l'option ``-p``, arrêtez-le à l'aide du fichier PID :: - $ kill + $ kill $(cat /path/to/fess/fess.pid) $ kill +Si vous l'aviez démarré sans ``-p``, identifiez le PID du processus et exécutez ``kill`` +manuellement (``-d`` seul ne crée pas de fichier PID). + Version RPM/DEB (systemd) :: $ sudo systemctl stop fess.service @@ -188,15 +253,42 @@ Version TAR.GZ/ZIP 1. Téléchargez et décompressez la nouvelle version :: - $ wget https://github.com/codelibs/fess/releases/download/fess-15.8.0/fess-15.8.0.tar.gz - $ tar -xzf fess-15.8.0.tar.gz + $ wget https://github.com/codelibs/fess/releases/download/fess-15.8.0/fess-15.8.0.zip + $ unzip fess-15.8.0.zip + + .. note:: + + La version archive de |Fess| n'est distribuée qu'au format ZIP (``fess-15.8.0.tar.gz`` + n'est pas fourni). 2. Copiez la configuration de l'ancienne version :: $ cp /path/to/old-fess/app/WEB-INF/conf/system.properties /path/to/fess-15.8.0/app/WEB-INF/conf/ + $ cp /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.8.0/app/WEB-INF/classes/ $ cp /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.8.0/bin/ -3. Vérifiez les différences de configuration et ajustez si nécessaire +3. Si vous avez des personnalisations, copiez également ce qui suit :: + + # Configuration des journaux + $ cp /path/to/old-fess/app/WEB-INF/classes/log4j2.xml /path/to/fess-15.8.0/app/WEB-INF/classes/ + # Plugins installés + $ cp -r /path/to/old-fess/app/WEB-INF/plugin/. /path/to/fess-15.8.0/app/WEB-INF/plugin/ + # Thème + $ cp -r /path/to/old-fess/app/themes/. /path/to/fess-15.8.0/app/themes/ + + .. warning:: + + Ne copiez pas tel quel les JSP (``app/WEB-INF/view/``) modifiés depuis l'écran + d'administration « Design ». Si la structure des JSP de la nouvelle version a changé, + l'affichage risque d'être incorrect. Réappliquez vos modifications sur les JSP de la + nouvelle version. + +4. Si vous utilisez OpenSearch intégré (configuration démarrant ``bin/fess`` sans définir + ``SEARCH_ENGINE_HTTP_URL``), copiez également les données d'index :: + + $ cp -r /path/to/old-fess/es/data/. /path/to/fess-15.8.0/es/data/ + +5. Vérifiez les différences de configuration et ajustez si nécessaire Version RPM/DEB --------------- @@ -211,8 +303,20 @@ Installez le package de la nouvelle version :: .. note:: - Les fichiers de configuration (``/etc/fess/*``) sont automatiquement conservés. - Cependant, si de nouvelles options de configuration ont été ajoutées, un ajustement manuel peut être nécessaire. + Dans la version RPM, les fichiers de configuration ``/etc/fess/*`` sont enregistrés en tant que + ``%config(noreplace)`` et sont donc conservés lors de la mise à niveau (les nouveaux fichiers + par défaut sont placés à côté avec l'extension ``.rpmnew``). Si de nouvelles options de + configuration ont été ajoutées, un ajustement manuel peut être nécessaire. + +.. warning:: + + Dans la version DEB, ``/etc/fess/*`` n'est pas enregistré en tant que conffile (les seuls + conffiles sont ``/etc/default/fess``, ``/etc/init.d/fess`` et + ``/usr/lib/systemd/system/fess.service``). Par conséquent, l'exécution de ``dpkg -i`` écrase + des fichiers tels que ``/etc/fess/fess_config.properties`` avec ceux de la nouvelle version. + Réappliquez après la mise à niveau la configuration sauvegardée à l'étape 1. + Notez que ``/etc/fess/system.properties`` n'est pas écrasé, car il s'agit d'un fichier généré + à l'exécution qui n'est pas inclus dans le paquet. Version Docker -------------- @@ -226,10 +330,13 @@ Version Docker $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull -Étape 4 : Mise à niveau d'OpenSearch (si nécessaire) -======================================================= +.. _upgrade-opensearch: + +Étape 4 : Mise à niveau d'OpenSearch +==================================== -Si vous mettez également à niveau OpenSearch, suivez les procédures suivantes. +|Fess| 15.8 est compatible avec OpenSearch 3.8.0. Si l'OpenSearch auquel vous vous connectez est +antérieur à cette version, effectuez la mise à niveau en suivant la procédure ci-dessous. .. note:: @@ -237,24 +344,43 @@ Si vous mettez également à niveau OpenSearch, suivez les procédures suivantes Pour la version Docker, l'obtention de la nouvelle image à l'étape 3 met également à jour OpenSearch et ses plugins simultanément ; cette étape n'est donc pas nécessaire. +.. important:: + + Que la recherche par vecteurs de chunks (recherche sémantique) soit utilisée ou non, |Fess| + 15.8 inclut toujours ``index.knn`` dans les réglages de l'index de recherche, ainsi que le + champ ``content_chunk_vector`` (de type ``knn_vector``) dans le mapping. Le **plugin k-NN est + donc obligatoire** sur l'OpenSearch auquel vous vous connectez. + + - Il est inclus dans la distribution standard d'OpenSearch et dans l'image de la version + Docker. + - **La distribution minimale ne l'inclut pas : la création d'un nouvel index échoue et + |Fess| ne peut pas démarrer.** + - Le réglage d'index ``knn.derived_source.enabled`` est également toujours envoyé. Sur un + OpenSearch ancien qui ne le reconnaît pas, la création de l'index échoue, que le plugin + k-NN soit présent ou non. + + Pour plus de détails, consultez la section « Prérequis » de :doc:`../config/search-semantic`. + .. warning:: Procédez avec précaution lors d'une mise à niveau majeure d'OpenSearch. Des problèmes de compatibilité d'index peuvent survenir. + |Fess| 14.x utilise la série OpenSearch 2.x ; une mise à niveau depuis la 14.x correspond donc + toujours à ce cas de figure. 1. Installez la nouvelle version d'OpenSearch 2. Réinstallez les plugins :: - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.7.0 - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.7.0 - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-minhash:3.7.0 - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-configsync:3.7.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.8.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.8.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-minhash:3.8.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-configsync:3.8.0 .. note:: La version de ces plugins doit correspondre à la version d'OpenSearch utilisée. - Fess 15.8 est compatible avec OpenSearch 3.7.0. Si les versions ne correspondent pas, + |Fess| 15.8 est compatible avec OpenSearch 3.8.0. Si les versions ne correspondent pas, l'installation du plugin échouera. 3. Démarrez OpenSearch :: @@ -267,7 +393,12 @@ Si vous mettez également à niveau OpenSearch, suivez les procédures suivantes Version TAR.GZ/ZIP :: $ cd /path/to/fess-15.8.0 - $ ./bin/fess -d + $ ./bin/fess -d -p /path/to/fess-15.8.0/fess.pid + +.. note:: + + L'option ``-p`` crée un fichier PID, qui permet d'arrêter |Fess| lors du prochain arrêt avec + ``kill $(cat /path/to/fess-15.8.0/fess.pid)``. Version RPM/DEB :: @@ -283,10 +414,26 @@ Version Docker :: 1. **Vérification des journaux** - Vérifiez qu'il n'y a pas d'erreurs :: + Vérifiez qu'il n'y a pas d'erreurs. + + Version TAR.GZ/ZIP :: $ tail -f /path/to/fess/logs/fess.log + Version RPM/DEB :: + + $ sudo tail -f /var/log/fess/fess.log + + Version Docker :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01 + + .. note:: + + Le même répertoire de journaux contient également ``fess-crawler.log`` pour le traitement + d'exploration, ``audit.log`` pour l'authentification et les opérations d'administration, et + ``searchlog.log`` pour les requêtes de recherche. + 2. **Accès à l'interface Web** Accédez à http://localhost:8080/ via un navigateur. @@ -323,6 +470,42 @@ En cas de mise à niveau majeure, il est recommandé de recréer l'index. 3. Attendez la fin de l'exploration 4. Vérifiez les résultats de recherche +.. warning:: + + La réindexation recrée l'index avec le nouveau mapping ; elle échoue donc sur un OpenSearch + dépourvu du plugin k-NN. Consultez les remarques de l'étape 4. + +Migrations spécifiques à la 15.8 +================================ + +Si vous effectuez une mise à niveau depuis la version 15.7 ou antérieure vers la 15.8, les +actions suivantes sont nécessaires selon les fonctionnalités que vous utilisez. + +Si vous utilisiez la recherche sémantique +----------------------------------------- + +Le plugin ``fess-webapp-semantic-search``, qui fournissait la recherche sémantique dans les +versions 15.7 et antérieures, n'est plus nécessaire (obsolète) car cette fonctionnalité a été +intégrée au cœur du produit en 15.8. Vous devez supprimer le plugin, retirer +``-Dfess.semantic_search.*`` ainsi que ``-Drank.fusion.searchers=default,semantic``, et détacher +l'ancien pipeline d'ingestion. Pour la procédure, consultez :ref:`semantic-search-migration` +(:doc:`../config/search-semantic`). + +Si vous utilisiez le mode de recherche IA (chat RAG) +---------------------------------------------------- + +À partir de la 15.8, la fonctionnalité du mode de recherche IA (chat RAG) a été séparée en +plugins tels que ``fess-llm-ollama``, ``fess-llm-openai`` et ``fess-llm-gemini``. Installez le +plugin correspondant au fournisseur que vous utilisez depuis « Système » → « Plugins » dans +l'écran d'administration. + +Mise à jour de la version des plugins +------------------------------------- + +Les plugins installés dans ``app/WEB-INF/plugin/`` doivent être remplacés par ceux correspondant +à la version de |Fess|. Si vous spécifiez ``FESS_PLUGINS`` pour la version Docker, mettez à jour +la partie version, par exemple ``fess-ds-wikipedia:15.8.0``. + Procédure de retour arrière ============================ @@ -363,10 +546,43 @@ Ou restauration du répertoire depuis la sauvegarde :: $ sudo tar xzf /backup/opensearch-data-backup.tar.gz -C / $ sudo systemctl start opensearch +Pour la version Docker, revenez au fichier Compose de l'ancienne version, puis restaurez le +contenu du volume :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + $ PROJECT=$(basename "$(pwd)") + $ docker run --rm -v ${PROJECT}_search01_data:/data -v $(pwd):/backup ubuntu \ + sh -c "rm -rf /data/* && tar xzf /backup/search01-data-backup.tar.gz -C /" + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + .. note:: - Les données de configuration téléchargées depuis l'écran d'administration (fichiers ``*.bulk``) peuvent être restaurées - en les réimportant via la fonction de téléversement de la page « Informations système » → « Sauvegarde » après le démarrage de Fess. + Les données de configuration téléchargées depuis l'écran d'administration peuvent être + restaurées en les réimportant via la fonction de téléversement de la page « Informations + système » → « Sauvegarde », une fois |Fess| démarré. Seuls les fichiers suivants peuvent être + téléversés, un fichier par opération : ``*.bulk``, les ``*.properties`` commençant par + ``system``, les ``*.xml`` commençant par ``gsa``, les ``*.json`` commençant par ``fess`` et les + ``*.json`` commençant par ``doc``. Les fichiers ``*.ndjson`` tels que les journaux de recherche + ne sont pas acceptés et provoquent une erreur. + +.. warning:: + + Le téléversement de ``fess.json`` et de ``doc.json`` écrase directement les fichiers de + définition d'index fournis avec |Fess|. Si vous téléversez après la mise à niveau un + ``fess.json`` ou un ``doc.json`` d'une ancienne version, les réglages et le mapping d'index de + la nouvelle version seront perdus. Ne les téléversez pas en dehors d'un retour arrière. + +.. note:: + + Le fichier ``system.properties`` téléversé n'est chargé qu'en mémoire et n'est jamais écrit sur + disque : son contenu est donc perdu au redémarrage de |Fess|. Pour une restauration fiable, + placez directement le fichier de sauvegarde à l'emplacement approprié (``app/WEB-INF/conf/`` + pour la version TAR.GZ/ZIP, ``/etc/fess/`` pour la version RPM/DEB) avant de démarrer |Fess|. + +.. note:: + + L'importation s'exécute de façon asynchrone ; l'écran indique seulement qu'elle a démarré. + Vérifiez ``fess.log`` pour savoir si elle a réellement réussi. Étape 4 : Démarrage et vérification du service ----------------------------------------------- @@ -393,19 +609,36 @@ R : La mise à niveau de Fess nécessite l'arrêt du service. Pour minimiser le Q : Est-il nécessaire de mettre à niveau OpenSearch également ? ---------------------------------------------------------------- -R : La version d'OpenSearch compatible est déterminée pour chaque version de Fess. -Fess 15.8 est compatible avec OpenSearch 3.7.0. -Les plugins OpenSearch pour Fess tels que ``opensearch-analysis-fess`` doivent correspondre exactement à la version d'OpenSearch ; -si vous mettez à niveau OpenSearch, veuillez également mettre à jour les plugins vers la version correspondante (3.7.0). +R : La version d'OpenSearch compatible est déterminée pour chaque version de |Fess|. +|Fess| 15.8 est compatible avec OpenSearch 3.8.0. +Les plugins OpenSearch pour |Fess| tels que ``opensearch-analysis-fess`` doivent correspondre exactement à la version d'OpenSearch ; +si vous mettez à niveau OpenSearch, mettez également à jour les plugins vers la version correspondante (3.8.0). + +Notez par ailleurs que |Fess| 15.8 rend le plugin k-NN obligatoire et envoie toujours +``knn.derived_source.enabled`` dans les réglages de l'index. Avec un OpenSearch ancien, la +création d'un nouvel index échoue : la mise à niveau d'OpenSearch est donc requise dans la +pratique. Voir l'étape 4 pour plus de détails. Q : Est-il nécessaire de recréer l'index ? ------------------------------------------- -R : Pour une mise à niveau mineure, ce n'est généralement pas nécessaire, mais pour une mise à niveau majeure, la recréation est recommandée. -Par ailleurs, si vous effectuez une mise à niveau depuis la version 15.7 ou antérieure vers la -15.8 ou une version ultérieure et que vous souhaitez activer nouvellement la recherche par -vecteurs de chunks (recherche sémantique), une réindexation est nécessaire, car l'index existant -n'adopte pas le nouveau mapping. Voir :doc:`../config/search-semantic` pour plus de détails. +R : Pour une mise à niveau mineure de |Fess| (15.x → 15.8) sans utilisation de la recherche par +vecteurs de chunks, ce n'est en général pas nécessaire. L'index existant peut continuer d'être +utilisé tel quel, et comme ``content_chunker.enabled`` (entre autres) est désactivé par défaut, +le comportement ne change pas. + +Une recréation et une réindexation sont nécessaires dans les cas suivants : + +- **Activation nouvelle de la recherche par vecteurs de chunks (recherche sémantique)** : l'index + existant n'adopte pas le nouveau mapping, une réindexation est donc obligatoire. Voir + :ref:`semantic-search-migration` (:doc:`../config/search-semantic`) pour plus de détails. +- **Mise à niveau depuis la 14.x** : OpenSearch passant de la série 2.x à la série 3.x (mise à + niveau majeure), la recréation de l'index est recommandée. + +.. warning:: + + Les opérations créant un nouvel index (y compris la réindexation) échouent sur un OpenSearch + dépourvu du plugin k-NN. Consultez les remarques de l'étape 4. Q : Les résultats de recherche ne s'affichent pas après la mise à niveau -------------------------------------------------------------------------- diff --git a/ja/15.8/install/upgrade.rst b/ja/15.8/install/upgrade.rst index 1ccd6fa3..7fb8f5db 100644 --- a/ja/15.8/install/upgrade.rst +++ b/ja/15.8/install/upgrade.rst @@ -14,31 +14,38 @@ - バージョンによっては、設定ファイルの形式が変更されている場合があります 対応バージョン -============ +============== このアップグレード手順は、以下のバージョン間のアップグレードに対応しています： - Fess 14.x → Fess 15.8 - Fess 15.x → Fess 15.8 +.. important:: + + |Fess| 14.x は OpenSearch 2.x 系、\ |Fess| 15.8 は OpenSearch 3.8.0 に対応しています。 + |Fess| 用の OpenSearch プラグインは OpenSearch のバージョンと完全に一致している必要があるため、 + 14.x からアップグレードする場合は OpenSearch のメジャーバージョンアップも必須です。 + :ref:`upgrade-opensearch` を参照してください。 + .. note:: さらに古いバージョン（13.x 以前）からアップグレードする場合は、段階的なアップグレードが必要な場合があります。 詳細はリリースノートを確認してください。 アップグレード前の準備 -==================== +====================== バージョン互換性の確認 --------------------- +---------------------- アップグレード先のバージョンと現在のバージョンの互換性を確認してください。 - `リリースノート `__ -- `アップグレードガイド `__ +- :doc:`prerequisites` - |Fess| 15.8 の動作環境（Java、OpenSearch のバージョン） ダウンタイムの計画 ----------------- +------------------ アップグレード作業には、システムの停止が必要です。以下を考慮してダウンタイムを計画してください： @@ -50,31 +57,43 @@ **推奨メンテナンス時間**: 合計 2 〜 4時間 ステップ 1: データのバックアップ -============================== +================================ アップグレード前に、すべてのデータをバックアップしてください。 設定データのバックアップ ----------------------- +------------------------ 1. **管理画面からのバックアップ** 管理画面にログインし、「システム情報」→「バックアップ」をクリックします。 バックアップページには、以下の設定データが項目ごとに一覧表示されます。 - 各リンクをクリックしてダウンロードします（単一の ZIP ファイルではなく、項目ごとの個別ファイルです）。 + 各行をクリックしてダウンロードします（単一の ZIP ファイルではなく、項目ごとの個別ファイルです。 + 一括ダウンロードの機能はないため、必要な項目を 1 つずつダウンロードします）。 - - ``fess_basic_config.bulk`` - 基本設定（全般設定） - - ``fess_config.bulk`` - クロール設定、スケジューラー、ラベル、キーマッチなどの構成情報 + - ``fess_basic_config.bulk`` - 設定インデックス（クロール設定、スケジューラー、ラベル、 + キーマッチ、ロール、Web/ファイル認証など 19 インデックス） + - ``fess_config.bulk`` - 上記 19 インデックスに加えて、クロール情報、障害 URL、ジョブログ、 + サムネイルキューなどの実行時データを含む 25 インデックス - ``fess_user.bulk`` - ユーザー、ロール、グループ - - ``system.properties`` - システム設定 - - ``fess.json`` / ``doc.json`` - インデックスの設定（マッピング） + - ``system.properties`` - 全般設定を含むシステム設定 + - ``fess.json`` - インデックスの設定（シャード数、\ ``index.knn`` など） + - ``doc.json`` - ドキュメントのマッピング（フィールド定義） + + .. note:: + + ``fess_config.bulk`` は ``fess_basic_config.bulk`` を包含しています。アップグレード前の + 設定バックアップとしては、\ ``fess_basic_config.bulk``\ 、\ ``fess_user.bulk``\ 、 + ``system.properties`` の 3 つで十分です。 .. note:: 検索ログやクリックログなどのログデータ（``search_log.ndjson``、``click_log.ndjson``、 ``favorite_log.ndjson``、``user_info.ndjson``）も同じページからダウンロードできます。 - 設定のみをバックアップする場合は不要です。 + 設定のみをバックアップする場合は不要です。なお、これらの ``*.ndjson`` ファイルは + バックアップページからアップロードして復元することはできません + （「ロールバック手順」を参照）。 2. **設定ファイルのバックアップ** @@ -82,11 +101,26 @@ $ cp /path/to/fess/app/WEB-INF/conf/system.properties /backup/ $ cp /path/to/fess/app/WEB-INF/classes/fess_config.properties /backup/ + $ cp /path/to/fess/bin/fess.in.sh /backup/ - RPM/DEB 版:: + RPM 版:: $ sudo cp /etc/fess/system.properties /backup/ $ sudo cp /etc/fess/fess_config.properties /backup/ + $ sudo cp /etc/sysconfig/fess /backup/ + + DEB 版:: + + $ sudo cp /etc/fess/system.properties /backup/ + $ sudo cp /etc/fess/fess_config.properties /backup/ + $ sudo cp /etc/default/fess /backup/ + + .. note:: + + ``/etc/sysconfig/fess``\ （RPM 版）と ``/etc/default/fess``\ （DEB 版）は、 + ``FESS_PORT``\ 、\ ``FESS_HEAP_SIZE``\ 、\ ``SEARCH_ENGINE_HTTP_URL``\ 、 + ``FESS_DICTIONARY_PATH`` などを指定する環境変数ファイルです。 + TAR.GZ/ZIP 版でこれらに相当する設定は ``bin/fess.in.sh`` にあります。 3. **カスタマイズした設定ファイル** @@ -94,13 +128,21 @@ $ cp /path/to/fess/app/WEB-INF/classes/log4j2.xml /backup/ + .. note:: + + ``app/WEB-INF/classes/log4j2.xml`` は |Fess| 本体（Web）プロセスのログ設定です。 + クローラーなどの子プロセスは別々のファイル + （``app/WEB-INF/env/crawler/resources/log4j2.xml`` など、\ ``crawler``\ 、\ ``suggest``\ 、 + ``thumbnail``\ 、\ ``chunk`` の 4 つ）を使用するため、これらを変更している場合は + あわせてバックアップしてください。 + インデックスデータのバックアップ ------------------------------- +-------------------------------- OpenSearch のインデックスデータをバックアップします。 方法 1: スナップショット機能を使用（推奨） -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ OpenSearch のスナップショット機能を使用して、インデックスをバックアップします。 @@ -128,7 +170,7 @@ OpenSearch のスナップショット機能を使用して、インデックス $ curl -X GET "http://localhost:9200/_snapshot/fess_backup/snapshot_1" 方法 2: ディレクトリごとバックアップ -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ OpenSearch を停止してから、データディレクトリをバックアップします。 @@ -139,7 +181,7 @@ OpenSearch を停止してから、データディレクトリをバックアッ $ sudo systemctl start opensearch Docker 版のバックアップ ---------------------- +----------------------- OpenSearch のデータは Docker ボリュームに保存されます。\ ``compose-opensearch3.yaml`` では、 インデックスデータ用の ``search01_data`` と、辞書ファイル用の ``search01_dictionary`` の @@ -152,23 +194,42 @@ OpenSearch のデータは Docker ボリュームに保存されます。\ ``com $ docker volume ls -コンテナーを停止してから、ボリュームをバックアップします:: +コンテナーを停止してから、ボリュームをバックアップします。\ ``docker run`` の ``-v`` には、 +接頭辞を含む実際のボリューム名を指定します:: $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop - $ docker run --rm -v search01_data:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-data-backup.tar.gz /data - $ docker run --rm -v search01_dictionary:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-dictionary-backup.tar.gz /data + $ PROJECT=$(basename "$(pwd)") + $ docker run --rm -v ${PROJECT}_search01_data:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-data-backup.tar.gz /data + $ docker run --rm -v ${PROJECT}_search01_dictionary:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-dictionary-backup.tar.gz /data $ docker compose -f compose.yaml -f compose-opensearch3.yaml start +.. warning:: + + ``-v`` に接頭辞なしの ``search01_data`` を指定すると、Docker は既存のボリュームを参照せず、 + 同名の空のボリュームを新規作成します。コマンドはエラーにならず中身が空のアーカイブが + 作成されるため、バックアップが取得できたように見えてしまいます。 + +.. note:: + + |Fess| 本体（``fess01``）のコンテナーには専用のボリュームがないため、バックアップ対象は + 上記の 2 つのみです。ただし、管理画面から変更した全般設定や、管理画面からインストールした + プラグインはコンテナー内にのみ保存され、コンテナーを再作成すると失われます。 + これらは Compose ファイルの ``FESS_JAVA_OPTS`` や ``FESS_PLUGINS`` で指定して永続化してください。 + ステップ 2: 現在のバージョンの停止 -================================ +================================== Fess と OpenSearch を停止します。 -TAR.GZ/ZIP 版:: +TAR.GZ/ZIP 版には停止用のスクリプトは同梱されていません。\ ``bin/fess`` を ``-p`` オプション付きで +起動していた場合は、PID ファイルを使って停止します:: - $ kill + $ kill $(cat /path/to/fess/fess.pid) $ kill +``-p`` を指定せずに起動していた場合は、プロセス ID を確認して ``kill`` します +（``-d`` だけでは PID ファイルは作成されません）。 + RPM/DEB 版 (systemd):: $ sudo systemctl stop fess.service @@ -179,27 +240,53 @@ Docker 版:: $ docker compose -f compose.yaml -f compose-opensearch3.yaml down ステップ 3: 新しいバージョンのインストール -====================================== +========================================== インストール方法により、手順が異なります。 TAR.GZ/ZIP 版 ------------- +------------- 1. 新しいバージョンをダウンロードして展開:: - $ wget https://github.com/codelibs/fess/releases/download/fess-15.8.0/fess-15.8.0.tar.gz - $ tar -xzf fess-15.8.0.tar.gz + $ wget https://github.com/codelibs/fess/releases/download/fess-15.8.0/fess-15.8.0.zip + $ unzip fess-15.8.0.zip + + .. note:: + + |Fess| のアーカイブ版は ZIP 形式でのみ配布されています（``fess-15.8.0.tar.gz`` は + 提供されていません）。 2. 古いバージョンの設定をコピー:: $ cp /path/to/old-fess/app/WEB-INF/conf/system.properties /path/to/fess-15.8.0/app/WEB-INF/conf/ + $ cp /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.8.0/app/WEB-INF/classes/ $ cp /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.8.0/bin/ -3. 設定差分を確認し、必要に応じて調整します +3. カスタマイズしている場合は、以下もコピーします:: + + # ログ設定 + $ cp /path/to/old-fess/app/WEB-INF/classes/log4j2.xml /path/to/fess-15.8.0/app/WEB-INF/classes/ + # インストール済みプラグイン + $ cp -r /path/to/old-fess/app/WEB-INF/plugin/. /path/to/fess-15.8.0/app/WEB-INF/plugin/ + # テーマ + $ cp -r /path/to/old-fess/app/themes/. /path/to/fess-15.8.0/app/themes/ + + .. warning:: + + 管理画面「デザイン」で編集した JSP（``app/WEB-INF/view/``）は、そのままコピーしないでください。 + 新しいバージョンの JSP と構造が変わっている場合、画面が正しく表示されなくなります。 + 新しいバージョンの JSP に対して変更内容を再適用してください。 + +4. 組み込み OpenSearch（``SEARCH_ENGINE_HTTP_URL`` を設定せずに ``bin/fess`` を起動する構成）を + 使用している場合は、インデックスデータもコピーします:: + + $ cp -r /path/to/old-fess/es/data/. /path/to/fess-15.8.0/es/data/ + +5. 設定差分を確認し、必要に応じて調整します RPM/DEB 版 ---------- +---------- 新しいバージョンのパッケージをインストール:: @@ -211,11 +298,22 @@ RPM/DEB 版 .. note:: - 設定ファイル（``/etc/fess/*``）は自動的に保持されます。 - ただし、新しい設定オプションが追加されている場合は、手動で調整が必要です。 + RPM 版では ``/etc/fess/*`` の設定ファイルは ``%config(noreplace)`` として登録されているため、 + アップグレード時も保持されます（新しい既定のファイルは ``.rpmnew`` として併置されます）。 + 新しい設定オプションが追加されている場合は、手動で調整が必要です。 + +.. warning:: + + DEB 版では ``/etc/fess/*`` は conffile として登録されていません（conffile は + ``/etc/default/fess``\ 、\ ``/etc/init.d/fess``\ 、\ ``/usr/lib/systemd/system/fess.service`` + の 3 つのみです）。そのため ``dpkg -i`` を実行すると ``/etc/fess/fess_config.properties`` などが + 新しいバージョンのファイルで上書きされます。ステップ 1 でバックアップした設定を、 + アップグレード後に再適用してください。 + なお ``/etc/fess/system.properties`` はパッケージに含まれない実行時生成ファイルのため、 + 上書きされません。 Docker 版 --------- +--------- 1. 新しいバージョンの Compose ファイルを取得:: @@ -226,10 +324,13 @@ Docker 版 $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull -ステップ 4: OpenSearch のアップグレード（必要な場合） -================================================= +.. _upgrade-opensearch: + +ステップ 4: OpenSearch のアップグレード +======================================= -OpenSearch もアップグレードする場合は、以下の手順に従ってください。 +|Fess| 15.8 は OpenSearch 3.8.0 に対応しています。接続先の OpenSearch がこれより古い場合は、 +以下の手順でアップグレードしてください。 .. note:: @@ -237,24 +338,38 @@ OpenSearch もアップグレードする場合は、以下の手順に従って Docker 版では、ステップ 3 で新しいイメージを取得すると OpenSearch とプラグインも まとめて更新されるため、本ステップは不要です。 +.. important:: + + |Fess| 15.8 は、チャンクベクトル検索（セマンティック検索）の利用有無にかかわらず、 + 検索インデックスの設定に ``index.knn`` を、マッピングに ``content_chunk_vector``\ （\ ``knn_vector`` + 型）を常に含めます。そのため、接続先の OpenSearch には **k-NN プラグインが必須** です。 + + - 標準配布の OpenSearch および Docker 版のイメージには同梱されています。 + - **minimal 配布には含まれないため、インデックスの新規作成に失敗し、\ |Fess| が起動できません。** + - インデックス設定には ``knn.derived_source.enabled`` も常に送信されます。これを認識できない + 古い OpenSearch では、k-NN プラグインの有無にかかわらずインデックスの作成に失敗します。 + + 詳細は :doc:`../config/search-semantic` の「前提条件」を参照してください。 + .. warning:: OpenSearch のメジャーバージョンアップグレードは慎重に行ってください。 インデックスの互換性に問題が発生する可能性があります。 + |Fess| 14.x は OpenSearch 2.x 系のため、14.x からのアップグレードでは必ずこのケースに該当します。 1. 新しいバージョンの OpenSearch をインストール 2. プラグインを再インストール:: - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.7.0 - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.7.0 - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-minhash:3.7.0 - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-configsync:3.7.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.8.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.8.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-minhash:3.8.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-configsync:3.8.0 .. note:: これらのプラグインのバージョンは、使用する OpenSearch のバージョンと一致させる必要があります。 - Fess 15.8 は OpenSearch 3.7.0 に対応しています。バージョンが一致しない場合、 + |Fess| 15.8 は OpenSearch 3.8.0 に対応しています。バージョンが一致しない場合、 プラグインのインストールに失敗します。 3. OpenSearch を起動:: @@ -262,12 +377,17 @@ OpenSearch もアップグレードする場合は、以下の手順に従って $ sudo systemctl start opensearch.service ステップ 5: 新しいバージョンの起動 -================================ +================================== TAR.GZ/ZIP 版:: $ cd /path/to/fess-15.8.0 - $ ./bin/fess -d + $ ./bin/fess -d -p /path/to/fess-15.8.0/fess.pid + +.. note:: + + ``-p`` を指定すると PID ファイルが作成され、次回の停止時に + ``kill $(cat /path/to/fess-15.8.0/fess.pid)`` で停止できます。 RPM/DEB 版:: @@ -279,14 +399,29 @@ Docker 版:: $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d ステップ 6: 動作確認 -================== +==================== 1. **ログの確認** - エラーがないことを確認します:: + エラーがないことを確認します。 + + TAR.GZ/ZIP 版:: $ tail -f /path/to/fess/logs/fess.log + RPM/DEB 版:: + + $ sudo tail -f /var/log/fess/fess.log + + Docker 版:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01 + + .. note:: + + 同じログディレクトリーに、クロール処理の ``fess-crawler.log``\ 、認証や管理操作の + ``audit.log``\ 、検索リクエストの ``searchlog.log`` も出力されます。 + 2. **Web インターフェースへのアクセス** ブラウザーで http://localhost:8080/ にアクセスします。 @@ -305,7 +440,7 @@ Docker 版:: 検索画面で検索を実行し、正常に結果が返されることを確認します。 ステップ 7: インデックスの再作成（推奨） -==================================== +======================================== メジャーバージョンアップの場合、インデックスを再作成することを推奨します。 @@ -323,13 +458,46 @@ Docker 版:: 3. クロールが完了するまで待機 4. 検索結果を確認 +.. warning:: + + 再インデクシングでは新しいマッピングでインデックスが作り直されるため、k-NN プラグインの + ない OpenSearch では失敗します。ステップ 4 の注意事項を確認してください。 + +15.8 固有の移行作業 +=================== + +15.7 以前から 15.8 へアップグレードする場合、利用している機能に応じて以下の作業が必要です。 + +セマンティック検索を利用していた場合 +------------------------------------ + +15.7 以前でセマンティック検索を提供していた ``fess-webapp-semantic-search`` プラグインは、 +15.8 でコアに統合されたため不要になりました（非推奨）。プラグインの削除、\ ``-Dfess.semantic_search.*`` +および ``-Drank.fusion.searchers=default,semantic`` の削除、旧 ingest pipeline のデタッチが +必要です。手順は :ref:`semantic-search-migration`\ （:doc:`../config/search-semantic`）を +参照してください。 + +AI 検索モード（RAG チャット）を利用していた場合 +----------------------------------------------- + +15.8 から、AI 検索モード（RAG チャット）の機能は ``fess-llm-ollama``\ 、\ ``fess-llm-openai``\ 、 +``fess-llm-gemini`` などのプラグインとして分離されました。利用しているプロバイダーに対応する +プラグインを管理画面「システム」→「プラグイン」からインストールしてください。 + +プラグインのバージョン更新 +-------------------------- + +``app/WEB-INF/plugin/`` にインストールされているプラグインは、\ |Fess| のバージョンに対応した +ものへ入れ替えが必要です。Docker 版で ``FESS_PLUGINS`` を指定している場合は、 +``fess-ds-wikipedia:15.8.0`` のようにバージョン部分を更新してください。 + ロールバック手順 -============== +================ アップグレードに失敗した場合、以下の手順でロールバックできます。 ステップ 1: 新しいバージョンの停止 ------------------------------- +---------------------------------- :: @@ -337,7 +505,7 @@ Docker 版:: $ sudo systemctl stop opensearch.service ステップ 2: 古いバージョンの復元 ----------------------------- +-------------------------------- バックアップから設定ファイルとデータを復元します。 @@ -350,7 +518,7 @@ RPM/DEB 版の場合:: $ sudo dpkg -i fess-.deb ステップ 3: データの復元 ----------------------- +------------------------ スナップショットから復元:: @@ -363,13 +531,43 @@ RPM/DEB 版の場合:: $ sudo tar xzf /backup/opensearch-data-backup.tar.gz -C / $ sudo systemctl start opensearch +Docker 版では、旧バージョンの Compose ファイルに戻したうえで、ボリュームの内容を復元します:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + $ PROJECT=$(basename "$(pwd)") + $ docker run --rm -v ${PROJECT}_search01_data:/data -v $(pwd):/backup ubuntu \ + sh -c "rm -rf /data/* && tar xzf /backup/search01-data-backup.tar.gz -C /" + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +.. note:: + + 管理画面からダウンロードした設定データは、\ |Fess| の起動後に「システム情報」→「バックアップ」 + ページのアップロード機能から再度インポートして復元できます。アップロードできるのは + ``*.bulk``\ 、\ ``system`` で始まる ``*.properties``\ 、\ ``gsa`` で始まる ``*.xml``\ 、 + ``fess`` で始まる ``*.json``\ 、\ ``doc`` で始まる ``*.json`` のみで、1 回の操作につき 1 ファイルです。 + 検索ログなどの ``*.ndjson`` ファイルは受け付けられず、エラーになります。 + +.. warning:: + + ``fess.json`` と ``doc.json`` のアップロードは、\ |Fess| に同梱されているインデックス定義 + ファイルそのものを上書きします。アップグレード後に旧バージョンの ``fess.json`` や + ``doc.json`` をアップロードすると、新しいバージョンのインデックス設定・マッピングが失われます。 + ロールバックの目的以外ではアップロードしないでください。 + +.. note:: + + アップロードされた ``system.properties`` はメモリー上にのみ読み込まれ、ファイルには + 書き出されません。そのため ``system.properties`` の内容は |Fess| を再起動すると失われます。 + 確実に復元するには、バックアップしたファイルを所定の場所（TAR.GZ/ZIP 版は + ``app/WEB-INF/conf/``\ 、RPM/DEB 版は ``/etc/fess/``\ ）へ直接配置してから起動してください。 + .. note:: - 管理画面からダウンロードした設定データ（``*.bulk`` ファイル）は、Fess の起動後に - 「システム情報」→「バックアップ」ページのアップロード機能から再度インポートして復元できます。 + インポートは非同期で実行され、画面には開始した旨のみが表示されます。 + 実際に成功したかどうかは ``fess.log`` を確認してください。 ステップ 4: サービスの起動と確認 ----------------------------- +-------------------------------- :: @@ -379,10 +577,10 @@ RPM/DEB 版の場合:: 動作を確認し、正常に戻ったことを確認します。 よくある質問 -========== +============ Q: ダウンタイムなしでアップグレードできますか？ --------------------------------------------- +----------------------------------------------- A: Fess のアップグレードには、サービスの停止が必要です。ダウンタイムを最小限にするには、以下を検討してください： @@ -391,24 +589,40 @@ A: Fess のアップグレードには、サービスの停止が必要です。 - メンテナンス時間を十分に確保する Q: OpenSearch もアップグレードする必要がありますか？ -------------------------------------------------- +---------------------------------------------------- -A: Fess のバージョンごとに対応する OpenSearch のバージョンが決まっています。 -Fess 15.8 は OpenSearch 3.7.0 に対応しています。 -``opensearch-analysis-fess`` などの Fess 用 OpenSearch プラグインは OpenSearch のバージョンと +A: |Fess| のバージョンごとに対応する OpenSearch のバージョンが決まっています。 +|Fess| 15.8 は OpenSearch 3.8.0 に対応しています。 +``opensearch-analysis-fess`` などの |Fess| 用 OpenSearch プラグインは OpenSearch のバージョンと 完全に一致している必要があるため、OpenSearch をアップグレードする場合は、 -対応するバージョン（3.7.0）のプラグインに更新してください。 +対応するバージョン（3.8.0）のプラグインに更新してください。 + +なお |Fess| 15.8 は k-NN プラグインを必須とし、インデックス設定に ``knn.derived_source.enabled`` +を常に送信します。古い OpenSearch のままでは新しいインデックスの作成に失敗するため、 +実質的に OpenSearch のアップグレードが必要です。詳細はステップ 4 を参照してください。 Q: インデックスを再作成する必要がありますか？ ------------------------------------------- +--------------------------------------------- -A: マイナーバージョンアップの場合は通常不要ですが、メジャーバージョンアップの場合は再作成を推奨します。 -また、15.7 以前から 15.8 以降へアップグレードし、新たにチャンクベクトル検索（セマンティック検索）を -有効にする場合は、既存インデックスにはマッピングが反映されないため、再インデクシングが必須です。 -詳細は :doc:`../config/search-semantic` を参照してください。 +A: |Fess| のマイナーバージョンアップ（15.x → 15.8）で、チャンクベクトル検索を利用しない場合は +通常不要です。既存インデックスはそのまま利用でき、\ ``content_chunker.enabled`` などは既定で +無効のため挙動は変わりません。 + +次の場合は再作成・再インデクシングが必要です。 + +- **新たにチャンクベクトル検索（セマンティック検索）を有効にする場合**: 既存インデックスには + 新しいマッピングが反映されないため、再インデクシングが必須です。詳細は + :ref:`semantic-search-migration`\ （:doc:`../config/search-semantic`）を参照してください。 +- **14.x からアップグレードする場合**: OpenSearch が 2.x から 3.x へメジャーバージョンアップ + するため、インデックスの再作成を推奨します。 + +.. warning:: + + インデックスを新規に作成する操作（再インデクシングを含む）は、k-NN プラグインのない + OpenSearch では失敗します。ステップ 4 の注意事項を確認してください。 Q: アップグレード後、検索結果が表示されません ------------------------------------------- +--------------------------------------------- A: 以下を確認してください： @@ -417,7 +631,7 @@ A: 以下を確認してください： 3. クロールを再実行 次のステップ -========== +============ アップグレードが完了したら： diff --git a/ko/15.8/install/upgrade.rst b/ko/15.8/install/upgrade.rst index b1103e1e..360b6285 100644 --- a/ko/15.8/install/upgrade.rst +++ b/ko/15.8/install/upgrade.rst @@ -21,6 +21,13 @@ - Fess 14.x → Fess 15.8 - Fess 15.x → Fess 15.8 +.. important:: + + |Fess| 14.x는 OpenSearch 2.x 계열, |Fess| 15.8은 OpenSearch 3.8.0에 대응합니다. + |Fess| 용 OpenSearch 플러그인은 OpenSearch 버전과 완전히 일치해야 하므로, + 14.x에서 업그레이드하는 경우 OpenSearch의 메이저 버전 업그레이드도 필수입니다. + :ref:`upgrade-opensearch` 를 참조하십시오. + .. note:: 더 오래된 버전(13.x 이전)에서 업그레이드하는 경우 단계적 업그레이드가 필요할 수 있습니다. @@ -35,7 +42,7 @@ 업그레이드 대상 버전과 현재 버전의 호환성을 확인하십시오. - `릴리스 노트 `__ -- `업그레이드 가이드 `__ +- :doc:`prerequisites` - |Fess| 15.8의 동작 환경(Java, OpenSearch 버전) 다운타임 계획 ---------------- @@ -62,19 +69,31 @@ 관리 화면에 로그인하여 「시스템 정보」→「백업」을 클릭합니다. 백업 페이지에는 다음 설정 데이터가 항목별로 목록 표시됩니다. - 각 링크를 클릭하여 다운로드합니다(단일 ZIP 파일이 아닌 항목별 개별 파일입니다). + 각 행을 클릭하여 다운로드합니다(단일 ZIP 파일이 아니라 항목별 개별 파일입니다. + 일괄 다운로드 기능은 없으므로 필요한 항목을 하나씩 다운로드합니다). - - ``fess_basic_config.bulk`` - 기본 설정(전반 설정) - - ``fess_config.bulk`` - 크롤 설정, 스케줄러, 레이블, 키 매치 등의 구성 정보 + - ``fess_basic_config.bulk`` - 설정 인덱스(크롤 설정, 스케줄러, 레이블, + 키 매치, 역할, 웹/파일 인증 등 19개 인덱스) + - ``fess_config.bulk`` - 위 19개 인덱스에 더해 크롤 정보, 장애 URL, 작업 로그, + 썸네일 큐 등 실행 시 데이터를 포함하는 25개 인덱스 - ``fess_user.bulk`` - 사용자, 역할, 그룹 - - ``system.properties`` - 시스템 설정 - - ``fess.json`` / ``doc.json`` - 인덱스 설정(매핑) + - ``system.properties`` - 전반 설정을 포함하는 시스템 설정 + - ``fess.json`` - 인덱스 설정(샤드 수, ``index.knn`` 등) + - ``doc.json`` - 문서 매핑(필드 정의) + + .. note:: + + ``fess_config.bulk`` 는 ``fess_basic_config.bulk`` 를 포함합니다. 업그레이드 전 + 설정 백업으로는 ``fess_basic_config.bulk``, ``fess_user.bulk``, + ``system.properties`` 3개면 충분합니다. .. note:: 검색 로그나 클릭 로그 등의 로그 데이터(``search_log.ndjson``, ``click_log.ndjson``, ``favorite_log.ndjson``, ``user_info.ndjson``)도 같은 페이지에서 다운로드할 수 있습니다. - 설정만 백업하는 경우에는 불필요합니다. + 설정만 백업하는 경우에는 불필요합니다. 또한 이 ``*.ndjson`` 파일들은 + 백업 페이지에서 업로드하여 복원할 수 없습니다 + (「롤백 절차」 참조). 2. **설정 파일 백업** @@ -82,11 +101,26 @@ $ cp /path/to/fess/app/WEB-INF/conf/system.properties /backup/ $ cp /path/to/fess/app/WEB-INF/classes/fess_config.properties /backup/ + $ cp /path/to/fess/bin/fess.in.sh /backup/ - RPM/DEB 버전:: + RPM 버전:: $ sudo cp /etc/fess/system.properties /backup/ $ sudo cp /etc/fess/fess_config.properties /backup/ + $ sudo cp /etc/sysconfig/fess /backup/ + + DEB 버전:: + + $ sudo cp /etc/fess/system.properties /backup/ + $ sudo cp /etc/fess/fess_config.properties /backup/ + $ sudo cp /etc/default/fess /backup/ + + .. note:: + + ``/etc/sysconfig/fess`` (RPM 버전)와 ``/etc/default/fess`` (DEB 버전)는 + ``FESS_PORT``, ``FESS_HEAP_SIZE``, ``SEARCH_ENGINE_HTTP_URL``, + ``FESS_DICTIONARY_PATH`` 등을 지정하는 환경 변수 파일입니다. + TAR.GZ/ZIP 버전에서 이에 해당하는 설정은 ``bin/fess.in.sh`` 에 있습니다. 3. **커스터마이징한 설정 파일** @@ -94,6 +128,14 @@ $ cp /path/to/fess/app/WEB-INF/classes/log4j2.xml /backup/ + .. note:: + + ``app/WEB-INF/classes/log4j2.xml`` 은 |Fess| 본체(Web) 프로세스의 로그 설정입니다. + 크롤러 등의 자식 프로세스는 별도의 파일 + (``app/WEB-INF/env/crawler/resources/log4j2.xml`` 등 ``crawler``, ``suggest``, + ``thumbnail``, ``chunk`` 총 4개)을 사용하므로, 이를 변경한 경우에는 + 함께 백업하십시오. + 인덱스 데이터 백업 ------------------------------ @@ -152,23 +194,42 @@ OpenSearch의 데이터는 Docker 볼륨에 저장됩니다. ``compose-opensearc $ docker volume ls -컨테이너를 중지한 후 볼륨을 백업합니다:: +컨테이너를 중지한 후 볼륨을 백업합니다. ``docker run`` 의 ``-v`` 에는 +접두사를 포함한 실제 볼륨 이름을 지정합니다:: $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop - $ docker run --rm -v search01_data:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-data-backup.tar.gz /data - $ docker run --rm -v search01_dictionary:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-dictionary-backup.tar.gz /data + $ PROJECT=$(basename "$(pwd)") + $ docker run --rm -v ${PROJECT}_search01_data:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-data-backup.tar.gz /data + $ docker run --rm -v ${PROJECT}_search01_dictionary:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-dictionary-backup.tar.gz /data $ docker compose -f compose.yaml -f compose-opensearch3.yaml start +.. warning:: + + ``-v`` 에 접두사 없이 ``search01_data`` 를 지정하면 Docker는 기존 볼륨을 참조하지 않고 + 같은 이름의 빈 볼륨을 새로 생성합니다. 명령은 오류 없이 실행되고 내용이 빈 아카이브가 + 생성되므로, 마치 백업이 정상적으로 취득된 것처럼 보일 수 있습니다. + +.. note:: + + |Fess| 본체(``fess01``) 컨테이너에는 전용 볼륨이 없으므로 백업 대상은 + 위 2개뿐입니다. 다만 관리 화면에서 변경한 전반 설정이나 관리 화면에서 설치한 + 플러그인은 컨테이너 내부에만 저장되며, 컨테이너를 재생성하면 유실됩니다. + 이러한 항목은 Compose 파일의 ``FESS_JAVA_OPTS`` 나 ``FESS_PLUGINS`` 로 지정하여 영속화하십시오. + 단계 2: 현재 버전 중지 ================================ Fess와 OpenSearch를 중지합니다. -TAR.GZ/ZIP 버전:: +TAR.GZ/ZIP 버전에는 중지용 스크립트가 포함되어 있지 않습니다. ``bin/fess`` 를 ``-p`` 옵션과 함께 +실행한 경우에는 PID 파일을 사용하여 중지합니다:: - $ kill + $ kill $(cat /path/to/fess/fess.pid) $ kill +``-p`` 를 지정하지 않고 실행한 경우에는 프로세스 ID를 확인하여 ``kill`` 합니다 +(``-d`` 만으로는 PID 파일이 생성되지 않습니다). + RPM/DEB 버전 (systemd):: $ sudo systemctl stop fess.service @@ -186,17 +247,43 @@ Docker 버전:: TAR.GZ/ZIP 버전 --------------- -1. 새 버전 다운로드 및 압축 해제:: +1. 새 버전을 다운로드하여 압축을 해제합니다:: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.8.0/fess-15.8.0.zip + $ unzip fess-15.8.0.zip - $ wget https://github.com/codelibs/fess/releases/download/fess-15.8.0/fess-15.8.0.tar.gz - $ tar -xzf fess-15.8.0.tar.gz + .. note:: + + |Fess| 의 아카이브 버전은 ZIP 형식으로만 배포됩니다(``fess-15.8.0.tar.gz`` 는 + 제공되지 않습니다). -2. 이전 버전 설정 복사:: +2. 이전 버전의 설정을 복사합니다:: $ cp /path/to/old-fess/app/WEB-INF/conf/system.properties /path/to/fess-15.8.0/app/WEB-INF/conf/ + $ cp /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.8.0/app/WEB-INF/classes/ $ cp /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.8.0/bin/ -3. 설정 차이를 확인하고 필요에 따라 조정합니다 +3. 커스터마이징한 경우에는 다음도 복사합니다:: + + # 로그 설정 + $ cp /path/to/old-fess/app/WEB-INF/classes/log4j2.xml /path/to/fess-15.8.0/app/WEB-INF/classes/ + # 설치된 플러그인 + $ cp -r /path/to/old-fess/app/WEB-INF/plugin/. /path/to/fess-15.8.0/app/WEB-INF/plugin/ + # 테마 + $ cp -r /path/to/old-fess/app/themes/. /path/to/fess-15.8.0/app/themes/ + + .. warning:: + + 관리 화면 「디자인」에서 편집한 JSP(``app/WEB-INF/view/``)는 그대로 복사하지 마십시오. + 새 버전의 JSP와 구조가 달라진 경우 화면이 올바르게 표시되지 않을 수 있습니다. + 새 버전의 JSP에 변경 내용을 다시 적용하십시오. + +4. 임베디드 OpenSearch(``SEARCH_ENGINE_HTTP_URL`` 을 설정하지 않고 ``bin/fess`` 를 실행하는 구성)를 + 사용하는 경우에는 인덱스 데이터도 복사합니다:: + + $ cp -r /path/to/old-fess/es/data/. /path/to/fess-15.8.0/es/data/ + +5. 설정 차이를 확인하고 필요에 따라 조정합니다 RPM/DEB 버전 ------------ @@ -211,8 +298,19 @@ RPM/DEB 버전 .. note:: - 설정 파일(``/etc/fess/*``)은 자동으로 유지됩니다. - 단, 새로운 설정 옵션이 추가된 경우 수동으로 조정이 필요합니다. + RPM 버전에서는 ``/etc/fess/*`` 의 설정 파일이 ``%config(noreplace)`` 로 등록되어 있으므로 + 업그레이드 시에도 유지됩니다(새 기본 파일은 ``.rpmnew`` 로 함께 배치됩니다). + 새로운 설정 옵션이 추가된 경우에는 수동으로 조정이 필요합니다. + +.. warning:: + + DEB 버전에서는 ``/etc/fess/*`` 가 conffile로 등록되어 있지 않습니다(conffile은 + ``/etc/default/fess``, ``/etc/init.d/fess``, ``/usr/lib/systemd/system/fess.service`` + 3개뿐입니다). 따라서 ``dpkg -i`` 를 실행하면 ``/etc/fess/fess_config.properties`` 등이 + 새 버전의 파일로 덮어써집니다. 단계 1에서 백업한 설정을 + 업그레이드 후에 다시 적용하십시오. + 또한 ``/etc/fess/system.properties`` 는 패키지에 포함되지 않는 실행 시 생성 파일이므로 + 덮어써지지 않습니다. Docker 버전 ----------- @@ -226,10 +324,13 @@ Docker 버전 $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull -단계 4: OpenSearch 업그레이드(필요한 경우) -================================================= +.. _upgrade-opensearch: + +단계 4: OpenSearch 업그레이드 +==================================== -OpenSearch도 업그레이드하는 경우 다음 절차를 따르십시오. +|Fess| 15.8은 OpenSearch 3.8.0에 대응합니다. 연결 대상 OpenSearch가 이보다 오래된 경우 +다음 절차에 따라 업그레이드하십시오. .. note:: @@ -237,24 +338,39 @@ OpenSearch도 업그레이드하는 경우 다음 절차를 따르십시오. Docker 버전에서는 단계 3에서 새 이미지를 가져오면 OpenSearch와 플러그인도 함께 업데이트되므로 이 단계는 불필요합니다. +.. important:: + + |Fess| 15.8은 청크 벡터 검색(시맨틱 검색) 사용 여부와 관계없이 검색 인덱스 설정에 + ``index.knn`` 을, 매핑에 ``content_chunk_vector`` (``knn_vector`` 타입)를 항상 + 포함합니다. 따라서 연결 대상 OpenSearch에는 **k-NN 플러그인이 필수** 입니다. + + - 표준 배포판 OpenSearch 및 Docker 버전의 이미지에는 동봉되어 있습니다. + - **minimal 배포판에는 포함되어 있지 않으므로 인덱스를 새로 생성하지 못해 |Fess| 가 + 시작되지 않습니다.** + - 인덱스 설정에는 ``knn.derived_source.enabled`` 도 항상 전송됩니다. 이를 인식하지 못하는 + 오래된 OpenSearch에서는 k-NN 플러그인 유무와 관계없이 인덱스 생성에 실패합니다. + + 자세한 내용은 :doc:`../config/search-semantic` 의 「전제 조건」을 참조하십시오. + .. warning:: OpenSearch의 메이저 버전 업그레이드는 신중하게 수행하십시오. 인덱스 호환성에 문제가 발생할 수 있습니다. + |Fess| 14.x는 OpenSearch 2.x 계열이므로, 14.x에서의 업그레이드는 반드시 이 경우에 해당합니다. 1. 새 버전의 OpenSearch 설치 2. 플러그인 재설치:: - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.7.0 - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.7.0 - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-minhash:3.7.0 - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-configsync:3.7.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.8.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.8.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-minhash:3.8.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-configsync:3.8.0 .. note:: 이러한 플러그인의 버전은 사용하는 OpenSearch의 버전과 일치시켜야 합니다. - Fess 15.8은 OpenSearch 3.7.0에 대응합니다. 버전이 일치하지 않으면 + |Fess| 15.8은 OpenSearch 3.8.0에 대응합니다. 버전이 일치하지 않으면 플러그인 설치에 실패합니다. 3. OpenSearch 시작:: @@ -267,7 +383,12 @@ OpenSearch도 업그레이드하는 경우 다음 절차를 따르십시오. TAR.GZ/ZIP 버전:: $ cd /path/to/fess-15.8.0 - $ ./bin/fess -d + $ ./bin/fess -d -p /path/to/fess-15.8.0/fess.pid + +.. note:: + + ``-p`` 를 지정하면 PID 파일이 생성되며, 다음 중지 시 + ``kill $(cat /path/to/fess-15.8.0/fess.pid)`` 로 중지할 수 있습니다. RPM/DEB 버전:: @@ -283,10 +404,25 @@ Docker 버전:: 1. **로그 확인** - 오류가 없는지 확인합니다:: + 오류가 없는지 확인합니다. + + TAR.GZ/ZIP 버전:: $ tail -f /path/to/fess/logs/fess.log + RPM/DEB 버전:: + + $ sudo tail -f /var/log/fess/fess.log + + Docker 버전:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01 + + .. note:: + + 같은 로그 디렉터리에 크롤 처리의 ``fess-crawler.log``, 인증 및 관리 작업의 + ``audit.log``, 검색 요청의 ``searchlog.log`` 도 출력됩니다. + 2. **웹 인터페이스 액세스** 브라우저에서 http://localhost:8080/ 에 액세스합니다. @@ -322,6 +458,39 @@ Docker 버전:: 3. 크롤이 완료될 때까지 대기 4. 검색 결과 확인 +.. warning:: + + 재인덱싱에서는 새로운 매핑으로 인덱스가 다시 생성되므로, k-NN 플러그인이 + 없는 OpenSearch에서는 실패합니다. 단계 4의 주의사항을 확인하십시오. + +15.8 전용 마이그레이션 작업 +=========================== + +15.7 이전 버전에서 15.8로 업그레이드하는 경우, 사용 중인 기능에 따라 다음 작업이 필요합니다. + +시맨틱 검색을 사용하고 있었던 경우 +---------------------------------- + +15.7 이전에 시맨틱 검색을 제공하던 ``fess-webapp-semantic-search`` 플러그인은 +15.8에서 코어로 통합되어 불필요해졌습니다(사용 중단). 플러그인 제거, ``-Dfess.semantic_search.*`` +및 ``-Drank.fusion.searchers=default,semantic`` 의 제거, 기존 인제스트 파이프라인 분리가 +필요합니다. 절차는 :ref:`semantic-search-migration` (:doc:`../config/search-semantic`)를 +참조하십시오. + +AI 검색 모드(RAG 채팅)를 사용하고 있었던 경우 +--------------------------------------------- + +15.8부터 AI 검색 모드(RAG 채팅) 기능은 ``fess-llm-ollama``, ``fess-llm-openai``, +``fess-llm-gemini`` 등의 플러그인으로 분리되었습니다. 사용 중인 프로바이더에 대응하는 +플러그인을 관리 화면 「시스템」→「플러그인」에서 설치하십시오. + +플러그인 버전 갱신 +------------------------ + +``app/WEB-INF/plugin/`` 에 설치된 플러그인은 |Fess| 버전에 대응하는 +것으로 교체해야 합니다. Docker 버전에서 ``FESS_PLUGINS`` 를 지정하는 경우에는 +``fess-ds-wikipedia:15.8.0`` 처럼 버전 부분을 갱신하십시오. + 롤백 절차 ============== @@ -362,10 +531,40 @@ RPM/DEB 버전의 경우:: $ sudo tar xzf /backup/opensearch-data-backup.tar.gz -C / $ sudo systemctl start opensearch +Docker 버전에서는 이전 버전의 Compose 파일로 되돌린 후 볼륨의 내용을 복원합니다:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + $ PROJECT=$(basename "$(pwd)") + $ docker run --rm -v ${PROJECT}_search01_data:/data -v $(pwd):/backup ubuntu \ + sh -c "rm -rf /data/* && tar xzf /backup/search01-data-backup.tar.gz -C /" + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + .. note:: - 관리 화면에서 다운로드한 설정 데이터(``*.bulk`` 파일)는 Fess 시작 후 - 「시스템 정보」→「백업」페이지의 업로드 기능으로 다시 임포트하여 복원할 수 있습니다. + 관리 화면에서 다운로드한 설정 데이터는 |Fess| 시작 후 「시스템 정보」→「백업」 + 페이지의 업로드 기능으로 다시 임포트하여 복원할 수 있습니다. 업로드할 수 있는 것은 + ``*.bulk``, ``system`` 으로 시작하는 ``*.properties``, ``gsa`` 로 시작하는 ``*.xml``, + ``fess`` 로 시작하는 ``*.json``, ``doc`` 으로 시작하는 ``*.json`` 뿐이며, 한 번의 조작에 파일 1개입니다. + 검색 로그 등의 ``*.ndjson`` 파일은 받아들여지지 않으며 오류가 됩니다. + +.. warning:: + + ``fess.json`` 과 ``doc.json`` 의 업로드는 |Fess| 에 동봉된 인덱스 정의 + 파일 자체를 덮어씁니다. 업그레이드 후에 이전 버전의 ``fess.json`` 이나 + ``doc.json`` 을 업로드하면 새 버전의 인덱스 설정·매핑이 유실됩니다. + 롤백 목적 이외에는 업로드하지 마십시오. + +.. note:: + + 업로드된 ``system.properties`` 는 메모리에만 로드되며 파일로는 + 기록되지 않습니다. 따라서 ``system.properties`` 의 내용은 |Fess| 를 재시작하면 유실됩니다. + 확실히 복원하려면 백업한 파일을 정해진 위치(TAR.GZ/ZIP 버전은 + ``app/WEB-INF/conf/``, RPM/DEB 버전은 ``/etc/fess/``)에 직접 배치한 후 시작하십시오. + +.. note:: + + 임포트는 비동기로 실행되며, 화면에는 시작되었다는 내용만 표시됩니다. + 실제로 성공했는지는 ``fess.log`` 를 확인하십시오. 단계 4: 서비스 시작 및 확인 ---------------------------- @@ -392,19 +591,35 @@ A: Fess의 업그레이드에는 서비스 중지가 필요합니다. 다운타 Q: OpenSearch도 업그레이드해야 합니까? ------------------------------------------------- -A: Fess 버전마다 대응하는 OpenSearch의 버전이 정해져 있습니다. -Fess 15.8은 OpenSearch 3.7.0에 대응합니다. -``opensearch-analysis-fess`` 등의 Fess용 OpenSearch 플러그인은 OpenSearch의 버전과 -완전히 일치해야 하므로 OpenSearch를 업그레이드하는 경우 -대응하는 버전(3.7.0)의 플러그인으로 업데이트하십시오. +A: |Fess| 버전마다 대응하는 OpenSearch 버전이 정해져 있습니다. +|Fess| 15.8은 OpenSearch 3.8.0에 대응합니다. +``opensearch-analysis-fess`` 등의 |Fess| 용 OpenSearch 플러그인은 OpenSearch 버전과 +완전히 일치해야 하므로, OpenSearch를 업그레이드하는 경우 +대응하는 버전(3.8.0)의 플러그인으로 업데이트하십시오. + +또한 |Fess| 15.8은 k-NN 플러그인을 필수로 하며, 인덱스 설정에 ``knn.derived_source.enabled`` +를 항상 전송합니다. 오래된 OpenSearch를 그대로 사용하면 새 인덱스 생성에 실패하므로 +사실상 OpenSearch의 업그레이드가 필요합니다. 자세한 내용은 단계 4를 참조하십시오. Q: 인덱스를 재작성해야 합니까? ------------------------------------------ -A: 마이너 버전 업그레이드의 경우 일반적으로 불필요하지만 메이저 버전 업그레이드의 경우 재작성을 권장합니다. -또한 15.7 이전 버전에서 15.8 이상으로 업그레이드하면서 청크 벡터 검색(시맨틱 검색)을 새로 -활성화하려는 경우에는, 기존 인덱스가 새 매핑을 반영하지 않으므로 재인덱싱이 필요합니다. -자세한 내용은 :doc:`../config/search-semantic` 을 참조하세요. +A: |Fess| 의 마이너 버전 업그레이드(15.x → 15.8)에서 청크 벡터 검색을 이용하지 않는 경우는 +일반적으로 불필요합니다. 기존 인덱스를 그대로 이용할 수 있으며, ``content_chunker.enabled`` 등은 +기본값이 비활성화이므로 동작은 변하지 않습니다. + +다음의 경우에는 재작성·재인덱싱이 필요합니다. + +- **새로 청크 벡터 검색(시맨틱 검색)을 활성화하는 경우**: 기존 인덱스에는 + 새 매핑이 반영되지 않으므로 재인덱싱이 필수입니다. 자세한 내용은 + :ref:`semantic-search-migration` (:doc:`../config/search-semantic`)를 참조하십시오. +- **14.x에서 업그레이드하는 경우**: OpenSearch가 2.x에서 3.x로 메이저 버전 업그레이드 + 되므로 인덱스 재작성을 권장합니다. + +.. warning:: + + 인덱스를 새로 생성하는 작업(재인덱싱 포함)은 k-NN 플러그인이 없는 + OpenSearch에서는 실패합니다. 단계 4의 주의사항을 확인하십시오. Q: 업그레이드 후 검색 결과가 표시되지 않습니다 ---------------------------------------------- diff --git a/zh-cn/15.8/install/upgrade.rst b/zh-cn/15.8/install/upgrade.rst index 3b5ceacd..0bb39947 100644 --- a/zh-cn/15.8/install/upgrade.rst +++ b/zh-cn/15.8/install/upgrade.rst @@ -21,6 +21,13 @@ - Fess 14.x → Fess 15.8 - Fess 15.x → Fess 15.8 +.. important:: + + |Fess| 14.x 对应 OpenSearch 2.x 系列，\ |Fess| 15.8 对应 OpenSearch 3.8.0。 + 由于 |Fess| 专用的 OpenSearch 插件必须与 OpenSearch 版本完全一致， + 因此从 14.x 升级时，也必须同时对 OpenSearch 进行主版本升级。 + 请参阅 :ref:`upgrade-opensearch`。 + .. note:: 如果从更旧的版本（13.x 及更早）升级，可能需要逐步升级。 @@ -35,7 +42,7 @@ 请确认升级目标版本与当前版本的兼容性。 - `发布说明 `__ -- `升级指南 `__ +- :doc:`prerequisites` - |Fess| 15.8 的系统要求（Java、OpenSearch 版本） 计划停机时间 ---------------- @@ -62,19 +69,31 @@ 登录管理页面，点击「系统信息」→「备份」。 备份页面按条目列出以下配置数据。 - 点击各链接下载（不是单个 ZIP 文件，而是按条目分别下载的独立文件）。 + 点击各行下载（不是单个 ZIP 文件，而是按条目分别下载的独立文件。 + 由于没有批量下载功能，需要将所需项目逐一下载）。 - - ``fess_basic_config.bulk`` - 基本设置（常规设置） - - ``fess_config.bulk`` - 爬取设置、调度器、标签、关键词匹配等配置信息 + - ``fess_basic_config.bulk`` - 配置索引（爬取设置、调度器、标签、 + 关键词匹配、角色、Web/文件认证等 19 个索引） + - ``fess_config.bulk`` - 除上述 19 个索引外，还包含爬取信息、失败 URL、作业日志、 + 缩略图队列等运行时数据，共 25 个索引 - ``fess_user.bulk`` - 用户、角色、群组 - - ``system.properties`` - 系统设置 - - ``fess.json`` / ``doc.json`` - 索引设置（映射） + - ``system.properties`` - 包含常规设置的系统设置 + - ``fess.json`` - 索引设置（分片数、\ ``index.knn`` 等） + - ``doc.json`` - 文档映射（字段定义） + + .. note:: + + ``fess_config.bulk`` 包含 ``fess_basic_config.bulk``。作为升级前的 + 配置备份，\ ``fess_basic_config.bulk``\ 、\ ``fess_user.bulk``\ 、 + ``system.properties`` 这 3 个文件就已足够。 .. note:: 搜索日志、点击日志等日志数据（``search_log.ndjson``、``click_log.ndjson``、 ``favorite_log.ndjson``、``user_info.ndjson``）也可从同一页面下载。 - 如果仅备份配置，则不需要下载这些文件。 + 如果仅备份配置，则不需要下载这些文件。另外，这些 ``*.ndjson`` 文件无法 + 通过备份页面的上传功能重新导入恢复 + （请参阅「回滚步骤」）。 2. **备份配置文件** @@ -82,11 +101,26 @@ $ cp /path/to/fess/app/WEB-INF/conf/system.properties /backup/ $ cp /path/to/fess/app/WEB-INF/classes/fess_config.properties /backup/ + $ cp /path/to/fess/bin/fess.in.sh /backup/ - RPM/DEB 版:: + RPM 版:: $ sudo cp /etc/fess/system.properties /backup/ $ sudo cp /etc/fess/fess_config.properties /backup/ + $ sudo cp /etc/sysconfig/fess /backup/ + + DEB 版:: + + $ sudo cp /etc/fess/system.properties /backup/ + $ sudo cp /etc/fess/fess_config.properties /backup/ + $ sudo cp /etc/default/fess /backup/ + + .. note:: + + ``/etc/sysconfig/fess``\ （RPM 版）和 ``/etc/default/fess``\ （DEB 版）是 + 用于指定 ``FESS_PORT``\ 、\ ``FESS_HEAP_SIZE``\ 、\ ``SEARCH_ENGINE_HTTP_URL``\ 、 + ``FESS_DICTIONARY_PATH`` 等内容的环境变量文件。 + TAR.GZ/ZIP 版中与之对应的设置位于 ``bin/fess.in.sh``。 3. **定制的配置文件** @@ -94,6 +128,14 @@ $ cp /path/to/fess/app/WEB-INF/classes/log4j2.xml /backup/ + .. note:: + + ``app/WEB-INF/classes/log4j2.xml`` 是 |Fess| 本体（Web）进程的日志配置。 + 爬虫等子进程使用各自独立的文件 + （例如 ``app/WEB-INF/env/crawler/resources/log4j2.xml`` 等，\ ``crawler``\ 、\ ``suggest``\ 、 + ``thumbnail``\ 、\ ``chunk`` 共 4 个），如果修改过这些文件， + 请一并备份。 + 备份索引数据 ------------------------------ @@ -152,23 +194,42 @@ OpenSearch 的数据保存在 Docker 卷中。\ ``compose-opensearch3.yaml`` 中 $ docker volume ls -停止容器后，备份卷:: +停止容器后，备份卷。\ ``docker run`` 的 ``-v`` 需要指定 +包含前缀的实际卷名:: $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop - $ docker run --rm -v search01_data:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-data-backup.tar.gz /data - $ docker run --rm -v search01_dictionary:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-dictionary-backup.tar.gz /data + $ PROJECT=$(basename "$(pwd)") + $ docker run --rm -v ${PROJECT}_search01_data:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-data-backup.tar.gz /data + $ docker run --rm -v ${PROJECT}_search01_dictionary:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-dictionary-backup.tar.gz /data $ docker compose -f compose.yaml -f compose-opensearch3.yaml start +.. warning:: + + 如果在 ``-v`` 中指定不带前缀的 ``search01_data``，Docker 不会引用现有卷， + 而是会新建一个同名的空卷。命令不会报错，且会生成内容为空的归档文件， + 看起来就像是已经完成了备份。 + +.. note:: + + |Fess| 本体（``fess01``）的容器没有专用卷，因此备份对象仅为 + 上述 2 个卷。但是，从管理页面更改的常规设置以及从管理页面安装的 + 插件仅保存在容器内部，重新创建容器后会丢失。 + 请通过 Compose 文件的 ``FESS_JAVA_OPTS`` 或 ``FESS_PLUGINS`` 指定这些内容以实现持久化。 + 步骤 2: 停止当前版本 ================================ 停止 Fess 和 OpenSearch。 -TAR.GZ/ZIP 版:: +TAR.GZ/ZIP 版没有附带用于停止的脚本。\ ``bin/fess`` 如果是使用 ``-p`` 选项 +启动的，可以使用 PID 文件停止:: - $ kill + $ kill $(cat /path/to/fess/fess.pid) $ kill +如果启动时未指定 ``-p``，请确认进程 ID 后使用 ``kill`` 停止 +（仅使用 ``-d`` 不会创建 PID 文件）。 + RPM/DEB 版 (systemd):: $ sudo systemctl stop fess.service @@ -184,22 +245,48 @@ Docker 版:: 根据安装方法，步骤有所不同。 TAR.GZ/ZIP 版 ------------- +------------- 1. 下载并解压新版本:: - $ wget https://github.com/codelibs/fess/releases/download/fess-15.8.0/fess-15.8.0.tar.gz - $ tar -xzf fess-15.8.0.tar.gz + $ wget https://github.com/codelibs/fess/releases/download/fess-15.8.0/fess-15.8.0.zip + $ unzip fess-15.8.0.zip + + .. note:: + + |Fess| 的归档版仅以 ZIP 格式发布（不提供 + ``fess-15.8.0.tar.gz``）。 2. 复制旧版本的配置:: $ cp /path/to/old-fess/app/WEB-INF/conf/system.properties /path/to/fess-15.8.0/app/WEB-INF/conf/ + $ cp /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.8.0/app/WEB-INF/classes/ $ cp /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.8.0/bin/ -3. 确认配置差异，根据需要进行调整 +3. 如有定制内容，请同时复制以下文件:: + + # 日志配置 + $ cp /path/to/old-fess/app/WEB-INF/classes/log4j2.xml /path/to/fess-15.8.0/app/WEB-INF/classes/ + # 已安装的插件 + $ cp -r /path/to/old-fess/app/WEB-INF/plugin/. /path/to/fess-15.8.0/app/WEB-INF/plugin/ + # 主题 + $ cp -r /path/to/old-fess/app/themes/. /path/to/fess-15.8.0/app/themes/ + + .. warning:: + + 在管理页面「页面设计」中编辑过的 JSP（``app/WEB-INF/view/``），请不要直接复制过去。 + 如果新版本的 JSP 结构发生了变化，画面可能无法正常显示。 + 请将修改内容重新应用到新版本的 JSP 上。 + +4. 如果使用内置 OpenSearch（未设置 ``SEARCH_ENGINE_HTTP_URL`` 而直接启动 ``bin/fess`` 的 + 配置），请同时复制索引数据:: + + $ cp -r /path/to/old-fess/es/data/. /path/to/fess-15.8.0/es/data/ + +5. 确认配置差异，根据需要进行调整 RPM/DEB 版 ---------- +---------- 安装新版本的包:: @@ -211,11 +298,21 @@ RPM/DEB 版 .. note:: - 配置文件（``/etc/fess/*``）会自动保留。 - 但是，如果添加了新的配置选项，需要手动调整。 + RPM 版中，``/etc/fess/*`` 的配置文件被注册为 ``%config(noreplace)``， + 因此在升级时会被保留（新的默认文件会以 ``.rpmnew`` 的形式并存）。 + 如果添加了新的配置选项，需要手动调整。 + +.. warning:: + + DEB 版中，``/etc/fess/*`` 并未注册为 conffile（conffile 仅有 + ``/etc/default/fess``\ 、\ ``/etc/init.d/fess``\ 、\ ``/usr/lib/systemd/system/fess.service`` + 这 3 个）。因此执行 ``dpkg -i`` 时，``/etc/fess/fess_config.properties`` 等文件会被 + 新版本的文件覆盖。请在升级后，重新应用步骤 1 中备份的配置。 + 另外，``/etc/fess/system.properties`` 是不包含在软件包中的运行时生成文件， + 因此不会被覆盖。 Docker 版 --------- +--------- 1. 获取新版本的 Compose 文件:: @@ -226,10 +323,13 @@ Docker 版 $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull -步骤 4: 升级 OpenSearch（如需要） -================================================= +.. _upgrade-opensearch: -如果要升级 OpenSearch，请按照以下步骤操作。 +步骤 4: 升级 OpenSearch +==================================== + +|Fess| 15.8 对应 OpenSearch 3.8.0。如果所连接的 OpenSearch 版本比这更旧， +请按照以下步骤升级。 .. note:: @@ -237,24 +337,38 @@ Docker 版 对于 Docker 版，在步骤 3 中获取新镜像时，OpenSearch 和插件也会一并更新， 因此无需执行本步骤。 +.. important:: + + 无论是否使用分块向量搜索（语义搜索），\ |Fess| 15.8 都会在搜索索引的设置中始终 + 包含 ``index.knn``，并在映射中始终包含 ``content_chunk_vector``\ （\ ``knn_vector`` + 类型）。因此，所连接的 OpenSearch **必须安装 k-NN 插件**。 + + - 标准发行版的 OpenSearch 以及 Docker 版镜像中已包含该插件。 + - **minimal 发行版不包含该插件，会导致索引新建失败，\ |Fess| 无法启动。** + - 索引设置中还会始终发送 ``knn.derived_source.enabled``。无法识别该配置的 + 旧版本 OpenSearch，无论是否安装 k-NN 插件，索引创建都会失败。 + + 详情请参阅 :doc:`../config/search-semantic` 中的「前提条件」。 + .. warning:: OpenSearch 的主版本升级需要谨慎进行。 可能会出现索引兼容性问题。 + |Fess| 14.x 对应 OpenSearch 2.x 系列，因此从 14.x 升级时必然属于这种情况。 1. 安装新版本的 OpenSearch 2. 重新安装插件:: - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.7.0 - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.7.0 - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-minhash:3.7.0 - $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-configsync:3.7.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.8.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.8.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-minhash:3.8.0 + $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-configsync:3.8.0 .. note:: 这些插件的版本必须与所使用的 OpenSearch 版本一致。 - Fess 15.8 对应 OpenSearch 3.7.0。如果版本不一致， + |Fess| 15.8 对应 OpenSearch 3.8.0。如果版本不一致， 插件安装将会失败。 3. 启动 OpenSearch:: @@ -267,7 +381,12 @@ Docker 版 TAR.GZ/ZIP 版:: $ cd /path/to/fess-15.8.0 - $ ./bin/fess -d + $ ./bin/fess -d -p /path/to/fess-15.8.0/fess.pid + +.. note:: + + 指定 ``-p`` 后会创建 PID 文件，下次停止时可以使用 + ``kill $(cat /path/to/fess-15.8.0/fess.pid)`` 来停止。 RPM/DEB 版:: @@ -283,10 +402,25 @@ Docker 版:: 1. **确认日志** - 确认没有错误:: + 确认没有错误。 + + TAR.GZ/ZIP 版:: $ tail -f /path/to/fess/logs/fess.log + RPM/DEB 版:: + + $ sudo tail -f /var/log/fess/fess.log + + Docker 版:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01 + + .. note:: + + 同一日志目录下，还会输出爬取处理的 ``fess-crawler.log``\ 、认证与管理操作的 + ``audit.log``\ 、以及检索请求的 ``searchlog.log``。 + 2. **访问 Web 界面** 在浏览器中访问 http://localhost:8080/。 @@ -320,6 +454,39 @@ Docker 版:: 3. 等待爬取完成 4. 确认搜索结果 +.. warning:: + + 由于重新索引会以新的映射重建索引，在没有 k-NN 插件的 OpenSearch 中会失败。 + 请确认步骤 4 中的注意事项。 + +15.8 特有的迁移工作 +=================== + +从 15.7 及更早版本升级到 15.8 时，需要根据所使用的功能执行以下工作。 + +若此前使用过语义搜索 +---------------------------------- + +在 |Fess| 15.7 及更早版本中提供语义搜索功能的 ``fess-webapp-semantic-search`` 插件， +已在 15.8 中并入核心，现已不再需要（已弃用）。需要移除该插件、删除 +``-Dfess.semantic_search.*`` 及 ``-Drank.fusion.searchers=default,semantic``\ ， +并解除旧的 ingest pipeline。详细步骤请参阅 +:ref:`semantic-search-migration`\ （:doc:`../config/search-semantic`）。 + +若此前使用过 AI 搜索模式（RAG Chat） +--------------------------------------------- + +自 15.8 起，AI 搜索模式（RAG Chat）功能已拆分为 ``fess-llm-ollama``\ 、\ ``fess-llm-openai``\ 、 +``fess-llm-gemini`` 等插件。请在管理页面「系统」→「插件」中安装与所使用的 +提供商对应的插件。 + +插件版本更新 +------------------------ + +安装在 ``app/WEB-INF/plugin/`` 中的插件，需要替换为与 |Fess| 版本对应的版本。 +如果在 Docker 版中指定了 ``FESS_PLUGINS``，请按照 ``fess-ds-wikipedia:15.8.0`` +的形式更新版本号部分。 + 回滚步骤 ============== @@ -360,10 +527,39 @@ RPM/DEB 版的情况:: $ sudo tar xzf /backup/opensearch-data-backup.tar.gz -C / $ sudo systemctl start opensearch +Docker 版中，请先切换回旧版本的 Compose 文件，再恢复卷中的内容:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + $ PROJECT=$(basename "$(pwd)") + $ docker run --rm -v ${PROJECT}_search01_data:/data -v $(pwd):/backup ubuntu \ + sh -c "rm -rf /data/* && tar xzf /backup/search01-data-backup.tar.gz -C /" + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + .. note:: - 从管理页面下载的配置数据（``*.bulk`` 文件），可在 Fess 启动后， - 通过「系统信息」→「备份」页面的上传功能重新导入并恢复。 + 从管理页面下载的配置数据，可在 |Fess| 启动后，通过「系统信息」→「备份」 + 页面的上传功能重新导入并恢复。可以上传的文件仅限于 + ``*.bulk``\ 、以 ``system``\ 开头的 ``*.properties``\ 、以 ``gsa``\ 开头的 ``*.xml``\ 、 + 以 ``fess``\ 开头的 ``*.json``\ 、以 ``doc``\ 开头的 ``*.json``\ ，且每次操作只能上传 1 个文件。 + 搜索日志等 ``*.ndjson`` 文件不被接受，会导致错误。 + +.. warning:: + + 上传 ``fess.json`` 和 ``doc.json`` 会覆盖 |Fess| 自带的索引定义文件本身。 + 升级后如果上传旧版本的 ``fess.json`` 或 ``doc.json``，会导致新版本的索引设置和映射丢失。 + 请勿在回滚以外的目的下上传这些文件。 + +.. note:: + + 上传的 ``system.properties`` 仅会加载到内存中，不会写入文件。 + 因此 ``system.properties`` 的内容会在 |Fess| 重启后丢失。 + 如需确保可靠恢复，请将备份的文件直接放置到指定位置（TAR.GZ/ZIP 版为 + ``app/WEB-INF/conf/``\ ，RPM/DEB 版为 ``/etc/fess/``\ ）后再启动。 + +.. note:: + + 导入操作以异步方式执行，画面上仅会显示已开始的提示。 + 请通过 ``fess.log`` 确认是否真正成功。 步骤 4: 启动和确认服务 ---------------------------- @@ -390,18 +586,34 @@ A: Fess 的升级需要停止服务。要最小化停机时间，请考虑以下 Q: 需要升级 OpenSearch 吗？ ------------------------------------------------- -A: 每个 Fess 版本对应特定的 OpenSearch 版本。 -Fess 15.8 对应 OpenSearch 3.7.0。 -由于 ``opensearch-analysis-fess`` 等 Fess 专用 OpenSearch 插件必须与 OpenSearch 版本完全一致， -因此在升级 OpenSearch 时，请同时将插件更新为对应版本（3.7.0）。 +A: 每个 |Fess| 版本对应特定的 OpenSearch 版本。 +|Fess| 15.8 对应 OpenSearch 3.8.0。 +由于 ``opensearch-analysis-fess`` 等 |Fess| 专用 OpenSearch 插件必须与 OpenSearch 版本完全一致， +因此在升级 OpenSearch 时，请同时将插件更新为对应版本（3.8.0）。 + +另外，|Fess| 15.8 强制要求安装 k-NN 插件，并会在索引设置中始终发送 +``knn.derived_source.enabled``。如果 OpenSearch 版本过旧，会导致新索引创建失败， +因此实质上必须升级 OpenSearch。详情请参阅步骤 4。 Q: 需要重建索引吗？ ------------------------------------------ -A: 小版本升级通常不需要，但主版本升级建议重建。 -另外，如果您正在从 15.7 或更早版本升级到 15.8 或更高版本，并希望新启用分块向量搜索（语义 -搜索），则需要重新索引，因为现有索引不会自动获取新的映射。详情请参阅 -:doc:`../config/search-semantic`。 +A: 对于 |Fess| 的小版本升级（15.x → 15.8），如果不使用分块向量搜索， +通常不需要重建索引。现有索引可以直接使用，\ ``content_chunker.enabled`` 等选项默认为 +禁用，因此行为不会改变。 + +以下情况需要重建索引并重新索引。 + +- **新启用分块向量搜索（语义搜索）时**: 由于现有索引不会反映新的映射， + 必须进行重新索引。详情请参阅 + :ref:`semantic-search-migration`\ （:doc:`../config/search-semantic`）。 +- **从 14.x 升级时**: 由于 OpenSearch 会从 2.x 主版本升级到 3.x， + 建议重建索引。 + +.. warning:: + + 新建索引的操作（包括重新索引）在没有 k-NN 插件的 OpenSearch 中会失败。 + 请确认步骤 4 中的注意事项。 Q: 升级后搜索结果不显示 ------------------------------------------