diff --git a/de/15.10/admin/accesstoken-guide.rst b/de/15.10/admin/accesstoken-guide.rst new file mode 100644 index 000000000..fbc8acee0 --- /dev/null +++ b/de/15.10/admin/accesstoken-guide.rst @@ -0,0 +1,80 @@ +============ +Zugriffstoken +============ + +Übersicht +========= + +Die Konfigurationsseite für Zugriffstoken verwaltet Zugriffstoken. + +Verwaltung +========== + +Anzeige +------- + +Um die Konfigurationsübersichtsseite für Zugriffstoken zu öffnen, klicken Sie im linken Menü auf [System > Zugriffstoken]. + +|image0| + +Klicken Sie auf den Konfigurationsnamen, um ihn zu bearbeiten. + +Konfiguration erstellen +----------------------- + +Um die Konfigurationsseite für Zugriffstoken zu öffnen, klicken Sie auf die Schaltfläche „Neu erstellen". + +|image1| + +Konfigurationsparameter +----------------------- + +Name +:::: + +Geben Sie einen Namen an, um dieses Zugriffstoken zu beschreiben. + +Berechtigung +:::::::::::: + +Legen Sie die Berechtigung für das Zugriffstoken fest. +Geben Sie diese im Format „{user\ |group|\ role}name" an. +Um beispielsweise Suchergebnisse für Benutzer anzuzeigen, die zur Gruppe „developer" gehören, legen Sie die Berechtigung auf „{group}developer" fest. + +.. warning:: + + Ein Zugriffstoken mit der Berechtigung ``{role}admin-api`` (gespeichert als ``Radmin-api``) kann jeden Endpunkt der Admin API nutzen; siehe :doc:`../api/admin/api-admin-overview`. Ein Benutzer mit der Rolle ``admin-accesstoken`` kann ein solches Zugriffstoken ausstellen, und ein Benutzer mit ``admin-accesstoken-view`` kann die Werte der Zugriffstoken anzeigen. Behandeln Sie daher beide Rollen wie die Administratorrolle und gewähren Sie sie nur vertrauenswürdigen Betreibern. + +Parametername +::::::::::::: + +Geben Sie den Namen des Anforderungsparameters an, wenn Sie die Berechtigung als Suchabfrage angeben. + +.. warning:: + + Die Parametername-Funktion ist ausschließlich für die Verwendung in vertrauenswürdigen internen Umgebungen konzipiert. + Wenn diese Funktion aktiviert ist, können zusätzliche Berechtigungen über URL-Parameter angegeben werden. + In extern zugänglichen Umgebungen oder bei Bereitstellung als öffentliche API können jedoch + böswillige Benutzer URL-Parameter manipulieren, um sich Berechtigungen zu verschaffen, die sie nicht haben sollten. + + Bitte beachten Sie Folgendes: + + * Verwenden Sie diese Funktion nur, wenn Fess in eine andere Anwendung oder einen Dienst eingebettet ist, der eingehende Anfragen vollständig kontrolliert. + * Konfigurieren Sie keinen Parameternamen, wenn Fess für nicht vertrauenswürdige Netzwerke zugänglich ist. + * Stellen Sie sicher, dass URL-Parameter bei Verwendung von Zugriffstoken nicht von externen Benutzern manipuliert werden können. + +Läuft ab +:::::::: + +Geben Sie das Ablaufdatum des Zugriffstokens an. + +Konfiguration löschen +--------------------- + +Klicken Sie auf den Konfigurationsnamen auf der Übersichtsseite und dann auf die Schaltfläche „Löschen". Es wird ein Bestätigungsbildschirm angezeigt. +Klicken Sie auf die Schaltfläche „Löschen", um die Konfiguration zu löschen. + + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/accesstoken-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/accesstoken-2.png diff --git a/de/15.10/admin/backup-guide.rst b/de/15.10/admin/backup-guide.rst new file mode 100644 index 000000000..9ae5cb701 --- /dev/null +++ b/de/15.10/admin/backup-guide.rst @@ -0,0 +1,115 @@ +========= +Sicherung +========= + +Übersicht +========= + +Auf der Sicherungsseite können Sie Konfigurationsinformationen von |Fess| herunterladen und hochladen. + +Download +-------- + +|Fess| speichert Konfigurationsinformationen als Index. +Klicken Sie zum Herunterladen auf den Indexnamen. + +|image0| + +.. note:: + + Wörterbuchdateien (Synonyme, Stoppwörter usw.) sind nicht Teil der Sicherung. + Sie liegen im Wörterbuchverzeichnis der Suchmaschine (``FESS_DICTIONARY_PATH``); + kopieren Sie sie bei Bedarf separat. + +fess_config.bulk +:::::::::::::::: + +fess_config.bulk enthält die Konfigurationsinformationen von |Fess|. + +fess_basic_config.bulk +:::::::::::::::::::::: + +fess_basic_config.bulk enthält die Konfigurationsinformationen von |Fess| ohne Crawl-Informationen, Fehler-URLs, Job-Protokolle, Thumbnail-Warteschlange, Benutzer-Tags und Ähnliches. + +fess_user.bulk +:::::::::::::: + +fess_user.bulk enthält Informationen zu Benutzern, Rollen und Gruppen. + +system.properties +::::::::::::::::: + +system.properties enthält allgemeine Konfigurationsinformationen. + +fess.json +::::::::: + +fess.json enthält die Konfigurationsinformationen des Fess-Index. + +doc.json +:::::::: + +doc.json enthält die Mapping-Informationen des Fess-Index. + +chat_log.ndjson +::::::::::::::: + +chat_log.ndjson enthält die Nutzungsprotokolle des KI-Chats. + +click_log.ndjson +:::::::::::::::: + +click_log.ndjson enthält Klick-Protokollinformationen. + +favorite_log.ndjson +::::::::::::::::::: + +favorite_log.ndjson enthält Favoriten-Protokollinformationen. + +search_log.ndjson +::::::::::::::::: + +search_log.ndjson enthält Such-Protokollinformationen. + +user_info.ndjson +:::::::::::::::: + +user_info.ndjson enthält Informationen zu Suchbenutzern. + +Upload +------ + +Sie können Konfigurationsinformationen hochladen und importieren. +Folgende Dateien können wiederhergestellt werden: + +- ``*.bulk`` +- ``system.properties`` +- ``fess.json`` und ``doc.json``: Sie ersetzen die Indexdefinitionsdateien, die |Fess| verwendet. Einstellungen und Mapping eines bestehenden Index werden dadurch nicht sofort geändert. +- ``gsa*.xml``: eine Konfigurationsdatei der Google Search Appliance. Sie wird als Web-Crawl-Konfiguration, Dateisystem-Crawl-Konfiguration und als Labels importiert. + +``*.ndjson``-Dateien (Suchprotokolle und andere Protokolle) können nicht hochgeladen und wiederhergestellt werden. + +Ein Dokument in einer \*.bulk-Datei, das ein ``updatedTime`` hat, wird nur geschrieben, wenn das +gespeicherte Dokument nicht existiert, kein ``updatedTime`` hat oder älter ist. Ein Dokument, das +nicht neuer ist, wird übersprungen und in ``fess.log`` auf INFO-Ebene protokolliert. So macht eine +Wiederherstellung Änderungen nach der Sicherung nicht rückgängig, und die mit der installierten +Version gelieferten geplanten Jobs (``updatedTime`` 0) bleiben unverändert. Dokumente ohne +``updatedTime`` werden immer geschrieben. + +.. note:: + + Das Überspringen wird auf INFO-Ebene protokolliert und erscheint daher mit der Standard-Protokollebene (``warn``) nicht in ``fess.log``. Um diese Einträge zu sehen, setzen Sie die Protokollebene vor der Wiederherstellung auf ``info``. Sie können sie in der Verwaltungsoberfläche unter [System > Allgemein] bei „Protokollebene" ändern (nach einem Neustart von |Fess| gilt wieder der konfigurierte Wert) oder unter Linux mit ``FESS_LOG_LEVEL=info``. Details finden Sie unter :doc:`../config/admin-logging`. + +.. note:: + + |Fess| 15.10 speichert das ``password`` der Web- und Datei-Authentifizierung mit dem Anwendungsschlüssel + (``app.cipher.key`` in ``fess_config.properties``) verschlüsselt, sodass ``fess_basic_config.bulk`` und + ``fess_config.bulk`` die verschlüsselten Werte enthalten. Übernehmen Sie beim Wiederherstellen einer Sicherung auf + einer anderen Installation denselben ``app.cipher.key``. Mit einem anderen Schlüssel schlagen Crawls, die diese + Zugangsdaten verwenden, mit einem Fehler fehl. Eine Sicherung, die vor 15.10 erstellt wurde, enthält sie im + Klartext und funktioniert weiterhin. + + Andere Werte in einer ``*.bulk``-Datei sind nicht verschlüsselt. Bewahren Sie diese Dateien daher als sensible + Dateien auf. + + .. |image0| image:: ../../../resources/images/en/15.10/admin/backup-1.png diff --git a/de/15.10/admin/badword-guide.rst b/de/15.10/admin/badword-guide.rst new file mode 100644 index 000000000..04a996b6a --- /dev/null +++ b/de/15.10/admin/badword-guide.rst @@ -0,0 +1,85 @@ +================== +Ausschlusswörter +================== + +Übersicht +========= + +Hier wird die Konfiguration von Ausschlusswörtern für Vorschläge erläutert. +Vorschläge werden entsprechend den Suchbegriffen angezeigt, aber Sie können konfigurieren, dass bestimmte Wörter nicht in den Vorschlägen erscheinen. + + +Verwaltung +========== + +Anzeige +------- + +Um die Konfigurationsübersichtsseite für Ausschlusswörter für Vorschläge zu öffnen, klicken Sie im linken Menü auf [Vorschlagen > Schlechtes Wort]. + +|image0| + +Klicken Sie auf den Konfigurationsnamen, um ihn zu bearbeiten. + +Konfiguration erstellen +----------------------- + +Um die Erstellungsseite für Ausschlusswörter für Vorschläge zu öffnen, klicken Sie auf die Schaltfläche „Neu erstellen". + +|image1| + +Konfigurationsparameter +----------------------- + +Schlechtes Wort +::::::::::::::: + +Registrieren Sie unerwünschte Wörter. +Wörter, die hier registriert sind, werden nicht in den Vorschlägen angezeigt. + +Konfiguration löschen +--------------------- + +Klicken Sie auf den Konfigurationsnamen auf der Übersichtsseite und dann auf die Schaltfläche „Löschen". Es wird ein Bestätigungsbildschirm angezeigt. +Klicken Sie auf die Schaltfläche „Löschen", um die Konfiguration zu löschen. + +Download +======== + +Laden Sie registrierte Wörter im CSV-Format herunter. + +|image2| + +CSV-Inhalt +---------- + +Zeile 1 ist die Kopfzeile. +Ab Zeile 2 werden die Ausschlusswörter aufgeführt. + +:: + +"BadWord" +"検索エンジン" + +Upload +====== + +Registrieren Sie Wörter im CSV-Format. + +|image3| + +CSV-Inhalt +---------- + +Zeile 1 ist die Kopfzeile. +Ab Zeile 2 beschreiben Sie die Ausschlusswörter. + +:: + +"BadWord" +"検索エンジン" + +.. |image0| image:: ../../../resources/images/en/15.10/admin/badword-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/badword-2.png +.. |image2| image:: ../../../resources/images/en/15.10/admin/badword-3.png +.. |image3| image:: ../../../resources/images/en/15.10/admin/badword-4.png diff --git a/de/15.10/admin/boostdoc-guide.rst b/de/15.10/admin/boostdoc-guide.rst new file mode 100644 index 000000000..268a4e214 --- /dev/null +++ b/de/15.10/admin/boostdoc-guide.rst @@ -0,0 +1,83 @@ +================== +Dokument-Boosting +================== + +Übersicht +========= + +Hier wird die Konfiguration für Dokument-Boosting erläutert. +Durch die Konfiguration von Dokument-Boosting können Sie Dokumente unabhängig vom Suchbegriff in den Suchergebnissen höher positionieren. + +Verwaltung +========== + +Anzeige +------- + +Um die Konfigurationsübersichtsseite für Dokument-Boosting zu öffnen, klicken Sie im linken Menü auf [Crawler > Dokument-Boost]. + +|image0| + +Klicken Sie auf den Konfigurationsnamen, um ihn zu bearbeiten. + +Konfiguration erstellen +----------------------- + +Um die Konfigurationsseite für Dokument-Boosting zu öffnen, klicken Sie auf die Schaltfläche „Neu erstellen". + +|image1| + +Konfigurationsparameter +----------------------- + +Bedingung +::::::::: + +Geben Sie die Bedingung für Dokumente an, die höher positioniert werden sollen. +Wenn Sie beispielsweise URLs mit https://www.n2sm.net/ höher anzeigen möchten, schreiben Sie url.matches("https://www.n2sm.net/.\*"). +Bedingungen werden in der Syntax der unter „Skripttyp" angegebenen Skript-Engine geschrieben. + +Boost-Ausdruck +:::::::::::::: + +Geben Sie den Gewichtungswert für das Dokument an. +Ausdrücke werden in der Syntax der unter „Skripttyp" angegebenen Skript-Engine geschrieben. + +Skripttyp +::::::::: + +Geben Sie die Skript-Engine an, mit der die Bedingung und der Boost-Ausdruck ausgewertet werden. +Neue Konfigurationen sind mit ``javascript`` vorausgefüllt. Für ``groovy`` ist das Plugin +``fess-script-groovy`` erforderlich. Bleibt das Feld leer, werden die Ausdrücke als Groovy ausgewertet. + +.. warning:: + + Schreiben Sie unter JavaScript die Bedingung und den Boost-Ausdruck als reine Ausdrücke ohne + abschließendes Semikolon. Text, der sich nur als Block von Anweisungen parsen lässt, wird zu + ``null`` ausgewertet, sofern er kein explizites ``return`` enthält. Siehe + :ref:`javascript-statement-null` (in :doc:`../config/scripting-javascript`). + +Sortierreihenfolge +:::::::::::::::::: + +Legen Sie die Sortierreihenfolge für das Dokument-Boosting fest. + +Zeitpunkt der Regelanwendung +---------------------------- + +Die Regeln für das Dokument-Boosting werden ausgewertet, wenn ein Web-Crawl oder ein Datei-Crawl ein Dokument im Index registriert. Auf Datenspeicher-Crawls werden sie nicht angewendet. +Das Hinzufügen, Ändern oder Löschen einer Regel ändert den Boost von Dokumenten, die sich bereits im Index befinden, nicht. + +Ist „Letzte Änderung prüfen" unter [System > Allgemein] aktiviert (Standard), wird ein Dokument, dessen Inhalt sich nicht geändert hat, beim erneuten Crawlen nicht erneut im Index registriert. Sein Boost wird daher nicht erneut ausgewertet. +Um eine neue oder geänderte Regel auf vorhandene Dokumente anzuwenden, löschen Sie diese Dokumente aus dem Index (siehe :doc:`searchlist-guide`) und crawlen Sie erneut. +Ein Dokument, das erneut registriert wird, zum Beispiel weil sich sein Inhalt geändert hat, wird zu diesem Zeitpunkt ausgewertet. +Ist „Letzte Änderung prüfen" deaktiviert, wird bei jedem Crawl jedes Dokument erneut registriert, sodass die Regeln jedes Mal ausgewertet werden. + +Konfiguration löschen +--------------------- + +Klicken Sie auf den Konfigurationsnamen auf der Übersichtsseite und dann auf die Schaltfläche „Löschen". Es wird ein Bestätigungsbildschirm angezeigt. Klicken Sie auf die Schaltfläche „Löschen", um die Konfiguration zu löschen. + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/boostdoc-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/boostdoc-2.png diff --git a/de/15.10/admin/crawlinginfo-guide.rst b/de/15.10/admin/crawlinginfo-guide.rst new file mode 100644 index 000000000..9169cdef3 --- /dev/null +++ b/de/15.10/admin/crawlinginfo-guide.rst @@ -0,0 +1,93 @@ +================== +Crawl-Informationen +================== + +Übersicht +========= + +Die Crawl-Ausführungsergebnisse werden aufgezeichnet, und Crawl-Informationen können auf diesem Verwaltungsbildschirm überprüft werden. + +Verwaltung +========== + +Übersicht +========= + +Jedes Mal, wenn ein Crawl ausgeführt wird, wird er als Crawl-Information aufgezeichnet. +In der Übersicht können Sie den Sitzungsnamen und die Ausführungszeit des durchgeführten Crawls überprüfen. +Um Details der Crawl-Informationen anzuzeigen, klicken Sie auf die entsprechende Crawl-Information. + +|image0| + +Details +======= + +Durch Klicken auf die Sitzungs-ID der Crawl-Informationen in der Übersicht werden die Details der entsprechenden Crawl-Informationen angezeigt. + +|image1| + +Parameterliste +-------------- + +Sitzungs-ID +::::::::::: + +Die Sitzungs-ID bei der Crawl-Ausführung. + +Crawler-Startzeit +::::::::::::::::: + +Die Uhrzeit, zu der der gesamte Crawl gestartet wurde. + +Crawl-Startzeit (Web/Datei) +::::::::::::::::::::::::::: + +Die Uhrzeit, zu der das Web- und Dateisystem-Crawling gestartet wurde. + +Crawl-Startzeit (Datenspeicher) +:::::::::::::::::::::::::::::::: + +Die Uhrzeit, zu der das Datenspeicher-Crawling gestartet wurde. + +Crawl-Endzeit (Web/Datei) +::::::::::::::::::::::::: + +Die Uhrzeit, zu der das Web- und Dateisystem-Crawling beendet wurde. + +Crawl-Ausführungszeit (Datenspeicher) +:::::::::::::::::::::::::::::::::::::: + +Die Ausführungszeit des Datenspeicher-Crawlings (in Millisekunden). + +Indizierungs-Ausführungszeit (Datenspeicher) +::::::::::::::::::::::::::::::::::::::::::::: + +Die Zeit, die für die Indizierung der Web- und Dateisystem-Crawl-Ergebnisse benötigt wurde (in Millisekunden). + +Indexgröße (Datenspeicher) +:::::::::::::::::::::::::: + +Die Anzahl der indizierten Dokumente. + +Crawl-Endzeit (Datenspeicher) +:::::::::::::::::::::::::::::: + +Die Uhrzeit, zu der das Datenspeicher-Crawling beendet wurde. + +Crawler-Status +:::::::::::::: + +Ob der Crawl erfolgreich war oder nicht. + +Crawler-Endzeit +::::::::::::::: + +Die Uhrzeit, zu der der gesamte Crawl beendet wurde. + +Crawler-Ausführungszeit +::::::::::::::::::::::: + +Die Ausführungszeit des gesamten Crawls (in Millisekunden). + +.. |image0| image:: ../../../resources/images/en/15.10/admin/crawlinginfo-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/crawlinginfo-2.png diff --git a/de/15.10/admin/dashboard-guide.rst b/de/15.10/admin/dashboard-guide.rst new file mode 100644 index 000000000..f010c2a3e --- /dev/null +++ b/de/15.10/admin/dashboard-guide.rst @@ -0,0 +1,58 @@ +=========== +Dashboard +=========== + +Übersicht +========= + +Das Dashboard bietet ein Web-Verwaltungstool zur Verwaltung der OpenSearch-Cluster und -Indizes, auf die |Fess| zugreift. + +|image0| + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: Von |Fess| verwaltete Indizes + :header-rows: 1 + + * - Indexname + - Beschreibung + * - fess.yyyyMMddHHmmssSSS + - Indizierte Dokumente + * - fess_log + - Zugriffsprotokolle + * - fess.suggest.yyyyMMddHHmmssSSS + - Vorschlagswörter + * - fess_config + - |Fess| Konfiguration + * - fess_user + - Benutzer-/Rollen-/Gruppendaten + * - configsync + - Wörterbuchkonfiguration + * - fess_suggest + - Vorschlags-Metadaten + * - fess_suggest_array + - Vorschlags-Metadaten + * - fess_suggest_badword + - Liste unerwünschter Vorschlagswörter + * - fess_suggest_analyzer + - Vorschlags-Metadaten + * - fess_crawler + - Crawl-Informationen + +Der Teil nach ``fess.`` und ``fess.suggest.`` ist der Zeitpunkt, zu dem der Index erstellt wurde (17 Ziffern, ``yyyyMMddHHmmssSSS``). + +Indexnamen, die mit einem Punkt (.) beginnen, sind Systemindizes und werden daher nicht angezeigt. +Um Systemindizes anzuzeigen, aktivieren Sie das Kontrollkästchen „Special". + +Anzahl indizierter Dokumente überprüfen +======================================== + +Die Anzahl der indizierten Dokumente wird wie in der Abbildung unten im Fess-Index angezeigt. + +|image1| + +Wenn Sie auf das Symbol oben rechts in jedem Index klicken, wird ein Operationsmenü für den Index angezeigt. +Um indizierte Dokumente zu löschen, löschen Sie sie über den Verwaltungssuchbildschirm. Achten Sie darauf, NICHT „Index löschen" zu verwenden. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/dashboard-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/dashboard-2.png +.. pdf :width: 400 px diff --git a/de/15.10/admin/dataconfig-guide.rst b/de/15.10/admin/dataconfig-guide.rst new file mode 100644 index 000000000..15b9089ba --- /dev/null +++ b/de/15.10/admin/dataconfig-guide.rst @@ -0,0 +1,408 @@ +=================== +Datenspeicher-Crawl +=================== + +Übersicht +========= + +Datenspeicher-Crawl registriert verschiedene Datenquellen jenseits von Websites und Dateien – etwa relationale Datenbanken (MySQL, PostgreSQL, Oracle) und CSV-Dateien – im Index von |Fess| für die Volltextsuche. Die unterstützten Datenquellen lassen sich durch Datenspeicher-Konnektor-Plugins erweitern. + +Mit |Fess| können Sie Datenquellen wie Datenbanken oder CSV als Crawl-Ziele festlegen. +Hier wird die erforderliche Datenspeicherkonfiguration dafür erläutert. + +Verwaltung +========== + +Anzeige +------- + +Um die Übersichtsseite für die Datenspeicherkonfiguration zu öffnen, klicken Sie im linken Menü auf [Crawler > Datenspeicher]. + +|image0| + +Klicken Sie auf den Konfigurationsnamen, um ihn zu bearbeiten. + +Konfiguration erstellen +----------------------- + +Um die Datenspeicherkonfigurationsseite zu öffnen, klicken Sie auf die Schaltfläche „Neu erstellen". + +|image1| + +Konfigurationsparameter +----------------------- + +Name +:::: + +Geben Sie den Namen der Crawl-Konfiguration an. + +Handler-Name +:::::::::::: + +Der Handler-Name zur Verarbeitung des Datenspeichers. + +* DatabaseDataStore: Crawlt eine Datenbank +* CsvDataStore: Crawlt CSV/TSV-Dateien +* CsvListDataStore: Crawlt eine CSV-Datei, die Dateipfade zu indizierenden Dateien beschreibt + +Die Auswahlliste für den Handler-Namen enthält nur die Handler der installierten Datenspeicher-Konnektor-Plugins (``fess-ds-*``). +Ist kein Plugin installiert, kann kein Handler ausgewählt werden. +Informationen zu weiteren Handlern finden Sie auf den Konnektor-Seiten, die in :doc:`../config/datastore/ds-overview` aufgeführt sind. +Beachten Sie, dass ``EsDataStore`` (das Plugin ``fess-ds-elasticsearch``) aus der Dokumentation früherer Versionen seit 15.6.0 nicht mehr veröffentlicht wurde und in 15.10 nicht verfügbar ist. + +.. note:: + + ``DatabaseDataStore`` wird durch das Datenbank-Konnektor-Plugin (``fess-ds-db``) bereitgestellt, ``CsvDataStore`` / ``CsvListDataStore`` durch das CSV-Konnektor-Plugin (``fess-ds-csv``). Eine Übersicht der verfügbaren Konnektoren finden Sie unter :doc:`../config/datastore/ds-overview`. + +Parameter +::::::::: + +Geben Sie Parameter für den Datenspeicher an. + +Der Parameter ``script_type`` legt fest, mit welcher Skript-Engine das nachfolgende +Skript ausgewertet wird. Neue Konfigurationen sind mit ``script_type=javascript`` +vorausgefüllt. Ist ``script_type`` nicht angegeben, wird das Skript als Groovy +ausgewertet. + +Skript +:::::: + +Geben Sie an, in welchen Feldern die vom Datenspeicher abgerufenen Werte festgelegt werden sollen. +Ausdrücke werden in der Syntax der mit ``script_type`` ausgewählten Skript-Engine +geschrieben (standardmäßig JavaScript). + +.. warning:: + + Schreiben Sie unter JavaScript jede Zeile als reinen Ausdruck ohne abschließendes Semikolon. + Eine Zeile, die sich nur als Block von Anweisungen parsen lässt — alles mit abschließendem + Semikolon oder eine ``let`` / ``const``-Deklaration — wird zu ``null`` ausgewertet, sofern + sie kein explizites ``return`` enthält, und ein Mapping, das zu ``null`` ausgewertet wird, + setzt dieses Feld schlicht nicht. Es gibt weder einen Fehler noch eine Logzeile; das einzige + Symptom ist ein still leer bleibendes Feld. Siehe :ref:`javascript-statement-null` + (in :doc:`../config/scripting-javascript`). + +Boost-Wert +:::::::::: + +Geben Sie den Boost-Wert für Dokumente an, die mit dieser Konfiguration gecrawlt werden. + +Berechtigung +:::::::::::: + +Geben Sie die Berechtigung für diese Konfiguration an. +Um beispielsweise Suchergebnisse für Benutzer anzuzeigen, die zur Gruppe „developer" gehören, geben Sie {group}developer an. +Für Benutzerebene geben Sie {user}Benutzername an, für Rollenebene {role}Rollenname und für Gruppenebene {group}Gruppenname. + +Virtueller Host +::::::::::::::: + +Geben Sie den Hostnamen des virtuellen Hosts an. +Weitere Details finden Sie unter :doc:`Virtueller Host im Konfigurationshandbuch <../config/security-virtual-host>`. + +Status +:::::: + +Geben Sie an, ob diese Crawl-Konfiguration verwendet werden soll. + +Beschreibung +:::::::::::: + +Sie können eine Beschreibung eingeben. + +Konfiguration löschen +--------------------- + +Klicken Sie auf den Konfigurationsnamen auf der Übersichtsseite und dann auf die Schaltfläche „Löschen". Es wird ein Bestätigungsbildschirm angezeigt. +Klicken Sie auf die Schaltfläche „Löschen", um die Konfiguration zu löschen. + +Beispiele +========= + +DatabaseDataStore +----------------- + +Datenbank-Crawling wird erklärt. + +Als Beispiel wird eine Tabelle in der MySQL-Datenbank testdb wie folgt angenommen, auf die mit Benutzername hoge und Passwort fuga zugegriffen werden kann. + +:: + + CREATE TABLE doc ( + id BIGINT NOT NULL AUTO_INCREMENT, + title VARCHAR(100) NOT NULL, + content VARCHAR(255) NOT NULL, + latitude VARCHAR(20), + longitude VARCHAR(20), + versionNo INTEGER NOT NULL, + PRIMARY KEY (id) + ); + +Hier fügen wir folgende Daten ein: + +:: + + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 1', 'コンテンツ 1 です．', '37.77493', ' -122.419416', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 2', 'コンテンツ 2 です．', '34.701909', '135.494977', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 3', 'コンテンツ 3 です．', '-33.868901', '151.207091', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 4', 'コンテンツ 4 です．', '51.500152', '-0.113736', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 5', 'コンテンツ 5 です．', '35.681137', '139.766084', 1); + +Parameter +::::::::: + +Ein Beispiel für die Parameterkonfiguration ist wie folgt: + +:: + + driver=com.mysql.jdbc.Driver + url=jdbc:mysql://localhost:3306/testdb?useUnicode=true&characterEncoding=UTF-8 + username=hoge + password=fuga + sql=select * from doc + +Parameter haben das Format „Schlüssel=Wert". Die Schlüsselerklärungen sind wie folgt: + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - driver + - Treiberklassenname + * - url + - URL + * - username + - Benutzername für die Datenbankverbindung + * - password + - Passwort für die Datenbankverbindung + * - sql + - SQL-Anweisung zum Abrufen von Crawl-Zielen + +Tabelle: Beispiel für DB-Konfigurationsparameter + + +Skript +:::::: + +Ein Beispiel für die Skriptkonfiguration ist wie folgt: + +:: + + url="http://SERVERNAME/" + id + host="SERVERNAME" + site="SERVERNAME" + title=title + content=content + cache=content + digest=content + anchor= + content_length=content.length() + last_modified=new java.util.Date() + location=latitude + "," + longitude + latitude=latitude + longitude=longitude + +Parameter haben das Format „Schlüssel=Wert". Die Schlüsselerklärungen sind wie folgt: + +Die Werte werden in der Syntax der mit ``script_type`` ausgewählten Skript-Engine geschrieben. +Schließen Sie Zeichenketten in doppelte Anführungszeichen ein. Durch Zugriff auf den Datenbank-Spaltennamen wird der entsprechende Wert abgerufen. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - url + - URL (Passen Sie sie an Ihre Umgebung an, um eine URL zu konfigurieren, über die auf die Daten zugegriffen werden kann) + * - host + - Hostname + * - site + - Site-Pfad + * - title + - Titel + * - content + - Dokumentinhalt (zu indizierender Text) + * - cache + - Dokument-Cache (nicht zu indizieren) + * - digest + - In Suchergebnissen angezeigter Digest-Teil + * - anchor + - Im Dokument enthaltene Links (normalerweise nicht erforderlich) + * - content_length + - Dokumentlänge + * - last_modified + - Letztes Änderungsdatum des Dokuments + +Tabelle: Skriptkonfigurationsinhalt + + +Treiber +::::::: + +Zum Verbinden mit der Datenbank ist ein Treiber erforderlich. Platzieren Sie die JAR-Datei in app/WEB-INF/lib. + +CsvDataStore +------------ + +CSV-Datei-Crawling wird erklärt. + +Erstellen Sie beispielsweise eine test.csv-Datei im Verzeichnis /home/taro/csv mit folgendem Inhalt. +Die Dateikodierung sollte Shift_JIS sein. + +:: + + 1,タイトル 1,テスト1です。 + 2,タイトル 2,テスト2です。 + 3,タイトル 3,テスト3です。 + 4,タイトル 4,テスト4です。 + 5,タイトル 5,テスト5です。 + 6,タイトル 6,テスト6です。 + 7,タイトル 7,テスト7です。 + 8,タイトル 8,テスト8です。 + 9,タイトル 9,テスト9です。 + + +Parameter +::::::::: + +Ein Beispiel für die Parameterkonfiguration ist wie folgt: + +:: + + directories=/home/taro/csv + fileEncoding=Shift_JIS + +Parameter haben das Format „Schlüssel=Wert". Die Schlüsselerklärungen sind wie folgt: + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - directories + - Verzeichnis mit CSV-Dateien (.csv oder .tsv) + * - files + - CSV-Dateien (bei direkter Angabe) + * - fileEncoding + - Kodierung der CSV-Datei + * - separatorCharacter + - Trennzeichen + + +Tabelle: Beispiel für CSV-Datei-Konfigurationsparameter + + +Skript +:::::: + +Ein Beispiel für die Skriptkonfiguration ist wie folgt: + +:: + + url="http://SERVERNAME/" + cell1 + host="SERVERNAME" + site="SERVERNAME" + title=cell2 + content=cell3 + cache=cell3 + digest=cell3 + anchor= + content_length=cell3.length() + last_modified=new java.util.Date() + +Parameter haben das Format „Schlüssel=Wert". +Die Schlüssel sind dieselben wie beim Datenbank-Crawling. +Daten in CSV-Dateien werden in cell[Nummer] gespeichert (Nummern beginnen bei 1). +Wenn keine Daten in einer CSV-Zelle vorhanden sind, kann der Wert null sein. + +CsvListDataStore +---------------- + +Wird zum Crawlen großer Dateimengen verwendet. +Durch Platzieren einer CSV-Datei mit Pfaden zu aktualisierten Dateien und Crawlen nur der angegebenen Pfade kann die Crawl-Ausführungszeit verkürzt werden. + +Das Format zum Beschreiben von Pfaden ist wie folgt: + +:: + + [Aktion][Pfad] + +Geben Sie eine der folgenden Aktionen an: + +* create: Datei wurde erstellt +* modify: Datei wurde aktualisiert +* delete: Datei wurde gelöscht + +Erstellen Sie beispielsweise eine test.csv-Datei im Verzeichnis /home/taro/csv mit folgendem Inhalt. +Die Dateikodierung sollte Shift_JIS sein. + +Pfade werden in derselben Notation wie bei der Angabe von Crawl-Zielpfaden beim Datei-Crawling beschrieben. +Geben Sie wie folgt „file:/[Pfad]" oder „smb://[Pfad]" an: + +:: + + modify,smb://servername/data/testfile1.txt + modify,smb://servername/data/testfile2.txt + modify,smb://servername/data/testfile3.txt + modify,smb://servername/data/testfile4.txt + modify,smb://servername/data/testfile5.txt + modify,smb://servername/data/testfile6.txt + modify,smb://servername/data/testfile7.txt + modify,smb://servername/data/testfile8.txt + modify,smb://servername/data/testfile9.txt + modify,smb://servername/data/testfile10.txt + + +Parameter +::::::::: + +Ein Beispiel für die Parameterkonfiguration ist wie folgt: + +:: + + directories=/home/taro/csv + fileEncoding=Shift_JIS + +Parameter haben das Format „Schlüssel=Wert". Die Schlüsselerklärungen sind wie folgt: + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - directories + - Verzeichnis mit CSV-Dateien (.csv oder .tsv) + * - fileEncoding + - Kodierung der CSV-Datei + * - separatorCharacter + - Trennzeichen + + +Tabelle: Beispiel für CSV-Datei-Konfigurationsparameter + + +Skript +:::::: + +Ein Beispiel für die Skriptkonfiguration ist wie folgt: + +:: + + event_type=cell1 + url=cell2 + +Parameter haben das Format „Schlüssel=Wert". +Die Schlüssel sind dieselben wie beim Datenbank-Crawling. + +Wenn für das Crawl-Ziel eine Authentifizierung erforderlich ist, müssen auch folgende Einstellungen konfiguriert werden: + +:: + + crawler.file.auth=example + crawler.file.auth.example.scheme=SAMBA + crawler.file.auth.example.username=username + crawler.file.auth.example.password=password + +Verwandte Seiten +================ + +- :doc:`../config/datastore/index` +- :doc:`../config/datastore/ds-database` +- :doc:`../config/datastore/ds-overview` +- :doc:`../config/crawler-basic` + +.. |image0| image:: ../../../resources/images/en/15.10/admin/dataconfig-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/dataconfig-2.png diff --git a/de/15.10/admin/dict-guide.rst b/de/15.10/admin/dict-guide.rst new file mode 100644 index 000000000..9d69279f8 --- /dev/null +++ b/de/15.10/admin/dict-guide.rst @@ -0,0 +1,170 @@ +=========== +Wörterbuch +=========== + +Übersicht +========= + +Hier wird die Konfiguration von Wörterbüchern erläutert. + +Nehmen Sie Wörterbuchänderungen nur vor, wenn Sie die Spezifikationen der jeweiligen Wörterbücher verstehen. +Fehlerhafte Wörterbuchänderungen können dazu führen, dass auf den Index nicht mehr zugegriffen werden kann. + +.. note:: + + Ist ``search_engine.type`` auf ``vanilla`` oder ``aws`` gesetzt (das OpenSearch hat also keine CodeLibs-Plugins), steht die Wörterbuchverwaltung nicht zur Verfügung. Siehe :doc:`../config/search-engine-type`. + +Übersicht +========= + +Um die Übersichtsseite der verwaltbaren Wörterbücher zu öffnen, klicken Sie im linken Menü auf [System > Wörterbuch]. + + +|image0| + + +Geltungsbereich der Wörterbücher und Zeitpunkt der Wirksamkeit +============================================================== + +Jedes Wörterbuch wirkt auf andere Felder und wird zu einem anderen Zeitpunkt +wirksam. Wenn Sie ein Wörterbuch bearbeitet haben und sich die Suchergebnisse +nicht ändern, prüfen Sie zuerst diese Tabelle. + +.. list-table:: + :header-rows: 1 + :widths: 22 26 28 24 + + * - Wörterbuch + - Datei + - Betroffene Felder + - Zeitpunkt der Wirksamkeit + * - Kuromoji + - ``ja/kuromoji.txt`` + - Nur ``_ja``-Felder wie ``content_ja`` + - Beim Indexieren (erneutes Crawlen erforderlich) + * - Synonym + - ``synonym.txt`` + - ``content`` und ``title`` + - Bei der Suche (kein erneutes Crawlen nötig) + * - Mapping (alle Sprachen) + - ``mapping.txt`` + - ``content`` und ``title`` + - Beim Indexieren (erneutes Crawlen erforderlich) + * - Mapping (je Sprache) + - ``ja/mapping.txt`` + - Nur ``_ja``-Felder wie ``content_ja`` + - Beim Indexieren (erneutes Crawlen erforderlich) + * - Protwords + - ``en/protwords.txt`` + - ``content`` und ``title`` + - Beim Indexieren und bei der Suche + * - Stoppwörter + - ``en/stopwords.txt`` + - ``content`` und ``title`` + - Beim Indexieren und bei der Suche + * - Stemmer-Überschreibung + - ``en/stemmer_override.txt`` + - ``content`` und ``title`` + - Beim Indexieren und bei der Suche + +.. note:: + + Ein Analyzer wird beim Öffnen des Index aufgebaut. Eine Änderung an einer + Wörterbuchdatei wird daher erst wirksam, **wenn der Index geschlossen und + wieder geöffnet wird**. Ein Wörterbuch, das beim Indexieren wirkt, wird + zudem nicht rückwirkend auf bereits indexierte Dokumente angewendet; diese + müssen erneut gecrawlt werden. + Wie Sie eine Änderung übernehmen, steht unter :ref:`dict-apply-changes`. + +.. warning:: + + Das Zeichenersetzungs-Wörterbuch, das auf ``content`` wirkt -- das Feld, aus + dem die meisten Suchen beantwortet werden -- ist die ``mapping.txt`` im + **Wurzelverzeichnis**, nicht ``ja/mapping.txt``. Beide heißen Mapping, sind + aber verschiedene Dateien. + +.. _dict-apply-changes: + +Wörterbuchänderungen übernehmen +------------------------------- + +Das Speichern eines Wörterbuchs ändert die Suchergebnisse nicht, egal wie lange Sie warten. Das +configsync-Plugin von OpenSearch schreibt die gespeicherten Wörterbücher etwa einmal pro Minute in +ihre Dateien, ein Analyzer liest seine Wörterbücher aber nur beim Öffnen des Index, sodass ein +bereits geöffneter Index weiter die alten verwendet. Laden Sie den Dokumentindex nach dem +Bearbeiten von Wörterbüchern neu: + +1. Öffnen Sie im linken Menü [Systeminformationen > Wartung]. +2. Klicken Sie unter „Dokumentenindex neu laden“ auf [Neu laden]. + +Die Schaltfläche schreibt zuerst die gespeicherten Wörterbücher in ihre Dateien und schließt und +öffnet dann den Index, auf den der Alias ``fess.update`` zeigt; auf das regelmäßige Schreiben +müssen Sie nicht warten. Ein Wörterbuch, das bei der Suche wirkt, etwa ein Synonym, wird wirksam, +sobald der Index wieder geöffnet ist. Bei einem Wörterbuch, das beim Indexieren wirkt, crawlen Sie +die betroffenen Dokumente zusätzlich erneut. + +.. warning:: + + Solange der Index geschlossen ist und bis seine Shards nach dem Öffnen wieder zugewiesen sind, + kann der Index nicht durchsucht werden: Suchen schlagen fehl oder liefern keine Ergebnisse. Je + größer der Index, desto länger dauert das; laden Sie ihn daher zu einer ruhigen Zeit neu. + +Um dasselbe ohne die Verwaltungsoberfläche aus einem Skript heraus zu tun, senden Sie dieselben +Operationen an OpenSearch:: + + curl -X POST "localhost:9200/_configsync/flush" + curl -X POST "localhost:9200/fess.update/_close" + curl -X POST "localhost:9200/fess.update/_open" + +``_configsync/flush`` schreibt die gespeicherten Wörterbücher sofort in ihre Dateien. Ohne diesen +Aufruf warten Sie nach dem Speichern mindestens eine Minute, bevor Sie den Index schließen. + +Kuromoji-Benutzerwörterbuch und Suchergebnisse +---------------------------------------------- + +Das Feld ``content`` wird mit dem Standard-Tokenizer und ``cjk_bigram`` +analysiert und ist deshalb davon unabhängig, wie Kuromoji ein Wort zerlegt. +Ein japanisches Kompositum im Kuromoji-Benutzerwörterbuch zu registrieren und +erneut zu crawlen ändert an einer Suche gegen ``content`` also nichts. Wirksam +wird der Eintrag in ``content_ja``, das je nach Sprache der Anfrage zur Abfrage +hinzugenommen wird. + +Kuromoji +======== + +Verwaltet das Wörterbuch für die japanische morphologische Analyse. +ja/kuromoji.txt ist das Wörterbuch für die japanische morphologische Analyse. + +Synonyme +======== + +Verwaltet das Synonym-Wörterbuch. +synonym.txt ist die sprachübergreifend verwendete Synonym-Wörterbuchdatei. + +Mapping +======= + +Verwaltet das Zeichenersetzungs-Wörterbuch. +mapping.txt ist die sprachübergreifende oder sprachspezifische Wortersetzungs-Wörterbuchdatei. + +Protwords +========= + +Verwaltet das Schutzwort-Wörterbuch. +protwords.txt wird für jede Sprache platziert und ist eine Wortliste für Wörter, die vom Stemming ausgeschlossen werden sollen. + +Stoppwörter +=========== + +Verwaltet das Stoppwort-Wörterbuch. +stopwords.txt wird für jede Sprache platziert und ist eine Wortliste für Wörter, die bei der Indexerstellung ausgeschlossen werden sollen. + +Stemmer-Überschreibung +====================== + +Verwaltet das Stemmer-Überschreibungs-Wörterbuch. +stemmer_override.txt wird für jede Sprache platziert und ist eine Wortersetzungs-Wörterbuchdatei zum Überschreiben der Stemming-Verarbeitung. + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/dict-1.png + :height: 940px diff --git a/de/15.10/admin/docreport-guide.rst b/de/15.10/admin/docreport-guide.rst new file mode 100644 index 000000000..6b861d559 --- /dev/null +++ b/de/15.10/admin/docreport-guide.rst @@ -0,0 +1,70 @@ +=============== +Dokumentbericht +=============== + +Übersicht +========= + +Die Seite Dokumentbericht hilft beim Aufräumen gecrawlter Dateiserver und Ähnlichem. Sie listet +Dokumente mit gleichem Inhalt und Dokumente auf, die lange nicht geändert wurden; jede Liste lässt +sich als CSV herunterladen. + +Um die Seite zu öffnen, wählen Sie im linken Menü [Systeminformationen > Dokumentbericht]. Zum +Anzeigen ist die Rolle ``admin-docreport`` oder ``admin-docreport-view`` erforderlich. Die Seite +zeigt Berichte nur an und lädt sie herunter; sie ändert keine Dokumente. + +Beide Registerkarten lassen sich mit „URL-Präfix“ eingrenzen, zum Beispiel ``smb://server/share/``. + +Duplikate +========= + +Dokumente mit gleichem oder nahezu gleichem Inhalt werden gruppiert, die größte Gruppe zuerst. Die +Gruppen beruhen auf der beim Indexieren berechneten Inhaltssignatur (``content_minhash_bits``, +dieselbe, die doppelte Suchergebnisse zusammenfasst); eine Neuindexierung ist daher nicht nötig. +Dokumente, deren Inhalt keine Wörter enthält (etwa leere Dateien), werden ausgelassen. + +Die Seite zeigt bis zu ``docreport.duplicate.group.size`` (Standard: 100) Gruppen und je Gruppe bis zu +``docreport.duplicate.docs.size`` (Standard: 10) Dokumente. Mit [CSV herunterladen] erhalten Sie alle +Gruppen. Die CSV-Datei liest auch bei einem großen Index alle Gruppen, mit den Spalten +``group, groupSize, url, title, filename, contentLength, lastModified, owner, lastModifier, clickCount, docId``. + +.. note:: + + Der Duplikatbericht benötigt die Inhaltssignatur, die die Indexdefinitionen für ein OpenSearch ohne die CodeLibs-Plugins (``search_engine.type`` mit ``vanilla``, ``aws`` oder dem veralteten ``cloud``) nicht berechnen. Bei diesen Typen wird die Registerkarte „Duplikate“ ausgeblendet, und nur der Bericht über inaktive Dokumente ist verfügbar. Siehe :doc:`../config/search-engine-type`. + +Inaktive Dokumente +================== + +Dokumente, deren letzte Änderung älter als die angegebene Anzahl von Tagen ist („Nicht geändert seit +(Tagen)“, Standard 365 aus ``docreport.dormant.days``), werden aufgelistet, die ältesten zuerst. +Dokumente ohne Änderungsdatum werden nicht aufgeführt. Mit „Nie aus den Suchergebnissen geöffnet“ +werden Dokumente ausgelassen, die aus Suchergebnissen angeklickt wurden. + +Die Seite zeigt die Anzahl der passenden Dokumente, ihre Gesamtgröße und eine seitenweise Liste. Das +Blättern endet bei ``indexer.max.result.window.size``; Dokumente darüber hinaus erhalten Sie mit +[CSV herunterladen]. + +Einstellungen +============= + +Die folgenden Einstellungen in ``fess_config.properties`` steuern den Bericht. + +.. list-table:: + :header-rows: 1 + :widths: 40 45 15 + + * - Eigenschaft + - Beschreibung + - Standard + * - ``docreport.duplicate.group.size`` + - Höchstzahl der Duplikatgruppen, die die Seite anzeigt + - ``100`` + * - ``docreport.duplicate.docs.size`` + - Höchstzahl der Dokumente, die die Seite je Gruppe auflistet + - ``10`` + * - ``docreport.duplicate.export.page.size`` + - Anzahl der Inhaltssignaturen, die beim CSV-Download je Anfrage gelesen werden + - ``10000`` + * - ``docreport.dormant.days`` + - Standardanzahl der Tage seit der letzten Änderung, ab der ein Dokument als inaktiv gilt + - ``365`` diff --git a/de/15.10/admin/duplicatehost-guide.rst b/de/15.10/admin/duplicatehost-guide.rst new file mode 100644 index 000000000..bd8b686fa --- /dev/null +++ b/de/15.10/admin/duplicatehost-guide.rst @@ -0,0 +1,59 @@ +================ +Duplikat-Hosts +================ + +Übersicht +========= + +Hier wird die Konfiguration von Duplikat-Hosts erläutert. +Duplikat-Hosts werden verwendet, wenn Sie verschiedene Hostnamen beim Crawlen als identisch behandeln möchten. +Zum Beispiel können Sie dies verwenden, wenn Sie www.example.com und example.com als dieselbe Site behandeln möchten. + +Verwaltung +========== + +Anzeige +------- + +Um die Übersichtsseite für die Duplikat-Host-Konfiguration zu öffnen, klicken Sie im linken Menü auf [Crawler > Doppelter Host]. + +|image0| + +Klicken Sie auf den Konfigurationsnamen, um ihn zu bearbeiten. + +Konfiguration erstellen +----------------------- + +Um die Duplikat-Host-Konfigurationsseite zu öffnen, klicken Sie auf die Schaltfläche „Neu erstellen". + +|image1| + +Konfigurationsparameter +----------------------- + +Regulärer Name +:::::::::::::: + +Geben Sie den kanonischen Hostnamen an. Duplikat-Hostnamen werden durch den kanonischen Hostnamen ersetzt. + +Doppelter Name +:::::::::::::: + +Geben Sie den duplizierenden Hostnamen an. Geben Sie den Hostnamen an, der ersetzt werden soll. + +.. note:: + + Eine URL, deren Hostname einem doppelten Namen entspricht, wird vor dem Crawlen durch die URL mit dem regulären Namen ersetzt. Das gilt sowohl für die unter „URLs" (den Start-URLs) der Crawl-Konfiguration eingetragenen URLs als auch für die URLs von Links, die beim Crawlen gefunden werden. + Daher werden „Eingeschlossene URLs" und „Ausgeschlossene URLs" der Crawl-Konfiguration anhand der URL nach der Ersetzung ausgewertet. Schreiben Sie sie mit dem Hostnamen des regulären Namens. + + Wenn der reguläre Name zum Beispiel ``example.com`` und der doppelte Name ``www.example.com`` lautet, wird bei einem Eintrag von nur ``https://www.example.com/.*`` unter „Eingeschlossene URLs" die Start-URL nach der Ersetzung (``https://example.com/``) ausgeschlossen. + In diesem Fall wird kein einziges Dokument im Index registriert, und es erscheinen weder ein Fehler noch eine Protokollmeldung. + +Konfiguration löschen +--------------------- + +Klicken Sie auf den Konfigurationsnamen auf der Übersichtsseite und dann auf die Schaltfläche „Löschen". Es wird ein Bestätigungsbildschirm angezeigt. +Klicken Sie auf die Schaltfläche „Löschen", um die Konfiguration zu löschen. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/duplicatehost-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/duplicatehost-2.png diff --git a/de/15.10/admin/elevateword-guide.rst b/de/15.10/admin/elevateword-guide.rst new file mode 100644 index 000000000..89e3426a4 --- /dev/null +++ b/de/15.10/admin/elevateword-guide.rst @@ -0,0 +1,106 @@ +=============== +Zusätzliche Wörter +=============== + +Übersicht +========= + +Hier wird die Konfiguration zusätzlicher Wörter für Vorschläge erläutert. Vorschläge werden entsprechend den Suchbegriffen angezeigt, aber Sie können zusätzliche Wörter hinzufügen. + +Verwaltung +========== + +Anzeige +------- + +Um die Übersichtsseite für die Konfiguration zusätzlicher Wörter zu öffnen, klicken Sie im linken Menü auf [Vorschlagen > Wort erhöhen]. + +|image0| + +Klicken Sie auf den Konfigurationsnamen, um ihn zu bearbeiten. + +Konfiguration erstellen +----------------------- + +Um die Konfigurationsseite für zusätzliche Wörter zu öffnen, klicken Sie auf die Schaltfläche „Neu erstellen". + +|image1| + +Konfigurationsparameter +----------------------- + +Wort +:::: + +Geben Sie das Wort an, das als Vorschlagskandidat angezeigt werden soll. + +Lesen +::::: + +Geben Sie die Lesung des Vorschlagskandidatenworts an. + +Berechtigung +:::::::::::: + +Legen Sie Rolleninformationen für das Wort fest. +Nur Benutzer mit der festgelegten Rolle können das Wort in den Vorschlägen sehen. + +Label +::::: + +Legen Sie ein Label für das Wort fest. +Wenn ein anderes als das festgelegte Label ausgewählt ist, wird das Wort nicht in den Vorschlägen angezeigt. + +Boost-Wert +:::::::::: + +Legen Sie einen Boost-Wert für das Wort fest. + +Konfiguration löschen +--------------------- + +Klicken Sie auf den Konfigurationsnamen auf der Übersichtsseite und dann auf die Schaltfläche „Löschen". Es wird ein Bestätigungsbildschirm angezeigt. +Klicken Sie auf die Schaltfläche „Löschen", um die Konfiguration zu löschen. + + +Download +======== + +Laden Sie registrierte Wörter im CSV-Format herunter. + +|image2| + +CSV-Inhalt +---------- + +Zeile 1 ist die Kopfzeile. +Ab Zeile 2 werden die zusätzlichen Wörter aufgeführt. + +:: + +"SuggestWord","Reading","Role","Label","Boost" +"fess","ふぇす","role1","label1","100" + +Upload +====== + +Registrieren Sie Wörter im CSV-Format. + +|image3| + +CSV-Inhalt +---------- + +Zeile 1 ist die Kopfzeile. +Ab Zeile 2 beschreiben Sie die zusätzlichen Wörter. + +:: + +"SuggestWord","Reading","Role","Label","Boost" +"fess","ふぇす","role1","label1","100" + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/elevateword-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/elevateword-2.png +.. |image2| image:: ../../../resources/images/en/15.10/admin/elevateword-3.png +.. |image3| image:: ../../../resources/images/en/15.10/admin/elevateword-4.png diff --git a/de/15.10/admin/esreq-guide.rst b/de/15.10/admin/esreq-guide.rst new file mode 100644 index 000000000..a2975e270 --- /dev/null +++ b/de/15.10/admin/esreq-guide.rst @@ -0,0 +1,53 @@ +======================= +Anfrage an OpenSearch +======================= + +Übersicht +========= + +Auf dieser Seite können Sie eine in einer JSON-Datei beschriebene Anfrage an OpenSearch senden. + +|image0| + +Diese Seite ist nicht im Menü enthalten. +Um sie anzuzeigen, melden Sie sich als Administrator an und geben ``/admin/sereq/`` als URL-Pfad ein. +Zum Senden einer Anfrage ist die Rolle ``admin`` (Administratoren) oder die Rolle ``admin-sereq`` erforderlich. + +Bedienung +========= + +Anforderung senden +------------------ + +Erstellen Sie die Anfrage, die Sie an OpenSearch senden möchten, als JSON-Datei, wählen Sie diese Datei als „Anforderungsdatei" aus und klicken Sie auf die Schaltfläche „Senden", um die Anfrage an OpenSearch zu senden. +Die Antwort wird als Datei heruntergeladen. + +Konfigurationsparameter +----------------------- + +Anforderungsdatei +::::::::::::::::: + +Geben Sie die Datei an, die die Anfrage enthält. + +Schreiben Sie in die erste Zeile `` ``, getrennt durch genau ein Leerzeichen, und in die folgenden Zeilen den Anfragekörper (zum Beispiel eine Abfrage-DSL). +Als Methode sind GET, POST, PUT und DELETE möglich. Der Pfad ist der Pfad auf OpenSearch; das führende ``/`` kann weggelassen werden. +Zum Beispiel könnte der Inhalt der Datei wie folgt aussehen. + +:: + + POST /_search + { + "query": { + "match_all": {} + } + } + +Zeilenumbrüche im Körper werden entfernt, und die Zeilen werden vor dem Senden zusammengefügt. Eine Anfrage, deren Körper pro Zeile ein JSON-Dokument enthält, wie ``_bulk``, kann daher nicht gesendet werden. + +.. warning:: + + Auch eine Anfrage mit der Methode PUT oder DELETE wird unverändert an OpenSearch gesendet. + Je nach Inhalt der Datei können dadurch die von |Fess| verwendeten Indizes geändert oder gelöscht werden und Daten verloren gehen. Prüfen Sie den Inhalt vor dem Senden sorgfältig. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/esreq-1.png diff --git a/de/15.10/admin/failureurl-guide.rst b/de/15.10/admin/failureurl-guide.rst new file mode 100644 index 000000000..d708b85c9 --- /dev/null +++ b/de/15.10/admin/failureurl-guide.rst @@ -0,0 +1,66 @@ +========= +Fehler-URLs +========= + +Übersicht +========= + +Hier werden Fehler-URLs erläutert. +URLs, die beim Crawlen nicht abgerufen werden konnten, werden aufgezeichnet und können als Fehler-URLs überprüft werden. + +Verwaltung +========== + +Anzeige +------- + +Um die Übersichtsseite zur Überprüfung von Fehler-URLs zu öffnen, klicken Sie im linken Menü auf [Systeminformationen > Fehler-URL]. + +|image0| + +Klicken Sie auf den Bestätigungslink der Fehler-URL, um Details anzuzeigen. + +Fehler-URL-Details +================== + +In den Fehler-URL-Details werden beim Crawlen aufgetretene Ausnahmen aufgezeichnet. + +|image1| + +Detailinhalt +------------ + +URL +::: + +Die URL, bei der die Ausnahme aufgetreten ist. + +Thread-Name +::::::::::: + +Der Name des Threads, der den Crawl ausgeführt hat. +Kann beim Überprüfen von Protokolldateien verwendet werden. + +Typ +::: + +Der Typ der Ausnahme. + +Protokoll +::::::::: + +Der Inhalt der Ausnahme. + +Fehleranzahl +:::::::::::: + +Die Anzahl, wie oft diese Ausnahme aufgetreten ist. + +Letzte Zugriffszeit +::::::::::::::::::: + +Die Uhrzeit, zu der diese Ausnahme aufgetreten ist. + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/failureurl-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/failureurl-2.png diff --git a/de/15.10/admin/fileauth-guide.rst b/de/15.10/admin/fileauth-guide.rst new file mode 100644 index 000000000..bdd866e2b --- /dev/null +++ b/de/15.10/admin/fileauth-guide.rst @@ -0,0 +1,85 @@ +================== +Dateiauthentifizierung +================== + +Übersicht +========= + +Hier wird die Konfigurationsmethode erläutert, wenn Dateiauthentifizierung für das Crawlen von Dateien erforderlich ist. +|Fess| unterstützt die Authentifizierung für FTP oder Windows-Freigabeordner. + +Verwaltung +========== + +Anzeige +------- + +Um die Übersichtsseite für die Dateiauthentifizierungskonfiguration zu öffnen, klicken Sie im linken Menü auf [Crawler > Datei-Authentifizierung]. + +|image0| + +Klicken Sie auf den Konfigurationsnamen, um ihn zu bearbeiten. + +Konfiguration erstellen +----------------------- + +Um die Dateiauthentifizierungskonfigurationsseite zu öffnen, klicken Sie auf die Schaltfläche „Neu erstellen". + +|image1| + +Konfigurationsparameter +----------------------- + +Hostname +:::::::: + +Geben Sie den Hostnamen der Site an, die Authentifizierung erfordert. +Verwenden Sie denselben Namen wie den Hostnamen in der zu crawlenden URL. Für eine URL mit einem anderen Namen (zum Beispiel einer IP-Adresse statt eines Alias) wird diese Authentifizierung nicht verwendet. + +Port +:::: + +Geben Sie den Port der Site an, die Authentifizierung erfordert. +Bleibt das Feld leer, zeigt die Liste „Beliebig" an. Die Bedeutung eines leeren Ports hängt vom Schema ab. + +* FTP: Wird für URLs mit beliebigem Port verwendet (eine URL ohne Port gilt als Port 21). +* SAMBA: Wird nur für URLs verwendet, die keinen Port enthalten (``smb://Server/Freigabe/``). Für eine URL mit Port, etwa ``smb://Server:445/Freigabe/``, wird sie nicht verwendet. Wenn Sie eine URL mit Port crawlen, geben Sie hier denselben Port an. + +Schema +:::::: + +Wählen Sie die Authentifizierungsmethode aus. +Sie können FTP oder SAMBA (Windows-Freigabeordnerauthentifizierung) verwenden. + +Benutzername +:::::::::::: + +Geben Sie den Benutzernamen für die Anmeldung bei der Authentifizierungssite an. + +Passwort +:::::::: + +Geben Sie das Passwort für die Anmeldung bei der Authentifizierungssite an. + +Parameter +::::::::: + +Konfigurieren Sie dies, wenn Konfigurationswerte für die Anmeldung bei der Authentifizierungssite erforderlich sind. Für SAMBA können Sie den Domänenwert konfigurieren. Geben Sie ihn wie folgt an: + +:: + + domain=FUGA + +Datei-Crawl-Konfiguration +::::::::::::::::::::::::: + +Geben Sie die Crawl-Konfiguration an, die diese Authentifizierungskonfiguration verwenden soll. + +Konfiguration löschen +--------------------- + +Klicken Sie auf den Konfigurationsnamen auf der Übersichtsseite und dann auf die Schaltfläche „Löschen". Es wird ein Bestätigungsbildschirm angezeigt. +Klicken Sie auf die Schaltfläche „Löschen", um die Konfiguration zu löschen. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/fileauth-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/fileauth-2.png diff --git a/de/15.10/admin/fileconfig-guide.rst b/de/15.10/admin/fileconfig-guide.rst new file mode 100644 index 000000000..d4b859de2 --- /dev/null +++ b/de/15.10/admin/fileconfig-guide.rst @@ -0,0 +1,263 @@ +================================ +Datei-Crawl (Dateiserver-Suche) +================================ + +Übersicht +========= + +Datei-Crawl ist eine Funktion, mit der Dokumente von internen Dateiservern, freigegebenen Windows-Ordnern oder Cloud-Speichern in den Index von |Fess| aufgenommen werden, sodass sie per Volltextsuche (Dateiserver-Suche) auffindbar sind. Zahlreiche Dateiformate wie Word, Excel, PowerPoint und PDF werden unterstützt. + +Welche Pfade gecrawlt werden, richtet sich nach dem im „Pfad" angegebenen Protokoll: + +- ``file:/`` … lokales oder eingehängtes Dateisystem +- ``smb://`` … Windows-Dateiserver/freigegebene Ordner (SMB/CIFS) +- ``smb1://`` … Windows-Dateiserver/freigegebene Ordner über das ältere SMB1-Protokoll +- ``ftp://`` … FTP-Server +- ``s3://`` … Amazon-S3-Bucket (erfordert das Plugin ``fess-storage-s3``) +- ``gcs://`` … Google-Cloud-Storage-Bucket (erfordert das Plugin ``fess-storage-gcs``) + +Auf der Datei-Crawl-Konfigurationsseite können Sie Konfigurationen zum Crawlen von Dateien im Dateisystem oder in freigegebenen Netzwerkordnern verwalten. + +Verwaltung +========== + +Anzeige +------- + +Um die Übersichtsseite für die Datei-Crawl-Konfiguration zu öffnen, klicken Sie im linken Menü auf [Crawler > Dateisystem]. + +|image0| + +Klicken Sie auf den Konfigurationsnamen, um ihn zu bearbeiten. + +Konfiguration erstellen +----------------------- + +Um die Datei-Crawl-Konfigurationsseite zu öffnen, klicken Sie auf die Schaltfläche „Neu erstellen". + +|image1| + +Konfigurationsparameter +----------------------- + +Name +:::: + +Der Name der Konfiguration. + +Pfad +:::: + +In diesem Pfad geben Sie an, wo das Crawlen beginnen soll (z. B. file:/, smb://, s3://, gcs://). + +Zu crawlender Pfad +:::::::::::::::::: + +Pfade, die mit dem regulären Ausdruck (Java-Format) übereinstimmen, der in diesem Element angegeben ist, werden vom |Fess| Crawler gecrawlt. + +Vom Crawlen ausgeschlossener Pfad +:::::::::::::::::::::::::::::::::: + +Pfade, die mit dem regulären Ausdruck (Java-Format) übereinstimmen, der in diesem Element angegeben ist, werden vom |Fess| Crawler nicht gecrawlt. + +Zu durchsuchender Pfad +::::::::::::::::::::::: + +Pfade, die mit dem regulären Ausdruck (Java-Format) übereinstimmen, der in diesem Element angegeben ist, werden in die Suche einbezogen. + +Von der Suche ausgeschlossener Pfad +:::::::::::::::::::::::::::::::::::: + +Pfade, die mit dem regulären Ausdruck (Java-Format) übereinstimmen, der in diesem Element angegeben ist, werden von der Suche ausgeschlossen. + +Konfigurationsparameter +::::::::::::::::::::::: + +Sie können Crawl-Konfigurationsinformationen angeben. + +Beim Crawlen von Pfaden, die mit ``file:`` beginnen (lokales oder eingehängtes Dateisystem), legen Sie mit ``client.followSymlink`` fest, ob symbolischen Links gefolgt wird. Der Standardwert ist ``true`` (Links werden verfolgt). Bei ``false`` werden symbolische Links übersprungen, und die Dateien, auf die sie verweisen, werden nicht über den Link gecrawlt (jeder übersprungene Link wird in ``fess-crawler.log`` auf INFO-Ebene protokolliert). Wird einem Link gefolgt, wird die Zieldatei ein zweites Mal mit den Berechtigungen der Konfiguration registriert, die den Link enthält. Erwägen Sie daher ``false``, wenn Sie eine Freigabe crawlen, die für mehr Benutzer lesbar ist als die Verzeichnisstruktur, auf die ihre Links verweisen. + +:: + + client.followSymlink=false + +Tiefe +::::: + +Geben Sie die Tiefe der zu crawlenden Dateisystemstruktur an. + +Maximale Zugriffszahl +::::::::::::::::::::: + +Geben Sie die Anzahl der zu indizierenden Pfade an. + +Thread-Anzahl +::::::::::::: + +Geben Sie die Anzahl der für diese Konfiguration zu verwendenden Threads an. + +Intervall +::::::::: + +Geben Sie die Wartezeit an, die jeder Thread nach dem Crawlen eines Pfads wartet. + +Boost-Wert +:::::::::: + +Der Boost-Wert ist die Priorität von Dokumenten, die durch diese Konfiguration indiziert werden. + +Berechtigung +:::::::::::: + +Geben Sie die Berechtigung für diese Konfiguration an. +Um beispielsweise Suchergebnisse für Benutzer anzuzeigen, die zur Gruppe „developer" gehören, geben Sie {group}developer an. +Für Benutzerebene geben Sie {user}Benutzername an, für Rollenebene {role}Rollenname und für Gruppenebene {group}Gruppenname. + +Virtueller Host +::::::::::::::: + +Geben Sie den Hostnamen des virtuellen Hosts an. +Weitere Details finden Sie unter :doc:`Virtueller Host im Konfigurationshandbuch <../config/security-virtual-host>`. + +Status +:::::: + +Wenn diese Konfiguration aktiviert ist, enthält der Standard-Crawler-Job diese Konfiguration beim Crawlen. + +Beschreibung +:::::::::::: + +Sie können eine Beschreibung eingeben. + +Konfiguration löschen +--------------------- + +Klicken Sie auf den Konfigurationsnamen auf der Übersichtsseite und dann auf die Schaltfläche „Löschen". Es wird ein Bestätigungsbildschirm angezeigt. Klicken Sie auf die Schaltfläche „Löschen", um die Konfiguration zu löschen. + +Beispiele +========= + +Lokale Dateien crawlen +---------------------- + +Um Dateien unter /home/share zu crawlen, würde die Konfiguration wie folgt aussehen: + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - Name + - Wert + * - Name + - Freigabeverzeichnis + * - Pfad + - file:/home/share + +Andere Parameter können mit Standardeinstellungen belassen werden. + +Windows-Freigabeordner crawlen +------------------------------- + +Um Dateien unter \\SERVER\SharedFolder zu crawlen, würde die Konfiguration wie folgt aussehen: + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - Name + - Wert + * - Name + - Freigabeordner + * - Pfad + - smb://SERVER/SharedFolder/ + +Wenn für den Zugriff auf den Freigabeordner ein Benutzername/Passwort erforderlich ist, müssen Sie eine Dateiauthentifizierungskonfiguration über [Crawler > Datei-Authentifizierung] im linken Menü erstellen. +Die Konfiguration dafür würde wie folgt aussehen: + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - Name + - Wert + * - Hostname + - SERVER + * - Schema + - SAMBA + * - Benutzername + - (Bitte eingeben) + * - Passwort + - (Bitte eingeben) + +Amazon S3-Buckets crawlen +------------------------- + +Um Dateien im Bucket my-bucket zu crawlen, würde die Konfiguration wie folgt aussehen: + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - Name + - Wert + * - Name + - S3-Bucket + * - Pfad + - s3://my-bucket/ + +Für den S3-Zugriff sind Anmeldeinformationen erforderlich. Fügen Sie Folgendes zu „Konfigurationsparameter" hinzu: + +:: + + client.endpoint=https://s3.ap-northeast-1.amazonaws.com + client.accessKey=IHR_ZUGRIFFSSCHLÜSSEL + client.secretKey=IHR_GEHEIMER_SCHLÜSSEL + client.region=ap-northeast-1 + +.. note:: + Die Unterstützung für Amazon S3 und S3-kompatible Speicher kommt aus dem Plugin + ``fess-storage-s3``, das nicht Teil der Distribution ist. Installieren Sie es über die + Seite **System > Plugin** in der Administrationsoberfläche oder mit + ``bin/fess-setup install plugin fess-storage-s3``. + +Google Cloud Storage-Buckets crawlen +------------------------------------ + +Um Dateien im Bucket my-gcs-bucket zu crawlen, würde die Konfiguration wie folgt aussehen: + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - Name + - Wert + * - Name + - GCS-Bucket + * - Pfad + - gcs://my-gcs-bucket/ + +Für den GCS-Zugriff sind Anmeldeinformationen erforderlich. Fügen Sie Folgendes zu „Konfigurationsparameter" hinzu: + +:: + + client.projectId=ihre-projekt-id + client.credentialsFile=/pfad/zu/service-account.json + +.. note:: + Die Unterstützung für Google Cloud Storage kommt aus dem Plugin ``fess-storage-gcs``, das + nicht Teil der Distribution ist. Installieren Sie es über die Seite **System > Plugin** in + der Administrationsoberfläche oder mit ``bin/fess-setup install plugin fess-storage-gcs``. + +Verwandte Seiten +================ + +- :doc:`../config/crawler-basic` +- :doc:`fileauth-guide` +- :doc:`../config/datastore/ds-overview` +- :doc:`../config/search-basic` +- :doc:`../user/index` + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/fileconfig-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/fileconfig-2.png +.. pdf :height: 940 px diff --git a/de/15.10/admin/general-guide.rst b/de/15.10/admin/general-guide.rst new file mode 100644 index 000000000..97e5e3eba --- /dev/null +++ b/de/15.10/admin/general-guide.rst @@ -0,0 +1,684 @@ +========= +Allgemein +========= + +Übersicht +========= + +Auf dieser Verwaltungsseite können Sie die Konfiguration von |Fess| verwalten. +Sie können verschiedene Konfigurationen von |Fess| ändern, ohne |Fess| neu zu starten. + +Konfigurationsinhalt +==================== + +System +------ + +|image0| + +JSON-Antwort +:::::::::::: + +Gibt an, ob die JSON-API aktiviert werden soll. + +Anmeldung erforderlich +:::::::::::::::::::::: + +Gibt an, ob eine Anmeldung für die Suchfunktion erforderlich ist. + +Anmeldelink anzeigen +:::::::::::::::::::: + +Konfiguriert, ob auf dem Suchbildschirm ein Link zur Anmeldeseite angezeigt werden soll. + +Doppelte Ergebnisse ausblenden +::::::::::::::::::::::::::::::: + +Konfiguriert, ob das Ausblenden doppelter Ergebnisse aktiviert werden soll. + +Ist ``search_engine.type`` auf ``vanilla`` oder ``aws`` gesetzt, wird dieser Eintrag nicht angezeigt, und das Ausblenden bleibt ausgeschaltet (siehe :doc:`../config/search-engine-type`). + +Miniaturansicht anzeigen +:::::::::::::::::::::::: + +Konfiguriert, ob die Miniaturansicht aktiviert werden soll. + +Systemeigenschaften +::::::::::::::::::: + +Konfiguriert die Systemeigenschaften von |Fess|. +Geben Sie im Format ``key=value`` an, eine pro Zeile. + +Standard-Labelwert +::::::::::::::::::: + +Beschreiben Sie den Label-Wert, der standardmäßig zur Suchbedingung hinzugefügt werden soll. +Um ihn für Rollen oder Gruppen anzugeben, fügen Sie „role:" oder „group:" hinzu, wie z. B. „role:admin=label1". + +Standard-Sortierwert +:::::::::::::::::::: + +Beschreiben Sie den Sortierwert, der standardmäßig zur Suchbedingung hinzugefügt werden soll. +Um ihn für Rollen oder Gruppen anzugeben, fügen Sie „role:" oder „group:" hinzu, wie z. B. „role:admin=content_length.desc". + +Virtueller Host +::::::::::::::: + +Konfigurieren Sie den virtuellen Host. +Weitere Details finden Sie unter :doc:`Virtueller Host im Konfigurationshandbuch <../config/security-virtual-host>`. + +Antwort für beliebtes Wort +:::::::::::::::::::::::::: + +Gibt an, ob die API für beliebte Wörter aktiviert werden soll. + +CSV-Dateikodierung +::::::::::::::::::: + +Geben Sie die Kodierung für heruntergeladene CSV-Dateien an. + +Suchparameter anhängen +:::::::::::::::::::::: + +Aktivieren Sie dies, wenn Sie Parameter an die Suchergebnisanzeige übergeben möchten. + +Suchdatei-Proxy +::::::::::::::: + +Gibt an, ob der Datei-Proxy für Suchergebnisse aktiviert werden soll. + +Browser-Gebietsschema verwenden +:::::::::::::::::::::::::::::::: + +Gibt an, ob das Browser-Gebietsschema für die Suche verwendet werden soll. + +SSO-Typ +::::::: + +Gibt den Typ der Einmalanmeldung (Single Sign-On) an. + +- **Keine**: SSO nicht verwenden +- **OpenID Connect**: OpenID Connect verwenden (erfordert das Plugin ``fess-sso-oidc``) +- **SAML**: SAML verwenden (erfordert das Plugin ``fess-sso-saml``) +- **SPNEGO**: SPNEGO verwenden (erfordert das Plugin ``fess-sso-spnego``) +- **Entra ID**: Microsoft Entra ID verwenden (erfordert das Plugin ``fess-sso-entraid``) + +Crawler +------- + +|image1| + +Letzte Änderung prüfen +:::::::::::::::::::::: + +Aktivieren Sie dies für differenzielles Crawling. + +Bei HTTP/HTTPS-URLs wird, wenn der ``Last-Modified``-Wert der HEAD-Antwort keine Entscheidung +erlaubt (kein Änderungsdatum im Index, kein ``Last-Modified`` in der HEAD-Antwort oder ein anderer +Status als 200/404), der GET als bedingter GET mit ``If-None-Match`` (dem indexierten ``ETag``) +und/oder ``If-Modified-Since`` gesendet. Eine mit ``304 Not Modified`` beantwortete Seite wird wie +eine unveränderte Seite behandelt und nicht erneut abgerufen. Um alles erneut abzurufen, etwa nach +einer Änderung der Crawl-Einstellungen, deaktivieren Sie diese Einstellung für einen Crawl. + +Gleichzeitige Crawler-Konfiguration +::::::::::::::::::::::::::::::::::::: + +Geben Sie die Anzahl der gleichzeitig auszuführenden Crawl-Konfigurationen an. + +Benutzer-Agent +:::::::::::::: + +Geben Sie den Benutzer-Agent-Namen an, der vom Crawler verwendet wird. + +Alte Dokumente löschen +:::::::::::::::::::::: + +Geben Sie die Gültigkeitsdauer von Dokumenten in Tagen an. Ein Dokument, das bei einem Crawl registriert oder aktualisiert wird, läuft diese Anzahl von Tagen nach dem Beginn des Crawls ab; wird ein Dokument beim nächsten Crawl erneut gefunden, verlängert sich seine Gültigkeit. Der Doc-Purger-Job des Schedulers (standardmäßig jede Minute ausgeführt) löscht abgelaufene Dokumente aus dem Index. + +Der Standardwert ist ``3``; zulässig sind Werte von ``-1`` bis ``1000``. Bei ``-1`` wird für Dokumente, die bei späteren Crawls registriert oder aktualisiert werden, kein Ablaufdatum gesetzt (ein bereits gesetztes Ablaufdatum wird nicht verlängert). + +Fehlertypen ignorieren +:::::::::::::::::::::: + +Fehler-URLs, die den Schwellenwert überschreiten, werden vom Crawlen ausgeschlossen, aber hier angegebene Ausnahmenamen werden auch dann gecrawlt, wenn sie den Schwellenwert überschreiten. + +Fehleranzahlschwelle +:::::::::::::::::::: + +Wenn ein zu crawlendes Dokument mehr als die hier angegebene Anzahl in Fehler-URLs aufgezeichnet wurde, wird es beim nächsten Crawl ausgeschlossen. + +Protokollierung +--------------- + +Suchprotokoll +::::::::::::: + +Gibt an, ob die Suchprotokollierung aktiviert werden soll. + +Benutzerprotokoll +::::::::::::::::: + +Gibt an, ob die Benutzerprotokollierung aktiviert werden soll. + +Favoritenprotokoll +:::::::::::::::::: + +Gibt an, ob die Favoritenprotokollierung aktiviert werden soll. + +Alte Suchprotokolle löschen +::::::::::::::::::::::::::: + +Löscht Suchprotokolle, die älter als die angegebene Anzahl von Tagen sind. Der Standardwert ist ``-1``; bei ``-1`` werden die Protokolle nicht gelöscht, sondern unbegrenzt aufbewahrt. +Klickprotokolle, Favoritenprotokolle und Chat-Protokolle werden nach derselben Anzahl von Tagen gelöscht. + +Alte Jobprotokolle löschen +:::::::::::::::::::::::::: + +Löscht Jobprotokolle, die älter als die angegebene Anzahl von Tagen sind. Der Standardwert ist ``-1``; bei ``-1`` werden sie nicht gelöscht. + +Alte Benutzerprotokolle löschen +::::::::::::::::::::::::::::::: + +Löscht Benutzerprotokolle, die älter als die angegebene Anzahl von Tagen sind. Der Standardwert ist ``-1``; bei ``-1`` werden sie nicht gelöscht. + +Bot-Namen zum Löschen von Protokollen +:::::::::::::::::::::::::::::::::::::: + +Geben Sie Bot-Namen an, die aus Suchprotokollen ausgeschlossen werden sollen. + +Protokollebene +:::::::::::::: + +Geben Sie die Protokollebene für fess.log an. + +Vorschlagen +----------- + +Vorschläge aus Suchbegriffen +:::::::::::::::::::::::::::: + +Gibt an, ob Vorschlagskandidaten aus Suchprotokollen generiert werden sollen. + +Vorschläge aus Dokumenten +::::::::::::::::::::::::: + +Gibt an, ob Vorschlagskandidaten aus indizierten Dokumenten generiert werden sollen. + +Alte Vorschlagsinformationen löschen +::::::::::::::::::::::::::::::::::::: + +Löscht Vorschlagsdaten, die älter als die angegebene Anzahl von Tagen sind. + +LDAP +---- + +|image2| + +LDAP-URL +:::::::: + +Geben Sie die URL des LDAP-Servers an. + +Basis-DN +:::::::: + +Geben Sie den Basis-Distinguished-Name für die Anmeldung am Suchbildschirm an. + +Bind-DN +::::::: + +Geben Sie den Bind-DN des Administrators an. + +Passwort +:::::::: + +Geben Sie das Passwort für den Bind-DN an. + +Benutzer-DN +::::::::::: + +Geben Sie den Distinguished-Name des Benutzers an. + +Kontofilter +::::::::::: + +Geben Sie den Common Name oder die UID des Benutzers an. + +Gruppenfilter +::::::::::::: + +Geben Sie die Filterbedingung für abzurufende Gruppen an. + +memberOf-Attribut +::::::::::::::::: + +Geben Sie den memberOf-Attributnamen an, der auf dem LDAP-Server verfügbar ist. +Für Active Directory ist es memberOf. +Für andere LDAP-Server kann es isMemberOf sein. + +Sicherheitsauthentifizierung +:::::::::::::::::::::::::::: + +Gibt die LDAP-Sicherheitsauthentifizierungsmethode an (z.B. simple). + +Initiale Kontextfabrik +:::::::::::::::::::::: + +Gibt die LDAP-Klasse der initialen Kontextfabrik an (z.B. com.sun.jndi.ldap.LdapCtxFactory). + +OpenID Connect +-------------- + +|image3| + +Client-ID +::::::::: + +Gibt die Client-ID des OpenID Connect-Anbieters an. + +Client-Geheimnis +:::::::::::::::: + +Gibt das Client-Geheimnis des OpenID Connect-Anbieters an. + +Autorisierungsserver-URL +:::::::::::::::::::::::: + +Gibt die URL des Autorisierungsservers für OpenID Connect an. + +Token-Server-URL +:::::::::::::::: + +Gibt die URL des Token-Servers für OpenID Connect an. + +Weiterleitungs-URL +:::::::::::::::::: + +Gibt die Weiterleitungs-URL für OpenID Connect an. + +Geltungsbereich +::::::::::::::: + +Gibt den Geltungsbereich für OpenID Connect an. + +Basis-URL +::::::::: + +Gibt die Basis-URL für OpenID Connect an. + +Standardgruppen +::::::::::::::: + +Gibt die Standardgruppen an, die Benutzern bei der OpenID Connect-Authentifizierung zugewiesen werden. + +Standardrollen +:::::::::::::: + +Gibt die Standardrollen an, die Benutzern bei der OpenID Connect-Authentifizierung zugewiesen werden. + +SAML +---- + +|image4| + +IdP-Entitäts-ID +::::::::::::::: + +Gibt die Entitäts-ID des IdP (Identity Provider) an. + +IdP SSO URL +::::::::::: + +Gibt die Single Sign-On-Dienst-URL des IdP an. + +IdP SLO URL +::::::::::: + +Gibt die Single Logout-Dienst-URL des IdP an. + +IdP X.509-Zertifikat +:::::::::::::::::::: + +Gibt das öffentliche X.509-Schlüsselzertifikat für die SAML-Assertion-Signaturverifizierung des IdP an. +Geben Sie nur den Base64-kodierten Inhalt ohne ``-----BEGIN CERTIFICATE-----`` und ``-----END CERTIFICATE-----`` Zeilen an. + +SP-Basis-URL +:::::::::::: + +Gibt die Basis-URL des SAML Service Providers an. + +SP-Entitäts-ID +:::::::::::::: + +Gibt die Entitäts-ID des SP (Service Provider) an. +Wird automatisch konfiguriert, wenn ``SP-Basis-URL`` gesetzt ist. + +SP ACS URL +:::::::::: + +Gibt die Assertion Consumer Service (ACS) URL an, die SAML-Assertions empfängt. +Wird automatisch konfiguriert, wenn ``SP-Basis-URL`` gesetzt ist. + +SP SLO URL +:::::::::: + +Gibt die Single Logout-Dienst-URL des SP an. +Wird automatisch konfiguriert, wenn ``SP-Basis-URL`` gesetzt ist. + +SP NameID-Format +:::::::::::::::: + +Gibt das NameID-Format an, das in SAML-Assertions verwendet wird. + +Gruppenattributname +::::::::::::::::::: + +Gibt den Attributnamen zum Abrufen von Gruppen aus der SAML-Antwort an. + +Rollenattributname +:::::::::::::::::: + +Gibt den Attributnamen zum Abrufen von Rollen aus der SAML-Antwort an. + +Standardgruppen +::::::::::::::: + +Gibt die Standardgruppen an, die Benutzern bei der SAML-Authentifizierung zugewiesen werden. + +Standardrollen +:::::::::::::: + +Gibt die Standardrollen an, die Benutzern bei der SAML-Authentifizierung zugewiesen werden. + +SPNEGO +------ + +|image5| + +.. note:: + SPNEGO-bezogene Einstellungen werden prozessweit innerhalb der zugrunde liegenden Bibliothek gemeinsam genutzt. Damit Änderungen daran wirksam werden, ist ein Neustart von |Fess| erforderlich. + +Krb5-Konfiguration +:::::::::::::::::: + +Gibt den Pfad zur Kerberos 5-Konfigurationsdatei an. + +Anmeldekonfiguration +:::::::::::::::::::: + +Gibt den Pfad zur JAAS-Anmeldekonfigurationsdatei (Java Authentication and Authorization Service) an. + +Anmelde-Client-Modul +:::::::::::::::::::: + +Gibt den Namen des JAAS-Client-Anmeldemoduls an. + +Anmelde-Server-Modul +:::::::::::::::::::: + +Gibt den Namen des JAAS-Server-Anmeldemoduls an. + +Vorab-Authentifizierung Benutzername +:::::::::::::::::::::::::::::::::::: + +Gibt den Benutzernamen für die SPNEGO-Vorab-Authentifizierung an. +Werden Benutzername und Passwort leer gelassen, wird die keytab-basierte Serveranmeldung verwendet. + +Vorab-Authentifizierung Passwort +:::::::::::::::::::::::::::::::: + +Gibt das Passwort für die SPNEGO-Vorab-Authentifizierung an. + +Basic-Authentifizierung erlauben +:::::::::::::::::::::::::::::::: + +Gibt an, ob Basic-Authentifizierung als Fallback erlaubt werden soll. + +Unsichere Basic-Authentifizierung erlauben +:::::::::::::::::::::::::::::::::::::::::: + +Gibt an, ob Basic-Authentifizierung über unsichere (HTTP) Verbindungen erlaubt werden soll. +Dies ist standardmäßig deaktiviert, damit Anmeldedaten nicht im Klartext übertragen werden (über HTTPS-Verbindungen wird Basic-Authentifizierung weiterhin angeboten). + +NTLM-Aufforderung +:::::::::::::::::: + +Gibt an, ob die NTLM-Aufforderung aktiviert werden soll. + +Localhost erlauben +:::::::::::::::::: + +Gibt an, ob der Zugriff vom Localhost erlaubt werden soll. +Dies ist aus Sicherheitsgründen standardmäßig deaktiviert, da bei Aktivierung Anfragen vom selben Host ohne Kerberos-Prüfung als Server-Betriebssystembenutzer authentifiziert werden. + +Delegation erlauben +::::::::::::::::::: + +Gibt an, ob Kerberos-Delegation erlaubt werden soll. + +Logger-Ebene +:::::::::::: + +Gibt die Protokollausgabeebene für die SPNEGO-Authentifizierung als numerischen Wert von 0 bis 7 an. +Wird das Feld leer gelassen oder ein nicht-numerischer Wert angegeben, wird die Protokollebene automatisch ermittelt. + +Entra ID +-------- + +|image6| + +Mandant (ID oder Domäne) +:::::::::::::::::::::::: + +Gibt die Mandanten-ID oder Domäne für Microsoft Entra ID an. + +Autorität +::::::::: + +Gibt die Autoritäts-URL für Microsoft Entra ID an. + +Client-ID +::::::::: + +Gibt die Anwendungs-(Client-)ID für Microsoft Entra ID an. + +Client-Geheimnis +:::::::::::::::: + +Gibt das Client-Geheimnis für Microsoft Entra ID an. + +Antwort-URL +::::::::::: + +Gibt die Antwort-(Weiterleitungs-)URL für Microsoft Entra ID an. + +Status-TTL +:::::::::: + +Gibt die Gültigkeitsdauer (TTL) des Authentifizierungsstatus an. + +Berechtigungsfelder +::::::::::::::::::: + +Gibt die Felder an, aus denen Berechtigungsinformationen von Entra ID abgerufen werden. + +Standardgruppen +::::::::::::::: + +Gibt die Standardgruppen an, die Benutzern bei der Entra ID-Authentifizierung zugewiesen werden. + +Standardrollen +:::::::::::::: + +Gibt die Standardrollen an, die Benutzern bei der Entra ID-Authentifizierung zugewiesen werden. + +Domänendienst verwenden +::::::::::::::::::::::: + +Gibt an, ob der Entra ID-Domänendienst verwendet werden soll. + +Hinweis +------- + +|image7| + +.. note:: + + Die Hinweise akzeptieren HTML. Wenn ein Such-Theme einen Hinweis anzeigt, bleiben nur die Tags und Attribute einer Zulassungsliste erhalten: Die Elemente `` + + + +Falls Ihre Website bereits jQuery verwendet, müssen Sie das jQuery-script-Element nicht hinzufügen. + +Die Vorschlagsfunktion verwendet die Vorschlags-API von |Fess| (``/api/v2/suggest-words``). +Ändern Sie ``url`` entsprechend der URL Ihres aufgebauten |Fess|-Servers. + +Die wichtigsten Optionen, die für ``suggestor`` angegeben werden können, sind die folgenden. + +.. list-table:: Wichtigste suggestor-Optionen + :header-rows: 1 + :widths: 25 75 + + * - Option + - Beschreibung + * - ``ajaxinfo.url`` + - Die URL der Vorschlags-API. Geben Sie ``/api/v2/suggest-words`` Ihres |Fess|-Servers an. + * - ``ajaxinfo.fn`` + - Ein Array von Feldnamen, aus denen Vorschläge bezogen werden. Sie können den Standardwert ``["_default", "content", "title"]`` unverändert verwenden. + * - ``ajaxinfo.num`` + - Die maximale Anzahl der angezeigten Vorschlagskandidaten. + * - ``ajaxinfo.lang`` + - Die Sprache zum Eingrenzen der Vorschlagskandidaten (optional). + * - ``minterm`` + - Die minimale Anzahl von Eingabezeichen, bevor Vorschläge angefordert werden. + * - ``adjustWidthVal`` + - Der Wert (in Pixeln), der zur Breite des Eingabefelds addiert wird, um die Breite des Vorschlagsbereichs anzupassen. + * - ``searchForm`` + - Das Suchformular-Element, das gesendet wird, wenn ein Kandidat ausgewählt wird. + * - ``boxCssInfo`` + - Das auf den Vorschlagsbereich angewendete CSS. + * - ``listSelectedCssInfo`` + - Das auf den ausgewählten Kandidaten angewendete CSS (optional). + * - ``listDeselectedCssInfo`` + - Das auf nicht ausgewählte Kandidaten angewendete CSS (optional). + +Geben Sie für "z-index" einen Wert an, der sich nicht mit anderen Elementen überschneidet. + +.. note:: + Wenn das Suchformular auf einer Seite platziert wird, deren Domain sich vom |Fess|-Server unterscheidet, wird die Anfrage an die Vorschlags-API zu einer Cross-Origin-Anfrage. + |Fess| erlaubt standardmäßig alle Ursprünge (``api.cors.allow.origin=*``), sodass es ohne Anpassung funktioniert. + Um den Zugriff einzuschränken, ändern Sie ``api.cors.allow.origin`` in ``fess_config.properties``. + +.. note:: + ``/api/v2/suggest-words`` ist die von |Fess| selbst bereitgestellte API. + Der in früheren Versionen verwendete Endpunkt ``/api/v1/suggest-words`` wird vom |Fess|-Kern nicht mehr bereitgestellt, und das Plugin ``fess-webapp-v1-api`` muss installiert werden, um ihn zu verwenden. + Verwenden Sie für neue Installationen ``/api/v2/suggest-words``. diff --git a/de/15.10/config/search-geosearch.rst b/de/15.10/config/search-geosearch.rst new file mode 100644 index 000000000..65a2ae4d3 --- /dev/null +++ b/de/15.10/config/search-geosearch.rst @@ -0,0 +1,359 @@ +============= +Standortsuche +============= + +========= +Übersicht +========= + +|Fess| kann geografische Bereichssuchen für Dokumente mit Breiten- und Längengraden durchführen. +Mit dieser Funktion können Sie Dokumente innerhalb einer bestimmten Entfernung von einem bestimmten Punkt suchen +oder Suchsysteme in Verbindung mit Kartendiensten wie Google Maps aufbauen. + +Intern wird die geo-distance-Abfrage von OpenSearch verwendet, um Dokumente zu filtern, +die innerhalb einer angegebenen Entfernung vom angegebenen Mittelpunkt liegen. + +=============== +Anwendungsfälle +=============== + +Standortsuche kann für folgende Zwecke genutzt werden: + +- Geschäftssuche: Suche nach Geschäften in der Nähe des aktuellen Standorts des Benutzers +- Immobiliensuche: Suche nach Immobilien innerhalb einer bestimmten Entfernung von einem Bahnhof oder einer Einrichtung +- Veranstaltungssuche: Suche nach Veranstaltungsinformationen in der Umgebung eines bestimmten Ortes +- Einrichtungssuche: Suche nach Sehenswürdigkeiten oder öffentlichen Einrichtungen in der Nähe + +============= +Konfiguration +============= + +Konfiguration bei der Indexgenerierung +--------------------------------------- + +Definition des Standortfeldes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In |Fess| ist ``location`` als Standardfeld für Standortinformationen definiert. +Dieses Feld ist als OpenSearch-Typ ``geo_point`` konfiguriert. + +Registrierungsformat für Standortinformationen +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Bei der Indexgenerierung werden Breiten- und Längengrad durch Komma getrennt im ``location``-Feld festgelegt. + +**Format:** + +:: + + Breitengrad,Längengrad + +**Beispiel:** + +:: + + 45.17614,-93.87341 + +.. note:: + Breitengrad wird im Bereich von -90 bis 90, Längengrad im Bereich von -180 bis 180 angegeben. + +Konfigurationsbeispiel für Datenspeicher-Crawling +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Bei Verwendung von Datenspeicher-Crawling werden Breiten- und Längengrade +aus einer Datenquelle mit Standortinformationen im ``location``-Feld festgelegt. + +**Beispiel: Abruf aus Datenbank** + +Wenn Breiten- und Längengrad in getrennten Spalten gespeichert sind, verbinden Sie diese per SQL zu einer kommaseparierten Zeichenfolge. +Die Parameter des Datenspeichers enthalten pro Zeile einen Eintrag. Schreiben Sie daher das SQL nach ``sql=`` in einer einzigen Zeile +(wenn Sie es auf mehrere Zeilen verteilen, wird nur das ``SELECT`` der ersten Zeile als SQL behandelt und es tritt ein Syntaxfehler auf). + +:: + + sql=SELECT id, name, address, CONCAT(latitude, ',', longitude) AS location FROM stores + +Im Konfigurationsskript des Datenspeichers ordnen Sie den abgerufenen Wert dem ``location``-Feld zu. +Beim Datenbank-Datenspeicher werden die Spaltennamen des SQL (einschließlich mit ``AS`` vergebener Aliase) direkt zu den Variablennamen im Skript. +Ein Präfix wie ``data.`` wird nicht vorangestellt. + +:: + + location=location + +Hinzufügen von Standortinformationen per Skript +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sie können Standortinformationen auch dynamisch zu Dokumenten hinzufügen, indem Sie die Skriptfunktion der Crawl-Konfiguration verwenden (standardmäßig JavaScript; Groovy kann ebenfalls ausgewählt werden). +Weisen Sie den Wert direkt dem Feldnamen zu. + +:: + + // Breiten- und Längengrad im location-Feld festlegen + location="35.681236,139.767125" + +Weitere Details zu Skripten finden Sie unter :doc:`scripting-overview`. + +Konfiguration bei der Suche +---------------------------- + +Für die Standortsuche geben Sie Mittelpunkt und Suchradius über Request-Parameter an. + +Request-Parameter +~~~~~~~~~~~~~~~~~ + +Der Parametername für die Standortsuche hat das Format ``geo..point`` und ``geo..distance``. +Für ```` wird der in ``query.geo.fields`` konfigurierte Feldname eingesetzt +(Standardwert: ``location``). + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Parametername + - Beschreibung + * - ``geo.location.point`` + - Breiten-/Längengrad des Suchmittelpunkts (durch Komma getrennt. Beispiel: ``35.681236,139.767125`` ) + * - ``geo.location.distance`` + - Suchradius vom Mittelpunkt (mit Einheit. Beispiel: ``10km`` ) + +.. note:: + ``point`` und ``distance`` müssen immer zusammen angegeben werden. Ein ``point`` ohne ``distance`` wird ignoriert. + Außerdem muss der Wert von ``point`` aus genau zwei numerischen Werten (Breiten- und Längengrad) bestehen; + bei ungültigem Format tritt ein Fehler auf. + +.. note:: + Die Standortsuche arbeitet als Einschränkung der Suchanfrage ``q``. Ist ``q`` leer, wird die Suche selbst nicht ausgeführt + und das Ergebnis enthält 0 Treffer. Geben Sie bei Anfragen für die Standortsuche daher einen Suchbegriff an. + +.. note:: + Werden für dasselbe Feld mehrere ``point``-Werte angegeben, gelten diese als ODER-Bedingung (innerhalb eines der Bereiche). + Werden Werte für mehrere Felder angegeben, gelten diese als UND-Bedingung (innerhalb aller Bereiche). + +Entfernungseinheiten +~~~~~~~~~~~~~~~~~~~~ + +Für Entfernungen können folgende Einheiten verwendet werden: + +- ``km``: Kilometer +- ``m``: Meter +- ``mi``: Meilen +- ``yd``: Yards + +.. note:: + Da der Entfernungswert direkt an OpenSearch übergeben wird, können neben den oben genannten Einheiten + auch alle anderen von OpenSearch unterstützten Einheiten verwendet werden + ( ``cm`` , ``mm`` , ``ft`` , ``in`` , ``nmi`` usw.). + +Reihenfolge der Suchergebnisse +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Die Standortsuche wirkt als **Filter**, der die Ergebnisse auf Dokumente innerhalb des angegebenen Bereichs einschränkt. +Sie hat keinen Einfluss auf den Suchscore (Relevanz) und sortiert die Ergebnisse nicht nach der Entfernung vom Mittelpunkt. +Die Ergebnisse werden wie gewohnt nach Relevanz (oder der mit dem ``sort``-Parameter angegebenen Reihenfolge) zurückgegeben. + +.. note:: + |Fess| unterstützt keine Sortierung nach Entfernung (Sortierung nach Nähe). + Wenn Sie Ergebnisse nach Entfernung sortiert anzeigen möchten, verwenden Sie die im Response enthaltenen Koordinaten und sortieren Sie clientseitig. + +============= +Suchbeispiele +============= + +Grundlegende Suche +------------------ + +Suche nach Dokumenten innerhalb eines Radius von 10 km vom Bahnhof Tokyo (35.681236, 139.767125): + +:: + + http://localhost:8080/search?q=Suchschlüsselwort&geo.location.point=35.681236,139.767125&geo.location.distance=10km + +Suche in der Nähe des aktuellen Standorts +------------------------------------------ + +Suche innerhalb von 1 km vom aktuellen Standort des Benutzers: + +:: + + http://localhost:8080/search?q=Ramen&geo.location.point=35.681236,139.767125&geo.location.distance=1km + +Verwendung in der API +--------------------- + +Die Standortsuche kann auch über die JSON-Suche-API v2 ( ``/api/v2/search`` ) verwendet werden. +Geben Sie ``geo.location.point`` und ``geo.location.distance`` als Request-Parameter an. + +:: + + curl "http://localhost:8080/api/v2/search?q=Hotel&geo.location.point=35.681236,139.767125&geo.location.distance=5km" + +Die Suchergebnisse werden im ``response.data``-Array des gemeinsamen Envelopes zurückgegeben. Weitere Details zur API finden Sie unter :doc:`../api/api-search` +und :doc:`../api/api-overview`. + +.. note:: + Das ``location``-Feld ist standardmäßig nicht in der API-Antwort enthalten. Um Breiten- und Längengrad in den Suchergebnissen einzuschließen, + fügen Sie die folgenden beiden Einstellungen in ``fess_config.properties`` hinzu und starten Sie |Fess| neu. + ``query.additional.response.fields`` fügt Felder hinzu, die von der Suchmaschine abgerufen werden, + und ``query.additional.api.response.fields`` erlaubt die Ausgabe von Feldern in der API-Antwort. + Mit nur einer der beiden Einstellungen ist ``location`` nicht in der Antwort enthalten. + + :: + + query.additional.response.fields=location + query.additional.api.response.fields=location + +======================= +Anpassung von Feldnamen +======================= + +Änderung des Standard-Feldnamens +--------------------------------- + +Um den für die Standortsuche verwendeten Feldnamen zu ändern, +passen Sie folgende Einstellung in ``fess_config.properties`` an: + +:: + + query.geo.fields=location + +Zur Angabe mehrerer Feldnamen trennen Sie diese durch Kommas. + +:: + + query.geo.fields=location,geo_point,coordinates + +.. note:: + - Der Name des Request-Parameters richtet sich nach dem konfigurierten Feldnamen. Bei der Einstellung + ``query.geo.fields=coordinates`` werden beispielsweise ``geo.coordinates.point`` und + ``geo.coordinates.distance`` verwendet. + - Jedes hier angegebene Feld muss im Index-Mapping als ``geo_point``-Typ definiert sein. + +========================= +Implementierungsbeispiele +========================= + +Implementierung in einer Webanwendung +-------------------------------------- + +Beispiel für die Suche mit JavaScript unter Abruf des aktuellen Standorts: + +.. code-block:: javascript + + // Aktuellen Standort mit der Browser-Geolocation-API abrufen + navigator.geolocation.getCurrentPosition(function(position) { + const latitude = position.coords.latitude; + const longitude = position.coords.longitude; + const distance = "5km"; + + // Such-URL erstellen (der Suchbegriff q darf nicht fehlen) + const searchUrl = `/search?q=${encodeURIComponent('Geschäfte')}&geo.location.point=${latitude},${longitude}&geo.location.distance=${distance}`; + + // Suche ausführen + window.location.href = searchUrl; + }); + +Integration mit Google Maps +---------------------------- + +Beispiel für die Anzeige von Suchergebnissen als Marker auf Google Maps: + +.. note:: + Dieses Beispiel greift auf das ``location``-Feld aus den Suchergebnissen zu. Setzen Sie zuvor + ``query.additional.response.fields=location`` und ``query.additional.api.response.fields=location``, + um die Koordinaten in der Antwort einzuschließen. + +.. code-block:: javascript + + // Karte initialisieren + const map = new google.maps.Map(document.getElementById('map'), { + center: {lat: 35.681236, lng: 139.767125}, + zoom: 13 + }); + + // Standortsuche mit der Fess v2-Suche-API ausführen + fetch('/api/v2/search?q=Geschäfte&geo.location.point=35.681236,139.767125&geo.location.distance=5km') + .then(response => response.json()) + .then(json => { + // Suchergebnisse (response.data-Array) als Marker anzeigen + json.response.data.forEach(doc => { + if (doc.location) { + const [lat, lng] = doc.location.split(',').map(Number); + new google.maps.Marker({ + position: {lat: lat, lng: lng}, + map: map, + title: doc.title + }); + } + }); + }); + +==================== +Leistungsoptimierung +==================== + +Überprüfung der Indexeinstellungen +------------------------------------ + +Das Standortfeld ist in der Installationsumgebung unter +``app/WEB-INF/classes/fess_indices/fess/doc.json`` als ``geo_point``-Typ definiert. + +:: + + "location": { + "type": "geo_point" + } + +Da Felder vom Typ ``geo_point`` im BKD-Baum indexiert werden, werden geo-distance-Abfragen effizient ausgeführt. + +Optimierung von Suchbereich und Antwort +----------------------------------------- + +Ein größerer Suchradius erhöht die Anzahl der übereinstimmenden Dokumente, was das Abrufen und Rendern der Ergebnisse verlangsamen kann. + +- Legen Sie je nach Verwendungszweck einen angemessenen Suchradius fest. +- Wenn viele Ergebnisse für die Kartenanzeige verarbeitet werden, begrenzen Sie die Anzahl der abgerufenen Einträge durch Anpassen der Seitengröße (``num``-Parameter). + +============== +Fehlerbehebung +============== + +Standortsuche funktioniert nicht +---------------------------------- + +1. Überprüfen Sie, ob Daten korrekt im ``location``-Feld gespeichert sind. +2. Überprüfen Sie, ob das Format für Breiten-/Längengrad korrekt ist (durch Komma getrennt: ``Breitengrad,Längengrad``; bei nicht genau zwei Werten tritt ein Fehler auf). +3. Überprüfen Sie, ob ``location`` im OpenSearch-Index-Mapping als ``geo_point``-Typ definiert ist. +4. Überprüfen Sie, ob sowohl ``point`` als auch ``distance`` angegeben sind (ein ``point`` ohne ``distance`` wird ignoriert). + +Keine Suchergebnisse zurückgegeben +------------------------------------ + +1. Überprüfen Sie, ob Dokumente innerhalb der angegebenen Entfernung existieren. +2. Überprüfen Sie, ob die Breiten-/Längengradwerte im korrekten Bereich liegen (Breitengrad: -90 bis 90, Längengrad: -180 bis 180). +3. Überprüfen Sie, ob die Entfernungseinheit korrekt angegeben ist. + +API-Antwort enthält keine Standortinformationen +------------------------------------------------ + +Das ``location``-Feld ist standardmäßig nicht in der API-Antwort enthalten. +Um Koordinaten in die Suchergebnisse aufzunehmen, setzen Sie +sowohl ``query.additional.response.fields=location`` als auch ``query.additional.api.response.fields=location`` +in ``fess_config.properties`` und starten Sie |Fess| neu. + +Standortinformationen werden nicht korrekt gespeichert +------------------------------------------------------- + +1. Überprüfen Sie, ob das ``location``-Feld beim Crawling korrekt gesetzt wird. +2. Überprüfen Sie, ob Breiten-/Längengrad aus der Datenquelle korrekt abgerufen werden. +3. Wenn Standortinformationen per Skript gesetzt werden, überprüfen Sie, ob das Zeichenfolgenformat ``Breitengrad,Längengrad`` korrekt ist. + +===================== +Referenzinformationen +===================== + +Weitere Details zur Standortsuche finden Sie in folgenden Ressourcen: + +- `OpenSearch Geo Queries `_ +- `OpenSearch Geo Point `_ +- `Geolocation API (MDN) `_ diff --git a/de/15.10/config/search-scroll.rst b/de/15.10/config/search-scroll.rst new file mode 100644 index 000000000..3179dcd47 --- /dev/null +++ b/de/15.10/config/search-scroll.rst @@ -0,0 +1,469 @@ +================================ +Massen-Abruf von Suchergebnissen +================================ + +Übersicht +========= + +Bei der normalen Suche in |Fess| wird durch die Paging-Funktion nur eine bestimmte Anzahl von +Suchergebnissen angezeigt. +Wenn Sie alle Suchergebnisse auf einmal abrufen möchten, verwenden Sie die Scroll-Search-Funktion +(Scroll-Suche). + +Diese Funktion ist nützlich, wenn alle Suchergebnisse verarbeitet werden müssen, +z. B. für den Massen-Datenexport, Backup oder die Analyse großer Datenmengen. + +Anwendungsfälle +=============== + +Scroll-Suche eignet sich für folgende Zwecke: + +- Vollständiger Export von Suchergebnissen +- Abruf großer Datenmengen für die Datenanalyse +- Datenabruf in der Batch-Verarbeitung +- Datensynchronisation mit externen Systemen +- Datenerfassung für die Berichtsgenerierung + +.. warning:: + Scroll-Suche gibt große Datenmengen zurück und verbraucht daher im Vergleich zur normalen + Suche mehr Serverressourcen. Aktivieren Sie diese Funktion nur bei Bedarf. + +Konfiguration +============= + +Aktivierung der Scroll-Suche +----------------------------- + +Standardmäßig ist die Scroll-Suche aus Sicherheits- und Leistungsgründen deaktiviert. +Zur Aktivierung ändern Sie folgende Einstellung in +``app/WEB-INF/classes/fess_config.properties`` (bei RPM/DEB-Paketen in +``/etc/fess/fess_config.properties``): + +:: + + api.search.scroll=true + +.. note:: + Nach einer Konfigurationsänderung muss |Fess| neu gestartet werden. + +Gültigkeitsdauer des Scroll-Kontexts +-------------------------------------- + +Die Gültigkeitsdauer des Scroll-Kontexts ist in |Fess| intern auf ``1m`` (1 Minute) festgelegt. +Dieser Wert kann über ``fess_config.properties`` nicht geändert werden. + +.. note:: + Die Einstellung ``index.scroll.search.timeout`` ist vorhanden, wird jedoch für interne + Operationen (update by query / delete by query) verwendet, die mit Indexaktualisierungen oder + -löschungen verbunden sind. Sie hat keinen Einfluss auf den Timeout dieser Funktion + (Scroll-Suche). + +Konfiguration der Response-Felder +----------------------------------- + +Sie können die Felder anpassen, die in den Suchergebnissen enthalten sind. +Standardmäßig werden zahlreiche Felder zurückgegeben; Sie können jedoch zusätzliche Felder +angeben. + +:: + + query.additional.scroll.response.fields=content + query.additional.api.response.fields=content + +Mehrere Felder werden durch Komma getrennt aufgelistet. + +.. note:: + Das Feld ``content`` ist standardmäßig nicht in den Response-Feldern enthalten. Um den + vollständigen Text abzurufen, sind beide obigen Einstellungen erforderlich. + ``query.additional.scroll.response.fields`` fügt das Feld zu den aus dem Index abgerufenen Feldern + hinzu, ``query.additional.api.response.fields`` zu den Feldern, die die API ausgeben darf. Mit nur + einer der beiden Einstellungen wird ``content`` nicht ausgegeben. + +Verwendung +========== + +Grundlegende Verwendung +------------------------ + +Der Zugriff auf die Scroll-Suche erfolgt über folgende URL: + +:: + + http://localhost:8080/api/v2/documents/all?q=Suchbegriff + +Die Suchergebnisse werden im NDJSON-Format (Newline Delimited JSON) zurückgegeben. +Pro Zeile wird ein Dokument im JSON-Format ausgegeben. + +**Beispiel:** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=Fess" + +Request-Parameter +------------------ + +Für die Scroll-Suche können folgende Parameter verwendet werden: + +.. note:: + Die Scroll-Suche unterstützt nur die GET-Methode. Bei zustandsändernden Methoden wie ``POST`` + wird zuerst das CSRF-Token geprüft; eine Anfrage ohne gültigen ``X-Fess-CSRF-Token``-Header + erhält daher ``403 Forbidden`` (``forbidden``), siehe :doc:`../api/api-overview`. + Mit einem gültigen Token wird ``405 Method Not Allowed`` (``method_not_allowed``) zurückgegeben. + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Parametername + - Beschreibung + * - ``q`` + - Suchabfrage (erforderlich) + * - ``num`` + - Anzahl der Treffer pro Scroll-Abruf (Standard: 10, Maximum: 100) + * - ``fields.label`` + - Filterung nach Label + +.. note:: + Der maximale Wert von ``num`` wird durch ``paging.search.page.max.size`` (Standard: 100) + gesteuert. Wird ein Wert angegeben, der das Maximum überschreitet, wird er automatisch auf + den Maximalwert begrenzt. Als Standardwert wird ``paging.search.page.size`` (Standard: 10) + verwendet. Wird für ``num`` ein Wert von 0 oder kleiner angegeben, wird ein Fehler + (``INVALID_REQUEST``) zurückgegeben. + +Angabe von Suchabfragen +------------------------ + +Sie können Suchabfragen wie bei der normalen Suche angeben. + +**Beispiel: Schlüsselwortsuche** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=Suchmaschine" + +**Beispiel: Feldspezifische Suche** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=title:Fess" + +**Beispiel: Vollständiger Abruf (ohne Suchbedingung)** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=*:*" + +Angabe der Abrufanzahl +----------------------- + +Sie können die Anzahl der Treffer pro Scroll-Abruf ändern. + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=Fess&num=100" + +.. note:: + Ein zu großer ``num``-Parameter erhöht die Speichernutzung. Der Standardmaximalwert ist 100. + Falls ein größerer Wert benötigt wird, ändern Sie die Einstellung + ``paging.search.page.max.size``. + +Filterung nach Label +--------------------- + +Sie können nur Dokumente bestimmter Labels abrufen. + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=*:*&fields.label=public" + +Zugriffskontrolle +------------------ + +.. note:: + Bei der Scroll-Suche wird wie bei der normalen Suche die rollenbasierte Zugriffskontrolle + (RBAC) angewendet. Es werden nur Dokumente zurückgegeben, auf die der anfragende Benutzer + gemäß seinen Rolleninformationen Zugriff hat. Dokumente ohne Leseberechtigung sind nicht + im Ergebnis enthalten. + +.. warning:: + Der Endpunkt der Scroll-Suche erfordert standardmäßig keine Authentifizierung (er ist für + jeden zugänglich). Die zurückgegebenen Dokumente werden jedoch durch die oben beschriebene + rollenbasierte Zugriffskontrolle gefiltert. Falls der Zugriff auf den Endpunkt selbst + eingeschränkt werden soll, konfigurieren Sie eine IP-Adressen-Beschränkung oder + Authentifizierung über einen Reverse-Proxy. + +Response-Format +=============== + +NDJSON-Format +-------------- + +Die Response der Scroll-Suche wird im NDJSON-Format (Newline Delimited JSON) zurückgegeben. +Der Content-Type ist ``application/x-ndjson; charset=UTF-8``. +Jede Zeile repräsentiert ein Dokument, das in der Form ``{"data": {...}}`` eingeschlossen ist. + +**Beispiel:** + +:: + + {"data":{"url":"http://example.com/page1","title":"Page 1","digest":"..."}} + {"data":{"url":"http://example.com/page2","title":"Page 2","digest":"..."}} + {"data":{"url":"http://example.com/page3","title":"Page 3","digest":"..."}} + +.. note:: + Jedes Dokument wird unter dem Schlüssel ``data`` gespeichert. Auf Client-Seite ist nach dem + Parsen jeder Zeile der Wert unter dem Schlüssel ``data`` zu lesen. + +Verhalten im Fehlerfall +------------------------ + +Tritt auf der Serverseite ein Fehler auf, nachdem die Übertragung des Streams begonnen hat, +wird in der letzten Zeile der Response folgende Fehler-Abschlusszeile ausgegeben: + +:: + + {"error":{"code":"internal_error","message":"stream error"}} + +.. note:: + Auf Client-Seite kann durch Prüfen, ob die letzte Zeile den Schlüssel ``error`` enthält, + unterschieden werden, ob der Stream normal abgeschlossen wurde oder ob auf der Serverseite + ein Fehler aufgetreten ist. Falls das Schreiben der Fehler-Abschlusszeile selbst fehlschlägt, + wird keine Abschlusszeile ausgegeben und der Stream endet vorzeitig. Behandeln Sie daher auch + unerwartete Verbindungsabbrüche als Fehler. + +Response-Felder +---------------- + +Standardmäßig enthaltene Felder: + +- ``score``: Suchscore +- ``_id``: Dokument-ID (OpenSearch-Dokument-ID) +- ``doc_id``: Dokument-ID (intern in |Fess|) +- ``boost``: Boost-Wert +- ``content_length``: Inhaltslänge +- ``host``: Hostname +- ``site``: Site +- ``last_modified``: Letztes Änderungsdatum +- ``timestamp``: Zeitstempel +- ``mimetype``: MIME-Typ +- ``filetype``: Dateityp +- ``filename``: Dateiname +- ``created``: Erstellungsdatum +- ``title``: Titel +- ``digest``: Textauszug +- ``url``: Dokument-URL +- ``thumbnail``: Vorschaubild +- ``click_count``: Klickanzahl +- ``favorite_count``: Favoritenanzahl +- ``has_cache``: Cache vorhanden +- ``content_title``: Anzeige-Titel +- ``content_description``: Textauszug für die Anzeige +- ``url_link``: Anzeige-Link-URL +- ``site_path``: Site-Pfad + +.. note:: + Die tatsächlich ausgegebenen Felder sind auf die für die API-Response zugelassenen Felder + beschränkt. Felder ohne Wert werden nicht ausgegeben. + +.. note:: + ``content`` (Volltext) ist standardmäßig nicht enthalten. + Er wird ausgegeben, wenn er sowohl zu ``query.additional.scroll.response.fields`` als auch zu + ``query.additional.api.response.fields`` hinzugefügt wird (siehe Konfiguration der Response-Felder). + +Datenverarbeitungsbeispiele +============================ + +Verarbeitungsbeispiel mit Python +--------------------------------- + +.. code-block:: python + + import requests + import json + + # Scroll-Suche ausführen + url = "http://localhost:8080/api/v2/documents/all" + params = { + "q": "Fess", + "num": 100 + } + + response = requests.get(url, params=params, stream=True) + + # NDJSON-Response zeilenweise verarbeiten + for line in response.iter_lines(): + if line: + record = json.loads(line) + if "error" in record: + # Fehler mitten im Stream + print("stream error:", record["error"]) + break + doc = record["data"] + print(f"Title: {doc.get('title')}") + print(f"URL: {doc.get('url')}") + print("---") + +Speichern in eine Datei +------------------------ + +Beispiel zum Speichern von Suchergebnissen in eine Datei: + +.. code-block:: bash + + curl "http://localhost:8080/api/v2/documents/all?q=*:*" > all_documents.ndjson + +Konvertierung zu CSV +--------------------- + +Beispiel für die Konvertierung zu CSV mit dem jq-Befehl: + +.. code-block:: bash + + curl "http://localhost:8080/api/v2/documents/all?q=Fess" | \ + jq -r '.data | [.url, .title, .score] | @csv' > results.csv + +Datenanalyse +------------- + +Beispiel für die Analyse abgerufener Daten: + +.. code-block:: python + + import json + import pandas as pd + + # NDJSON-Datei einlesen (data-Schlüssel aus jeder Zeile entnehmen) + documents = [] + with open('all_documents.ndjson', 'r') as f: + for line in f: + record = json.loads(line) + if "data" in record: + documents.append(record["data"]) + + # In DataFrame konvertieren + df = pd.DataFrame(documents) + + # Grundstatistik + print(f"Total documents: {len(df)}") + print(f"Average score: {df['score'].mean()}") + + # URL-Domain-Analyse + df['domain'] = df['url'].apply(lambda x: x.split('/')[2]) + print(df['domain'].value_counts()) + +Leistung und Best Practices +============================ + +Effiziente Verwendung +---------------------- + +1. **Angemessene Einstellung des num-Parameters** + + - Zu klein erhöht den Kommunikations-Overhead + - Zu groß erhöht die Speichernutzung + - Standardmaximalwert: 100 + +2. **Optimierung der Suchbedingungen** + + - Suchbedingungen so angeben, dass nur benötigte Dokumente abgerufen werden + - Vollständigen Abruf nur bei wirklichem Bedarf ausführen + +3. **Nutzung von Nebenzeiten** + + - Abruf großer Datenmengen in Zeiten niedriger Systemlast ausführen + +4. **Verwendung in der Batch-Verarbeitung** + + - Regelmäßige Datensynchronisation als Batch-Job ausführen + +Optimierung der Speichernutzung +--------------------------------- + +Bei der Verarbeitung großer Datenmengen verwenden Sie Streaming-Verarbeitung, um die +Speichernutzung zu reduzieren. + +.. code-block:: python + + import requests + import json + + url = "http://localhost:8080/api/v2/documents/all" + params = {"q": "*:*", "num": 100} + + # Mit Streaming verarbeiten + with requests.get(url, params=params, stream=True) as response: + for line in response.iter_lines(decode_unicode=True): + if line: + record = json.loads(line) + if "error" in record: + break + # Dokument verarbeiten + process_document(record["data"]) + +Sicherheitsüberlegungen +======================== + +Zugriffsbeschränkung +--------------------- + +Da die Scroll-Suche große Datenmengen zurückgibt, konfigurieren Sie angemessene +Zugriffsbeschränkungen. Da der Endpunkt selbst standardmäßig keine Authentifizierung erfordert, +erwägen Sie bei Bedarf folgende Maßnahmen: + +1. **IP-Adressen-Beschränkung** + + Zugriff nur von bestimmten IP-Adressen erlauben + +2. **API-Authentifizierung** + + API-Token oder Basic-Authentifizierung über einen Reverse-Proxy verwenden + +3. **Rollenbasierte Zugriffskontrolle** + + Die zurückgegebenen Dokumente werden durch die rollenbasierte Zugriffskontrolle von |Fess| + gefiltert + +Rate-Limiting +-------------- + +Zur Vermeidung übermäßiger Zugriffe wird empfohlen, Rate-Limiting im Reverse-Proxy zu +konfigurieren. + +Fehlerbehebung +============== + +Scroll-Suche nicht verfügbar +------------------------------ + +1. Überprüfen Sie, ob ``api.search.scroll`` auf ``true`` gesetzt ist. +2. Überprüfen Sie, ob |Fess| neu gestartet wurde. +3. Überprüfen Sie die Fehlerprotokolle. + +Timeout-Fehler tritt auf +------------------------- + +1. Verkleinern Sie den ``num``-Parameter, um die Verarbeitung zu verteilen. +2. Grenzen Sie die Suchbedingungen ein, um die abzurufende Datenmenge zu reduzieren. + +Speichermangel-Fehler +---------------------- + +1. Verkleinern Sie den ``num``-Parameter. +2. Erhöhen Sie den Heap-Speicher von |Fess|. +3. Überprüfen Sie den Heap-Speicher von OpenSearch. + +Response ist leer +------------------ + +1. Überprüfen Sie, ob die Suchabfrage korrekt ist. +2. Überprüfen Sie, ob die angegebenen Labels oder Filterbedingungen korrekt sind. +3. Aufgrund der rollenbasierten Zugriffskontrolle sind Dokumente ohne Leseberechtigung nicht + im Ergebnis enthalten. Überprüfen Sie die Rolleneinstellungen des Requests. + +Referenzinformationen +===================== + +- :doc:`search-basic` - Details zu Suchfunktionen +- :doc:`search-advanced` - Suchbezogene Konfigurationen +- `OpenSearch Scroll API `_ diff --git a/de/15.10/config/search-semantic.rst b/de/15.10/config/search-semantic.rst new file mode 100644 index 000000000..b5b3084a7 --- /dev/null +++ b/de/15.10/config/search-semantic.rst @@ -0,0 +1,989 @@ +==================================================== +Semantische Suche (Content-Chunking + Vektorsuche) +==================================================== + +Übersicht +========= + +In |Fess| 15.10 wurde die **Content-Chunking-Funktion** — die Dokumentinhalte in Chunks aufteilt +und für jeden Chunk einen Embedding-Vektor generiert und speichert — in den Kern integriert. +Die generierten Vektoren werden für zwei Zwecke verwendet: + +- **Semantische Suche**: eine hybride Suche, die Schlüsselwortsuche (BM25) und Vektorsuche über + Rank Fusion kombiniert. Dokumente, die der Anfrage semantisch nahestehen, können auch ohne + exakte Schlüsselwortübereinstimmung gefunden werden. +- **KI-Suchmodus (RAG)**: Bei der Antwortgenerierung werden nur die Chunks, die der Frage + semantisch am nächsten stehen, als Kontext für das LLM ausgewählt, was die Antwortqualität und + die Token-Effizienz verbessert. + +All dies ist standardmäßig deaktiviert. Solange Sie es nicht aktivieren, funktioniert |Fess| +weiterhin genau wie zuvor und verwendet ausschließlich die Schlüsselwortsuche. Wenn Sie |Fess| von +Version 15.7 oder früher aktualisieren oder das ``fess-webapp-semantic-search``-Plugin verwendet +haben, siehe :ref:`semantic-search-migration`. + +Verarbeitungsablauf +-------------------- + +1. Der Crawler indiziert Dokumente wie gewohnt (zu diesem Zeitpunkt existieren noch keine Chunks). +2. Der Scheduler-Job **Content Chunk Vector Indexer** sucht nach unverarbeiteten Dokumenten, + teilt deren Inhalt (das Feld ``content``) in Chunks auf, generiert Embedding-Vektoren und + speichert sie im Feld ``content_chunk_vector``. Dabei wird auch das Feld ``content`` selbst + in das Array der Chunks umgeschrieben (``content_length`` behält seinen ursprünglichen Wert). +3. Das Ergebnis dieser Verarbeitung wird im Feld ``content_chunk_status`` (unten beschrieben) + festgehalten. +4. Wenn ``content_chunker.search.enabled=true`` gesetzt ist, nimmt der semantische Sucher zur + Suchzeit an Rank Fusion teil. + +Voraussetzungen +================ + +- **OpenSearch mit dem k-NN-Plugin**: In |Fess| 15.10 enthält das Mapping des Suchindex + (``fess.search``) immer das Feld ``content_chunk_vector`` (ein ``nested``-Feld, dessen + Unterfeld ``vector`` der ``knn_vector``-Typ für ANN ist), und die Indexeinstellungen enthalten + immer ``index.knn: true`` — unabhängig davon, ob die Content-Chunking-Funktion aktiviert ist. + Wenn OpenSearch das k-NN-Plugin nicht installiert hat, schlägt die Erstellung eines neuen Index + daher grundsätzlich fehl, und |Fess| kann nicht starten. + + .. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Konfiguration + - Unterstützung des k-NN-Plugins + * - Docker (``ghcr.io/codelibs/fess-opensearch``), die RPM/DEB-Pakete (die sich immer mit + einem separat installierten externen OpenSearch verbinden) oder ein weiteres externes + OpenSearch (Standarddistribution) + - Vollständig unterstützt, einschließlich ``faiss``. + * - Die **Minimaldistribution** eines externen OpenSearch + - **Nicht unterstützt.** Sie enthält das k-NN-Plugin nicht, sodass die Erstellung eines + neuen Index fehlschlägt. + + ``nmslib`` ist bei keiner der obigen Konfigurationen ein zulässiger Wert für + ``content_chunker.search.knn.engine``: ``content_chunk_vector`` ist ein ``nested``-Feld, und + das k-NN-Plugin unterstützt nested Felder nur für die Engines ``lucene``/``faiss`` (``nmslib`` + ist außerdem ab OpenSearch 3.0 veraltet und eingeschränkt). Wird es dennoch gesetzt, greift mit + einer Warnung der Fallback auf ``lucene``; die übrigen zulässigen Werte für die ANN-Einstellungen + finden Sie unten in der Konfigurationsreferenz. + +- **OpenSearch-Version eines externen Clusters**: Die mitgelieferten + ``fess.search``-Indexeinstellungen senden in ``fess_indices/fess.json`` (sowie in + ``fess_indices/_vanilla/fess.json``, das ``vanilla``, ``aws`` und das veraltete ``cloud`` verwenden) immer ``index.knn`` und ``knn.derived_source.enabled``. Letzteres ist eine + vergleichsweise neue Einstellung des k-NN-Plugins: Ein älteres OpenSearch, das sie nicht kennt, + lässt die Erstellung des Index fehlschlagen — unabhängig davon, ob das k-NN-Plugin selbst + installiert ist. Welche OpenSearch-Versionen |Fess| 15.10 unterstützt, entnehmen Sie + :doc:`../install/prerequisites`. + +- **Embedding-Anbieter**: Verwenden Sie einen der folgenden. + +.. list-table:: + :header-rows: 1 + :widths: 20 25 55 + + * - Konfigurationswert + - Bereitgestellt durch + - Beschreibung + * - ``opensearch`` + - |Fess|-Kern (eingebaut) + - Verwendet ein in OpenSearch ML Commons bereitgestelltes Embedding-Modell. Kein + zusätzliches Plugin erforderlich. Standardeinstellung. + * - ``ollama`` + - ``fess-llm-ollama``-Plugin + - Verwendet ein Ollama-Embedding-Modell (z. B. ``nomic-embed-text``). + * - ``openai`` + - ``fess-llm-openai``-Plugin + - Verwendet die OpenAI-Embeddings-API. + * - ``gemini`` + - ``fess-llm-gemini``-Plugin + - Verwendet die Google-Gemini-Embeddings-API. + * - ``bedrock`` + - ``fess-llm-bedrock``-Plugin + - Verwendet Amazon Titan Text Embeddings V2 oder Cohere Embed über Amazon Bedrock. + * - ``none`` + - |Fess|-Kern (eingebaut) + - Teilt Dokumente nur in Chunks auf; es werden keine Vektoren generiert (Nur-Chunk-Modus). + +Konfigurationsreferenz +======================== + +Alle ``content_chunker.*``-Einstellungen liegen in einem einzigen Kanal: den +**Systemeigenschaften** (``system.properties``). Setzen Sie sie in +``app/WEB-INF/conf/system.properties`` (bei den RPM/DEB-Paketen ``/etc/fess/system.properties``, +unter Docker ``/opt/fess/system.properties``), oder geben Sie einen Initialwert über die +Startoption ``-Dfess.system.`` an. Werte werden zur Laufzeit neu geladen, sodass die meisten +Einstellungen sofort nach der Änderung wirksam werden. Die einzige Ausnahme ist die Aktivierung +von ``content_chunker.search.enabled`` (``false`` → ``true``): Da der semantische Sucher nur beim +Start registriert wird, **erfordert diese Änderung einen Neustart, um wirksam zu werden**. + +.. note:: + + Die ``content_chunker.*``-Schlüssel werden ausschließlich über den Kanal ``system.properties`` + gelesen. Einträge in ``fess_config.properties`` oder ``-Dfess.config.`` werden ignoriert — + konfigurieren Sie sie daher stets in ``system.properties``. Der Admin-Bildschirm + **Systeminformationen > Konfigurationsinformationen** zeigt lediglich die aktuellen Werte an + und ist **rein lesend**; ``content_chunker.*`` lässt sich dort nicht setzen. + +Einstellungen in system.properties +------------------------------------ + +.. list-table:: + :header-rows: 1 + :widths: 40 15 45 + + * - Eigenschaft + - Standard + - Beschreibung + * - ``content_chunker.enabled`` + - ``false`` + - Hauptschalter für die gesamte Content-Chunking-Funktion + * - ``content_chunker.chunker.name`` + - ``length`` + - Chunking-Methode + * - ``content_chunker.length.chunk_size`` + - ``800`` + - Zielanzahl der Zeichen pro Chunk. Bei aktivierter grenzbewusster Aufteilung (Standard) + ist dies ein Zielwert und keine harte Obergrenze: Ein Chunk kann um bis zu + ``boundary.lookback_percent`` kürzer und um bis zu ``max(lookahead, 32)`` Zeichen länger + sein -- mit den Standardwerten 640 bis 840 Zeichen. Halten Sie diesen Spielraum gegenüber + dem Token-Limit des Embedding-Modells frei + * - ``content_chunker.length.overlap`` + - ``0`` + - Anzahl der Zeichen, die sich zwischen Chunks überlappen. Auch der Wiedereinstiegspunkt + wird auf eine Grenze gezogen, und zwar ausschließlich nach vorn, sodass die effektive + Überlappung zwischen diesem Wert und seinem Doppelten liegt + * - ``content_chunker.length.boundary.enabled`` + - ``true`` + - Verschiebt jeden Schnitt auf eine sinnvolle Textgrenze, statt exakt bei + ``chunk_size`` Zeichen zu schneiden. Die Kandidaten sind gestuft, und der nächstgelegene + Kandidat der höchsten vorhandenen Stufe gewinnt: Zeilenumbruch oder Satzende, sonst + Teilsatztrenner oder Leerzeichen, sonst Schriftsystemwechsel. ``false`` stellt das + bisherige Verhalten mit fester Länge wieder her + * - ``content_chunker.length.boundary.lookback_percent`` + - ``20`` + - Wie weit vor dem idealen Schnitt nach einer Grenze gesucht werden darf, als + Prozentsatz von ``chunk_size`` (0-50) + * - ``content_chunker.length.boundary.lookahead_percent`` + - ``5`` + - Wie weit nach dem idealen Schnitt nach einem Satzende oder Zeilenumbruch gesucht + werden darf, als Prozentsatz von ``chunk_size`` (0-25). Wird nur verwendet, wenn davor + nichts gefunden wurde + * - ``content_chunker.max_chunks_per_document`` + - ``1000`` + - Maximale Anzahl von Chunks pro Dokument. Dokumente, die diesen Wert überschreiten, werden + als ``skipped`` markiert und erhalten keine Embeddings. Da die grenzbewusste + Aufteilung die Chunks verkürzt, ergibt ein Dokument etwa 3 % bis 25 % mehr Chunks als bei + fester Länge; für sehr große Dokumente kann hier ein höherer Wert nötig sein + * - ``content_chunker.embedding.name`` + - ``opensearch`` + - Embedding-Anbieter (``opensearch`` / ``ollama`` / ``openai`` / ``gemini`` / ``bedrock`` / ``none``) + * - ``content_chunker.embedding.dimension`` + - ``768`` + - Dimension des Embedding-Vektors. Dieser Wert wird bei der Erstellung des Mappings + verwendet und **muss** daher mit der Dimension des verwendeten Embedding-Modells + übereinstimmen. Für diesen Wert gibt es zwei Lesepfade, die sich unterschiedlich verhalten. + Bei der Erstellung des Index-Mappings wird ``768`` **ohne jede Warnung** verwendet, wenn + der Wert nicht gesetzt ist; ist er leer, nicht-numerisch, nicht positiv oder größer als + ``16000`` (das Maximum des k-NN-Plugins selbst), wird mit einer Warnung ``768`` verwendet. + Zur Laufzeit des Embedding-Prozesses gibt es dagegen keinen + Fallback: nicht gesetzte, nicht-numerische und nicht positive Werte führen jeweils zu einem + Fehler. Werte über ``16000`` werden zur Laufzeit nicht abgelehnt, sodass nur das Mapping + mit ``768`` erstellt wird und es zu einer Dimensionsabweichung kommt. Die Dimension des + Mappings lässt sich nach der Erstellung des Index nicht mehr ändern; zur Behebung bei einem + Index, der ohne gesetzten Wert erstellt wurde, siehe *Wenn der Index ohne Dimension + erstellt wurde* unter *Hinweise* + * - ``content_chunker.job.concurrency`` + - ``2`` + - Anzahl paralleler Worker für den Indexer-Job + * - ``content_chunker.job.bulk_size`` + - ``20`` + - Anzahl der pro Batch abgerufenen und geschriebenen Dokumente + * - ``content_chunker.job.max_documents_per_run`` + - ``-1``\ (unbegrenzt) + - Maximale Anzahl der pro Job-Lauf verarbeiteten Dokumente. Jeder Wert von ``0`` oder + kleiner wird als unbegrenzt behandelt + * - ``content_chunker.job.retry_failed`` + - ``false`` + - Wenn auf ``true`` gesetzt, werden Dokumente, deren vorheriger Lauf mit + ``content_chunk_status=fail`` endete, auch in das Verarbeitungsziel des nächsten Laufs + einbezogen. Es gibt keine automatische Wiederholung oder Zählung der Versuche; der + vorgesehene Arbeitsablauf besteht darin, die zugrunde liegende Ursache zu beheben und + dies dann vorübergehend zu aktivieren, um es erneut zu versuchen + * - ``content_chunker.chat.top_k`` + - ``3`` + - Anzahl der Chunks, die bei der Antwortgenerierung im KI-Suchmodus ausgewählt werden + * - ``content_chunker.search.enabled`` + - ``false`` + - Rank-Fusion-Integration für die semantische Suche (**die Aktivierung erfordert einen + Neustart**) + * - ``content_chunker.search.min_score`` + - (nicht gesetzt) + - Minimale Kosinusähnlichkeit (0–1), die für die Aufnahme eines Ergebnisses erforderlich + ist. Ohne diesen Wert erfolgt kein Cutoff. Im Modus ``ann`` wird der Cutoff mit einer + Warnung übersprungen, wenn ``search.knn.space_type`` nicht ``cosinesimil`` ist, da sich + dann kein kosinusbasierter Cutoff definieren lässt + * - ``content_chunker.search.knn.method`` + - ``hnsw`` + - ANN-Indexmethode. ``hnsw`` ist derzeit der einzige zulässige Wert; jeder andere Wert führt + mit einer Warnung zum Fallback auf ``hnsw`` (wird im Mapping abgebildet; eine Änderung + erfordert die Neuerstellung des Index) + * - ``content_chunker.search.knn.engine`` + - ``lucene`` + - ANN-Engine. Zulässig sind nur ``lucene`` oder ``faiss`` (siehe Voraussetzungen oben); jeder + andere Wert führt mit einer Warnung zum Fallback auf ``lucene`` (wird im Mapping + abgebildet; eine Änderung erfordert die Neuerstellung des Index) + * - ``content_chunker.search.knn.space_type`` + - ``cosinesimil`` + - Distanzraum. Zulässig sind nur ``cosinesimil``, ``innerproduct`` oder ``l2``; jeder andere + Wert führt mit einer Warnung zum Fallback auf ``cosinesimil`` (wird im Mapping abgebildet; + eine Änderung erfordert die Neuerstellung des Index) + * - ``content_chunker.search.knn.k`` + - ``100`` + - Anzahl der pro Shard von der ANN-Abfrage abgerufenen Nachbarn. Führt |Fess| die Fusion + durch, fällt der wirksame Wert nie unter ``rank.fusion.window_size`` geteilt durch die + Anzahl der Sucher (standardmäßig 200 / 2 = 100); ein kleinerer Wert hat daher keine + Wirkung. Führt die Suchmaschine die Fusion durch, wird dieser Wert unverändert verwendet + * - ``content_chunker.search.knn.param.ef_search`` + - (nicht gesetzt) + - Der Parameter ``ef_search`` für ANN-Abfragen + +.. note:: + + Mit ``content_chunker.length.boundary.enabled=true`` (Standardeinstellung) wird + ``content_chunker.length.chunk_size`` zu einem Zielwert statt zu einer harten Obergrenze: + Jeder Schnitt verschiebt sich zum nächstgelegenen Kandidaten der höchsten im Suchfenster + vorhandenen Stufe. Ein Zeilenumbruch oder Satzende gewinnt gegen jedes Teilsatztrennzeichen + und jedes Leerzeichen, gleichgültig wie viel weiter zurück es liegt, und diese gewinnen gegen + einen Schriftsystemwechsel. Verschoben wird dabei nur der Schnittpunkt selbst; es geht kein + Zeichen verloren, sodass das Zusammenfügen der Chunks eines Dokuments weiterhin exakt dessen + Inhalt ergibt. Die Vorwärtssuche kann ``chunk_size`` um bis zu + ``content_chunker.length.boundary.lookahead_percent`` überschreiten. Ein zweites, unabhängiges + Überschreiten um bis zu 32 Zeichen kann auftreten, wenn ein Schnitt sonst mitten in einem + Graphemcluster (ein kombinierendes Zeichen, ein Variationsselektor oder eine durch + Zero-Width-Joiner verbundene Emoji-Sequenz) landen würde — dieses ignoriert + ``lookahead_percent`` und kann auch bei ``0`` auftreten. Die beiden Überschreitungen treten + nie beim selben Schnitt gemeinsam auf, sodass ein Chunk mit den Standardwerten zwischen 640 + und 840 Zeichen lang ist. Da die Chunks im Mittel kürzer ausfallen, ergibt ein Dokument etwa + 3 % bis 25 % mehr Chunks als bei fester Länge (siehe + ``content_chunker.max_chunks_per_document``). ``content_chunker.length.boundary.enabled`` auf + ``false`` zu setzen -- oder beide Prozentwerte auf ``0`` -- reproduziert exakt das bisherige + Verhalten mit fester Länge. Änderungen an diesen Einstellungen wirken sich nur auf danach + gechunkte Dokumente aus: Ein bereits als Chunk-Array gespeichertes Dokument behält seine + Grenzen, bis es erneut gecrawlt wird. + +.. note:: + + ``content_chunker.length.chunk_size`` wird in Zeichen angegeben, ein Embedding-Modell kann + aber nur Text bis zu seinem Token-Limit aufnehmen. |Fess| kürzt den eingebetteten Text nicht, + sodass der Teil jenseits dieses Limits möglicherweise nicht im Vektor berücksichtigt wird. + Wählen Sie ``chunk_size`` anhand des Eingabelimits des verwendeten Modells. Gemessen mit + ``paraphrase-multilingual-MiniLM-L12-v2`` (höchstens 128 Token) wurden beispielsweise etwa + 440 Zeichen englischer und etwa 210 Zeichen japanischer Text im Vektor berücksichtigt (je nach + Text unterschiedlich). Bei diesem Modell wird der hintere Teil eines Chunks mit dem Standardwert + ``chunk_size=800`` nicht im Vektor berücksichtigt. + +.. note:: + + Die HNSW-Parameter ``m`` und ``ef_construction`` sind in ``doc.json`` fest codiert + (``m=16`` / ``ef_construction=100``) und können nicht über die Konfiguration geändert werden. + +Verbindungseinstellungen für den Anbieter opensearch +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Verbindungseinstellungen für den eingebauten Anbieter ``opensearch`` (OpenSearch ML Commons). +Diese werden in derselben Datei ``system.properties`` wie oben gesetzt. + +.. list-table:: + :header-rows: 1 + :widths: 50 20 30 + + * - Eigenschaft + - Standard + - Beschreibung + * - ``content_chunker.embedding.opensearch.model.id`` + - (erforderlich) + - ID des bereits in ML Commons bereitgestellten Modells + * - ``content_chunker.embedding.opensearch.api.url`` + - Adresse der Suchmaschine + - ML-Commons-API-Endpunkt. Ohne diese Einstellung wird standardmäßig die Suchmaschine + verwendet, die |Fess| bereits nutzt (z. B. ``http://localhost:9200``) + * - ``content_chunker.embedding.opensearch.username`` / ``password`` + - Zugangsdaten der Suchmaschine + - Ohne diese Einstellung werden die für die Verbindung zur Suchmaschine verwendeten + Zugangsdaten übernommen — jedoch nur, solange ``api.url`` nicht konfiguriert ist (d. h. + das Ziel ist dasselbe Cluster, das |Fess| bereits verwendet). Sobald ``api.url`` gesetzt + ist, entfällt dieser Fallback. + * - ``content_chunker.embedding.opensearch.timeout`` + - ``60000`` + - Anfrage-Timeout (ms) + * - ``content_chunker.embedding.opensearch.connect.timeout`` + - ``5000`` + - Verbindungs-Timeout (ms) + * - ``content_chunker.embedding.opensearch.retry.max`` + - ``3`` + - Maximale Anzahl der Versuche einschließlich des ersten bei vorübergehenden Fehlern (429, + 5xx usw.). Das ist nicht die Anzahl der Wiederholungen: ``3`` bedeutet insgesamt höchstens + drei Anfragen mit zwei Wartezeiten dazwischen. Ein Wert von ``1`` oder weniger bedeutet + keine Wiederholung + * - ``content_chunker.embedding.opensearch.retry.base.delay.ms`` + - ``2000`` + - Basisverzögerung für Wiederholungen (ms) + * - ``content_chunker.embedding.opensearch.availability.check.interval`` + - ``60`` + - Intervall zwischen Verfügbarkeitsprüfungen des Anbieters (Sekunden) + * - ``content_chunker.embedding.opensearch.document.prefix`` / ``query.prefix`` + - (leer) + - Präfix, das dem Dokument-/Anfragetext vor dem Embedding vorangestellt wird + +.. warning:: + + Der Inhalt von ``system.properties`` ist im Admin-Bildschirm **Systeminformationen > + Konfigurationsinformationen**, im Bereich **App-Eigenschaften**, einsehbar. + ``content_chunker.embedding.opensearch.password`` wird auf diesem Bildschirm zu ``XXXXXXXX`` + maskiert, ``username`` dagegen unverändert angezeigt. Werte, die Sie über + ``-Dfess.system.`` angeben, erscheinen auf demselben Bildschirm im Bereich + **Systemeigenschaften** **unmaskiert** — tragen Sie Zugangsdaten daher in + ``system.properties`` ein und nicht in die Startoptionen. + +Andere Anbieter (ollama / openai / gemini / bedrock) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Der Anbieter ``ollama`` (``fess-llm-ollama``-Plugin) verwendet denselben Einstellungsstil unter +dem Präfix ``content_chunker.embedding.ollama.`` (``api.url`` ist standardmäßig +``http://localhost:11434``, ``model`` standardmäßig ``embeddinggemma``, und +``document.prefix`` / ``query.prefix`` sind standardmäßig ``title: none | text:`` bzw. +``task: search result | query:``). Verwenden Sie ein Modell der ``nomic-embed-text``-Familie, +setzen Sie ``document.prefix`` / ``query.prefix`` explizit auf ``search_document:`` bzw. +``search_query:``. Diese Präfixe werden unverändert mit dem einzubettenden Text verkettet +(umgebende Leerzeichen werden nicht entfernt), daher enthalten sowohl die obigen Standardwerte +als auch ``search_document:`` bzw. ``search_query:`` jeweils **ein abschließendes Leerzeichen**. +Denken Sie an das trennende Leerzeichen, wenn Sie ein Präfix selbst setzen. +Die Anbieter ``openai`` und ``gemini`` werden auf dieselbe Weise +konfiguriert, unter den Präfixen ``content_chunker.embedding.openai.`` bzw. +``content_chunker.embedding.gemini.``. Die vollständige Liste der Einstellungen finden Sie in der +jeweiligen Plugin-Dokumentation. Der Anbieter ``bedrock`` verwendet das Präfix +``content_chunker.embedding.bedrock.``, und ``content_chunker.embedding.dimension`` muss eine Größe +sein, die das konfigurierte Modell erzeugt; siehe :doc:`llm-bedrock`. + +Einrichtungsverfahren (Beispiel mit dem Anbieter opensearch) +================================================================ + +Dieser Abschnitt führt durch ein Konfigurationsbeispiel mit dem eingebauten Anbieter +``opensearch`` (ML Commons). + +1. Embedding-Modell bereitstellen +------------------------------------ + +Registrieren und bereitstellen Sie ein Embedding-Modell in OpenSearch ML Commons. In einem +Single-Node-Cluster müssen Sie zunächst die folgende Einstellung anwenden. + +.. code-block:: bash + + curl -XPUT "http://localhost:9200/_cluster/settings" \ + -H "Content-Type: application/json" -d ' + {"persistent": {"plugins.ml_commons.only_run_on_ml_node": false}}' + +Registrieren und bereitstellen Sie das Modell (Beispiel: ein Sentence-Embedding-Modell mit +384 Dimensionen): + +.. code-block:: bash + + # Modell registrieren (model_id aus dem task_id der Antwort entnehmen) + curl -XPOST "http://localhost:9200/_plugins/_ml/models/_register" \ + -H "Content-Type: application/json" -d ' + { + "name": "huggingface/sentence-transformers/all-MiniLM-L6-v2", + "version": "1.0.2", + "model_format": "TORCH_SCRIPT" + }' + + # Abschluss der Aufgabe prüfen und model_id abrufen + # (sobald state auf COMPLETED steht, wird model_id zurückgegeben) + curl "http://localhost:9200/_plugins/_ml/tasks/" + + # Bereitstellen + curl -XPOST "http://localhost:9200/_plugins/_ml/models//_deploy" + + # Status prüfen: model_state sollte DEPLOYED sein + curl "http://localhost:9200/_plugins/_ml/models/" + +.. note:: + + Ein Modell, das sich noch im Status ``REGISTERED`` befindet, kann nicht verwendet werden. + Stellen Sie sicher, dass Sie es bereitstellen und bestätigen, dass ``model_state`` zu + ``DEPLOYED`` wird. + +2. |Fess| konfigurieren +-------------------------- + +``app/WEB-INF/conf/system.properties`` (bei den RPM/DEB-Paketen ``/etc/fess/system.properties``, +unter Docker ``/opt/fess/system.properties``; alles Folgende gehört in dieselbe Datei):: + + content_chunker.enabled=true + content_chunker.embedding.name=opensearch + content_chunker.embedding.dimension=384 + content_chunker.embedding.opensearch.model.id= + +Wenn Sie zusätzlich die semantische Suche nutzen möchten, fügen Sie außerdem Folgendes hinzu:: + + content_chunker.search.enabled=true + +Starten Sie |Fess| nach diesen Änderungen neu. + +3. Index neu erstellen (bei Aktivierung auf einer bestehenden Installation) +------------------------------------------------------------------------------- + +Das Mapping für das Feld ``content_chunk_vector`` — einschließlich der von Ihnen konfigurierten +Dimension und ANN-Methodeneinstellungen — wird **in dem Moment angewendet, in dem der Index** +``fess.search`` **neu erstellt wird**. + +- **Neuinstallationen**: Wenn Sie die obigen Einstellungen in ``system.properties`` anwenden, + bevor Sie |Fess| zum ersten Mal starten, wird das korrekte Mapping automatisch angewendet, wenn + der Index erstmals erstellt wird; dieser Schritt ist dann nicht erforderlich. +- **Wenn bereits ein Index existiert** (das heißt, wenn Sie |Fess| bereits mindestens einmal + gestartet haben): Der laufende Index übernimmt das neue Mapping nicht automatisch, und ein + bestehendes Mapping kann nachträglich nicht geändert werden. Erstellen Sie den Index wie folgt + neu: + + Öffnen Sie **Systeminformationen > Wartung**, und führen Sie unter **Neuindizierung** die + Neuindizierung mit aktivierter Option **Aliase ersetzen** aus. + + Anschließend können Sie bestätigen, dass der neu erstellte Index ``index.knn: true`` in den + Indexeinstellungen sowie ein ``content_chunk_vector``-Mapping mit der von Ihnen konfigurierten + Dimension und den ANN-Methodeneinstellungen enthält (``index.knn`` gehört zu den + Indexeinstellungen, die ANN-Methodeneinstellungen zum Mapping — zwei verschiedene Ziele). + +.. warning:: + + Die Neuindizierung läuft als asynchroner Hintergrundprozess, und die Admin-Oberfläche zeigt + keine Erfolgsmeldung an. ``_cat/indices`` zeigt nur, dass der neue Index existiert (Status, + Dokumentanzahl usw.) — nicht, worauf die Aliase zeigen. Bevor Sie mit dem unten beschriebenen + Indexer-Job fortfahren, prüfen Sie stattdessen ``_cat/aliases`` und vergewissern Sie sich, dass + sowohl ``fess.search`` als auch ``fess.update`` auf den neuen Index zeigen; das |Fess|-Log + protokolliert nur bei einem Fehler eine Warnung, sodass ein stilles Log kein Erfolgsnachweis + ist, sondern nur das Fehlen eines bekannten Fehlers anzeigt. Der alte Index (der physische + Index, auf den der Alias ``fess.search`` zuvor verwies, benannt ``fess.``) wird + nicht automatisch gelöscht; entfernen Sie ihn manuell, sobald Sie ihn nicht mehr benötigen. + Solange beide Indizes existieren, ist mit etwa der doppelten üblichen Index-Festplattennutzung + zu rechnen. + +4. Indexer-Job aktivieren +----------------------------- + +Chunking und Embedding-Generierung werden vom Scheduler-Job **Content Chunk Vector Indexer** +durchgeführt (ID: ``content-chunk-vector-indexer``; standardmäßig deaktiviert; geplant mit +``0 13 * * *``). + +Aktivieren Sie diesen Job unter **System > Scheduler** und führen Sie ihn dann einmal mit +**Jetzt starten** aus. Danach werden unverarbeitete Dokumente unabhängig vom Abschluss eines +Crawls gemäß dem konfigurierten Zeitplan (standardmäßig täglich um 13:00 Uhr) verarbeitet. Der +Job ist nicht mit dem Crawl-Job verkettet; wenn Sie unmittelbar nach einem Crawl verarbeiten +möchten, legen Sie den Zeitplan auf einen Zeitpunkt nach dem erwarteten Ende des Crawl-Jobs. + +.. note:: + + In einer Multi-Node-Bereitstellung empfehlen wir, diesen Job an genau einen Knoten zu binden. + Wird er auf jedem Knoten gleichzeitig ausgeführt, führt dies zwar nicht zu Fehlern in der + Korrektheit, aber jeder Knoten verarbeitet und embeddet dieselben Dokumente redundant, was die + Last und die Kosten bei Ihrem Embedding-Anbieter um die Anzahl der Knoten vervielfacht. + + Die Bindung erfordert **beide** der folgenden Einstellungen — jede für sich allein bindet den + Job nicht. + + 1. **Auf dem Knoten, auf dem der Job laufen soll**: Setzen Sie + ``scheduler.target.name=`` in + ``app/WEB-INF/classes/fess_config.properties`` (bei den RPM/DEB-Paketen + ``/etc/fess/fess_config.properties``; oder über + ``-Dfess.config.scheduler.target.name=``) und starten Sie diesen Knoten neu. + (Der Standardwert ist leer; belassen Sie alle anderen Knoten auf dem Standardwert.) + 2. Öffnen Sie in der Admin-Oberfläche unter **System > Scheduler** den Job Content Chunk + Vector Indexer und ändern Sie dessen Feld **Ziel** von ``all`` auf dieselbe Kennung, die + Sie in Schritt 1 gesetzt haben, und speichern Sie. + + Was das Feld **Ziel** bedeutet, entnehmen Sie :doc:`../admin/scheduler-guide`. Das alleinige + Setzen von ``scheduler.target.name`` bindet den Job nicht, wenn das Feld **Ziel** auf ``all`` + belassen wird: **er wird dann nicht gebunden**. ``all`` wird als Sonderwert behandelt, der + immer zutrifft, sodass Schritt 1 allein oder Schritt 2 allein nicht ausreicht — Sie müssen + beides tun. + +.. warning:: + + Führen Sie **Jetzt starten** nach der Bindung ebenfalls **über die Admin-Oberfläche des + Knotens aus, für den Sie in Schritt 1 die Kennung gesetzt haben**. Drücken Sie **Jetzt + starten** auf einem anderen Knoten, meldet der Bildschirm zwar „Job … gestartet.", der Job + läuft aber wegen der Abweichung im Feld **Ziel** nicht (im Log dieses Knotens erscheint + lediglich eine INFO-Zeile ``Ignoring job``). + +5. Verarbeitungsstatus prüfen +--------------------------------- + +Sie können das Ergebnis für jedes Dokument in dessen Feld ``content_chunk_status`` prüfen. + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Wert + - Bedeutung + * - (Feld fehlt) + - Noch nicht verarbeitet (wird beim nächsten Job-Lauf aufgenommen). Dokumente kehren nach + einem erneuten Crawl ebenfalls in diesen Zustand zurück + * - ``done`` + - Chunking und Vektorgenerierung abgeschlossen + * - ``chunked`` + - Nur Chunking abgeschlossen (Nur-Chunk-Modus). Das gilt für ``embedding.name=none``, aber + ebenso, wenn das Plugin des unter ``embedding.name`` angegebenen Anbieters nicht + installiert ist + * - ``skipped`` + - Verarbeitung übersprungen. Das betrifft Dokumente mit leerem Text (auch nur aus + Leerzeichen), Dokumente, für die kein Chunk erzeugt wurde, und Dokumente, die + ``max_chunks_per_document`` überschreiten. Nennt ``content_chunker.chunker.name`` einen + nicht vorhandenen Chunker, wird kein Chunker gefunden und kein Chunk erzeugt; dann landen + alle Dokumente in diesem Zustand. Es ist ein Endzustand: Ein erneuter Job-Lauf verarbeitet + das Dokument nicht noch einmal + * - ``fail`` + - Verarbeitung fehlgeschlagen (Protokolle prüfen). Es ist ein Endzustand: Standardmäßig + verarbeitet ein erneuter Job-Lauf das Dokument nicht noch einmal. Setzen Sie + ``content_chunker.job.retry_failed`` auf ``true``, um es erneut zu verarbeiten + +Sie können die Verteilung der Statuswerte durch eine direkte Abfrage der Suchmaschine prüfen:: + + curl -XPOST "http://localhost:9200/fess.search/_search" \ + -H "Content-Type: application/json" -d ' + {"size": 0, "aggs": {"status": {"terms": {"field": "content_chunk_status", "missing": "pending"}}}}' + +Durch die Option ``missing`` werden Dokumente ohne ``content_chunk_status`` (also unverarbeitete +Dokumente) in einem Bucket mit dem Schlüssel ``pending`` zusammengefasst. + +Beurteilen Sie den Zustand des Chunk-Jobs anhand dieser Verteilung von ``content_chunk_status``. +Wenn ``pending`` mit jedem Job-Lauf kleiner und ``done`` (im Nur-Chunk-Modus ``chunked``) größer +wird, macht der Job Fortschritte. Taucht ``fail`` auf, prüfen Sie die |Fess|-Protokolle auf die +Ursache. ``skipped`` ist bei Dokumenten wie solchen mit leerem Text normal; sind aber fast alle +Dokumente ``skipped``, vermuten Sie einen falschen Wert für ``content_chunker.chunker.name`` +(wird kein Chunker gefunden, wird eine WARN-Meldung ``Chunker not found`` protokolliert). + +.. warning:: + + Das Korrigieren der Konfiguration macht ``skipped`` oder ``fail`` nicht von selbst rückgängig. + Ein Dokument mit ``skipped`` wird bei einem erneuten Job-Lauf nicht aufgenommen (ein erneut + gecrawltes Dokument kehrt in den unverarbeiteten Zustand zurück), und ein Dokument mit ``fail`` + wird nur dann erneut verarbeitet, wenn ``content_chunker.job.retry_failed`` auf ``true`` steht. + Lief der Job zum Beispiel mit einem falschen ``content_chunker.chunker.name`` und alle + Dokumente wurden ``skipped``, korrigieren Sie den Namen, löschen Sie ``content_chunk_status`` + wie unten gezeigt und führen Sie den Job danach erneut aus (das Feld ``content`` eines + ``skipped``-Dokuments wurde nicht überschrieben, daher kann es unverändert verarbeitet + werden):: + + curl -XPOST "http://localhost:9200/fess.search/_update_by_query" \ + -H "Content-Type: application/json" -d ' + { + "query": {"term": {"content_chunk_status": "skipped"}}, + "script": {"source": "ctx._source.remove(\"content_chunk_status\")"} + }' + +Verhalten der semantischen Suche +==================================== + +Das Setzen von ``content_chunker.search.enabled=true`` registriert den semantischen Sucher bei +Rank Fusion, das dann die Ergebnisse der Schlüsselwortsuche mit denen der Vektorsuche +zusammenführt. (Siehe :doc:`rank-fusion` für die Funktionsweise von Rank Fusion.) Standardmäßig +führt |Fess| die Fusion selbst durch; mit ``rank.fusion.engine.enabled=true`` übernimmt dies +stattdessen OpenSearch (siehe :ref:`rank-fusion-engine`). +Zur Suchzeit wird zusätzlich ``content_chunker.enabled`` ausgewertet: Bei +``content_chunker.enabled=false`` oder ``content_chunker.embedding.name=none`` findet keine +semantische Suche statt, auch wenn der Sucher registriert ist (diese Prüfung erfolgt pro Anfrage, +ein Neustart ist also nicht nötig). + +.. warning:: + + Da der semantische Sucher beim Start registriert wird, **erfordert die Aktivierung einen + Neustart**. Das Deaktivieren (Zurücksetzen des Werts auf ``false``) wird pro Anfrage + ausgewertet und wirkt daher sofort. + +Modus exact und Modus ann +----------------------------- + +Die Suchmethode wird automatisch anhand des Zustands des Index gewählt. + +.. list-table:: + :header-rows: 1 + :widths: 12 44 44 + + * - Modus + - Bedingung + - Merkmale + * - ``ann`` + - Ein Index mit ``index.knn``- und ANN-Methodeneinstellungen + - Approximate-Nearest-Neighbor-Suche mit HNSW. Geeignet für große Indizes + * - ``exact`` + - Alles andere (ein Index, dem entweder ``index.knn`` oder die ANN-Methodeneinstellungen + fehlen — einschließlich des Falls, dass die Ermittlung des Indexzustands fehlschlägt) + - Exakte Kosinusähnlichkeitsberechnung über jeden Vektor. Geeignet für kleine bis mittlere + Indizes + +Jeder unter |Fess| 15.10 neu erstellte ``fess.search``-Index hat immer ``index.knn``- und +ANN-Methodeneinstellungen, unabhängig vom Wert von ``content_chunker.search.enabled`` — daher +wird normalerweise stets der Modus ``ann`` verwendet. Der Modus ``exact`` ist ein Fallback für +ältere Indizes, die vor der Einführung dieses Mechanismus erstellt wurden. Da k-NN-Einstellungen +einem bestehenden Index nicht nachträglich hinzugefügt werden können, erfordert der Wechsel eines +Index im Modus ``exact`` in den Modus ``ann`` die Neuerstellung des Index (siehe +:ref:`semantic-search-migration`). Das Ergebnis dieser Ermittlung wird 60 Sekunden lang +zwischengespeichert; unmittelbar nach einer Neuerstellung des Index kann es daher bis zu +60 Sekunden dauern, bis die Umstellung wirksam wird. + +Score-Cutoff +-------------- + +Das Setzen von ``content_chunker.search.min_score`` auf eine Kosinusähnlichkeit (0–1) schließt +Dokumente von den Ergebnissen der semantischen Suche aus, deren bester Chunk diesen Wert nicht +erreicht (da der Score eines Dokuments der Score seines besten Chunks ist, wirkt der Cutoff auf +Dokumentebene). Verwenden Sie dies, um die Trefferzahl bei Anfragen ohne Vokabularüberschneidung +einzugrenzen, wenn diese zu breit gestreut werden:: + + content_chunker.search.min_score=0.4 + +Der konfigurierte Wert wird sowohl im Modus ``exact`` als auch im Modus ``ann`` als +Kosinusähnlichkeit interpretiert (intern wird er in die Score-Skala des jeweiligen Modus +umgerechnet). + +.. note:: + + Dieser Cutoff wird nur angewendet, wenn ``content_chunker.search.knn.space_type`` auf + ``cosinesimil`` (dem Standard) steht. Bei einem Index im Modus ``ann`` mit ``innerproduct`` + oder ``l2`` lässt sich keine Kosinusähnlichkeit definieren; der Cutoff wird dann übersprungen, + und für jede solche Suche wird eine Warnung protokolliert. + +Einschränkungen +------------------ + +- Feldbezogene Bedingungen in der Anfrage (``label:``, ``site:``, ``filetype:``, Bereiche auf + ``timestamp`` / ``last_modified`` usw.) werden vom einzubettenden Text getrennt und als Filter + auf die Vektorsuche angewendet. Die Anfrage wird **nach** ihrer Zusammensetzung untersucht; + Vorgänge, die solche Bedingungen intern anhängen — die Auswahl eines Labels, die Eingrenzung + über Facetten oder Dateityp, Site und Zeitraum der erweiterten Suche, einschließlich + Bedingungen, die über die Parameter ``ex_q`` und ``fields.*`` übergeben werden —, führen die + semantische Suche daher weiterhin aus, eingegrenzt durch dieselben Bedingungen wie die + Schlüsselwortsuche. +- **Die semantische Suche wird** bei den folgenden Anfragen **übersprungen**, und es läuft nur die + Schlüsselwortsuche. + + - Eine Sortierbedingung (das Pseudofeld ``sort:`` oder der Parameter ``sort``, der intern + ebenfalls als ``sort:...`` angehängt wird) + - Eine Phrase (``"..."``), ein Platzhalter (``*`` ``?``), eine unscharfe Suche (``~``) oder ein + Bereich auf Wörtern ohne Feldangabe, einschließlich der Phrase der erweiterten Suche. Das + ASCII-Zeichen ``?`` wird als Platzhalter gelesen, daher wird auch ein natürlichsprachlicher + Satz, der mit einem ASCII-Fragezeichen endet (etwa „Was ist ...?"), übersprungen (das + Vollbreiten-``？`` zählt nicht dazu). + - Das Ausschließen eines Wortes (``-wort``, ``NOT wort``, einschließlich der Ausschlusswörter + der erweiterten Suche) oder dessen Gewichtung (``wort^2``) + - Eine Anfrage, deren Bedingungen sich nicht als Filter abtrennen lassen, etwa ein Wort und eine + Bedingung, die mit ``OR`` verknüpft sind + - ``allintitle:`` / ``allinurl:`` + - Eine Anfrage, die nur Bedingungen und keine einzubettenden Wörter enthält + - Eine Anfrage, die sich nicht parsen lässt + +- Sie wird ebenfalls übersprungen, wenn sie mit der Geolokalisierungssuche (einem Geo-Filter) + oder der Suche nach ähnlichen Dokumenten kombiniert wird. +- Wie tiefe Ergebnisseiten behandelt werden, hängt davon ab, wo die Fusion stattfindet. + + - Führt |Fess| die Fusion durch (Standard), bestimmt ``rank.fusion.window_size`` (Standard + ``200``) die Grenze; standardmäßig werden alle Treffer ab dem 101. Suchergebnis nur aus der + Schlüsselwortsuche geliefert. + - Führt die Suchmaschine die Fusion durch (``rank.fusion.engine.enabled=true``), wird jede + Seite fusioniert, aber das Blättern endet nach ``rank.fusion.pagination_depth`` Ergebnissen + (Standard ``1000``); eine Seite dahinter kann nicht angefordert werden. + + Siehe :doc:`rank-fusion` für Details. +- Ist der Embedding-Anbieter nicht erreichbar oder tritt ein Suchfehler auf, fällt |Fess| + automatisch auf reine Schlüsselwortergebnisse zurück (die Suche selbst schlägt dadurch nie + fehl). +- Die rollen- und virtual-host-basierte Zugriffskontrolle gilt auch für Ergebnisse der + semantischen Suche. + +Integration mit dem KI-Suchmodus +==================================== + +Wenn der KI-Suchmodus (:doc:`rag-chat`, ``rag.chat.enabled=true``) aktiviert ist, berechnet die +Antwortgenerierung für Dokumente, deren ``content_chunk_status`` ``done`` ist, die Ähnlichkeit +zu jedem Chunk und verwendet nur die ``content_chunker.chat.top_k`` relevantesten Chunks +(Standard: ``3``) als Kontext für das LLM. + +Eingebettet wird dabei nicht die Äußerung der Nutzenden selbst, sondern die **vom LLM in der +Phase der Absichtserkennung generierte Suchanfrage** (bei einer erneuten Suche entsprechend die +neu generierte Anfrage). Wird keine Suchanfrage generiert — etwa wenn um die Zusammenfassung +eines Dokuments gebeten wird —, findet keine Chunk-Auswahl statt. + +Dadurch werden selbst bei langen Dokumenten nur die relevanten Abschnitte an das LLM übergeben, +was die Antwortgenauigkeit verbessern und die Token-Nutzung reduzieren kann. Bei Dokumenten mit +``content_chunk_status`` ``chunked`` (Chunks vorhanden, aber keine Vektoren) erfolgt die +Chunk-Auswahl statt über die Ähnlichkeitsberechnung über Schlüsselwort- bzw. +Hervorhebungstreffer. Dokumente mit ``skipped`` oder ``fail`` sowie unverarbeitete Dokumente +verwenden wie bisher den vollständigen Inhalt (oder einen hervorgehobenen Ausschnitt). + +Dieses Verhalten ist unabhängig von ``content_chunker.search.enabled``, setzt aber voraus, dass +``content_chunker.enabled`` aktiviert ist. Beachten Sie außerdem, dass auch der aus den +ausgewählten Chunks zusammengesetzte Text auf ``rag.chat.content.fulltext.max.length`` +(Standard ``3000``) gekürzt wird: Selbst wenn Sie ``content_chunker.chat.top_k`` oder +``content_chunker.length.chunk_size`` erhöhen, überschreitet die an das LLM übergebene +Zeichenzahl diese Obergrenze nicht. + +.. _semantic-search-migration: + +Migration von 15.7 oder früheren Versionen +============================================= + +Wenn Sie |Fess| von Version 15.7 oder früher aktualisieren, fällt Ihre Situation je nachdem, wie +Sie diese Funktionen aktuell nutzen, in eines der vier folgenden Muster. Folgen Sie den +Anweisungen für das für Sie zutreffende Muster. + +Neuinstallationen +-------------------- + +Es ist keine zusätzliche Arbeit erforderlich. Wenn Sie die Vektorsuche nutzen möchten, +konfigurieren Sie ``system.properties`` einfach gemäß dem Abschnitt *Konfigurationsreferenz* auf +dieser Seite, bevor Sie |Fess| zum ersten Mal starten; das korrekte Mapping wird automatisch +angewendet, wenn der Index erstmals erstellt wird. (Die konkreten Schritte finden Sie oben unter +*Einrichtungsverfahren*.) + +.. note:: + + Wenn Sie |Fess| bereits mindestens einmal gestartet haben (das heißt, der Index bereits + existiert), folgen Sie stattdessen einem der unten stehenden Muster für *bestehende Nutzer*. + +Bestehende Nutzer, die keine Vektorsuche wünschen +------------------------------------------------------ + +Es ist keine Arbeit erforderlich. ``content_chunker.enabled`` und +``content_chunker.search.enabled`` sind beide standardmäßig ``false``, sodass sich Ihre +Suchergebnisse und das bestehende Indexverhalten nach dem Upgrade nicht ändern. Der neue +Scheduler-Job **Content Chunk Vector Indexer** wird beim Start automatisch registriert, läuft +aber, da er standardmäßig deaktiviert ist, nie, und der semantische Sucher wird nie bei Rank +Fusion registriert. (Der Job wird bei jedem Start registriert; löschen Sie ihn in der +Admin-Oberfläche, wird er beim nächsten Start im deaktivierten Zustand neu angelegt.) + +.. note:: + + Auch wenn Sie die Vektorsuche nicht nutzen: Sobald ab |Fess| 15.10 ein Index **neu erstellt** + wird (einschließlich einer Neuindizierung), werden das Mapping mit ``content_chunk_vector`` + (Typ ``knn_vector``) und ``index.knn: true`` angewendet. In einer Konfiguration ohne das + k-NN-Plugin in OpenSearch schlägt die Erstellung des Index dann genau an dieser Stelle fehl. + Einzelheiten finden Sie im Abschnitt *Voraussetzungen* auf dieser Seite. + +Bestehende Nutzer, die die Vektorsuche aktivieren möchten +---------------------------------------------------------- + +Der laufende Index übernimmt das neue Mapping nicht automatisch, daher sind die folgenden +Schritte erforderlich. + +1. Wenden Sie die Einstellungen wie im Abschnitt *Konfigurationsreferenz* auf dieser Seite + beschrieben auf ``system.properties`` an (die konkreten Schritte bei Verwendung des Anbieters + opensearch finden Sie oben unter *Einrichtungsverfahren*). +2. Starten Sie |Fess| neu. +3. Führen Sie in der Admin-Oberfläche unter **Systeminformationen > Wartung** die + **Neuindizierung** mit aktivierter Option **Aliase ersetzen** aus. Dies läuft im Hintergrund + ohne Erfolgsmeldung ab. ``_cat/indices`` zeigt nur, dass der neue Index existiert, nicht ob die + Aliase umgeschaltet wurden — prüfen Sie stattdessen ``_cat/aliases`` und vergewissern Sie sich, + dass ``fess.search``/``fess.update`` auf den neuen Index zeigen (das |Fess|-Log warnt nur bei + einem Fehler, Stille ist also kein Erfolgsnachweis). Der alte Index wird nicht automatisch + gelöscht (entfernen Sie ihn manuell, sobald Sie ihn nicht mehr benötigen); bis dahin verdoppelt + sich in etwa die Index-Festplattennutzung. +4. Erst nachdem Sie den oben genannten Alias-Wechsel bestätigt haben, aktivieren und starten Sie + den Job Content Chunk Vector Indexer unter **System > Scheduler** (ein erneutes Crawlen ist + nicht erforderlich: Der Job liest ``content`` aus der ``_source`` des bestehenden Index, um es + zu chunken und zu embedden). + +.. note:: + + Wenn Sie bereits in Schritt 1 ``content_chunker.search.enabled=true`` setzen, wird zwischen + dem Neustart in Schritt 2 und dem Abschluss von Schritt 4 bei jeder Suche lediglich die + Anfrage eingebettet, ohne dass sich dies in den Ergebnissen niederschlägt. Bei + nutzungsabhängig abgerechneten Anbietern wie ``openai``, ``gemini`` oder ``bedrock`` sollten Sie + ``content_chunker.search.enabled=true`` daher erst nach Abschluss von Schritt 4 setzen und + |Fess| dann neu starten. + +Wenn Sie das Plugin fess-webapp-semantic-search verwendet haben +------------------------------------------------------------------ + +Das Plugin ``fess-webapp-semantic-search``, das die semantische Suche in |Fess| 15.7 und früher +bereitstellte, wurde in 15.10 in den Kern integriert und ist nun **unnötig (veraltet)**. +Zusätzlich zu den oben unter *Bestehende Nutzer, die die Vektorsuche aktivieren möchten* +beschriebenen Schritten müssen Sie außerdem Folgendes tun. + +1. **Plugin entfernen**: Löschen Sie ``fess-webapp-semantic-search-*.jar`` aus + ``app/WEB-INF/plugin/`` (schließen Sie es unter Docker aus ``FESS_PLUGINS`` aus). + +2. **Alte Einstellungen entfernen**: Löschen Sie jede Startoption ``-Dfess.semantic_search.*``. + Wenn Sie außerdem ``-Drank.fusion.searchers=default,semantic`` für das alte Plugin angegeben + hatten, entfernen Sie dies ebenfalls. Wird es beibehalten, schließt es den neuen semantischen + Sucher (``semantic_chunk``) von Rank Fusion aus und protokolliert beim Start eine Warnung. + +3. **Alte Ingest-Pipeline lösen**: Sofern ``-Dfess.semantic_search.pipeline`` konfiguriert war, + trägt das alte Plugin bei der Erstellung des Index ``default_pipeline`` (eine Ingest-Pipeline + für die neuronale Suche) in die Indexeinstellungen ein. **Das Entfernen des Plugins entfernt + die Pipeline nicht** — sie bleibt am Index angehängt und läuft weiter —, sodass Sie sie lösen + müssen, und zwar **vor** der Neuindizierung aus dem Abschnitt *Bestehende Nutzer, die die + Vektorsuche aktivieren möchten*. Der nach der Neuindizierung erstellte neue Index trägt diese + Einstellung nicht mehr, ein späteres Ausführen des Befehls bliebe also wirkungslos. Ermitteln + Sie mit ``_cat/aliases``, auf welches ``fess.`` der Alias ``fess.search`` zeigt, + und geben Sie den konkreten Indexnamen an, nicht den Alias:: + + curl -XPUT "http://localhost:9200/fess./_settings" \ + -H "Content-Type: application/json" -d ' + {"index": {"default_pipeline": "_none"}}' + + Das Lösen der Indexeinstellung entfernt die Ingest-Pipeline selbst nicht aus der Suchmaschine. + Löschen Sie sie separat, wenn Sie sie künftig nicht mehr benötigen:: + + curl -XDELETE "http://localhost:9200/_ingest/pipeline/" + +4. **Neue Einstellungen hinzufügen**: Konfigurieren Sie ``content_chunker.*`` in + ``system.properties`` wie im Abschnitt *Konfigurationsreferenz* auf dieser Seite beschrieben. + Wenn Sie Ihr bestehendes ML-Commons-Modell weiter verwenden, setzen Sie + ``content_chunker.embedding.name=opensearch`` und tragen Sie dessen bestehende ``model_id`` + in ``content_chunker.embedding.opensearch.model.id`` ein. + +5. **Index neu erstellen und Job ausführen**: Das Vektorfeld, das das alte Plugin speicherte + (in der Standardkonfiguration ``content_vector``), und das Feld ``content_chunk_vector``, das + die neue Kernfunktion verwendet, sind unterschiedliche Felder; die alten Vektoren lassen sich + mit der neuen Funktion nicht nutzen. Die Neuindizierung kopiert ``_source`` jedoch unverändert, + sodass die alten Vektoren auch in den neuen Index übernommen werden und dort über das + dynamische Mapping dauerhaft Festplattenspeicher verbrauchen. Wir empfehlen daher, sie **vor** + der Neuindizierung zu entfernen (falls Sie den Feldnamen geändert haben, passen Sie ihn + entsprechend an):: + + curl -XPOST "http://localhost:9200/fess.search/_update_by_query" \ + -H "Content-Type: application/json" -d ' + { + "query": {"exists": {"field": "content_vector"}}, + "script": {"source": "ctx._source.remove(\"content_vector\")"} + }' + + Führen Sie anschließend die **Neuindizierung** unter **Systeminformationen > Wartung** aus und + aktivieren und starten Sie danach den Job Content Chunk Vector Indexer, um die Vektoren neu zu + generieren. + +Hinweise +========== + +Das Embedding-Modell (Dimension) wechseln +-------------------------------------------- + +Um zu einem Embedding-Modell mit einer anderen Dimension zu wechseln, gehen Sie in dieser +Reihenfolge vor. + +1. Löschen Sie die bestehenden, alten Vektoren. Bleiben Vektoren in der alten Dimension bei der + Neuindizierung erhalten, akzeptiert das neue Mapping sie nicht, und die Verarbeitung läuft + weiter, ohne die betroffenen Dokumente in den neuen Index zu kopieren. Da |Fess| nur den + HTTP-Status der Neuindizierung prüft, zeigt die Admin-Oberfläche keinen Fehler an, während + Dokumente verloren gehen:: + + curl -XPOST "http://localhost:9200/fess.search/_update_by_query" \ + -H "Content-Type: application/json" -d ' + { + "query": {"exists": {"field": "content_chunk_status"}}, + "script": {"source": "ctx._source.remove(\"content_chunk_vector\"); ctx._source.remove(\"content_chunk_status\")"} + }' + + .. note:: + + Als Ziel können Sie ebenso gut ``fess.update`` (den Update-Alias, aus dem die + Neuindizierung liest) angeben. Beachten Sie außerdem, dass das Feld ``content`` bei diesem + Vorgang ein Array von Chunks bleibt. Beim nächsten Job-Lauf wird es wieder zusammengefügt + und neu aufgeteilt; ist ``content_chunker.length.overlap`` auf einen Wert ungleich 0 + gesetzt, sind die Überlappungen dabei doppelt enthalten. Wenn Sie das vermeiden möchten, + crawlen Sie die betroffenen Dokumente erneut. + +2. Ändern Sie ``content_chunker.embedding.dimension`` und die Modelleinstellung für Ihren + Anbieter. +3. Erstellen Sie den Index gemäß dem Abschnitt *3. Index neu erstellen (bei Aktivierung auf einer + bestehenden Installation)* unter *Einrichtungsverfahren* neu und führen Sie den Indexer-Job + erneut aus. + +Wechsel zu einem anderen Modell mit gleicher Dimension +--------------------------------------------------------- + +Ändern Sie die Embedding-Modelleinstellung, etwa +``content_chunker.embedding.opensearch.model.id``, auf ein anderes Modell mit derselben +Dimension, akzeptiert |Fess| das ohne Fehler oder Warnung. Geprüft wird nur die Dimension; das +Modell, das die Vektoren erzeugt hat, wird im Index nicht festgehalten. Die gespeicherten +Vektoren stammen dann vom alten Modell und die Abfragevektoren bei der Suche vom neuen; beide +liegen in verschiedenen Vektorräumen, sodass die Relevanz der Suchergebnisse zusammenbricht. +Auch die Verteilung der Kosinus-Ähnlichkeitswerte unterscheidet sich von Modell zu Modell, sodass +ein auf das alte Modell abgestimmtes ``content_chunker.search.min_score`` für das neue Modell zu +streng sein kann und die meisten Ergebnisse abschneidet. + +Um das Modell zu wechseln, setzen Sie das neue Modell, löschen Sie ``content_chunk_vector`` und +``content_chunk_status`` mit demselben ``_update_by_query`` wie in Schritt 1 von *Das +Embedding-Modell (Dimension) wechseln* oben und führen Sie den Indexer-Job erneut aus, um die +Vektoren aller Dokumente neu zu erzeugen (der Index muss nicht neu erstellt werden, weil die +Dimension gleich ist). Haben Sie ``content_chunker.search.min_score`` gesetzt, überprüfen Sie +den Wert mit dem neuen Modell. + +Wenn der Index ohne Dimension erstellt wurde +--------------------------------------------- + +Wird der Index ``fess.search`` erstellt, während ``content_chunker.embedding.dimension`` nicht +gesetzt ist, erhält das Mapping von ``content_chunk_vector`` ohne jede Warnung die Dimension +``768``, und sie lässt sich danach nicht mehr ändern. Führen Sie dann den Indexer-Job aus, lässt +sich die Dimension beim Embedding nicht lesen, was ein Fehler ist, sodass die Dokumente ``fail`` +werden. + +- Hat das verwendete Modell die Dimension ``768``, setzen Sie + ``content_chunker.embedding.dimension=768``. Sie stimmt mit dem Mapping überein, der Index + muss also nicht neu erstellt werden. +- Andernfalls setzen Sie die richtige Dimension. Solange Mapping (``768``) und Einstellung + voneinander abweichen, protokolliert der Indexer-Job einen ERROR und überspringt den Lauf. + Erstellen Sie den Index nach derselben Methode wie in Schritt 3 von *Das Embedding-Modell + (Dimension) wechseln* oben neu. + +In beiden Fällen werden Dokumente, die bereits ``fail`` sind, nicht automatisch erneut +verarbeitet. Erstellen Sie den Index neu, löscht das ``_update_by_query`` in Schritt 1 von *Das +Embedding-Modell (Dimension) wechseln* auch ``content_chunk_status``. Erstellen Sie ihn nicht neu, +setzen Sie ``content_chunker.job.retry_failed`` vorübergehend auf ``true`` und führen Sie den Job +erneut aus. + +Festplattennutzung +--------------------- + +Chunk-Vektoren werden zusätzlich zu den Suchindexstrukturen in ``_source`` vorgehalten, sodass +jedes Dokument zusätzlichen Festplattenspeicher proportional zur Anzahl seiner Chunks +multipliziert mit der Vektordimension verbraucht. Wenn der Festplattenspeicher knapp wird, passen +Sie ``content_chunker.length.chunk_size`` oder ``content_chunker.max_chunks_per_document`` an. + +Nur-Chunk-Modus +------------------ + +Das Setzen von ``content_chunker.embedding.name=none`` führt nur das Chunking durch, ohne +Embedding-Vektoren zu generieren (``content_chunk_status`` wird zu ``chunked``). Damit können Sie +das Chunking bereits durchführen, bevor Ihr Embedding-Anbieter bereit ist; sobald Sie später +einen Anbieter konfigurieren und den Job erneut ausführen, werden für die bereits gespeicherten +Chunks Vektoren generiert, ohne dass diese erneut gechunkt werden. + +Speichereinstellungen für große Korpora +------------------------------------------- + +Die Kind-JVM des Indexer-Jobs wird mit ``jvm.chunk.options`` in ``fess_config.properties`` +gestartet (JVM-Optionen, die standardmäßig ``-Xms128m -Xmx1g`` enthalten). Da +``content_chunker.job.max_documents_per_run`` standardmäßig unbegrenzt ist, hält ein einzelner +Lauf alle ausstehenden Dokument-IDs im Speicher. Eine Dokument-ID ist ein SHA-512-Digest +(128 Zeichen) und belegt im Heap rund 200 Byte; die Chunk-Verarbeitung selbst benötigt zusätzlich +etwa 200–250 MB. Erhöhen Sie daher bei **Korpora ab etwa 1 bis 2 Millionen Dokumenten** den +``-Xmx``-Wert in ``jvm.chunk.options`` oder setzen Sie +``content_chunker.job.max_documents_per_run`` auf einen endlichen Wert, um die Verarbeitung auf +mehrere Läufe aufzuteilen. ``jvm.chunk.options`` überschreiben Sie in +``app/WEB-INF/classes/fess_config.properties`` (bei den RPM/DEB-Paketen +``/etc/fess/fess_config.properties``); siehe :doc:`setup-memory` zum Umgang mit JVM-Optionen. + +Derselbe unbegrenzte Standardwert hat auch Kostenfolgen bei einem nutzungsabhängig abgerechneten +Embedding-Anbieter (``openai``, ``gemini``, ``bedrock``): Der erste Indexer-Lauf embedded den gesamten +vorhandenen Korpus in einem Durchgang und verursacht dafür die gesamten Kosten auf einmal. Setzen +Sie ``content_chunker.job.max_documents_per_run`` auf einen endlichen Wert, um diese Kosten +stattdessen auf mehrere Läufe zu verteilen. + +Referenzen +============ + +- :doc:`rank-fusion` - Konfiguration von Rank Fusion (hybride Suche) +- :doc:`rag-chat` - Konfiguration des KI-Suchmodus +- :doc:`llm-overview` - Übersicht über die LLM-Integration +- :doc:`llm-ollama` - Ollama-Konfiguration +- :doc:`setup-memory` - JVM-Speichereinstellungen +- :doc:`../install/upgrade` - Upgrade-Verfahren diff --git a/de/15.10/config/security-role.rst b/de/15.10/config/security-role.rst new file mode 100644 index 000000000..e1f7080df --- /dev/null +++ b/de/15.10/config/security-role.rst @@ -0,0 +1,72 @@ +==================================== +Konfiguration rollenbasierter Suche +==================================== + +Über rollenbasierte Suche +========================= + +|Fess| kann Suchergebnisse basierend auf den Authentifizierungsinformationen von Benutzern differenzieren, die durch beliebige Authentifizierungssysteme authentifiziert wurden. +Beispielsweise werden für Benutzer A mit Rolle a Suchergebnisse mit Informationen zur Rolle a angezeigt, während Benutzer B ohne Rolle a diese bei der Suche nicht sieht. +Mit dieser Funktion können Sie in Portal- oder Single-Sign-On-Umgebungen eine abteilungs- oder positionsbezogene Suche für angemeldete Benutzer realisieren. + +Bei rollenbasierter Suche in |Fess| können Rolleninformationen aus folgenden Quellen abgerufen werden: + +- Request-Parameter + +- Request-Header + +- Cookie + +- |Fess|-Authentifizierungsinformationen + +Bei Portal- oder Agent-basierten Single-Sign-On-Systemen können Rolleninformationen abgerufen werden, indem bei der Authentifizierung Authentifizierungsinformationen per Cookie für die Domain und den Pfad gespeichert werden, auf dem |Fess| läuft. +Bei Reverse-Proxy-basierten Single-Sign-On-Systemen können Rolleninformationen abgerufen werden, indem beim Zugriff auf |Fess| Authentifizierungsinformationen zu Request-Parametern oder Request-Headern hinzugefügt werden. + +.. note:: + Der Abruf von Rolleninformationen aus Request-Parametern, Request-Headern und Cookies ist standardmäßig deaktiviert. + Wenn Sie diese verwenden möchten, müssen Sie im ``roleQueryHelper``-Komponenten in ``app/WEB-INF/classes/fess.xml`` den zu referenzierenden Schlüsselnamen (``parameterKey``, ``headerKey``, ``cookieKey``), die Verschlüsselung der Werte (``encryptedParameterValue`` usw.) sowie die Trennzeichen (``valueSeparator``, ``roleSeparator``) konfigurieren. + Standardmäßig ist nur die rollenbasierte Suche unter Verwendung der |Fess|-Authentifizierungsinformationen aktiviert. + +Konfiguration rollenbasierter Suche +===================================== + +Hier wird die Konfiguration der rollenbasierten Suche unter Verwendung der |Fess|-Authentifizierungsinformationen erläutert. + +Konfiguration in der |Fess|-Verwaltungsoberfläche +-------------------------------------------------- + +Starten Sie |Fess| und melden Sie sich als Administrator an. +Erstellen Sie Rollen und Benutzer. +Erstellen Sie beispielsweise im Rollen-Verwaltungsbildschirm die Rolle Role1 und legen Sie im Benutzer-Verwaltungsbildschirm einen Benutzer an, der zu Role1 gehört. +Wenn Sie die Zuweisung auf Gruppenebene vornehmen möchten, erstellen Sie im Gruppen-Verwaltungsbildschirm eine Gruppe und weisen Sie den Benutzer der Gruppe zu. + +Tragen Sie anschließend in der Crawl-Konfiguration im Berechtigungsfeld ``{role}Role1`` ein und speichern Sie die Einstellung. +Für benutzerspezifische Angaben verwenden Sie ``{user}username``, für gruppenspezifische Angaben ``{group}groupname``. +Wenn mehrere Berechtigungen angegeben werden sollen, trennen Sie diese durch Zeilenumbrüche. + +Durch das Crawlen mit dieser Crawl-Konfiguration wird ein Index erstellt, der nur für Benutzer durchsuchbar ist, die der angegebenen Rolle, dem Benutzer oder der Gruppe angehören. +Angemeldeten Benutzern werden automatisch die Berechtigungen für ihre eigene Person (``{user}username``), ihre zugehörigen Rollen (``{role}``) und ihre zugehörigen Gruppen (``{group}``) zugewiesen und mit den am Dokument gesetzten Berechtigungen abgeglichen. + +.. note:: + Wenn Sie den Zugriff von bestimmten Rollen, Benutzern oder Gruppen explizit verweigern möchten, fügen Sie ``(deny)`` vor dem Eintrag ein, z. B. ``(deny){role}Role1`` (mit ``(allow)`` wird der Zugriff erlaubt, was dem Standardverhalten ohne Angabe entspricht). + +.. note:: + Bei der Anbindung an LDAP oder Single Sign-On werden die Rollen- und Gruppeninformationen des Benutzers vom Authentifizierungsanbieter abgerufen und ebenfalls als Berechtigungen behandelt. + Das Verhalten bei der LDAP-Integration kann über ``ldap.role.search.user.enabled``, ``ldap.role.search.group.enabled`` und ``ldap.role.search.role.enabled`` in ``fess_config.properties`` gesteuert werden (Standardwert jeweils ``true``). + +Anmeldung +--------- + +Melden Sie sich von der Verwaltungsoberfläche ab. +Melden Sie sich mit einem Benutzer an, der zu Role1 gehört. +Bei erfolgreicher Anmeldung werden Sie zur Startseite des Suchbildschirms weitergeleitet. + +Bei einer normalen Suche werden nur Ergebnisse angezeigt, für die in der Crawl-Konfiguration die Rolle Role1 gesetzt wurde. + +Suchanfragen ohne Anmeldung werden als Suche des Gastbenutzers (guest) ausgeführt. +Für Dokumente, die auch nicht angemeldeten Benutzern angezeigt werden sollen, tragen Sie im Berechtigungsfeld der Crawl-Konfiguration ``{role}guest`` ein (der Standardwert ist unter ``role.search.guest.permissions`` definiert). + +Abmeldung +--------- + +Wenn Sie mit einem anderen Benutzer als dem Administrator angemeldet sind, können Sie sich im Suchbildschirm über die Abmelden-Option abmelden. diff --git a/de/15.10/config/security-virtual-host.rst b/de/15.10/config/security-virtual-host.rst new file mode 100644 index 000000000..53eb1aa19 --- /dev/null +++ b/de/15.10/config/security-virtual-host.rst @@ -0,0 +1,91 @@ +================ +Virtueller Host +================ + +Über virtuelle Hosts +==================== + +|Fess| kann Suchergebnisse basierend auf dem Hostnamen (dem Wert des HTTP-``Host``-Headers) differenzieren, mit dem auf |Fess| zugegriffen wird. +Ein einzelner |Fess|-Server kann unter mehreren Hostnamen veröffentlicht werden, wobei je nach Hostname unterschiedliche Suchziele (Crawl-Konfigurationen) und Seitendesigns bereitgestellt werden können. +Auch der Suchbildschirm kann für jeden Host anders aussehen: Für einen Host wird das statische Theme verwendet, dessen Name mit dem virtuellen Hostnamen übereinstimmt. + +Die Funktion für virtuelle Hosts ist standardmäßig deaktiviert (nicht konfiguriert). Die Einrichtung erfolgt mit den folgenden Schritten. + +Systemkonfiguration +------------------- + +Konfigurieren Sie unter :doc:`Administratorhandbuch > Allgemeine Einstellungen <../admin/general-guide>` im Abschnitt „Virtueller Host" die Zuordnung zwischen dem Hostnamen der Anfrage und dem virtuellen Hostnamen. Geben Sie den hier konfigurierten virtuellen Hostnamen in der Crawl-Konfiguration an. + +**Format** + +Tragen Sie einen virtuellen Host pro Zeile im folgenden Format ein: + +:: + + Headername:Headerwert=VirtuellerHostname + +.. list-table:: + + * - *Headername* + - Name des HTTP-Request-Headers, der für die Auswertung verwendet wird. Normalerweise wird ``Host`` angegeben. Bei Zugriffen über einen Reverse-Proxy kann auch ``X-Forwarded-Host`` angegeben werden. + * - *Headerwert* + - Der im obigen Header enthaltene Hostname (bei Bedarf im Format ``Hostname:Portnummer``). Wenn der vom Client beim Zugriff gesendete Headerwert vollständig übereinstimmt (Groß-/Kleinschreibung wird nicht berücksichtigt), wird dieser virtuelle Host angewendet. + * - *VirtuellerHostname* + - Virtueller Hostname, der in der Crawl-Konfiguration angegeben wird + +**Beispiel** + +:: + + Host:abc.example.com=host1 + Host:192.168.1.123:8080=host2 + +.. note:: + + Die Auswertung erfolgt nicht durch Namensauflösung (DNS), sondern durch Zeichenkettenvergleich mit dem Wert des Request-Headers. + Der vom Browser gesendete ``Host``-Header enthält bei Standardports (HTTP: 80, HTTPS: 443) keine Portnummer; bei anderen Ports wird die Portnummer im Format ``Hostname:Portnummer`` mitgesendet. + Wenn der Dienst daher über einen Nicht-Standardport erreichbar ist, muss die Portnummer explizit angegeben werden, z. B. ``Host:abc.example.com:8080=host1``. + +.. note:: + + Für virtuelle Hostnamen können nur alphanumerische Zeichen und Unterstriche ( ``a-z`` , ``A-Z`` , ``0-9`` , ``_`` ) verwendet werden. + Andere Zeichen werden automatisch entfernt. + + Die folgenden Namen sind reserviert und können nicht als virtuelle Hostnamen verwendet werden: + ``admin`` , ``common`` , ``error`` , ``login`` , ``profile`` + +Seitendesign pro virtuellem Host +-------------------------------- + +Um einem virtuellen Host einen eigenen Suchbildschirm zu geben, installieren Sie ein statisches Theme, dessen ``name`` in ``theme.yml`` der virtuelle Hostname in Kleinbuchstaben ist (zum Beispiel ``host1``). +Eine Anfrage, die dem virtuellen Host entspricht, wird mit diesem Theme ausgeliefert; jede andere Anfrage mit dem Standardtheme. +Das Theme muss nicht als Standard festgelegt werden. Wie Sie ein Theme aus dem mitgelieferten erstellen, lesen Sie unter :ref:`theme-customize-bundled`; wie Sie es installieren, unter :doc:`../admin/theme-guide`. + +.. note:: + + Seit |Fess| 15.10 werden beim Speichern der Konfiguration keine JSPs mehr unter ``WEB-INF/view/VirtuellerHostname`` generiert. + Der Anmeldebildschirm (``/login/``) ist für alle virtuellen Hosts derselbe (``WEB-INF/view/admin/login/``) und kann nicht pro virtuellem Host geändert werden. + Ein eigenes Aussehen pro virtuellem Host erhalten Sie, wie oben beschrieben, mit einem statischen Theme, das nach dem virtuellen Host benannt ist. + + +Crawl-Konfiguration +------------------- + +Geben Sie „Virtueller Host" in der Web-Crawl-Konfiguration, der Datei-Crawl-Konfiguration oder der Datenspeicher-Crawl-Konfiguration an. +Unter „Virtueller Host" wird einer der in der Systemkonfiguration definierten virtuellen Hostnamen angegeben. Einer Crawl-Konfiguration können auch mehrere virtuelle Hosts zugewiesen werden (ein Eintrag pro Zeile). + +Suchanfragen, die über einen virtuellen Host eingehen, zeigen ausschließlich Dokumente aus den Crawl-Konfigurationen an, denen dieser virtuelle Host zugewiesen ist. +Bei Zugriffen, die keinem virtuellen Host entsprechen (normaler Zugriff ohne konfigurierte virtuelle Hosts), wird diese Einschränkung nicht angewendet, und alle Suchergebnisse werden wie gewohnt angezeigt. + +**Beispiel** + +.. list-table:: + + * - *Virtueller Host* + - ``host1`` + + +Benutzer-Tags +------------- + +Auch die Tags, die angemeldete Benutzer an Suchergebnisse vergeben (Meine Tags), folgen dem virtuellen Host, wenn die Tag-Funktion aktiviert ist. Ein auf einem virtuellen Host erstelltes Tag wird nur auf diesem virtuellen Host aufgelistet und kann nur dort verwendet werden. Eine Anfrage, die zu keinem virtuellen Host passt, sieht alle Tags. Ein Tag mit virtuellem Host wird nur an die Dokumente der Crawl-Einstellungen vergeben, die diesen virtuellen Host haben. Weitere Informationen finden Sie unter :doc:`../admin/tagtype-guide` und :doc:`../api/api-tag`. diff --git a/de/15.10/config/setup-memory.rst b/de/15.10/config/setup-memory.rst new file mode 100644 index 000000000..a8df6f235 --- /dev/null +++ b/de/15.10/config/setup-memory.rst @@ -0,0 +1,440 @@ +============ +Speicherkonfiguration +============ + +Übersicht +==== + +Java-Anwendungen erfordern die Konfiguration des maximalen Heap-Speichers pro Prozess. +Bei |Fess| werden Speichereinstellungen für die folgenden drei Komponenten separat konfiguriert. + +- Fess-Webanwendung +- Crawler-Prozess +- OpenSearch + +Durch angemessene Speicherkonfiguration können Leistungsverbesserungen und stabiler Betrieb erreicht werden. + +Speicherkonfiguration der Fess-Webanwendung +====================================== + +Situationen, in denen Konfiguration erforderlich ist +---------------- + +Erwägen Sie die Anpassung der Speichergröße in folgenden Fällen: + +- OutOfMemory-Fehler werden in ``fess.log`` aufgezeichnet +- Hohe Anzahl gleichzeitiger Zugriffe muss verarbeitet werden +- Verwaltungsoberfläche ist langsam oder läuft in einen Timeout + +Die Standardspeichergröße ist für normale Nutzung ausreichend, aber in Umgebungen mit hoher Last ist eine Erhöhung erforderlich. + +Konfiguration über Umgebungsvariablen +------------------ + +Setzen Sie die Umgebungsvariable ``FESS_HEAP_SIZE``. + +:: + + export FESS_HEAP_SIZE=2g + +Einheiten: + +- ``m``: Megabyte +- ``g``: Gigabyte + +Detaillierte Speichersteuerung +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``FESS_HEAP_SIZE`` setzt ``-Xms`` und ``-Xmx`` auf denselben Wert. Um die anfängliche und maximale Heap-Größe unabhängig zu steuern, verwenden Sie die Umgebungsvariablen ``FESS_MIN_MEM`` und ``FESS_MAX_MEM``. + +:: + + export FESS_MIN_MEM=256m + export FESS_MAX_MEM=2g + +.. list-table:: Standard-Speichereinstellungen nach Plattform + :header-rows: 1 + :widths: 30 35 35 + + * - Plattform + - FESS_MIN_MEM (Standard) + - FESS_MAX_MEM (Standard) + * - Linux + - 256m + - 2g + * - Windows + - 256m + - 1g + +.. note:: + Wenn ``FESS_HEAP_SIZE`` gesetzt ist, werden ``FESS_MIN_MEM`` und ``FESS_MAX_MEM`` ignoriert. + +.. note:: + Bei den RPM/DEB-Paketen setzt die Umgebungsdatei (``/etc/sysconfig/fess``, bei DEB ``/etc/default/fess``) ``FESS_HEAP_SIZE=512m``. Der Heap ist daher auf 512m festgelegt und nicht auf die Standardwerte der obigen Tabelle. Um die Heap-Größe zu ändern, passen Sie diesen Wert von ``FESS_HEAP_SIZE`` an. + +Bei RPM/DEB-Paketen +------------------------ + +Bei Installation über RPM-Paket bearbeiten Sie ``/etc/sysconfig/fess``. + +:: + + FESS_HEAP_SIZE=2g + +Bei DEB-Paketen bearbeiten Sie ``/etc/default/fess``. + +:: + + FESS_HEAP_SIZE=2g + +.. warning:: + Nach Änderung der Speichergröße muss der |Fess|-Dienst neu gestartet werden. + +Empfohlene Speichergrößen +---------------- + +.. list-table:: + :header-rows: 1 + :widths: 30 30 40 + + * - Umgebung + - Empfohlene Heap-Größe + - Anmerkungen + * - Entwicklungs-/Testumgebung + - 512m–1g + - Kleine Indizes + * - Kleine Produktionsumgebung + - 1g–2g + - Zehntausende bis hunderttausende Dokumente + * - Mittlere Produktionsumgebung + - 2g–4g + - Hunderttausende bis Millionen Dokumente + * - Große Produktionsumgebung + - 4g–8g + - Mehrere Millionen Dokumente + +Speicherkonfiguration des Crawlers +====================== + +Situationen, in denen Konfiguration erforderlich ist +---------------- + +In folgenden Fällen muss die Speichergröße des Crawlers erhöht werden: + +- Bei Erhöhung der Anzahl paralleler Crawls +- Beim Crawlen großer Dateien +- Bei Auftreten von OutOfMemory-Fehlern während der Crawler-Ausführung + +Konfigurationsmethode +-------- + +Bearbeiten Sie ``app/WEB-INF/classes/fess_config.properties`` oder ``/etc/fess/fess_config.properties``. + +``jvm.crawler.options`` ist eine einzelne Einstellung, die die JVM-Optionen des Crawler-Prozesses durch Zeilenumbrüche (``\n``) getrennt auflistet. Beim Ändern des Werts werden alle Standardoptionen ersetzt. Wenn Sie nur ``-Xmx512m`` schreiben, gehen daher auch die übrigen Standardoptionen verloren, etwa ``-Dfile.encoding=UTF-8`` und die G1GC-Einstellungen. Behalten Sie den in ``fess_config.properties`` aufgeführten Standardwert bei und ändern Sie nur die Zeilen zur Heap-Größe. + +Um beispielsweise den maximalen Heap auf 1 GB zu ändern, ändern Sie die Zeile ``-Xmx512m`` des Standardwerts wie folgt. + +:: + + -Xms128m\n\ + -Xmx1g\n\ + +.. note:: + Diese Einstellung wird pro Crawler-Prozess (pro Scheduler-Job) angewendet. + Bei gleichzeitiger Ausführung mehrerer Crawler-Jobs wird für jeden Job der angegebene Speicher verwendet. + +Empfohlene Einstellungen +-------- + +- **Normales Web-Crawling**: 512m–1g +- **Massiv paralleles Crawling**: 1g–2g +- **Crawlen großer Dateien**: 2g–4g + +Detaillierte JVM-Optionen +------------------ + +Detaillierte JVM-Optionen für den Crawler können über ``jvm.crawler.options`` konfiguriert werden. +Die Standardkonfiguration umfasst folgende Optimierungen: + +**Hauptoptionen:** + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - Option + - Beschreibung + * - ``-Xms128m -Xmx512m`` + - Initiale und maximale Heap-Größe + * - ``-XX:MaxMetaspaceSize=128m`` + - Maximale Metaspace-Größe + * - ``-XX:+UseG1GC`` + - Verwendung des G1-Garbage-Collectors + * - ``-XX:MaxGCPauseMillis=60000`` + - Maximales GC-Pausenzeit-Ziel (60 Sekunden) – ein bewusst lockeres Ziel für Crawler-Workloads (typischer Standardwert ~200 ms) + * - ``-XX:-HeapDumpOnOutOfMemoryError`` + - Deaktivierung von Heap-Dumps bei OutOfMemory + +Speicherkonfiguration von OpenSearch +======================= + +Wichtige Überlegungen +-------------- + +Bei OpenSearch müssen folgende zwei Punkte für die Speicherkonfiguration berücksichtigt werden: + +1. **Java-Heap-Speicher**: Verwendet vom OpenSearch-Prozess +2. **OS-Dateisystem-Cache**: Wichtig für Such-Performance + +.. warning:: + Wenn der Java-Heap-Speicher zu groß eingestellt wird, verringert sich + der für den OS-Dateisystem-Cache verfügbare Speicher, + was die Such-Performance beeinträchtigt. + +Konfigurationsmethode +-------- + +Linux-Umgebungen +~~~~~~~~~ + +Der Heap-Speicher von OpenSearch wird über die OpenSearch-Konfigurationsdatei ``config/jvm.options`` angegeben. + +Bearbeiten Sie ``config/jvm.options``: + +:: + + -Xms2g + -Xmx2g + +.. note:: + Es wird empfohlen, die minimale Heap-Größe (``-Xms``) und die maximale Heap-Größe (``-Xmx``) auf denselben Wert zu setzen. + +.. note:: + Die Umgebungsvariable ``OPENSEARCH_HEAP_SIZE`` ist in OpenSearch 3.x veraltet (deprecated). Verwenden Sie stattdessen ``config/jvm.options`` oder die Umgebungsvariable ``OPENSEARCH_JAVA_OPTS``: + + :: + + export OPENSEARCH_JAVA_OPTS="-Xms2g -Xmx2g" + +Windows-Umgebungen +~~~~~~~~~~~ + +Bearbeiten Sie die Datei ``config\jvm.options``. + +:: + + -Xms2g + -Xmx2g + +Empfohlene Speichergrößen +---------------- + +.. list-table:: + :header-rows: 1 + :widths: 30 30 40 + + * - Indexgröße + - Empfohlene Heap-Größe + - Empfohlener Gesamtspeicher + * - ~10 GB + - 2g + - 4 GB oder mehr + * - 10 GB–50 GB + - 4g + - 8 GB oder mehr + * - 50 GB–100 GB + - 8g + - 16 GB oder mehr + * - Über 100 GB + - 16g–31g + - 32 GB oder mehr + +.. warning:: + Der Heap-Speicher von OpenSearch sollte 32 GB nicht überschreiten. + Bei über 32 GB wird Compressed OOP deaktiviert und die Speichereffizienz nimmt ab. + +Best Practices +------------------ + +1. **50% des physischen Speichers dem Heap zuweisen** + + Weisen Sie etwa 50% des physischen Speichers des Servers dem OpenSearch-Heap zu. + Der Rest wird für OS und Dateisystem-Cache verwendet. + +2. **Maximum von 31 GB** + + Die Heap-Größe sollte maximal 31 GB betragen. Bei höherem Bedarf sollten zusätzliche Knoten hinzugefügt werden. + +3. **Überprüfung in Produktionsumgebungen** + + Konsultieren Sie die offizielle OpenSearch-Dokumentation für optimale umgebungsspezifische Einstellungen. + +Speicherkonfiguration für Vorschlag- und Thumbnail-Verarbeitung +====================================== + +Vorschlags-Generierungsprozess +---------------------- + +Die Speicherkonfiguration für die Vorschlags-Generierung wird über ``jvm.suggest.options`` konfiguriert. + +Wie beim Crawler enthält diese Einstellung alle Standardoptionen. Ändern Sie daher nur die Zeile ``-Xmx256m`` und behalten Sie die übrigen bei. + +Standardmäßig werden folgende Einstellungen verwendet: + +- Initialer Heap: 128 MB +- Maximaler Heap: 256 MB +- Maximaler Metaspace: 128 MB + +Thumbnail-Generierungsprozess +---------------------- + +Die Speicherkonfiguration für die Thumbnail-Generierung wird über ``jvm.thumbnail.options`` konfiguriert. + +Wie beim Crawler enthält diese Einstellung alle Standardoptionen. Ändern Sie daher nur die Zeile ``-Xmx256m`` und behalten Sie die übrigen bei. + +Standardmäßig werden folgende Einstellungen verwendet: + +- Initialer Heap: 128 MB +- Maximaler Heap: 256 MB +- Maximaler Metaspace: 128 MB + +.. note:: + Bei der Verarbeitung großer Bilder für die Thumbnail-Generierung muss der Speicher erhöht werden. + +Speicherüberwachung und -Tuning +======================== + +Überprüfung der Speichernutzung +-------------------- + +Speichernutzung von Fess +~~~~~~~~~~~~~~~~~~~~~ + +Kann in der Verwaltungsoberfläche unter „Systeminformationen" überprüft werden. + +Oder verwenden Sie JVM-Überwachungstools: + +:: + + jps -l # Fess-Prozesse anzeigen + jstat -gcutil 1000 # GC-Statistiken jede Sekunde anzeigen + +Speichernutzung von OpenSearch +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + curl -X GET "localhost:9200/_nodes/stats/jvm?pretty" + curl -X GET "localhost:9200/_cat/nodes?v&h=heap.percent,ram.percent" + +Anzeichen von Speichermangel +---------------- + +Bei folgenden Symptomen besteht möglicherweise Speichermangel. + +**Fess-Webanwendung:** + +- Langsame Antwortzeiten +- ``OutOfMemoryError`` in Protokollen aufgezeichnet +- Prozess beendet sich unerwartet + +**Crawler:** + +- Crawling stoppt mittendrin +- ``OutOfMemoryError`` in ``fess-crawler.log`` aufgezeichnet +- Crawlen großer Dateien schlägt fehl + +**OpenSearch:** + +- Langsame Suche +- Langsame Indexerstellung +- ``circuit_breaker_exception``-Fehler treten auf + +Tuning-Verfahren +---------------- + +1. **Aktuelle Speichernutzung überprüfen** + + Überwachen Sie die Speichernutzung jeder Komponente. + +2. **Engpass identifizieren** + + Identifizieren Sie, welche Komponente Speichermangel hat. + +3. **Schrittweise erhöhen** + + Erhöhen Sie nicht auf einmal stark, sondern in Schritten von 25–50% und überprüfen Sie die Wirkung. + +4. **Gesamtsystembalance berücksichtigen** + + Stellen Sie sicher, dass die Gesamtsumme des Speichers aller Komponenten den physischen Speicher nicht überschreitet. + +5. **Kontinuierliche Überwachung** + + Überwachen Sie kontinuierlich die Speichernutzung und passen Sie bei Bedarf an. + +Maßnahmen gegen Speicherlecks +---------------- + +Bei Verdacht auf Speicherlecks: + +1. **Heap-Dump erstellen** + +:: + + jmap -dump:format=b,file=heap.bin + +2. **Heap-Dump analysieren** + + Analysieren Sie mit Tools wie Eclipse Memory Analyzer (MAT). + +3. **Problem melden** + + Wenn Sie ein Speicherleck entdecken, melden Sie es bitte über GitHub Issues. + +Fehlersuche +====================== + +OutOfMemoryError tritt auf +--------------------------- + +**Fess-Webanwendung:** + +1. Erhöhen Sie ``FESS_HEAP_SIZE``. +2. Beschränken Sie die Anzahl gleichzeitiger Zugriffe. +3. Senken Sie den Log-Level, um Speichernutzung durch Protokollierung zu reduzieren. + +**Crawler:** + +1. Erhöhen Sie ``-Xmx`` in ``jvm.crawler.options``. +2. Reduzieren Sie die Anzahl paralleler Crawls. +3. Passen Sie die Crawler-Konfiguration an, um große Dateien auszuschließen. + +**OpenSearch:** + +1. Erhöhen Sie die Heap-Größe (bis maximal 31 GB). +2. Überprüfen Sie die Anzahl der Index-Shards. +3. Überprüfen Sie die Komplexität der Abfragen. + +Lange Pausenzeiten durch GC +---------------------- + +1. Passen Sie die G1GC-Einstellungen an. +2. Konfigurieren Sie die Heap-Größe angemessen (sowohl zu groß als auch zu klein führt zu häufigen GCs). +3. Erwägen Sie ein Update auf eine neuere Java-Version. + +Leistung verbessert sich nicht trotz Speicherkonfiguration +------------------------------ + +1. Überprüfen Sie andere Ressourcen wie CPU, Disk-I/O, Netzwerk. +2. Führen Sie eine Indexoptimierung durch. +3. Überprüfen Sie Abfragen und Crawler-Konfigurationen. + +Referenzinformationen +======== + +- :doc:`setup-port-network` - Port- und Netzwerkkonfiguration +- :doc:`crawler-advanced` - Erweiterte Crawler-Konfiguration +- :doc:`admin-logging` - Protokollkonfiguration +- `OpenSearch Memory Settings `_ +- `Java GC Tuning `_ diff --git a/de/15.10/config/setup-port-network.rst b/de/15.10/config/setup-port-network.rst new file mode 100644 index 000000000..ff7115906 --- /dev/null +++ b/de/15.10/config/setup-port-network.rst @@ -0,0 +1,471 @@ +====================== +Port- und Netzwerkkonfiguration +====================== + +Übersicht +==== + +Dieser Abschnitt beschreibt die netzwerkbezogenen Konfigurationen von |Fess|. +Er behandelt Einstellungen für Netzwerkverbindungen wie Änderungen der Portnummer, Proxy-Konfiguration und HTTP-Kommunikationseinstellungen. + +Konfiguration der verwendeten Ports +================ + +Standard-Ports +---------------- + +|Fess| verwendet standardmäßig die folgenden Ports. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Dienst + - Portnummer + * - Fess-Webanwendung + - 8080 + * - OpenSearch (HTTP) + - 9200 + * - OpenSearch (Transport) + - 9300 + +Ändern des Ports der Fess-Webanwendung +-------------------------------------- + +Konfiguration in Linux-Umgebungen +~~~~~~~~~~~~~~~~~ + +Um die Portnummer in Linux-Umgebungen zu ändern, bearbeiten Sie ``bin/fess.in.sh``. + +:: + + FESS_JAVA_OPTS="$FESS_JAVA_OPTS -Dfess.port=8080" + +Beispiel für die Verwendung von Port 80: + +:: + + FESS_JAVA_OPTS="$FESS_JAVA_OPTS -Dfess.port=80" + +.. note:: + Für die Verwendung von Portnummern unter 1024 sind Root-Rechte oder entsprechende Berechtigungen (CAP_NET_BIND_SERVICE) erforderlich. + +Konfiguration über Umgebungsvariablen +~~~~~~~~~~~~~~~~~~ + +Sie können die Portnummer auch über eine Umgebungsvariable angeben. + +:: + + export FESS_PORT=8080 + +.. warning:: + Die Umgebungsvariable ``FESS_PORT`` ist nur unter Linux verfügbar. Unter Windows bearbeiten Sie ``-Dfess.port`` direkt in ``bin\fess.in.bat``. + +Bei RPM/DEB-Paketen +~~~~~~~~~~~~~~~~~~~~~~~~ + +Bei RPM-Paketen bearbeiten Sie ``/etc/sysconfig/fess``, bei DEB-Paketen ``/etc/default/fess``. + +:: + + FESS_PORT=8080 + +Konfiguration in Windows-Umgebungen +~~~~~~~~~~~~~~~~~~~ + +In Windows-Umgebungen bearbeiten Sie ``bin\fess.in.bat``. + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.port=8080 + +Bei Registrierung als Windows-Dienst +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Wenn Sie |Fess| in einer Windows-Umgebung als Dienst registrieren und verwenden möchten, ändern Sie bitte auch die Portkonfiguration in ``bin\service.bat``. +Weitere Informationen finden Sie unter :doc:`setup-windows-service`. + +Konfiguration des Kontextpfads +---------------------- + +Wenn Sie |Fess| in einem Unterverzeichnis veröffentlichen möchten, können Sie einen Kontextpfad konfigurieren. + +**Linux:** + +:: + + export FESS_CONTEXT_PATH=/search + +**Windows:** + +Bearbeiten Sie ``bin\fess.in.bat``: + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.context.path=/search + +Mit dieser Einstellung wird der Zugriff unter ``http://localhost:8080/search/`` möglich. + +.. warning:: + Die Umgebungsvariable ``FESS_CONTEXT_PATH`` ist nur unter Linux verfügbar. Unter Windows bearbeiten Sie ``-Dfess.context.path`` direkt in ``bin\fess.in.bat``. + +.. warning:: + Wenn Sie den Kontextpfad ändern, müssen Sie auch die Pfade für statische Dateien entsprechend konfigurieren. + +Proxy-Konfiguration +============ + +Übersicht +---- + +Beim Crawlen externer Websites aus einem Intranet oder beim Zugriff auf externe APIs kann die Kommunikation durch eine Firewall blockiert werden. +In solchen Umgebungen ist eine Konfiguration für die Kommunikation über einen Proxy-Server erforderlich. + +Proxy-Konfiguration für den Crawler +-------------------------- + +Grundkonfiguration +~~~~~~~~ + +Geben Sie in den Crawl-Einstellungen in der Verwaltungsoberfläche die folgenden Konfigurationsparameter an. + +:: + + client.proxyHost=proxy.example.com + client.proxyPort=8080 + +Konfiguration eines Proxys mit Authentifizierung +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Wenn der Proxy-Server eine Authentifizierung erfordert, fügen Sie Folgendes hinzu. + +:: + + client.proxyHost=proxy.example.com + client.proxyPort=8080 + client.proxyUsername=proxyuser + client.proxyPassword=proxypass + +Ausschluss bestimmter Hosts vom Proxy +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Die Crawler-Proxy-Einstellungen unterstützen nonProxyHosts nicht. +Um bestimmte Hosts vom Proxy auszuschließen, verwenden Sie die Umgebungsvariable ``FESS_NON_PROXY_HOSTS``. +Diese Einstellung wird in die Java-Systemeigenschaft ``http.nonProxyHosts`` umgewandelt und gilt für die gesamte HTTP-Kommunikation von Fess. + +:: + + FESS_NON_PROXY_HOSTS=localhost|*.local|192.168.* + +Standard-Proxy-Konfiguration für den Crawler +------------------------------ + +Um einen Standard-Proxy festzulegen, wenn ``client.proxyHost`` nicht in den einzelnen Crawl-Konfigurationen angegeben ist, konfigurieren Sie dies in ``fess_config.properties``. +Diese Einstellung gilt für den Standard-Proxy des Crawlers sowie für die HTTP-Kommunikation der LLM-Integration und für Plugin-Downloads. +Sie gilt jedoch nicht für die Kommunikation einiger Java-Bibliotheken wie der SSO-Authentifizierung. +Um einen Proxy für die gesamte Fess-Anwendung (einschließlich SSO-Authentifizierung) anzuwenden, verwenden Sie die weiter unten beschriebenen Umgebungsvariablen (``FESS_PROXY_HOST`` usw.). + +:: + + http.proxy.host=proxy.example.com + http.proxy.port=8080 + http.proxy.username=proxyuser + http.proxy.password=proxypass + +.. warning:: + Passwörter werden unverschlüsselt gespeichert. Setzen Sie entsprechende Dateiberechtigungen. + +.. note:: + Die Einstellungen ``http.proxy.*`` gelten nicht für die SSO-Authentifizierung usw. + Um einen Proxy für die gesamte Fess-Anwendung einschließlich SSO-Authentifizierung (JVM-weite HTTP-Kommunikation) zu verwenden, setzen Sie die Umgebungsvariablen ``FESS_PROXY_HOST`` und ``FESS_PROXY_PORT``. + Einzelheiten siehe „Proxy-Konfiguration über Umgebungsvariablen" weiter unten. + +Proxy-Konfiguration über Umgebungsvariablen +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Wenn Java-Bibliotheken wie SSO-Authentifizierung einen Proxy verwenden müssen, müssen Sie ihn über Umgebungsvariablen konfigurieren. +Diese Umgebungsvariablen werden in Java-Systemeigenschaften (``http.proxyHost``, ``https.proxyHost`` usw.) umgewandelt. + +:: + + FESS_PROXY_HOST=proxy.example.com + FESS_PROXY_PORT=8080 + FESS_NON_PROXY_HOSTS=localhost|*.local|192.168.* + +Für RPM-Pakete konfigurieren Sie in ``/etc/sysconfig/fess``. Für DEB-Pakete konfigurieren Sie in ``/etc/default/fess``. + +.. note:: + Die Einstellungen ``http.proxy.*`` in ``fess_config.properties`` werden für den Standard-Proxy des Crawlers sowie für die LLM-Integration und Plugin-Downloads verwendet. + Um einen Proxy für die gesamte Fess-Anwendung einschließlich SSO-Authentifizierung (JVM-weite HTTP-Kommunikation) zu verwenden, setzen Sie die oben genannten Umgebungsvariablen. + +HTTP-Kommunikationseinstellungen +============ + +Beschränkung von Datei-Uploads +-------------------------- + +Sie können die Größe von Datei-Uploads über die Verwaltungsoberfläche beschränken. + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - Konfigurationselement + - Beschreibung + * - ``http.fileupload.max.size`` + - Maximale Datei-Upload-Größe (Standard: 262144000 Bytes = 250 MB) + * - ``http.fileupload.threshold.size`` + - Schwellenwertgröße für die Speicherung im Arbeitsspeicher (Standard: 262144 Bytes = 256 KB) + * - ``http.fileupload.max.file.count`` + - Anzahl der Dateien, die gleichzeitig hochgeladen werden können (Standard: 10) + +Konfigurationsbeispiel in ``fess_config.properties``: + +:: + + http.fileupload.max.size=524288000 + http.fileupload.threshold.size=524288 + http.fileupload.max.file.count=20 + +OpenSearch-Verbindungseinstellungen +------------------------------------ + +Sie können die OpenSearch-Verbindungs-URL und das Intervall der Integritätsprüfung (Heartbeat) konfigurieren. + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - Konfigurationselement + - Beschreibung + * - ``search_engine.http.url`` + - OpenSearch-URL (Standard: http://localhost:9200). Die Umgebungsvariable ``SEARCH_ENGINE_HTTP_URL`` hat Vorrang (siehe unten). + * - ``search_engine.heartbeat_interval`` + - Intervall für Gesundheitsprüfungen (Millisekunden, Standard: 10000) + +Ändern der OpenSearch-Verbindung +---------------------- + +Die URL, zu der |Fess| sich verbindet, legen Sie mit der Umgebungsvariablen +``SEARCH_ENGINE_HTTP_URL`` fest. Sie hat Vorrang vor ``search_engine.http.url`` +in ``fess_config.properties``. ``bin/fess.in.sh`` des ZIP-Pakets und die +Umgebungsdatei der RPM/DEB-Pakete setzen diese Variable standardmäßig auf +``http://localhost:9200``. Eine Änderung von ``search_engine.http.url`` ändert +das Verbindungsziel daher nicht. + +Wo Sie sie setzen, hängt von der Installationsart ab: + +- ZIP-Paket: Bearbeiten Sie die Zeile ``SEARCH_ENGINE_HTTP_URL`` in + ``bin/fess.in.sh``, oder exportieren Sie ``SEARCH_ENGINE_HTTP_URL`` in der + Umgebung, in der |Fess| gestartet wird (siehe :doc:`../install/install-linux`). +- RPM/DEB-Paket: ``SEARCH_ENGINE_HTTP_URL`` in ``/etc/sysconfig/fess`` (RPM) + oder ``/etc/default/fess`` (DEB). +- Docker: die Container-Umgebungsvariable ``SEARCH_ENGINE_HTTP_URL`` (siehe + :doc:`../install/install-docker`). +- ZIP-Paket unter Windows: die Zeile ``-Dfess.search_engine.http_address`` in + ``bin\fess.in.bat`` (siehe :doc:`../install/install-windows`). + +:: + + SEARCH_ENGINE_HTTP_URL=http://opensearch-cluster.example.com:9200 + +Verbindung zu mehreren Knoten +~~~~~~~~~~~~~~~~~~ + +Um eine Verbindung zu mehreren OpenSearch-Knoten herzustellen, trennen Sie die +URLs durch Kommas. Sind einige der Knoten ausgefallen, verbindet sich |Fess| mit +den übrigen. + +:: + + SEARCH_ENGINE_HTTP_URL=http://node1:9200,http://node2:9200,http://node3:9200 + +Konfiguration von SSL/TLS-Verbindungen +----------------- + +Für HTTPS-Verbindungen zu OpenSearch geben Sie auf dieselbe Weise wie oben eine +``https://``-URL an: + +:: + + SEARCH_ENGINE_HTTP_URL=https://opensearch.example.com:9200 + +Das CA-Zertifikat und die Anmeldedaten legen Sie in ``fess_config.properties`` +fest: + +:: + + search_engine.http.ssl.certificate_authorities=/path/to/ca.crt + search_engine.username=admin + search_engine.password=admin_password + +.. note:: + Für die Zertifikatsvalidierung geben Sie den Pfad zum CA-Zertifikat unter ``certificate_authorities`` an. + +Konfiguration virtueller Hosts +============== + +Übersicht +---- + +|Fess| kann Suchergebnisse basierend auf dem Hostnamen, über den darauf zugegriffen wird, unterschiedlich darstellen. +Weitere Informationen finden Sie unter :doc:`security-virtual-host`. + +Grundkonfiguration +------------------ + +Konfigurieren Sie virtuelle Hosts über die Verwaltungsoberfläche „System > Allgemein" (``virtual.host.headers``). +Geben Sie pro Zeile einen virtuellen Host im Format ``Host:Hostname[:Port]=VirtualHostName`` an. +Der Standardwert ist leer (nicht gesetzt), und die Funktion für virtuelle Hosts ist deaktiviert. + +:: + + Host:search1.example.com=site1 + Host:search2.example.com=site2 + +.. note:: + Der Wert von ``virtual.host.headers`` ist KEINE Liste von Header-Namen wie ``X-Forwarded-Host,Host``. + Jede Zeile beschreibt eine Zuordnung in der Form ``Header-Name:Header-Wert=VirtualHostName``. + Einzelheiten zum Format und zu den Einschränkungen finden Sie unter :doc:`security-virtual-host`. + +Integration mit Reverse-Proxys +======================== + +Konfigurationsbeispiel für Nginx +-------------- + +:: + + server { + listen 80; + server_name search.example.com; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Host $host; + } + } + +Konfigurationsbeispiel für Apache +--------------- + +:: + + + ServerName search.example.com + + ProxyPreserveHost On + ProxyPass / http://localhost:8080/ + ProxyPassReverse / http://localhost:8080/ + + RequestHeader set X-Forwarded-Proto "http" + RequestHeader set X-Forwarded-Host "search.example.com" + + +SSL/TLS-Terminierung +----------- + +Konfigurationsbeispiel für SSL/TLS-Terminierung am Reverse-Proxy (Nginx): + +:: + + server { + listen 443 ssl http2; + server_name search.example.com; + + ssl_certificate /path/to/cert.pem; + ssl_certificate_key /path/to/key.pem; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto https; + proxy_set_header X-Forwarded-Host $host; + } + } + +Firewall-Konfiguration +==================== + +Öffnen erforderlicher Ports +------------------ + +Um |Fess| von extern zugänglich zu machen, öffnen Sie die folgenden Ports. + +**Konfigurationsbeispiel für iptables:** + +:: + + # Fess-Webanwendung + iptables -A INPUT -p tcp --dport 8080 -j ACCEPT + + # Für HTTPS-Zugriff (über Reverse-Proxy) + iptables -A INPUT -p tcp --dport 443 -j ACCEPT + +**Konfigurationsbeispiel für firewalld:** + +:: + + # Fess-Webanwendung + firewall-cmd --permanent --add-port=8080/tcp + firewall-cmd --reload + +Konfiguration von Sicherheitsgruppen (Cloud-Umgebungen) +------------------------------------------ + +In Cloud-Umgebungen wie AWS, GCP oder Azure öffnen Sie bitte die entsprechenden Ports über Sicherheitsgruppen oder Netzwerk-ACLs. + +Empfohlene Konfiguration: +- Eingehend: Ports 80/443 (über HTTP-Reverse-Proxy) +- Port 8080 nur intern zugänglich beschränken +- OpenSearch-Ports 9200/9300 nur intern zugänglich beschränken + +Fehlersuche +====================== + +Kein Zugriff nach Portänderung möglich +------------------------------ + +1. Überprüfen Sie, ob |Fess| neu gestartet wurde. +2. Überprüfen Sie, ob der entsprechende Port in der Firewall geöffnet ist. +3. Überprüfen Sie Fehler in der Protokolldatei (``fess.log``). + +Crawlen über Proxy nicht möglich +------------------------------ + +1. Überprüfen Sie, ob Hostname und Port des Proxy-Servers korrekt sind. +2. Wenn der Proxy-Server eine Authentifizierung erfordert, konfigurieren Sie Benutzername und Passwort. +3. Überprüfen Sie, ob Verbindungsversuche im Protokoll des Proxy-Servers aufgezeichnet werden. +4. Überprüfen Sie, ob die Konfiguration von ``nonProxyHosts`` korrekt ist. + +Keine Verbindung zu OpenSearch möglich +------------------------- + +1. Überprüfen Sie, ob OpenSearch läuft. +2. Überprüfen Sie, ob die Einstellung ``search_engine.http.url`` korrekt ist. +3. Überprüfen Sie die Netzwerkverbindung: ``curl http://localhost:9200`` +4. Überprüfen Sie Fehler im OpenSearch-Protokoll. + +Fehlfunktion beim Zugriff über Reverse-Proxy +---------------------------------------------------- + +1. Überprüfen Sie, ob der Header ``X-Forwarded-Host`` korrekt konfiguriert ist. +2. Überprüfen Sie, ob der Header ``X-Forwarded-Proto`` korrekt konfiguriert ist. +3. Überprüfen Sie, ob der Kontextpfad korrekt konfiguriert ist. +4. Überprüfen Sie Fehler im Reverse-Proxy-Protokoll. + +Referenzinformationen +======== + +- :doc:`setup-memory` - Speicherkonfiguration +- :doc:`setup-windows-service` - Windows-Dienst-Konfiguration +- :doc:`security-virtual-host` - Konfiguration virtueller Hosts +- :doc:`crawler-advanced` - Erweiterte Crawler-Konfiguration +- `OpenSearch Configuration `_ diff --git a/de/15.10/config/setup-windows-service.rst b/de/15.10/config/setup-windows-service.rst new file mode 100644 index 000000000..d73b8761c --- /dev/null +++ b/de/15.10/config/setup-windows-service.rst @@ -0,0 +1,134 @@ +================================ +Registrierung als Windows-Dienst +================================ + +Registrierung als Windows-Dienst +================================= + +|Fess| kann als Windows-Dienst registriert werden. Nach der Registrierung als Dienst kann |Fess| beim Systemstart automatisch gestartet werden. +Zum Betrieb von |Fess| muss OpenSearch gestartet sein. +In diesem Dokument wird davon ausgegangen, dass |Fess| unter ``c:\opt\fess`` und OpenSearch unter ``c:\opt\opensearch`` installiert sind (passen Sie die Pfade an Ihre Umgebung an). + +.. note:: + |Fess| und OpenSearch unterstützen ausschließlich die 64-Bit-Version. + +Vorbereitung +------------ + +Setzen Sie ``JAVA_HOME`` als Systemumgebungsvariable. ``service.bat`` wird mit einem Fehler beendet, wenn ``JAVA_HOME`` nicht gesetzt ist. + +Registrierung von OpenSearch als Dienst +---------------------------------------- + +Öffnen Sie die Eingabeaufforderung mit Administratorrechten und führen Sie ``c:\opt\opensearch\bin\opensearch-service.bat`` aus. + +:: + + > cd c:\opt\opensearch\bin + > opensearch-service.bat install + ... + The service 'opensearch-service-x64' has been installed. + +Weitere Informationen finden Sie in der `OpenSearch-Dokumentation `_. + +Konfiguration von |Fess| +------------------------ + +Der Dienst wird über ``c:\opt\fess\bin\service.bat`` registriert. ``service.bat`` liest bei der Registrierung ``bin\fess.in.bat`` ein und übernimmt dessen Inhalt als Startoptionen für |Fess|. +Fügen Sie die Verbindungseinstellungen für OpenSearch in ``c:\opt\fess\bin\fess.in.bat`` ein. + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200 + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=c:/opt/opensearch/config/dictionary/ + +.. note:: + - Geben Sie unter ``fess.search_engine.http_address`` die Verbindungsadresse des registrierten OpenSearch-Dienstes an. Ohne diese Einstellung kann |Fess| die Verbindungsadresse nicht ermitteln und startet nicht; es meldet, dass keine Adresse der Suchmaschine konfiguriert ist. + - Wenn OpenSearch auf einem anderen Host läuft, ändern Sie den Hostnamen oder die IP-Adresse entsprechend. + - Verwenden Sie ``/`` als Pfadtrennzeichen. + +Die Standard-Portnummer für Such- und Verwaltungsoberfläche von |Fess| ist ``8080``. Um den Port zu ändern, bearbeiten Sie ``-Dfess.port`` in ``c:\opt\fess\bin\fess.in.bat``. + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.port=80 + +.. note:: + Bei der Registrierung als Dienst ist ``-Dfess.port=8080`` auch in ``FESS_PARAMS`` in ``bin\service.bat`` fest eingetragen. Da dieser Wert Vorrang vor der Einstellung in ``fess.in.bat`` hat, muss beim Ändern des Ports auch ``FESS_PARAMS`` in ``service.bat`` entsprechend angepasst werden. + +Dienstanpassung (optional) +-------------------------- + +Durch das Setzen von Umgebungsvariablen vor der Ausführung von ``service.bat install`` kann die Dienstkonfiguration angepasst werden. Die wichtigsten Umgebungsvariablen sind: + +.. list-table:: + :header-rows: 1 + + * - Umgebungsvariable + - Beschreibung + * - ``FESS_START_TYPE`` + - Starttyp (``auto`` oder ``manual``). Standardwert ist ``manual``. + * - ``FESS_HEAP_SIZE`` + - Heap-Größe (z. B. ``1g``). Um minimale und maximale Heap-Größe separat anzugeben, verwenden Sie ``FESS_MIN_MEM`` (Standard ``256m``) und ``FESS_MAX_MEM`` (Standard ``1g``). + * - ``SERVICE_USERNAME`` / ``SERVICE_PASSWORD`` + - Windows-Konto, unter dem der Dienst ausgeführt wird. + * - ``SERVICE_DISPLAY_NAME`` + - Anzeigename des Dienstes. + * - ``SERVICE_DESCRIPTION`` + - Beschreibung des Dienstes. + +Registrierungsmethode +--------------------- + +Führen Sie ``c:\opt\fess\bin\service.bat`` aus einer Eingabeaufforderung mit Administratorrechten aus. + +:: + + > cd c:\opt\fess\bin + > service.bat install + ... + The service 'fess-service-x64' has been installed. + +Dienstkonfiguration +------------------- + +Beim manuellen Start des Dienstes starten Sie zuerst den OpenSearch-Dienst und dann den |Fess|-Dienst. +Für den automatischen Start beim Systemstart werden Starttyp und Abhängigkeiten konfiguriert. + +1. Setzen Sie in den allgemeinen Diensteinstellungen den Starttyp auf „Automatisch (Verzögerter Start)". +2. Dienstabhängigkeiten werden in der Registrierung konfiguriert. + +Fügen Sie im Registrierungs-Editor (regedit) den folgenden Schlüssel und Wert hinzu. + +.. list-table:: + + * - *Schlüssel* + - ``Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\fess-service-x64\DependOnService`` + * - *Wert* + - ``opensearch-service-x64`` + +Nach dem Hinzufügen wird opensearch-service-x64 in den Abhängigkeiten der |Fess|-Diensteigenschaften angezeigt. + +.. note:: + Wenn Sie die Umgebungsvariable ``FESS_START_TYPE=auto`` vor ``service.bat install`` setzen, wird der Starttyp als „Automatisch" registriert. Da „Automatisch (Verzögerter Start)" und die Konfiguration von Abhängigkeiten über ``service.bat`` nicht möglich sind, führen Sie diese Einstellungen wie oben beschrieben durch. + +Dienstverwaltung +---------------- + +Mit ``service.bat`` können die folgenden Befehle zur Steuerung des Dienstes verwendet werden. + +.. list-table:: + :header-rows: 1 + + * - Befehl + - Beschreibung + * - ``service.bat install`` + - Registriert den Dienst. + * - ``service.bat remove`` + - Entfernt den Dienst. + * - ``service.bat start`` + - Startet den Dienst. + * - ``service.bat stop`` + - Stoppt den Dienst. + * - ``service.bat manager`` + - Startet die grafische Benutzeroberfläche zur Dienstverwaltung. diff --git a/de/15.10/config/sso-entraid.rst b/de/15.10/config/sso-entraid.rst new file mode 100644 index 000000000..1d85c46eb --- /dev/null +++ b/de/15.10/config/sso-entraid.rst @@ -0,0 +1,440 @@ +===================================== +SSO-Konfiguration mit Entra ID +===================================== + +Übersicht +========= + +|Fess| unterstützt Single Sign-On (SSO)-Authentifizierung mit Microsoft Entra ID (ehemals Azure AD). +Durch die Verwendung der Entra ID-Authentifizierung können Benutzerinformationen und Gruppeninformationen aus Ihrer Microsoft 365-Umgebung mit der rollenbasierten Suche von |Fess| integriert werden. + +.. note:: + Die Unterstützung für die Entra ID-Authentifizierung kommt aus dem Plugin + ``fess-sso-entraid``, das nicht Teil der Distribution ist. Installieren Sie es über die + Seite **System > Plugin** in der Administrationsoberfläche oder mit + ``bin/fess-setup install plugin fess-sso-entraid``. + Bis dahin wird eine Anfrage an ``/sso/`` mit ``sso.type=entraid`` (oder dem alten ``aad``) + nur zur Anmeldeseite zurückgeleitet. + +Wie die Entra ID-Authentifizierung funktioniert +----------------------------------------------- + +Bei der Entra ID-Authentifizierung fungiert |Fess| als OAuth 2.0/OpenID Connect-Client und arbeitet mit Microsoft Entra ID für die Authentifizierung zusammen. + +1. Benutzer greift auf den |Fess| SSO-Endpunkt (``/sso/``) zu +2. |Fess| leitet zum Entra ID-Autorisierungsendpunkt weiter +3. Benutzer authentifiziert sich bei Entra ID (Microsoft-Anmeldung) +4. Entra ID leitet den Autorisierungscode an |Fess| weiter +5. |Fess| verwendet den Autorisierungscode, um ein Zugriffstoken zu erhalten +6. Benutzer wird angemeldet +7. Im Hintergrund verwendet |Fess| die Microsoft Graph API, um die Gruppen- und Rolleninformationen des Benutzers abzurufen, und wendet sie nach Abschluss der Auflösung auf die rollenbasierte Suche an + +.. note:: + Ab |Fess| 15.10 wird die Autorisierungsantwort in Schritt 4 als GET-Anfrage zurückgegeben, da + |Fess| beim Autorisierungsendpunkt ``response_mode=query`` anfordert. Bis 15.7 erfolgte dies + über einen websiteübergreifenden POST, bei dem der ausgelieferte Standardwert + ``tomcat.sameSiteCookies = lax`` das Sitzungscookie nicht mitsendet; deshalb war + ``tomcat.sameSiteCookies = none`` als Umgehungslösung erforderlich. Wenn Sie ``none`` nur aus + diesem Grund gesetzt haben, können Sie zum Standardwert zurückkehren. + +Informationen zur Integration mit der rollenbasierten Suche finden Sie unter :doc:`security-role`. + +Voraussetzungen +=============== + +Bevor Sie die Entra ID-Authentifizierung konfigurieren, überprüfen Sie die folgenden Voraussetzungen: + +- |Fess| 15.10 oder höher ist installiert +- Ein Microsoft Entra ID (Azure AD)-Mandant ist verfügbar +- |Fess| ist über HTTPS erreichbar (für Produktionsumgebungen erforderlich) +- Sie haben die Berechtigung, Anwendungen in Entra ID zu registrieren + +Grundkonfiguration +================== + +SSO aktivieren +-------------- + +Um die Entra ID-Authentifizierung zu aktivieren, fügen Sie die folgende Einstellung in ``app/WEB-INF/conf/system.properties`` hinzu: + +:: + + sso.type=entraid + +Erforderliche Einstellungen +--------------------------- + +Konfigurieren Sie die von Entra ID erhaltenen Informationen. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Eigenschaft + - Beschreibung + - Standard + * - ``entraid.tenant`` + - Mandanten-ID (z.B. ``xxx.onmicrosoft.com``) + - (Erforderlich) + * - ``entraid.client.id`` + - Anwendungs-(Client-)ID + - (Erforderlich) + * - ``entraid.client.secret`` + - Wert des Clientgeheimnisses + - (Erforderlich) + * - ``entraid.reply.url`` + - Umleitungs-URI (Callback-URL) + - Verwendet Anfrage-URL + +.. note:: + Anstelle des Präfixes ``entraid.*`` können Sie für die Abwärtskompatibilität auch das Legacy-Präfix ``aad.*`` verwenden. + +Optionale Einstellungen +----------------------- + +Die folgenden Einstellungen können bei Bedarf hinzugefügt werden. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Eigenschaft + - Beschreibung + - Standard + * - ``entraid.authority`` + - Authentifizierungsserver-URL + - ``https://login.microsoftonline.com/`` + * - ``entraid.state.ttl`` + - State-Lebensdauer (Sekunden) + - ``3600`` + * - ``entraid.response.mode`` + - Art, wie die Autorisierungsantwort zurückgegeben wird. Entweder ``query`` oder ``form_post``. + - ``query`` + * - ``entraid.default.groups`` + - Standardgruppen (kommagetrennt). Werden auf jeden Entra ID-Benutzer angewendet. + - (Keine) + * - ``entraid.default.roles`` + - Standardrollen (kommagetrennt). Werden auf jeden Entra ID-Benutzer angewendet. + - (Keine) + * - ``entraid.permission.fields`` + - Gruppen-/Rollenfelder (kommagetrennt), die zusätzlich als Berechtigungswerte verwendet werden. Die Gruppen-/Rollen-ID (GUID) wird stets als Berechtigung verwendet; die hier angegebenen Felder (z.B. ``mail``) werden zusätzlich hinzugefügt. Verwendbar sind nur Felder, deren Wert eine Zeichenkette ist. Microsoft Graph liefert ein Feld wie ``securityEnabled`` als booleschen Wert und ``groupTypes`` als Liste; keines von beiden kann ein Berechtigungswert werden, ein solches Feld wird daher ignoriert und eine Warnung mit seinem Namen ins Protokoll geschrieben. + - ``mail`` + * - ``entraid.use.ds`` + - Domänendienst-Integration. Bei ``true`` wird für Berechtigungswerte im Format ``name@domain`` auch der lokale Teil (``name``) ohne den Domänenanteil als Berechtigung hinzugefügt. Das gilt nicht nur für Gruppen und Rollen, sondern auch für den angemeldeten Benutzer selbst: Der lokale Teil seines Benutzerprinzipalnamens (UPN) wird als benutzerbezogene Berechtigung hinzugefügt. Mit ``false`` entfällt daher auch diese benutzerbezogene Berechtigung, nicht nur die der Gruppen. + - ``true`` + +.. note:: + + Die Gruppen-/Rollen-ID (GUID) wird stets als Berechtigung verwendet, aber nur E-Mail-aktivierte + Gruppen besitzen einen ``mail``-Wert. Microsoft-365-Gruppen sind E-Mail-aktiviert, daher wird + auch ihr Name als Berechtigung registriert. **Sicherheitsgruppen sind nicht E-Mail-aktiviert; + mit dem Standardwert wird daher nur ihre GUID zu einer Berechtigung.** Wenn die Zugriffsrechte + im Dateisystem eine Sicherheitsgruppe benennen, stimmen die Berechtigungen nicht überein und + diese Dokumente erscheinen nicht in den Suchergebnissen. + + Fügen Sie in diesem Fall ``displayName`` hinzu, das jede Gruppe besitzt: + + .. code-block:: properties + + entraid.permission.fields=mail,displayName + + ``displayName`` ist nicht domänenqualifiziert und nicht eindeutig und deshalb nicht Teil des + Standardwerts. Existiert in Entra ID beispielsweise eine Gruppe namens ``Administrators``, so + passt sie auch auf Dokumente, deren Zugriffsrechte die integrierte Windows-Gruppe + ``Administrators`` benennen. Prüfen Sie vor dem Hinzufügen, dass die Namen nicht mit den bereits + in Ihren Zugriffsrechten verwendeten kollidieren. + +.. note:: + Beim Standardwert ``query`` steht der Autorisierungscode in der Query-Zeichenfolge der + Callback-URL. ``form_post`` hält den Code aus der URL heraus und damit auch aus dem + Browserverlauf und den Zugriffsprotokollen vorgelagerter Proxys oder einer WAF. Allerdings wird + der Callback dadurch zu einem websiteübergreifenden POST und erfordert + ``tomcat.sameSiteCookies = none``. Ohne diese Einstellung wird das Sitzungscookie nicht + zurückgesendet und die Anmeldung schlägt fehl. Browser akzeptieren ``none`` zudem nur bei einem + Cookie, das auch das Attribut ``Secure`` trägt; ``form_post`` setzt daher voraus, dass |Fess| + über HTTPS bereitgestellt wird. Über einfaches HTTP speichert der Browser das Sitzungscookie + überhaupt nicht und die Anmeldung schlägt weiterhin fehl. Die meisten Installationen sollten + daher beim Standardwert bleiben. Andere Werte werden mit einer Warnung ignoriert und ``query`` + wird verwendet. + +.. warning:: + + ``entraid.default.groups`` und ``entraid.default.roles`` sind einzelne globale Werte ohne + benutzerbezogene Abgrenzung. |Fess| wendet sie bei der Anmeldung auf jeden Entra ID-Benutzer an + und wendet sie bei jeder späteren Auflösung erneut an, sodass Microsoft Graph sie nie wieder + entzieht. Tragen Sie insbesondere niemals die |Fess|-Administratorrolle — bei ausgeliefertem + ``authentication.admin.roles`` also ``admin`` — in ``entraid.default.roles`` ein: Das gewährt + jedem Benutzer im Mandanten dauerhaften Zugriff auf die Verwaltungsseiten. + +Konfiguration auf der Entra ID-Seite +==================================== + +App-Registrierung im Azure Portal +--------------------------------- + +1. Melden Sie sich beim `Azure Portal `_ an + +2. Wählen Sie **Microsoft Entra ID** + +3. Gehen Sie zu **Verwalten** → **App-Registrierungen** → **Neue Registrierung** + +4. Registrieren Sie die Anwendung: + + .. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Einstellung + - Wert + * - Name + - Beliebiger Name (z.B. Fess SSO) + * - Unterstützte Kontotypen + - "Nur Konten in diesem Organisationsverzeichnis" + * - Plattform + - Web + * - Umleitungs-URI + - ``https:///sso/`` + +5. Klicken Sie auf **Registrieren** + +Erstellen eines Clientgeheimnisses +---------------------------------- + +1. Klicken Sie auf der App-Detailseite auf **Zertifikate & Geheimnisse** + +2. Klicken Sie auf **Neues Clientgeheimnis** + +3. Legen Sie eine Beschreibung und ein Ablaufdatum fest und klicken Sie auf **Hinzufügen** + +4. Kopieren und speichern Sie den generierten **Wert** (dieser Wert wird nicht erneut angezeigt) + +.. warning:: + Der Wert des Clientgeheimnisses wird nur unmittelbar nach der Erstellung angezeigt. + Stellen Sie sicher, dass Sie ihn notieren, bevor Sie die Seite verlassen. + +Konfigurieren der API-Berechtigungen +------------------------------------ + +1. Klicken Sie im linken Menü auf **API-Berechtigungen** + +2. Klicken Sie auf **Berechtigung hinzufügen** + +3. Wählen Sie **Microsoft Graph** + +4. Wählen Sie **Delegierte Berechtigungen** + +5. Fügen Sie die folgende Berechtigung hinzu: + + - ``User.Read`` - Erforderlich zum Abrufen der Gruppenmitgliedschaften des angemeldeten Benutzers (``/me/memberOf``). Wird beim Erstellen der App-Registrierung standardmäßig erteilt + - ``GroupMember.Read.All`` - Erforderlich zum Lesen von Gruppenattributen wie dem Gruppennamen und zum Auflösen verschachtelter Gruppen + +6. Klicken Sie auf **Berechtigungen hinzufügen** + +7. Klicken Sie auf **Administratorzustimmung für erteilen** + +.. note:: + Die Administratorzustimmung erfordert Mandantenadministratorrechte. + +.. note:: + Anstelle von ``GroupMember.Read.All`` können auch ``Group.Read.All`` oder + ``Directory.Read.All`` erteilt werden; das Abrufen der Gruppenattribute und das Auflösen + verschachtelter Gruppen funktioniert damit ebenfalls. ``/me/memberOf`` wird durch + ``Group.Read.All`` jedoch nicht autorisiert, sodass ``User.Read`` in jedem Fall erforderlich + ist. + +.. note:: + Die oben genannten Berechtigungen decken den ``displayName`` einer Verzeichnisrolle nicht ab: + Microsoft Graph gibt ihn als null zurück. ``displayName`` in ``entraid.permission.fields`` + bewirkt daher für eine Verzeichnisrolle nichts, und nur die ID (GUID) der Rolle wird zu einer + Berechtigung. Um Rollennamen als Berechtigungswerte zu verwenden, erteilen Sie zusätzlich + ``RoleManagement.Read.Directory`` (oder ``Directory.Read.All``). + +.. note:: + |Fess| fordert beim Token-Abruf den Scope ``https://graph.microsoft.com/.default`` an. + Ab 15.10 wird zusätzlich ``openid profile offline_access https://graph.microsoft.com/.default`` an den Autorisierungsendpunkt gesendet, sodass die Zustimmung für denselben Umfang eingeholt wird. + Das bedeutet, dass alle in der App-Registrierung konfigurierten und genehmigten Zugriffsberechtigungen verwendet werden. + Um Gruppeninformationen abzurufen, müssen daher die oben genannten Berechtigungen zur App-Registrierung hinzugefügt und die Administratorzustimmung erteilt werden. + +Zu erhaltende Informationen +--------------------------- + +Die folgenden Informationen werden für die Fess-Konfiguration verwendet: + +- **Anwendungs-(Client-)ID**: Auf der Übersichtsseite als "Anwendungs-(Client-)ID" aufgeführt +- **Mandanten-ID**: Auf der Übersichtsseite als "Verzeichnis-(Mandanten-)ID" oder im Format ``xxx.onmicrosoft.com`` aufgeführt +- **Clientgeheimniswert**: Der in Zertifikate & Geheimnisse erstellte Wert + +Gruppen- und Rollenzuordnung +============================ + +Mit der Entra ID-Authentifizierung ruft |Fess| automatisch die Gruppen und Rollen ab, zu denen ein Benutzer gehört, unter Verwendung der Microsoft Graph API. +Die abgerufenen Gruppen-IDs und Gruppennamen können für die rollenbasierte Suche von |Fess| verwendet werden. + +Verschachtelte Gruppen +---------------------- + +|Fess| ruft nicht nur Gruppen ab, zu denen Benutzer direkt gehören, sondern auch die übergeordneten Gruppen, zu denen diese wiederum gehören (verschachtelte Gruppen). +Sowohl die direkte Mitgliedschaftsabfrage als auch die Suche nach übergeordneten Gruppen laufen nach der Anmeldung in derselben Hintergrundaufgabe, sodass die Anmeldung selbst nie durch Microsoft Graph verzögert wird. +Die Suche nach übergeordneten Gruppen verwendet den Microsoft Graph-Vorgang ``getMemberGroups``, der transitiv auflöst: Ein Aufruf je direkt zugewiesener Gruppe liefert alle darüberliegenden Gruppen, unabhängig davon, wie tief die Verschachtelung reicht. Die abgerufenen Ergebnisse werden für einen bestimmten Zeitraum zwischengespeichert. +Sobald diese Hintergrundaufgabe abgeschlossen ist, werden die Berechtigungen des Benutzers neu berechnet. + +Standardgruppeneinstellungen +---------------------------- + +Um allen Entra ID-Benutzern gemeinsame Gruppen zuzuweisen: + +:: + + entraid.default.groups=authenticated_users,entra_users + +Konfigurationsbeispiele +======================= + +Minimale Konfiguration (zum Testen) +----------------------------------- + +Das Folgende ist ein minimales Konfigurationsbeispiel zur Verifizierung in einer Testumgebung. + +:: + + # SSO aktivieren + sso.type=entraid + + # Entra ID-Einstellungen + entraid.tenant=yourcompany.onmicrosoft.com + entraid.client.id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + entraid.client.secret=your-client-secret-value + entraid.reply.url=http://localhost:8080/sso/ + +Empfohlene Konfiguration (für Produktion) +----------------------------------------- + +Das Folgende ist ein empfohlenes Konfigurationsbeispiel für Produktionsumgebungen. + +:: + + # SSO aktivieren + sso.type=entraid + + # Entra ID-Einstellungen + entraid.tenant=yourcompany.onmicrosoft.com + entraid.client.id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + entraid.client.secret=your-client-secret-value + entraid.reply.url=https://fess.example.com/sso/ + + # Standardgruppen (optional) + entraid.default.groups=authenticated_users + +Legacy-Konfiguration (Abwärtskompatibilität) +-------------------------------------------- + +Für die Kompatibilität mit früheren Versionen kann auch das Präfix ``aad.*`` verwendet werden. +Wenn eine ``entraid.*``-Eigenschaft nicht gesetzt ist, wird der Wert der entsprechenden ``aad.*``-Eigenschaft verwendet. +Außerdem wird ``sso.type=aad`` genauso behandelt wie ``sso.type=entraid``. + +:: + + # SSO aktivieren (sso.type=aad kann ebenfalls verwendet werden) + sso.type=entraid + + # Legacy-Konfigurationsschlüssel + aad.tenant=yourcompany.onmicrosoft.com + aad.client.id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + aad.client.secret=your-client-secret-value + aad.reply.url=https://fess.example.com/sso/ + +Fehlerbehebung +============== + +Häufige Probleme und Lösungen +----------------------------- + +Kann nach der Authentifizierung nicht zu Fess zurückkehren +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Überprüfen Sie, ob die Umleitungs-URI in der Azure Portal-App-Registrierung korrekt konfiguriert ist +- Stellen Sie sicher, dass der Wert von ``entraid.reply.url`` genau mit der Azure Portal-Konfiguration übereinstimmt +- Überprüfen Sie, ob das Protokoll (HTTP/HTTPS) übereinstimmt +- Überprüfen Sie, ob die Umleitungs-URI mit ``/`` endet +- Wenn ``entraid.response.mode`` auf ``form_post`` gesetzt ist, prüfen Sie sowohl, ob + ``tomcat.sameSiteCookies = none`` konfiguriert ist, als auch, ob |Fess| über HTTPS bereitgestellt + wird. Beim ausgelieferten Standardwert ``lax`` sendet der Browser das Sitzungscookie nicht mit dem + websiteübergreifenden POST des Callbacks; mit ``none`` über einfaches HTTP speichert der Browser + dieses Cookie überhaupt nicht, da ``none`` das Attribut ``Secure`` voraussetzt. In beiden Fällen + schlägt die Anmeldung genau einmal fehl: Der Browser kehrt zur Anmeldeseite zurück und zeigt + "SSO-Anmeldevorgang fehlgeschlagen.", und im Protokoll erscheint eine Warnung mit dem Wortlaut + ``Failed to process SSO login: could not validate state`` + +Authentifizierungsfehler treten auf +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Überprüfen Sie, ob Mandanten-ID, Client-ID und Clientgeheimnis korrekt konfiguriert sind +- Überprüfen Sie, ob das Clientgeheimnis nicht abgelaufen ist +- Überprüfen Sie, ob die Administratorzustimmung für API-Berechtigungen erteilt wurde + +Gruppeninformationen können nicht abgerufen werden +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Überprüfen Sie, ob die Berechtigungen ``User.Read`` und ``GroupMember.Read.All`` erteilt wurden + (``GroupMember.Read.All`` kann durch ``Group.Read.All`` oder ``Directory.Read.All`` ersetzt + werden, ``/me/memberOf`` benötigt jedoch weiterhin ``User.Read``) +- Überprüfen Sie, ob die Administratorzustimmung erteilt wurde +- Überprüfen Sie, ob der Benutzer in Entra ID zu Gruppen gehört +- Wenn verschachtelte übergeordnete Gruppen nicht aufgelöst werden können, wird die Warnung + ``Not allowed to read the parent groups of ...`` protokolliert. Erteilen Sie in diesem Fall + ``GroupMember.Read.All`` +- |Fess| löst die Gruppen- und Rollenmitgliedschaft des Benutzers im Hintergrund auf, nachdem die + Anmeldung abgeschlossen ist; die Anmeldung selbst wartet also nie auf Microsoft Graph. Bis die + Auflösung abgeschlossen ist, besitzt der Benutzer nur seine eigene benutzerbezogene Berechtigung + sowie die in ``entraid.default.groups`` und ``entraid.default.roles`` konfigurierten Gruppen und + Rollen. Ist beides nicht gesetzt — der ausgelieferte Standard —, liefert eine Suche in diesem + Zeitfenster überhaupt keine Dokumente: ``role.search.default.permissions`` ist ab Werk leer, und + eine mit dem ausgelieferten ``role.search.default.display.permissions`` angelegte + Crawl-Konfiguration vergibt ``{role}guest``, was ein angemeldeter Benutzer nicht besitzt. Das + Zeitfenster umfasst bis zu etwa eine Sekunde Planungsverzögerung zuzüglich der Aufrufe von + Microsoft Graph selbst — einer für die direkten Mitgliedschaften, dann je einer pro dieser + Gruppen für den Durchlauf der verschachtelten Gruppen, nacheinander und bei kaltem Cache + abgesetzt —, es wächst also mit der Anzahl der Gruppen des Benutzers. Währenddessen teilt die + Suchseite dem Benutzer mit, dass seine Gruppen- und Rollenberechtigungen noch geladen werden, + und bittet ihn, die Suche in einem Moment zu wiederholen +- Gelingt die Auflösung nicht vollständig, teilt die Suchseite dem Benutzer mit, dass seine + Gruppen- und Rollenberechtigungen nicht vollständig geladen werden konnten, und bittet ihn, sich + ab- und wieder anzumelden sowie bei wiederholtem Auftreten den Administrator zu kontaktieren. + „Nicht vollständig“ ist bewusst gewählt: Die Auflösung gilt nur dann als erfolgreich, wenn sowohl + die Abfrage der direkten Mitgliedschaften als auch der Durchlauf der verschachtelten Gruppen + gelungen ist — ein Benutzer, der seine direkten Gruppen, aber nicht seine übergeordneten Gruppen + besitzt, erhält diesen Hinweis also ebenfalls. Ein Fall ist davon ausgenommen, und zwar genau + der aus dem vorherigen Punkt: Verweigert Microsoft Graph die Abfrage der verschachtelten Gruppen + mit ``Authorization_RequestDenied``, weil ``GroupMember.Read.All`` nie erteilt wurde, wertet + |Fess| das nicht als Fehlschlag, sondern als Antwort, die besagt, dass die Gruppe keine + übergeordneten Gruppen hat. Die Auflösung gilt dann als erfolgreich und **es wird kein Hinweis + angezeigt**, obwohl die Berechtigungen der übergeordneten Gruppen fehlen. Das einzige Anzeichen + ist die Warnung ``Not allowed to read the parent groups of ...`` im Protokoll; prüfen Sie das + Protokoll deshalb darauf, wann immer verschachtelte Gruppen im Einsatz sind. Häufigste Ursache des + Teilfalls ist Drosselung: + Ein einziges HTTP 429 oder 503 von Microsoft Graph lässt |Fess| so lange pausieren, wie es der + Header ``Retry-After`` verlangt (60 Sekunden, wenn er nichts Verwertbares nennt, höchstens 60 + Minuten), und in dieser Zeit wird in der gesamten |Fess|-Instanz jede Abfrage verschachtelter + Gruppen übersprungen, während die direkten Abfragen weiter beantwortet werden. Der Fehlschlag ist nicht zwangsläufig endgültig: Die Auflösung wird + bei jeder Erneuerung des Zugriffstokens erneut angestoßen, und ein späterer Erfolg lässt den + Hinweis verschwinden und stellt die fehlenden Berechtigungen wieder her. Abmelden und erneut + anmelden versucht es sofort erneut — wird die SSO-Anmelde-URL im angemeldeten Zustand + aufgerufen, erfolgt lediglich eine Umleitung zurück zur Suchseite + +Debug-Einstellungen +------------------- + +Um Probleme zu untersuchen, können Sie detaillierte Entra ID-bezogene Protokolle ausgeben, indem Sie die |Fess|-Protokollebene anpassen. + +In ``app/WEB-INF/classes/log4j2.xml`` können Sie den folgenden Logger hinzufügen, um die Protokollebene zu ändern: + +:: + + + +Referenz +======== + +- :doc:`security-role` - Konfiguration der rollenbasierten Suche +- :doc:`sso-saml` - SSO-Konfiguration mit SAML-Authentifizierung +- :doc:`sso-oidc` - SSO-Konfiguration mit OpenID Connect-Authentifizierung diff --git a/de/15.10/config/sso-oidc.rst b/de/15.10/config/sso-oidc.rst new file mode 100644 index 000000000..67272b01b --- /dev/null +++ b/de/15.10/config/sso-oidc.rst @@ -0,0 +1,333 @@ +==================================== +SSO-Konfiguration mit OpenID Connect +==================================== + +Überblick +========= + +|Fess| unterstützt Single Sign-On (SSO) Authentifizierung mit OpenID Connect (OIDC). +OpenID Connect ist ein Authentifizierungsprotokoll, das auf OAuth 2.0 aufbaut und ID-Token (JWT) für die Benutzerauthentifizierung verwendet. +Durch die Verwendung von OpenID Connect können Benutzerinformationen, die von einem OpenID Provider (OP) authentifiziert wurden, mit |Fess| integriert werden. + +.. note:: + Die Unterstützung für die OpenID Connect Authentifizierung kommt aus dem Plugin + ``fess-sso-oidc``, das nicht Teil der Distribution ist. Installieren Sie es über die Seite + **System > Plugin** in der Administrationsoberfläche oder mit + ``bin/fess-setup install plugin fess-sso-oidc``. Das Plugin heißt ``fess-sso-oidc``, während + der Wert von ``sso.type`` weiterhin ``oic`` lautet. + Bis dahin wird eine Anfrage an ``/sso/`` mit ``sso.type=oic`` nur zur Anmeldeseite + zurückgeleitet. + +Funktionsweise der OpenID Connect Authentifizierung +---------------------------------------------------- + +Bei der OpenID Connect Authentifizierung fungiert |Fess| als Relying Party (RP) und arbeitet mit einem externen OpenID Provider (OP) für die Authentifizierung zusammen. + +1. Benutzer greift auf den |Fess| SSO-Endpunkt (``/sso/``) zu +2. |Fess| leitet zum Autorisierungsendpunkt des OP weiter +3. Benutzer authentifiziert sich beim OP +4. OP leitet den Autorisierungscode an |Fess| weiter +5. |Fess| verwendet den Autorisierungscode, um ein ID-Token vom Token-Endpunkt zu erhalten +6. |Fess| prüft die Claims des ID-Tokens (JWT), ruft daraus Benutzerinformationen ab und meldet den Benutzer an + +.. note:: + |Fess| verwendet den Authorization Code Flow. Das ID-Token wird nicht über den Browser, sondern direkt vom Token-Endpunkt über einen Backkanal (Server-zu-Server-Kommunikation) zwischen |Fess| und dem OP abgerufen. + |Fess| dekodiert das ID-Token und entnimmt daraus Claims (z. B. ``email`` und ``groups``), um die Benutzerinformationen zusammenzustellen, führt jedoch keine kryptografische Überprüfung der JWT-Signatur durch. OpenID Connect Core erlaubt dies, weil das Token direkt vom Token-Endpunkt über TLS empfangen wird; daher muss die Token-Endpunkt-URL (``oic.token.server.url``) HTTPS verwenden. ``http`` wird nur für ``localhost``, ``127.x.x.x`` und ``::1`` akzeptiert. + |Fess| prüft aber die Claims: ``aud`` muss ``oic.client.id`` enthalten (und ``azp`` muss, sofern vorhanden, ihm entsprechen), ``exp`` muss vorhanden und darf nicht abgelaufen sein (eine Zeitabweichung von bis zu 300 Sekunden wird toleriert), und ``iss`` muss ``oic.issuer`` entsprechen, sofern dieser Schlüssel gesetzt ist. Ohne ``oic.issuer`` wird ``iss`` nicht geprüft, und bei der ersten Anmeldung nach jedem Start wird eine Warnung protokolliert. ``nonce`` und PKCE werden nicht verwendet. + +Für die Integration mit rollenbasierter Suche siehe :doc:`security-role`. + +Voraussetzungen +=============== + +Bevor Sie die OpenID Connect Authentifizierung konfigurieren, überprüfen Sie die folgenden Voraussetzungen: + +- |Fess| 15.10 oder höher ist installiert +- Ein OpenID Connect-kompatibler Provider (OP) ist verfügbar +- |Fess| ist über HTTPS erreichbar (erforderlich für Produktionsumgebungen) +- Sie haben die Berechtigung, |Fess| als Client (RP) auf der OP-Seite zu registrieren + +Beispiele für unterstützte Provider: + +- Microsoft Entra ID (Azure AD) +- Google Workspace / Google Cloud Identity +- Okta +- Keycloak +- Auth0 +- Andere OpenID Connect-kompatible Provider + +Grundkonfiguration +================== + +SSO aktivieren +-------------- + +Um die OpenID Connect Authentifizierung zu aktivieren, fügen Sie die folgende Einstellung in ``app/WEB-INF/conf/system.properties`` hinzu: + +:: + + sso.type=oic + +.. note:: + ``sso.type`` sowie die im Folgenden beschriebenen ``oic.*``-Einstellungen mit Ausnahme von ``oic.issuer`` können auch über die Administrationsseite „System > Allgemein" konfiguriert und geändert werden. + Über die Administrationsseite vorgenommene Änderungen werden in ``system.properties`` gespeichert und bleiben auch nach einem Neustart erhalten. + ``oic.issuer`` lässt sich nur in ``system.properties`` festlegen. + +Provider-Konfiguration +---------------------- + +Konfigurieren Sie die vom OP erhaltenen Informationen. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Eigenschaft + - Beschreibung + - Standard + * - ``oic.auth.server.url`` + - Autorisierungsendpunkt-URL + - ``https://accounts.google.com/o/oauth2/auth`` + * - ``oic.token.server.url`` + - Token-Endpunkt-URL + - ``https://accounts.google.com/o/oauth2/token`` + * - ``oic.issuer`` + - Aussteller-Kennung (Issuer, optional). Wenn gesetzt, muss der ``iss``-Claim des ID-Tokens exakt damit übereinstimmen (ein abschließender Schrägstrich zählt mit) + - (leer: ``iss`` wird nicht geprüft) + +.. note:: + Diese URLs und der Aussteller können vom Discovery-Endpunkt des OP (``/.well-known/openid-configuration``) abgerufen werden; der Aussteller ist dessen ``issuer``-Wert. + + Die Token-Endpunkt-URL (``oic.token.server.url``) muss HTTPS verwenden. ``http`` wird nur akzeptiert, wenn der Host ``localhost`` (Groß-/Kleinschreibung egal), eine IPv4-Adresse der Form ``127.x.x.x`` oder ``::1`` ist. Der Host wird so verglichen, wie er geschrieben ist, und nie aufgelöst. Deshalb wird ein Docker-Compose-Servicename (z. B. ``http://keycloak:8080/...``) oder ein interner Hostname über ``http`` abgelehnt, auch wenn er auf denselben Rechner zeigt. + + Geprüft wird nur der Token-Endpunkt, nicht der Autorisierungsendpunkt (``oic.auth.server.url``). Die Prüfung erfolgt bei der Anmeldung, nicht beim Start. Das Setzen von ``oic.issuer`` lockert diese Regel nicht; es aktiviert nur die Prüfung des ``iss``-Claims. + +Client-Konfiguration +-------------------- + +Konfigurieren Sie die beim OP registrierten Client-Informationen. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Eigenschaft + - Beschreibung + - Standard + * - ``oic.client.id`` + - Client-ID + - (leer) + * - ``oic.client.secret`` + - Client-Secret + - (leer) + * - ``oic.scope`` + - Angeforderte Scopes + - (leer) + +.. note:: + Der Scope muss mindestens ``openid`` enthalten. + Um die E-Mail-Adresse des Benutzers abzurufen, geben Sie ``openid email`` an. + +Redirect-URL-Konfiguration +-------------------------- + +Konfigurieren Sie die Callback-URL nach der Authentifizierung. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Eigenschaft + - Beschreibung + - Standard + * - ``oic.redirect.url`` + - Redirect-URL (Callback-URL) + - ``{oic.base.url}/sso/`` + * - ``oic.base.url`` + - |Fess| Basis-URL + - ``http://localhost:8080`` + +.. note:: + Wenn ``oic.redirect.url`` weggelassen wird, wird sie automatisch aus ``oic.base.url`` erstellt. + Für Produktionsumgebungen setzen Sie ``oic.base.url`` auf eine HTTPS-URL. + +Benutzerattribut-Konfiguration +------------------------------- + +Konfigurieren Sie die Standardgruppen und -rollen, die OIDC-authentifizierten Benutzern zugewiesen werden. +Benutzer-ID, Gruppen und Rollen werden jeweils wie folgt ermittelt: + +- **Benutzer-ID**: Wird aus dem ``email``-Claim des ID-Tokens (JWT) bezogen. Daher muss der Scope in der Praxis ``email`` enthalten (kann der ``email``-Claim nicht abgerufen werden, ist kein ordnungsgemäßer Login möglich). +- **Gruppen**: Werden aus dem ``groups``-Claim des ID-Tokens bezogen. Ist kein ``groups``-Claim vorhanden, wird der Wert von ``oic.default.groups`` verwendet. Ein leeres ``groups``-Array gilt als vorhanden: ``oic.default.groups`` wird dann nicht verwendet, und der Benutzer wird als Benutzer ohne Gruppen behandelt. +- **Rollen**: Es wird stets der Wert von ``oic.default.roles`` verwendet (ein Mechanismus zur Übernahme von Rollen aus ID-Token-Claims ist nicht vorhanden). + +.. note:: + |Fess| übernimmt die Werte des ``groups``-Claims unverändert: Es findet keine + Verzeichnisabfrage statt, und verschachtelte (transitive) Gruppen werden nicht aufgelöst. + Ob übergeordnete Gruppen enthalten sind, hängt daher allein von der Claim-Konfiguration des OP + ab -- anders als bei :doc:`sso-entraid`, wo |Fess| übergeordnete Gruppen über die + Microsoft Graph API auflöst. + Der Claim-Wert wird unverändert zur Suchberechtigung. Ist der OP so konfiguriert, dass er + vollständige Gruppenpfade ausgibt, lauten die Werte etwa ``/uebergeordnet/untergeordnet`` und + passen damit nicht zu Dokumenten, die nur mit dem reinen Gruppennamen versehen sind. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Eigenschaft + - Beschreibung + - Standard + * - ``oic.default.groups`` + - Standardgruppen (kommagetrennt) + - (leer) + * - ``oic.default.roles`` + - Standardrollen (kommagetrennt) + - (leer) + +.. note:: + Bei Verwendung der rollenbasierten Suche müssen Benutzern geeignete Gruppen oder Rollen zugewiesen werden. + Weitere Informationen finden Sie unter :doc:`security-role`. + +OP-seitige Konfiguration +======================== + +Wenn Sie |Fess| als Client (RP) auf der OP-Seite registrieren, konfigurieren Sie die folgenden Informationen: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Einstellung + - Wert + * - Anwendungstyp + - Webanwendung + * - Redirect-URI / Callback-URL + - ``https:///sso/`` + * - Erlaubte Scopes + - ``openid`` und erforderliche Scopes (``email``, ``profile`` usw.) + +Vom OP zu erhaltende Informationen +----------------------------------- + +Rufen Sie die folgenden Informationen vom Konfigurationsbildschirm oder Discovery-Endpunkt des OP für die |Fess| Konfiguration ab: + +- **Autorisierungsendpunkt (Authorization Endpoint)**: URL zum Starten der Benutzerauthentifizierung +- **Token-Endpunkt (Token Endpoint)**: URL zum Abrufen von Token +- **Issuer** (optional): ``issuer``-Wert des Discovery-Dokuments, der für ``oic.issuer`` verwendet wird +- **Client-ID**: Vom OP ausgestellte Client-Kennung +- **Client-Secret**: Geheimer Schlüssel für die Client-Authentifizierung + +.. note:: + Die meisten OPs ermöglichen es Ihnen, die Autorisierungs- und Token-Endpunkt-URLs vom + Discovery-Endpunkt (``https:///.well-known/openid-configuration``) zu überprüfen. + +Konfigurationsbeispiele +======================= + +Minimalkonfiguration (für Tests) +--------------------------------- + +Das folgende Beispiel zeigt eine minimale Konfiguration zur Überprüfung in einer Testumgebung. + +:: + + # SSO aktivieren + sso.type=oic + + # Provider-Konfiguration (vom OP erhaltene Werte eintragen) + oic.auth.server.url=https://op.example.com/authorize + oic.token.server.url=https://op.example.com/token + + # Client-Konfiguration + oic.client.id=your-client-id + oic.client.secret=your-client-secret + oic.scope=openid email + + # Redirect-URL (Testumgebung) + oic.redirect.url=http://localhost:8080/sso/ + +Empfohlene Konfiguration (für Produktion) +------------------------------------------ + +Das folgende Beispiel zeigt eine empfohlene Konfiguration für Produktionsumgebungen. + +:: + + # SSO aktivieren + sso.type=oic + + # Provider-Konfiguration + oic.auth.server.url=https://op.example.com/authorize + oic.token.server.url=https://op.example.com/token + + # Issuer (issuer-Wert des Discovery-Dokuments) + oic.issuer=https://op.example.com + + # Client-Konfiguration + oic.client.id=your-client-id + oic.client.secret=your-client-secret + oic.scope=openid email profile + + # Basis-URL (HTTPS für Produktion verwenden) + oic.base.url=https://fess.example.com + +Fehlerbehebung +============== + +Häufige Probleme und Lösungen +------------------------------ + +Rückkehr zu |Fess| nach der Authentifizierung nicht möglich +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Überprüfen Sie, ob die Redirect-URI auf der OP-Seite korrekt konfiguriert ist +- Stellen Sie sicher, dass der Wert von ``oic.redirect.url`` oder ``oic.base.url`` mit der OP-Konfiguration übereinstimmt +- Überprüfen Sie, ob das Protokoll (HTTP/HTTPS) übereinstimmt + +Authentifizierungsfehler treten auf +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Überprüfen Sie, ob Client-ID und Client-Secret korrekt konfiguriert sind +- Stellen Sie sicher, dass der Scope ``openid`` enthält +- Überprüfen Sie, ob die Autorisierungsendpunkt-URL und Token-Endpunkt-URL korrekt sind +- Wenn die Anmeldung fehlschlägt, enthält ``fess.log`` eine Warnung ``Failed to process the OpenID Connect callback:`` gefolgt vom Grund +- ``The ID token was not issued for this client``: Der ``aud``-Claim des ID-Tokens entspricht nicht ``oic.client.id``; überprüfen Sie die Client-ID +- ``The ID token has expired``: Die Uhren des |Fess|-Hosts und des OP weichen um mehr als 300 Sekunden voneinander ab; synchronisieren Sie die Uhrzeit (NTP) +- ``The ID token was not issued by the configured issuer``: ``oic.issuer`` weicht vom ``iss`` ab, das in der Meldung angezeigt wird; kopieren Sie den ``issuer``-Wert des Discovery-Dokuments exakt +- ``oic.token.server.url must be https``: Verwenden Sie eine HTTPS-Token-Endpunkt-URL (``http`` funktioniert nur für ``localhost``, ``127.x.x.x`` und ``::1``; ``http`` zu einem Docker-Compose-Servicenamen oder einem internen Hostnamen wird ebenfalls abgelehnt) + +Benutzerinformationen können nicht abgerufen werden +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Stellen Sie sicher, dass der Scope die erforderlichen Berechtigungen (``email``, ``profile`` usw.) enthält +- Überprüfen Sie, ob die erforderlichen Scopes für den Client auf der OP-Seite erlaubt sind +- Bei Microsoft Entra ID enthält der ``groups``-Claim die ``ObjectId``-GUIDs der Gruppen, sofern + kein anderes Quellattribut ausgewählt ist; die Werte stimmen daher nicht mit den Gruppennamen + überein +- Microsoft Entra ID lässt den ``groups``-Claim vollständig weg, wenn ein Benutzer mehr als 200 + Gruppen angehört (verschachtelte Gruppen zählen mit); |Fess| greift dann auf + ``oic.default.groups`` zurück + +Debug-Einstellungen +-------------------- + +Um Probleme zu untersuchen, können Sie detaillierte OpenID Connect-bezogene Protokolle ausgeben, indem Sie die |Fess| Protokollebene anpassen. + +In ``app/WEB-INF/classes/log4j2.xml`` können Sie den folgenden Logger hinzufügen, um die Protokollebene zu ändern: + +:: + + + +.. warning:: + Steht dieser Logger auf DEBUG, werden die Claims des ID-Tokens (z. B. ``email`` und ``groups``) + in die Protokolldatei geschrieben. Setzen Sie die Protokollebene nach der Untersuchung zurück + und behandeln Sie die erzeugten Protokolle entsprechend. + +Referenz +======== + +- :doc:`security-role` - Konfiguration der rollenbasierten Suche +- :doc:`sso-saml` - SSO-Konfiguration mit SAML-Authentifizierung +- :doc:`sso-entraid` - SSO-Konfiguration speziell für Microsoft Entra ID (bei Verwendung von Entra ID kann statt der allgemeinen OpenID Connect-Konfiguration auch die dedizierte Einstellung verwendet werden) diff --git a/de/15.10/config/sso-saml.rst b/de/15.10/config/sso-saml.rst new file mode 100644 index 000000000..ea45edbff --- /dev/null +++ b/de/15.10/config/sso-saml.rst @@ -0,0 +1,654 @@ +========================================== +SAML-Authentifizierung SSO-Einrichtung +========================================== + +Übersicht +========= + +|Fess| unterstützt Single Sign-On (SSO) Authentifizierung mit SAML (Security Assertion Markup Language) 2.0. +Durch die Verwendung von SAML-Authentifizierung können Benutzerinformationen, die von einem IdP (Identity Provider) authentifiziert wurden, mit |Fess| integriert werden. In Kombination mit rollenbasierter Suche ermöglicht dies die Anzeige von Suchergebnissen basierend auf Benutzerberechtigungen. + +.. note:: + Die Unterstützung für die SAML-Authentifizierung kommt aus dem Plugin ``fess-sso-saml``, + das nicht Teil der Distribution ist. Installieren Sie es über die Seite **System > Plugin** + in der Administrationsoberfläche oder mit ``bin/fess-setup install plugin fess-sso-saml``. + Bis dahin wird eine Anfrage an ``/sso/`` mit ``sso.type=saml`` nur zur Anmeldeseite + zurückgeleitet. + +Funktionsweise der SAML-Authentifizierung +----------------------------------------- + +Bei der SAML-Authentifizierung fungiert |Fess| als SP (Service Provider) und arbeitet mit einem externen IdP zur Authentifizierung zusammen. + +1. Benutzer greift auf den |Fess| SSO-Endpunkt (``/sso/``) zu +2. |Fess| leitet die Authentifizierungsanfrage an den IdP weiter +3. Benutzer authentifiziert sich beim IdP +4. IdP sendet SAML-Assertion an |Fess| +5. |Fess| validiert die Assertion und meldet den Benutzer an + +.. note:: + Unterstützt wird ausschließlich die SP-initiierte Anmeldung, die wie oben beschrieben am + |Fess| SSO-Endpunkt (``/sso/``) beginnt. |Fess| bindet jede SAML-Antwort an die ID der von ihm + gesendeten AuthnRequest. Eine IdP-initiierte (unaufgeforderte) Antwort, etwa von einer + |Fess| -Kachel im Okta-Dashboard oder im Portal „Meine Apps" von Microsoft Entra ID, hat daher + keine zugehörige AuthnRequest und wird abgelehnt. Wenn Sie auf der IdP-Seite eine Kachel + anlegen, lassen Sie diese auf den |Fess| -Endpunkt ``/sso/`` verweisen. + + Beachten Sie: In 15.7 funktionierte eine IdP-initiierte Anmeldung zufällig, wenn + ``tomcat.sameSiteCookies=none`` gesetzt war. |Fess| schickte die nicht zuordenbare Antwort an den + IdP zurück, und der IdP lieferte sofort eine angeforderte Assertion. In 15.10 erfolgt dieses + Zurückschicken nicht mehr, sodass die IdP-initiierte Anmeldung nicht funktioniert. + +Für die Integration mit rollenbasierter Suche siehe :doc:`security-role`. + +Voraussetzungen +=============== + +Überprüfen Sie vor der Konfiguration der SAML-Authentifizierung die folgenden Voraussetzungen: + +- |Fess| 15.10 oder höher ist installiert +- Ein SAML 2.0-kompatibler IdP (Identity Provider) ist verfügbar +- |Fess| ist über HTTPS erreichbar (erforderlich für Produktionsumgebungen) +- Sie haben die Berechtigung, |Fess| als SP beim IdP zu registrieren + +Unterstützte IdP-Beispiele: + +- Microsoft Entra ID (Azure AD) +- Okta +- Google Workspace +- Keycloak +- OneLogin +- Andere SAML 2.0-kompatible IdPs + +Grundkonfiguration +================== + +SSO aktivieren +-------------- + +Um die SAML-Authentifizierung zu aktivieren, fügen Sie die folgende Einstellung in ``app/WEB-INF/conf/system.properties`` hinzu: + +:: + + sso.type=saml + +.. note:: + ``sso.type`` und die grundlegenden SAML-Einstellungen (IdP-Informationen, SP-Informationen, Benutzerattribut-Zuordnung) können auch über die Administrationsseite „System > Allgemein" konfiguriert werden. + Im Admin-Bereich vorgenommene Änderungen werden in ``system.properties`` gespeichert und bleiben nach einem Neustart erhalten. + Sicherheitseinstellungen wie Signierung/Verschlüsselung sowie das SP-Zertifikat und der private Schlüssel können jedoch nicht über die Administrationsseite konfiguriert werden und müssen direkt in ``system.properties`` eingetragen werden. + +.. note:: + Einstellungen, die mit ``saml.`` beginnen, werden ausschließlich aus ``system.properties`` gelesen. + JVM-Systemeigenschaften wie ``-Dsaml.security....`` oder ``-Dfess.saml.security....`` werden nicht ausgewertet. + Insbesondere ``saml.security.*``, ``saml.strict`` und ``saml.debug`` haben auch kein Feld auf der Administrationsseite; + der einzige Weg, sie zu setzen, ist der direkte Eintrag in ``system.properties``. + +Konfiguration des Sitzungs-Cookies +---------------------------------- + +Der IdP sendet die Assertion als **seitenübergreifenden POST** an |Fess| zurück. Ein ``SameSite=Lax``-Cookie wird bei einer solchen Anfrage nicht mitgesendet, sodass die SAML-Anmeldung mit dem von |Fess| ausgelieferten Standardwert nicht abgeschlossen wird. + +Ändern Sie ``tomcat.sameSiteCookies`` in ``tomcat_config.properties`` auf ``none``. Diese Datei liegt beim ZIP-Paket unter ``lib/classes/`` und bei den DEB-/RPM-Paketen unter ``/etc/fess/``. + +:: + + tomcat.sameSiteCookies = none + +.. warning:: + Browser akzeptieren ``none`` nur bei einem Cookie, das auch das Attribut ``Secure`` trägt. |Fess| muss daher über HTTPS bereitgestellt werden. Über einfaches HTTP macht diese Einstellung eine Anmeldung bei |Fess| unmöglich. + +.. note:: + Der Standardwert ``lax`` ist für SSO-Verfahren gedacht, deren Callback als Weiterleitung (GET) zurückkommt. Die HTTP-POST-Bindung von SAML gehört nicht dazu, daher ist diese Änderung nur bei Verwendung von SAML erforderlich. Nach der Änderung muss |Fess| neu gestartet werden. + +SP (Service Provider) Konfiguration +----------------------------------- + +Um |Fess| als SP zu konfigurieren, geben Sie die SP Base URL an. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Eigenschaft + - Beschreibung + - Standard + * - ``saml.sp.base.url`` + - SP Basis-URL + - ``http://localhost:8080`` + +.. note:: + Der Standardwert von ``saml.sp.base.url`` ist ``http://localhost:8080``. + Außerhalb von Testumgebungen muss immer die URL gesetzt werden, über die |Fess| von außen erreichbar ist (in Produktionsumgebungen HTTPS). + +Diese Einstellung konfiguriert automatisch die folgenden Endpunkte: + +- **Entity ID**: ``{saml.sp.base.url}/sso/metadata`` +- **ACS URL**: ``{saml.sp.base.url}/sso/`` +- **SLO URL**: ``{saml.sp.base.url}/sso/logout`` + +Beispiel:: + + saml.sp.base.url=https://fess.example.com + +Individuelle URL-Konfiguration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Normalerweise werden durch das Setzen von ``saml.sp.base.url`` alle Endpunkt-URLs automatisch konfiguriert. Bei Bedarf können einzelne URLs jedoch auch explizit mit den folgenden Eigenschaften überschrieben werden. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Eigenschaft + - Beschreibung + - Standard + * - ``saml.sp.entityid`` + - SP Entity ID + - ``{saml.sp.base.url}/sso/metadata`` + * - ``saml.sp.assertion_consumer_service.url`` + - Assertion Consumer Service URL + - ``{saml.sp.base.url}/sso/`` + * - ``saml.sp.single_logout_service.url`` + - Single Logout Service URL + - ``{saml.sp.base.url}/sso/logout`` + +IdP (Identity Provider) Konfiguration +------------------------------------- + +Konfigurieren Sie die von Ihrem IdP erhaltenen Informationen. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Eigenschaft + - Beschreibung + - Standard + * - ``saml.idp.entityid`` + - IdP Entity ID + - (Erforderlich) + * - ``saml.idp.single_sign_on_service.url`` + - IdP SSO-Service-URL + - (Erforderlich) + * - ``saml.idp.x509cert`` + - IdP-Signatur X.509-Zertifikat (Base64-codiert, ohne Zeilenumbrüche) + - (Erforderlich) + * - ``saml.idp.single_logout_service.url`` + - IdP SLO-Service-URL + - (Optional) + +.. note:: + Geben Sie für ``saml.idp.x509cert`` nur den Base64-codierten Inhalt des Zertifikats in einer einzigen Zeile ohne Zeilenumbrüche an. + Die Zeilen ``-----BEGIN CERTIFICATE-----`` und ``-----END CERTIFICATE-----`` dürfen nicht enthalten sein. + +SP-Metadaten abrufen +-------------------- + +Nach dem Start von |Fess| können Sie die SP-Metadaten im XML-Format vom Endpunkt ``/sso/metadata`` abrufen. + +:: + + https://fess.example.com/sso/metadata + +Importieren Sie diese Metadaten in Ihren IdP oder registrieren Sie den SP manuell auf der IdP-Seite unter Verwendung der Metadateninhalte. + +.. note:: + Um die Metadaten abzurufen, müssen Sie zuerst die grundlegende SAML-Konfiguration (``sso.type=saml`` und ``saml.sp.base.url``) abschließen und |Fess| starten. + +IdP-seitige Konfiguration +========================= + +Bei der Registrierung von |Fess| als SP auf der IdP-Seite konfigurieren Sie die folgenden Informationen: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Einstellung + - Wert + * - ACS URL / Reply URL + - ``https:///sso/`` + * - Entity ID / Audience URI + - ``https:///sso/metadata`` + * - Name ID Format + - ``urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`` (Empfohlen) + +Informationen vom IdP abrufen +----------------------------- + +Holen Sie die folgenden Informationen aus der Konfigurationsoberfläche oder den Metadaten Ihres IdPs für die |Fess|-Konfiguration: + +- **IdP Entity ID**: URI zur Identifizierung des IdP +- **SSO URL (HTTP-Redirect)**: Single Sign-On Endpunkt-URL +- **X.509-Zertifikat**: Öffentliches Schlüsselzertifikat zur Überprüfung der SAML-Assertion-Signatur + +Benutzerattribut-Zuordnung +========================== + +Sie können Benutzerattribute aus SAML-Assertionen |Fess|-Gruppen und -Rollen zuordnen. + +Gruppenattribut-Konfiguration +----------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Eigenschaft + - Beschreibung + - Standard + * - ``saml.attribute.group.name`` + - Attributname mit Gruppeninformationen + - ``memberOf`` + * - ``saml.default.groups`` + - Standardgruppen (kommagetrennt) + - (Keine) + +Beispiel:: + + saml.attribute.group.name=groups + saml.default.groups=user + +.. note:: + |Fess| übernimmt die Gruppenwerte aus der Assertion unverändert: Es findet keine + Verzeichnisabfrage statt, und verschachtelte (transitive) Gruppen werden nicht aufgelöst. + Ob übergeordnete Gruppen enthalten sind, hängt daher allein von der Claim-Konfiguration des IdP + ab -- anders als bei :doc:`sso-entraid`, wo |Fess| übergeordnete Gruppen über die + Microsoft Graph API auflöst. + +Rollenattribut-Konfiguration +---------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Eigenschaft + - Beschreibung + - Standard + * - ``saml.attribute.role.name`` + - Attributname mit Rolleninformationen + - (Keine) + * - ``saml.default.roles`` + - Standardrollen (kommagetrennt) + - (Keine) + +Beispiel:: + + saml.attribute.role.name=roles + saml.default.roles=viewer + +.. note:: + Wenn Attribute nicht vom IdP abgerufen werden können, werden Standardwerte verwendet. + Bei Verwendung der rollenbasierten Suche konfigurieren Sie entsprechende Gruppen oder Rollen. + +.. warning:: + Wenn ``saml.attribute.role.name`` gesetzt ist, werden die vom IdP gesendeten Attributwerte + unverändert zu |Fess|-Rollen. Da ``authentication.admin.roles`` in ``fess_config.properties`` + standardmäßig ``admin`` lautet, erhält jeder Benutzer, dessen Rollenattribut ``admin`` enthält, + Administratorrechte in |Fess|. Prüfen Sie, wer das Rollenattribut auf der IdP-Seite steuern kann, + und ändern Sie ``authentication.admin.roles`` bei Bedarf in einen anderen Namen. + +IdPs mit wiederholten Attributnamen +----------------------------------- + +Wenn der IdP denselben Attributnamen auf mehrere ````-Elemente verteilt, weist |Fess| +die Assertion zurück und die Anmeldung selbst schlägt fehl. + +Keycloak sendet standardmäßig Assertions dieser Form: Seine Rollen- und Gruppen-Mapper geben pro +Wert ein eigenes ````-Element aus, solange deren Option ``single`` nicht aktiviert ist, +und jedes Keycloak-Konto besitzt mehrere Standard-Realm-Rollen. + +Es gibt zwei Abhilfen: + +- Die Werte auf der IdP-Seite in einem einzigen Element zusammenfassen (bei Keycloak die Option + ``single`` der Mapper aktivieren) +- In |Fess| die Wiederholungen zulassen und die Werte zusammenführen + +.. list-table:: + :header-rows: 1 + :widths: 45 40 15 + + * - Eigenschaft + - Beschreibung + - Standard + * - ``saml.security.allow_duplicated_attribute_name`` + - Erlaubt denselben Attributnamen auf mehreren Elementen und führt die Werte zusammen + - ``false`` + +Beispiel:: + + saml.security.allow_duplicated_attribute_name=true + +Sicherheitskonfiguration +======================== + +Für Produktionsumgebungen wird empfohlen, die folgenden Sicherheitseinstellungen zu aktivieren. + +.. note:: + Wenn nicht empfohlene Einstellungen bestehen bleiben, wird beim Laden der SAML-Einstellungen eine + Warnung ``Insecure SAML settings: ...`` in das Protokoll geschrieben. + +Signatureinstellungen +--------------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Eigenschaft + - Beschreibung + - Standard + * - ``saml.security.authnrequest_signed`` + - Authentifizierungsanfragen signieren + - ``false`` + * - ``saml.security.want_messages_signed`` + - Nachrichtensignaturen erfordern + - ``false`` + * - ``saml.security.want_assertions_signed`` + - Assertion-Signaturen erfordern + - ``false`` + * - ``saml.security.logoutrequest_signed`` + - Logout-Anfragen signieren + - ``false`` + * - ``saml.security.logoutresponse_signed`` + - Logout-Antworten signieren + - ``false`` + * - ``saml.security.reject_deprecated_alg`` + - Veraltete Signaturalgorithmen wie SHA-1 ablehnen + - ``false`` + +.. warning:: + Sicherheitsfunktionen sind standardmäßig deaktiviert. + Für Produktionsumgebungen wird dringend empfohlen, mindestens ``saml.security.want_assertions_signed=true`` zu setzen. + +.. note:: + Solange ``saml.security.reject_deprecated_alg`` auf ``false`` steht, werden auch Assertions und + Nachrichten akzeptiert, die mit SHA-1 (``rsa-sha1`` und ``dsa-sha1``) signiert wurden. + Die Option ist nicht standardmäßig aktiviert, weil sie IdPs ablehnt, die weiterhin mit SHA-1 signieren. + Stellen Sie sicher, dass Ihr IdP mit SHA-256 oder stärker signiert, und setzen Sie anschließend + ``saml.security.reject_deprecated_alg=true``. + +.. warning:: + Wenn Single Logout konfiguriert ist (``saml.idp.single_logout_service.url``), setzen Sie unbedingt + auch ``saml.security.want_messages_signed=true``. + Solange die Option ``false`` ist, wird eine LogoutRequest ohne Signatur akzeptiert, sodass eine + präparierte URL die Sitzung eines authentifizierten Benutzers beenden kann. + Die Auswirkung ist eine erzwungene Abmeldung (Denial of Service), keine Kontoübernahme. + +Verschlüsselungseinstellungen +----------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Eigenschaft + - Beschreibung + - Standard + * - ``saml.security.want_assertions_encrypted`` + - Assertion-Verschlüsselung erfordern + - ``false`` + * - ``saml.security.want_nameid_encrypted`` + - NameID-Verschlüsselung erfordern + - ``false`` + * - ``saml.security.allowed_key_transport_algorithms`` + - Beim Entschlüsseln einer Assertion akzeptierte Key-Transport-Algorithmen (kommagetrennte URIs) + - (leer: jeder Algorithmus wird akzeptiert) + +.. note:: + |Fess| validiert Antworten, die mit XML Encryption 1.1 verschlüsselt sind. Das aktuelle + Keycloak verwendet zum Beispiel ``http://www.w3.org/2009/xmlenc11#rsa-oaep`` und nimmt ein + ````-Element in seine Antwort auf; eine solche Antwort wird bei aktivierter + Schemaprüfung angenommen. Frühere Versionen wiesen sie mit + ``Invalid SAML Response. Not match the saml-schema-protocol-2.0.xsd`` zurück. Wurde dafür + ``saml.security.want_xml_validation=false`` gesetzt, entfernen Sie die Einstellung wieder. + +.. note:: + Setzen Sie ``saml.security.allowed_key_transport_algorithms``, sobald ein privater + SP-Schlüssel konfiguriert ist. Solange die Einstellung fehlt, wird jeder + Key-Transport-Algorithmus akzeptiert, auch das veraltete + ``http://www.w3.org/2001/04/xmlenc#rsa-1_5``. Der Assertion-Consumer-Endpunkt ist ohne + Anmeldung erreichbar, und die Entschlüsselung läuft vor der Validierung der Antwort. Ein + nicht authentifizierter Aufrufer kann den privaten SP-Schlüssel daher einen Geheimtext + seiner Wahl entschlüsseln lassen. |Fess| meldet in diesem Fall beim Start + ``key_transport_algorithms_not_restricted`` in der Zeile ``Insecure SAML settings``. + Beschränken Sie die Einstellung auf das, was der IdP tatsächlich verwendet:: + + saml.security.allowed_key_transport_algorithms=http://www.w3.org/2009/xmlenc11#rsa-oaep + +Konfiguration von SP-Zertifikat und privatem Schlüssel +------------------------------------------------------ + +Wenn der SP Authentifizierungsanfragen oder Logout-Nachrichten signiert (z. B. ``saml.security.authnrequest_signed``) oder die Verschlüsselung von Assertions oder der NameID anfordert (z. B. ``saml.security.want_assertions_encrypted``), müssen der private Schlüssel und das X.509-Zertifikat des SP konfiguriert werden. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Eigenschaft + - Beschreibung + - Standard + * - ``saml.sp.x509cert`` + - SP X.509-Zertifikat (Base64-codiert, ohne Zeilenumbrüche) + - + * - ``saml.sp.privatekey`` + - Privater Schlüssel des SP (Base64-codiert, ohne Zeilenumbrüche) + - + +.. note:: + Für ``saml.sp.x509cert`` und ``saml.sp.privatekey`` gilt, wie bei ``saml.idp.x509cert``, dass der Base64-codierte Inhalt als einzelne Zeile ohne Zeilenumbrüche angegeben werden muss (die Zeilen ``-----BEGIN ...-----`` und ``-----END ...-----`` dürfen nicht enthalten sein). + Wenn Signierung oder Verschlüsselung aktiviert wird, muss das SP-Zertifikat auch auf der IdP-Seite registriert werden. Das SP-Zertifikat wird im SP-Metadaten-Endpunkt unter ``/sso/metadata`` veröffentlicht. + +Weitere Sicherheitseinstellungen +-------------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Eigenschaft + - Beschreibung + - Standard + * - ``saml.strict`` + - Strikter Modus (strenge Validierung durchführen) + - ``true`` + * - ``saml.security.want_xml_validation`` + - XML-Schema-Validierung von Nachrichten durchführen + - ``true`` + * - ``saml.security.signature_algorithm`` + - Signaturalgorithmus + - ``http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`` + * - ``saml.security.requested_authncontext`` + - Angeforderter Authentifizierungskontext + - ``urn:oasis:names:tc:SAML:2.0:ac:classes:Password`` + * - ``saml.sp.nameidformat`` + - NameID-Format + - ``urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`` + +.. note:: + |Fess| verwendet intern eine SAML-Bibliothek (java-saml), und Eigenschaften mit dem Präfix ``saml.`` werden auf die entsprechenden Einstellungen der Bibliothek (Präfix ``onelogin.saml2.``) abgebildet. + Daher können in ``system.properties`` neben den hier aufgeführten Einstellungen auch detailliertere Einstellungen vorgenommen werden, wie z. B. Bindings (z. B. ``saml.sp.assertion_consumer_service.binding``), Organisationsinformationen (``saml.organization.*``) und Kontaktinformationen (``saml.contacts.*``). + +AuthnRequest-Gültigkeitsdauer +============================= + +|Fess| sendet bei jedem Zugriff auf ``/sso/`` eine AuthnRequest an den IdP und speichert deren ID in der Sitzung. +Die vom IdP zurückgegebene SAML-Antwort wird anhand der gespeicherten ID validiert. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Eigenschaft + - Beschreibung + - Standard + * - ``saml.request.id.ttl`` + - Wie lange die ID einer unbeantworteten AuthnRequest aufbewahrt wird (Sekunden) + - ``3600`` + +Eine gespeicherte ID wird verworfen, sobald dieser Zeitraum verstrichen ist. +Ist die Gültigkeit abgelaufen (zum Beispiel weil die Anmeldeseite des IdP offen gelassen wurde), kann die zurückgegebene Assertion nicht zugeordnet werden, und die Anmeldung schlägt einmalig fehl. + +Konfigurationsbeispiele +======================= + +Minimale Konfiguration (für Tests) +---------------------------------- + +Das Folgende ist ein minimales Konfigurationsbeispiel zur Überprüfung in einer Testumgebung. + +:: + + # SSO aktivieren + sso.type=saml + + # SP-Konfiguration + saml.sp.base.url=https://fess.example.com + + # IdP-Konfiguration (Werte aus der IdP-Administrationskonsole setzen) + saml.idp.entityid=https://idp.example.com/saml/metadata + saml.idp.single_sign_on_service.url=https://idp.example.com/saml/sso + saml.idp.x509cert=MIIDpDCCAoygAwIBAgI...(Base64-codiertes Zertifikat) + + # Standardgruppen + saml.default.groups=user + +Empfohlene Konfiguration (für Produktion) +----------------------------------------- + +Das Folgende ist ein empfohlenes Konfigurationsbeispiel für Produktionsumgebungen. + +:: + + # SSO aktivieren + sso.type=saml + + # SP-Konfiguration + saml.sp.base.url=https://fess.example.com + + # IdP-Konfiguration + saml.idp.entityid=https://idp.example.com/saml/metadata + saml.idp.single_sign_on_service.url=https://idp.example.com/saml/sso + saml.idp.single_logout_service.url=https://idp.example.com/saml/logout + saml.idp.x509cert=MIIDpDCCAoygAwIBAgI...(Base64-codiertes Zertifikat) + + # Benutzerattribut-Zuordnung + saml.attribute.group.name=groups + saml.attribute.role.name=roles + saml.default.groups=user + + # Sicherheitseinstellungen (für Produktion empfohlen) + saml.security.want_assertions_signed=true + saml.security.want_messages_signed=true + + # Aktivieren, nachdem bestätigt wurde, dass der IdP mit SHA-256 oder stärker signiert + saml.security.reject_deprecated_alg=true + +Fehlerbehebung +============== + +Häufige Probleme und Lösungen +----------------------------- + +Kann nach der Authentifizierung nicht zu Fess zurückkehren +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Überprüfen Sie, ob die ACS URL auf der IdP-Seite korrekt konfiguriert ist +- Stellen Sie sicher, dass der Wert von ``saml.sp.base.url`` mit der IdP-Konfiguration übereinstimmt +- Die SAML-Assertion trifft als seitenübergreifender POST vom IdP ein. Wenn + ``tomcat.sameSiteCookies`` in ``tomcat_config.properties`` auf ``lax`` (Standard) steht, sendet der + Browser das Sitzungs-Cookie nicht mit, und die Anmeldung schlägt einmalig fehl. + Setzen Sie in diesem Fall ``tomcat.sameSiteCookies = none`` (``SameSite=None`` erfordert HTTPS) +- Wenn die Anmeldung am IdP zu lange gedauert hat, ist die AuthnRequest-ID nicht mehr vorhanden, + sobald die Assertion zurückkommt; die Anmeldung schlägt einmalig fehl und muss neu gestartet werden +- |Fess| setzt in ``app/WEB-INF/web.xml`` kein ``session-timeout``, sodass der Standardwert des + Servlet-Containers von 30 Minuten gilt; er ist kürzer als die 3600 Sekunden von + ``saml.request.id.ttl``, sodass die Sitzung zuerst verworfen wird. Ein höherer Wert für + ``saml.request.id.ttl`` allein verlängert daher nicht die Zeit, die Benutzer für die Anmeldung am + IdP haben. Erhöhen Sie dafür auch den Sitzungs-Timeout + +Destination-Validierung schlägt hinter einem Reverse Proxy fehl +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Wenn |Fess| hinter einem TLS-terminierenden Reverse Proxy oder Load Balancer betrieben wird, kann die +Assertion-Validierung fehlschlagen, obwohl ``saml.sp.base.url`` korrekt gesetzt ist. + +Das Attribut ``Destination`` der Assertion wird mit der URL der Anfrage verglichen, so wie sie bei +|Fess| ankommt -- hinter einem TLS-terminierenden Proxy also eine interne ``http://``-URL und nicht +die externe, an die der IdP die Assertion gesendet hat. ``saml.sp.base.url`` wird für diesen +Vergleich nicht herangezogen; die Einstellung allein behebt das Problem daher nicht. + +Setzen Sie ``saml.debug=true``, damit der Grund ins Protokoll geschrieben wird: + +:: + + The response was received at http://... instead of https://fess.example.com/sso/ + +Passen Sie die Connector-Einstellungen in ``tomcat_config.properties`` an das von außen sichtbare +Schema und den Port an. Diese Einstellungen werden auskommentiert ausgeliefert: + +:: + + tomcat.secure=true + tomcat.scheme=https + tomcat.proxyPort=443 + +Konfigurieren Sie außerdem den Reverse Proxy so, dass er den ursprünglichen ``Host``-Header an |Fess| +durchreicht, denn der Hostname-Teil der Anfrage-URL wird aus diesem Header gebildet. Nach Änderungen +an ``tomcat_config.properties`` muss |Fess| neu gestartet werden. + +Dieselbe Prüfung gilt für Single-Logout-Nachrichten; konfigurieren Sie dies bei Verwendung von SLO +entsprechend. + +Signaturüberprüfungsfehler +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Überprüfen Sie, ob das IdP-Zertifikat korrekt konfiguriert ist +- Stellen Sie sicher, dass das Zertifikat nicht abgelaufen ist +- Das Zertifikat sollte nur als Base64-codierter Inhalt ohne Zeilenumbrüche angegeben werden + +Anmeldung schlägt wegen wiederholter Attributnamen fehl +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Wenn im Log eine Warnung beginnend mit ``The IdP repeated an attribute name in the SAML + assertion`` erscheint, verteilt der IdP denselben Attributnamen auf mehrere ````-Elemente +- Die Assertion selbst wurde erfolgreich geprüft; Zertifikat und Zeitabweichung sind nicht die Ursache +- Fassen Sie die Attribute auf der IdP-Seite zusammen oder setzen Sie + ``saml.security.allow_duplicated_attribute_name=true`` + +Benutzergruppen/-rollen werden nicht reflektiert +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Überprüfen Sie, ob die Attribute auf der IdP-Seite korrekt konfiguriert sind +- Stellen Sie sicher, dass der Wert von ``saml.attribute.group.name`` mit dem vom IdP gesendeten Attributnamen übereinstimmt +- Bei Microsoft Entra ID enthält der Gruppen-Claim die ``ObjectId``-GUIDs der Gruppen, sofern kein + anderes Quellattribut ausgewählt ist; die Werte stimmen daher nicht mit den Gruppennamen überein +- Microsoft Entra ID lässt den Gruppen-Claim vollständig weg, wenn ein Benutzer mehr als 150 + Gruppen angehört (verschachtelte Gruppen zählen mit); |Fess| greift dann auf + ``saml.default.groups`` zurück +- Aktivieren Sie den Debug-Modus, um den Inhalt der SAML-Assertion zu überprüfen + +Debug-Einstellungen +------------------- + +Um Probleme zu untersuchen, können Sie den Debug-Modus mit der folgenden Einstellung aktivieren: + +:: + + saml.debug=true + +Durch das Setzen von ``saml.debug=true`` wird bei einem fehlgeschlagenen SAML-Authentifizierungsversuch die detaillierte Fehlerursache in das Protokoll ausgegeben. + +Außerdem können detaillierte SAML-bezogene Protokolle ausgegeben werden, indem der folgende Logger in ``app/WEB-INF/classes/log4j2.xml`` hinzugefügt wird: + +:: + + + +Referenz +======== + +- :doc:`security-role` - Konfiguration der rollenbasierten Suche +- :doc:`sso-oidc` - SSO-Konfiguration mit OpenID Connect +- :doc:`sso-entraid` - SSO-Konfiguration speziell für Microsoft Entra ID diff --git a/de/15.10/config/sso-spnego.rst b/de/15.10/config/sso-spnego.rst new file mode 100644 index 000000000..bfaaa1681 --- /dev/null +++ b/de/15.10/config/sso-spnego.rst @@ -0,0 +1,499 @@ +============================================================ +SSO-Konfiguration mit Windows-integrierter Authentifizierung +============================================================ + +Übersicht +========= + +|Fess| unterstützt Single Sign-On (SSO)-Authentifizierung mit Windows-integrierter Authentifizierung (SPNEGO/Kerberos). +Durch die Verwendung der Windows-integrierten Authentifizierung können Benutzer, die an einem Windows-Domänencomputer angemeldet sind, ohne zusätzliche Anmeldevorgänge auf |Fess| zugreifen. + +.. note:: + Die Unterstützung für die Windows-integrierte Authentifizierung kommt aus dem Plugin + ``fess-sso-spnego``, das nicht Teil der Distribution ist. Installieren Sie es über die Seite + **System > Plugin** in der Administrationsoberfläche oder mit + ``bin/fess-setup install plugin fess-sso-spnego``. + Bis dahin wird eine Anfrage an ``/sso/`` mit ``sso.type=spnego`` nur zur Anmeldeseite + zurückgeleitet. + +Wie die Windows-integrierte Authentifizierung funktioniert +---------------------------------------------------------- + +Bei der Windows-integrierten Authentifizierung verwendet |Fess| das SPNEGO-Protokoll (Simple and Protected GSSAPI Negotiation Mechanism) für die Kerberos-Authentifizierung. + +1. Benutzer meldet sich an der Windows-Domäne an +2. Benutzer greift auf |Fess| zu +3. |Fess| sendet eine SPNEGO-Herausforderung +4. Browser erhält ein Kerberos-Ticket und sendet es an den Server +5. |Fess| validiert das Ticket und ruft den Benutzernamen ab +6. Gruppeninformationen des Benutzers werden über LDAP abgerufen +7. Benutzer ist angemeldet und Gruppeninformationen werden auf die rollenbasierte Suche angewendet + +Informationen zur Integration mit der rollenbasierten Suche finden Sie unter :doc:`security-role`. + +Voraussetzungen +=============== + +Bevor Sie die Windows-integrierte Authentifizierung konfigurieren, überprüfen Sie die folgenden Voraussetzungen: + +- |Fess| 15.10 oder höher ist installiert +- Ein Active Directory (AD)-Server ist verfügbar +- |Fess|-Server ist von der AD-Domäne aus erreichbar +- Sie haben die Berechtigung, Dienstprinzipalnamen (SPN) in AD zu konfigurieren +- Ein Konto zum Abrufen von Benutzerinformationen über LDAP ist verfügbar + +Active Directory-seitige Konfiguration +======================================= + +Registrieren des Dienstprinzipalnamens (SPN) +-------------------------------------------- + +Sie müssen einen SPN für |Fess| in Active Directory registrieren. +Öffnen Sie eine Eingabeaufforderung auf einem Windows-Computer, der der AD-Domäne beigetreten ist, und führen Sie den Befehl ``setspn`` aus. + +:: + + setspn -S HTTP/ + +Beispiel: + +:: + + setspn -S HTTP/fess-server.example.local svc_fess + +So überprüfen Sie die Registrierung: + +:: + + setspn -L + +.. note:: + Wenn Sie den Befehl auf dem Fess-Server ausgeführt haben, melden Sie sich nach der SPN-Registrierung von Windows ab und wieder an. + +Grundkonfiguration +================== + +SSO aktivieren +-------------- + +Um die Windows-integrierte Authentifizierung zu aktivieren, fügen Sie die folgende Einstellung in ``app/WEB-INF/conf/system.properties`` hinzu: + +:: + + sso.type=spnego + +Kerberos-Konfigurationsdatei +---------------------------- + +Erstellen Sie ``app/WEB-INF/classes/krb5.conf`` mit der Kerberos-Konfiguration. + +:: + + [libdefaults] + default_realm = EXAMPLE.LOCAL + default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + + [realms] + EXAMPLE.LOCAL = { + kdc = AD-SERVER.EXAMPLE.LOCAL + default_domain = EXAMPLE.LOCAL + } + + [domain_realm] + example.local = EXAMPLE.LOCAL + .example.local = EXAMPLE.LOCAL + +.. note:: + Ersetzen Sie ``EXAMPLE.LOCAL`` durch Ihren AD-Domänennamen (Großbuchstaben) und ``AD-SERVER.EXAMPLE.LOCAL`` durch Ihren AD-Server-Hostnamen. + +.. warning:: + Ein Service-Ticket mit einem Verschlüsselungstyp, der nicht in ``permitted_enctypes`` aufgeführt ist, + wird von der Kerberos-Gegenstelle mit ``encryption type not in permitted_enctypes list`` abgelehnt. + Active Directory stellt in der Regel AES256-Service-Tickets aus, daher muss AES256 enthalten sein. + +.. note:: + RC4 (``rc4-hmac``), 3DES und DES sind ab Java 17 standardmäßig deaktiviert; sie aufzuführen hat + keine Wirkung. Das obige Beispiel gibt daher nur AES an. + ``aes256-cts-hmac-sha384-192`` und ``aes128-cts-hmac-sha256-128`` sind die von Windows Server 2025 + unterstützten AES-SHA2-Typen (RFC 8009). + Ein Dienstkonto, das nur einen RC4-Schlüssel besitzt, kann nicht für die Kerberos-Authentifizierung + verwendet werden. Setzen Sie sein Kennwort zurück, damit AES-Schlüssel erzeugt werden. + +Login-Konfigurationsdatei +------------------------- + +Erstellen Sie ``app/WEB-INF/classes/auth_login.conf`` mit der JAAS-Login-Konfiguration. + +:: + + spnego-client { + com.sun.security.auth.module.Krb5LoginModule required; + }; + + spnego-server { + com.sun.security.auth.module.Krb5LoginModule required + storeKey=true + isInitiator=false; + }; + +.. note:: + Die Standarddateinamen für ``krb5.conf`` und ``auth_login.conf`` werden über ``spnego.krb5.conf`` bzw. ``spnego.login.conf`` festgelegt, die Dateien selbst müssen jedoch zwingend erstellt werden. + SPNEGO wird bei der ersten Anmeldung initialisiert. Fehlen diese Dateien, startet |Fess| zwar, die SSO-Anmeldung schlägt jedoch fehl. + +Erforderliche Einstellungen +--------------------------- + +Fügen Sie die folgenden Einstellungen zu ``app/WEB-INF/conf/system.properties`` hinzu. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Eigenschaft + - Beschreibung + - Standard + * - ``spnego.preauth.username`` + - AD-Verbindungsbenutzername + - (Erforderlich, sofern kein Keytab verwendet wird) + * - ``spnego.preauth.password`` + - AD-Verbindungspasswort + - (Erforderlich, sofern kein Keytab verwendet wird) + * - ``spnego.krb5.conf`` + - Pfad zur Kerberos-Konfigurationsdatei + - ``krb5.conf`` + * - ``spnego.login.conf`` + - Pfad zur Login-Konfigurationsdatei + - ``auth_login.conf`` + +.. note:: + Bleiben ``spnego.preauth.username`` und ``spnego.preauth.password`` beide leer, verwendet das + Server-Login-Modul eine Keytab-Datei. + Wenn Sie das Kennwort des AD-Dienstkontos nicht in einer |Fess|-Konfigurationsdatei speichern + möchten, erstellen Sie eine Keytab-Datei und konfigurieren Sie ``spnego-server`` in + ``auth_login.conf`` wie folgt. + + :: + + spnego-server { + com.sun.security.auth.module.Krb5LoginModule required + useKeyTab=true + keyTab="/var/lib/fess/fess.keytab" + principal="HTTP/fess-server.example.local@EXAMPLE.LOCAL" + storeKey=true + isInitiator=false; + }; + +Optionale Einstellungen +----------------------- + +Die folgenden Einstellungen können bei Bedarf hinzugefügt werden. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Eigenschaft + - Beschreibung + - Standard + * - ``spnego.login.client.module`` + - Name des Client-Moduls + - ``spnego-client`` + * - ``spnego.login.server.module`` + - Name des Server-Moduls + - ``spnego-server`` + * - ``spnego.allow.basic`` + - Basic-Authentifizierung erlauben + - ``true`` + * - ``spnego.allow.unsecure.basic`` + - Unsichere Basic-Authentifizierung erlauben + - ``false`` + * - ``spnego.prompt.ntlm`` + - Bei Empfang eines NTLM-Tokens auf Basic-Authentifizierung zurückfallen + - ``true`` + * - ``spnego.allow.localhost`` + - Localhost-Zugriff erlauben + - ``false`` + * - ``spnego.allow.delegation`` + - Delegierung erlauben + - ``false`` + * - ``spnego.allowed.realms`` + - Zusätzlich zur Server-Realm akzeptierte Kerberos-Realms (kommagetrennt) + - (Keine) + * - ``spnego.logger.level`` + - Interner Protokollierungsgrad der SPNEGO-Bibliothek (``1`` =FINEST, ``2`` =FINER, ``3`` =FINE, ``4`` =CONFIG, ``6`` =WARNING, ``7`` =SEVERE; alle anderen Werte einschließlich ``0`` und ``5`` werden als INFO behandelt) + - (Automatisch) + +.. warning:: + ``spnego.allow.unsecure.basic=true`` kann Base64-kodierte Anmeldeinformationen über unverschlüsselte Verbindungen senden. + Für Produktionsumgebungen wird dringend empfohlen, dies auf ``false`` zu setzen und HTTPS zu verwenden. + +.. note:: + Mit ``spnego.allow.unsecure.basic=false`` (Standard) wird die Basic-Authentifizierung nur für + Anfragen angeboten, bei denen ``HttpServletRequest#isSecure()`` ``true`` zurückgibt. + Wird TLS an einem Reverse-Proxy terminiert und die Anfrage per HTTP an |Fess| weitergeleitet, + ist dieser Wert ``false``. Ein Client, der kein Kerberos-Ticket erhalten kann und auf NTLM + zurückfällt, kann sich dann nicht anmelden. Setzen Sie ``tomcat.secure=true`` in + ``tomcat_config.properties``, damit |Fess| die Anfrage als über HTTPS eingegangen behandelt. + Diese Datei liegt in der ZIP-Distribution unter ``lib/classes/`` und in den DEB/RPM-Paketen + unter ``/etc/fess/``; nach einer Änderung muss |Fess| neu gestartet werden. + +.. warning:: + In |Fess| 15.10 wird eine Anmeldung standardmäßig abgelehnt, wenn sich die Realm des + Client-Principals von der Realm des Servers unterscheidet. Melden sich Benutzer aus einer + untergeordneten Domäne einer AD-Domänenstruktur oder aus einer vertrauten Gesamtstruktur an, + tragen Sie diese Realms kommagetrennt in ``spnego.allowed.realms`` ein. Andernfalls werden + Benutzer, die sich bis 15.7 anmelden konnten, mit ``Kerberos realm is not allowed`` + abgewiesen. + +.. warning:: + |Fess| identifiziert einen Benutzer über den Teil des Principals vor ``@``; die Realm ist damit + nicht Teil des Benutzernamens. Wenn Sie in ``spnego.allowed.realms`` weitere Realms eintragen, + werden Benutzer, die denselben Kontonamen in mehreren Realms besitzen — zum Beispiel + ``alice@CORP.EXAMPLE.COM`` und ``alice@PARTNER.EXAMPLE.COM`` — zu demselben |Fess|-Benutzer + und teilen sich dessen Gruppen, Rollen und Dokumentberechtigungen. Tragen Sie eine Realm nur + dann ein, wenn der Kontoname über alle aufgeführten Realms hinweg genau eine Person + identifiziert. + +.. note:: + Die Zulassungsliste gilt auch für den Rückfall auf die Basic-Authentifizierung. Gibt ein + Benutzer einen Namen der Form ``user@REALM`` ein, wird diese Realm gegen + ``spnego.allowed.realms`` geprüft und die Anmeldung abgelehnt, wenn sie nicht zulässig ist. Ein + einfacher Kontoname oder die Form ``DOMAIN\user`` benennt keine Realm und wird in der + Standard-Realm aus ``krb5.conf`` authentifiziert. Da eine Basic-Anmeldung direkt gegen die vom + Benutzer eingegebene Realm authentifiziert wird, halten Sie die Zulassungsliste möglichst klein + und setzen Sie ``spnego.allow.basic`` auf ``false``, wenn Sie sich auf sie als Sicherheitsgrenze + verlassen. + +.. note:: + Wenn ``spnego.prompt.ntlm=true`` (Standard), muss auch ``spnego.allow.basic`` auf ``true`` gesetzt sein. + Wenn Sie ``spnego.allow.basic=false`` setzen, müssen Sie gleichzeitig ``spnego.prompt.ntlm=false`` setzen. + Wird diese Bedingung nicht erfüllt, tritt bei der SPNEGO-Initialisierung ein Fehler auf. + +.. note:: + ``spnego.logger.level`` steuert den Protokollierungsgrad des internen Loggers der SPNEGO-Bibliothek (``java.util.logging``-Logger mit dem Namen ``Spnego``). + Wenn nicht gesetzt, wird er automatisch entsprechend dem Protokollierungsgrad von |Fess| bestimmt. + +LDAP-Konfiguration +================== + +Die LDAP-Konfiguration ist erforderlich, um Gruppeninformationen für Benutzer abzurufen, die über Windows-integrierte Authentifizierung authentifiziert werden. +Konfigurieren Sie LDAP-Einstellungen im |Fess|-Administrationsbereich unter "System" -> "Allgemein". + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Element + - Beispiel + * - LDAP-URL + - ``ldap://AD-SERVER.example.local:389`` + * - Basis-DN + - ``dc=example,dc=local`` + * - Bind-DN + - ``svc_fess@example.local`` + * - Passwort + - Passwort für AD-Zugriffsbenutzer + * - Benutzer-DN + - ``%s@example.local`` + * - Kontofilter + - ``(&(objectClass=user)(sAMAccountName=%s))`` + * - memberOf-Attribut + - ``memberOf`` + +.. note:: + |Fess| liest das Attribut ``memberOf`` des Benutzers nur eine Ebene tief, sodass verschachtelte + Gruppen (eine Gruppe als Mitglied einer anderen Gruppe) standardmäßig nicht aufgelöst werden. + Um verschachtelte AD-Gruppen abzubilden, setzen Sie unter „System“ → „Allgemein“ in der + Administrationsoberfläche den Gruppenfilter (``ldap.group.filter``) auf + ``(member:1.2.840.113556.1.4.1941:=%s)``. Die Auflösung läuft nach der Anmeldung asynchron, + daher enthält der Anmeldeeintrag im Audit-Log nur die zuvor aufgelösten Gruppen. + +Browser-Einstellungen +===================== + +Client-Browser-Einstellungen sind erforderlich, um die Windows-integrierte Authentifizierung zu verwenden. + +Internet Explorer / Microsoft Edge +---------------------------------- + +1. Internetoptionen öffnen +2. Registerkarte "Sicherheit" auswählen +3. Auf "Sites" für die Zone "Lokales Intranet" klicken +4. Auf "Erweitert" klicken und die Fess-URL hinzufügen +5. Auf "Stufe anpassen" für die Zone "Lokales Intranet" klicken +6. Unter "Benutzerauthentifizierung" -> "Anmeldung" die Option "Automatische Anmeldung nur in der Intranetzone" auswählen +7. Auf der Registerkarte "Erweitert" die Option "Integrierte Windows-Authentifizierung aktivieren" aktivieren + +Google Chrome +------------- + +Chrome verwendet normalerweise die Windows-Internetoptionseinstellungen. +Falls zusätzliche Konfiguration erforderlich ist, setzen Sie ``AuthServerAllowlist`` über Gruppenrichtlinie oder Registrierung. + +Mozilla Firefox +--------------- + +1. ``about:config`` in die Adressleiste eingeben +2. Nach ``network.negotiate-auth.trusted-uris`` suchen +3. Die Fess-Server-URL oder Domäne setzen (z.B. ``https://fess-server.example.local``) + +Konfigurationsbeispiele +======================= + +Minimale Konfiguration (zum Testen) +------------------------------------ + +Das Folgende ist ein minimales Konfigurationsbeispiel für eine Testumgebung. + +``app/WEB-INF/conf/system.properties``: + +:: + + # SSO aktivieren + sso.type=spnego + + # SPNEGO-Einstellungen + spnego.preauth.username=svc_fess + spnego.preauth.password=your-password + +``app/WEB-INF/classes/krb5.conf``: + +:: + + [libdefaults] + default_realm = EXAMPLE.LOCAL + default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + + [realms] + EXAMPLE.LOCAL = { + kdc = AD-SERVER.EXAMPLE.LOCAL + default_domain = EXAMPLE.LOCAL + } + + [domain_realm] + example.local = EXAMPLE.LOCAL + .example.local = EXAMPLE.LOCAL + +``app/WEB-INF/classes/auth_login.conf``: + +:: + + spnego-client { + com.sun.security.auth.module.Krb5LoginModule required; + }; + + spnego-server { + com.sun.security.auth.module.Krb5LoginModule required + storeKey=true + isInitiator=false; + }; + +Empfohlene Konfiguration (für Produktion) +------------------------------------------ + +Das Folgende ist ein empfohlenes Konfigurationsbeispiel für Produktionsumgebungen. + +``app/WEB-INF/conf/system.properties``: + +:: + + # SSO aktivieren + sso.type=spnego + + # SPNEGO-Einstellungen + spnego.preauth.username=svc_fess + spnego.preauth.password=your-secure-password + spnego.krb5.conf=krb5.conf + spnego.login.conf=auth_login.conf + + # Sicherheitseinstellungen (Produktion) + spnego.allow.basic=false + spnego.allow.unsecure.basic=false + spnego.prompt.ntlm=false + spnego.allow.localhost=false + +.. note:: + Wenn Sie ``spnego.allow.basic=false`` setzen, müssen Sie auch ``spnego.prompt.ntlm=false`` zwingend setzen. + Da ``spnego.prompt.ntlm`` standardmäßig ``true`` ist, tritt bei der Initialisierung ein Fehler auf, wenn diese Einstellung weggelassen wird. + +Fehlerbehebung +============== + +Häufige Probleme und Lösungen +------------------------------ + +Authentifizierungsdialog erscheint +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Überprüfen Sie, ob der Fess-Server in den Browser-Einstellungen zur Zone "Lokales Intranet" hinzugefügt wurde +- Überprüfen Sie, ob "Integrierte Windows-Authentifizierung aktivieren" aktiviert ist +- Überprüfen Sie, ob der SPN korrekt registriert ist (``setspn -L ``) + +Authentifizierungsfehler treten auf +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Überprüfen Sie, ob der Domänenname (Großbuchstaben) und der AD-Servername in ``krb5.conf`` korrekt sind +- Überprüfen Sie, ob ``spnego.preauth.username`` und ``spnego.preauth.password`` korrekt sind +- Überprüfen Sie die Netzwerkverbindung zum AD-Server + +Gruppeninformationen können nicht abgerufen werden +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Überprüfen Sie, ob die LDAP-Einstellungen korrekt sind +- Überprüfen Sie, ob Bind-DN und Passwort korrekt sind +- Überprüfen Sie, ob der Benutzer in AD zu Gruppen gehört + +Die Anmeldung liefert HTTP 400 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Bei Benutzern mit vielen Gruppenmitgliedschaften wird das Kerberos-Ticket (PAC) groß, und der +``Authorization``-Header kann Tomcats Standardgrenze von 8 KB überschreiten, was mit 400 beantwortet wird. +Die Anfrage erreicht |Fess| nie, daher wird nichts protokolliert. +Erhöhen Sie das Limit in ``tomcat_config.properties``. + +:: + + tomcat.maxHttpHeaderSize=65536 + +Nach Änderung des Dienstkonto-Kennworts schlägt die Authentifizierung fehl +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Die Server-Anmeldeinformationen werden einmalig bei der ersten Anmeldung ermittelt und für die +Laufzeit des Prozesses zwischengespeichert. +Starten Sie |Fess| neu, nachdem Sie das Kennwort des Dienstkontos in AD geändert oder die +Keytab-Datei ersetzt haben. Ebenso ist nach einer Änderung von ``spnego.*``-Einstellungen ein +Neustart erforderlich. + +Debug-Einstellungen +-------------------- + +Um Probleme zu untersuchen, können Sie detaillierte SPNEGO-bezogene Protokolle ausgeben. + +Um detaillierte interne Protokolle der SPNEGO-Bibliothek auszugeben, fügen Sie Folgendes zu ``app/WEB-INF/conf/system.properties`` hinzu. +``spnego.logger.level=1`` gibt die ausführlichsten Protokolle (FINEST) aus. + +:: + + spnego.logger.level=1 + +Um detaillierte Protokolle der SPNEGO-Integrations-Verarbeitung auf der |Fess|-Seite (Paket ``org.codelibs.fess.sso.spnego``) auszugeben, fügen Sie den folgenden Logger zu ``app/WEB-INF/classes/log4j2.xml`` hinzu. + +:: + + + +.. note:: + Die Protokolle der SPNEGO-Bibliothek selbst werden über ``java.util.logging`` ausgegeben und daher über ``spnego.logger.level`` und nicht über ``log4j2.xml`` gesteuert. + Die Protokolle der Integrations-Verarbeitung auf der |Fess|-Seite werden über den Logger in ``log4j2.xml`` gesteuert. + +Referenz +======== + +- :doc:`security-role` - Konfiguration der rollenbasierten Suche +- :doc:`sso-saml` - SSO-Konfiguration mit SAML-Authentifizierung +- :doc:`sso-oidc` - SSO-Konfiguration mit OpenID Connect-Authentifizierung +- :doc:`sso-entraid` - SSO-Konfiguration mit Microsoft Entra ID diff --git a/de/15.10/dev/datastore-plugin.rst b/de/15.10/dev/datastore-plugin.rst new file mode 100644 index 000000000..aaa9ba0d2 --- /dev/null +++ b/de/15.10/dev/datastore-plugin.rst @@ -0,0 +1,557 @@ +================================== +DataStore-Plugin-Entwicklung +================================== + +Übersicht +========= + +Durch die Entwicklung eines DataStore-Plugins können Sie |Fess| um die Fähigkeit +zur Inhaltserfassung aus neuen Datenquellen erweitern. Ein DataStore ruft +Datensätze aus externen Systemen wie Datenbanken, APIs oder Dateien ab, wandelt +sie gemäß dem in der Administrationsoberfläche konfigurierten Mapping-Skript in +Indexfelder um und registriert sie anschließend im Index von |Fess|. + +Alle öffentlich verfügbaren Konnektoren (``fess-ds-*``) für CSV, JSON, +Datenbanken, Git und verschiedene Cloud-Dienste sind nach diesem Mechanismus +implementiert. Als Implementierungsvorlage steht +`fess-ds-example `__ zur Verfügung. +Beim Erstellen eines neuen Konnektors ist es daher am einfachsten, dieses +Repository zu kopieren und darauf aufzubauen. + +Grundstruktur +============= + +Ein DataStore-Plugin besteht aus den folgenden drei Elementen: + +- Erstellen einer Klasse, die von ``AbstractDataStore`` erbt +- Implementieren der beiden Methoden ``getName()`` und ``storeData()`` +- Registrieren als Komponente in ``fess_ds++.xml`` + +Minimale Implementierung +------------------------- + +.. code-block:: java + + package org.codelibs.fess.ds.example; + + import java.util.Map; + + import org.codelibs.fess.ds.AbstractDataStore; + import org.codelibs.fess.ds.callback.IndexUpdateCallback; + import org.codelibs.fess.entity.DataStoreParams; + import org.codelibs.fess.opensearch.config.exentity.DataConfig; + + public class ExampleDataStore extends AbstractDataStore { + + @Override + protected String getName() { + // Wird als Handler-Name verwendet. Es ist üblich, den einfachen + // Klassennamen zurückzugeben + return this.getClass().getSimpleName(); + } + + @Override + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { + + // Datenabruf und -verarbeitung hier implementieren + } + } + +.. note:: + + ``getName()`` und ``storeData()`` sind beide ``protected`` deklarierte + abstrakte Methoden. Beachten Sie, dass sich das Paket von ``DataConfig`` in + |Fess| 15.x unter ``org.codelibs.fess.opensearch.config.exentity`` befindet + (das frühere ``org.codelibs.fess.es.config.exentity`` wurde entfernt). + +Komponenten-Registrierung +-------------------------- + +Damit |Fess| den erstellten DataStore erkennt, wird die Komponente in +``src/main/resources/fess_ds++.xml`` registriert. + +.. code-block:: xml + + + + + + + + + +Durch ```` wird nach der Erzeugung der +Komponente automatisch die von ``AbstractDataStore`` bereitgestellte Methode +``register()`` aufgerufen, wodurch sich die Komponente selbst bei +``DataStoreFactory`` registriert. Der dabei registrierte Name ist der +Rückgabewert von ``getName()`` (im obigen Beispiel ``ExampleDataStore``) und +entspricht dem „Handler-Name", der in der Datenspeicher-Konfiguration der +Administrationsoberfläche ausgewählt wird. + +AbstractDataStore +================= + +Wichtige Methoden +------------------ + +.. list-table:: + :header-rows: 1 + :widths: 35 20 45 + + * - Methode + - Kategorie + - Beschreibung + * - ``getName()`` + - Implementierung (erforderlich) + - Abstrakte Methode, die den Handler-Namen des DataStore zurückgibt. Es ist üblich, ``getClass().getSimpleName()`` zurückzugeben + * - ``storeData()`` + - Implementierung (erforderlich) + - Abstrakte Methode, die Datenabruf, -umwandlung und Index-Registrierung durchführt + * - ``register()`` + - Geerbt (in der Regel keine Änderung nötig) + - Wird über ``postConstruct`` in ``fess_ds++.xml`` automatisch aufgerufen und registriert die Komponente bei ``DataStoreFactory`` + * - ``store()`` + - Geerbt (Framework-Aufruf) + - Einstiegspunkt, der vom Framework aufgerufen wird. Bereitet u. a. ``defaultDataMap`` vor und ruft ``storeData()`` auf + * - ``convertValue()`` + - Geerbt (Hilfsmethode) + - Wertet den Wert (das Template) aus ``scriptMap`` mit der Skript-Engine aus + * - ``getScriptType()`` + - Geerbt (Hilfsmethode) + - Ruft den Parameter ``script_type`` ab (Standard ist Groovy) + * - ``getReadInterval()`` + - Geerbt (Hilfsmethode) + - Ruft den Parameter ``readInterval`` (in Millisekunden) ab + * - ``sleep()`` + - Geerbt (Hilfsmethode) + - Wartet die angegebene Anzahl an Millisekunden (wird zum Warten zwischen Datensätzen verwendet) + +Parameter von storeData +------------------------- + +An die Methode ``storeData()`` übergebene Parameter: + +.. list-table:: + :header-rows: 1 + :widths: 25 35 40 + + * - Parameter + - Typ + - Beschreibung + * - ``dataConfig`` + - ``DataConfig`` + - Datenspeicher-Konfiguration (ID, Handler-Name, Parameter, Skript usw.) + * - ``callback`` + - ``IndexUpdateCallback`` + - Callback zur Registrierung des erzeugten Dokuments im Index + * - ``paramMap`` + - ``DataStoreParams`` + - Konfigurationswerte aus dem Feld „Parameter" der Administrationsoberfläche. Zugriff über ``getAsString(key)`` / ``getAsString(key, default)`` / ``get(key)`` / ``asMap()`` / ``containsKey(key)`` + * - ``scriptMap`` + - ``Map`` + - Konfiguration aus dem Feld „Skript" der Administrationsoberfläche. Der Schlüssel ist der Indexfeldname, der Wert das auszuwertende Skript-Template + * - ``defaultDataMap`` + - ``Map`` + - Standardfeldwerte jedes Dokuments (Konfigurations-ID, Boost, Rolle, MIME-Type, virtueller Host usw.), die vom Framework bereitgestellt werden + +.. warning:: + + Der Typ von ``paramMap`` ist nicht ``Map``, sondern + ``DataStoreParams``. Da ``DataStoreParams`` das Interface ``Map`` nicht + implementiert, verwenden Sie zum Abrufen von Werten nicht ``get()``, sondern + ``getAsString()``, das einen String zurückgibt. + +Ablauf der Datenverarbeitung +------------------------------ + +Die Implementierung von ``storeData()`` verarbeitet Daten in folgendem Ablauf. + +#. Abrufen der Quelldatensätze aus dem externen System. +#. Erstellen von ``resultMap`` durch Zusammenführen der Felder des + Quelldatensatzes mit ``paramMap.asMap()`` (das Skript wird gegen dieses + ``resultMap`` ausgewertet). +#. Auswerten jedes Eintrags von ``scriptMap`` mit + ``convertValue(scriptType, template, resultMap)`` und Speichern des + Ergebnisses in ``dataMap``. Wichtig ist, dass das Mapping nicht im Code fest + verdrahtet ist, sondern vom Administrator im Feld „Skript" definiert wird. +#. Aufrufen von ``callback.store(paramMap, dataMap)``, um das Dokument im Index + zu registrieren. + +Implementierungsbeispiel +========================== + +Einfacher DataStore +--------------------- + +Ein Beispiel, das Datensätze von einer externen API abruft und im Index +registriert. + +.. code-block:: java + + @Override + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { + + // Parameter abrufen (bei DataStoreParams wird getAsString verwendet) + final String apiUrl = paramMap.getAsString("api.url"); + final String apiKey = paramMap.getAsString("api.key"); + + // Auswertungstyp des Skripts (Standard ist Groovy) + final String scriptType = getScriptType(paramMap); + // Wartezeit zwischen Datensätzen (in Millisekunden) + final long readInterval = getReadInterval(paramMap); + + try { + // Daten vom externen System abrufen + final List> records = fetchRecords(apiUrl, apiKey); + + for (final Map record : records) { + // dataMap durch Kopieren der Standardfelder initialisieren + final Map dataMap = new HashMap<>(defaultDataMap); + + // resultMap durch Zusammenführen von Parametern und + // Quelldatensatz erstellen + // (das Skript wird gegen dieses resultMap ausgewertet) + final Map resultMap = new LinkedHashMap<>(paramMap.asMap()); + resultMap.putAll(record); + + // Jeden Eintrag von scriptMap auswerten, um Indexfelder zu erzeugen + for (final Map.Entry entry : scriptMap.entrySet()) { + final Object value = convertValue(scriptType, entry.getValue(), resultMap); + if (value != null) { + dataMap.put(entry.getKey(), value); + } + } + + // Im Index registrieren + callback.store(paramMap, dataMap); + + if (readInterval > 0) { + sleep(readInterval); + } + } + } catch (final Exception e) { + throw new DataStoreException("Failed to crawl data from " + apiUrl, e); + } + } + +``fetchRecords()`` ist eine eigene Methode, die die Liste der Datensätze vom +externen System abruft. Die Feldnamen der einzelnen abgerufenen Datensätze +(``Map``) sind die Namen, auf die im Skript von ``scriptMap`` +verwiesen werden kann. ``DataStoreException`` ist eine Klasse aus dem Paket +``org.codelibs.fess.exception``. + +Unterstützung für Paginierung +------------------------------- + +Beim Umgang mit großen Datenmengen erfolgt die Verarbeitung seitenweise. Wenn +die Verarbeitung pro Datensatz (Erstellen von ``resultMap``, Auswerten von +``scriptMap``, Aufruf von ``callback.store()``) in eine Methode wie +``processRecord()`` ausgelagert wird, lässt sie sich von der Abruflogik +trennen. + +.. code-block:: java + + int offset = 0; + final int pageSize = 100; + + while (true) { + final List> records = fetchRecords(apiUrl, apiKey, offset, pageSize); + + if (records.isEmpty()) { + break; + } + + for (final Map record : records) { + processRecord(record, callback, paramMap, scriptMap, defaultDataMap); + } + + offset += pageSize; + } + +Implementierung der Authentifizierung +======================================== + +Die Authentifizierung gegenüber dem externen System wird auf Seiten des +Konnektors implementiert. Das folgende Beispiel verwendet eine gängige +HTTP-Client-Bibliothek und ist keine von |Fess| bereitgestellte API. Binden Sie +die verwendete Bibliothek als Abhängigkeit des Plugins ein. + +OAuth 2.0 +--------- + +.. code-block:: java + + protected String getAccessToken(final String clientId, final String clientSecret, final String refreshToken) { + // Beispiel zum Abrufen eines Access-Tokens mittels Refresh-Token + final OkHttpClient client = new OkHttpClient(); + + final RequestBody body = new FormBody.Builder() + .add("grant_type", "refresh_token") + .add("client_id", clientId) + .add("client_secret", clientSecret) + .add("refresh_token", refreshToken) + .build(); + + final Request request = new Request.Builder() + .url("https://oauth.example.com/token") + .post(body) + .build(); + + try (Response response = client.newCall(request).execute()) { + final JsonNode json = objectMapper.readTree(response.body().string()); + return json.get("access_token").asText(); + } + } + +API-Key-Authentifizierung +--------------------------- + +.. code-block:: java + + protected Response callApi(final String url, final String apiKey) { + final Request request = new Request.Builder() + .url(url) + .addHeader("Authorization", "Bearer " + apiKey) + .build(); + + return httpClient.newCall(request).execute(); + } + +Fehlerbehandlung +================== + +Bei fatalen Fehlern, die die Verarbeitung abbrechen sollen, wird +``DataStoreException`` geworfen. + +.. code-block:: java + + @Override + protected void storeData(...) { + try { + // Verarbeitung + } catch (final AuthenticationException e) { + logger.error("Authentication failed. Check your credentials.", e); + throw new DataStoreException("Authentication failed", e); + } catch (final RateLimitException e) { + logger.warn("Rate limit exceeded. Waiting..."); + sleep(60000L); + // Retry-Logik + } catch (final Exception e) { + logger.error("Unexpected error occurred", e); + throw new DataStoreException("Failed to crawl data", e); + } + } + +.. note:: + + Bei tatsächlichen Konnektoren wie ``fess-ds-example`` wird + ``CrawlingAccessException`` pro Datensatz abgefangen, damit ein Fehler bei + einem einzelnen Datensatz nicht den gesamten Crawl-Vorgang stoppt; die + fehlerhafte URL wird dabei bei ``FailureUrlService`` protokolliert. Außerdem + wird über das Abbruch-Flag von ``DataStoreCrawlingException`` gesteuert, ob + der gesamte Crawl-Vorgang abgebrochen werden soll. Wenn Sie einen robusten + Konnektor implementieren möchten, orientieren Sie sich an der + Implementierung von ``ExampleDataStore``. + +Tests +===== + +Unit-Tests +---------- + +|Fess|-Plugins werden mit ``LastaDiTestCase`` aus UTFlute getestet. Die Tests +werden mit JUnit 5 (Jupiter) geschrieben. Indem ``IndexUpdateCallback`` durch +eine Implementierung ersetzt wird, die die registrierten ``dataMap``-Werte +sammelt, lässt sich das Mapping-Ergebnis ohne Mock-Bibliothek überprüfen. + +.. code-block:: java + + public class ExampleDataStoreTest extends LastaDiTestCase { + + public ExampleDataStore dataStore; + + @Override + protected String prepareConfigFile() { + return "test_app.xml"; + } + + @Override + public void setUp(final TestInfo testInfo) throws Exception { + super.setUp(testInfo); + dataStore = new ExampleDataStore(); + } + + @Test + public void test_getName() { + assertEquals("ExampleDataStore", dataStore.getName()); + } + + @Test + public void test_storeData() { + final TestIndexUpdateCallback callback = new TestIndexUpdateCallback(); + final DataStoreParams paramMap = new DataStoreParams(); + + final Map scriptMap = new HashMap<>(); + scriptMap.put("title", "title"); + + dataStore.storeData(new DataConfig(), callback, paramMap, scriptMap, new HashMap<>()); + + assertFalse(callback.getDataMapList().isEmpty()); + } + + // Test-Callback, der die registrierten dataMap-Werte sammelt + private static class TestIndexUpdateCallback implements IndexUpdateCallback { + private final List> dataMapList = new ArrayList<>(); + + @Override + public void store(final DataStoreParams paramMap, final Map dataMap) { + dataMapList.add(new HashMap<>(dataMap)); + } + + @Override + public long getExecuteTime() { + return 0; + } + + @Override + public long getDocumentSize() { + return dataMapList.size(); + } + + @Override + public void commit() { + // Keine Aktion + } + + public List> getDataMapList() { + return dataMapList; + } + } + } + +.. note:: + + Da ``setUp`` in der Basisklasse bereits mit ``@BeforeEach`` versehen ist, + muss beim Überschreiben keine Lifecycle-Annotation erneut hinzugefügt + werden. Jeder Testmethode wird ``@Test`` (``org.junit.jupiter.api.Test``) + hinzugefügt. + +Build und Installation +======================== + +pom.xml +------- + +Das Plugin wird als jar mit ``fess-parent`` als übergeordnetem POM gebaut. Die +Abhängigkeiten von ``fess`` und ``opensearch`` werden zur Laufzeit von |Fess| +selbst bereitgestellt und daher als ``provided`` deklariert. + +.. code-block:: xml + + + 4.0.0 + org.codelibs.fess + fess-ds-example + 15.10.0 + jar + + + org.codelibs.fess + fess-parent + 15.10.0 + + + + + + org.codelibs.fess + fess + provided + + + org.opensearch + opensearch + provided + + + + +Für Tests werden JUnit 5 und ``org.dbflute.utflute:utflute-lastaflute`` +verwendet. + +Build +----- + +.. code-block:: bash + + mvn clean package + +Im Verzeichnis ``target/`` wird ``fess-ds-example-15.10.0.jar`` erzeugt. + +Installation +------------ + +Installieren Sie das erzeugte JAR in |Fess| und starten Sie |Fess| neu. +Details zum Installationsvorgang finden Sie unter +:doc:`../admin/plugin-guide`. Erstellen Sie nach der Installation über +„Crawler > Datenspeicher" in der Administrationsoberfläche eine neue +Konfiguration und geben Sie als „Handler-Name" den von ``getName()`` +zurückgegebenen Namen an (in diesem Beispiel ``ExampleDataStore``). + +Konfigurationsbeispiel +======================== + +Konfigurationsbeispiel in der Administrationsoberfläche: + +Parameter +--------- + +Im Feld „Parameter" werden die Schlüssel und Werte angegeben, die der +Konnektor aus ``paramMap`` ausliest. + +:: + + api.url=https://api.example.com/v1 + api.key=your_api_key + +Skript +------ + +Im Feld „Skript" wird das Mapping im Format ``linke Seite=rechte Seite`` +angegeben. Die linke Seite ist der Indexfeldname, die rechte Seite ein Skript +(JavaScript bei einer neu erstellten Konfiguration; eine Konfiguration ohne +hinterlegten Skripttyp wird als Groovy behandelt), das auf ein Feld des +Quelldatensatzes verweist. Das +folgende Beispiel gilt für den Fall, dass der Quelldatensatz die Felder +``url`` / ``title`` / ``content`` / ``updated_at`` / ``content_type`` besitzt. + +:: + + url=url + title=title + content=content + last_modified=updated_at + mimetype=content_type + +.. note:: + + Welche Feldnamen auf der rechten Seite referenziert werden können, hängt + von den Werten ab, die der Konnektor in ``resultMap`` ablegt (Werte aus + ``paramMap`` und Felder des Quelldatensatzes). Bei bestehenden Konnektoren + wie CSV oder JSON kann ein eigenes Präfix wie ``data.*`` vorangestellt + sein; weitere Details finden Sie in der Dokumentation des jeweiligen + Konnektors. + +Referenzinformationen +====================== + +- :doc:`plugin-architecture` - Plugin-Architektur +- :doc:`../admin/plugin-guide` - Plugin-Installation +- :doc:`../config/datastore/ds-overview` - Übersicht der Datenspeicher-Konnektoren +- `fess-ds-example `__ - Implementierungsvorlage für DataStore-Plugins +- `GitHub: fess-ds-* `__ - Beispiele veröffentlichter Konnektoren diff --git a/de/15.10/dev/index.rst b/de/15.10/dev/index.rst new file mode 100644 index 000000000..e11084922 --- /dev/null +++ b/de/15.10/dev/index.rst @@ -0,0 +1,27 @@ +================================== +|Fess| Entwicklerdokumentation +================================== + +Dokumentation zur Erweiterungsentwicklung von |Fess|. + +.. toctree:: + :maxdepth: 2 + :caption: Übersicht + + overview + +.. toctree:: + :maxdepth: 2 + :caption: Plugin-Entwicklung + + plugin-architecture + datastore-plugin + script-engine-plugin + webapp-plugin + ingest-plugin + +.. toctree:: + :maxdepth: 2 + :caption: Anpassung + + theme-development diff --git a/de/15.10/dev/ingest-plugin.rst b/de/15.10/dev/ingest-plugin.rst new file mode 100644 index 000000000..5f6fd8b15 --- /dev/null +++ b/de/15.10/dev/ingest-plugin.rst @@ -0,0 +1,181 @@ +================================== +Ingest-Plugin +================================== + +Übersicht +========= + +Ingest-Plugins bieten eine Funktion zur Verarbeitung und Transformation von +Daten, unmittelbar bevor Dokumente im Index registriert werden. Jedes durch +den Crawl abgerufene Dokument durchläuft vor der Übermittlung an den Index +die registrierten Ingester. + +Anwendungsfälle +=============== + +- Textnormalisierung (z. B. Konvertierung zwischen Vollbreiten- und + Halbbreitenzeichen, Formatierung von Leerzeichen usw.) +- Hinzufügen von Metadaten oder benutzerdefinierten Feldern +- Maskierung sensibler Informationen +- Umwandlung von Werten (z. B. Dekodierung kodierter Vektor-Embeddings) + +Ingester-Klasse +=============== + +Die Ingest-Funktion wird implementiert, indem die abstrakte Klasse +``org.codelibs.fess.ingest.Ingester`` erweitert wird. ``Ingester`` stellt +``process``-Methoden bereit, die je nach Crawl-Typ und Verarbeitungsphase +aufgerufen werden. Da alle Standardimplementierungen das empfangene +``target`` unverändert zurückgeben (also nichts tun), müssen nur die +benötigten Methoden überschrieben werden. + +- ``protected Map process(Map target)`` + + Dies ist das gemeinsame Delegationsziel der beiden ``Map``-Varianten der + Methode. Wird diese Methode überschrieben, gilt sie sowohl für Dokumente + aus dem Datenspeicher-Crawl als auch für Dokumente aus dem Web-/Datei-Crawl + (bei der Indexregistrierung). Für die meisten Anwendungsfälle genügt es, + nur diese Methode zu überschreiben. + +- ``public Map process(Map target, DataStoreParams params)`` + + Wird beim Datenspeicher-Crawl aufgerufen. Standardmäßig wird an + ``process(target)`` delegiert. + +- ``public Map process(Map target, AccessResult accessResult)`` + + Wird bei der Indexregistrierung im Web-/Datei-Crawl aufgerufen. + Standardmäßig wird an ``process(target)`` delegiert. + +- ``public ResultData process(ResultData target, ResponseData responseData)`` + + Wird bei der Antwortverarbeitung im Web-/Datei-Crawl aufgerufen (bevor das + Zugriffsergebnis gespeichert wird). Standardmäßig wird ``target`` + unverändert zurückgegeben. + +Ausführungsreihenfolge (priority) +---------------------------------- + +Wenn mehrere Ingester registriert sind, werden sie in aufsteigender +Reihenfolge des Felds ``priority`` ausgeführt (kleinere Werte zuerst). Der +Standardwert ist ``99``. Er kann direkt im Konstruktor gesetzt oder über +``setPriority(int)`` geändert werden. + +.. code-block:: java + + public int getPriority() + public void setPriority(final int priority) + +Implementierungsbeispiel +========================= + +Ein Beispiel, bei dem ``process(Map)`` überschrieben wird, +um den Inhalt zu normalisieren und ein benutzerdefiniertes Feld +hinzuzufügen: + +.. code-block:: java + + package org.codelibs.fess.ingest.example; + + import java.util.Map; + + import org.codelibs.fess.ingest.Ingester; + + public class ExampleIngester extends Ingester { + + public ExampleIngester() { + // Ausführungsreihenfolge festlegen (kleinere Werte werden zuerst ausgeführt; Standard ist 99) + setPriority(50); + } + + @Override + protected Map process(final Map target) { + // Normalisierung des Inhalts + final Object content = target.get("content"); + if (content instanceof String) { + target.put("content", ((String) content).trim().replaceAll("\\s+", " ")); + } + + // Hinzufügen eines benutzerdefinierten Felds + target.put("ingested_by", ExampleIngester.class.getSimpleName()); + + // Das verarbeitete Dokument zurückgeben + return target; + } + } + +.. note:: + + Wenn die ``process``-Methode ``null`` zurückgibt, schlägt die + Indexregistrierung fehl. Da es keinen Mechanismus zum Überspringen von + Dokumenten gibt, muss stets ``target`` zurückgegeben werden. + +Registrierung +============= + +Ingester werden über den DI-Container registriert. Das Plugin enthält dafür +die Datei ``fess_ingest++.xml``. Das ``++`` am Ende des Dateinamens ist eine +Merge-Konvention, mit der die Konfiguration an die Datei +``fess_ingest.xml`` (welche die ``ingestFactory``, die die Ingester +verwaltet, definiert) der |Fess|-Kernanwendung angehängt wird. + +.. code-block:: xml + + + + + + + + + +Durch ```` wird nach der Erzeugung der +Komponente ``Ingester#register()`` aufgerufen, wodurch sie sich selbst bei +der ``ingestFactory`` registriert. + +Für die Ingest-Funktion gibt es keine Konfigurationseinträge in +``fess_config.properties``. Aktivierung bzw. Deaktivierung erfolgt durch das +Vorhandensein des Plugins, und die Ausführungsreihenfolge wird über +``priority`` gesteuert. + +Ausführungsablauf +================== + +Ingester werden unmittelbar bevor das verarbeitete Dokument an den Index +übermittelt wird, an den folgenden Stellen in aufsteigender Reihenfolge von +``priority`` aufgerufen: + +- **Datenspeicher-Crawl**: Unmittelbar bevor das Dokument gesendet wird, + wird ``process(Map, DataStoreParams)`` aufgerufen. +- **Web-/Datei-Crawl (bei der Antwortverarbeitung)**: Bevor das + Crawl-Ergebnis gespeichert wird, wird ``process(ResultData, ResponseData)`` + aufgerufen. +- **Web-/Datei-Crawl (bei der Indexregistrierung)**: Unmittelbar bevor das + Dokument gesendet wird, wird ``process(Map, AccessResult)`` aufgerufen. + +In allen Fällen wird, wenn ein Ingester eine Ausnahme auslöst, eine +Warnmeldung protokolliert und die Verarbeitung fortgesetzt (die +Indexregistrierung des betreffenden Dokuments wird dadurch nicht +abgebrochen). + +.. note:: + + Da Ingester in der Ausführungsumgebung des Crawlers (``ingestFactory``) + registriert werden, arbeiten sie als Teil des Crawl-Prozesses. + +Referenzimplementierungen +========================== + +Als Referenz für die Implementierung sind die folgenden Plugins auf GitHub +unter `CodeLibs `__ veröffentlicht: + +- ``fess-ingest-example`` - Minimalistische Beispielimplementierung +- ``fess-webapp-multimodal`` - Plugin mit ``EmbeddingIngester``, der + Vektor-Embeddings dekodiert + +Referenzinformationen +====================== + +- :doc:`plugin-architecture` - Plugin-Architektur diff --git a/de/15.10/dev/overview.rst b/de/15.10/dev/overview.rst new file mode 100644 index 000000000..841db0fce --- /dev/null +++ b/de/15.10/dev/overview.rst @@ -0,0 +1,237 @@ +================================== +Entwicklerdokumentation Übersicht +================================== + +Übersicht +========= + +Dieser Abschnitt beschreibt die Erweiterungsentwicklung von |Fess|. +Er bietet Informationen zur Plugin-Entwicklung, zur Erstellung benutzerdefinierter Konnektoren, +zur Theme-Anpassung und zu weiteren Möglichkeiten, |Fess| zu erweitern. + +Zielgruppe +========== + +- Entwickler, die benutzerdefinierte Funktionen für |Fess| entwickeln möchten +- Entwickler, die Plugins erstellen möchten +- Entwickler, die den Quellcode von |Fess| verstehen möchten + +Voraussetzungen +---------------- + +- Grundkenntnisse in Java 21 +- Grundlagen von Maven (Build-System) +- Erfahrung in der Webanwendungsentwicklung +- Grundkenntnisse von OpenSearch (|Fess| verwendet OpenSearch als Suchmaschine) + +Entwicklungsumgebung +===================== + +Empfohlene Umgebung +-------------------- + +- **JDK**: OpenJDK 21 oder höher +- **IDE**: IntelliJ IDEA / Eclipse / VS Code +- **Build-Tool**: Maven (für den Build ist keine Mindestversion vorgeschrieben, empfohlen wird jedoch eine neuere 3.x-Version, die Java 21 unterstützt) +- **Git**: Versionskontrolle +- **OpenSearch**: Backend der Suchmaschine (beim Start aus der IDE werden die benötigten Module und Plugins beim Build heruntergeladen) + +Setup +----- + +|Fess| wird als Maven-Projekt gebaut. Bei der Entwicklung ist es am einfachsten, es aus der IDE zu starten. + +1. Quellcode abrufen: + + :: + + git clone https://github.com/codelibs/fess.git + +2. Import in die IDE: + + Importieren Sie das abgerufene Verzeichnis als Maven-Projekt in Ihre IDE. + +3. Module und Plugins für OpenSearch herunterladen: + + Nur beim ersten Mal werden mit folgendem Befehl die Module und Plugins der Suchmaschine in das Verzeichnis ``plugins`` geladen. + + :: + + mvn antrun:run + +4. Entwicklungsserver starten (aus der IDE): + + Führen Sie in der IDE ``org.codelibs.fess.FessBoot`` aus oder starten Sie ihn im Debug-Modus, + und öffnen Sie im Browser http://localhost:8080/. + Der Administrationsbereich ist unter http://localhost:8080/admin/ erreichbar (Standardkonto: ``admin`` / ``admin``). + +5. Paket bauen (Erstellung des Verteilungspakets): + + Falls ein Verteilungspaket benötigt wird, führen Sie das Ziel ``package`` aus. + Die Artefakte werden unter ``target/releases`` erzeugt (um Unit-Tests zu überspringen, fügen Sie ``-DskipTests`` hinzu). + + :: + + mvn package + + Entpacken Sie das erzeugte Verteilungspaket, um das Startskript ``bin/fess`` nutzen zu können. + + :: + + unzip target/releases/fess-*.zip + ./fess-*/bin/fess + +.. note:: + + Das Startskript ``bin/fess`` ist im Verteilungspaket (zip/rpm/deb) enthalten. + Wird ``mvn package`` lediglich im Quellverzeichnis ausgeführt, wird ``bin/fess`` nicht direkt im Wurzelverzeichnis des Repositorys erzeugt. + Führen Sie bei der Entwicklung aus dem Quellcode wie oben beschrieben ``FessBoot`` in der IDE aus, + oder verwenden Sie ``bin/fess`` aus dem entpackten Verteilungspaket. + +Architekturüberblick +===================== + +|Fess| besteht aus den folgenden Hauptkomponenten: + +Komponentenstruktur +-------------------- + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Komponente + - Beschreibung + * - Web-Schicht + - MVC-Implementierung mit dem LastaFlute-Framework + * - Service-Schicht + - Geschäftslogik + * - Datenzugriffsschicht + - Typsicherer OpenSearch-Zugriff mit DBFlute (ESFlute/FreeGen) + * - Crawler + - Inhaltserfassung mit der fess-crawler-Bibliothek + * - Suchmaschine + - Volltextsuche mit OpenSearch + +Hauptframeworks +---------------- + +- **LastaFlute**: Web-Framework (Actions, Forms, Validierung) +- **DBFlute**: Datenzugriffs-Framework. Die typsicheren Zugriffsklassen für OpenSearch (``Bhv`` / ``ConditionBean``) + werden durch die FreeGen-Funktion von DBFlute und ESFlute-Templates generiert + (zur Neugenerierung: ``mvn dbflute:freegen``) +- **Lasta Di**: Dependency-Injection-Container + +Verzeichnisstruktur +===================== + +:: + + fess/ + ├── src/main/java/org/codelibs/fess/ + │ ├── app/ + │ │ ├── web/ # Controller (Action) + │ │ ├── service/ # Services + │ │ ├── logic/ # Logik + │ │ └── pager/ # Paginierung + │ ├── api/ # REST API (z. B. api/v2) + │ ├── helper/ # Hilfsklassen + │ ├── crawler/ # Crawler-bezogen + │ ├── indexer/ # Indexverarbeitung + │ ├── opensearch/ # OpenSearch-Zugriff (ESFlute/FreeGen-generiert) + │ ├── llm/ # LLM-Integration + │ ├── ds/ # DataStore-Konnektoren + │ ├── ingest/ # Ingest (Datenverarbeitung beim Indexieren) + │ ├── script/ # Skript-Engine + │ ├── entity/ # Entitäten + │ └── mylasta/ # LastaFlute-Konfiguration (DI, Meldungen, typsichere Einstellungen) + ├── src/main/resources/ + │ ├── fess_config.properties # Konfiguration + │ └── fess_*.xml # DI-Konfiguration (app.xml, fess_ds.xml usw.) + └── src/main/webapp/ + └── WEB-INF/view/ # JSPs der Verwaltungs- und Anmeldebildschirme + +Erweiterungspunkte +==================== + +|Fess| bietet folgende Erweiterungspunkte: + +Plugins +------- + +Mit Plugins können Funktionen hinzugefügt werden. + +- **DataStore-Plugin**: Crawling von neuen Datenquellen (erbt von ``AbstractDataStore``) +- **Script-Engine-Plugin**: Unterstützung neuer Skriptsprachen (implementiert ``ScriptEngine``) +- **WebApp-Plugin**: Erweiterung der Weboberfläche (Überschreiben von Lasta-Di-Komponenten und Zusammenführen von Ressourcen) +- **Ingest-Plugin**: Datenverarbeitung beim Indexieren (erbt von ``Ingester``) + +Details: :doc:`plugin-architecture` + +.. note:: + + |Fess| selbst wird als ``war`` paketiert. Wenn beim lokalen Erstellen eines Plugins + |Fess| nicht als Abhängigkeit aufgelöst werden kann, ändern Sie in der ``pom.xml`` das ```` + vorübergehend auf ``jar``, führen Sie ``mvn clean install -DskipTests`` aus + und setzen Sie es anschließend wieder auf ``war`` zurück. + +Themes +------ + +Das Design der Suchoberfläche kann angepasst werden. + +Details: :doc:`theme-development` + +Konfiguration +-------------- + +Viele Verhaltensweisen können über ``fess_config.properties`` angepasst werden. + +Details: :doc:`../config/intro` + +Plugin-Entwicklung +==================== + +Für Details zur Plugin-Entwicklung siehe: + +- :doc:`plugin-architecture` - Plugin-Architektur +- :doc:`datastore-plugin` - DataStore-Plugin-Entwicklung +- :doc:`script-engine-plugin` - Script-Engine-Plugin +- :doc:`webapp-plugin` - WebApp-Plugin +- :doc:`ingest-plugin` - Ingest-Plugin + +Theme-Entwicklung +==================== + +- :doc:`theme-development` - Theme-Anpassung + +Best Practices +================ + +Coding-Konventionen +--------------------- + +- Dem bestehenden Codestil von |Fess| folgen +- ``mvn formatter:format`` für die Code-Formatierung +- ``mvn license:format`` zum Hinzufügen des Lizenz-Headers + +Tests +----- + +- Unit-Tests (``*Test.java``): werden mit dem Standardprofil ``build`` über ``mvn test`` ausgeführt +- Integrationstests (``*Tests.java``): werden mit ``mvn test -P integrationTests`` ausgeführt. + Für die Ausführung der Integrationstests sind ein laufender |Fess|-Server und OpenSearch erforderlich + +Logging +------- + +- Log4j2 verwenden +- ``logger.debug()`` / ``logger.info()`` / ``logger.warn()`` / ``logger.error()`` +- Keine sensiblen Informationen in Logs ausgeben + +Ressourcen +=========== + +- `GitHub Repository `__ +- `Issue Tracker `__ +- `Discussions `__ diff --git a/de/15.10/dev/plugin-architecture.rst b/de/15.10/dev/plugin-architecture.rst new file mode 100644 index 000000000..8c8364936 --- /dev/null +++ b/de/15.10/dev/plugin-architecture.rst @@ -0,0 +1,391 @@ +================================== +Plugin-Architektur +================================== + +Übersicht +========= + +Das Plugin-System von |Fess| ermöglicht die Erweiterung der Kernfunktionen. +Plugins werden als JAR-Dateien ausgeliefert; sobald sie dem Klassenpfad +hinzugefügt werden, lädt der DI-Container (Lasta Di) die Komponenten und +registriert sie bei den entsprechenden Factory- bzw. Manager-Klassen. + +Plugin-Typen +============ + +|Fess| unterscheidet die Plugin-Typen anhand des Präfixes des +Artefaktnamens (``PluginHelper.ArtifactType``). Die wichtigsten Typen sind: + +.. list-table:: + :header-rows: 1 + :widths: 20 25 55 + + * - Typ + - Präfix + - Beschreibung + * - DataStore + - ``fess-ds-*`` + - Inhaltserfassung aus neuen Datenquellen (Box, Slack, Git usw.) + * - Webanwendung + - ``fess-webapp-*`` + - Erweiterung der Web-Oberfläche und der Suchfunktionen + * - Skript-Engine + - ``fess-script-*`` + - Unterstützung neuer Skriptsprachen + * - Ingest + - ``fess-ingest-*`` + - Dokumentverarbeitung bei der Index-Registrierung + * - Thumbnail + - ``fess-thumbnail-*`` + - Hinzufügen von Verfahren zur Thumbnail-Erzeugung + * - LLM + - ``fess-llm-*`` + - Hinzufügen von LLM-Anbietern für RAG/Chat + * - Crawler + - ``fess-crawler-*`` + - Erweiterung des Crawler-Clients + * - Speicher + - ``fess-storage-*`` + - Hinzufügen eines Objektspeicher-Backends für das Crawling und die Speicherfunktion + * - SSO + - ``fess-sso-*`` + - Hinzufügen eines über ``sso.type`` ausgewählten Single-Sign-On-Verfahrens + +.. note:: + + Der Typ ``fess-theme-*`` (JAR-Theme), der JSPs bereitstellte, wurde in 15.10 entfernt. + Das Aussehen der Suchoberfläche ändern Sie mit einem statischen Theme, nicht mit + einem Plugin (siehe :doc:`theme-development`). + +Plugin-Struktur +=============== + +Grundstruktur +------------- + +Am Beispiel von `fess-ds-example `__, +der Implementierungsvorlage für DataStore-Plugins, besteht ein Plugin aus +einer „Implementierungsklasse" und einer „DI-Registrierungsdatei": + +:: + + fess-ds-example/ + ├── pom.xml + └── src/main/ + ├── java/org/codelibs/fess/ds/example/ + │ └── ExampleDataStore.java # DataStore-Implementierung + └── resources/ + └── fess_ds++.xml # DI-Komponentenregistrierung + +Beispiel für pom.xml +--------------------- + +Das Plugin wird als jar mit ``fess-parent`` als übergeordnetem POM gebaut. +Bibliotheken wie ``fess`` und ``opensearch``, die zur Laufzeit von |Fess| +selbst bereitgestellt werden, werden mit dem Scope ``provided`` deklariert. +Versionsnummer und Build-Konfiguration (z. B. Formatter und +Lizenzkopfzeilen) werden vom übergeordneten POM geerbt. + +.. code-block:: xml + + + + 4.0.0 + + org.codelibs.fess + fess-ds-example + 15.10.0 + jar + + + org.codelibs.fess + fess-parent + 15.10.0 + + + + + + org.codelibs.fess + fess + provided + + + org.opensearch + opensearch + provided + + + + +.. note:: + + In Branches, die sich in der Entwicklung befinden, erhält die Version ein + Suffix ``-SNAPSHOT``, z. B. ``15.10.0-SNAPSHOT``. Plugin-spezifische + Abhängigkeitsbibliotheken werden als normale Maven-Abhängigkeiten + deklariert. Da diese nicht in |Fess| selbst enthalten sind, müssen sie + zusammen mit dem Plugin verteilt werden. + +Plugin-Registrierung +===================== + +Registrierung im DI-Container +------------------------------ + +Ein Plugin registriert seine Komponenten in einer DI-Konfigurationsdatei, +deren Name auf ``++`` endet, wie z. B. ``fess_ds++.xml``. Lasta Di führt +Dateien mit der Endung ``++``, die im Klassenpfad gefunden werden, +automatisch mit der entsprechenden Konfigurationsdatei von |Fess| selbst +zusammen (in diesem Beispiel ``fess_ds.xml``). Durch diesen Mechanismus kann +ein Plugin eigene Komponenten hinzufügen, ohne Dateien von |Fess| selbst zu +bearbeiten. + +.. code-block:: xml + + + + + + + + + +Je nach Plugin-Typ unterscheidet sich die Ziel-Datei für das Merging. +Beispielsweise verwendet die Skript-Engine ``fess_se++.xml``, Ingest +``fess_ingest++.xml``, der LLM-Anbieter ``fess_llm++.xml`` und die +Webanwendung ``app++.xml``. + +Initialisierung der Komponente +-------------------------------- + +```` ist eine Lifecycle-Konfiguration von +Lasta Di, die die nach der Erzeugung der Komponente aufzurufende Methode +angibt. Im Fall eines DataStore wird die von ``AbstractDataStore`` +bereitgestellte Methode ``register()`` aufgerufen, wodurch sich die +Komponente selbst bei ``DataStoreFactory`` registriert: + +.. code-block:: java + + // Implementierung von AbstractDataStore (in der Regel keine Überschreibung nötig) + public void register() { + ComponentUtil.getDataStoreFactory().add(getName(), this); + } + +.. note:: + + Dies ist keine Initialisierung über die Java-Annotation + ``@PostConstruct``, sondern über das Element ```` der + DI-Konfigurationsdatei. Der registrierte Name ist der Rückgabewert von + ``getName()`` und entspricht dem Namen, der bei der Auswahl des Plugins + in der Administrationsoberfläche verwendet wird. + +Plugin-Lebenszyklus +===================== + +Initialisierung +---------------- + +1. Das Plugin-JAR wird dem Klassenpfad hinzugefügt. +2. Der DI-Container führt ``fess_*++.xml`` zusammen und erzeugt die + Komponenten. +3. Die in ```` angegebene Methode (z. B. ``register``) wird + aufgerufen. +4. Das Plugin wird bei der entsprechenden Factory- bzw. Manager-Klasse + registriert. + +Beendigung +---------- + +1. Beim Beenden des DI-Containers wird die in ```` angegebene + Methode aufgerufen (sofern definiert). +2. Bereinigung von Ressourcen. + +.. note:: + + Im Fall eines DataStore wird ein laufender Crawl-Vorgang durch + ``AbstractDataStore.stop()`` mit einem Stopp-Flag versehen, sodass die + Verarbeitungsschleife für die Datensätze sicher beendet wird. + +Abhängigkeiten +================ + +Abhängigkeit von Fess selbst +------------------------------- + +Da die Klassen von |Fess| selbst zur Laufzeit im Klassenpfad des Servers +vorhanden sind, wird die Abhängigkeit mit dem Scope ``provided`` deklariert +(sie ist nicht im Plugin-JAR enthalten). + +.. code-block:: xml + + + org.codelibs.fess + fess + provided + + +Externe Bibliotheken +--------------------- + +Ein Plugin kann eigene Abhängigkeitsbibliotheken enthalten: + +.. code-block:: xml + + + com.example + example-sdk + 1.0.0 + + +Da diese nicht in |Fess| selbst enthalten sind, müssen sie zusammen mit dem +Plugin verteilt werden. + +Abrufen der Konfiguration +============================ + +Abrufen von Parametern und FessConfig +---------------------------------------- + +In ``storeData()`` eines DataStore werden die in der +Administrationsoberfläche konfigurierten Parameter aus ``DataStoreParams`` +abgerufen. Zum Abrufen der Werte wird ``getAsString()`` verwendet (da +``DataStoreParams`` das Interface ``Map`` nicht implementiert, gibt +``get()`` keinen String zurück). Konfigurationswerte von |Fess| lassen sich +außerdem über ``ComponentUtil.getFessConfig()`` abrufen: + +.. code-block:: java + + public class ExampleDataStore extends AbstractDataStore { + + @Override + protected String getName() { + // Wird als Handler-Name verwendet. Es ist üblich, den einfachen Klassennamen zurückzugeben + return this.getClass().getSimpleName(); + } + + @Override + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { + + // Abrufen der Parameter + final String apiKey = paramMap.getAsString("api.key"); + final String baseUrl = paramMap.getAsString("base.url"); + + // Abrufen von FessConfig + final FessConfig fessConfig = ComponentUtil.getFessConfig(); + } + } + +Detaillierte Informationen zur Implementierung von ``storeData()`` (Ablauf +von Datenabruf, Skriptauswertung und Index-Registrierung) finden Sie unter +:doc:`datastore-plugin`. + +Build und Installation +======================== + +Build +----- + +:: + + mvn clean package + +Im Verzeichnis ``target/`` wird eine JAR-Datei erzeugt (z. B. +``fess-ds-example-15.10.0.jar``). + +Installation +------------ + +1. **Über die Administrationsoberfläche**: + + - Öffnen Sie „System" → „Plugin" → „Installieren". + - Wählen Sie aus der Liste des Plugin-Repositorys aus, oder laden Sie die + erstellte JAR-Datei hoch, um sie zu installieren. + +2. **Manuell**: + + - Kopieren Sie die JAR-Datei in das Verzeichnis + ``app/WEB-INF/plugin/``. + - Starten Sie |Fess| neu. + +Details zum Installationsvorgang finden Sie unter +:doc:`../admin/plugin-guide`. + +Debugging +========= + +Log-Ausgabe +------------ + +|Fess| verwendet Log4j2. Der Logger wird über ``LogManager.getLogger()`` +abgerufen: + +.. code-block:: java + + private static final Logger logger = LogManager.getLogger(ExampleDataStore.class); + + public void someMethod() { + logger.debug("Debug message"); + logger.info("Info message"); + } + +.. note:: + + Geben Sie keine sensiblen Informationen wie Passwörter oder Token in + Logs aus. + +Entwicklungsmodus +------------------ + +Während der Entwicklung können Sie |Fess| aus der IDE starten und +debuggen: + +1. Führen Sie die Klasse ``org.codelibs.fess.FessBoot`` im Debug-Modus aus. +2. Nehmen Sie den Quellcode des Plugins in das Projekt auf. +3. Setzen Sie Breakpoints. + +Liste veröffentlichter Plugins +================================ + +Im |Fess|-Projekt sind zahlreiche Plugins veröffentlicht. Im Folgenden +finden Sie repräsentative Beispiele (diese Liste ist nicht vollständig): + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Plugin + - Beschreibung + * - ``fess-ds-box`` + - Box-Konnektor + * - ``fess-ds-dropbox`` + - Dropbox-Konnektor + * - ``fess-ds-slack`` + - Slack-Konnektor + * - ``fess-ds-atlassian`` + - JIRA-/Confluence-Konnektor + * - ``fess-ds-git`` + - Git-Repository-Konnektor + * - ``fess-llm-openai`` + - OpenAI-LLM-Anbieter + +Darüber hinaus sind DataStore-Konnektoren wie ``fess-ds-csv`` / +``fess-ds-db`` / ``fess-ds-json`` / ``fess-ds-microsoft365`` / +``fess-ds-sharepoint`` sowie LLM-Anbieter wie ``fess-llm-ollama`` / +``fess-llm-gemini`` / ``fess-llm-bedrock`` veröffentlicht. Diese Plugins sind als Referenz für die +Entwicklung auf `GitHub `__ veröffentlicht. + +Referenzinformationen +======================= + +- :doc:`datastore-plugin` - DataStore-Plugin-Entwicklung +- :doc:`script-engine-plugin` - Skript-Engine-Plugin +- :doc:`webapp-plugin` - Webanwendungs-Plugin +- :doc:`ingest-plugin` - Ingest-Plugin +- :doc:`theme-development` - Anpassung von Themes +- :doc:`../admin/plugin-guide` - Plugin-Installation diff --git a/de/15.10/dev/script-engine-plugin.rst b/de/15.10/dev/script-engine-plugin.rst new file mode 100644 index 000000000..891857f96 --- /dev/null +++ b/de/15.10/dev/script-engine-plugin.rst @@ -0,0 +1,61 @@ +================================== +Script-Engine-Plugin +================================== + +Übersicht +========= + +Durch die Entwicklung eines Script-Engine-Plugins konnen Sie |Fess| Unterstutzung +fur neue Skriptsprachen hinzufugen. + +Grundimplementierung +==================== + +Implementieren Sie das ``ScriptEngine``-Interface: + +.. code-block:: java + + package org.codelibs.fess.script.example; + + import org.codelibs.fess.script.ScriptEngine; + import java.util.Map; + + public class ExampleScriptEngine implements ScriptEngine { + + @Override + public String getName() { + return "example"; + } + + @Override + public Object evaluate(String script, Map params) { + // Skript-Auswertungslogik + return executeScript(script, params); + } + } + +Registrierung +============= + +.. code-block:: java + + @PostConstruct + public void register() { + ComponentUtil.getScriptEngineManager().add(this); + } + +Verwendungsbeispiel +=================== + +Auswahl als Skripttyp in der Administrationsoberflache: + +:: + + scriptType=example + scriptData=your script here + +Referenzinformationen +===================== + +- :doc:`plugin-architecture` - Plugin-Architektur +- :doc:`../config/scripting-overview` - Scripting-Übersicht diff --git a/de/15.10/dev/theme-development.rst b/de/15.10/dev/theme-development.rst new file mode 100644 index 000000000..b4baa76e5 --- /dev/null +++ b/de/15.10/dev/theme-development.rst @@ -0,0 +1,360 @@ +================================== +Theme-Entwicklungsleitfaden +================================== + +Übersicht +========= + +In |Fess| 15.10 ist die Suchoberfläche immer ein statisches Theme. Ein +statisches Theme ist eine eigenständige SPA (Single-Page-Anwendung), +die die ``/api/v2/*`` API nutzt. Themes werden als ZIP-Dateien +verteilt, über die Administrationsoberfläche hochgeladen und dort +aktiviert. Ist kein Theme ausgewählt, verwendet |Fess| ``bootstrap``, +das mitgelieferte statische Theme. + +Um das Aussehen der Suchoberfläche zu ändern, installieren Sie entweder +ein anderes Theme (siehe :doc:`../admin/theme-guide`) oder erstellen ein +eigenes: Am schnellsten kopieren Sie das mitgelieferte Theme und ändern +die Kopie, wie unter `Mitgeliefertes Theme anpassen`_ beschrieben. + +.. note:: + + Statische Themes stehen ab |Fess| 15.7 zur Verfügung und wurden in + 15.10 zur Standard-Suchoberfläche. JAR-Theme-Plugins, die die JSPs + der Suchoberfläche ersetzten, wurden in 15.10 entfernt; siehe + `JAR-Theme-Plugin (in 15.10 entfernt)`_. + +Statisches Theme +================ + +Ein statisches Theme ist eine Sammlung statischer Ressourcen, die das +``theme.yml``-Manifest und ``index.html`` enthält. Das Theme selbst +wird als Frontend-Anwendung implementiert, die die ``/api/v2/*`` API +von |Fess| aufruft. + +Struktur +-------- + +Ein statisches Theme hat die folgende Verzeichnisstruktur. + +:: + + example/ + ├── theme.yml # Manifest (erforderlich) + ├── index.html # Einstiegs-HTML der SPA + ├── assets/ # Statische Ressourcen wie JavaScript und CSS + │ └── styles.css + ├── i18n/ # Mehrsprachige Meldungen (messages..json) + │ └── messages.en.json + ├── help/ # Hilfedefinitionen (.json) + │ └── en.json + └── thumbnail.png # Vorschaubild (optional) + +Manifest (theme.yml) +--------------------- + +``theme.yml`` ist das erforderliche Manifest, das im Stammverzeichnis +des ZIP abgelegt wird. Im Folgenden sehen Sie ein Beispiel für die +minimale Konfiguration. + +.. code-block:: yaml + + apiVersion: fess.codelibs.org/v1 + kind: StaticTheme + name: example + displayName: "Example Theme" + version: "15.10.0" + minFessVersion: "15.10" + entry: index.html + spaFallback: true + +Die folgenden Felder können angegeben werden. + +.. list-table:: + :header-rows: 1 + :widths: 22 12 66 + + * - Feld + - Erforderlich + - Beschreibung + * - ``apiVersion`` + - Erforderlich + - Fester Wert ``fess.codelibs.org/v1``. + * - ``kind`` + - Erforderlich + - Fester Wert ``StaticTheme``. + * - ``name`` + - Erforderlich + - Theme-Name. Muss dem Muster ``^[a-z0-9][a-z0-9_-]{0,63}$`` + entsprechen. Wird als Verzeichnisname des Themes verwendet, der + unter ``themes/`` entpackt wird (beim Hochladen wird dieser Name + automatisch aus ``name`` bestimmt), sowie für die + Auslieferungs-URL (``/themes//``). + * - ``displayName`` + - Erforderlich + - Der in der Administrationsoberfläche angezeigte Name. + * - ``version`` + - Erforderlich + - Format nach Semantic Versioning (Beispiel: ``15.10.0``, + ``15.10.1-beta.1``). Per Konvention ist ``major.minor`` die |Fess|-Linie, + für die das Theme gebaut ist, sodass schon die Version beantwortet, für + welches |Fess| ein Theme gedacht ist. + * - ``author`` + - Optional + - Name des Autors. + * - ``description`` + - Optional + - Beschreibung des Themes. + * - ``license`` + - Optional + - Lizenz. + * - ``homepage`` + - Optional + - URL der Homepage. + * - ``minFessVersion`` + - Optional + - Die minimale |Fess|-Version, die vom Theme unterstützt wird. Halten Sie sie + gleich dem ``major.minor`` von ``version``. Ein ``maxFessVersion`` gibt es + nicht; siehe `Veröffentlichen`_. + * - ``supportedLocales`` + - Optional + - Liste der unterstützten Locales (Beispiel: ``[en, ja, de]``). + * - ``entry`` + - Optional + - Einstiegs-HTML der SPA. Standardwert ist ``index.html``. + * - ``spaFallback`` + - Optional + - Veraltet. Wird aus Kompatibilitätsgründen akzeptiert, aber nicht + mehr gelesen: Seit 15.10 wird für die Pfade der Suchoberfläche + immer das Einstiegs-HTML ausgeliefert. + +.. note:: + + Beim Hochladen als ZIP wird der Name des Zielverzeichnisses + automatisch aus ``name`` bestimmt. Wenn Sie ein Theme manuell im + Verzeichnis ``themes/`` ablegen, muss der Verzeichnisname mit + ``name`` übereinstimmen. Themes, deren Name nicht übereinstimmt, + werden beim erneuten Scannen ignoriert. + +.. note:: + + Das Vorschau-Thumbnail wird im Stammverzeichnis des Themes unter dem + festen Namen ``thumbnail.png`` abgelegt (es wird in der Theme-Liste + der Administrationsoberfläche angezeigt). Dieses Bild wird anhand + des Dateinamens erkannt, nicht über ein Feld im Manifest. Empfohlen + wird eine Größe von maximal 512 KB und maximal 512×512 Pixeln. + +Auslieferung und API +--------------------- + +- Statische Themes werden unter ``/themes//`` ausgeliefert + (```` ist der Wert von ``name`` in ``theme.yml``). +- Für die Pfade ``/``, ``/search``, ``/advance``, ``/help``, + ``/error``, ``/profile``, ``/cache`` und ``/chat`` wird jeweils das + Einstiegs-HTML (Standard: ``index.html``) zurückgegeben, und das + weitere Routing übernimmt die SPA. Seit 15.10 geschieht dies + unabhängig davon, was ``spaFallback`` angibt; das Feld wird nicht + mehr gelesen. +- Auch Fehler werden vom Theme dargestellt: Schlägt eine Anfrage fehl, + erhält ein Browser das Einstiegs-HTML des Themes unter der + angeforderten URL, mit dem tatsächlichen HTTP-Status. +- Die Administrationsoberfläche (``/admin/*``), ``/api/*``, die + Anmeldeseite und Ähnliches fallen nicht unter das statische Theme und + werden vom |Fess|-Kern selbst verarbeitet. +- ``{{themePath}}`` im Einstiegs-HTML wird bei der Auslieferung durch + ``themes/`` ersetzt. Verweisen Sie in ``index.html`` auf die + eigenen Dateien des Themes als ``{{themePath}}/assets/styles.css`` usw. + Der Theme-Name steht dann nicht in der Seite, sodass das Theme unter + jedem Namen, unter dem es installiert ist, seine eigenen Dateien lädt. +- Das Einstiegs-HTML wird mit einem ``Content-Security-Policy``-Header + ausgeliefert, der Skripte, Stylesheets, Bilder und Verbindungen nur + von |Fess| selbst zulässt (Inline-Styles sind erlaubt, Inline-Skripte + nicht). Schriften oder Skripte von einem externen CDN werden daher + nicht geladen; liefern Sie sie im Theme mit. +- Die ``Content-Security-Policy`` des Einstiegs-HTML enthält + ``frame-ancestors 'none'``, und die Antwort trägt zusätzlich + ``X-Frame-Options: DENY``; die Seite wird daher nicht im Frame einer + anderen Seite angezeigt. Der Wert von ``frame-ancestors`` lässt sich mit + ``theme.index.frame.ancestors`` in ``fess_config.properties`` ändern + (Standard: ``'none'``). Ein leerer Wert lässt ``frame-ancestors`` weg + (``X-Frame-Options: DENY`` wird weiterhin gesendet). Unter + ``frame-ancestors 'none'`` lassen WebKit-basierte Browser wie Safari die + Frames leer, die ein Theme aus einer ``blob:``-URL anzeigt (PDF-Vorschau + oder zwischengespeicherte Kopie). Setzen Sie den Wert leer, um sie + anzuzeigen. +- Die SPA des Themes ruft Daten wie Suchergebnisse und Chat über die + ``/api/v2/*`` API ab. + +Packaging +--------- + +Mit ``scripts/package.sh`` aus dem Repository +`fess-themes `__ können Sie +das Theme zu einem ZIP für die Verteilung zusammenfassen. + +:: + + ./scripts/package.sh example + +Es wird ``dist/example-.zip`` erzeugt (```` ist der +Wert von ``version`` in ``theme.yml``). + +.. note:: + + ``theme.yml`` muss im Stammverzeichnis des ZIP abgelegt werden. Wird + die Datei in einem Unterverzeichnis abgelegt, wird sie beim + Hochladen nicht erkannt. + +Veröffentlichen +--------------- + +Die vom |Fess|-Projekt entwickelten Themes werden unter +https://maven.codelibs.org/release/org/codelibs/fess/themes/ veröffentlicht, als +``//-.zip`` mit einer ``.sha1`` daneben und einer +``maven-metadata.xml`` je Theme, die die veröffentlichten Versionen auflistet. +``bin/fess-setup install theme `` liest diese Metadaten, um die Version zu wählen, die für +das laufende |Fess| gebaut wurde. + +Versionieren Sie ein Theme auf der |Fess|-Linie, für die es gedacht ist, und erhöhen Sie die +Version immer dann, wenn sich ändert, was das Archiv ausliefert. Eine veröffentlichte Version wird +nie überschrieben, eine Änderung unter derselben Version wird also schlicht nie verteilt. + +Aus demselben Grund gibt es im Manifest kein Feld für eine Obergrenze. Weil ein veröffentlichtes +Archiv sich nie ändert, ließe sich eine Obergrenze später nicht ergänzen, wenn ein Theme auf einem +neueren |Fess| nicht mehr läuft. Das Theme für die neuere Linie nicht zu veröffentlichen sagt +dasselbe -- zu dem Zeitpunkt, an dem man es weiß. + +.. note:: + + Ermitteln Sie die veröffentlichten Versionen aus ``maven-metadata.xml`` statt aus einer + Verzeichnisauflistung. Der Verzeichnisindex wird periodisch erzeugt, ein frisch + veröffentlichtes Theme ist also über seine Metadaten lesbar, bevor es in einer Auflistung + auftaucht. + +Installation und Aktivierung +------------------------------ + +1. Öffnen Sie in der Administrationsoberfläche „System" → „Theme" + (``/admin/theme/``). +2. Laden Sie die erstellte ZIP-Datei hoch. Ein veröffentlichtes Theme lässt sich + stattdessen mit ``bin/fess-setup install theme `` von der Kommandozeile + installieren; siehe :doc:`../install/fess-setup`. +3. Wählen Sie auf der Listenseite im Dropdown-Menü „Standard-Theme" das + gewünschte Theme aus, und klicken Sie auf die Schaltfläche + „Festlegen", um es zu aktivieren. + +Der Aktivierungsmechanismus funktioniert wie folgt. + +- Beim Klicken auf die Schaltfläche „Festlegen" wird der Name des + ausgewählten Themes in der Systemeigenschaft ``theme.default`` + gespeichert und wird so zum systemweiten Standard-Theme. +- Wenn der Theme-Name mit dem Schlüssel eines virtuellen Hosts + übereinstimmt, wird das Theme nur beim Zugriff auf diesen virtuellen + Host angewendet. Dadurch kann das Theme pro virtuellem Host + umgeschaltet werden. +- Wenn Sie das Verzeichnis ``themes/`` direkt auf der Festplatte + aktualisieren, können Sie mit „Neu laden" ein erneutes Scannen + auslösen. + +.. note:: + + Für das Hochladen von ZIP-Dateien gelten Obergrenzen für + Dateigröße, Gesamtgröße nach dem Entpacken und Anzahl der Einträge; + diese lassen sich über die ``theme.*``-Eigenschaften in + ``fess_config.properties`` anpassen (Beispiel: + ``theme.upload.max.size`` beträgt standardmäßig 50MB, + ``theme.directory.path`` ist standardmäßig ``themes``). Beim + Entpacken werden Prüfungen durchgeführt, um Angriffe durch ZIP Slip + und Zip Bombs zu verhindern. + +.. _theme-customize-bundled: + +Mitgeliefertes Theme anpassen +----------------------------- + +Das mitgelieferte Theme ``bootstrap`` liegt in ``app/themes/bootstrap/`` +der |Fess|-Installation (``/usr/share/fess/app/themes/bootstrap/`` bei +den RPM/DEB-Paketen). Bearbeiten Sie es nicht direkt: Ein Upgrade +ersetzt es, und der Name ``bootstrap`` ist dafür reserviert, sodass es +weder gelöscht noch durch einen Upload ersetzt werden kann. Kopieren +Sie es stattdessen unter einem neuen Namen. + +1. Kopieren Sie das Verzeichnis, zum Beispiel nach ``mytheme``:: + + $ cp -r app/themes/bootstrap /tmp/mytheme + +2. Ändern Sie in ``theme.yml`` den Wert ``name`` in ``mytheme`` und + ändern Sie ``displayName``. ``name`` muss mit dem Verzeichnisnamen + übereinstimmen. + +3. Lassen Sie ``index.html`` unverändert. Die mitgelieferte + ``index.html`` verweist auf ihre eigenen Dateien, etwa das Stylesheet, + die Logos und das Skript, als ``{{themePath}}/assets/...``, und |Fess| + ersetzt ``{{themePath}}`` bei der Auslieferung durch ``themes/`` + (den ``name`` in ``theme.yml``). Das Umbenennen genügt daher, damit die + Kopie ihre eigenen Dateien lädt. Wenn Sie eine Datei hinzufügen, auf die + ``index.html`` verweist, schreiben Sie ihre URL ebenfalls als + ``{{themePath}}/assets/...``. + +4. Nehmen Sie Ihre Änderungen vor: + + - Farben und Layout: ``assets/styles.css``. + - Logos: ``assets/logo-head.png`` (Kopfzeile) und ``assets/logo.png`` + (Startseite der Suche). + - Texte, etwa die Fußzeile (``footer.copyright_org``): die Dateien + ``i18n/messages..json``, eine pro Sprache. + - Seitenstruktur: ``index.html``. + +5. Packen Sie das Verzeichnis als ZIP mit ``theme.yml`` im + Stammverzeichnis und laden Sie es in der Administrationsoberfläche + unter „System" → „Theme" hoch:: + + $ cd /tmp/mytheme && zip -r ../mytheme.zip . + + Alternativ legen Sie das Verzeichnis in ``app/themes/`` ab und + klicken auf derselben Seite auf „Neu laden". + +6. Wählen Sie auf dieser Seite ``mytheme`` als Standard-Theme aus. + +.. note:: + + Ersetzen Sie die Kopie nach jedem |Fess|-Upgrade durch eine neue + Kopie des mitgelieferten Themes und wenden Sie Ihre Änderungen + erneut an, da das mitgelieferte Theme der ``/api/v2/*`` API seiner + |Fess|-Version folgt. + +JAR-Theme-Plugin (in 15.10 entfernt) +==================================== + +Der Typ JAR-Theme-Plugin, der JSPs, CSS und Bilder in einem ``fess-theme-*``-JAR bündelte +und sie als das nach dem Schlüssel eines virtuellen Hosts benannte Theme anwendete, wurde in +|Fess| 15.10 entfernt. 15.10 entpackt kein JAR-Theme und verwendet es für keinen Bildschirm. + +- Wenn Sie eines über „System" → „Plugin" in der Verwaltungsoberfläche installieren, wird es + nur als allgemeines JAR vom Typ ``jar`` in ``app/WEB-INF/plugin/`` abgelegt; kein + Bildschirm ändert sich. Ein aus einer früheren Version verbliebenes ``fess-theme-*.jar`` + wird ebenso aufgeführt und kann auf dieser Seite oder mit + ``bin/fess-setup remove plugin `` gelöscht werden. +- ``bin/fess-setup`` listet ``fess-theme-*`` weder auf noch installiert es sie. + +Übertragen Sie die Änderungen aus einem JAR-Theme in ein statisches Theme: + +- Für Farben, Layout und Logo der Suchoberfläche kopieren Sie das mitgelieferte Theme und + ändern die Kopie (siehe `Mitgeliefertes Theme anpassen`_). +- Wenn Sie das Aussehen pro virtuellem Host geändert haben, installieren Sie ein statisches + Theme, das nach dem virtuellen Host benannt ist (siehe :doc:`../config/security-virtual-host`). +- Der Anmeldebildschirm (``/login/``) ist für alle virtuellen Hosts derselbe. Ein Theme + kann ihn nicht ändern. + +Beispiele für vorhandene Themes +=================================== + +- `fess-themes `__ - Sammlung + statischer Themes (enthält mehrere statische Themes wie + ``codesearch`` und ``docsearch``) + +Referenzinformationen +========================= + +- :doc:`plugin-architecture` - Plugin-Architektur +- :doc:`../admin/plugin-guide` - Plugin-Installation diff --git a/de/15.10/dev/webapp-plugin.rst b/de/15.10/dev/webapp-plugin.rst new file mode 100644 index 000000000..0997bcbd6 --- /dev/null +++ b/de/15.10/dev/webapp-plugin.rst @@ -0,0 +1,334 @@ +================================== +Webanwendungs-Plugin +================================== + +Übersicht +========= + +Webanwendungs-Plugins (``fess-webapp-*``) sind Plugins, die die Webanwendung +von |Fess| erweitern. Anders als andere Plugin-Typen fügen sie nicht direkt +Action-Klassen oder JSPs hinzu, sondern erweitern die Funktionalität, indem +sie dem DI-Container (Lasta Di) **Komponenten hinzufügen oder ersetzen**. +Typische Anwendungsfälle sind: + +- Hinzufügen neuer Komponenten (z. B. Helper, Services) +- Ersetzen von Komponenten des |Fess|-Kerns (durch Unterklassenbildung) +- Hinzufügen von REST-API-Endpunkten (``WebApiManager``) +- Erweiterung des Suchverhaltens (Query-Commands, Rank-Fusion usw.) + +.. note:: + + Webanwendungs-Plugins werden als JAR-Datei ausgeliefert; ihre Klassen und + DI-Konfigurationsdateien werden in den Klassenpfad der Webanwendung von + |Fess| geladen. Sie fügen keine JSP-Views hinzu. Wenn Sie das Design der + Suchoberfläche anpassen möchten, lesen Sie :doc:`theme-development`. + +Grundstruktur +============= + +Am Beispiel von +`fess-webapp-example `__, +der Implementierungsvorlage für Webanwendungs-Plugins, besteht ein Plugin +aus einer „Implementierungsklasse" und einer „DI-Registrierungsdatei": + +:: + + fess-webapp-example/ + ├── pom.xml + └── src/main/ + ├── java/org/codelibs/fess/webapp/example/helper/ + │ ├── ExampleHelper.java # Hinzuzufügende Komponente + │ └── CustomSystemHelper.java # Ersetzen einer Kernkomponente + └── resources/ + ├── app++.xml # Hinzufügen einer Komponente (Merge) + └── fess+systemHelper.xml # Ersetzen einer Komponente + +.. note:: + + Das Paket der Implementierungsklasse folgt dem Schema + ``org.codelibs.fess.webapp.``. Die DI-Konfigurationsdateien + werden unter ``src/main/resources/`` abgelegt. Anders als bei + DataStore-Plugins enthält das Projekt kein ``src/main/webapp/`` und + keine JSPs. + +pom.xml und Manifest +==================== + +Webanwendungs-Plugins werden als jar mit ``fess-parent`` als übergeordnetem +POM gebaut. Bibliotheken wie ``fess`` und ``opensearch``, die zur Laufzeit +vom |Fess|-Kern bereitgestellt werden, werden mit dem Scope ``provided`` +deklariert. Zur Laufzeit benötigte Bibliotheken wie ``lastaflute``, +``dbflute-runtime`` und ``corelib`` werden mit dem normalen Scope +deklariert. + +Das Wichtigste bei einem Webanwendungs-Plugin ist, dem JAR-Manifest den +Eintrag ``Fess-WebAppJar: true`` hinzuzufügen. Durch diese Deklaration +mountet |Fess| die Klassen und DI-Konfigurationsdateien des Plugins in den +Klassenlader der Webanwendung. Diese Einstellung wird über +``maven-jar-plugin`` vorgenommen: + +.. code-block:: xml + + + + + maven-jar-plugin + + + + true + + + + + + + +.. warning:: + + Wird ``Fess-WebAppJar: true`` nicht gesetzt, werden die Klassen und + DI-Konfigurationsdateien des Plugins nicht in den Klassenpfad der + Webanwendung geladen, und das Hinzufügen bzw. Ersetzen von Komponenten + wird nicht wirksam. + +Den vollständigen Aufbau der pom.xml (übergeordnetes POM, Deklaration von +Abhängigkeiten usw.) finden Sie unter :doc:`plugin-architecture`. + +Erweiterungsmuster +================== + +Hinzufügen von Komponenten (app++.xml) +-------------------------------------- + +Die grundlegendste Erweiterungsmethode besteht darin, eigene Komponenten +hinzuzufügen. Lasta Di **merged** die ``app++.xml`` im Klassenpfad in den +``app``-Namensraum, der aus der ``app.xml`` des |Fess|-Kerns aufgebaut wird +(das ``++`` am Ende ist die Konvention für ein zusammenführendes Merge). +Da die hinzuzufügenden Komponenten Namen verwenden, die im |Fess|-Kern +nicht existieren, wird nichts überschrieben. + +.. code-block:: xml + + + + + + + + +Bei der Implementierung der Komponente wird für die Initialisierung +``@PostConstruct`` verwendet; Komponenten des |Fess|-Kerns werden über +``ComponentUtil`` abgerufen und wiederverwendet (nicht kopiert oder +überschrieben): + +.. code-block:: java + + package org.codelibs.fess.webapp.example.helper; + + import org.codelibs.fess.helper.SystemHelper; + import org.codelibs.fess.util.ComponentUtil; + + import jakarta.annotation.PostConstruct; + + public class ExampleHelper { + + protected String pluginName = "fess-webapp-example"; + + @PostConstruct + public void init() { + // Initialisierungslogik, die nach der Erzeugung durch DI einmalig aufgerufen wird + } + + public String getPluginLabel() { + // Wiederverwendung des Core-SystemHelper zum Ermitteln der laufenden Fess-Version + final SystemHelper systemHelper = ComponentUtil.getSystemHelper(); + final String version = systemHelper != null ? systemHelper.getProductVersion() : "unknown"; + return pluginName + " (Fess " + version + ")"; + } + } + +.. tip:: + + Ziehen Sie zunächst dieses „Hinzufügen von Komponenten" in Betracht. + Solange keine Kernfunktionen geändert werden müssen, ist dies sicherer + und besser wartbar als ein Ersetzen. + +Ersetzen von Kernkomponenten (fess+componentName.xml) +------------------------------------------------------ + +Wenn Sie das Verhalten einer Komponente des |Fess|-Kerns ändern möchten, +bilden Sie eine Unterklasse der Zielklasse und registrieren diese in einer +DI-Konfigurationsdatei mit dem Namen ``+.xml`` +**erneut unter demselben Komponentennamen**. Da ``systemHelper`` +beispielsweise in der ``fess.xml`` des |Fess|-Kerns deklariert ist, lautet +die Ersetzungsdatei ``fess+systemHelper.xml`` (nicht +``app+systemHelper.xml``). + +.. code-block:: java + + package org.codelibs.fess.webapp.example.helper; + + import java.nio.file.Path; + + import org.codelibs.fess.helper.SystemHelper; + + public class CustomSystemHelper extends SystemHelper { + + @Override + protected void parseProjectProperties(final Path propPath) { + try { + super.parseProjectProperties(propPath); + } catch (final Exception e) { + // eigene Verarbeitung + } + System.setProperty("fess.webapp.plugin", "true"); + } + } + +.. warning:: + + Das Ersetzen (einzelnes ``+``) ersetzt die Komponentendefinition + **vollständig**. Aus diesem Grund müssen in der Ersetzungsdatei alle + ````-Einträge, die in der Kerndefinition vorhanden sind, + erneut angegeben werden (z. B. ``queryHelper`` in ``app.xml``). Diese + müssen mit jedem |Fess|-Release synchronisiert werden. Ruft die Datei + weiterhin eine Methode auf, die aus dem Kern entfernt wurde, schlägt die + Initialisierung der Komponentendefinition mit einer + ``BeanMethodNotFoundException`` fehl. So wurde in 15.10 + ``addDesignJspFileName`` aus ``systemHelper`` entfernt; eine + Ersetzungsdatei, die sie noch aufruft, schlägt fehl. Dieser + Wartungsaufwand ist der Grund, warum das Hinzufügen dem Ersetzen + vorgezogen werden sollte. + +Hinzufügen einer REST-API (fess_api++.xml) +------------------------------------------- + +Um einen neuen REST-API-Endpunkt hinzuzufügen, implementieren Sie +``WebApiManager``. Erben Sie von ``BaseApiManager`` und registrieren Sie +sich selbst in ``@PostConstruct`` bei der ``WebApiManagerFactory``. Der +registrierte API-Manager wird bei jeder Anfrage von ``WebApiFilter`` +aufgerufen. Registrieren Sie die Komponente in ``fess_api++.xml``: + +.. code-block:: xml + + + + + + + + +.. code-block:: java + + package org.codelibs.fess.webapp.example.api; + + import java.io.IOException; + + import org.codelibs.fess.api.BaseApiManager; + import org.codelibs.fess.util.ComponentUtil; + + import jakarta.annotation.PostConstruct; + import jakarta.servlet.FilterChain; + import jakarta.servlet.ServletException; + import jakarta.servlet.http.HttpServletRequest; + import jakarta.servlet.http.HttpServletResponse; + + public class ExampleApiManager extends BaseApiManager { + + public ExampleApiManager() { + // Pfadpräfix, das von diesem Manager verarbeitet wird + setPathPrefix("/api/example"); + } + + @PostConstruct + public void register() { + ComponentUtil.getWebApiManagerFactory().add(this); + } + + @Override + public boolean matches(final HttpServletRequest request) { + // Prüft, ob dieser Manager die Anfrage verarbeiten soll + return request.getServletPath().startsWith(pathPrefix); + } + + @Override + public void process(final HttpServletRequest request, final HttpServletResponse response, + final FilterChain chain) throws IOException, ServletException { + // Verarbeitung der Anfrage und Schreiben der Antwort + } + + @Override + protected void writeHeaders(final HttpServletResponse response) { + // Setzen der Antwort-Header (bei Bedarf) + } + } + +Als Implementierungsbeispiele bieten sich +`fess-webapp-v1-api `__, +das ``/api/v1`` bereitstellt, sowie +`fess-webapp-classic-api `__, +das ``/json`` / ``/suggest`` bereitstellt, als Referenz an. + +Anpassung der Suchoberfläche +============================ + +Webanwendungs-Plugins können keine JSP-Views hinzufügen. JSP-Views befinden +sich unter ``WEB-INF/view/`` im WAR des |Fess|-Kerns, während das +Plugin-JAR in den Klassenpfad (``WEB-INF/classes``) gemountet wird. Wenn +Sie das Design der Suchoberfläche ändern möchten, nutzen Sie ein statisches +Theme. Es passt das Design der Suchoberfläche (HTML/CSS/JavaScript) an. +Siehe :doc:`theme-development`. + +Build und Installation +======================= + +:: + + mvn clean package + +Im Verzeichnis ``target/`` wird eine JAR-Datei erzeugt (z. B. +``fess-webapp-example-15.10.0.jar``). Installieren Sie das erzeugte JAR +entweder über die Administrationsoberfläche, oder legen Sie es im +Verzeichnis ``app/WEB-INF/plugin/`` ab und starten Sie |Fess| neu. Details +zum Installationsvorgang finden Sie unter :doc:`../admin/plugin-guide`. + +Beispiele veröffentlichter Plugins +================================== + +Im |Fess|-Projekt sind die folgenden Webanwendungs-Plugins veröffentlicht. +Sie sind als Referenz für die Entwicklung auf +`GitHub `__ verfügbar: + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Plugin + - Beschreibung + * - ``fess-webapp-example`` + - Implementierungsvorlage für Plugins + * - ``fess-webapp-v1-api`` + - ``/api/v1`` REST-API + * - ``fess-webapp-classic-api`` + - ``/json`` / ``/suggest`` Legacy-REST-API + * - ``fess-webapp-mcp`` + - MCP-Server (Model Context Protocol) + * - ``fess-webapp-bangs`` + - Bangs im Stil von DuckDuckGo (``!g``), die eine Suche an eine andere Website senden + * - ``fess-webapp-semantic-search`` + - Neuronale Suche/Vektorsuche (veraltet; abgelöst durch die Kernintegration in 15.10) + * - ``fess-webapp-multimodal`` + - Multimodale Suche (Bild und Text) + +Referenzinformationen +===================== + +- :doc:`plugin-architecture` - Plugin-Architektur +- :doc:`theme-development` - Theme-Anpassung +- :doc:`../admin/plugin-guide` - Plugin-Installation +- :doc:`overview` - Entwicklerdokumentation Übersicht + diff --git a/de/15.10/install/fess-setup.rst b/de/15.10/install/fess-setup.rst new file mode 100644 index 000000000..c9ab19437 --- /dev/null +++ b/de/15.10/install/fess-setup.rst @@ -0,0 +1,355 @@ +====================== +Der Befehl fess-setup +====================== + +``bin/fess-setup`` (unter Windows ``bin\fess-setup.bat``) liegt dem ZIP-Paket von |Fess| bei. +Es installiert, was |Fess| benötigt, aber nicht mitliefert: OpenSearch mit den von |Fess| +benötigten Plugins, Node.js für die Playwright-Plugins, |Fess|-Plugins und statische Themes. Außerdem prüft es eine +Installation. + +Führen Sie es im |Fess|-Verzeichnis aus. Ohne Argumente gibt es die Liste der Befehle aus. + +:: + + $ cd /path/to/fess-15.10.0 + $ bin/fess-setup [options] + +Exit-Codes +========== + +.. list-table:: + :header-rows: 1 + :widths: 15 85 + + * - Code + - Bedeutung + * - ``0`` + - Der Befehl war erfolgreich. + * - ``1`` + - Der Befehl ist fehlgeschlagen: zum Beispiel ist ein Download fehlgeschlagen, die angeforderte + Version existiert nicht, OpenSearch veröffentlicht für diese Plattform keinen Build, oder + ``check`` hat ein Problem gefunden. + * - ``2`` + - Die Befehlszeile ist fehlerhaft: ein unbekannter Befehl oder ein fehlendes Argument wie ein + Plugin-Name. + +Installation von OpenSearch und Node.js +======================================= + +install opensearch +------------------ + +:: + + $ bin/fess-setup install opensearch [--dest ] [--version ] [--keep-bundled-plugins] + +Lädt die von diesem |Fess| unterstützte OpenSearch-Version nach ``opensearch/`` im +|Fess|-Verzeichnis herunter, installiert die vier von |Fess| benötigten Plugins +(``opensearch-analysis-fess``, ``opensearch-analysis-extension``, ``opensearch-minhash`` und +``opensearch-configsync``) und fügt der ``config/opensearch.yml`` dieser Installation die folgenden +Einstellungen hinzu: + +- ``configsync.config_path``, gesetzt auf das Verzeichnis ``config/dictionary`` dieses OpenSearch +- ``plugins.security.disabled: true`` + +Außerdem entfernt der Befehl die mitgelieferten Plugins ``opensearch-security-analytics`` und +``opensearch-performance-analyzer``, die |Fess| nicht verwendet; auch das OpenSearch im Docker-Image +enthält sie nicht. Ein Plugin, das im Download nicht enthalten ist, wird übersprungen. + +Eine Einstellung, die ``opensearch.yml`` bereits enthält, wird nicht erneut hinzugefügt, und +``plugins.security.disabled: true`` wird nicht hinzugefügt, wenn die Datei irgendeine +``plugins.security.*``-Einstellung enthält. Existiert das OpenSearch-Verzeichnis bereits, wird der +Download übersprungen; ein erneuter Aufruf für eine vorhandene Installation fügt daher nur die +fehlenden Einstellungen hinzu. + +Der Befehl gibt jede hinzugefügte Einstellung aus und anschließend, ob ``bin/fess.in.sh`` dieses +OpenSearch selbst findet. Das ist der Fall, wenn es das einzige OpenSearch mit einem Verzeichnis +``config/dictionary`` unter ``opensearch/`` im |Fess|-Verzeichnis ist: ``bin/fess.in.sh`` (unter +Windows ``bin\fess.in.bat``) setzt dann ``FESS_DICTIONARY_PATH`` auf dieses Verzeichnis, und für ein +OpenSearch auf demselben Host ist nichts weiter zu konfigurieren. Andernfalls gibt der Befehl die +Werte für ``SEARCH_ENGINE_HTTP_URL`` und ``FESS_DICTIONARY_PATH`` aus, die zu setzen sind, wie in +:doc:`install-linux` oder :doc:`install-windows` beschrieben. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Option + - Beschreibung + * - ``--dest `` + - Das Verzeichnis, in das OpenSearch entpackt wird, anstelle von ``opensearch/`` im + |Fess|-Verzeichnis. ``bin/fess.in.sh`` sucht außerhalb dieses Verzeichnisses nicht nach + OpenSearch. + * - ``--version `` + - Die zu installierende OpenSearch-Version. Die Plugins werden in derselben Version installiert. + * - ``--keep-bundled-plugins`` + - Behält die mitgelieferten Plugins (``opensearch-security-analytics`` und ``opensearch-performance-analyzer``), statt sie zu entfernen, und lässt den Download unverändert. + +OpenSearch veröffentlicht offizielle Builds nur für Linux und Windows. Auf anderen Plattformen wie +macOS beendet sich der Befehl vor jedem Download mit dem Exit-Code ``1`` und schlägt vor, OpenSearch +mit Homebrew zu installieren und die Plugins mit ``install opensearch-plugins`` hinzuzufügen oder +Docker zu verwenden. + +.. warning:: + + Mit ``plugins.security.disabled: true`` nimmt OpenSearch Anfragen ohne Authentifizierung an. + OpenSearch lauscht nur auf der Loopback-Adresse, sofern ``network.host`` nicht gesetzt ist. Bevor + es auf einer anderen Adresse lauscht, konfigurieren Sie stattdessen das Sicherheits-Plugin; siehe + :doc:`security`. + +install opensearch-plugins +-------------------------- + +:: + + $ bin/fess-setup install opensearch-plugins --opensearch-home [--version ] + +Installiert die vier von |Fess| benötigten Plugins in ein bereits vorhandenes OpenSearch, anstatt +dessen ``bin/opensearch-plugin install`` viermal auszuführen. ``--opensearch-home`` ist das +Installationsverzeichnis von OpenSearch und muss angegeben werden. ``--version`` legt die +Plugin-Version fest, die mit der OpenSearch-Version übereinstimmen muss. + +Dieser Befehl ändert ``opensearch.yml`` nicht. Fügen Sie ``configsync.config_path`` und die übrigen +Einstellungen selbst hinzu, wie in :doc:`install-linux` oder :doc:`install-windows` beschrieben. + +install nodejs +-------------- + +:: + + $ bin/fess-setup install nodejs [--dest ] [--version ] + +Lädt Node.js, das die Playwright-Plugins benötigen (``fess-crawler-playwright`` für den +Playwright-Crawler und ``fess-thumbnail-playwright`` für Thumbnails), nach ``nodejs/`` im +|Fess|-Verzeichnis herunter. +``bin/fess.in.sh`` (unter Windows ``bin\fess.in.bat``) findet es dort und setzt +``PLAYWRIGHT_NODEJS_PATH``. Liegt das mit ``--dest`` angegebene Verzeichnis außerhalb des +|Fess|-Verzeichnisses, gibt der Befehl stattdessen die ``PLAYWRIGHT_NODEJS_PATH``-Zeile aus, die in +``bin/fess.in.sh`` einzutragen ist. ``--version`` wählt eine andere Node.js-Version. Zum +Playwright-Crawler siehe :doc:`../config/crawler-advanced`. + +Verwaltung von Plugins +====================== + +Diese Befehle arbeiten mit dem Plugin-Verzeichnis ``app/WEB-INF/plugin`` der |Fess|-Installation. +Starten Sie |Fess| neu, nachdem Sie Plugins installiert, aktualisiert oder entfernt haben. Plugins +lassen sich auch über die Seite **System > Plugin** in der Administrationsoberfläche verwalten; siehe +:doc:`../admin/plugin-guide`. + +``install plugin``, ``list plugins``, ``list installed``, ``upgrade plugins``, ``remove plugin`` und ``check`` akzeptieren ``--dest ``. Damit wird das Plugin-Verzeichnis angegeben, das anstelle von ``app/WEB-INF/plugin`` verwendet wird: das Verzeichnis, das die Plugin-JARs selbst enthält, nicht dessen übergeordnetes Verzeichnis. Ein relativer Pfad wird ab dem aktuellen Verzeichnis aufgelöst, nicht ab dem |Fess|-Verzeichnis. Bei ``install opensearch`` und ``install nodejs`` ist ``--dest`` dagegen das Verzeichnis, in das das Archiv entpackt wird. + +``install plugin``, ``list plugins`` und ``upgrade plugins`` akzeptieren ``--repository ``. +Damit werden die Versionsliste, die JARs und ihre Prüfsummen aus diesem einen Maven-Repository +bezogen, etwa einem internen Mirror, statt aus den standardmäßigen Release- und +Snapshot-Repositories und von GitHub. + +``--repository`` akzeptiert auch eine URL, die mit ``file:///`` beginnt. Legen Sie auf einem Server +ohne Internetzugang eine Kopie des Maven-Repositorys ab und geben Sie dieses Verzeichnis an. Anzugeben +ist das Verzeichnis, das die Verzeichnisse der einzelnen Plugins enthält (``/maven-metadata.xml`` +usw.), also die Stelle, die ``https://maven.codelibs.org/release/org/codelibs/fess/`` des +Standard-Repositorys entspricht. Versionen werden wie bei einem HTTP-Repository aufgelöst und +Prüfsummen ebenso geprüft. + +:: + + $ bin/fess-setup install plugin fess-ds-csv --repository file:///opt/maven-repo/org/codelibs/fess/ + +Ein anderes Schema als ``http``, ``https`` und ``file`` oder eine URL ohne Schema wird mit einer +einzeiligen Fehlermeldung abgelehnt. + +install plugin +-------------- + +:: + + $ bin/fess-setup install plugin [:]... [--version ] [--repository ] [--dest ] + +Installiert ein oder mehrere |Fess|-Plugins, zum Beispiel ``fess-script-groovy`` oder +``fess-ds-git``. Ein Name ohne Version installiert die neueste für dieses |Fess| gebaute Version. +``:`` legt die Version dieses Plugins fest, und ``--version`` gilt für alle Namen ohne +eigene Version. Die zuvor installierte Version eines Plugins wird gelöscht, nachdem die neue +installiert wurde. + +Ein JAR wird aus dem GitHub-Release des Plugins bezogen oder aus dem Maven-Repository, wenn das +Release keine solche Datei enthält, und wird gegen die SHA-1-Prüfsumme geprüft, die das +Maven-Repository veröffentlicht. Ein Entwicklungs-Build von |Fess| installiert auch die +Snapshot-Builds seiner eigenen Versionslinie und bevorzugt diese. + +Beispiele finden Sie unter :doc:`../admin/plugin-guide`. + +Installiert werden können nur die Plugin-Typen, die |Fess| lädt: Namen, die mit ``fess-ds-``, +``fess-ingest-``, ``fess-script-``, ``fess-webapp-``, ``fess-thumbnail-``, ``fess-crawler-``, +``fess-llm-``, ``fess-storage-`` oder ``fess-sso-`` beginnen, also dieselben, die ``list plugins`` +anzeigt. Jeder andere Name (``fess-theme-*`` oder eine Bibliothek wie ``fess`` oder ``fess-crawler``) +wird vor jedem Download mit einer einzeiligen Fehlermeldung und Exit-Code 2 abgelehnt. Wird einer von +mehreren Namen abgelehnt, wird keiner installiert. Ein statisches Theme installieren Sie mit +``install theme``. + +list plugins +------------ + +:: + + $ bin/fess-setup list plugins [--repository ] [--dest ] + +Listet die für dieses |Fess| veröffentlichten Plugins auf und kennzeichnet die installierten mit +``(installed: )``. Plugins, die installiert, aber nicht im Repository veröffentlicht sind, +etwa ein lokal gebautes JAR, werden gesondert aufgeführt. Ein Entwicklungs-Build von |Fess| +berücksichtigt zusätzlich das Snapshot-Repository. + +list installed +-------------- + +:: + + $ bin/fess-setup list installed [--dest ] + +Listet die installierten Plugins und ihre Versionen auf, ohne das Repository abzufragen. + +upgrade plugins +--------------- + +:: + + $ bin/fess-setup upgrade plugins [--repository ] [--dest ] + +Installiert jedes installierte Plugin in der Version neu, die zu diesem |Fess| passt. Ein Plugin, das +bereits diese Version hat, bleibt unverändert. Die Plugins in ``app/WEB-INF/plugin`` sind für ein +bestimmtes |Fess|-Release gebaut; führen Sie diesen Befehl daher nach einem Upgrade von |Fess| aus. + +remove plugin +------------- + +:: + + $ bin/fess-setup remove plugin ... [--dest ] + +Löscht die installierten JARs der angegebenen Plugins. Ein Name, der nicht installiert ist, wird +gemeldet und ändert den Exit-Code nicht. + +.. _fess-setup-offline: + +Umgebungen ohne Internetzugang +------------------------------ + +``install plugin``, ``list plugins`` und ``upgrade plugins`` beziehen Plugins aus Repositorys im +Internet. Auch die Installationsseite unter **System > Plugin** in der Administrationsoberfläche +bezieht die Liste der installierbaren Plugins aus den Repositorys (``plugin.repositories``) und kann +sie daher ohne Zugang nach außen nicht anzeigen. + +Bringen Sie in einer solchen Umgebung die JARs der Plugins selbst mit: + +1. Laden Sie in einer Umgebung mit Internetzugang das |Fess|-ZIP-Paket und die JARs der benötigten + Plugins herunter. Ein JAR erhalten Sie unter + ``https://maven.codelibs.org/release/org/codelibs/fess///-.jar``. + Wählen Sie die Version für dieses |Fess| (15.10.x für |Fess| 15.10). +2. Entpacken Sie in der Zielumgebung das ZIP und legen Sie die JARs in ``app/WEB-INF/plugin/`` ab. + Nach dem Start von |Fess| können Sie sie auch auf der Registerkarte „Lokal" der + Plugin-Installationsseite in der Administrationsoberfläche hochladen; siehe :doc:`../admin/plugin-guide`. +3. Starten Sie |Fess|. Wenn Sie die JARs während des Betriebs abgelegt haben, starten Sie es neu. + +Statt jedes JAR einzeln mitzubringen, können Sie auch den benötigten Teil des Maven-Repositorys (die +Verzeichnisse ``org/codelibs/fess//``) auf den Server kopieren und mit ``install plugin`` und +``--repository file:///...`` installieren. Auch dabei werden die Prüfsummen geprüft. + +Themes verwalten +================ + +Diese Befehle arbeiten auf dem Theme-Verzeichnis ``app/themes`` der |Fess|-Installation. Starten +Sie |Fess| nach dem Installieren oder Entfernen eines Themes neu, oder klicken Sie auf der Seite +System > Theme auf [Neu laden]. Themes lassen sich auch dort hochladen; siehe +:doc:`../admin/theme-guide`. + +``install theme``, ``list themes`` und ``remove theme`` akzeptieren ``--dest `` auf dieselbe Weise und geben das Theme-Verzeichnis an, das anstelle von ``app/themes`` verwendet wird. + +Die Version eines Themes benennt die |Fess|-Linie, für die es gebaut ist: ``15.10.0`` ist ein Theme +für |Fess| 15.10. Ein Name ohne Version wird deshalb zu dem Theme aufgelöst, das für dieses |Fess| +gebaut wurde -- genau wie bei einem Plugin. + +install theme +------------- + +:: + + $ bin/fess-setup install theme [:]... [--version ] [--repository ] [--dest ] + +Installiert ein oder mehrere statische Themes, zum Beispiel ``docuforge`` oder ``voicebox``. Ein +Name ohne Version installiert die neueste für dieses |Fess| gebaute Version. ``:`` +legt die Version dieses Themes fest, und ``--version`` gilt für jeden Namen, der keine eigene hat. + +Das Archiv wird gegen die SHA-1-Prüfsumme geprüft, die das Maven-Repository veröffentlicht, und +nach ``app/themes/`` entpackt. Ein unter diesem Namen bereits installiertes Theme wird +ebenso lange als Sicherung aufbewahrt wie eines, das über die Administrationsoberfläche ersetzt +wurde (Standard 7 Tage, ``theme.upload.attic.retention.days``). + +Herunterladen, Entpacken und die Prüfung des Manifests geschehen alle, bevor etwas Installiertes +angefasst wird: Ein bereits vorhandenes Theme übersteht eine fehlgeschlagene Installation +unverändert. Ein Archiv, dessen ``theme.yml`` ein anderes Theme nennt, wird abgelehnt. + +list themes +----------- + +:: + + $ bin/fess-setup list themes [--repository ] [--dest ] + +Listet die für dieses |Fess| veröffentlichten Themes auf und kennzeichnet die installierten mit +``(installed: )``. Themes, die installiert sind, aber nicht im Repository gelistet werden, +erscheinen getrennt. + +Die Liste stammt aus dem Verzeichnisindex des Repositorys, der periodisch erzeugt wird. Lässt er +sich nicht lesen, nennt der Befehl die versuchte URL und listet die installierten Themes trotzdem +auf: Ein Theme lässt sich über seinen Namen installieren, ob der Index es führt oder nicht. + +remove theme +------------ + +:: + + $ bin/fess-setup remove theme ... [--dest ] + +Löscht die genannten Themes aus ``app/themes`` und bewahrt jedes für die Aufbewahrungsfrist als +Sicherung auf. Ein nicht installierter Name wird gemeldet und ändert den Exit-Code nicht. + +War ein entferntes Theme das Standard-Theme, fällt |Fess| auf das mitgelieferte +``bootstrap``-Theme zurück, bis ein anderes gewählt wird. + +Prüfen einer Installation +========================= + +list +---- + +:: + + $ bin/fess-setup list + +Zeigt die Komponenten, die ``install`` herunterlädt, ``opensearch`` und ``nodejs``, jeweils mit ihrer +Version. + +check +----- + +:: + + $ bin/fess-setup check [--url ] [--playwright] [--dest ] + +Prüft die Installation und gibt je Prüfung eine Zeile aus, gekennzeichnet mit ``OK``, ``WARN`` oder +``FAIL``: + +- Die Suchmaschine: ob sie erreichbar ist, ihre Version (eine Warnung, wenn die Knoten + unterschiedliche Versionen melden), ob die vier von |Fess| benötigten Plugins darin installiert + sind und ob ``configsync`` antwortet. +- |Fess|: ob das Plugin-Verzeichnis existiert und beschreibbar ist, jedes installierte Plugin (ein + Fehler für ein Plugin, das für ein anderes |Fess|-Release gebaut wurde, und für ein Plugin, das + in zwei Versionen installiert ist) und ob Node.js in ``nodejs/`` im + |Fess|-Verzeichnis installiert ist. + +Die URL der Suchmaschine ist ``--url``, andernfalls die Umgebungsvariable +``SEARCH_ENGINE_HTTP_URL``, andernfalls ``http://localhost:9200``. ``bin/fess-setup`` liest +``bin/fess.in.sh`` nicht; geben Sie daher ``--url`` an, wenn OpenSearch woanders läuft. Ein +fehlendes Node.js wird nur gemeldet, es sei denn, ``--playwright`` ist angegeben; dann gilt es als +Fehler. + +Der Befehl endet mit dem Exit-Code ``0``, wenn keine Prüfung fehlgeschlagen ist, auch wenn einige +Prüfungen Warnungen ausgegeben haben, und andernfalls mit dem Exit-Code ``1``. diff --git a/de/15.10/install/index.rst b/de/15.10/install/index.rst new file mode 100644 index 000000000..57205fb51 --- /dev/null +++ b/de/15.10/install/index.rst @@ -0,0 +1,25 @@ +|Fess| Installationsanleitung +============================= + +Die Installation und der Start von |Fess| unter Linux, Windows oder +Docker, mit Voraussetzungen, Sicherheitseinstellungen, Aktualisierung +und Fehlerbehebung. + +.. toctree:: + :maxdepth: 2 + :caption: Inhalt + + intro + prerequisites + install + install-linux + install-windows + install-docker + fess-setup + run + security + upgrade + uninstall + troubleshooting + + diff --git a/de/15.10/install/install-docker.rst b/de/15.10/install/install-docker.rst new file mode 100644 index 000000000..b2c485320 --- /dev/null +++ b/de/15.10/install/install-docker.rst @@ -0,0 +1,608 @@ +===================================== +Installation mit Docker (Detailliert) +===================================== + +Diese Seite beschreibt die Installationsschritte von |Fess| mit Docker und Docker Compose. +Mit Docker können Sie schnell und einfach eine |Fess|-Umgebung einrichten. + +Voraussetzungen +================ + +- Die in :doc:`prerequisites` beschriebenen Systemanforderungen sind erfüllt +- Docker 20.10 oder höher ist installiert +- Docker Compose 2.0 oder höher ist installiert + +Überprüfung der Docker-Installation +==================================== + +Überprüfen Sie die Version von Docker und Docker Compose mit folgenden Befehlen. + +:: + + $ docker --version + $ docker compose version + +.. note:: + + Bei Verwendung einer älteren Version von Docker Compose verwenden Sie den Befehl ``docker-compose``. + Diese Dokumentation verwendet das neue ``docker compose``-Befehlsformat. + +Über Docker-Images +=================== + +Wenn Sie |Fess| mit Docker Compose starten, laufen die folgenden zwei Container: + +- **Fess** (``fess01``): das Volltext-Suchsystem selbst +- **OpenSearch** (``search01``): die Suchmaschine + +Das offizielle Docker-Image wird auf der `GitHub Container Registry `__ veröffentlicht. +Die Compose-Dateien und die Startanleitung werden im Repository `docker-fess `__ verwaltet. + +Schritt 1: Abrufen der Docker Compose-Dateien +============================================== + +Für den Start mit Docker Compose werden folgende Dateien benötigt. + +Methode 1: Dateien einzeln herunterladen +----------------------------------------- + +Laden Sie folgende Dateien herunter: + +:: + + $ mkdir fess-docker + $ cd fess-docker + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose.yaml + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose-opensearch3.yaml + +Methode 2: Repository mit Git klonen +------------------------------------- + +Wenn Git installiert ist, können Sie auch das gesamte Repository klonen: + +:: + + $ git clone --depth 1 --branch v15.10.0 https://github.com/codelibs/docker-fess.git + $ cd docker-fess/compose + +Schritt 2: Überprüfung der Docker Compose-Dateien +================================================== + +Inhalt von ``compose.yaml`` +---------------------------- + +``compose.yaml`` enthält die Konfiguration von Fess selbst (dem ``fess01``-Dienst). + +Hauptkonfigurationspunkte: + +- **Portnummer**: Port der Fess-Weboberfläche (Standard: 8080) +- **Umgebungsvariablen**: z. B. das OpenSearch-Verbindungsziel (``SEARCH_ENGINE_HTTP_URL``) oder der Pfad der Wörterbuchdateien (``FESS_DICTIONARY_PATH``) +- **Startreihenfolge**: Über ``depends_on`` ist konfiguriert, dass der Start erst erfolgt, nachdem OpenSearch (``search01``) einen normalen Zustand erreicht hat + +Inhalt von ``compose-opensearch3.yaml`` +---------------------------------------- + +``compose-opensearch3.yaml`` enthält die Konfiguration der Suchmaschine (dem ``search01``-Dienst, OpenSearch). + +Hauptkonfigurationspunkte: + +- **OpenSearch-Image**: das verwendete OpenSearch-Image (``ghcr.io/codelibs/fess-opensearch``) +- **Speichereinstellungen**: JVM-Heap-Größe +- **Volumes**: Volumes zur Datenpersistenz (``search01_data``: Indexdaten, ``search01_dictionary``: Wörterbuchdateien) + +Anpassung der Konfiguration (Optional) +----------------------------------------- + +Wenn Sie die Standardkonfiguration ändern möchten, bearbeiten Sie ``compose.yaml``. + +Beispiel: Änderung der Portnummer:: + + services: + fess01: + ports: + - "9080:8080" # Zuordnung zu Port 9080 auf dem Host + +Beispiel: Änderung der Speichereinstellungen:: + + services: + fess01: + environment: + - "FESS_HEAP_SIZE=2g" # Fess-Heap-Größe auf 2 GB setzen + +Image-Typen und Thumbnails +-------------------------- + +Die Docker-Images von |Fess| gibt es in mehreren Varianten, die sich durch ein Tag-Suffix (``-noble``, ``-al2023`` usw.) unterscheiden. Das Standard-Image ohne Suffix (Alpine-basiert) enthält nicht die externen Werkzeuge, die Thumbnails von Bildern, PDF-Dateien und Office-Dokumenten erzeugen (ImageMagick, poppler-utils, unoconv und LibreOffice). Mit diesem Image werden nur für HTML-Seiten Thumbnails erzeugt; für Bilder, PDF-Dateien und Office-Dokumente entstehen keine Thumbnails. + +Benötigen Sie diese Thumbnails, setzen Sie ``image`` in ``compose.yaml`` auf ein Tag mit dem Suffix ``-noble``, das die Werkzeuge enthält. + +:: + + services: + fess01: + image: ghcr.io/codelibs/fess:15.10.0-noble + +Die folgende Tabelle zeigt, was die einzelnen Images unterstützen. + +.. list-table:: + :header-rows: 1 + :widths: 40 30 30 + + * - Tag + - Bilder und PDF + - Office-Dokumente + * - ``15.10.0-noble`` + - Wird erzeugt + - Wird erzeugt + * - ``15.10.0-al2023`` + - Wird erzeugt + - Wird nicht erzeugt + * - ``15.10.0``, ``15.10.0-slim``, ``15.10.0-slim-noble``, ``15.10.0-slim-al2023`` + - Wird nicht erzeugt + - Wird nicht erzeugt + +Das Thumbnail einer HTML-Seite wird bei jedem Image aus einem Bild auf der Seite erzeugt. Damit Thumbnails angezeigt werden, aktivieren Sie außerdem die Thumbnail-Anzeige in den allgemeinen Einstellungen der Verwaltungsoberfläche. Details finden Sie unter :doc:`../config/crawler-thumbnail`. + +Schritt 3: Starten der Docker-Container +======================================== + +Grundlegender Start +-------------------- + +Starten Sie Fess und OpenSearch mit folgendem Befehl: + +:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +.. note:: + + - Mit der Option ``-f`` werden mehrere Compose-Dateien angegeben + - Mit der Option ``-d`` wird im Hintergrund ausgeführt + +Überprüfung der Startprotokolle:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f + +Drücken Sie ``Ctrl+C``, um die Protokollanzeige zu beenden. + +Überprüfung des Starts +------------------------ + +Überprüfen Sie den Status der Container:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps + +Vergewissern Sie sich, dass folgende Container gestartet sind: + +- ``fess01`` +- ``search01`` + +.. tip:: + + Der Start kann einige Minuten dauern. Zuerst erreicht OpenSearch (``search01``) einen normalen Zustand, danach startet Fess (``fess01``). + Überprüfen Sie mit ``docker compose ... ps`` den Status der einzelnen Container; sobald ``fess01`` gestartet ist, können Sie im Browser auf http://localhost:8080/ zugreifen. + +Schritt 4: Zugriff über den Browser +==================================== + +Nach Abschluss des Starts greifen Sie auf folgende URL zu: + +- **Suchseite**: http://localhost:8080/ +- **Verwaltungsseite**: http://localhost:8080/admin + +Die Suchseite ist ``bootstrap``, das mit |Fess| mitgelieferte statische Theme. Wie Sie ihr Aussehen +ändern, lesen Sie unter :doc:`../admin/theme-guide`. + +Standard-Administratorkonto: + +- Benutzername: ``admin`` +- Passwort: ``admin`` + +.. warning:: + + **Wichtiger Sicherheitshinweis** + + In Produktionsumgebungen ändern Sie bitte unbedingt das Administratorpasswort. + Weitere Informationen finden Sie unter :doc:`security`. + +Aktivierung des AI-Suchmodus (LLM-Plugins) +============================================ + +Seit |Fess| 15.10 wurde die Funktion des AI-Suchmodus (RAG Chat) als ``fess-llm-*``-Plugins ausgelagert. +Das offizielle Repository `docker-fess `__ enthält Overlay-Dateien für die wichtigsten LLM-Anbieter. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Overlay + - Verwendung + * - ``compose-ollama.yaml`` + - Ollama (lokales LLM, startet zusätzlichen ``ollama01``-Dienst) + * - ``compose-gemini.yaml`` + - Google Gemini (Cloud-API) + * - ``compose-openai.yaml`` + - OpenAI (Cloud-API) + +Jedes Overlay lädt automatisch das entsprechende Plugin über ``FESS_PLUGINS`` und aktiviert RAG Chat, indem es +``-Dfess.config.rag.chat.enabled=true`` in ``FESS_JAVA_OPTS`` setzt. +Bei Gemini und OpenAI, die Cloud-APIs verwenden, wird zusätzlich über ``-Dfess.system.rag.llm.name`` der verwendete Anbieter angegeben, +und es werden der API-Schlüssel (``rag.llm..api.key``) sowie das Modell (``rag.llm..model``) konfiguriert. +Bei Ollama wird der Standardwert von ``rag.llm.name`` (``ollama``) unverändert verwendet, sodass keine explizite Angabe erforderlich ist, +und es wird lediglich das Verbindungsziel (``rag.llm.ollama.api.url``) konfiguriert. + +Beispiel für die Verwendung von Gemini:: + + $ export GEMINI_API_KEY="AIzaSy..." + $ docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-gemini.yaml up -d + +Beispiel für die Verwendung von OpenAI:: + + $ export OPENAI_API_KEY="sk-..." + $ docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-openai.yaml up -d + +.. note:: + + Das verwendete Modell kann über die Umgebungsvariablen ``GEMINI_MODEL`` und ``OPENAI_MODEL`` geändert werden + (die Standardwerte sind ``gemini-2.5-flash`` bzw. ``gpt-5-mini``). + +Beispiel für die Verwendung von Ollama:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-ollama.yaml up -d + $ docker exec -it ollama01 ollama pull gpt-oss:20b + +.. warning:: + + Der ``ollama01``-Dienst in ``compose-ollama.yaml`` ist standardmäßig so definiert, dass er eine NVIDIA-GPU verwendet + (dafür ist das `NVIDIA Container Toolkit `__ erforderlich). + Wenn Sie in einer Umgebung ohne GPU ausführen, entfernen oder kommentieren Sie den ``deploy:``-Block (die GPU-Angabe unter ``reservations``) in ``compose-ollama.yaml``. + +.. tip:: + + Nach dem Start können Sie im Verwaltungsbildschirm unter „System > Allgemein" den verwendeten LLM-Anbieter (``rag.llm.name``) + und anbieterspezifische Einstellungen ändern. Diese Änderungen werden jedoch in einer Konfigurationsdatei innerhalb des Containers gespeichert + und gehen daher verloren, wenn der Container neu erstellt wird (``docker compose down`` gefolgt von ``up``). + Um die Einstellungen dauerhaft zu speichern, geben Sie sie wie in den obigen Beispielen über ``FESS_JAVA_OPTS`` in der Compose-Datei an. + +Datenpersistenz +================ + +Alle Daten von |Fess| (Index, gecrawlte Dokumente, Benutzerinformationen, Einstellungen usw.) werden in OpenSearch gespeichert. +Da diese Daten in den Volumes von OpenSearch persistiert werden, bleiben sie auch nach dem Löschen der Container erhalten. +Der Container von Fess selbst (``fess01``) ist zustandslos und besitzt kein eigenes Volume. + +Überprüfung der Volumes:: + + $ docker volume ls + +Die in ``compose-opensearch3.yaml`` definierten Hauptvolumes: + +- ``search01_data``: Indexdaten von OpenSearch (enthält alle Daten von Fess) +- ``search01_dictionary``: Wörterbuchdateien + +.. note:: + + Dem Volume-Namen von Docker Compose wird der Projektname (standardmäßig der Name des Verzeichnisses, in dem sich die Compose-Datei befindet) als Präfix vorangestellt. + Wenn Sie beispielsweise im Verzeichnis ``compose`` starten, lautet der tatsächliche Volume-Name z. B. ``compose_search01_data``. + +.. important:: + + Beim Löschen der Container werden die Volumes nicht gelöscht. + Um Volumes zu löschen, muss explizit der Befehl ``docker volume rm`` ausgeführt werden. + +Stoppen der Docker-Container +============================= + +Container stoppen:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop + +Container stoppen und löschen:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +.. warning:: + + Der Befehl ``down`` löscht die Container, aber nicht die Volumes. + Wenn Sie auch die Volumes (z. B. ``search01_data``) löschen möchten, fügen Sie die Option ``-v`` hinzu:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down -v + + **Achtung**: Wenn Sie diesen Befehl ausführen, werden alle in OpenSearch gespeicherten Daten gelöscht. + +Erweiterte Konfiguration +========================== + +Anpassung der Umgebungsvariablen +----------------------------------- + +Durch Hinzufügen oder Ändern von Umgebungsvariablen in ``compose.yaml`` sind detaillierte Konfigurationen möglich. + +Hauptumgebungsvariablen: + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Umgebungsvariable + - Beschreibung + * - ``FESS_HEAP_SIZE`` + - Fess-JVM-Heap-Größe (Standardwert des Docker-Images: 512m) + * - ``FESS_JAVA_OPTS`` + - Angabe zusätzlicher JVM-Optionen (z. B. Überschreiben von Einstellungen mittels ``-Dfess.config.*``) + * - ``FESS_PLUGINS`` + - Beim Start automatisch zu installierende Plugins (durch Leerzeichen getrenntes Format ``name:version``. Beispiel: ``fess-ds-wikipedia:15.10.0``) + * - ``SEARCH_ENGINE_HTTP_URL`` + - HTTP-Endpunkt von OpenSearch (Standardwert in ``compose.yaml``: ``http://search01:9200``) + * - ``SEARCH_ENGINE_TYPE`` + - Der Typ der Suchmaschine (``default``, ``vanilla`` oder ``aws``). ``vanilla`` erfordert ein Image ab Fess 15.10; verwenden Sie bei älteren Images ``cloud`` (siehe :doc:`../config/search-engine-type`). Bei den 15.8-Images gibt nur die ``-noble``-Variante den Wert an Fess weiter. + * - ``SEARCH_ENGINE_USERNAME`` / ``SEARCH_ENGINE_PASSWORD`` + - Anmeldedaten für die Verbindung zu einem OpenSearch mit aktivierter Authentifizierung + * - ``FESS_DICTIONARY_PATH`` + - Pfad der Wörterbuchdateien (mit OpenSearch gemeinsam genutztes Verzeichnis) + * - ``FESS_PORT`` + - Port, auf dem Fess innerhalb des Containers lauscht (Standardwert: 8080) + +Beispiel:: + + services: + fess01: + environment: + - "FESS_HEAP_SIZE=4g" + +.. note:: + + Wenn Sie die Zeitzone ändern möchten, geben Sie in ``FESS_JAVA_OPTS`` beispielsweise ``-Duser.timezone=Asia/Tokyo`` an. + +Anwendung von Konfigurationsdateien +-------------------------------------- + +Detaillierte Einstellungen von |Fess| werden in der Datei ``fess_config.properties`` beschrieben. +Im Docker-Image befindet sich ``fess_config.properties`` unter ``/etc/fess`` im Container. +Um die Einstellungen in der Docker-Umgebung zu übernehmen, gibt es folgende Methoden. + +Methode 1: Konfigurationsdatei mounten +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``/etc/fess`` enthält auch andere Konfigurationsdateien, die für den Betrieb von Fess erforderlich sind. Wenn Sie dieses Verzeichnis direkt durch ein Mount ersetzen, schlägt der Start fehl. +Verwenden Sie stattdessen das Override-Verzeichnis ``/opt/fess``, das an den Anfang des Klassenpfads angehängt wird (im Ausgangszustand ist es leer). + +1. Erstellen Sie auf der Host-Seite ein Verzeichnis zur Bereitstellung der Konfigurationsdatei:: + + $ mkdir -p /path/to/fess-config + +2. Holen Sie die Vorlage der Konfigurationsdatei (nur beim ersten Mal):: + + $ curl -o /path/to/fess-config/fess_config.properties https://raw.githubusercontent.com/codelibs/fess/refs/tags/fess-15.10.0/src/main/resources/fess_config.properties + +3. Bearbeiten Sie ``/path/to/fess-config/fess_config.properties`` und tragen Sie die erforderlichen Einstellungen ein:: + + # Beispiel + crawler.document.cache.enabled=false + adaptive.load.control=20 + query.facet.fields=label,host + +4. Fügen Sie im ``fess01``-Dienst von ``compose.yaml`` einen Volume-Mount hinzu:: + + services: + fess01: + volumes: + - /path/to/fess-config/fess_config.properties:/opt/fess/fess_config.properties + +5. Starten Sie den Container:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +.. note:: + + Da ``/opt/fess`` an den Anfang des Klassenpfads angehängt wird, hat die hier abgelegte ``fess_config.properties`` + Vorrang vor der im Image enthaltenen ``/etc/fess/fess_config.properties``. + Property-Dateien werden dateiweise geladen und nicht Eintrag für Eintrag zusammengeführt. + Ein Eintrag, der in Ihrer Datei fehlt, führt nicht zu einem Fehler: |Fess| verwendet den mit seiner Version ausgelieferten Standardwert und schreibt pro Eintrag eine Warnung ins Protokoll. + Eine Datei, die nur die zu ändernden Einträge enthält, funktioniert daher. Um die Warnungen zu vermeiden, gehen Sie wie in Schritt 2 von der vollständigen Datei aus. + Wenn Sie nur einzelne Einträge ändern möchten, verwenden Sie die im Folgenden beschriebene „Methode 2". + Ist ein Eintrag sowohl in dieser Datei als auch mit ``-Dfess.config.`` (Methode 2) gesetzt, gilt der mit ``-D`` gesetzte Wert. + +Methode 2: Konfiguration über Systemeigenschaften +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sie können die Konfigurationseinträge von ``fess_config.properties`` über Umgebungsvariablen als Systemeigenschaften überschreiben. + +Konfigurationseinträge, die in ``fess_config.properties`` stehen (z. B. ``crawler.document.cache.enabled=false``), +geben Sie im Format ``-Dfess.config.Einstellungsname=Wert`` an. + +Fügen Sie den Umgebungsvariablen des ``fess01``-Dienstes in ``compose.yaml`` ``FESS_JAVA_OPTS`` hinzu:: + + services: + fess01: + environment: + - "FESS_JAVA_OPTS=-Dfess.config.crawler.document.cache.enabled=false -Dfess.config.adaptive.load.control=20 -Dfess.config.query.facet.fields=label,host" + +.. note:: + + Der Teil nach ``-Dfess.config.`` entspricht dem Namen des Konfigurationseintrags in ``fess_config.properties``. + Wenn Sie nur einzelne Einträge überschreiben möchten, ist diese Methode einfacher. + +Verbindung zu externem OpenSearch +------------------------------------ + +Wenn Sie einen bestehenden OpenSearch-Cluster verwenden möchten, starten Sie nur mit ``compose.yaml`` ohne ``compose-opensearch3.yaml`` und ändern das Verbindungsziel. + +1. Starten Sie, ohne ``compose-opensearch3.yaml`` anzugeben:: + + $ docker compose -f compose.yaml up -d + +2. Legen Sie im ``fess01``-Dienst von ``compose.yaml`` das Verbindungsziel fest:: + + environment: + - "SEARCH_ENGINE_HTTP_URL=http://your-opensearch-host:9200" + +.. note:: + + Wenn Sie sich mit einem OpenSearch mit aktivierter Authentifizierung verbinden, geben Sie zusätzlich ``SEARCH_ENGINE_USERNAME`` und ``SEARCH_ENGINE_PASSWORD`` an. + +Weitere Overlays und Konfigurationen +---------------------------------------- + +Das ``docker-fess``-Repository enthält neben den oben genannten weitere Compose-Dateien und Verzeichnisse für unterschiedliche Einsatzzwecke. + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Datei / Verzeichnis + - Verwendung + * - ``compose-dashboards3.yaml`` + - Fügt OpenSearch Dashboards hinzu (Port 5601, für die Datenvisualisierung) + * - ``compose-minio.yaml`` + - Fügt MinIO (Objektspeicher) hinzu und verwendet es als Speicherziel für die Speicherfunktion von Fess + * - ``vanilla/`` + - Konfiguration mit einem reinen OpenSearch ohne die CodeLibs-Plugins (``SEARCH_ENGINE_TYPE=vanilla``; erfordert ein Image ab Fess 15.10, bei älteren Images ``cloud`` verwenden). Einige Funktionen wie die Wörterbuchverwaltung stehen nicht zur Verfügung (siehe :doc:`../config/search-engine-type`) + * - ``snapshot/`` + - Konfiguration mit Entwicklungs-(Snapshot-)Images (einschließlich Cluster-Konfigurationen und der Kombination mit Elasticsearch 8) + * - ``multi-instance/`` + - Konfiguration zum Starten mehrerer Fess-Instanzen, die sich ein einzelnes OpenSearch teilen + +Konfiguration des Docker-Netzwerks +-------------------------------------- + +Bei der Integration mit mehreren Diensten können Sie ein benutzerdefiniertes Netzwerk verwenden. + +Beispiel:: + + networks: + fess-network: + driver: bridge + + services: + fess01: + networks: + - fess-network + +Produktionsbetrieb mit Docker Compose +======================================= + +Empfohlene Einstellungen bei Verwendung von Docker Compose in Produktionsumgebungen: + +1. **Festlegen von Ressourcenbeschränkungen**:: + + deploy: + resources: + limits: + cpus: '2.0' + memory: 4G + reservations: + cpus: '1.0' + memory: 2G + +2. **Festlegen der Neustartrichtlinie**:: + + restart: unless-stopped + +3. **Protokollkonfiguration**:: + + logging: + driver: "json-file" + options: + max-size: "10m" + max-file: "3" + +4. **Aktivierung der Sicherheitseinstellungen** + + Aktivieren Sie das Sicherheits-Plugin von OpenSearch und konfigurieren Sie eine geeignete Authentifizierung. + Weitere Informationen finden Sie unter :doc:`security`. + +Fehlerbehebung +================ + +Container startet nicht +-------------------------- + +1. Überprüfen Sie die Protokolle:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs + +2. Überprüfen Sie Portnummer-Konflikte:: + + $ sudo ss -tuln | grep 8080 + $ sudo ss -tuln | grep 9200 + +3. Überprüfen Sie den Festplattenspeicherplatz:: + + $ df -h + +Speicher-Fehler +------------------ + +Wenn OpenSearch aufgrund von Speichermangel nicht startet, muss ``vm.max_map_count`` erhöht werden. + +Unter Linux:: + + $ sudo sysctl -w vm.max_map_count=262144 + +Für eine dauerhafte Einstellung:: + + $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf + $ sudo sysctl -p + +Dateninitialisierung +----------------------- + +Alle Daten löschen und in den Ausgangszustand zurücksetzen:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down -v + $ docker volume prune + +.. warning:: + + Wenn Sie diesen Befehl ausführen, werden alle Daten vollständig gelöscht. + +Nächste Schritte +================== + +Nach Abschluss der Installation lesen Sie bitte die folgende Dokumentation: + +- :doc:`run` - Start und Ersteinrichtung von |Fess| +- :doc:`security` - Sicherheitseinstellungen für Produktionsumgebungen +- :doc:`troubleshooting` - Fehlerbehebung + +Häufig gestellte Fragen +========================== + +F: Wie viel Speicherplatz wird für den Download der Images benötigt? +------------------------------------------------------------------------ + +A: Die Images von Fess und OpenSearch werden beim ersten Start heruntergeladen und benötigen zusammen einige GB an Speicherplatz. +Je nach Netzwerkumgebung kann der Download einige Zeit in Anspruch nehmen. + +F: Ist ein Betrieb unter Kubernetes möglich? +----------------------------------------------- + +A: Ja, das ist möglich. Sie können die Docker Compose-Dateien mit Tools wie ``kompose`` in Kubernetes-Manifeste konvertieren +oder eigene Manifeste erstellen und damit betreiben (ein offizielles Helm-Chart wird nicht bereitgestellt). + +F: Wie aktualisiert man die Container? +------------------------------------------ + +A: Aktualisieren Sie mit folgenden Schritten: + +1. Besorgen Sie die neuesten Compose-Dateien +2. Stoppen Sie die Container:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +3. Holen Sie neue Images:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull + +4. Starten Sie die Container:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +F: Ist eine Multi-Node-Konfiguration möglich? +------------------------------------------------- + +A: Ja, das ist möglich. Anhand von ``snapshot/compose-cluster.yaml`` im ``docker-fess``-Repository können Sie OpenSearch mit mehreren Knoten konfigurieren, +oder anhand von ``multi-instance/`` mehrere Fess-Instanzen konfigurieren, die sich ein einzelnes OpenSearch teilen. +Für Produktionsumgebungen wird jedoch die Verwendung von Orchestrierungs-Tools wie Kubernetes empfohlen. diff --git a/de/15.10/install/install-linux.rst b/de/15.10/install/install-linux.rst new file mode 100644 index 000000000..9df1879de --- /dev/null +++ b/de/15.10/install/install-linux.rst @@ -0,0 +1,575 @@ +====================================================== +Installation unter Linux (Detaillierte Anleitung) +====================================================== + +Diese Seite beschreibt die Installationsschritte von |Fess| in Linux-Umgebungen. +Sie behandelt die Paketformate ZIP, RPM und DEB. + +.. note:: + + |Fess| enthält keine Suchmaschine. Ein OpenSearch-Server ist erforderlich; die + folgenden Schritte richten ihn ein. + +Voraussetzungen +==================== + +- Die in :doc:`prerequisites` beschriebenen Systemanforderungen sind erfüllt +- Java 21 ist installiert +- OpenSearch 3.9.0 ist verfügbar (oder wird neu installiert) + +Auswahl der Installationsmethode +===================================== + +In Linux-Umgebungen können Sie aus folgenden Installationsmethoden wählen: + +.. list-table:: + :header-rows: 1 + :widths: 20 40 40 + + * - Methode + - Empfohlene Umgebung + - Merkmale + * - ZIP + - Entwicklungsumgebung, Umgebungen mit Anpassungsbedarf + - Kann in beliebiges Verzeichnis entpackt werden + * - RPM + - RHEL, CentOS, Fedora-Systeme + - Dienstverwaltung mit systemd möglich + * - DEB + - Debian, Ubuntu-Systeme + - Dienstverwaltung mit systemd möglich + +Systemkonfiguration für den Betrieb von OpenSearch +======================================================= + +Um OpenSearch unter Linux stabil zu betreiben, müssen die folgenden Kernel-Parameter und Ressourcenbegrenzungen konfiguriert werden. +Diese sind hauptsächlich für die TAR.GZ-Version erforderlich (wenn OpenSearch manuell installiert wird). +Bei den RPM-/DEB-Versionen legen die Pakete von OpenSearch und |Fess| die Anzahl der Dateideskriptoren usw. über systemd fest, aber da ``vm.max_map_count`` eine Kernel-Einstellung auf Host-Ebene ist, sollten Sie diese unabhängig von der gewählten Methode überprüfen. + +Maximale Anzahl virtueller Speicher-Mappings +------------------------------------------------- + +Da OpenSearch eine große Anzahl an Speicher-Mappings verwendet, setzen Sie ``vm.max_map_count`` auf mindestens ``262144``. + +Für eine temporäre Einstellung:: + + $ sudo sysctl -w vm.max_map_count=262144 + +Für eine dauerhafte Einstellung:: + + $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf + $ sudo sysctl -p + +Anzahl der Dateideskriptoren +--------------------------------- + +Wenn Sie OpenSearch manuell ausführen (TAR.GZ-Version), setzen Sie das Limit für die Anzahl der Dateideskriptoren des Benutzers, der OpenSearch ausführt, auf mindestens ``65535``. + +Fügen Sie Folgendes zu ``/etc/security/limits.conf`` hinzu (ersetzen Sie ``opensearch`` durch den Benutzernamen, unter dem OpenSearch ausgeführt wird):: + + opensearch - nofile 65535 + +.. note:: + + Bei den RPM-/DEB-Versionen wird das Limit für die Anzahl der Dateideskriptoren bereits in der systemd-Dienstdefinition festgelegt, sodass diese Einstellung nicht erforderlich ist. + +Installation mit ZIP-Version +==================================== + +Schritt 1: Installation von OpenSearch +------------------------------------------- + +.. important:: + + Installieren und betreiben Sie OpenSearch als normaler Benutzer, nicht als ``root``: OpenSearch + verweigert den Start als ``root``. Führen Sie auch ``bin/fess-setup`` unten als dieser Benutzer + aus, damit die entpackten Dateien diesem Benutzer gehören. Siehe :doc:`run`, falls ein Start als + ``root`` bereits verweigert wurde. + +.. tip:: + + ``bin/fess-setup``, das |Fess| beiliegt, führt die Schritte 1 bis 3 unten in einem Befehl aus. + Es lädt OpenSearch herunter und entpackt es nach ``opensearch/`` im |Fess|-Verzeichnis, + installiert die benötigten Plugins und fügt ``configsync.config_path`` und + ``plugins.security.disabled: true`` zu dessen ``config/opensearch.yml`` hinzu. Entpacken Sie + zuerst das ZIP von |Fess|, wie in Schritt 2 beschrieben. + + :: + + $ cd /path/to/fess-15.10.0 + $ bin/fess-setup install opensearch + + ``bin/fess.in.sh`` findet ein so installiertes OpenSearch und setzt ``FESS_DICTIONARY_PATH`` + selbst, sodass „Konfiguration von Fess" in Schritt 2 keine Änderung erfordert, solange OpenSearch + auf demselben Host läuft. Der Befehl gibt die hinzugefügten Einstellungen aus und ob + ``bin/fess.in.sh`` die Installation findet. Lesen Sie die Warnung in Schritt 3, bevor OpenSearch + auf einer anderen Adresse als ``localhost`` lauscht. + + Folgen Sie den Schritten unten, um sie einzeln durchzugehen oder ein vorhandenes OpenSearch + zu verwenden. Um nur die Plugins in ein vorhandenes OpenSearch zu installieren, verwenden Sie + ``bin/fess-setup install opensearch-plugins --opensearch-home /path/to/opensearch``. + Alle Befehle finden Sie unter :doc:`fess-setup`. + +.. note:: + + OpenSearch veröffentlicht keinen Build für macOS, daher bricht + ``bin/fess-setup install opensearch`` unter macOS mit einem Fehler ab. Installieren Sie + OpenSearch mit Homebrew und fügen Sie die Plugins mit ``bin/fess-setup install opensearch-plugins`` + hinzu, oder verwenden Sie stattdessen :doc:`install-docker`:: + + $ brew install opensearch + $ bin/fess-setup install opensearch-plugins --opensearch-home $(brew --prefix opensearch) + + Konfigurieren Sie dieses OpenSearch anschließend wie in Schritt 3, und setzen Sie + ``FESS_DICTIONARY_PATH`` wie unter „Konfiguration von Fess" in Schritt 2 beschrieben. + +1. Download von OpenSearch + + Laden Sie die TAR.GZ-Version von `Download OpenSearch `__ herunter. + + :: + + $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.9.0/opensearch-3.9.0-linux-x64.tar.gz + $ tar -xzf opensearch-3.9.0-linux-x64.tar.gz + $ cd opensearch-3.9.0 + + Auf einem arm64-Rechner (aarch64) ersetzen Sie in den obigen Dateinamen ``linux-x64`` durch ``linux-arm64`` (zum Beispiel ``opensearch-3.9.0-linux-arm64.tar.gz``). + + .. note:: + + In diesem Beispiel wird OpenSearch 3.9.0 verwendet. + |Fess| 15.10 unterstützt OpenSearch 3.9.0. + +2. Installation der OpenSearch-Plugins + + Installieren Sie die von |Fess| benötigten Plugins. + + :: + + $ cd /path/to/opensearch-3.9.0 + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + + .. important:: + + Die Plugin-Version muss mit der OpenSearch-Version übereinstimmen. + Im obigen Beispiel sind alle auf 3.9.0 gesetzt. + + Die vier Plugins für |Fess| werden auf maven.codelibs.org veröffentlicht und daher per URL + installiert. Die Form ``groupId:artifactId:version`` von ``opensearch-plugin install`` sucht + nur in Maven Central. + +3. Konfiguration von OpenSearch + + Fügen Sie in ``config/opensearch.yml`` folgende Einstellungen hinzu. + + :: + + # Pfad für Konfigurationssynchronisation (als absoluter Pfad angeben) + configsync.config_path: /path/to/opensearch-3.9.0/config/dictionary/ + + # Deaktivierung des Sicherheits-Plugins (nur Entwicklungsumgebung) + plugins.security.disabled: true + + .. important:: + + Geben Sie für ``configsync.config_path`` ein Verzeichnis unterhalb des OpenSearch-Konfigurationsverzeichnisses an (in diesem Beispiel ``/path/to/opensearch-3.9.0/config/``). + Ab OpenSearch 3.8.0 wird die Erstellung eines Index verweigert, wenn sich Wörterbuchdateien außerhalb des Konfigurationsverzeichnisses befinden. + Wenn Sie ein Verzeichnis außerhalb des Konfigurationsverzeichnisses angeben, z. B. ``/path/to/opensearch-3.9.0/data/config/``, kann |Fess| seine Indizes nicht erstellen und startet nicht. + + .. warning:: + + **Wichtiger Sicherheitshinweis** + + ``plugins.security.disabled: true`` sollte nur in Entwicklungs- oder Testumgebungen verwendet werden. + In Produktionsumgebungen aktivieren Sie bitte das Sicherheits-Plugin von OpenSearch und konfigurieren Sie entsprechende Authentifizierungs- und Autorisierungseinstellungen. + Wenn Sie das Sicherheits-Plugin unter OpenSearch 2.12 oder höher aktivieren, muss beim ersten Start ein Administratorkennwort (Umgebungsvariable ``OPENSEARCH_INITIAL_ADMIN_PASSWORD``) festgelegt werden. + Weitere Informationen finden Sie unter :doc:`security`. + + .. tip:: + + Passen Sie andere Einstellungen wie Clustername und Netzwerkeinstellungen entsprechend Ihrer Umgebung an. + Konfigurationsbeispiel:: + + cluster.name: fess-cluster + node.name: fess-node-1 + network.host: 0.0.0.0 + discovery.type: single-node + + .. tip:: + + Die Heap-Größe von OpenSearch wird über ``-Xms`` / ``-Xmx`` in ``config/jvm.options`` konfiguriert. + Es wird empfohlen, für ``-Xms`` und ``-Xmx`` denselben Wert anzugeben, der höchstens die Hälfte des verfügbaren physischen Arbeitsspeichers beträgt und unter 32 GB liegt. + +Schritt 2: Installation von Fess +------------------------------------- + +1. Download und Entpacken von Fess + + Laden Sie die ZIP-Version von der `Download-Site `__ herunter. + + :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.zip + $ unzip fess-15.10.0.zip + $ cd fess-15.10.0 + + .. note:: + + Wählen Sie ein Verzeichnis ohne Leerzeichen im Pfad (auch unter macOS). Enthält der Pfad ein Leerzeichen, startet ``bin/fess`` nicht und gibt ``Could not find or load main class`` aus. + +2. Konfiguration von Fess + + Die Verbindungsinformationen zu OpenSearch stehen in ``bin/fess.in.sh``. Bei einem OpenSearch, das + ``bin/fess-setup install opensearch`` nach ``opensearch/`` im |Fess|-Verzeichnis installiert hat + und das auf demselben Host läuft, muss diese Datei nicht geändert werden: + ``SEARCH_ENGINE_HTTP_URL`` ist standardmäßig ``http://localhost:9200``, und + ``FESS_DICTIONARY_PATH`` wird auf das Verzeichnis ``config/dictionary`` dieses OpenSearch gesetzt. + + Bearbeiten Sie ``bin/fess.in.sh`` in den folgenden Fällen: + + - OpenSearch wurde auf andere Weise installiert, etwa mit den Schritten 1 bis 3 oben oder mit + Homebrew, oder mit ``--dest`` außerhalb des |Fess|-Verzeichnisses. + - ``opensearch/`` im |Fess|-Verzeichnis enthält mehr als ein von ``bin/fess-setup`` + installiertes OpenSearch, zum Beispiel zwei Versionen. ``bin/fess.in.sh`` kann nicht erkennen, + welches davon verwendet wird, gibt daher eine Warnung aus und lässt ``FESS_DICTIONARY_PATH`` + ungesetzt. + - OpenSearch läuft auf einem anderen Host oder Port. + + :: + + $ vi bin/fess.in.sh + + Entfernen Sie in der Nähe des Dateianfangs das führende ``#`` der Zeile ``FESS_DICTIONARY_PATH`` + und setzen Sie den Pfad; ändern Sie bei Bedarf die URL in der Zeile ``SEARCH_ENGINE_HTTP_URL``. + + Vor der Änderung (Standardzustand, Kommentarzeilen ausgelassen):: + + SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://localhost:9200} + #FESS_DICTIONARY_PATH=/var/lib/opensearch/config/ + + Nach der Änderung:: + + SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://localhost:9200} + FESS_DICTIONARY_PATH=/path/to/opensearch-3.9.0/config/dictionary/ + + .. note:: + + - Setzen Sie für ``FESS_DICTIONARY_PATH`` denselben Pfad wie den in ``opensearch.yml`` von OpenSearch angegebenen ``configsync.config_path``. Ohne diese Einstellung kann |Fess| seine Indizes nicht anlegen und startet nicht. + - Wenn OpenSearch auf einem anderen Host ausgeführt wird, ändern Sie die URL in der Zeile ``SEARCH_ENGINE_HTTP_URL`` auf diesen Host. Beispiel: ``SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://192.168.1.100:9200}``. ``FESS_DICTIONARY_PATH`` ist dann der ``configsync.config_path`` dieses Servers. + - Statt die Datei zu bearbeiten, können beide Variablen auch in der Umgebung exportiert werden, aus der |Fess| gestartet wird. Eine exportierte ``SEARCH_ENGINE_HTTP_URL`` hat Vorrang vor der URL in der Datei, und ein exportierter ``FESS_DICTIONARY_PATH`` wird verwendet, solange die entsprechende Zeile in der Datei auskommentiert bleibt. + - Fügen Sie keine neue Zeile ``SEARCH_ENGINE_HTTP_URL=...`` hinzu, sondern bearbeiten Sie die vorhandene. + + .. tip:: + + Um die Heap-Größe von |Fess| zu ändern, bearbeiten Sie ``FESS_MIN_MEM`` (Standard: ``256m``) und ``FESS_MAX_MEM`` (Standard: ``2g``) in ``bin/fess.in.sh``, oder setzen Sie die Umgebungsvariable ``FESS_HEAP_SIZE``. + +3. Überprüfung der Installation + + Überprüfen Sie, ob die Konfigurationsdatei korrekt bearbeitet wurde:: + + $ grep "SEARCH_ENGINE_HTTP_URL" bin/fess.in.sh + $ grep "FESS_DICTIONARY_PATH" bin/fess.in.sh + + Sobald OpenSearch läuft, meldet ``bin/fess-setup check``, ob es erreichbar ist, ob es die von + |Fess| benötigten Plugins enthält und ob ``configsync`` antwortet. Der Befehl endet mit dem + Exit-Code ``0``, wenn keine Prüfung fehlgeschlagen ist. Geben Sie ``--url`` an, wenn OpenSearch + nicht unter ``http://localhost:9200`` erreichbar ist. + +Schritt 3: Start +--------------------- + +Die Startanleitung finden Sie unter :doc:`run`. + +Installation mit RPM-Version +================================= + +Die RPM-Version wird für RPM-basierte Linux-Distributionen wie Red Hat Enterprise Linux, CentOS und Fedora verwendet. + +Schritt 1: Installation von OpenSearch +------------------------------------------- + +1. Download und Installation des OpenSearch-RPM + + Laden Sie das RPM-Paket von `Download OpenSearch `__ herunter und installieren Sie es. + + :: + + $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.9.0/opensearch-3.9.0-linux-x64.rpm + $ sudo rpm -ivh opensearch-3.9.0-linux-x64.rpm + + Auf einem arm64-Rechner (aarch64) ersetzen Sie in den obigen Dateinamen ``linux-x64`` durch ``linux-arm64`` (zum Beispiel ``opensearch-3.9.0-linux-arm64.rpm``). + + Alternativ können Sie auch ein Repository hinzufügen und die Installation durchführen. + Details finden Sie unter `Installing OpenSearch `__. + +2. Installation der OpenSearch-Plugins + + :: + + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + +3. Konfiguration von OpenSearch + + Fügen Sie in ``/etc/opensearch/opensearch.yml`` folgende Einstellungen hinzu. + + :: + + $ sudo vi /etc/opensearch/opensearch.yml + + Hinzuzufügende Einstellungen:: + + configsync.config_path: /etc/opensearch/dictionary/ + plugins.security.disabled: true + + Erstellen Sie das Verzeichnis für die Wörterbuchdateien:: + + $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary + + .. important:: + + Geben Sie für ``configsync.config_path`` ein Verzeichnis unterhalb des OpenSearch-Konfigurationsverzeichnisses ``/etc/opensearch/`` an. + Ab OpenSearch 3.8.0 wird die Erstellung eines Index verweigert, wenn sich Wörterbuchdateien außerhalb des Konfigurationsverzeichnisses befinden. + Wenn Sie ein Verzeichnis außerhalb des Konfigurationsverzeichnisses angeben, z. B. ``/var/lib/opensearch/data/config/``, kann |Fess| seine Indizes nicht erstellen und startet nicht. + + .. warning:: + + Verwenden Sie ``plugins.security.disabled: true`` nicht in Produktionsumgebungen. + Siehe :doc:`security` für entsprechende Sicherheitseinstellungen. + +Schritt 2: Installation von Fess +------------------------------------- + +1. Installation des Fess-RPM + + Laden Sie das RPM-Paket von der `Download-Site `__ herunter und installieren Sie es. + + :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.rpm + $ sudo rpm -ivh fess-15.10.0.rpm + +2. Konfiguration von Fess + + Bei der RPM-Version bearbeiten Sie die Umgebungsvariablen-Konfigurationsdatei ``/etc/sysconfig/fess``. + Diese Datei bleibt auch bei einem Paket-Upgrade erhalten (``/usr/share/fess/bin/fess.in.sh`` wird bei einem Upgrade überschrieben, bearbeiten Sie diese Datei daher nicht direkt). + + :: + + $ sudo vi /etc/sysconfig/fess + + Konfigurieren Sie die Verbindungsinformationen zu OpenSearch. Der Standardwert ``/var/lib/opensearch/config/`` von ``FESS_DICTIONARY_PATH`` weicht von ``configsync.config_path`` aus Schritt 3 ab. Ändern Sie ihn daher wie folgt. Ändern Sie ``SEARCH_ENGINE_HTTP_URL`` bei Bedarf:: + + SEARCH_ENGINE_HTTP_URL=http://localhost:9200 + FESS_DICTIONARY_PATH=/etc/opensearch/dictionary/ + + .. note:: + + Geben Sie für ``FESS_DICTIONARY_PATH`` denselben Pfad wie ``configsync.config_path`` in ``opensearch.yml`` an. + +3. Dienstregistrierung und -aktivierung + + Aktivieren Sie den Dienst mit systemd (bei RHEL 8 oder höher und CentOS 8 oder höher ist systemd der Standard):: + + $ sudo systemctl daemon-reload + $ sudo systemctl enable opensearch.service + $ sudo systemctl enable fess.service + + .. note:: + + Da der |Fess|-Dienst vom OpenSearch-Dienst abhängt, muss OpenSearch zuerst gestartet werden. + + .. note:: + + In älteren Umgebungen ohne systemd können Sie |Fess| mit ``chkconfig`` registrieren:: + + $ sudo /sbin/chkconfig --add fess + +Schritt 3: Start +--------------------- + +Die Startanleitung finden Sie unter :doc:`run`. + +Installation mit DEB-Version +================================= + +Die DEB-Version wird für DEB-basierte Linux-Distributionen wie Debian und Ubuntu verwendet. + +Schritt 1: Installation von OpenSearch +------------------------------------------- + +1. Download und Installation des OpenSearch-DEB + + Laden Sie das DEB-Paket von `Download OpenSearch `__ herunter und installieren Sie es. + + :: + + $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.9.0/opensearch-3.9.0-linux-x64.deb + $ sudo dpkg -i opensearch-3.9.0-linux-x64.deb + + Auf einem arm64-Rechner (aarch64) ersetzen Sie in den obigen Dateinamen ``linux-x64`` durch ``linux-arm64`` (zum Beispiel ``opensearch-3.9.0-linux-arm64.deb``). + + Alternativ können Sie auch ein Repository hinzufügen und die Installation durchführen. + Details finden Sie unter `Installing OpenSearch `__. + +2. Installation der OpenSearch-Plugins + + :: + + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + +3. Konfiguration von OpenSearch + + Fügen Sie in ``/etc/opensearch/opensearch.yml`` folgende Einstellungen hinzu. + + :: + + $ sudo vi /etc/opensearch/opensearch.yml + + Hinzuzufügende Einstellungen:: + + configsync.config_path: /etc/opensearch/dictionary/ + plugins.security.disabled: true + + Erstellen Sie das Verzeichnis für die Wörterbuchdateien:: + + $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary + + .. important:: + + Geben Sie für ``configsync.config_path`` ein Verzeichnis unterhalb des OpenSearch-Konfigurationsverzeichnisses ``/etc/opensearch/`` an. + Ab OpenSearch 3.8.0 wird die Erstellung eines Index verweigert, wenn sich Wörterbuchdateien außerhalb des Konfigurationsverzeichnisses befinden. + Wenn Sie ein Verzeichnis außerhalb des Konfigurationsverzeichnisses angeben, z. B. ``/var/lib/opensearch/data/config/``, kann |Fess| seine Indizes nicht erstellen und startet nicht. + + .. warning:: + + Verwenden Sie ``plugins.security.disabled: true`` nicht in Produktionsumgebungen. + Siehe :doc:`security` für entsprechende Sicherheitseinstellungen. + +Schritt 2: Installation von Fess +------------------------------------- + +1. Installation des Fess-DEB + + Laden Sie das DEB-Paket von der `Download-Site `__ herunter und installieren Sie es. + + :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.deb + $ sudo dpkg -i fess-15.10.0.deb + +2. Konfiguration von Fess + + Bei der DEB-Version bearbeiten Sie die Umgebungsvariablen-Konfigurationsdatei ``/etc/default/fess``. + Diese Datei bleibt auch bei einem Paket-Upgrade erhalten (``/usr/share/fess/bin/fess.in.sh`` wird bei einem Upgrade überschrieben, bearbeiten Sie diese Datei daher nicht direkt). + + :: + + $ sudo vi /etc/default/fess + + Konfigurieren Sie die Verbindungsinformationen zu OpenSearch. Der Standardwert ``/var/lib/opensearch/config/`` von ``FESS_DICTIONARY_PATH`` weicht von ``configsync.config_path`` aus Schritt 3 ab. Ändern Sie ihn daher wie folgt. Ändern Sie ``SEARCH_ENGINE_HTTP_URL`` bei Bedarf:: + + SEARCH_ENGINE_HTTP_URL=http://localhost:9200 + FESS_DICTIONARY_PATH=/etc/opensearch/dictionary/ + + .. note:: + + Geben Sie für ``FESS_DICTIONARY_PATH`` denselben Pfad wie ``configsync.config_path`` in ``opensearch.yml`` an. + +3. Dienstregistrierung und -aktivierung + + Aktivieren Sie den Dienst mit systemd:: + + $ sudo systemctl daemon-reload + $ sudo systemctl enable opensearch.service + $ sudo systemctl enable fess.service + + .. note:: + + Da der |Fess|-Dienst vom OpenSearch-Dienst abhängt, muss OpenSearch zuerst gestartet werden. + +Schritt 3: Start +--------------------- + +Die Startanleitung finden Sie unter :doc:`run`. + +Überprüfung nach der Installation +====================================== + +Überprüfen Sie nach Abschluss der Installation Folgendes: + +1. **Überprüfung der Konfigurationsdateien** + + - Konfigurationsdatei von OpenSearch (opensearch.yml) + - Konfigurationsdatei von |Fess| + + - ZIP-Version: ``bin/fess.in.sh`` + - RPM-Version: ``/etc/sysconfig/fess`` + - DEB-Version: ``/etc/default/fess`` + +2. **Verzeichnisberechtigungen** + + Überprüfen Sie, ob das in der Konfiguration angegebene Verzeichnis (``configsync.config_path`` / ``FESS_DICTIONARY_PATH``) existiert und die entsprechenden Berechtigungen gesetzt sind. + + Bei der ZIP-Version:: + + $ ls -ld /path/to/opensearch-3.9.0/config/dictionary/ + + Bei der RPM-/DEB-Version:: + + $ sudo ls -ld /etc/opensearch/dictionary/ + +3. **Überprüfung der Kernel-Parameter** + + :: + + $ sysctl vm.max_map_count + + Überprüfen Sie, dass der Wert mindestens ``262144`` beträgt. + +4. **Überprüfung der Java-Version** + + :: + + $ java -version + + Überprüfen Sie, ob Java 21 oder höher installiert ist. + +Nächste Schritte +===================== + +Nach Abschluss der Installation lesen Sie bitte folgende Dokumentation: + +- :doc:`run` - Start und Ersteinrichtung von |Fess| +- :doc:`security` - Sicherheitseinstellungen für Produktionsumgebungen +- :doc:`troubleshooting` - Fehlerbehebung + +Häufig gestellte Fragen +============================ + +F: Funktioniert OpenSearch auch mit anderen Versionen? +----------------------------------------------------------- + +A: |Fess| hängt von einer bestimmten Version von OpenSearch ab. +Um die Plugin-Kompatibilität zu gewährleisten, wird die Verwendung der empfohlenen Version (3.9.0) dringend empfohlen. +Bei Verwendung anderer Versionen muss auch die Plugin-Version entsprechend angepasst werden. + +F: Können mehrere Fess-Instanzen denselben OpenSearch teilen? +------------------------------------------------------------------ + +A: Möglich, aber nicht empfohlen. Es wird empfohlen, für jede Fess-Instanz einen eigenen OpenSearch-Cluster bereitzustellen. +Bei gemeinsamer Nutzung von OpenSearch durch mehrere Fess-Instanzen ist auf Indexnamen-Konflikte zu achten. + +F: Wie konfiguriert man OpenSearch als Cluster? +---------------------------------------------------- + +A: Siehe die offizielle OpenSearch-Dokumentation `Cluster formation `__. +Bei Cluster-Konfiguration muss die Einstellung ``discovery.type: single-node`` entfernt und entsprechende Cluster-Einstellungen hinzugefügt werden. diff --git a/de/15.10/install/install-windows.rst b/de/15.10/install/install-windows.rst new file mode 100644 index 000000000..966995437 --- /dev/null +++ b/de/15.10/install/install-windows.rst @@ -0,0 +1,363 @@ +==================================================== +Installation unter Windows (Detaillierte Anleitung) +==================================================== + +Diese Seite beschreibt die Installationsschritte von |Fess| in Windows-Umgebungen. +Sie behandelt die Installationsmethode mit dem ZIP-Paket. + +.. note:: + + |Fess| enthält keine Suchmaschine. Ein OpenSearch-Server ist erforderlich; die + folgenden Schritte richten ihn ein. + +Voraussetzungen +=============== + +- Die in :doc:`prerequisites` beschriebenen Systemanforderungen sind erfüllt +- Java 21 ist installiert +- OpenSearch 3.9.0 ist verfügbar (oder wird neu installiert) +- Die Windows-Umgebungsvariable ``JAVA_HOME`` ist korrekt konfiguriert + +Überprüfung der Java-Installation +================================== + +Öffnen Sie die Eingabeaufforderung oder PowerShell und überprüfen Sie die Java-Version mit folgendem Befehl. + +Bei Eingabeaufforderung:: + + C:\> java -version + +Bei PowerShell:: + + PS C:\> java -version + +Vergewissern Sie sich, dass Java 21 oder höher angezeigt wird. + +Konfiguration der Umgebungsvariablen +===================================== + +1. Einstellung der ``JAVA_HOME``-Umgebungsvariablen + + Setzen Sie das Verzeichnis, in dem Java installiert ist, als ``JAVA_HOME``. + + Beispiel:: + + JAVA_HOME=C:\Program Files\Eclipse Adoptium\jdk-21.0.1.12-hotspot + +2. Hinzufügen zur ``PATH``-Umgebungsvariablen + + Fügen Sie ``%JAVA_HOME%\bin`` zur ``PATH``-Umgebungsvariablen hinzu. + +.. tip:: + + So konfigurieren Sie Umgebungsvariablen: + + 1. Öffnen Sie „Einstellungen" über das „Start"-Menü + 2. Klicken Sie auf „System" → „Info" → „Erweiterte Systemeinstellungen" + 3. Klicken Sie auf die Schaltfläche „Umgebungsvariablen" + 4. Konfigurieren Sie in „Systemvariablen" oder „Benutzervariablen" + +Schritt 1: Installation von OpenSearch +======================================= + +.. tip:: + + ``bin\fess-setup``, das |Fess| beiliegt, führt die folgenden Schritte in einem Befehl aus. Es + lädt OpenSearch herunter und entpackt es nach ``opensearch\`` im |Fess|-Verzeichnis, installiert + die benötigten Plugins und fügt ``configsync.config_path`` und ``plugins.security.disabled: true`` + zu dessen ``config\opensearch.yml`` hinzu. Entpacken Sie zuerst das ZIP von |Fess|, wie in + Schritt 2 beschrieben. + + :: + + > cd C:\fess-15.10.0 + > bin\fess-setup install opensearch + + ``bin\fess.in.bat`` findet ein so installiertes OpenSearch und übergibt dessen Verzeichnis + ``config\dictionary`` an |Fess|, sodass „Konfiguration von Fess" in Schritt 2 keine Änderung + erfordert, solange OpenSearch auf demselben Host läuft. Der Befehl gibt die hinzugefügten + Einstellungen aus und ob ``bin\fess.in.bat`` die Installation findet. Lesen Sie die Warnung unter + „Konfiguration von OpenSearch", bevor OpenSearch auf einer anderen Adresse als ``localhost`` + lauscht. + + Folgen Sie den Schritten unten, um sie einzeln durchzugehen oder ein vorhandenes OpenSearch + zu verwenden. Um nur die Plugins in ein vorhandenes OpenSearch zu installieren, verwenden Sie + ``bin\fess-setup install opensearch-plugins --opensearch-home C:\opensearch-3.9.0``. + Alle Befehle finden Sie unter :doc:`fess-setup`. + +Download von OpenSearch +----------------------- + +1. Laden Sie das ZIP-Paket für Windows von `Download OpenSearch `__ herunter. + +2. Entpacken Sie die heruntergeladene ZIP-Datei in ein beliebiges Verzeichnis. + + Beispiel:: + + C:\opensearch-3.9.0 + + .. note:: + + Es wird empfohlen, ein Verzeichnis ohne japanische Zeichen oder Leerzeichen im Pfad zu wählen. + +Installation der OpenSearch-Plugins +------------------------------------ + +Öffnen Sie die Eingabeaufforderung **mit Administratorrechten** und führen Sie folgende Befehle aus. + +:: + + C:\> cd C:\opensearch-3.9.0 + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + +.. important:: + + Die Plugin-Version muss mit der OpenSearch-Version übereinstimmen. + Im obigen Beispiel sind alle auf 3.9.0 gesetzt. + + Die vier Plugins für |Fess| werden auf maven.codelibs.org veröffentlicht und daher per URL + installiert. Die Form ``groupId:artifactId:version`` von ``opensearch-plugin install`` sucht nur + in Maven Central. + +Konfiguration von OpenSearch +----------------------------- + +Öffnen Sie ``config\opensearch.yml`` mit einem Texteditor und fügen Sie folgende Einstellungen hinzu. + +:: + + # Pfad für Konfigurationssynchronisation (als absoluter Pfad angeben) + configsync.config_path: C:/opensearch-3.9.0/config/dictionary/ + + # Deaktivierung des Sicherheits-Plugins (nur Entwicklungsumgebung) + plugins.security.disabled: true + +.. warning:: + + **Wichtiger Sicherheitshinweis** + + ``plugins.security.disabled: true`` sollte nur in Entwicklungs- oder Testumgebungen verwendet werden. + In Produktionsumgebungen aktivieren Sie bitte das Sicherheits-Plugin von OpenSearch und konfigurieren Sie entsprechende Authentifizierungs- und Autorisierungseinstellungen. + Weitere Informationen finden Sie unter :doc:`security`. + +.. note:: + + Bei Windows verwenden Sie ``/`` anstelle von ``\`` als Pfadtrennzeichen. + Schreiben Sie ``C:/opensearch-3.9.0/config/dictionary/`` statt ``C:\opensearch-3.9.0\config\dictionary\``. + +.. important:: + + Geben Sie für ``configsync.config_path`` ein Verzeichnis unterhalb des OpenSearch-Konfigurationsverzeichnisses an (in diesem Beispiel ``C:/opensearch-3.9.0/config/``). + Ab OpenSearch 3.8.0 wird die Erstellung eines Index verweigert, wenn sich Wörterbuchdateien außerhalb des Konfigurationsverzeichnisses befinden. + Wenn Sie ein Verzeichnis außerhalb des Konfigurationsverzeichnisses angeben, z. B. ``C:/opensearch-3.9.0/data/config/``, kann |Fess| seine Indizes nicht erstellen und startet nicht. + +.. tip:: + + Weitere empfohlene Einstellungen:: + + cluster.name: fess-cluster + node.name: fess-node-1 + network.host: 0.0.0.0 + discovery.type: single-node + +.. tip:: + + Der Heap-Speicher von OpenSearch wird in ``config\jvm.options`` über ``-Xms`` und ``-Xmx`` konfiguriert. + Es wird empfohlen, beide Werte gleich zu setzen und dabei weniger als die Hälfte des verfügbaren physischen Speichers sowie weniger als 32 GB zu verwenden. + +Schritt 2: Installation von Fess +================================= + +Download von Fess +----------------- + +1. Laden Sie das ZIP-Paket für Windows von der `Download-Site `__ herunter. + +2. Entpacken Sie die heruntergeladene ZIP-Datei in ein beliebiges Verzeichnis. + + Beispiel:: + + C:\fess-15.10.0 + + .. note:: + + Es wird empfohlen, ein Verzeichnis ohne japanische Zeichen oder Leerzeichen im Pfad zu wählen. + +Konfiguration von Fess +----------------------- + +Bei einem OpenSearch, das ``bin\fess-setup install opensearch`` nach ``opensearch\`` im +|Fess|-Verzeichnis installiert hat und das auf demselben Host läuft, ist hier nichts zu +konfigurieren. Andernfalls, zum Beispiel wenn OpenSearch mit den obigen Schritten installiert wurde, +auf einem anderen Host läuft oder ``opensearch\`` mehr als ein von ``bin\fess-setup`` installiertes +OpenSearch enthält, konfigurieren Sie die Verbindung wie folgt. + +Öffnen Sie ``bin\fess.in.bat`` mit einem Texteditor. +Am Ende dieser Datei sind Einstellungen für die Verbindung zu einem externen OpenSearch-Cluster bereits als auskommentierte Vorlage vorhanden. + +Zustand vor der Änderung (Standardzustand):: + + REM External opensearch cluster + REM set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200 + REM set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=C:/opensearch/config/dictionary + +Entfernen Sie das ``REM `` am Anfang der unteren zwei Zeilen, um den Kommentar aufzuheben, und ändern Sie den Wert von ``fess.dictionary.path`` auf den Konfigurationssynchronisationspfad von OpenSearch. + +Zustand nach der Änderung:: + + REM External opensearch cluster + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200 + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=C:/opensearch-3.9.0/config/dictionary/ + +.. note:: + + - Setzen Sie ``fess.dictionary.path`` auf denselben Pfad, der in ``opensearch.yml`` als ``configsync.config_path`` angegeben ist. + - Wenn OpenSearch auf einem anderen Host ausgeführt wird, ändern Sie den Hostnamen oder die IP-Adresse in ``fess.search_engine.http_address`` entsprechend. + - Verwenden Sie ``/`` als Pfadtrennzeichen. |Fess| fügt den Pfad in die Indexeinstellungen ein, wobei ein ``\`` verloren geht; ein mit ``\`` geschriebener Pfad wird daher nicht gefunden. + - Fügen Sie keine neuen ``set FESS_JAVA_OPTS=...``-Zeilen hinzu, sondern heben Sie die vorhandenen Kommentarzeilen auf und bearbeiten Sie diese. Die doppelte Angabe derselben Option kann zu unerwünschtem Verhalten führen. + +.. tip:: + + Um den Heap-Speicher von |Fess| anzupassen, bearbeiten Sie ``FESS_MIN_MEM`` (Standard: ``256m``) und ``FESS_MAX_MEM`` (Standard: ``1g``) in ``bin\fess.in.bat`` oder setzen Sie die Umgebungsvariable ``FESS_HEAP_SIZE``. + +Überprüfung der Installation +----------------------------- + +Überprüfen Sie, ob die Konfigurationsdateien korrekt bearbeitet wurden. + +In der Eingabeaufforderung:: + + C:\> findstr "fess.search_engine.http_address" C:\fess-15.10.0\bin\fess.in.bat + C:\> findstr "fess.dictionary.path" C:\fess-15.10.0\bin\fess.in.bat + +Schritt 3: Start +================ + +Die Startanleitung finden Sie unter :doc:`run`. + +Registrierung als Windows-Dienst (Optional) +============================================ + +Durch Registrierung von |Fess| als Windows-Dienst kann es beim Systemstart automatisch gestartet werden. + +|Fess| enthält das mitgelieferte Skript ``bin\service.bat`` zur Registrierung als Windows-Dienst. +Da dieses Skript Apache Commons Daemon (procrun) verwendet, ist kein zusätzliches Drittanbieter-Tool wie NSSM erforderlich. + +.. note:: + + Stellen Sie sicher, dass die Umgebungsvariable ``JAVA_HOME`` korrekt gesetzt ist, bevor Sie ``service.bat`` ausführen. + +Registrierung des |Fess|-Dienstes +----------------------------------- + +Öffnen Sie die Eingabeaufforderung **mit Administratorrechten** und führen Sie folgende Befehle aus. + +1. Dienst registrieren:: + + C:\> cd C:\fess-15.10.0 + C:\fess-15.10.0> bin\service.bat install + + Standardmäßig wird der Dienst in 64-Bit-Umgebungen als ``fess-service-x64`` und in 32-Bit-Umgebungen als ``fess-service-x86`` registriert. + Um die Dienst-ID explizit anzugeben, übergeben Sie sie als Argument: ``bin\service.bat install ``. + +2. Dienst starten und stoppen:: + + C:\fess-15.10.0> bin\service.bat start + C:\fess-15.10.0> bin\service.bat stop + +3. Dienstkonfiguration anzeigen und ändern (GUI):: + + C:\fess-15.10.0> bin\service.bat manager + +4. Dienst entfernen:: + + C:\fess-15.10.0> bin\service.bat remove + +.. note:: + + - Da ``service.bat`` intern ``bin\fess.in.bat`` lädt, werden die im Abschnitt „Konfiguration von Fess" vorgenommenen Verbindungseinstellungen für den externen OpenSearch-Cluster auch für den Dienst übernommen. + - Der Standardstarttyp ist „Manuell". Um den Dienst beim Systemstart automatisch zu starten, setzen Sie die Umgebungsvariable ``FESS_START_TYPE`` vor der Registrierung auf ``auto``, oder ändern Sie den Starttyp nach der Registrierung im Dienstverwaltungs-Tool (``services.msc``) auf „Automatisch". + - Mit ``service.bat`` kann nur der |Fess|-Dienst registriert werden. Informationen zur Registrierung von OpenSearch als Dienst finden Sie in der OpenSearch-Dokumentation. + +Firewall-Konfiguration +====================== + +Öffnen Sie die erforderlichen Ports in der Windows Defender Firewall. + +1. Öffnen Sie „Systemsteuerung" → „Windows Defender Firewall" → „Erweiterte Einstellungen" + +2. Erstellen Sie eine neue Regel unter „Eingehende Regeln" + + - Regeltyp: Port + - Protokoll und Ports: TCP, 8080 + - Aktion: Verbindung zulassen + - Name: Fess Web Interface + +Oder führen Sie in PowerShell aus:: + + PS C:\> New-NetFirewallRule -DisplayName "Fess Web Interface" -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow + +Fehlerbehebung +============== + +Portnummer-Konflikt +------------------- + +Wenn Port 8080 oder 9200 bereits verwendet wird, können Sie dies mit folgendem Befehl überprüfen:: + + C:\> netstat -ano | findstr :8080 + C:\> netstat -ano | findstr :9200 + +Ändern Sie die verwendete Portnummer oder stoppen Sie den konfliktverursachenden Prozess. + +Pfadlängenbeschränkung +---------------------- + +Windows hat eine Pfadlängenbeschränkung. Es wird empfohlen, in einem möglichst kurzen Pfad zu installieren. + +Beispiel:: + + C:\opensearch (empfohlen) + C:\Program Files\opensearch-3.9.0 (nicht empfohlen - Pfad zu lang) + +Java wird nicht erkannt +----------------------- + +Wenn der Befehl ``java -version`` einen Fehler anzeigt: + +1. Überprüfen Sie, ob die ``JAVA_HOME``-Umgebungsvariable korrekt gesetzt ist +2. Überprüfen Sie, ob ``%JAVA_HOME%\bin`` in der ``PATH``-Umgebungsvariablen enthalten ist +3. Starten Sie die Eingabeaufforderung neu, um die Einstellungen zu übernehmen + +Nächste Schritte +================ + +Nach Abschluss der Installation lesen Sie bitte folgende Dokumentation: + +- :doc:`run` - Start und Ersteinrichtung von |Fess| +- :doc:`security` - Sicherheitseinstellungen für Produktionsumgebungen +- :doc:`troubleshooting` - Fehlerbehebung + +Häufig gestellte Fragen +======================= + +F: Wird der Betrieb auf Windows Server empfohlen? +-------------------------------------------------- + +A: Ja, der Betrieb auf Windows Server ist möglich. +Bei Betrieb auf Windows Server sollten Sie als Windows-Dienst registrieren und entsprechende Überwachung einrichten. + +F: Was ist der Unterschied zwischen 64-Bit- und 32-Bit-Version? +---------------------------------------------------------------- + +A: |Fess| und OpenSearch unterstützen nur die 64-Bit-Version. +Sie funktionieren nicht auf 32-Bit-Windows. + +F: Was tun bei japanischen Zeichen im Pfad? +-------------------------------------------- + +A: Installieren Sie bitte nach Möglichkeit in einem Pfad ohne japanische Zeichen oder Leerzeichen. +Wenn Sie unbedingt japanische Pfade verwenden müssen, müssen Pfade in den Konfigurationsdateien entsprechend maskiert werden. diff --git a/de/15.10/install/install.rst b/de/15.10/install/install.rst new file mode 100644 index 000000000..951a40c1b --- /dev/null +++ b/de/15.10/install/install.rst @@ -0,0 +1,247 @@ +================================ +Auswahl der Installationsmethode +================================ + +Diese Seite beschreibt eine Übersicht über die Installationsmethoden von |Fess|. +Bitte wählen Sie die für Ihre Umgebung geeignete Installationsmethode. + +.. note:: + + |Fess| enthält keine Suchmaschine. Jede der folgenden Installationsmethoden + benötigt einen separaten OpenSearch-Server. + +Überprüfung der Voraussetzungen +================================ + +Überprüfen Sie vor Beginn der Installation die Systemanforderungen. + +Weitere Informationen finden Sie unter :doc:`prerequisites`. + +Vergleich der Installationsmethoden +==================================== + +|Fess| kann mit folgenden Methoden installiert werden. Wählen Sie je nach Umgebung und Verwendungszweck die passende Methode. + +.. list-table:: + :header-rows: 1 + :widths: 15 25 30 30 + + * - Methode + - Ziel-OS + - Empfohlene Verwendung + - Detaillierte Dokumentation + * - Docker + - Linux, Windows, macOS + - Entwicklungs-/Evaluierungsumgebung, schnelle Einrichtung + - :doc:`install-docker` + * - ZIP + - Linux, macOS + - Umgebungen, die Anpassungen erfordern + - :doc:`install-linux` + * - RPM + - RHEL, CentOS, Fedora + - Produktionsumgebung (RPM-basiert) + - :doc:`install-linux` + * - DEB + - Debian, Ubuntu + - Produktionsumgebung (DEB-basiert) + - :doc:`install-linux` + * - ZIP + - Windows + - Entwicklung/Produktion in Windows-Umgebung + - :doc:`install-windows` + +Merkmale der einzelnen Installationsmethoden +============================================= + +Docker-Version +-------------- + +**Vorteile:** + +- Schnellste Einrichtung möglich +- Keine Verwaltung von Abhängigkeiten erforderlich +- Ideal für Entwicklungsumgebungen +- Einfaches Starten und Stoppen von Containern + +**Nachteile:** + +- Docker-Kenntnisse erforderlich + +**Empfohlene Umgebung:** Entwicklungs-, Evaluierungs-, POC- und Produktionsumgebungen + +Details: :doc:`install-docker` + +Linux-Paketversion (ZIP/RPM/DEB) +----------------------------------- + +**Vorteile:** + +- Hohe Leistung in nativer Umgebung +- Als Systemdienst verwaltbar (RPM/DEB) +- Detaillierte Anpassungen möglich + +**Nachteile:** + +- Manuelle Installation von Java und OpenSearch erforderlich +- Konfigurationsaufwand + +**Empfohlene Umgebung:** Produktionsumgebung (für die Verwaltung als Systemdienst wird RPM/DEB empfohlen), Umgebungen mit Anpassungsbedarf + +Details: :doc:`install-linux` + +Windows-Version (ZIP) +--------------------- + +**Vorteile:** + +- Läuft in nativer Windows-Umgebung +- Kein Installer erforderlich + +**Nachteile:** + +- Manuelle Installation von Java und OpenSearch erforderlich +- Konfigurationsaufwand + +**Empfohlene Umgebung:** Entwicklung/Evaluierung in Windows-Umgebung, Produktionsbetrieb auf Windows Server + +Details: :doc:`install-windows` + +Grundlegender Installationsablauf +================================== + +Der grundlegende Ablauf ist bei allen Installationsmethoden gleich. + +1. **Überprüfung der Systemanforderungen** + + Siehe :doc:`prerequisites` und überprüfen Sie, ob die Systemanforderungen erfüllt sind. + +2. **Software-Download** + + Laden Sie |Fess| von der `Download-Site `__ herunter. + + Bei der Docker-Version laden Sie die Docker Compose-Dateien herunter. + +3. **Einrichtung von OpenSearch** + + Bei anderen Versionen als der Docker-Version muss OpenSearch separat eingerichtet werden. + + - Installation von OpenSearch 3.9.0 + - Installation der erforderlichen Plugins + - Bearbeitung der Konfigurationsdateien + +4. **Einrichtung von Fess** + + - Installation von Fess + - Bearbeitung der Konfigurationsdateien (Verbindungsinformationen zu OpenSearch usw.) + +5. **Start und Überprüfung** + + - Start des Dienstes + - Zugriff über den Browser und Funktionsprüfung + + Details finden Sie unter :doc:`run`. + +Erforderliche Komponenten +========================= + +Für den Betrieb von |Fess| sind folgende Komponenten erforderlich. + +Fess-Hauptsystem +---------------- + +Das Volltext-Suchsystem selbst. Es bietet Funktionen wie Weboberfläche, Crawler und Indexer. + +OpenSearch +---------- + +Verwendet OpenSearch als Suchmaschine. + +- **Unterstützte Version**: OpenSearch 3.9.0 +- **Erforderliche Plugins**: + + - opensearch-analysis-fess + - opensearch-analysis-extension + - opensearch-minhash + - opensearch-configsync + +.. important:: + + Die Version von OpenSearch und die Version der Plugins müssen übereinstimmen. + Versionsunterschiede können zu Startfehlern oder unerwartetem Verhalten führen. + +``bin/fess-setup install opensearch`` richtet OpenSearch mit diesen Plugins unter Linux und Windows ein. Einzelheiten, auch zu macOS, wo OpenSearch auf andere Weise installiert werden muss, siehe :doc:`install-linux`; alle Befehle siehe :doc:`fess-setup`. + +.. note:: + + Wenn Sie ein OpenSearch verwenden, in dem sich diese Plugins nicht installieren lassen, etwa einen verwalteten Dienst, setzen Sie ``search_engine.type`` auf ``vanilla`` (ab |Fess| 15.10). Einige Funktionen wie die Wörterbuchverwaltung stehen dann nicht zur Verfügung. Siehe :doc:`../config/search-engine-type`. + +Java (außer Docker-Version) +---------------------------- + +Für die ZIP/RPM/DEB-Version ist Java 21 oder höher erforderlich. + +- Empfohlen: `Eclipse Temurin `__ +- OpenJDK 21 oder höher kann ebenfalls verwendet werden + +.. note:: + + Bei der Docker-Version ist Java im Docker-Image enthalten und muss nicht separat installiert werden. + +Nächste Schritte +================ + +Überprüfen Sie die Systemanforderungen und wählen Sie die geeignete Installationsmethode. + +1. :doc:`prerequisites` - Überprüfung der Systemanforderungen +2. Auswahl der Installationsmethode: + + - :doc:`install-docker` - Installation mit Docker + - :doc:`install-linux` - Installation unter Linux + - :doc:`install-windows` - Installation unter Windows + +3. :doc:`run` - Start und Ersteinrichtung von |Fess| +4. :doc:`security` - Sicherheitseinstellungen (für Produktionsumgebungen) + +Häufig gestellte Fragen +======================= + +F: Ist OpenSearch erforderlich? +-------------------------------- + +A: Ja, es ist erforderlich. |Fess| verwendet OpenSearch als Suchmaschine. +Bei der Docker-Version wird es automatisch eingerichtet, bei anderen Methoden muss es manuell installiert werden. + +F: Ist ein Upgrade von früheren Versionen möglich? +--------------------------------------------------- + +A: Ja, das ist möglich. Weitere Informationen finden Sie unter :doc:`upgrade`. + +F: Kann das System auf mehreren Servern konfiguriert werden? +------------------------------------------------------------- + +A: Ja, das ist möglich. Fess und OpenSearch können auf separaten Servern ausgeführt werden. +Durch Konfiguration von OpenSearch als Cluster sind hohe Verfügbarkeit und Leistungsverbesserungen möglich. + +Downloads +========= + +|Fess| und zugehörige Komponenten können von folgenden Quellen heruntergeladen werden: + +- **Fess**: `Download-Site `__ +- **OpenSearch**: `Download OpenSearch `__ +- **Java (Adoptium)**: `Adoptium `__ +- **Docker**: `Get Docker `__ + +Versionsinformationen +===================== + +Diese Dokumentation bezieht sich auf folgende Versionen: + +- **Fess**: 15.10.0 +- **OpenSearch**: 3.9.0 +- **Java**: 21 oder höher +- **Docker**: 20.10 oder höher +- **Docker Compose**: 2.0 oder höher + +Dokumentation für frühere Versionen finden Sie in der jeweiligen Versionsdokumentation. diff --git a/de/15.10/install/intro.rst b/de/15.10/install/intro.rst new file mode 100644 index 000000000..cdd867af2 --- /dev/null +++ b/de/15.10/install/intro.rst @@ -0,0 +1,70 @@ +============================== +Einführung in die Installation +============================== + +Über dieses Dokument +==================== + +Diese Installationsanleitung beschreibt die Installation, den Start, das Upgrade und die Deinstallation von |Fess|. +Bitte wählen Sie die für Ihre Umgebung geeignete Installationsmethode. + +Zielgruppe +========== + +Dieses Dokument richtet sich an Benutzer, die für die Installation und Deinstallation von |Fess| verantwortlich sind. + +Vor dem Lesen +============= + +Dieses Dokument beschreibt die Installationsmethoden für |Fess|. Folgende Kenntnisse werden vorausgesetzt: + +- Grundkenntnisse in der Serververwaltung +- Bedienung der Kommandozeile unter Linux oder Windows +- Grundlegende Netzwerk- und Firewall-Konfiguration +- Grundkenntnisse in Docker (bei Verwendung der Docker-Version) + +Dokumentstruktur +================ + +Diese Installationsanleitung besteht aus folgenden Abschnitten: + +- **Systemanforderungen**: Hardware- und Softwareanforderungen für den Betrieb von |Fess| +- **Installation**: Installationsanweisungen für verschiedene Plattformen + + - Auswahl der Installationsmethode (Übersicht und Vergleich) + - Installation für Linux (ZIP/RPM/DEB) + - Installation für Windows (ZIP) + - Installation für Docker + +- **Start, Stopp und Ersteinrichtung**: Start, Stopp und Ersteinrichtung des |Fess|-Servers +- **Sicherheitseinstellungen**: Empfohlene Sicherheitseinstellungen für Produktionsumgebungen +- **Upgrade**: Upgrade-Verfahren von früheren Versionen auf die neueste Version +- **Deinstallation**: Vollständige Deinstallation von |Fess| +- **Fehlerbehebung**: Häufige Probleme und Lösungen + +Online-Zugang +============= + +Für Downloads, professionelle Dienste, Support und weitere Entwicklerinformationen besuchen Sie bitte: + +- Projekt-Website: `https://fess.codelibs.org/ `__ + +Kontakt für technischen Support +================================ + +Bei technischen Fragen oder Problemen zu diesem Produkt wenden Sie sich bitte an: + +- Issues: `https://github.com/codelibs/fess/issues `__ + +Kommerzieller Support +--------------------- + +Wenn Sie kommerziellen Support wie technische Unterstützung oder Wartung für dieses Produkt benötigen, wenden Sie sich bitte an `N2SM, Inc. `__. + +Kommentare und Vorschläge +========================== + +Wenn Sie Probleme oder Verbesserungsvorschläge haben, senden Sie diese bitte über folgende Kanäle: + +- Produktprobleme: `https://github.com/codelibs/fess/issues `__ +- Dokumentationsprobleme: `https://github.com/codelibs/fess-docs/issues `__ diff --git a/de/15.10/install/prerequisites.rst b/de/15.10/install/prerequisites.rst new file mode 100644 index 000000000..a434c342a --- /dev/null +++ b/de/15.10/install/prerequisites.rst @@ -0,0 +1,185 @@ +================== +Systemanforderungen +================== + +Auf dieser Seite werden die Hardware- und Softwareanforderungen beschrieben, die für den Betrieb von |Fess| erforderlich sind. + +Hardwareanforderungen +===================== + +Mindestanforderungen +-------------------- + +Die folgenden Mindestanforderungen gelten für Evaluierungs- und Entwicklungsumgebungen: + +- CPU: 2 Kerne oder mehr +- Arbeitsspeicher: 4 GB oder mehr +- Festplattenkapazität: 10 GB oder mehr freier Speicherplatz + +Empfohlene Anforderungen +------------------------ + +Für Produktionsumgebungen werden folgende Spezifikationen empfohlen: + +- CPU: 4 Kerne oder mehr +- Arbeitsspeicher: 8 GB oder mehr (abhängig von der Indexgröße) +- Festplattenkapazität: + + - Systembereich: 20 GB oder mehr + - Datenbereich: Mindestens das Dreifache der Indexgröße (einschließlich Replikate) + +- Netzwerk: 1 Gbps oder mehr + +.. note:: + + Wenn die Indexgröße zunimmt oder häufige Crawls durchgeführt werden, + sollten Arbeitsspeicher und Festplattenkapazität entsprechend erhöht werden. + +Softwareanforderungen +===================== + +Betriebssystem +-------------- + +|Fess| läuft auf folgenden Betriebssystemen: + +**Linux** + +- Red Hat Enterprise Linux 8 oder höher +- CentOS 8 oder höher +- Ubuntu 20.04 LTS oder höher +- Debian 11 oder höher +- Andere Linux-Distributionen (Umgebungen, in denen Java 21 ausgeführt werden kann) + +**Windows** + +- Windows Server 2019 oder höher +- Windows 10 oder höher + +**Sonstiges** + +- macOS 11 (Big Sur) oder höher (nur für Entwicklungsumgebungen empfohlen; für macOS gibt es keine offizielle OpenSearch-Distribution, verwenden Sie Homebrew oder Docker) +- Umgebungen, in denen Docker ausgeführt werden kann + +Erforderliche Software +---------------------- + +Je nach Installationsmethode wird folgende Software benötigt: + +ZIP/RPM/DEB Version +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- **Java 21**: `Eclipse Temurin `__ wird empfohlen + + - OpenJDK 21 oder höher + - Eclipse Temurin 21 oder höher + +- **OpenSearch 3.9.0**: Erforderlich. Mit einer älteren Version als OpenSearch 3 startet |Fess| nicht + + - Unterstützte Version: OpenSearch 3.9.0 + - Bei anderen Versionen ist auf Plugin-Kompatibilität zu achten + +Docker Version +~~~~~~~~~~~~~~ + +- **Docker**: 20.10 oder höher +- **Docker Compose**: 2.0 oder höher + +Netzwerkanforderungen +===================== + +Erforderliche Ports +------------------- + +Die Hauptports, die von |Fess| verwendet werden, sind wie folgt: + +.. list-table:: + :header-rows: 1 + :widths: 15 15 50 + + * - Port + - Protokoll + - Verwendungszweck + * - 8080 + - HTTP + - |Fess| Weboberfläche (Such- und Verwaltungsseite) + * - 9200 + - HTTP + - OpenSearch HTTP API (Kommunikation von |Fess| zu OpenSearch) + * - 9300 + - TCP + - OpenSearch Transport-Kommunikation (bei Cluster-Konfiguration) + +.. warning:: + + In Produktionsumgebungen wird dringend empfohlen, den direkten Zugriff auf die Ports 9200 und 9300 von außen zu beschränken. + Diese Ports sollten nur für die interne Kommunikation zwischen |Fess| und OpenSearch verwendet werden. + +Firewall-Konfiguration +---------------------- + +Wenn |Fess| von außen zugänglich sein soll, muss Port 8080 geöffnet werden. + +**Linux (mit firewalld)** + +:: + + $ sudo firewall-cmd --permanent --add-port=8080/tcp + $ sudo firewall-cmd --reload + +**Linux (mit iptables)** + +:: + + $ sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT + $ sudo iptables-save + +Browseranforderungen +==================== + +Für die Verwaltungs- und Suchoberfläche von |Fess| werden folgende Browser empfohlen: + +- Google Chrome (neueste Version) +- Mozilla Firefox (neueste Version) +- Microsoft Edge (neueste Version) +- Safari (neueste Version) + +.. note:: + + Internet Explorer wird nicht unterstützt. + +Checkliste für Voraussetzungen +=============================== + +Überprüfen Sie vor der Installation folgende Punkte: + +.. list-table:: + :header-rows: 1 + :widths: 50 50 + + * - Prüfpunkt + - Status + * - Werden die Hardwareanforderungen erfüllt? + - □ + * - Ist Java 21 installiert? (außer Docker-Version) + - □ + * - Ist Docker installiert? (Docker-Version) + - □ + * - Sind die erforderlichen Ports verfügbar? + - □ + * - Ist die Firewall-Konfiguration korrekt? + - □ + * - Ist ausreichend Festplattenkapazität vorhanden? + - □ + * - Funktioniert die Netzwerkverbindung? (beim Crawlen externer Sites) + - □ + +Nächste Schritte +================ + +Nachdem Sie die Systemanforderungen überprüft haben, fahren Sie mit den Installationsanweisungen für Ihre Umgebung fort: + +- :doc:`install-linux` - Installation für Linux (ZIP/RPM/DEB) +- :doc:`install-windows` - Installation für Windows (ZIP) +- :doc:`install-docker` - Installation für Docker +- :doc:`install` - Übersicht über Installationsmethoden diff --git a/de/15.10/install/run.rst b/de/15.10/install/run.rst new file mode 100644 index 000000000..b905e87e9 --- /dev/null +++ b/de/15.10/install/run.rst @@ -0,0 +1,517 @@ +================================ +Start, Stopp, Erstkonfiguration +================================ + +Diese Seite beschreibt die Verfahren zum Starten, Stoppen und zur Ersteinrichtung des |Fess|-Servers. + +.. important:: + + Starten Sie vor dem Start von |Fess| unbedingt OpenSearch. + Wenn OpenSearch nicht läuft, funktioniert |Fess| nicht ordnungsgemäß. + +Startmethoden +============= + +Die Startverfahren unterscheiden sich je nach Installationsmethode. + +ZIP-Version +-------------- + +Start von OpenSearch +~~~~~~~~~~~~~~~~~~~~ + +:: + + $ cd /path/to/opensearch-3.9.0 + $ ./bin/opensearch + +Für Hintergrundstart:: + + $ ./bin/opensearch -d + +.. note:: + + ``bin/fess-setup install opensearch`` legt OpenSearch in ``opensearch/opensearch-3.9.0`` im + |Fess|-Verzeichnis ab. + +.. important:: + + Starten Sie OpenSearch als normaler Benutzer. Als ``root`` verweigert es den Start und beendet + sich mit ``can not run opensearch as root``. Der verweigerte Start hinterlässt dennoch Dateien wie + ``config/opensearch.keystore`` im Besitz von ``root``, und der nächste Start als normaler + Benutzer schlägt dann mit ``AccessDeniedException`` fehl. Übertragen Sie das + OpenSearch-Verzeichnis vor dem nächsten Start wieder an diesen Benutzer, zum Beispiel:: + + $ sudo chown -R /path/to/opensearch-3.9.0 + +Start von Fess +~~~~~~~~~~~~~~ + +:: + + $ cd /path/to/fess-15.10.0 + $ ./bin/fess + +Für Hintergrundstart:: + + $ ./bin/fess -d + +.. note:: + + Der Start kann einige Minuten dauern. + Der Startstatus kann in den Protokolldateien im Verzeichnis ``logs/`` überprüft werden: ``fess.log`` + enthält die Meldungen von |Fess| selbst, ``server_0.log`` die des eingebetteten Tomcat (einschließlich + der Startabschlussmeldung). + +ZIP-Version (Windows) +--------------------- + +Start von OpenSearch +~~~~~~~~~~~~~~~~~~~~ + +1. Öffnen Sie das OpenSearch-Installationsverzeichnis +2. Doppelklicken Sie auf ``opensearch.bat`` im ``bin``-Ordner + +Oder von der Eingabeaufforderung:: + + C:\> cd C:\opensearch-3.9.0 + C:\opensearch-3.9.0> bin\opensearch.bat + +Start von Fess +~~~~~~~~~~~~~~ + +1. Öffnen Sie das Fess-Installationsverzeichnis +2. Doppelklicken Sie auf ``fess.bat`` im ``bin``-Ordner + +Oder von der Eingabeaufforderung:: + + C:\> cd C:\fess-15.10.0 + C:\fess-15.10.0> bin\fess.bat + +RPM/DEB-Version (chkconfig) +---------------------------- + +Start von OpenSearch:: + + $ sudo service opensearch start + +Start von Fess:: + + $ sudo service fess start + +Überprüfung des Startstatus:: + + $ sudo service fess status + +RPM/DEB-Version (systemd) +-------------------------- + +Start von OpenSearch:: + + $ sudo systemctl start opensearch.service + +Start von Fess:: + + $ sudo systemctl start fess.service + +Überprüfung des Startstatus:: + + $ sudo systemctl status fess.service + +Aktivierung des automatischen Starts:: + + $ sudo systemctl enable opensearch.service + $ sudo systemctl enable fess.service + +Docker-Version +-------------- + +.. note:: + + ``compose.yaml`` und ``compose-opensearch3.yaml`` sind nicht im Lieferumfang von |Fess| selbst enthalten. Sie werden vom docker-fess-Projekt (https://github.com/codelibs/docker-fess) bereitgestellt. Laden Sie das Repository herunter und führen Sie die folgenden Befehle im Verzeichnis ``compose`` aus. + +Start mit Docker Compose:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +Überprüfung des Startstatus:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps + +Überprüfung der Protokolle:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01 + +Überprüfung des Starts +====================== + +Überprüfen Sie, dass |Fess| erfolgreich gestartet wurde. + +Gesundheitsprüfung +------------------ + +Greifen Sie über den Browser oder mit dem curl-Befehl auf folgende URL zu:: + + http://localhost:8080/ + +Bei erfolgreichem Start wird die Fess-Suchseite angezeigt. + +Überprüfung über die Kommandozeile:: + + $ curl -I http://localhost:8080/ + +Wenn ``HTTP/1.1 200 OK`` zurückgegeben wird, ist der Start erfolgreich. + +Überprüfung der Protokolle +--------------------------- + +Überprüfen Sie die Startprotokolle und stellen Sie sicher, dass keine Fehler vorliegen. + +ZIP-Version:: + + $ tail -f /path/to/fess-15.10.0/logs/fess.log + +RPM/DEB-Version:: + + $ sudo tail -f /var/log/fess/fess.log + +Oder mit journalctl:: + + $ sudo journalctl -u fess.service -f + +Docker-Version:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01 + +.. tip:: + + Wenn der Start erfolgreich abgeschlossen wurde, wird eine Startabschlussmeldung wie die folgende in die Datei ``server_0.log`` im Protokollverzeichnis geschrieben (``logs/`` der ZIP-Version, ``/var/log/fess/`` der RPM/DEB-Version). Sie erscheint weder auf der Konsole noch in ``fess.log``: + + :: + + ...Booting the Tomcat: port=8080 contextPath= + ... + Boot successful: url -> http://localhost:8080 + +Zugriff über den Browser +========================= + +Greifen Sie auf folgende URLs zu und überprüfen Sie die Weboberfläche. + +Suchseite +--------- + +**URL**: http://localhost:8080/ + +Die Fess-Suchseite wird angezeigt. Im Ausgangszustand werden keine Suchergebnisse angezeigt, da noch keine Crawl-Konfiguration vorgenommen wurde. + +Die Suchseite ist ``bootstrap``, das mit |Fess| mitgelieferte statische Theme. Um ihr Aussehen zu +ändern, installieren Sie ein anderes Theme über „System" → „Theme" in der Verwaltungsseite oder mit +``bin/fess-setup install theme `` (siehe :doc:`fess-setup`), oder kopieren Sie das mitgelieferte +Theme und ändern Sie die Kopie (siehe :ref:`theme-customize-bundled`). + +Verwaltungsseite +---------------- + +**URL**: http://localhost:8080/admin + +Standard-Administratorkonto: + +- **Benutzername**: ``admin`` +- **Passwort**: ``admin`` + +.. warning:: + + **Wichtiger Sicherheitshinweis** + + Ändern Sie unbedingt das Standardpasswort. + Besonders in Produktionsumgebungen wird dringend empfohlen, das Passwort unmittelbar nach der ersten Anmeldung zu ändern. + +Erstkonfiguration +================= + +Nach Anmeldung in der Verwaltungsseite führen Sie folgende Erstkonfigurationen durch. + +Schritt 1: Änderung des Administratorpassworts +----------------------------------------------- + +1. Anmeldung in der Verwaltungsseite (http://localhost:8080/admin) +2. Klicken Sie im linken Menü auf „Benutzer" → „Benutzer" +3. Klicken Sie auf den Benutzer ``admin`` +4. Geben Sie ein neues Passwort in das Feld [Passwort] ein +5. Geben Sie dasselbe Passwort erneut in das Feld [Passwort (bestätigen)] ein +6. Klicken Sie auf die Schaltfläche [Aktualisieren] + +.. important:: + + Es wird empfohlen, dass Passwörter folgende Bedingungen erfüllen: + + - 8 Zeichen oder mehr (die erforderliche Mindestlänge, festgelegt durch ``password.min.length``) + - Kombination aus Groß- und Kleinbuchstaben, Zahlen und Sonderzeichen + - Nicht leicht zu erraten + + Standardmäßig wird nur die Mindestlänge (8 Zeichen) geprüft; eine Kombination aus verschiedenen Zeichentypen wird nicht erzwungen. Anforderungen an Zeichentypen können mit Einstellungen wie ``password.require.uppercase`` aktiviert werden. + +Schritt 2: Erstellung der Crawl-Konfiguration +---------------------------------------------- + +Erstellen Sie eine Konfiguration zum Crawlen der zu durchsuchenden Websites oder Dateisysteme. + +1. Klicken Sie im linken Menü auf „Crawler" → „Web" +2. Klicken Sie auf die Schaltfläche „Neu erstellen" +3. Geben Sie die erforderlichen Informationen ein: + + - **Name**: Name der Crawl-Konfiguration (z.B.: Firmen-Website) + - **URL**: Ziel-URL für das Crawling (z.B.: https://www.example.com/). Um mehrere URLs anzugeben, geben Sie eine URL pro Zeile ein + - **Maximale Zugriffe**: Maximale Anzahl der zu crawlenden Dokumente (optional) + - **Intervall**: Wartezeit zwischen den Zugriffen (Millisekunden; Standard: ``10000``) + + .. note:: + + Andere Felder (wie Benutzeragent, Anzahl der Threads und Tiefe) verwenden + ihre Standardwerte, wenn sie leer gelassen werden. + +4. Klicken Sie auf die Schaltfläche „Erstellen" + +Schritt 3: Ausführung des Crawls +--------------------------------- + +1. Klicken Sie im linken Menü auf [System] → [Scheduler] +2. Öffnen Sie den Job [Default Crawler] und klicken Sie auf die Schaltfläche „Jetzt starten" +3. Warten Sie, bis der Crawl abgeschlossen ist (Fortschritt kann im Dashboard überprüft werden) + +Schritt 4: Überprüfung der Suche +--------------------------------- + +1. Greifen Sie auf die Suchseite zu (http://localhost:8080/) +2. Geben Sie ein Suchwort ein +3. Überprüfen Sie, dass Suchergebnisse angezeigt werden + +.. note:: + + Das Crawlen kann Zeit in Anspruch nehmen. + Bei großen Websites kann es mehrere Stunden bis Tage dauern. + +Weitere empfohlene Einstellungen +================================= + +Bei Betrieb in Produktionsumgebungen sollten Sie auch folgende Einstellungen in Betracht ziehen. + +Haupteinstellungen über Umgebungsvariablen +------------------------------------------ + +Einstellungen wie Portnummer, JVM-Heap-Größe und die OpenSearch-Verbindungs-URL können über Umgebungsvariablen geändert werden. Bearbeiten Sie ``bin/fess.in.sh`` für die ZIP-Version, ``/etc/sysconfig/fess`` für die RPM-Version und ``/etc/default/fess`` für die DEB-Version. Nach Änderungen ist ein Neustart von |Fess| erforderlich. + +.. list-table:: + :widths: 30 25 45 + :header-rows: 1 + + * - Umgebungsvariable + - Standardwert + - Beschreibung + * - ``FESS_PORT`` + - ``8080`` + - Der HTTP-Port, auf dem |Fess| lauscht. + * - ``FESS_HEAP_SIZE`` + - (nicht gesetzt) + - JVM-Heap-Größe. Setzt denselben Wert für Minimum und Maximum. Wenn nicht gesetzt, werden mindestens ``256m`` und maximal ``2g`` verwendet (die Windows-ZIP-Version verwendet maximal ``1g``); die RPM/DEB-Version verwendet ``512m``. + * - ``SEARCH_ENGINE_HTTP_URL`` + - ``http://localhost:9200`` + - URL des OpenSearch, zu dem eine Verbindung hergestellt wird. Bei der ZIP-Version setzt ``bin/fess.in.sh`` diesen Wert standardmäßig. Exportieren Sie die Variable oder bearbeiten Sie ``bin/fess.in.sh``, wenn OpenSearch auf einem anderen Port oder Host läuft. Die RPM/DEB-Version setzt ihn in der Paketumgebungsdatei. + * - ``FESS_LOG_LEVEL`` + - ``warn`` + - Protokollniveau von |Fess|. + * - ``FESS_HEAP_NEWSIZE`` + - (nicht gesetzt) + - Größe der Young Generation des JVM-Heaps (``-Xmn``), z. B. ``256m``. Wenn nicht gesetzt, entscheidet die JVM. + * - ``FESS_TEMP_PATH`` + - ``temp`` im |Fess|-Verzeichnis (RPM/DEB-Version: ``/var/tmp/fess``) + - Verzeichnis für temporäre Dateien, einschließlich des Arbeitsverzeichnisses des eingebetteten Tomcat. Der Benutzer, unter dem |Fess| läuft, muss darin schreiben können. + * - ``FESS_CONF_PATH`` + - (nicht gesetzt) (RPM/DEB-Version: ``/etc/fess``) + - Verzeichnis mit den Konfigurationsdateien. ``bin/fess`` stellt es an den Anfang des Klassenpfads und übergibt es als ``-Dfess.conf.path`` an |Fess|. Von Dateien wie ``tomcat_config.properties`` in ``lib/classes`` hat die Datei in diesem Verzeichnis Vorrang. In der ZIP-Version liest die Webanwendung jedoch zuerst die Dateien in ``app/WEB-INF/classes``; eine in diesem Verzeichnis abgelegte ``fess_config.properties`` überschreibt daher die Werte der ``fess_config.properties`` in ``app/WEB-INF/classes`` nicht (Kindprozesse wie der Crawler lesen dieses Verzeichnis vor ``WEB-INF/classes``). Ändern Sie in der ZIP-Version die Datei in ``app/WEB-INF/classes``, um ``fess_config.properties`` anzupassen. Die RPM/DEB-Version legt keine ``fess_config.properties`` in ``app/WEB-INF/classes`` ab und verwendet nur die Datei in ``/etc/fess``. + * - ``FESS_USE_IPV4`` + - (nicht gesetzt) + - Mit einem beliebigen nicht leeren Wert verwendet die JVM nur den IPv4-Stack (``-Djava.net.preferIPv4Stack=true``). + * - ``FESS_USE_GC_LOGGING`` + - (nicht gesetzt) + - Mit einem beliebigen nicht leeren Wert schreibt die JVM ihr GC-Protokoll nach ``gc-fess.log`` im Protokollverzeichnis (bis zu 5 Dateien mit je 64 MB). + +.. note:: + + Die Datei ``bin\fess.in.bat`` der Windows-ZIP-Version liest von diesen Umgebungsvariablen ``FESS_HEAP_SIZE``, ``FESS_HEAP_NEWSIZE``, ``FESS_USE_IPV4`` und ``FESS_USE_GC_LOGGING`` sowie die folgenden Umgebungsvariablen, die nicht in der Tabelle stehen: + + - ``FESS_MIN_MEM``, ``FESS_MAX_MEM``: Legen die minimale und die maximale Heap-Größe einzeln fest (werden ignoriert, wenn ``FESS_HEAP_SIZE`` gesetzt ist). + - ``FESS_DIRECT_SIZE``: Obergrenze des Direct Memory (``-XX:MaxDirectMemorySize``). + - ``FESS_DICTIONARY_PATH``: Das Verzeichnis ``config\dictionary`` von OpenSearch. + - ``FESS_PROXY_HOST``, ``FESS_PROXY_PORT``, ``FESS_NON_PROXY_HOSTS``: Proxy-Einstellungen. + - ``FESS_JAVA_OPTS``: ``fess.in.bat`` hängt diese JVM-Optionen hinter die bereits gesetzten Werte an. + - ``PLAYWRIGHT_NODEJS_PATH``: Die ausführbare Node.js-Datei, die das Playwright-Plugin verwendet. + - ``JAVA_HOME``: Erforderlich. + + ``FESS_PORT``, ``FESS_LOG_LEVEL``, ``FESS_TEMP_PATH``, ``FESS_CONF_PATH`` und ``SEARCH_ENGINE_HTTP_URL`` + werden nicht gelesen. Diese Werte sind direkt in der Datei eingetragen; bearbeiten Sie daher ``bin\fess.in.bat`` direkt, um sie zu ändern. + +Konfiguration des Mail-Servers +------------------------------- + +Um Fehlermeldungen und ähnliche Nachrichten per E-Mail zu erhalten, konfigurieren Sie den SMTP-Server und die Empfängeradresse für Benachrichtigungen. + +1. Geben Sie in ``fess_env_web.properties`` und ``fess_env_crawler.properties`` den SMTP-Serverhost und -port in ``mail.smtp.server.main.host.and.port`` an (Standard: ``localhost:25``). Die Dateien liegen beim ZIP-Paket in ``app/WEB-INF/classes/`` und bei den RPM/DEB-Paketen in ``/etc/fess/``. Der Web-Prozess von |Fess| liest die erste, der Crawler, der die E-Mail zum Abschluss des Crawlings sendet, die zweite; ``fess_env.properties`` wird nicht verwendet. Nach der Änderung ist ein Neustart von |Fess| erforderlich. +2. Klicken Sie in der Administrator-Oberfläche im linken Menü auf [System] → [Allgemein]. +3. Geben Sie die Empfänger-E-Mail-Adresse in das Feld [Benachrichtigungs-E-Mail] ein. +4. Klicken Sie auf die Schaltfläche [Aktualisieren]. +5. Mit der Schaltfläche [Test-E-Mail senden] können Sie überprüfen, ob E-Mails korrekt versendet werden. + +Zeitzoneneinstellung +-------------------- + +|Fess| verwendet die Zeitzone des Servers (Betriebssystem / JVM). Es gibt keine Einstellung zur Änderung der Zeitzone in der Administrator-Oberfläche. Um sie zu ändern, passen Sie die Zeitzoneneinstellung des Betriebssystems an oder fügen Sie die JVM-Option ``-Duser.timezone=Asia/Tokyo`` zu ``FESS_JAVA_OPTS`` in ``bin/fess.in.sh`` hinzu (unter Windows: ``bin\fess.in.bat``). + +Anpassung des Protokollniveaus +------------------------------- + +In Produktionsumgebungen kann das Protokollniveau angepasst werden, um die Festplattennutzung zu reduzieren. + +Das Gesamtprotokollniveau von |Fess| kann mit der Umgebungsvariable ``FESS_LOG_LEVEL`` geändert werden (Standard: ``warn``). Zur detaillierten Steuerung einzelner Logger bearbeiten Sie die Konfigurationsdatei ``app/WEB-INF/classes/log4j2.xml``. Crawling, Vorschläge und die Thumbnail-Generierung laufen als separate Prozesse; konfigurieren Sie deren Protokollniveaus daher separat in ``app/WEB-INF/env/{crawler,suggest,thumbnail}/resources/log4j2.xml``. + +Weitere Informationen finden Sie unter :doc:`../admin/index`. + +Stoppmethoden +============= + +ZIP-Version +------------------ + +Stoppen von Fess +~~~~~~~~~~~~~~~~ + +Beenden Sie den Prozess mit kill:: + + $ ps aux | grep fess + $ kill + +Oder stoppen Sie über die Konsole mit ``Ctrl+C`` (bei Vordergrundausführung). + +Stoppen von OpenSearch:: + + $ ps aux | grep opensearch + $ kill + +RPM/DEB-Version (chkconfig) +---------------------------- + +Stoppen von Fess:: + + $ sudo service fess stop + +Stoppen von OpenSearch:: + + $ sudo service opensearch stop + +RPM/DEB-Version (systemd) +-------------------------- + +Stoppen von Fess:: + + $ sudo systemctl stop fess.service + +Stoppen von OpenSearch:: + + $ sudo systemctl stop opensearch.service + +Docker-Version +-------------- + +Stoppen der Container:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop + +Stoppen und Löschen der Container:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +.. warning:: + + Zum Löschen auch der Volumes mit dem Befehl ``down`` fügen Sie die Option ``-v`` hinzu. + In diesem Fall werden alle Daten gelöscht, seien Sie also vorsichtig. + +Neustartmethoden +================ + +ZIP-Version +------------------ + +Stoppen Sie zuerst und starten Sie dann neu. + +RPM/DEB-Version +--------------- + +chkconfig:: + + $ sudo service fess restart + +systemd:: + + $ sudo systemctl restart fess.service + +Docker-Version +-------------- + +:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml restart + +Fehlerbehebung +============== + +Wenn es nicht startet +--------------------- + +1. **Überprüfen Sie, ob OpenSearch läuft** + + :: + + $ curl http://localhost:9200/ + + Wenn OpenSearch nicht läuft, starten Sie zunächst OpenSearch. + +2. **Überprüfen Sie Portnummer-Konflikte** + + :: + + $ sudo ss -tuln | grep 8080 + + Ist net-tools installiert, liefert ``sudo netstat -tuln | grep 8080`` dieselben Informationen. + + Wenn Port 8080 bereits verwendet wird, ändern Sie die Portnummer: + + - ZIP-Version: Ändern Sie ``FESS_PORT`` in ``bin/fess.in.sh`` + - ZIP-Version (Windows): Bearbeiten Sie ``-Dfess.port=8080`` direkt in ``bin\fess.in.bat`` + - RPM-Version: Ändern Sie ``FESS_PORT`` in ``/etc/sysconfig/fess`` + - DEB-Version: Ändern Sie ``FESS_PORT`` in ``/etc/default/fess`` + +3. **Überprüfen Sie die Protokolle** + + Identifizieren Sie das Problem anhand der Fehlermeldungen. + +4. **Überprüfen Sie die Java-Version** + + :: + + $ java -version + + Vergewissern Sie sich, dass Java 21 oder höher installiert ist. + +Detaillierte Fehlerbehebung finden Sie unter :doc:`troubleshooting`. + +Nächste Schritte +================ + +Nach erfolgreichem Start von |Fess| beginnen Sie den Betrieb unter Bezugnahme auf folgende Dokumentation: + +- :doc:`../admin/index` - Details zu Crawl-Konfiguration, Such-Konfiguration und Systemeinstellungen +- :doc:`security` - Sicherheitseinstellungen für Produktionsumgebungen +- :doc:`troubleshooting` - Häufige Probleme und Lösungen +- :doc:`upgrade` - Upgrade-Verfahren +- :doc:`uninstall` - Deinstallationsverfahren diff --git a/de/15.10/install/security.rst b/de/15.10/install/security.rst new file mode 100644 index 000000000..cb4a608dd --- /dev/null +++ b/de/15.10/install/security.rst @@ -0,0 +1,355 @@ +======================== +Sicherheitseinstellungen +======================== + +Diese Seite beschreibt die empfohlenen Sicherheitseinstellungen für den sicheren Betrieb von |Fess| in Produktionsumgebungen. + +.. danger:: + + **Sicherheit ist äußerst wichtig** + + In Produktionsumgebungen wird dringend empfohlen, alle auf dieser Seite beschriebenen Sicherheitseinstellungen zu implementieren. + Vernachlässigung der Sicherheitseinstellungen erhöht das Risiko von unbefugtem Zugriff, Datenlecks und Systemkompromittierung. + +Erforderliche Sicherheitseinstellungen +======================================= + +Änderung des Administratorpassworts +------------------------------------ + +Das Standard-Administratorpasswort (``admin`` / ``admin``) muss unbedingt geändert werden. + +**Vorgehensweise:** + +1. Anmeldung in der Verwaltungsseite: http://localhost:8080/admin +2. Klicken Sie auf „Benutzer" → „Benutzer" +3. Wählen Sie den Benutzer ``admin`` +4. Setzen Sie ein starkes Passwort +5. Klicken Sie auf die Schaltfläche „Aktualisieren" + +.. note:: + + Sobald Sie das Passwort von ``admin`` geändert haben, können Sie es nicht mehr auf einen einfachen Wert wie ``admin`` zurücksetzen (eine Sperrliste für Administratorpasswörter wird über ``password.invalid.admin.passwords`` konfiguriert). Außerdem können Sie das Initialpasswort des Benutzers ``admin`` bereits vor dem ersten Start ändern, indem Sie ``index.user.initial_password`` in ``fess_config.properties`` setzen. + +**Empfohlene Passwort-Richtlinie:** + +|Fess| bietet eine integrierte Funktion, die die Mindest- und Höchstlänge des Passworts sowie Anforderungen an die Zeichenarten erzwingt. Konfigurieren Sie die folgenden Eigenschaften in ``fess_config.properties`` (Standardwerte in Klammern): + +- ``password.min.length`` (Standard: ``8``): Mindestlänge. 12 oder mehr wird empfohlen. +- ``password.max.length`` (Standard: ``100``): Höchstlänge. +- ``password.require.uppercase`` (Standard: ``false``): Großbuchstaben erforderlich. +- ``password.require.lowercase`` (Standard: ``false``): Kleinbuchstaben erforderlich. +- ``password.require.digit`` (Standard: ``false``): Ziffern erforderlich. +- ``password.require.special.char`` (Standard: ``false``): Sonderzeichen erforderlich. + +.. note:: + + Standardmäßig beträgt die Mindestlänge ``8`` und alle Anforderungen an Zeichenarten sind deaktiviert. Um Passwörter zu stärken, setzen Sie die oben genannten Eigenschaften explizit. Beachten Sie, dass |Fess| keine Funktion zum Ablaufen von Passwörtern (erzwungene regelmäßige Änderung) besitzt. Wenn Sie regelmäßige Passwortänderungen als Betriebsregel durchsetzen möchten, führen Sie diese manuell durch. + +Aktivierung des OpenSearch-Sicherheits-Plugins +----------------------------------------------- + +**Vorgehensweise:** + +1. Entfernen oder kommentieren Sie folgende Zeile in ``opensearch.yml``:: + + # plugins.security.disabled: true + +2. Konfiguration des Sicherheits-Plugins:: + + plugins.security.allow_default_init_securityindex: true + plugins.security.authcz.admin_dn: + - CN=admin,OU=SSL,O=Test,L=Test,C=DE + +3. Konfiguration von TLS/SSL-Zertifikaten + +4. Neustart von OpenSearch + +5. Konfigurieren Sie auf Seiten von |Fess| die Verbindung zu OpenSearch. + + Geben Sie die Verbindungs-URL über die Umgebungsvariable ``SEARCH_ENGINE_HTTP_URL`` an (bearbeiten Sie ``bin/fess.in.sh`` oder die Umgebungsdatei des Dienstes; der Standardwert stammt aus ``search_engine.http.url`` in ``fess_config.properties``):: + + SEARCH_ENGINE_HTTP_URL=https://opensearch:9200 + + Geben Sie die Zugangsdaten über die folgenden Eigenschaften in ``fess_config.properties`` an (es gibt keine Umgebungsvariablen ``SEARCH_ENGINE_USERNAME`` / ``SEARCH_ENGINE_PASSWORD``):: + + search_engine.username=admin + search_engine.password= + +Details finden Sie unter `OpenSearch Security Plugin `__. + +Aktivierung von HTTPS +---------------------- + +HTTP-Kommunikation ist nicht verschlüsselt und birgt Risiken von Abhören und Manipulation. In Produktionsumgebungen muss unbedingt HTTPS verwendet werden. + +**Methode 1: Verwendung eines Reverse-Proxys (empfohlen)** + +Platzieren Sie Nginx oder Apache vor |Fess| für HTTPS-Terminierung. + +Nginx-Konfigurationsbeispiel:: + + server { + listen 443 ssl http2; + server_name ihre-fess-domain.com; + + ssl_certificate /path/to/cert.pem; + ssl_certificate_key /path/to/key.pem; + + ssl_protocols TLSv1.2 TLSv1.3; + ssl_ciphers HIGH:!aNULL:!MD5; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + } + +**Methode 2: HTTPS-Konfiguration in Fess selbst** + +Fügen Sie in ``tomcat_config.properties`` Folgendes hinzu:: + + tomcat.secure=true + tomcat.scheme=https + tomcat.SSLEnabled=true + tomcat.certificateKeystoreFile=[Pfad zur Keystore-Datei] + tomcat.certificateKeystorePassword=[Passwort, das beim Erstellen der Keystore-Datei angegeben wurde] + tomcat.certificateKeyAlias=[Zertifikat-Alias] + tomcat.sslProtocol=[SSL-Protokoll (z.B. TLS)] + tomcat.enabledProtocols=Liste der aktivierten Protokolle (kommagetrennt) (z.B. TLSv1.2,TLSv1.1,TLSv1) + +Empfohlene Sicherheitseinstellungen +==================================== + +Firewall-Konfiguration +----------------------- + +Öffnen Sie nur erforderliche Ports und schließen Sie unnötige Ports. + +**Zu öffnende Ports:** + +- **8080** (oder HTTPS 443): |Fess| Weboberfläche (bei externem Zugriff erforderlich) +- **22**: SSH (nur für Verwaltung, nur von vertrauenswürdigen IP-Adressen) + +**Zu schließende Ports:** + +- **9200, 9300**: OpenSearch (nur interne Kommunikation, externer Zugriff blockieren) + +Linux (firewalld) Konfigurationsbeispiel:: + + $ sudo firewall-cmd --permanent --add-service=http + $ sudo firewall-cmd --permanent --add-service=https + $ sudo firewall-cmd --permanent --remove-service=opensearch # Bei benutzerdefiniertem Dienst + $ sudo firewall-cmd --reload + +IP-Adressbeschränkung:: + + $ sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="192.168.1.0/24" port port="8080" protocol="tcp" accept' + +Zugriffskontroll-Konfiguration +------------------------------- + +Erwägen Sie, den Zugriff auf die Verwaltungsseite auf bestimmte IP-Adressen zu beschränken. + +Nginx-Zugriffsbeschränkungsbeispiel:: + + location /admin { + allow 192.168.1.0/24; + deny all; + + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + } + +Rollen und Zugriffskontrolle +---------------------------- + +|Fess| stellt standardmäßig zwei Rollen bereit: + +- ``admin``: Administratorrolle, die alle Operationen einschließlich der Verwaltungsseite ausführen kann. +- ``guest``: Rolle, die nicht angemeldeten (anonymen) Benutzern zugewiesen wird. + +Alle anderen Rollen können frei über die Verwaltungsseite erstellt werden. In |Fess| ist eine Rolle ein Tag, das nur einen Namen besitzt, und wird hauptsächlich zur Zugriffskontrolle von Suchergebnissen verwendet (welche Dokumente ein Benutzer einsehen darf). Eine Ausnahme bildet eine Rolle mit dem Namen ``admin-``, gefolgt vom Namen einer Verwaltungsseite, etwa ``admin-user`` oder ``admin-scheduler``: Sie erlaubt es einem Benutzer, diese Seite zu öffnen, und die ``-view``-Form, etwa ``admin-user-view``, erlaubt reinen Lesezugriff. + +.. warning:: + + Die ``admin-*``-Rollen ermöglichen es, alltägliche Verwaltungsseiten auf mehrere Betreiber aufzuteilen, sie sind jedoch keine Berechtigungsgrenze. Ein Benutzer mit ``admin-user`` kann jedem Benutzer eine beliebige vorhandene Rolle zuweisen, einschließlich der Administratorrolle; ``admin-accesstoken`` kann ein Zugriffstoken mit der Berechtigung ``Radmin-api`` ausstellen, die die gesamte Admin API freigibt; ``admin-scheduler`` kann Skript-Jobs auf dem Server ausführen, und ``admin-plugin`` kann Plugins installieren. Behandeln Sie jede ``admin-*``-Rolle wie die Administratorrolle (``authentication.admin.roles``, Standardwert ``admin``) und gewähren Sie sie nur vertrauenswürdigen Betreibern. + +Befolgen Sie das Prinzip der geringsten Rechte: Gewähren Sie die Administratorrolle (``admin``) nur Benutzern, die administrative Aufgaben durchführen, und nicht allgemeinen Suchbenutzern. + +**Vorgehensweise:** + +1. Klicken Sie in der Verwaltungsseite auf „Benutzer" → „Rolle" +2. Erstellen Sie die erforderlichen Rollen +3. Weisen Sie Benutzern unter „Benutzer" → „Benutzer" Rollen zu + +Audit-Protokollierung +---------------------- + +Der Systembetriebsverlauf, wie Authentifizierung und administrative Operationen, wird standardmäßig als Audit-Protokoll aufgezeichnet. Das Audit-Protokoll wird vom Logger ``fess.log.audit`` ausgegeben, der in ``log4j2.xml`` definiert ist, und sein Standard-Ausgabeziel ist ``audit.log``. + +Da dies standardmäßig aktiviert ist, ist keine zusätzliche Konfiguration erforderlich. Um das Ausgabeziel oder die Protokollstufe anzupassen, bearbeiten Sie die folgende Definition in ``log4j2.xml``:: + + + + + +Regelmäßige Sicherheitsupdates +------------------------------- + +Wenden Sie regelmäßig Sicherheitsupdates für |Fess| und OpenSearch an. + +**Empfohlene Vorgehensweise:** + +1. Regelmäßige Überprüfung von Sicherheitsinformationen + + - `Fess-Versionsinformationen `__ + - `OpenSearch Security Advisories `__ + +2. Überprüfung von Updates in der Testumgebung +3. Anwendung von Updates in der Produktionsumgebung + +Datenschutz +=========== + +Verschlüsselung von Backups +---------------------------- + +Backup-Daten können vertrauliche Informationen enthalten. Verschlüsseln und speichern Sie Backup-Dateien. + +Beispiel für verschlüsselte Backups:: + + $ tar czf fess-backup.tar.gz /var/lib/opensearch /etc/fess + $ gpg --symmetric --cipher-algo AES256 fess-backup.tar.gz + +Sicherheits-Best-Practices +=========================== + +Prinzip der geringsten Rechte +------------------------------ + +- Fess und OpenSearch nicht als Root-Benutzer ausführen +- Mit dediziertem Benutzerkonto ausführen +- Minimal erforderliche Dateisystemberechtigungen gewähren + +Netzwerk-Isolation +------------------ + +- OpenSearch in privatem Netzwerk platzieren +- VPN oder privates Netzwerk für interne Kommunikation verwenden +- Nur |Fess| Weboberfläche in DMZ platzieren + +Regelmäßige Sicherheitsaudits +------------------------------ + +- Regelmäßige Überprüfung von Zugriffslogs +- Erkennung abnormaler Zugriffsmuster +- Regelmäßige Durchführung von Schwachstellen-Scans + +Konfiguration von Sicherheits-Headern +-------------------------------------- + +Konfigurieren Sie bei Bedarf Sicherheits-Header in Nginx oder Apache:: + + add_header X-Frame-Options "SAMEORIGIN" always; + add_header X-Content-Type-Options "nosniff" always; + add_header X-XSS-Protection "1; mode=block" always; + add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; + add_header Content-Security-Policy "default-src 'self'" always; + +Sicherheits-Checkliste +======================= + +Überprüfen Sie vor der Bereitstellung in der Produktionsumgebung folgende Checkliste: + +Grundkonfiguration +------------------ + +- [ ] Administratorpasswort geändert +- [ ] HTTPS aktiviert +- [ ] Standard-Portnummer geändert (optional) + +Netzwerksicherheit +------------------ + +- [ ] Unnötige Ports mit Firewall geschlossen +- [ ] Zugriff auf Verwaltungsseite IP-beschränkt (falls möglich) +- [ ] Zugriff auf OpenSearch nur auf internes Netzwerk beschränkt + +Zugriffskontrolle +----------------- + +- [ ] Rollen und Zugriffsberechtigungen angemessen konfiguriert (Administratorrolle nur an notwendige Benutzer vergeben) +- [ ] Unnötige Benutzerkonten gelöscht +- [ ] Passwort-Richtlinie konfiguriert + +Überwachung und Protokollierung +-------------------------------- + +- [ ] Bestätigt, dass die Audit-Protokollierung aktiviert ist +- [ ] Aufbewahrungsdauer für Protokolle konfiguriert +- [ ] Log-Überwachungsmechanismus eingerichtet (falls möglich) + +Backup und Recovery +------------------- + +- [ ] Regelmäßiger Backup-Zeitplan konfiguriert +- [ ] Backup-Daten verschlüsselt +- [ ] Wiederherstellungsverfahren getestet + +Update- und Patch-Management +----------------------------- + +- [ ] Mechanismus zum Empfangen von Sicherheitsupdate-Benachrichtigungen eingerichtet +- [ ] Update-Verfahren dokumentiert +- [ ] System zur Überprüfung von Updates in Testumgebung eingerichtet + +Reaktion auf Sicherheitsvorfälle +================================= + +Reaktionsverfahren bei Sicherheitsvorfällen: + +1. **Erkennung von Vorfällen** + + - Überprüfung von Protokollen + - Erkennung abnormaler Zugriffsmuster + - Überprüfung von Systemanormalitäten + +2. **Erstreaktion** + + - Identifizierung des Umfangs der Auswirkungen + - Verhinderung der Schadensausweitung (Stoppen betroffener Dienste etc.) + - Sicherung von Beweisen + +3. **Untersuchung und Analyse** + + - Detaillierte Analyse von Protokollen + - Identifizierung des Eindringwegs + - Identifizierung möglicherweise durchgesickerter Daten + +4. **Wiederherstellung** + + - Behebung von Schwachstellen + - Systemwiederherstellung + - Verstärkung der Überwachung + +5. **Nachbereitung** + + - Erstellung eines Vorfallsberichts + - Umsetzung von Präventivmaßnahmen + - Berichterstattung an Stakeholder + +Referenzinformationen +====================== + +- `OpenSearch Security Plugin `__ +- `OWASP Top 10 `__ +- `CIS Benchmarks `__ + +Bei Fragen oder Problemen zur Sicherheit wenden Sie sich bitte an: + +- Issues: https://github.com/codelibs/fess/issues +- Kommerzieller Support: https://www.n2sm.net/ diff --git a/de/15.10/install/troubleshooting.rst b/de/15.10/install/troubleshooting.rst new file mode 100644 index 000000000..896c4d890 --- /dev/null +++ b/de/15.10/install/troubleshooting.rst @@ -0,0 +1,596 @@ +================== +Fehlerbehebung +================== + +Diese Seite beschreibt häufige Probleme und deren Lösungen bei Installation, Start und Betrieb von |Fess|. + +Probleme bei der Installation +============================== + +Java wird nicht erkannt +----------------------- + +**Symptom:** + +:: + + -bash: java: command not found + +Oder:: + + 'java' is not recognized as an internal or external command + +**Ursache:** + +Java ist nicht installiert oder die PATH-Umgebungsvariable ist nicht korrekt gesetzt. + +**Lösung:** + +1. Überprüfen Sie, ob Java installiert ist:: + + $ which java + $ java -version + +2. Falls nicht installiert, installieren Sie Java 21:: + + # Ubuntu/Debian + $ sudo apt-get update + $ sudo apt-get install openjdk-21-jdk + + # RHEL/CentOS + $ sudo yum install java-21-openjdk + + Die Standard-Repositories von Debian 12 enthalten kein Paket ``openjdk-21-jdk``. Installieren Sie unter Debian 12 stattdessen Eclipse Temurin 21 gemäß der Debian-Anleitung in der `Adoptium-Installationsanleitung für Linux `__. + +3. Setzen Sie die JAVA_HOME-Umgebungsvariable:: + + $ export JAVA_HOME=/path/to/java + $ export PATH=$JAVA_HOME/bin:$PATH + + Fügen Sie für permanente Einstellung zu ``~/.bashrc`` oder ``/etc/profile`` hinzu. + +Plugin-Installation schlägt fehl +--------------------------------- + +**Symptom:** + +:: + + ERROR: Plugin installation failed + +**Ursache:** + +- Netzwerkverbindungsprobleme +- Plugin-Version stimmt nicht mit OpenSearch-Version überein +- Berechtigungsprobleme + +**Lösung:** + +1. Überprüfen Sie die OpenSearch-Version:: + + $ /path/to/opensearch/bin/opensearch --version + +2. Passen Sie die Plugin-Version an die OpenSearch-Version an:: + + $ /path/to/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + +3. Überprüfen Sie Berechtigungen:: + + $ sudo /path/to/opensearch/bin/opensearch-plugin install ... + +4. Bei Installation über Proxy:: + + $ export ES_JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080" + $ /path/to/opensearch/bin/opensearch-plugin install ... + +Probleme beim Start +=================== + +Fess startet nicht +------------------ + +**Symptom:** + +Beim Ausführen des Fess-Startbefehls tritt ein Fehler auf oder es endet sofort. + +**Prüfpunkte:** + +1. **Überprüfen Sie, ob OpenSearch läuft**:: + + $ curl http://localhost:9200/ + + Bei normalem Betrieb wird eine JSON-Antwort zurückgegeben. + + Antwortet kein OpenSearch, versucht |Fess| es etwa eine Minute lang erneut und bricht den Start + dann mit der folgenden Meldung auf der Konsole und in ``logs/fess.log`` ab:: + + The search engine at http://localhost:9200 did not become available within 60221ms. Check that OpenSearch is running and reachable. If there is none yet, run bin/fess-setup install opensearch to set one up. + + Starten Sie OpenSearch, oder überprüfen Sie ``SEARCH_ENGINE_HTTP_URL``. Eine neue + ZIP-Installation hat kein OpenSearch, bis eines mit ``bin/fess-setup install opensearch`` + eingerichtet wurde; siehe :doc:`install-linux`. + +2. **Überprüfen Sie Portnummer-Konflikte**:: + + $ sudo ss -tuln | grep 8080 + + Falls Port 8080 bereits verwendet wird, ändern Sie die Portnummer in der Konfigurationsdatei. + +3. **Überprüfen Sie Protokolldateien**:: + + $ tail -f /path/to/fess/logs/fess.log + + Identifizieren Sie die Ursache anhand der Fehlermeldungen. + +4. **Überprüfen Sie die Java-Version**:: + + $ java -version + + Vergewissern Sie sich, dass Java 21 oder höher installiert ist. + +5. **Überprüfen Sie Speichermangel**:: + + $ free -h + + Bei Speichermangel passen Sie die Heap-Größe an oder erhöhen Sie den Systemspeicher. + +OpenSearch startet nicht +------------------------- + +**Symptom:** + +:: + + ERROR: bootstrap checks failed + +**Ursache:** + +Die Systemkonfiguration erfüllt nicht die Anforderungen von OpenSearch. + +**Lösung:** + +1. **Einstellung von vm.max_map_count**:: + + $ sudo sysctl -w vm.max_map_count=262144 + + Permanente Einstellung:: + + $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf + $ sudo sysctl -p + +2. **Erhöhung der Dateideskriptor-Grenze**:: + + $ sudo vi /etc/security/limits.conf + + Fügen Sie Folgendes hinzu:: + + opensearch - nofile 65535 + opensearch - nproc 4096 + +3. **Einstellung für Memory-Lock**:: + + $ sudo vi /etc/security/limits.conf + + Fügen Sie Folgendes hinzu:: + + opensearch - memlock unlimited + +4. OpenSearch neu starten:: + + $ sudo systemctl restart opensearch + +Index kann nicht erstellt werden (Pfad der Wörterbuchdateien) +------------------------------------------------------------- + +**Symptom:** + +Beim Zugriff auf |Fess| wird HTTP 404 zurückgegeben, und in ``fess.log`` wird folgender Fehler ausgegeben:: + + Failed to create index: index=fess, path=fess_indices/fess.json + ... reason=Resource path must be inside config directory: /var/lib/opensearch/data/config/ja/mapping.txt + +**Ursache:** + +Ab OpenSearch 3.8.0 wird die Erstellung eines Index verweigert, wenn sich Wörterbuchdateien außerhalb des OpenSearch-Konfigurationsverzeichnisses befinden. +``configsync.config_path`` und ``FESS_DICTIONARY_PATH`` zeigen auf ein Verzeichnis außerhalb des Konfigurationsverzeichnisses (z. B. ``data/config/``). + +**Lösung:** + +1. Ändern Sie ``configsync.config_path`` und ``FESS_DICTIONARY_PATH`` auf ein Verzeichnis unterhalb des OpenSearch-Konfigurationsverzeichnisses. + + - RPM/DEB-Version: ``/etc/opensearch/dictionary/`` + - ZIP-Version: ``/path/to/opensearch-3.9.0/config/dictionary/`` + +2. Wenn bereits Wörterbuchdateien vorhanden sind, kopieren Sie sie in das neue Verzeichnis. +3. Starten Sie zuerst OpenSearch und dann |Fess| neu. + +Details finden Sie unter :doc:`install-linux`. + +Portnummer-Konflikt +------------------- + +**Symptom:** + +:: + + Address already in use + +**Lösung:** + +1. Überprüfen Sie verwendete Ports:: + + $ sudo ss -tuln | grep 8080 + $ sudo lsof -i :8080 + +2. Stoppen Sie den verwendenden Prozess oder ändern Sie die Fess-Portnummer + + Informationen zur Änderung der Portnummer finden Sie unter :doc:`Port- und Netzwerkkonfiguration <../config/setup-port-network>`. + +Verbindungsprobleme +=================== + +Fess kann nicht mit OpenSearch verbinden +----------------------------------------- + +**Symptom:** + +Im Protokoll werden folgende Fehler angezeigt:: + + Connection refused + oder + No route to host + +**Lösung:** + +1. **Überprüfen Sie, ob OpenSearch läuft**:: + + $ curl http://localhost:9200/ + +2. **Überprüfen Sie die Verbindungs-URL** + + Überprüfen Sie, ob die in ``fess.in.sh`` oder ``fess.in.bat`` gesetzte URL korrekt ist:: + + SEARCH_ENGINE_HTTP_URL=http://localhost:9200 + +3. **Überprüfen Sie die Firewall**:: + + $ sudo firewall-cmd --list-all + + Überprüfen Sie, ob Port 9200 geöffnet ist. + +4. **Überprüfen Sie die Netzwerkverbindung** + + Bei Ausführung von OpenSearch auf einem anderen Host:: + + $ ping opensearch-host + $ telnet opensearch-host 9200 + +Kein Zugriff auf Fess über den Browser +--------------------------------------- + +**Symptom:** + +Kein Zugriff auf http://localhost:8080/ über den Browser möglich. + +**Lösung:** + +1. **Überprüfen Sie, ob Fess läuft**:: + + $ ps aux | grep fess + +2. **Versuchen Sie Zugriff über Localhost**:: + + $ curl http://localhost:8080/ + +3. **Überprüfen Sie die Firewall**:: + + $ sudo firewall-cmd --list-all + + Überprüfen Sie, ob Port 8080 geöffnet ist. + +4. **Bei Zugriff von einem anderen Host** + + Überprüfen Sie, ob Fess auf mehr als nur Localhost lauscht:: + + $ ss -tuln | grep 8080 + + Falls ``127.0.0.1:8080``, ändern Sie die Konfiguration, um auf ``0.0.0.0:8080`` oder einer bestimmten IP-Adresse zu lauschen. + +Leistungsprobleme +================= + +Suche ist langsam +----------------- + +**Ursache:** + +- Index ist groß +- Speichermangel +- Langsames Festplatten-I/O +- Komplexe Query + +**Lösung:** + +1. **Heap-Größe erhöhen** + + Übergeben Sie ``FESS_HEAP_SIZE`` als Umgebungsvariable beim Start von |Fess|:: + + $ FESS_HEAP_SIZE=4g bin/fess + + Wenn Sie die Einstellung in ``bin/fess.in.sh`` vornehmen, schreiben Sie ``FESS_HEAP_SIZE=4g`` **vor** die Zeile, die den Standardwert von ``FESS_MIN_MEM`` und damit die Heap-Größe festlegt. Ein Eintrag am Ende der Datei wirkt nicht, da die Heap-Größe zu diesem Zeitpunkt bereits feststeht. Bei der RPM/DEB-Version tragen Sie die Einstellung in ``/etc/sysconfig/fess`` ein (bei der DEB-Version in ``/etc/default/fess``). + + Passen Sie auch die OpenSearch-Heap-Größe an:: + + export OPENSEARCH_JAVA_OPTS="-Xms4g -Xmx4g" + +2. **SSD verwenden** + + Bei Festplatten-I/O als Engpass wechseln Sie zu SSD. + +3. **Cache aktivieren** + + Aktivieren Sie Query-Cache in der Konfigurationsdatei. + +Crawling ist langsam +-------------------- + +**Ursache:** + +- Langes Crawl-Intervall +- Langsame Antwort der Ziel-Site +- Geringe Anzahl an Threads + +**Lösung:** + +1. **Crawl-Intervall anpassen** + + Verkürzen Sie das „Intervall" in der Crawl-Konfiguration der Verwaltungsseite (in Millisekunden). + + .. warning:: + + Ein zu kurzes Intervall belastet die Ziel-Site. Setzen Sie einen angemessenen Wert. + +2. **Thread-Anzahl erhöhen** + + Erhöhen Sie in der Verwaltungsseite die „Anzahl der Threads" der Crawl-Konfiguration. Der Standardwert beträgt 1 für Web-Crawls und 5 für Dateisystem-Crawls. + +3. **Timeout-Wert anpassen** + + Bei langsam antwortenden Sites erhöhen Sie den Timeout-Wert. + +Datenprobleme +============= + +Keine Suchergebnisse angezeigt +------------------------------- + +**Ursache:** + +- Index nicht erstellt +- Crawling fehlgeschlagen +- Falsche Such-Query + +**Lösung:** + +1. **Index überprüfen**:: + + $ curl http://localhost:9200/_cat/indices?v + + Überprüfen Sie, ob |Fess|-Indizes vorhanden sind. + +2. **Crawl-Protokoll überprüfen** + + Laden Sie in der Verwaltungsseite unter „Systeminformationen" → „Protokolldatei" das Crawl-Protokoll (``fess-crawler.log``) herunter und prüfen Sie es auf Fehler. + +3. **Crawl erneut ausführen** + + Führen Sie in der Verwaltungsseite unter „System" → „Scheduler" den „Default Crawler" aus. + +4. **Such-Query vereinfachen** + + Suchen Sie zunächst mit einem einfachen Stichwort und überprüfen Sie, ob Ergebnisse zurückgegeben werden. + +Index ist beschädigt +-------------------- + +**Symptom:** + +Bei der Suche treten Fehler auf oder es werden unerwartete Ergebnisse zurückgegeben. + +**Lösung:** + +1. **Index löschen und neu erstellen** + + .. warning:: + + Beim Löschen des Index gehen alle Suchdaten verloren. Erstellen Sie unbedingt ein Backup. + + :: + + $ curl -X DELETE http://localhost:9200/fess* + +2. **Fess neu starten** + + Die Indizes werden beim Start von |Fess| angelegt. Unmittelbar nach dem Löschen ist auch der Index mit den Benutzerinformationen verloren, sodass Sie sich nicht in der Verwaltungsseite anmelden können (``/api/v2/health`` liefert weiterhin ``200``). Nach einem Neustart von |Fess| werden die Indizes, die Standard-Jobs und der Anfangsbenutzer (``admin``) neu erstellt. + +3. **Crawl erneut ausführen** + + Führen Sie über die Verwaltungsseite „Default Crawler" aus, um die zu durchsuchenden Dokumente erneut zu registrieren. + +Docker-spezifische Probleme +=========================== + +Container startet nicht +----------------------- + +**Symptom:** + +Container startet nicht mit ``docker compose up``. + +**Lösung:** + +1. **Protokolle überprüfen**:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs + +2. **Speichermangel überprüfen** + + Erhöhen Sie den Docker zugewiesenen Speicher (über Docker Desktop-Einstellungen). + +3. **Port-Konflikte überprüfen**:: + + $ docker ps + + Überprüfen Sie, ob andere Container Port 8080 oder 9200 verwenden. + +4. **Docker Compose-Datei überprüfen** + + Überprüfen Sie auf Syntaxfehler in der YAML-Datei:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml config + +Container läuft, aber kein Zugriff auf Fess möglich +---------------------------------------------------- + +**Lösung:** + +1. **Container-Status überprüfen**:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps + +2. **Protokolle überprüfen**:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs fess + +3. **Netzwerkkonfiguration überprüfen**:: + + $ docker network ls + $ docker network inspect + +Windows-spezifische Probleme +============================= + +Pfadprobleme +------------ + +**Symptom:** + +Bei Pfaden mit Leerzeichen oder japanischen Zeichen treten Fehler auf. + +**Lösung:** + +Installieren Sie in einem Verzeichnis ohne Leerzeichen oder japanische Zeichen im Pfad. + +Beispiel:: + + C:\opensearch (empfohlen) + C:\Program Files\opensearch (nicht empfohlen) + +Registrierung als Dienst nicht möglich +--------------------------------------- + +**Lösung:** + +Verwenden Sie ein Drittanbieter-Tool wie NSSM zur Registrierung als Windows-Dienst. + +Details finden Sie unter :doc:`install-windows`. + +Sonstige Probleme +================= + +Änderung des Protokollniveaus +------------------------------ + +Ändern Sie das Protokollniveau auf DEBUG, um detaillierte Protokolle zu überprüfen. + +Bearbeiten Sie ``log4j2.xml``:: + + + +Datenbank zurücksetzen +----------------------- + +Löschen Sie OpenSearch-Indizes, um die Konfiguration zurückzusetzen:: + + $ curl -X DELETE 'http://localhost:9200/fess_config.*' + +.. warning:: + + Dieser Befehl löscht alle Konfigurationsdaten. + +Administratorpasswort vergessen +------------------------------- + +Wenn Sie das Administratorpasswort vergessen haben, können Sie es zurücksetzen, indem Sie das Benutzerdokument direkt im Index ``fess_user.user`` von OpenSearch aktualisieren. Das Passwort ist im Feld ``password`` als Hash in der Form ``{bcrypt}$2a$...`` gespeichert. Die Änderung wird ohne Neustart von |Fess| wirksam. + +1. Erstellen Sie den Hash des neuen Passworts. |Fess| akzeptiert nur bcrypt-Hashes, die mit ``$2a$`` beginnen. Ersetzen Sie daher das von ``htpasswd`` (enthalten im Paket ``apache2-utils`` bzw. ``httpd-tools``) ausgegebene ``$2y$`` durch ``$2a$``. Ersetzen Sie ``NewPassword`` durch das neue Passwort:: + + $ HASH=$(htpasswd -bnBC 10 "" 'NewPassword' | tr -d ':\n' | sed 's/^\$2y/$2a/') + +2. Aktualisieren Sie das Passwort im Dokument des Admin-Benutzers. Die Dokument-ID des Admin-Benutzers im Ausgangszustand lautet ``YWRtaW4=``:: + + $ curl -X POST 'http://localhost:9200/fess_user.user/_update/YWRtaW4=?refresh=true' \ + -H 'Content-Type: application/json' \ + -d "{\"doc\":{\"password\":\"{bcrypt}${HASH}\"}}" + + Um das Passwort eines anderen Benutzers zurückzusetzen, ermitteln Sie die ``_id`` mit ``curl 'http://localhost:9200/fess_user.user/_search?q=name:BENUTZERNAME'`` und verwenden Sie diese ID. Wenn für OpenSearch eine Authentifizierung aktiviert ist, geben Sie die Zugangsdaten bei curl an. + +3. Prüfen Sie, ob Sie sich mit dem neuen Passwort an der Verwaltungsseite anmelden können. Bleibt das Passwort in Ihrem Befehlsverlauf erhalten, setzen Sie es nach der Anmeldung unter [Benutzer > Benutzer] erneut. + +Support-Informationen +===================== + +Falls das Problem nicht gelöst werden kann, nutzen Sie folgende Support-Ressourcen: + +Community-Support +----------------- + +- **Issues**: https://github.com/codelibs/fess/issues + + Fügen Sie beim Melden von Problemen folgende Informationen hinzu: + + - Fess-Version + - OpenSearch-Version + - OS und Version + - Fehlermeldungen (aus Protokollen) + - Reproduktionsschritte + +- **Forum**: https://discuss.codelibs.org/ + +Kommerzieller Support +--------------------- + +Bei Bedarf an kommerziellem Support wenden Sie sich bitte an N2SM, Inc.: + +- **Website**: https://www.n2sm.net/ + +Sammlung von Debug-Informationen +================================= + +Beim Melden von Problemen ist das Sammeln folgender Informationen hilfreich: + +1. **Versionsinformationen** (``bin/fess -v`` ist ab 15.10 verfügbar):: + + $ /path/to/fess/bin/fess -v + $ /path/to/opensearch/bin/opensearch --version + $ java -version + +2. **Systeminformationen**:: + + $ uname -a + $ cat /etc/os-release + $ free -h + $ df -h + +3. **Protokolldateien**:: + + $ tar czf fess-logs.tar.gz /path/to/fess/logs/ + +4. **Konfigurationsdateien** (nach Entfernung vertraulicher Informationen):: + + $ tar czf fess-config.tar.gz /path/to/fess/app/WEB-INF/conf/ + +5. **OpenSearch-Status**:: + + $ curl http://localhost:9200/_cluster/health?pretty + $ curl http://localhost:9200/_cat/indices?v diff --git a/de/15.10/install/uninstall.rst b/de/15.10/install/uninstall.rst new file mode 100644 index 000000000..665a1e577 --- /dev/null +++ b/de/15.10/install/uninstall.rst @@ -0,0 +1,481 @@ +======================== +Deinstallationsverfahren +======================== + +Diese Seite beschreibt die Verfahren zur vollständigen Deinstallation von |Fess|. + +.. warning:: + + **Wichtige Hinweise vor der Deinstallation** + + - Bei der Deinstallation werden alle Daten gelöscht + - Bei wichtigen Daten erstellen Sie unbedingt ein Backup + - Backup-Verfahren finden Sie unter :doc:`upgrade` + +Vorbereitung vor der Deinstallation +=================================== + +Erstellung eines Backups +------------------------ + +Erstellen Sie Backups der benötigten Daten: + +1. **Konfigurationsdaten** + + Download über die Verwaltungsseite unter „System" → „Sicherung". + Mit diesem Vorgang können Sie verschiedene Einstellungen (einschließlich der Crawl-Einstellungen) sowie Suchprotokolle gesammelt exportieren. + +2. **Angepasste Konfigurationsdateien** + + ZIP-Version:: + + $ cp -r /path/to/fess/app/WEB-INF/conf /backup/ + $ cp -r /path/to/fess/app/WEB-INF/classes /backup/ + + RPM/DEB-Version:: + + $ sudo cp -r /etc/fess /backup/ + +.. note:: + + Der Großteil der Indizes und Einstellungen von |Fess| wird in OpenSearch gespeichert. + Wenn Sie die Indexdaten sichern möchten, verwenden Sie die Snapshot-Funktion von OpenSearch. + Ausführliche Anweisungen finden Sie unter :doc:`upgrade`. + +Stopp der Dienste +----------------- + +Stoppen Sie vor der Deinstallation alle Dienste. + +ZIP-Version:: + + $ ps aux | grep -E 'fess|opensearch' + $ kill + $ kill + +RPM/DEB-Version:: + + $ sudo systemctl stop fess.service + $ sudo systemctl stop opensearch.service + +Docker-Version:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +Deinstallation der ZIP-Version +===================================== + +Schritt 1: Löschen von Fess +--------------------------- + +Löschen Sie das Installationsverzeichnis:: + + $ rm -rf /path/to/fess-15.10.0 + +Schritt 2: Löschen von OpenSearch +--------------------------------- + +Löschen Sie das OpenSearch-Installationsverzeichnis:: + + $ rm -rf /path/to/opensearch-3.9.0 + +Schritt 3: Löschen des Datenverzeichnisses (Optional) +----------------------------------------------------- + +Die Indexdaten von |Fess| werden in OpenSearch gespeichert. +Standardmäßig werden sie innerhalb des OpenSearch-Installationsverzeichnisses gespeichert (z. B. ``opensearch-3.9.0/data``). +Falls Sie mit ``path.data`` einen anderen Speicherort angegeben haben, löschen Sie auch dieses Verzeichnis:: + + $ rm -rf /path/to/data + +Schritt 4: Löschen des Protokollverzeichnisses (Optional) +--------------------------------------------------------- + +Löschen Sie die Protokolldateien:: + + $ rm -rf /path/to/fess-15.10.0/logs + $ rm -rf /path/to/opensearch-3.9.0/logs + +Deinstallation der RPM-Version +============================== + +Schritt 1: Deinstallation von Fess +---------------------------------- + +Deinstallieren Sie das RPM-Paket:: + + $ sudo rpm -e fess + +.. note:: + + Bei der Deinstallation des |Fess|-Pakets werden durch das Löschskript des Pakets + der ``fess``-Dienst gestoppt und deaktiviert sowie der Benutzer ``fess`` und die Gruppe ``fess`` automatisch gelöscht. + Die folgenden Schritte werden ausgeführt, um sicherzustellen, dass diese zuverlässig gelöscht wurden, oder + um Daten und Konfigurationsdateien manuell zu löschen. + +Schritt 2: Deinstallation von OpenSearch +---------------------------------------- + +:: + + $ sudo rpm -e opensearch + +Schritt 3: Überprüfung der Deaktivierung der Dienste +---------------------------------------------------- + +Normalerweise werden die Dienste beim Löschen des Pakets deaktiviert. Um sie sicherheitshalber zu überprüfen bzw. zu deaktivieren, führen Sie Folgendes aus. + +Bei systemd:: + + $ sudo systemctl disable fess.service + $ sudo systemctl disable opensearch.service + $ sudo systemctl daemon-reload + +Bei einer älteren SysV-init-Umgebung (chkconfig):: + + $ sudo /sbin/chkconfig --del fess + $ sudo /sbin/chkconfig --del opensearch + +Schritt 4: Löschen des Datenverzeichnisses +------------------------------------------ + +.. warning:: + + Bei Ausführung dieser Operation werden alle Indexdaten vollständig gelöscht. + +Da das Datenverzeichnis bei der Deinstallation des Pakets nicht gelöscht wird, löschen Sie es manuell:: + + $ sudo rm -rf /var/lib/fess + $ sudo rm -rf /var/lib/opensearch + +Schritt 5: Löschen der Konfigurationsdateien +-------------------------------------------- + +Löschen Sie die Konfigurationsdateien und die Umgebungseinstellungsdateien:: + + $ sudo rm -rf /etc/fess + $ sudo rm -rf /etc/sysconfig/fess + $ sudo rm -rf /etc/opensearch + +.. note:: + + Bei RPM können die Konfigurationsdateien in ``/etc/fess`` unter dem Namen ``.rpmsave`` zurückbleiben. + Um sie vollständig zu löschen, löschen Sie sie wie oben gezeigt manuell. + +Schritt 6: Löschen der Protokolldateien +--------------------------------------- + +:: + + $ sudo rm -rf /var/log/fess + $ sudo rm -rf /var/log/opensearch + +Schritt 7: Löschen des temporären Verzeichnisses (Optional) +----------------------------------------------------------- + +:: + + $ sudo rm -rf /var/tmp/fess + +Schritt 8: Löschen von Benutzer und Gruppe (Optional) +----------------------------------------------------- + +Normalerweise werden der Benutzer ``fess`` und die Gruppe ``fess`` beim Löschen des Pakets gelöscht. +Falls sie zurückgeblieben sind oder Sie den Benutzer und die Gruppe für OpenSearch löschen möchten, führen Sie Folgendes aus:: + + $ sudo userdel fess + $ sudo groupdel fess + $ sudo userdel opensearch + $ sudo groupdel opensearch + +Deinstallation der DEB-Version +============================== + +Schritt 1: Deinstallation von Fess +---------------------------------- + +Deinstallieren Sie das DEB-Paket:: + + $ sudo dpkg -r fess + +Um es einschließlich der Konfigurationsdateien und der Umgebungseinstellungsdateien vollständig zu löschen, verwenden Sie purge:: + + $ sudo dpkg -P fess + +.. note:: + + Bei ``dpkg -r`` (remove) bleiben die Konfigurationsdateien (conffile) wie ``/etc/default/fess`` zurück. + Wenn Sie ``dpkg -P`` (purge) verwenden, werden diese Konfigurationsdateien sowie der Benutzer ``fess`` und die Gruppe ``fess`` ebenfalls gelöscht. + +Schritt 2: Deinstallation von OpenSearch +---------------------------------------- + +:: + + $ sudo dpkg -r opensearch + +Oder vollständiges Löschen einschließlich der Konfigurationsdateien:: + + $ sudo dpkg -P opensearch + +Schritt 3: Überprüfung der Deaktivierung der Dienste +---------------------------------------------------- + +Normalerweise werden die Dienste beim Löschen des Pakets deaktiviert. Um sie sicherheitshalber zu überprüfen bzw. zu deaktivieren, führen Sie Folgendes aus:: + + $ sudo systemctl disable fess.service + $ sudo systemctl disable opensearch.service + $ sudo systemctl daemon-reload + +Schritt 4: Löschen des Datenverzeichnisses +------------------------------------------ + +.. warning:: + + Bei Ausführung dieser Operation werden alle Indexdaten vollständig gelöscht. + +:: + + $ sudo rm -rf /var/lib/fess + $ sudo rm -rf /var/lib/opensearch + +Schritt 5: Löschen der Konfigurationsdateien (bei Nicht-Verwendung von dpkg -P) +------------------------------------------------------------------------------- + +:: + + $ sudo rm -rf /etc/fess + $ sudo rm -rf /etc/default/fess + $ sudo rm -rf /etc/opensearch + +Schritt 6: Löschen der Protokolldateien +--------------------------------------- + +:: + + $ sudo rm -rf /var/log/fess + $ sudo rm -rf /var/log/opensearch + +Schritt 7: Löschen von Benutzer und Gruppe (Optional) +----------------------------------------------------- + +Falls Sie ``dpkg -P`` nicht verwendet haben, bleiben der Benutzer ``fess`` und die Gruppe ``fess`` zurück. +Um sie zu löschen, führen Sie Folgendes aus:: + + $ sudo userdel fess + $ sudo groupdel fess + $ sudo userdel opensearch + $ sudo groupdel opensearch + +Deinstallation der Docker-Version +================================= + +Schritt 1: Löschen von Containern und Netzwerken +------------------------------------------------ + +Löschen Sie die Container sowie das von Docker Compose erstellte Netzwerk (``search_net``):: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +Schritt 2: Löschen der Volumes +------------------------------ + +.. warning:: + + Bei Ausführung dieser Operation werden alle Daten vollständig gelöscht. + +Die Daten von |Fess| (Indizes, Wörterbücher usw.) werden in den Volumes von OpenSearch gespeichert. +Überprüfen Sie zunächst die Liste der Volumes:: + + $ docker volume ls + +Löschen Sie die OpenSearch-bezogenen Volumes:: + + $ docker volume rm _search01_data + $ docker volume rm _search01_dictionary + +.. note:: + + Den Volume-Namen wird der Projektname von Docker Compose (normalerweise der Name des + Verzeichnisses, in dem die Compose-Dateien abgelegt sind) als Präfix vorangestellt. Überprüfen Sie die tatsächlichen Namen mit ``docker volume ls``. + +Um Container und Volumes auf einmal zu löschen, fügen Sie ``down`` die Option ``-v`` hinzu:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down -v + +Schritt 3: Löschen der Images (Optional) +---------------------------------------- + +Wenn Sie Docker-Images löschen und Festplattenplatz freigeben möchten:: + + $ docker images | grep fess + $ docker rmi ghcr.io/codelibs/fess:15.10.0 + $ docker rmi ghcr.io/codelibs/fess-opensearch:3.9.0 + +Schritt 4: Löschen der Compose-Dateien +-------------------------------------- + +:: + + $ rm compose.yaml compose-opensearch3.yaml + +Überprüfung der Deinstallation +============================== + +Überprüfen Sie, dass alle Komponenten gelöscht wurden. + +Überprüfung der Prozesse +------------------------ + +:: + + $ ps aux | grep fess + $ ps aux | grep opensearch + +Wenn nichts angezeigt wird, sind die Prozesse gestoppt. + +Überprüfung der Ports +--------------------- + +:: + + $ sudo ss -tuln | grep 8080 + $ sudo ss -tuln | grep 9200 + +Überprüfen Sie, dass keine Ports verwendet werden. + +Überprüfung der Dateien +----------------------- + +ZIP-Version:: + + $ ls /path/to/fess-15.10.0 # Überprüfen, dass Verzeichnis nicht existiert + +RPM/DEB-Version:: + + $ ls /var/lib/fess # Überprüfen, dass Verzeichnis nicht existiert + $ ls /etc/fess # Überprüfen, dass Verzeichnis nicht existiert + +Docker-Version:: + + $ docker ps -a | grep -E 'fess01|search01' # Überprüfen, dass Container nicht existieren + $ docker volume ls | grep search01 # Überprüfen, dass Volumes nicht existieren + +Überprüfung der Pakete +---------------------- + +RPM-Version:: + + $ rpm -qa | grep fess + $ rpm -qa | grep opensearch + +DEB-Version:: + + $ dpkg -l | grep fess + $ dpkg -l | grep opensearch + +Wenn nichts angezeigt wird, sind die Pakete gelöscht. + +Teilweise Deinstallation +======================== + +Nur Fess löschen und OpenSearch behalten +---------------------------------------- + +Falls Sie OpenSearch auch für andere Anwendungen verwenden, können Sie nur Fess löschen. + +1. Fess stoppen +2. Fess-Paket oder -Verzeichnis löschen +3. Fess-Datenverzeichnis löschen (``/var/lib/fess`` usw.) +4. Die in OpenSearch erstellten |Fess|-Indizes löschen + + Die Namen der |Fess|-Indizes beginnen mit ``fess`` (``fess.*``, ``fess_config.*``, ``fess_user.*``, ``fess_log.*``, ``fess_crawler.*``, ``fess_suggest*`` usw.). Mit dem folgenden Befehl können Sie sie gesammelt löschen. + + :: + + $ curl -X DELETE 'http://localhost:9200/fess*' + + Prüfen Sie vor dem Löschen mit ``curl 'http://localhost:9200/_cat/indices?v'``, dass es keine Indizes anderer Anwendungen gibt, deren Name mit ``fess`` beginnt. Auch der Index ``configsync`` zur Synchronisierung von Wörterbüchern kann gelöscht werden, sofern er nicht von anderen Anwendungen verwendet wird. + +5. OpenSearch nicht löschen + +Nur OpenSearch löschen und Fess behalten +---------------------------------------- + +.. warning:: + + Wenn Sie OpenSearch löschen, funktioniert Fess nicht mehr. + Ändern Sie die Konfiguration, um sich mit einem anderen OpenSearch-Cluster zu verbinden. + +1. OpenSearch stoppen +2. OpenSearch-Paket oder -Verzeichnis löschen +3. OpenSearch-Datenverzeichnis löschen (``/var/lib/opensearch`` usw.) +4. Fess-Konfiguration aktualisieren und anderen OpenSearch-Cluster angeben + +Fehlerbehebung +============== + +Paket kann nicht gelöscht werden +-------------------------------- + +**Symptom:** + +Fehler bei ``rpm -e`` oder ``dpkg -r``. + +**Lösung:** + +1. Überprüfen Sie, dass der Dienst gestoppt ist:: + + $ sudo systemctl stop fess.service + +2. Überprüfen Sie Abhängigkeiten:: + + $ rpm -qa | grep fess + $ dpkg -l | grep fess + +3. Erzwungenes Löschen (letzte Option):: + + $ sudo rpm -e --nodeps fess + $ sudo dpkg -r --force-all fess + +Verzeichnis kann nicht gelöscht werden +-------------------------------------- + +**Symptom:** + +Verzeichnis kann mit ``rm -rf`` nicht gelöscht werden. + +**Lösung:** + +1. Überprüfen Sie Berechtigungen:: + + $ ls -ld /path/to/directory + +2. Löschen mit sudo:: + + $ sudo rm -rf /path/to/directory + +3. Überprüfen Sie, ob Prozesse Dateien verwenden:: + + $ sudo lsof | grep /path/to/directory + +Vorbereitung für Neuinstallation +================================ + +Bei Neuinstallation nach der Deinstallation überprüfen Sie Folgendes: + +1. Alle Prozesse sind gestoppt +2. Alle Dateien und Verzeichnisse sind gelöscht +3. Ports 8080 und 9200 werden nicht verwendet +4. Keine früheren Konfigurationsdateien vorhanden + +Neuinstallationsverfahren finden Sie unter :doc:`install`. + +Nächste Schritte +================ + +Nach Abschluss der Deinstallation: + +- Bei Installation einer neuen Version siehe :doc:`install` +- Bei Datenmigration siehe :doc:`upgrade` +- Bei Erwägung alternativer Suchlösungen siehe die offizielle Fess-Website diff --git a/de/15.10/install/upgrade.rst b/de/15.10/install/upgrade.rst new file mode 100644 index 000000000..b090210a7 --- /dev/null +++ b/de/15.10/install/upgrade.rst @@ -0,0 +1,1721 @@ +==================== +Upgrade-Verfahren +==================== + +Diese Seite beschreibt die Verfahren zum Upgrade von |Fess| von einer früheren Version auf die neueste Version. + +.. warning:: + + **Wichtige Hinweise vor dem Upgrade** + + - Erstellen Sie vor dem Upgrade unbedingt ein Backup + - Es wird dringend empfohlen, das Upgrade zunächst in einer Testumgebung zu überprüfen + - Während des Upgrades wird der Dienst gestoppt, planen Sie daher eine angemessene Wartungszeit ein + - Je nach Version kann sich das Format der Konfigurationsdateien geändert haben + +Unterstützte Versionen +====================== + +Dieses Upgrade-Verfahren unterstützt Upgrades zwischen folgenden Versionen: + +- Fess 14.x → Fess 15.10 +- Fess 15.x → Fess 15.10 + +.. important:: + + |Fess| 14.x unterstützt OpenSearch der 2.x-Reihe, |Fess| 15.10 unterstützt OpenSearch 3.9.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. + Details finden Sie in den Release Notes. + +Vorbereitung vor dem Upgrade +============================== + +Überprüfung der Versionskompatibilität +--------------------------------------- + +Überprüfen Sie die Kompatibilität zwischen der Zielversion und der aktuellen Version des Upgrades. + +- `Release Notes `__ +- :doc:`prerequisites` - Systemvoraussetzungen für |Fess| 15.10 (Java- und OpenSearch-Version) + +Planung der Ausfallzeit +------------------------ + +Die Upgrade-Arbeiten erfordern einen Systemstopp. Planen Sie die Ausfallzeit unter Berücksichtigung folgender Punkte: + +- Backup-Zeit: 10 Minuten ~ mehrere Stunden (abhängig vom Datenvolumen) +- Upgrade-Zeit: 10 ~ 30 Minuten +- Funktionsprüfungszeit: 30 Minuten ~ 1 Stunde +- Pufferzeit: 30 Minuten + +**Empfohlene Wartungszeit**: Insgesamt 2 ~ 4 Stunden + +Schritt 1: Daten-Backup +======================== + +Erstellen Sie vor dem Upgrade ein Backup aller Daten. + +Backup der Konfigurationsdaten +------------------------------- + +1. **Backup über die Verwaltungsseite** + + 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 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 bis 15.8; 15.10 ergänzt den Index ``tag_type``, der die Benutzer-Tags + enthält, sodass es 26 sind + - ``fess_user.bulk`` - Benutzer, Rollen und Gruppen + - ``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``. Stammt die Sicherung von 15.10 oder neuer und werden Benutzer-Tags verwendet, laden Sie zusätzlich ``fess_config.bulk`` herunter, da der Index ``tag_type`` mit den Benutzer-Tags nicht in ``fess_basic_config.bulk`` enthalten ist (siehe :doc:`../admin/tagtype-guide`). + + .. note:: + + Protokolldaten wie Suchanfragenprotokolle und Klickprotokolle (``search_log.ndjson``, ``click_log.ndjson``, + ``favorite_log.ndjson``, ``user_info.ndjson``; 15.10 bietet zusätzlich ``chat_log.ndjson`` an) + können ebenfalls von derselben Seite heruntergeladen werden. + 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** + + ZIP-Version:: + + $ 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-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 ZIP-Version befinden sich die entsprechenden Einstellungen in ``bin/fess.in.sh``. + +3. **Angepasste Konfigurationsdateien** + + Falls angepasste Konfigurationsdateien vorhanden sind, erstellen Sie auch von diesen Backups:: + + $ cp /path/to/fess/app/WEB-INF/classes/log4j2.xml /backup/ + $ cp /path/to/fess/lib/classes/tomcat_config.properties /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 +---------------------- + +Erstellen Sie ein Backup der OpenSearch-Indexdaten. + +Methode 1: Verwendung der Snapshot-Funktion (empfohlen) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Verwenden Sie die Snapshot-Funktion von OpenSearch für das Backup der Indizes. + +.. note:: + + Um ein Dateisystem-Repository (``fs``) zu registrieren, müssen Sie zuvor in der ``opensearch.yml`` von OpenSearch + das Zielverzeichnis für das Backup unter ``path.repo`` angeben und OpenSearch neu starten. + +1. Repository-Konfiguration:: + + $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup" -H 'Content-Type: application/json' -d' + { + "type": "fs", + "settings": { + "location": "/backup/opensearch/snapshots" + } + }' + +2. Snapshot-Erstellung:: + + $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup/snapshot_1?wait_for_completion=true" + +3. Snapshot-Überprüfung:: + + $ curl -X GET "http://localhost:9200/_snapshot/fess_backup/snapshot_1" + +Methode 2: Backup des gesamten Verzeichnisses +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Stoppen Sie OpenSearch und erstellen Sie ein Backup des Datenverzeichnisses. + +:: + + $ sudo systemctl stop opensearch + $ sudo tar czf /backup/opensearch-data-$(date +%Y%m%d).tar.gz /var/lib/opensearch/data + $ sudo systemctl start opensearch + +Backup der Docker-Version +-------------------------- + +Die OpenSearch-Daten werden in Docker-Volumes gespeichert. ``compose-opensearch3.yaml`` definiert zwei Volumes: +``search01_data`` für Indexdaten und ``search01_dictionary`` für Wörterbuchdateien. + +.. note:: + + Die tatsächlichen Volume-Namen werden mit dem Compose-Projektnamen als Präfix versehen (standardmäßig der Name des + Verzeichnisses, das die Compose-Dateien enthält). Überprüfen Sie die genauen Namen mit folgendem Befehl:: + + $ docker volume ls + +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 + $ 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. + +Die 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 $(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 + $ sudo systemctl stop opensearch.service + +Docker-Version:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +.. warning:: + + Stellen Sie sicher, dass |Fess| gestoppt ist, bevor Sie mit Schritt 3 beginnen, und ersetzen Sie + weder das Paket noch die Dateien eines |Fess|, das noch läuft. Nachdem das DEB-Paket eines + laufenden 15.8-|Fess| durch das von 15.10 ersetzt worden war, antwortete die Suchseite mit + ``404``, bis |Fess| neu gestartet wurde. Die Paketversionen prüfen Sie mit + ``systemctl status fess.service``. + +Schritt 3: Installation der neuen Version +========================================== + +Die Vorgehensweise unterscheidet sich je nach Installationsmethode. + +ZIP-Version +------------------ + +1. Neue Version herunterladen und entpacken:: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.zip + $ unzip fess-15.10.0.zip + + .. note:: + + Die Archivversion von |Fess| wird ausschließlich im ZIP-Format bereitgestellt + (``fess-15.10.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.10.0/app/WEB-INF/conf/ + $ cp /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.10.0/app/WEB-INF/classes/ + $ cp /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.10.0/bin/ + + .. warning:: + + Unverändert kopiert behalten ``fess_config.properties`` und ``fess.in.sh`` ihre alten Werte, + auch solche, deren Standardwert sich in 15.10 geändert hat: Danach angelegte Jobs verwenden + zum Beispiel standardmäßig Groovy. Vergleichen Sie jede Datei vor den letzten beiden Befehlen + mit der Datei in ``fess-15.10.0`` und übernehmen Sie nur die Werte, die Sie selbst geändert + haben. Was zu prüfen ist, beschreibt :ref:`upgrade-159-carried-over-config`. + +3. Falls Sie Anpassungen vorgenommen haben, kopieren Sie zusätzlich Folgendes:: + + # Tomcat-Einstellungen (die SAML-Einstellung tomcat.sameSiteCookies=none steht hier) + $ cp /path/to/old-fess/lib/classes/tomcat_config.properties /path/to/fess-15.10.0/lib/classes/ + # Installierte Plugins + $ cp -r /path/to/old-fess/app/WEB-INF/plugin/. /path/to/fess-15.10.0/app/WEB-INF/plugin/ + # Selbst hochgeladene statische Themes (ein Verzeichnis pro Theme; nie bootstrap) + $ cp -r /path/to/old-fess/app/themes/ /path/to/fess-15.10.0/app/themes/ + + .. warning:: + + Ohne die ``tomcat_config.properties`` der alten Installation fällt ``tomcat.sameSiteCookies`` + stillschweigend auf den Standardwert ``lax`` zurück, und die SAML-Anmeldung funktioniert nicht + mehr (siehe :ref:`upgrade-159-saml`). Die ausgelieferte Datei ist in 15.8.0 und 15.10 + identisch, sodass sie unverändert kopiert werden kann. + + .. warning:: + + Kopieren Sie ``log4j2.xml`` nicht über die Datei von 15.10. Die Datei von 15.10 belässt den + Logger ``RequestLoggingFilter`` auf ``warn``, und eine aus 15.8 kopierte Datei entfernt diese + Einstellung: Bei der Log-Ebene DEBUG werden dann die Request-Header (einschließlich + ``Authorization``) und die Request-Parameter (einschließlich des im Anmeldeformular + eingegebenen Passworts) in das Log geschrieben. Vergleichen Sie beide Dateien mit ``diff`` und + übertragen Sie nur die Änderungen, die Sie selbst vorgenommen haben, erneut in die Datei von + 15.10. + + .. warning:: + + Kopieren Sie nicht das gesamte Verzeichnis ``app/themes/``. Es enthält auch ``bootstrap``, das + mit |Fess| mitgelieferte Theme, und wenn Sie es über das von 15.10 kopieren, wird die + Suchoberfläche von 15.10 durch die 15.8-Version des Themes ersetzt. Kopieren Sie nur die + Verzeichnisse von Themes, die Sie selbst erstellt haben. Für ein vom |Fess|-Projekt + veröffentlichtes Theme installieren Sie stattdessen die Version für 15.10 mit + ``bin/fess-setup install theme `` (siehe :doc:`fess-setup`). + + .. warning:: + + Kopieren Sie keine JSPs (``app/WEB-INF/view/``), die Sie über „Design" in der + Verwaltungsseite bearbeitet haben. Die Suchoberfläche von 15.10 ist ein statisches Theme und + verwendet diese JSPs nicht mehr; wohin solche Änderungen jetzt gehören, beschreibt + :ref:`upgrade-159-static-theme`. + + .. note:: + + Aus ``app/WEB-INF/plugin/`` kopierte Plugins wurden für die alte Version gebaut. Führen Sie + nach dem Kopieren in ``fess-15.10.0`` den Befehl ``bin/fess-setup upgrade plugins`` aus, um + jedes Plugin durch die für 15.10 gebaute Version zu ersetzen; siehe + :ref:`upgrade-plugin-versions`. + +4. Überprüfen Sie Konfigurationsdifferenzen und passen Sie diese bei Bedarf an + +RPM/DEB-Version +--------------- + +Installieren Sie das Paket der neuen Version:: + + # RPM + $ sudo rpm -Uvh fess-15.10.0.rpm + + # DEB + $ sudo dpkg -i fess-15.10.0.deb + +.. note:: + + 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. Eine von Ihnen geänderte + ``/etc/fess/fess_config.properties`` behält in 15.10 ihre alten Werte, genau wie eine im + ZIP-Verfahren kopierte Datei; siehe :ref:`upgrade-159-carried-over-config`. + +.. warning:: + + Bei der DEB-Version sind die Dateien unter ``/etc/fess`` (wie ``fess_config.properties`` und + ``tomcat_config.properties``) als Conffile registriert, ebenso wie ``/etc/default/fess``, + ``/etc/init.d/fess`` und ``/usr/lib/systemd/system/fess.service``. Beim ersten Upgrade von 15.8 + behandelt ``dpkg`` sie wie folgt: + + - Eine Datei, die Sie nie bearbeitet haben, wird ohne Rückfrage durch die Datei von 15.10 ersetzt. + - Bei einer Datei, die Sie bearbeitet haben, fragt ``dpkg`` nach. Behalten Sie Ihre Datei (die + Standardantwort oder ``--force-confold``), wird die Datei von 15.10 daneben als + ``.dpkg-dist`` abgelegt. Installieren Sie die neue Datei (``Y`` oder + ``--force-confnew``), wird Ihre Datei als ``.dpkg-old`` gesichert. + - ``dpkg -i`` und ``apt-get install -y`` bleiben bei der ersten Frage stehen, wenn niemand sie + beantworten kann. Übergeben Sie für ein unbeaufsichtigtes Upgrade ``--force-confold`` + (``--force-confdef`` vermeidet die Fragen ebenfalls), zum Beispiel + ``sudo dpkg --force-confold -i fess-15.10.0.deb`` oder + ``sudo apt-get install -y -o Dpkg::Options::=--force-confold ./fess-15.10.0.deb``. + + Sichern Sie ``/etc/fess`` in jedem Fall vorher (Schritt 1). Eine Datei, die Sie behalten, hat + weiterhin ihre Werte von 15.8; vergleichen Sie sie daher mit der ``.dpkg-dist``-Datei, statt sie + unverändert zu verwenden (siehe :ref:`upgrade-159-carried-over-config`). + ``/etc/fess/system.properties`` wird zur Laufzeit erzeugt und ist nicht Teil des Pakets, sodass + diese Datei nicht überschrieben wird. + +Docker-Version +-------------- + +1. Neue Version der Compose-Dateien herunterladen:: + + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose.yaml + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose-opensearch3.yaml + +2. Neue Images herunterladen:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull + +.. _upgrade-opensearch: + +Schritt 4: Upgrade von OpenSearch +================================= + +|Fess| 15.10 unterstützt OpenSearch 3.9.0. Wenn das verbundene OpenSearch älter ist, aktualisieren +Sie es anhand der folgenden Schritte. + +.. note:: + + Diese Anleitung gilt für die manuelle Verwaltung von OpenSearch bei der ZIP-Version und der RPM/DEB-Version. + 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.10 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. + + Ein mit OpenSearch 3.9.0 erstellter Snapshot lässt sich nicht in OpenSearch 3.8.0 oder älter + wiederherstellen. Bewahren Sie den vor dem Upgrade erstellten Snapshot für ein mögliches Rollback + auf. + +1. Installieren Sie die neue Version von OpenSearch + +2. Plugins neu installieren:: + + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + + .. note:: + + Die Versionen dieser Plugins müssen mit der verwendeten OpenSearch-Version übereinstimmen. + |Fess| 15.10 ist kompatibel mit OpenSearch 3.9.0. Bei Versionsabweichungen schlägt die + Plugin-Installation fehl. + + Die vier Plugins für |Fess| werden auf maven.codelibs.org veröffentlicht und daher per URL + installiert. Die Form ``groupId:artifactId:version`` von ``opensearch-plugin install`` sucht + nur in Maven Central. + +3. Wörterbuchverzeichnis unter das OpenSearch-Konfigurationsverzeichnis verschieben + + Ab OpenSearch 3.8.0 wird die Erstellung eines Index verweigert, wenn sich Wörterbuchdateien außerhalb des OpenSearch-Konfigurationsverzeichnisses befinden. + Wenn ``configsync.config_path`` gemäß der früheren Anleitung auf ein Verzeichnis außerhalb des Konfigurationsverzeichnisses zeigt, z. B. ``/var/lib/opensearch/data/config/`` (bei der ZIP-Version ``/path/to/opensearch/data/config/``), + kann |Fess| seine Indizes nicht erstellen und startet nicht. + Kopieren Sie bei der RPM/DEB-Version die Wörterbuchdateien wie folgt nach ``/etc/opensearch/dictionary/``:: + + $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary + $ sudo cp -a /var/lib/opensearch/data/config/. /etc/opensearch/dictionary/ + $ sudo chown -R opensearch:opensearch /etc/opensearch/dictionary + + Ändern Sie anschließend sowohl ``configsync.config_path`` in ``/etc/opensearch/opensearch.yml`` als auch ``FESS_DICTIONARY_PATH`` von |Fess| (``/etc/sysconfig/fess`` bei der RPM-Version, ``/etc/default/fess`` bei der DEB-Version) auf ``/etc/opensearch/dictionary/``. + Verwenden Sie bei der ZIP-Version ``config/dictionary/`` von OpenSearch. Details finden Sie unter :doc:`install-linux`. + +4. OpenSearch starten:: + + $ sudo systemctl start opensearch.service + +Schritt 5: Start der neuen Version +==================================== + +ZIP-Version:: + + $ cd /path/to/fess-15.10.0 + $ ./bin/fess -d -p /path/to/fess-15.10.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.10.0/fess.pid)`` beenden können. + +RPM/DEB-Version:: + + $ sudo systemctl start opensearch.service + $ sudo systemctl start fess.service + +Docker-Version:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +Schritt 6: Funktionsprüfung +============================ + +1. **Überprüfung der Protokolle** + + Stellen Sie sicher, dass keine Fehler vorliegen. + + 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. + +3. **Anmeldung in der Verwaltungsseite** + + Greifen Sie auf http://localhost:8080/admin zu und melden Sie sich mit dem Administratorkonto an. + +4. **Versionsüberprüfung** + + Klicken Sie in der Verwaltungsseite auf „Systeminformationen" → „Konfigurationsinformationen" und überprüfen Sie, + dass ``fess.version`` unter „Systemeigenschaften" die neue Version anzeigt. + +5. **Funktionsprüfung der Suche** + + Führen Sie auf der Suchseite eine Suche durch und überprüfen Sie, dass Ergebnisse korrekt zurückgegeben werden. + +Schritt 7: Neuerstellung des Index (empfohlen) +=============================================== + +Bei Major-Version-Upgrades wird die Neuerstellung des Index empfohlen. + +.. note:: + + Die folgenden Schritte führen den Crawl erneut aus; sie aktualisieren nicht das Index-Mapping + (Felddefinitionen). Wenn Sie eine Neuindizierung benötigen, die das Mapping aktualisiert — zum + Beispiel, um die Chunk-Vektor-Suche (semantische Suche) neu zu aktivieren —, führen Sie separat + die „Neuindizierung" unter „Systeminformationen" → „Wartung" in der Admin-Oberfläche aus. Siehe + :ref:`semantic-search-migration` (:doc:`../config/search-semantic`) für Details. + + Wenn Sie einen mit 15.8 oder älter erstellten Dokumentindex weiterverwenden, lesen Sie auch + :ref:`upgrade-reindex-new-fields`. + +.. warning:: + + OpenSearch 3.9.0 lehnt Wörterbucheinträge ab, die 15.8 noch akzeptiert hat, etwa denselben + ``mapping``-Eintrag, der zweimal gespeichert wurde, oder ein ``kuromoji``-Token, das ein + Leerzeichen enthält. Bei einem solchen Eintrag legt die „Neuindizierung" den neuen Dokumentindex + nicht an: ``fess.log`` meldet nur ``Failed to create index``, und der alte Index beantwortet + weiterhin die Suchen. Laden Sie das Wörterbuch unter „System" → „Wörterbuch" herunter, entfernen + Sie die doppelten oder ungültigen Zeilen, laden Sie es erneut hoch und führen Sie die + „Neuindizierung" erneut aus. Welche Einträge 15.10 nicht mehr speichert, steht unter + :ref:`upgrade-159-api-requests`. + +1. Überprüfen Sie bestehende Crawl-Zeitpläne +2. Führen Sie „Default Crawler" unter „System" → „Scheduler" aus +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. + +Upgrade von 15.8 auf 15.10 +========================= + +Wenn Sie von 15.8 aktualisieren, sind die folgenden Änderungen nicht abwärtskompatibel. Wenn Sie von +15.7 oder früher aktualisieren, gelten sie ebenfalls für Sie: Lesen Sie alle Abschnitte von +„Entfernung des eingebetteten OpenSearch" bis „Neue Felder und Kana-Normalisierung auf einen +vorhandenen Dokumentindex anwenden" (das eingebettete OpenSearch, die Skript-Engine, die S3- und +SSO-Plugins, der Job Index Exporter und so weiter) und danach „Migrationsaufgaben speziell für 15.10" +am Ende dieser Seite. + +Entfernung des eingebetteten OpenSearch +--------------------------------------- + +Bis 15.8 startete |Fess| einen OpenSearch-Knoten in der eigenen JVM, wenn ``bin/fess`` ohne +gesetzte ``SEARCH_ENGINE_HTTP_URL`` aufgerufen wurde. Diese Konfiguration entfällt in 15.10: Die +Suchmaschine ist immer ein eigener Server. + +``bin/fess.in.sh`` setzt jetzt standardmäßig ``SEARCH_ENGINE_HTTP_URL=http://localhost:9200``. +Ist kein OpenSearch erreichbar, startet |Fess| nicht. ``bin/fess-setup install opensearch`` +richtet einen ein (nur Linux und Windows; für macOS gibt es keine offizielle OpenSearch- +Distribution, verwenden Sie dort Homebrew oder Docker). + +|Fess| benötigt außerdem einen ``FESS_DICTIONARY_PATH``, der mit ``configsync.config_path`` in der +``opensearch.yml`` dieses OpenSearch übereinstimmt; ohne ihn kann |Fess| seine Indizes nicht +anlegen. Das ``bin/fess.in.sh`` von 15.10 (unter Windows ``bin\fess.in.bat``) setzt ihn selbst, wenn +``opensearch/`` im |Fess|-Verzeichnis genau ein von ``bin/fess-setup install opensearch`` +installiertes OpenSearch enthält. Für jedes andere OpenSearch setzen Sie ihn wie in +:doc:`install-linux` oder :doc:`install-windows` beschrieben. + +Ebenfalls entfallen: + +- das Verzeichnis ``es/`` (``es/modules``, ``es/plugins`` und ``es/data``) +- ``-Dfess.es.dir`` und ``SEARCH_ENGINE_HOME`` +- ``bin/module.xml`` und ``bin/plugin.xml`` +- die Rückfalloptionen auf die alten ``elasticsearch.*``-Konfigurationsschlüssel + +Eine ältere Version als OpenSearch 3 verhindert nun ebenfalls den Start, während 15.8 nur einen +Fehler protokollierte und fortfuhr. Diese Versionen implementieren die ``_shard_doc``-Sortierung +nicht, auf die alle Operationen über vollständige Ergebnismengen angewiesen sind, und über HTTP +hängt eine solche Anfrage, statt fehlzuschlagen. + +.. warning:: + + Indexdaten aus einer eingebetteten Installation lassen sich nicht übernehmen. Richten Sie + einen neuen externen OpenSearch-Server ein, übertragen Sie die Einstellungen über die + Sicherungsseite im Administrationsbereich und crawlen Sie erneut. Die Sicherung umfasst + Crawl-Einstellungen, Benutzer und Protokolle, **nicht** die gecrawlten Dokumente. + +.. note:: + + Zwei Dinge sind zu beachten, wenn Sie eine 15.8-Sicherung auf dem neuen 15.10-Server + wiederherstellen: + + - Jobs werden nur wiederhergestellt, wenn sie neuer sind als die auf dem Server. Die mitgelieferten + Jobs, die Sie unter 15.8 nie bearbeitet haben, behalten daher ihre JavaScript-Fassung aus 15.10. + Ein Job, den Sie unter 15.8 bearbeitet oder angelegt haben, kommt mit der gespeicherten + Skript-Engine zurück, bei einem mitgelieferten Job ist das ``groovy``, und ohne das Plugin + ``fess-script-groovy`` schlägt er mit ``groovy is not found`` fehl. Installieren Sie das Plugin + oder stellen Sie solche Jobs auf JavaScript um; beides beschreibt :ref:`upgrade-159-script-engine`. + - Passwörter und Geheimnisse, die in den Einstellungen der Web-Authentifizierung, der + Crawl-Konfiguration und der Datenspeicher-Konfiguration gespeichert sind, werden mit + ``app.cipher.key`` verschlüsselt. Setzen Sie in der ``fess_config.properties`` des neuen + Servers den Wert der alten Installation, wie unter :ref:`upgrade-159-carried-over-config` + beschrieben; andernfalls lassen sie sich nicht entschlüsseln. + +Playwright-Crawler wird als Plugin ausgeliefert +----------------------------------------------- + +Der Playwright-Crawler und die Node.js-Programmdateien, die er ausführt, sind nicht mehr Teil +der Distribution. In ``fess-15.8.0.zip`` (457,1 MiB) belegte das Playwright-Treiberpaket mit den +Node.js-Programmdateien 204,3 MiB. + +Wenn eine Crawl-Konfiguration den Playwright-Client benennt, etwa mit +``client.crawlerClients=playwright:http://.*`` in ihren Konfigurationsparametern, installieren +Sie sowohl das Plugin als auch Node.js. Das Plugin lässt sich auch über die Seite +**System > Plugin** im Administrationsbereich installieren. ``bin/fess.in.sh`` findet Node.js +und setzt ``PLAYWRIGHT_NODEJS_PATH``. + +:: + + $ bin/fess-setup install plugin fess-crawler-playwright + $ bin/fess-setup install nodejs + +Ohne das Plugin wird eine solche Konfiguration trotzdem gecrawlt, allerdings mit dem normalen +HTTP-Client, sodass Text, der erst durch JavaScript entsteht, nicht indexiert wird. Der Crawl-Job +endet dennoch erfolgreich, und es wird keine fehlgeschlagene URL erfasst. Bei jedem Crawl +protokolliert ``fess-crawler.log`` pro Crawl-Konfiguration eine Warnung, die das Plugin und die +beiden obigen Befehle nennt. + +Das Plugin ``fess-thumbnail-playwright``, das mit Playwright Thumbnails von HTML-Seiten erzeugt, +läuft ebenfalls auf Node.js. Wenn Sie es verwenden, installieren Sie Node.js mit +``bin/fess-setup install nodejs``; dieselbe Installation dient beiden Plugins. + +Wenn Sie weder den Playwright-Crawler noch das Plugin ``fess-thumbnail-playwright`` verwenden, ist +nichts zu tun. + +Google Cloud Storage wird als Plugin ausgeliefert +------------------------------------------------- + +Das Google-Cloud-Storage-SDK ist nicht mehr Teil der Distribution; ``gcs://``-Crawls und der +Speichertyp ``gcs`` kommen jetzt aus dem Plugin ``fess-storage-gcs``. Installieren Sie es über +die Seite **System > Plugin** in der Administrationsoberfläche oder mit dem folgenden Befehl. + +:: + + $ bin/fess-setup install plugin fess-storage-gcs + +``gcs`` ist auch aus dem ausgelieferten ``crawler.file.protocols`` verschwunden, das nun +``file,smb,smb1,ftp`` lautet; das Plugin fügt es bei der Installation wieder hinzu. Bis dahin +wird eine Datei-Crawl-Konfiguration, deren Pfad mit ``gcs:`` beginnt, als Warnung +protokolliert und liefert nichts. Eine aktualisierte Installation behält ihr eigenes +``crawler.file.protocols``, der Pfad wird also weiterhin akzeptiert, aber kein Crawler-Client +verarbeitet ihn; in einer neuen Installation ist ``gcs:`` kein konfiguriertes Protokoll, +sodass die Administrationsoberfläche das Speichern des Pfades ablehnt und ein früher +gespeicherter Pfad als lokaler Dateipfad gelesen wird. Auch die Speicherseite protokolliert +eine Warnung und zeigt den Fehler mit dem Namen des zu installierenden Plugins an, wo sie +vorher nur eine leere Dateiliste anzeigte. + +Ohne Google Cloud Storage ist nichts zu tun. Amazon S3 und S3-kompatible Speicher wie MinIO +sind auf dieselbe Weise als Plugin ausgeliefert; siehe den nächsten Abschnitt. + +Amazon S3 wird als Plugin ausgeliefert +-------------------------------------- + +Das AWS-SDK ist nicht mehr Teil der Distribution; ``s3://``-Crawls und die Speichertypen +``s3`` und ``s3_compat`` kommen jetzt aus dem Plugin ``fess-storage-s3``. Installieren Sie es +über die Seite **System > Plugin** in der Administrationsoberfläche oder mit dem folgenden +Befehl. + +:: + + $ bin/fess-setup install plugin fess-storage-s3 + +``s3`` ist auch aus dem ausgelieferten ``crawler.file.protocols`` verschwunden, das nun +``file,smb,smb1,ftp`` lautet; das Plugin fügt es bei der Installation wieder hinzu. +``storage.type`` hat weiterhin den Standardwert ``auto``, der ohne gesetzten Endpunkt zu S3 +aufgelöst wird; die Speicherseite in der Administrationsoberfläche funktioniert daher erst +nach der Installation des Plugins, auch wenn Sie ``s3`` nie selbst angegeben haben. Ihre +``storage.*``-Werte bleiben erhalten, weil sie in ``WEB-INF/conf/system.properties`` liegen, +und ein vorhandenes ``crawler.file.protocols`` wird durch das Upgrade ebenfalls nicht ersetzt. + +Ohne Amazon S3 oder S3-kompatible Speicher wie MinIO ist nichts zu tun. + +Die SSO-Authentifizierung wird als Plugins ausgeliefert +------------------------------------------------------- + +Keiner der vier SSO-Authentifikatoren ist mehr Teil der Distribution; jeder Wert von +``sso.type`` kommt jetzt aus einem eigenen Plugin, das auch die benötigte +Identitätsbibliothek mitbringt: ``saml`` aus ``fess-sso-saml``, ``spnego`` aus +``fess-sso-spnego``, ``entraid`` (und das alte ``aad``) aus ``fess-sso-entraid`` und ``oic`` +aus ``fess-sso-oidc``. Beachten Sie das letzte Paar: das Plugin heißt ``fess-sso-oidc``, +während der Wert von ``sso.type`` weiterhin ``oic`` lautet; das ist die einzige Stelle, an der +sich beide unterscheiden. Installieren Sie das benötigte Plugin über die Seite +**System > Plugin** in der Administrationsoberfläche oder mit dem folgenden Befehl. + +:: + + $ bin/fess-setup install plugin fess-sso-saml + +Ihre Einstellungen bleiben erhalten, weil ``sso.type`` und die Schlüssel ``saml.*``, +``spnego.*``, ``entraid.*``, ``aad.*`` und ``oic.*`` in ``WEB-INF/conf/system.properties`` +liegen. Auch „System" → „Allgemein" auf der Verwaltungsseite bietet weiterhin alle vier Typen +an und zeigt weiterhin deren Einstellungen, weil ein Plugin keine JSP bereitstellen kann; auf +dieser Seite weist also nichts auf ein fehlendes Plugin hin. + +Bis das Plugin installiert ist, wird eine Anfrage an ``/sso/`` zur Anmeldeseite +zurückgeleitet, die den fehlgeschlagenen SSO-Login meldet, und niemand kann sich über SSO +anmelden. 15.10 protokolliert in ``fess.log`` eine Warnung mit dem Namen der gesuchten +Komponente und des Plugins, das sie bereitstellt, wo bis 15.8 auf keiner Log-Ebene etwas +ausgegeben wurde. + +Das ``oic``-Plugin ist strenger als der Authentifikator von 15.8. ``oic.token.server.url`` muss +HTTPS verwenden (``http`` nur für ``localhost``, ``127.x.x.x`` und ``::1``), die Claims ``aud`` +und ``exp`` des ID-Tokens werden geprüft, und ``iss`` wird geprüft, wenn der neue Schlüssel +``oic.issuer`` gesetzt ist. Einzelheiten finden Sie unter :doc:`../config/sso-oidc`. + +In 15.8 konnte für ``oic.token.server.url`` eine ``http``-URL mit beliebigem Host angegeben werden. In 15.10 wird ``http`` zu einem Docker-Compose-Servicenamen (z. B. ``http://keycloak:8080/...``) oder einem internen Hostnamen abgelehnt, auch wenn dieser auf denselben Rechner zeigt. Die Anmeldung schlägt dann fehl, und ``fess.log`` enthält eine Warnung, die mit ``Failed to process the OpenID Connect callback: oic.token.server.url must be https`` beginnt. Stellen Sie den Token-Endpunkt vor dem Update auf eine HTTPS-URL um. + +Setzen Sie außerdem ``oic.issuer`` auf den ``issuer``-Wert aus dem Discovery-Dokument des OP. Ohne diesen Wert wird ``iss`` nicht geprüft, und bei der ersten Anmeldung nach dem Start wird eine Warnung protokolliert. Das Setzen von ``oic.issuer`` lockert die HTTPS-Regel nicht. + +Ohne SSO ist nichts zu tun, also wenn ``sso.type`` den Wert ``none`` hat oder nicht gesetzt ist. + +.. _upgrade-159-script-engine: + +Die eingebaute Skript-Engine wechselt von Groovy zu JavaScript +-------------------------------------------------------------- + +Bis 15.8 war die eingebaute Skript-Engine Groovy, und ``job.default.script`` hatte den +Standardwert ``groovy``. In 15.10 ist die eingebaute Engine JavaScript und der Standardwert +``javascript``. Groovy ist nicht mehr fest eingebaut, sondern wird vom Plugin +``fess-script-groovy`` bereitgestellt, das installiert sein muss, damit der ``scriptType`` +``groovy`` aufgelöst werden kann. + +Ein Upgrade ändert die mit einer Einstellung gespeicherte Engine nicht, und eine vor 15.10 +gespeicherte Einstellung ohne Engine gilt als ``groovy``. Ohne das Plugin funktioniert Folgendes +nicht mehr: + +- Als ``groovy`` gespeicherte geplante Jobs. **Das gilt auch für die Jobs, die 15.8 selbst angelegt + hat:** Default Crawler, Suggest Indexer, Config Reloader, Log Aggregator, Doc Purger und die + übrigen mitgelieferten Jobs sind alle als ``groovy`` gespeichert, und 15.10 legt beim Start nur + die mitgelieferten Jobs an, die noch nicht existieren, lässt diese also unverändert. Jeder dieser + Jobs schlägt bei jeder planmäßigen Ausführung fehl, sodass Default Crawler nicht mehr crawlt. Bei + den meisten mitgelieferten Jobs ist „Protokollierung" ausgeschaltet; ihre Fehler erscheinen dann + nicht im Jobprotokoll, sondern nur als Warnungen ``Failed to execute job`` in ``fess.log``. +- Web- und Datei-Crawl-Konfigurationen mit Feldskripten (``field.script.``) in + „Konfigurationsparameter". Jedes Dokument einer solchen Konfiguration schlägt mit einer + ``ScriptEngineException`` fehl und wird als fehlgeschlagene URL erfasst, während der Crawl-Job + selbst erfolgreich endet. +- Datenspeicher-Konfigurationen mit einem „Skript". Werte, die nicht nur aus einem Parameternamen + bestehen, können nicht ausgewertet werden; siehe :doc:`../config/datastore/ds-overview`. +- Dokument-Boost-Regeln. Eine solche Regel boostet nichts. +- Pfad-Mappings, deren „Ersetzung" mit ``groovy:`` beginnt. Ein solches Mapping wird nicht + angewendet, und URLs bleiben unverändert. + +Suchen Sie nach dem ersten Start in ``fess.log`` nach einer Warnung, die mit +``Settings use the script engine groovy, which is not registered`` beginnt. |Fess| prüft die +obigen Einstellungen einmal beim Start und gibt für jede Art an, wie viele davon eine Engine +verwenden, die kein Plugin bereitstellt. Die Warnung nennt außerdem ``job.default.script``, wenn +eine aus 15.8 übernommene ``fess_config.properties`` noch ``groovy`` setzt; dann verwenden auch +nach dem Upgrade angelegte Jobs Groovy (siehe :ref:`upgrade-159-carried-over-config`). Es gibt zwei +Wege: + +- Installieren Sie das Plugin und starten Sie |Fess| neu. Die gespeicherten Groovy-Skripte laufen + dann unverändert, und die Warnung wird nicht mehr protokolliert. Das Plugin lässt sich auch über + die Verwaltungsseite unter „System" → „Plugins" installieren. + + :: + + $ bin/fess-setup install plugin fess-script-groovy + +- Stellen Sie jede Einstellung auf JavaScript um. Schreiben Sie zuerst jede Syntax um, die nur + Groovy akzeptiert, und wählen Sie dann JavaScript: + + - Geplante Jobs: Stellen Sie unter „System" → „Scheduler" die „Ausführungsmethode" auf + ``javascript``. Die Skripte der mitgelieferten Jobs sind unverändert gültiges JavaScript, mit + zwei Ausnahmen: Thumbnail Purger verwendet das Groovy-``long``-Literal ``1000L``, das + JavaScript ablehnt (schreiben Sie ``1000``), und Index Exporter benötigt die in + :ref:`upgrade-159-index-exporter` beschriebene Änderung. Ein JavaScript-Array-Literal wird + automatisch in ein Java-``String[]`` umgewandelt, sodass die Umwandlungen ``as String[]`` der + Groovy-Schreibweise entfallen: + + :: + + return container.getComponent("crawlJob").logLevel("info").webConfigIds(["1", "2"]).fileConfigIds(["1"]).dataConfigIds([]).execute(executor); + + - Web- und Datei-Crawl-Konfigurationen: Ergänzen Sie ``config.script.type=javascript`` in + „Konfigurationsparameter". + - Datenspeicher-Konfigurationen: Ergänzen Sie ``script_type=javascript`` in „Parameter". + - Dokument-Boost-Regeln: Stellen Sie „Skripttyp" auf ``javascript``. + - Pfad-Mappings: Beginnen Sie die „Ersetzung" mit ``javascript:`` statt mit ``groovy:``. + - ``job.default.script``: Setzen Sie den Wert in einer aus 15.8 übernommenen + ``fess_config.properties`` auf ``javascript``. + +``crawler.default.script`` wurde entfernt +----------------------------------------- + +``crawler.default.script`` gibt es in ``fess_config.properties`` nicht mehr. Entfernen Sie die +Einstellung; ein unter diesem Namen verbliebener Wert hat keine Wirkung. + +Das Crawl-Protokoll ``storage`` wurde entfernt +---------------------------------------------- + +``storage`` wird in ``crawler.file.protocols`` nicht mehr akzeptiert; der mitgelieferte Wert +lautet ``file,smb,smb1,ftp``. Verwenden Sie stattdessen ``s3`` und stellen Sie jede +Datei-Crawl-Konfiguration, deren Pfad mit ``storage:`` beginnt, auf einen ``s3:``-Pfad um. +``s3`` benötigt das Plugin ``fess-storage-s3``. + +.. _upgrade-159-index-exporter: + +Der Job Index Exporter verweist auf ein entferntes Paket +-------------------------------------------------------- + +15.10 enthält die ``org.opensearch``-Klassen nicht mehr; die Query-Builder, die Job-Skripte +verwenden, liegen jetzt unter ``org.codelibs.fesen.opensearch``. Das Skript, das 15.8 für den Job +Index Exporter gespeichert hat, verweist auf ``org.opensearch.index.query.QueryBuilders``, und das +Upgrade ersetzt es nicht. Der Job schlägt daher auch mit installiertem ``fess-script-groovy`` fehl. +Er wird deaktiviert und ohne Zeitplan ausgeliefert und betrifft Sie also nur, wenn Sie ihn +ausführen. Öffnen Sie ihn unter „System" → „Scheduler" und ändern Sie das Paket in seinem Skript +auf das von 15.10: + +:: + + return new org.codelibs.fess.job.IndexExportJob().query(org.codelibs.fesen.opensearch.index.query.QueryBuilders.matchAllQuery()).execute() + +Ändern Sie eigene Skripte, die ``org.opensearch.index.query`` verwenden, auf dieselbe Weise. +Weitere Abfragebeispiele finden Sie unter :doc:`../config/admin-index-export`. + +.. _upgrade-159-carried-over-config: + +Aus 15.8 übernommene Konfigurationsdateien +------------------------------------------ + +Das ZIP-Verfahren in Schritt 3 kopiert ``fess_config.properties`` und ``bin/fess.in.sh`` aus der +alten Installation, und ein RPM-Upgrade behält eine von Ihnen geänderte +``/etc/fess/fess_config.properties`` (die Datei von 15.10 wird daneben als +``fess_config.properties.rpmnew`` abgelegt). Ein DEB-Upgrade verhält sich ebenso, wenn Sie bei der +Rückfrage Ihre Version behalten (die Datei von 15.10 wird daneben als +``fess_config.properties.dpkg-dist`` abgelegt). In jedem Fall läuft 15.10 anschließend mit den +Werten von 15.8, auch dort, wo sich der ausgelieferte Wert in 15.10 geändert hat. Prüfen Sie +mindestens die folgenden Schlüssel. + +.. list-table:: + :header-rows: 1 + + * - Schlüssel + - 15.8.0 + - 15.10 + - Folge, wenn der Wert von 15.8 bleibt + * - ``job.default.script`` + - ``groovy`` + - ``javascript`` + - Unter „System" → „Scheduler" angelegte Jobs verwenden standardmäßig ``groovy`` und schlagen + ohne das Plugin ``fess-script-groovy`` fehl. + * - ``job.template.script`` + - Groovy-Schreibweise mit ``as String[]`` + - JavaScript-Schreibweise + - Ein aus einer Crawl-Konfiguration angelegter Job erhält ein Groovy-Skript. + * - ``crawler.file.protocols`` + - ``file,smb,smb1,ftp,storage,s3,gcs`` + - ``file,smb,smb1,ftp`` + - Ein Pfad, der mit ``s3:`` oder ``gcs:`` beginnt, wird auch ohne das zugehörige Plugin + akzeptiert und beim Crawlen mit einer Warnung übersprungen. ``storage`` wird nicht mehr + unterstützt. + * - ``search_engine.http.url`` + - ``http://localhost:9201`` + - ``http://localhost:9200`` + - Wird verwendet, wenn ``SEARCH_ENGINE_HTTP_URL`` nicht gesetzt ist, etwa in einer aus 15.8 + kopierten ``bin/fess.in.sh``, in der Sie es nicht gesetzt haben. |Fess| sucht OpenSearch + dann auf Port 9201, dem Port des in 15.10 entfernten eingebetteten OpenSearch. + * - ``jvm.crawler.options``, ``jvm.thumbnail.options`` + - ``-Djcifs.smb.client.*``, ``-Djcifs.smb1.smb.client.*`` + - ``-Djcifs.client.*`` + - Die SMB-Timeouts bleiben auf den Standardwerten von jcifs; siehe :ref:`upgrade-159-jcifs`. + * - ``response.headers`` + - Enthält die Zeile ``text/html=Content-Security-Policy: reflected-xss block`` + - Zeile entfernt + - Die Anmeldeseite, die Administrationsoberfläche und die übrigen von |Fess| selbst gerenderten + Seiten werden mit einem Header ``Content-Security-Policy: reflected-xss block`` ausgeliefert, + den kein Browser kennt, und die Browser-Konsole meldet + ``Unrecognized Content-Security-Policy directive 'reflected-xss'``. Der Header schränkt nichts + ein. Entfernen Sie die Zeile, wie unten beschrieben. + * - ``app.encrypt.property.pattern`` + - ``.*password|.*key|.*token|.*secret`` + - ``.*password|.*passphrase|.*key|.*token|.*secret`` + - Ein Parameter, dessen Name auf ``passphrase`` endet (zum Beispiel ``ssh.passphrase`` einer + Datenspeicher-Konfiguration), wird im Klartext gespeichert. Ein früher gespeicherter Wert + bleibt im Klartext, bis die Einstellung mit dem Muster von 15.10 erneut gespeichert wird. + * - ``index.backup.log.targets`` + - ``click_log.ndjson,favorite_log.ndjson,search_log.ndjson,user_info.ndjson`` + - ``chat_log.ndjson,click_log.ndjson,favorite_log.ndjson,search_log.ndjson,user_info.ndjson`` + - Die Seite „Systeminformationen" → „Sicherung" bietet ``chat_log.ndjson`` nicht an. + * - ``index.export.exclude.fields`` + - ``cache`` + - ``cache,tag`` + - Das Feld ``tag``, das die Benutzer-Tags enthält, wird nicht mehr aus den Dateien + ausgeschlossen, die der Job Index Exporter schreibt. + * - ``crawler.default.script``, ``theme.allowed.archive.extensions``, + ``theme.assets.cache.max.age``, ``theme.assets.precompressed``, + ``rag.chat.message.max.length``, ``supported.uploaded.js.extentions``, + ``supported.uploaded.css.extentions``, ``supported.uploaded.media.extentions``, + ``supported.uploaded.files``, ``online.help.name.design`` + - Vorhanden + - Entfernt + - Keine Wirkung; entfernen Sie sie. + +Der mitgelieferte Wert von ``response.headers`` enthält in 15.0 bis 15.8 die Zeile +``text/html=Content-Security-Policy: reflected-xss block``. ``reflected-xss`` war eine Direktive eines +frühen Entwurfs von Content-Security-Policy, die Browser nicht mehr kennen; der Header schränkt daher +nichts ein und erzeugt nur den Fehler in der Konsole. 15.10 liefert die Zeile nicht mehr mit (die Zeilen +``X-XSS-Protection`` und ``X-Frame-Options`` bleiben unverändert), aber ein aus 15.8 übernommenes +``response.headers`` behält sie. Entfernen Sie in ``fess_config.properties`` nur diese Zeile aus +``response.headers``. Das ``\n\`` am Ende jeder Zeile setzt den Wert in der nächsten Zeile fort; wenn +Sie die ganze Zeile löschen, bleiben die übrigen unverändert:: + + text/html=Content-Security-Policy: reflected-xss block\n\ + +Setzen Sie ``response.headers`` stattdessen mit ``-Dfess.config.response.headers``, entfernen Sie +denselben Eintrag aus diesem Wert. + +Einer aus 15.8 kopierten ``bin/fess.in.sh`` fehlen außerdem zwei Dinge, die die Datei von 15.10 +enthält. Sie lässt ``SEARCH_ENGINE_HTTP_URL`` ungesetzt, sofern Sie es nicht selbst gesetzt haben, +während 15.10 ``http://localhost:9200`` setzt, und sie sucht nicht nach dem mit +``bin/fess-setup install nodejs`` installierten Node.js. Die Playwright-Plugins finden Node.js dann +nur, wenn Sie ``PLAYWRIGHT_NODEJS_PATH`` selbst setzen. + +Kopieren Sie keine der beiden Dateien vollständig, sondern gehen Sie von der mit 15.10 +ausgelieferten Datei aus und übertragen Sie die Werte, die Sie geändert haben. ``diff`` zeigt sie +an:: + + $ diff /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.10.0/app/WEB-INF/classes/fess_config.properties + $ diff /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.10.0/bin/fess.in.sh + +Vergleichen Sie bei einem RPM-Upgrade auf dieselbe Weise ``/etc/fess/fess_config.properties`` mit +``/etc/fess/fess_config.properties.rpmnew`` und bei einem DEB-Upgrade mit +``/etc/fess/fess_config.properties.dpkg-dist``. Eine ``fess_config.properties``, die Sie nie +bearbeitet haben, wird bei einem DEB-Upgrade durch die Datei von 15.10 ersetzt (siehe Schritt 3); +dort beginnen Sie also mit den Werten von 15.10. + +``app.cipher.key`` ist der eine Wert, den Sie übernehmen müssen, obwohl 15.10 ihn nicht geändert hat. +Es ist der Schlüssel, der die Passwörter und Geheimnisse verschlüsselt, die in den Parametern der +Web-Authentifizierung, der Crawl-Konfigurationen und der Datenspeicher-Konfigurationen gespeichert +sind. Läuft die neue Installation mit einem anderen Schlüssel als dem, mit dem sie gespeichert +wurden, weil Sie die ausgelieferte ``fess_config.properties`` übernommen oder eine Sicherung auf +einem neuen Server wiederhergestellt haben, lassen sie sich nicht entschlüsseln: ``fess-crawler.log`` +protokolliert eine ``CipherFailureException``, und ein Crawl, der eine solche Konfiguration +einschließt, kann nichts indexieren. + +.. note:: + + |Fess| 15.10 speichert auch das ``password`` der Web- und Datei-Authentifizierung mit ``app.cipher.key`` + verschlüsselt, sodass ``fess_basic_config.bulk`` und ``fess_config.bulk`` einer Sicherung die verschlüsselten Werte + enthalten. Übernehmen Sie beim Wiederherstellen auf einer anderen Installation denselben ``app.cipher.key``; mit + einem anderen Schlüssel schlagen Crawls, die diese Zugangsdaten verwenden, mit einem Fehler fehl. Eine Sicherung, + die vor 15.10 erstellt wurde, enthält sie im Klartext und funktioniert weiterhin (siehe + :doc:`../admin/backup-guide`). + +.. _upgrade-159-jcifs: + +SMB-Timeouts verwenden die Eigenschaftsnamen von jcifs 3 +-------------------------------------------------------- + +jcifs, die Bibliothek, mit der |Fess| SMB-Dateiserver crawlt, hat ihre Eigenschaften in Version 3 +umbenannt: Aus ``jcifs.smb.client.*`` wurde ``jcifs.client.*``, und die separaten Namen +``jcifs.smb1.smb.client.*`` für SMB1 gingen in denselben Eigenschaften auf. Bis 15.8 übergaben +``jvm.crawler.options`` und ``jvm.thumbnail.options`` noch die alten Namen, die jcifs ignoriert; +SMB-Crawls liefen daher mit den Standardwerten von jcifs. 15.10 übergibt die neuen Namen: + +:: + + -Djcifs.client.responseTimeout=30000 + -Djcifs.client.soTimeout=35000 + -Djcifs.client.connTimeout=60000 + -Djcifs.client.sessionTimeout=60000 + +Verbindungs- und Sitzungs-Timeout wirken damit zum ersten Mal und steigen vom jcifs-Standardwert +von 35 Sekunden auf 60 Sekunden: Ein Crawl wartet jetzt bis zu 60 Sekunden auf einen SMB-Server, +der nicht antwortet. Antwort- und Socket-Timeout entsprechen den Standardwerten von jcifs und +ändern sich daher nicht. + +Wenn Sie diese Timeouts geändert haben, benennen Sie sie in beiden Optionen um. Unter den alten +Namen hatten sie auch in 15.8 keine Wirkung. Eine aus 15.8 übernommene ``fess_config.properties`` +behält die alten Namen und damit die Standardwerte von jcifs. + +Vier wirkungslose Eigenschaften wurden entfernt +----------------------------------------------- + +Die folgenden Schlüssel gibt es in ``fess_config.properties`` nicht mehr. |Fess| hat sie nie aus +dieser Datei gelesen; ein unter diesen Namen verbliebener Wert hat also wie bisher keine Wirkung. + +- ``theme.allowed.archive.extensions`` +- ``theme.assets.cache.max.age`` +- ``theme.assets.precompressed`` +- ``rag.chat.message.max.length`` + +Die Grenze, die ``rag.chat.message.max.length`` festlegt, gilt weiterhin, wird aber als +Systemeigenschaft gelesen: Setzen Sie sie in ``app/WEB-INF/conf/system.properties`` oder mit +``-Dfess.system.rag.chat.message.max.length``, wie in :doc:`../config/rag-chat` beschrieben. + +.. _upgrade-159-static-theme: + +Die Suchoberfläche ist jetzt ein statisches Theme +------------------------------------------------- + +Die Suchoberfläche wird vom statischen Theme ``bootstrap`` ausgeliefert, das mit |Fess| mitgeliefert +wird, sofern kein anderes Theme ausgewählt ist. Das gilt für ``/``, ``/search``, ``/advance``, +``/help``, ``/profile``, ``/cache``, ``/chat`` und die Fehlerseiten. Bis 15.8 waren diese Seiten +JSPs, sofern kein Standard-Theme festgelegt war. + +Die Umstellung erfolgt auch beim Upgrade. Eine 15.8-Installation, die nie ein Standard-Theme +festgelegt hat, hat kein ``theme.default`` in ``system.properties`` und zeigt daher nach dem Upgrade +das statische Theme; dabei wird nichts in die Konfiguration geschrieben und nichts protokolliert. Es +gibt keine Einstellung, die die JSP-Suchoberfläche zurückbringt. Wenn Sie in 15.8 ein Standard-Theme +festgelegt hatten, bleibt diese Einstellung erhalten; installieren Sie die 15.10-Version des Themes +(``bin/fess-setup install theme ``), denn ein Standard, der ein nicht installiertes Theme nennt, +fällt mit einer Warnung in ``fess.log`` auf ``bootstrap`` zurück. + +Wenn Sie die JSPs, CSS oder Bilder der Suchoberfläche geändert haben, über „Seitengestaltung" in der +Verwaltungsoberfläche oder in einem JAR-Theme-Plugin, sind diese Änderungen nicht mehr sichtbar. +Nehmen Sie sie in einem statischen Theme vor: Kopieren Sie das mitgelieferte Theme und ändern Sie +die Kopie, wie unter :ref:`theme-customize-bundled` beschrieben, oder installieren Sie ein +veröffentlichtes Theme über „System" → „Theme" in der Verwaltungsoberfläche oder mit +``bin/fess-setup install theme ``. Ein eigenes Aussehen pro virtuellem Host ist jetzt ein +statisches Theme, das nach dem virtuellen Host benannt ist; siehe +:doc:`../config/security-virtual-host`. + +Zwei weitere Dinge entfallen: + +- Die Anmeldeseite pro virtuellem Host. Bis 15.8 kopierte das Speichern von „System" → „Allgemein" + JSPs einschließlich der Anmeldeseite nach ``WEB-INF/view//``, wo jeder + virtuelle Host seine eigene Kopie bearbeiten konnte. 15.10 erstellt diese Kopien nicht mehr. Die + Anmeldeseite (``/login/``) ist weiterhin eine JSP, aber alle virtuellen Hosts erhalten dieselbe aus + ``WEB-INF/view/admin/login/``. Früher kopierte JSPs werden nicht verwendet. +- JAR-Theme-Plugins (``fess-theme-*``). Bei der Installation wird ein solches nur als allgemeines JAR + vom Typ ``jar`` abgelegt; kein Bildschirm ändert sich. Ein verbliebenes JAR löschen Sie auf der + Seite „System" → „Plugin" oder mit ``bin/fess-setup remove plugin `` (siehe + :doc:`../dev/theme-development`). + +Wenn die JSP-Suchergebnisse in 15.8 ein eigenes Feld anzeigten, fügen Sie dieses Feld zusätzlich zu +``query.additional.response.fields`` auch zu ``query.additional.api.response.fields`` hinzu. Das +statische Theme bezieht seine Ergebnisse von ``/api/v2/search``. ``query.additional.response.fields`` +fügt ein Feld nur zu den aus der Suchmaschine abgerufenen Feldern hinzu; die API gibt nur die Felder +zurück, die in ``query.additional.api.response.fields`` aufgeführt sind (siehe +:doc:`../config/search-advanced`). Ändern Sie außerdem das Theme so, dass es das Feld anzeigt. + +Was Clients sehen +~~~~~~~~~~~~~~~~~ + +Fehler werden jetzt direkt dargestellt, unter der angeforderten URL und mit dem tatsächlichen +HTTP-Status. Ein Browser (eine Anfrage, deren ``Accept``-Header ``text/html`` enthält) erhält die +Fehlerseite des Themes; jeder andere Client erhält einen einzeiligen ``text/plain``-Body (zum +Beispiel ``Not Found.`` für ``404``). Bis 15.8 antworteten die meisten Fehler mit einer +``302``-Weiterleitung auf eine ``/error/...``-Seite, die selbst ``200`` zurückgab. Überprüfen Sie +Monitoring, Health-Checks und Clients, die ``Location``-Headern folgen oder ``/error/``-URLs +erwarten. + +.. list-table:: + :header-rows: 1 + + * - Anfrage + - Bis 15.8 + - 15.10 + * - ``/go/`` mit fehlendem Parameter oder für ein nicht vorhandenes Dokument + - ``200`` oder ``302`` auf ``/error/`` + - ``400`` oder ``404`` + * - ``/thumbnail/`` mit fehlendem Parameter, für ein unbekanntes Dokument oder ohne Vorschaubild + - ``200`` oder ``302`` + - ``400`` oder ``404`` + * - ``/sso/metadata`` und ``/sso/logout``, wenn der konfigurierte SSO-Typ sie nicht verarbeitet + - ``302`` auf ``/error/badrequest/`` + - ``400`` + * - ``/api/v1/*``, ``/json`` und jede unbekannte URL + - ``302`` auf ``/error/notfound/`` + - ``404`` + * - Eine nicht abgefangene Ausnahme, auch in der Admin-API + - ``302`` auf ``/error/systemerror/`` + - ``500`` mit dem Body ``System Error.`` (kein JSON) + * - ``/error/notfound/``, ``/error/badrequest/``, ``/error/systemerror/`` selbst + - ``200`` + - ``404``, ``400``, ``500`` + +Mit ``login.required=true`` leiten die Suchseiten einen anonymen Benutzer nicht mehr weiter. Sie +geben ``200`` mit dem Theme zurück, das den Benutzer zur Anmeldung auffordert, und stattdessen werden +die dahinterliegenden Daten verweigert: Jeder ``/api/v2/``-Endpunkt außer ``/health``, ``/auth/*`` +und ``/ui/config``, einschließlich ``/api/v2/search``, antwortet mit ``401``, bis sich der Benutzer +anmeldet. ``/go/``, ``/thumbnail/`` und ``/osdd`` leiten weiterhin zur Anmeldung weiter. Eine +Prüfung, die für eine anonyme Anfrage an ``/`` eine Weiterleitung erwartet, muss stattdessen +``/api/v2/search`` auf ``401`` testen. + +Die Suchoberfläche sucht außerdem über ``/api/v2/search``, sodass eine Suche protokolliert wird, +wenn diese API aufgerufen wird, nicht wenn ``/search`` angefordert wird. Ein Client, der kein +JavaScript ausführt, erhält die Seite ohne Ergebnisse. + +Das HTML der Suchoberfläche enthält ``X-Frame-Options: DENY`` und eine ``Content-Security-Policy`` mit +``frame-ancestors 'none'``, sodass keine andere Seite es in einem Frame anzeigen kann. Die +JSP-Suchoberfläche von 15.8 sendete ``X-Frame-Options: SAMEORIGIN`` (Standardwert von ``response.headers``) +und ließ sich in einem ``iframe`` auf einer Seite desselben Origins anzeigen. Wenn Sie die Suchoberfläche in +einem ``iframe`` desselben Origins eingebettet haben, setzen Sie ``theme.index.frame.ancestors`` in +``fess_config.properties`` (Standard: ``'none'``) auf ``'self'``. Für die Einbettung von einem anderen +Origin geben Sie stattdessen diesen Origin an (siehe :doc:`../dev/theme-development`). + +Die Seitengestaltung wurde entfernt +----------------------------------- + +[System > Seitengestaltung] ist nicht mehr Teil der Verwaltungsoberfläche. JSP-, CSS- und +Bilddateien der Suchoberfläche lassen sich dort nicht mehr bearbeiten. Um das Aussehen der +Suchoberfläche zu ändern, verwenden Sie ein statisches Theme (siehe :ref:`theme-customize-bundled`). + +Außerdem wurden die folgenden Schlüssel aus ``fess_config.properties`` entfernt. Ein unter diesen +Namen verbliebener Wert wird nicht verwendet. + +- ``supported.uploaded.js.extentions`` +- ``supported.uploaded.css.extentions`` +- ``supported.uploaded.media.extentions`` +- ``supported.uploaded.files`` +- ``online.help.name.design`` + +Die Rollen ``admin-design`` und ``admin-design-view`` gewähren keine Rechte mehr. Ein Benutzer, der +nur diese Rollen hat, gelangt nach der Anmeldung zur Suchoberfläche statt zur Verwaltungsoberfläche. + +``api.access.token.required`` wurde entfernt +-------------------------------------------- + +``api.access.token.required`` gibt es in ``fess_config.properties`` nicht mehr. Ein unter diesem +Namen verbliebener Wert hat keine Wirkung, auch in einer aus 15.8 übernommenen +``fess_config.properties``. Mit ``true`` lehnte die Einstellung jede API-Anfrage eines nicht +angemeldeten Benutzers ab. Da die Suchoberfläche jetzt über ``/api/v2/search`` sucht, hätte sie +anonymen Benutzern zudem eine Suchoberfläche ohne Ergebnisse gezeigt. + +Eine Installation, die sie auf ``true`` gesetzt hatte, beantwortet API-Anfragen anonymer Benutzer +jetzt wie die Suchoberfläche mit den Gastrollen. Um anonyme Benutzer von der Suche auszuschließen, +setzen Sie ``login.required=true``. Zugriffstoken funktionieren wie bisher: Eine Anfrage mit einem +registrierten Zugriffstoken erhält dessen Berechtigungen, eine Anfrage mit einem nicht registrierten +oder abgelaufenen Token wird abgelehnt. + +.. _upgrade-159-api-requests: + +Anfragen, die die API jetzt ablehnt +----------------------------------- + +15.10 lehnt die folgenden Anfragen ab, die 15.8 noch akzeptiert hat. Prüfen Sie die Clients und Skripte, die +Sie für 15.8 geschrieben haben. Die Admin-API beantwortet eine Ablehnung mit HTTP ``400`` und ``status`` +``1`` im Body. + +.. list-table:: + :header-rows: 1 + + * - Anfrage + - Bis 15.8 + - 15.10 + * - ``/api/v2/search`` mit ``facet.field`` oder ``facet.query`` und einem ``facet.size`` von ``0`` oder weniger oder einem ``facet.size`` bzw. ``facet.minDocCount``, der keine ganze Zahl ist + - ``200``, aber ein leeres Ergebnis: ``record_count`` ist ``0`` und ``partial`` ist ``true`` + - ``400`` (``invalid_request``). ``facet.size`` muss ``1`` oder größer sein + * - ``track_total_hits=false``. Ist ``query.track.total.hits`` auf ``false`` gesetzt, ist jede Suche betroffen + - ``200``, aber ohne Ergebnisse + - Die Suche wird abgelehnt (``/api/v2/search`` antwortet mit ``400`` und ``invalid_request``). ``true`` und positive ganze Zahlen funktionieren wie bisher + * - Ein Eintrag im Wörterbuch ``mapping`` oder ``kuromoji``, der einen vorhandenen Eintrag wiederholt und über die Admin-API angelegt oder geändert wird + - Wird gespeichert. Das Laden des Wörterbuchs schlägt danach fehl, wodurch die Suche ausfallen kann + - ``400`` + * - Ein Eintrag im Wörterbuch ``kuromoji``, dessen ``token`` ein Leerzeichen enthält oder dessen ``segmentation`` und ``reading`` eine unterschiedliche Anzahl durch Leerzeichen getrennter Teile haben und der über die Admin-API angelegt oder geändert wird + - Wird gespeichert. Das Laden des Wörterbuchs schlägt auf dieselbe Weise fehl + - ``400`` + * - ``DELETE /api/admin/searchlist/doc/{doc_id}``, das nichts löscht: eine ``doc_id``, die nicht existiert, oder ein Wert, der keine ``doc_id`` ist, etwa die ``_id`` aus der Dokumentliste + - ``200`` (``status`` ``0``); das Dokument wird nicht gelöscht + - ``400`` + * - Ein Rollen- oder Gruppenname in ``roles`` oder ``groups`` eines Benutzers in der Admin-API + - Wird gespeichert, aber der Name wirkt nicht als Rolle. Bei manchen Namen schlägt das Lesen des Benutzers fehl + - ``400``. Geben Sie die ID der Rolle bzw. Gruppe an (das ``id`` aus ``GET /api/admin/role/settings`` und ``GET /api/admin/group/settings``) + * - Ein Benutzer in der Admin-API, dessen Passwort die Passwortrichtlinie verletzt (etwa ``password.min.length``, Standard ``8``); eine Anlage ohne Passwort; ein ``confirm_password``, das von ``password`` abweicht + - Wird gespeichert; der Benutzer kann sich mit diesem Passwort anmelden + - ``400`` + +Die Zeilen von ``/api/v2/documents/all`` enthalten kein ``score`` mehr. Bis 15.8 hatte jedes Dokument seinen +Suchscore; 15.10 durchläuft das gesamte Ergebnis mit einem Point in Time und ``search_after``, wodurch kein +Score entsteht. ``/json?type=scroll`` und ``/api/v1/documents/all`` der Plugins für die alten APIs verhalten +sich genauso. Ein Skript, das ``score`` liest, muss damit umgehen können, dass der Wert fehlt. + +Datei-Uploads der Admin-API (die sechs Wörterbücher, ``badword``, ``elevateword`` und ``storage``) werden +per ``POST`` entgegengenommen. Die Dokumentation von 15.8 empfahl ``PUT``, doch ein ``PUT`` mit +``multipart/form-data`` liefert die Datei nie an, sodass es in 15.8 wie in 15.10 mit dem Validierungsfehler +fehlschlägt, dass die Datei erforderlich ist. Die ``PUT``-Endpunkte bleiben bestehen; verwenden Sie für +Uploads ``POST``. + +``search_engine.type=cloud`` ist veraltet +----------------------------------------- + +Mit 15.10 erhält ``search_engine.type`` den Wert ``vanilla`` für ein reines OpenSearch ohne die CodeLibs-Plugins (siehe :doc:`../config/search-engine-type`). ``cloud`` ist jetzt ein veralteter Alias für ``vanilla``: Er funktioniert weiterhin, aber |Fess| schreibt beim Start eine Warnung ins Log. Ändern Sie den Wert auf ``vanilla``, sobald die Installation mit 15.10 läuft. ``aws`` funktioniert unverändert weiter. + +* ``vanilla`` erfordert 15.10. |Fess| 15.8 und früher kennen den Wert nicht; behalten Sie daher ``cloud`` bei, solange Sie noch auf 15.8 zurückgehen können. +* Die Indexdefinitionen von ``aws`` und ``cloud`` stammen jetzt aus ``fess_indices/_vanilla/``. Die mitgelieferten Verzeichnisse ``fess_indices/_aws/`` und ``fess_indices/_cloud/`` gibt es nicht mehr, und ein von Ihnen selbst angelegtes Verzeichnis ``fess_indices/_aws/`` oder ``fess_indices/_cloud/`` wird nicht mehr gelesen. Übernehmen Sie Ihre Änderungen nach ``fess_indices/_vanilla/``. Bereits vorhandene Indizes werden nicht verändert. +* Die Suggest-Einstellungen, die 15.8 in der Suchmaschine gespeichert hat, werden automatisch migriert; Sie müssen nichts tun. + +Der CSV-Datenspeicher verarbeitet Felder in Anführungszeichen +------------------------------------------------------------- + +Das Plugin ``fess-ds-csv`` von 15.10 wertet Anführungszeichen standardmäßig aus. Ein Feld wie +``"Yamada, Taro"`` ist eine einzige Spalte, während das Plugin von 15.8.0 es am Komma trennte. +Prüfen Sie nach ``bin/fess-setup upgrade plugins`` die Datenspeicher-Konfigurationen, die +CSV-Dateien mit Feldern in Anführungszeichen lesen. Um das Verhalten von 15.8 beizubehalten, +ergänzen Sie ``quote_disabled=true`` in „Parameter"; siehe :doc:`../config/datastore/ds-csv`, wo auch +beschrieben ist, was ein nicht geschlossenes Anführungszeichen bewirkt. + +.. _upgrade-reindex-new-fields: + +Neue Felder und Kana-Normalisierung auf einen vorhandenen Dokumentindex anwenden +-------------------------------------------------------------------------------- + +Beim Start fügt 15.10 den Konfigurations-, Log- und Benutzerindizes neue Felder hinzu. Im +Dokumentindex ergänzt es nur das Feld ``tag`` (``keyword``), das die Benutzer-Tags enthält; das +übrige Mapping und die Analyseeinstellungen werden nicht geändert. Wenn Sie einen mit 15.8 oder +älter erstellten Dokumentindex weiterverwenden, wirken die folgenden Änderungen von 15.10 nicht. + +- **Eigentümer und letzter Bearbeiter einer Datei** (``owner``, ``last_modifier``): neue Felder, die + beim Crawlen von Dateisystem, SMB und FTP indiziert werden. Der vorhandene Dokumentindex enthält + keine Definition dafür, daher werden sie anhand des ersten gecrawlten Werts dynamisch als ``text`` + gemappt, und Suchen wie ``owner:alice`` oder ``facet.field=owner`` funktionieren nicht wie vorgesehen. +- **ETag** (``etag``): das Feld, in dem der Crawler den ETag einer gecrawlten Seite speichert und + das 15.10 als ``If-None-Match`` zurücksendet, damit eine unveränderte Seite nicht erneut abgerufen + wird. Auch dafür enthält der vorhandene Dokumentindex keine Definition, daher wird es dynamisch + als ``text`` gemappt statt als das mitgelieferte nicht indizierte ``keyword``. Bedingte Anfragen + funktionieren mit diesem Mapping weiterhin. +- **Normalisierung von Kana-Varianten und von Strichen anstelle des Dehnungszeichens** (zum Beispiel + wird ``サ―バ－`` als dasselbe Wort wie ``サーバー`` behandelt): Die Regeln stehen in den + Analyseeinstellungen des Dokumentindex und im Wörterbuch ``mapping.txt``, ein vorhandener Index + erhält sie daher nicht. + +Um beides anzuwenden, aktivieren Sie unter „Systeminformationen" → „Wartung" in der +Admin-Oberfläche „Aliase ersetzen" und „Wörterbücher zurücksetzen" und führen die „Neuindizierung" +aus. Die Neuindizierung kopiert die vorhandenen Dokumente in einen neuen Index; ein erneuter Crawl +ist nicht nötig. + +.. warning:: + + „Wörterbücher zurücksetzen" überschreibt die Wörterbücher auf der OpenSearch-Seite mit den + mitgelieferten Wörterbuchdateien. Wenn Sie Synonyme oder andere Wörterbücher unter „Wörterbuch" + in der Admin-Oberfläche bearbeitet haben, laden Sie sie vorher herunter und übernehmen Sie sie + nach der Neuindizierung erneut: Entfernen Sie doppelte oder ungültige Einträge aus den + heruntergeladenen Dateien (siehe Schritt 7), laden Sie sie hoch und klicken Sie dann unter + „Dokumentenindex neu laden" in „Systeminformationen" → „Wartung" auf „Neu laden". Bis dahin + verwenden die Analyzer des Dokumentindex weiterhin die mitgelieferten Wörterbücher, und ein + wiederhergestelltes Synonym greift nicht, wie lange Sie auch warten. Ein Wörterbuch, das beim + Indexieren wirkt, erfordert zusätzlich, dass die Dokumente erneut gecrawlt werden; siehe + :ref:`dict-apply-changes`. + +.. note:: + + Dateien, die mit 15.8 oder älter indiziert wurden, haben keine Werte für Eigentümer und letzten + Bearbeiter. Beim inkrementellen Crawlen werden unveränderte Dateien nicht erneut abgerufen. + Deaktivieren Sie daher vorübergehend „Letzte Änderung prüfen" unter „System" → „Allgemein" und + crawlen Sie, um die Werte zu ergänzen. + + +Migrationsaufgaben speziell für 15.10 +==================================== + +Wenn Sie von 15.7 oder früher auf 15.10 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.10 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.10 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". 15.10 fügt außerdem +``fess-llm-bedrock`` für Amazon Bedrock hinzu. + +Falls Sie SPNEGO (Windows-integrierte Authentifizierung) genutzt haben +---------------------------------------------------------------------- + +Ab 15.10 wird eine SPNEGO-Anmeldung abgelehnt, wenn sich die Kerberos-Realm des Client-Principals +von der Realm des Servers unterscheidet. Melden sich Ihre Benutzer aus einer untergeordneten +Domäne einer AD-Domänenstruktur oder aus einer vertrauten Gesamtstruktur an, tragen Sie diese +Realms kommagetrennt in ``spnego.allowed.realms`` ein, entweder über die Verwaltungsseite unter +„System" → „Allgemein" oder in ``app/WEB-INF/conf/system.properties``. Andernfalls werden +Benutzer, die sich bis 15.7 anmelden konnten, mit ``Kerberos realm is not allowed`` abgewiesen. +Einzelheiten finden Sie unter :doc:`../config/sso-spnego`. + +Außerdem wurden in 15.10 die im Code hinterlegten Standardwerte von +``spnego.allow.unsecure.basic`` und ``spnego.allow.localhost`` von ``true`` auf ``false`` +geändert. Eine Installation, in der diese Schlüssel in ``app/WEB-INF/conf/system.properties`` +fehlen, übernimmt mit dem Upgrade das strengere Verhalten. Insbesondere bietet die +SPNEGO-Bibliothek bei ``spnego.allow.unsecure.basic=false`` die Basic-Authentifizierung nur noch +für Anfragen an, bei denen ``HttpServletRequest#isSecure()`` ``true`` zurückgibt. Hinter einem +Reverse-Proxy, der TLS terminiert und die Anfrage per HTTP weiterleitet, können sich Clients, die +bisher auf die Basic-Authentifizierung zurückgefallen sind, dann nicht mehr anmelden. Setzen Sie +in diesem Fall ``tomcat.secure=true`` in ``tomcat_config.properties``; Einzelheiten finden Sie +unter :doc:`../config/sso-spnego`. + +.. warning:: + + Ein im Code hinterlegter Standardwert greift nur, solange der Schlüssel fehlt, und + „System" → „Allgemein" auf der Verwaltungsseite schreibt bei jedem Speichern sämtliche + ``spnego.*``-Schlüssel. In einer Installation, in der unter 15.7 auf dieser Seite jemals + „Aktualisieren" gedrückt wurde, sind daher weiterhin + ``spnego.allow.unsecure.basic=true`` und ``spnego.allow.localhost=true`` gespeichert. Das + Upgrade auf 15.10 härtet eine solche Installation nicht: Sie behält das freizügige Verhalten + stillschweigend bei, und 15.10 protokolliert beim Initialisieren von SPNEGO lediglich eine + Warnung in ``fess.log``. Öffnen Sie „System" → „Allgemein" (oder bearbeiten Sie + ``system.properties``) und schalten Sie beide Einstellungen bewusst ab. + ``spnego.allow.localhost=true`` ist dabei die gefährlichere der beiden Optionen: Die + SPNEGO-Bibliothek authentifiziert Anfragen vom selben Host dann als Betriebssystembenutzer des + Servers, ganz ohne Kerberos-Prüfung, was hinter einem Reverse-Proxy auf demselben Host unsicher + ist. + +.. _upgrade-159-saml: + +Falls Sie SAML-Authentifizierung (SSO) genutzt haben +---------------------------------------------------- + +Ab 15.10 bindet |Fess| jede SAML-Antwort an die ID der von ihm gesendeten AuthnRequest, sodass +IdP-initiiertes (unaufgefordertes) SSO nicht mehr funktioniert. Eine Anmeldung, die von einer +|Fess|-Kachel in einem IdP-Portal wie dem Okta-Dashboard oder dem Portal „Meine Apps" von +Microsoft Entra ID aus gestartet wird, hat keine zugehörige AuthnRequest und wird abgelehnt. Bis +15.7 funktionierte dies, weil |Fess| die nicht zuordenbare Antwort an den IdP zurückschickte und +der IdP sofort eine angeforderte Assertion lieferte. Wenn Sie auf der IdP-Seite eine Kachel +anlegen, lassen Sie diese auf den |Fess|-Endpunkt ``/sso/`` verweisen, damit die Anmeldung +SP-initiiert erfolgt. + +Zudem sendet der IdP die Assertion als seitenübergreifenden POST zurück, weshalb +``tomcat.sameSiteCookies`` in ``tomcat_config.properties`` auf ``none`` gesetzt werden muss. Mit +dem ausgelieferten Standardwert ``lax`` wird das Sitzungs-Cookie bei dieser Anfrage nicht +mitgesendet und die SAML-Anmeldung kann nicht abgeschlossen werden. Diese Datei liegt beim +ZIP-Paket unter ``lib/classes/`` und bei den DEB-/RPM-Paketen unter ``/etc/fess/``; nach der +Änderung muss |Fess| neu gestartet werden. Browser akzeptieren ``none`` nur bei einem Cookie, das +auch das Attribut ``Secure`` trägt, sodass |Fess| über HTTPS bereitgestellt werden muss. Bis 15.7 +führte dieselbe Fehlkonfiguration nicht zu einem klaren Fehler, sondern zu einer endlosen +Weiterleitungsschleife zum IdP; prüfen Sie die Einstellung daher auch bei einer Installation, die +zu funktionieren schien. In 15.10 schlägt die Anmeldung einmalig fehl, statt in einer Schleife zu +laufen. Einzelheiten finden Sie unter :doc:`../config/sso-saml`. + +Falls Sie Microsoft Entra ID (Azure AD) genutzt haben +----------------------------------------------------- + +Ab 15.10 lautet der Standardwert des beim Autorisierungsendpunkt angeforderten Response-Modus +``query`` statt ``form_post``. Bis 15.7 wurde der Callback als websiteübergreifender POST +zurückgegeben, und beim |Fess|-Standardwert ``tomcat.sameSiteCookies = lax`` wird das +Sitzungscookie dabei nicht mitgesendet, sodass ``tomcat.sameSiteCookies = none`` erforderlich +war. Wenn Sie ``none`` nur aus diesem Grund gesetzt haben, können Sie zum Standardwert +zurückkehren. Um das bisherige Verhalten beizubehalten, setzen Sie +``entraid.response.mode=form_post`` und belassen ``tomcat.sameSiteCookies = none``. Browser +akzeptieren ``none`` nur bei einem Cookie, das auch das Attribut ``Secure`` trägt; auch dieser Weg +setzt daher voraus, dass |Fess| über HTTPS bereitgestellt wird. + +Ab 15.10 löst |Fess| außerdem die Gruppen- und Rollenmitgliedschaft des Benutzers im Hintergrund +auf, nachdem die Anmeldung abgeschlossen ist, statt die Anmeldung auf Microsoft Graph warten zu +lassen. Bis die Auflösung abgeschlossen ist — oder wenn sie nicht vollständig gelingt — besitzt +der Benutzer nur seine eigene benutzerbezogene Berechtigung sowie das, was +``entraid.default.groups`` und ``entraid.default.roles`` beisteuern. Ist beides nicht gesetzt — +der ausgelieferte Standard —, liefert eine Suche in diesem Zeitfenster überhaupt keine Dokumente, +denn eine mit den ausgelieferten Standardwerten angelegte Crawl-Konfiguration vergibt +``{role}guest``, und diese Rolle besitzt ein angemeldeter Benutzer nicht. Während die Auflösung +läuft, weist die Suchseite darauf hin, und bei einer nicht vollständig gelungenen Auflösung zeigt +sie einen anderen Hinweis — die Auflösung gilt nur dann als erfolgreich, wenn sowohl die Abfrage +der direkten Mitgliedschaften als auch der Durchlauf der verschachtelten Gruppen gelungen ist. Die +Auflösung wird bei jeder Erneuerung des Zugriffstokens erneut angestoßen, und ein späterer Erfolg +lässt den Hinweis verschwinden; für eine Sitzung, die länger als die Gültigkeitsdauer des Tokens +besteht, ist ein Fehlschlag daher nicht endgültig. Um es sofort erneut zu versuchen, melden Sie +sich ab und anschließend wieder an. Einzelheiten finden Sie unter :doc:`../config/sso-entraid`. + +Eine Folge der Auflösung im Hintergrund: Bis die Auflösung eintrifft, sind die aufgelösten Rollen +des Benutzers noch nicht bekannt. Ein Administrator wird deshalb zur Suchseite statt zum Dashboard +der Verwaltungsseite weitergeleitet, und wer in diesem Zeitfenster eine Seite der Verwaltungsseite +öffnet, landet wieder auf der Suchseite. Das Zeitfenster umfasst bis zu etwa eine Sekunde +Planungsverzögerung zuzüglich der Aufrufe von Microsoft Graph selbst — einer für die direkten +Mitgliedschaften, dann je einer pro dieser Gruppen für den Durchlauf der verschachtelten Gruppen, +nacheinander und bei kaltem Cache abgesetzt —, es wächst also mit der Anzahl der Gruppen des +Benutzers. In diesem Zeitfenster wird der Zugriff immer nur verweigert, niemals gewährt, und es +ist keine Konfiguration nötig, um es zu überbrücken: Die Autorisierung wird bei jeder Anfrage +derselben Sitzung erneut ausgewertet, sodass sich die Verwaltungsseiten nach Abschluss der +Auflösung ohne erneute Anmeldung normal öffnen lassen. + +.. warning:: + + Verkürzen Sie dieses Zeitfenster nicht, indem Sie die |Fess|-Administratorrolle in + ``entraid.default.roles`` eintragen. Diese Eigenschaft ist ein einzelner globaler Wert, den + |Fess| bei der Anmeldung auf jeden Entra ID-Benutzer anwendet und bei jeder späteren Auflösung + erneut anwendet; sie würde jedem Benutzer im Mandanten dauerhafte + |Fess|-Administratorrechte verleihen. + +Bei Verwendung von LDAP / Active Directory +------------------------------------------ + +Ab 15.10 ist der Berechtigungsname einer Gruppe oder Rolle der Wert des RDN des Eintrags und nicht +mehr ein Ausschnitt des DN-Textes. Eine Gruppe, deren CN ein im DN maskiertes Zeichen enthält -- +üblicherweise ein Komma --, erhält daher einen anderen Berechtigungsnamen als in 15.7. + +.. list-table:: + :header-rows: 1 + + * - DN des Gruppeneintrags + - Berechtigungsname bis 15.7 + - Berechtigungsname in 15.10 + * - ``CN=Sales\, EMEA,CN=Users,...`` + - ``2Sales`` + - ``2Sales, EMEA`` + * - ``CN=Sales\, APAC,CN=Users,...`` + - ``2Sales`` + - ``2Sales, APAC`` + +Bis 15.7 fielen mehrere Gruppen, die bis zum Komma übereinstimmen, auf denselben Berechtigungsnamen +zusammen. Mitglieder von ``Sales, EMEA`` und ``Sales, APAC`` konnten daher die Dokumente der jeweils +anderen Gruppe und der Gruppe ``Sales`` lesen. In 15.10 erhält jede Gruppe ihren eigenen +Berechtigungsnamen, und dieser gruppenübergreifende Zugriff tritt nicht mehr auf. + +Im Gegenzug sind **Dokumente, die unter dem alten Berechtigungsnamen indexiert wurden, für +Mitglieder dieser Gruppe nicht mehr sichtbar**. Enthält die Berechtigungseinstellung einer +Crawl-Konfiguration einen alten Berechtigungsnamen, aktualisieren Sie ihn auf den neuen und crawlen +(oder reindexieren) Sie erneut. Wenn Sie keine Gruppe verwenden, deren CN ein Komma oder ein anderes +maskiertes Zeichen enthält, ändert sich kein Berechtigungsname. + +Änderung an ``ldap.role.search.user.enabled`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Bis 15.7 wurde die aus dem Benutzernamen abgeleitete Berechtigung (``role.search.user.prefix`` +gefolgt vom Benutzernamen) auch bei ``ldap.role.search.user.enabled=false`` vergeben. Ab 15.10 wird +die Einstellung wirksam, und die Berechtigung wird bei ``false`` nicht mehr vergeben. + +In einer Installation, die sie auf ``false`` setzt, verlieren Benutzer nach dem Upgrade die nach +ihnen benannte Berechtigung. Dokumente, die einzelnen Benutzern zugewiesen sind, werden für diese +Benutzer dann nicht mehr gefunden. Um das bisherige Verhalten beizubehalten, stellen Sie den +mitgelieferten Standardwert ``true`` wieder her. + +Falls Sie die /api/v2-Konfigurationsschlüssel geändert haben +------------------------------------------------------------ + +In 15.8.0 haben vier Konfigurationsschlüssel ihr Präfix ``api.v2.`` verloren. Werte, Standardwerte +und Verhalten bleiben unverändert, **es gibt jedoch keinen abwärtskompatiblen Aliasnamen**: Eine +unter dem alten Namen belassene Einstellung wird ohne Warnung ignoriert, und stattdessen greift +der mitgelieferte Standardwert. + +.. list-table:: + :header-rows: 1 + + * - Bis 15.7 + - 15.8.0 und später + - Standardwert + * - ``api.v2.chat.stream.keepalive.interval.ms`` + - ``api.chat.stream.keepalive.interval.ms`` + - ``15000`` + * - ``api.v2.param.max.length`` + - ``api.param.max.length`` + - ``1000`` + * - ``api.v2.param.max.array.size`` + - ``api.param.max.array.size`` + - ``100`` + * - ``api.v2.click.max.rt`` + - ``api.click.max.timestamp`` + - ``9999999999999`` + +Wenn Sie einen dieser Schlüssel in ``fess_config.properties`` oder als JVM-Argument +``-Dfess.config.`` gesetzt haben, benennen Sie ihn um. Betroffen sind nur explizit +gesetzte Werte; eine Installation, die sie nie geändert hat, erfordert keine Maßnahme. + +Der erste Schlüssel bestimmt, wie oft ein Keep-alive-Frame gesendet wird, während +``POST /api/v2/chat/stream`` auf das Modell wartet - eine verlorene Einstellung fällt daher im +KI-Suchmodus auf. Der letzte Schlüssel wurde auch aus Gründen der Genauigkeit umbenannt: Er +begrenzt den Wert ``rt`` eines Klickprotokolls, der ein Zeitstempel und keine Antwortzeit ist. + + +.. _upgrade-plugin-versions: + +Aktualisierung der Plugin-Versionen +----------------------------------- + +Die unter ``app/WEB-INF/plugin/`` installierten Plugins müssen durch die zur |Fess|-Version +passenden Versionen ersetzt werden. ``bin/fess-setup upgrade plugins`` erledigt das für alle +installierten Plugins: Es installiert die für dieses |Fess| gebaute Version und löscht die alte. +Starten Sie |Fess| anschließend neu. ``bin/fess-setup check`` meldet danach den Zustand von +OpenSearch, seinen Plugins und den installierten |Fess|-Plugins und endet mit dem Exit-Code 1, +wenn etwas nicht stimmt. Es liest weder ``bin/fess.in.sh`` noch ``/etc/sysconfig/fess`` oder +``/etc/default/fess``; wenn OpenSearch nicht unter ``http://localhost:9200`` erreichbar ist, +übergeben Sie daher ``--url`` oder setzen Sie ``SEARCH_ENGINE_HTTP_URL`` in der Shell, die es +ausführt, sonst meldet es die Suchmaschine als nicht erreichbar. + +:: + + $ bin/fess-setup upgrade plugins + $ bin/fess-setup check + +``upgrade plugins`` berücksichtigt nur bereits installierte Plugins. Plugins, die in 15.10 aus der +Distribution entfernte Teile ersetzen, etwa ``fess-script-groovy``, installieren Sie wie in den +obigen Abschnitten beschrieben mit ``bin/fess-setup install plugin``. + +Wenn Sie bei der Docker-Version ``FESS_PLUGINS`` angeben, aktualisieren Sie den Versionsanteil +entsprechend, z. B. ``fess-ds-wikipedia:15.10.0``. + +Rollback-Verfahren +================== + +Bei fehlgeschlagenem Upgrade können Sie mit folgenden Schritten ein Rollback durchführen. + +Schritt 1: Stopp der neuen Version +----------------------------------- + +:: + + $ sudo systemctl stop fess.service + $ sudo systemctl stop opensearch.service + +Schritt 2: Wiederherstellung der alten Version +----------------------------------------------- + +Stellen Sie Konfigurationsdateien und Daten aus dem Backup wieder her. + +Bei RPM/DEB-Version:: + + $ sudo rpm -Uvh --oldpackage --nodeps fess-.rpm + +oder:: + + $ sudo dpkg -i fess-.deb + +.. note:: + + Bei RPM ist ``--nodeps`` erforderlich. Das Paket 15.8.0 verlangt die Benutzer und Gruppen ``fess`` + und ``opensearch``, und ohne die Option lehnt ``rpm`` das Downgrade mit ``Failed dependencies: + group(fess) is needed by fess-15.8.0`` ab. + +.. warning:: + + Das DEB-Paket 15.8.0 registriert ``/etc/fess/*`` nicht als Conffile, sodass ``dpkg -i`` die von + Ihnen bearbeiteten Dateien wie ``/etc/fess/fess_config.properties`` ohne Sicherungskopie + überschreibt. Stellen Sie sie aus dem Backup wieder her, das Sie in Schritt 1 erstellt haben. + +Schritt 3: Datenwiederherstellung +---------------------------------- + +Wiederherstellung aus Snapshot. OpenSearch muss laufen und |Fess| gestoppt sein: + +1. Starten Sie OpenSearch:: + + $ sudo systemctl start opensearch.service + +2. Ein Snapshot lässt sich nicht über einen vorhandenen Index wiederherstellen. Löschen Sie daher + zuerst jeden Fess-Index, auch die nach dem Upgrade (zum Beispiel durch eine Neuindizierung) + erstellten, sowie den Index ``configsync``, den das OpenSearch-Plugin anlegt. Löschen Sie nur die + Indizes, die im Snapshot enthalten sind, bleibt ein durch die Neuindizierung erstellter Index + zurück, ``fess.search`` zeigt auf zwei Indizes, und 15.8.0 startet nicht:: + + $ curl "http://localhost:9200/_cat/indices/fess*,configsync?h=index" + $ curl -X DELETE "http://localhost:9200/" + + Führen Sie den zweiten Befehl für jeden Index aus, den der erste auflistet. + +3. Stellen Sie den Snapshot wieder her:: + + $ curl -X POST "http://localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true" + +.. note:: + + Das Wörterbuchverzeichnis muss wie zuvor vorhanden sein (``configsync.config_path``, mit den + Wörterbuchdateien). Auf einem Rechner, auf dem es verloren gegangen ist, wird die + Wiederherstellung abgeschlossen, aber die Indizes, die die Wörterbücher verwenden, bleiben rot. + +Oder Wiederherstellung des Verzeichnisses aus dem Backup (verwenden Sie den Namen des Archivs, das +Sie in Schritt 1 erstellt haben):: + + $ sudo systemctl stop opensearch + $ sudo rm -rf /var/lib/opensearch/data/* + $ sudo tar xzf /backup/opensearch-data-.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 (ZIP-Version: ``app/WEB-INF/conf/``, + RPM/DEB-Version: ``/etc/fess/``). + +.. note:: + + 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 +---------------------------------------------- + +:: + + $ sudo systemctl start opensearch.service + $ sudo systemctl start fess.service + +Überprüfen Sie den Betrieb und stellen Sie sicher, dass alles wieder normal läuft. + +Häufig gestellte Fragen +======================= + +F: Ist ein Upgrade ohne Ausfallzeit möglich? +--------------------------------------------- + +A: Ein Upgrade von Fess erfordert einen Dienststopp. Um die Ausfallzeit zu minimieren, sollten Sie Folgendes in Betracht ziehen: + +- Überprüfung der Vorgehensweise in der Testumgebung im Voraus +- Backup im Voraus erstellen +- Ausreichend Wartungszeit einplanen + +F: Muss auch OpenSearch aktualisiert werden? +--------------------------------------------- + +A: Für jede |Fess|-Version ist eine bestimmte OpenSearch-Version vorgesehen. +|Fess| 15.10 unterstützt OpenSearch 3.9.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.9.0). + +|Fess| 15.10 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 einem Minor-Version-Upgrade von |Fess| (15.x → 15.10) 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. +- **Suche nach Eigentümer oder Kana-Normalisierung mit einem unter 15.8 oder älter erstellten + Dokumentindex**: Eine Neuindizierung ist erforderlich. Siehe :ref:`upgrade-reindex-new-fields`. + +.. 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 +---------------------------------------------------------- + +A: Überprüfen Sie Folgendes: + +1. Überprüfen Sie, ob OpenSearch läuft +2. Überprüfen Sie, ob Indizes vorhanden sind (``curl http://localhost:9200/_cat/indices``) +3. Crawl erneut ausführen + +Nächste Schritte +================ + +Nach Abschluss des Upgrades: + +- :doc:`run` - Überprüfung von Start und Erstkonfiguration +- :doc:`security` - Überprüfung der Sicherheitseinstellungen +- :doc:`../config/search-semantic` - Konfiguration und Migrationsschritte für die + Chunk-Vektor-Suche (semantische Suche) +- Überprüfung neuer Funktionen in den Release Notes diff --git a/de/15.10/user/advanced-search.rst b/de/15.10/user/advanced-search.rst new file mode 100644 index 000000000..c93e04e32 --- /dev/null +++ b/de/15.10/user/advanced-search.rst @@ -0,0 +1,79 @@ +================== +Erweiterte Suche +================== + +Der erweiterte Suchbildschirm ermöglicht komplexere Suchen durch die Kombination mehrerer Bedingungen. + +Verwendung +----------- + +Der erweiterte Suchbildschirm wird über den Link "Erweiterte Suche" in den Suchoptionen des Suchbildschirms aufgerufen. Wird er vom Suchergebnisbildschirm aus geöffnet, werden die bereits eingegebenen Suchbegriffe in das Feld "Alle Wörter enthalten" übernommen. + +|image0| + +Geben Sie in jedem Feld die gewünschten Bedingungen ein und klicken Sie auf die Suchschaltfläche unten auf der Seite. Die mehreren eingegebenen Felder werden zu einer einzigen Suchbedingung kombiniert. + +Elementliste +------------- + +Alle Wörter enthalten +::::::::::::::::::::::::: + +Sucht nach Dokumenten, die alle eingegebenen Wörter enthalten (UND-Suche). Mehrere Wörter können durch Leerzeichen getrennt angegeben werden. + +Exakte Übereinstimmung einschließlich Wortreihenfolge +::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: + +Sucht nach Dokumenten, die die eingegebene Zeichenkette exakt, einschließlich der Wortreihenfolge, enthalten (Phrasensuche). Da die gesamte Zeichenkette einschließlich der Leerzeichen als eine einzige Phrase behandelt wird, kann sie nicht in einzelne Wörter für die Suche aufgeteilt werden. + +Eines der Wörter enthalten +:::::::::::::::::::::::::::::::: + +Sucht nach Dokumenten, die eines der eingegebenen Wörter enthalten (ODER-Suche). Mehrere Wörter können durch Leerzeichen getrennt angegeben werden. + +Auszuschließende Wörter +:::::::::::::::::::::::::::: + +Sucht nach Dokumenten, die die eingegebenen Wörter nicht enthalten. Mehrere Wörter können durch Leerzeichen getrennt angegeben werden; alle angegebenen Wörter werden aus den Suchergebnissen ausgeschlossen. + +Anzahl der Anzeigen +:::::::::::::::::::::: + +Gibt die Anzahl der pro Seite angezeigten Suchergebnisse an. Sie können zwischen 10, 20, 30, 40, 50 und 100 wählen. Wenn kein Wert angegeben wird, wird die Standardanzahl der Anzeigen (Anfangswert 10) verwendet. + +Sortierung +:::::::::::: + +Gibt das Kriterium für die Sortierung der Suchergebnisse an. Sie können zwischen "nach Punktzahl", "nach Dateiname", "nach Datum", "nach Größe" und "nach letzter Änderung" wählen, jeweils in aufsteigender oder absteigender Reihenfolge. Die Sortierung "nach Klickanzahl" oder "nach Favoritenanzahl" ist verfügbar, wenn die entsprechende Funktion aktiviert ist. + +Bevorzugte Sprache +:::::::::::::::::::: + +Gibt die bevorzugte Sprache für die Suchergebnisse an. Es können mehrere Sprachen ausgewählt werden. Wenn "Alle Sprachen" ausgewählt ist, wird keine bestimmte Sprache bevorzugt. + +Label +:::::::: + +Filtert die Suche nach Label. Es können mehrere Label ausgewählt werden. Es wird nicht angezeigt, wenn keine Label registriert sind oder wenn es keine Label gibt, die der aktuelle Benutzer anzeigen darf. + +Aktualisierungsdatum +:::::::::::::::::::::::: + +Filtert die Suche nach dem Aktualisierungsdatum bzw. -zeitpunkt des Dokuments. Sie können zwischen "Jederzeit", "Letzte 24 Stunden", "Letzte Woche", "Letzter Monat" und "Letztes Jahr" wählen. + +Dateiformat +::::::::::::: + +Filtert die Suche nach dem Dateiformat des Dokuments. Sie können zwischen "Beliebiges Format", "HTML", "PDF", "MS Word", "MS Excel" und "MS PowerPoint" wählen. + +Suchziel +:::::::::: + +Gibt an, wo gesucht werden soll. Sie können zwischen "Überall auf der Seite", "im Titel der Seite" und "in der URL der Seite" wählen. Wenn "im Titel der Seite" oder "in der URL der Seite" ausgewählt ist, werden die eingegebenen Wörter nur im Titel bzw. in der URL gesucht. + +Website oder Domain +:::::::::::::::::::::: + +Filtert die Suche nach der eingegebenen Website oder Domain. Geben Sie dies an, wenn Sie nur Dokumente durchsuchen möchten, die in einer bestimmten Website oder Domain enthalten sind. + +.. |image0| image:: ../../../resources/images/en/15.10/user/advanced-search-1.png diff --git a/de/15.10/user/chat-search.rst b/de/15.10/user/chat-search.rst new file mode 100644 index 000000000..2ff3a3ef6 --- /dev/null +++ b/de/15.10/user/chat-search.rst @@ -0,0 +1,283 @@ +============ +KI-Suchmodus +============ + +Übersicht +========= + +Mit der Funktion KI-Suchmodus (RAG-Chat) von |Fess| können Sie zusätzlich zur herkömmlichen +Stichwortsuche auch in natürlicher Gesprächsform nach Informationen suchen. Wenn Sie eine +Frage eingeben, durchsucht der KI-Assistent die relevanten Dokumente und generiert auf +Basis ihres Inhalts eine leicht verständliche Antwort. + +.. note:: + Der KI-Suchmodus ist standardmäßig deaktiviert. Damit Sie ihn nutzen können, muss der + Systemadministrator die Funktion aktivieren und einen LLM-Provider (Large Language Model) + konfigurieren. Informationen zur Konfiguration finden Sie unter :doc:`../config/rag-chat` + und :doc:`../config/llm-overview`. + +Merkmale des KI-Suchmodus +========================= + +Dialogbasierte Suche +-------------------- + +Anstatt sich Schlüsselwörter zu überlegen, können Sie Fragen wie in einem gewöhnlichen +Gespräch stellen. + +Beispiele: + +- "Wie installiere ich Fess?" +- "Wie kann ich Dateien crawlen?" +- "Was kann ich tun, wenn keine Suchergebnisse angezeigt werden?" + +Kontextbezogene Antworten +------------------------- + +Der KI-Assistent analysiert die Absicht der Frage, durchsucht relevante Dokumente und +extrahiert aus mehreren Suchergebnissen die benötigten Informationen, um daraus eine +strukturierte Antwort zu erstellen. + +Angabe der Quellen +------------------- + +Am unteren Rand der Antwort werden die Dokumente, auf denen die Antwort basiert, als +"Quellen" aufgelistet. Jede Quelle ist ein nummerierter Link, über den Sie das +Originaldokument direkt aufrufen können. Außerdem kann der Antworttext Zitate mit +Nummern wie ``[1]`` oder ``[2]`` enthalten, die den Nummern in der Quellenliste +entsprechen. + +Gesprächsfortsetzung +-------------------- + +Es muss nicht bei einer einzigen Frage bleiben – Sie können das Gespräch fortsetzen. +Der KI-Assistent beantwortet weitere Fragen unter Berücksichtigung des Kontexts +vorheriger Fragen und Antworten. + +Verwendung der Chat-Suche +========================== + +Den KI-Suchmodus öffnen +------------------------ + +1. Öffnen Sie die Suchseite von |Fess| +2. Klicken Sie in der Navigationsleiste am oberen Bildschirmrand auf den Link "KI-Suche" (Roboter-Symbol) +3. Der Bildschirm des KI-Suchmodus wird angezeigt + +.. note:: + Der Link "KI-Suche" wird nur angezeigt, wenn der KI-Suchmodus aktiviert ist und ein + LLM-Provider zur Verfügung steht. Wenn der Link nicht angezeigt wird, lesen Sie den + Abschnitt `Häufig gestellte Fragen`_. + +Eine Frage eingeben +-------------------- + +1. Geben Sie Ihre Frage in das Textfeld am unteren Bildschirmrand ein (maximal 4000 Zeichen pro Frage) +2. Klicken Sie auf die Schaltfläche "Nachricht senden" (Papierflieger-Symbol) oder drücken Sie die Eingabetaste (Enter) +3. Der KI-Assistent beginnt mit der Generierung der Antwort + +.. note:: + Wenn Sie einen Zeilenumbruch eingeben möchten, drücken Sie anstelle der Eingabetaste + die Tastenkombination Umschalt+Eingabetaste (Shift+Enter). + +.. note:: + Die Generierung der Antwort kann einige Sekunden bis zu einer knappen Minute dauern. + Während der Verarbeitung wird der aktuelle Verarbeitungsschritt in einer + Fortschrittsanzeige (Analyse → Suche → Bewertung → Abruf → Antwort) dargestellt, + begleitet von Meldungen wie "Denkt nach...", "Suche läuft...", + "Suchergebnisse werden überprüft...", "Dokumente werden abgerufen..." und + "Antwort wird generiert...". Sobald die Suche abgeschlossen ist, wird zusätzlich die + Anzahl der gefundenen Dokumente angezeigt. + +Antwort überprüfen +------------------- + +Die Antwort des KI-Assistenten wird angezeigt. Sie enthält folgende Informationen: + +- **Antworttext**: Die Antwort auf Ihre Frage (im Markdown-Format formatiert) +- **Quellen**: Eine Liste nummerierter Links zu den Dokumenten, auf denen die Antwort + basiert (ein Klick öffnet das Originaldokument in einem neuen Tab) + +Der Antworttext kann Zitatnummern wie ``[1]`` oder ``[2]`` enthalten, die den Nummern in +der Quellenliste entsprechen. Jede Antwort verfügt über eine Kopieren-Schaltfläche, mit +der Sie den Antwortinhalt in die Zwischenablage kopieren können. + +.. note:: + Die KI verwendet als Grundlage für die Antwort nur die Dokumente, die sie unter den + Suchergebnissen als am relevantesten einstuft. Daher kann die Anzahl der Quellen + geringer sein als die Anzahl der bei der Suche gefundenen Dokumente. + +Suchbereich eingrenzen +------------------------ + +Je nach Thema können Sie über die Schaltfläche "Filter" am oberen Bildschirmrand den +Suchbereich anhand von Kriterien wie Labels, Dateityp, Änderungsdatum oder Größe +eingrenzen. Das ist praktisch, wenn Sie der KI nur zu einem bestimmten Dokumentenbereich +Fragen stellen möchten. + +Das Gespräch fortsetzen +------------------------- + +Wenn Sie weitere Fragen haben, können Sie direkt weiterfragen: + +- "Können Sie das genauer erklären?" +- "Gibt es noch andere Möglichkeiten?" +- "Mehr Details zu XXX" + +Der KI-Assistent berücksichtigt bei der Antwort den Kontext des vorherigen Gesprächs. + +Ein neues Gespräch beginnen +----------------------------- + +Wenn Sie zu einem anderen Thema eine Frage stellen möchten, klicken Sie auf die +Schaltfläche "Neuer Chat" (Plus-Symbol). Dadurch wird der bisherige Gesprächsverlauf +gelöscht und Sie können ein neues Gespräch beginnen. + +Tipps für effektive Fragen +============================ + +Konkret fragen +-------------- + +Konkrete Fragen liefern passendere Antworten als vage Fragen. + +.. list-table:: + :header-rows: 1 + :widths: 50 50 + + * - Vage Frage + - Konkrete Frage + * - Wie konfiguriert man das? + - Wie ändere ich die Speichereinstellungen von Fess? + * - Es tritt ein Fehler auf + - Bei der Suche erscheint die Fehlermeldung "Index nicht gefunden" + * - Zum Crawling + - Wie richte ich Ausschlussregeln beim Crawlen einer Website ein? + +Hintergrundinformationen angeben +----------------------------------- + +Wenn Sie Ihre Situation oder Ihr Ziel angeben, erhalten Sie passendere Antworten. + +Gute Beispiele: + +- "Ich betreibe Fess in einer Docker-Umgebung. Ich möchte den Speicherort der Logs ändern – wie mache ich das?" +- "Ich benutze Fess zum ersten Mal. Was sollte ich zuerst tun?" + +Schrittweise fragen +-------------------- + +Bei komplexen Problemen wird das Verständnis durch schrittweises Nachfragen erleichtert. + +1. "Kann Fess Dateifreigaben crawlen?" +2. "Wie stelle ich eine Verbindung über das SMB-Protokoll her?" +3. "Was mache ich, wenn der Freigabeordner eine Authentifizierung erfordert?" + +Häufig gestellte Fragen +========================== + +F: Der KI-Suchmodus wird nicht angezeigt +------------------------------------------ + +A: Möglicherweise ist der KI-Suchmodus nicht aktiviert. Der Link "KI-Suche" wird nur +angezeigt, wenn die Funktion aktiviert ist (``rag.chat.enabled=true``) und ein +LLM-Provider (z. B. OpenAI, Gemini, Ollama) konfiguriert und verfügbar ist. Fragen Sie +Ihren Systemadministrator, ob der KI-Suchmodus aktiviert und der LLM-Provider korrekt +konfiguriert ist (Details siehe :doc:`../config/rag-chat`). + +F: Es dauert lange, bis die Antwort angezeigt wird +------------------------------------------------------ + +A: Da die KI die Frage analysiert, Dokumente durchsucht und bewertet, bevor sie die +Antwort generiert, kann dies einige Sekunden bis zu einer knappen Minute dauern. +Während der Verarbeitung wird der aktuelle Verarbeitungsschritt angezeigt +("Denkt nach...", "Suche läuft...", "Suchergebnisse werden überprüft...", +"Dokumente werden abgerufen...", "Antwort wird generiert..."). + +F: Die Quellen scheinen falsch zu sein +------------------------------------------ + +A: Klicken Sie auf den Link der Quelle, um das Originaldokument zu überprüfen. Die KI +generiert die Antwort auf Basis der Suchergebnisse, wobei es zu Interpretationsfehlern +kommen kann. Wir empfehlen, wichtige Informationen stets im Originaldokument zu +überprüfen. + +F: Das vorherige Gespräch scheint vergessen worden zu sein +---------------------------------------------------------------- + +A: Möglicherweise ist die Gesprächssitzung abgelaufen. Wenn über einen bestimmten +Zeitraum (standardmäßig 30 Minuten) keine Aktivität stattfindet, wird der +Gesprächsverlauf gelöscht. Da der Gesprächsverlauf zudem nur temporär im Arbeitsspeicher +des Servers gehalten wird, geht er auch bei einem Neustart des Servers verloren. +Beginnen Sie in diesem Fall ein neues Gespräch. + +.. note:: + Die hier genannte "Sitzung" bezieht sich auf die Gesprächssitzung des KI-Suchmodus + und ist von der Anmeldesitzung bei |Fess| zu unterscheiden. + +F: Ich erhalte auf bestimmte Fragen keine Antwort +------------------------------------------------------- + +A: Folgende Ursachen sind möglich: + +- In den durchsuchten Dokumenten sind keine relevanten Informationen enthalten +- Die Frage ist zu vage formuliert, sodass keine geeignete Suche möglich ist +- Das Rate-Limit wurde erreicht (die maximale Anzahl an Anfragen pro Minute oder die + maximale Anzahl gleichzeitiger Anfragen wurde überschritten) + +Formulieren Sie die Frage um oder warten Sie eine Weile, bevor Sie es erneut versuchen. + +F: Gibt es eine Begrenzung für die Anzahl der eingebbaren Zeichen? +------------------------------------------------------------------------ + +A: Pro Frage sind maximal 4000 Zeichen zulässig. Unterhalb des Textfelds wird ein +Zeichenzähler angezeigt, der eine Warnung ausgibt, sobald Sie sich der Obergrenze +nähern. Fassen Sie lange Fragen auf die wesentlichen Punkte zusammen. + +F: Kann ich auch in anderen Sprachen als Japanisch fragen? +------------------------------------------------------------------ + +A: Ja, in den meisten Fällen können Sie auch auf Englisch oder in anderen Sprachen +fragen. Die KI versucht, basierend auf der Anzeigesprache des Browsers bzw. der +Oberfläche, so weit wie möglich in derselben Sprache zu antworten. Dies erfolgt jedoch +nach bestem Bemühen (Best Effort), sodass die Antwort je nach Situation nicht in der +gewünschten Sprache erfolgen kann. + +Hinweise +======== + +Über die KI-Antworten +----------------------- + +- Die Antworten der KI werden auf Grundlage der Suchergebnisse generiert +- Die Genauigkeit der Antworten wird nicht garantiert +- Überprüfen Sie für wichtige Entscheidungen stets das Originaldokument (die Quelle) +- Aktuelle Informationen finden Sie in der offiziellen Dokumentation + +Zum Datenschutz +----------------- + +- Eingegebene Fragen werden für die Suche sowie für die KI-Verarbeitung durch den + konfigurierten LLM-Provider verwendet +- Wenn ein externer LLM-Dienst (z. B. OpenAI oder Gemini) konfiguriert ist, werden der + Inhalt der Frage sowie die Suchergebnisse an diesen Dienst übermittelt. Wenn die + Verarbeitung ausschließlich intern erfolgen soll, wenden Sie sich an Ihren + Administrator bezüglich der Nutzung eines lokal betriebenen Providers (z. B. Ollama) +- Der Gesprächsverlauf wird temporär im Arbeitsspeicher des Servers gespeichert und + gelöscht, wenn die Sitzung abläuft, "Neuer Chat" ausgeführt wird oder der Server neu + gestartet wird +- Wie bei der regulären Suche gilt auch hier die Zugriffskontrolle über Rollen + (Berechtigungen) und Labels; Dokumente, auf die kein Zugriff besteht, werden nicht als + Grundlage für die Antwort verwendet +- Je nach Systemkonfiguration können Protokolle aufgezeichnet werden + +Referenzinformationen +====================== + +- :doc:`../config/rag-chat` - Konfiguration der Funktion KI-Suchmodus (für Administratoren) +- :doc:`../config/llm-overview` - Konfiguration des LLM-Providers +- :doc:`../api/api-chat` - Chat-API (Nutzung über Programme) +- :doc:`search-and` - Verwendung der UND-Suche +- :doc:`search-not` - Verwendung der NICHT-Suche +- :doc:`search-field` - Verwendung der Feldsuche +- :doc:`advanced-search` - Erweiterte Suchfunktionen diff --git a/de/15.10/user/index.rst b/de/15.10/user/index.rst new file mode 100644 index 000000000..4ce28d80b --- /dev/null +++ b/de/15.10/user/index.rst @@ -0,0 +1,29 @@ +|Fess| Benutzerhandbuch +======================== + +Wie Suchanfragen in |Fess| geschrieben werden: UND, ODER und NICHT, +Feld- und Labelsuche, Sortierung, Platzhalter, Bereiche, Boosting, +unscharfe Suche, Näherungssuche und Geo-Suche. + +.. toctree:: + :maxdepth: 2 + + intro + search-and + search-or + search-not + search-bangs + search-label + search-field + search-sort + search-wildcard + search-range + search-boost + search-fuzzy + search-proximity + search-geo + search-additional + role-search + special-char + advanced-search + chat-search diff --git a/de/15.10/user/intro.rst b/de/15.10/user/intro.rst new file mode 100644 index 000000000..829e7c1ff --- /dev/null +++ b/de/15.10/user/intro.rst @@ -0,0 +1,49 @@ +======================= +Einführung in die Suche +======================= + +Zielgruppe +============ + +|Fess| ist ein unternehmensweiter Suchserver, der die Volltextsuche über Dokumente in Websites, Dateien, Datenbanken und weiteren Quellen ermöglicht. + +Diese Dokumentation richtet sich an Benutzer, die |Fess| verwenden. + +Bevor Sie beginnen +=================== + +Diese Dokumentation beschreibt die Suchmethoden in |Fess|. Neben der grundlegenden Stichwortsuche behandelt sie auch die Verfeinerung der Suche über den erweiterten Suchbildschirm sowie den KI-Suchmodus, mit dem Sie in natürlicher Gesprächsform nach Informationen suchen können. Grundlegende Kenntnisse im Umgang mit Computern werden vorausgesetzt. + +Online-Zugriff +=============== + +Für Downloads, professionelle Dienstleistungen, Support und weitere Entwicklerinformationen besuchen Sie bitte: + +- Projekt-Website: https://fess.codelibs.org/ + +Kontakt für technischen Support +================================= + +Sollten Sie technische Fragen zu diesem Produkt haben, für die Sie in dieser Dokumentation keine Lösung finden, besuchen Sie bitte: + +- Issues: + `https://github.com/codelibs/fess/issues `__ + +Kommerzieller Support +----------------------- + +Wenn Sie kommerziellen Support benötigen, wie z. B. technische Unterstützung oder Wartung für dieses Produkt, wenden Sie sich bitte an `N2SM, Inc. `__. + +Haftungsausschluss für Websites Dritter +========================================== + +Das |Fess|-Projekt übernimmt keine Verantwortung für die Verfügbarkeit der in dieser Dokumentation erwähnten Websites Dritter. Das |Fess|-Projekt übernimmt keine Gewährleistung, Verantwortung oder Haftung für Inhalte, Werbung, Produkte, Dienstleistungen oder andere Materialien, die auf oder über solche Websites oder Ressourcen verfügbar sind. Das |Fess|-Projekt haftet nicht für Schäden oder Verluste, die durch die Nutzung oder das Vertrauen auf solche Inhalte, Werbung, Produkte, Dienstleistungen oder andere Materialien entstehen oder geltend gemacht werden, die auf oder über solche Websites oder Ressourcen verfügbar sind. + +Einreichen von Kommentaren und Vorschlägen +=========================================== + +Das |Fess|-Projekt ist bestrebt, diese Dokumentation zu verbessern, und begrüßt Kommentare und Vorschläge von Lesern. + +- Issues: + `https://github.com/codelibs/fess-docs/issues `__ + diff --git a/de/15.10/user/role-search.rst b/de/15.10/user/role-search.rst new file mode 100644 index 000000000..1091e98b5 --- /dev/null +++ b/de/15.10/user/role-search.rst @@ -0,0 +1,58 @@ +==================== +Rollenbasierte Suche +==================== + +|Fess| bietet eine Benutzerverwaltungsfunktion, mit der angemeldete Benutzer basierend auf den Rollen suchen können, denen sie angehören. Benutzer, die von |Fess| verwaltet werden, können nach der Anmeldung die Rollensuche nutzen und ihr eigenes Passwort ändern. + +Bei der Rollensuche werden die für einen Inhalt festgelegten Berechtigungen (Rolle, Gruppe, Benutzer) mit den Berechtigungen des suchenden Benutzers abgeglichen, sodass in den Suchergebnissen nur Inhalte angezeigt werden, für die der Zugriff erlaubt ist. Informationen zur Konfiguration der rollenbasierten Suche, einschließlich der Erstellung von Rollen und Benutzern sowie der Zuweisung von Berechtigungen zu Inhalten, finden Sie unter :doc:`../config/security-role`. + + +Suchmethode +----------- + +Wenn Rollen festgelegt sind und die entsprechenden Inhalte gecrawlt und indiziert wurden, können die Suchergebnisse nur Benutzern angezeigt werden, die über die jeweilige Rolle verfügen. +Wenn ein Benutzer angemeldet ist, erfolgt die Suche basierend auf den Rollen und Gruppen, denen dieser Benutzer angehört. +Ist der Benutzer nicht angemeldet, erfolgt die Suche als guest-Benutzer, wobei nur die für guest freigegebenen Inhalte angezeigt werden. + +.. note:: + Die Suche eines angemeldeten Benutzers verwendet ausschließlich die Berechtigungen des Benutzers selbst sowie seiner Rollen und Gruppen; für guest freigegebene Inhalte (``{role}guest``) werden dabei nicht berücksichtigt. Inhalte, die nur für guest freigegeben sind, werden daher nicht angemeldeten Besuchern angezeigt, angemeldeten Benutzern jedoch nicht (auch nicht solchen, die keine Rollen oder Gruppen haben). Wenn Inhalte auch angemeldeten Benutzern angezeigt werden sollen, tragen Sie in den Berechtigungen der Crawl-Konfiguration zusätzlich zu ``{role}guest`` auch die Rolle ein, die diese Benutzer besitzen (wenn die Inhalte allen Benutzern angezeigt werden sollen, eine Rolle, die allen Benutzern zugewiesen ist). + +Anmeldung +--------- + +Wenn Sie auf den Link „Anmelden“ oben im Suchbildschirm klicken, wird der Anmeldebildschirm angezeigt. Nach Eingabe von Benutzername und Passwort und der Anmeldung kehren Sie zum Suchbildschirm zurück, und alle weiteren Suchen erfolgen basierend auf den Rollen, denen dieser Benutzer angehört. + +.. note:: + Bei einer Integration mit Single Sign-On oder LDAP erfolgt die Anmeldung über das jeweilige Authentifizierungsverfahren. Außerdem kann die Anzeige des Anmeldelinks je nach Konfiguration geändert werden. + +Passwort ändern +--------------- + +Wenn Sie nach der Anmeldung auf den oben im Suchbildschirm angezeigten Benutzernamen klicken, wird ein Menü angezeigt. + +|image0| + +Wenn Sie im Menü auf „Passwort ändern“ klicken, wird der Bildschirm zur Passwortänderung angezeigt. + +|image1| + +Geben Sie im Feld „Aktuelles Passwort“ Ihr aktuelles Passwort, im Feld „Neues Passwort“ das neue Passwort und im Feld „Neues Passwort bestätigen“ das neue Passwort zur Bestätigung (erneut) ein und klicken Sie auf die Schaltfläche „Aktualisieren“, um das Passwort zu aktualisieren. +Durch die Passwortänderung werden Sie abgemeldet; melden Sie sich mit dem neuen Passwort erneut an. +Dieser Bildschirm ist die Seite ``/profile`` des Themes der Suchoberfläche, und das Passwort wird mit ``POST /api/v2/auth/password`` geändert (siehe :doc:`../api/api-auth`). + +.. note:: + Das Menü „Passwort ändern“ wird nur für Benutzer angezeigt, die von |Fess| verwaltet werden (sowie für LDAP-Benutzer, deren Bearbeitung erlaubt ist). Für Benutzer, die per Single Sign-On authentifiziert wurden, wird es nicht angezeigt. + Für das neue Passwort können Passwortrichtlinien gelten, die sich beispielsweise auf die Länge oder die zulässigen Zeichenarten beziehen. + +Abmelden +-------- + +Wenn Sie angemeldet sind, können Sie sich abmelden, indem Sie auf den oben im Suchbildschirm angezeigten Benutzernamen klicken und im Menü „Abmelden“ auswählen. +Benutzer mit Administratorrechten können über dasselbe Menü auch „Verwaltung“ auswählen, um zum Verwaltungsbildschirm zu wechseln. + + + +.. |image0| image:: ../../../resources/images/en/15.10/user/role-search-1.png +.. pdf :width: 200 px +.. |image1| image:: ../../../resources/images/en/15.10/user/role-search-2.png +.. pdf :width: 300 px diff --git a/de/15.10/user/search-additional.rst b/de/15.10/user/search-additional.rst new file mode 100644 index 000000000..412378fc5 --- /dev/null +++ b/de/15.10/user/search-additional.rst @@ -0,0 +1,30 @@ +======================== +Versteckte Suchkriterien +======================== + +Wenn Sie eine bestimmte Suchbedingung weitergeben möchten, ohne deren Text auf dem Bildschirm anzuzeigen, können Sie den Parameter ``ex_q`` verwenden. Die in ``ex_q`` angegebene Bedingung wird nicht im Suchfeld angezeigt und bleibt auch dann erhalten, wenn der Bildschirm durch Paginierung oder Facettenfilterung aktualisiert wird. + +In ``ex_q`` können Sie dieselbe Abfragesyntax wie beim regulären Suchbegriff (``q``) verwenden – das Format ``field:value``, Phrasen, Bereichsangaben, Operatoren wie ``OR`` und weitere. Die angegebene Bedingung wird bei der Suche standardmäßig per AND mit der Bedingung von ``q`` verknüpft. Das heißt, Dokumente, die der Bedingung von ``ex_q`` nicht entsprechen, werden aus den Suchergebnissen ausgeschlossen. + +Verwendung +---------- + +Wenn Sie eine Suche ausführen (z. B. über ein Suchformular), fügen Sie den Wert von ``ex_q`` als verstecktes Formularfeld oder als URL-Abfrageparameter hinzu und führen Sie die Suche aus. So können Sie suchen, ohne die Bedingung auf dem Bildschirm anzuzeigen. + +Sie können ``ex_q`` mehrfach angeben. Wie im folgenden Beispiel gezeigt, wird bei Übergabe mehrerer ``ex_q``-Werte jeder davon als Suchbedingung hinzugefügt (leere oder doppelte Werte werden ignoriert). + +.. code-block:: none + + /search?q=keyword&ex_q=label:manual&ex_q=filetype:pdf + +Beibehaltung bei der Paginierung +-------------------------------- + +Fess fügt Paginierungslinks (z. B. nächste/vorherige Seite) und Links zur Facettenfilterung automatisch den Wert von ``ex_q`` hinzu. Dadurch bleibt die Bedingung von ``ex_q`` auch dann erhalten, wenn der Bildschirm durch diese Aktionen aktualisiert wird. + +Wird dagegen über das normale Suchfeld ein Suchbegriff eingegeben und erneut gesucht, wird ``ex_q`` nicht übernommen. Wenn die Bedingung auch über das Suchfeld erhalten bleiben soll, richten Sie in Ihrem eigenen Suchformular ein verstecktes ``ex_q``-Feld ein und senden Sie ``ex_q`` bei jeder Suche mit. + +.. note:: + + * Wenn die Länge eines einzelnen ``ex_q``-Werts ``query.max.length`` (Standardwert: 1000 Zeichen) überschreitet, wird dieser Wert ohne Fehlermeldung ignoriert. + * ``ex_q`` kann nicht nur für die Suche im Web-Bildschirm, sondern auch über die Such-API (``/api/v2``) verwendet werden. In der API gelten die Obergrenze für die Anzahl der ``ex_q``-Elemente pro Anfrage (``api.v2.param.max.array.size``, Standardwert: 100) sowie die Obergrenze für die Länge jedes Elements (``api.v2.param.max.length``, Standardwert: 1000 Zeichen). diff --git a/de/15.10/user/search-and.rst b/de/15.10/user/search-and.rst new file mode 100644 index 000000000..559c42ddd --- /dev/null +++ b/de/15.10/user/search-and.rst @@ -0,0 +1,46 @@ +=========== +AND-Suche +=========== + +Wenn Sie nach Dokumenten suchen möchten, die alle angegebenen Suchbegriffe enthalten, verwenden Sie die AND-Suche. Wenn Sie mehrere Wörter durch Leerzeichen getrennt in das Suchfeld eingeben, wird standardmäßig eine AND-Suche durchgeführt, sodass Sie AND auch weglassen können und dennoch das gleiche Ergebnis erhalten. + +Verwendung +----------- + +Um eine AND-Suche zu verwenden, fügen Sie AND zwischen den Suchbegriffen ein. AND +muss in Großbuchstaben geschrieben werden und erfordert Leerzeichen davor und danach. AND +kann auch weggelassen werden. + +Wenn Sie beispielsweise nach Dokumenten suchen möchten, die sowohl "Suchbegriff1" als auch "Suchbegriff2" enthalten, geben Sie Folgendes in das Suchformular ein: + +:: + + Suchbegriff1 AND Suchbegriff2 + +Wenn Sie AND weglassen und stattdessen Folgendes eingeben, erhalten Sie das gleiche Ergebnis: + +:: + + Suchbegriff1 Suchbegriff2 + +Sie können mit AND auch drei oder mehr Suchbegriffe miteinander verknüpfen. + +:: + + Suchbegriff1 AND Suchbegriff2 AND Suchbegriff3 + +.. note:: + + AND muss in Großbuchstaben geschrieben werden. Wenn es wie ``and`` in Kleinbuchstaben geschrieben wird, wird es nicht als Operator behandelt, sondern als gewöhnliches Suchwort "and" gesucht. ``&&`` kann ebenfalls mit derselben Bedeutung wie AND verwendet werden. + +Mit runden Klammern ``( )`` können Sie die AND-Suche mit anderen Suchbedingungen kombinieren. Wenn Sie beispielsweise nach Dokumenten suchen möchten, die "Suchbegriff1" sowie entweder "Suchbegriff2" oder "Suchbegriff3" enthalten, geben Sie Folgendes ein: + +:: + + Suchbegriff1 AND (Suchbegriff2 OR Suchbegriff3) + +Sie können die AND-Suche auch für bestimmte Felder durchführen. Im folgenden Beispiel werden Dokumente gesucht, die im Feld title "Suchbegriff1" sowie im Feld content "Suchbegriff2" enthalten. + +:: + + title:Suchbegriff1 AND content:Suchbegriff2 diff --git a/de/15.10/user/search-bangs.rst b/de/15.10/user/search-bangs.rst new file mode 100644 index 000000000..08183640a --- /dev/null +++ b/de/15.10/user/search-bangs.rst @@ -0,0 +1,80 @@ +============================================= +Bang-Suche (auf einer anderen Website suchen) +============================================= + +Ein Bang leitet eine Suche an eine andere Website weiter, statt |Fess| zu durchsuchen. Er funktioniert wie die Bangs von DuckDuckGo: Fügen Sie der Suchanfrage ``!`` und ein kurzes Auslösewort hinzu, und |Fess| sendet den Rest der Anfrage an die Website, für die das Auslösewort steht. + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Suchanfrage + - Ziel + * - ``airplane !g`` + - Google, Suche nach ``airplane`` + * - ``!w Ohm's law`` + - Wikipedia, Suche nach ``Ohm's law`` + * - ``!g`` + - Startseite von Google + * - ``airplane !unknown`` + - |Fess|, als normale Suche (``!`` bedeutet NOT, siehe :doc:`search-not`) + +Bangs werden vom Plugin ``fess-webapp-bangs`` bereitgestellt, das |Fess| 15.10 oder neuer voraussetzt. Installieren Sie es über [System > Plugin] in der Administrationsoberfläche oder mit ``bin/fess-setup install plugin fess-webapp-bangs`` (siehe :doc:`../admin/plugin-guide`) und starten Sie |Fess| neu. + +Wann ein Bang erkannt wird +========================== + +- Ein Bang besteht aus ``!`` gefolgt von einem Auslösewort und wird als eigenständiges Wort geschrieben. Beim Auslösewort wird Groß- und Kleinschreibung nicht unterschieden. +- Der Bang wird aus der Suchanfrage entfernt, und der Rest der Anfrage wird an die URL des Bangs gesendet. +- Enthält eine Suchanfrage mehrere definierte Bangs, zählt nur der erste. +- Ein nicht definiertes Auslösewort ist kein Bang. ``!unknown`` wird wie gewohnt gesucht und schließt das Wort ``unknown`` aus. +- ``-g`` und ``NOT g`` schließen weiterhin das Wort ``g`` aus. Nur ``!g`` ist ein Bang. + +Die Suchseite und ``/api/v2/search`` folgen der Weiterleitung: Die API liefert ``redirect_url`` (siehe :doc:`../api/api-search`), und das mit |Fess| gelieferte Theme ``bootstrap`` navigiert dorthin. Andere Themes benötigen die gleiche Behandlung. + +Aufrufer, die nicht weiterleiten können, etwa der Chat, MCP, die JSON-APIs v1 und Classic sowie die Suche in der Administrationsoberfläche, senden die Suche nicht an eine andere Website. Sie entfernen den Bang und durchsuchen den Rest der Anfrage. + +Bangs definieren +================ + +Bangs werden mit der Systemeigenschaft ``bangs.definitions`` definiert. Tragen Sie sie in ``app/WEB-INF/conf/system.properties`` ein oder übergeben Sie sie als ``-Dfess.system.bangs.definitions=...``. Eine Änderung in ``system.properties`` wird ohne Neustart von |Fess| übernommen. + +Der Wert ist eine durch Leerraum getrennte Liste von Einträgen der Form ``Auslösewort=URL``. In der URL wird ``{query}`` durch den URL-kodierten Rest der Suchanfrage ersetzt: + +:: + + bangs.definitions=g=https://www.google.com/search?q={query} w=https://en.wikipedia.org/wiki/Special:Search?search={query} + +- Ein Auslösewort darf weder Leerraum noch ``(``, ``)``, ``!``, ``"``, ``=`` oder ``:`` enthalten. +- Akzeptiert werden nur absolute URLs mit ``http`` oder ``https``. +- Ein Eintrag, der diese Regeln nicht erfüllt, wird nicht verwendet. Im |Fess|-Protokoll wird eine Warnung ausgegeben, die übrigen Einträge bleiben in Kraft. +- Wird dasselbe Auslösewort zweimal definiert, gilt die erste Definition. +- Ein leerer Wert schaltet alle Bangs aus. + +Ist ``bangs.definitions`` nicht gesetzt, stehen die folgenden fünf Bangs zur Verfügung: + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Auslösewort + - Website + * - ``g`` + - Google + * - ``b`` + - Bing + * - ``ddg`` + - DuckDuckGo + * - ``w`` + - Wikipedia (Englisch) + * - ``gh`` + - GitHub + +Das Setzen von ``bangs.definitions`` ersetzt diese Liste. Um die Standard-Bangs zu behalten und einen weiteren hinzuzufügen, schreiben Sie alle benötigten Einträge auf. + +Siehe auch +========== + +- :doc:`search-not` - NOT-Suche +- :doc:`special-char` - Sonderzeichen und Escape-Zeichen +- :doc:`../api/api-search` - Such-API diff --git a/de/15.10/user/search-boost.rst b/de/15.10/user/search-boost.rst new file mode 100644 index 000000000..6b1f0e378 --- /dev/null +++ b/de/15.10/user/search-boost.rst @@ -0,0 +1,46 @@ +================== +Boost-Suche +================== + +Boost-Suche (Gewichtete Suche) +================================ + +Wenn Sie unter den Suchbegriffen einen bestimmten Suchbegriff bevorzugen möchten, verwenden Sie die Boost-Suche. Mit der Boost-Suche ist eine Suche entsprechend der Wichtigkeit der Suchbegriffe möglich. + +Verwendung +------------ + +Um die Boost-Suche zu verwenden, geben Sie den Boost-Wert (Gewichtungswert) unmittelbar nach dem Suchbegriff im Format „^Boost-Wert“ an. Schreiben Sie den Boost-Wert ohne Leerzeichen direkt hinter den Suchbegriff. + +Wenn Sie beispielsweise bei der Suche nach „Apfel Orange“ „Apfel“ stärker gewichten möchten, geben Sie Folgendes in das Suchformular ein: + +:: + + Apfel^100 Orange + +In diesem Beispiel wird der Boost-Wert nur auf „Apfel“ angewendet, nicht auf „Orange“. + +Boost-Wert +------------ + +Als Boost-Wert geben Sie eine Zahl an. Neben Ganzzahlen können auch Dezimalzahlen wie ``2.5`` angegeben werden. + +- Bei Angabe eines Werts größer als 1 erhöht sich die Gewichtung dieses Suchbegriffs. +- Bei Angabe eines Werts größer als 0 und kleiner als 1 (z. B. ``0.5``) verringert sich die Gewichtung dieses Suchbegriffs. + +Der Boost-Wert legt nicht absolut die Score der Suchergebnisse fest, sondern passt die relative Gewichtung im Verhältnis zu den anderen Suchbegriffen an. + +Kombination mit anderer Suchsyntax +------------------------------------ + +Die Boost-Suche kann mit anderer Suchsyntax kombiniert werden. So kann beispielsweise auch einem Suchbegriff, für den ein Feld angegeben ist, ein Boost-Wert hinzugefügt werden. + +:: + + title:Apfel^100 Orange + +In diesem Beispiel gilt der Standardoperator (AND) für mehrere nebeneinander stehende Suchbegriffe. Es werden daher nur Dokumente gefunden, die im Feld title „Apfel“ und außerdem „Orange“ enthalten. Wenn Dokumente mit „Apfel“ bevorzugt werden sollen, Dokumente ohne „Apfel“ aber ebenfalls im Ergebnis bleiben sollen, verknüpfen Sie die Begriffe mit OR. + +:: + + title:Apfel^100 OR Orange diff --git a/de/15.10/user/search-field.rst b/de/15.10/user/search-field.rst new file mode 100644 index 000000000..b57c749d2 --- /dev/null +++ b/de/15.10/user/search-field.rst @@ -0,0 +1,137 @@ +=============================================== +Feldsuche (Eingrenzung auf Titel, URL und mehr) +=============================================== + +Feldspezifische Suche +======================= + +Durch eine feldspezifische Suche (Feldsuche), die sich nur auf ein bestimmtes Feld bezieht, können Sie die Suche gezielt eingrenzen – zum Beispiel nur auf den Titel oder nur auf die URL. + +Die von |Fess| gecrawlten Ergebnisse werden in einzelnen Feldern wie Titel oder Haupttext gespeichert. Durch die Angabe dieser Felder bei der Suche können Sie detaillierte Suchkriterien wie Dokumenttyp oder Größe festlegen. + +Verfügbare Felder +------------------- + +Standardmäßig können die folgenden Felder für die Suche angegeben werden. + +.. list-table:: + :header-rows: 1 + + * - Feldname + - Beschreibung + - Datentyp + * - url + - Gecrawlte URL + - Keyword + * - host + - In der gecrawlten URL enthaltener Hostname + - Keyword + * - site + - Zeichenkette aus der URL ohne Schema und Query-String (Hostname und Pfad). Die Suche erfolgt als Präfix-Suche (Anfangsübereinstimmung) + - Keyword + * - title + - Titel + - Text + * - content + - Haupttext + - Text + * - content_length + - Größe des Dokuments (in Byte) + - Numerisch + * - last_modified + - Datum und Uhrzeit der letzten Änderung des Dokuments + - Datum + * - timestamp + - Datum und Uhrzeit der Registrierung des Dokuments (bzw. der Zeitpunkt des Crawlings, falls das letzte Änderungsdatum nicht ermittelt werden kann) + - Datum + * - mimetype + - MIME-Typ des Dokuments (z. B. ``text/html``) + - Keyword + * - filetype + - Aus dem MIME-Typ abgeleiteter Dateityp (z. B. ``html``, ``word``, ``pdf``; falls nicht zutreffend ``others``) + - Keyword + * - filename + - Dateiname am Ende des URL-Pfads + - Keyword + * - label + - Dem Dokument zugewiesener Label-Wert + - Keyword + * - lang + - Sprachcode des Dokuments (z. B. ``ja``, ``en``) + - Keyword + * - anchor + - Aus einer HTML-Seite extrahierte Ziel-URL eines Links (nur beim Web-Crawling) + - Keyword + * - click_count + - Anzahl der Klicks auf das Dokument + - Numerisch + * - favorite_count + - Anzahl der Favorisierungen des Dokuments + - Numerisch + * - owner + - Kontoname des Dateibesitzers + - Keyword + * - last_modifier + - Letzter Bearbeiter der Datei + - Keyword + +Tabelle: Liste der verfügbaren Felder + +Der „Datentyp" gibt an, wie sich die Suchmethode je nach Feld unterscheidet. + +* Keyword: Es wird eine exakte Übereinstimmung über den gesamten Wert durchgeführt. Kann auch mit Wildcard-Suche oder Präfix-Suche kombiniert werden. +* Text: Es wird eine Volltextsuche über die durch morphologische Analyse usw. zerlegten Wörter durchgeführt. Dies betrifft z. B. title und content. +* Numerisch/Datum: Die :doc:`Bereichssuche ` kann verwendet werden. + +Wenn kein Feld angegeben wird, erfolgt die Suche über title und content. Je nach Konfiguration können auch weitere Felder als Suchziel hinzugefügt werden. + +.. note:: + Je nach Crawling-Ziel werden manche Felder nicht mit einem Wert belegt. So wird anchor beispielsweise nur beim Web-Crawling registriert. lang wird aus dem Sprachattribut des HTML oder aus der im Text des Dokuments erkannten Sprache übernommen; es wird nicht registriert, wenn keine Sprache erkannt werden kann oder die erkannte Sprache nicht in ``supported.languages`` enthalten ist. Außerdem lassen sich Felder wie segment (eine Sitzungs-ID, die den jeweiligen Crawling-Lauf kennzeichnet) oder doc_id (eine vom System vergebene interne ID) angeben, diese werden jedoch bei der normalen Suche in der Regel nicht verwendet. + +owner und last_modifier werden beim Crawlen von Dateiservern und Ähnlichem registriert. owner +enthält den Kontonamen des Dateibesitzers aus SMB-, Dateisystem- und FTP-Crawls (ein Wert wie +``DOMAIN\alice`` wird zu ``alice``). last_modifier enthält den letzten Bearbeiter, der aus einem +Office-Dokument o. Ä. extrahiert wird, ersatzweise den Besitzer. Für HTML aus einem Web-Crawl wird +kein owner registriert. Suchen Sie zum Beispiel mit ``owner:alice`` oder +``last_modifier:"Taro Yamada"``. Im mitgelieferten Theme lassen sich Besitzer und letzter Bearbeiter +in der erweiterten Suche angeben. Administratoren können die Felder mit +``crawler.document.file.owner.enabled`` und ``crawler.document.file.last.modifier.enabled`` +(beide standardmäßig ``true``) ein- und ausschalten. + +Wenn HTML-Dateien als Suchziel verwendet werden, wird das title-Tag im title-Feld und die Zeichenkette unter dem body-Tag im content-Feld registriert. + +Verwendung +----------- + +Um eine feldspezifische Suche durchzuführen, geben Sie "Feldname:Suchbegriff" in das Suchformular ein, wobei Feldname und Suchbegriff durch einen Doppelpunkt (:) getrennt sind. + +Um nach fess im title-Feld zu suchen, geben Sie Folgendes ein: + +:: + + title:fess + +Mit dieser Suche werden Dokumente als Suchergebnis angezeigt, die fess im title-Feld enthalten. + +Um im url-Feld zu suchen, geben Sie Folgendes ein: + +:: + + url:https\:\/\/fess.codelibs.org\/ja\/15.10\/* + url:"https://fess.codelibs.org/ja/15.10/*" + +Da bei der ersten Variante Wildcard-Suche verwendet werden kann, ist auch eine Schreibweise wie ``url:*\/\/fess.codelibs.org\/*`` möglich. Da „:" und „/" in der URL Sonderzeichen der Suchabfrage sind, müssen sie mit ``\`` maskiert werden (siehe :doc:`special-char`). Bei der zweiten Variante kann keine Wildcard-Suche verwendet werden, aber ein Wort, das mit ``*`` endet, wird als Präfix-Suche (Anfangsübereinstimmung) behandelt. + +.. tip:: + Wenn Sie nach einem Teil der URL suchen möchten, können Sie mit ``inurl:`` eine Teilübereinstimmungssuche für die URL durchführen. Beispielsweise sucht ``inurl:15.10`` nach Dokumenten, deren URL ``15.10`` enthält. + +Wenn Sie Felder wie mimetype, filetype oder site angeben, deren Werte ein „/" enthalten, schließen Sie den Wert in Anführungszeichen ein, wie in ``mimetype:"text/html"``, oder maskieren Sie ihn wie in ``mimetype:text\/html``. + +Zu verwandten Suchsyntaxen siehe auch die :doc:`Wildcard-Suche `, die :doc:`Bereichssuche `, die :doc:`Sortierte Suche ` und :doc:`Sonderzeichen `. + +Siehe auch +----------- + +- :doc:`search-range` +- :doc:`search-wildcard` +- :doc:`special-char` diff --git a/de/15.10/user/search-fuzzy.rst b/de/15.10/user/search-fuzzy.rst new file mode 100644 index 000000000..d479acd36 --- /dev/null +++ b/de/15.10/user/search-fuzzy.rst @@ -0,0 +1,66 @@ +================ +Unscharfe Suche +================ + +Unscharfe Suche (Fuzzy-Suche) +=============================== + +Wenn Sie auch nach Wörtern suchen möchten, die nicht exakt mit dem Suchbegriff übereinstimmen, können Sie die unscharfe Suche (Fuzzy-Suche) verwenden. Dies ist beispielsweise bei Tippfehlern, abweichender Schreibweise oder Rechtschreibvarianten hilfreich. Die unscharfe Suche ist eine Suchmethode, bei der ein Wort als Treffer gilt, wenn der Unterschied (die Editierdistanz) zwischen dem Suchbegriff und einem im Index registrierten Wort innerhalb eines bestimmten Bereichs liegt. Die Editierdistanz ist die minimale Anzahl an Einfügungen, Löschungen und Ersetzungen von Zeichen, die notwendig sind, um ein Wort in ein anderes umzuwandeln. |Fess| verwendet standardmäßig zusätzlich zu diesen Operationen die Damerau-Levenshtein-Distanz (optimal string alignment), bei der auch das Vertauschen von 2 benachbarten Zeichen als eine einzelne Änderung gezählt wird. + +Verwendung +----------- + +Fügen Sie "~" nach dem Suchbegriff an, auf den Sie die unscharfe Suche anwenden möchten. + +Wenn Sie beispielsweise das Wort "fess" unscharf suchen möchten, können Sie durch Eingabe des Folgenden in das Suchformular Dokumente finden, die Wörter enthalten, die "fess" ähnlich sind (z. B. "fes"). + +:: + + fess~ + +Wenn Sie nach "~" eine Zahl anfügen, können Sie die zulässige Editierdistanz (bis zu wie vielen Zeichen Unterschied toleriert wird) angeben. Zulässige Werte sind die ganzen Zahlen 0, 1 oder 2. + +:: + + fess~1 + +Im obigen Beispiel werden Wörter gesucht, deren Editierdistanz zu "fess" höchstens 1 beträgt. + +Wenn Sie die Zahl weglassen und nur "~" angeben, wird eine Editierdistanz von 2 verwendet. Der Höchstwert der Editierdistanz ist 2; auch wenn ein Wert von 3 oder mehr angegeben wird, wird er als 2 behandelt. + +Sie können die unscharfe Suche auch auf ein bestimmtes Feld anwenden. Im folgenden Beispiel werden im Feld title Dokumente gesucht, die Wörter enthalten, die "fess" ähnlich sind. + +:: + + title:fess~ + +Wenn kein Feld angegeben wird, erfolgt die unscharfe Suche in den Feldern title und content. + +Nutzungsbedingungen +-------------------- + +Beachten Sie bei der Verwendung der unscharfen Suche die folgenden Punkte: + +* Die unscharfe Suche wird auf einzelne Wörter angewendet. Sie kann nicht auf Phrasen angewendet werden, die in Anführungszeichen eingeschlossen sind. Eine Zahl, die einer Phrase angehängt wird (zum Beispiel ``"Fess Search"~2``), stellt dabei keine unscharfe Suche dar, sondern eine :doc:`Näherungssuche ` (proximity search), die den Abstand zwischen den Wörtern angibt. +* Die unscharfe Suche erfolgt auf Basis der im Index registrierten Wörter, wobei der Suchbegriff nicht erneut analysiert wird. Daher funktioniert sie möglicherweise nicht wie erwartet bei Texten wie Japanisch, die per Bi-Gramm oder morphologischer Analyse in Token zerlegt werden. Die unscharfe Suche ist vor allem bei alphanumerischen Wörtern wirksam. +* Der Suchbegriff der unscharfen Suche wird einschließlich Groß- und Kleinschreibung unverändert für die Editierdistanz herangezogen. Englische Wörter werden im Index normalerweise in Kleinbuchstaben umgewandelt gespeichert; verwenden Sie daher für den Suchbegriff Kleinbuchstaben. Zum Beispiel verbraucht ``Fess~1`` die Editierdistanz 1 bereits allein durch den Großbuchstaben ``F`` am Anfang und liefert daher nicht dasselbe Ergebnis wie ``fess~1``. Außerdem trifft ``Fess~0`` auf nichts zu, da im Index kein Wort ``Fess`` mit Großbuchstaben existiert (das kleingeschriebene ``fess~0`` ist eine exakte Übereinstimmung). +* Wenn Sie an sehr kurze Wörter mit 1 bis 2 Zeichen "~" (Editierdistanz 2) anhängen, werden auch Wörter gefunden, bei denen nur ungefähr so viele Zeichen ersetzt wurden, wie das Wort lang ist. Zum Beispiel trifft ``ab~`` neben ``ab`` und ``ac`` auch auf ``xy`` zu, bei dem sich beide Zeichen unterscheiden. Da dadurch mehr unerwünschte Treffer entstehen, geben Sie bei kurzen Wörtern eine kleinere Editierdistanz an, etwa ``ab~1``. + +.. note:: + + Das Verhalten der unscharfen Suche kann in ``fess_config.properties`` angepasst werden. + + * ``query.fuzzy.prefix_length`` (Standardwert: ``0``): Die Anzahl der Zeichen vom Anfang des Wortes an, die exakt übereinstimmen müssen. Ein höherer Wert schränkt den Bereich ein, in dem Abweichungen toleriert werden. + * ``query.fuzzy.expansions`` (Standardwert: ``50``): Die maximale Anzahl der Wörter, die als Treffer-Kandidaten expandiert werden. + * ``query.fuzzy.transpositions`` (Standardwert: ``true``): Legt fest, ob das Vertauschen von 2 benachbarten Zeichen als eine einzelne Änderung gezählt wird. Bei ``true`` wird die Damerau-Levenshtein-Distanz verwendet, bei ``false`` die klassische Levenshtein-Distanz. + +.. note:: + + Auch bei einer normalen Suche ohne angehängtes "~" fügt |Fess| für Suchbegriffe ab einer bestimmten Länge (standardmäßig ab 4 Zeichen) automatisch eine leicht gewichtete unscharfe Übereinstimmung als unterstützende Funktion hinzu, um die Relevanz zu erhöhen (``query.boost.fuzzy.*``). Dies dient hauptsächlich der Anpassung der Rangfolge der Suchergebnisse und ist ein von der unscharfen Suche mittels "~" unabhängiger Mechanismus. Da diese unterstützende Übereinstimmung jedoch ebenfalls in die Suchergebnisse einfließt, können Dokumente zum Ergebnis hinzukommen, die den Suchbegriff selbst nicht enthalten, sondern nur ein Wort, das sich um ein Zeichen unterscheidet (Dokumente, die den Suchbegriff selbst enthalten, werden höher eingestuft). Wenn Sie dieses Verhalten abschalten möchten, setzen Sie ``query.boost.fuzzy.min.length`` auf einen negativen Wert (z. B. ``-1``). + +Siehe auch +========== + +- :doc:`search-wildcard` +- :doc:`search-proximity` +- :doc:`special-char` diff --git a/de/15.10/user/search-geo.rst b/de/15.10/user/search-geo.rst new file mode 100644 index 000000000..1d7a28fec --- /dev/null +++ b/de/15.10/user/search-geo.rst @@ -0,0 +1,56 @@ +========================= +Standortbasierte Suche +========================= + +Indem Sie bei der Indexerstellung jedem Dokument Standortinformationen (Breiten- und Längengrad) hinzufügen, können Sie bei der Suche nach dem Abstand von einem angegebenen Punkt filtern. + +Übersicht +------------ + +Bei der standortbasierten Suche werden nur Dokumente in die Suchergebnisse aufgenommen, die sich innerhalb eines Radius um einen angegebenen Punkt (Breiten- und Längengrad) befinden. Diese Einschränkung wird als Filter mithilfe einer geo_distance-Abfrage von OpenSearch angewendet und wirkt sich daher nicht auf die Bewertung (Relevanz) aus. Zudem wird eine Sortierung nach Entfernung nicht unterstützt. + +Das Feld, in dem die Standortinformationen gespeichert werden, muss im OpenSearch-Mapping als Typ ``geo_point`` definiert sein. Standardmäßig ist das Feld ``location`` als Typ ``geo_point`` vorbereitet. Da jedoch standardmäßig kein Mechanismus zum Speichern von Werten im Feld ``location`` bereitgestellt wird, müssen Sie die Standortinformationen selbst hinterlegen, etwa über die Feldzuordnung beim Data-Store-Crawling, per Skript oder über die API zum Registrieren von Dokumenten in der Suchmaschine. + +Verwendung +------------- + +Die standortbasierte Suche wird angegeben, indem Sie der Suchanfrage die folgenden Parameter hinzufügen. Standardmäßig ist sie für das Feld ``location`` verfügbar. + +.. list-table:: + :header-rows: 1 + + * - Parameter + - Beschreibung + * - ``geo..point`` + - Geben Sie Breiten- und Längengrad des Mittelpunkts im Format ``Breitengrad,Längengrad`` an. Die Werte sind Dezimalgrad (Typ Double); geben Sie zwei durch Komma getrennte Zahlen an. Beispiel: ``35.681236,139.767125`` + * - ``geo..distance`` + - Geben Sie die Entfernung (den Radius) vom Mittelpunkt an. Beispiel: ``10km`` + +Tabelle: Anfrageparameter + +Für ```` geben Sie den Namen des Feldes an, in dem die Standortinformationen gespeichert sind. Angegeben werden können nur Felder, die in ``query.geo.fields`` registriert sind; standardmäßig ist dies ``location``. Um ein anderes Feld zu verwenden, mappen Sie es als Typ ``geo_point`` und fügen Sie es durch Komma getrennt in ``query.geo.fields`` in ``fess_config.properties`` hinzu. + +Um beispielsweise Dokumente innerhalb eines Radius von 10 km um den Punkt mit Breitengrad 35.681236 und Längengrad 139.767125 (in der Nähe des Bahnhofs Tokio) zu suchen, fügen Sie der Suchanfrage die folgenden Parameter hinzu. + +:: + + geo.location.point=35.681236,139.767125&geo.location.distance=10km + +Entfernungseinheiten +------------------------ + +Der Wert von ``geo..distance`` wird als Entfernungseinheit von OpenSearch interpretiert. Neben ``km`` (Kilometer) können unter anderem ``mm``, ``cm``, ``m``, ``in``, ``ft``, ``yd``, ``mi`` (Meilen) und ``nmi`` (Seemeilen) verwendet werden. Wird die Einheit weggelassen und nur eine Zahl angegeben, wird diese als Meter interpretiert (Beispiel: ``500`` entspricht 500 Metern). + +Mehrfachangabe +----------------- + +* Wenn Sie für dasselbe Feld mehrere ``geo..point``-Werte angeben, werden Dokumente gesucht, die sich innerhalb des Radius mindestens eines der Punkte befinden (ODER-Bedingung). +* Wenn Sie für unterschiedliche Felder jeweils Standortinformationen angeben, werden Dokumente gesucht, die alle Bedingungen erfüllen (UND-Bedingung). + +.. note:: + + ``geo..point`` und ``geo..distance`` müssen beide angegeben werden. Wird ``distance`` nicht angegeben, wird die Bedingung für dieses ``point`` ignoriert. Zudem tritt ein Fehler auf, wenn der Wert von ``point`` nicht dem Format ``Breitengrad,Längengrad`` (zwei durch Komma getrennte Zahlen) entspricht oder nicht als Zahl interpretiert werden kann. + +.. note:: + + Die Standortsuche ist eine Einschränkung der Suchbegriffe. Ist der Suchbegriff leer, wird die Suche daher nicht ausgeführt und das Ergebnis enthält 0 Treffer. Geben Sie bei Anfragen für die Standortsuche einen Suchbegriff an. diff --git a/de/15.10/user/search-label.rst b/de/15.10/user/search-label.rst new file mode 100644 index 000000000..da61d19d3 --- /dev/null +++ b/de/15.10/user/search-label.rst @@ -0,0 +1,29 @@ +==================== +Label-basierte Suche +==================== + +Label-basierte Suche (Kategoriesuche) +===================================== + +Durch Hinzufügen von Label-Informationen zur Kategorisierung der zu durchsuchenden Dokumente ist es möglich, bei der Suche eine nach Labeln gefilterte Suche durchzuführen. Mithilfe von Labeln können Sie den Suchbereich beispielsweise auf Abteilungen, Websites oder Dokumenttypen eingrenzen. + +Wenn Labels vorab in der Verwaltungsoberfläche registriert werden, kann die Filterung nach Labeln im Suchbildschirm verwendet werden. Die verfügbaren Labels können bei der Suche über ein Dropdown-Menü in Mehrfachauswahl ausgewählt werden. Werden mehrere Labels ausgewählt, umfasst die Suche Dokumente, denen mindestens eines der ausgewählten Labels zugewiesen ist. Wenn keine Labels registriert sind, wird das Label-Dropdown-Feld nicht angezeigt. + +.. note:: + Da für Labels Berechtigungen festgelegt werden können, werden im Dropdown-Menü nur die Labels angezeigt, auf die der suchende Benutzer Zugriff hat. Außerdem können die angezeigten Labels je nach virtuellem Host oder Locale (Sprache) unterschiedlich sein. Daher werden registrierte Labels je nach Benutzer unter Umständen nicht im Dropdown-Menü angezeigt. + +Labels werden definiert, indem die Ziele, denen ein Label zugewiesen werden soll, über einen regulären Ausdruck für den URL-Pfad angegeben werden. Informationen zur Registrierung von Labels und zu den Konfigurationselementen finden Sie in der :doc:`Label-Verwaltungsanleitung <../admin/labeltype-guide>`. + +Verwendung +---------- + +Bei der Suche können Sie Label-Informationen auswählen. Die Label-Informationen können in den Suchoptionen ausgewählt werden, die durch Klicken auf die Schaltfläche „Optionen" angezeigt werden. + +|image0| + +Indem Sie Labels festlegen und einen Index erstellen, können Sie nach Dokumenten suchen, denen jeweils ein Label zugewiesen wurde. Eine Suche ohne Angabe eines Labels entspricht wie gewohnt einer Suche über alle Dokumente. + +Die Zuweisung von Labels zu Dokumenten erfolgt beim Crawlen und Erstellen des Index, indem die URL des Dokuments mit den für das Label konfigurierten Pfaden abgeglichen wird. Wenn Sie daher die Label-Definition (Zielpfade oder ausgeschlossene Pfade) hinzufügen oder ändern, wirkt sich dies nicht automatisch auf bereits indexierte Dokumente aus. Um die Änderungen zu übernehmen, crawlen Sie die betreffenden Dokumente erneut, oder aktualisieren Sie den Index, indem Sie den im Scheduler registrierten Job „Label Updater" ausführen. + +.. |image0| image:: ../../../resources/images/en/15.10/user/search-label-1.png +.. pdf :width: 300 px diff --git a/de/15.10/user/search-not.rst b/de/15.10/user/search-not.rst new file mode 100644 index 000000000..91a075b29 --- /dev/null +++ b/de/15.10/user/search-not.rst @@ -0,0 +1,45 @@ +=========================== +NOT-Suche (Ausschlusssuche) +=========================== + +Wenn Sie nach Dokumenten suchen möchten, die ein bestimmtes Wort nicht enthalten, können Sie die NOT-Suche verwenden. +Dies wird auch als Ausschlusssuche bezeichnet und ist hilfreich, wenn Sie bestimmte Schlüsselwörter aus den Suchergebnissen ausschließen und dadurch irrelevante Treffer reduzieren möchten. + +Verwendung +----------- + +Bei der NOT-Suche wird NOT vor das Wort gesetzt, das nicht enthalten sein soll. NOT +muss in Großbuchstaben geschrieben werden und erfordert Leerzeichen davor und danach. + +Wenn Sie beispielsweise nach Dokumenten suchen möchten, die "Suchbegriff1" enthalten, aber "Suchbegriff2" nicht enthalten, geben Sie Folgendes ein: + +:: + + Suchbegriff1 NOT Suchbegriff2 + +.. note:: + + NOT muss in Großbuchstaben geschrieben werden. Wenn es wie ``not`` in Kleinbuchstaben geschrieben wird, wird es nicht als Operator behandelt, sondern als gewöhnliches Suchwort "not" gesucht. Wird zudem direkt vor dem auszuschließenden Wort ein ``-`` vorangestellt, wie in ``Suchbegriff1 -Suchbegriff2``, hat dies dieselbe Bedeutung wie NOT. + +Mit runden Klammern ``( )`` können Sie die NOT-Suche mit anderen Suchbedingungen kombinieren. Wenn Sie beispielsweise nach Dokumenten suchen möchten, die entweder "Suchbegriff1" oder "Suchbegriff2" enthalten, aber "Suchbegriff3" nicht enthalten, geben Sie Folgendes ein: + +:: + + (Suchbegriff1 OR Suchbegriff2) NOT Suchbegriff3 + +Sie können die NOT-Suche auch für ein bestimmtes Feld durchführen. Im folgenden Beispiel werden Dokumente gesucht, die im Feld title "Suchbegriff1" enthalten, aber im Feld title "Suchbegriff2" nicht enthalten. + +:: + + title:Suchbegriff1 NOT title:Suchbegriff2 + +.. note:: + + Ist das Plugin ``fess-webapp-bangs`` installiert, ist ein definierter Bang wie ``!g`` kein Ausschluss mehr, sondern sendet die Suche an eine andere Website. Siehe :doc:`search-bangs`. + +Siehe auch +----------- + +- :doc:`search-and` +- :doc:`search-or` +- :doc:`special-char` diff --git a/de/15.10/user/search-or.rst b/de/15.10/user/search-or.rst new file mode 100644 index 000000000..40f578742 --- /dev/null +++ b/de/15.10/user/search-or.rst @@ -0,0 +1,39 @@ +============================================= +OR-Suche (Treffer mit einem der Suchbegriffe) +============================================= + +Wenn Sie nach Dokumenten suchen möchten, die einen der Suchbegriffe enthalten, verwenden Sie die OR-Suche. Wenn Sie mehrere Wörter in das Suchfeld eingeben, wird standardmäßig eine AND-Suche durchgeführt. + +Verwendung +----------- + +Um eine OR-Suche zu verwenden, fügen Sie OR zwischen den Suchbegriffen ein. OR +muss in Großbuchstaben geschrieben werden und erfordert Leerzeichen davor und danach. + +Wenn Sie beispielsweise nach Dokumenten suchen möchten, die entweder "Suchbegriff1" oder "Suchbegriff2" enthalten, geben Sie Folgendes in das Suchformular ein: + +:: + + Suchbegriff1 OR Suchbegriff2 + +Sie können mit OR auch drei oder mehr Suchbegriffe miteinander verknüpfen. + +:: + + Suchbegriff1 OR Suchbegriff2 OR Suchbegriff3 + +.. note:: + + OR muss in Großbuchstaben geschrieben werden. Wenn es wie ``or`` in Kleinbuchstaben geschrieben wird, wird es nicht als Operator behandelt, sondern als gewöhnliches Suchwort "or" gesucht. ``||`` kann ebenfalls mit derselben Bedeutung wie OR verwendet werden. + +Mit runden Klammern ``( )`` können Sie die OR-Suche mit anderen Suchbedingungen kombinieren. Wenn Sie beispielsweise nach Dokumenten suchen möchten, die entweder "Suchbegriff1" oder "Suchbegriff2" sowie "Suchbegriff3" enthalten, geben Sie Folgendes ein: + +:: + + (Suchbegriff1 OR Suchbegriff2) Suchbegriff3 + +Sie können die OR-Suche auch für bestimmte Felder durchführen. Im folgenden Beispiel werden Dokumente gesucht, die im Feld title "Suchbegriff1" oder im Feld content "Suchbegriff2" enthalten. + +:: + + title:Suchbegriff1 OR content:Suchbegriff2 diff --git a/de/15.10/user/search-proximity.rst b/de/15.10/user/search-proximity.rst new file mode 100644 index 000000000..24cd16f6c --- /dev/null +++ b/de/15.10/user/search-proximity.rst @@ -0,0 +1,70 @@ +================ +Näherungssuche +================ +Näherungssuche (Proximity-Suche) +================================== + +Mit der Näherungssuche finden Sie Dokumente, in denen die Wörter einer Phrase nahe beieinander stehen, auch wenn sie nicht direkt aufeinander folgen. Sie ist nützlich, wenn zwischen den gesuchten Wörtern weitere Wörter stehen können. + +Verwendung +------------ + +Schließen Sie die Wörter in doppelte Anführungszeichen ein und fügen Sie hinter dem schließenden Anführungszeichen "~" und eine Zahl an. + +Die folgende Suche findet beispielsweise Dokumente, in denen "Fess" und "Suche" innerhalb eines Abstands von 3 vorkommen: + +:: + + "Fess Suche"~3 + +Die Zahl gibt die maximale Anzahl an Positionsverschiebungen an, die zwischen den Wörtern zulässig sind (siehe "Wie der Abstand gezählt wird" weiter unten). Je größer die Zahl, desto weiter dürfen die Wörter auseinander liegen. + +Sie können die Näherungssuche auch auf ein bestimmtes Feld anwenden. Im folgenden Beispiel wird das Feld title durchsucht. + +:: + + title:"Fess Suche"~3 + +Wenn Sie die Zahl weglassen und nur "~" angeben (zum Beispiel ``"Fess Suche"~``), wird die Phrase als normale Phrasensuche behandelt, bei der die Wörter direkt aufeinander folgen müssen. Eine Dezimalzahl wird auf eine ganze Zahl gekürzt (``~2.5`` wird als ``~2`` behandelt). + +Die Näherungssuche kann mit einem Boost kombiniert werden. Im folgenden Beispiel wird die Näherungssuche mit dem Faktor 2 gewichtet (siehe :doc:`search-boost`). + +:: + + "Fess Suche"~5^2 + +Wie der Abstand gezählt wird +------------------------------ + +* Die Zahl ist die maximale Anzahl an Positionsverschiebungen zwischen den Wörtern. Sie wird in Token gezählt, die der Analyzer des Zielfelds erzeugt, nicht in Zeichen oder durch Leerzeichen getrennten Wörtern. Bei englischem Text entspricht sie ungefähr der Anzahl der Wörter zwischen den Begriffen. Wörter, die bei der Analyse als Stoppwörter entfernt werden, werden dennoch mitgezählt. +* Die Wörter dürfen in anderer Reihenfolge vorkommen, für die umgekehrte Reihenfolge ist jedoch eine größere Zahl erforderlich. Ein Dokument mit "quick brown fox" trifft beispielsweise auf ``"quick fox"~1`` zu, auf ``"fox quick"`` aber erst ab ``~3``. + +:: + + "quick fox"~1 + "fox quick"~3 + +Japanische, chinesische und koreanische Texte (CJK) +----------------------------------------------------- + +Bei japanischen und anderen CJK-Texten hängt die Einheit, in der der Abstand gezählt wird, vom Feld ab. + +* In den allgemeinen Feldern title und content entspricht der Abstand in etwa der Anzahl der Zeichen zwischen den Wörtern. +* In den sprachspezifischen Feldern wird in morphologischen Token gezählt; entfernte Partikel werden ebenfalls mitgezählt. + +Trennen Sie die Wörter daher durch Leerzeichen und geben Sie eine großzügige Zahl an. + +:: + + "全文 検索"~5 + "大阪 おいしい"~10 + +Eine Zeichenfolge ohne Leerzeichen (zum Beispiel ``"大阪おいしい"~10``) funktioniert als Näherungssuche zwischen den Wörtern möglicherweise nicht wie erwartet, da sie in den allgemeinen Feldern als eine zusammenhängende Zeichenfolge abgeglichen wird. Trennen Sie die Wörter daher durch Leerzeichen. Der Abstand lässt sich nicht exakt in eine Zeichenanzahl umrechnen. Beginnen Sie daher mit einer großzügigen Zahl und grenzen Sie sie anhand der Ergebnisse ein. + +Siehe auch +============ + +- :doc:`search-fuzzy` +- :doc:`search-boost` +- :doc:`search-field` +- :doc:`special-char` diff --git a/de/15.10/user/search-range.rst b/de/15.10/user/search-range.rst new file mode 100644 index 000000000..eb9a8a95b --- /dev/null +++ b/de/15.10/user/search-range.rst @@ -0,0 +1,71 @@ +============= +Bereichssuche +============= + +Wenn Sie in einem Feld Daten speichern, für die sich ein Bereich angeben lässt, wie z. B. Zahlen oder Datums-/Zeitangaben, können Sie für dieses Feld eine Bereichssuche durchführen. + +Verwendung +---------- + +Um eine Bereichssuche durchzuführen, geben Sie "Feldname:[Wert TO Wert]" in das Suchformular ein. Als Trennzeichen für den Bereich wird das großgeschriebene ``TO`` in Halbbreitenschreibweise verwendet. + +Um beispielsweise Dokumente zu suchen, deren content_length-Feld einen Wert zwischen 1 kByte und 10 kByte hat, geben Sie Folgendes in das Suchformular ein: + +:: + + content_length:[1000 TO 10000] + +Eckige Klammern ``[ ]`` schließen die Bereichsgrenzen ein (größer/gleich bzw. kleiner/gleich), geschweifte Klammern ``{ }`` schließen die Bereichsgrenzen aus (größer als bzw. kleiner als). Beide Klammertypen lassen sich auch kombinieren. So steht ``content_length:{1000 TO 10000]`` beispielsweise für Dokumente, deren Wert größer als 1000 und kleiner oder gleich 10000 ist. + +Setzen Sie eine Seite auf ``*``, geben Sie damit einen offenen Bereich an, bei dem nur die Ober- oder Untergrenze festgelegt ist. ``content_length:[1000 TO *]`` steht für "größer oder gleich 1000", ``content_length:[* TO 10000]`` für "kleiner oder gleich 10000". + +Die Bereichssuche ist nur für Felder verfügbar, die als Suchziel registriert sind. Standardmäßig lässt sich die Bereichssuche für Felder wie content_length, last_modified, timestamp, click_count und favorite_count verwenden. + +Zeitbereichssuche +----------------- + +Um eine Bereichssuche nach Zeit (Datum/Uhrzeit) durchzuführen, geben Sie "last_modified:[Datum/Zeit1 TO Datum/Zeit2]" (Datum/Zeit1 < Datum/Zeit2) in das Suchformular ein. Liegt Datum/Zeit1 dabei nach Datum/Zeit2, führt dies nicht zu einem Fehler, sondern liefert lediglich 0 Treffer. + +Datum und Uhrzeit werden im Format ISO 8601 angegeben. Das Format lautet ``YYYY-MM-DDThh:mm:ss.SSSZ``, wobei die Uhrzeit und alles danach weggelassen werden kann. + +.. list-table:: + :header-rows: 1 + + * - Angabe + - Beispiel + * - Nur Jahr, Monat, Tag + - 2012-12-02 + * - Jahr, Monat, Tag sowie Stunde, Minute, Sekunde + - 2012-12-02T10:45:23Z + * - Jahr, Monat, Tag sowie Stunde, Minute, Sekunde (bis Millisekunden) + - 2012-12-02T10:45:23.235Z + +Bei der Angabe von Datum und Uhrzeit können Sie eine Datums-/Zeitarithmetik verwenden, die auf dem aktuellen Zeitpunkt basiert. Die verfügbaren Symbole sind wie folgt: + +.. list-table:: + :header-rows: 1 + + * - Symbol + - Bedeutung + * - ``now`` + - Aktuelles Datum/Aktuelle Uhrzeit + * - ``y`` / ``M`` / ``w`` / ``d`` / ``h`` / ``m`` / ``s`` + - Jahr / Monat / Woche / Tag / Stunde / Minute / Sekunde + * - ``+`` / ``-`` + - Addition / Subtraktion + * - ``/`` + - Runden (auf die Einheit nach ``/``) + +Wenn Sie ``now`` oder ein bestimmtes Datum/eine bestimmte Uhrzeit als Referenz verwenden, können Sie Symbole wie ``+``, ``-`` (Addition, Subtraktion) oder ``/`` (Runden) anhängen. Verwenden Sie jedoch nicht ``now``, sondern ein bestimmtes Datum/eine bestimmte Uhrzeit als Referenz, müssen Sie zwischen Datum/Uhrzeit und dem Symbol ``||`` einfügen (Beispiel: ``2016-01-01||+1M/d``). + +``/`` ist ein Symbol, das auf die dem ``/`` folgende Einheit rundet. ``now-1d/d`` steht unabhängig davon, um welche Uhrzeit die Suche heute ausgeführt wird, für 00:00 Uhr des Vortages, also für 00:00 Uhr des heutigen Tages minus 1 Tag. + +Diese Datums-/Zeitarithmetik wird auf Seiten der Suchmaschine (OpenSearch) ausgewertet und ist nur für Felder vom Datums-/Zeittyp gültig. + +Um beispielsweise Dokumente zu suchen, deren last_modified-Feld einen Wert zwischen dem aktuellen Datum (angenommen 21. Februar 2016, 20 Uhr) und 30 Tagen davor aufweist, geben Sie Folgendes in das Suchformular ein: + +:: + + last_modified:[now-30d TO now] + +Ist die aktuelle Zeit der 21. Februar 2016, 20 Uhr (UTC), entspricht dies ungefähr dem Bereich ``[2016-01-22T20:00:00Z TO 2016-02-21T20:00:00Z]``. diff --git a/de/15.10/user/search-sort.rst b/de/15.10/user/search-sort.rst new file mode 100644 index 000000000..75dbb7c35 --- /dev/null +++ b/de/15.10/user/search-sort.rst @@ -0,0 +1,76 @@ +================== +Sortierte Suche +================== + +Sie können Suchergebnisse nach Feldern wie dem Suchdatum sortieren. + +Sortierbare Felder +-------------------- + +Standardmäßig können die folgenden Felder zum Sortieren angegeben werden. + +.. list-table:: + :header-rows: 1 + + * - Feldname + - Beschreibung + * - created + - Crawl-Datum und Uhrzeit + * - content_length + - Größe des gecrawlten Dokuments + * - last_modified + - Letztes Änderungsdatum und Uhrzeit des gecrawlten Dokuments + * - filename + - Dateiname + * - score + - Bewertung + * - timestamp + - Datum und Uhrzeit der Dokumentindizierung + * - click_count + - Anzahl der Klicks auf das Dokument + * - favorite_count + - Anzahl der Favorisierungen des Dokuments + +Tabelle: Liste der sortierbaren Felder + + +Sie können auch eigene Felder als Sortierziel hinzufügen. Geben Sie dazu in ``query.additional.sort.fields`` in ``fess_config.properties`` die gewünschten Feldnamen durch Kommas getrennt an (der Standardwert ist leer). Die hier angegebenen Felder werden zu den oben genannten Standardfeldern hinzugefügt und stehen dann zur Sortierung zur Verfügung. Zu beachten ist, dass die als Sortierziel vorgesehenen Felder zuvor im Index registriert sein müssen. + +Verwendung +----------- + +Bei der Suche können Sortierkriterien ausgewählt werden. Sortierkriterien können im Suchoptionen-Dialog ausgewählt werden, der durch Klicken auf die Optionsschaltfläche angezeigt wird. + +|image0| + +Um im Suchfeld zu sortieren, geben Sie "sort:Feldname" in das Suchformular ein, wobei sort und Feldname durch einen Doppelpunkt (:) getrennt sind. + +Das Folgende sucht nach fess und sortiert nach Dokumentgröße in aufsteigender Reihenfolge. + +:: + + fess sort:content_length + +Um in absteigender Reihenfolge zu sortieren, fügen Sie ``.desc`` hinter dem Feldnamen an. + +:: + + fess sort:content_length.desc + +Als Suffix nach dem Feldnamen kann ``.asc`` (aufsteigend) oder ``.desc`` (absteigend) angegeben werden; wird es weggelassen, wird aufsteigend sortiert. + +Um nach mehreren Feldern zu sortieren, geben Sie diese wie folgt durch Kommas (,) getrennt an. Das zuerst angegebene Feld hat Vorrang, und Dokumente mit demselben Wert für dieses Feld werden anhand des nächsten Feldes sortiert. + +:: + + fess sort:content_length.desc,last_modified + +.. note:: + Wenn Sie in ``sort:`` in den Suchbegriffen einen Feldnamen angeben, der nicht in der Liste der sortierbaren Felder enthalten ist, oder eine andere Sortierreihenfolge als ``asc`` oder ``desc``, führt das nicht zu einem Fehler. + Stattdessen wird ``sort:`` nicht als Sortierbedingung behandelt, und die Suche wird erneut ausgeführt, wobei die Sonderzeichen im gesamten Suchbegriff (etwa ``:``) als gewöhnliche Zeichen behandelt werden. + Die Ergebnisse werden nicht sortiert, und in den meisten Fällen werden keine Dokumente gefunden. + + Wird derselbe Wert im Parameter ``sort`` der Such-API angegeben, führt das zu einem Fehler (400 Bad Request). + +.. |image0| image:: ../../../resources/images/en/15.10/user/search-sort-1.png +.. pdf :width: 300 px diff --git a/de/15.10/user/search-wildcard.rst b/de/15.10/user/search-wildcard.rst new file mode 100644 index 000000000..967a10035 --- /dev/null +++ b/de/15.10/user/search-wildcard.rst @@ -0,0 +1,53 @@ +==================== +Wildcard-Suche +==================== + +Sie können Wildcards für ein oder mehrere Zeichen innerhalb von Suchbegriffen verwenden. ? kann als Wildcard für ein Zeichen angegeben werden, und \* kann als Wildcard für mehrere Zeichen angegeben werden. Wildcards können für Wörter verwendet werden. Wildcard-Suchen für Sätze sind nicht möglich. + +Verwendung +----------- + +Um ein Ein-Zeichen-Wildcard zu verwenden, nutzen Sie ? wie folgt: + +:: + + te?t + +In diesem Fall wird es als Ein-Zeichen-Wildcard behandelt, z. B. text oder test. + +Um ein Mehrzeichen-Wildcard zu verwenden, nutzen Sie \* wie folgt: + +:: + + test* + +In diesem Fall wird es als Mehrzeichen-Wildcard behandelt, z. B. test, tests oder tester. Außerdem + +:: + + te*t + +kann innerhalb des Suchbegriffs verwendet werden. Außerdem + +:: + + *test + +kann auch am Anfang des Suchbegriffs verwendet werden. + +Sie können die Wildcard-Suche auch auf ein bestimmtes Feld anwenden. Im folgenden Beispiel werden im Feld title Dokumente gesucht, die ein mit te beginnendes und mit t endendes Wort enthalten. + +:: + + title:te*t + +Wenn kein Feld angegeben wird, erfolgt die Suche in den Feldern title und content. + +Nutzungsbedingungen +--------------------- + +Beachten Sie bei der Verwendung der Wildcard-Suche die folgenden Punkte: + +* Wildcards werden auf im Index registrierte Zeichenketten (Token) angewendet. Da der Suchbegriff nicht erneut analysiert wird, funktionieren Wildcards für Japanisch nicht wie erwartet, wenn der Index beispielsweise mit bi-gram erstellt wurde, da Japanisch dabei als bedeutungslose Zeichenkette fester Länge behandelt wird. Wenn Sie Wildcards für Japanisch verwenden möchten, nutzen Sie bitte Felder, die morphologische Analyse verwenden. +* Muster, die am Anfang oder in der Mitte des Suchbegriffs eine Wildcard (``*``, ``?``) enthalten, unterscheiden zwischen Groß- und Kleinschreibung. Da im Index registrierte Wörter normalerweise in Kleinbuchstaben umgewandelt werden, verwenden Sie im Muster bitte Kleinbuchstaben. Beispielsweise stimmen ``Te*t``, ``Te?t`` und ``*Test`` nicht mit dem in Kleinbuchstaben registrierten ``test`` überein. Dagegen wird bei Mustern, die nur am Ende ein ``*`` haben (z. B. ``Test*``), der Suchbegriff als Präfixsuche in Kleinbuchstaben umgewandelt und analysiert; ``Test*`` stimmt daher auch mit ``test`` überein. +* Eine Suche mit einer Wildcard am Anfang (zum Beispiel ``*test``) durchsucht alle Wörter im Index und kann daher länger dauern. diff --git a/de/15.10/user/special-char.rst b/de/15.10/user/special-char.rst new file mode 100644 index 000000000..429164f90 --- /dev/null +++ b/de/15.10/user/special-char.rst @@ -0,0 +1,88 @@ +================ +Sonderzeichen +================ + +Die folgenden Zeichen haben in der Syntax der Suchanfrage eine besondere Bedeutung und werden daher in Suchbegriffen als Sonderzeichen behandelt. Um diese Zeichen als literale Suchzeichen zu verwenden, müssen Sie sie maskieren. + +:: + + + - && || ! ( ) { } [ ] ^ " ~ * ? : \ / + +Diese Zeichen werden verwendet, um Suchfunktionen wie erforderliche/ausgeschlossene Begriffe (``+`` ``-``), boolesche Operatoren (``&&`` ``||`` ``!``), Gruppierung (``( )``), Bereichssuche (``[ ]`` ``{ }``), Boost-Suche (``^``), Phrasensuche (``"``), unscharfe Suche und Näherungssuche (``~``), Platzhaltersuche (``*`` ``?``) und Feldsuche (``:``) aufzurufen. + +Wird beispielsweise ein in einer URL oder einem Dateipfad enthaltenes „/" oder „:" oder ein in Programmcode enthaltenes „+" oder „-" unmaskiert als Suchbegriff verwendet, kann dies zu einem unerwarteten Suchergebnis führen. + +Liste der Sonderzeichen und ihre Bedeutung +-------------------------------------------- + +.. list-table:: + :header-rows: 1 + + * - Sonderzeichen + - Bedeutung + - Verwandte Seite + * - ``+`` ``-`` + - Kennzeichnung von Pflicht- bzw. ausgeschlossenen Begriffen (AND-Suche / NOT-Suche) + - :doc:`search-and` / :doc:`search-not` + * - ``&&`` ``||`` + - AND-Suche / OR-Suche + - :doc:`search-and` / :doc:`search-or` + * - ``!`` + - NOT-Suche (Ausschlusssuche) + - :doc:`search-not` + * - ``( )`` + - Gruppierung von Suchbedingungen + - :doc:`advanced-search` + * - ``[ ]`` ``{ }`` + - Bereichssuche (``[ ]`` schließt die Grenzwerte ein, ``{ }`` schließt sie aus) + - :doc:`search-range` + * - ``^`` + - Boost-Suche (Gewichtung) + - :doc:`search-boost` + * - ``"`` + - Phrasensuche (behandelt den eingeschlossenen Text als zusammenhängendes Wort; kann auch anstelle einer Maskierung verwendet werden) + - :doc:`advanced-search` + * - ``~`` + - Unscharfe Suche (nach einem Wort) / Näherungssuche (nach einer Phrase) + - :doc:`search-fuzzy` / :doc:`search-proximity` + * - ``*`` ``?`` + - Wildcard-Suche + - :doc:`search-wildcard` + * - ``:`` + - Angabe des Suchfelds + - :doc:`search-field` + * - ``\`` + - Escape-Zeichen (Maskierungszeichen) + - (diese Seite) + * - ``/`` + - Schrägstrich (muss maskiert werden, wenn er z. B. in einer URL enthalten ist) + - :doc:`search-field` + +Verwendung +----------- + +Um ein Sonderzeichen als literales Suchzeichen zu behandeln, verwenden Sie eine der folgenden Methoden. + +* Setzen Sie ``\`` unmittelbar vor das zu maskierende Zeichen. Das darauffolgende einzelne Zeichen wird als normales Zeichen behandelt und nicht als Syntax der Suchanfrage interpretiert. +* Schließen Sie den Suchbegriff in ``"`` ein. Die eingeschlossene Zeichenfolge wird als Phrasensuche behandelt, und die darin enthaltenen Sonderzeichen werden nicht als Syntax der Suchanfrage interpretiert. Beachten Sie jedoch, dass dadurch Funktionen wie die Platzhaltersuche (``*`` ``?``) nicht verfügbar sind, da es sich um eine Phrasensuche handelt. + +:: + + aaa\/bbb + "aaa/bbb" + +Möchten Sie beispielsweise „C++" als Suchbegriff verwenden, maskieren Sie es wie folgt: + +:: + + C\+\+ + "C++" + +Siehe auch +----------- + +- :doc:`search-field` +- :doc:`search-wildcard` +- :doc:`search-fuzzy` +- :doc:`search-proximity` +- :doc:`advanced-search` diff --git a/en/15.10/admin/accesstoken-guide.rst b/en/15.10/admin/accesstoken-guide.rst new file mode 100644 index 000000000..53dcb5735 --- /dev/null +++ b/en/15.10/admin/accesstoken-guide.rst @@ -0,0 +1,79 @@ +============ +Access Token +============ + +Overview +======== + +The access token settings page manages access tokens. + +Management Operations +===================== + +Display Method +-------------- + +To open the access token configuration list page shown below, click [System > Access Token] in the left menu. + +|image0| + +Click the configuration name to edit it. + +Creating Configuration +---------------------- + +To open the access token configuration page, click the New button. + +|image1| + +Configuration Items +------------------- + +Name +:::: + +Specifies the name to describe this access token. + +Permission +:::::::::: + +Sets the permission for the access token. +Described in "{user\ |group|\ role}name" format. +For example, to allow users belonging to the developer group to view search results, set the permission to "{group}developer". + +.. warning:: + + An access token with the ``{role}admin-api`` permission (stored as ``Radmin-api``) can use every Admin API endpoint; see :doc:`../api/admin/api-admin-overview`. A user with the ``admin-accesstoken`` role can issue such a token, and a user with ``admin-accesstoken-view`` can display the token values, so treat both roles as equivalent to the administrator role and grant them only to trusted operators. + +Parameter Name +:::::::::::::: + +Specifies the request parameter name when specifying permission as a search query. + +.. warning:: + + The parameter name feature is designed for use in trusted internal environments only. + When this feature is enabled, additional permissions can be specified through URL parameters. + However, in externally accessible environments or when exposed as a public API, + malicious users may manipulate URL parameters to escalate to privileges they should not have. + + Please note the following: + + * Use this feature only when Fess is embedded within another application or service that fully controls inbound requests. + * Do not configure a parameter name when Fess is exposed to untrusted networks. + * Ensure that URL parameters cannot be manipulated by external users when using access tokens. + +Expiration Date +::::::::::::::: + +Specifies the expiration date for the access token. + +Deleting Configuration +---------------------- + +Click the configuration name on the list page, then click the Delete button to display a confirmation screen. +Click the Delete button to remove the configuration. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/accesstoken-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/accesstoken-2.png + diff --git a/en/15.10/admin/backup-guide.rst b/en/15.10/admin/backup-guide.rst new file mode 100644 index 000000000..e3904a569 --- /dev/null +++ b/en/15.10/admin/backup-guide.rst @@ -0,0 +1,115 @@ +====== +Backup +====== + +Overview +======== + +Backup page allows you to download and upload your configuration data for |Fess|. + +Management Operations +===================== + +Download Data +-------------- + +|Fess| manages configuration data as indices. +To download your configuration, click the index name. + +|image0| + +.. note:: + + Dictionary files (synonyms, stop words, and so on) are not part of the backup. + They are stored in the dictionary directory of the search engine (``FESS_DICTIONARY_PATH``), + so copy them separately if you need them. + +fess_config.bulk +:::::::::::::::: + +fess_config.bulk contains configuration information for Fess. + +fess_basic_config.bulk +:::::::::::::::::::::: + +fess_basic_config.bulk contains Fess configuration information excluding crawl information, failure URLs, job logs, the thumbnail queue, user tags, and similar data. + +fess_user.bulk +:::::::::::::: + +fess_user.bulk includes information about users, roles, and groups. + +system.properties +::::::::::::::::: + +system.properties contains general settings information. + +fess.json +::::::::: + +fess.json contains configuration information for the fess index. + +doc.json +:::::::: + +doc.json contains mapping information for the fess index. + +chat_log.ndjson +::::::::::::::: + +chat_log.ndjson includes AI chat usage log information. + +click_log.ndjson +:::::::::::::::: + +click_log.ndjson includes click log information. + +favorite_log.ndjson +::::::::::::::::::: + +favorite_log.ndjson contains favorite log information. + +search_log.ndjson +::::::::::::::::: + +search_log.ndjson includes search log information. + +user_info.ndjson +:::::::::::::::: + +user_info.ndjson contains information about search users. + +Upload +------ + +Configuration data can be imported by uploading a file. +The files that can be restored are as follows. + +- ``*.bulk`` +- ``system.properties`` +- ``fess.json`` and ``doc.json``: replace the index definition files that |Fess| uses. The settings and mapping of an existing index are not changed on the spot. +- ``gsa*.xml``: a Google Search Appliance configuration file. It is imported as web crawl configuration, file crawl configuration, and labels. + +``*.ndjson`` files (search logs and other logs) cannot be uploaded to restore them. + +A document in a \*.bulk file that has an ``updatedTime`` is written only when the stored document +does not exist, has no ``updatedTime``, or is older. A document that is not newer is skipped and +logged at INFO level in ``fess.log``, so a restore does not roll back changes made after the backup +was taken, and the scheduled jobs bundled with the installed version (``updatedTime`` 0) are kept +as they are. Documents without an ``updatedTime`` are always written. + +.. note:: + + The skip is logged at INFO level, so with the default log level (``warn``) nothing is written to ``fess.log``. To see these entries, set the log level to ``info`` before the restore. You can change it with "Log Level" under [System > General] in the administration screen (it returns to its configured value when |Fess| restarts), or, on Linux, with ``FESS_LOG_LEVEL=info``. See :doc:`../config/admin-logging` for details. + +.. note:: + + |Fess| 15.10 stores the ``password`` of web and file authentication encrypted with the application cipher key + (``app.cipher.key`` in ``fess_config.properties``), so ``fess_basic_config.bulk`` and ``fess_config.bulk`` contain + the encrypted values. When you restore a backup onto another installation, carry the same ``app.cipher.key`` + over. With a different key, crawls that use these credentials fail with an error. A backup made before 15.10 holds + them in plain text and keeps working. + + Other values in a ``*.bulk`` file are not encrypted, so keep these files as sensitive files. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/backup-1.png diff --git a/en/15.10/admin/badword-guide.rst b/en/15.10/admin/badword-guide.rst new file mode 100644 index 000000000..f4ac7f8ff --- /dev/null +++ b/en/15.10/admin/badword-guide.rst @@ -0,0 +1,66 @@ +======== +Bad Word +======== + +Overview +======== + +Bad Word Configuration page manages words to exclude them from suggest feature. + +Management Operations +===================== + +Display Configurations +---------------------- + +Select Suggest > Bad Word in the left menu to display a list page of Bad Word Configuration, as below. + +|image0| + +Click a configuration name if you want to edit it. + +Create Configuration +-------------------- + +Click Create New button to display a form page for Bad Word configuration. + +|image1| + +Configurations +-------------- + +Bad Word +:::::::: + +Word to exclude it from Suggest. + +Delete Configuration +-------------------- + +Click a configuration on a list page, and click Delete button to display a confirmation dialog. +Click Delete button to delete the configuration. + +Download +======== + +You can download a word list file as CSV file. + +|image2| + +Upload +====== + +You can upload CSV file containing a word list to exclude from Suggest. + +|image3| + +CSV File +-------- + +The content of downloaded/uploaded CSV file is 1 column, and contains only a word. + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/badword-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/badword-2.png +.. |image2| image:: ../../../resources/images/en/15.10/admin/badword-3.png +.. |image3| image:: ../../../resources/images/en/15.10/admin/badword-4.png diff --git a/en/15.10/admin/boostdoc-guide.rst b/en/15.10/admin/boostdoc-guide.rst new file mode 100644 index 000000000..487e049dd --- /dev/null +++ b/en/15.10/admin/boostdoc-guide.rst @@ -0,0 +1,82 @@ +============== +Document Boost +============== + +Overview +======== + +This page explains the configuration settings related to document boost. +By configuring document boost settings, you can position documents at the top of search results regardless of search terms. + +Management Operations +===================== + +Display Method +-------------- + +To open the document boost configuration list page shown below, click [Crawler > Document Boost] in the left menu. + +|image0| + +Click the configuration name to edit it. + +Creating Configuration +---------------------- + +To open the document boost configuration page, click the New button. + +|image1| + +Configuration Items +------------------- + +Condition +::::::::: + +Specifies the condition for documents to position at the top. +For example, to display URLs containing https://www.n2sm.net/ at the top, write url.matches("https://www.n2sm.net/.\*"). +Conditions are written in the syntax of the scripting engine specified in "Script Type" below. + +Boost Value Expression +:::::::::::::::::::::: + +Specifies the weighting value for documents. +Expressions are written in the syntax of the scripting engine specified in "Script Type" below. + +Script Type +::::::::::: + +Specifies the scripting engine used to evaluate the condition and boost value expression. +New configurations are prefilled with ``javascript``. Selecting ``groovy`` requires the +``fess-script-groovy`` plugin. If left blank, the expressions are evaluated as Groovy. + +.. warning:: + + Under JavaScript, write the condition and the boost value expression as bare expressions + with no trailing semicolon. Text that can only be parsed as a block of statements evaluates + to ``null`` unless it contains an explicit ``return``. See :ref:`javascript-statement-null` + (in :doc:`../config/scripting-javascript`). + +Sort Order +:::::::::: + +Configures the sort order for document boost. + +When Rules Are Applied +---------------------- + +Document boost rules are evaluated when a web crawl or a file crawl registers a document in the index. They are not applied to data store crawls. +Adding, changing or deleting a rule does not change the boost of documents that are already in the index. + +When "Check Last Modified" in [System > General] is enabled (the default), a document whose content has not changed is not registered in the index again by a recrawl, so its boost is not evaluated again. +To apply a new or changed rule to existing documents, delete those documents from the index (see :doc:`searchlist-guide`) and crawl again. +A document that is registered again, for example because its content has been updated, is evaluated at that time. +If "Check Last Modified" is disabled, every document is registered again on each crawl, so the rules are evaluated every time. + +Deleting Configuration +---------------------- + +Click the configuration name on the list page, then click the Delete button to display a confirmation screen. Click the Delete button to remove the configuration. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/boostdoc-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/boostdoc-2.png diff --git a/en/15.10/admin/crawlinginfo-guide.rst b/en/15.10/admin/crawlinginfo-guide.rst new file mode 100644 index 000000000..c07356765 --- /dev/null +++ b/en/15.10/admin/crawlinginfo-guide.rst @@ -0,0 +1,91 @@ +============= +Crawling Info +============= + +Overview +======== + +Crawling Info page manages execution logs for crawling information. + +Management Operations +===================== + +Display Crawling Info +--------------------- + +Select System Info > Crawling Info in the left menu to display a list page of Crawling Info, as below. + +|image0| + +Details +------- + +To display details for specific crawling session, click the row of crawling info data. + +|image1| + +Field List +---------- + +Session ID +:::::::::: + +The session ID during crawl execution. + +Crawler Start Time +:::::::::::::::::: + +The time when the entire crawl started. + +Crawl Start Time (Web/File) +:::::::::::::::::::::::::::: + +The time when web and file system crawling started. + +Crawl Start Time (Data Store) +:::::::::::::::::::::::::::::: + +The time when data store crawling started. + +Crawl End Time (Web/File) +:::::::::::::::::::::::::: + +The time when web and file system crawling ended. + +Crawl Execution Time (Data Store) +:::::::::::::::::::::::::::::::::: + +The execution time of data store crawling (in milliseconds). + +Indexing Execution Time (Data Store) +::::::::::::::::::::::::::::::::::::: + +The time taken to index the results of web and file system crawling (in milliseconds). + +Index Size (Data Store) +:::::::::::::::::::::::: + +The number of indexed documents. + +Crawl End Time (Data Store) +:::::::::::::::::::::::::::: + +The time when data store crawling ended. + +Crawler Status +:::::::::::::: + +Whether the crawl was successful or not. + +Crawler End Time +:::::::::::::::: + +The time when the entire crawl ended. + +Crawler Execution Time +:::::::::::::::::::::: + +The total execution time of the crawl (in milliseconds). + +.. |image0| image:: ../../../resources/images/en/15.10/admin/crawlinginfo-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/crawlinginfo-2.png diff --git a/en/15.10/admin/dashboard-guide.rst b/en/15.10/admin/dashboard-guide.rst new file mode 100644 index 000000000..873da8022 --- /dev/null +++ b/en/15.10/admin/dashboard-guide.rst @@ -0,0 +1,58 @@ +========= +Dashboard +========= + +Overview +======== + +The Dashboard provides a web-based management tool for administering the OpenSearch cluster and indices that |Fess| accesses. + +|image0| + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: Indices Managed by |Fess| + :header-rows: 1 + + * - Index Name + - Description + * - fess.yyyyMMddHHmmssSSS + - Indexed documents + * - fess_log + - Access logs + * - fess.suggest.yyyyMMddHHmmssSSS + - Suggest words + * - fess_config + - |Fess| configuration + * - fess_user + - User/role/group data + * - configsync + - Dictionary configuration + * - fess_suggest + - Suggest metadata + * - fess_suggest_array + - Suggest metadata + * - fess_suggest_badword + - Suggest bad word list + * - fess_suggest_analyzer + - Suggest metadata + * - fess_crawler + - Crawl information + +In ``fess.`` and ``fess.suggest.``, the part that follows is the date and time the index was created (17 digits, ``yyyyMMddHHmmssSSS``). + +Indices starting with a dot (.) are system indices and are not displayed by default. +To display system indices, enable the "Special" checkbox. + +Checking Indexed Document Count +================================ + +The number of indexed documents is displayed in the fess index as shown below. + +|image1| + +Clicking the icon in the upper right corner of each index displays the operation menu for that index. +To delete indexed documents, use the administrative search screen. Do not use "delete index" to remove documents. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/dashboard-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/dashboard-2.png +.. pdf :width: 400 px diff --git a/en/15.10/admin/dataconfig-guide.rst b/en/15.10/admin/dataconfig-guide.rst new file mode 100644 index 000000000..c6a91e3de --- /dev/null +++ b/en/15.10/admin/dataconfig-guide.rst @@ -0,0 +1,402 @@ +=================== +Data Store Crawling +=================== + +Overview +======== + +Data Store Crawling registers various data sources other than websites and files — such as relational databases (MySQL, PostgreSQL, Oracle) and CSV files — into the |Fess| index for full-text search. The supported data sources can be extended with data store connector plugins. + +|Fess| supports crawling data sources such as databases and CSV files. +This section describes the data store configuration required for this functionality. + +.. note:: + + ``DatabaseDataStore`` is provided by the database connector plugin (``fess-ds-db``), and ``CsvDataStore`` / ``CsvListDataStore`` are provided by the CSV connector plugin (``fess-ds-csv``). See :doc:`../config/datastore/ds-overview` for the list of available connectors. + +Configuration Management +======================== + +Display Method +-------------- + +To open the Data Store configuration list page shown below, click [Crawler > Data Store] in the left menu. + +|image0| + +Click the configuration name to edit it. + +Creating a Configuration +------------------------ + +Click the "Create New" button to open the Data Store configuration page. + +|image1| + +Configuration Options +--------------------- + +Name +:::: + +Specifies the name of the crawl configuration. + +Handler Name +:::::::::::: + +The handler name for processing the data store. + +* DatabaseDataStore: Crawls a database +* CsvDataStore: Crawls CSV/TSV files +* CsvListDataStore: Crawls a CSV file containing file paths to index + +The handler name drop-down lists only the handlers provided by the installed data store connector plugins (``fess-ds-*``). +If no plugin is installed, there is no handler to select. +For other handlers, see the connector pages listed in :doc:`../config/datastore/ds-overview`. +Note that ``EsDataStore`` (the ``fess-ds-elasticsearch`` plugin) described in the documentation of earlier versions has not been published since 15.6.0 and is not available in 15.10. + +Parameters +:::::::::: + +Specifies parameters related to the data store. + +The ``script_type`` parameter selects the scripting engine used to evaluate the +Script field below. New configurations are prefilled with ``script_type=javascript``. +If ``script_type`` is not specified, the script is evaluated as Groovy. + +Script +:::::: + +Specifies which fields to assign values retrieved from the data store. +Expressions are written in the syntax of the scripting engine selected by the +``script_type`` parameter above (JavaScript by default). + +.. warning:: + + Under JavaScript, write each line as a bare expression with no trailing semicolon. A line + that can only be parsed as a block of statements — anything with a trailing semicolon, or a + ``let`` / ``const`` declaration — evaluates to ``null`` unless it contains an explicit + ``return``, and a mapping that evaluates to ``null`` simply does not set that field. There + is no error and no log line; the only symptom is a field that quietly goes empty. See + :ref:`javascript-statement-null` (in :doc:`../config/scripting-javascript`). + +Boost Value +::::::::::: + +Specifies the boost value for documents crawled with this configuration. + +Permissions +::::::::::: + +Specifies permissions for this configuration. +The permission format is as follows: to display search results to users in the developer group, specify {group}developer. +User-level: {user}username, Role-level: {role}rolename, Group-level: {group}groupname. + +Virtual Host +:::::::::::: + +Specifies the virtual host hostname. +For details, see :doc:`Virtual Hosts in the Configuration Guide <../config/security-virtual-host>`. + +Status +:::::: + +Specifies whether to use this crawl configuration. + +Description +::::::::::: + +Enter a description. + +Deleting a Configuration +------------------------ + +Click the configuration name on the list page, then click the "Delete" button to display a confirmation screen. +Click the "Delete" button to remove the configuration. + +Examples +======== + +DatabaseDataStore +----------------- + +This section describes database crawling. + +As an example, assume the following table exists in a MySQL database named "testdb," and you can connect using username "hoge" and password "fuga". + +:: + + CREATE TABLE doc ( + id BIGINT NOT NULL AUTO_INCREMENT, + title VARCHAR(100) NOT NULL, + content VARCHAR(255) NOT NULL, + latitude VARCHAR(20), + longitude VARCHAR(20), + versionNo INTEGER NOT NULL, + PRIMARY KEY (id) + ); + +Here, populate the table with the following data: + +:: + + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 1', 'コンテンツ 1 です．', '37.77493', ' -122.419416', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 2', 'コンテンツ 2 です．', '34.701909', '135.494977', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 3', 'コンテンツ 3 です．', '-33.868901', '151.207091', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 4', 'コンテンツ 4 です．', '51.500152', '-0.113736', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 5', 'コンテンツ 5 です．', '35.681137', '139.766084', 1); + +Parameters +:::::::::: + +An example parameter configuration is as follows: + +:: + + driver=com.mysql.jdbc.Driver + url=jdbc:mysql://localhost:3306/testdb?useUnicode=true&characterEncoding=UTF-8 + username=hoge + password=fuga + sql=select * from doc + +Parameters are in "key=value" format. Key descriptions are as follows: + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - driver + - Driver class name + * - url + - URL + * - username + - Username for DB connection + * - password + - Password for DB connection + * - sql + - SQL statement to retrieve crawl targets + +Table: DB Configuration Parameters Example + + +Script +:::::: + +An example script configuration is as follows: +:: + + url="http://SERVERNAME/" + id + host="SERVERNAME" + site="SERVERNAME" + title=title + content=content + cache=content + digest=content + anchor= + content_length=content.length() + last_modified=new java.util.Date() + location=latitude + "," + longitude + latitude=latitude + longitude=longitude + +Parameters are in "key=value" format. Key descriptions are as follows: + +Values are written in the syntax of the scripting engine selected by ``script_type``. +Enclose strings in double quotation marks. Access database column names to retrieve their values. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - url + - URL (Set an accessible URL to the data for your environment) + * - host + - Hostname + * - site + - Site path + * - title + - Title + * - content + - Document content (indexed text) + * - cache + - Document cache (not indexed) + * - digest + - Digest portion displayed in search results + * - anchor + - Links contained in the document (normally not necessary) + * - content_length + - Document length + * - last_modified + - Last modified date of the document + +Table: Script Configuration + + +Driver +:::::: + +A driver is required to connect to the database. Place the jar file in app/WEB-INF/lib. + +CsvDataStore +------------ + +This section describes crawling CSV files. + +For example, create a test.csv file with the following content in the /home/taro/csv directory. +Set the file encoding to Shift_JIS. + +:: + + 1,Title 1,This is test 1. + 2,Title 2,This is test 2. + 3,Title 3,This is test 3. + 4,Title 4,This is test 4. + 5,Title 5,This is test 5. + 6,Title 6,This is test 6. + 7,Title 7,This is test 7. + 8,Title 8,This is test 8. + 9,Title 9,This is test 9. + +Parameters +:::::::::: + +Here's an example of parameter configuration: + +:: + + directories=/home/taro/csv + fileEncoding=Shift_JIS + +Parameters are in "key=value" format. Key descriptions are as follows: + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - directories + - Directory containing CSV files (.csv or .tsv) + * - files + - CSV files (for direct specification) + * - fileEncoding + - CSV file encoding + * - separatorCharacter + - Separator character + +Table: CSV File Configuration Parameters Example + + +Script +:::::: + +An example script configuration is as follows: + +:: + + url="http://SERVERNAME/" + cell1 + host="SERVERNAME" + site="SERVERNAME" + title=cell2 + content=cell3 + cache=cell3 + digest=cell3 + anchor= + content_length=cell3.length() + last_modified=new java.util.Date() + +Parameters are in "key=value" format. +Keys are the same as for database crawling. +CSV file data is stored in cell[number] format (numbers start from 1). +Cells with no data may be null. + +CsvListDataStore +---------------- + +Use this when crawling a large number of files. +By placing a CSV file containing the paths of updated files and crawling only the specified paths, you can shorten crawl execution time. + +The format for specifying paths is as follows: + +:: + + [Action][Path] + +Specify one of the following actions: + +* create: File was created +* modify: File was updated +* delete: File was deleted + +For example, create a test.csv file with the following content in the /home/taro/csv directory. +Set the file encoding to Shift_JIS. + +Paths are specified in the same format as when specifying file crawl paths. +Specify like "file:/[path]" or "smb://[path]". + +:: + + modify,smb://servername/data/testfile1.txt + modify,smb://servername/data/testfile2.txt + modify,smb://servername/data/testfile3.txt + modify,smb://servername/data/testfile4.txt + modify,smb://servername/data/testfile5.txt + modify,smb://servername/data/testfile6.txt + modify,smb://servername/data/testfile7.txt + modify,smb://servername/data/testfile8.txt + modify,smb://servername/data/testfile9.txt + modify,smb://servername/data/testfile10.txt + + +Parameters +:::::::::: + +An example parameter configuration is as follows: + +:: + + directories=/home/taro/csv + fileEncoding=Shift_JIS + +Parameters are in "key=value" format. Key descriptions are as follows: + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - directories + - Directory containing CSV files (.csv or .tsv) + * - fileEncoding + - CSV file encoding + * - separatorCharacter + - Separator character + +Table: CSV File Configuration Parameters Example + + +Script +:::::: + +An example script configuration is as follows: + +:: + + event_type=cell1 + url=cell2 + +Parameters are in "key=value" format. +Keys are the same as for database crawling. + +If authentication is required at the crawl destination, the following settings are also necessary: + +:: + + crawler.file.auth=example + crawler.file.auth.example.scheme=SAMBA + crawler.file.auth.example.username=username + crawler.file.auth.example.password=password + +Related Pages +============= + +- :doc:`../config/datastore/index` +- :doc:`../config/datastore/ds-database` +- :doc:`../config/datastore/ds-overview` +- :doc:`../config/crawler-basic` + +.. |image0| image:: ../../../resources/images/en/15.10/admin/dataconfig-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/dataconfig-2.png diff --git a/en/15.10/admin/dict-guide.rst b/en/15.10/admin/dict-guide.rst new file mode 100644 index 000000000..e450474aa --- /dev/null +++ b/en/15.10/admin/dict-guide.rst @@ -0,0 +1,164 @@ +========== +Dictionary +========== + +Overview +======== + +This page explains the configuration settings related to dictionaries. + +Make changes to dictionaries only after understanding the specifications of each dictionary. +Incorrect dictionary changes may make the index inaccessible. + +.. note:: + + Dictionary management is not available when ``search_engine.type`` is ``vanilla`` or ``aws``, that is, when OpenSearch has no CodeLibs plugins. See :doc:`../config/search-engine-type`. + +List +==== + +To open the manageable dictionary list page shown below, click [System > Dictionary] in the left menu. + +|image0| + +What Each Dictionary Affects, and When It Takes Effect +====================================================== + +Each dictionary applies to different fields and takes effect at a different +point. If you edited a dictionary and the search results did not change, check +this table first. + +.. list-table:: + :header-rows: 1 + :widths: 22 26 28 24 + + * - Dictionary + - File + - Fields it applies to + - When it takes effect + * - Kuromoji + - ``ja/kuromoji.txt`` + - ``_ja`` fields only, such as ``content_ja`` + - At index time (a recrawl is required) + * - Synonym + - ``synonym.txt`` + - ``content`` and ``title`` + - At search time (no recrawl needed) + * - Mapping (all languages) + - ``mapping.txt`` + - ``content`` and ``title`` + - At index time (a recrawl is required) + * - Mapping (per language) + - ``ja/mapping.txt`` + - ``_ja`` fields only, such as ``content_ja`` + - At index time (a recrawl is required) + * - Protwords + - ``en/protwords.txt`` + - ``content`` and ``title`` + - At index time and at search time + * - Stopwords + - ``en/stopwords.txt`` + - ``content`` and ``title`` + - At index time and at search time + * - Stemmer Override + - ``en/stemmer_override.txt`` + - ``content`` and ``title`` + - At index time and at search time + +.. note:: + + An analyzer is built when the index is opened, so updating a dictionary file + does not take effect **until the index is closed and opened again**. + A dictionary that applies at index time is not applied retroactively to + documents that are already indexed either, so those documents have to be + crawled again. + See :ref:`dict-apply-changes` for how to apply a change. + +.. warning:: + + The character mapping dictionary that applies to ``content``, the field most + searches are answered from, is the **root** ``mapping.txt``, not + ``ja/mapping.txt``. They share the name Mapping but they are different files. + +.. _dict-apply-changes: + +Applying Dictionary Changes +--------------------------- + +Saving a dictionary does not change search results, however long you wait. The configsync plugin +of OpenSearch writes the saved dictionaries to their files about once a minute, but an analyzer +reads its dictionaries only when the index is opened, so an index that is already open keeps +using the old ones. After editing dictionaries, reload the document index: + +1. Open [System Info > Maintenance] in the left menu. +2. Click [Reload] under Reload Document Index. + +The button writes the saved dictionaries to their files first, then closes and reopens the index +that the ``fess.update`` alias points to, so there is no need to wait for the periodic write. A +dictionary that applies at search time, such as a synonym, takes effect as soon as the index is +open again. For a dictionary that applies at index time, crawl the affected documents again as +well. + +.. warning:: + + While the index is closed, and until its shards are assigned again after it is opened, the + index cannot be searched: searches fail or return no results. The larger the index, the longer + this takes, so reload it at a quiet time. + +To do the same from a script without the admin screen, send the same operations to OpenSearch:: + + curl -X POST "localhost:9200/_configsync/flush" + curl -X POST "localhost:9200/fess.update/_close" + curl -X POST "localhost:9200/fess.update/_open" + +``_configsync/flush`` writes the saved dictionaries to their files immediately. Without it, wait +at least a minute after saving before closing the index. + +The Kuromoji User Dictionary and Search Results +----------------------------------------------- + +The ``content`` field is analyzed with the standard tokenizer and +``cjk_bigram``, so it is not affected by how Kuromoji segments a word. +Registering a Japanese compound word in the Kuromoji user dictionary and +crawling again therefore does not change what a search against ``content`` +returns. The registration shows up in ``content_ja``, which is added to the +query depending on the language of the request. + +Kuromoji +======== + +Manages the dictionary for Japanese morphological analysis. +ja/kuromoji.txt is the dictionary file for Japanese morphological analysis. + +Synonym +======= + +Manages the synonym dictionary. +synonym.txt is the synonym dictionary file used across all languages. + +Mapping +======= + +Manages the character replacement dictionary. +mapping.txt is the word replacement dictionary file used across all languages or for each language. + +Protwords +========= + +Manages the protected words dictionary. +protwords.txt is deployed for each language and contains a list of words to exclude from stemming. + +Stopwords +========= + +Manages the stopwords dictionary. +stopwords.txt is deployed for each language and contains a list of words to exclude during index creation. + +Stemmer Override +================ + +Manages the stemmer override dictionary. +stemmer_override.txt is deployed for each language and is a word replacement dictionary file for overriding stemming processing. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/dict-1.png + :height: 940px diff --git a/en/15.10/admin/docreport-guide.rst b/en/15.10/admin/docreport-guide.rst new file mode 100644 index 000000000..19f3dce97 --- /dev/null +++ b/en/15.10/admin/docreport-guide.rst @@ -0,0 +1,69 @@ +=============== +Document Report +=============== + +Overview +======== + +The Document Report page helps you clean up crawled file servers and the like. It lists documents +with the same content and documents that have not been modified for a long time, and each list can +be downloaded as CSV. + +To open the page, select [System Info > Document Report] in the left menu. Viewing requires the +``admin-docreport`` or ``admin-docreport-view`` role. The page only shows and downloads reports; it +does not change any document. + +Both tabs can be narrowed with "URL prefix", for example ``smb://server/share/``. + +Duplicates +========== + +Documents whose content is the same or nearly the same are grouped, largest group first. The groups +use the content signature computed at index time (``content_minhash_bits``, the same one that +collapses duplicate search results), so no reindex is needed. Documents whose content has no words +(such as empty files) are left out. + +The screen shows up to ``docreport.duplicate.group.size`` (default: 100) groups and up to +``docreport.duplicate.docs.size`` (default: 10) documents per group. Use [Download CSV] to get every +group. The CSV reads all groups, even on a large index, with the columns +``group, groupSize, url, title, filename, contentLength, lastModified, owner, lastModifier, clickCount, docId``. + +.. note:: + + The duplicate report needs the content signature, which the index definitions for an OpenSearch without the CodeLibs plugins (``search_engine.type`` of ``vanilla``, ``aws`` or the deprecated ``cloud``) do not compute. With these types the "Duplicates" tab is hidden and only the dormant documents report is available. See :doc:`../config/search-engine-type`. + +Dormant Documents +================= + +Documents whose last modification is older than the given number of days ("Not modified for +(days)", default 365 from ``docreport.dormant.days``) are listed, oldest first. Documents without a +last modification date are not listed. With "Never opened from search results", documents that have +been clicked from search results are left out. + +The screen shows the number of matching documents, their total size and a paged list. Paging stops +at ``indexer.max.result.window.size``; use [Download CSV] to get the documents beyond it. + +Settings +======== + +The following settings in ``fess_config.properties`` adjust the report. + +.. list-table:: + :header-rows: 1 + :widths: 40 45 15 + + * - Property + - Description + - Default + * - ``docreport.duplicate.group.size`` + - Maximum number of duplicate groups the screen shows + - ``100`` + * - ``docreport.duplicate.docs.size`` + - Maximum number of documents the screen lists for each group + - ``10`` + * - ``docreport.duplicate.export.page.size`` + - Number of content signatures read per request when downloading the CSV + - ``10000`` + * - ``docreport.dormant.days`` + - Default number of days since the last modification after which a document is dormant + - ``365`` diff --git a/en/15.10/admin/duplicatehost-guide.rst b/en/15.10/admin/duplicatehost-guide.rst new file mode 100644 index 000000000..299355386 --- /dev/null +++ b/en/15.10/admin/duplicatehost-guide.rst @@ -0,0 +1,56 @@ +============== +Duplicate Host +============== + +Overview +======== + +Here, we will explain the configuration for handling duplicate hosts. Duplicate hosts are used when you want to treat different hostnames as the same during crawling. For example, if you want to treat "www.example.com" and "example.com" as the same site, you can use this configuration. + +Management Operations +===================== + +Display Configurations +---------------------- + +To access the list page for configuring duplicate hosts shown below, click on "[Crawler > Duplicate Hosts]" in the left menu. + +|image0| + +To edit, click on the configuration name. + +Create Configuration +-------------------- + +To open the Duplicate Hosts settings page, click on the "Create New" button. + +|image1| + +Configurations +-------------- + +Regular Name +:::::::::::: + +Specify the canonical hostname. The duplicate hostnames will be replaced with the canonical hostname. + +Duplicate Name +:::::::::::::: + +Specify the duplicate hostname that you want to replace. + +.. note:: + + A URL whose hostname matches a duplicate name is replaced with the URL of the regular name before crawling. This applies to the URLs written in "URLs" (the start URLs) of the crawl configuration and to the URLs of links found during the crawl. + As a result, "Included URLs" and "Excluded URLs" of the crawl configuration are evaluated against the URL after the replacement. Write them with the hostname of the regular name. + + For example, if the regular name is ``example.com`` and the duplicate name is ``www.example.com``, writing only ``https://www.example.com/.*`` in "Included URLs" excludes the start URL after the replacement (``https://example.com/``). + In this case, no document is registered in the index, and neither an error nor a log message is output. + +Delete Configuration +-------------------- + +Click on the configuration name on the list page, and when the delete button is clicked, a confirmation screen will appear. Clicking the delete button will remove the configuration. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/duplicatehost-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/duplicatehost-2.png diff --git a/en/15.10/admin/elevateword-guide.rst b/en/15.10/admin/elevateword-guide.rst new file mode 100644 index 000000000..c7736a0ec --- /dev/null +++ b/en/15.10/admin/elevateword-guide.rst @@ -0,0 +1,92 @@ +=============== +Additional Word +=============== + +Overview +======== + +Additional Word page manages preferred words to display on a keyword suggest. +The keyword suggest words are generated from search queries and indexed contents automatically, and you can add words to them. + +Management Operations +===================== + +Display Configurations +---------------------- + +Select Suggest > Additional Word in the left menu to display a list page of Additional Word Configuration, as below. + +|image0| + +Click a configuration name if you want to edit it. + +Create Configuration +-------------------- + +Click Create New button to display a form page for Additional Word configuration. + +|image1| + +Configurations +-------------- + +Word +:::: + +Displayed suggest word. + +Reading +::::::: + +Reading for suggest word. + +Permissions +:::: + +Roles to restrict suggesting. +If roles are specified, suggest word is displayed in users which has roles. + +Label +::::: + +Labels to restrict suggesting. +If labels are specified, suggest word is displayed in users which has labels. + +Boost +::::: + +Boost value. +Higher value is displayed at the top. + +Delete Configuration +-------------------- + +Click a configuration on a list page, and click Delete button to display a confirmation dialog. +Click Delete button to delete the configuration. + +Download +======== + +You can download a word list file as CSV file. + +|image2| + + +Upload +====== + +You can upload CSV file containing a word list to exclude from Suggest. + +|image3| + +CSV File +--------------- + +The content of downloaded/uploaded CSV file is 5 column. + + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/elevateword-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/elevateword-2.png +.. |image2| image:: ../../../resources/images/en/15.10/admin/elevateword-3.png +.. |image3| image:: ../../../resources/images/en/15.10/admin/elevateword-4.png diff --git a/en/15.10/admin/esreq-guide.rst b/en/15.10/admin/esreq-guide.rst new file mode 100644 index 000000000..a73867756 --- /dev/null +++ b/en/15.10/admin/esreq-guide.rst @@ -0,0 +1,53 @@ +======================= +Request to OpenSearch +======================= + +Overview +======== + +This page sends a request written in a JSON file to OpenSearch. + +|image0| + +This page is not in a menu pane. +To display this page, log in as an administrator and type ``/admin/sereq/`` as the URL path. +The ``admin`` role (administrators) or the ``admin-sereq`` role is required to send a request. + +Operations +========== + +Send Request +------------ + +Create a JSON file that contains the request you want to send to OpenSearch, select it as "Request File" and click the "Send" button to send the request to OpenSearch. +The response is downloaded as a file. + +Configurations +-------------- + +Request File +:::::::::::: + +Specifies the file that contains the request. + +Write `` `` on the first line, separated by a single space, and the request body (such as a query DSL) on the following lines. +The method can be GET, POST, PUT or DELETE. The path is the path on OpenSearch, and the leading ``/`` can be omitted. +For example, the content of the file looks like this. + +:: + + POST /_search + { + "query": { + "match_all": {} + } + } + +Line breaks in the body are removed and the lines are joined before the request is sent. A request whose body has one JSON document per line, such as ``_bulk``, cannot be sent. + +.. warning:: + + A request whose method is PUT or DELETE is also sent to OpenSearch as it is. + Depending on the content of the file, this can change or delete the indices that |Fess| uses and lose data. Check the content carefully before sending. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/esreq-1.png diff --git a/en/15.10/admin/failureurl-guide.rst b/en/15.10/admin/failureurl-guide.rst new file mode 100644 index 000000000..da09adc71 --- /dev/null +++ b/en/15.10/admin/failureurl-guide.rst @@ -0,0 +1,66 @@ +=========== +Failure URL +=========== + +Overview +======== + +Failure URL page display URLs/paths which are not correctly crawled. + + +Management Operations +===================== + +Display Failure URL +------------------- + +Select System Info > Failure URL in the left menu to display a list page of failure URLs, as below. + +|image0| + +Clicking a failure URL link displays the details. + +Failure URL Details +=================== + +Failure URL details record exceptions that occurred during crawling. + +|image1| + +Details Content +--------------- + +URL +:::: + +The URL where the exception occurred. + +Thread Name +::::::::::: + +The thread name that was executing the crawl. +Can be used when checking log files. + +Type +:::: + +The type of exception. + +Log +:::: + +The content of the exception. + +Error Count +::::::::::: + +The number of times this exception occurred. + +Last Access Time +:::::::::::::::: + +The time when this exception occurred. + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/failureurl-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/failureurl-2.png diff --git a/en/15.10/admin/fileauth-guide.rst b/en/15.10/admin/fileauth-guide.rst new file mode 100644 index 000000000..bc3f8d583 --- /dev/null +++ b/en/15.10/admin/fileauth-guide.rst @@ -0,0 +1,85 @@ +=================== +File Authentication +=================== + +Overview +======== + +Here, we will explain the configuration for enabling file authentication when crawling files. |Fess| supports authentication for FTP and Windows shared folders. + +Management Operations +===================== + +Display Configurations +---------------------- + +To access the list page for configuring File Authentication shown below, click on "[Crawler > File Authentication]" in the left menu. + +|image0| + +To edit, click on the configuration name. + +Create Configuration +-------------------- + +To open the File Authentication settings page, click on the "Create New" button. + +|image1| + +Configurations +-------------- + +Hostname +:::::::: + +Specify the hostname of the site that requires authentication. +Use the same name as the hostname in the URL to be crawled. This authentication is not used for a URL written with a different name (for example, an IP address instead of an alias). + +Port +:::: + +Specify the port of the site that requires authentication. +If left blank, the list shows "Any". The meaning of a blank port depends on the scheme. + +* FTP: Used for URLs with any port (a URL without a port is treated as port 21). +* SAMBA: Used only for URLs that do not contain a port (``smb://server/share/``). It is not used for a URL that contains a port, such as ``smb://server:445/share/``. To crawl a URL that contains a port, specify the same port here. + +Scheme +:::::: + +Select the authentication method. +You can choose between FTP or SAMBA (Windows shared folder authentication). + +Username +:::::::: + +Specify the username to log in to the authentication site. + +Password +:::::::: + +Specify the password to log in to the authentication site. + +Parameters +:::::::::: + +If there are any additional settings required to log in to the authentication site, specify them here. +For SAMBA, you can set the value for the domain. +Use the following format to specify the parameters: + +:: + + domain=FUGA + +File System Config +:::::::::::::::::: + +Specify the crawl configuration that will use this authentication setting. + +Delete Configuration +-------------------- + +Click on the configuration name on the list page, and when the delete button is clicked, a confirmation screen will appear. Clicking the delete button will remove the configuration. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/fileauth-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/fileauth-2.png diff --git a/en/15.10/admin/fileconfig-guide.rst b/en/15.10/admin/fileconfig-guide.rst new file mode 100644 index 000000000..117cb75ad --- /dev/null +++ b/en/15.10/admin/fileconfig-guide.rst @@ -0,0 +1,261 @@ +================================== +File Crawling (File Server Search) +================================== + +Overview +======== + +File Crawling registers documents from internal file servers, Windows shared folders, and cloud storage into the |Fess| index, enabling full-text search (file server search). It supports a wide range of file formats, including Word, Excel, PowerPoint, and PDF. + +The File Crawling configuration page allows you to configure settings for crawling files in the file system or shared network folders. + +Crawl targets are determined by the protocol specified in the path: + +- ``file:/`` … local or mounted file system +- ``smb://`` … Windows file server / shared folder (SMB/CIFS) +- ``smb1://`` … Windows file server / shared folder over the legacy SMB1 protocol +- ``ftp://`` … FTP server +- ``s3://`` … Amazon S3 bucket (requires the ``fess-storage-s3`` plugin) +- ``gcs://`` … Google Cloud Storage bucket (requires the ``fess-storage-gcs`` plugin) + +Configuration Management +======================== + +Display Method +-------------- + +To open the File Crawling configuration list page, click [Crawler > File System] in the left menu. + +|image0| + +Click the configuration name to edit it. + +Creating a Configuration +------------------------ + +Click the "Create New" button to open the File Crawling configuration page. + +|image1| + +Configuration Options +--------------------- + +Name +:::: + +Configuration name. + +Path +:::: + +This path specifies where to start crawling (e.g., file:/, smb://, s3://, gcs://). + +Included Paths for Crawling +:::::::::::::::::::::::::::: + +Paths matching this regular expression (Java format) will be crawled by the |Fess| crawler. + +Excluded Paths for Crawling +:::::::::::::::::::::::::::: + +Paths matching this regular expression (Java format) will not be crawled by the |Fess| crawler. + +Included Paths for Indexing +:::::::::::::::::::::::::::: + +Paths matching this regular expression (Java format) will be included in the search index. + +Excluded Paths for Indexing +:::::::::::::::::::::::::::: + +Paths matching this regular expression (Java format) will be excluded from the search index. + +Configuration Parameters +:::::::::::::::::::::::: + +Specifies crawl configuration information. + +For crawls of paths that start with ``file:`` (the local or mounted file system), ``client.followSymlink`` specifies whether symbolic links are followed. The default is ``true`` (follow). When set to ``false``, symbolic links are skipped and the files they point to are not crawled through the link (each skipped link is logged at INFO level in ``fess-crawler.log``). Following a link registers the target file a second time under the permissions of the configuration that contains the link, so consider ``false`` when you crawl a share that more users can read than the tree its links point into. + +:: + + client.followSymlink=false + +Depth +::::: + +Specifies the depth of the file system structure to crawl. + +Max Access Count +:::::::::::::::: + +The number of paths to index. + +Number of Threads +::::::::::::::::: + +The number of threads to use for this configuration. + +Interval +:::::::: + +The time interval to wait when threads crawl each path. + +Boost Value +::::::::::: + +The boost value is the priority of documents indexed by this configuration. + +Permissions +::::::::::: + +Specifies permissions for this configuration. +The permission format is as follows: to display search results to users in the developer group, specify {group}developer. +User-level: {user}username, Role-level: {role}rolename, Group-level: {group}groupname. + +Virtual Host +:::::::::::: + +Specifies the virtual host hostname. +For details, see :doc:`Virtual Hosts in the Configuration Guide <../config/security-virtual-host>`. + +Status +:::::: + +If enabled, the default crawler's scheduled job will include this configuration. + +Description +::::::::::: + +Enter a description. + +Deleting a Configuration +------------------------ + +Click the configuration name on the list page, then click the "Delete" button to display a confirmation screen. Click the "Delete" button to remove the configuration. + +Examples +======== + +Crawling Local Files +-------------------- + +To crawl files under /home/share, the configuration values are as follows: + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - Configuration Item + - Value + * - Name + - Share Directory + * - Path + - file:/home/share + +Other parameters can use default settings. + +Crawling Windows Shared Folders +-------------------------------- + +To crawl files under \\SERVER\SharedFolder, the configuration values are as follows: + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - Configuration Item + - Value + * - Name + - Shared Folder + * - Path + - smb://SERVER/SharedFolder/ + +If a username and password are required to access the shared folder, you need to create file authentication settings by clicking [Crawler > File Authentication] in the left menu. The configuration values are as follows: + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - Configuration Item + - Value + * - Hostname + - SERVER + * - Scheme + - SAMBA + * - Username + - (Please enter) + * - Password + - (Please enter) + +Crawling Amazon S3 Buckets +-------------------------- + +To crawl files in the my-bucket bucket, the configuration values are as follows: + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - Configuration Item + - Value + * - Name + - S3 Bucket + * - Path + - s3://my-bucket/ + +S3 access requires authentication credentials. Add the following to "Configuration Parameters": + +:: + + client.endpoint=https://s3.ap-northeast-1.amazonaws.com + client.accessKey=YOUR_ACCESS_KEY + client.secretKey=YOUR_SECRET_KEY + client.region=ap-northeast-1 + +.. note:: + Amazon S3 and S3-compatible storage support comes from the ``fess-storage-s3`` plugin, which + is not part of the distribution. Install it from the System > Plugin page in the + administration screen, or with ``bin/fess-setup install plugin fess-storage-s3``. + +Crawling Google Cloud Storage Buckets +------------------------------------- + +To crawl files in the my-gcs-bucket bucket, the configuration values are as follows: + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - Configuration Item + - Value + * - Name + - GCS Bucket + * - Path + - gcs://my-gcs-bucket/ + +GCS access requires authentication credentials. Add the following to "Configuration Parameters": + +:: + + client.projectId=your-project-id + client.credentialsFile=/path/to/service-account.json + +.. note:: + Google Cloud Storage support comes from the ``fess-storage-gcs`` plugin, which is not part of + the distribution. Install it from the System > Plugin page in the administration screen, + or with ``bin/fess-setup install plugin fess-storage-gcs``. + +Related Pages +============= + +- :doc:`../config/crawler-basic` +- :doc:`fileauth-guide` +- :doc:`../config/datastore/ds-overview` +- :doc:`../config/search-basic` +- :doc:`../user/index` + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/fileconfig-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/fileconfig-2.png +.. pdf :height: 940 px diff --git a/en/15.10/admin/general-guide.rst b/en/15.10/admin/general-guide.rst new file mode 100644 index 000000000..3d5322f49 --- /dev/null +++ b/en/15.10/admin/general-guide.rst @@ -0,0 +1,683 @@ +================ +General Settings +================ + +Overview +======== + +This administration page allows you to manage |Fess| configuration settings. +You can modify various |Fess| settings without restarting |Fess|. + +Configuration Options +===================== + +System +------ + +|image0| + +JSON Response +::::::::::::: + +Specify whether to enable the JSON API. + +Login Required +:::::::::::::: + +Specify whether to require login for search functionality. + +Display Login Link +:::::::::::::::::: + +Configures whether to display a link to the login page on the search screen. + +Result Collapse +::::::::::::::: + +Specifies whether to enable collapsing of duplicate results. + +This item is not shown, and collapsing stays disabled, when ``search_engine.type`` is ``vanilla`` or ``aws`` (see :doc:`../config/search-engine-type`). + +Thumbnail View +:::::::::::::: + +Specify whether to enable thumbnail display. + +System Property +::::::::::::::: + +Configures the system properties of |Fess|. +Specify in ``key=value`` format, one per line. + +Default Label Value +::::::::::::::::::: + +Specifies the label value to add to the search conditions by default. +To specify per role or group, add "role:" or "group:" prefix, such as "role:admin=label1". + +Default Sort Value +:::::::::::::::::: + +Specifies the sort value to add to the search conditions by default. +To specify per role or group, add "role:" or "group:" prefix, such as "role:admin=content_length.desc". + +Virtual Host +:::::::::::: + +Configures virtual hosts. +For details, see :doc:`Virtual Hosts in the Configuration Guide <../config/security-virtual-host>`. + +Popular Word Response +::::::::::::::::::::: + +Specify whether to enable the popular word API. + +CSV File Encoding +::::::::::::::::: + +Specifies the encoding for downloadable CSV files. + +Append Search Parameters +:::::::::::::::::::::::: + +Enable when passing parameters to the search result display. + +Search File Proxy +::::::::::::::::: + +Specify whether to enable file proxy for search results. + +Use Browser Locale +:::::::::::::::::: + +Specify whether to use the browser locale for search. + +SSO Type +:::::::: + +Specifies the single sign-on type. + +- **None**: Do not use SSO +- **OpenID Connect**: Use OpenID Connect (requires the ``fess-sso-oidc`` plugin) +- **SAML**: Use SAML (requires the ``fess-sso-saml`` plugin) +- **SPNEGO**: Use SPNEGO (requires the ``fess-sso-spnego`` plugin) +- **Entra ID**: Use Microsoft Entra ID (requires the ``fess-sso-entraid`` plugin) + +Crawler +------- + +|image1| + +Check Last Modified +::::::::::::::::::: + +Enable to perform differential crawling. + +For HTTP/HTTPS URLs, when the ``Last-Modified`` of the HEAD response cannot decide (no last +modified date is indexed, the HEAD response has no ``Last-Modified``, or the HEAD returns a status +other than 200/404), the GET is sent as a conditional GET with ``If-None-Match`` (the indexed +``ETag``) and/or ``If-Modified-Since``. A page answered with ``304 Not Modified`` is handled like an +unchanged page and is not fetched again. To fetch everything again, for example after changing crawl +settings, turn this setting off for a crawl. + +Concurrent Crawler Config +::::::::::::::::::::::::: + +Specifies the number of crawl configurations to execute simultaneously. + +User Agent +:::::::::: + +Specifies the user agent name used by the crawler. + +Delete old documents +:::::::::::::::::::: + +Specifies the expiration period of documents in days. A document that is registered or updated by a crawl expires this many days after the crawl started, and a document that is found again by the next crawl has its expiration extended. The Doc Purger job of the scheduler (run every minute by default) deletes expired documents from the index. + +The default is ``3`` and the allowed values are ``-1`` to ``1000``. With ``-1``, no expiration is set on documents registered or updated by later crawls (an expiration that is already set is not extended). + +Ignore Failure Types +:::::::::::::::::::: + +Failure URLs that exceed the threshold are excluded from crawl targets, but exception names specified here will be crawl targets even if they exceed the failure URL threshold. + +Failure Count Threshold +::::::::::::::::::::::: + +If a crawl target document is recorded in failure URLs more times than specified here, it will be excluded from the next crawl. + +Logging +------- + +Search Log +:::::::::: + +Specifies whether to enable recording of search logs. + +User Log +:::::::: + +Specifies whether to enable recording of user logs. + +Favorite Log +:::::::::::: + +Specifies whether to enable recording of favorite logs. + +Delete old search logs +:::::::::::::::::::::: + +Deletes search logs older than the specified number of days. The default is ``-1``; with ``-1``, logs are never deleted and are kept indefinitely. +Click logs, favorite logs, and chat logs are deleted by the same number of days. + +Delete old job logs +::::::::::::::::::: + +Deletes job logs older than the specified number of days. The default is ``-1``; with ``-1``, they are not deleted. + +Delete old user logs +:::::::::::::::::::: + +Deletes user logs older than the specified number of days. The default is ``-1``; with ``-1``, they are not deleted. + +Bot names to delete logs +:::::::::::::::::::::::: + +Specifies bot names to exclude from search logs. + +Log Level +::::::::: + +Specify the log level for fess.log. + +Suggest +------- + +Suggest from Search Terms +::::::::::::::::::::::::: + +Specifies whether to generate suggest candidates from search logs. + +Suggest from Documents +:::::::::::::::::::::: + +Specifies whether to generate suggest candidates from indexed documents. + +Delete old suggest info +::::::::::::::::::::::: + +Deletes suggest data older than the specified number of days. + +LDAP +---- + +|image2| + +LDAP URL +:::::::: + +Specifies the URL of the LDAP server. + +Base DN +::::::: + +Specifies the base distinguished name for logging into the search screen. + +Bind DN +::::::: + +Specifies the Bind DN for administrators. + +Password +:::::::: + +Specifies the password for the Bind DN. + +User DN +::::::: + +Specifies the distinguished name for users. + +Account Filter +:::::::::::::: + +Specifies the user's Common Name, uid, etc. + +Group Filter +:::::::::::: + +Specifies the filter conditions for the groups to retrieve. + +memberOf Attribute +:::::::::::::::::: + +Specifies the memberOf attribute name available on the LDAP server. +For Active Directory, it is "memberOf". +For other LDAP servers, it may be "isMemberOf". + +Security Authentication +::::::::::::::::::::::: + +Specifies the LDAP security authentication method (e.g., simple). + +Initial Context Factory +::::::::::::::::::::::: + +Specifies the LDAP initial context factory class (e.g., com.sun.jndi.ldap.LdapCtxFactory). + +OpenID Connect +-------------- + +|image3| + +Client ID +::::::::: + +Specifies the client ID of the OpenID Connect provider. + +Client Secret +::::::::::::: + +Specifies the client secret of the OpenID Connect provider. + +Auth Server URL +::::::::::::::: + +Specifies the authorization server URL for OpenID Connect. + +Token Server URL +:::::::::::::::: + +Specifies the token server URL for OpenID Connect. + +Redirect URL +:::::::::::: + +Specifies the redirect URL for OpenID Connect. + +Scope +::::: + +Specifies the scope for OpenID Connect. + +Base URL +:::::::: + +Specifies the base URL for OpenID Connect. + +Default Groups +:::::::::::::: + +Specifies the default groups to assign to users during OpenID Connect authentication. + +Default Roles +::::::::::::: + +Specifies the default roles to assign to users during OpenID Connect authentication. + +SAML +---- + +|image4| + +IdP Entity ID +::::::::::::: + +Specifies the entity ID of the IdP (Identity Provider). + +IdP SSO URL +::::::::::: + +Specifies the Single Sign-On service URL of the IdP. + +IdP SLO URL +::::::::::: + +Specifies the Single Logout service URL of the IdP. + +IdP X.509 Certificate +::::::::::::::::::::: + +Specifies the X.509 public key certificate used for SAML assertion signature verification of the IdP. +Specify only the Base64-encoded content without ``-----BEGIN CERTIFICATE-----`` and ``-----END CERTIFICATE-----`` lines. + +SP Base URL +::::::::::: + +Specifies the base URL of the SAML Service Provider. + +SP Entity ID +:::::::::::: + +Specifies the entity ID of the SP (Service Provider). +Automatically configured when ``SP Base URL`` is set. + +SP ACS URL +:::::::::: + +Specifies the Assertion Consumer Service (ACS) URL that receives SAML assertions. +Automatically configured when ``SP Base URL`` is set. + +SP SLO URL +:::::::::: + +Specifies the Single Logout service URL of the SP. +Automatically configured when ``SP Base URL`` is set. + +SP NameID Format +:::::::::::::::: + +Specifies the NameID format used in SAML assertions. + +Group Attribute Name +:::::::::::::::::::: + +Specifies the attribute name to retrieve groups from the SAML response. + +Role Attribute Name +::::::::::::::::::: + +Specifies the attribute name to retrieve roles from the SAML response. + +Default Groups +:::::::::::::: + +Specifies the default groups to assign to users during SAML authentication. + +Default Roles +::::::::::::: + +Specifies the default roles to assign to users during SAML authentication. + +SPNEGO +------ + +|image5| + +.. note:: + SPNEGO settings are shared process-wide inside the underlying library, so a |Fess| restart is required to apply changes to them. + +Krb5 Config +::::::::::: + +Specifies the path to the Kerberos 5 configuration file. + +Login Config +:::::::::::: + +Specifies the path to the JAAS (Java Authentication and Authorization Service) login configuration file. + +Login Client Module +::::::::::::::::::: + +Specifies the JAAS client login module name. + +Login Server Module +::::::::::::::::::: + +Specifies the JAAS server login module name. + +Pre-Auth Username +::::::::::::::::: + +Specifies the username for SPNEGO pre-authentication. +Leaving the username and password empty enables keytab-based server login. + +Pre-Auth Password +::::::::::::::::: + +Specifies the password for SPNEGO pre-authentication. + +Allow Basic Auth +:::::::::::::::: + +Specify whether to allow Basic authentication fallback. + +Allow Unsecure Basic Auth +::::::::::::::::::::::::: + +Specify whether to allow Basic authentication over unsecure (HTTP) connections. +This is disabled by default to prevent credentials from being sent in clear text (Basic authentication is still offered over HTTPS connections). + +Prompt NTLM +:::::::::::: + +Specify whether to enable NTLM prompt. + +Allow Localhost +::::::::::::::: + +Specify whether to allow access from localhost. +This is disabled by default for security reasons, because when enabled, same-host requests are authenticated as the server OS user without Kerberos verification. + +Allow Delegation +:::::::::::::::: + +Specify whether to allow Kerberos delegation. + +Logger Level +:::::::::::: + +Specifies the log output level for SPNEGO authentication as a numeric value from 0 to 7. +If left empty or set to a non-numeric value, the log level is detected automatically. + +Entra ID +-------- + +|image6| + +Tenant (ID or Domain) +::::::::::::::::::::: + +Specifies the tenant ID or domain for Microsoft Entra ID. + +Authority +::::::::: + +Specifies the authority URL for Microsoft Entra ID. + +Client ID +::::::::: + +Specifies the application (client) ID for Microsoft Entra ID. + +Client Secret +::::::::::::: + +Specifies the client secret for Microsoft Entra ID. + +Reply URL +::::::::: + +Specifies the reply (redirect) URL for Microsoft Entra ID. + +State TTL +::::::::: + +Specifies the time-to-live (TTL) for the authentication state. + +Permission Fields +::::::::::::::::: + +Specifies the fields to retrieve permission information from Entra ID. + +Default Groups +:::::::::::::: + +Specifies the default groups to assign to users during Entra ID authentication. + +Default Roles +::::::::::::: + +Specifies the default roles to assign to users during Entra ID authentication. + +Use Domain Services +::::::::::::::::::: + +Specify whether to use Entra ID Domain Service. + +Notice +------ + +|image7| + +.. note:: + + The notices accept HTML. When a search theme displays a notice, only an allowlist of tags and attributes is kept: `` + + + +If your site already uses jQuery, you do not need to add the jQuery script element. + +The suggest feature uses the |Fess| suggest API (``/api/v2/suggest-words``). +Change ``url`` to match the URL of your |Fess| server. + +The main options that can be specified for ``suggestor`` are as follows. + +.. list-table:: Main suggestor options + :header-rows: 1 + :widths: 25 75 + + * - Option + - Description + * - ``ajaxinfo.url`` + - The suggest API URL. Specify ``/api/v2/suggest-words`` of your |Fess| server. + * - ``ajaxinfo.fn`` + - An array of field names to get suggestions from. You can use the default ``["_default", "content", "title"]`` as is. + * - ``ajaxinfo.num`` + - The maximum number of suggestion candidates to display. + * - ``ajaxinfo.lang`` + - The language used to narrow down suggestion candidates (optional). + * - ``minterm`` + - The minimum number of input characters before suggestions are requested. + * - ``adjustWidthVal`` + - The value (in pixels) added to the input field width to adjust the width of the suggestion box. + * - ``searchForm`` + - The search form element that is submitted when a candidate is selected. + * - ``boxCssInfo`` + - The CSS applied to the suggestion box. + * - ``listSelectedCssInfo`` + - The CSS applied to the selected candidate (optional). + * - ``listDeselectedCssInfo`` + - The CSS applied to non-selected candidates (optional). + +Specify a value for "z-index" that does not overlap with other elements. + +.. note:: + When the search form is placed on a page whose domain differs from the |Fess| server, the request to the suggest API becomes a cross-origin request. + |Fess| allows all origins by default (``api.cors.allow.origin=*``), so it works as is. + To restrict access, change ``api.cors.allow.origin`` in ``fess_config.properties``. + +.. note:: + ``/api/v2/suggest-words`` is the API provided by |Fess| itself. + The ``/api/v1/suggest-words`` endpoint used in earlier versions is no longer provided by |Fess| core, and the ``fess-webapp-v1-api`` plugin must be installed to use it. + For new setups, use ``/api/v2/suggest-words``. diff --git a/en/15.10/config/search-form.rst b/en/15.10/config/search-form.rst new file mode 100644 index 000000000..84f2a82e3 --- /dev/null +++ b/en/15.10/config/search-form.rst @@ -0,0 +1,64 @@ +======================== +Placement of Search Form +======================== + +How to Place the Search Form +============================ + +You can guide users to Fess search results by adding a search form to an existing website. +Here, we will explain with an example of setting up Fess on https://search.n2sm.co.jp/ and placing a search form on various pages of an existing site. + +Search Form +----------- + +Place the following code in the location where you want to have a search form within the page: + +:: + +
+ + +
+ +Please adjust it as needed using CSS to match the design of your site by adding class names through the class attribute. +Make sure to replace the URL of https://search.n2sm.co.jp/ with the URL of the Fess server you have set up for your use. + +Suggestion +---------- + +You can also set up a suggestion feature for the placed search form. If you wish to set it up, add the following code before : + +:: + + + + + +If you are already using jQuery on your site, there is no need to add the jQuery script element. + +Specify a value for "z-index" that does not overlap with other elements. + diff --git a/en/15.10/config/search-geosearch.rst b/en/15.10/config/search-geosearch.rst new file mode 100644 index 000000000..d48c4c1d9 --- /dev/null +++ b/en/15.10/config/search-geosearch.rst @@ -0,0 +1,352 @@ +================== +Geolocation Search +================== + +Overview +======== + +|Fess| can execute searches with geographical ranges specified for documents containing latitude and longitude location information. +Using this feature, you can search for documents within a certain distance from a specific point, +or build search systems integrated with map services like Google Maps. + +Internally, it uses OpenSearch's geo-distance query to filter documents that exist +within a specified distance from a given center point. + +Use Cases +========= + +Geolocation search can be utilized for purposes such as: + +- Store Search: Search for stores near the user's current location +- Real Estate Search: Search for properties within a certain distance from specific stations or facilities +- Event Search: Search for event information around specified locations +- Facility Search: Search for tourist spots or public facilities nearby + +Configuration +============= + +Index Generation Settings +-------------------------- + +Location Field Definition +~~~~~~~~~~~~~~~~~~~~~~~~~ + +In |Fess|, ``location`` is defined as a standard field for storing location information. +This field is configured as OpenSearch's ``geo_point`` type. + +Location Registration Format +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When generating indexes, set latitude and longitude separated by commas in the ``location`` field. + +**Format:** + +:: + + latitude,longitude + +**Example:** + +:: + + 45.17614,-93.87341 + +.. note:: + Specify latitude in the range -90 to 90, and longitude in the range -180 to 180. + +Data Store Crawl Configuration Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When using data store crawl, set latitude and longitude in the ``location`` field from data sources with location information. + +**Example: Retrieving from Database** + +If latitude and longitude are stored in separate columns, concatenate them into a comma-separated string in SQL. +Data store parameters take one item per line, so write the SQL on a single line following ``sql=`` +(if you break it across multiple lines, only the first line, ``SELECT``, is treated as the SQL and a syntax error occurs). + +:: + + sql=SELECT id, name, address, CONCAT(latitude, ',', longitude) AS location FROM stores + +Map the retrieved value to the ``location`` field in the data store configuration script. +In the database data store, the SQL column names (including aliases given with ``AS``) become the script variable names as they are. +No prefix such as ``data.`` is added. + +:: + + location=location + +Adding Location Information via Script +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can also dynamically add location information to documents using the script feature in crawl configuration (JavaScript by default; Groovy can also be selected). +Assign the value directly to the field name. + +:: + + // Set latitude and longitude in the location field + location="35.681236,139.767125" + +For details on scripting, refer to :doc:`scripting-overview`. + +Search Settings +--------------- + +To execute geolocation search, specify the search center point and range in request parameters. + +Request Parameters +~~~~~~~~~~~~~~~~~~ + +The parameter names for geolocation search follow the format ``geo..point`` and ``geo..distance``. +```` is the field name configured in ``query.geo.fields`` +(default is ``location``). + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Parameter Name + - Description + * - ``geo.location.point`` + - Latitude and longitude of the search center point (comma-separated. Example: ``35.681236,139.767125``) + * - ``geo.location.distance`` + - Search radius from center point (with unit. Example: ``10km``) + +.. note:: + ``point`` and ``distance`` must be specified together. A ``point`` without ``distance`` is ignored. + Also, the value of ``point`` must consist of exactly two numeric values (latitude,longitude); an error + will occur if the format is invalid. + +.. note:: + Geolocation search works as a filter on the search term ``q``. If ``q`` is empty, the search itself is not executed + and the result is 0 documents. Specify a search term in geolocation search requests. + +.. note:: + If multiple ``point`` values are specified for the same field, they are treated as OR conditions (within any of the ranges). + If specified for multiple fields, they are treated as AND conditions (within all of the ranges). + +Distance Units +~~~~~~~~~~~~~~ + +The following units can be used for distance: + +- ``km``: kilometers +- ``m``: meters +- ``mi``: miles +- ``yd``: yards + +.. note:: + Since the distance value is passed directly to OpenSearch, you can also use other units supported by OpenSearch + (such as ``cm``, ``mm``, ``ft``, ``in``, ``nmi``). + +Sort Order of Search Results +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Geolocation search operates as a **filter** that narrows results to documents within the specified range. +It does not affect the search score (relevance), and results are not sorted by distance from the center point. +Results are returned in the usual relevance order (or the order specified by the ``sort`` parameter). + +.. note:: + |Fess| does not support sorting by distance (nearest-first ordering). + If you want to display results in distance order, sort them on the client side using the latitude and longitude + included in the response. + +Search Examples +=============== + +Basic Search +------------ + +To search for documents within a 10km radius from Tokyo Station (35.681236, 139.767125): + +:: + + http://localhost:8080/search?q=keyword&geo.location.point=35.681236,139.767125&geo.location.distance=10km + +Nearby Search +------------- + +To search within 1km from the user's current location: + +:: + + http://localhost:8080/search?q=ramen&geo.location.point=35.681236,139.767125&geo.location.distance=1km + +API Usage +--------- + +Geolocation search can also be used with the v2 JSON search API (``/api/v2/search``). +Specify ``geo.location.point`` and ``geo.location.distance`` as request parameters. + +:: + + curl "http://localhost:8080/api/v2/search?q=hotel&geo.location.point=35.681236,139.767125&geo.location.distance=5km" + +Search results are returned in the ``response.data`` array of the common envelope. For details on the API, refer to +:doc:`../api/api-search` and :doc:`../api/api-overview`. + +.. note:: + The ``location`` field is not included in the API response by default. To include latitude and longitude in + the search results, add the following two settings to ``fess_config.properties`` and restart |Fess|. + ``query.additional.response.fields`` adds the field to be retrieved from the search engine, and + ``query.additional.api.response.fields`` allows the field to be output in the API response. + If only one of them is set, ``location`` is not included in the response. + + :: + + query.additional.response.fields=location + query.additional.api.response.fields=location + +Field Name Customization +======================== + +Changing the Default Field Name +-------------------------------- + +To change the field name used for geolocation search, +change the following setting in ``fess_config.properties``. + +:: + + query.geo.fields=location + +To specify multiple field names, separate them with commas. + +:: + + query.geo.fields=location,geo_point,coordinates + +.. note:: + - Request parameter names correspond to the configured field names. For example, + if you set ``query.geo.fields=coordinates``, specify ``geo.coordinates.point`` and + ``geo.coordinates.distance``. + - Each field specified here must be defined as the ``geo_point`` type in the index mapping. + +Implementation Examples +======================= + +Web Application Implementation +------------------------------- + +Example of retrieving current location and searching using JavaScript: + +.. code-block:: javascript + + // Get current location using browser's Geolocation API + navigator.geolocation.getCurrentPosition(function(position) { + const latitude = position.coords.latitude; + const longitude = position.coords.longitude; + const distance = "5km"; + + // Build search URL (the search term q cannot be omitted) + const searchUrl = `/search?q=${encodeURIComponent('store')}&geo.location.point=${latitude},${longitude}&geo.location.distance=${distance}`; + + // Execute search + window.location.href = searchUrl; + }); + +Google Maps Integration +------------------------ + +Example of displaying search results as markers on Google Maps: + +.. note:: + This example references the ``location`` field from search results. You must configure + ``query.additional.response.fields=location`` and ``query.additional.api.response.fields=location`` in advance + so that latitude and longitude are included in the response. + +.. code-block:: javascript + + // Initialize map + const map = new google.maps.Map(document.getElementById('map'), { + center: {lat: 35.681236, lng: 139.767125}, + zoom: 13 + }); + + // Execute geolocation search using the Fess v2 search API + fetch('/api/v2/search?q=store&geo.location.point=35.681236,139.767125&geo.location.distance=5km') + .then(response => response.json()) + .then(json => { + // Display search results (response.data array) as markers + json.response.data.forEach(doc => { + if (doc.location) { + const [lat, lng] = doc.location.split(',').map(Number); + new google.maps.Marker({ + position: {lat: lat, lng: lng}, + map: map, + title: doc.title + }); + } + }); + }); + +Performance Optimization +======================== + +Verifying Index Configuration +------------------------------ + +The location field is defined as the ``geo_point`` type in +``app/WEB-INF/classes/fess_indices/fess/doc.json`` at the installation location. + +:: + + "location": { + "type": "geo_point" + } + +Fields of type ``geo_point`` are indexed using a BKD tree, so geo-distance queries +are executed efficiently. + +Optimizing Search Range and Response +------------------------------------- + +Increasing the search radius increases the number of matching documents within the range, +which may cause longer retrieval and rendering times. + +- Set an appropriate search radius according to your use case. +- When handling a large number of results (such as for map display), adjust the page size + (``num`` parameter) to limit the number of results retrieved. + +Troubleshooting +=============== + +Geolocation Search Not Working +------------------------------- + +1. Verify that data is correctly stored in the ``location`` field. +2. Verify that the latitude and longitude format is correct (comma-separated as ``latitude,longitude``; an error will occur if there are not exactly two values). +3. Verify that ``location`` is defined as ``geo_point`` type in OpenSearch index mapping. +4. Verify that both ``point`` and ``distance`` are specified (a ``point`` without ``distance`` is ignored). + +No Search Results Returned +--------------------------- + +1. Verify that documents exist within the specified distance range. +2. Verify that latitude and longitude values are within the correct range (latitude: -90 to 90, longitude: -180 to 180). +3. Verify that distance units are specified correctly. + +Location Information Not Included in API Response +-------------------------------------------------- + +The ``location`` field is not included in the API response by default. +To include latitude and longitude in search results, set both +``query.additional.response.fields=location`` and ``query.additional.api.response.fields=location`` +in ``fess_config.properties`` and restart |Fess|. + +Location Information Not Registered Correctly +---------------------------------------------- + +1. Verify that the ``location`` field is set correctly during crawling. +2. Verify that the latitude and longitude from the data source are being retrieved correctly. +3. When setting location information via script, verify that it is in the string format ``latitude,longitude``. + +References +========== + +For details on geolocation search, refer to the following resources: + +- `OpenSearch Geo Queries `_ +- `OpenSearch Geo Point `_ +- `Geolocation API (MDN) `_ diff --git a/en/15.10/config/search-scroll.rst b/en/15.10/config/search-scroll.rst new file mode 100644 index 000000000..2f32579f5 --- /dev/null +++ b/en/15.10/config/search-scroll.rst @@ -0,0 +1,455 @@ +================================ +Bulk Retrieval of Search Results +================================ + +Overview +======== + +In |Fess| normal search, only a certain number of search results are displayed via paging functionality. +To retrieve all search results in bulk, use the Scroll Search feature. + +This feature is useful when you need to process all search results, +such as bulk data export or backup, and large-scale data analysis. + +Use Cases +========= + +Scroll search is suitable for purposes such as: + +- Exporting all search results +- Retrieving large amounts of data for data analysis +- Data retrieval in batch processing +- Data synchronization to external systems +- Data collection for report generation + +.. warning:: + Scroll search returns large amounts of data and consumes more server resources + compared to normal search. Enable only when necessary. + +Configuration +============= + +Enabling Scroll Search +---------------------- + +By default, scroll search is disabled from security and performance perspectives. +To enable it, change the following setting in ``app/WEB-INF/classes/fess_config.properties`` (or +``/etc/fess/fess_config.properties`` for RPM/DEB packages). + +:: + + api.search.scroll=true + +.. note:: + After changing settings, you must restart |Fess|. + +Scroll Context Lifetime +----------------------- + +The scroll context lifetime for scroll search is fixed internally in |Fess| at ``1m`` (1 minute). +This value cannot be changed from ``fess_config.properties``. + +.. note:: + There is a setting called ``index.scroll.search.timeout``, but it is used for internal operations + involving index updates or deletions (update by query / delete by query) and does not affect + the timeout for this feature (search scrolling). + +Response Field Configuration +----------------------------- + +You can customize the fields included in search result responses. +By default, many fields are returned, but you can also specify additional fields. + +:: + + query.additional.scroll.response.fields=content + query.additional.api.response.fields=content + +When specifying multiple fields, list them separated by commas. + +.. note:: + The ``content`` field is not included in the default response. To retrieve full text, you + need both settings above. ``query.additional.scroll.response.fields`` adds the field to what is fetched + from the index, and ``query.additional.api.response.fields`` adds it to the fields the API is allowed to + return. With only one of them, ``content`` is not output. + +Usage +===== + +Basic Usage +----------- + +Access scroll search using the following URL: + +:: + + http://localhost:8080/api/v2/documents/all?q=search keyword + +Search results are returned in NDJSON (Newline Delimited JSON) format. +Each line outputs one document in JSON format. + +**Example:** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=Fess" + +Request Parameters +------------------ + +The following parameters can be used with scroll search: + +.. note:: + Scroll search only supports the GET method. For a state-changing method such as ``POST``, + the CSRF token is checked first, so a request without a valid ``X-Fess-CSRF-Token`` header + gets ``403 Forbidden`` (``forbidden``); see :doc:`../api/api-overview`. + With a valid token, it gets ``405 Method Not Allowed`` (``method_not_allowed``). + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Parameter Name + - Description + * - ``q`` + - Search query (required) + * - ``num`` + - Number of items to retrieve per scroll (default: 10, max: 100) + * - ``fields.label`` + - Filtering by label + +.. note:: + The maximum value of ``num`` is controlled by ``paging.search.page.max.size`` (default: 100). + Values exceeding the maximum are automatically capped. + The default value uses ``paging.search.page.size`` (default: 10). + If a value of 0 or less is specified for ``num``, an error (``INVALID_REQUEST``) is returned. + +Specifying Search Queries +-------------------------- + +You can specify search queries just like normal searches. + +**Example: Keyword search** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=search engine" + +**Example: Field-specific search** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=title:Fess" + +**Example: Retrieve all (no search conditions)** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=*:*" + +Specifying Retrieval Count +--------------------------- + +You can change the number of items retrieved per scroll. + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=Fess&num=100" + +.. note:: + Increasing the ``num`` parameter too much will increase memory usage. + The default maximum is 100. If a larger value is needed, change the + ``paging.search.page.max.size`` setting. + +Filtering by Label +------------------ + +You can retrieve only documents belonging to a specific label. + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=*:*&fields.label=public" + +About Access Control +-------------------- + +.. note:: + Scroll search applies role-based access control (RBAC) just like normal search. + Only documents accessible based on the role information in the request are returned; + documents for which the user does not have view permissions are not included in the results. + +.. warning:: + The scroll search endpoint does not require authentication by default (anyone can access it). + However, the documents returned are filtered by the role-based access control described above. + If you wish to restrict access to the endpoint itself, configure IP address restrictions or + authentication via a reverse proxy or similar mechanism. + +Response Format +=============== + +NDJSON Format +------------- + +Scroll search responses are returned in NDJSON (Newline Delimited JSON) format. +The Content-Type is ``application/x-ndjson; charset=UTF-8``. +Each line represents one document wrapped in the ``{"data": {...}}`` format. + +**Example:** + +:: + + {"data":{"url":"http://example.com/page1","title":"Page 1","digest":"..."}} + {"data":{"url":"http://example.com/page2","title":"Page 2","digest":"..."}} + {"data":{"url":"http://example.com/page3","title":"Page 3","digest":"..."}} + +.. note:: + Each document is stored under the ``data`` key. On the client side, parse each line and + then refer to the value of the ``data`` key. + +Error Behavior +-------------- + +If an error occurs on the server side after the stream has started being sent, the following +error terminator line is output as the final line of the response. + +:: + + {"error":{"code":"internal_error","message":"stream error"}} + +.. note:: + On the client side, you can determine whether the stream completed successfully or whether + a server-side error occurred mid-stream by checking whether the final line contains the + ``error`` key. Note that if writing the error terminator line itself fails, the terminator + line will not be output and the stream will end mid-way; treat unexpected disconnections + as errors as well. + +Response Fields +--------------- + +Fields included by default: + +- ``score``: Search score +- ``_id``: Document ID (OpenSearch document ID) +- ``doc_id``: Document ID (internal to |Fess|) +- ``boost``: Boost value +- ``content_length``: Content length +- ``host``: Hostname +- ``site``: Site +- ``last_modified``: Last modified date/time +- ``timestamp``: Timestamp +- ``mimetype``: MIME type +- ``filetype``: File type +- ``filename``: Filename +- ``created``: Creation date/time +- ``title``: Title +- ``digest``: Body excerpt +- ``url``: Document URL +- ``thumbnail``: Thumbnail +- ``click_count``: Click count +- ``favorite_count``: Favorite count +- ``has_cache``: Cache availability +- ``content_title``: Display title +- ``content_description``: Display body excerpt +- ``url_link``: Display link URL +- ``site_path``: Site path + +.. note:: + The fields actually output are limited to those permitted as API response fields. + Fields with no value are not output. + +.. note:: + ``content`` (full text) is not included by default. + It is output when added to both ``query.additional.scroll.response.fields`` and + ``query.additional.api.response.fields`` (see Response Field Configuration). + +Data Processing Examples +======================== + +Python Processing Example +-------------------------- + +.. code-block:: python + + import requests + import json + + # Execute scroll search + url = "http://localhost:8080/api/v2/documents/all" + params = { + "q": "Fess", + "num": 100 + } + + response = requests.get(url, params=params, stream=True) + + # Process NDJSON response line by line + for line in response.iter_lines(): + if line: + record = json.loads(line) + if "error" in record: + # An error occurred mid-stream + print("stream error:", record["error"]) + break + doc = record["data"] + print(f"Title: {doc.get('title')}") + print(f"URL: {doc.get('url')}") + print("---") + +Saving to File +-------------- + +Example of saving search results to a file: + +.. code-block:: bash + + curl "http://localhost:8080/api/v2/documents/all?q=*:*" > all_documents.ndjson + +Converting to CSV +----------------- + +Example of converting to CSV using the jq command: + +.. code-block:: bash + + curl "http://localhost:8080/api/v2/documents/all?q=Fess" | \ + jq -r '.data | [.url, .title, .score] | @csv' > results.csv + +Data Analysis +------------- + +Example of analyzing retrieved data: + +.. code-block:: python + + import json + import pandas as pd + + # Read NDJSON file (extract the data key from each line) + documents = [] + with open('all_documents.ndjson', 'r') as f: + for line in f: + record = json.loads(line) + if "data" in record: + documents.append(record["data"]) + + # Convert to DataFrame + df = pd.DataFrame(documents) + + # Basic statistics + print(f"Total documents: {len(df)}") + print(f"Average score: {df['score'].mean()}") + + # URL domain analysis + df['domain'] = df['url'].apply(lambda x: x.split('/')[2]) + print(df['domain'].value_counts()) + +Performance and Best Practices +================================ + +Efficient Usage +--------------- + +1. **Set an appropriate num parameter** + + - Too small increases communication overhead + - Too large increases memory usage + - Default maximum: 100 + +2. **Optimize search conditions** + + - Specify search conditions to retrieve only necessary documents + - Execute full retrieval only when truly necessary + +3. **Use off-peak hours** + + - Retrieve large amounts of data during periods of low system load + +4. **Use in batch processing** + + - Execute periodic data synchronization as batch jobs + +Optimizing Memory Usage +------------------------ + +When processing large amounts of data, use streaming processing to reduce memory usage. + +.. code-block:: python + + import requests + import json + + url = "http://localhost:8080/api/v2/documents/all" + params = {"q": "*:*", "num": 100} + + # Process with streaming + with requests.get(url, params=params, stream=True) as response: + for line in response.iter_lines(decode_unicode=True): + if line: + record = json.loads(line) + if "error" in record: + break + # Process document + process_document(record["data"]) + +Security Considerations +======================= + +Access Restrictions +------------------- + +Since scroll search returns large amounts of data, configure appropriate access restrictions. +The endpoint does not require authentication by default, so consider the following measures as needed. + +1. **IP Address Restriction** + + Allow access only from specific IP addresses + +2. **API Authentication** + + Use API tokens or Basic authentication via a reverse proxy or similar mechanism + +3. **Role-Based Access Control** + + Documents returned are filtered by |Fess| role-based access control + +Rate Limiting +------------- + +To prevent excessive access, it is recommended to configure rate limiting with a reverse proxy. + +Troubleshooting +=============== + +Cannot Use Scroll Search +------------------------ + +1. Verify that ``api.search.scroll`` is set to ``true``. +2. Verify that |Fess| was restarted. +3. Check error logs. + +Timeout Errors Occur +-------------------- + +1. Reduce the ``num`` parameter to distribute processing. +2. Narrow search conditions to reduce the amount of retrieved data. + +Out of Memory Errors +-------------------- + +1. Reduce the ``num`` parameter. +2. Increase the |Fess| heap memory size. +3. Check the OpenSearch heap memory size. + +Response is Empty +----------------- + +1. Verify that the search query is correct. +2. Verify that specified labels or filter conditions are correct. +3. Role-based access control means documents for which the user does not have view permissions are not included in the results. Verify the role settings on the request. + +References +========== + +- :doc:`search-basic` - Search features details +- :doc:`search-advanced` - Search-related settings +- `OpenSearch Scroll API `_ diff --git a/en/15.10/config/search-semantic.rst b/en/15.10/config/search-semantic.rst new file mode 100644 index 000000000..edcd88b80 --- /dev/null +++ b/en/15.10/config/search-semantic.rst @@ -0,0 +1,919 @@ +===================================================== +Semantic Search (Content Chunking + Vector Search) +===================================================== + +Overview +======== + +In |Fess| 15.10, the **content chunking feature** — which splits document bodies into chunks and +generates and stores an embedding vector for each chunk — has been integrated into the core. +The generated vectors are used for two purposes: + +- **Semantic search**: a hybrid search that combines keyword (BM25) search and vector search via + Rank Fusion. Documents that are semantically close to the query can match even without exact + keyword overlap. +- **AI search mode (RAG)**: when generating an answer, only the chunks that are semantically + closest to the question are selected as the LLM's context, improving answer quality and token + efficiency. + +All of this is disabled by default. Unless you enable it, |Fess| continues to operate exactly as +before, using keyword search only. If you are upgrading |Fess| from 15.7 or earlier, or if you +were using the ``fess-webapp-semantic-search`` plugin, see :ref:`semantic-search-migration`. + +Processing Flow +---------------- + +1. The crawler indexes documents as usual (no chunks exist at this point). +2. The scheduler job **Content Chunk Vector Indexer** finds unprocessed documents, splits their + bodies (the ``content`` field) into chunks, generates embedding vectors, and stores them in the + ``content_chunk_vector`` field. At this point the ``content`` field itself is also rewritten + into an array of those chunks (``content_length`` keeps its original value). +3. The outcome of that processing is recorded in the ``content_chunk_status`` field (described + below). +4. When ``content_chunker.search.enabled=true``, the semantic searcher participates in Rank + Fusion at search time. + +Prerequisites +============= + +- **OpenSearch with the k-NN plugin**: In |Fess| 15.10, the mapping for the search index + (``fess.search``) always includes the ``content_chunk_vector`` field (a ``nested`` field whose + ``vector`` sub-field is the ``knn_vector`` type used for ANN), and the index settings always + include ``index.knn: true``, regardless of whether the content chunking feature is enabled. As a + result, if OpenSearch does not have the k-NN plugin installed, creating a new index fails + outright and |Fess| cannot start. + + .. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Configuration + - k-NN Plugin Support + * - Docker (``ghcr.io/codelibs/fess-opensearch``), the RPM/DEB packages (which always connect + to a separately installed external OpenSearch), or another external OpenSearch (standard + distribution) + - Fully supported, including ``faiss``. + * - The **minimal distribution** of an external OpenSearch + - **Not supported.** It does not include the k-NN plugin, so creating a new index fails. + + ``nmslib`` is never an accepted value for ``content_chunker.search.knn.engine``, on any of the + configurations above: ``content_chunk_vector`` is a ``nested`` field, and the k-NN plugin only + supports nested fields for the ``lucene``/``faiss`` engines (``nmslib`` is also deprecated and + restricted starting with OpenSearch 3.0). Setting it falls back to ``lucene`` with a warning; see + Configuration Reference below for the other ANN settings' accepted values. + +- **OpenSearch version for an external cluster**: the shipped ``fess.search`` index settings always + send ``index.knn`` and ``knn.derived_source.enabled`` (in ``fess_indices/fess.json`` and in + ``fess_indices/_vanilla/fess.json``, which ``vanilla``, ``aws`` and the deprecated ``cloud`` use). The latter is a relatively recent k-NN plugin setting, and an older + OpenSearch that does not recognize it fails to create the index regardless of whether the k-NN + plugin itself is installed. See :doc:`../install/prerequisites` for the OpenSearch versions + |Fess| 15.10 supports. + +- **Embedding provider**: use one of the following. + +.. list-table:: + :header-rows: 1 + :widths: 20 25 55 + + * - Configuration Value + - Provided By + - Description + * - ``opensearch`` + - |Fess| core (built in) + - Uses an embedding model deployed to OpenSearch ML Commons. No additional plugin required. + Default setting. + * - ``ollama`` + - ``fess-llm-ollama`` plugin + - Uses an Ollama embedding model (e.g. ``nomic-embed-text``). + * - ``openai`` + - ``fess-llm-openai`` plugin + - Uses the OpenAI embeddings API. + * - ``gemini`` + - ``fess-llm-gemini`` plugin + - Uses the Google Gemini embeddings API. + * - ``bedrock`` + - ``fess-llm-bedrock`` plugin + - Uses Amazon Titan Text Embeddings V2 or Cohere Embed through Amazon Bedrock. + * - ``none`` + - |Fess| core (built in) + - Splits documents into chunks only; no vectors are generated (chunk-only mode). + +Configuration Reference +======================== + +All ``content_chunker.*`` settings live in a single channel: **system properties** +(``system.properties``). Set them in ``app/WEB-INF/conf/system.properties`` +(``/etc/fess/system.properties`` on the RPM/DEB packages, ``/opt/fess/system.properties`` on +Docker), or supply an initial value with the ``-Dfess.system.`` startup option. Values are +reloaded at runtime, so most settings take effect immediately after you change them. The one +exception is enabling +``content_chunker.search.enabled`` (``false`` → ``true``): because the semantic searcher is only +registered at startup, **this change requires a restart to take effect**. + +.. note:: + + The ``content_chunker.*`` keys are only read from the ``system.properties`` channel. Writing + them in ``fess_config.properties`` or passing them as ``-Dfess.config.`` has no effect, so + always set them in ``system.properties``. Note also that the admin **System Info > Config + Info** screen is a **read-only** view of the current values — you cannot set + ``content_chunker.*`` from it. + +system.properties Settings +---------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 40 15 45 + + * - Property + - Default + - Description + * - ``content_chunker.enabled`` + - ``false`` + - Master switch for the entire content chunking feature + * - ``content_chunker.chunker.name`` + - ``length`` + - Chunking method + * - ``content_chunker.length.chunk_size`` + - ``800`` + - Target number of characters per chunk. With boundary-aware splitting enabled (the + default) this is a target rather than a hard limit: a chunk may be up to + ``boundary.lookback_percent`` of it shorter, and up to ``max(lookahead, 32)`` characters + longer -- 640 to 840 characters at the defaults. Leave that margin against the embedding + model's token limit + * - ``content_chunker.length.overlap`` + - ``0`` + - Number of characters to overlap between chunks. The restart point is snapped to a + boundary as well, and snapping can only move it earlier, so the effective overlap is + between this value and twice this value + * - ``content_chunker.length.boundary.enabled`` + - ``true`` + - Move each cut to a sensible text boundary instead of cutting at exactly + ``chunk_size`` characters. Candidates are tiered and the nearest candidate of the highest + tier present wins: a line break or sentence end, otherwise a clause separator or space, + otherwise a writing-system change. Set to ``false`` for the previous fixed-length + behaviour + * - ``content_chunker.length.boundary.lookback_percent`` + - ``20`` + - How far before the ideal cut a boundary may be searched, as a percentage of + ``chunk_size`` (0-50) + * - ``content_chunker.length.boundary.lookahead_percent`` + - ``5`` + - How far after the ideal cut a sentence end or line break may be searched, as a + percentage of ``chunk_size`` (0-25). Used only when nothing was found behind the cut + * - ``content_chunker.max_chunks_per_document`` + - ``1000`` + - Maximum number of chunks per document. Documents that exceed this are marked ``skipped`` + and receive no embeddings. Because boundary-aware splitting makes chunks shorter, a + document yields roughly 3% to 25% more chunks than a fixed-length split, so a corpus of + very large documents may need a higher value here + * - ``content_chunker.embedding.name`` + - ``opensearch`` + - Embedding provider (``opensearch`` / ``ollama`` / ``openai`` / ``gemini`` / ``bedrock`` / ``none``) + * - ``content_chunker.embedding.dimension`` + - ``768`` + - Dimension of the embedding vector. This value is used when the mapping is created, so it + **must** match the dimension of the embedding model you use. There are two distinct read + paths for this value, and they behave differently. When the index mapping is created, an + unset value falls back to ``768`` **without any warning**, and an empty, non-numeric, + non-positive, or above-``16000`` value (``16000`` is the k-NN plugin's own maximum) falls + back to ``768`` with a warning. The embedding process itself, by contrast, has no + fallback: an unset, non-numeric, or non-positive value is an error there. A value above + ``16000`` is not rejected at runtime, so only the mapping ends up at ``768`` and you get a + dimension mismatch. The mapping's dimension cannot be changed once the index has been + created; see *If the Index Was Created Without a Dimension* under *Notes* for how to + recover from an index created with the value unset + * - ``content_chunker.job.concurrency`` + - ``2`` + - Number of parallel workers for the indexer job + * - ``content_chunker.job.bulk_size`` + - ``20`` + - Number of documents fetched and written per batch + * - ``content_chunker.job.max_documents_per_run`` + - ``-1``\ (unlimited) + - Maximum number of documents processed per job run. Any value of ``0`` or less is treated + as unlimited + * - ``content_chunker.job.retry_failed`` + - ``false`` + - When set to ``true``, documents that ended the previous run with + ``content_chunk_status=fail`` are included in the next run's processing target as well. + There is no automatic retry or attempt-count tracking; the intended workflow is to fix the + underlying cause, then temporarily enable this to retry + * - ``content_chunker.chat.top_k`` + - ``3`` + - Number of chunks selected when AI search mode generates an answer + * - ``content_chunker.search.enabled`` + - ``false`` + - Rank Fusion integration for semantic search (**enabling this requires a restart**) + * - ``content_chunker.search.min_score`` + - (unset) + - Minimum cosine similarity (0-1) required for a result to be included. No cutoff when unset. + In ``ann`` mode, if ``search.knn.space_type`` is anything other than ``cosinesimil``, a + cosine-based cutoff cannot be defined, so the cutoff is skipped with a warning + * - ``content_chunker.search.knn.method`` + - ``hnsw`` + - ANN index method. ``hnsw`` is currently the only accepted value; any other value falls back + to ``hnsw`` with a warning (reflected in the mapping; changing it requires recreating the + index) + * - ``content_chunker.search.knn.engine`` + - ``lucene`` + - ANN engine. Only ``lucene`` or ``faiss`` are accepted (see Prerequisites above); any other + value falls back to ``lucene`` with a warning (reflected in the mapping; changing it + requires recreating the index) + * - ``content_chunker.search.knn.space_type`` + - ``cosinesimil`` + - Distance space. Only ``cosinesimil``, ``innerproduct``, or ``l2`` are accepted; any other + value falls back to ``cosinesimil`` with a warning (reflected in the mapping; changing it + requires recreating the index) + * - ``content_chunker.search.knn.k`` + - ``100`` + - Number of neighbors retrieved per shard by the ANN query. When |Fess| performs the fusion, + the effective value never falls below ``rank.fusion.window_size`` divided by the number of + searchers (200 / 2 = 100 by default), so a smaller value has no effect. When the search + engine performs the fusion, this value is used as is + * - ``content_chunker.search.knn.param.ef_search`` + - (unset) + - The ``ef_search`` parameter for ANN queries + +.. note:: + + With ``content_chunker.length.boundary.enabled=true`` (the default), + ``content_chunker.length.chunk_size`` becomes a target rather than a hard ceiling: each cut + moves to the nearest candidate of the highest tier present in the search window. A line break + or sentence end wins over any clause separator or space no matter how much farther back it + is, and those win over a writing-system change. Only the cut point ever moves; no character + is dropped, so concatenating a document's chunks still reproduces its content exactly. The + forward search can overshoot ``chunk_size`` by up to + ``content_chunker.length.boundary.lookahead_percent``; a second, independent overshoot of up + to 32 characters can occur when a cut would otherwise land inside a grapheme cluster (a + combining mark, a variation selector, or a zero-width-joined emoji sequence) — that one + ignores ``lookahead_percent`` and can happen even when it is ``0``. The two overshoots never + occur on the same cut, so at the shipped defaults a chunk runs from 640 to 840 characters. + Because chunks come in shorter on average, a document yields roughly 3% to 25% more chunks + than a fixed-length split (see ``content_chunker.max_chunks_per_document``). Setting + ``content_chunker.length.boundary.enabled`` to ``false``, or both percentages to ``0``, + reproduces the previous fixed-length behaviour exactly. Changing any of these settings only + affects documents chunked afterwards: a document already stored as a chunk array keeps its + boundaries until it is re-crawled. + +.. note:: + + ``content_chunker.length.chunk_size`` is specified in characters, but an embedding model can + only take in text up to its token limit. |Fess| does not truncate the text it embeds, so the + part beyond that limit may not be reflected in the vector. Choose ``chunk_size`` from the + input limit of the model you use. For example, measured with + ``paraphrase-multilingual-MiniLM-L12-v2`` (128 tokens at most), the part that was reflected + in the vector was about 440 characters of English and about 210 characters of Japanese (it + varies with the text). With this model, the later part of a chunk at the default + ``chunk_size=800`` is not reflected in the vector. + +.. note:: + + The HNSW ``m`` and ``ef_construction`` parameters are hard-coded in ``doc.json`` + (``m=16`` / ``ef_construction=100``) and cannot be changed through configuration. + +Connection Settings for the opensearch Provider +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Connection settings for the built-in ``opensearch`` provider (OpenSearch ML Commons). These are +set in the same ``system.properties`` file as above. + +.. list-table:: + :header-rows: 1 + :widths: 50 20 30 + + * - Property + - Default + - Description + * - ``content_chunker.embedding.opensearch.model.id`` + - (required) + - ID of the model already deployed to ML Commons + * - ``content_chunker.embedding.opensearch.api.url`` + - The search engine's address + - ML Commons API endpoint. When unset, defaults to the search engine |Fess| is already using + (e.g. ``http://localhost:9200``) + * - ``content_chunker.embedding.opensearch.username`` / ``password`` + - The search engine's credentials + - When unset, falls back to the credentials used for the search engine connection — but + only while ``api.url`` is left unconfigured (i.e. the target is the same cluster |Fess| + already uses). Once ``api.url`` is set, there is no fallback. + * - ``content_chunker.embedding.opensearch.timeout`` + - ``60000`` + - Request timeout (ms) + * - ``content_chunker.embedding.opensearch.connect.timeout`` + - ``5000`` + - Connection timeout (ms) + * - ``content_chunker.embedding.opensearch.retry.max`` + - ``3`` + - Maximum number of attempts, including the first, for transient errors (429, 5xx, etc.). + This is not the number of retries: ``3`` means at most three requests in total, with two + waits in between. A value of ``1`` or less means no retry + * - ``content_chunker.embedding.opensearch.retry.base.delay.ms`` + - ``2000`` + - Base retry backoff delay (ms) + * - ``content_chunker.embedding.opensearch.availability.check.interval`` + - ``60`` + - Interval between provider availability checks (seconds) + * - ``content_chunker.embedding.opensearch.document.prefix`` / ``query.prefix`` + - (empty) + - Prefix prepended to document/query text before embedding + +.. warning:: + + The contents of ``system.properties`` can be viewed on the admin **System Info > Config Info** + screen, in the **App Properties** panel. ``content_chunker.embedding.opensearch.password`` is + masked there as ``XXXXXXXX``, but ``username`` is shown as-is. Values supplied with + ``-Dfess.system.``, on the other hand, are shown **unmasked** in the **System Properties** + panel of that same screen — so put credentials in ``system.properties`` rather than in startup + options. + +Other Providers (ollama / openai / gemini / bedrock) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``ollama`` provider (``fess-llm-ollama`` plugin) uses the same style of settings under the +``content_chunker.embedding.ollama.`` prefix (``api.url`` defaults to ``http://localhost:11434``, +``model`` defaults to ``embeddinggemma``, and ``document.prefix`` / ``query.prefix`` default to +``title: none | text:`` / ``task: search result | query:`` respectively). If you use a model in +the ``nomic-embed-text`` family, set ``document.prefix`` / ``query.prefix`` explicitly to +``search_document:`` / ``search_query:``. These prefixes are concatenated with the text to be +embedded exactly as configured (surrounding whitespace is not trimmed), so the defaults above and +``search_document:`` / ``search_query:`` all **include one trailing space**. Remember the +separating space when you set a prefix yourself. The ``openai`` and ``gemini`` providers +are configured the same way, under the ``content_chunker.embedding.openai.`` and +``content_chunker.embedding.gemini.`` prefixes respectively. See each plugin's documentation for +the full list of settings. The ``bedrock`` provider uses the ``content_chunker.embedding.bedrock.`` +prefix, and ``content_chunker.embedding.dimension`` must be a size the configured model produces; +see :doc:`llm-bedrock`. + +Setup Procedure (opensearch Provider Example) +=============================================== + +This section walks through a configuration example using the built-in ``opensearch`` provider +(ML Commons). + +1. Deploy the Embedding Model +------------------------------- + +Register and deploy an embedding model to OpenSearch ML Commons. On a single-node cluster, you +must apply the following setting first. + +.. code-block:: bash + + curl -XPUT "http://localhost:9200/_cluster/settings" \ + -H "Content-Type: application/json" -d ' + {"persistent": {"plugins.ml_commons.only_run_on_ml_node": false}}' + +Register and deploy the model (example: a 384-dimension sentence embedding model): + +.. code-block:: bash + + # Register the model (get model_id from the response's task_id) + curl -XPOST "http://localhost:9200/_plugins/_ml/models/_register" \ + -H "Content-Type: application/json" -d ' + { + "name": "huggingface/sentence-transformers/all-MiniLM-L6-v2", + "version": "1.0.2", + "model_format": "TORCH_SCRIPT" + }' + + # Check the task and obtain model_id (model_id is returned once state becomes COMPLETED) + curl "http://localhost:9200/_plugins/_ml/tasks/" + + # Deploy + curl -XPOST "http://localhost:9200/_plugins/_ml/models//_deploy" + + # Check status: model_state should be DEPLOYED + curl "http://localhost:9200/_plugins/_ml/models/" + +.. note:: + + A model that is still ``REGISTERED`` cannot be used. Be sure to deploy it and confirm that + ``model_state`` becomes ``DEPLOYED``. + +2. Configure |Fess| +---------------------- + +``app/WEB-INF/conf/system.properties`` (``/etc/fess/system.properties`` on the RPM/DEB packages, +``/opt/fess/system.properties`` on Docker; everything below goes in that same file):: + + content_chunker.enabled=true + content_chunker.embedding.name=opensearch + content_chunker.embedding.dimension=384 + content_chunker.embedding.opensearch.model.id= + +If you also want to use semantic search, add the following as well:: + + content_chunker.search.enabled=true + +Restart |Fess| after making these changes. + +3. Recreate the Index (When Enabling on an Existing Deployment) +------------------------------------------------------------------- + +The mapping for the ``content_chunk_vector`` field — including the dimension and ANN method +settings you configured — is applied **at the moment the** ``fess.search`` **index is newly +created**. + +- **New installations**: If you apply the settings above to ``system.properties`` before starting + |Fess| for the first time, the correct mapping is applied automatically when the index is first + created, so this step is unnecessary. +- **If an index already exists** (that is, if you have started |Fess| at least once before): the + running index does not pick up the new mapping automatically, and an existing mapping cannot be + amended after the fact. Recreate the index as follows: + + Open **System Info > Maintenance**, and under **Re-indexing** run it with **Replace Aliases** + enabled. + + You can then confirm that the recreated index has ``index.knn: true`` in its index settings and a + ``content_chunk_vector`` mapping carrying your configured dimension and ANN method settings + (``index.knn`` is an index setting while the ANN method settings live in the mapping — they are + applied in two different places). + +.. warning:: + + Re-indexing runs as an asynchronous background operation, and the admin UI shows no completion + notification. ``_cat/indices`` only shows that the new index exists (health, doc count, and so + on) — it does not show which index the aliases point to. Before moving on to the indexer job + below, check ``_cat/aliases`` instead and confirm that both ``fess.search`` and ``fess.update`` + point to the new index; the |Fess| log only logs a warning on failure, so a quiet log is not + proof of success, only the absence of a known failure. The old index (the physical index that + the ``fess.search`` alias previously pointed to, named ``fess.``) is not deleted + automatically; remove it manually once you no longer need it. While both indices exist, expect + roughly double the usual index disk usage. + +4. Enable the Indexer Job +---------------------------- + +Chunking and embedding generation are performed by the scheduler job **Content Chunk Vector +Indexer** (ID: ``content-chunk-vector-indexer``; disabled by default; scheduled ``0 13 * * *``). + +Enable this job under **System > Scheduler**, then run it once with **Start Now**. After that, +unprocessed documents are picked up on the configured schedule (daily at 13:00 by default), +independently of when crawling finishes. This job is not chained to the crawler job, so if you want +documents processed right after a crawl, set its schedule to a time later than the crawler job is +expected to finish. + +.. note:: + + In a multi-node deployment, we recommend pinning this job to run on exactly one node. Running + it on every node at once does not break correctness, but every node processes and embeds the + same documents redundantly, multiplying the load and cost on your embedding provider by the + number of nodes. + + Pinning it requires **both** of the following settings — either one alone does not pin the job. + + 1. **On the node you want to run the job**: set ``scheduler.target.name=`` in + ``app/WEB-INF/classes/fess_config.properties`` (``/etc/fess/fess_config.properties`` on the + RPM/DEB packages, or via ``-Dfess.config.scheduler.target.name=``), then + restart that node. (The default is empty; leave every other node at the default.) + 2. In the admin UI, under **System > Scheduler**, open the Content Chunk Vector Indexer job and + change its **Target** field from ``all`` to the same identifier you set in step 1, then + save. + + See :doc:`../admin/scheduler-guide` for what the **Target** field means. Setting + ``scheduler.target.name`` alone does not pin the job if the **Target** field is left at + ``all``: **it will not be pinned**. ``all`` is treated as a special value that always matches, + so step 1 alone or step 2 alone is not enough — you must do both. + +.. warning:: + + Once the job is pinned, run **Start Now** **from the admin UI of the node you gave the + identifier to in step 1**. If you press **Start Now** on any other node, the screen still + reports "Started a job: ...", but the job does not actually run because the **Target** does not + match — the only trace is an ``Ignoring job`` line logged at INFO level on that node. + +5. Check Processing Status +----------------------------- + +You can check the outcome for each document in its ``content_chunk_status`` field. + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Value + - Meaning + * - (field absent) + - Not yet processed (will be picked up by the next job run). Documents also return to this + state after being re-crawled + * - ``done`` + - Chunking and vector generation completed + * - ``chunked`` + - Chunking completed only (chunk-only mode). This is the state when + ``embedding.name=none``, and also when the plugin for the provider named in + ``embedding.name`` is not installed + * - ``skipped`` + - Processing skipped. This covers documents whose body is empty (including whitespace + only), documents for which no chunk was produced, and documents that exceed + ``max_chunks_per_document``. If ``content_chunker.chunker.name`` names a chunker that does + not exist, no chunker is found and no chunk is produced, so every document ends up in this + state. It is a terminal state: re-running the job does not process the document again + * - ``fail`` + - Processing failed (check the logs). It is a terminal state: by default, re-running the job + does not process the document again. Set ``content_chunker.job.retry_failed`` to ``true`` + to process it again + +You can check the distribution of statuses by querying the search engine directly:: + + curl -XPOST "http://localhost:9200/fess.search/_search" \ + -H "Content-Type: application/json" -d ' + {"size": 0, "aggs": {"status": {"terms": {"field": "content_chunk_status", "missing": "pending"}}}}' + +Thanks to the ``missing`` option, documents that have no ``content_chunk_status`` (that is, +unprocessed documents) are aggregated into a bucket keyed ``pending``. + +Judge the state of the chunk job by this distribution of ``content_chunk_status``. If ``pending`` +shrinks and ``done`` (``chunked`` in chunk-only mode) grows with each job run, the job is making +progress. If ``fail`` appears, check the |Fess| logs for the cause. ``skipped`` is normal for +documents such as those with an empty body, but if nearly every document is ``skipped``, suspect a +wrong ``content_chunker.chunker.name`` (when no chunker is found, a ``Chunker not found`` WARN +message is logged). + +.. warning:: + + Fixing the configuration does not by itself undo ``skipped`` or ``fail``. A ``skipped`` + document is not picked up when the job is re-run (a re-crawled document returns to the + unprocessed state), and a ``fail`` document is processed again only when + ``content_chunker.job.retry_failed`` is ``true``. For example, if the job ran with a wrong + ``content_chunker.chunker.name`` and every document became ``skipped``, correct the name, + delete ``content_chunk_status`` as shown below, and then re-run the job (a ``skipped`` + document's ``content`` has not been rewritten, so it can be processed as it is):: + + curl -XPOST "http://localhost:9200/fess.search/_update_by_query" \ + -H "Content-Type: application/json" -d ' + { + "query": {"term": {"content_chunk_status": "skipped"}}, + "script": {"source": "ctx._source.remove(\"content_chunk_status\")"} + }' + +How Semantic Search Behaves +============================== + +Setting ``content_chunker.search.enabled=true`` registers the semantic searcher with Rank Fusion, +which then merges keyword search results with vector search results. (See :doc:`rank-fusion` for +how Rank Fusion works.) By default |Fess| performs the fusion itself; setting +``rank.fusion.engine.enabled=true`` has OpenSearch perform it instead (see +:ref:`rank-fusion-engine`). +Note that ``content_chunker.enabled`` is also consulted at search time: when +``content_chunker.enabled=false`` or ``content_chunker.embedding.name=none``, semantic search does +not run even though the searcher is registered. (This is evaluated per request, so no restart is +needed.) + +.. warning:: + + Because the semantic searcher is registered at startup, **enabling this requires a restart**. + Disabling it (changing the value back to ``false``) is evaluated per request, so it takes + effect immediately. + +exact Mode and ann Mode +-------------------------- + +The search method is chosen automatically based on the state of the index. + +.. list-table:: + :header-rows: 1 + :widths: 12 44 44 + + * - Mode + - Condition + - Characteristics + * - ``ann`` + - An index that has ``index.knn`` and ANN method settings + - Approximate nearest-neighbor search using HNSW. Suited to large indexes + * - ``exact`` + - Anything else (an index missing either ``index.knn`` or the ANN method settings, including + the case where the index state cannot be determined) + - Exact cosine-similarity computation against every vector. Suited to small-to-medium + indexes + +Any ``fess.search`` index newly created under |Fess| 15.10 always has ``index.knn`` and ANN method +settings, regardless of the value of ``content_chunker.search.enabled`` — so ``ann`` mode is +normally always used. ``exact`` mode is a fallback for older indexes created before this mechanism +existed. Because k-NN settings cannot be added to an existing index after the fact, switching an +``exact``-mode index to ``ann`` mode requires recreating the index (see +:ref:`semantic-search-migration`). Note that the result of this determination is cached for 60 +seconds, so it can take up to 60 seconds after recreating an index for the change to take effect. + +Score Cutoff +-------------- + +Setting ``content_chunker.search.min_score`` to a cosine similarity (0-1) excludes from semantic +search results any document whose best-matching chunk still falls short of that value. (A +document's score is the score of its best chunk, so the cutoff operates per document, not per +chunk.) Use it to rein in hit counts when queries with no vocabulary overlap are matching too +broadly:: + + content_chunker.search.min_score=0.4 + +The configured value is interpreted as a cosine similarity in both ``exact`` and ``ann`` mode; it is +converted internally to each mode's score scale. + +.. note:: + + This cutoff is applied only when ``content_chunker.search.knn.space_type`` is ``cosinesimil`` + (the default). On an ``ann``-mode index that uses ``innerproduct`` or ``l2``, a cosine + similarity cannot be defined, so the cutoff is skipped and a warning is logged for each such search. + +Limitations +------------- + +- Field-qualified conditions in the query (``label:``, ``site:``, ``filetype:``, ranges on + ``timestamp`` / ``last_modified``, and so on) are separated from the text to embed and applied + to the vector search as filters. The query is examined **after** it has been assembled, so + operations that append such conditions internally - specifying a label, drilling down with a + facet, or the file type, site and date range of advanced search, including conditions passed + through the ``ex_q`` and ``fields.*`` parameters - still run semantic search, narrowed by the + same conditions as the keyword search. +- **Semantic search is skipped** for the following queries, and only keyword search runs. + + - A sort order (the ``sort:`` pseudo field, or the ``sort`` parameter, which is also appended + internally as ``sort:...``) + - A phrase (``"..."``), wildcard (``*`` ``?``), fuzzy search (``~``) or range on words that name + no field, including the phrase of advanced search. The ASCII ``?`` is read as a wildcard, so a + natural-language question ending in an ASCII question mark - "what is ...?" - is skipped as + well. (The full-width ``？`` is not affected.) + - Excluding a word (``-word``, ``NOT word``, including the excluded words of advanced search) or + boosting one (``word^2``) + - A query whose conditions cannot be separated out as a filter, such as a word and a condition + joined with ``OR`` + - ``allintitle:`` / ``allinurl:`` + - A query that has conditions only, with no words to embed + - A query that cannot be parsed + +- It is also skipped when combined with geolocation search (a geo filter) or similar-document + search. +- How deep result pages are handled depends on where the fusion is performed. + + - When |Fess| performs the fusion (the default), the boundary is determined by + ``rank.fusion.window_size`` (default ``200``); by default everything from result 101 onward + is keyword-only. + - When the search engine performs the fusion (``rank.fusion.engine.enabled=true``), every + page is fused, but paging stops at ``rank.fusion.pagination_depth`` results (default + ``1000``); a page beyond that cannot be requested. + + See :doc:`rank-fusion` for details. +- If the embedding provider is unreachable or a search error occurs, |Fess| automatically falls + back to keyword-only results (the search itself never fails as a result). +- Role- and virtual-host-based access control applies to semantic search results as well. + +Integration with AI Search Mode +================================== + +When AI search mode (:doc:`rag-chat`, ``rag.chat.enabled=true``) is enabled, for documents whose +``content_chunk_status`` is ``done``, answer generation computes the similarity against each chunk +and uses only the top ``content_chunker.chat.top_k`` most relevant chunks (default: ``3``) as the +LLM's context. + +What is embedded here is not the user's own utterance but **the search query the LLM generated in +the intent-detection phase** (if a re-search occurs, the regenerated query is used instead). When +no search query is generated at all — as when the user asks for a summary of a document — no chunk +selection takes place. + +As a result, even for long documents only the relevant portions are passed to the LLM, which can +improve answer accuracy and reduce token usage. For documents whose ``content_chunk_status`` is +``chunked`` (chunks exist but vectors do not), chunk selection is performed by keyword (highlight) +matching instead of a similarity computation. Documents that are ``skipped`` or ``fail``, and +unprocessed documents, still use the full body (or a highlighted excerpt) as before. + +This behavior is independent of ``content_chunker.search.enabled``, but it does require +``content_chunker.enabled`` to be on. Note that the text formed by joining the selected chunks is +still truncated at ``rag.chat.content.fulltext.max.length`` (default ``3000``), so raising +``content_chunker.chat.top_k`` or ``content_chunker.length.chunk_size`` never sends more characters +than that limit to the LLM. + +.. _semantic-search-migration: + +Migrating from 15.7 or Earlier +================================= + +If you are upgrading |Fess| from 15.7 or earlier, your situation falls into one of the four +patterns below, depending on how you currently use these features. Follow the instructions for +the pattern that applies to you. + +New Installations +-------------------- + +No extra work is needed. If you want to use vector search, simply configure +``system.properties`` according to the *Configuration Reference* section on this page before +starting |Fess| for the first time; the correct mapping is applied automatically when the index is +first created. (See *Setup Procedure* above for the concrete steps.) + +.. note:: + + If you have started |Fess| even once before (that is, the index already exists), follow one of + the *existing users* patterns below instead of this one. + +Existing Users Who Do Not Want Vector Search +------------------------------------------------ + +No work is needed. ``content_chunker.enabled`` and ``content_chunker.search.enabled`` are both +``false`` by default, so your search results and existing index behavior are unchanged after the +upgrade. The new scheduler job **Content Chunk Vector Indexer** is registered automatically at +startup, but since it is disabled by default it never runs, and the semantic searcher is never +registered with Rank Fusion. (The job is registered on every startup, so if you delete it from the +admin UI it is recreated — still disabled — the next time |Fess| starts.) + +.. note:: + + Even if you never use vector search, **creating a new index** under |Fess| 15.10 or later + (including re-indexing) applies a mapping containing ``content_chunk_vector`` (a ``knn_vector`` + type) together with ``index.knn: true``. On a deployment whose OpenSearch does not have the + k-NN plugin installed, index creation fails at that point. See *Prerequisites* on this page for + details. + +Existing Users Who Want to Enable Vector Search +---------------------------------------------------- + +The running index does not pick up the new mapping automatically, so the following steps are +required. + +1. Apply the settings to ``system.properties`` as described in *Configuration Reference* on this + page (see *Setup Procedure* above for the concrete steps when using the opensearch provider). +2. Restart |Fess|. +3. In the admin UI, run **Re-indexing** under **System Info > Maintenance** with **Replace + Aliases** enabled. This runs in the background with no completion notification. + ``_cat/indices`` only shows that the new index exists, not whether the aliases have switched — + check ``_cat/aliases`` instead and confirm ``fess.search``/``fess.update`` point to the new + index (the |Fess| log only warns on failure, so silence is not proof of success). The old index + is not deleted automatically (remove it manually once you no longer need it), and index disk + usage roughly doubles until you do. +4. Only after confirming that the alias swap above has finished, enable and run the Content Chunk + Vector Indexer job under **System > Scheduler** (you do not need to re-crawl: the job reads + ``content`` from the existing index's ``_source`` to chunk and embed it). + +.. note:: + + If you also apply ``content_chunker.search.enabled=true`` in step 1, then between the restart in + step 2 and the completion of step 4 every search embeds the query without that embedding + affecting the results at all. With a metered provider such as ``openai``, ``gemini`` or ``bedrock``, apply + ``content_chunker.search.enabled=true`` and restart only after step 4 has completed. + +If You Were Using the fess-webapp-semantic-search Plugin +-------------------------------------------------------------- + +The ``fess-webapp-semantic-search`` plugin, which provided semantic search in |Fess| 15.7 and +earlier, has been folded into the core in 15.10 and is now **unnecessary (deprecated)**. In +addition to the steps in *Existing Users Who Want to Enable Vector Search* above, you also need to +do the following. + +1. **Remove the plugin**: delete ``fess-webapp-semantic-search-*.jar`` from + ``app/WEB-INF/plugin/`` (on Docker, exclude it from ``FESS_PLUGINS``). + +2. **Remove the old settings**: delete every ``-Dfess.semantic_search.*`` startup option. Also, + if you had specified ``-Drank.fusion.searchers=default,semantic`` for the old plugin, remove + it. Leaving it in place excludes the new semantic searcher (``semantic_chunk``) from Rank + Fusion and logs a warning at startup. + +3. **Detach the old ingest pipeline**: if you had configured ``-Dfess.semantic_search.pipeline``, + the old plugin embedded ``default_pipeline`` (an ingest pipeline for neural search) into the + index settings when the index was created. **Removing the plugin does not remove the + pipeline** — it stays attached to the index and keeps running — so detach it **before** you run + the re-indexing described in *Existing Users Who Want to Enable Vector Search*. The new index + produced by that re-indexing never carries the setting, so running the command afterwards + achieves nothing. Use ``_cat/aliases`` to find the ``fess.`` index that + ``fess.search`` points to, and target that concrete index name rather than the alias:: + + curl -XPUT "http://localhost:9200/fess./_settings" \ + -H "Content-Type: application/json" -d ' + {"index": {"default_pipeline": "_none"}}' + + Detaching it from the index settings leaves the ingest pipeline itself in place in the search + engine. If you will not be using it any more, delete it as well:: + + curl -XDELETE "http://localhost:9200/_ingest/pipeline/" + +4. **Add the new settings**: configure ``content_chunker.*`` in ``system.properties`` as + described in *Configuration Reference* on this page. If you continue to use your existing ML + Commons model, set ``content_chunker.embedding.name=opensearch`` and put its existing + ``model_id`` in ``content_chunker.embedding.opensearch.model.id``. + +5. **Recreate the index and run the job**: the vector field the old plugin stored + (``content_vector`` in the default configuration) and the ``content_chunk_vector`` field the new + core feature uses are different fields, so the old vectors cannot be used by the new feature. + Re-indexing copies ``_source`` verbatim, however, so those old vectors *are* duplicated into the + new index, where dynamic mapping keeps them consuming disk space. We recommend purging them + **before** re-indexing (adjust the field name if you had changed it):: + + curl -XPOST "http://localhost:9200/fess.search/_update_by_query" \ + -H "Content-Type: application/json" -d ' + { + "query": {"exists": {"field": "content_vector"}}, + "script": {"source": "ctx._source.remove(\"content_vector\")"} + }' + + Then run **Re-indexing** under **System Info > Maintenance**, and enable and run the Content + Chunk Vector Indexer job to regenerate the vectors. + +Notes +======= + +Changing the Embedding Model (Dimension) +-------------------------------------------- + +To switch to an embedding model with a different dimension, follow this order. + +1. Delete the existing, old vectors. If vectors at the old dimension are still present when you + re-index, the new mapping cannot accept them, and the affected documents are left uncopied to + the new index while processing carries on. |Fess| only checks the HTTP status of the re-index, + so the admin UI shows no error even though documents go missing:: + + curl -XPOST "http://localhost:9200/fess.search/_update_by_query" \ + -H "Content-Type: application/json" -d ' + { + "query": {"exists": {"field": "content_chunk_status"}}, + "script": {"source": "ctx._source.remove(\"content_chunk_vector\"); ctx._source.remove(\"content_chunk_status\")"} + }' + + .. note:: + + You may equally well target ``fess.update`` (the update alias that re-indexing reads from). + Also note that this operation leaves the ``content`` field as an array of chunks. The next + job run joins it back together and re-splits it, so if you have set + ``content_chunker.length.overlap`` to something other than 0, the overlapping portions end up + included twice when it is re-split. Re-crawl the affected documents if that concerns you. + +2. Change ``content_chunker.embedding.dimension`` and the model setting for your provider. +3. Recreate the index as described in *3. Recreate the Index (When Enabling on an Existing + Deployment)* under *Setup Procedure*, then re-run the indexer job. + +Changing to Another Model with the Same Dimension +--------------------------------------------------- + +If you change the embedding model setting, such as +``content_chunker.embedding.opensearch.model.id``, to another model with the same dimension, +|Fess| accepts it without any error or warning. Only the dimension is checked, and the model +that created the vectors is not recorded in the index. The stored vectors were then created by +the old model and the query vectors at search time by the new one; the two live in different +vector spaces, so the relevance of search results breaks down. The distribution of cosine +similarity values also differs from model to model, so a ``content_chunker.search.min_score`` +tuned for the old model can be too strict for the new one and cut off most results. + +To switch models, set the new model, delete ``content_chunk_vector`` and ``content_chunk_status`` +with the same ``_update_by_query`` as in step 1 of *Changing the Embedding Model (Dimension)* +above, and re-run the indexer job to regenerate the vectors of every document (the index does not +need to be recreated, because the dimension is the same). If you have set +``content_chunker.search.min_score``, review it with the new model. + +If the Index Was Created Without a Dimension +--------------------------------------------- + +If the ``fess.search`` index is created while ``content_chunker.embedding.dimension`` is unset, +the ``content_chunk_vector`` mapping gets a dimension of ``768`` without any warning, and it +cannot be changed afterwards. If you then run the indexer job, the dimension cannot be read when +embedding, which is an error, so the documents become ``fail``. + +- If the model you use has a dimension of ``768``, set ``content_chunker.embedding.dimension=768``. + It matches the mapping, so the index does not need to be recreated. +- Otherwise, set the correct dimension. While the mapping (``768``) and the setting disagree, the + indexer job logs an ERROR and skips the run. Recreate the index by the same method as in step 3 + of *Changing the Embedding Model (Dimension)* above. + +In either case, documents that have already become ``fail`` are not processed again +automatically. If you recreate the index, the ``_update_by_query`` in step 1 of *Changing the +Embedding Model (Dimension)* also deletes ``content_chunk_status``. If you do not recreate it, +temporarily set ``content_chunker.job.retry_failed`` to ``true`` and re-run the job. + +Disk Usage +------------ + +Chunk vectors are retained in ``_source`` in addition to the search index structures, so each +document consumes extra disk space proportional to its number of chunks times the vector +dimension. If disk space becomes a concern, adjust ``content_chunker.length.chunk_size`` or +``content_chunker.max_chunks_per_document``. + +chunk-only Mode +------------------ + +Setting ``content_chunker.embedding.name=none`` performs chunking only, without generating +embedding vectors (``content_chunk_status`` becomes ``chunked``). This lets you run chunking +ahead of time, before your embedding provider is ready; once you configure a provider later and +re-run the job, vectors are generated for the chunks already stored, without re-chunking them. + +Memory Settings for Large Corpora +-------------------------------------- + +The indexer job's child JVM is started with ``jvm.chunk.options`` in ``fess_config.properties`` +(JVM options that default to include ``-Xms128m -Xmx1g``). Because +``content_chunker.job.max_documents_per_run`` defaults to unlimited, a single run holds every +pending document ID in memory. Document IDs are SHA-512 digests (128 characters) and occupy roughly +200 bytes each on the heap, and chunk processing itself uses another 200-250MB — so for **corpora +beyond 1 to 2 million documents**, either raise the ``-Xmx`` value in ``jvm.chunk.options`` or set +a finite ``content_chunker.job.max_documents_per_run`` to split the work across several runs. +Override ``jvm.chunk.options`` in ``app/WEB-INF/classes/fess_config.properties`` +(``/etc/fess/fess_config.properties`` on the RPM/DEB packages); see :doc:`setup-memory` for how JVM +options work. + +The same unlimited default has a cost consequence with a metered embedding provider (``openai``, +``gemini``, ``bedrock``): the first indexer run embeds the entire existing corpus in one pass and bills for it +all at once. Set a finite ``content_chunker.job.max_documents_per_run`` to spread that cost across +multiple runs instead. + +References +============ + +- :doc:`rank-fusion` - Rank Fusion (hybrid search) configuration +- :doc:`rag-chat` - AI search mode configuration +- :doc:`llm-overview` - LLM integration overview +- :doc:`llm-ollama` - Ollama configuration +- :doc:`setup-memory` - JVM memory settings +- :doc:`../install/upgrade` - Upgrade procedure diff --git a/en/15.10/config/search.rst b/en/15.10/config/search.rst new file mode 100644 index 000000000..44e6593b0 --- /dev/null +++ b/en/15.10/config/search.rst @@ -0,0 +1,10 @@ +==================== +Search Functionality +==================== + +Display of Search Results Count +=============================== + +When the search results exceed 10,000, the search results page will display "about 10,000" as the result count. +To display the precise number of hits, a configuration change is required. + diff --git a/en/15.10/config/security-role.rst b/en/15.10/config/security-role.rst new file mode 100644 index 000000000..30b4c58c7 --- /dev/null +++ b/en/15.10/config/security-role.rst @@ -0,0 +1,72 @@ +================================ +Role-Based Search Configuration +================================ + +About Role-Based Search +======================== + +|Fess| can provide different search results based on the authentication information of users authenticated by any authentication system. +For example, User A with role a will see role a information in search results, but User B without role a will not see it when searching. +Using this feature, you can implement searches by department or position for users logged into portals or single sign-on environments. + +|Fess| role-based search can obtain role information from the following sources: + +- Request parameters + +- Request headers + +- Cookies + +- |Fess| authentication information + +In portals or agent-type single sign-on systems, role information can be obtained by storing authentication information in cookies for the domain and path where |Fess| is running during authentication. +In reverse proxy-type single sign-on systems, role information can be obtained by adding authentication information to request parameters or request headers when accessing |Fess|. + +.. note:: + Obtaining role information from request parameters, request headers, and cookies is disabled by default. + To use these sources, you must configure the key names to reference (``parameterKey``, ``headerKey``, ``cookieKey``), value encryption (``encryptedParameterValue``, etc.), and delimiters (``valueSeparator``, ``roleSeparator``) in the ``roleQueryHelper`` component of ``app/WEB-INF/classes/fess.xml``. + By default, only role-based search using |Fess| authentication information is enabled. + +Role-Based Search Configuration +================================ + +This section explains how to configure role-based search using |Fess| authentication information. + +Configuration in |Fess| Administration Screen +--------------------------------------------- + +Start |Fess| and log in as an administrator. +Create roles and users. +For example, create Role1 on the role management screen, and create a user belonging to Role1 on the user management screen. +If you want to assign by group, create a group on the group management screen and assign it to users. + +Next, in the crawl configuration, enter ``{role}Role1`` in the permission field and save. +To specify by user, use ``{user}username``; to specify by group, use ``{group}groupname``. +When specifying multiple permissions, separate each entry with a newline. + +After crawling with this crawl configuration, an index is created that is searchable only by users belonging to the specified roles, users, and groups. +Logged-in users are automatically granted permissions representing themselves (``{user}username``), their roles (``{role}``), and their groups (``{group}``), which are matched against the permissions set on documents. + +.. note:: + To explicitly deny access from a specific role, user, or group, prefix the entry with ``(deny)``, for example ``(deny){role}Role1``. Prefixing with ``(allow)`` grants access, which is treated the same as having no prefix. + +.. note:: + When integrating with LDAP or single sign-on, the user's role and group information is retrieved from the authentication source and treated as permissions in the same way. + The behavior during LDAP integration can be controlled by ``ldap.role.search.user.enabled``, ``ldap.role.search.group.enabled``, and ``ldap.role.search.role.enabled`` in ``fess_config.properties`` (all default to ``true``). + +Login +----- + +Log out from the administration screen. +Log in with a user belonging to Role1. +Upon successful login, you will be redirected to the top of the search screen. + +When searching normally, only items whose crawl configuration has the Role1 role set will be displayed. + +Also, searches performed without logging in are treated as searches by the guest user. +For documents you want to display to users who are not logged in, set ``{role}guest`` in the permission field of the crawl configuration (the default value is defined by ``role.search.guest.permissions``). + +Logout +------ + +When logged in as a user other than an administrator, select logout on the search screen to log out. diff --git a/en/15.10/config/security-virtual-host.rst b/en/15.10/config/security-virtual-host.rst new file mode 100644 index 000000000..cc8a6146c --- /dev/null +++ b/en/15.10/config/security-virtual-host.rst @@ -0,0 +1,91 @@ +============ +Virtual Host +============ + +About Virtual Host +================== + +|Fess| can serve different search results depending on the hostname (the value of the HTTP ``Host`` header) used to access it. +A single |Fess| server can be published under multiple hostnames, providing a different set of crawl targets and page design for each hostname. +The search screen can also look different for each host: a static theme whose name matches the virtual host name is used for that host. + +The virtual host feature is disabled (unconfigured) by default. Configure it using the steps below. + +System Configuration +-------------------- + +In :doc:`Administrator Guide > General Settings <../admin/general-guide>`, set the mapping between the requesting hostname and the virtual host name under "Virtual Host". Specify the virtual host name configured here in the crawl configuration. + +**Format** + +Specify one virtual host per line using the following format. + +:: + + header_name:header_value=virtual_host_name + +.. list-table:: + + * - *header_name* + - The name of the HTTP request header used for matching. Normally specify ``Host``. When accessing via a reverse proxy, you can also specify ``X-Forwarded-Host``. + * - *header_value* + - The hostname contained in the above header (in the form ``hostname:port`` if necessary). The virtual host is applied when this value exactly matches the value of the header sent by the client at access time (case-insensitive). + * - *virtual_host_name* + - The virtual host name to specify in the crawl configuration + +**Example** + +:: + + Host:abc.example.com=host1 + Host:192.168.1.123:8080=host2 + +.. note:: + + Matching is performed by string comparison against the request header value, not by hostname resolution (DNS). + The ``Host`` header sent by the browser does not include the port number when accessing via a standard port (80 for HTTP, 443 for HTTPS), but does include it in the form ``hostname:port`` when accessing via any other port. + Therefore, when publishing on a non-standard port, specify the port number explicitly, for example ``Host:abc.example.com:8080=host1``. + +.. note:: + + Only alphanumeric characters and underscores ( ``a-z`` , ``A-Z`` , ``0-9`` , ``_`` ) can be used in virtual host names. + Other characters are automatically removed. + + The following names are reserved and cannot be used as virtual host names: + ``admin`` , ``common`` , ``error`` , ``login`` , ``profile`` + +Page Design per Virtual Host +----------------------------- + +To give a virtual host its own search screen, install a static theme whose ``name`` in ``theme.yml`` is the virtual host name in lowercase (for example ``host1``). +A request that matches the virtual host is served with that theme; any other request is served with the default theme. +The theme does not have to be set as the default. See :ref:`theme-customize-bundled` for how to create a theme from the bundled one, and :doc:`../admin/theme-guide` for how to install it. + +.. note:: + + Since |Fess| 15.10, saving the configuration no longer generates JSPs under ``WEB-INF/view/virtual_host_name``. + The login screen (``/login/``) is the same page for every virtual host (``WEB-INF/view/admin/login/``) and cannot be changed per virtual host. + To give a virtual host its own look, use a static theme named after the virtual host, as described above. + + +Crawl Configuration +------------------- + +Specify "Virtual Host" in web crawl configuration, file crawl configuration, or data store crawl configuration. +"Virtual Host" should be one of the virtual host names configured in the system settings. You can specify multiple virtual hosts for a single crawl configuration (one per line). + +Searches made from a matched virtual host will only display documents belonging to crawl configurations that have that virtual host assigned. +Accesses that do not match any virtual host (normal access with no virtual host configured) are not filtered, and all search results are returned as usual. + +**Example** + +.. list-table:: + + * - *Virtual Host* + - ``host1`` + + +User Tags +--------- + +The tags that logged-in users put on search results (My tags) follow the virtual host too, when the tag feature is enabled. A tag made on a virtual host is listed and usable only on that virtual host. A request that matches no virtual host sees every tag. A tag that has a virtual host is put only on the documents of crawl settings that have that virtual host. For details, see :doc:`../admin/tagtype-guide` and :doc:`../api/api-tag`. diff --git a/en/15.10/config/setup-memory.rst b/en/15.10/config/setup-memory.rst new file mode 100644 index 000000000..3e39db544 --- /dev/null +++ b/en/15.10/config/setup-memory.rst @@ -0,0 +1,439 @@ +================== +Memory Configuration +================== + +Overview +======== + +For Java applications, you need to configure the maximum heap memory used by each process. +In |Fess|, memory configuration is performed for the following three components: + +- Fess Web Application +- Crawler Process +- OpenSearch + +Proper memory configuration enables improved performance and stable operation. + +Fess Web Application Memory Configuration +========================================== + +When Configuration is Needed +----------------------------- + +Consider adjusting the memory size in the following cases: + +- OutOfMemory errors are recorded in ``fess.log`` +- Need to handle a large number of concurrent requests +- Administration screen operations are slow or timeout + +The default memory size is sufficient for typical usage, but high-load environments require an increase. + +Configuration via Environment Variables +---------------------------------------- + +Set the ``FESS_HEAP_SIZE`` environment variable. + +:: + + export FESS_HEAP_SIZE=2g + +Units: + +- ``m``: megabytes +- ``g``: gigabytes + +Fine-Grained Memory Control +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``FESS_HEAP_SIZE`` sets both ``-Xms`` and ``-Xmx`` to the same value. To control the initial and maximum heap sizes independently, use the ``FESS_MIN_MEM`` and ``FESS_MAX_MEM`` environment variables. + +:: + + export FESS_MIN_MEM=256m + export FESS_MAX_MEM=2g + +.. list-table:: Default Memory Settings by Platform + :header-rows: 1 + :widths: 30 35 35 + + * - Platform + - FESS_MIN_MEM (Default) + - FESS_MAX_MEM (Default) + * - Linux + - 256m + - 2g + * - Windows + - 256m + - 1g + +.. note:: + When ``FESS_HEAP_SIZE`` is set, ``FESS_MIN_MEM`` and ``FESS_MAX_MEM`` are ignored. + +.. note:: + With the RPM/DEB packages, the environment file (``/etc/sysconfig/fess``, or ``/etc/default/fess`` for DEB) sets ``FESS_HEAP_SIZE=512m``. The heap is therefore fixed at 512m instead of the defaults in the table above. To change the heap size, change this ``FESS_HEAP_SIZE`` value. + +For RPM/DEB Packages +--------------------- + +For RPM package installations, edit ``/etc/sysconfig/fess``. + +:: + + FESS_HEAP_SIZE=2g + +For DEB packages, edit ``/etc/default/fess``. + +:: + + FESS_HEAP_SIZE=2g + +.. warning:: + After changing the memory size, you must restart the |Fess| service. + +Recommended Memory Sizes +------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 30 30 40 + + * - Environment + - Recommended Heap Size + - Notes + * - Development/Test + - 512m-1g + - Small-scale index + * - Small Production + - 1g-2g + - Tens to hundreds of thousands of documents + * - Medium Production + - 2g-4g + - Hundreds of thousands to millions of documents + * - Large Production + - 4g-8g + - Millions or more documents + +Crawler Memory Configuration +============================= + +When Configuration is Needed +----------------------------- + +You need to increase crawler memory size in the following cases: + +- Increasing parallel crawl count +- Crawling large files +- OutOfMemory errors occur during crawling + +Configuration Method +-------------------- + +Edit ``app/WEB-INF/classes/fess_config.properties`` or ``/etc/fess/fess_config.properties``. + +``jvm.crawler.options`` is a single setting that lists the JVM options of the crawler process, separated by newlines (``\n``). Changing the value replaces all of the default options, so if you write only ``-Xmx512m``, the other default options, such as ``-Dfile.encoding=UTF-8`` and the G1GC settings, are lost as well. Keep the default value listed in ``fess_config.properties`` and change only the heap size lines. + +For example, to change the maximum heap to 1GB, rewrite the ``-Xmx512m`` line of the default value as follows. + +:: + + -Xms128m\n\ + -Xmx1g\n\ + +.. note:: + This setting applies per crawler process (per scheduler job). + When running multiple crawl jobs simultaneously, each job uses the specified memory. + +Recommended Settings +-------------------- + +- **Normal Web Crawling**: 512m-1g +- **High-Volume Parallel Crawling**: 1g-2g +- **Large File Crawling**: 2g-4g + +Detailed JVM Options +-------------------- + +Detailed JVM options for the crawler can be configured in ``jvm.crawler.options``. +The default configuration includes the following optimizations: + +**Key Options:** + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - Option + - Description + * - ``-Xms128m -Xmx512m`` + - Initial and maximum heap size + * - ``-XX:MaxMetaspaceSize=128m`` + - Maximum Metaspace size + * - ``-XX:+UseG1GC`` + - Use G1 garbage collector + * - ``-XX:MaxGCPauseMillis=60000`` + - Maximum GC pause time goal (60 seconds). A relaxed target for crawler workloads (typical applications use ~200ms) + * - ``-XX:-HeapDumpOnOutOfMemoryError`` + - Disable heap dump on OutOfMemory + +OpenSearch Memory Configuration +================================ + +Important Considerations +------------------------ + +For OpenSearch, you need to consider the following two points when configuring memory: + +1. **Java Heap Memory**: Used by the OpenSearch process +2. **OS Filesystem Cache**: Critical for search performance + +.. warning:: + If Java heap memory is set too large, the memory available for OS filesystem cache + will decrease, resulting in degraded search performance. + +Configuration Method +-------------------- + +Linux Environment +~~~~~~~~~~~~~~~~~ + +OpenSearch heap memory is recommended to be configured in ``config/jvm.options``. + +Edit ``config/jvm.options``: + +:: + + -Xms2g + -Xmx2g + +.. note:: + It is recommended to set the minimum heap size (``-Xms``) and maximum heap size (``-Xmx``) to the same value. + +.. note:: + The ``OPENSEARCH_HEAP_SIZE`` environment variable is deprecated in OpenSearch 3.x and later. Use ``config/jvm.options`` or the ``OPENSEARCH_JAVA_OPTS`` environment variable instead. + + :: + + export OPENSEARCH_JAVA_OPTS="-Xms2g -Xmx2g" + +Windows Environment +~~~~~~~~~~~~~~~~~~~ + +Edit the ``config\jvm.options`` file. + +:: + + -Xms2g + -Xmx2g + +Recommended Memory Sizes +------------------------ + +.. list-table:: + :header-rows: 1 + :widths: 30 30 40 + + * - Index Size + - Recommended Heap Size + - Recommended Total Memory + * - Up to 10GB + - 2g + - 4GB or more + * - 10GB-50GB + - 4g + - 8GB or more + * - 50GB-100GB + - 8g + - 16GB or more + * - 100GB or more + - 16g-31g + - 32GB or more + +.. warning:: + Do not configure OpenSearch heap memory to exceed 32GB. + Exceeding 32GB disables Compressed OOP, reducing memory efficiency. + +Best Practices +-------------- + +1. **Allocate 50% of Physical Memory to Heap** + + Allocate approximately 50% of the server's physical memory to OpenSearch heap. + The remainder is used for the OS and filesystem cache. + +2. **Maximum 31GB** + + Set heap size to a maximum of 31GB; if more is needed, add additional nodes. + +3. **Verification in Production** + + Refer to the official OpenSearch documentation for optimal settings based on your environment. + +Suggest and Thumbnail Processing Memory Configuration +====================================================== + +Suggest Generation Process +--------------------------- + +Memory configuration for suggest generation processing is set in ``jvm.suggest.options``. + +Like the crawler's, this setting holds all the default options, so change only the ``-Xmx256m`` line and keep the others. + +The following settings are used by default: + +- Initial heap: 128MB +- Maximum heap: 256MB +- Maximum Metaspace: 128MB + +Thumbnail Generation Process +----------------------------- + +Memory configuration for thumbnail generation processing is set in ``jvm.thumbnail.options``. + +Like the crawler's, this setting holds all the default options, so change only the ``-Xmx256m`` line and keep the others. + +The following settings are used by default: + +- Initial heap: 128MB +- Maximum heap: 256MB +- Maximum Metaspace: 128MB + +.. note:: + When processing large images for thumbnail generation, you need to increase memory. + +Memory Monitoring and Tuning +============================= + +Checking Memory Usage +--------------------- + +Fess Memory Usage +~~~~~~~~~~~~~~~~~ + +You can check this on the "System Information" page in the administration screen. + +Or use JVM monitoring tools: + +:: + + jps -l # Check Fess process + jstat -gcutil 1000 # Display GC statistics every second + +OpenSearch Memory Usage +~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + curl -X GET "localhost:9200/_nodes/stats/jvm?pretty" + curl -X GET "localhost:9200/_cat/nodes?v&h=heap.percent,ram.percent" + +Signs of Memory Shortage +------------------------- + +If the following symptoms appear, there may be a memory shortage. + +**Fess Web Application:** + +- Slow response +- ``OutOfMemoryError`` recorded in logs +- Process terminates unexpectedly + +**Crawler:** + +- Crawling stops midway +- ``OutOfMemoryError`` recorded in ``fess-crawler.log`` +- Large file crawling fails + +**OpenSearch:** + +- Slow search +- Slow indexing +- ``circuit_breaker_exception`` errors occur + +Tuning Procedure +---------------- + +1. **Check Current Memory Usage** + + Monitor memory usage for each component. + +2. **Identify Bottlenecks** + + Determine which component is experiencing memory shortage. + +3. **Increase Gradually** + + Rather than increasing significantly at once, increase by 25-50% and verify effectiveness. + +4. **Consider Overall System Balance** + + Ensure total memory for all components does not exceed physical memory. + +5. **Continuous Monitoring** + + Continuously monitor memory usage and adjust as needed. + +Memory Leak Countermeasures +---------------------------- + +If a memory leak is suspected: + +1. **Obtain Heap Dump** + +:: + + jmap -dump:format=b,file=heap.bin + +2. **Analyze Heap Dump** + + Analyze using tools such as Eclipse Memory Analyzer (MAT). + +3. **Report Issues** + + If you discover a memory leak, please report it on GitHub Issues. + +Troubleshooting +=============== + +OutOfMemoryError Occurs +------------------------ + +**Fess Web Application:** + +1. Increase ``FESS_HEAP_SIZE``. +2. Limit concurrent access count. +3. Lower log level to reduce memory usage from logging. + +**Crawler:** + +1. Increase ``-Xmx`` in ``jvm.crawler.options``. +2. Reduce parallel crawl count. +3. Adjust crawl settings to exclude large files. + +**OpenSearch:** + +1. Increase heap size (up to 31GB maximum). +2. Review index shard count. +3. Check query complexity. + +Long GC Pause Times +------------------- + +1. Adjust G1GC settings. +2. Set heap size appropriately (too large or too small will cause frequent GC). +3. Consider updating to a newer Java version. + +Performance Does Not Improve After Memory Configuration +-------------------------------------------------------- + +1. Check other resources such as CPU, disk I/O, and network. +2. Optimize indexes. +3. Review queries and crawl settings. + +References +========== + +- :doc:`setup-port-network` - Port and Network Configuration +- :doc:`crawler-advanced` - Advanced Crawler Configuration +- :doc:`admin-logging` - Log Configuration +- `OpenSearch Memory Settings `_ +- `Java GC Tuning `_ diff --git a/en/15.10/config/setup-port-network.rst b/en/15.10/config/setup-port-network.rst new file mode 100644 index 000000000..8c8555b3a --- /dev/null +++ b/en/15.10/config/setup-port-network.rst @@ -0,0 +1,467 @@ +======================== +Port and Network Settings +======================== + +Overview +======== + +This section describes network-related configurations for |Fess|. +It covers settings for network connectivity, including port number changes, proxy configurations, and HTTP communication settings. + +Port Configuration +================== + +Default Ports +------------- + +|Fess| uses the following ports by default: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Service + - Port Number + * - Fess Web Application + - 8080 + * - OpenSearch (HTTP) + - 9200 + * - OpenSearch (Transport) + - 9300 + +Changing Fess Web Application Port +----------------------------------- + +Configuration on Linux +~~~~~~~~~~~~~~~~~~~~~~ + +To change the port number on Linux, edit ``bin/fess.in.sh``. + +:: + + FESS_JAVA_OPTS="$FESS_JAVA_OPTS -Dfess.port=8080" + +For example, to use port 80: + +:: + + FESS_JAVA_OPTS="$FESS_JAVA_OPTS -Dfess.port=80" + +.. note:: + Using port numbers below 1024 requires root privileges or appropriate permission settings (CAP_NET_BIND_SERVICE). + +Configuration via Environment Variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can also specify the port number using environment variables. + +:: + + export FESS_PORT=8080 + +.. warning:: + The ``FESS_PORT`` environment variable is only available on Linux. On Windows, edit ``-Dfess.port`` directly in ``bin\fess.in.bat``. + +For RPM/DEB Packages +~~~~~~~~~~~~~~~~~~~~~ + +For RPM packages, edit ``/etc/sysconfig/fess``; for DEB packages, edit ``/etc/default/fess``. + +:: + + FESS_PORT=8080 + +Configuration on Windows +~~~~~~~~~~~~~~~~~~~~~~~~~ + +On Windows, edit ``bin\fess.in.bat``. + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.port=8080 + +Registering as a Windows Service +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When using |Fess| as a Windows service, also modify the port settings in ``bin\service.bat``. +For details, see :doc:`setup-windows-service`. + +Context Path Configuration +--------------------------- + +To publish |Fess| under a subdirectory, you can configure the context path. + +Linux: + +:: + + export FESS_CONTEXT_PATH=/search + +On Windows, edit ``-Dfess.context.path`` directly in ``bin\fess.in.bat``. + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.context.path=/search + +This configuration makes |Fess| accessible at ``http://localhost:8080/search/``. + +.. warning:: + The ``FESS_CONTEXT_PATH`` environment variable is only available on Linux. On Windows, edit ``bin\fess.in.bat`` directly. + +.. warning:: + When changing the context path, you must also configure static file paths appropriately. + +Proxy Configuration +=================== + +Overview +-------- + +When crawling external sites from within an intranet or accessing external APIs, +communications may be blocked by a firewall. +In such environments, you need to configure communication via a proxy server. + +Crawler Proxy Configuration +---------------------------- + +Basic Configuration +~~~~~~~~~~~~~~~~~~~ + +In the crawl configuration settings on the administration screen, specify the following parameters: + +:: + + client.proxyHost=proxy.example.com + client.proxyPort=8080 + +Authenticated Proxy Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the proxy server requires authentication, add the following: + +:: + + client.proxyHost=proxy.example.com + client.proxyPort=8080 + client.proxyUsername=proxyuser + client.proxyPassword=proxypass + +Excluding Specific Hosts from Proxy +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The crawler proxy settings do not support nonProxyHosts. +To exclude specific hosts from the proxy, use the environment variable ``FESS_NON_PROXY_HOSTS``. +This setting is converted to the Java system property ``http.nonProxyHosts`` and applies to all HTTP communication in Fess. + +:: + + FESS_NON_PROXY_HOSTS=localhost|*.local|192.168.* + +Crawler Default Proxy Configuration +------------------------------------- + +To set a default proxy for when ``client.proxyHost`` is not specified in individual crawl configurations, configure it in ``fess_config.properties``. +This setting applies to the crawler default proxy as well as to LLM integration HTTP communication and plugin downloads. +However, it does not apply to communication by some Java libraries such as SSO authentication. +To apply a proxy to the entire Fess application (including SSO authentication), use the environment variables described later (``FESS_PROXY_HOST``, etc.). + +:: + + http.proxy.host=proxy.example.com + http.proxy.port=8080 + http.proxy.username=proxyuser + http.proxy.password=proxypass + +.. warning:: + Passwords are stored without encryption. Set appropriate file permissions. + +.. note:: + The ``http.proxy.*`` settings do not apply to SSO authentication, etc. To use a proxy for the entire Fess application including SSO authentication (JVM-wide HTTP communication), set the environment variables ``FESS_PROXY_HOST`` and ``FESS_PROXY_PORT``. See "Proxy Configuration via Environment Variables" below for details. + +Proxy Configuration via Environment Variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When Java libraries such as SSO authentication need to use a proxy, you must configure it via environment variables. +These environment variables are converted to Java system properties (``http.proxyHost``, ``https.proxyHost``, etc.). + +:: + + FESS_PROXY_HOST=proxy.example.com + FESS_PROXY_PORT=8080 + FESS_NON_PROXY_HOSTS=localhost|*.local|192.168.* + +For RPM packages, configure in ``/etc/sysconfig/fess``. For DEB packages, configure in ``/etc/default/fess``. + +.. note:: + The ``http.proxy.*`` settings in ``fess_config.properties`` are used for the crawler default proxy, as well as for LLM integration and plugin downloads. + To use a proxy for the entire Fess application including SSO authentication (JVM-wide HTTP communication), configure the environment variables above. + +HTTP Communication Settings +=========================== + +File Upload Limits +------------------ + +You can limit file upload sizes from the administration screen. + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - Configuration Item + - Description + * - ``http.fileupload.max.size`` + - Maximum file upload size (Default: 262144000 bytes = 250MB) + * - ``http.fileupload.threshold.size`` + - Threshold size to keep in memory (Default: 262144 bytes = 256KB) + * - ``http.fileupload.max.file.count`` + - Maximum number of files that can be uploaded at once (Default: 10) + +Configuration example in ``fess_config.properties``: + +:: + + http.fileupload.max.size=524288000 + http.fileupload.threshold.size=524288 + http.fileupload.max.file.count=20 + +OpenSearch Connection Settings +------------------------------ + +You can configure the OpenSearch connection URL and the health-check (heartbeat) interval. + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - Configuration Item + - Description + * - ``search_engine.http.url`` + - OpenSearch URL (Default: http://localhost:9200). The ``SEARCH_ENGINE_HTTP_URL`` environment variable takes precedence (see below). + * - ``search_engine.heartbeat_interval`` + - Health check interval in milliseconds (Default: 10000) + +Changing OpenSearch Connection +------------------------------- + +Set the URL to connect to with the ``SEARCH_ENGINE_HTTP_URL`` environment +variable. It takes precedence over ``search_engine.http.url`` in +``fess_config.properties``. The ZIP package's ``bin/fess.in.sh`` and the +RPM/DEB packages' environment file set this variable to +``http://localhost:9200`` by default, so changing ``search_engine.http.url`` +does not change where |Fess| connects. + +Where to set it depends on how |Fess| is installed: + +- ZIP package: edit the ``SEARCH_ENGINE_HTTP_URL`` line in + ``bin/fess.in.sh``, or export ``SEARCH_ENGINE_HTTP_URL`` in the + environment that starts |Fess| (see :doc:`../install/install-linux`). +- RPM/DEB package: ``SEARCH_ENGINE_HTTP_URL`` in ``/etc/sysconfig/fess`` + (RPM) or ``/etc/default/fess`` (DEB). +- Docker: the container environment variable ``SEARCH_ENGINE_HTTP_URL`` + (see :doc:`../install/install-docker`). +- ZIP package on Windows: the ``-Dfess.search_engine.http_address`` line in + ``bin\fess.in.bat`` (see :doc:`../install/install-windows`). + +:: + + SEARCH_ENGINE_HTTP_URL=http://opensearch-cluster.example.com:9200 + +Connecting to Multiple Nodes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To connect to multiple OpenSearch nodes, separate the URLs with commas. +If some of the nodes are down, |Fess| connects to the remaining ones. + +:: + + SEARCH_ENGINE_HTTP_URL=http://node1:9200,http://node2:9200,http://node3:9200 + +SSL/TLS Connection Configuration +--------------------------------- + +To connect to OpenSearch via HTTPS, specify an ``https://`` URL in the +same way as above: + +:: + + SEARCH_ENGINE_HTTP_URL=https://opensearch.example.com:9200 + +Set the CA certificate and the credentials in ``fess_config.properties``: + +:: + + search_engine.http.ssl.certificate_authorities=/path/to/ca.crt + search_engine.username=admin + search_engine.password=admin_password + +.. note:: + To verify certificates, specify the path to the CA certificate in ``certificate_authorities``. + +Virtual Host Configuration +========================== + +Overview +-------- + +|Fess| can provide different search results based on the hostname used to access it. +For details, see :doc:`security-virtual-host`. + +Basic Configuration +------------------- + +Configure virtual hosts from the admin UI "System > General" (``virtual.host.headers``). +Specify one virtual host per line in the format ``Host:hostname[:port]=virtualHostName``. +The default is empty (unset), and the virtual host feature is disabled. + +:: + + Host:search1.example.com=site1 + Host:search2.example.com=site2 + +.. note:: + The value of ``virtual.host.headers`` is NOT a list of header names such as ``X-Forwarded-Host,Host``. + Each line describes a mapping in the form ``HeaderName:HeaderValue=virtualHostName``. + For the detailed format and constraints, see :doc:`security-virtual-host`. + +Reverse Proxy Integration +========================== + +Nginx Configuration Example +---------------------------- + +:: + + server { + listen 80; + server_name search.example.com; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Host $host; + } + } + +Apache Configuration Example +----------------------------- + +:: + + + ServerName search.example.com + + ProxyPreserveHost On + ProxyPass / http://localhost:8080/ + ProxyPassReverse / http://localhost:8080/ + + RequestHeader set X-Forwarded-Proto "http" + RequestHeader set X-Forwarded-Host "search.example.com" + + +SSL/TLS Termination +------------------- + +Configuration example for SSL/TLS termination at the reverse proxy (Nginx): + +:: + + server { + listen 443 ssl http2; + server_name search.example.com; + + ssl_certificate /path/to/cert.pem; + ssl_certificate_key /path/to/key.pem; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto https; + proxy_set_header X-Forwarded-Host $host; + } + } + +Firewall Configuration +====================== + +Opening Required Ports +----------------------- + +To make |Fess| accessible from external networks, open the following ports: + +**iptables configuration example:** + +:: + + # Fess web application + iptables -A INPUT -p tcp --dport 8080 -j ACCEPT + + # For HTTPS access (via reverse proxy) + iptables -A INPUT -p tcp --dport 443 -j ACCEPT + +**firewalld configuration example:** + +:: + + # Fess web application + firewall-cmd --permanent --add-port=8080/tcp + firewall-cmd --reload + +Security Group Configuration (Cloud Environments) +-------------------------------------------------- + +In cloud environments such as AWS, GCP, and Azure, open the appropriate ports +using security groups or network ACLs. + +Recommended settings: +- Inbound: Ports 80/443 (via HTTP reverse proxy) +- Restrict port 8080 to internal access only +- Restrict OpenSearch ports 9200/9300 to internal access only + +Troubleshooting +=============== + +Cannot Access After Changing Port +---------------------------------- + +1. Verify that |Fess| has been restarted. +2. Confirm that the port is open in the firewall. +3. Check for errors in the log file (``fess.log``). + +Cannot Crawl via Proxy +----------------------- + +1. Verify that the proxy server hostname and port are correct. +2. If the proxy server requires authentication, configure the username and password. +3. Check the proxy server logs to see if connection attempts are recorded. +4. Verify that the ``nonProxyHosts`` setting is appropriate. + +Cannot Connect to OpenSearch +----------------------------- + +1. Verify that OpenSearch is running. +2. Confirm that the ``search_engine.http.url`` setting is correct. +3. Verify network connectivity: ``curl http://localhost:9200`` +4. Check OpenSearch logs for errors. + +Not Working Properly When Accessed via Reverse Proxy +----------------------------------------------------- + +1. Verify that the ``X-Forwarded-Host`` header is configured correctly. +2. Verify that the ``X-Forwarded-Proto`` header is configured correctly. +3. Verify that the context path is configured correctly. +4. Check reverse proxy logs for errors. + +References +========== + +- :doc:`setup-memory` - Memory Configuration +- :doc:`setup-windows-service` - Windows Service Configuration +- :doc:`security-virtual-host` - Virtual Host Configuration +- :doc:`crawler-advanced` - Advanced Crawler Configuration +- `OpenSearch Configuration `_ diff --git a/en/15.10/config/setup-windows-service.rst b/en/15.10/config/setup-windows-service.rst new file mode 100644 index 000000000..3620f46ad --- /dev/null +++ b/en/15.10/config/setup-windows-service.rst @@ -0,0 +1,134 @@ +============================= +Windows Service Registration +============================= + +Registering as a Windows Service +================================== + +|Fess| can be registered as a Windows service. Registering as a service allows |Fess| to start automatically when the system boots. +To run |Fess|, OpenSearch must be started first. +This guide assumes |Fess| is installed in ``c:\opt\fess`` and OpenSearch in ``c:\opt\opensearch`` (adjust the paths to match your environment). + +.. note:: + |Fess| and OpenSearch support 64-bit editions only. + +Prerequisites +------------- + +Set ``JAVA_HOME`` as a system environment variable. ``service.bat`` will exit with an error if ``JAVA_HOME`` is not set. + +Registering OpenSearch as a Service +------------------------------------ + +Open a command prompt with administrator privileges and run ``c:\opt\opensearch\bin\opensearch-service.bat``. + +:: + + > cd c:\opt\opensearch\bin + > opensearch-service.bat install + ... + The service 'opensearch-service-x64' has been installed. + +For details, refer to the `OpenSearch documentation `_. + +|Fess| Configuration +--------------------- + +The service is registered via ``c:\opt\fess\bin\service.bat``. When registering, ``service.bat`` reads ``bin\fess.in.bat`` and applies its contents to the |Fess| startup options. +Add the settings required to connect to OpenSearch to ``c:\opt\fess\bin\fess.in.bat``. + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200 + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=c:/opt/opensearch/config/dictionary/ + +.. note:: + - ``fess.search_engine.http_address`` specifies the connection target for the registered OpenSearch service. If this setting is omitted, |Fess| cannot locate the connection target and does not start; it reports that no search engine address is configured. + - If OpenSearch is running on a different host, change the hostname or IP address accordingly. + - Use ``/`` as the path separator. + +The default port number for the |Fess| search and administration screens is ``8080``. To change it to a different port, edit ``-Dfess.port`` in ``c:\opt\fess\bin\fess.in.bat``. + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.port=80 + +.. note:: + When registering as a service, ``-Dfess.port=8080`` is also hardcoded in ``FESS_PARAMS`` inside ``bin\service.bat``. Because this value takes precedence over the settings in ``fess.in.bat``, also edit ``FESS_PARAMS`` in ``service.bat`` when changing the port. + +Service Customization (Optional) +--------------------------------- + +You can change the service configuration by setting environment variables before running ``service.bat install``. The main environment variables are listed below. + +.. list-table:: + :header-rows: 1 + + * - Environment Variable + - Description + * - ``FESS_START_TYPE`` + - Startup type (``auto`` or ``manual``). Default is ``manual``. + * - ``FESS_HEAP_SIZE`` + - Heap size (e.g. ``1g``). To specify minimum and maximum heap sizes individually, use ``FESS_MIN_MEM`` (default ``256m``) and ``FESS_MAX_MEM`` (default ``1g``). + * - ``SERVICE_USERNAME`` / ``SERVICE_PASSWORD`` + - Windows account under which the service runs. + * - ``SERVICE_DISPLAY_NAME`` + - Display name of the service. + * - ``SERVICE_DESCRIPTION`` + - Description of the service. + +Registration Procedure +---------------------- + +From a command prompt with administrator privileges, run ``c:\opt\fess\bin\service.bat``. + +:: + + > cd c:\opt\fess\bin + > service.bat install + ... + The service 'fess-service-x64' has been installed. + +Service Configuration +--------------------- + +If starting the service manually, start the OpenSearch service first and then start the |Fess| service. +To start automatically at system boot, configure the startup type and service dependencies. + +1. In the service General settings, set the Startup type to "Automatic (Delayed Start)". +2. Configure service dependencies in the registry. + +Add the following key and value in the Registry Editor (regedit). + +.. list-table:: + + * - *Key* + - ``Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\fess-service-x64\DependOnService`` + * - *Value* + - ``opensearch-service-x64`` + +Once added, opensearch-service-x64 will appear in the Dependencies tab of the |Fess| service properties. + +.. note:: + Setting the environment variable ``FESS_START_TYPE=auto`` before running ``service.bat install`` registers the service with a startup type of "Automatic". However, "Automatic (Delayed Start)" and dependency configuration cannot be performed through ``service.bat``, so use the procedure described above for those settings. + +Service Management +------------------ + +The following commands are available in ``service.bat`` to manage the service. + +.. list-table:: + :header-rows: 1 + + * - Command + - Description + * - ``service.bat install`` + - Registers the service. + * - ``service.bat remove`` + - Removes the service. + * - ``service.bat start`` + - Starts the service. + * - ``service.bat stop`` + - Stops the service. + * - ``service.bat manager`` + - Launches the GUI for managing the service. diff --git a/en/15.10/config/sso-entraid.rst b/en/15.10/config/sso-entraid.rst new file mode 100644 index 000000000..b90d623e2 --- /dev/null +++ b/en/15.10/config/sso-entraid.rst @@ -0,0 +1,423 @@ +=================================== +SSO Configuration with Entra ID +=================================== + +Overview +======== + +|Fess| supports Single Sign-On (SSO) authentication using Microsoft Entra ID (formerly Azure AD). +By using Entra ID authentication, you can integrate user information and group information from your Microsoft 365 environment with |Fess| role-based search. + +.. note:: + Entra ID authentication comes from the ``fess-sso-entraid`` plugin, which is not part of the + distribution. Install it from the System > Plugin page in the administration screen, or with + ``bin/fess-setup install plugin fess-sso-entraid``. + Until it is installed, ``sso.type=entraid`` (or the legacy ``aad``) only redirects every + request to ``/sso/`` back to the login page. + +How Entra ID Authentication Works +--------------------------------- + +In Entra ID authentication, |Fess| operates as an OAuth 2.0/OpenID Connect client and collaborates with Microsoft Entra ID for authentication. + +1. User accesses the |Fess| SSO endpoint (``/sso/``) +2. |Fess| redirects to the Entra ID authorization endpoint +3. User authenticates with Entra ID (Microsoft sign-in) +4. Entra ID redirects the authorization code to |Fess| +5. |Fess| uses the authorization code to obtain an access token +6. User is logged in +7. In the background, |Fess| uses the Microsoft Graph API to retrieve the user's group and role information and applies it to role-based search once resolution completes + +.. note:: + From |Fess| 15.10, the authorization response in step 4 is returned as a GET request, because + |Fess| asks the authorization endpoint for ``response_mode=query``. Up to 15.7 it was returned + as a cross-site POST, and the shipped default ``tomcat.sameSiteCookies = lax`` does not send the + session cookie on such a request, so ``tomcat.sameSiteCookies = none`` was required as a + workaround. If you set ``none`` only for that reason, you can restore the default. + +For role-based search integration, see :doc:`security-role`. + +Prerequisites +============= + +Before configuring Entra ID authentication, verify the following prerequisites: + +- |Fess| 15.10 or later is installed +- A Microsoft Entra ID (Azure AD) tenant is available +- |Fess| is accessible via HTTPS (required for production environments) +- You have permission to register applications in Entra ID + +Basic Configuration +=================== + +Enabling SSO +------------ + +To enable Entra ID authentication, add the following setting in ``app/WEB-INF/conf/system.properties``: + +:: + + sso.type=entraid + +Required Settings +----------------- + +Configure the information obtained from Entra ID. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Property + - Description + - Default + * - ``entraid.tenant`` + - Tenant ID (e.g., ``xxx.onmicrosoft.com``) + - (Required) + * - ``entraid.client.id`` + - Application (Client) ID + - (Required) + * - ``entraid.client.secret`` + - Client secret value + - (Required) + * - ``entraid.reply.url`` + - Redirect URI (Callback URL) + - Uses request URL + +.. note:: + Instead of the ``entraid.*`` prefix, you can also use the legacy ``aad.*`` prefix for backward compatibility. + +Optional Settings +----------------- + +The following settings can be added as needed. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Property + - Description + - Default + * - ``entraid.authority`` + - Authentication server URL + - ``https://login.microsoftonline.com/`` + * - ``entraid.state.ttl`` + - State time-to-live (seconds) + - ``3600`` + * - ``entraid.response.mode`` + - How the authorization response is returned. Either ``query`` or ``form_post``. + - ``query`` + * - ``entraid.default.groups`` + - Default groups (comma-separated). Applied to every Entra ID user. + - (None) + * - ``entraid.default.roles`` + - Default roles (comma-separated). Applied to every Entra ID user. + - (None) + * - ``entraid.permission.fields`` + - Group/role fields (comma-separated) to additionally use as permission values. The group/role ID (GUID) is always used as a permission, and the values of the fields specified here (e.g., ``mail``) are added. Only a field whose value is a string can be used. Microsoft Graph answers a field such as ``securityEnabled`` with a boolean and ``groupTypes`` with a list, and neither can become a permission value, so such a field is ignored and a warning naming it is written to the log. + - ``mail`` + * - ``entraid.use.ds`` + - Domain service integration. When ``true``, for permission values in the ``name@domain`` format, the local part (``name``) with the domain part removed is also added as a permission. This applies to the signed-in user as well as to groups and roles: the local part of the user principal name is added as a user-level permission. Setting it to ``false`` therefore removes that user-level permission too, not only the group ones. + - ``true`` + +.. note:: + + The group/role ID (GUID) is always used as a permission, but only mail-enabled groups have a + ``mail`` value. Microsoft 365 groups are mail-enabled, so their name is registered as a + permission as well. **Security groups are not mail-enabled, so with the default only their GUID + becomes a permission.** If file system access rights name a security group, the permissions do + not match and those documents do not appear in search results. + + In that case, add ``displayName``, which every group has: + + .. code-block:: properties + + entraid.permission.fields=mail,displayName + + ``displayName`` is not domain-qualified and is not unique, which is why it is not in the + default. For example, if Entra ID has a group named ``Administrators``, it also matches + documents whose access rights name the built-in Windows ``Administrators`` group. Before adding + it, check that the names do not collide with the ones already used in your access rights. + +.. note:: + With the default ``query``, the authorization code is included in the query string of the + callback URL. ``form_post`` keeps the code out of the URL, and therefore out of browser history + and the access logs of any front-end proxy or WAF, but it makes the callback a cross-site POST + and requires ``tomcat.sameSiteCookies = none``. Without that setting the session cookie is not + sent back and login fails. Browsers also only accept ``none`` on a cookie that carries the + ``Secure`` attribute, so ``form_post`` additionally requires |Fess| to be served over HTTPS: + over plain HTTP the browser does not store the session cookie at all and login still fails. + Most deployments should therefore keep the default. Any other value is ignored with a warning + and ``query`` is used. + +.. warning:: + + ``entraid.default.groups`` and ``entraid.default.roles`` are single global values with no + per-user scoping. |Fess| applies them to every Entra ID user at login and applies them again on + every later resolution, so Microsoft Graph never takes them away. In particular, never put the + |Fess| administrator role — ``admin`` with the shipped ``authentication.admin.roles`` — in + ``entraid.default.roles``: that grants every user in the tenant permanent access to the + administration screens. + +Entra ID Side Configuration +=========================== + +App Registration in Azure Portal +-------------------------------- + +1. Sign in to `Azure Portal `_ + +2. Select **Microsoft Entra ID** + +3. Go to **Manage** → **App registrations** → **New registration** + +4. Register the application: + + .. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Setting + - Value + * - Name + - Any name (e.g., Fess SSO) + * - Supported account types + - "Accounts in this organizational directory only" + * - Platform + - Web + * - Redirect URI + - ``https:///sso/`` + +5. Click **Register** + +Creating a Client Secret +------------------------ + +1. On the app details page, click **Certificates & secrets** + +2. Click **New client secret** + +3. Set a description and expiration, then click **Add** + +4. Copy and save the generated **Value** (this value will not be shown again) + +.. warning:: + The client secret value is only displayed immediately after creation. + Be sure to record it before navigating away from the page. + +Configuring API Permissions +--------------------------- + +1. Click **API permissions** in the left menu + +2. Click **Add a permission** + +3. Select **Microsoft Graph** + +4. Select **Delegated permissions** + +5. Add the following permission: + + - ``User.Read`` - Required to retrieve the signed-in user's group memberships (``/me/memberOf``). Granted by default when the app registration is created + - ``GroupMember.Read.All`` - Required to read group attributes such as the group name, and to resolve nested groups + +6. Click **Add permissions** + +7. Click **Grant admin consent for ** + +.. note:: + Admin consent requires tenant administrator privileges. + +.. note:: + ``Group.Read.All`` or ``Directory.Read.All`` can be granted instead of + ``GroupMember.Read.All``, and the group attribute lookup and the nested group resolution still + work. However, ``/me/memberOf`` is not authorized by ``Group.Read.All``, so ``User.Read`` is + required in either case. + +.. note:: + The permissions above do not cover the ``displayName`` of a directory role: Microsoft Graph + returns it as null. Naming ``displayName`` in ``entraid.permission.fields`` therefore adds + nothing for a directory role, and only the role's ID (GUID) becomes a permission. To use role + names as permission values, also grant ``RoleManagement.Read.Directory`` (or + ``Directory.Read.All``). + +.. note:: + |Fess| requests the ``https://graph.microsoft.com/.default`` scope when acquiring a token, and from 15.10 it also sends ``openid profile offline_access https://graph.microsoft.com/.default`` to the authorization endpoint so that consent is requested for the same set. This means that all access permissions configured and consented to on the app registration are used. Therefore, to retrieve group information, you must add the permissions above to the app registration and grant administrator consent. + +Information to Obtain +--------------------- + +The following information is used for Fess configuration: + +- **Application (Client) ID**: Found on the Overview page as "Application (client) ID" +- **Tenant ID**: Found on the Overview page as "Directory (tenant) ID" or in ``xxx.onmicrosoft.com`` format +- **Client secret value**: The value created in Certificates & secrets + +Group and Role Mapping +====================== + +With Entra ID authentication, |Fess| automatically retrieves the groups and roles that a user belongs to using the Microsoft Graph API. +The retrieved group IDs and group names can be used for |Fess| role-based search. + +Nested Groups +------------- + +|Fess| retrieves not only groups that users directly belong to, but also the parent groups those belong to (nested groups). +Both the direct membership lookup and the parent group lookup run in the same background task after login, so login itself is never slowed down by Microsoft Graph. +The parent group lookup uses the Microsoft Graph ``getMemberGroups`` operation, which resolves transitively: one call per directly assigned group returns every group above it, however deep the nesting goes. The retrieved results are cached for a certain period. +When that background task completes, the user's permissions are recalculated. + +Default Group Settings +---------------------- + +To assign common groups to all Entra ID users: + +:: + + entraid.default.groups=authenticated_users,entra_users + +Configuration Examples +====================== + +Minimal Configuration (for Testing) +----------------------------------- + +The following is a minimal configuration example for verification in a test environment. + +:: + + # Enable SSO + sso.type=entraid + + # Entra ID settings + entraid.tenant=yourcompany.onmicrosoft.com + entraid.client.id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + entraid.client.secret=your-client-secret-value + entraid.reply.url=http://localhost:8080/sso/ + +Recommended Configuration (for Production) +------------------------------------------ + +The following is a recommended configuration example for production environments. + +:: + + # Enable SSO + sso.type=entraid + + # Entra ID settings + entraid.tenant=yourcompany.onmicrosoft.com + entraid.client.id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + entraid.client.secret=your-client-secret-value + entraid.reply.url=https://fess.example.com/sso/ + + # Default groups (optional) + entraid.default.groups=authenticated_users + +Legacy Configuration (Backward Compatibility) +--------------------------------------------- + +For compatibility with previous versions, the ``aad.*`` prefix can also be used. +When each ``entraid.*`` property is not set, the value of the corresponding ``aad.*`` property is used. +In addition, ``sso.type=aad`` is treated the same as ``sso.type=entraid``. + +:: + + # Enable SSO (sso.type=aad can also be used) + sso.type=entraid + + # Legacy configuration keys + aad.tenant=yourcompany.onmicrosoft.com + aad.client.id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + aad.client.secret=your-client-secret-value + aad.reply.url=https://fess.example.com/sso/ + +Troubleshooting +=============== + +Common Issues and Solutions +--------------------------- + +Cannot Return to Fess After Authentication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verify that the Redirect URI is correctly configured in the Azure Portal app registration +- Ensure the ``entraid.reply.url`` value exactly matches the Azure Portal configuration +- Check that the protocol (HTTP/HTTPS) matches +- Verify the Redirect URI ends with ``/`` +- If ``entraid.response.mode`` is set to ``form_post``, check both that + ``tomcat.sameSiteCookies = none`` is configured and that |Fess| is served over HTTPS. With the + shipped default ``lax`` the browser does not send the session cookie on the callback's + cross-site POST; with ``none`` over plain HTTP the browser does not store that cookie at all, + because ``none`` requires the ``Secure`` attribute. Either way the login fails once, on the + spot: the browser returns to the login page showing "SSO login process failed.", and a warning + reading ``Failed to process SSO login: could not validate state`` is written to the log + +Authentication Errors Occur +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verify that the Tenant ID, Client ID, and Client Secret are correctly configured +- Check that the client secret has not expired +- Verify that admin consent has been granted for API permissions + +Cannot Retrieve Group Information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verify that the ``User.Read`` and ``GroupMember.Read.All`` permissions have been granted + (``Group.Read.All`` or ``Directory.Read.All`` can replace ``GroupMember.Read.All``, but + ``/me/memberOf`` still requires ``User.Read``) +- Verify that admin consent has been granted +- Check that the user belongs to groups in Entra ID +- If nested parent groups cannot be resolved, ``Not allowed to read the parent groups of ...`` is + logged as a warning. Grant ``GroupMember.Read.All`` in that case +- |Fess| resolves the user's group and role membership in the background after login completes, + so login itself never waits on Microsoft Graph. Until resolution finishes, the user holds only + their own user-level permission and whatever ``entraid.default.groups`` and + ``entraid.default.roles`` provide. With neither of those set, which is the shipped default, a + search made in that window returns no documents at all: ``role.search.default.permissions`` is + empty out of the box, and a crawling configuration created with the shipped + ``role.search.default.display.permissions`` grants ``{role}guest``, which a logged-in user does + not hold. The window is up to about a second of scheduling delay plus the Microsoft Graph calls + themselves — one for the direct memberships, then one more for each of those groups to walk the + nested groups, issued one after another on a cold cache — so it grows with the number of groups + the user belongs to. While it lasts, the search screen tells the user that their group and role + permissions are still loading and asks them to search again in a moment +- If resolution does not fully succeed, the search screen tells the user that their group and role + permissions could not be fully loaded, asks them to log out and log in again, and to contact an + administrator if it keeps happening. "Not fully" is deliberate: the resolution counts as failed + unless both the direct membership lookup and the nested group walk succeeded, so a user who + holds their direct groups but not their parent groups gets that message too. One case is + exempt, and it is the one the previous item describes: when Microsoft Graph refuses the nested + group lookup with ``Authorization_RequestDenied`` because ``GroupMember.Read.All`` was never + granted, |Fess| takes that as an answer meaning the group has no parents rather than as a + failure. Resolution then counts as successful and **no message is shown**, even though the + parent group permissions are missing. The only sign is the + ``Not allowed to read the parent groups of ...`` warning in the log, so check for it whenever + nested groups are in use. Throttling is the usual cause of the partial case — a single HTTP 429 + or 503 from Microsoft Graph makes |Fess| back + off for as long as the ``Retry-After`` header asks (60 seconds when it says nothing usable, 60 + minutes at most), and every nested group lookup in the whole |Fess| instance is skipped for that + time while the direct lookups keep answering. The + failure is not necessarily final: resolution is retried whenever the access token is renewed, + and a later success clears the message and restores the missing permissions. Logging out and + logging in again retries it straight away — opening the SSO login URL while still logged in only + redirects back to the search screen + +Debug Settings +-------------- + +To investigate issues, you can output detailed Entra ID-related logs by adjusting the |Fess| log level. + +In ``app/WEB-INF/classes/log4j2.xml``, you can add the following logger to change the log level: + +:: + + + +Reference +========= + +- :doc:`security-role` - Role-based search configuration +- :doc:`sso-saml` - SSO configuration with SAML authentication +- :doc:`sso-oidc` - SSO configuration with OpenID Connect authentication diff --git a/en/15.10/config/sso-oidc.rst b/en/15.10/config/sso-oidc.rst new file mode 100644 index 000000000..4455f8ad9 --- /dev/null +++ b/en/15.10/config/sso-oidc.rst @@ -0,0 +1,329 @@ +===================================== +SSO Configuration with OpenID Connect +===================================== + +Overview +======== + +|Fess| supports Single Sign-On (SSO) authentication using OpenID Connect (OIDC). +OpenID Connect is an authentication protocol built on top of OAuth 2.0 that uses ID Tokens (JWT) for user authentication. +By using OpenID Connect authentication, user information authenticated by an OpenID Provider (OP) can be integrated with |Fess|. + +.. note:: + OpenID Connect authentication comes from the ``fess-sso-oidc`` plugin, which is not part of + the distribution. Install it from the System > Plugin page in the administration screen, or + with ``bin/fess-setup install plugin fess-sso-oidc``. The plugin is named ``fess-sso-oidc`` + while the ``sso.type`` value stays ``oic``. + Until it is installed, ``sso.type=oic`` only redirects every request to ``/sso/`` back to the + login page. + +How OpenID Connect Authentication Works +--------------------------------------- + +In OpenID Connect authentication, |Fess| operates as a Relying Party (RP) and collaborates with an external OpenID Provider (OP) for authentication. + +1. User accesses the |Fess| SSO endpoint (``/sso/``) +2. |Fess| redirects to the OP's authorization endpoint +3. User authenticates at the OP +4. OP redirects the authorization code to |Fess| +5. |Fess| uses the authorization code to obtain an ID Token from the token endpoint +6. |Fess| decodes the ID Token (JWT), checks its claims, extracts user information and logs in the user + +.. note:: + |Fess| uses the Authorization Code Flow. The ID Token is obtained directly from the token endpoint via a back-channel (server-to-server communication) between |Fess| and the OP, without passing through the browser. + |Fess| decodes the ID Token and extracts claims (such as ``email`` and ``groups``) to construct user information, but does NOT cryptographically verify the JWT signature. OpenID Connect Core allows this because the token is received directly from the token endpoint over TLS, so the token endpoint URL (``oic.token.server.url``) must be HTTPS. ``http`` is accepted only for ``localhost``, ``127.x.x.x`` and ``::1``. + |Fess| does check the claims: ``aud`` must contain ``oic.client.id`` (and ``azp``, when present, must equal it), ``exp`` must be present and not past (a clock difference of up to 300 seconds is tolerated), and ``iss`` must equal ``oic.issuer`` when that key is set. Without ``oic.issuer``, ``iss`` is not checked, and a warning is logged at the first login after each start. ``nonce`` and PKCE are not used. + +For integration with role-based search, see :doc:`security-role`. + +Prerequisites +============= + +Before configuring OpenID Connect authentication, verify the following prerequisites: + +- |Fess| 15.10 or later is installed +- An OpenID Connect-compatible provider (OP) is available +- |Fess| is accessible via HTTPS (required for production environments) +- You have permission to register |Fess| as a client (RP) on the OP side + +Examples of supported providers: + +- Microsoft Entra ID (Azure AD) +- Google Workspace / Google Cloud Identity +- Okta +- Keycloak +- Auth0 +- Other OpenID Connect-compatible providers + +Basic Configuration +=================== + +Enabling SSO +------------ + +To enable OpenID Connect authentication, add the following setting to ``app/WEB-INF/conf/system.properties``: + +:: + + sso.type=oic + +.. note:: + The ``sso.type`` setting and the ``oic.*`` settings described below, except ``oic.issuer``, can also be configured and changed from the admin "System > General" page. + Settings changed through the admin page are saved to ``system.properties`` and persist after restart. + ``oic.issuer`` can only be set in ``system.properties``. + +Provider Configuration +---------------------- + +Configure the information obtained from your OP. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Property + - Description + - Default + * - ``oic.auth.server.url`` + - Authorization endpoint URL + - ``https://accounts.google.com/o/oauth2/auth`` + * - ``oic.token.server.url`` + - Token endpoint URL + - ``https://accounts.google.com/o/oauth2/token`` + * - ``oic.issuer`` + - Issuer identifier (optional). When set, the ``iss`` claim of the ID Token must equal it exactly (a trailing slash counts) + - (empty: ``iss`` is not checked) + +.. note:: + These URLs and the issuer can be obtained from the OP's Discovery endpoint (``/.well-known/openid-configuration``); the issuer is its ``issuer`` value. + The token endpoint URL (``oic.token.server.url``) must be HTTPS. ``http`` is accepted only when the host is ``localhost`` (any case), an IPv4 address of the form ``127.x.x.x``, or ``::1``. The host is compared as written and is never resolved, so a Docker Compose service name (such as ``http://keycloak:8080/...``) or an internal host name is refused over ``http`` even if it points to the same machine. + + Only the token endpoint is checked, not the authorization endpoint (``oic.auth.server.url``). The check runs at login, not at startup. Setting ``oic.issuer`` does not relax this rule; it only turns on the check of the ``iss`` claim. + +Client Configuration +-------------------- + +Configure the client information registered with the OP. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Property + - Description + - Default + * - ``oic.client.id`` + - Client ID + - (empty) + * - ``oic.client.secret`` + - Client secret + - (empty) + * - ``oic.scope`` + - Requested scopes + - (empty) + +.. note:: + The scope must include at least ``openid``. + To retrieve the user's email address, specify ``openid email``. + +Redirect URL Configuration +-------------------------- + +Configure the callback URL after authentication. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Property + - Description + - Default + * - ``oic.redirect.url`` + - Redirect URL (callback URL) + - ``{oic.base.url}/sso/`` + * - ``oic.base.url`` + - |Fess| base URL + - ``http://localhost:8080`` + +.. note:: + If ``oic.redirect.url`` is omitted, it is automatically constructed from ``oic.base.url``. + For production environments, set ``oic.base.url`` to an HTTPS URL. + +User Attribute Configuration +----------------------------- + +Configure the default groups and roles to assign to users authenticated via OIDC. +The user ID, groups, and roles are determined as follows: + +- **User ID**: Obtained from the ``email`` claim of the ID Token (JWT). For this reason, the ``email`` scope is effectively required (if the ``email`` claim cannot be obtained, login will not work correctly). +- **Groups**: Obtained from the ``groups`` claim of the ID Token. If the ``groups`` claim is not present, the value of ``oic.default.groups`` is used. An empty ``groups`` array counts as present, so ``oic.default.groups`` is not used and the user is treated as having no groups. +- **Roles**: Always taken from the value of ``oic.default.roles`` (there is no mechanism to obtain roles from ID Token claims). + +.. note:: + |Fess| uses the values of the ``groups`` claim as they are; it performs no directory lookup and + does not expand nested (transitive) groups. Whether parent groups appear is therefore decided + entirely by the OP's claim configuration -- unlike :doc:`sso-entraid`, where |Fess| resolves + parent groups through the Microsoft Graph API. + The claim value becomes the search permission verbatim. A provider configured to emit full group + paths therefore sends values such as ``/parent/child``, and those do not match documents tagged + with the plain group name. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Property + - Description + - Default + * - ``oic.default.groups`` + - Default groups (comma-separated) + - (empty) + * - ``oic.default.roles`` + - Default roles (comma-separated) + - (empty) + +.. note:: + When using role-based search, you must assign appropriate groups or roles to users. + See :doc:`security-role` for details. + +OP-Side Configuration +===================== + +When registering |Fess| as a client (RP) on the OP side, configure the following information: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Setting + - Value + * - Application type + - Web application + * - Redirect URI / Callback URL + - ``https:///sso/`` + * - Allowed scopes + - ``openid`` and required scopes (``email``, ``profile``, etc.) + +Information to Obtain from OP +------------------------------ + +Obtain the following information from the OP's configuration screen or Discovery endpoint for use in |Fess| configuration: + +- **Authorization Endpoint**: URL to initiate user authentication +- **Token Endpoint**: URL to obtain tokens +- **Issuer** (optional): ``issuer`` value of the Discovery document, used for ``oic.issuer`` +- **Client ID**: Client identifier issued by the OP +- **Client Secret**: Secret key used for client authentication + +.. note:: + Most OPs allow you to check the authorization and token endpoint URLs from the + Discovery endpoint (``https:///.well-known/openid-configuration``). + +Configuration Examples +====================== + +Minimal Configuration (for Testing) +------------------------------------- + +The following is a minimal configuration example for verification in a test environment. + +:: + + # Enable SSO + sso.type=oic + + # Provider configuration (set values obtained from OP) + oic.auth.server.url=https://op.example.com/authorize + oic.token.server.url=https://op.example.com/token + + # Client configuration + oic.client.id=your-client-id + oic.client.secret=your-client-secret + oic.scope=openid email + + # Redirect URL (test environment) + oic.redirect.url=http://localhost:8080/sso/ + +Recommended Configuration (for Production) +------------------------------------------- + +The following is a recommended configuration example for production environments. + +:: + + # Enable SSO + sso.type=oic + + # Provider configuration + oic.auth.server.url=https://op.example.com/authorize + oic.token.server.url=https://op.example.com/token + + # Issuer (the "issuer" value of the Discovery document) + oic.issuer=https://op.example.com + + # Client configuration + oic.client.id=your-client-id + oic.client.secret=your-client-secret + oic.scope=openid email profile + + # Base URL (use HTTPS for production) + oic.base.url=https://fess.example.com + +Troubleshooting +=============== + +Common Problems and Solutions +------------------------------ + +Cannot Return to Fess After Authentication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verify that the redirect URI is correctly configured on the OP side +- Ensure that the ``oic.redirect.url`` or ``oic.base.url`` value matches the OP configuration +- Verify that the protocol (HTTP/HTTPS) matches + +Authentication Errors Occur +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verify that the client ID and client secret are correctly configured +- Ensure that the scope includes ``openid`` +- Verify that the authorization endpoint URL and token endpoint URL are correct +- If login fails, ``fess.log`` contains a warning ``Failed to process the OpenID Connect callback:`` followed by the reason +- ``The ID token was not issued for this client``: ``aud`` of the ID Token is not ``oic.client.id``; check the client ID +- ``The ID token has expired``: the clocks of the |Fess| host and the OP differ by more than 300 seconds; synchronize the time (NTP) +- ``The ID token was not issued by the configured issuer``: ``oic.issuer`` differs from the ``iss`` shown in the message; copy the ``issuer`` value of the Discovery document exactly +- ``oic.token.server.url must be https``: use an HTTPS token endpoint URL (``http`` works only for ``localhost``, ``127.x.x.x`` and ``::1``; ``http`` to a Docker Compose service name or an internal host name is refused too) + +Cannot Retrieve User Information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Ensure that the scope includes the required permissions (``email``, ``profile``, etc.) +- Verify that the required scopes are allowed for the client on the OP side +- With Microsoft Entra ID, the ``groups`` claim carries group ``ObjectId`` GUIDs unless a different + source attribute is selected, so the values will not match group names +- Microsoft Entra ID omits the ``groups`` claim entirely when the user belongs to more than 200 + groups (nested groups count toward this limit), and |Fess| then falls back to + ``oic.default.groups`` + +Debug Configuration +-------------------- + +To investigate problems, you can output detailed OpenID Connect-related logs by adjusting the |Fess| log level. + +In ``app/WEB-INF/classes/log4j2.xml``, add the following logger to change the log level: + +:: + + + +.. warning:: + With this logger at DEBUG, the claims of the ID Token (such as ``email`` and ``groups``) are + written to the log file. Restore the log level once the investigation is over, and handle the + log output accordingly. + +Reference +========= + +- :doc:`security-role` - Role-based search configuration +- :doc:`sso-saml` - SSO configuration with SAML authentication +- :doc:`sso-entraid` - SSO configuration for Microsoft Entra ID (if you are using Entra ID, you may use this dedicated configuration instead of the generic OpenID Connect settings) diff --git a/en/15.10/config/sso-saml.rst b/en/15.10/config/sso-saml.rst new file mode 100644 index 000000000..78bd4f8d9 --- /dev/null +++ b/en/15.10/config/sso-saml.rst @@ -0,0 +1,644 @@ +============================= +SAML Authentication SSO Setup +============================= + +Overview +======== + +|Fess| supports Single Sign-On (SSO) authentication using SAML (Security Assertion Markup Language) 2.0. +By using SAML authentication, user information authenticated by an IdP (Identity Provider) can be integrated with |Fess|, enabling role-based search results based on user permissions when combined with role-based search. + +.. note:: + SAML authentication comes from the ``fess-sso-saml`` plugin, which is not part of the + distribution. Install it from the System > Plugin page in the administration screen, or with + ``bin/fess-setup install plugin fess-sso-saml``. + Until it is installed, ``sso.type=saml`` only redirects every request to ``/sso/`` back to + the login page. + +How SAML Authentication Works +----------------------------- + +In SAML authentication, |Fess| operates as an SP (Service Provider) and collaborates with an external IdP for authentication. + +1. User accesses the |Fess| SSO endpoint (``/sso/``) +2. |Fess| redirects the authentication request to the IdP +3. User authenticates at the IdP +4. IdP sends SAML assertion to |Fess| +5. |Fess| validates the assertion and logs in the user + +.. note:: + Only SP-initiated login, which starts at the |Fess| SSO endpoint (``/sso/``) as shown above, is supported. + |Fess| binds every SAML response to the ID of the AuthnRequest it sent, so an IdP-initiated + (unsolicited) response, for example from a |Fess| tile on an Okta dashboard or in the Microsoft + Entra ID "My Apps" portal, has no AuthnRequest to match against and is rejected. + If you place a tile on the IdP side, point it at the |Fess| ``/sso/`` endpoint. + + Note that in 15.7 an IdP-initiated login happened to work when ``tomcat.sameSiteCookies=none`` + was set: |Fess| bounced the unmatched response back to the IdP, and the IdP immediately returned + a solicited assertion. 15.10 no longer bounces the response, so IdP-initiated login does not work. + +For role-based search integration, see :doc:`security-role`. + +Prerequisites +============= + +Before configuring SAML authentication, verify the following prerequisites: + +- |Fess| 15.10 or later is installed +- A SAML 2.0 compatible IdP (Identity Provider) is available +- |Fess| is accessible via HTTPS (required for production environments) +- You have permission to register |Fess| as an SP on the IdP side + +Supported IdP examples: + +- Microsoft Entra ID (Azure AD) +- Okta +- Google Workspace +- Keycloak +- OneLogin +- Other SAML 2.0 compatible IdPs + +Basic Configuration +=================== + +Enabling SSO +------------ + +To enable SAML authentication, add the following setting to ``app/WEB-INF/conf/system.properties``: + +:: + + sso.type=saml + +.. note:: + ``sso.type`` and the basic SAML settings (IdP info, SP info, user attribute mapping) can also be configured from the admin "System > General" page. + Settings changed in the admin UI are saved to ``system.properties`` and persist after restart. + However, security settings such as signing/encryption and the SP certificate/private key cannot be configured in the admin UI, so write them directly in ``system.properties``. + +.. note:: + Settings that start with ``saml.`` are read only from ``system.properties``. + JVM system properties such as ``-Dsaml.security....`` or ``-Dfess.saml.security....`` are not consulted. + In particular, ``saml.security.*``, ``saml.strict`` and ``saml.debug`` have no field in the admin UI either, + so writing them directly in ``system.properties`` is the only way to set them. + +Session Cookie Configuration +---------------------------- + +The IdP returns the assertion to |Fess| as a **cross-site POST**. A ``SameSite=Lax`` cookie is not sent on such a request, so SAML login does not complete with the default value shipped with |Fess|. + +Change ``tomcat.sameSiteCookies`` to ``none`` in ``tomcat_config.properties``. This file is located in ``lib/classes/`` for the ZIP package and in ``/etc/fess/`` for the DEB/RPM packages. + +:: + + tomcat.sameSiteCookies = none + +.. warning:: + Browsers only accept ``none`` on a cookie that also carries the ``Secure`` attribute, so |Fess| must be served over HTTPS. Over plain HTTP, this setting makes it impossible to log in to |Fess|. + +.. note:: + The default ``lax`` is set for SSO methods whose callback returns as a redirect (GET). SAML's HTTP-POST binding is not one of them, so this change is only needed when using SAML. |Fess| must be restarted after changing the setting. + +SP (Service Provider) Configuration +------------------------------------ + +To configure |Fess| as an SP, specify the SP Base URL. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Property + - Description + - Default + * - ``saml.sp.base.url`` + - SP base URL + - ``http://localhost:8080`` + +.. note:: + The default of ``saml.sp.base.url`` is ``http://localhost:8080``. + Outside of test environments, always set the URL used to access |Fess| externally (HTTPS in production). + +This setting automatically configures the following endpoints: + +- **Entity ID**: ``{saml.sp.base.url}/sso/metadata`` +- **ACS URL**: ``{saml.sp.base.url}/sso/`` +- **SLO URL**: ``{saml.sp.base.url}/sso/logout`` + +Example:: + + saml.sp.base.url=https://fess.example.com + +Individual URL Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Normally, setting ``saml.sp.base.url`` automatically configures each endpoint URL, but you can override individual URLs explicitly with the following properties if needed. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Property + - Description + - Default + * - ``saml.sp.entityid`` + - SP Entity ID + - ``{saml.sp.base.url}/sso/metadata`` + * - ``saml.sp.assertion_consumer_service.url`` + - Assertion Consumer Service URL + - ``{saml.sp.base.url}/sso/`` + * - ``saml.sp.single_logout_service.url`` + - Single Logout Service URL + - ``{saml.sp.base.url}/sso/logout`` + +IdP (Identity Provider) Configuration +------------------------------------- + +Configure the information obtained from your IdP. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Property + - Description + - Default + * - ``saml.idp.entityid`` + - IdP Entity ID + - (Required) + * - ``saml.idp.single_sign_on_service.url`` + - IdP SSO service URL + - (Required) + * - ``saml.idp.x509cert`` + - IdP signing X.509 certificate (Base64 encoded, no line breaks) + - (Required) + * - ``saml.idp.single_logout_service.url`` + - IdP SLO service URL + - (Optional) + +.. note:: + For ``saml.idp.x509cert``, specify only the Base64-encoded content of the certificate on a single line without line breaks. + Do not include the ``-----BEGIN CERTIFICATE-----`` and ``-----END CERTIFICATE-----`` lines. + +Retrieving SP Metadata +---------------------- + +After starting |Fess|, you can retrieve the SP metadata in XML format from the ``/sso/metadata`` endpoint. + +:: + + https://fess.example.com/sso/metadata + +Import this metadata into your IdP, or manually register the SP on the IdP side using the metadata contents. + +.. note:: + To retrieve the metadata, you must first complete the basic SAML configuration (``sso.type=saml`` and ``saml.sp.base.url``) and start |Fess|. + +IdP Side Configuration +====================== + +When registering |Fess| as an SP on the IdP side, configure the following information: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Setting + - Value + * - ACS URL / Reply URL + - ``https:///sso/`` + * - Entity ID / Audience URI + - ``https:///sso/metadata`` + * - Name ID Format + - ``urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`` (Recommended) + +Information to Obtain from IdP +------------------------------ + +Obtain the following information from your IdP's configuration screen or metadata for use in |Fess| configuration: + +- **IdP Entity ID**: URI that identifies the IdP +- **SSO URL (HTTP-Redirect)**: Single sign-on endpoint URL +- **X.509 Certificate**: Public key certificate used for SAML assertion signature verification + +User Attribute Mapping +====================== + +You can map user attributes obtained from SAML assertions to |Fess| groups and roles. + +Group Attribute Configuration +----------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Property + - Description + - Default + * - ``saml.attribute.group.name`` + - Attribute name containing group information + - ``memberOf`` + * - ``saml.default.groups`` + - Default groups (comma-separated) + - (None) + +Example:: + + saml.attribute.group.name=groups + saml.default.groups=user + +.. note:: + |Fess| uses the group values in the assertion as they are; it performs no directory lookup and + does not expand nested (transitive) groups. Whether parent groups appear is therefore decided + entirely by the IdP's claim configuration -- unlike :doc:`sso-entraid`, where |Fess| resolves + parent groups through the Microsoft Graph API. + +Role Attribute Configuration +---------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Property + - Description + - Default + * - ``saml.attribute.role.name`` + - Attribute name containing role information + - (None) + * - ``saml.default.roles`` + - Default roles (comma-separated) + - (None) + +Example:: + + saml.attribute.role.name=roles + saml.default.roles=viewer + +.. note:: + If attributes cannot be obtained from the IdP, default values will be used. + When using role-based search, configure appropriate groups or roles. + +.. warning:: + When ``saml.attribute.role.name`` is set, the attribute values sent by the IdP become |Fess| roles + as they are. Because ``authentication.admin.roles`` in ``fess_config.properties`` defaults to + ``admin``, any user whose role attribute contains ``admin`` gains |Fess| administrator privileges. + Check who can control the role attribute on the IdP side, and change + ``authentication.admin.roles`` to a different name if necessary. + +IdPs that repeat an attribute name +---------------------------------- + +If the IdP splits the same attribute name across several ```` elements, |Fess| refuses +the assertion and the login itself fails. + +Keycloak sends assertions of this shape by default: its role and group mappers emit one +```` element per value unless their ``single`` option is enabled, and every Keycloak +account carries several default realm roles. + +There are two remedies: + +- Aggregate the values into a single element at the IdP (in Keycloak, enable the ``single`` option + of the mappers) +- Accept the repeats in |Fess| and merge their values + +.. list-table:: + :header-rows: 1 + :widths: 45 40 15 + + * - Property + - Description + - Default + * - ``saml.security.allow_duplicated_attribute_name`` + - Allows the same attribute name on several elements and merges their values + - ``false`` + +Example:: + + saml.security.allow_duplicated_attribute_name=true + +Security Configuration +====================== + +For production environments, it is recommended to enable the following security settings. + +.. note:: + When settings that are not recommended remain in place, an ``Insecure SAML settings: ...`` + warning is written to the log as the SAML settings are loaded. + +Signature Settings +------------------ + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Property + - Description + - Default + * - ``saml.security.authnrequest_signed`` + - Sign authentication requests + - ``false`` + * - ``saml.security.want_messages_signed`` + - Require message signatures + - ``false`` + * - ``saml.security.want_assertions_signed`` + - Require assertion signatures + - ``false`` + * - ``saml.security.logoutrequest_signed`` + - Sign logout requests + - ``false`` + * - ``saml.security.logoutresponse_signed`` + - Sign logout responses + - ``false`` + * - ``saml.security.reject_deprecated_alg`` + - Reject deprecated signature algorithms such as SHA-1 + - ``false`` + +.. warning:: + Security features are disabled by default. + For production environments, it is strongly recommended to set at least ``saml.security.want_assertions_signed=true``. + +.. note:: + While ``saml.security.reject_deprecated_alg`` is ``false``, assertions and messages signed with + SHA-1 (``rsa-sha1`` and ``dsa-sha1``) are also accepted. It is not enabled by default because + turning it on rejects IdPs that still sign with SHA-1. + Confirm that your IdP signs with SHA-256 or stronger, then set ``saml.security.reject_deprecated_alg=true``. + +.. warning:: + When Single Logout is configured (``saml.idp.single_logout_service.url``), always set + ``saml.security.want_messages_signed=true`` as well. + While it is ``false``, a LogoutRequest that carries no signature is accepted, so a crafted URL + can end an authenticated user's session. + The impact is a forced logout (denial of service), not account takeover. + +Encryption Settings +------------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Property + - Description + - Default + * - ``saml.security.want_assertions_encrypted`` + - Require assertion encryption + - ``false`` + * - ``saml.security.want_nameid_encrypted`` + - Require NameID encryption + - ``false`` + * - ``saml.security.allowed_key_transport_algorithms`` + - Key transport algorithms accepted when decrypting an assertion (comma-separated URIs) + - (empty: every algorithm is accepted) + +.. note:: + |Fess| validates responses encrypted with XML Encryption 1.1. Current Keycloak, for + example, uses ``http://www.w3.org/2009/xmlenc11#rsa-oaep`` and includes an + ```` element in its response; such a response is accepted with schema + validation left on. Earlier versions rejected it with + ``Invalid SAML Response. Not match the saml-schema-protocol-2.0.xsd``. If + ``saml.security.want_xml_validation=false`` was set to work around that, remove it. + +.. note:: + Set ``saml.security.allowed_key_transport_algorithms`` whenever an SP private key is + configured. While it is unset, every key transport algorithm is accepted, including the + legacy ``http://www.w3.org/2001/04/xmlenc#rsa-1_5``. The assertion consumer endpoint is + anonymous and decryption runs before the response is validated, so an unauthenticated + caller can have the SP private key decrypt a ciphertext of their choosing. |Fess| reports + ``key_transport_algorithms_not_restricted`` in the ``Insecure SAML settings`` line at + start-up while this is the case. Restrict it to what the IdP actually uses:: + + saml.security.allowed_key_transport_algorithms=http://www.w3.org/2009/xmlenc11#rsa-oaep + +SP Certificate and Private Key Configuration +-------------------------------------------- + +When the SP signs authentication requests or logout messages (e.g., ``saml.security.authnrequest_signed``), or requests encryption of assertions or NameID (e.g., ``saml.security.want_assertions_encrypted``), you must configure the SP's private key and X.509 certificate. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Property + - Description + - Default + * - ``saml.sp.x509cert`` + - SP X.509 certificate (Base64-encoded, no line breaks) + - (empty) + * - ``saml.sp.privatekey`` + - SP private key (Base64-encoded, no line breaks) + - (empty) + +.. note:: + For ``saml.sp.x509cert`` and ``saml.sp.privatekey``, as with ``saml.idp.x509cert``, specify the Base64-encoded content as a single line without line breaks (do not include the ``-----BEGIN ...-----`` and ``-----END ...-----`` lines). + When enabling signing/encryption, also register the SP certificate on the IdP side. The SP certificate is published in the SP metadata at ``/sso/metadata``. + +Other Security Settings +----------------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Property + - Description + - Default + * - ``saml.strict`` + - Strict mode (perform strict validation) + - ``true`` + * - ``saml.security.want_xml_validation`` + - Validate the XML schema of messages + - ``true`` + * - ``saml.security.signature_algorithm`` + - Signature algorithm + - ``http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`` + * - ``saml.security.requested_authncontext`` + - Requested authentication context + - ``urn:oasis:names:tc:SAML:2.0:ac:classes:Password`` + * - ``saml.sp.nameidformat`` + - NameID format + - ``urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`` + +.. note:: + |Fess| internally uses a SAML library (java-saml), and properties starting with ``saml.`` are mapped to the library's corresponding settings (the ``onelogin.saml2.`` prefix). + Therefore, in addition to those listed here, you can specify detailed settings in ``system.properties`` such as bindings (e.g., ``saml.sp.assertion_consumer_service.binding``), organization information (``saml.organization.*``), and contact information (``saml.contacts.*``). + +AuthnRequest Expiration +======================= + +|Fess| sends one AuthnRequest to the IdP for each access to ``/sso/`` and records its ID in the session. +The SAML response returned by the IdP is validated against the recorded ID. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Property + - Description + - Default + * - ``saml.request.id.ttl`` + - How long an unanswered AuthnRequest ID is retained (seconds) + - ``3600`` + +A recorded ID is discarded once this period passes. +If it expires (for example the IdP login page was left open), the returned assertion cannot be matched and the login fails once. + +Configuration Examples +====================== + +Minimal Configuration (for Testing) +----------------------------------- + +The following is a minimal configuration example for verification in a test environment. + +:: + + # Enable SSO + sso.type=saml + + # SP configuration + saml.sp.base.url=https://fess.example.com + + # IdP configuration (set values obtained from IdP admin console) + saml.idp.entityid=https://idp.example.com/saml/metadata + saml.idp.single_sign_on_service.url=https://idp.example.com/saml/sso + saml.idp.x509cert=MIIDpDCCAoygAwIBAgI...(Base64 encoded certificate) + + # Default groups + saml.default.groups=user + +Recommended Configuration (for Production) +------------------------------------------ + +The following is a recommended configuration example for production environments. + +:: + + # Enable SSO + sso.type=saml + + # SP configuration + saml.sp.base.url=https://fess.example.com + + # IdP configuration + saml.idp.entityid=https://idp.example.com/saml/metadata + saml.idp.single_sign_on_service.url=https://idp.example.com/saml/sso + saml.idp.single_logout_service.url=https://idp.example.com/saml/logout + saml.idp.x509cert=MIIDpDCCAoygAwIBAgI...(Base64 encoded certificate) + + # User attribute mapping + saml.attribute.group.name=groups + saml.attribute.role.name=roles + saml.default.groups=user + + # Security settings (recommended for production) + saml.security.want_assertions_signed=true + saml.security.want_messages_signed=true + + # Enable after confirming the IdP signs with SHA-256 or stronger + saml.security.reject_deprecated_alg=true + +Troubleshooting +=============== + +Common Issues and Solutions +--------------------------- + +Cannot return to Fess after authentication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verify that the ACS URL is correctly configured on the IdP side +- Ensure the ``saml.sp.base.url`` value matches the IdP configuration +- The SAML assertion arrives as a cross-site POST from the IdP. When ``tomcat.sameSiteCookies`` in + ``tomcat_config.properties`` is ``lax`` (the default), the browser does not send the session cookie + with it and the login fails once. Set ``tomcat.sameSiteCookies = none`` in that case + (``SameSite=None`` requires HTTPS) +- If the login took too long at the IdP, the AuthnRequest ID is no longer there when the assertion + comes back, so the login fails once and has to be started again +- |Fess| leaves ``session-timeout`` unset in ``app/WEB-INF/web.xml``, so the servlet container's + default of 30 minutes applies and is shorter than the 3600 seconds of ``saml.request.id.ttl``. + Raising ``saml.request.id.ttl`` on its own therefore does not give users longer to finish logging + in at the IdP: raise the session timeout as well + +Destination validation fails behind a reverse proxy +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When |Fess| runs behind a TLS-terminating reverse proxy or load balancer, assertion validation can +fail even though ``saml.sp.base.url`` is set correctly. + +The ``Destination`` attribute of the assertion is compared against the URL of the request as it +reaches |Fess|, which behind a TLS-terminating proxy is an internal ``http://`` URL rather than the +external one the IdP sent the assertion to. ``saml.sp.base.url`` is not used for this comparison, +so setting it alone does not fix the problem. + +Set ``saml.debug=true`` to have the reason written to the log: + +:: + + The response was received at http://... instead of https://fess.example.com/sso/ + +Align the connector settings in ``tomcat_config.properties`` with the externally visible scheme and +port. These settings ship commented out: + +:: + + tomcat.secure=true + tomcat.scheme=https + tomcat.proxyPort=443 + +Also configure the reverse proxy to pass the original ``Host`` header through to |Fess|, because the +host part of the request URL is built from that header. |Fess| must be restarted after changing +``tomcat_config.properties``. + +The same validation applies to Single Logout messages, so configure this when using SLO as well. + +Signature verification error +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verify that the IdP certificate is correctly configured +- Ensure the certificate has not expired +- The certificate should be specified as Base64-encoded content only, without line breaks + +Login fails because an attribute name is repeated +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- If the log contains a warning beginning with ``The IdP repeated an attribute name in the SAML + assertion``, the IdP is splitting the same attribute name across several ```` elements +- The assertion itself passed validation, so the certificate and clock skew are not the cause +- Aggregate the attributes at the IdP, or set ``saml.security.allow_duplicated_attribute_name=true`` + +User groups/roles not reflected +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verify that attributes are correctly configured on the IdP side +- Ensure the ``saml.attribute.group.name`` value matches the attribute name sent by the IdP +- With Microsoft Entra ID, the group claim carries group ``ObjectId`` GUIDs unless a different + source attribute is selected, so the values will not match group names +- Microsoft Entra ID omits the group claim entirely when the user belongs to more than 150 groups + (nested groups count toward this limit), and |Fess| then falls back to ``saml.default.groups`` +- Enable debug mode to inspect the SAML assertion contents + +Debug Settings +-------------- + +To investigate issues, you can enable debug mode with the following setting: + +:: + + saml.debug=true + +Setting ``saml.debug=true`` outputs the detailed reason to the log when SAML authentication fails. + +You can also output detailed SAML-related logs by adding the following logger to ``app/WEB-INF/classes/log4j2.xml``: + +:: + + + +Reference +========= + +- :doc:`security-role` - Role-based search configuration +- :doc:`sso-oidc` - About SSO configuration with OpenID Connect +- :doc:`sso-entraid` - About SSO configuration dedicated to Microsoft Entra ID diff --git a/en/15.10/config/sso-spnego.rst b/en/15.10/config/sso-spnego.rst new file mode 100644 index 000000000..3e98c84b1 --- /dev/null +++ b/en/15.10/config/sso-spnego.rst @@ -0,0 +1,490 @@ +================================================ +SSO Configuration with Windows Integrated Auth +================================================ + +Overview +======== + +|Fess| supports Single Sign-On (SSO) authentication using Windows Integrated Authentication (SPNEGO/Kerberos). +By using Windows Integrated Authentication, users who are logged into a Windows domain-joined computer can access |Fess| without additional login operations. + +.. note:: + Windows Integrated Authentication comes from the ``fess-sso-spnego`` plugin, which is not + part of the distribution. Install it from the System > Plugin page in the administration + screen, or with ``bin/fess-setup install plugin fess-sso-spnego``. + Until it is installed, ``sso.type=spnego`` only redirects every request to ``/sso/`` back to + the login page. + +How Windows Integrated Authentication Works +------------------------------------------- + +In Windows Integrated Authentication, |Fess| uses the SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) protocol for Kerberos authentication. + +1. User logs into the Windows domain +2. User accesses |Fess| +3. |Fess| sends an SPNEGO challenge +4. Browser obtains a Kerberos ticket and sends it to the server +5. |Fess| validates the ticket and retrieves the username +6. User's group information is retrieved via LDAP +7. User is logged in and group information is applied to role-based search + +For role-based search integration, see :doc:`security-role`. + +Prerequisites +============= + +Before configuring Windows Integrated Authentication, verify the following prerequisites: + +- |Fess| 15.10 or later is installed +- An Active Directory (AD) server is available +- |Fess| server is accessible from the AD domain +- You have permission to configure Service Principal Names (SPN) in AD +- An account for retrieving user information via LDAP is available + +Active Directory Side Configuration +==================================== + +Registering Service Principal Name (SPN) +----------------------------------------- + +You need to register an SPN for |Fess| in Active Directory. +Open a command prompt on a Windows computer joined to the AD domain and run the ``setspn`` command. + +:: + + setspn -S HTTP/ + +Example: + +:: + + setspn -S HTTP/fess-server.example.local svc_fess + +To verify the registration: + +:: + + setspn -L + +.. note:: + After registering the SPN, if you ran the command on the Fess server, log out of Windows and log back in. + +Basic Configuration +=================== + +Enabling SSO +------------ + +To enable Windows Integrated Authentication, add the following setting in ``app/WEB-INF/conf/system.properties``: + +:: + + sso.type=spnego + +Kerberos Configuration File +---------------------------- + +Create ``app/WEB-INF/classes/krb5.conf`` with the Kerberos configuration. + +:: + + [libdefaults] + default_realm = EXAMPLE.LOCAL + default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + + [realms] + EXAMPLE.LOCAL = { + kdc = AD-SERVER.EXAMPLE.LOCAL + default_domain = EXAMPLE.LOCAL + } + + [domain_realm] + example.local = EXAMPLE.LOCAL + .example.local = EXAMPLE.LOCAL + +.. note:: + Replace ``EXAMPLE.LOCAL`` with your AD domain name (uppercase) and ``AD-SERVER.EXAMPLE.LOCAL`` with your AD server hostname. + +.. warning:: + A service ticket encrypted with a type that is not listed in ``permitted_enctypes`` is rejected by + the Kerberos acceptor as ``encryption type not in permitted_enctypes list``. + Active Directory normally issues AES256 service tickets, so AES256 must be listed. + +.. note:: + RC4 (``rc4-hmac``), 3DES and DES are disabled by default in Java 17 and later, so listing them has + no effect; the example above specifies AES only. + ``aes256-cts-hmac-sha384-192`` and ``aes128-cts-hmac-sha256-128`` are the AES-SHA2 (RFC 8009) types + supported by Windows Server 2025. + A service account that holds only an RC4 key cannot be used for Kerberos authentication; reset its + password so that AES keys are generated. + +Login Configuration File +------------------------ + +Create ``app/WEB-INF/classes/auth_login.conf`` with the JAAS login configuration. + +:: + + spnego-client { + com.sun.security.auth.module.Krb5LoginModule required; + }; + + spnego-server { + com.sun.security.auth.module.Krb5LoginModule required + storeKey=true + isInitiator=false; + }; + +.. note:: + ``krb5.conf`` and ``auth_login.conf`` have their default filenames set via ``spnego.krb5.conf`` / ``spnego.login.conf``, but the files themselves must be created. + SPNEGO is initialized on the first login, so |Fess| itself still starts when these files are missing, but SSO login fails. + +Required Settings +----------------- + +Add the following settings to ``app/WEB-INF/conf/system.properties``. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Property + - Description + - Default + * - ``spnego.preauth.username`` + - AD connection username + - (Required unless a keytab is used) + * - ``spnego.preauth.password`` + - AD connection password + - (Required unless a keytab is used) + * - ``spnego.krb5.conf`` + - Kerberos configuration file path + - ``krb5.conf`` + * - ``spnego.login.conf`` + - Login configuration file path + - ``auth_login.conf`` + +.. note:: + Leaving both ``spnego.preauth.username`` and ``spnego.preauth.password`` empty makes the server + login module use a keytab. + If you do not want to store the AD service account password in a |Fess| configuration file, create + a keytab and configure ``spnego-server`` in ``auth_login.conf`` as follows. + + :: + + spnego-server { + com.sun.security.auth.module.Krb5LoginModule required + useKeyTab=true + keyTab="/var/lib/fess/fess.keytab" + principal="HTTP/fess-server.example.local@EXAMPLE.LOCAL" + storeKey=true + isInitiator=false; + }; + +Optional Settings +----------------- + +The following settings can be added as needed. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Property + - Description + - Default + * - ``spnego.login.client.module`` + - Client module name + - ``spnego-client`` + * - ``spnego.login.server.module`` + - Server module name + - ``spnego-server`` + * - ``spnego.allow.basic`` + - Allow Basic authentication + - ``true`` + * - ``spnego.allow.unsecure.basic`` + - Allow unsecure Basic authentication + - ``false`` + * - ``spnego.prompt.ntlm`` + - Fall back to Basic authentication when an NTLM token is received + - ``true`` + * - ``spnego.allow.localhost`` + - Allow localhost access + - ``false`` + * - ``spnego.allow.delegation`` + - Allow delegation + - ``false`` + * - ``spnego.allowed.realms`` + - Kerberos realms accepted in addition to the server realm (comma-separated) + - (None) + * - ``spnego.logger.level`` + - Internal log level of the SPNEGO library (``1`` =FINEST, ``2`` =FINER, ``3`` =FINE, ``4`` =CONFIG, ``6`` =WARNING, ``7`` =SEVERE; any other value including ``0`` and ``5`` is treated as INFO) + - (Auto) + +.. warning:: + ``spnego.allow.unsecure.basic=true`` may send Base64-encoded credentials over unencrypted connections. + For production environments, it is strongly recommended to set this to ``false`` and use HTTPS. + +.. note:: + With ``spnego.allow.unsecure.basic=false`` (the default), Basic authentication is only offered + for requests where ``HttpServletRequest#isSecure()`` returns ``true``. + When TLS is terminated at a reverse proxy and the request is forwarded to |Fess| over HTTP, + that value is ``false``, so a client that cannot obtain a Kerberos ticket and falls back to + NTLM cannot log in. Set ``tomcat.secure=true`` in ``tomcat_config.properties`` to tell |Fess| + that the request arrived over HTTPS. That file lives in ``lib/classes/`` in the ZIP + distribution and in ``/etc/fess/`` in the DEB/RPM packages, and |Fess| must be restarted + after it is changed. + +.. warning:: + In |Fess| 15.10, a login is rejected by default when the realm of the client principal differs + from the server realm. If users log in from a child domain of an AD domain tree or from a + trusted forest, list those realms in ``spnego.allowed.realms``, separated by commas. + Otherwise users who could log in up to 15.7 are rejected with + ``Kerberos realm is not allowed``. + +.. warning:: + |Fess| identifies a user by the part of the principal before ``@``, so the realm is not part of + the user name. When you list additional realms in ``spnego.allowed.realms``, users who share an + account name across realms — for example ``alice@CORP.EXAMPLE.COM`` and + ``alice@PARTNER.EXAMPLE.COM`` — become the same |Fess| user and share that user's groups, roles + and document permissions. Add a realm only when the account name identifies exactly one person + across every realm you list. + +.. note:: + The allow list also applies to the Basic authentication fallback. If a user enters a name of the + form ``user@REALM``, that realm is checked against ``spnego.allowed.realms`` and the login is + refused when it is not allowed. A plain account name, or the ``DOMAIN\user`` form, names no realm + and is authenticated in the default realm of ``krb5.conf``. Because a Basic login is + authenticated directly against the realm the user types, keep the allow list minimal, and + consider setting ``spnego.allow.basic`` to ``false`` if you rely on it as a security boundary. + +.. note:: + When ``spnego.prompt.ntlm=true`` (the default), ``spnego.allow.basic`` must also be ``true``. + If you set ``spnego.allow.basic=false``, you must also set ``spnego.prompt.ntlm=false``. + If this condition is not met, an error will occur during SPNEGO initialization. + +.. note:: + ``spnego.logger.level`` controls the log level of the SPNEGO library's internal logger (a ``java.util.logging`` logger named ``Spnego``). + When not set, the level is determined automatically based on the |Fess| log level. + +LDAP Configuration +================== + +LDAP configuration is required to retrieve group information for users authenticated via Windows Integrated Authentication. +Configure LDAP settings in the |Fess| admin panel under "System" -> "General". + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Item + - Example + * - LDAP URL + - ``ldap://AD-SERVER.example.local:389`` + * - Base DN + - ``dc=example,dc=local`` + * - Bind DN + - ``svc_fess@example.local`` + * - Password + - Password for AD access user + * - User DN + - ``%s@example.local`` + * - Account Filter + - ``(&(objectClass=user)(sAMAccountName=%s))`` + * - memberOf Attribute + - ``memberOf`` + +.. note:: + |Fess| reads the ``memberOf`` attribute of the user one level deep, so nested groups (a group + that is a member of another group) are not expanded by default. To reflect AD nested groups, + set ``(member:1.2.840.113556.1.4.1941:=%s)`` as the Group Filter (``ldap.group.filter``) under + "System" → "General" in the administration UI. The expansion runs asynchronously after login, + so the login entry in the audit log records only the groups resolved before it completed. + +Browser Settings +================ + +Client browser settings are required to use Windows Integrated Authentication. + +Internet Explorer / Microsoft Edge +----------------------------------- + +1. Open Internet Options +2. Select the "Security" tab +3. Click "Sites" for the "Local intranet" zone +4. Click "Advanced" and add the Fess URL +5. Click "Custom level" for the "Local intranet" zone +6. Under "User Authentication" -> "Logon", select "Automatic logon only in Intranet zone" +7. In the "Advanced" tab, check "Enable Integrated Windows Authentication" + +Google Chrome +------------- + +Chrome typically uses the Windows Internet Options settings. +If additional configuration is needed, set ``AuthServerAllowlist`` via Group Policy or registry. + +Mozilla Firefox +--------------- + +1. Enter ``about:config`` in the address bar +2. Search for ``network.negotiate-auth.trusted-uris`` +3. Set the Fess server URL or domain (e.g., ``https://fess-server.example.local``) + +Configuration Examples +====================== + +Minimal Configuration (for Testing) +------------------------------------- + +The following is a minimal configuration example for a test environment. + +``app/WEB-INF/conf/system.properties``: + +:: + + # Enable SSO + sso.type=spnego + + # SPNEGO settings + spnego.preauth.username=svc_fess + spnego.preauth.password=your-password + +``app/WEB-INF/classes/krb5.conf``: + +:: + + [libdefaults] + default_realm = EXAMPLE.LOCAL + default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + + [realms] + EXAMPLE.LOCAL = { + kdc = AD-SERVER.EXAMPLE.LOCAL + default_domain = EXAMPLE.LOCAL + } + + [domain_realm] + example.local = EXAMPLE.LOCAL + .example.local = EXAMPLE.LOCAL + +``app/WEB-INF/classes/auth_login.conf``: + +:: + + spnego-client { + com.sun.security.auth.module.Krb5LoginModule required; + }; + + spnego-server { + com.sun.security.auth.module.Krb5LoginModule required + storeKey=true + isInitiator=false; + }; + +Recommended Configuration (for Production) +------------------------------------------- + +The following is a recommended configuration example for production environments. + +``app/WEB-INF/conf/system.properties``: + +:: + + # Enable SSO + sso.type=spnego + + # SPNEGO settings + spnego.preauth.username=svc_fess + spnego.preauth.password=your-secure-password + spnego.krb5.conf=krb5.conf + spnego.login.conf=auth_login.conf + + # Security settings (production) + spnego.allow.basic=false + spnego.allow.unsecure.basic=false + spnego.prompt.ntlm=false + spnego.allow.localhost=false + +.. note:: + When setting ``spnego.allow.basic=false``, you must also set ``spnego.prompt.ntlm=false``. + Since ``spnego.prompt.ntlm`` defaults to ``true``, omitting this setting will cause an error during initialization. + +Troubleshooting +=============== + +Common Issues and Solutions +---------------------------- + +Authentication Dialog Appears +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verify that the Fess server is added to the Local Intranet zone in browser settings +- Check that "Enable Integrated Windows Authentication" is enabled +- Verify that the SPN is correctly registered (``setspn -L ``) + +Authentication Errors Occur +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verify that the domain name (uppercase) and AD server name in ``krb5.conf`` are correct +- Check that ``spnego.preauth.username`` and ``spnego.preauth.password`` are correct +- Verify network connectivity to the AD server + +Cannot Retrieve Group Information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verify that LDAP settings are correct +- Check that Bind DN and password are correct +- Verify that the user belongs to groups in AD + +Login returns HTTP 400 +~~~~~~~~~~~~~~~~~~~~~~ + +For a user who belongs to many groups the Kerberos ticket (PAC) grows large, and the +``Authorization`` header can exceed Tomcat's default limit of 8KB, which is answered with 400. +The request never reaches |Fess|, so nothing is written to the log. +Raise the limit in ``tomcat_config.properties``. + +:: + + tomcat.maxHttpHeaderSize=65536 + +Authentication fails after the service account password is changed +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The server credential is obtained once on the first login and cached for the lifetime of the process. +Restart |Fess| after changing the service account password in AD or replacing the keytab. +A restart is likewise required after changing any ``spnego.*`` setting. + +Debug Settings +-------------- + +To investigate issues, you can output detailed SPNEGO-related logs. + +To output verbose internal logs from the SPNEGO library, add the following to ``app/WEB-INF/conf/system.properties``. +``spnego.logger.level=1`` outputs the most detailed logs (FINEST). + +:: + + spnego.logger.level=1 + +To output detailed logs for the |Fess|-side SPNEGO integration processing (the ``org.codelibs.fess.sso.spnego`` package), add the following logger to ``app/WEB-INF/classes/log4j2.xml``: + +:: + + + +.. note:: + The SPNEGO library itself outputs logs via ``java.util.logging``, so its log level is controlled by ``spnego.logger.level`` rather than ``log4j2.xml``. + The |Fess|-side integration logs are controlled by the ``log4j2.xml`` logger. + +Reference +========= + +- :doc:`security-role` - Role-based search configuration +- :doc:`sso-saml` - SSO configuration with SAML authentication +- :doc:`sso-oidc` - SSO configuration with OpenID Connect authentication +- :doc:`sso-entraid` - SSO configuration with Microsoft Entra ID diff --git a/en/15.10/config/system.rst b/en/15.10/config/system.rst new file mode 100644 index 000000000..8c989dcac --- /dev/null +++ b/en/15.10/config/system.rst @@ -0,0 +1,92 @@ +======================= +System-related settings +======================= + +Configuration of ports used +=========================== + +The default port used by |Fess| is 8080. To change it, follow these steps: + +For Linux environments, edit ``bin/fess.in.sh``: + +:: + + FESS_JAVA_OPTS="$FESS_JAVA_OPTS -Dfess.port=8080" + +For Windows environments, edit ``bin\\fess.in.bat``: + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.port=8080 + +If you are registering |Fess| as a Windows service, also update the port in ``bin\\service.bat``: + +:: + + set FESS_PARAMS=-Dfess;-Dfess.home="%FESS_HOME%";-Dfess.es.dir="%SEARCH_ENGINE_HOME%";-Dfess.home="%FESS_HOME%";-Dfess.context.path="/";-Dfess.port=8080;-Dfess.webapp.path="%FESS_HOME%\\app";-Dfess.temp.path="%FESS_HOME%\\temp";-Dfess.log.name="%APP_NAME%";-Dfess.log.path="%FESS_HOME%\\logs";-Dfess.log.level=warn;-Dlasta.env=web;-Dtomcat.config.path=tomcat_config.properties + +Configuration of memory used +============================ + +In Java, each process has a maximum memory limit. Even if your server has 8GB of physical memory, the process won't use more memory than the defined limit. The amount of memory consumed can vary significantly depending on the number of crawling threads and intervals. If you encounter memory issues, follow these steps to adjust the settings. + +On servers running OpenSearch, excessive allocation of Java heap memory can degrade performance due to the use of the OS file system cache. Refer to the OpenSearch documentation for appropriate settings. + +Changing the maximum heap memory value +-------------------------------------- + +Depending on the crawl settings, the following OutOfMemory error may occur. + +:: + + java.lang.OutOfMemoryError: Java heap space + +If this occurs, increase the maximum value of heap memory. +Specify the environment variable FESS_HEAP_SIZE as FESS_HEAP_SIZE=2g or change FESS_HEAP_SIZE in ``/etc/sysconfig/fess`` if it is rpm. + +Crawler-side heap memory maximum change +--------------------------------------- + +The maximum heap memory on the crawler side can also be adjusted. +It should be increased if the filesystem or other systems are being heavily crawled. +To make this change, modify the line -Xmx512m in the jvm.crawler.options found in ``app/WEB-INF/classes/fess_config.properties`` or ``/etc/fess/fess_config.properties``. + +Configuration of logs +===================== + +Log files +--------- + +|Fess| output log files are listed below. + +Table: list of log files + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: Table: List of log files + :header-rows: 1 + + * - filename + - Contents. + * - ``fess.log`` + - Logs of operations on the admin and search screens. + * - ``fess_crawler.log`` + - Output logs when crawling is executed. + * - ``fess_suggest.log`` + - Output logs when suggestions are generated. + * - ``server_? .log`` + - Outputs the system log. + * - ``audit.log`` + - Outputs the audit log of logins, etc. + + +Check the above logs in case of problems with operation. + +Change log level +---------------- + +You can change the log level value of the output log in General on the management screen. +If you want to configure more detailed log settings, you can change them in ``app/WEB-INF/classes/log4j2.xml`` or ``/etc/fess/log4j2.xml``. +By default, the output is at WARN level. + +Crawler logs are output at INFO level by default. +If you want to change the log level, specify it using the logLevel(String) method in the crawl job settings on the management screen. diff --git a/en/15.10/config/thumbnail.rst b/en/15.10/config/thumbnail.rst new file mode 100644 index 000000000..5dbb72a7c --- /dev/null +++ b/en/15.10/config/thumbnail.rst @@ -0,0 +1,57 @@ +============================= +Thumbnail Image Configuration +============================= + +Displaying Thumbnail Images +=========================== + +In |Fess|, you have the option to display thumbnail images in search results. Thumbnail images are generated based on the MIME type of the search result. If the MIME type is supported, thumbnail images are automatically generated when displaying search results. You can configure the process of generating thumbnail images for different MIME types. + +To enable the display of thumbnail images, log in as an administrator, go to the General Settings, and enable the Thumbnail Display option. Don't forget to save your changes. + +Thumbnail Images for HTML Files +=============================== + +Thumbnail images for HTML files utilize images specified within the HTML document or images contained within it. Thumbnail images are determined based on the following criteria, in order: + +- The value of the `content` attribute in the meta tag with the `name` attribute set to "thumbnail." +- The value of the `content` attribute in the meta tag with the `property` attribute set to "og:image." +- An `img` tag with an image of an appropriate size for a thumbnail. + +Thumbnail Images for MS Office Files +==================================== + +Thumbnail images for MS Office files are generated using LibreOffice and ImageMagick. Thumbnail generation requires the unoconv and convert commands to be installed. + +Package Installation +-------------------- + +For Redhat-based operating systems, install the following packages to enable image creation: + +:: + + $ sudo yum install unoconv libreoffice-headless vlgothic-fonts ImageMagick + +Generation Scripts +------------------ + +When installed via RPM/Deb packages, the script for generating MS Office thumbnails is located at /usr/share/fess/bin/generate-thumbnail. + +Thumbnail Images for PDF Files +============================== + +Thumbnail images for PDF files are generated using ImageMagick. Thumbnail generation requires the convert command to be installed. + +Disabling Thumbnail Jobs +======================== + +To disable thumbnail jobs, follow these steps: + +1. In the admin panel, navigate to System > General, uncheck the "Thumbnail Display" option, and click "Update." +2. Set ``thumbnail.crawler.enabled`` to ``false`` in either ``app/WEB-INF/classes/fess_config.properties`` or ``/etc/fess/fess_config.properties``. + +:: + + thumbnail.crawler.enabled=false + +3. Restart the Fess service. diff --git a/en/15.10/config/virtual-host.rst b/en/15.10/config/virtual-host.rst new file mode 100644 index 000000000..627b149a7 --- /dev/null +++ b/en/15.10/config/virtual-host.rst @@ -0,0 +1,52 @@ +:canonical: security-virtual-host + +============ +Virtual Host +============ + +About Virtual Host +================== + +You can differentiate search results based on the hostname (URL's host part) when accessing Fess. A static theme whose name matches the virtual host name is used for that host, so you can also customize the design. + +System Configuration +-------------------- + +Configure the "Virtual Host" in the :doc:`Administrator's Guide > General Settings <../admin/general-guide>`. Specify the configured virtual host name in the crawl settings. + +**Format** + +:: + + Host:hostname[:port]=virtual_host_name + +.. list-table:: + + * - *hostname* + - A hostname or IP address that can be resolved (DNS) on the system. + * - *port* + - Optional. The default is 80. + * - *virtual_host_name* + - The virtual host name specified in the crawl settings. + +**Example** + +:: + + Host:abc.example.com:8080=host1 + Host:192.168.1.123:8080=host2 + +To customize the page design for a virtual host, install a static theme whose name is the virtual host name in lowercase. See :doc:`security-virtual-host` for details. + + +Crawl Configuration +------------------- + +Specify the "Virtual Host" in the web crawl settings, file crawl settings, or data store crawl settings. The "Virtual Host" should match one of the virtual host names configured in the system settings. + +**Example** + +.. list-table:: + + * - *Virtual Host* + - ``host1`` diff --git a/en/15.10/config/windows-service.rst b/en/15.10/config/windows-service.rst new file mode 100644 index 000000000..37785a556 --- /dev/null +++ b/en/15.10/config/windows-service.rst @@ -0,0 +1,73 @@ +============================ +Register for Windows Service +============================ + +Registering as a Windows Service +================================ + +You can register |Fess| as a Windows service. To run |Fess|, you need to have OpenSearch running. In this guide, we assume that |Fess| is installed in ``c:\opt\fess`` and OpenSearch is installed in ``c:\opt\opensearch``. + +Preparations +------------ + +Please set the JAVA_HOME environment variable in your system. + +Registering OpenSearch as a Service +----------------------------------- + +From a command prompt, run ``c:\opt\fess\bin\service.bat`` as administrator. + +:: + + > cd c:\opt\opensearch\bin + > opensearch-service.bat install + ... + The service 'opensearch-service-x64' has been installed. + +For more details, refer to the `OpenSearch documentation `_. + +Configuration +------------- + +Edit ``c:\opt\fess\bin\fess.in.bat`` and set SEARCH_ENGINE_HOME to the installation path of OpenSearch. + +:: + + set SEARCH_ENGINE_HOME=c:/opt/opensearch + +The default port for |Fess| search and administration interfaces is 8080. If you want to change it to port 80, modify the fess.port in ``c:\opt\fess\bin\fess.in.bat``. + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.port=80 + +Registration +------------ + +From a command prompt, run ``c:\opt\fess\bin\service.bat`` as administrator. + +:: + + > cd c:\opt\fess\bin + > service.bat install + ... + The service 'fess-service-x64' has been installed. + +Service Configuration +--------------------- + +If you want to start the service manually, first start the OpenSearch service, and then start the |Fess| service. If you want it to start automatically, add dependencies. + +1. Set the startup type to "Automatic (Delayed Start)" in the service's general settings. +2. Configure the service dependencies in the registry. + +In the Registry Editor (regedit), add the following key and value: + +.. list-table:: + + * - *Key* + - ``Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services \fess-service-x64\DependOnService`` + * - *Value* + - ``opensearch-service-x64`` + +After adding this, opensearch-service-x64 will be listed as a dependency in the properties of the |Fess| service. diff --git a/en/15.10/dev/datastore-plugin.rst b/en/15.10/dev/datastore-plugin.rst new file mode 100644 index 000000000..ecdbe72a1 --- /dev/null +++ b/en/15.10/dev/datastore-plugin.rst @@ -0,0 +1,557 @@ +================================== +Data Store Plugin Development +================================== + +Overview +======== + +By developing a Data Store plugin, you can add functionality to |Fess| for +retrieving content from new data sources. A Data Store retrieves records from +external systems such as databases, APIs, and files, converts them into index +fields according to the mapping script configured in the admin console, and +registers them into the |Fess| index. + +Published connectors (``fess-ds-*``) for CSV, JSON, databases, Git, and +various cloud services are all implemented using this mechanism. Because +`fess-ds-example `__ is published +as an implementation template, the easiest way to create a new connector is +to copy it as a starting point. + +Basic Structure +=============== + +A Data Store plugin consists of the following three parts: + +- Create a class that extends ``AbstractDataStore`` +- Implement the two methods ``getName()`` and ``storeData()`` +- Register it as a component in ``fess_ds++.xml`` + +Minimum Implementation +---------------------- + +.. code-block:: java + + package org.codelibs.fess.ds.example; + + import java.util.Map; + + import org.codelibs.fess.ds.AbstractDataStore; + import org.codelibs.fess.ds.callback.IndexUpdateCallback; + import org.codelibs.fess.entity.DataStoreParams; + import org.codelibs.fess.opensearch.config.exentity.DataConfig; + + public class ExampleDataStore extends AbstractDataStore { + + @Override + protected String getName() { + // Used as the handler name. Convention is to return the class's simple name + return this.getClass().getSimpleName(); + } + + @Override + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { + + // Implement data retrieval and processing here + } + } + +.. note:: + + Both ``getName()`` and ``storeData()`` are ``protected`` abstract methods. + Note that in |Fess| 15.x, the package for ``DataConfig`` is + ``org.codelibs.fess.opensearch.config.exentity`` (the former + ``org.codelibs.fess.es.config.exentity`` has been removed). + +Component Registration +---------------------- + +To make |Fess| recognize the Data Store you created, register the component +in ``src/main/resources/fess_ds++.xml``. + +.. code-block:: xml + + + + + + + + + +With ````, the ``register()`` method inherited +from ``AbstractDataStore`` is automatically invoked after the component is +created, registering itself with the ``DataStoreFactory``. The name +registered at this time is the return value of ``getName()`` (``ExampleDataStore`` +in the example above), and this becomes the "handler name" selected in the +Data Store settings in the admin console. + +AbstractDataStore +================= + +Main Methods +------------ + +.. list-table:: + :header-rows: 1 + :widths: 35 20 45 + + * - Method + - Category + - Description + * - ``getName()`` + - Implementation (required) + - Abstract method that returns the Data Store's handler name. Convention + is to return ``getClass().getSimpleName()`` + * - ``storeData()`` + - Implementation (required) + - Abstract method that performs data retrieval, conversion, and index + registration + * - ``register()`` + - Inherited (normally no changes needed) + - Automatically invoked from the ``postConstruct`` in ``fess_ds++.xml`` + and registers with ``DataStoreFactory`` + * - ``store()`` + - Inherited (called by the framework) + - The entry point invoked by the framework. Prepares ``defaultDataMap`` + and other data, then calls ``storeData()`` + * - ``convertValue()`` + - Inherited (helper) + - Evaluates the value (template) in ``scriptMap`` using the script engine + * - ``getScriptType()`` + - Inherited (helper) + - Retrieves the ``script_type`` parameter (default is Groovy) + * - ``getReadInterval()`` + - Inherited (helper) + - Retrieves the ``readInterval`` parameter (in milliseconds) + * - ``sleep()`` + - Inherited (helper) + - Sleeps for the specified number of milliseconds (used to wait between + records) + +storeData Parameters +-------------------- + +Parameters passed to the ``storeData()`` method: + +.. list-table:: + :header-rows: 1 + :widths: 25 35 40 + + * - Parameter + - Type + - Description + * - ``dataConfig`` + - ``DataConfig`` + - Data Store configuration (ID, handler name, parameters, scripts, etc.) + * - ``callback`` + - ``IndexUpdateCallback`` + - Callback for registering generated documents to the index + * - ``paramMap`` + - ``DataStoreParams`` + - Configuration values from the "Parameters" field in the admin console. + Access them using ``getAsString(key)`` / ``getAsString(key, default)`` / + ``get(key)`` / ``asMap()`` / ``containsKey(key)`` + * - ``scriptMap`` + - ``Map`` + - Configuration from the "Scripts" field in the admin console. The key + is the index field name, and the value is the script template to be + evaluated + * - ``defaultDataMap`` + - ``Map`` + - Default field values for each document (config ID, boost, role, + mimetype, virtual host, etc.), prepared by the framework + +.. warning:: + + The type of ``paramMap`` is ``DataStoreParams``, not + ``Map``. Since ``DataStoreParams`` does not implement + ``Map``, use ``getAsString()``, which returns a string, instead of + ``get()`` to retrieve values. + +Data Processing Flow +-------------------- + +The implementation of ``storeData()`` processes data in the following flow. + +#. Retrieve source records from the external system. +#. Merge the source record's fields into ``paramMap.asMap()`` to build + ``resultMap`` (scripts are evaluated against this ``resultMap``). +#. Evaluate each entry in ``scriptMap`` with + ``convertValue(scriptType, template, resultMap)`` and store the result in + ``dataMap``. The important point is that the mapping is not hardcoded in + the code, but defined by the administrator in the "Scripts" field. +#. Call ``callback.store(paramMap, dataMap)`` to register the document to + the index. + +Implementation Examples +======================= + +Simple Data Store +------------------ + +An example of retrieving records from an external API and registering them +to the index. + +.. code-block:: java + + @Override + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { + + // Get parameters (use getAsString with DataStoreParams) + final String apiUrl = paramMap.getAsString("api.url"); + final String apiKey = paramMap.getAsString("api.key"); + + // Script evaluation type (default is Groovy) + final String scriptType = getScriptType(paramMap); + // Wait time between records (milliseconds) + final long readInterval = getReadInterval(paramMap); + + try { + // Retrieve data from the external system + final List> records = fetchRecords(apiUrl, apiKey); + + for (final Map record : records) { + // Copy default fields to initialize dataMap + final Map dataMap = new HashMap<>(defaultDataMap); + + // Build resultMap by merging parameters and the source record + // (scripts are evaluated against this resultMap) + final Map resultMap = new LinkedHashMap<>(paramMap.asMap()); + resultMap.putAll(record); + + // Evaluate each entry in scriptMap to generate index fields + for (final Map.Entry entry : scriptMap.entrySet()) { + final Object value = convertValue(scriptType, entry.getValue(), resultMap); + if (value != null) { + dataMap.put(entry.getKey(), value); + } + } + + // Register to the index + callback.store(paramMap, dataMap); + + if (readInterval > 0) { + sleep(readInterval); + } + } + } catch (final Exception e) { + throw new DataStoreException("Failed to crawl data from " + apiUrl, e); + } + } + +``fetchRecords()`` is a custom method that retrieves a list of records from +the external system. The field names of each retrieved record +(``Map``) become the names that can be referenced from the +scripts in ``scriptMap``. ``DataStoreException`` is a class in the +``org.codelibs.fess.exception`` package. + +Pagination Support +------------------- + +When handling large volumes of data, process the data page by page while +retrieving it. By extracting the per-record processing (building +``resultMap``, evaluating ``scriptMap``, and calling ``callback.store()``) +into a method such as ``processRecord()``, you can separate it from the +retrieval logic. + +.. code-block:: java + + int offset = 0; + final int pageSize = 100; + + while (true) { + final List> records = fetchRecords(apiUrl, apiKey, offset, pageSize); + + if (records.isEmpty()) { + break; + } + + for (final Map record : records) { + processRecord(record, callback, paramMap, scriptMap, defaultDataMap); + } + + offset += pageSize; + } + +Authentication Implementation +============================= + +Authentication with the external system is implemented on the connector +side. The following is an example implementation using a common HTTP client +library; it is not an API provided by |Fess|. Include the library you use +as a dependency of the plugin. + +OAuth 2.0 +--------- + +.. code-block:: java + + protected String getAccessToken(final String clientId, final String clientSecret, final String refreshToken) { + // Example of obtaining an access token using a refresh token + final OkHttpClient client = new OkHttpClient(); + + final RequestBody body = new FormBody.Builder() + .add("grant_type", "refresh_token") + .add("client_id", clientId) + .add("client_secret", clientSecret) + .add("refresh_token", refreshToken) + .build(); + + final Request request = new Request.Builder() + .url("https://oauth.example.com/token") + .post(body) + .build(); + + try (Response response = client.newCall(request).execute()) { + final JsonNode json = objectMapper.readTree(response.body().string()); + return json.get("access_token").asText(); + } + } + +API Key Authentication +---------------------- + +.. code-block:: java + + protected Response callApi(final String url, final String apiKey) { + final Request request = new Request.Builder() + .url(url) + .addHeader("Authorization", "Bearer " + apiKey) + .build(); + + return httpClient.newCall(request).execute(); + } + +Error Handling +============== + +For fatal errors that should abort processing, throw ``DataStoreException``. + +.. code-block:: java + + @Override + protected void storeData(...) { + try { + // Processing + } catch (final AuthenticationException e) { + logger.error("Authentication failed. Check your credentials.", e); + throw new DataStoreException("Authentication failed", e); + } catch (final RateLimitException e) { + logger.warn("Rate limit exceeded. Waiting..."); + sleep(60000L); + // Retry logic + } catch (final Exception e) { + logger.error("Unexpected error occurred", e); + throw new DataStoreException("Failed to crawl data", e); + } + } + +.. note:: + + In actual connectors such as ``fess-ds-example``, to avoid stopping the + entire crawl due to an error in a single record, ``CrawlingAccessException`` + is caught per record and the error URL is recorded in + ``FailureUrlService``. The interrupt flag of ``DataStoreCrawlingException`` + is also used to control whether to abort the entire crawl. When + implementing a robust connector, refer to the implementation of + ``ExampleDataStore``. + +Testing +======= + +Unit Testing +------------ + +|Fess| plugins are tested using UTFlute's ``LastaDiTestCase``. Tests are +written in JUnit 5 (Jupiter). By replacing ``IndexUpdateCallback`` with an +implementation that collects the registered ``dataMap``, you can verify the +mapping results without using a mock library. + +.. code-block:: java + + public class ExampleDataStoreTest extends LastaDiTestCase { + + public ExampleDataStore dataStore; + + @Override + protected String prepareConfigFile() { + return "test_app.xml"; + } + + @Override + public void setUp(final TestInfo testInfo) throws Exception { + super.setUp(testInfo); + dataStore = new ExampleDataStore(); + } + + @Test + public void test_getName() { + assertEquals("ExampleDataStore", dataStore.getName()); + } + + @Test + public void test_storeData() { + final TestIndexUpdateCallback callback = new TestIndexUpdateCallback(); + final DataStoreParams paramMap = new DataStoreParams(); + + final Map scriptMap = new HashMap<>(); + scriptMap.put("title", "title"); + + dataStore.storeData(new DataConfig(), callback, paramMap, scriptMap, new HashMap<>()); + + assertFalse(callback.getDataMapList().isEmpty()); + } + + // Test callback that collects the registered dataMap + private static class TestIndexUpdateCallback implements IndexUpdateCallback { + private final List> dataMapList = new ArrayList<>(); + + @Override + public void store(final DataStoreParams paramMap, final Map dataMap) { + dataMapList.add(new HashMap<>(dataMap)); + } + + @Override + public long getExecuteTime() { + return 0; + } + + @Override + public long getDocumentSize() { + return dataMapList.size(); + } + + @Override + public void commit() { + // Do nothing + } + + public List> getDataMapList() { + return dataMapList; + } + } + } + +.. note:: + + Since ``setUp`` is annotated with ``@BeforeEach`` in the base class, there + is no need to re-annotate the lifecycle annotation on the overriding side. + Add ``@Test`` (``org.junit.jupiter.api.Test``) to each test method. + +Build and Installation +======================= + +pom.xml +------- + +The plugin is built as a jar with ``fess-parent`` as the parent POM. +Dependencies on ``fess`` and ``opensearch`` are set to ``provided`` because +they are supplied by the |Fess| core at runtime. + +.. code-block:: xml + + + 4.0.0 + org.codelibs.fess + fess-ds-example + 15.10.0 + jar + + + org.codelibs.fess + fess-parent + 15.10.0 + + + + + + org.codelibs.fess + fess + provided + + + org.opensearch + opensearch + provided + + + + +JUnit 5 and ``org.dbflute.utflute:utflute-lastaflute`` are used for testing. + +Build +----- + +.. code-block:: bash + + mvn clean package + +``fess-ds-example-15.10.0.jar`` is generated in the ``target/`` directory. + +Installation +------------ + +Install the generated JAR into |Fess| and restart |Fess|. For details on the +installation procedure, see :doc:`../admin/plugin-guide`. After installation, +create a new configuration from "Crawler > Data Store" in the admin console, +and specify the name returned by ``getName()`` (``ExampleDataStore`` in this +example) as the "handler name". + +Configuration Example +====================== + +Example configuration in the admin console: + +Parameters +---------- + +In the "Parameters" field, describe the keys and values that the connector +reads from ``paramMap``. + +:: + + api.url=https://api.example.com/v1 + api.key=your_api_key + +Scripts +------- + +In the "Scripts" field, describe the mapping in the form +``left-hand side=right-hand side``. The left-hand side is the index field +name, and the right-hand side is a script (JavaScript for a newly created +configuration; a configuration that records no script type is treated as +Groovy) that +references a field of the source record. The following is an example where +the source record has the ``url`` / ``title`` / ``content`` / +``updated_at`` / ``content_type`` fields. + +:: + + url=url + title=title + content=content + last_modified=updated_at + mimetype=content_type + +.. note:: + + The field names that can be referenced on the right-hand side depend on + the values that the connector stores in ``resultMap`` (the values of + ``paramMap`` and the fields of the source record). Existing connectors + such as CSV and JSON may use a custom prefix such as ``data.*``, so refer + to the documentation for each connector. + +Reference +========= + +- :doc:`plugin-architecture` - Plugin Architecture +- :doc:`../admin/plugin-guide` - Plugin Installation +- :doc:`../config/datastore/ds-overview` - Data Store Connector Overview +- `fess-ds-example `__ - Data Store plugin implementation template +- `GitHub: fess-ds-* `__ - Examples of published connectors diff --git a/en/15.10/dev/index.rst b/en/15.10/dev/index.rst new file mode 100644 index 000000000..1e27f15ff --- /dev/null +++ b/en/15.10/dev/index.rst @@ -0,0 +1,28 @@ +================================== +|Fess| Developer Documentation +================================== + +Documentation for extending |Fess|. + +.. toctree:: + :maxdepth: 2 + :caption: Overview + + overview + +.. toctree:: + :maxdepth: 2 + :caption: Plugin Development + + plugin-architecture + datastore-plugin + script-engine-plugin + webapp-plugin + ingest-plugin + +.. toctree:: + :maxdepth: 2 + :caption: Customization + + theme-development + diff --git a/en/15.10/dev/ingest-plugin.rst b/en/15.10/dev/ingest-plugin.rst new file mode 100644 index 000000000..133bbfcae --- /dev/null +++ b/en/15.10/dev/ingest-plugin.rst @@ -0,0 +1,174 @@ +================================== +Ingest Plugin +================================== + +Overview +======== + +Ingest plugins provide functionality to process and transform data +immediately before a document is registered in the index. Each document +retrieved by a crawl passes through the registered Ingesters before it is +sent to the index. + +Use Cases +========= + +- Text normalization (full-width/half-width conversion, whitespace formatting, etc.) +- Adding metadata or custom fields +- Masking sensitive information +- Value conversion (e.g., decoding encoded vector embeddings) + +Ingester Class +============== + +Ingest functionality is implemented by extending the +``org.codelibs.fess.ingest.Ingester`` abstract class. ``Ingester`` provides +``process`` methods that are invoked depending on the type of crawl and the +processing stage. Since the default implementations simply return the +received ``target`` unchanged (i.e., do nothing), you only need to override +the methods you actually need. + +- ``protected Map process(Map target)`` + + This is the common delegation target for the two ``Map``-based methods. + Overriding this method applies it to documents from both data store crawls + and web/file crawls (at index registration time). For most use cases, + overriding only this method is sufficient. + +- ``public Map process(Map target, DataStoreParams params)`` + + Called during a data store crawl. By default, it delegates to + ``process(target)``. + +- ``public Map process(Map target, AccessResult accessResult)`` + + Called when registering a document from a web/file crawl into the index. + By default, it delegates to ``process(target)``. + +- ``public ResultData process(ResultData target, ResponseData responseData)`` + + Called during response processing of a web/file crawl (before the access + result is saved). By default, it returns ``target`` unchanged. + +Execution Order (priority) +--------------------------- + +When multiple Ingesters are registered, they are executed in ascending +order of the ``priority`` field (lower values run first). The default +value is ``99``. You can set it directly in the constructor, or change it +using ``setPriority(int)``. + +.. code-block:: java + + public int getPriority() + public void setPriority(final int priority) + +Implementation Example +======================= + +The following example overrides ``process(Map)`` to +normalize the content and add a custom field: + +.. code-block:: java + + package org.codelibs.fess.ingest.example; + + import java.util.Map; + + import org.codelibs.fess.ingest.Ingester; + + public class ExampleIngester extends Ingester { + + public ExampleIngester() { + // Set the execution order (lower values execute first; default is 99) + setPriority(50); + } + + @Override + protected Map process(final Map target) { + // Normalize the content + final Object content = target.get("content"); + if (content instanceof String) { + target.put("content", ((String) content).trim().replaceAll("\\s+", " ")); + } + + // Add a custom field + target.put("ingested_by", ExampleIngester.class.getSimpleName()); + + // Return the processed document + return target; + } + } + +.. note:: + + Returning ``null`` from the ``process`` method will cause index + registration to fail. There is no mechanism for skipping a document, + so always return ``target``. + +Registration +============ + +Ingesters are registered via the DI container. Include ``fess_ingest++.xml`` +in your plugin. The ``++`` suffix in the file name follows the merge +convention that appends the configuration to |Fess|'s own +``fess_ingest.xml`` (which defines the ``ingestFactory`` that manages +Ingesters). + +.. code-block:: xml + + + + + + + + + +With ````, ``Ingester#register()`` is +called after the component is created, registering itself with the +``ingestFactory``. + +There are no ``fess_config.properties`` settings related to the Ingest +functionality. Whether it is enabled or disabled is determined by whether +the plugin is installed, and the execution order is controlled by +``priority``. + +Execution Flow +============== + +Ingesters are called, in ascending order of ``priority``, immediately +before the processed document is sent to the index, at the following +points: + +- **Data store crawl**: ``process(Map, DataStoreParams)`` is called + immediately before the document is sent. +- **Web/file crawl (response processing)**: ``process(ResultData, + ResponseData)`` is called before the crawl result is saved. +- **Web/file crawl (index registration)**: ``process(Map, AccessResult)`` + is called immediately before the document is sent. + +In every case, if an Ingester throws an exception, a warning is logged and +processing continues (index registration of that document is not +interrupted). + +.. note:: + + Since Ingesters are registered in the crawler's runtime environment + (``ingestFactory``), they operate as part of the crawl process. + +Reference Implementations +========================== + +For reference, the following plugins are published on GitHub under +`CodeLibs `__: + +- ``fess-ingest-example`` - A minimal sample implementation +- ``fess-webapp-multimodal`` - A plugin that includes ``EmbeddingIngester``, which decodes vector embeddings + +References +========== + +- :doc:`plugin-architecture` - Plugin Architecture diff --git a/en/15.10/dev/overview.rst b/en/15.10/dev/overview.rst new file mode 100644 index 000000000..1bf8051c7 --- /dev/null +++ b/en/15.10/dev/overview.rst @@ -0,0 +1,236 @@ +================================== +Developer Documentation Overview +================================== + +Overview +======== + +This section explains extension development for |Fess|. +It provides information for extending |Fess|, including plugin development, +custom connector creation, and theme customization. + +Target Audience +================ + +- Developers who want to create custom features for |Fess| +- Developers who want to create plugins +- Developers who want to understand the |Fess| source code + +Prerequisites +------------- + +- Basic knowledge of Java 21 +- Basics of Maven (build system) +- Experience with web application development +- Basic knowledge of OpenSearch (|Fess| uses OpenSearch as its search engine) + +Development Environment +======================== + +Recommended Environment +------------------------ + +- **JDK**: OpenJDK 21 or higher +- **IDE**: IntelliJ IDEA / Eclipse / VS Code +- **Build Tool**: Maven (the build does not enforce a minimum version, but a recent 3.x release that supports Java 21 is recommended) +- **Git**: Version control +- **OpenSearch**: Search engine backend (when launching from the IDE, the required modules and plugins are downloaded during the build) + +Setup +----- + +|Fess| is built as a Maven project. During development, the easiest way is to launch it from an IDE. + +1. Get the source code: + + :: + + git clone https://github.com/codelibs/fess.git + +2. Import into the IDE: + + Import the cloned directory into your IDE as a Maven project. + +3. Download the OpenSearch modules and plugins: + + The first time only, run the following command to fetch the search engine's modules and plugins into the ``plugins`` directory. + + :: + + mvn antrun:run + +4. Start the development server (from the IDE): + + Run or debug ``org.codelibs.fess.FessBoot`` in your IDE, then open + http://localhost:8080/ in your browser. + The admin screen is at http://localhost:8080/admin/ (default account: ``admin`` / ``admin``). + +5. Build the package (create a distribution): + + If you need a distribution package, run the ``package`` goal. + The artifact is generated in ``target/releases`` (add ``-DskipTests`` to skip unit tests). + + :: + + mvn package + + After extracting the generated distribution, the ``bin/fess`` startup script becomes available. + + :: + + unzip target/releases/fess-*.zip + ./fess-*/bin/fess + +.. note:: + + The ``bin/fess`` startup script is included in the distribution packages (zip/rpm/deb). + Simply running ``mvn package`` in the source tree does not generate ``bin/fess`` at the + root of the repository. For development from source, either run ``FessBoot`` in your IDE + as described above, or use ``bin/fess`` from an extracted distribution. + +Architecture Overview +====================== + +|Fess| consists of the following major components: + +Component Structure +-------------------- + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Component + - Description + * - Web Layer + - MVC implementation using the LastaFlute framework + * - Service Layer + - Business logic + * - Data Access Layer + - Type-safe OpenSearch access using DBFlute (ESFlute/FreeGen) + * - Crawler + - Content collection using the fess-crawler library + * - Search Engine + - Full-text search using OpenSearch + +Major Frameworks +----------------- + +- **LastaFlute**: Web framework (actions, forms, validation) +- **DBFlute**: Data access framework. The type-safe access classes for OpenSearch + (``Bhv`` / ``ConditionBean``) are generated by DBFlute's FreeGen feature together with + ESFlute templates (regenerate with ``mvn dbflute:freegen``) +- **Lasta Di**: Dependency injection container + +Directory Structure +==================== + +:: + + fess/ + ├── src/main/java/org/codelibs/fess/ + │ ├── app/ + │ │ ├── web/ # Controllers (Action) + │ │ ├── service/ # Services + │ │ ├── logic/ # Logic + │ │ └── pager/ # Pagination + │ ├── api/ # REST API (api/v2, etc.) + │ ├── helper/ # Helper classes + │ ├── crawler/ # Crawler related + │ ├── indexer/ # Index processing + │ ├── opensearch/ # OpenSearch access (ESFlute/FreeGen generated) + │ ├── llm/ # LLM integration + │ ├── ds/ # DataStore connectors + │ ├── ingest/ # Ingest (data processing during indexing) + │ ├── script/ # Script engine + │ ├── entity/ # Entities + │ └── mylasta/ # LastaFlute configuration (DI, messages, type-safe settings) + ├── src/main/resources/ + │ ├── fess_config.properties # Configuration + │ └── fess_*.xml # DI configuration (app.xml, fess_ds.xml, etc.) + └── src/main/webapp/ + └── WEB-INF/view/ # JSPs of the admin and login screens + +Extension Points +================= + +|Fess| provides the following extension points: + +Plugins +------- + +You can add features using plugins. + +- **DataStore Plugin**: Crawl from new data sources (extend ``AbstractDataStore``) +- **Script Engine Plugin**: Support for new scripting languages (implement ``ScriptEngine``) +- **Web App Plugin**: Extend the web interface (override Lasta Di components and merge resources) +- **Ingest Plugin**: Process data during indexing (extend ``Ingester``) + +Details: :doc:`plugin-architecture` + +.. note:: + + The |Fess| core is packaged as a ``war``. When building a plugin locally, if |Fess| + cannot be resolved as a dependency, temporarily change ```` in ``pom.xml`` + to ``jar``, run ``mvn clean install -DskipTests``, and then change it back to ``war``. + +Themes +------ + +You can customize the design of the search screen. + +Details: :doc:`theme-development` + +Configuration +------------- + +Many behaviors can be customized via ``fess_config.properties``. + +Details: :doc:`../config/intro` + +Plugin Development +=================== + +For details on plugin development, see the following: + +- :doc:`plugin-architecture` - Plugin architecture +- :doc:`datastore-plugin` - DataStore plugin development +- :doc:`script-engine-plugin` - Script engine plugin +- :doc:`webapp-plugin` - Web app plugin +- :doc:`ingest-plugin` - Ingest plugin + +Theme Development +================== + +- :doc:`theme-development` - Theme customization + +Best Practices +================ + +Coding Standards +----------------- + +- Follow the existing |Fess| code style +- Format code with ``mvn formatter:format`` +- Add license headers with ``mvn license:format`` + +Testing +------- + +- Unit tests (``*Test.java``): Run as ``mvn test`` under the default ``build`` profile +- Integration tests (``*Tests.java``): Run via ``mvn test -P integrationTests``. + Running integration tests requires a running |Fess| server and OpenSearch + +Logging +------- + +- Uses Log4j2 +- ``logger.debug()`` / ``logger.info()`` / ``logger.warn()`` / ``logger.error()`` +- Do not log sensitive information + +Resources +========= + +- `GitHub Repository `__ +- `Issue Tracker `__ +- `Discussions `__ diff --git a/en/15.10/dev/plugin-architecture.rst b/en/15.10/dev/plugin-architecture.rst new file mode 100644 index 000000000..2d75bffdd --- /dev/null +++ b/en/15.10/dev/plugin-architecture.rst @@ -0,0 +1,387 @@ +================================== +Plugin Architecture +================================== + +Overview +======== + +The |Fess| plugin system lets you extend core functionality. +Plugins are distributed as JAR files, and once added to the classpath, +their components are loaded by the DI container (Lasta Di) and +registered with the corresponding factory or manager. + +Plugin Types +============ + +|Fess| determines the plugin type from the prefix of the artifact name +(``PluginHelper.ArtifactType``). The main types are as follows: + +.. list-table:: + :header-rows: 1 + :widths: 20 25 55 + + * - Type + - Prefix + - Description + * - Data Store + - ``fess-ds-*`` + - Retrieves content from new data sources (Box, Slack, Git, etc.) + * - Web App + - ``fess-webapp-*`` + - Extends the web interface and search functionality + * - Script Engine + - ``fess-script-*`` + - Adds support for new scripting languages + * - Ingest + - ``fess-ingest-*`` + - Processes documents during index registration + * - Thumbnail + - ``fess-thumbnail-*`` + - Adds new thumbnail generation methods + * - LLM + - ``fess-llm-*`` + - Adds LLM providers used for RAG/chat + * - Crawler + - ``fess-crawler-*`` + - Extends crawler clients + * - Storage + - ``fess-storage-*`` + - Adds an object storage backend for crawling and for the storage feature + * - SSO + - ``fess-sso-*`` + - Adds a single sign-on authenticator selected by ``sso.type`` + +.. note:: + + The ``fess-theme-*`` (JAR theme) type, which supplied JSPs, was removed in 15.10. + Change the look of the search screen with a static theme, not a plugin + (see :doc:`theme-development`). + +Plugin Structure +================= + +Basic Structure +---------------- + +Taking `fess-ds-example `__, +the implementation template for Data Store plugins, as an example, a +plugin consists of an "implementation class" and a "DI registration +file": + +:: + + fess-ds-example/ + ├── pom.xml + └── src/main/ + ├── java/org/codelibs/fess/ds/example/ + │ └── ExampleDataStore.java # Data Store implementation + └── resources/ + └── fess_ds++.xml # DI component registration + +pom.xml Example +----------------- + +The plugin is built as a jar with ``fess-parent`` as the parent POM. +Libraries such as ``fess`` and ``opensearch``, which are supplied by +the |Fess| core at runtime, are declared with ``provided`` scope. +Version numbers and build settings (formatter, license header, etc.) +are inherited from the parent POM. + +.. code-block:: xml + + + + 4.0.0 + + org.codelibs.fess + fess-ds-example + 15.10.0 + jar + + + org.codelibs.fess + fess-parent + 15.10.0 + + + + + + org.codelibs.fess + fess + provided + + + org.opensearch + opensearch + provided + + + + +.. note:: + + On branches under development, the version has a ``-SNAPSHOT`` + suffix, such as ``15.10.0-SNAPSHOT``. Dependencies specific to the + plugin are declared as ordinary Maven dependencies. Since these are + not bundled with the |Fess| core, they must be distributed together + with the plugin. + +Plugin Registration +===================== + +Registering with the DI Container +------------------------------------ + +Plugins register components using a DI configuration file whose name +ends in ``++``, such as ``fess_ds++.xml``. Lasta Di automatically +merges any file with a ``++`` suffix found on the classpath into the +corresponding configuration file in the |Fess| core (``fess_ds.xml`` +in this example). This mechanism lets a plugin add its own components +without modifying any file in the |Fess| core. + +.. code-block:: xml + + + + + + + + + +The target file for merging differs depending on the plugin type. For +example, Script Engine plugins use ``fess_se++.xml``, Ingest plugins +use ``fess_ingest++.xml``, LLM providers use ``fess_llm++.xml``, and +Web App plugins use ``app++.xml``. + +Component Initialization +-------------------------- + +```` is a Lasta Di lifecycle setting +that specifies the method to invoke after the component is created. +In the case of a Data Store, the ``register()`` method provided by +``AbstractDataStore`` is invoked, which registers the component itself +with the ``DataStoreFactory``: + +.. code-block:: java + + // Implementation in AbstractDataStore (normally no need to override) + public void register() { + ComponentUtil.getDataStoreFactory().add(getName(), this); + } + +.. note:: + + Note that this is not Java's ``@PostConstruct`` annotation, but + initialization via the ```` element in the DI + configuration file. The name registered here is the return value of + ``getName()``, and this becomes the name used when selecting the + plugin in the admin console. + +Plugin Lifecycle +================== + +Initialization +---------------- + +1. The plugin JAR is added to the classpath +2. The DI container merges ``fess_*++.xml`` and creates the components +3. The method specified in ```` (e.g., ``register``) is + invoked +4. The plugin is registered with the corresponding factory/manager + +Termination +------------ + +1. When the DI container shuts down, the method specified in + ```` is invoked (if defined) +2. Resources are cleaned up + +.. note:: + + In the case of a Data Store, an in-progress crawl has its stop flag + set by ``AbstractDataStore.stop()``, which allows the record + processing loop to terminate safely. + +Dependencies +============= + +Dependency on the Fess Core +----------------------------- + +Since classes in the |Fess| core are present on the server's classpath +at runtime, declare the dependency with ``provided`` scope (do not +bundle it into the plugin JAR). + +.. code-block:: xml + + + org.codelibs.fess + fess + provided + + +External Libraries +-------------------- + +A plugin can include its own dependency libraries: + +.. code-block:: xml + + + com.example + example-sdk + 1.0.0 + + +Since these are not bundled with the |Fess| core, they must be +distributed together with the plugin. + +Retrieving Configuration +========================== + +Retrieving Parameters and FessConfig +-------------------------------------- + +In a Data Store's ``storeData()``, parameters configured in the admin +console are retrieved from ``DataStoreParams``. Use ``getAsString()`` +to retrieve values (since ``DataStoreParams`` does not implement +``Map``, ``get()`` does not return a string). |Fess| configuration +values can also be retrieved from ``ComponentUtil.getFessConfig()``: + +.. code-block:: java + + public class ExampleDataStore extends AbstractDataStore { + + @Override + protected String getName() { + // Used as the handler name. Convention is to return the class's simple name + return this.getClass().getSimpleName(); + } + + @Override + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { + + // Retrieve parameters + final String apiKey = paramMap.getAsString("api.key"); + final String baseUrl = paramMap.getAsString("base.url"); + + // Retrieve FessConfig + final FessConfig fessConfig = ComponentUtil.getFessConfig(); + } + } + +For details on how to implement ``storeData()`` (the flow of data +retrieval, script evaluation, and index registration), see +:doc:`datastore-plugin`. + +Build and Installation +======================== + +Build +------ + +:: + + mvn clean package + +A JAR file (e.g., ``fess-ds-example-15.10.0.jar``) is generated in the +``target/`` directory. + +Installation +------------- + +1. **From the admin console**: + + - Open "System" -> "Plugin" -> "Install" + - Select from the list of plugin repositories, or upload and + install the JAR file you built + +2. **Manually**: + + - Copy the JAR file to the ``app/WEB-INF/plugin/`` directory + - Restart |Fess| + +For details on the installation procedure, see +:doc:`../admin/plugin-guide`. + +Debugging +========== + +Logging +-------- + +|Fess| uses Log4j2. Obtain a logger with ``LogManager.getLogger()``: + +.. code-block:: java + + private static final Logger logger = LogManager.getLogger(ExampleDataStore.class); + + public void someMethod() { + logger.debug("Debug message"); + logger.info("Info message"); + } + +.. note:: + + Do not output sensitive information such as passwords or tokens to + the log. + +Development Mode +------------------ + +During development, you can start |Fess| from your IDE for debugging: + +1. Debug-run the ``org.codelibs.fess.FessBoot`` class +2. Include the plugin's source code in the project +3. Set breakpoints + +List of Published Plugins +=========================== + +Many plugins are published by the |Fess| project. The following are +representative examples (this is not an exhaustive list): + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Plugin + - Description + * - ``fess-ds-box`` + - Box connector + * - ``fess-ds-dropbox`` + - Dropbox connector + * - ``fess-ds-slack`` + - Slack connector + * - ``fess-ds-atlassian`` + - JIRA / Confluence connector + * - ``fess-ds-git`` + - Git repository connector + * - ``fess-llm-openai`` + - OpenAI LLM provider + +In addition, Data Store connectors such as ``fess-ds-csv`` / +``fess-ds-db`` / ``fess-ds-json`` / ``fess-ds-microsoft365`` / +``fess-ds-sharepoint``, and LLM providers such as ``fess-llm-ollama`` / +``fess-llm-gemini`` / ``fess-llm-bedrock``, are also published. These plugins are published +on `GitHub `__ as a reference for +development. + +Reference +========== + +- :doc:`datastore-plugin` - Data Store plugin development +- :doc:`script-engine-plugin` - Script Engine plugin +- :doc:`webapp-plugin` - Web App plugin +- :doc:`ingest-plugin` - Ingest plugin +- :doc:`theme-development` - Theme customization +- :doc:`../admin/plugin-guide` - Plugin installation + diff --git a/en/15.10/dev/script-engine-plugin.rst b/en/15.10/dev/script-engine-plugin.rst new file mode 100644 index 000000000..b78ef2018 --- /dev/null +++ b/en/15.10/dev/script-engine-plugin.rst @@ -0,0 +1,62 @@ +================================== +Script Engine Plugin +================================== + +Overview +======== + +By developing a Script Engine plugin, you can add support for new scripting +languages to |Fess|. + +Basic Implementation +==================== + +Implement the ``ScriptEngine`` interface: + +.. code-block:: java + + package org.codelibs.fess.script.example; + + import org.codelibs.fess.script.ScriptEngine; + import java.util.Map; + + public class ExampleScriptEngine implements ScriptEngine { + + @Override + public String getName() { + return "example"; + } + + @Override + public Object evaluate(String script, Map params) { + // Script evaluation logic + return executeScript(script, params); + } + } + +Registration +============ + +.. code-block:: java + + @PostConstruct + public void register() { + ComponentUtil.getScriptEngineManager().add(this); + } + +Usage Example +============= + +Select as script type in admin console: + +:: + + scriptType=example + scriptData=your script here + +Reference +========= + +- :doc:`plugin-architecture` - Plugin Architecture +- :doc:`../config/scripting-overview` - Scripting Overview + diff --git a/en/15.10/dev/theme-development.rst b/en/15.10/dev/theme-development.rst new file mode 100644 index 000000000..86f32f88b --- /dev/null +++ b/en/15.10/dev/theme-development.rst @@ -0,0 +1,334 @@ +================================== +Theme Development Guide +================================== + +Overview +======== + +In |Fess| 15.10, the search screen is always a static theme. A static +theme is an independent SPA (Single Page Application) that uses the +``/api/v2/*`` API. Themes are distributed as ZIP files, uploaded +through the admin console, and enabled there. When no theme is +selected, |Fess| uses ``bootstrap``, the static theme bundled with it. + +To change how the search screen looks, either install another theme +(see :doc:`../admin/theme-guide`) or make your own: the quickest way +is to copy the bundled theme and change the copy, as described in +`Customizing the Bundled Theme`_. + +.. note:: + + Static themes are available in |Fess| 15.7 and later, and became the + default search screen in 15.10. JAR theme plugins, which replaced the + JSPs of the search screen, were removed in 15.10; see + `JAR Theme Plugin (Removed in 15.10)`_. + +Static Theme +============ + +A static theme is a collection of static resources that includes a +``theme.yml`` manifest and ``index.html``. Implement the theme itself +as a front-end application that calls the |Fess| ``/api/v2/*`` API. + +Structure +--------- + +A static theme has the following directory structure. + +:: + + example/ + ├── theme.yml # Manifest (required) + ├── index.html # SPA entry HTML + ├── assets/ # Static resources such as JavaScript and CSS + │ └── styles.css + ├── i18n/ # Localized messages (messages..json) + │ └── messages.en.json + ├── help/ # Help definitions (.json) + │ └── en.json + └── thumbnail.png # Preview image (optional) + +Manifest (theme.yml) +-------------------- + +``theme.yml`` is a required manifest placed at the root of the ZIP +file. The following is an example of a minimal configuration. + +.. code-block:: yaml + + apiVersion: fess.codelibs.org/v1 + kind: StaticTheme + name: example + displayName: "Example Theme" + version: "15.10.0" + minFessVersion: "15.10" + entry: index.html + spaFallback: true + +The fields that can be specified are as follows. + +.. list-table:: + :header-rows: 1 + :widths: 22 12 66 + + * - Field + - Required + - Description + * - ``apiVersion`` + - Required + - Fixed value ``fess.codelibs.org/v1``. + * - ``kind`` + - Required + - Fixed value ``StaticTheme``. + * - ``name`` + - Required + - The theme name. Must match ``^[a-z0-9][a-z0-9_-]{0,63}$``. It is + used for the directory name the theme is expanded into under + ``themes/`` (when uploading, this is determined automatically + from ``name``), and for the delivery URL (``/themes//``). + * - ``displayName`` + - Required + - The name displayed in the admin console. + * - ``version`` + - Required + - Semantic versioning format (e.g., ``15.10.0``, ``15.10.1-beta.1``). By convention the + ``major.minor`` is the |Fess| line the theme targets, so that the version alone answers + which |Fess| a theme is for. + * - ``author`` + - Optional + - The author's name. + * - ``description`` + - Optional + - A description of the theme. + * - ``license`` + - Optional + - The license. + * - ``homepage`` + - Optional + - The homepage URL. + * - ``minFessVersion`` + - Optional + - The minimum |Fess| version the theme supports. Keep it equal to the ``major.minor`` of + ``version``. There is no ``maxFessVersion``: see `Publishing`_. + * - ``supportedLocales`` + - Optional + - A list of supported locales (e.g., ``[en, ja, de]``). + * - ``entry`` + - Optional + - The SPA entry HTML. Defaults to ``index.html``. + * - ``spaFallback`` + - Optional + - Deprecated. Accepted for compatibility but no longer read: since + 15.10 the entry HTML is always served for the search screen paths. + +.. note:: + + When uploading via ZIP, the destination directory name is + determined automatically from ``name``. If you place a theme + manually in the ``themes/`` directory, make sure the directory name + matches ``name``. Themes whose directory name does not match are + ignored on rescan. + +.. note:: + + The preview thumbnail is placed at the root of the theme with the + fixed name ``thumbnail.png`` (it is displayed in the theme list in + the admin console). This image is recognized by its file name, not + by a manifest field. A size of 512KB or less and 512x512 pixels or + less is recommended. + +Serving and API +--------------- + +- A static theme is served under ``/themes//`` (```` is + the ``name`` in ``theme.yml``). +- The entry HTML (``index.html`` by default) is returned for the paths + ``/``, ``/search``, ``/advance``, ``/help``, ``/error``, ``/profile``, + ``/cache``, and ``/chat``, and subsequent routing is handled by the + SPA. Since 15.10 this happens whatever ``spaFallback`` says; the field + is no longer read. +- Errors are rendered by the theme as well: when a request fails, a + browser receives the theme's entry HTML at the requested URL, with the + real HTTP status. +- The admin console (``/admin/*``), ``/api/*``, the login screen, and + similar are not covered by the static theme and are handled by the + |Fess| core. +- ``{{themePath}}`` in the entry HTML is replaced with ``themes/`` + when the page is served. Refer to the theme's own files from + ``index.html`` as ``{{themePath}}/assets/styles.css`` and so on. The + theme name is then not written into the page, so the theme loads its + own files under whatever name it is installed. +- The entry HTML is served with a ``Content-Security-Policy`` header that + allows scripts, styles, images and connections only from |Fess| + itself (inline styles are allowed; inline scripts are not). Fonts or + scripts from an external CDN are therefore not loaded; ship them in the + theme. +- The ``Content-Security-Policy`` of the entry HTML contains + ``frame-ancestors 'none'``, and the response also carries + ``X-Frame-Options: DENY``, so the page is not shown in a frame of + another page. The ``frame-ancestors`` value can be changed with + ``theme.index.frame.ancestors`` in ``fess_config.properties`` + (default: ``'none'``). An empty value drops ``frame-ancestors`` + (``X-Frame-Options: DENY`` is still sent). Under + ``frame-ancestors 'none'``, WebKit-based browsers such as Safari leave + blank the frames that a theme shows from a ``blob:`` URL (a PDF + preview or a cached copy). Set the value to empty to show them. +- The theme's SPA retrieves data such as search results and chat from + the ``/api/v2/*`` API. + +Packaging +--------- + +Using ``scripts/package.sh`` from the +`fess-themes `__ repository, +you can package a theme into a ZIP for distribution. + +:: + + ./scripts/package.sh example + +``dist/example-.zip`` is generated (```` is the +``version`` in ``theme.yml``). + +.. note:: + + ``theme.yml`` must be placed at the root of the ZIP. If it is + placed in a subdirectory, it will not be recognized when uploaded. + +Publishing +---------- + +The themes the |Fess| project develops are published under +https://maven.codelibs.org/release/org/codelibs/fess/themes/ , at +``//-.zip`` with a ``.sha1`` beside it, and a per-theme +``maven-metadata.xml`` listing the published versions. ``bin/fess-setup install theme `` +reads that metadata to pick the version built for the running |Fess|. + +Version a theme on the |Fess| line it targets and raise the version whenever you change what the +archive ships. A published version is never overwritten, so a change that keeps its version is +simply never distributed. + +This is also why there is no upper-bound field in the manifest. Because a published archive never +changes, an upper bound could not be added later for a theme that stops working on a newer |Fess|. +Not publishing that theme for the newer line says the same thing, at the point it is known. + +.. note:: + + Enumerate the published versions from ``maven-metadata.xml`` rather than from a directory + listing. The directory index is generated periodically, so a newly published theme is readable + through its metadata before it appears in any listing. + +Installation and Activation +---------------------------- + +1. In the admin console, open "System" -> "Theme" (``/admin/theme/``). +2. Upload the ZIP file you created. A published theme can instead be installed from the command + line with ``bin/fess-setup install theme ``; see :doc:`../install/fess-setup`. +3. On the list page, select the target theme from the "Default Theme" + drop-down and click the "Set" button to enable it. + +The activation mechanism works as follows. + +- Clicking "Set" saves the selected theme name to the + ``theme.default`` system property, making it the system-wide default + theme. +- If you match the theme name to a virtual host key, the theme is + applied only when that virtual host is accessed. This lets you + switch themes per virtual host. +- If you update the ``themes/`` directory on disk directly, you can + rescan it with "Reload". + +.. note:: + + There are limits on ZIP uploads, such as file size, total size + after extraction, and number of entries, which can be adjusted with + the ``theme.*`` properties in ``fess_config.properties`` (for + example, ``theme.upload.max.size`` defaults to 50MB, and + ``theme.directory.path`` defaults to ``themes``). During extraction, + validation is performed to prevent ZIP Slip and zip bomb attacks. + +.. _theme-customize-bundled: + +Customizing the Bundled Theme +----------------------------- + +The bundled theme ``bootstrap`` is in ``app/themes/bootstrap/`` of the +|Fess| installation (``/usr/share/fess/app/themes/bootstrap/`` for the +RPM/DEB packages). Do not edit it in place: an upgrade replaces it, and +the name ``bootstrap`` is reserved for it, so it can be neither deleted +nor replaced by an upload. Copy it under a new name instead. + +1. Copy the directory, for example to ``mytheme``:: + + $ cp -r app/themes/bootstrap /tmp/mytheme + +2. In ``theme.yml``, change ``name`` to ``mytheme`` and change + ``displayName``. ``name`` must match the directory name. + +3. Leave ``index.html`` as it is. The bundled ``index.html`` refers to + its own files, such as the stylesheet, the logos and the script, as + ``{{themePath}}/assets/...``, and |Fess| replaces ``{{themePath}}`` + with ``themes/`` (the ``name`` in ``theme.yml``) when it serves + the page. Renaming the copy is therefore enough for it to load its own + files. When you add a file that ``index.html`` refers to, write its + URL as ``{{themePath}}/assets/...`` as well. + +4. Make your changes: + + - Colors and layout: ``assets/styles.css``. + - Logos: ``assets/logo-head.png`` (header) and ``assets/logo.png`` + (search top page). + - Texts, such as the footer (``footer.copyright_org``): the + ``i18n/messages..json`` files, one per language. + - Page structure: ``index.html``. + +5. Package the directory as a ZIP with ``theme.yml`` at its root, and + upload it on "System" > "Theme" in the admin console:: + + $ cd /tmp/mytheme && zip -r ../mytheme.zip . + + Alternatively, place the directory in ``app/themes/`` and click + "Reload" on the same page. + +6. Select ``mytheme`` as the default theme on that page. + +.. note:: + + Replace the copy with a fresh one from the bundled theme after each + |Fess| upgrade and reapply your changes, as the bundled theme follows + the ``/api/v2/*`` API of its |Fess| version. + +JAR Theme Plugin (Removed in 15.10) +================================== + +The JAR theme plugin type, which put JSPs, CSS and images in a ``fess-theme-*`` JAR and +applied them as the theme named after a virtual host key, was removed in |Fess| 15.10. +15.10 does not extract a JAR theme and does not use it for any screen. + +- Installing one from "System" > "Plugin" in the admin UI only places it in + ``app/WEB-INF/plugin/`` as a generic JAR of type ``jar``; no screen changes. A + ``fess-theme-*.jar`` left over from an earlier version is listed the same way, and can be + deleted on that page or with ``bin/fess-setup remove plugin ``. +- ``bin/fess-setup`` neither lists nor installs ``fess-theme-*``. + +Move the changes you made in a JAR theme to a static theme: + +- For the colors, layout and logo of the search screen, copy the bundled theme and change + the copy (see `Customizing the Bundled Theme`_). +- If you changed the look per virtual host, install a static theme named after the + virtual host (see :doc:`../config/security-virtual-host`). +- The login screen (``/login/``) is the same for every virtual host. A theme cannot + change it. + +Examples of Existing Themes +============================ + +- `fess-themes `__ - A + collection of static themes (includes multiple static themes such as + ``codesearch`` and ``docsearch``) + +Reference +========= + +- :doc:`plugin-architecture` - Plugin architecture +- :doc:`../admin/plugin-guide` - Plugin installation diff --git a/en/15.10/dev/webapp-plugin.rst b/en/15.10/dev/webapp-plugin.rst new file mode 100644 index 000000000..f72dfe3f8 --- /dev/null +++ b/en/15.10/dev/webapp-plugin.rst @@ -0,0 +1,327 @@ +================================== +Web App Plugin +================================== + +Overview +======== + +Web App plugins (``fess-webapp-*``) extend the |Fess| web application. +Unlike other plugin types, they do not add Action classes or JSPs +directly; instead, they extend functionality by **adding or replacing +components** in the DI container (Lasta Di). Typical use cases +include: + +- Adding new components (helpers, services, etc.) +- Replacing components in the |Fess| core (via subclassing) +- Adding REST API endpoints (``WebApiManager``) +- Extending search behavior (query commands, rank fusion, etc.) + +.. note:: + + Web App plugins are distributed as JAR files, and their internal + classes and DI configuration files are loaded onto the classpath of + the |Fess| web application. They do not add JSP views. If you want + to customize the design of the search screen, see + :doc:`theme-development`. + +Basic Structure +=============== + +Taking `fess-webapp-example `__, +the implementation template for Web App plugins, as an example, a +plugin consists of an "implementation class" and a "DI registration +file": + +:: + + fess-webapp-example/ + ├── pom.xml + └── src/main/ + ├── java/org/codelibs/fess/webapp/example/helper/ + │ ├── ExampleHelper.java # Component to add + │ └── CustomSystemHelper.java # Replacement for a core component + └── resources/ + ├── app++.xml # Adds components (merge) + └── fess+systemHelper.xml # Replaces a component + +.. note:: + + The implementation class package uses + ``org.codelibs.fess.webapp.``. DI configuration files + are placed under ``src/main/resources/``. Unlike Data Store + plugins, there is no ``src/main/webapp/`` directory or JSP files. + +pom.xml and Manifest +===================== + +Web App plugins are built as a jar with ``fess-parent`` as the parent +POM. Libraries such as ``fess`` and ``opensearch``, which are supplied +by the |Fess| core at runtime, are declared with ``provided`` scope, +while libraries required at runtime such as ``lastaflute``, +``dbflute-runtime``, and ``corelib`` are declared with normal scope. + +The most important part of a Web App plugin is adding +``Fess-WebAppJar: true`` to the JAR manifest. This declaration tells +|Fess| to mount the plugin's classes and DI configuration files onto +the web application's classloader. This is configured via the +``maven-jar-plugin``: + +.. code-block:: xml + + + + + maven-jar-plugin + + + + true + + + + + + + +.. warning:: + + If ``Fess-WebAppJar: true`` is not set, the plugin's classes and DI + configuration files will not be loaded onto the web application's + classpath, and component addition/replacement will not take + effect. + +For the overall structure of pom.xml (parent POM, how to declare +dependencies, etc.), see :doc:`plugin-architecture`. + +Extension Patterns +================== + +Adding Components (app++.xml) +------------------------------ + +The most basic way to extend the plugin is to add your own +components. Lasta Di **merges** ``app++.xml`` found on the classpath +into the ``app`` namespace built from the |Fess| core's ``app.xml`` +(the trailing ``++`` is the convention for an additive merge). Since +the components you add use names that do not exist in the |Fess| +core, nothing is overwritten. + +.. code-block:: xml + + + + + + + + +In the component implementation, use ``@PostConstruct`` for +initialization, and retrieve and reuse |Fess| core components via +``ComponentUtil`` (do not copy or override them): + +.. code-block:: java + + package org.codelibs.fess.webapp.example.helper; + + import org.codelibs.fess.helper.SystemHelper; + import org.codelibs.fess.util.ComponentUtil; + + import jakarta.annotation.PostConstruct; + + public class ExampleHelper { + + protected String pluginName = "fess-webapp-example"; + + @PostConstruct + public void init() { + // Initialization logic invoked once after creation by DI + } + + public String getPluginLabel() { + // Reuse the core SystemHelper to get the running Fess version + final SystemHelper systemHelper = ComponentUtil.getSystemHelper(); + final String version = systemHelper != null ? systemHelper.getProductVersion() : "unknown"; + return pluginName + " (Fess " + version + ")"; + } + } + +.. tip:: + + Consider this "component addition" approach first. Unless you need + to change core functionality, it is safer and easier to maintain + than replacement. + +Replacing Core Components (fess+componentName.xml) +---------------------------------------------------- + +If you want to change the behavior of a |Fess| core component, +subclass the target class and **re-register it under the same +component name** in a DI configuration file named +``+.xml``. For example, since ``systemHelper`` +is declared in the |Fess| core's ``fess.xml``, the replacement file is +``fess+systemHelper.xml`` (not ``app+systemHelper.xml``). + +.. code-block:: java + + package org.codelibs.fess.webapp.example.helper; + + import java.nio.file.Path; + + import org.codelibs.fess.helper.SystemHelper; + + public class CustomSystemHelper extends SystemHelper { + + @Override + protected void parseProjectProperties(final Path propPath) { + try { + super.parseProjectProperties(propPath); + } catch (final Exception e) { + // Custom handling + } + System.setProperty("fess.webapp.plugin", "true"); + } + } + +.. warning:: + + Replacement (a single ``+``) replaces the component definition + **in its entirety**. This means the replacement file must include + every ```` entry that the core definition performs + (for example, ``queryHelper`` in ``app.xml``). These must be kept in + sync with each |Fess| release. If the file keeps calling a method + that the core removed, the component definition fails to initialize + with a ``BeanMethodNotFoundException``. For example, 15.10 removed + ``addDesignJspFileName`` from ``systemHelper``, so a replacement file + that still calls it fails. This maintenance cost is why addition is + recommended over replacement. + +Adding a REST API (fess_api++.xml) +------------------------------------ + +To add a new REST API endpoint, implement ``WebApiManager``. Extend +``BaseApiManager`` and register itself with the +``WebApiManagerFactory`` in ``@PostConstruct``. The registered API +manager is invoked by ``WebApiFilter`` for every request. Register the +component in ``fess_api++.xml``: + +.. code-block:: xml + + + + + + + + +.. code-block:: java + + package org.codelibs.fess.webapp.example.api; + + import java.io.IOException; + + import org.codelibs.fess.api.BaseApiManager; + import org.codelibs.fess.util.ComponentUtil; + + import jakarta.annotation.PostConstruct; + import jakarta.servlet.FilterChain; + import jakarta.servlet.ServletException; + import jakarta.servlet.http.HttpServletRequest; + import jakarta.servlet.http.HttpServletResponse; + + public class ExampleApiManager extends BaseApiManager { + + public ExampleApiManager() { + // Path prefix handled by this manager + setPathPrefix("/api/example"); + } + + @PostConstruct + public void register() { + ComponentUtil.getWebApiManagerFactory().add(this); + } + + @Override + public boolean matches(final HttpServletRequest request) { + // Determine whether this manager should handle the request + return request.getServletPath().startsWith(pathPrefix); + } + + @Override + public void process(final HttpServletRequest request, final HttpServletResponse response, + final FilterChain chain) throws IOException, ServletException { + // Process the request and write the response + } + + @Override + protected void writeHeaders(final HttpServletResponse response) { + // Set response headers (as needed) + } + } + +For implementation examples, see +`fess-webapp-v1-api `__, +which provides ``/api/v1``, and +`fess-webapp-classic-api `__, +which provides ``/json`` / ``/suggest``. + +Customizing the Search Screen +============================== + +Web App plugins cannot add JSP views. JSP views are located under +``WEB-INF/view/`` in the |Fess| core WAR, while plugin JARs are mounted +onto the classpath (``WEB-INF/classes``). To change the design of the +search screen, use a static theme, which customizes the design +(HTML/CSS/JavaScript) of the search screen. See :doc:`theme-development`. + +Build and Installation +======================== + +:: + + mvn clean package + +A JAR file (e.g., ``fess-webapp-example-15.10.0.jar``) is generated in +the ``target/`` directory. Install the generated JAR from the admin +console, or place it in the ``app/WEB-INF/plugin/`` directory and +restart |Fess|. For details on the installation procedure, see +:doc:`../admin/plugin-guide`. + +Examples of Published Plugins +=============================== + +The |Fess| project publishes the following Web App plugins. They are +published on `GitHub `__ as a reference +for development: + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Plugin + - Description + * - ``fess-webapp-example`` + - Plugin implementation template + * - ``fess-webapp-v1-api`` + - ``/api/v1`` REST API + * - ``fess-webapp-classic-api`` + - Legacy REST API for ``/json`` / ``/suggest`` + * - ``fess-webapp-mcp`` + - MCP (Model Context Protocol) server + * - ``fess-webapp-bangs`` + - DuckDuckGo-style bangs (``!g``) that send a search to another site + * - ``fess-webapp-semantic-search`` + - Neural search / vector search (deprecated; superseded by the core integration in 15.10) + * - ``fess-webapp-multimodal`` + - Multimodal (image/text) search + +Reference +========= + +- :doc:`plugin-architecture` - Plugin Architecture +- :doc:`theme-development` - Theme customization +- :doc:`../admin/plugin-guide` - Plugin installation +- :doc:`overview` - Developer Documentation Overview diff --git a/en/15.10/install/fess-setup.rst b/en/15.10/install/fess-setup.rst new file mode 100644 index 000000000..1ef226b06 --- /dev/null +++ b/en/15.10/install/fess-setup.rst @@ -0,0 +1,336 @@ +================== +fess-setup Command +================== + +``bin/fess-setup`` (``bin\fess-setup.bat`` on Windows) is included with the |Fess| ZIP package. +It installs what |Fess| needs but does not bundle: OpenSearch with the plugins |Fess| requires, +Node.js for the Playwright plugins, |Fess| plugins, and static themes. It also reports on an +installation. + +Run it from the |Fess| directory. Without arguments, it prints the list of commands. + +:: + + $ cd /path/to/fess-15.10.0 + $ bin/fess-setup [options] + +Exit Codes +========== + +.. list-table:: + :header-rows: 1 + :widths: 15 85 + + * - Code + - Meaning + * - ``0`` + - The command succeeded. + * - ``1`` + - The command failed: for example, a download failed, the requested version does not exist, + OpenSearch publishes no build for this platform, or ``check`` found a problem. + * - ``2`` + - The command line is wrong: an unknown command, or a missing argument such as a plugin name. + +Installing OpenSearch and Node.js +================================= + +install opensearch +------------------ + +:: + + $ bin/fess-setup install opensearch [--dest ] [--version ] [--keep-bundled-plugins] + +Downloads the OpenSearch version this |Fess| supports into ``opensearch/`` in the |Fess| directory, +installs the four plugins |Fess| requires (``opensearch-analysis-fess``, +``opensearch-analysis-extension``, ``opensearch-minhash`` and ``opensearch-configsync``), and +appends the following settings to its ``config/opensearch.yml``: + +- ``configsync.config_path``, set to the ``config/dictionary`` directory of that OpenSearch +- ``plugins.security.disabled: true`` + +It also removes ``opensearch-security-analytics`` and ``opensearch-performance-analyzer``, +bundled plugins that |Fess| does not use, as the OpenSearch in the Docker image does not have them +either. A plugin the download does not include is skipped. + +A setting that ``opensearch.yml`` already has is not added again, and +``plugins.security.disabled: true`` is not added when the file has any ``plugins.security.*`` +setting. When the OpenSearch directory already exists, the download is skipped, so running the +command again on an existing installation only adds the settings that are missing. + +The command prints each setting it added, and then whether ``bin/fess.in.sh`` finds this OpenSearch +on its own. It does when this is the only OpenSearch with a ``config/dictionary`` directory under +``opensearch/`` in the |Fess| directory: ``bin/fess.in.sh`` (``bin\fess.in.bat`` on Windows) then +sets ``FESS_DICTIONARY_PATH`` to that directory, and nothing else needs to be configured for an +OpenSearch on the same host. Otherwise the command prints the ``SEARCH_ENGINE_HTTP_URL`` and +``FESS_DICTIONARY_PATH`` values to set, as described in :doc:`install-linux` or +:doc:`install-windows`. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Option + - Description + * - ``--dest `` + - The directory to extract OpenSearch into, instead of ``opensearch/`` in the |Fess| + directory. ``bin/fess.in.sh`` does not look for OpenSearch outside that directory. + * - ``--version `` + - The OpenSearch version to install. The plugins are installed at the same version. + * - ``--keep-bundled-plugins`` + - Keeps the bundled plugins (``opensearch-security-analytics`` and ``opensearch-performance-analyzer``) instead of removing them, leaving the download as shipped. + +OpenSearch publishes official builds for Linux and Windows only. On other platforms, such as macOS, +the command exits with code ``1`` before downloading anything and suggests installing OpenSearch +with Homebrew and adding the plugins with ``install opensearch-plugins``, or using Docker. + +.. warning:: + + With ``plugins.security.disabled: true``, OpenSearch accepts requests without authentication. + OpenSearch listens only on the loopback address unless ``network.host`` is set. Before it listens + on any other address, configure the security plugin instead; see :doc:`security`. + +install opensearch-plugins +-------------------------- + +:: + + $ bin/fess-setup install opensearch-plugins --opensearch-home [--version ] + +Installs the four plugins |Fess| requires into an OpenSearch you already have, in place of running +its ``bin/opensearch-plugin install`` four times. ``--opensearch-home`` is the OpenSearch +installation directory and is required. ``--version`` sets the plugin version, which must match the +OpenSearch version. + +This command does not change ``opensearch.yml``. Add ``configsync.config_path`` and the other +settings yourself, as described in :doc:`install-linux` or :doc:`install-windows`. + +install nodejs +-------------- + +:: + + $ bin/fess-setup install nodejs [--dest ] [--version ] + +Downloads Node.js, which the Playwright plugins need (``fess-crawler-playwright`` for the Playwright +crawler and ``fess-thumbnail-playwright`` for thumbnails), into ``nodejs/`` in the |Fess| directory. +``bin/fess.in.sh`` (``bin\fess.in.bat`` on Windows) finds it there and sets +``PLAYWRIGHT_NODEJS_PATH``. With ``--dest`` outside the |Fess| directory, the command prints the +``PLAYWRIGHT_NODEJS_PATH`` line to add to ``bin/fess.in.sh`` instead. ``--version`` selects another +Node.js version. See :doc:`../config/crawler-advanced` for the Playwright crawler. + +Managing Plugins +================ + +These commands work on the plugin directory ``app/WEB-INF/plugin`` of the |Fess| installation. +Restart |Fess| after installing, upgrading or removing plugins. Plugins can also be managed from +the System > Plugin page in the administration screen; see :doc:`../admin/plugin-guide`. + +``install plugin``, ``list plugins``, ``list installed``, ``upgrade plugins``, ``remove plugin`` and ``check`` accept ``--dest ``. It names the plugin directory to use instead of ``app/WEB-INF/plugin``: the directory that holds the plugin jars itself, not its parent. A relative path is resolved from the current directory, not from the |Fess| directory. For ``install opensearch`` and ``install nodejs``, ``--dest`` is instead the directory the archive is extracted into. + +``install plugin``, ``list plugins`` and ``upgrade plugins`` accept ``--repository ``. It takes +the version list, the jars and their checksums from that one Maven repository, such as an internal +mirror, instead of the default release and snapshot repositories and GitHub. + +``--repository`` also accepts a URL that starts with ``file:///``. On a server with no route to the +Internet, put a copy of the Maven repository on the server and name that directory. Name the directory +that contains the directory of each plugin (``/maven-metadata.xml`` and so on), the place that +corresponds to ``https://maven.codelibs.org/release/org/codelibs/fess/`` of the default repository. +Versions are resolved and checksums are verified the same way as with an HTTP repository. + +:: + + $ bin/fess-setup install plugin fess-ds-csv --repository file:///opt/maven-repo/org/codelibs/fess/ + +A scheme other than ``http``, ``https`` and ``file``, or a URL without a scheme, is refused with a +one-line error. + +install plugin +-------------- + +:: + + $ bin/fess-setup install plugin [:]... [--version ] [--repository ] [--dest ] + +Installs one or more |Fess| plugins, for example ``fess-script-groovy`` or ``fess-ds-git``. A name +without a version installs the newest version built for this |Fess|. ``:`` pins the +version of that plugin, and ``--version`` is the version for every name that has none of its own. +The previously installed version of a plugin is deleted once the new one has been installed. + +A jar comes from the plugin's GitHub release, or from the Maven repository when the release has no +such asset, and is checked against the SHA-1 checksum the Maven repository publishes. A development +build of |Fess| also installs the snapshot builds of its own line, and prefers them. + +See :doc:`../admin/plugin-guide` for examples. + +Only the plugin types that |Fess| loads can be installed: names that start with ``fess-ds-``, +``fess-ingest-``, ``fess-script-``, ``fess-webapp-``, ``fess-thumbnail-``, ``fess-crawler-``, +``fess-llm-``, ``fess-storage-`` or ``fess-sso-``, the same ones ``list plugins`` shows. Any other name +(``fess-theme-*``, or a library such as ``fess`` or ``fess-crawler``) is refused with a one-line error +and exit code 2 before anything is downloaded. If one of several names is refused, none of them is +installed. Install a static theme with ``install theme``. + +list plugins +------------ + +:: + + $ bin/fess-setup list plugins [--repository ] [--dest ] + +Lists the plugins published for this |Fess|, and marks the installed ones with +``(installed: )``. Plugins that are installed but not published in the repository, such as +a locally built jar, are listed separately. A development build of |Fess| lists the snapshot +repository as well. + +list installed +-------------- + +:: + + $ bin/fess-setup list installed [--dest ] + +Lists the installed plugins and their versions, without contacting the repository. + +upgrade plugins +--------------- + +:: + + $ bin/fess-setup upgrade plugins [--repository ] [--dest ] + +Reinstalls every installed plugin at the version that fits this |Fess|. A plugin that is already at +that version is left as it is. The plugins in ``app/WEB-INF/plugin`` are built for one |Fess| +release, so run this command after upgrading |Fess|. + +remove plugin +------------- + +:: + + $ bin/fess-setup remove plugin ... [--dest ] + +Deletes the installed jars of the named plugins. A name that is not installed is reported, and does +not change the exit code. + +.. _fess-setup-offline: + +Without Internet Access +----------------------- + +``install plugin``, ``list plugins`` and ``upgrade plugins`` get plugins from repositories on the +Internet. The install page under System > Plugin in the administration screen also gets the list of +installable plugins from the repositories (``plugin.repositories``), so it cannot show the list where +there is no outside access. + +In such an environment, bring in the plugin jars: + +1. Where there is Internet access, download the |Fess| ZIP package and the jars of the plugins you need. + A jar can be downloaded from + ``https://maven.codelibs.org/release/org/codelibs/fess///-.jar``. + Choose the version for this |Fess| (15.10.x for |Fess| 15.10). +2. In the target environment, extract the ZIP and put the jars in ``app/WEB-INF/plugin/``. After |Fess| + starts, you can also upload them on the "Local" tab of the plugin install page in the administration + screen; see :doc:`../admin/plugin-guide`. +3. Start |Fess|. If you put the jars there while it was running, restart it. + +Instead of bringing in each jar, you can also copy the needed part of the Maven repository (the +``org/codelibs/fess//`` directories) to the server and install with ``install plugin`` and +``--repository file:///...``. The checksums are verified in this case too. + +Managing Themes +=============== + +These commands work on the theme directory ``app/themes`` of the |Fess| installation. Restart +|Fess| after installing or removing a theme, or click [Reload] on the System > Theme page. Themes +can also be uploaded from that page; see :doc:`../admin/theme-guide`. + +``install theme``, ``list themes`` and ``remove theme`` accept ``--dest `` in the same way, naming the theme directory to use instead of ``app/themes``. + +A theme's version is the |Fess| line it targets, so ``15.10.0`` is a theme for |Fess| 15.10. A name +without a version therefore resolves to the theme built for this |Fess|, the same way a plugin +version does. + +install theme +------------- + +:: + + $ bin/fess-setup install theme [:]... [--version ] [--repository ] [--dest ] + +Installs one or more static themes, for example ``docuforge`` or ``voicebox``. A name without a +version installs the newest one built for this |Fess|. ``:`` pins the version of +that theme, and ``--version`` is the version for every name that has none of its own. + +The archive is checked against the SHA-1 checksum the Maven repository publishes, and extracted +into ``app/themes/``. A theme already installed under that name is kept as a backup for the +same period as one replaced from the administration screen (default 7 days, +``theme.upload.attic.retention.days``). + +The download, the extraction and the manifest check all happen before anything installed is +touched, so a theme that is already there survives a failed install. An archive whose +``theme.yml`` names a different theme is rejected. + +list themes +----------- + +:: + + $ bin/fess-setup list themes [--repository ] [--dest ] + +Lists the themes published for this |Fess|, and marks the installed ones with +``(installed: )``. Themes that are installed but not listed by the repository are shown +separately. + +The list is read from the repository's directory index, which is generated periodically. When it +cannot be read, the command reports the URL it tried and still lists the installed themes: a theme +can be installed by naming it whether or not the index lists it. + +remove theme +------------ + +:: + + $ bin/fess-setup remove theme ... [--dest ] + +Deletes the named themes from ``app/themes``, keeping each as a backup for the retention period. A +name that is not installed is reported, and does not change the exit code. + +If a removed theme was the default, |Fess| falls back to the bundled ``bootstrap`` theme until +another one is chosen. + +Checking an Installation +======================== + +list +---- + +:: + + $ bin/fess-setup list + +Shows the components that ``install`` downloads, ``opensearch`` and ``nodejs``, with the version of +each. + +check +----- + +:: + + $ bin/fess-setup check [--url ] [--playwright] [--dest ] + +Reports on the installation, one line per check, each marked ``OK``, ``WARN`` or ``FAIL``: + +- The search engine: whether it is reachable, its version (a warning when the nodes report + different versions), whether the four plugins |Fess| requires are installed in it, and whether + ``configsync`` responds. +- |Fess|: whether the plugin directory exists and is writable, each installed plugin (a failure for + a plugin built for another |Fess| release and for a plugin installed in two versions), and + whether Node.js is installed in ``nodejs/`` in the |Fess| directory. + +The engine URL is ``--url``, otherwise the ``SEARCH_ENGINE_HTTP_URL`` environment variable, +otherwise ``http://localhost:9200``. ``bin/fess-setup`` does not read ``bin/fess.in.sh``, so pass +``--url`` when OpenSearch is somewhere else. A missing Node.js is only reported, unless +``--playwright`` is given, which makes it a failure. + +The command exits with code ``0`` when no check failed, even if some produced warnings, and with +code ``1`` otherwise. diff --git a/en/15.10/install/index.rst b/en/15.10/install/index.rst new file mode 100644 index 000000000..b610e1986 --- /dev/null +++ b/en/15.10/install/index.rst @@ -0,0 +1,24 @@ +|Fess| Installation Guide +========================== + +How to install and run |Fess| on Linux, Windows, or Docker, with the +prerequisites, security settings, upgrading, and troubleshooting. + +.. toctree:: + :maxdepth: 2 + :caption: Table of Contents + + intro + prerequisites + install + install-linux + install-windows + install-docker + fess-setup + run + security + upgrade + uninstall + troubleshooting + + diff --git a/en/15.10/install/install-docker.rst b/en/15.10/install/install-docker.rst new file mode 100644 index 000000000..cad49269f --- /dev/null +++ b/en/15.10/install/install-docker.rst @@ -0,0 +1,608 @@ +==================================== +Docker Installation (Detailed Guide) +==================================== + +This page describes the installation procedure for |Fess| using Docker and Docker Compose. +Using Docker allows you to set up a |Fess| environment easily and quickly. + +Prerequisites +============= + +- System requirements described in :doc:`prerequisites` are met +- Docker 20.10 or later is installed +- Docker Compose 2.0 or later is installed + +Verify Docker Installation +========================== + +Verify the Docker and Docker Compose versions with the following commands. + +:: + + $ docker --version + $ docker compose version + +.. note:: + + If you are using an older version of Docker Compose, use the ``docker-compose`` command. + This document uses the new ``docker compose`` command format. + +About Docker Images +=================== + +When you start |Fess| with Docker Compose, the following two containers run. + +- **Fess** (``fess01``): The full-text search system itself +- **OpenSearch** (``search01``): The search engine + +The official Docker image is published on `GitHub Container Registry `__. +The Compose files and startup instructions are maintained in the `docker-fess `__ repository. + +Step 1: Obtain Docker Compose Files +=================================== + +The following files are required to start using Docker Compose. + +Method 1: Download Files Individually +------------------------------------- + +Download the following files: + +:: + + $ mkdir fess-docker + $ cd fess-docker + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose.yaml + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose-opensearch3.yaml + +Method 2: Clone Repository with Git +----------------------------------- + +If Git is installed, you can also clone the entire repository: + +:: + + $ git clone --depth 1 --branch v15.10.0 https://github.com/codelibs/docker-fess.git + $ cd docker-fess/compose + +Step 2: Review Docker Compose Files +=================================== + +Contents of ``compose.yaml`` +---------------------------- + +``compose.yaml`` contains the configuration for Fess itself (the ``fess01`` service). + +Main configuration items: + +- **Port number**: The Fess web interface port (default: 8080) +- **Environment variables**: Settings such as the OpenSearch connection endpoint (``SEARCH_ENGINE_HTTP_URL``) and the dictionary file path (``FESS_DICTIONARY_PATH``) +- **Startup order**: ``depends_on`` is configured so that the service starts only after OpenSearch (``search01``) becomes healthy + +Contents of ``compose-opensearch3.yaml`` +---------------------------------------- + +``compose-opensearch3.yaml`` contains the configuration for the search engine (the ``search01`` service, OpenSearch). + +Main configuration items: + +- **OpenSearch image**: The OpenSearch image used (``ghcr.io/codelibs/fess-opensearch``) +- **Memory settings**: JVM heap size +- **Volumes**: Volumes for data persistence (``search01_data``: index data, ``search01_dictionary``: dictionary files) + +Customize Configuration (Optional) +---------------------------------- + +To change the default settings, edit ``compose.yaml``. + +Example: Changing the port number:: + + services: + fess01: + ports: + - "9080:8080" # Map to port 9080 on the host + +Example: Changing memory settings:: + + services: + fess01: + environment: + - "FESS_HEAP_SIZE=2g" # Set the Fess heap size to 2GB + +Image Types and Thumbnails +-------------------------- + +The |Fess| Docker images come in several types that differ by a tag suffix (``-noble``, ``-al2023``, and so on). The default image without a suffix (Alpine-based) does not contain the external tools that create thumbnails of images, PDF files, and Office documents (ImageMagick, poppler-utils, unoconv, and LibreOffice). With this image, only HTML pages get thumbnails; no thumbnails are generated for images, PDF files, or Office documents. + +If you need these thumbnails, set the ``image`` in ``compose.yaml`` to a tag with the ``-noble`` suffix, which includes the tools. + +:: + + services: + fess01: + image: ghcr.io/codelibs/fess:15.10.0-noble + +The following table shows what each image supports. + +.. list-table:: + :header-rows: 1 + :widths: 40 30 30 + + * - Tag + - Images and PDF + - Office documents + * - ``15.10.0-noble`` + - Generated + - Generated + * - ``15.10.0-al2023`` + - Generated + - Not generated + * - ``15.10.0``, ``15.10.0-slim``, ``15.10.0-slim-noble``, ``15.10.0-slim-al2023`` + - Not generated + - Not generated + +With any image, the thumbnail of an HTML page is created from an image in the page. To display thumbnails, also enable thumbnail display in the General settings of the administration screen. See :doc:`../config/crawler-thumbnail` for details. + +Step 3: Start Docker Containers +=============================== + +Basic Startup +------------- + +Start Fess and OpenSearch with the following command: + +:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +.. note:: + + - The ``-f`` option specifies multiple Compose files + - The ``-d`` option runs it in the background + +Check the startup logs:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f + +You can exit the log view with ``Ctrl+C``. + +Verify Startup +-------------- + +Check the container status:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps + +Verify that the following containers are running: + +- ``fess01`` +- ``search01`` + +.. tip:: + + Startup may take several minutes. OpenSearch (``search01``) becomes healthy first, and then Fess (``fess01``) starts. + Check the status of each container with ``docker compose ... ps``; once ``fess01`` is up, you can access http://localhost:8080/ in your browser. + +Step 4: Access via Browser +========================== + +Once startup is complete, access the following URLs: + +- **Search screen**: http://localhost:8080/ +- **Admin screen**: http://localhost:8080/admin + +The search screen is ``bootstrap``, the static theme bundled with |Fess|. To change how it looks, +see :doc:`../admin/theme-guide`. + +Default administrator account: + +- Username: ``admin`` +- Password: ``admin`` + +.. warning:: + + **Important Security Notice** + + In production environments, be sure to change the administrator password. + For details, refer to :doc:`security`. + +Enabling AI Search Mode (LLM Plugin) +==================================== + +Starting with |Fess| 15.10, the AI Search Mode (RAG Chat) feature has been separated into ``fess-llm-*`` plugins. +The official `docker-fess `__ repository includes overlay files for the major LLM providers. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Overlay + - Purpose + * - ``compose-ollama.yaml`` + - Ollama (local LLM, starts an additional ``ollama01`` service) + * - ``compose-gemini.yaml`` + - Google Gemini (cloud API) + * - ``compose-openai.yaml`` + - OpenAI (cloud API) + +Each overlay automatically retrieves the matching plugin via ``FESS_PLUGINS`` and enables RAG Chat by setting +``-Dfess.config.rag.chat.enabled=true`` in ``FESS_JAVA_OPTS``. +For Gemini and OpenAI, which use cloud APIs, the provider to use is additionally specified with ``-Dfess.system.rag.llm.name``, +and the API key (``rag.llm..api.key``) and model (``rag.llm..model``) are configured. +For Ollama, since the default value of ``rag.llm.name`` (``ollama``) is used as is, no explicit setting is required, +and only the connection endpoint (``rag.llm.ollama.api.url``) is configured. + +Example using Gemini:: + + $ export GEMINI_API_KEY="AIzaSy..." + $ docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-gemini.yaml up -d + +Example using OpenAI:: + + $ export OPENAI_API_KEY="sk-..." + $ docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-openai.yaml up -d + +.. note:: + + The model to use can be changed with the ``GEMINI_MODEL`` and ``OPENAI_MODEL`` environment variables + (the defaults are ``gemini-2.5-flash`` and ``gpt-5-mini``, respectively). + +Example using Ollama:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-ollama.yaml up -d + $ docker exec -it ollama01 ollama pull gpt-oss:20b + +.. warning:: + + The ``ollama01`` service in ``compose-ollama.yaml`` is defined to use an NVIDIA GPU by default + (the `NVIDIA Container Toolkit `__ is required). + If you are running in an environment without a GPU, remove or comment out the ``deploy:`` block (the GPU specification under ``reservations``) in ``compose-ollama.yaml``. + +.. tip:: + + After startup, you can change the LLM provider to use (``rag.llm.name``) and provider-specific settings + from the "System > General" settings screen in the administration screen. However, since these changes are saved to + the configuration file inside the container, they are lost when the container is re-created (``up`` after ``docker compose down``). + To persist the settings, specify them in ``FESS_JAVA_OPTS`` in the Compose file, as in the examples above. + +Data Persistence +================ + +All |Fess| data (index, crawled documents, user information, settings, etc.) is stored entirely in OpenSearch. +Since this data is persisted in OpenSearch's volumes, it is retained even if the container is removed. +The Fess service itself (``fess01``) is stateless and has no dedicated volume. + +Check the volumes:: + + $ docker volume ls + +Main volumes defined in ``compose-opensearch3.yaml``: + +- ``search01_data``: OpenSearch index data (includes all Fess data) +- ``search01_dictionary``: Dictionary files + +.. note:: + + Docker Compose volume names are prefixed with the project name (by default, the name of the directory containing the Compose file). + For example, if started from the ``compose`` directory, the actual volume name would be something like ``compose_search01_data``. + +.. important:: + + Volumes are not deleted when containers are removed. + To delete a volume, you must explicitly run the ``docker volume rm`` command. + +Stop Docker Containers +====================== + +Stop the containers:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop + +Stop and remove the containers:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +.. warning:: + + The ``down`` command removes containers but does not delete volumes. + To also delete volumes (such as ``search01_data``), add the ``-v`` option:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down -v + + **Note**: Running this command deletes all data stored in OpenSearch. + +Advanced Configuration +====================== + +Customize Environment Variables +------------------------------- + +You can perform detailed configuration by adding or changing environment variables in ``compose.yaml``. + +Main environment variables: + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Environment Variable + - Description + * - ``FESS_HEAP_SIZE`` + - Fess JVM heap size (default in the Docker image: 512m) + * - ``FESS_JAVA_OPTS`` + - Specify additional JVM options (such as overriding settings with ``-Dfess.config.*``) + * - ``FESS_PLUGINS`` + - Plugins to automatically install at startup (space-separated ``name:version`` format; e.g., ``fess-ds-wikipedia:15.10.0``) + * - ``SEARCH_ENGINE_HTTP_URL`` + - OpenSearch HTTP endpoint (default in ``compose.yaml``: ``http://search01:9200``) + * - ``SEARCH_ENGINE_TYPE`` + - The type of search engine (``default``, ``vanilla`` or ``aws``). ``vanilla`` requires a Fess 15.10 or later image; use ``cloud`` with older images (see :doc:`../config/search-engine-type`). On the 15.8 images, only the ``-noble`` variant passes it to Fess. + * - ``SEARCH_ENGINE_USERNAME`` / ``SEARCH_ENGINE_PASSWORD`` + - Credentials for connecting to an OpenSearch instance with authentication enabled + * - ``FESS_DICTIONARY_PATH`` + - Path to the dictionary files (a directory shared with OpenSearch) + * - ``FESS_PORT`` + - Port on which Fess listens inside the container (default: 8080) + +Example:: + + services: + fess01: + environment: + - "FESS_HEAP_SIZE=4g" + +.. note:: + + To change the time zone, specify something like ``-Duser.timezone=Asia/Tokyo`` in ``FESS_JAVA_OPTS``. + +How to Apply Configuration Files +-------------------------------- + +Detailed |Fess| settings are written in the ``fess_config.properties`` file. +In the Docker image, ``fess_config.properties`` is located at ``/etc/fess`` inside the container. +The following methods are available for applying settings in a Docker environment. + +Method 1: Mount Configuration File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Since ``/etc/fess`` also contains other configuration files required for Fess to run, replacing this entire directory with a mount will cause startup to fail. +Instead, use the override directory ``/opt/fess``, which is added to the front of the classpath (it is empty by default). + +1. Create a directory on the host to hold the configuration file:: + + $ mkdir -p /path/to/fess-config + +2. Obtain the configuration file template (first time only):: + + $ curl -o /path/to/fess-config/fess_config.properties https://raw.githubusercontent.com/codelibs/fess/refs/tags/fess-15.10.0/src/main/resources/fess_config.properties + +3. Edit ``/path/to/fess-config/fess_config.properties`` to write the required settings:: + + # Example + crawler.document.cache.enabled=false + adaptive.load.control=20 + query.facet.fields=label,host + +4. Add a volume mount to the ``fess01`` service in ``compose.yaml``:: + + services: + fess01: + volumes: + - /path/to/fess-config/fess_config.properties:/opt/fess/fess_config.properties + +5. Start the container:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +.. note:: + + Since ``/opt/fess`` is added to the front of the classpath, the ``fess_config.properties`` placed here + takes precedence over the ``/etc/fess/fess_config.properties`` bundled with the image. + Property files are loaded as whole files and are not merged item by item. + An item that is missing from your file does not stop |Fess|: it uses the default shipped with its version, and one warning per item is logged. + A file that holds only the items you want to change therefore works. To avoid the warnings, start from the complete file, as in step 2. + If you only want to change some items, use "Method 2" below instead. + When an item is set both in this file and with ``-Dfess.config.`` (Method 2), the value set with ``-D`` is used. + +Method 2: Configuration via System Properties +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can override configuration items in ``fess_config.properties`` as system properties via environment variables. + +Configuration items written in ``fess_config.properties`` (e.g., ``crawler.document.cache.enabled=false``) +are specified in the form ``-Dfess.config.setting_name=value``. + +Add ``FESS_JAVA_OPTS`` to the environment variables of the ``fess01`` service in ``compose.yaml``:: + + services: + fess01: + environment: + - "FESS_JAVA_OPTS=-Dfess.config.crawler.document.cache.enabled=false -Dfess.config.adaptive.load.control=20 -Dfess.config.query.facet.fields=label,host" + +.. note:: + + The part following ``-Dfess.config.`` corresponds to the configuration item name in ``fess_config.properties``. + This method is simpler when you only want to override a few items. + +Connect to External OpenSearch +------------------------------ + +To use an existing OpenSearch cluster, start with only ``compose.yaml`` (without ``compose-opensearch3.yaml``) and change the connection destination. + +1. Start without specifying ``compose-opensearch3.yaml``:: + + $ docker compose -f compose.yaml up -d + +2. Set the connection destination in the ``fess01`` service of ``compose.yaml``:: + + environment: + - "SEARCH_ENGINE_HTTP_URL=http://your-opensearch-host:9200" + +.. note:: + + If connecting to an OpenSearch instance with authentication enabled, also specify ``SEARCH_ENGINE_USERNAME`` and ``SEARCH_ENGINE_PASSWORD``. + +Other Overlays and Configurations +--------------------------------- + +The ``docker-fess`` repository also includes Compose files and directories for other purposes. + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - File / Directory + - Purpose + * - ``compose-dashboards3.yaml`` + - Adds OpenSearch Dashboards (port 5601, for data visualization) + * - ``compose-minio.yaml`` + - Adds MinIO (object storage) and uses it as the storage destination for Fess's storage feature + * - ``vanilla/`` + - A configuration that combines Fess with a plain OpenSearch that does not include the CodeLibs plugins (``SEARCH_ENGINE_TYPE=vanilla``, which requires a Fess 15.10 or later image; use ``cloud`` with older images). Some features, such as dictionary management, are unavailable (see :doc:`../config/search-engine-type`) + * - ``snapshot/`` + - A configuration that uses development (snapshot) images (including cluster configurations and combinations with Elasticsearch 8) + * - ``multi-instance/`` + - A configuration that starts multiple Fess instances sharing a single OpenSearch + +Docker Network Configuration +---------------------------- + +When integrating with multiple services, you can use a custom network. + +Example:: + + networks: + fess-network: + driver: bridge + + services: + fess01: + networks: + - fess-network + +Production Operation with Docker Compose +======================================== + +Recommended settings when using Docker Compose in a production environment: + +1. **Set resource limits**:: + + deploy: + resources: + limits: + cpus: '2.0' + memory: 4G + reservations: + cpus: '1.0' + memory: 2G + +2. **Set the restart policy**:: + + restart: unless-stopped + +3. **Configure logging**:: + + logging: + driver: "json-file" + options: + max-size: "10m" + max-file: "3" + +4. **Enable security settings** + + Enable the OpenSearch security plugin and configure appropriate authentication. + For details, refer to :doc:`security`. + +Troubleshooting +=============== + +Container Won't Start +--------------------- + +1. Check the logs:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs + +2. Check for port conflicts:: + + $ sudo ss -tuln | grep 8080 + $ sudo ss -tuln | grep 9200 + +3. Check disk space:: + + $ df -h + +Out of Memory Error +------------------- + +If OpenSearch fails to start due to insufficient memory, you need to increase ``vm.max_map_count``. + +On Linux:: + + $ sudo sysctl -w vm.max_map_count=262144 + +To make the setting persistent:: + + $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf + $ sudo sysctl -p + +Initialize Data +--------------- + +To delete all data and return to the initial state:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down -v + $ docker volume prune + +.. warning:: + + Running this command completely deletes all data. + +Next Steps +========== + +After installation is complete, refer to the following documents: + +- :doc:`run` - Starting |Fess| and initial setup +- :doc:`security` - Security configuration for production environments +- :doc:`troubleshooting` - Troubleshooting + +Frequently Asked Questions +========================== + +Q: How much disk space is required to download the images? +---------------------------------------------------------- + +A: The Fess and OpenSearch images are downloaded on first startup and together require several GB of disk space. +Depending on your network environment, the download may take some time. + +Q: Can I run this on Kubernetes? +-------------------------------- + +A: Yes, it is possible. You can convert the Docker Compose files into Kubernetes manifests using a tool such as ``kompose``, +or create your own manifests to operate on Kubernetes (an official Helm chart is not provided). + +Q: How do I update the containers? +---------------------------------- + +A: Update using the following procedure: + +1. Obtain the latest Compose files +2. Stop the containers:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +3. Pull the new images:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull + +4. Start the containers:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +Q: Is a multi-node configuration possible? +------------------------------------------ + +A: Yes, it is possible. You can configure OpenSearch with multiple nodes by referring to ``snapshot/compose-cluster.yaml`` in the ``docker-fess`` repository, +or configure multiple Fess instances sharing a single OpenSearch by referring to ``multi-instance/``. +However, for production environments, we recommend using an orchestration tool such as Kubernetes. diff --git a/en/15.10/install/install-linux.rst b/en/15.10/install/install-linux.rst new file mode 100644 index 000000000..744bb5d99 --- /dev/null +++ b/en/15.10/install/install-linux.rst @@ -0,0 +1,570 @@ +======================================== +Linux Installation (Detailed Procedure) +======================================== + +This page describes the installation procedure for |Fess| on Linux environments. +It covers the ZIP, RPM, and DEB package formats. + +.. note:: + + |Fess| does not bundle a search engine. An OpenSearch server is required, and the + steps below set one up. + +Prerequisites +============= + +- The system requirements described in :doc:`prerequisites` are met +- Java 21 is installed +- OpenSearch 3.9.0 is available for use (or is newly installed) + +Choosing an Installation Method +================================ + +For Linux environments, you can choose from the following installation methods: + +.. list-table:: + :header-rows: 1 + :widths: 20 40 40 + + * - Method + - Recommended Environments + - Features + * - ZIP + - Development environments, environments requiring customization + - Can be extracted to any directory + * - RPM + - RHEL, CentOS, Fedora systems + - Service management via systemd possible + * - DEB + - Debian, Ubuntu systems + - Service management via systemd possible + +System Configuration for Running OpenSearch +============================================ + +To run OpenSearch stably on Linux, configure the following kernel parameters and resource limits. +These are mainly required for the TAR.GZ version (when installing OpenSearch manually). +For the RPM / DEB versions, the OpenSearch and |Fess| packages configure settings such as the file descriptor limit via systemd, but since ``vm.max_map_count`` is a host-level kernel setting, be sure to check it regardless of which installation method you use. + +Maximum Map Count for Virtual Memory +------------------------------------- + +Because OpenSearch uses a large number of memory maps, set ``vm.max_map_count`` to ``262144`` or higher. + +To set this temporarily:: + + $ sudo sysctl -w vm.max_map_count=262144 + +To set this persistently:: + + $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf + $ sudo sysctl -p + +File Descriptor Limit +----------------------- + +When running OpenSearch manually (TAR.GZ version), set the file descriptor limit for the user running OpenSearch to ``65535`` or higher. + +Add the following to ``/etc/security/limits.conf`` (replace ``opensearch`` with the username that runs OpenSearch):: + + opensearch - nofile 65535 + +.. note:: + + For the RPM / DEB versions, this setting is not necessary because the file descriptor limit is configured in the systemd service definition. + +Installation with ZIP Version +================================= + +Step 1: Install OpenSearch +--------------------------- + +.. important:: + + Install and run OpenSearch as a regular user, not as ``root``: OpenSearch refuses to start as + ``root``. Run ``bin/fess-setup`` below as that user as well, so that the files it extracts belong + to that user. See :doc:`run` if a start as ``root`` has already been refused. + +.. tip:: + + ``bin/fess-setup``, included with |Fess|, performs steps 1 to 3 below in one command. It + downloads and extracts OpenSearch into ``opensearch/`` in the |Fess| directory, installs the + required plugins, and adds ``configsync.config_path`` and ``plugins.security.disabled: true`` + to its ``config/opensearch.yml``. Extract the |Fess| ZIP first, as described in Step 2. + + :: + + $ cd /path/to/fess-15.10.0 + $ bin/fess-setup install opensearch + + ``bin/fess.in.sh`` finds an OpenSearch installed this way and sets ``FESS_DICTIONARY_PATH`` on + its own, so "Configure Fess" in Step 2 needs no change as long as OpenSearch runs on the same + host. The command prints the settings it added and whether ``bin/fess.in.sh`` finds the + installation. Read the warning in step 3 before OpenSearch listens on any address other than + ``localhost``. + + Follow the steps below to work through them individually, or when using an OpenSearch you + already have. To install only the plugins into an existing OpenSearch, use + ``bin/fess-setup install opensearch-plugins --opensearch-home /path/to/opensearch``. + See :doc:`fess-setup` for all commands. + +.. note:: + + OpenSearch publishes no macOS build, so on macOS ``bin/fess-setup install opensearch`` exits + with an error. Install OpenSearch with Homebrew and add the plugins with + ``bin/fess-setup install opensearch-plugins``, or use :doc:`install-docker` instead:: + + $ brew install opensearch + $ bin/fess-setup install opensearch-plugins --opensearch-home $(brew --prefix opensearch) + + Then configure that OpenSearch as in step 3, and set ``FESS_DICTIONARY_PATH`` as described in + "Configure Fess" in Step 2. + +1. Download OpenSearch + + Download the TAR.GZ version from `Download OpenSearch `__. + + :: + + $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.9.0/opensearch-3.9.0-linux-x64.tar.gz + $ tar -xzf opensearch-3.9.0-linux-x64.tar.gz + $ cd opensearch-3.9.0 + + On an arm64 (aarch64) machine, replace ``linux-x64`` with ``linux-arm64`` in the file names above (for example, ``opensearch-3.9.0-linux-arm64.tar.gz``). + + .. note:: + + This example uses OpenSearch 3.9.0. + |Fess| 15.10 supports OpenSearch 3.9.0. + +2. Install OpenSearch Plugins + + Install the plugins required by |Fess|. + + :: + + $ cd /path/to/opensearch-3.9.0 + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + + .. important:: + + Plugin versions must match the OpenSearch version. + In the example above, all are specified as 3.9.0. + + The four |Fess| plugins are published on maven.codelibs.org, so they are installed by URL. The + ``groupId:artifactId:version`` form of ``opensearch-plugin install`` looks only at Maven + Central. + +3. Configure OpenSearch + + Add the following settings to ``config/opensearch.yml``. + + :: + + # Path for configuration synchronization (specify an absolute path) + configsync.config_path: /path/to/opensearch-3.9.0/config/dictionary/ + + # Disable the security plugin (development environments only) + plugins.security.disabled: true + + .. important:: + + Set ``configsync.config_path`` to a directory under the OpenSearch configuration directory (``/path/to/opensearch-3.9.0/config/`` in this example). + OpenSearch 3.8.0 and later refuse to create an index when dictionary files are outside the configuration directory. + If you specify a directory outside the configuration directory, such as ``/path/to/opensearch-3.9.0/data/config/``, |Fess| cannot create its indices and does not start. + + .. warning:: + + **Important Security Notice** + + Use ``plugins.security.disabled: true`` only in development or test environments. + In production environments, enable the OpenSearch security plugin and configure appropriate authentication and authorization. + When enabling the security plugin on OpenSearch 2.12 or later, you must set the administrator password (environment variable ``OPENSEARCH_INITIAL_ADMIN_PASSWORD``) at the first startup. + For details, refer to :doc:`security`. + + .. tip:: + + Adjust other settings, such as the cluster name and network settings, according to your environment. + Example configuration:: + + cluster.name: fess-cluster + node.name: fess-node-1 + network.host: 0.0.0.0 + discovery.type: single-node + + .. tip:: + + The OpenSearch heap size is configured with ``-Xms`` / ``-Xmx`` in ``config/jvm.options``. + As a guideline, use no more than half of the available physical memory and less than 32GB, and it is recommended to specify the same value for ``-Xms`` and ``-Xmx``. + +Step 2: Install Fess +--------------------- + +1. Download and Extract Fess + + Download the ZIP version from the `download site `__. + + :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.zip + $ unzip fess-15.10.0.zip + $ cd fess-15.10.0 + + .. note:: + + Select a directory that does not contain spaces in the path, on macOS as well. If the path contains a space, ``bin/fess`` does not start and prints ``Could not find or load main class``. + +2. Configure Fess + + The connection information to OpenSearch is in ``bin/fess.in.sh``. With an OpenSearch that + ``bin/fess-setup install opensearch`` installed into ``opensearch/`` in the |Fess| directory and + that runs on the same host, this file needs no change: ``SEARCH_ENGINE_HTTP_URL`` defaults to + ``http://localhost:9200``, and ``FESS_DICTIONARY_PATH`` is set to the ``config/dictionary`` + directory of that OpenSearch. + + Edit ``bin/fess.in.sh`` in any of the following cases: + + - OpenSearch was installed another way, such as by steps 1 to 3 above or with Homebrew, or with + ``--dest`` outside the |Fess| directory. + - ``opensearch/`` in the |Fess| directory holds more than one OpenSearch installed by + ``bin/fess-setup``, for example two versions. ``bin/fess.in.sh`` cannot tell which one is in + use, so it prints a warning and leaves ``FESS_DICTIONARY_PATH`` unset. + - OpenSearch runs on another host or port. + + :: + + $ vi bin/fess.in.sh + + Near the top of the file, remove the leading ``#`` from the ``FESS_DICTIONARY_PATH`` line and set + the path, and change the URL in the ``SEARCH_ENGINE_HTTP_URL`` line if needed. + + Before (default state, comment lines omitted):: + + SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://localhost:9200} + #FESS_DICTIONARY_PATH=/var/lib/opensearch/config/ + + After:: + + SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://localhost:9200} + FESS_DICTIONARY_PATH=/path/to/opensearch-3.9.0/config/dictionary/ + + .. note:: + + - Set ``FESS_DICTIONARY_PATH`` to the same path specified for ``configsync.config_path`` in OpenSearch's ``opensearch.yml``. Without it, |Fess| cannot create its indices and does not start. + - If OpenSearch is running on a different host, change the URL in the ``SEARCH_ENGINE_HTTP_URL`` line to that host. Example: ``SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://192.168.1.100:9200}``. ``FESS_DICTIONARY_PATH`` is then the ``configsync.config_path`` of that server. + - Instead of editing the file, both variables can be exported in the environment |Fess| is started from. An exported ``SEARCH_ENGINE_HTTP_URL`` takes precedence over the URL in the file, and an exported ``FESS_DICTIONARY_PATH`` is used as long as its line in the file stays commented out. + - Rather than adding a new ``SEARCH_ENGINE_HTTP_URL=...`` line, edit the existing one. + + .. tip:: + + To change the |Fess| heap size, edit ``FESS_MIN_MEM`` (default: ``256m``) and ``FESS_MAX_MEM`` (default: ``2g``) in ``bin/fess.in.sh``, or set the environment variable ``FESS_HEAP_SIZE``. + +3. Verify Installation + + Verify that the configuration file has been edited correctly:: + + $ grep "SEARCH_ENGINE_HTTP_URL" bin/fess.in.sh + $ grep "FESS_DICTIONARY_PATH" bin/fess.in.sh + + Once OpenSearch is running, ``bin/fess-setup check`` reports whether it is reachable, whether it + has the plugins |Fess| requires, and whether ``configsync`` responds. It exits with code ``0`` + when no check failed. Pass ``--url`` when OpenSearch is not at ``http://localhost:9200``. + +Step 3: Startup +----------------- + +For startup procedures, refer to :doc:`run`. + +Installation with RPM Version +============================== + +The RPM version is used on RPM-based Linux distributions such as Red Hat Enterprise Linux, CentOS, and Fedora. + +Step 1: Install OpenSearch +--------------------------- + +1. Download and Install OpenSearch RPM + + Download the RPM package from `Download OpenSearch `__ and install it. + + :: + + $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.9.0/opensearch-3.9.0-linux-x64.rpm + $ sudo rpm -ivh opensearch-3.9.0-linux-x64.rpm + + On an arm64 (aarch64) machine, replace ``linux-x64`` with ``linux-arm64`` in the file names above (for example, ``opensearch-3.9.0-linux-arm64.rpm``). + + Alternatively, you can add a repository and install from it. + For details, refer to `Installing OpenSearch `__. + +2. Install OpenSearch Plugins + + :: + + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + +3. Configure OpenSearch + + Add the following settings to ``/etc/opensearch/opensearch.yml``. + + :: + + $ sudo vi /etc/opensearch/opensearch.yml + + Settings to add:: + + configsync.config_path: /etc/opensearch/dictionary/ + plugins.security.disabled: true + + Create the directory for dictionary files:: + + $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary + + .. important:: + + Set ``configsync.config_path`` to a directory under the OpenSearch configuration directory ``/etc/opensearch/``. + OpenSearch 3.8.0 and later refuse to create an index when dictionary files are outside the configuration directory. + If you specify a directory outside the configuration directory, such as ``/var/lib/opensearch/data/config/``, |Fess| cannot create its indices and does not start. + + .. warning:: + + Do not use ``plugins.security.disabled: true`` in production environments. + Refer to :doc:`security` for appropriate security configuration. + +Step 2: Install Fess +--------------------- + +1. Install Fess RPM + + Download the RPM package from the `download site `__ and install it. + + :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.rpm + $ sudo rpm -ivh fess-15.10.0.rpm + +2. Configure Fess + + For the RPM version, edit the environment variable configuration file ``/etc/sysconfig/fess``. + This file is preserved across package upgrades (do not edit ``/usr/share/fess/bin/fess.in.sh`` directly, since it is overwritten during upgrades). + + :: + + $ sudo vi /etc/sysconfig/fess + + Configure the connection information to OpenSearch. The default value of ``FESS_DICTIONARY_PATH``, ``/var/lib/opensearch/config/``, differs from ``configsync.config_path`` in step 3, so change it as follows. Change ``SEARCH_ENGINE_HTTP_URL`` as needed:: + + SEARCH_ENGINE_HTTP_URL=http://localhost:9200 + FESS_DICTIONARY_PATH=/etc/opensearch/dictionary/ + + .. note:: + + Set ``FESS_DICTIONARY_PATH`` to the same path as ``configsync.config_path`` in ``opensearch.yml``. + +3. Register and Enable the Service + + Enable the services using systemd (systemd is the standard on RHEL 8 and later, and CentOS 8 and later):: + + $ sudo systemctl daemon-reload + $ sudo systemctl enable opensearch.service + $ sudo systemctl enable fess.service + + .. note:: + + Because the |Fess| service depends on the OpenSearch service, OpenSearch must be started first. + + .. note:: + + On legacy environments that do not use systemd, you can register |Fess| with ``chkconfig``:: + + $ sudo /sbin/chkconfig --add fess + +Step 3: Startup +----------------- + +For startup procedures, refer to :doc:`run`. + +Installation with DEB Version +============================== + +The DEB version is used on DEB-based Linux distributions such as Debian and Ubuntu. + +Step 1: Install OpenSearch +--------------------------- + +1. Download and Install OpenSearch DEB + + Download the DEB package from `Download OpenSearch `__ and install it. + + :: + + $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.9.0/opensearch-3.9.0-linux-x64.deb + $ sudo dpkg -i opensearch-3.9.0-linux-x64.deb + + On an arm64 (aarch64) machine, replace ``linux-x64`` with ``linux-arm64`` in the file names above (for example, ``opensearch-3.9.0-linux-arm64.deb``). + + Alternatively, you can add a repository and install from it. + For details, refer to `Installing OpenSearch `__. + +2. Install OpenSearch Plugins + + :: + + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + +3. Configure OpenSearch + + Add the following settings to ``/etc/opensearch/opensearch.yml``. + + :: + + $ sudo vi /etc/opensearch/opensearch.yml + + Settings to add:: + + configsync.config_path: /etc/opensearch/dictionary/ + plugins.security.disabled: true + + Create the directory for dictionary files:: + + $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary + + .. important:: + + Set ``configsync.config_path`` to a directory under the OpenSearch configuration directory ``/etc/opensearch/``. + OpenSearch 3.8.0 and later refuse to create an index when dictionary files are outside the configuration directory. + If you specify a directory outside the configuration directory, such as ``/var/lib/opensearch/data/config/``, |Fess| cannot create its indices and does not start. + + .. warning:: + + Do not use ``plugins.security.disabled: true`` in production environments. + Refer to :doc:`security` for appropriate security configuration. + +Step 2: Install Fess +--------------------- + +1. Install Fess DEB + + Download the DEB package from the `download site `__ and install it. + + :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.deb + $ sudo dpkg -i fess-15.10.0.deb + +2. Configure Fess + + For the DEB version, edit the environment variable configuration file ``/etc/default/fess``. + This file is preserved across package upgrades (do not edit ``/usr/share/fess/bin/fess.in.sh`` directly, since it is overwritten during upgrades). + + :: + + $ sudo vi /etc/default/fess + + Configure the connection information to OpenSearch. The default value of ``FESS_DICTIONARY_PATH``, ``/var/lib/opensearch/config/``, differs from ``configsync.config_path`` in step 3, so change it as follows. Change ``SEARCH_ENGINE_HTTP_URL`` as needed:: + + SEARCH_ENGINE_HTTP_URL=http://localhost:9200 + FESS_DICTIONARY_PATH=/etc/opensearch/dictionary/ + + .. note:: + + Set ``FESS_DICTIONARY_PATH`` to the same path as ``configsync.config_path`` in ``opensearch.yml``. + +3. Register and Enable the Service + + Enable the services using systemd:: + + $ sudo systemctl daemon-reload + $ sudo systemctl enable opensearch.service + $ sudo systemctl enable fess.service + + .. note:: + + Because the |Fess| service depends on the OpenSearch service, OpenSearch must be started first. + +Step 3: Startup +----------------- + +For startup procedures, refer to :doc:`run`. + +Post-Installation Verification +================================ + +After the installation is complete, verify the following: + +1. **Verify Configuration Files** + + - OpenSearch configuration file (opensearch.yml) + - |Fess| configuration file + + - ZIP version: ``bin/fess.in.sh`` + - RPM version: ``/etc/sysconfig/fess`` + - DEB version: ``/etc/default/fess`` + +2. **Directory Permissions** + + Verify that the directories specified in the configuration (``configsync.config_path`` / ``FESS_DICTIONARY_PATH``) exist and have appropriate permissions set. + + For the ZIP version:: + + $ ls -ld /path/to/opensearch-3.9.0/config/dictionary/ + + For the RPM/DEB versions:: + + $ sudo ls -ld /etc/opensearch/dictionary/ + +3. **Verify Kernel Parameters** + + :: + + $ sysctl vm.max_map_count + + Verify that the value is ``262144`` or higher. + +4. **Verify Java Version** + + :: + + $ java -version + + Verify that Java 21 or later is installed. + +Next Steps +========== + +After installation is complete, refer to the following documentation: + +- :doc:`run` - Starting |Fess| and initial setup +- :doc:`security` - Security configuration for production environments +- :doc:`troubleshooting` - Troubleshooting + +Frequently Asked Questions +============================ + +Q: Will other versions of OpenSearch work? +--------------------------------------------- + +A: |Fess| depends on a specific version of OpenSearch. +To ensure plugin compatibility, it is strongly recommended to use the recommended version (3.9.0). +If you use a different version, you must also adjust the plugin versions appropriately. + +Q: Can multiple Fess instances share the same OpenSearch? +------------------------------------------------------------- + +A: It is possible, but not recommended. We recommend providing a dedicated OpenSearch cluster for each Fess instance. +If you share OpenSearch among multiple Fess instances, be careful of index name conflicts. + +Q: How do I configure OpenSearch as a cluster? +--------------------------------------------------- + +A: Refer to the official OpenSearch documentation `Cluster formation `__. +For a cluster configuration, you must remove the ``discovery.type: single-node`` setting and add appropriate cluster settings. diff --git a/en/15.10/install/install-windows.rst b/en/15.10/install/install-windows.rst new file mode 100644 index 000000000..e15c4b678 --- /dev/null +++ b/en/15.10/install/install-windows.rst @@ -0,0 +1,359 @@ +========================================== +Windows Installation (Detailed Procedure) +========================================== + +This page describes the installation procedure for |Fess| on Windows environments. +It covers the installation method using ZIP packages. + +.. note:: + + |Fess| does not bundle a search engine. An OpenSearch server is required, and the + steps below set one up. + +Prerequisites +============= + +- System requirements described in :doc:`prerequisites` are met +- Java 21 is installed +- OpenSearch 3.9.0 is available (or new installation) +- Windows environment variable ``JAVA_HOME`` is configured appropriately + +Verify Java Installation +========================= + +Open Command Prompt or PowerShell and verify the Java version with the following command. + +For Command Prompt:: + + C:\> java -version + +For PowerShell:: + + PS C:\> java -version + +Verify that Java 21 or later is displayed. + +Environment Variable Configuration +=================================== + +1. Set ``JAVA_HOME`` Environment Variable + + Set the directory where Java is installed as ``JAVA_HOME``. + + Example:: + + JAVA_HOME=C:\Program Files\Eclipse Adoptium\jdk-21.0.1.12-hotspot + +2. Add to ``PATH`` Environment Variable + + Add ``%JAVA_HOME%\bin`` to the ``PATH`` environment variable. + +.. tip:: + + How to configure environment variables: + + 1. Open "Settings" from the Start menu + 2. Click "System" → "About" → "Advanced system settings" + 3. Click the "Environment Variables" button + 4. Configure in "System variables" or "User variables" + +Step 1: Install OpenSearch +=========================== + +.. tip:: + + ``bin\fess-setup``, included with |Fess|, performs the steps below in one command. It + downloads and extracts OpenSearch into ``opensearch\`` in the |Fess| directory, installs the + required plugins, and adds ``configsync.config_path`` and ``plugins.security.disabled: true`` + to its ``config\opensearch.yml``. Extract the |Fess| ZIP first, as described in Step 2. + + :: + + > cd C:\fess-15.10.0 + > bin\fess-setup install opensearch + + ``bin\fess.in.bat`` finds an OpenSearch installed this way and passes its ``config\dictionary`` + directory to |Fess|, so "Configure Fess" in Step 2 needs no change as long as OpenSearch runs on + the same host. The command prints the settings it added and whether ``bin\fess.in.bat`` finds + the installation. Read the warning in "Configure OpenSearch" before OpenSearch listens on any + address other than ``localhost``. + + Follow the steps below to work through them individually, or when using an OpenSearch you + already have. To install only the plugins into an existing OpenSearch, use + ``bin\fess-setup install opensearch-plugins --opensearch-home C:\opensearch-3.9.0``. + See :doc:`fess-setup` for all commands. + +Download OpenSearch +------------------- + +1. Download the ZIP package for Windows from `Download OpenSearch `__. + +2. Extract the downloaded ZIP file to any directory. + + Example:: + + C:\opensearch-3.9.0 + + .. note:: + + It is recommended to select a directory that does not contain Japanese characters or spaces in the path. + +Install OpenSearch Plugins +--------------------------- + +Open Command Prompt **with administrator privileges** and execute the following commands. + +:: + + C:\> cd C:\opensearch-3.9.0 + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + +.. important:: + + Plugin versions must match the OpenSearch version. + In the example above, all are specified as 3.9.0. + + The four |Fess| plugins are published on maven.codelibs.org, so they are installed by URL. The + ``groupId:artifactId:version`` form of ``opensearch-plugin install`` looks only at Maven Central. + +Configure OpenSearch +-------------------- + +Open ``config\opensearch.yml`` with a text editor and add the following settings. + +:: + + # Configuration synchronization path (specify absolute path) + configsync.config_path: C:/opensearch-3.9.0/config/dictionary/ + + # Disable security plugin (development environment only) + plugins.security.disabled: true + +.. warning:: + + **Important Security Notice** + + Use ``plugins.security.disabled: true`` only in development or test environments. + In production environments, enable the OpenSearch security plugin and configure appropriate authentication and authorization. + For details, refer to :doc:`security`. + +.. note:: + + On Windows, use ``/`` instead of ``\`` for path separators. + Write ``C:/opensearch-3.9.0/config/dictionary/`` instead of ``C:\opensearch-3.9.0\config\dictionary\``. + +.. important:: + + Set ``configsync.config_path`` to a directory under the OpenSearch configuration directory (``C:/opensearch-3.9.0/config/`` in this example). + OpenSearch 3.8.0 and later refuse to create an index when dictionary files are outside the configuration directory. + If you specify a directory outside the configuration directory, such as ``C:/opensearch-3.9.0/data/config/``, |Fess| cannot create its indices and does not start. + +.. tip:: + + Other recommended settings:: + + cluster.name: fess-cluster + node.name: fess-node-1 + network.host: 0.0.0.0 + discovery.type: single-node + +.. tip:: + + The OpenSearch heap size is configured via ``-Xms`` / ``-Xmx`` in ``config\jvm.options``. + It is recommended to set both ``-Xms`` and ``-Xmx`` to the same value, targeting no more than half of available physical memory and less than 32 GB. + +Step 2: Install Fess +===================== + +Download Fess +------------- + +1. Download the ZIP package for Windows from the `download site `__. + +2. Extract the downloaded ZIP file to any directory. + + Example:: + + C:\fess-15.10.0 + + .. note:: + + It is recommended to select a directory that does not contain Japanese characters or spaces in the path. + +Configure Fess +-------------- + +With an OpenSearch that ``bin\fess-setup install opensearch`` installed into ``opensearch\`` in the +|Fess| directory and that runs on the same host, nothing needs to be configured here. Otherwise, for +example when OpenSearch was installed by the steps above, runs on another host, or ``opensearch\`` +holds more than one OpenSearch installed by ``bin\fess-setup``, configure the connection as follows. + +Open ``bin\fess.in.bat`` with a text editor. +Near the end of this file, the settings for connecting to an external OpenSearch cluster are already present as commented-out lines. + +Before (default state):: + + REM External opensearch cluster + REM set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200 + REM set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=C:/opensearch/config/dictionary + +Remove the leading ``REM `` from the bottom two lines to uncomment them, and change the value of ``fess.dictionary.path`` to the configuration synchronization path for OpenSearch. + +After:: + + REM External opensearch cluster + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200 + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=C:/opensearch-3.9.0/config/dictionary/ + +.. note:: + + - Set ``fess.dictionary.path`` to the same path specified for ``configsync.config_path`` in OpenSearch's ``opensearch.yml``. + - If OpenSearch is running on a different host, change the hostname or IP address in ``fess.search_engine.http_address`` to the appropriate value. + - Use ``/`` for path separators. |Fess| inserts the path into the index settings, where a ``\`` is dropped, so a path written with ``\`` is not found. + - Do not add new ``set FESS_JAVA_OPTS=...`` lines; instead, uncomment and edit the existing commented lines. Specifying the same option more than once may cause unexpected behavior. + +.. tip:: + + To change the |Fess| heap size, edit ``FESS_MIN_MEM`` (default: ``256m``) and ``FESS_MAX_MEM`` (default: ``1g``) in ``bin\fess.in.bat``, or set the ``FESS_HEAP_SIZE`` environment variable. + +Verify Installation +------------------- + +Verify that the configuration files have been edited correctly. + +In Command Prompt:: + + C:\> findstr "fess.search_engine.http_address" C:\fess-15.10.0\bin\fess.in.bat + C:\> findstr "fess.dictionary.path" C:\fess-15.10.0\bin\fess.in.bat + +Step 3: Startup +=============== + +For startup procedures, refer to :doc:`run`. + +Register as Windows Service (Optional) +======================================= + +By registering |Fess| as a Windows service, you can configure it to start automatically on system startup. + +|Fess| ships with ``bin\service.bat`` for registering it as a Windows service. +This script uses Apache Commons Daemon (procrun), so no third-party tools such as NSSM are required. + +.. note:: + + Before running ``service.bat``, verify that the ``JAVA_HOME`` environment variable is configured correctly. + +Register Fess Service +--------------------- + +Open Command Prompt **with administrator privileges** and execute the following commands. + +1. Register the service:: + + C:\> cd C:\fess-15.10.0 + C:\fess-15.10.0> bin\service.bat install + + By default, the service is registered with the ID ``fess-service-x64`` on 64-bit systems and ``fess-service-x86`` on 32-bit systems. + To specify a service ID explicitly, pass it as an argument: ``bin\service.bat install ``. + +2. Start and stop the service:: + + C:\fess-15.10.0> bin\service.bat start + C:\fess-15.10.0> bin\service.bat stop + +3. View and change service settings (GUI):: + + C:\fess-15.10.0> bin\service.bat manager + +4. Remove the service:: + + C:\fess-15.10.0> bin\service.bat remove + +.. note:: + + - ``service.bat`` internally loads ``bin\fess.in.bat``, so the external OpenSearch connection settings configured in the "Configure Fess" section are also applied to the service. + - The default startup type is "Manual". To start automatically at system boot, either set the environment variable ``FESS_START_TYPE`` to ``auto`` before registering the service, or change the startup type to "Automatic" in the Services management tool (``services.msc``) after registration. + - ``service.bat`` registers only the |Fess| service. To register OpenSearch as a service, refer to the procedure provided by OpenSearch. + +Firewall Configuration +====================== + +Open the necessary ports in Windows Defender Firewall. + +1. Open "Control Panel" → "Windows Defender Firewall" → "Advanced settings" + +2. Create a new rule in "Inbound Rules" + + - Rule type: Port + - Protocol and port: TCP, 8080 + - Action: Allow the connection + - Name: Fess Web Interface + +Or execute in PowerShell:: + + PS C:\> New-NetFirewallRule -DisplayName "Fess Web Interface" -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow + +Troubleshooting +=============== + +Port Conflict +------------- + +If port 8080 or 9200 is already in use, you can check with the following command:: + + C:\> netstat -ano | findstr :8080 + C:\> netstat -ano | findstr :9200 + +Change the conflicting port number or stop the conflicting process. + +Path Length Limitation +---------------------- + +Windows has a path length limitation. It is recommended to install in a path as short as possible. + +Example:: + + C:\opensearch (recommended) + C:\Program Files\opensearch-3.9.0 (not recommended - path is too long) + +Java Not Recognized +------------------- + +If the ``java -version`` command displays an error: + +1. Verify that the ``JAVA_HOME`` environment variable is configured correctly +2. Verify that ``%JAVA_HOME%\bin`` is included in the ``PATH`` environment variable +3. Restart Command Prompt to reflect the settings + +Next Steps +========== + +After installation is complete, refer to the following documentation: + +- :doc:`run` - Starting |Fess| and initial setup +- :doc:`security` - Security configuration for production environments +- :doc:`troubleshooting` - Troubleshooting + +Frequently Asked Questions +=========================== + +Q: Is operation on Windows Server recommended? +----------------------------------------------- + +A: Yes, operation on Windows Server is possible. +When operating on Windows Server, register as a Windows service and configure appropriate monitoring. + +Q: What is the difference between 64-bit and 32-bit versions? +-------------------------------------------------------------- + +A: |Fess| and OpenSearch support only the 64-bit version. +They will not run on 32-bit Windows. + +Q: How to handle paths containing non-ASCII characters? +-------------------------------------------------------- + +A: Install in a path that does not contain non-ASCII characters or spaces whenever possible. +If you must use a non-ASCII path, you need to properly escape the path in configuration files. diff --git a/en/15.10/install/install.rst b/en/15.10/install/install.rst new file mode 100644 index 000000000..e1550b273 --- /dev/null +++ b/en/15.10/install/install.rst @@ -0,0 +1,247 @@ +============================ +Choosing an Installation Method +============================ + +This page provides an overview of |Fess| installation methods. +Select the appropriate installation method based on your environment. + +.. note:: + + |Fess| does not bundle a search engine. Every installation method below needs a + separate OpenSearch server. + +Verify Prerequisites +==================== + +Before starting the installation, verify the system requirements. + +For details, refer to :doc:`prerequisites`. + +Installation Method Comparison +=============================== + +|Fess| can be installed using the following methods. Choose according to your environment and use case. + +.. list-table:: + :header-rows: 1 + :widths: 15 25 30 30 + + * - Method + - Target OS + - Recommended Use + - Detailed Documentation + * - Docker + - Linux, Windows, macOS + - Development/evaluation environments, rapid setup + - :doc:`install-docker` + * - ZIP + - Linux, macOS + - Environments requiring customization + - :doc:`install-linux` + * - RPM + - RHEL, CentOS, Fedora + - Production environments (RPM-based) + - :doc:`install-linux` + * - DEB + - Debian, Ubuntu + - Production environments (DEB-based) + - :doc:`install-linux` + * - ZIP + - Windows + - Development/production on Windows + - :doc:`install-windows` + +Features of Each Installation Method +===================================== + +Docker Version +-------------- + +**Advantages:** + +- Fastest setup possible +- No need to manage dependencies +- Ideal for development environments +- Easy to start and stop containers + +**Disadvantages:** + +- Requires Docker knowledge + +**Recommended Environments:** Development, evaluation, PoC, and production environments + +Details: :doc:`install-docker` + +Linux Package Versions (ZIP/RPM/DEB) +---------------------------------------- + +**Advantages:** + +- High performance in native environments +- Can be managed as system services (RPM/DEB) +- Allows detailed customization + +**Disadvantages:** + +- Requires manual installation of Java and OpenSearch +- Configuration requires more effort + +**Recommended Environments:** Production environments (RPM/DEB, which can be managed as a system service, are recommended), environments requiring customization + +Details: :doc:`install-linux` + +Windows Version (ZIP) +--------------------- + +**Advantages:** + +- Runs in Windows native environments +- No installer required + +**Disadvantages:** + +- Requires manual installation of Java and OpenSearch +- Configuration requires more effort + +**Recommended Environments:** Development/evaluation on Windows, production operation on Windows Server + +Details: :doc:`install-windows` + +Basic Installation Flow +======================== + +The basic flow is the same for all installation methods. + +1. **Verify System Requirements** + + Refer to :doc:`prerequisites` to ensure system requirements are met. + +2. **Download Software** + + Download |Fess| from the `download site `__. + + For the Docker version, obtain the Docker Compose file. + +3. **Set Up OpenSearch** + + For non-Docker versions, OpenSearch must be set up separately. + + - Install OpenSearch 3.9.0 + - Install required plugins + - Edit configuration files + +4. **Set Up Fess** + + - Install Fess + - Edit configuration files (connection information to OpenSearch, etc.) + +5. **Start and Verify** + + - Start services + - Verify operation by accessing through a browser + + For details, refer to :doc:`run`. + +Required Components +=================== + +The following components are required to run |Fess|. + +Fess Main System +---------------- + +The main full-text search system. Provides functionality such as web interface, crawler, and indexer. + +OpenSearch +---------- + +OpenSearch is used as the search engine. + +- **Supported Version**: OpenSearch 3.9.0 +- **Required Plugins**: + + - opensearch-analysis-fess + - opensearch-analysis-extension + - opensearch-minhash + - opensearch-configsync + +.. important:: + + The OpenSearch version and plugin versions must match. + Version mismatches can cause startup errors or unexpected behavior. + +``bin/fess-setup install opensearch`` sets up OpenSearch with these plugins on Linux and Windows. See :doc:`install-linux` for details, including macOS, where OpenSearch has to be installed another way, and :doc:`fess-setup` for all commands. + +.. note:: + + If you use an OpenSearch to which you cannot add these plugins, such as a managed service, set ``search_engine.type`` to ``vanilla`` (|Fess| 15.10 and later). Some features, such as dictionary management, are then unavailable. See :doc:`../config/search-engine-type`. + +Java (Non-Docker Versions) +--------------------------- + +For ZIP/RPM/DEB versions, Java 21 or later is required. + +- Recommended: `Eclipse Temurin `__ +- OpenJDK 21 or later can also be used + +.. note:: + + For the Docker version, Java is included in the Docker image and does not need to be installed separately. + +Next Steps +========== + +Verify the system requirements and select the appropriate installation method. + +1. :doc:`prerequisites` - Verify system requirements +2. Choose an installation method: + + - :doc:`install-docker` - Docker installation + - :doc:`install-linux` - Linux installation + - :doc:`install-windows` - Windows installation + +3. :doc:`run` - Starting |Fess| and initial setup +4. :doc:`security` - Security configuration (for production environments) + +Frequently Asked Questions +=========================== + +Q: Is OpenSearch required? +--------------------------- + +A: Yes, it is required. |Fess| uses OpenSearch as its search engine. +For the Docker version, it is automatically set up, but for other methods, manual installation is necessary. + +Q: Can I upgrade from a previous version? +------------------------------------------ + +A: Yes, you can. For details, refer to :doc:`upgrade`. + +Q: Can I configure with multiple servers? +------------------------------------------ + +A: Yes, you can. Fess and OpenSearch can run on separate servers. +Additionally, by configuring OpenSearch as a cluster, high availability and improved performance can be achieved. + +Download +======== + +|Fess| and related components can be downloaded from: + +- **Fess**: `Download Site `__ +- **OpenSearch**: `Download OpenSearch `__ +- **Java (Adoptium)**: `Adoptium `__ +- **Docker**: `Get Docker `__ + +Version Information +=================== + +This document covers the following versions: + +- **Fess**: 15.10.0 +- **OpenSearch**: 3.9.0 +- **Java**: 21 or later +- **Docker**: 20.10 or later +- **Docker Compose**: 2.0 or later + +For documentation on previous versions, please refer to the documentation for each version. diff --git a/en/15.10/install/intro.rst b/en/15.10/install/intro.rst new file mode 100644 index 000000000..ed6e37085 --- /dev/null +++ b/en/15.10/install/intro.rst @@ -0,0 +1,70 @@ +============================ +Introduction to Installation +============================ + +About This Document +=================== + +This installation guide describes the procedures for installing, starting, upgrading, and uninstalling |Fess|. +Select the appropriate installation method according to your environment. + +Target Audience +=============== + +This document is intended for users responsible for installing and uninstalling |Fess|. + +Before You Begin +================ + +This document provides installation instructions for |Fess|. The following knowledge is required: + +- Basic server administration +- Linux or Windows command-line operations +- Basic network and firewall configuration +- Docker fundamentals (if using the Docker version) + +Document Structure +================== + +This installation guide consists of the following sections: + +- **System Requirements**: Hardware and software requirements for running |Fess| +- **Installation**: Platform-specific installation procedures + + - Choosing an installation method (overview and comparison) + - Linux (ZIP/RPM/DEB) installation + - Windows (ZIP) installation + - Docker installation + +- **Startup, Shutdown, and Initial Setup**: Starting, stopping, and initial setup of the |Fess| server +- **Security Settings**: Recommended security configurations for production environments +- **Upgrade**: Procedures for upgrading from previous versions to the latest release +- **Uninstall**: Complete uninstallation procedures for |Fess| +- **Troubleshooting**: Common issues and solutions + +Online Access +============= + +For downloads, professional services, support, and other developer information, visit: + +- Project Site: `https://fess.codelibs.org/ `__ + +Technical Support Contact +========================= + +For technical questions or issues regarding this product, visit: + +- Issues: `https://github.com/codelibs/fess/issues `__ + +Commercial Support +------------------ + +For commercial support including technical assistance and maintenance, please contact `N2SM, Inc. `__. + +How to Submit Comments and Suggestions +======================================= + +If you have any issues or suggestions for improvement, please submit them here: + +- Product Issues: `https://github.com/codelibs/fess/issues `__ +- Documentation Issues: `https://github.com/codelibs/fess-docs/issues `__ diff --git a/en/15.10/install/prerequisites.rst b/en/15.10/install/prerequisites.rst new file mode 100644 index 000000000..18ffdf858 --- /dev/null +++ b/en/15.10/install/prerequisites.rst @@ -0,0 +1,185 @@ +=================== +System Requirements +=================== + +This page describes the hardware and software requirements for running |Fess|. + +Hardware Requirements +===================== + +Minimum Requirements +-------------------- + +The following are minimum requirements for evaluation and development environments: + +- CPU: 2 cores or more +- Memory: 4GB or more +- Disk Space: 10GB or more of available space + +Recommended Requirements +------------------------ + +For production environments, the following specifications are recommended: + +- CPU: 4 cores or more +- Memory: 8GB or more (scale up according to index size) +- Disk Space: + + - System: 20GB or more + - Data: 3 times the index size or more (including replicas) + +- Network: 1Gbps or faster + +.. note:: + + When the index size is large or you perform high-frequency crawling, + increase memory and disk space appropriately. + +Software Requirements +===================== + +Operating Systems +----------------- + +|Fess| runs on the following operating systems: + +**Linux** + +- Red Hat Enterprise Linux 8 or later +- CentOS 8 or later +- Ubuntu 20.04 LTS or later +- Debian 11 or later +- Other Linux distributions (environments where Java 21 can run) + +**Windows** + +- Windows Server 2019 or later +- Windows 10 or later + +**Others** + +- macOS 11 (Big Sur) or later (recommended for development environments only; OpenSearch publishes no macOS build, so install it with Homebrew or Docker) +- Environments where Docker can run + +Required Software +----------------- + +The required software varies depending on the installation method: + +ZIP/RPM/DEB Versions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- **Java 21**: `Eclipse Temurin `__ is recommended + + - OpenJDK 21 or later + - Eclipse Temurin 21 or later + +- **OpenSearch 3.9.0**: Required. |Fess| refuses to start against an engine older than OpenSearch 3 + + - Supported Version: OpenSearch 3.9.0 + - Compatibility with plugins must be considered for other versions + +Docker Version +~~~~~~~~~~~~~~ + +- **Docker**: 20.10 or later +- **Docker Compose**: 2.0 or later + +Network Requirements +==================== + +Required Ports +-------------- + +The main ports used by |Fess| are as follows: + +.. list-table:: + :header-rows: 1 + :widths: 15 15 50 + + * - Port + - Protocol + - Purpose + * - 8080 + - HTTP + - |Fess| Web Interface (search and admin screens) + * - 9200 + - HTTP + - OpenSearch HTTP API (communication from |Fess| to OpenSearch) + * - 9300 + - TCP + - OpenSearch transport communication (cluster configuration) + +.. warning:: + + In production environments, strongly recommend restricting direct external access to ports 9200 and 9300. + These ports should only be used for internal communication between |Fess| and OpenSearch. + +Firewall Settings +----------------- + +To make |Fess| accessible from external sources, port 8080 must be opened. + +**Linux (using firewalld)** + +:: + + $ sudo firewall-cmd --permanent --add-port=8080/tcp + $ sudo firewall-cmd --reload + +**Linux (using iptables)** + +:: + + $ sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT + $ sudo iptables-save + +Browser Requirements +==================== + +The following browsers are recommended for |Fess| admin and search screens: + +- Google Chrome (latest version) +- Mozilla Firefox (latest version) +- Microsoft Edge (latest version) +- Safari (latest version) + +.. note:: + + Internet Explorer is not supported. + +Prerequisites Checklist +======================= + +Before installation, verify the following items: + +.. list-table:: + :header-rows: 1 + :widths: 50 50 + + * - Verification Item + - Status + * - Hardware requirements met + - □ + * - Java 21 installed (except Docker version) + - □ + * - Docker installed (Docker version) + - □ + * - Required ports available + - □ + * - Firewall configured appropriately + - □ + * - Sufficient disk space available + - □ + * - Network connection working (for crawling external sites) + - □ + +Next Steps +========== + +After verifying the system requirements, proceed to the installation procedure for your environment: + +- :doc:`install-linux` - Linux (ZIP/RPM/DEB) Installation +- :doc:`install-windows` - Windows (ZIP) Installation +- :doc:`install-docker` - Docker Installation +- :doc:`install` - Installation Method Overview diff --git a/en/15.10/install/run.rst b/en/15.10/install/run.rst new file mode 100644 index 000000000..d72ecdf31 --- /dev/null +++ b/en/15.10/install/run.rst @@ -0,0 +1,544 @@ +============================= +Startup, Shutdown, and Initial Setup +============================= + +This page describes the procedures for starting, stopping, and initial setup of the |Fess| server. + +.. important:: + + Before starting |Fess|, you must start OpenSearch. + If OpenSearch is not running, |Fess| will not function correctly. + +Startup Methods +=============== + +The startup procedure varies depending on the installation method. + +ZIP Version +-------------- + +Start OpenSearch +~~~~~~~~~~~~~~~~ + +:: + + $ cd /path/to/opensearch-3.9.0 + $ ./bin/opensearch + +To start in the background:: + + $ ./bin/opensearch -d + +.. note:: + + ``bin/fess-setup install opensearch`` puts OpenSearch in ``opensearch/opensearch-3.9.0`` in the + |Fess| directory. + +.. important:: + + Start OpenSearch as a regular user. It refuses to run as ``root`` and exits with + ``can not run opensearch as root``. The refused start still leaves files such as + ``config/opensearch.keystore`` owned by ``root``, and the next start as a regular user then + fails with ``AccessDeniedException``. Give the OpenSearch directory back to that user before + starting it again, for example:: + + $ sudo chown -R /path/to/opensearch-3.9.0 + +Start Fess +~~~~~~~~~~ + +:: + + $ cd /path/to/fess-15.10.0 + $ ./bin/fess + +To start in the background:: + + $ ./bin/fess -d + +.. note:: + + Startup may take several minutes. + You can check the startup status in the log files in ``logs/``: ``fess.log`` holds the + messages of |Fess| itself, and ``server_0.log`` those of the embedded Tomcat, including the + startup-completion message. + +ZIP Version (Windows) +--------------------- + +Start OpenSearch +~~~~~~~~~~~~~~~~ + +1. Open the OpenSearch installation directory +2. Double-click ``opensearch.bat`` in the ``bin`` folder + +Or from Command Prompt:: + + C:\> cd C:\opensearch-3.9.0 + C:\opensearch-3.9.0> bin\opensearch.bat + +Start Fess +~~~~~~~~~~ + +1. Open the Fess installation directory +2. Double-click ``fess.bat`` in the ``bin`` folder + +Or from Command Prompt:: + + C:\> cd C:\fess-15.10.0 + C:\fess-15.10.0> bin\fess.bat + +RPM/DEB Version (chkconfig) +--------------------------- + +Start OpenSearch:: + + $ sudo service opensearch start + +Start Fess:: + + $ sudo service fess start + +Check startup status:: + + $ sudo service fess status + +RPM/DEB Version (systemd) +------------------------- + +Start OpenSearch:: + + $ sudo systemctl start opensearch.service + +Start Fess:: + + $ sudo systemctl start fess.service + +Check startup status:: + + $ sudo systemctl status fess.service + +Enable automatic startup:: + + $ sudo systemctl enable opensearch.service + $ sudo systemctl enable fess.service + +Docker Version +-------------- + +.. note:: + + ``compose.yaml`` and ``compose-opensearch3.yaml`` are not included with + |Fess| itself. They are provided by the docker-fess project + (https://github.com/codelibs/docker-fess); obtain the repository and run the + following commands inside the ``compose`` directory. + +Start using Docker Compose:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +Check startup status:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps + +Check logs:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01 + +Verify Startup +============== + +Verify that |Fess| has started successfully. + +Health Check +------------ + +Access the following URL using a browser or curl command:: + + http://localhost:8080/ + +If started successfully, the Fess search screen will be displayed. + +Check from command line:: + + $ curl -I http://localhost:8080/ + +If ``HTTP/1.1 200 OK`` is returned, it has started successfully. + +Check Logs +---------- + +Check the startup logs to ensure there are no errors. + +ZIP version:: + + $ tail -f /path/to/fess-15.10.0/logs/fess.log + +RPM/DEB version:: + + $ sudo tail -f /var/log/fess/fess.log + +Or use journalctl:: + + $ sudo journalctl -u fess.service -f + +Docker version:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01 + +.. tip:: + + When startup completes successfully, a startup-completion message like the + following is written to ``server_0.log`` in the log directory (``logs/`` of the ZIP version, + ``/var/log/fess/`` of the RPM/DEB version). It is not shown on the console and is not written + to ``fess.log``:: + + ...Booting the Tomcat: port=8080 contextPath= + ... + Boot successful: url -> http://localhost:8080 + +Access via Browser +================== + +Access the following URLs to verify the web interface. + +Search Screen +------------- + +**URL**: http://localhost:8080/ + +The Fess search screen will be displayed. In the initial state, no search results will be displayed because no crawl configuration has been performed. + +The search screen is ``bootstrap``, the static theme bundled with |Fess|. To change how it looks, +install another theme from "System" > "Theme" in the admin screen or with +``bin/fess-setup install theme `` (see :doc:`fess-setup`), or copy the bundled theme and +change the copy (see :ref:`theme-customize-bundled`). + +Admin Screen +------------ + +**URL**: http://localhost:8080/admin + +Default administrator account: + +- **Username**: ``admin`` +- **Password**: ``admin`` + +.. warning:: + + **Important Security Notice** + + You must change the default password. + Especially in production environments, it is strongly recommended to change the password immediately after the first login. + +Initial Setup +============= + +After logging into the admin screen, perform the following initial configuration. + +Step 1: Change Administrator Password +-------------------------------------- + +1. Log in to the admin screen (http://localhost:8080/admin) +2. Click "User" → "User" from the left menu +3. Click the ``admin`` user +4. Enter a new password in the [Password] field +5. Re-enter the same password in the [Password (Confirm)] field +6. Click the [Update] button + +.. important:: + + Passwords should meet the following criteria: + + - 8 characters or more (the required minimum length set by ``password.min.length``) + - Combination of uppercase letters, lowercase letters, numbers, and symbols + - Not easily guessed + + By default, only the minimum length (8 characters) is required; a combination + of character types is not enforced. Character-type requirements can be enabled + with settings such as ``password.require.uppercase``. + +Step 2: Create Crawl Configuration +----------------------------------- + +Create a configuration to crawl target sites or file systems. + +1. Click "Crawler" → "Web" from the left menu +2. Click the "New" button +3. Enter required information: + + - **Name**: Name of the crawl configuration (e.g., Company Website) + - **URL**: Target URL for crawling (e.g., https://www.example.com/). To specify multiple URLs, enter one URL per line + - **Max Access Count**: Maximum number of documents to crawl (optional) + - **Interval**: Wait time between accesses (milliseconds; default: ``10000``) + + .. note:: + + Other items (such as user agent, number of threads, and depth) use their + default values when left blank. + +4. Click the "Create" button + +Step 3: Execute Crawl +--------------------- + +1. Click "System" → "Scheduler" from the left menu +2. Open the [Default Crawler] job and click the "Start Now" button +3. Wait for the crawl to complete (progress can be checked on the dashboard) + +Step 4: Verify Search +--------------------- + +1. Access the search screen (http://localhost:8080/) +2. Enter a search keyword +3. Verify that search results are displayed + +.. note:: + + Crawling may take time. + For large-scale sites, it may take from several hours to several days. + +Other Recommended Settings +=========================== + +For production environments, consider the following settings. + +Main Settings via Environment Variables +--------------------------------------- + +Settings such as the port number, JVM heap size, and the OpenSearch connection +URL can be changed via environment variables. Edit ``bin/fess.in.sh`` for the +ZIP edition, ``/etc/sysconfig/fess`` for the RPM edition, and +``/etc/default/fess`` for the DEB edition. A restart of |Fess| is required after +making changes. + +.. list-table:: + :header-rows: 1 + :widths: 30 25 45 + + * - Environment Variable + - Default + - Description + * - ``FESS_PORT`` + - ``8080`` + - The HTTP port that |Fess| listens on. + * - ``FESS_HEAP_SIZE`` + - (unset) + - JVM heap size. Sets the same value for the minimum and maximum. When unset, a minimum of ``256m`` and a maximum of ``2g`` are used (the Windows ZIP edition uses a maximum of ``1g``); the RPM/DEB edition uses ``512m``. + * - ``SEARCH_ENGINE_HTTP_URL`` + - ``http://localhost:9200`` + - URL of the OpenSearch to connect to. For the ZIP distribution, ``bin/fess.in.sh`` sets this by default. Export the variable, or edit ``bin/fess.in.sh``, when OpenSearch runs on a different port or host. The RPM/DEB edition sets it in the package environment file. + * - ``FESS_LOG_LEVEL`` + - ``warn`` + - Log level of |Fess|. + * - ``FESS_HEAP_NEWSIZE`` + - (unset) + - Size of the young generation of the JVM heap (``-Xmn``), such as ``256m``. When unset, the JVM decides. + * - ``FESS_TEMP_PATH`` + - ``temp`` in the |Fess| directory (RPM/DEB edition: ``/var/tmp/fess``) + - Directory for temporary files, including the working directory of the embedded Tomcat. The user that runs |Fess| must be able to write to it. + * - ``FESS_CONF_PATH`` + - (unset) (RPM/DEB edition: ``/etc/fess``) + - Directory that holds the configuration files. ``bin/fess`` places it at the front of the class path and passes it to |Fess| as ``-Dfess.conf.path``. For files such as ``tomcat_config.properties`` in ``lib/classes``, the one in this directory takes priority. However, in the ZIP edition the web application reads the files in ``app/WEB-INF/classes`` first, so a ``fess_config.properties`` placed in this directory does not override the values of the ``fess_config.properties`` in ``app/WEB-INF/classes`` (child processes such as the crawler read this directory before ``WEB-INF/classes``). In the ZIP edition, edit the file in ``app/WEB-INF/classes`` to change ``fess_config.properties``. The RPM/DEB edition does not put a ``fess_config.properties`` in ``app/WEB-INF/classes`` and uses only the one in ``/etc/fess``. + * - ``FESS_USE_IPV4`` + - (unset) + - With any non-empty value, the JVM uses the IPv4 stack only (``-Djava.net.preferIPv4Stack=true``). + * - ``FESS_USE_GC_LOGGING`` + - (unset) + - With any non-empty value, the JVM writes its garbage collection log to ``gc-fess.log`` in the log directory (up to 5 files of 64 MB). + +.. note:: + + The environment variables that the Windows ZIP edition's ``bin\fess.in.bat`` reads are + ``FESS_HEAP_SIZE``, ``FESS_HEAP_NEWSIZE``, ``FESS_USE_IPV4`` and + ``FESS_USE_GC_LOGGING`` from the table above, and the following ones that are not in the table. + + - ``FESS_MIN_MEM``, ``FESS_MAX_MEM``: Specify the minimum and maximum heap sizes individually (ignored when ``FESS_HEAP_SIZE`` is set). + - ``FESS_DIRECT_SIZE``: Upper limit of direct memory (``-XX:MaxDirectMemorySize``). + - ``FESS_DICTIONARY_PATH``: The ``config\dictionary`` directory of OpenSearch. + - ``FESS_PROXY_HOST``, ``FESS_PROXY_PORT``, ``FESS_NON_PROXY_HOSTS``: Proxy settings. + - ``FESS_JAVA_OPTS``: ``fess.in.bat`` appends these JVM options after the values already set. + - ``PLAYWRIGHT_NODEJS_PATH``: The Node.js executable used by the Playwright plugin. + - ``JAVA_HOME``: Required. + + ``FESS_PORT``, ``FESS_LOG_LEVEL``, ``FESS_TEMP_PATH``, ``FESS_CONF_PATH`` and ``SEARCH_ENGINE_HTTP_URL`` + are not read. These values are written directly in the file, so edit ``bin\fess.in.bat`` directly to change them. + +Configure Mail Server +--------------------- + +To receive failure notifications and similar messages by email, configure the +SMTP server and the notification recipient address. + +1. In ``fess_env_web.properties`` and ``fess_env_crawler.properties``, specify the + SMTP server host and port in ``mail.smtp.server.main.host.and.port`` + (default: ``localhost:25``). The files are in ``app/WEB-INF/classes/`` for the + ZIP package and in ``/etc/fess/`` for the RPM/DEB packages. The |Fess| web + process reads the first, and the crawler, which sends the crawl completion + mail, reads the second; ``fess_env.properties`` is not used. A restart of + |Fess| is required after the change. +2. In the admin UI, click [System] → [General] in the left menu. +3. Enter the recipient email address in the [Notification Mail] field. +4. Click the [Update] button. +5. You can verify that mail is sent correctly with the [Send Test Mail] button. + +Configure Time Zone +------------------- + +|Fess| uses the server's (OS / JVM) time zone. There is no setting to change the +time zone in the admin UI. To change it, change the OS time zone setting, or add +the JVM option ``-Duser.timezone=Asia/Tokyo`` to ``FESS_JAVA_OPTS`` in +``bin/fess.in.sh`` (on Windows, ``bin\fess.in.bat``). + +Adjust Log Level +---------------- + +In production, you can adjust the log level to reduce disk usage. + +The overall log level of |Fess| can be changed with the ``FESS_LOG_LEVEL`` +environment variable (default: ``warn``). To control individual loggers in +detail, edit the config file ``app/WEB-INF/classes/log4j2.xml``. Crawling, +suggest, and thumbnail generation run as separate processes, so configure their +log levels individually in +``app/WEB-INF/env/{crawler,suggest,thumbnail}/resources/log4j2.xml``. + +See :doc:`../admin/index` for details. + +Shutdown Methods +================ + +ZIP Version +------------------ + +Stop Fess +~~~~~~~~~ + +Kill the process:: + + $ ps aux | grep fess + $ kill + +Or, stop from the console with ``Ctrl+C`` (if running in the foreground). + +Stop OpenSearch:: + + $ ps aux | grep opensearch + $ kill + +RPM/DEB Version (chkconfig) +--------------------------- + +Stop Fess:: + + $ sudo service fess stop + +Stop OpenSearch:: + + $ sudo service opensearch stop + +RPM/DEB Version (systemd) +------------------------- + +Stop Fess:: + + $ sudo systemctl stop fess.service + +Stop OpenSearch:: + + $ sudo systemctl stop opensearch.service + +Docker Version +-------------- + +Stop containers:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop + +Stop and remove containers:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +.. warning:: + + To also delete volumes with the ``down`` command, add the ``-v`` option. + In this case, all data will be deleted, so use with caution. + +Restart Methods +=============== + +ZIP Version +------------------ + +Stop and then start. + +RPM/DEB Version +--------------- + +chkconfig:: + + $ sudo service fess restart + +systemd:: + + $ sudo systemctl restart fess.service + +Docker Version +-------------- + +:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml restart + +Troubleshooting +=============== + +Won't Start +----------- + +1. **Verify OpenSearch is running** + + :: + + $ curl http://localhost:9200/ + + If OpenSearch is not running, start OpenSearch first. + +2. **Check for port conflicts** + + :: + + $ sudo ss -tuln | grep 8080 + + Where net-tools is installed, ``sudo netstat -tuln | grep 8080`` shows the same information. + + If port 8080 is already in use, change the port number. + + - ZIP edition: change ``FESS_PORT`` in ``bin/fess.in.sh`` + - ZIP edition (Windows): edit ``-Dfess.port=8080`` directly in ``bin\fess.in.bat`` + - RPM edition: change ``FESS_PORT`` in ``/etc/sysconfig/fess`` + - DEB edition: change ``FESS_PORT`` in ``/etc/default/fess`` + +3. **Check logs** + + Identify the problem from error messages. + +4. **Verify Java version** + + :: + + $ java -version + + Verify that Java 21 or later is installed. + +For detailed troubleshooting, refer to :doc:`troubleshooting`. + +Next Steps +========== + +After |Fess| has started successfully, refer to the following documentation to begin operation: + +- :doc:`../admin/index` - Details on crawl configuration, search settings, and system settings +- :doc:`security` - Security configuration for production environments +- :doc:`troubleshooting` - Common problems and solutions +- :doc:`upgrade` - Version upgrade procedures +- :doc:`uninstall` - Uninstall procedures diff --git a/en/15.10/install/security.rst b/en/15.10/install/security.rst new file mode 100644 index 000000000..685312afc --- /dev/null +++ b/en/15.10/install/security.rst @@ -0,0 +1,355 @@ +==================== +Security Configuration +==================== + +This page describes the security configurations recommended for safe operation of |Fess| in production environments. + +.. danger:: + + **Security is Critical** + + In production environments, it is strongly recommended to implement all security configurations described on this page. + Failure to implement proper security configurations increases the risk of unauthorized access, data breaches, and system compromise. + +Essential Security Configurations +================================== + +Change Administrator Password +------------------------------ + +The default administrator password (``admin`` / ``admin``) must be changed. + +**Procedure:** + +1. Log in to the admin screen: http://localhost:8080/admin +2. Click "User" → "User" +3. Select the ``admin`` user +4. Set a strong password +5. Click the "Update" button + +.. note:: + + Once you have changed the password from ``admin``, you cannot set it back to a simple value such as ``admin`` (a blacklist of administrator passwords is configured via ``password.invalid.admin.passwords``). You can also change the initial password of the ``admin`` user before the first startup by setting ``index.user.initial_password`` in ``fess_config.properties``. + +**Recommended Password Policy:** + +|Fess| provides a built-in feature that enforces the minimum/maximum password length and character-type requirements. Configure the following properties in ``fess_config.properties`` (defaults in parentheses): + +- ``password.min.length`` (default: ``8``): Minimum length. 12 or more is recommended. +- ``password.max.length`` (default: ``100``): Maximum length. +- ``password.require.uppercase`` (default: ``false``): Require uppercase letters. +- ``password.require.lowercase`` (default: ``false``): Require lowercase letters. +- ``password.require.digit`` (default: ``false``): Require digits. +- ``password.require.special.char`` (default: ``false``): Require symbols. + +.. note:: + + By default, the minimum length is ``8`` and all character-type requirements are disabled. To strengthen passwords, set the properties above explicitly. Note that |Fess| has no password expiration (forced periodic change) feature; if you want to enforce periodic password changes as an operational rule, do so manually. + +Enable OpenSearch Security Plugin +---------------------------------- + +**Procedure:** + +1. Remove or comment out the following line from ``opensearch.yml``:: + + # plugins.security.disabled: true + +2. Configure the security plugin:: + + plugins.security.allow_default_init_securityindex: true + plugins.security.authcz.admin_dn: + - CN=admin,OU=SSL,O=Test,L=Test,C=DE + +3. Configure TLS/SSL certificates + +4. Restart OpenSearch + +5. Configure the connection to OpenSearch on the |Fess| side. + + Specify the connection URL with the ``SEARCH_ENGINE_HTTP_URL`` environment variable (edit ``bin/fess.in.sh`` or the service environment file; the default value comes from ``search_engine.http.url`` in ``fess_config.properties``):: + + SEARCH_ENGINE_HTTP_URL=https://opensearch:9200 + + Specify the credentials with the following properties in ``fess_config.properties`` (there are no ``SEARCH_ENGINE_USERNAME`` / ``SEARCH_ENGINE_PASSWORD`` environment variables):: + + search_engine.username=admin + search_engine.password= + +For details, refer to the `OpenSearch Security Plugin `__. + +Enable HTTPS +------------ + +HTTP communication is not encrypted and poses risks of eavesdropping and tampering. Always use HTTPS in production environments. + +**Method 1: Using a Reverse Proxy (Recommended)** + +Deploy Nginx or Apache in front of |Fess| for HTTPS termination. + +Nginx configuration example:: + + server { + listen 443 ssl http2; + server_name your-fess-domain.com; + + ssl_certificate /path/to/cert.pem; + ssl_certificate_key /path/to/key.pem; + + ssl_protocols TLSv1.2 TLSv1.3; + ssl_ciphers HIGH:!aNULL:!MD5; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + } + +**Method 2: Configure HTTPS in Fess Itself** + +Add the following to ``tomcat_config.properties``:: + + tomcat.secure=true + tomcat.scheme=https + tomcat.SSLEnabled=true + tomcat.certificateKeystoreFile=[path to keystore file] + tomcat.certificateKeystorePassword=[password specified when creating the keystore file] + tomcat.certificateKeyAlias=[certificate alias] + tomcat.sslProtocol=[SSL protocol (e.g., TLS)] + tomcat.enabledProtocols=list of enabled protocols (comma-separated) (e.g., TLSv1.2,TLSv1.1,TLSv1) + +Recommended Security Configurations +==================================== + +Firewall Configuration +---------------------- + +Open only necessary ports and close unnecessary ones. + +**Ports to Open:** + +- **8080** (or 443 for HTTPS): |Fess| web interface (if external access is required) +- **22**: SSH (administration only, from trusted IP addresses only) + +**Ports to Close:** + +- **9200, 9300**: OpenSearch (internal communication only, block external access) + +Linux (firewalld) configuration example:: + + $ sudo firewall-cmd --permanent --add-service=http + $ sudo firewall-cmd --permanent --add-service=https + $ sudo firewall-cmd --permanent --remove-service=opensearch # for custom services + $ sudo firewall-cmd --reload + +IP address restriction:: + + $ sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="192.168.1.0/24" port port="8080" protocol="tcp" accept' + +Access Control Configuration +----------------------------- + +Consider restricting access to the admin screen to specific IP addresses. + +Nginx access restriction example:: + + location /admin { + allow 192.168.1.0/24; + deny all; + + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + } + +Roles and Access Control +------------------------ + +|Fess| provides two built-in roles: + +- ``admin``: Administrator role that can perform all operations, including the admin screen. +- ``guest``: Role assigned to unauthenticated (anonymous) users. + +Any other roles can be freely created from the admin screen. In |Fess|, a role is a tag that has only a name and is used mainly for access control of search results (which documents a user can view). The exception is a role named ``admin-`` followed by the name of an admin screen, such as ``admin-user`` or ``admin-scheduler``: it allows a user to open that screen, and the ``-view`` form, such as ``admin-user-view``, allows read-only access. + +.. warning:: + + The ``admin-*`` roles let you split day-to-day admin screens among operators, but they are not a privilege boundary. A user with ``admin-user`` can give any existing role, including the administrator role, to any user; ``admin-accesstoken`` can issue an access token with the ``Radmin-api`` permission, which grants the whole Admin API; ``admin-scheduler`` can run script jobs on the server; and ``admin-plugin`` can install plugins. Treat every ``admin-*`` role as equivalent to the administrator role (``authentication.admin.roles``, default ``admin``) and grant them only to trusted operators. + +Following the principle of least privilege, grant the administrator role (``admin``) only to users who perform administrative tasks, and do not grant it to general search users. + +**Procedure:** + +1. Click "User" → "Role" in the admin screen +2. Create the necessary roles +3. Assign roles to users in "User" → "User" + +Audit Logging +------------- + +System operation history, such as authentication and administrative operations, is recorded as an audit log by default. The audit log is output by the ``fess.log.audit`` logger defined in ``log4j2.xml``, and its default output destination is ``audit.log``. + +Because it is enabled by default, no additional configuration is required. To customize the output destination or log level, edit the following definition in ``log4j2.xml``:: + + + + + +Regular Security Updates +------------------------ + +Apply security updates for |Fess| and OpenSearch regularly. + +**Recommended Procedure:** + +1. Regularly check security information + + - `Fess Release Information `__ + - `OpenSearch Security Advisories `__ + +2. Validate updates in a test environment +3. Apply updates to the production environment + +Data Protection +=============== + +Encrypt Backups +--------------- + +Backup data may contain sensitive information. Store backup files encrypted. + +Encrypted backup example:: + + $ tar czf fess-backup.tar.gz /var/lib/opensearch /etc/fess + $ gpg --symmetric --cipher-algo AES256 fess-backup.tar.gz + +Security Best Practices +======================== + +Principle of Least Privilege +----------------------------- + +- Do not run Fess and OpenSearch as the root user +- Run with a dedicated user account +- Grant minimum necessary filesystem permissions + +Network Isolation +----------------- + +- Deploy OpenSearch in a private network +- Use VPN or private networks for internal communication +- Deploy only the |Fess| web interface in a DMZ + +Regular Security Audits +----------------------- + +- Regularly review access logs +- Detect abnormal access patterns +- Conduct regular vulnerability scans + +Security Header Configuration +------------------------------ + +Configure security headers in Nginx or Apache as needed:: + + add_header X-Frame-Options "SAMEORIGIN" always; + add_header X-Content-Type-Options "nosniff" always; + add_header X-XSS-Protection "1; mode=block" always; + add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; + add_header Content-Security-Policy "default-src 'self'" always; + +Security Checklist +================== + +Before deploying to production, verify the following checklist: + +Basic Configuration +------------------- + +- [ ] Administrator password changed +- [ ] HTTPS enabled +- [ ] Default port numbers changed (optional) + +Network Security +---------------- + +- [ ] Unnecessary ports closed with firewall +- [ ] Admin screen access IP restricted (if possible) +- [ ] OpenSearch access restricted to internal network only + +Access Control +-------------- + +- [ ] Configured roles and access permissions appropriately (grant the administrator role only to necessary users) +- [ ] Unnecessary user accounts removed +- [ ] Password policy configured + +Monitoring and Logging +---------------------- + +- [ ] Confirmed that audit logging is enabled +- [ ] Log retention period configured +- [ ] Log monitoring mechanism established (if possible) + +Backup and Recovery +------------------- + +- [ ] Regular backup schedule configured +- [ ] Backup data encrypted +- [ ] Restore procedures validated + +Updates and Patch Management +----------------------------- + +- [ ] Security update notification mechanism established +- [ ] Update procedures documented +- [ ] Test environment established for update validation + +Security Incident Response +=========================== + +Response procedure when a security incident occurs: + +1. **Incident Detection** + + - Log review + - Abnormal access pattern detection + - System behavior anomaly verification + +2. **Initial Response** + + - Identify scope of impact + - Prevent damage escalation (stop relevant services, etc.) + - Preserve evidence + +3. **Investigation and Analysis** + + - Detailed log analysis + - Identify intrusion routes + - Identify potentially leaked data + +4. **Recovery** + + - Fix vulnerabilities + - Restore systems + - Strengthen monitoring + +5. **Post-Incident Response** + + - Create incident report + - Implement recurrence prevention measures + - Report to stakeholders + +Reference Information +===================== + +- `OpenSearch Security Plugin `__ +- `OWASP Top 10 `__ +- `CIS Benchmarks `__ + +For security questions or issues, please contact: + +- Issues: https://github.com/codelibs/fess/issues +- Commercial Support: https://www.n2sm.net/ diff --git a/en/15.10/install/troubleshooting.rst b/en/15.10/install/troubleshooting.rst new file mode 100644 index 000000000..6d8a0b26a --- /dev/null +++ b/en/15.10/install/troubleshooting.rst @@ -0,0 +1,595 @@ +=============== +Troubleshooting +=============== + +This page describes common problems and solutions during installation, startup, and operation of |Fess|. + +Installation Issues +=================== + +Java Not Recognized +------------------- + +**Symptoms:** + +:: + + -bash: java: command not found + +Or:: + + 'java' is not recognized as an internal or external command + +**Cause:** + +Java is not installed, or the PATH environment variable is not configured correctly. + +**Solution:** + +1. Verify Java is installed:: + + $ which java + $ java -version + +2. If not installed, install Java 21:: + + # Ubuntu/Debian + $ sudo apt-get update + $ sudo apt-get install openjdk-21-jdk + + # RHEL/CentOS + $ sudo yum install java-21-openjdk + + The standard repositories of Debian 12 have no ``openjdk-21-jdk`` package. On Debian 12, install Eclipse Temurin 21 instead, following the instructions for Debian in the `Adoptium installation guide for Linux `__. + +3. Set JAVA_HOME environment variable:: + + $ export JAVA_HOME=/path/to/java + $ export PATH=$JAVA_HOME/bin:$PATH + + For persistent configuration, add to ``~/.bashrc`` or ``/etc/profile``. + +Plugin Installation Fails +-------------------------- + +**Symptoms:** + +:: + + ERROR: Plugin installation failed + +**Causes:** + +- Network connection issues +- Plugin version does not match OpenSearch version +- Permission issues + +**Solution:** + +1. Verify OpenSearch version:: + + $ /path/to/opensearch/bin/opensearch --version + +2. Match plugin version to OpenSearch version:: + + $ /path/to/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + +3. Verify permissions:: + + $ sudo /path/to/opensearch/bin/opensearch-plugin install ... + +4. For installation through a proxy:: + + $ export ES_JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080" + $ /path/to/opensearch/bin/opensearch-plugin install ... + +Startup Issues +============== + +Fess Won't Start +---------------- + +**Symptoms:** + +Fess startup command produces an error or exits immediately. + +**Verification Items:** + +1. **Verify OpenSearch is running**:: + + $ curl http://localhost:9200/ + + If working correctly, a JSON response will be returned. + + When no OpenSearch answers, |Fess| retries for about a minute and then stops starting up, with + the following message on the console and in ``logs/fess.log``:: + + The search engine at http://localhost:9200 did not become available within 60221ms. Check that OpenSearch is running and reachable. If there is none yet, run bin/fess-setup install opensearch to set one up. + + Start OpenSearch, or check ``SEARCH_ENGINE_HTTP_URL``. A new ZIP installation has no OpenSearch + until one is set up with ``bin/fess-setup install opensearch``; see :doc:`install-linux`. + +2. **Check for port conflicts**:: + + $ sudo ss -tuln | grep 8080 + + If port 8080 is already in use, change the port number in the configuration file. + +3. **Check log files**:: + + $ tail -f /path/to/fess/logs/fess.log + + Identify the cause from error messages. + +4. **Verify Java version**:: + + $ java -version + + Verify that Java 21 or later is installed. + +5. **Check for insufficient memory**:: + + $ free -h + + If memory is insufficient, adjust heap size or increase system memory. + +OpenSearch Won't Start +---------------------- + +**Symptoms:** + +:: + + ERROR: bootstrap checks failed + +**Cause:** + +System configuration does not meet OpenSearch requirements. + +**Solution:** + +1. **Set vm.max_map_count**:: + + $ sudo sysctl -w vm.max_map_count=262144 + + For persistent configuration:: + + $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf + $ sudo sysctl -p + +2. **Increase file descriptor limits**:: + + $ sudo vi /etc/security/limits.conf + + Add the following:: + + opensearch - nofile 65535 + opensearch - nproc 4096 + +3. **Configure memory locking**:: + + $ sudo vi /etc/security/limits.conf + + Add the following:: + + opensearch - memlock unlimited + +4. Restart OpenSearch:: + + $ sudo systemctl restart opensearch + +Index Cannot Be Created (Dictionary File Path) +---------------------------------------------- + +**Symptoms:** + +Accessing |Fess| returns HTTP 404, and the following error is written to ``fess.log``:: + + Failed to create index: index=fess, path=fess_indices/fess.json + ... reason=Resource path must be inside config directory: /var/lib/opensearch/data/config/ja/mapping.txt + +**Cause:** + +OpenSearch 3.8.0 and later refuse to create an index when dictionary files are outside the OpenSearch configuration directory. +``configsync.config_path`` and ``FESS_DICTIONARY_PATH`` point outside the configuration directory (such as ``data/config/``). + +**Solution:** + +1. Change ``configsync.config_path`` and ``FESS_DICTIONARY_PATH`` to a directory under the OpenSearch configuration directory. + + - RPM/DEB version: ``/etc/opensearch/dictionary/`` + - ZIP version: ``/path/to/opensearch-3.9.0/config/dictionary/`` + +2. If you have existing dictionary files, copy them to the new directory. +3. Restart OpenSearch, then |Fess|. + +For details, see :doc:`install-linux`. + +Port Conflict +------------- + +**Symptoms:** + +:: + + Address already in use + +**Solution:** + +1. Check ports in use:: + + $ sudo ss -tuln | grep 8080 + $ sudo lsof -i :8080 + +2. Stop the process using the port, or change Fess port number + + For port number changes, see :doc:Port and Network Settings <../config/setup-port-network>. + +Connection Issues +================= + +Fess Cannot Connect to OpenSearch +---------------------------------- + +**Symptoms:** + +Logs show errors like the following:: + + Connection refused + or + No route to host + +**Solution:** + +1. **Verify OpenSearch is running**:: + + $ curl http://localhost:9200/ + +2. **Verify connection URL** + + Verify the URL configured in ``fess.in.sh`` or ``fess.in.bat`` is correct:: + + SEARCH_ENGINE_HTTP_URL=http://localhost:9200 + +3. **Check firewall**:: + + $ sudo firewall-cmd --list-all + + Verify port 9200 is open. + +4. **Verify network connection** + + If OpenSearch is running on a different host:: + + $ ping opensearch-host + $ telnet opensearch-host 9200 + +Cannot Access Fess from Browser +-------------------------------- + +**Symptoms:** + +Cannot access http://localhost:8080/ in browser. + +**Solution:** + +1. **Verify Fess is running**:: + + $ ps aux | grep fess + +2. **Try accessing on localhost**:: + + $ curl http://localhost:8080/ + +3. **Check firewall**:: + + $ sudo firewall-cmd --list-all + + Verify port 8080 is open. + +4. **When accessing from another host** + + Verify Fess is listening beyond localhost:: + + $ ss -tuln | grep 8080 + + If ``127.0.0.1:8080``, configure to listen on ``0.0.0.0:8080`` or a specific IP address. + +Performance Issues +================== + +Slow Search +----------- + +**Causes:** + +- Large index size +- Insufficient memory +- Slow disk I/O +- Complex queries + +**Solution:** + +1. **Increase heap size** + + Start |Fess| with ``FESS_HEAP_SIZE`` passed as an environment variable:: + + $ FESS_HEAP_SIZE=4g bin/fess + + To set it in ``bin/fess.in.sh``, write ``FESS_HEAP_SIZE=4g`` **before** the line that determines the heap size (the line that sets the default value of ``FESS_MIN_MEM``). Appending it to the end of the file has no effect because the heap size has already been determined by then. For the RPM/DEB edition, set it in ``/etc/sysconfig/fess`` (``/etc/default/fess`` for DEB). + + Also adjust OpenSearch heap size:: + + export OPENSEARCH_JAVA_OPTS="-Xms4g -Xmx4g" + +2. **Use SSD** + + If disk I/O is a bottleneck, migrate to SSD. + +3. **Enable caching** + + Enable query cache in configuration file. + +Slow Crawling +------------- + +**Causes:** + +- Long crawl interval +- Slow target site response +- Insufficient number of threads + +**Solution:** + +1. **Adjust crawl interval** + + Shorten the "Interval" in crawl configuration on the admin screen (in milliseconds). + + .. warning:: + + If the interval is too short, it may overload the target site. Set an appropriate value. + +2. **Increase number of threads** + + Increase the "Number of Threads" of the crawl configuration on the admin screen. The default is 1 for Web crawls and 5 for file system crawls. + +3. **Adjust timeout values** + + For sites with slow responses, increase timeout values. + +Data Issues +=========== + +No Search Results Displayed +---------------------------- + +**Causes:** + +- Index not created +- Crawl failed +- Incorrect search query + +**Solution:** + +1. **Verify index**:: + + $ curl http://localhost:9200/_cat/indices?v + + Verify |Fess| indexes exist. + +2. **Check crawl logs** + + Download the crawl log (``fess-crawler.log``) from "System Info" → "Log File" in the admin screen and check it for errors. + +3. **Re-run crawl** + + Execute "Default Crawler" from "System" → "Scheduler" in the admin screen. + +4. **Simplify search query** + + First search with simple keywords to verify results are returned. + +Index Corrupted +--------------- + +**Symptoms:** + +Errors occur during search or unexpected results are returned. + +**Solution:** + +1. **Delete and recreate index** + + .. warning:: + + Deleting the index will lose all search data. Always create a backup first. + + :: + + $ curl -X DELETE http://localhost:9200/fess* + +2. **Restart Fess** + + The indexes are created when |Fess| starts. Immediately after the deletion, the user information index is also lost, so you cannot log in to the admin screen (``/api/v2/health`` keeps returning ``200``). Restarting |Fess| recreates the indexes, the default jobs, and the initial user (``admin``). + +3. **Re-run crawl** + + Execute "Default Crawler" from the admin screen to register the documents to be searched again. + +Docker-Specific Issues +====================== + +Container Won't Start +--------------------- + +**Symptoms:** + +Container does not start with ``docker compose up``. + +**Solution:** + +1. **Check logs**:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs + +2. **Check for insufficient memory** + + Increase memory allocated to Docker (from Docker Desktop settings). + +3. **Check for port conflicts**:: + + $ docker ps + + Verify no other containers are using ports 8080 or 9200. + +4. **Verify Docker Compose file** + + Check for syntax errors in YAML file:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml config + +Container Starts But Cannot Access Fess +---------------------------------------- + +**Solution:** + +1. **Check container status**:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps + +2. **Check logs**:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs fess + +3. **Verify network settings**:: + + $ docker network ls + $ docker network inspect + +Windows-Specific Issues +======================= + +Path Issues +----------- + +**Symptoms:** + +Errors occur when paths contain spaces or Japanese characters. + +**Solution:** + +Install in a directory that does not contain spaces or Japanese characters in the path. + +Example:: + + C:\opensearch (recommended) + C:\Program Files\opensearch (not recommended) + +Cannot Register as Service +--------------------------- + +**Solution:** + +Use third-party tools such as NSSM to register as a Windows service. + +For details, refer to :doc:`install-windows`. + +Other Issues +============ + +Change Log Level +---------------- + +To check detailed logs, change the log level to DEBUG. + +Edit ``log4j2.xml``:: + + + +Reset Database +-------------- + +To reset configuration, delete OpenSearch indexes:: + + $ curl -X DELETE 'http://localhost:9200/fess_config.*' + +.. warning:: + + This command will delete all configuration data. + +Forgotten Administrator Password +-------------------------------- + +If you forgot the administrator password, you can reset it by updating the user document directly in the ``fess_user.user`` index of OpenSearch. The password is stored in the ``password`` field as a hash in the form ``{bcrypt}$2a$...``. The change takes effect without restarting |Fess|. + +1. Create the hash of the new password. |Fess| accepts only bcrypt hashes that start with ``$2a$``, so replace the ``$2y$`` printed by ``htpasswd`` (contained in the ``apache2-utils`` or ``httpd-tools`` package) with ``$2a$``. Replace ``NewPassword`` with the new password:: + + $ HASH=$(htpasswd -bnBC 10 "" 'NewPassword' | tr -d ':\n' | sed 's/^\$2y/$2a/') + +2. Update the password in the document of the admin user. The document ID of the admin user in its initial state is ``YWRtaW4=``:: + + $ curl -X POST 'http://localhost:9200/fess_user.user/_update/YWRtaW4=?refresh=true' \ + -H 'Content-Type: application/json' \ + -d "{\"doc\":{\"password\":\"{bcrypt}${HASH}\"}}" + + To reset the password of another user, look up the ``_id`` with ``curl 'http://localhost:9200/fess_user.user/_search?q=name:USERNAME'`` and use that ID. If authentication is enabled for OpenSearch, add the credentials to curl. + +3. Confirm that you can log in to the admin screen with the new password. If the password remains in your command history, set the password again under [User > User] after logging in. + +Support Information +=================== + +If problems cannot be resolved, use the following support resources: + +Community Support +----------------- + +- **Issues**: https://github.com/codelibs/fess/issues + + When reporting issues, include the following information: + + - Fess version + - OpenSearch version + - OS and version + - Error messages (excerpts from logs) + - Reproduction steps + +- **Forum**: https://discuss.codelibs.org/ + +Commercial Support +------------------ + +For commercial support needs, please contact N2SM, Inc.: + +- **Web**: https://www.n2sm.net/ + +Collecting Debug Information +============================= + +When reporting issues, collecting the following information is helpful: + +1. **Version information** (``bin/fess -v`` is available in 15.10 and later):: + + $ /path/to/fess/bin/fess -v + $ /path/to/opensearch/bin/opensearch --version + $ java -version + +2. **System information**:: + + $ uname -a + $ cat /etc/os-release + $ free -h + $ df -h + +3. **Log files**:: + + $ tar czf fess-logs.tar.gz /path/to/fess/logs/ + +4. **Configuration files** (after removing sensitive information):: + + $ tar czf fess-config.tar.gz /path/to/fess/app/WEB-INF/conf/ + +5. **OpenSearch status**:: + + $ curl http://localhost:9200/_cluster/health?pretty + $ curl http://localhost:9200/_cat/indices?v diff --git a/en/15.10/install/uninstall.rst b/en/15.10/install/uninstall.rst new file mode 100644 index 000000000..e66e07797 --- /dev/null +++ b/en/15.10/install/uninstall.rst @@ -0,0 +1,481 @@ +======================== +Uninstallation Procedure +======================== + +This page describes the procedures for completely uninstalling |Fess|. + +.. warning:: + + **Important Notes Before Uninstallation** + + - Uninstalling will delete all data + - If you have important data, be sure to create a backup first + - For backup procedures, refer to :doc:`upgrade` + +Preparation Before Uninstallation +================================= + +Create Backup +------------- + +Back up the necessary data: + +1. **Configuration Data** + + Download it from "System" → "Backup" in the admin screen. + This operation lets you export various settings (including crawl settings), search logs, and more all at once. + +2. **Customized Configuration Files** + + ZIP version:: + + $ cp -r /path/to/fess/app/WEB-INF/conf /backup/ + $ cp -r /path/to/fess/app/WEB-INF/classes /backup/ + + RPM/DEB version:: + + $ sudo cp -r /etc/fess /backup/ + +.. note:: + + Most of |Fess|'s indexes and settings are stored in OpenSearch. + To back up index data, use OpenSearch's snapshot feature. + For detailed procedures, refer to :doc:`upgrade`. + +Stop Services +------------- + +Before uninstallation, stop all services. + +ZIP version:: + + $ ps aux | grep -E 'fess|opensearch' + $ kill + $ kill + +RPM/DEB version:: + + $ sudo systemctl stop fess.service + $ sudo systemctl stop opensearch.service + +Docker version:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +Uninstalling the ZIP Version +=================================== + +Step 1: Remove Fess +------------------- + +Delete the installation directory:: + + $ rm -rf /path/to/fess-15.10.0 + +Step 2: Remove OpenSearch +------------------------- + +Delete the OpenSearch installation directory:: + + $ rm -rf /path/to/opensearch-3.9.0 + +Step 3: Delete the Data Directory (Optional) +-------------------------------------------- + +|Fess|'s index data is stored in OpenSearch. +By default it is stored inside the OpenSearch installation directory (such as ``opensearch-3.9.0/data``), +but if you have specified a different location with ``path.data``, delete that directory as well:: + + $ rm -rf /path/to/data + +Step 4: Delete the Log Directory (Optional) +------------------------------------------- + +Delete the log files:: + + $ rm -rf /path/to/fess-15.10.0/logs + $ rm -rf /path/to/opensearch-3.9.0/logs + +Uninstalling the RPM Version +============================ + +Step 1: Uninstall Fess +---------------------- + +Uninstall the RPM package:: + + $ sudo rpm -e fess + +.. note:: + + When the |Fess| package is uninstalled, the package's removal script automatically + stops and disables the ``fess`` service and removes the ``fess`` user and group. + The following steps are performed to confirm that these have been reliably removed, or + to manually delete data and configuration files. + +Step 2: Uninstall OpenSearch +---------------------------- + +:: + + $ sudo rpm -e opensearch + +Step 3: Confirm the Service Is Disabled +--------------------------------------- + +The service is usually disabled when the package is removed, but to confirm or disable it just in case, run the following. + +For systemd:: + + $ sudo systemctl disable fess.service + $ sudo systemctl disable opensearch.service + $ sudo systemctl daemon-reload + +For older SysV init (chkconfig) environments:: + + $ sudo /sbin/chkconfig --del fess + $ sudo /sbin/chkconfig --del opensearch + +Step 4: Delete the Data Directory +--------------------------------- + +.. warning:: + + Performing this operation completely deletes all index data. + +The data directory is not removed when the package is uninstalled, so delete it manually:: + + $ sudo rm -rf /var/lib/fess + $ sudo rm -rf /var/lib/opensearch + +Step 5: Delete the Configuration Files +-------------------------------------- + +Delete the configuration files and environment settings files:: + + $ sudo rm -rf /etc/fess + $ sudo rm -rf /etc/sysconfig/fess + $ sudo rm -rf /etc/opensearch + +.. note:: + + With RPM, configuration files in ``/etc/fess`` may remain with a name like ``.rpmsave``. + To delete them completely, remove them manually as shown above. + +Step 6: Delete the Log Files +---------------------------- + +:: + + $ sudo rm -rf /var/log/fess + $ sudo rm -rf /var/log/opensearch + +Step 7: Delete the Temporary Directory (Optional) +------------------------------------------------- + +:: + + $ sudo rm -rf /var/tmp/fess + +Step 8: Delete the User and Group (Optional) +-------------------------------------------- + +The ``fess`` user and group are usually removed when the package is deleted. +If they remain, or to remove the user and group for OpenSearch, run the following:: + + $ sudo userdel fess + $ sudo groupdel fess + $ sudo userdel opensearch + $ sudo groupdel opensearch + +Uninstalling the DEB Version +============================ + +Step 1: Uninstall Fess +---------------------- + +Uninstall the DEB package:: + + $ sudo dpkg -r fess + +To completely remove it including configuration files and environment settings files, use purge:: + + $ sudo dpkg -P fess + +.. note:: + + With ``dpkg -r`` (remove), configuration files (conffiles) such as ``/etc/default/fess`` remain. + Using ``dpkg -P`` (purge) also deletes these configuration files and the ``fess`` user and group. + +Step 2: Uninstall OpenSearch +---------------------------- + +:: + + $ sudo dpkg -r opensearch + +Or remove it including configuration files:: + + $ sudo dpkg -P opensearch + +Step 3: Confirm the Service Is Disabled +--------------------------------------- + +The service is usually disabled when the package is removed. To confirm or disable it just in case, run the following:: + + $ sudo systemctl disable fess.service + $ sudo systemctl disable opensearch.service + $ sudo systemctl daemon-reload + +Step 4: Delete the Data Directory +--------------------------------- + +.. warning:: + + Performing this operation completely deletes all index data. + +:: + + $ sudo rm -rf /var/lib/fess + $ sudo rm -rf /var/lib/opensearch + +Step 5: Delete the Configuration Files (if dpkg -P was not used) +---------------------------------------------------------------- + +:: + + $ sudo rm -rf /etc/fess + $ sudo rm -rf /etc/default/fess + $ sudo rm -rf /etc/opensearch + +Step 6: Delete the Log Files +---------------------------- + +:: + + $ sudo rm -rf /var/log/fess + $ sudo rm -rf /var/log/opensearch + +Step 7: Delete the User and Group (Optional) +-------------------------------------------- + +If you did not use ``dpkg -P``, the ``fess`` user and group remain. +To remove them, run the following:: + + $ sudo userdel fess + $ sudo groupdel fess + $ sudo userdel opensearch + $ sudo groupdel opensearch + +Uninstalling the Docker Version +=============================== + +Step 1: Remove Containers and Networks +-------------------------------------- + +Remove the containers and the network created by Docker Compose (``search_net``):: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +Step 2: Remove Volumes +---------------------- + +.. warning:: + + Performing this operation completely deletes all data. + +|Fess|'s data (such as indexes and dictionaries) is stored in OpenSearch volumes. +First, check the list of volumes:: + + $ docker volume ls + +Remove the OpenSearch-related volumes:: + + $ docker volume rm _search01_data + $ docker volume rm _search01_dictionary + +.. note:: + + Volume names are prefixed with the Docker Compose project name (usually the name of the + directory where the Compose files are located). Check the actual names with ``docker volume ls``. + +To remove the containers and volumes all at once, add the ``-v`` option to ``down``:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down -v + +Step 3: Remove Images (Optional) +-------------------------------- + +To remove the Docker images and free up disk space:: + + $ docker images | grep fess + $ docker rmi ghcr.io/codelibs/fess:15.10.0 + $ docker rmi ghcr.io/codelibs/fess-opensearch:3.9.0 + +Step 4: Remove Compose Files +---------------------------- + +:: + + $ rm compose.yaml compose-opensearch3.yaml + +Verifying the Uninstallation +============================ + +Verify that all components have been removed. + +Verify Processes +---------------- + +:: + + $ ps aux | grep fess + $ ps aux | grep opensearch + +If nothing is displayed, the processes are stopped. + +Verify Ports +------------ + +:: + + $ sudo ss -tuln | grep 8080 + $ sudo ss -tuln | grep 9200 + +Verify that the ports are not in use. + +Verify Files +------------ + +ZIP version:: + + $ ls /path/to/fess-15.10.0 # Verify that the directory does not exist + +RPM/DEB version:: + + $ ls /var/lib/fess # Verify that the directory does not exist + $ ls /etc/fess # Verify that the directory does not exist + +Docker version:: + + $ docker ps -a | grep -E 'fess01|search01' # Verify that the containers do not exist + $ docker volume ls | grep search01 # Verify that the volumes do not exist + +Verify Packages +--------------- + +RPM version:: + + $ rpm -qa | grep fess + $ rpm -qa | grep opensearch + +DEB version:: + + $ dpkg -l | grep fess + $ dpkg -l | grep opensearch + +If nothing is displayed, the packages have been removed. + +Partial Uninstallation +====================== + +Remove Only Fess, Keeping OpenSearch +------------------------------------ + +If OpenSearch is also used by other applications, you can remove only Fess. + +1. Stop Fess +2. Remove the Fess package or directory +3. Remove the Fess data directory (such as ``/var/lib/fess``) +4. Delete the |Fess| indexes created in OpenSearch + + The names of |Fess| indexes begin with ``fess`` (such as ``fess.*``, ``fess_config.*``, ``fess_user.*``, ``fess_log.*``, ``fess_crawler.*`` and ``fess_suggest*``). You can delete them all at once with the following command. + + :: + + $ curl -X DELETE 'http://localhost:9200/fess*' + + Before deleting, run ``curl 'http://localhost:9200/_cat/indices?v'`` and confirm that there are no indexes of other applications whose names begin with ``fess``. The ``configsync`` index used to synchronize dictionaries can also be deleted if no other application uses it. + +5. Do not remove OpenSearch + +Remove Only OpenSearch, Keeping Fess +------------------------------------ + +.. warning:: + + Removing OpenSearch will cause Fess to stop functioning. + Change the configuration to connect to a different OpenSearch cluster. + +1. Stop OpenSearch +2. Remove the OpenSearch package or directory +3. Remove the OpenSearch data directory (such as ``/var/lib/opensearch``) +4. Update the Fess configuration to specify a different OpenSearch cluster + +Troubleshooting +=============== + +Cannot Remove the Package +------------------------- + +**Symptoms:** + +An error occurs with ``rpm -e`` or ``dpkg -r``. + +**Solution:** + +1. Verify that the service is stopped:: + + $ sudo systemctl stop fess.service + +2. Check dependencies:: + + $ rpm -qa | grep fess + $ dpkg -l | grep fess + +3. Force removal (last resort):: + + $ sudo rpm -e --nodeps fess + $ sudo dpkg -r --force-all fess + +Cannot Delete the Directory +--------------------------- + +**Symptoms:** + +Cannot delete a directory with ``rm -rf``. + +**Solution:** + +1. Check permissions:: + + $ ls -ld /path/to/directory + +2. Delete with sudo:: + + $ sudo rm -rf /path/to/directory + +3. Verify that no process is using the files:: + + $ sudo lsof | grep /path/to/directory + +Preparing for Reinstallation +============================ + +When reinstalling after uninstallation, verify the following: + +1. All processes are stopped +2. All files and directories are deleted +3. Ports 8080 and 9200 are not in use +4. No previous configuration files remain + +For reinstallation procedures, refer to :doc:`install`. + +Next Steps +========== + +Once uninstallation is complete: + +- To install a new version, refer to :doc:`install` +- To migrate data, refer to :doc:`upgrade` +- To consider an alternative search solution, refer to the official Fess website diff --git a/en/15.10/install/upgrade.rst b/en/15.10/install/upgrade.rst new file mode 100644 index 000000000..039fef57a --- /dev/null +++ b/en/15.10/install/upgrade.rst @@ -0,0 +1,1628 @@ +================== +Upgrade Procedure +================== + +This page describes the procedures for upgrading |Fess| from a previous version to the latest release. + +.. warning:: + + **Important Notes Before Upgrade** + + - Always create a backup before upgrading + - It is strongly recommended to validate the upgrade in a test environment first + - Services will be stopped during the upgrade, so schedule appropriate maintenance time + - Configuration file formats may have changed depending on the version + +Supported Versions +================== + +This upgrade procedure supports upgrades between the following versions: + +- Fess 14.x → Fess 15.10 +- Fess 15.x → Fess 15.10 + +.. important:: + + |Fess| 14.x supports the OpenSearch 2.x series, while |Fess| 15.10 supports OpenSearch 3.9.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. + For details, check the release notes. + +Pre-Upgrade Preparation +======================= + +Verify Version Compatibility +----------------------------- + +Verify the compatibility between the upgrade target version and the current version. + +- `Release Notes `__ +- :doc:`prerequisites` - |Fess| 15.10 system requirements (Java and OpenSearch versions) + +Plan Downtime +------------- + +The upgrade process requires system shutdown. Plan downtime considering the following: + +- Backup time: 10 minutes to several hours (depending on data volume) +- Upgrade time: 10 to 30 minutes +- Verification time: 30 minutes to 1 hour +- Reserve time: 30 minutes + +**Recommended Maintenance Time**: Total 2 to 4 hours + +Step 1: Data Backup +=================== + +Back up all data before upgrading. + +Configuration Data Backup +-------------------------- + +1. **Backup from Admin Screen** + + Log in to the admin screen and click "System Info" → "Backup". + + The backup page lists the following configuration data as individual items. + 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`` - 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 up to 15.8; 15.10 adds the + ``tag_type`` index that holds user tags, for 26) + - ``fess_user.bulk`` - Users, roles, and groups + - ``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. However, if the source is 15.10 or later and you use user tags, also download ``fess_config.bulk``: the ``tag_type`` index that holds the user tags is not part of ``fess_basic_config.bulk`` (see :doc:`../admin/tagtype-guide`). + + .. note:: + + Log data such as search logs and click logs (``search_log.ndjson``, ``click_log.ndjson``, + ``favorite_log.ndjson``, ``user_info.ndjson``; 15.10 also offers ``chat_log.ndjson``) can also + be downloaded from the same page. + 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** + + ZIP version:: + + $ 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 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 ZIP version, the + equivalent settings are in ``bin/fess.in.sh``. + +3. **Customized Configuration Files** + + If you have customized configuration files, back up those as well:: + + $ cp /path/to/fess/app/WEB-INF/classes/log4j2.xml /backup/ + $ cp /path/to/fess/lib/classes/tomcat_config.properties /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 +----------------- + +Back up OpenSearch index data. + +Method 1: Use Snapshot Feature (Recommended) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Back up the index using OpenSearch snapshot feature. + +.. note:: + + To register a filesystem (``fs``) repository, you must first specify the backup destination + directory in ``path.repo`` in OpenSearch's ``opensearch.yml`` and restart OpenSearch. + +1. Configure repository:: + + $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup" -H 'Content-Type: application/json' -d' + { + "type": "fs", + "settings": { + "location": "/backup/opensearch/snapshots" + } + }' + +2. Create snapshot:: + + $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup/snapshot_1?wait_for_completion=true" + +3. Verify snapshot:: + + $ curl -X GET "http://localhost:9200/_snapshot/fess_backup/snapshot_1" + +Method 2: Backup Entire Directory +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Stop OpenSearch and back up the data directory. + +:: + + $ sudo systemctl stop opensearch + $ sudo tar czf /backup/opensearch-data-$(date +%Y%m%d).tar.gz /var/lib/opensearch/data + $ sudo systemctl start opensearch + +Docker Version Backup +--------------------- + +OpenSearch data is stored in Docker volumes. ``compose-opensearch3.yaml`` defines two volumes: +``search01_data`` for index data and ``search01_dictionary`` for dictionary files. + +.. note:: + + The actual volume names are prefixed with the Compose project name (by default, the name of + the directory containing the Compose files). Check the exact names with:: + + $ docker volume ls + +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 + $ 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. + +The ZIP version does not include a stop script. If you started ``bin/fess`` with the +``-p`` option, stop it using the PID file:: + + $ 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 + $ sudo systemctl stop opensearch.service + +Docker version:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +.. warning:: + + Make sure |Fess| has stopped before you start Step 3, and do not replace the package or the files + of a |Fess| that is still running. After the DEB package of a running 15.8 |Fess| was replaced + by the 15.10 one, the search screen answered ``404`` until |Fess| was restarted. For the package + versions, check with ``systemctl status fess.service``. + +Step 3: Install New Version +============================ + +The procedure varies depending on the installation method. + +ZIP Version +------------------ + +1. Download and extract the new version:: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.zip + $ unzip fess-15.10.0.zip + + .. note:: + + |Fess| archives are distributed only in ZIP format (``fess-15.10.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.10.0/app/WEB-INF/conf/ + $ cp /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.10.0/app/WEB-INF/classes/ + $ cp /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.10.0/bin/ + + .. warning:: + + Copied whole, ``fess_config.properties`` and ``fess.in.sh`` keep their old values, including + values whose default changed in 15.10: jobs created afterwards default to Groovy, for example. + Before running the last two commands, compare each file with the one in ``fess-15.10.0`` and + carry over only the values you changed yourself. See :ref:`upgrade-159-carried-over-config` + for what to check. + +3. If you have customizations, also copy the following:: + + # Tomcat settings (the SAML setting tomcat.sameSiteCookies=none is kept here) + $ cp /path/to/old-fess/lib/classes/tomcat_config.properties /path/to/fess-15.10.0/lib/classes/ + # Installed plugins + $ cp -r /path/to/old-fess/app/WEB-INF/plugin/. /path/to/fess-15.10.0/app/WEB-INF/plugin/ + # Static themes you uploaded yourself (one directory per theme; never bootstrap) + $ cp -r /path/to/old-fess/app/themes/ /path/to/fess-15.10.0/app/themes/ + + .. warning:: + + Without ``tomcat_config.properties`` from the old installation, ``tomcat.sameSiteCookies`` + silently returns to the default ``lax``, and SAML login stops working (see + :ref:`upgrade-159-saml`). The shipped file is the same in 15.8.0 and 15.10, so it can be + copied as it is. + + .. warning:: + + Do not copy ``log4j2.xml`` over the 15.10 file. The 15.10 file keeps the ``RequestLoggingFilter`` + logger at ``warn``, and a file copied from 15.8 removes that setting: with the log level at + DEBUG, the request headers (including ``Authorization``) and the request parameters (including + the password typed on the login form) are then written to the log. Compare the two files with + ``diff`` and reapply only the changes you made yourself to the 15.10 file. + + .. warning:: + + Do not copy the whole ``app/themes/`` directory. It also holds ``bootstrap``, the theme + bundled with |Fess|, and copying it over the 15.10 one replaces the 15.10 search screen with + the 15.8 version of the theme. Copy only the directories of themes you created yourself. + For a theme published by the |Fess| project, install the build for 15.10 instead, with + ``bin/fess-setup install theme `` (see :doc:`fess-setup`). + + .. warning:: + + Do not copy JSPs (``app/WEB-INF/view/``) edited via "Design" in the admin UI. The search + screen of 15.10 is a static theme and no longer uses those JSPs; see + :ref:`upgrade-159-static-theme` for where such changes go now. + + .. note:: + + Plugins copied from ``app/WEB-INF/plugin/`` were built for the old version. After copying + them, run ``bin/fess-setup upgrade plugins`` in ``fess-15.10.0`` to replace each one with the + version built for 15.10; see :ref:`upgrade-plugin-versions`. + +4. Verify configuration differences and adjust as necessary + +RPM/DEB Version +--------------- + +Install the new version package:: + + # RPM + $ sudo rpm -Uvh fess-15.10.0.rpm + + # DEB + $ sudo dpkg -i fess-15.10.0.deb + +.. note:: + + 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. A ``/etc/fess/fess_config.properties`` that you modified + keeps its old values in 15.10, just as a file copied in the ZIP procedure does; see + :ref:`upgrade-159-carried-over-config`. + +.. warning:: + + For the DEB version, the files under ``/etc/fess`` (such as ``fess_config.properties`` and + ``tomcat_config.properties``) are registered as conffiles, like ``/etc/default/fess``, + ``/etc/init.d/fess``, and ``/usr/lib/systemd/system/fess.service``. On the first upgrade from + 15.8, ``dpkg`` treats them as follows: + + - A file you never edited is replaced with the 15.10 file without a question. + - For a file you edited, ``dpkg`` asks. If you keep your file (the default answer, or + ``--force-confold``), the 15.10 file is placed beside it as ``.dpkg-dist``. If you + install the new file (``Y`` or ``--force-confnew``), your file is saved as + ``.dpkg-old``. + - ``dpkg -i`` and ``apt-get install -y`` stop at the first question when nobody can answer it. + For an unattended upgrade, pass ``--force-confold`` (``--force-confdef`` also avoids the + questions), for example ``sudo dpkg --force-confold -i fess-15.10.0.deb`` or + ``sudo apt-get install -y -o Dpkg::Options::=--force-confold ./fess-15.10.0.deb``. + + Back up ``/etc/fess`` first (Step 1) in any case. A file you keep still has its 15.8 values, so + compare it with the ``.dpkg-dist`` file instead of using it as it is (see + :ref:`upgrade-159-carried-over-config`). Note that ``/etc/fess/system.properties`` is a + runtime-generated file not included in the package, so it is not overwritten. + +Docker Version +-------------- + +1. Obtain Compose files for the new version:: + + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose.yaml + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose-opensearch3.yaml + +2. Pull new images:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull + +.. _upgrade-opensearch: + +Step 4: Upgrade OpenSearch +========================== + +|Fess| 15.10 supports OpenSearch 3.9.0. If the OpenSearch you connect to is older than that, +upgrade it using the following procedure. + +.. note:: + + This procedure applies when you are managing OpenSearch manually on a ZIP or RPM/DEB + 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.10 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. + + A snapshot taken on OpenSearch 3.9.0 cannot be restored to OpenSearch 3.8.0 or earlier. Keep the + snapshot you took before the upgrade in case you need to roll back. + +1. Install the new version of OpenSearch + +2. Reinstall plugins:: + + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + + .. note:: + + The version of these plugins must match the version of OpenSearch you use. |Fess| 15.10 + supports OpenSearch 3.9.0. Installation fails if the versions do not match. + + The four |Fess| plugins are published on maven.codelibs.org, so they are installed by URL. The + ``groupId:artifactId:version`` form of ``opensearch-plugin install`` looks only at Maven + Central. + +3. Move the dictionary directory under the OpenSearch configuration directory + + OpenSearch 3.8.0 and later refuse to create an index when dictionary files are outside the OpenSearch configuration directory. + If, following the earlier instructions, ``configsync.config_path`` points outside the configuration directory, such as ``/var/lib/opensearch/data/config/`` (``/path/to/opensearch/data/config/`` for the ZIP version), + |Fess| cannot create its indices and does not start. + For the RPM/DEB version, copy the dictionary files to ``/etc/opensearch/dictionary/`` as follows:: + + $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary + $ sudo cp -a /var/lib/opensearch/data/config/. /etc/opensearch/dictionary/ + $ sudo chown -R opensearch:opensearch /etc/opensearch/dictionary + + Then change both ``configsync.config_path`` in ``/etc/opensearch/opensearch.yml`` and ``FESS_DICTIONARY_PATH`` of |Fess| (``/etc/sysconfig/fess`` for the RPM version, ``/etc/default/fess`` for the DEB version) to ``/etc/opensearch/dictionary/``. + For the ZIP version, use ``config/dictionary/`` of OpenSearch. For details, see :doc:`install-linux`. + +4. Start OpenSearch:: + + $ sudo systemctl start opensearch.service + +Step 5: Start New Version +========================== + +ZIP version:: + + $ cd /path/to/fess-15.10.0 + $ ./bin/fess -d -p /path/to/fess-15.10.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.10.0/fess.pid)``. + +RPM/DEB version:: + + $ sudo systemctl start opensearch.service + $ sudo systemctl start fess.service + +Docker version:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +Step 6: Verify Operation +========================= + +1. **Check Logs** + + Verify there are no errors. + + 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. + +3. **Log in to Admin Screen** + + Access http://localhost:8080/admin and log in with the administrator account. + +4. **Check the Version** + + In the admin UI, click "System Info" → "Config Info" and confirm that ``fess.version`` + shown under "System Properties" reflects the new version. + +5. **Verify Search Operation** + + Execute a search on the search screen and verify results are returned normally. + +Step 7: Recreate Index (Recommended) +===================================== + +For major version upgrades, it is recommended to recreate the index. + +.. note:: + + The steps below re-run the crawl; they do not update the index mapping (field definitions). + If you need a re-index that updates the mapping — for example, to newly enable chunk-vector + search (semantic search) — separately run "Re-indexing" under "System Info" → "Maintenance" in + the admin UI. See :ref:`semantic-search-migration` (in :doc:`../config/search-semantic`) for + details. + + If you keep a document index created by 15.8 or earlier, also see + :ref:`upgrade-reindex-new-fields`. + +.. warning:: + + OpenSearch 3.9.0 refuses dictionary entries that 15.8 accepted, such as the same ``mapping`` + entry saved twice or a ``kuromoji`` token that contains a space. With such an entry, "Re-indexing" + does not create the new document index: ``fess.log`` only says ``Failed to create index``, and + the old index keeps serving searches. Download the dictionary under "System" → "Dictionary", + remove the duplicate or invalid lines, upload it again, and run "Re-indexing" again. See + :ref:`upgrade-159-api-requests` for the entries that 15.10 no longer saves. + +1. Verify existing crawl schedules +2. Execute "Default Crawler" from "System" → "Scheduler" +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. + +Upgrading from 15.8 to 15.10 +=========================== + +If you are upgrading from 15.8, the following changes are not backward compatible. If you are +upgrading from 15.7 or earlier, they apply to you as well: read every section from "Removal of the +embedded OpenSearch" through "Applying New Fields and Kana Normalization to an Existing Document +Index" (the embedded OpenSearch, the script engine, the S3 and SSO plugins, the Index Exporter job, +and so on), and then "15.10-Specific Migration Tasks" at the end of this page. + +Removal of the embedded OpenSearch +---------------------------------- + +Up to 15.8, starting ``bin/fess`` without setting ``SEARCH_ENGINE_HTTP_URL`` made |Fess| run an +OpenSearch node inside its own JVM. That configuration is gone in 15.10: the search engine is +always a separate server. + +``bin/fess.in.sh`` now sets ``SEARCH_ENGINE_HTTP_URL=http://localhost:9200`` by default. |Fess| +refuses to start when no OpenSearch is reachable. ``bin/fess-setup install opensearch`` installs +one (Linux and Windows only; OpenSearch publishes no macOS build, so use Homebrew or Docker +there). + +|Fess| also needs ``FESS_DICTIONARY_PATH`` to match ``configsync.config_path`` in the +``opensearch.yml`` of that OpenSearch; without it, |Fess| cannot create its indices. The 15.10 +``bin/fess.in.sh`` (``bin\fess.in.bat`` on Windows) sets it on its own when ``opensearch/`` in the +|Fess| directory holds exactly one OpenSearch installed by ``bin/fess-setup install opensearch``. +For any other OpenSearch, set it as described in :doc:`install-linux` or :doc:`install-windows`. + +Removed along with it: + +- the ``es/`` directory (``es/modules``, ``es/plugins`` and ``es/data``) +- ``-Dfess.es.dir`` and ``SEARCH_ENGINE_HOME`` +- ``bin/module.xml`` and ``bin/plugin.xml`` +- the fallbacks to the legacy ``elasticsearch.*`` configuration keys + +An engine older than OpenSearch 3 also stops startup now, where 15.8 logged an error and carried +on. Those versions do not implement the ``_shard_doc`` sort that every whole-result-set operation +relies on, and over HTTP such a request hangs rather than failing. + +.. warning:: + + Index data from an embedded installation cannot be carried over. Build a new external + OpenSearch server, move the settings with the admin Backup page, and re-crawl. The backup + covers crawl settings, users and logs; it does **not** contain the crawled documents. + +.. note:: + + Two things to know when you restore a 15.8 backup onto the new 15.10 server: + + - Jobs are restored only when they are newer than the ones on the server. The bundled jobs that + you never edited on 15.8 therefore keep their 15.10 JavaScript version. A job that you edited or + created on 15.8 comes back with the script engine it was saved with, which is ``groovy`` for a + bundled job, and without the ``fess-script-groovy`` plugin it fails with + ``groovy is not found``. Install the plugin, or switch such jobs to JavaScript; both are + described in :ref:`upgrade-159-script-engine`. + - Passwords and secrets stored in the web authentication, crawling configuration and data store + settings are encrypted with ``app.cipher.key``. Set the value of the old installation in the + ``fess_config.properties`` of the new server, as described in + :ref:`upgrade-159-carried-over-config`; otherwise they cannot be decrypted. + +Playwright Crawler Moved to a Plugin +------------------------------------ + +The Playwright crawler, and the Node.js executables it runs, are no longer part of the +distribution. In ``fess-15.8.0.zip`` (457.1 MiB), the Playwright driver bundle that carried the +Node.js executables took up 204.3 MiB. + +If a crawl configuration names the Playwright client, for example with +``client.crawlerClients=playwright:http://.*`` in its configuration parameters, install both the +plugin and Node.js. The plugin is also available from the System > Plugin page in the +administration screen. ``bin/fess.in.sh`` discovers Node.js and sets ``PLAYWRIGHT_NODEJS_PATH``. + +:: + + $ bin/fess-setup install plugin fess-crawler-playwright + $ bin/fess-setup install nodejs + +Without the plugin, such a configuration is still crawled, but with the plain HTTP client, so +text that only JavaScript produces is not indexed. The crawl job still ends successfully and no +failure URL is recorded. For each crawl, ``fess-crawler.log`` records one warning per crawling +configuration that names the plugin and the two commands above. + +The ``fess-thumbnail-playwright`` plugin, which generates thumbnails of HTML pages with +Playwright, runs on Node.js as well. If you use it, install Node.js with +``bin/fess-setup install nodejs``; the same installation serves both plugins. + +Nothing is needed if you use neither the Playwright crawler nor the ``fess-thumbnail-playwright`` +plugin. + +Google Cloud Storage Moved to a Plugin +-------------------------------------- + +The Google Cloud Storage SDK is no longer part of the distribution, so ``gcs://`` crawling +and the ``gcs`` storage type now come from the ``fess-storage-gcs`` plugin. Install it from the +System > Plugin page in the administration screen, or with the command below. + +:: + + $ bin/fess-setup install plugin fess-storage-gcs + +``gcs`` also left the shipped ``crawler.file.protocols``, which is now +``file,smb,smb1,ftp``; the plugin adds it back when it is installed. Until then a file crawl +configuration whose path begins with ``gcs:`` is logged as a warning and crawls nothing. An +installation that upgrades keeps its own ``crawler.file.protocols``, so the path is still +accepted but no crawler client handles it; on a new installation ``gcs:`` is not a configured +protocol, so the administration screen refuses to save the path and a path saved earlier is +read as a local file path. The storage page logs a warning as well and shows the failure as an +error naming the plugin to install, where before it rendered an empty file list. + +Nothing is needed if you do not use Google Cloud Storage. Amazon S3 and S3-compatible +storage such as MinIO moved to a plugin in the same way; see the next section. + +Amazon S3 Moved to a Plugin +--------------------------- + +The AWS SDK is no longer part of the distribution, so ``s3://`` crawling and the ``s3`` and +``s3_compat`` storage types now come from the ``fess-storage-s3`` plugin. Install it from the +System > Plugin page in the administration screen, or with the command below. + +:: + + $ bin/fess-setup install plugin fess-storage-s3 + +``s3`` also left the shipped ``crawler.file.protocols``, which is now ``file,smb,smb1,ftp``; +the plugin adds it back when it is installed. ``storage.type`` still defaults to ``auto``, +which resolves to S3 when no endpoint is set, so the storage page in the administration screen +does not work until the plugin is installed even if you never named ``s3`` yourself. Your +``storage.*`` values are kept, because they live in ``WEB-INF/conf/system.properties``, and an +existing ``crawler.file.protocols`` is not replaced by the upgrade either. + +Nothing is needed if you do not use Amazon S3 or S3-compatible storage such as MinIO. + +SSO Authentication Moved to Plugins +----------------------------------- + +None of the four SSO authenticators is part of the distribution any more. Each ``sso.type`` +value now comes from its own plugin, which carries the identity library it needs: ``saml`` from +``fess-sso-saml``, ``spnego`` from ``fess-sso-spnego``, ``entraid`` (and the legacy ``aad``) +from ``fess-sso-entraid``, and ``oic`` from ``fess-sso-oidc``. Note the last pair: the plugin is +named ``fess-sso-oidc`` while the ``sso.type`` value stays ``oic``, the one place where the two +differ. Install the one you use from the System > Plugin page in the administration screen, or +with the command below. + +:: + + $ bin/fess-setup install plugin fess-sso-saml + +Your settings are kept, because ``sso.type`` and the ``saml.*``, ``spnego.*``, ``entraid.*``, +``aad.*`` and ``oic.*`` keys live in ``WEB-INF/conf/system.properties``. "System" → "General" in +the admin UI also still offers all four types and still shows their settings, because a plugin +cannot supply a JSP, so nothing on that screen reports a missing plugin. + +Until the plugin is installed, a request to ``/sso/`` is redirected back to the login page, +which reports that the SSO login failed, and no one can log in through SSO. 15.10 records a +warning in ``fess.log`` naming the component it looked for and the plugin that provides it, +where up to 15.8 nothing was logged at any level. + +The ``oic`` plugin is stricter than the 15.8 authenticator. ``oic.token.server.url`` must be +HTTPS (``http`` only for ``localhost``, ``127.x.x.x`` and ``::1``), the ``aud`` and ``exp`` claims +of the ID Token are checked, and ``iss`` is checked when the new ``oic.issuer`` key is set. See +:doc:`../config/sso-oidc`. + +In 15.8, ``oic.token.server.url`` could be an ``http`` URL for any host. In 15.10, ``http`` to a Docker Compose service name (such as ``http://keycloak:8080/...``) or an internal host name is refused, even if it points to the same machine. Login then fails and ``fess.log`` records a warning that starts with ``Failed to process the OpenID Connect callback: oic.token.server.url must be https``. Change the token endpoint to an HTTPS URL before you upgrade. + +Also set ``oic.issuer`` to the ``issuer`` value of the OP's Discovery document. Without it, ``iss`` is not checked and a warning is logged at the first login after startup. Setting ``oic.issuer`` does not relax the HTTPS rule. + +Nothing is needed if you do not use SSO, that is if ``sso.type`` is ``none`` or unset. + +.. _upgrade-159-script-engine: + +The Built-in Script Engine Changed from Groovy to JavaScript +------------------------------------------------------------ + +Up to 15.8 the built-in script engine was Groovy and ``job.default.script`` defaulted to +``groovy``. In 15.10 the built-in engine is JavaScript and the default is ``javascript``. Groovy is +no longer built in: it is provided by the ``fess-script-groovy`` plugin, which has to be installed +before a ``scriptType`` of ``groovy`` can be resolved. + +An upgrade does not change the engine stored with a setting, and a setting saved before 15.10 that +records no engine counts as ``groovy``. Without the plugin, the following stop working: + +- Scheduled jobs saved as ``groovy``. **This includes the jobs that 15.8 created itself:** + Default Crawler, Suggest Indexer, Config Reloader, Log Aggregator, Doc Purger and the other + bundled jobs are all saved as ``groovy``, and at startup 15.10 only adds the bundled jobs that do + not exist yet, so it leaves them as they are. Each of them fails whenever its schedule fires, so + Default Crawler no longer crawls. Most bundled jobs have "Logging" turned off, so their failures + do not appear in the job log, only as ``Failed to execute job`` warnings in ``fess.log``. +- Web and file crawling configurations with field scripts (``field.script.``) in + "Config Parameters". Every document of such a configuration fails with a + ``ScriptEngineException``, recorded as a failure URL, while the crawl job itself still ends + successfully. +- Data store configurations with a "Script". Values other than a plain parameter name cannot be + evaluated; see :doc:`../config/datastore/ds-overview`. +- Document boost rules. Such a rule boosts nothing. +- Path mappings whose "Replacement" begins with ``groovy:``. Such a mapping is not applied, and + URLs are left unchanged. + +After the first start, look in ``fess.log`` for a warning that begins with +``Settings use the script engine groovy, which is not registered``. |Fess| checks the settings +above once at startup and lists how many of each kind use an engine that no plugin provides. It +also names ``job.default.script`` when a ``fess_config.properties`` carried over from 15.8 still +sets ``groovy``, in which case jobs created after the upgrade use Groovy too (see +:ref:`upgrade-159-carried-over-config`). Resolve it in one of two ways: + +- Install the plugin and restart |Fess|. The stored Groovy scripts then run unchanged, and the + warning is no longer logged. The plugin can also be installed from "System" → "Plugins" in the + admin UI. + + :: + + $ bin/fess-setup install plugin fess-script-groovy + +- Move each setting to JavaScript. First rewrite any syntax that only Groovy accepts, then select + JavaScript: + + - Scheduled jobs: under "System" → "Scheduler", set "Execution Method" to ``javascript``. The + scripts of the bundled jobs are valid JavaScript as they are, with two exceptions: Thumbnail + Purger uses the Groovy ``long`` literal ``1000L``, which JavaScript rejects (write ``1000``), + and Index Exporter needs the change described in :ref:`upgrade-159-index-exporter`. A + JavaScript array literal is converted to a Java ``String[]`` automatically, so the + ``as String[]`` casts of the Groovy form are dropped: + + :: + + return container.getComponent("crawlJob").logLevel("info").webConfigIds(["1", "2"]).fileConfigIds(["1"]).dataConfigIds([]).execute(executor); + + - Web and file crawling configurations: add ``config.script.type=javascript`` to + "Config Parameters". + - Data store configurations: add ``script_type=javascript`` to "Parameters". + - Document boost rules: set "Script Type" to ``javascript``. + - Path mappings: begin the "Replacement" with ``javascript:`` instead of ``groovy:``. + - ``job.default.script``: set it to ``javascript`` in a ``fess_config.properties`` carried over + from 15.8. + +``crawler.default.script`` Was Removed +-------------------------------------- + +``crawler.default.script`` no longer exists in ``fess_config.properties``. Remove it from your +configuration; a value left under that name has no effect. + +The ``storage`` Crawl Protocol Was Removed +------------------------------------------ + +``storage`` is no longer accepted in ``crawler.file.protocols``; the shipped value is +``file,smb,smb1,ftp``. Use ``s3`` instead, and change any file crawling configuration whose +path begins with ``storage:`` to an ``s3:`` path. ``s3`` needs the ``fess-storage-s3`` plugin. + +.. _upgrade-159-index-exporter: + +The Index Exporter Job Names a Removed Package +---------------------------------------------- + +15.10 no longer ships the ``org.opensearch`` classes; the query builders that job scripts use now +live under ``org.codelibs.fesen.opensearch``. The script that 15.8 stored for the Index Exporter +job names ``org.opensearch.index.query.QueryBuilders``, and the upgrade does not replace it, so +the job fails even with ``fess-script-groovy`` installed. The job ships disabled and without a +schedule, so this only matters if you run it. Open it under "System" → "Scheduler" and change the +package in its script to the one 15.10 uses: + +:: + + return new org.codelibs.fess.job.IndexExportJob().query(org.codelibs.fesen.opensearch.index.query.QueryBuilders.matchAllQuery()).execute() + +Change any script of your own that names ``org.opensearch.index.query`` in the same way. See +:doc:`../config/admin-index-export` for more query examples. + +.. _upgrade-159-carried-over-config: + +Configuration Files Carried Over from 15.8 +------------------------------------------ + +The ZIP procedure in Step 3 copies ``fess_config.properties`` and ``bin/fess.in.sh`` from the old +installation, and an RPM upgrade keeps a ``/etc/fess/fess_config.properties`` that you modified +(the 15.10 file is placed next to it as ``fess_config.properties.rpmnew``). A DEB upgrade does the +same when you keep your version at the question (the 15.10 file is placed next to it as +``fess_config.properties.dpkg-dist``). Either way, 15.10 then runs with the 15.8 values, including +those whose shipped value changed in 15.10. Review at least the following keys. + +.. list-table:: + :header-rows: 1 + + * - Key + - 15.8.0 + - 15.10 + - Effect of keeping the 15.8 value + * - ``job.default.script`` + - ``groovy`` + - ``javascript`` + - Jobs created under "System" → "Scheduler" default to ``groovy`` and fail without the + ``fess-script-groovy`` plugin. + * - ``job.template.script`` + - Groovy form with ``as String[]`` + - JavaScript form + - A job created from a crawling configuration gets a Groovy script. + * - ``crawler.file.protocols`` + - ``file,smb,smb1,ftp,storage,s3,gcs`` + - ``file,smb,smb1,ftp`` + - A path beginning with ``s3:`` or ``gcs:`` is still accepted without its plugin and is + skipped with a warning when crawled. ``storage`` is no longer supported. + * - ``search_engine.http.url`` + - ``http://localhost:9201`` + - ``http://localhost:9200`` + - Used when ``SEARCH_ENGINE_HTTP_URL`` is not set, as in a ``bin/fess.in.sh`` copied from + 15.8 in which you did not set it. |Fess| then looks for OpenSearch on port 9201, the port + of the embedded OpenSearch that 15.10 removed. + * - ``jvm.crawler.options``, ``jvm.thumbnail.options`` + - ``-Djcifs.smb.client.*``, ``-Djcifs.smb1.smb.client.*`` + - ``-Djcifs.client.*`` + - The SMB timeouts stay at the jcifs defaults; see :ref:`upgrade-159-jcifs`. + * - ``response.headers`` + - Includes the row ``text/html=Content-Security-Policy: reflected-xss block`` + - Row removed + - The login page, the admin console and the other pages |Fess| renders itself are sent with a + ``Content-Security-Policy: reflected-xss block`` header that no browser recognizes, and the + browser console logs ``Unrecognized Content-Security-Policy directive 'reflected-xss'``. The + header restricts nothing. Remove the row, as described below. + * - ``app.encrypt.property.pattern`` + - ``.*password|.*key|.*token|.*secret`` + - ``.*password|.*passphrase|.*key|.*token|.*secret`` + - A parameter whose name ends with ``passphrase`` (for example ``ssh.passphrase`` of a data + store configuration) is saved in plain text. A value saved earlier stays in plain text until + the setting is saved again with the 15.10 pattern. + * - ``index.backup.log.targets`` + - ``click_log.ndjson,favorite_log.ndjson,search_log.ndjson,user_info.ndjson`` + - ``chat_log.ndjson,click_log.ndjson,favorite_log.ndjson,search_log.ndjson,user_info.ndjson`` + - The "System Info" → "Backup" page does not offer ``chat_log.ndjson``. + * - ``index.export.exclude.fields`` + - ``cache`` + - ``cache,tag`` + - The ``tag`` field, which holds user tags, is no longer left out of the files that the Index + Export job writes. + * - ``crawler.default.script``, ``theme.allowed.archive.extensions``, + ``theme.assets.cache.max.age``, ``theme.assets.precompressed``, + ``rag.chat.message.max.length``, ``supported.uploaded.js.extentions``, + ``supported.uploaded.css.extentions``, ``supported.uploaded.media.extentions``, + ``supported.uploaded.files``, ``online.help.name.design`` + - Present + - Removed + - No effect; remove them. + +The shipped ``response.headers`` of 15.0 through 15.8 contains the row +``text/html=Content-Security-Policy: reflected-xss block``. ``reflected-xss`` was a directive of an +early draft of Content-Security-Policy that browsers no longer recognize, so the header restricts +nothing and only adds the console error. 15.10 no longer ships the row (the ``X-XSS-Protection`` and +``X-Frame-Options`` rows are unchanged), but a ``response.headers`` carried over from 15.8 keeps it. +Remove only this row from ``response.headers`` in ``fess_config.properties``. The ``\n\`` at the end +of each row continues the value on the next line, so deleting the whole line leaves the others +intact:: + + text/html=Content-Security-Policy: reflected-xss block\n\ + +If you set ``response.headers`` with ``-Dfess.config.response.headers`` instead, remove the same +entry from that value. + +A ``bin/fess.in.sh`` copied from 15.8 also lacks two things that the 15.10 file has. It leaves +``SEARCH_ENGINE_HTTP_URL`` unset unless you set it yourself, where 15.10 sets +``http://localhost:9200``, and it does not look for the Node.js installed by +``bin/fess-setup install nodejs``, so the Playwright plugins cannot find Node.js unless you set +``PLAYWRIGHT_NODEJS_PATH``. + +Rather than copying either file whole, start from the file shipped with 15.10 and reapply the values +you changed. ``diff`` shows them:: + + $ diff /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.10.0/app/WEB-INF/classes/fess_config.properties + $ diff /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.10.0/bin/fess.in.sh + +For an RPM upgrade, compare ``/etc/fess/fess_config.properties`` with +``/etc/fess/fess_config.properties.rpmnew`` in the same way, and for a DEB upgrade with +``/etc/fess/fess_config.properties.dpkg-dist``. A ``fess_config.properties`` that you never edited +is replaced by the 15.10 file on a DEB upgrade (see Step 3), so it starts from the 15.10 values. + +``app.cipher.key`` is the one value you must carry over even though 15.10 did not change it. It is +the key that encrypts the passwords and secrets stored in the parameters of web authentication, +crawling configurations and data store configurations. If the new installation runs with a +different key than the one that saved them, because you took the shipped ``fess_config.properties`` +or restored a backup onto a new server, they cannot be decrypted: ``fess-crawler.log`` records a +``CipherFailureException``, and a crawl that includes such a configuration can index nothing. + +.. note:: + + |Fess| 15.10 also stores the ``password`` of web and file authentication encrypted with ``app.cipher.key``, so + ``fess_basic_config.bulk`` and ``fess_config.bulk`` in a backup contain the encrypted values. When you restore onto + another installation, carry the same ``app.cipher.key`` over; with a different key, crawls that use these + credentials fail with an error. A backup made before 15.10 holds them in plain text and keeps working (see + :doc:`../admin/backup-guide`). + +.. _upgrade-159-jcifs: + +SMB Timeouts Use the jcifs 3 Property Names +------------------------------------------- + +jcifs, the library |Fess| uses to crawl SMB file servers, renamed its properties in version 3: +``jcifs.smb.client.*`` became ``jcifs.client.*``, and the separate ``jcifs.smb1.smb.client.*`` +names for SMB1 were folded into the same properties. Up to 15.8, ``jvm.crawler.options`` and +``jvm.thumbnail.options`` still passed the old names, which jcifs ignores, so SMB crawls ran with +the jcifs defaults. 15.10 passes the new names: + +:: + + -Djcifs.client.responseTimeout=30000 + -Djcifs.client.soTimeout=35000 + -Djcifs.client.connTimeout=60000 + -Djcifs.client.sessionTimeout=60000 + +The connect and session timeouts therefore take effect for the first time and grow from the +jcifs default of 35 seconds to 60 seconds: a crawl now waits up to 60 seconds for an SMB server +that does not respond. The response and socket timeouts equal the jcifs defaults, so they do not +change. + +If you changed these timeouts, rename them in both options. Under the old names they had no +effect in 15.8 either. A ``fess_config.properties`` carried over from 15.8 keeps the old names, +and with them the jcifs defaults. + +Four Properties Without Effect Were Removed +------------------------------------------- + +The following keys no longer exist in ``fess_config.properties``. |Fess| never read them from that +file, so a value left under these names has no effect, as before. + +- ``theme.allowed.archive.extensions`` +- ``theme.assets.cache.max.age`` +- ``theme.assets.precompressed`` +- ``rag.chat.message.max.length`` + +The limit that ``rag.chat.message.max.length`` sets still works, but it is read as a system +property: set it in ``app/WEB-INF/conf/system.properties`` or with +``-Dfess.system.rag.chat.message.max.length``, as described in :doc:`../config/rag-chat`. + +.. _upgrade-159-static-theme: + +The Search Screen Is Now a Static Theme +--------------------------------------- + +The search screen is served by the static theme ``bootstrap``, which is bundled with |Fess|, unless +another theme is selected. This applies to ``/``, ``/search``, ``/advance``, ``/help``, +``/profile``, ``/cache``, ``/chat`` and the error pages. Up to 15.8, these pages were JSPs unless a +default theme was set. + +The switch happens on upgrade as well. A 15.8 installation that never set a default theme has no +``theme.default`` in ``system.properties``, so after the upgrade it shows the static theme; nothing is +written to the configuration and nothing is logged. There is no setting that brings back the JSP +search screen. If you had set a default theme in 15.8, that setting is kept; install the 15.10 build +of the theme (``bin/fess-setup install theme ``), because a default that names a theme that is +not installed falls back to ``bootstrap`` with a warning in ``fess.log``. + +If you changed the JSPs, CSS or images of the search screen, through "Page Design" in the admin UI +or in a JAR theme plugin, those changes no longer show. Make them in a static theme: copy the bundled +theme and change the copy, as described in :ref:`theme-customize-bundled`, or install a published +theme from "System" > "Theme" in the admin UI or with ``bin/fess-setup install theme ``. A +per-virtual-host look is now a static theme named after the virtual host; see +:doc:`../config/security-virtual-host`. + +Two more things are gone: + +- The per-virtual-host login screen. Up to 15.8, saving "System" > "General" copied JSPs, + including the login screen, into ``WEB-INF/view//``, where each virtual host + could edit its own copy. 15.10 no longer makes these copies. The login screen (``/login/``) is + still a JSP, but every virtual host gets the same one from ``WEB-INF/view/admin/login/``. JSPs + copied earlier are not used. +- JAR theme plugins (``fess-theme-*``). Installing one only places it as a generic JAR of type + ``jar``; no screen changes. Delete a leftover JAR on the "System" > "Plugin" page or with + ``bin/fess-setup remove plugin `` (see :doc:`../dev/theme-development`). + +If the JSP search results showed a field of your own in 15.8, add that field to +``query.additional.api.response.fields`` as well as ``query.additional.response.fields``. The static +theme gets its results from ``/api/v2/search``. ``query.additional.response.fields`` only adds a field +to what is fetched from the search engine; the API returns only the fields listed in +``query.additional.api.response.fields`` (see :doc:`../config/search-advanced`). Change the theme to +show the field as well. + +What Clients See +~~~~~~~~~~~~~~~~ + +Errors are now rendered in place, at the URL that was requested and with the real HTTP status. A +browser (a request whose ``Accept`` header includes ``text/html``) gets the theme's error page; any +other client gets a one-line ``text/plain`` body (for example ``Not Found.`` for ``404``). Up to 15.8, most errors +answered with a ``302`` redirect to an ``/error/...`` page that itself returned ``200``. Review +monitoring, health checks and clients that follow ``Location`` headers or expect ``/error/`` URLs. + +.. list-table:: + :header-rows: 1 + + * - Request + - Up to 15.8 + - 15.10 + * - ``/go/`` with a missing parameter, or for a document that does not exist + - ``200``, or ``302`` to ``/error/`` + - ``400`` or ``404`` + * - ``/thumbnail/`` with a missing parameter, for an unknown document, or with no thumbnail + - ``200`` or ``302`` + - ``400`` or ``404`` + * - ``/sso/metadata`` and ``/sso/logout`` when the configured SSO type does not handle them + - ``302`` to ``/error/badrequest/`` + - ``400`` + * - ``/api/v1/*``, ``/json`` and any unknown URL + - ``302`` to ``/error/notfound/`` + - ``404`` + * - An uncaught exception, including in the admin API + - ``302`` to ``/error/systemerror/`` + - ``500`` with the body ``System Error.`` (not JSON) + * - ``/error/notfound/``, ``/error/badrequest/``, ``/error/systemerror/`` themselves + - ``200`` + - ``404``, ``400``, ``500`` + +With ``login.required=true``, the search pages no longer redirect an anonymous user. They return +``200`` with the theme, which asks the user to log in, and the data behind them is refused instead: +every ``/api/v2/`` endpoint other than ``/health``, ``/auth/*`` and ``/ui/config``, including +``/api/v2/search``, answers ``401`` until the user logs in. ``/go/``, ``/thumbnail/`` and ``/osdd`` still +redirect to the login. A check that expects a redirect for an anonymous request to ``/`` has to test +``/api/v2/search`` for ``401`` instead. + +The search screen also searches through ``/api/v2/search``, so a search is logged when that API is +called, not when ``/search`` is requested. A client that does not run JavaScript receives the page +without results. + +The HTML of the search screen carries ``X-Frame-Options: DENY`` and a ``Content-Security-Policy`` with +``frame-ancestors 'none'``, so no other page can show it in a frame. The JSP search screen of 15.8 sent +``X-Frame-Options: SAMEORIGIN`` (the default of ``response.headers``) and could be shown in an ``iframe`` on +a page of the same origin. If you embedded the search screen in an ``iframe`` of the same origin, set +``theme.index.frame.ancestors`` in ``fess_config.properties`` (default ``'none'``) to ``'self'``. To embed +it from another origin, name that origin instead (see :doc:`../dev/theme-development`). + +The Page Design Editor Was Removed +---------------------------------- + +[System > Page Design] is no longer in the admin UI, so the JSP, CSS and image files of the search +screen can no longer be edited there. Use a static theme to change how the search screen looks (see +:ref:`theme-customize-bundled`). + +The following keys were removed from ``fess_config.properties`` as well. A value left under these +names is not used. + +- ``supported.uploaded.js.extentions`` +- ``supported.uploaded.css.extentions`` +- ``supported.uploaded.media.extentions`` +- ``supported.uploaded.files`` +- ``online.help.name.design`` + +The ``admin-design`` and ``admin-design-view`` roles no longer grant anything. A user who has only +these roles is taken to the search screen instead of the admin UI after logging in. + +``api.access.token.required`` Was Removed +----------------------------------------- + +``api.access.token.required`` no longer exists in ``fess_config.properties``. A value left under +that name, including in a ``fess_config.properties`` carried over from 15.8, has no effect. With +``true`` it refused every API request from a user who was not logged in. Because the search screen +now searches through ``/api/v2/search``, it would also have left anonymous users with a search +screen that shows no results. + +An installation that set it to ``true`` now answers API requests from anonymous users with the +guest roles, as it does the search screen. To keep anonymous users from searching, set +``login.required=true``. Access tokens work as before: a request with a registered access token is +given the token's permissions, and a request with an unregistered or expired token is refused. + +.. _upgrade-159-api-requests: + +Requests the API Now Refuses +---------------------------- + +15.10 refuses the following requests, which 15.8 accepted. Check the clients and scripts you wrote for 15.8. +The admin API answers a refusal with HTTP ``400`` and ``status`` ``1`` in the body. + +.. list-table:: + :header-rows: 1 + + * - Request + - Up to 15.8 + - 15.10 + * - ``/api/v2/search`` with ``facet.field`` or ``facet.query``, and a ``facet.size`` of ``0`` or less, or a ``facet.size`` or ``facet.minDocCount`` that is not an integer + - ``200``, but an empty result: ``record_count`` is ``0`` and ``partial`` is ``true`` + - ``400`` (``invalid_request``). ``facet.size`` must be ``1`` or more + * - ``track_total_hits=false``. With ``query.track.total.hits`` set to ``false``, every search is affected + - ``200``, but with no results + - The search is refused (``/api/v2/search`` answers ``400`` with ``invalid_request``). ``true`` and positive integers work as before + * - An entry in the ``mapping`` or ``kuromoji`` dictionary that repeats an existing entry, added or updated through the admin API + - Saved. Loading the dictionary then fails, which can make search unavailable + - ``400`` + * - An entry in the ``kuromoji`` dictionary whose ``token`` contains a space, or whose ``segmentation`` and ``reading`` have different numbers of space-separated parts, added or updated through the admin API + - Saved. Loading the dictionary fails in the same way + - ``400`` + * - ``DELETE /api/admin/searchlist/doc/{doc_id}`` that deletes nothing: a ``doc_id`` that does not exist, or a value that is not a ``doc_id``, such as the ``_id`` shown in the document list + - ``200`` (``status`` ``0``); the document is not deleted + - ``400`` + * - A role or group name in ``roles`` or ``groups`` of a user in the admin API + - Saved, but the name does not act as a role. For some names, reading the user fails + - ``400``. Give the ID of the role or group (the ``id`` returned by ``GET /api/admin/role/settings`` and ``GET /api/admin/group/settings``) + * - A user in the admin API whose password breaks the password policy (for example ``password.min.length``, default ``8``); a create request without a password; a ``confirm_password`` that differs from ``password`` + - Saved; the user can log in with that password + - ``400`` + +Rows of ``/api/v2/documents/all`` no longer carry ``score``. Up to 15.8 every document had its search score; +15.10 walks the whole result with a point in time and ``search_after``, which gives no score. +``/json?type=scroll`` and ``/api/v1/documents/all`` of the legacy API plugins behave the same. A script that +reads ``score`` has to cope with it being absent. + +File uploads of the admin API (the six dictionaries, ``badword``, ``elevateword`` and ``storage``) are +accepted by ``POST``. The 15.8 documentation told you to use ``PUT``, but a ``multipart/form-data`` ``PUT`` +never delivers the file, so in 15.8 as well as in 15.10 it fails with the validation error that the file is +required. The ``PUT`` endpoints remain; use ``POST`` for uploads. + +``search_engine.type=cloud`` is deprecated +------------------------------------------ + +15.10 adds the value ``vanilla`` to ``search_engine.type`` for a plain OpenSearch without the CodeLibs plugins (see :doc:`../config/search-engine-type`). ``cloud`` is now a deprecated alias of ``vanilla``: it keeps working, but |Fess| logs a warning at startup. Change it to ``vanilla`` once the installation runs 15.10. ``aws`` keeps working as before. + +* ``vanilla`` requires 15.10. |Fess| 15.8 and earlier do not know the value, so keep ``cloud`` as long as you may still roll back to 15.8. +* The index definitions of ``aws`` and ``cloud`` now come from ``fess_indices/_vanilla/``. The bundled ``fess_indices/_aws/`` and ``fess_indices/_cloud/`` directories no longer exist, and a ``fess_indices/_aws/`` or ``fess_indices/_cloud/`` directory that you added yourself is no longer read. Move your changes to ``fess_indices/_vanilla/``. Indices that already exist are not changed. +* The suggest settings that 15.8 stored in the search engine are migrated automatically; you do not have to do anything. + +The CSV Data Store Parses Quoted Fields +--------------------------------------- + +The ``fess-ds-csv`` plugin of 15.10 interprets quotes by default. A field such as ``"Yamada, Taro"`` +is one column, where the 15.8.0 plugin split it at the comma. After ``bin/fess-setup upgrade plugins``, +check data store configurations that read CSV files with quoted fields. To keep the 15.8 behavior, +add ``quote_disabled=true`` to "Parameters"; see :doc:`../config/datastore/ds-csv`, which also +describes what an unmatched quote does. + +.. _upgrade-reindex-new-fields: + +Applying New Fields and Kana Normalization to an Existing Document Index +------------------------------------------------------------------------ + +At startup 15.10 adds new fields to the configuration, log and user indices. In the document index +it adds only the ``tag`` field (``keyword``), which holds user tags; the rest of the mapping and +the analysis settings are not changed. If you keep using a document index created by 15.8 or +earlier, the following 15.10 changes do not take effect. + +- **File owner and last modifier** (``owner``, ``last_modifier``): new fields indexed by file + system, SMB and FTP crawls. The existing document index has no definition for them, so the first + crawled value maps them dynamically as ``text``, and searches such as ``owner:alice`` or + ``facet.field=owner`` do not work as intended. +- **ETag** (``etag``): the field in which the crawler stores the ETag of a crawled page, which 15.10 + sends back as ``If-None-Match`` so that an unchanged page is not fetched again. The existing + document index has no definition for it either, so it is mapped dynamically as ``text`` instead + of the bundled non-indexed ``keyword``. Conditional requests still work with that mapping. +- **Normalization of kana variants and of dashes written in place of the long vowel mark** (for + example, ``サ―バ－`` is treated as the same word as ``サーバー``): the rules live in the analysis + settings of the document index and in the ``mapping.txt`` dictionary, so an existing index does + not get them. + +To apply both, enable "Replace Aliases" and "Reset Dictionaries" under "System Info" → "Maintenance" +in the admin UI and run "Re-indexing". Re-indexing copies the existing documents into a new index, so +you do not need to crawl again. + +.. warning:: + + "Reset Dictionaries" overwrites the dictionaries on the OpenSearch side with the bundled + dictionary files. If you have edited synonyms or other dictionaries under "Dictionary" in the + admin UI, download them first and apply them again after re-indexing: remove duplicate or + invalid entries from the downloaded files (see Step 7), upload them, and then click "Reload" + under Reload Document Index in "System Info" → "Maintenance". Until you do, the analyzers of the + document index keep using the bundled dictionaries and a restored synonym does not match, however + long you wait. A dictionary that applies at index time also needs the documents to be crawled + again; see :ref:`dict-apply-changes`. + +.. note:: + + Files indexed by 15.8 or earlier have no owner or last modifier values. Incremental crawling does + not fetch unchanged files again, so to add the values, temporarily disable "Check Last Modified" + under "System" → "General" and crawl. + + +15.10-Specific Migration Tasks +============================= + +If you are upgrading from 15.7 or earlier to 15.10, 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.10. 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.10, 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. 15.10 also adds +``fess-llm-bedrock`` for Amazon Bedrock. + +If You Were Using SPNEGO (Windows Integrated Authentication) +------------------------------------------------------------ + +Starting with 15.10, a SPNEGO login is rejected when the Kerberos realm of the client principal +differs from the server realm. If your users log in from a child domain of an AD domain tree or +from a trusted forest, list those realms in ``spnego.allowed.realms``, separated by commas, from +"System" → "General" in the admin UI or in ``app/WEB-INF/conf/system.properties``. Otherwise +users who could log in up to 15.7 are rejected with ``Kerberos realm is not allowed``. For +details, see :doc:`../config/sso-spnego`. + +The coded defaults of ``spnego.allow.unsecure.basic`` and ``spnego.allow.localhost`` also changed +from ``true`` to ``false`` in 15.10. An installation where these keys are absent from +``app/WEB-INF/conf/system.properties`` inherits the stricter behavior on upgrade. In particular, +with ``spnego.allow.unsecure.basic=false`` the SPNEGO library only offers Basic authentication for +requests where ``HttpServletRequest#isSecure()`` returns ``true``, so behind a reverse proxy that +terminates TLS and forwards plain HTTP, clients that used to fall back to Basic authentication can +no longer log in. Set ``tomcat.secure=true`` in ``tomcat_config.properties`` in that case; see +:doc:`../config/sso-spnego` for details. + +.. warning:: + + A coded default only applies while the key is absent, and "System" → "General" in the admin UI + writes every ``spnego.*`` key each time you save. An installation that ever pressed Update on + that screen under 15.7 therefore still has ``spnego.allow.unsecure.basic=true`` and + ``spnego.allow.localhost=true`` stored, so upgrading to 15.10 does not harden it: the permissive + behavior is kept silently, and 15.10 only records a warning in ``fess.log`` when SPNEGO is + initialized. Open "System" → "General" in the admin UI (or edit ``system.properties``) and + turn both off deliberately. ``spnego.allow.localhost=true`` is the more dangerous of the two, + because the SPNEGO library then authenticates same-host requests as the server OS user with no + Kerberos verification at all, which is unsafe behind a same-host reverse proxy. + +.. _upgrade-159-saml: + +If You Were Using SAML Authentication (SSO) +------------------------------------------- + +Starting with 15.10, |Fess| binds every SAML response to the ID of the AuthnRequest it sent, so +IdP-initiated (unsolicited) SSO no longer works. A login started from a |Fess| tile in an IdP +portal, such as the Okta dashboard or the Microsoft Entra ID "My Apps" portal, has no AuthnRequest +to match against and is rejected. It worked up to 15.7 because |Fess| bounced the unmatched +response back to the IdP and the IdP immediately returned a solicited assertion. If you place a +tile on the IdP side, point it at the |Fess| ``/sso/`` endpoint so that the login is SP-initiated. + +The IdP also returns the assertion as a cross-site POST, so ``tomcat.sameSiteCookies`` in +``tomcat_config.properties`` must be set to ``none``. With the shipped default ``lax`` the session +cookie is not sent on that request and the SAML login cannot complete. This file is located in +``lib/classes/`` for the ZIP package and in ``/etc/fess/`` for the DEB/RPM packages, and |Fess| +must be restarted after the change. Browsers only accept ``none`` on a cookie that also carries +the ``Secure`` attribute, so |Fess| must be served over HTTPS. Up to 15.7 the same +misconfiguration did not produce a clean error but an endless redirect loop back to the IdP, so +check the setting even on a site that appeared to work; 15.10 fails once instead of looping. For +details, see :doc:`../config/sso-saml`. + +If You Were Using Microsoft Entra ID (Azure AD) +----------------------------------------------- + +Starting with 15.10, the response mode requested from the authorization endpoint defaults to +``query`` instead of ``form_post``. Up to 15.7 the callback was returned as a cross-site POST, +and the |Fess| default ``tomcat.sameSiteCookies = lax`` does not send the session cookie with +such a request, so ``tomcat.sameSiteCookies = none`` was required. If you set ``none`` only for +that reason, you can restore the default. To keep the previous behaviour, set +``entraid.response.mode=form_post`` and leave ``tomcat.sameSiteCookies = none`` in place. +Browsers only accept ``none`` on a cookie that also carries the ``Secure`` attribute, so that +path requires |Fess| to be served over HTTPS as well. + +Starting with 15.10, |Fess| also resolves the user's group and role membership in the background +after login completes, instead of blocking the login on Microsoft Graph. Until resolution +finishes — or if it does not fully succeed — the user holds only their own user-level permission +and whatever ``entraid.default.groups`` and ``entraid.default.roles`` provide. With neither of +those set, which is the shipped default, a search made in that window returns no documents at all, +because a crawling configuration created with the shipped defaults grants ``{role}guest`` and a +logged-in user does not hold that role. The search screen says so while resolution is in progress, +and says something different if it did not fully succeed — the resolution counts as failed unless +both the direct membership lookup and the nested group walk succeeded. Resolution is retried +whenever the access token is renewed, and a later success clears the message, so a failure is not +final for a session that outlives the token; to retry straight away, log out and log in again. For +details, see :doc:`../config/sso-entraid`. + +One consequence of resolving in the background: until it lands, the user's resolved roles are not +yet known. An administrator is therefore redirected to the search screen instead of the admin +dashboard, and opening an administration page during that window returns them to the search +screen. The window is up to about a second of scheduling delay plus the Microsoft Graph calls +themselves — one for the direct memberships, then one more for each of those groups to walk the +nested groups, issued one after another on a cold cache — so it grows with the number of groups +the user belongs to. Access is only ever refused, never granted, in that window, and it needs no +configuration to get past: authorization is evaluated again on every request of the same session, +so once resolution has landed the administration screens open normally, without logging in again. + +.. warning:: + + Do not shorten that window by putting the |Fess| administrator role in + ``entraid.default.roles``. That property is a single global value that |Fess| applies to every + Entra ID user at login and re-applies on every later resolution, so it would give every user in + the tenant permanent |Fess| administrator rights. + +If You Use LDAP / Active Directory +---------------------------------- + +From 15.10, the permission name of a group or role is the value of the entry's RDN rather than a +slice of the DN text. A group whose CN contains a character the DN escapes -- a comma is the +common one -- therefore gets a different permission name than it did in 15.7. + +.. list-table:: + :header-rows: 1 + + * - Group entry DN + - Permission name up to 15.7 + - Permission name in 15.10 + * - ``CN=Sales\, EMEA,CN=Users,...`` + - ``2Sales`` + - ``2Sales, EMEA`` + * - ``CN=Sales\, APAC,CN=Users,...`` + - ``2Sales`` + - ``2Sales, APAC`` + +Up to 15.7 several groups agreeing up to the comma collapsed onto one permission name, so members +of ``Sales, EMEA`` and ``Sales, APAC`` could read each other's documents and those of the ``Sales`` +group. In 15.10 each gets its own permission name and that cross-group access does not happen. + +In exchange, **documents indexed under the old permission name are no longer visible to members of +that group**. If a crawling configuration's permission setting holds an old permission name, update +it to the new one and crawl (or reindex) again. If you use no group whose CN contains a comma or +another escaped character, no permission name changes. + +Change to ``ldap.role.search.user.enabled`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Up to 15.7 the permission derived from the user name (``role.search.user.prefix`` followed by the +user name) was granted even with ``ldap.role.search.user.enabled=false``. From 15.10 the setting +takes effect and the permission is not granted when it is off. + +In a deployment that sets it to ``false``, users lose the permission named after themselves after +the upgrade, so documents permissioned to an individual user stop matching for that user. To keep +the previous behaviour, restore the shipped default of ``true``. + +If You Changed the /api/v2 Configuration Keys +------------------------------------------------ + +In 15.8.0, four configuration keys lost their ``api.v2.`` prefix. Their values, defaults and +behaviour are unchanged, but **no backward-compatible alias is kept**: a setting left under its +old name is ignored without any warning, and the shipped default takes effect instead. + +.. list-table:: + :header-rows: 1 + + * - Up to 15.7 + - 15.8.0 and later + - Default + * - ``api.v2.chat.stream.keepalive.interval.ms`` + - ``api.chat.stream.keepalive.interval.ms`` + - ``15000`` + * - ``api.v2.param.max.length`` + - ``api.param.max.length`` + - ``1000`` + * - ``api.v2.param.max.array.size`` + - ``api.param.max.array.size`` + - ``100`` + * - ``api.v2.click.max.rt`` + - ``api.click.max.timestamp`` + - ``9999999999999`` + +If you set any of these in ``fess_config.properties`` or as a ``-Dfess.config.`` JVM +argument, rename them. Only an explicit setting is affected; an installation that never changed +them needs no action. + +The first key controls how often a keep-alive frame is sent while ``POST /api/v2/chat/stream`` +is waiting for the model, so AI search mode is where a lost setting becomes visible. The last +key was renamed for accuracy as well: it bounds the ``rt`` value a click log may carry, which is +a timestamp rather than a response time. + + +.. _upgrade-plugin-versions: + +Updating Plugin Versions +------------------------ + +Plugins installed under ``app/WEB-INF/plugin/`` need to be replaced with versions matching your +|Fess| version. ``bin/fess-setup upgrade plugins`` does this for every installed plugin: it +installs the version built for this |Fess| and deletes the old one. Restart |Fess| afterwards. +``bin/fess-setup check`` then reports on OpenSearch, its plugins and the installed |Fess| plugins, +and exits with code 1 when something is wrong. It does not read ``bin/fess.in.sh``, +``/etc/sysconfig/fess`` or ``/etc/default/fess``, so when OpenSearch is not at +``http://localhost:9200``, pass ``--url`` or set ``SEARCH_ENGINE_HTTP_URL`` in the shell that runs +it; otherwise it reports the engine as unreachable. + +:: + + $ bin/fess-setup upgrade plugins + $ bin/fess-setup check + +``upgrade plugins`` only handles plugins that are already installed. Install the plugins that +replace parts removed from the distribution in 15.10, such as ``fess-script-groovy``, with +``bin/fess-setup install plugin`` as described in the sections above. + +If you specify ``FESS_PLUGINS`` in the Docker version, update the version part, for example to +``fess-ds-wikipedia:15.10.0``. + +Rollback Procedure +================== + +If the upgrade fails, you can rollback with the following procedure. + +Step 1: Stop New Version +------------------------- + +:: + + $ sudo systemctl stop fess.service + $ sudo systemctl stop opensearch.service + +Step 2: Restore Old Version +---------------------------- + +Restore configuration files and data from backup. + +For RPM/DEB version:: + + $ sudo rpm -Uvh --oldpackage --nodeps fess-.rpm + +Or:: + + $ sudo dpkg -i fess-.deb + +.. note:: + + ``--nodeps`` is needed for the RPM. The 15.8.0 package requires the ``fess`` and ``opensearch`` + users and groups, and without it ``rpm`` refuses the downgrade with ``Failed dependencies: + group(fess) is needed by fess-15.8.0``. + +.. warning:: + + The 15.8.0 DEB package does not register ``/etc/fess/*`` as conffiles, so ``dpkg -i`` overwrites + the files you edited, such as ``/etc/fess/fess_config.properties``, without keeping a copy. Restore + them from the backup you took in Step 1. + +Step 3: Restore Data +--------------------- + +Restore from snapshot. OpenSearch must be running and |Fess| stopped: + +1. Start OpenSearch:: + + $ sudo systemctl start opensearch.service + +2. A snapshot cannot be restored over an index that exists, so delete every Fess index first, + including the ones created after the upgrade (for example by re-indexing), and the ``configsync`` + index that the OpenSearch plugin creates. If you delete only the indices that are in the + snapshot, an index created by re-indexing stays behind, ``fess.search`` points at two indices, + and 15.8.0 does not start:: + + $ curl "http://localhost:9200/_cat/indices/fess*,configsync?h=index" + $ curl -X DELETE "http://localhost:9200/" + + Run the second command for each index that the first one lists. + +3. Restore the snapshot:: + + $ curl -X POST "http://localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true" + +.. note:: + + The dictionary directory must exist as before (``configsync.config_path``, with the dictionary + files). On a machine that has lost it, the restore finishes but the indices that use the + dictionaries stay red. + +Or restore directory from backup (use the name of the archive you created in Step 1):: + + $ sudo systemctl stop opensearch + $ sudo rm -rf /var/lib/opensearch/data/* + $ sudo tar xzf /backup/opensearch-data-.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 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 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 +--------------------------------- + +:: + + $ sudo systemctl start opensearch.service + $ sudo systemctl start fess.service + +Verify operation and confirm it has returned to normal. + +Frequently Asked Questions +=========================== + +Q: Can I upgrade without downtime? +----------------------------------- + +A: Upgrading Fess requires service shutdown. To minimize downtime, consider the following: + +- Verify procedures in a test environment first +- Create backups in advance +- Secure sufficient maintenance time + +Q: Do I need to upgrade OpenSearch too? +---------------------------------------- + +A: Each version of |Fess| requires a specific version of OpenSearch. +|Fess| 15.10 requires OpenSearch 3.9.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.9.0). + +Also, |Fess| 15.10 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 a |Fess| minor version upgrade (15.x → 15.10) 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. +- **Using owner search or the kana normalization with a document index created by 15.8 or earlier**: + a re-index is needed. See :ref:`upgrade-reindex-new-fields` for details. + +.. 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 +-------------------------------------------------- + +A: Verify the following: + +1. Verify OpenSearch is running +2. Verify indexes exist (``curl http://localhost:9200/_cat/indices``) +3. Re-run crawl + +Next Steps +========== + +After the upgrade is complete: + +- :doc:`run` - Verify startup and initial configuration +- :doc:`security` - Review security configuration +- :doc:`../config/search-semantic` - Chunk-vector search (semantic search) configuration and migration steps +- Check release notes for new features diff --git a/en/15.10/user/advanced-search.rst b/en/15.10/user/advanced-search.rst new file mode 100644 index 000000000..049f8bc5c --- /dev/null +++ b/en/15.10/user/advanced-search.rst @@ -0,0 +1,79 @@ +=============== +Advanced Search +=============== + +The Advanced Search page enables you to perform more advanced searches by combining multiple conditions. + +Usage +----- + +The Advanced Search page can be accessed from the Advanced Search link in the search options on the search screen. When you open it from the search results screen, the search keywords you have already entered are carried over to the All These Words field. + +|image0| + +Enter conditions in each field and click the Search button at the bottom of the page to execute your search. The multiple fields you enter are combined into a single search condition. + +Field List +---------- + +All These Words +::::::::::::::: + +Searches for documents that contain all of the words you enter (AND search). You can specify multiple words separated by spaces. + +This Exact Phrase +::::::::::::::::: + +Searches for documents that contain the string you enter exactly, including word order (phrase search). Because the entire string, including spaces, is treated as a single phrase, you cannot search word by word. + +Any of These Words +:::::::::::::::::: + +Searches for documents that contain any of the words you enter (OR search). You can specify multiple words separated by spaces. + +None of These Words +::::::::::::::::::: + +Searches for documents that do not contain the words you enter. You can specify multiple words separated by spaces, and all of the specified words are excluded from the search results. + +Results per Page +:::::::::::::::: + +Specifies the number of search results to display per page. You can choose from 10, 20, 30, 40, 50, or 100. If not specified, the default number of results (10 by default) is used. + +Sort +:::: + +Specifies the criteria for sorting search results. You can choose from by Score, by Filename, by Date, by Size, and by Last Modified, and you can specify ascending or descending order for each. Sorting by Click Count or by Favorite Count can be selected when the corresponding feature is enabled. + +Preferred Languages +::::::::::::::::::: + +Specifies the language to prefer in search results. You can also select multiple languages. If you select All Languages, no specific language is preferred. + +Labels +:::::: + +Filters search results by label. You can also select multiple labels. This option is not displayed if no labels are registered or if there are no labels that the current user can access. + +Last Modified +::::::::::::: + +Filters search results by the document's modification date and time. You can choose from Anytime, Past 24 hours, Past week, Past month, and Past year. + +File Type +::::::::: + +Filters search results by the document's file type. You can choose from Any format, HTML, PDF, MS Word, MS Excel, and MS PowerPoint. + +Search Target +::::::::::::: + +Specifies the target to search. You can choose from Anywhere in the page, in the title of the page, and in the URL of the page. If you specify in the title of the page or in the URL of the page, the words you enter are searched only within the title or URL. + +Site or Domain +:::::::::::::: + +Filters search results by the site or domain you enter. Specify this when you want to search only documents contained in a specific site or domain. + +.. |image0| image:: ../../../resources/images/en/15.10/user/advanced-search-1.png diff --git a/en/15.10/user/chat-search.rst b/en/15.10/user/chat-search.rst new file mode 100644 index 000000000..230587a6b --- /dev/null +++ b/en/15.10/user/chat-search.rst @@ -0,0 +1,272 @@ +================== +AI Search Mode +================== + +Overview +========== + +With the AI search mode feature (RAG chat) in |Fess|, you can look for information through natural +conversation, in addition to traditional keyword search. When you enter a question, the AI +assistant searches for relevant documents and generates an easy-to-understand answer based on +their content. + +.. note:: + AI search mode is disabled by default. To use it, a system administrator must enable + the feature and configure an LLM (Large Language Model) provider. For configuration + instructions, see :doc:`../config/rag-chat` and :doc:`../config/llm-overview`. + +Features of AI Search Mode +============================ + +Conversational Search +----------------------- + +Instead of coming up with keywords, you can ask questions just as you would in everyday +conversation. + +For example: + +- "Tell me how to install Fess" +- "How do I crawl files?" +- "What should I do if no search results appear?" + +Context-Aware Answers +----------------------- + +The AI assistant analyzes the intent of your question, searches for relevant documents, and +extracts the necessary information from multiple search results to provide an organized answer. + +Clearly Cited Sources +----------------------- + +At the bottom of an answer, the documents that the answer was based on are listed as +"Sources". Each source is a numbered link, and clicking it lets you view the original +document directly. The answer body may also include citation numbers such as ``[1]`` +and ``[2]``, which correspond to the numbers in the sources list. + +Multi-Turn Conversations +-------------------------- + +You are not limited to a single question; you can keep the conversation going. The AI +assistant answers additional questions while taking the context of previous questions and +answers into account. + +How to Use Chat Search +========================= + +Opening AI Search Mode +------------------------ + +1. Open the |Fess| search screen +2. Click the "AI Search" link (robot icon) in the navigation bar at the top of the screen +3. The AI search mode screen is displayed + +.. note:: + The "AI Search" link is displayed only when AI search mode is enabled and an LLM + provider is available. If the link does not appear, see `Frequently Asked Questions`_. + +Entering a Question +--------------------- + +1. Enter your question in the text box at the bottom of the screen (up to 4000 characters + per question) +2. Click the "Send message" button (paper airplane icon), or press Enter +3. The AI assistant starts generating an answer + +.. note:: + To insert a line break, press Shift+Enter instead of Enter, as indicated by the hint + below the text box: "Press Enter to send, Shift+Enter for new line". + +.. note:: + Generating an answer can take anywhere from a few seconds to over ten seconds. While + processing, the current phase is shown in a progress indicator (Analyze → Search → + Evaluate → Retrieve → Answer), along with messages such as "Thinking...", + "Searching...", "Reviewing search results...", "Retrieving documents...", and + "Generating answer...". Once the search is complete, the number of documents found is + also displayed. + +Reviewing the Answer +----------------------- + +The AI assistant's answer is displayed. The answer includes the following information: + +- **Answer body**: The answer to your question (formatted in Markdown) +- **Sources**: A numbered list of links to the documents the answer is based on (clicking a + link opens the original document in a new tab) + +The answer body may include citation numbers such as ``[1]`` and ``[2]``, which correspond +to the numbers in the sources list. Each answer has a copy button that lets you copy its +content to the clipboard. + +.. note:: + The AI uses only the top documents it considers most relevant among the search results + as the basis for its answer. As a result, the number of sources may be smaller than the + number of documents that matched the search. + +Narrowing Down Search Targets +------------------------------- + +Depending on the topic, you can use the "Filter" button at the top of the screen to narrow +down the search target by criteria such as label, file type, last modified date, and size. +This is useful when you want to ask the AI about a specific set of documents only. + +Continuing the Conversation +------------------------------ + +If you have additional questions, you can simply keep asking: + +- "Could you explain in more detail?" +- "Are there other ways to do this?" +- "Tell me more about XX" + +The AI assistant answers while taking the context of the previous conversation into account. + +Starting a New Conversation +------------------------------ + +If you want to ask about a different topic, click the "New Chat" button (plus icon). This +clears the previous conversation history so you can start a new conversation. + +Tips for Effective Questions +=============================== + +Be Specific +------------- + +Specific questions get more appropriate answers than vague ones. + +.. list-table:: + :header-rows: 1 + :widths: 50 50 + + * - Vague Question + - Specific Question + * - How do I configure this? + - How do I change the memory settings in Fess? + * - I'm getting an error + - I get an "index not found" error when searching + * - About crawling + - How do I configure exclusions when crawling a website? + +Include Background Information +---------------------------------- + +Including your situation and purpose leads to more appropriate answers. + +Good examples: + +- "I'm running Fess in a Docker environment. I want to change where the logs are stored — + how do I do that?" +- "This is my first time using Fess. What should I do first?" + +Ask Questions Step by Step +------------------------------ + +Complex issues are easier to understand when you ask about them step by step. + +1. "Can Fess crawl file shares?" +2. "How do I connect using the SMB protocol?" +3. "What should I do for shared folders that require authentication?" + +Frequently Asked Questions +============================= + +Q: AI Search Mode Doesn't Appear +----------------------------------- + +A: AI search mode may not be enabled. The "AI Search" link is displayed only when the +feature is enabled (``rag.chat.enabled=true``) and an LLM provider (such as OpenAI, Gemini, +or Ollama) is configured and available. Ask your system administrator to check whether AI +search mode is enabled and whether the LLM provider is configured correctly (see +:doc:`../config/rag-chat` for details). + +Q: It Takes a Long Time for the Answer to Appear +---------------------------------------------------- + +A: Since the AI analyzes your question, searches for and evaluates documents, and then +generates an answer, this can take anywhere from a few seconds to over ten seconds. While +processing, the current phase is displayed ("Thinking...", "Searching...", "Reviewing +search results...", "Retrieving documents...", "Generating answer..."). + +Q: The Sources Seem to Be Incorrect +--------------------------------------- + +A: Click the source links to check the original documents. The AI generates answers based +on search results, but its interpretation may occasionally be incorrect. We recommend +always verifying important information against the original documents. + +Q: It Seems to Have Forgotten the Previous Conversation +------------------------------------------------------------- + +A: The conversation session may have timed out. If there is no activity for a certain +period (30 minutes by default), the conversation history is cleared. In addition, since +the conversation history is temporarily kept in the server's memory, it is also lost if the +server restarts. If this happens, please start a new conversation. + +.. note:: + The "session" mentioned here refers to the AI search mode's conversation session, which + is separate from your |Fess| login session. + +Q: I Can't Get an Answer to a Specific Question +----------------------------------------------------- + +A: The following are possible causes: + +- There is no relevant information in the documents being searched +- The question is too vague for the search to work properly +- A rate limit has been reached (the maximum number of requests per minute, or the maximum + number of concurrent requests, has been exceeded) + +Try rephrasing your question, or wait a while and try again. + +Q: Is There a Limit on the Number of Characters I Can Enter? +-------------------------------------------------------------- + +A: You can enter up to 4000 characters per question. A character counter is displayed +below the text box, and it switches to a warning display as you approach the limit. If +your question is long, shorten it by focusing on the key points. + +Q: Can I Ask Questions in Languages Other Than English? +--------------------------------------------------------- + +A: Yes, in most cases you can also ask questions in other languages. Based on your +browser's or the screen's display language, the AI tries to respond in the same language +whenever possible. However, this is a best-effort behavior, and in some cases the response +may not be in the language you intended. + +Notes +======= + +About AI Responses +-------------------- + +- AI responses are generated based on search results +- The accuracy of responses is not guaranteed +- For important decisions, always check the original documents (sources) +- For the latest information, refer to the official documentation + +About Privacy +--------------- + +- The questions you enter are used for search and for AI processing by the configured LLM + provider +- If the system is configured to use an external LLM service (such as OpenAI or Gemini), + the content of your questions and the search results are sent to that service. If you + want processing to stay entirely in-house, ask your administrator about using a locally + running provider (such as Ollama) +- Conversation history is temporarily kept in the server's memory and is deleted when the + session times out, when you click "New Chat", or when the server restarts +- As with regular search, role (permission) and label-based access control applies, so + documents you are not permitted to view are not used as a basis for answers +- Depending on the system configuration, logs may be recorded + +References +============ + +- :doc:`../config/rag-chat` - Configuring the AI search mode feature (for administrators) +- :doc:`../config/llm-overview` - Configuring LLM providers +- :doc:`../api/api-chat` - Chat API (for programmatic use) +- :doc:`search-and` - How to Use AND Search +- :doc:`search-not` - How to Use NOT Search +- :doc:`search-field` - How to Use Field Search +- :doc:`advanced-search` - Advanced Search Features diff --git a/en/15.10/user/index.rst b/en/15.10/user/index.rst new file mode 100644 index 000000000..1d5c4c616 --- /dev/null +++ b/en/15.10/user/index.rst @@ -0,0 +1,29 @@ +|Fess| User Guide +================== + +How to write search queries in |Fess|: AND, OR and NOT, field and +label search, sorting, wildcards, ranges, boosting, fuzzy search, proximity search, +and geo search. + +.. toctree:: + :maxdepth: 2 + + intro + search-and + search-or + search-not + search-bangs + search-label + search-field + search-sort + search-wildcard + search-range + search-boost + search-fuzzy + search-proximity + search-geo + search-additional + role-search + special-char + advanced-search + chat-search diff --git a/en/15.10/user/intro.rst b/en/15.10/user/intro.rst new file mode 100644 index 000000000..cf5ae1ae6 --- /dev/null +++ b/en/15.10/user/intro.rst @@ -0,0 +1,48 @@ +========================= +Introduction to Searching +========================= + +Intended Audience +================= + +|Fess| is an enterprise search server that provides full-text search over documents in web sites, files, databases, and more. + +This document is intended for |Fess| users. + +Before You Read This Document +============================== + +This document explains how to search with |Fess|. In addition to basic keyword search, it also covers refining your search using the Advanced Search page and the AI search mode, which lets you look for information in a natural, conversational way. Basic knowledge of computer operation is required. + +Online Access +============= + +For downloads, professional services, support, and other developer information, please visit: + +- Project site: https://fess.codelibs.org/ + +Technical Support Contact +========================= + +If you have technical questions about this product that cannot be resolved through this documentation, please visit: + +- Issues: + `https://github.com/codelibs/fess/issues `__ + +Commercial Support +------------------ + +If you require commercial support such as technical assistance or maintenance for this product, please contact `N2SM, Inc. `__. + +Third-Party Website References +=============================== + +The |Fess| project is not responsible for the validity of third-party websites listed in this document. The |Fess| project does not provide any warranties, responsibilities, or obligations regarding content, advertisements, products, services, or other materials available through such sites or resources. The |Fess| project shall not be liable or responsible for any damages or losses caused or alleged to be caused by or in connection with the use of or reliance on such content, advertisements, products, services, or other materials available through such sites or resources. + +Submitting Comments and Suggestions +==================================== + +The |Fess| project strives to improve this documentation and welcomes comments and suggestions from readers. + +- Issues: + `https://github.com/codelibs/fess-docs/issues `__ diff --git a/en/15.10/user/role-search.rst b/en/15.10/user/role-search.rst new file mode 100644 index 000000000..0c38eedf5 --- /dev/null +++ b/en/15.10/user/role-search.rst @@ -0,0 +1,58 @@ +=========== +Role Search +=========== + +|Fess| provides user management functionality, and users who have logged in can search based on the roles they belong to. Users managed by |Fess| can use role search and change their own password after logging in. + +Role search compares the permissions (roles, groups, and users) set on content with the permissions held by the searching user, and displays only the content for which access is permitted in the search results. For information on how to create roles and users, and how to assign permissions to content, and other role-based search configuration, see :doc:`../config/security-role`. + + +Search Method +------------- + +If roles are configured and the content has been crawled and indexed with those roles, the search results can be displayed only to users who hold that role. +When a user is logged in, searches are performed based on the roles and groups that user belongs to. +When not logged in, searches are performed as the guest user, and only content published for guest is displayed. + +.. note:: + A search by a logged-in user is performed using only the permissions of that user and of the roles and groups the user belongs to, and content published for guest (``{role}guest``) is not included. Therefore, content published only for guest is displayed to visitors who are not logged in, but is not displayed to logged-in users (including users who have no roles or groups). For content that logged-in users should also see, set in the permissions of the crawl configuration, in addition to ``{role}guest``, the roles those users have (or, to show it to all users, a role granted to all users). + +Login +----- + +Clicking the Login link displayed at the top of the search screen displays the login screen. After entering your username and password and logging in, you are returned to the search screen, and subsequent searches are performed based on the roles the user belongs to. + +.. note:: + If integrated with single sign-on or LDAP, log in using the respective authentication method. Also, whether the Login link is displayed can be changed via configuration. + +Changing Password +------------------ + +After logging in, click the username displayed at the top of the search screen to display the menu. + +|image0| + +Clicking "Change Password" in the menu displays the password change screen. + +|image1| + +Enter your Current Password, New Password, and Confirm New Password (re-enter), then click the Update button to update your password. +Changing your password logs you out, so log in again with the new password. +This screen is the ``/profile`` page of the search screen's theme, and the password is changed with ``POST /api/v2/auth/password`` (see :doc:`../api/api-auth`). + +.. note:: + The "Change Password" menu item is displayed only for users managed by |Fess| (and LDAP users permitted to edit their password). It is not displayed for users authenticated via single sign-on. + A password policy, such as length and allowed character types, may apply to the new password. + +Logging Out +----------- + +While logged in, click the username displayed at the top of the search screen and select "Logout" from the menu to log out. +Users with administrator privileges can also select "Administration" from the same menu to go to the administration screen. + + + +.. |image0| image:: ../../../resources/images/en/15.10/user/role-search-1.png +.. pdf :width: 200 px +.. |image1| image:: ../../../resources/images/en/15.10/user/role-search-2.png +.. pdf :width: 300 px diff --git a/en/15.10/user/search-additional.rst b/en/15.10/user/search-additional.rst new file mode 100644 index 000000000..56ccb6003 --- /dev/null +++ b/en/15.10/user/search-additional.rst @@ -0,0 +1,30 @@ +======================== +Hidden Search Conditions +======================== + +You can use the ``ex_q`` parameter when you want to carry a specific search condition without displaying its text on the screen. Conditions specified in ``ex_q`` are not shown in the search keyword input field, and they are retained even when the screen is refreshed through pagination or facet filtering. + +In ``ex_q``, you can use the same query syntax as the regular search keyword (``q``) — the ``field:value`` format, phrases, range specifications, operators such as ``OR``, and so on. The specified condition is combined with the ``q`` condition using AND by default when the search is executed. In other words, documents that do not match the ``ex_q`` condition are excluded from the search results. + +Usage +----- + +When executing a search (for example, from a search form), append the value of ``ex_q`` as a hidden form field or as a URL query parameter, then execute the search. This lets you search without displaying the condition on the screen. + +You can specify ``ex_q`` more than once. As shown in the example below, passing multiple ``ex_q`` values adds each one as a search condition (empty or duplicate values are ignored). + +.. code-block:: none + + /search?q=keyword&ex_q=label:manual&ex_q=filetype:pdf + +Retention During Pagination +--------------------------- + +Fess automatically appends the value of ``ex_q`` to pagination links (such as next page and previous page) and facet filtering links. As a result, the ``ex_q`` condition is retained even when the screen is refreshed through these operations. + +On the other hand, if you enter a keyword in the standard search keyword input field (the search box) and search again, ``ex_q`` is not carried over. If you want the condition to be retained through the search box as well, add a hidden ``ex_q`` field to your own search form and submit ``ex_q`` with every search. + +.. note:: + + * If the length of an individual ``ex_q`` value exceeds ``query.max.length`` (default: 1000 characters), that value is ignored without causing an error. + * ``ex_q`` can be used not only for searches on the web screen but also with the search API (``/api/v2``). In the API, the maximum number of ``ex_q`` elements per request (``api.v2.param.max.array.size``, default: 100) and the maximum length of each element (``api.v2.param.max.length``, default: 1000 characters) apply. diff --git a/en/15.10/user/search-and.rst b/en/15.10/user/search-and.rst new file mode 100644 index 000000000..08bd82279 --- /dev/null +++ b/en/15.10/user/search-and.rst @@ -0,0 +1,44 @@ +========== +AND Search +========== + +Use AND search to find documents that contain all of the specified search terms. When multiple words are separated by spaces in the search input field, the default is AND search, so you can omit AND and still get the same result. + +Usage +----- + +To use AND search, specify AND between search terms. AND must be written in uppercase letters with spaces before and after it. AND can also be omitted. + +For example, to search for documents containing both "term1" and "term2", enter the following in the search form: + +:: + + term1 AND term2 + +You can also omit AND and write it as follows, which gives the same result: + +:: + + term1 term2 + +You can also connect three or more search terms with AND. + +:: + + term1 AND term2 AND term3 + +.. note:: + + AND must be written in uppercase letters. If written in lowercase as ``and``, it is not treated as an operator but is searched as an ordinary search term "and". ``&&`` can also be used with the same meaning as AND. + +Using parentheses ``( )``, you can combine AND search with other search conditions. For example, to search for documents that contain "term1", and also contain either "term2" or "term3", enter the following: + +:: + + term1 AND (term2 OR term3) + +You can also perform an AND search by specifying a field. In the following example, it searches for documents that contain "term1" in the title field, and "term2" in the content field. + +:: + + title:term1 AND content:term2 diff --git a/en/15.10/user/search-bangs.rst b/en/15.10/user/search-bangs.rst new file mode 100644 index 000000000..17b7f2a4c --- /dev/null +++ b/en/15.10/user/search-bangs.rst @@ -0,0 +1,80 @@ +============================== +Bangs (Searching Another Site) +============================== + +A bang sends a search to another site instead of searching |Fess|. It works like the bangs of DuckDuckGo: put ``!`` and a short trigger word in the query, and |Fess| sends the rest of the query to the site the trigger stands for. + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Query + - Goes to + * - ``airplane !g`` + - Google, searching for ``airplane`` + * - ``!w Ohm's law`` + - Wikipedia, searching for ``Ohm's law`` + * - ``!g`` + - The home page of Google + * - ``airplane !unknown`` + - |Fess|, as a normal search (``!`` means NOT, see :doc:`search-not`) + +Bangs are provided by the ``fess-webapp-bangs`` plugin, which requires |Fess| 15.10 or later. Install it from [System > Plugin] in the admin console or with ``bin/fess-setup install plugin fess-webapp-bangs`` (see :doc:`../admin/plugin-guide`), and restart |Fess|. + +How a Bang Is Recognized +======================== + +- A bang is ``!`` followed by a trigger, written as a separate word. The trigger is case-insensitive. +- The bang is removed from the query, and the rest of the query is sent to the URL of the bang. +- When a query holds more than one defined bang, only the first one counts. +- A trigger that is not defined is not a bang. ``!unknown`` is searched as usual, and excludes the word ``unknown``. +- ``-g`` and ``NOT g`` still exclude the word ``g``. Only ``!g`` is a bang. + +The search page and ``/api/v2/search`` follow the redirect: the API returns ``redirect_url`` (see :doc:`../api/api-search`), and the ``bootstrap`` theme bundled with |Fess| navigates to it. Other themes need the same handling. + +Callers that cannot redirect, such as chat, MCP, the v1 and classic JSON APIs, and the admin search, do not send the search elsewhere. They drop the bang and search the rest of the query. + +Defining Bangs +============== + +Bangs are defined by the system property ``bangs.definitions``. Set it in ``app/WEB-INF/conf/system.properties``, or pass it as ``-Dfess.system.bangs.definitions=...``. A change in ``system.properties`` is picked up without restarting |Fess|. + +The value is a whitespace-separated list of ``trigger=url`` entries. In the URL, ``{query}`` is replaced with the URL-encoded rest of the query: + +:: + + bangs.definitions=g=https://www.google.com/search?q={query} w=https://en.wikipedia.org/wiki/Special:Search?search={query} + +- A trigger cannot contain whitespace, ``(``, ``)``, ``!``, ``"``, ``=`` or ``:``. +- Only absolute ``http`` or ``https`` URLs are accepted. +- An entry that does not follow these rules is not used. A warning is written to the |Fess| log, and the other entries stay in effect. +- If the same trigger is defined twice, the first definition is used. +- An empty value turns every bang off. + +When ``bangs.definitions`` is not set, the following five bangs are available: + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Trigger + - Site + * - ``g`` + - Google + * - ``b`` + - Bing + * - ``ddg`` + - DuckDuckGo + * - ``w`` + - Wikipedia (English) + * - ``gh`` + - GitHub + +Setting ``bangs.definitions`` replaces this list. To keep the defaults and add one more, write all of the entries you need. + +Related Topics +============== + +- :doc:`search-not` - NOT search syntax +- :doc:`special-char` - Special characters and escaping +- :doc:`../api/api-search` - Search API diff --git a/en/15.10/user/search-boost.rst b/en/15.10/user/search-boost.rst new file mode 100644 index 000000000..b670904d0 --- /dev/null +++ b/en/15.10/user/search-boost.rst @@ -0,0 +1,46 @@ +============ +Boost Search +============ + +Boost Search (Weighted Search) +=============================== + +Use boost search when you want to prioritize specific search terms among your search keywords. Boost search allows you to search according to the importance of each search term. + +Usage +----- + +To use boost search, specify a boost value (weighting value) in the format "^boost_value" immediately after the search term. Make sure not to include a space between the search term and the boost value. + +For example, if you want to prioritize "apple" when searching for "apple orange", enter the following in the search form: + +:: + + apple^100 orange + +In this example, the boost value is applied only to "apple", not to "orange". + +Boost Value +----------- + +Specify a number for the boost value. You can specify not only integers but also decimals such as ``2.5``. + +- Specifying a value greater than 1 increases the weight of that search term. +- Specifying a value greater than 0 and less than 1 (e.g., ``0.5``) decreases the weight of that search term. + +The boost value does not determine the search result score in absolute terms; rather, it adjusts the relative weighting among search terms. + +Combining with Other Search Syntax +----------------------------------- + +Boost search can be combined with other search syntax. For example, you can also add a boost value to a search term that specifies a field. + +:: + + title:apple^100 orange + +In this example, the default operator (AND) for multiple search terms is applied, so only documents whose title field contains "apple" and that also contain "orange" are searched. To prioritize documents containing "apple" while keeping documents that do not contain it in the results, combine the terms with OR. + +:: + + title:apple^100 OR orange diff --git a/en/15.10/user/search-field.rst b/en/15.10/user/search-field.rst new file mode 100644 index 000000000..80eca0864 --- /dev/null +++ b/en/15.10/user/search-field.rst @@ -0,0 +1,134 @@ +=============================================== +Field Search (Narrowing by Title, URL and More) +=============================================== + +Field-Specified Search +====================== + +By searching within a specific field (field-specified search), you can narrow your search to just the title, just the URL, and so on. Content crawled by |Fess| is stored in separate fields such as title and body. You can search by specifying these fields. By specifying fields, you can define detailed search conditions such as by document type or size. + +Available Fields +---------------- + +By default, you can search using the following fields: + +.. list-table:: + :header-rows: 1 + + * - Field Name + - Description + - Data Type + * - url + - Crawled URL + - Keyword + * - host + - Host name contained in the crawled URL + - Keyword + * - site + - The URL with the scheme and query string removed (host name and path). Matched using prefix search + - Keyword + * - title + - Title + - Text + * - content + - Body text + - Text + * - content_length + - Document size (in bytes) + - Numeric + * - last_modified + - Last modified date and time of the document + - Date + * - timestamp + - Registration date and time of the document (the crawl execution time, if the last modified date and time cannot be obtained) + - Date + * - mimetype + - MIME type of the document (e.g., ``text/html``) + - Keyword + * - filetype + - File type determined from the MIME type (e.g., ``html``, ``word``, ``pdf``; ``others`` if none apply) + - Keyword + * - filename + - File name at the end of the URL path + - Keyword + * - label + - Value of the label assigned to the document + - Keyword + * - lang + - Language code of the document (e.g., ``ja``, ``en``) + - Keyword + * - anchor + - Link destination URLs extracted from within the HTML page (web crawl only) + - Keyword + * - click_count + - Number of times the document has been clicked + - Numeric + * - favorite_count + - Number of times the document has been added as a favorite + - Numeric + * - owner + - Account name of the file owner + - Keyword + * - last_modifier + - Last modifier of the file + - Keyword + +Table: Available Field List + +"Data Type" indicates the difference in search method for each field. + +* Keyword: Searches for an exact match against the entire value. It can also be combined with wildcard search or prefix search. +* Text: Performs full-text search against tokens split by morphological analysis, etc. This applies to fields such as title and content. +* Numeric/Date: You can use :doc:`Range-Specified Search `. + +If no field is specified, the search targets the title and content fields. Depending on the configuration, you can also add fields to be searched. + +.. note:: + Depending on the crawl target, some fields may not have values registered. For example, anchor is registered only during web crawling. lang is registered from the language attribute of the HTML or from the language detected in the text of the document; it is not registered when no language can be detected or when the detected language is not in ``supported.languages``. Fields such as segment (a session ID representing the crawl execution unit) and doc_id (an internal ID assigned by the system) can also be specified, but they are not used in normal searches. + +owner and last_modifier are registered when crawling file servers and the like. owner holds the +account name of the file owner obtained by SMB, file system and FTP crawls (a value such as +``DOMAIN\alice`` becomes ``alice``). last_modifier holds the last author extracted from an Office +document or similar, and falls back to the owner. No owner is registered for HTML from a web crawl. +Search them as ``owner:alice`` or ``last_modifier:"Taro Yamada"``. In the bundled theme, the +advanced search can specify the owner and the last modifier. Administrators can turn the fields on +and off with ``crawler.document.file.owner.enabled`` and +``crawler.document.file.last.modifier.enabled`` (both ``true`` by default). + +For HTML files, the title tag is stored in the title field, and the text under the body tag is stored in the content field. + +Usage +----- + +To perform a field-specified search, enter "field_name:search_term" in the search form, separating the field name and search term with a colon (:). + +To search for fess in the title field, enter: + +:: + + title:fess + +The above search displays documents containing fess in the title field. + +To search the url field, enter: + +:: + + url:https\:\/\/fess.codelibs.org\/ja\/15.10\/* + url:"https://fess.codelibs.org/ja/15.10/*" + +The first format supports wildcard search, so you can also write it as ``url:*\/\/fess.codelibs.org\/*``. The ":" and "/" characters contained in the URL are special characters in the search query, so escape them with ``\`` (see :doc:`special-char`). The second format does not support wildcard search, but a term ending in ``*`` is treated as a prefix (leading) match search. + +.. tip:: + If you want to search using part of the URL, you can use ``inurl:`` to perform a partial match search against the URL. For example, ``inurl:15.10`` searches for documents whose URL contains ``15.10``. + +When specifying a field whose value contains "/", such as mimetype, filetype, or site, enclose it in quotes as in ``mimetype:"text/html"``, or escape it as in ``mimetype:text\/html``. + +For related search syntax, see also :doc:`Wildcard Search `, :doc:`Range-Specified Search `, :doc:`Sort Search `, and :doc:`Special Characters `. + +Related Topics +-------------- + +- :doc:`search-range` - Range-specified search +- :doc:`search-wildcard` - Wildcard search +- :doc:`special-char` - Special characters and escaping diff --git a/en/15.10/user/search-fuzzy.rst b/en/15.10/user/search-fuzzy.rst new file mode 100644 index 000000000..ba4667815 --- /dev/null +++ b/en/15.10/user/search-fuzzy.rst @@ -0,0 +1,66 @@ +============ +Fuzzy Search +============ + +Fuzzy Search (Approximate Search) +================================= + +You can use fuzzy search (approximate search) when you want to search for words that do not exactly match the search term. Fuzzy search is a method that treats a word in the index as a match if the difference (edit distance) between the search term and that word is within a certain range. Edit distance is the minimum number of character insertions, deletions, and substitutions required to transform one word into another. By default, |Fess| uses the Damerau-Levenshtein distance (optimal string alignment), which, in addition to these operations, also counts the transposition of two adjacent characters as a single difference. + +Usage +----- + +Add "~" after the search term to which you want to apply fuzzy search. + +For example, to perform a fuzzy search for the word "fess", enter it in the search form as shown below to search for documents containing words similar to "fess" (such as "fes"): + +:: + + fess~ + +By adding a number after "~", you can specify the allowed edit distance (how many characters of difference are permitted). The value can be an integer of 0, 1, or 2. + +:: + + fess~1 + +In the example above, words with an edit distance of 1 or less from "fess" are searched for. + +If you omit the number and specify only "~", the edit distance is treated as 2. The maximum edit distance is 2, and specifying a value of 3 or higher is also treated as 2. + +You can also perform a fuzzy search on a specific field. In the following example, documents containing words similar to "fess" in the title field are searched for. + +:: + + title:fess~ + +If you do not specify a field, fuzzy search is performed on the title and content fields. + +Usage Conditions +---------------- + +Please note the following points when using fuzzy search. + +* Fuzzy search is applied on a per-word basis. It cannot be applied to phrases enclosed in quotation marks. Note that a number placed after a phrase (for example, ``"Fess Search"~2``) is not a fuzzy search but a :doc:`proximity search ` that represents the distance between words. +* Fuzzy search targets words that have been registered in the index, and the search term is not re-analyzed. As a result, it may not work as expected for text such as Japanese, which is tokenized using bi-grams or morphological analysis. Fuzzy search is mainly effective for alphanumeric words. +* The search term of a fuzzy search is counted for edit distance as is, including the distinction between uppercase and lowercase. Since alphabetic words registered in the index are usually converted to lowercase, use lowercase letters in the search term. For example, ``Fess~1`` uses up its edit distance of 1 on the leading uppercase ``F`` alone, so it does not give the same results as ``fess~1``. Also, ``Fess~0`` matches nothing because the index has no word that matches the uppercase word ``Fess`` (the lowercase ``fess~0`` is an exact match). +* If you add "~" (edit distance 2) to a very short word of one or two characters, it also matches words in which only about as many characters as the length of the word have been replaced. For example, ``ab~`` matches ``xy``, in which both characters differ, in addition to ``ab`` and ``ac``. Because this increases unintended results, specify a small edit distance such as ``ab~1`` for short words. + +.. note:: + + The behavior of fuzzy search can be adjusted in ``fess_config.properties``. + + * ``query.fuzzy.prefix_length`` (default: ``0``): The number of characters from the beginning of the word that must match exactly. Increasing this value narrows the range of errors allowed. + * ``query.fuzzy.expansions`` (default: ``50``): The maximum number of words expanded as match candidates. + * ``query.fuzzy.transpositions`` (default: ``true``): Specifies whether the transposition of two adjacent characters is counted as a single edit. When ``true``, the Damerau-Levenshtein distance is used; when ``false``, the classic Levenshtein distance is used. + +.. note:: + + Even in a normal search without "~", |Fess| automatically adds a small amount of weighted fuzzy matching as an auxiliary aid, for the purpose of increasing relevance, for search terms of a certain length or longer (4 characters or more by default) (``query.boost.fuzzy.*``). This is mainly a feature for adjusting the ranking of search results and is a separate mechanism from fuzzy search using "~". However, this auxiliary matching is also included in the search results, so documents that do not contain the search term itself but contain only a word that differs by one character may be added to the results (documents containing the search term itself are ranked higher). If you want to stop this behavior, specify a negative value (for example, ``-1``) for ``query.boost.fuzzy.min.length``. + +Related Topics +-------------- + +- :doc:`search-wildcard` - Wildcard search +- :doc:`search-proximity` - Proximity search +- :doc:`special-char` - Special characters and escaping diff --git a/en/15.10/user/search-geo.rst b/en/15.10/user/search-geo.rst new file mode 100644 index 000000000..f7a90467a --- /dev/null +++ b/en/15.10/user/search-geo.rst @@ -0,0 +1,56 @@ +========================== +Geolocation-Based Search +========================== + +By attaching latitude and longitude geolocation information to each document during index generation, you can filter search results based on the distance from a specified point at search time. + +Overview +-------- + +Geolocation-based search includes in the search results only those documents that fall within a radius centered on a specified point (latitude and longitude). This filtering is applied as a filter using OpenSearch's geo_distance query, so it does not affect the score (relevance). Also, sorting by distance is not supported. + +The field that stores geolocation information must be defined as the ``geo_point`` type in the OpenSearch mapping. By default, the ``location`` field is provided as the ``geo_point`` type. However, since no built-in process is provided to populate the ``location`` field with a value, you must populate the geolocation information yourself, using data store crawling field mappings or scripts, the API for registering documents with the search engine, or similar means. + +Usage +----- + +Geolocation-based search is specified by adding the following parameters to the search request. By default, it can be used with the ``location`` field. + +.. list-table:: + :header-rows: 1 + + * - Parameter + - Description + * - ``geo..point`` + - Specify the latitude and longitude of the center point in the format ``latitude,longitude``. The value consists of two comma-separated numbers in decimal degrees (Double type). Example: ``35.681236,139.767125`` + * - ``geo..distance`` + - Specify the distance (radius) from the center point. Example: ``10km`` + +Table: Request Parameters + +For ````, specify the name of the field that stores geolocation information. Only fields registered in ``query.geo.fields`` can be specified, and by default this is ``location``. To use a different field, map it as the ``geo_point`` type, and add it to ``query.geo.fields`` in ``fess_config.properties``, separated by commas. + +For example, to search for documents within a 10km radius from latitude 35.681236 and longitude 139.767125 (near Tokyo Station), add the following parameters to the search request. + +:: + + geo.location.point=35.681236,139.767125&geo.location.distance=10km + +Distance Units +-------------- + +The value of ``geo..distance`` is interpreted as an OpenSearch distance unit. In addition to ``km`` (kilometers), you can use ``mm``, ``cm``, ``m``, ``in``, ``ft``, ``yd``, ``mi`` (miles), ``nmi`` (nautical miles), and others. If you omit the unit and specify only a number, it is treated as meters (for example, ``500`` means 500 meters). + +Specifying Multiple Conditions +------------------------------- + +* If you specify ``geo..point`` multiple times for the same field, documents that fall within the radius of any of the points are searched (OR condition). +* If you specify geolocation information for different fields, documents that satisfy all of the conditions are searched (AND condition). + +.. note:: + + Both ``geo..point`` and ``geo..distance`` must be specified. If ``distance`` is not specified, the corresponding ``point`` condition is ignored. In addition, an error occurs if the value of ``point`` is not in the ``latitude,longitude`` format (two comma-separated numbers) or cannot be interpreted as numbers. + +.. note:: + + Geolocation search works as a filter on the search term, so if the search term is empty, the search is not executed and the result is 0 documents. Specify a search term in geolocation search requests. diff --git a/en/15.10/user/search-label.rst b/en/15.10/user/search-label.rst new file mode 100644 index 000000000..774c56d24 --- /dev/null +++ b/en/15.10/user/search-label.rst @@ -0,0 +1,29 @@ +====================== +Label-Specified Search +====================== + +Label-Specified Search (Category Search) +======================================== + +By adding label information to categorize search target documents, you can perform filtered searches by specifying labels at search time. By using labels, for example, you can limit the search scope by department, site, or document type. + +By registering labels in advance in the administration screen, label-based filtering becomes available on the search screen. Available labels can be selected from a dropdown menu at search time, and multiple labels can be selected; if multiple labels are selected, documents that have any of the selected labels become the search target. If no labels are registered, the label dropdown box will not be displayed. + +.. note:: + Since permissions can be set for labels, only the labels that the searching user is authorized to access are displayed in the dropdown. In addition, the labels displayed may differ depending on the virtual host or locale (language). Therefore, even if labels are registered, they may not appear in the dropdown for some users. + +Labels are defined by specifying, as a regular expression against the URL path, which documents the label should be applied to. For information on how to register labels and their configuration items, see the :doc:`Label Management Guide <../admin/labeltype-guide>`. + +Usage +----- + +You can select label information when searching. Label information can be selected within the search options displayed by clicking the Options button. + +|image0| + +By creating an index with labels configured, you can search documents by their assigned labels. Searching without specifying a label performs a normal full search. + +Labels are assigned to documents by matching the document's URL against the paths configured for the label at crawl time, when the index is created. Therefore, if you add or change a label definition (the target paths or excluded paths), the change is not automatically applied to documents that have already been indexed. To apply the change, either crawl the target documents again, or run the "Label Updater" job registered in the scheduler to update the index. + +.. |image0| image:: ../../../resources/images/en/15.10/user/search-label-1.png +.. pdf :width: 300 px diff --git a/en/15.10/user/search-not.rst b/en/15.10/user/search-not.rst new file mode 100644 index 000000000..ceb58032d --- /dev/null +++ b/en/15.10/user/search-not.rst @@ -0,0 +1,43 @@ +============================ +NOT Search (Excluding Words) +============================ + +NOT search can be used to search for documents that do not contain a specific word. This is also called exclusion search, and it's useful when you want to reduce noise by excluding specific keywords from your search results. + +Usage +----- + +For NOT search, place NOT before the word to exclude. NOT must be in uppercase letters with spaces before and after it. + +For example, to search for documents that contain "term1" but do not contain "term2", enter the following: + +:: + + term1 NOT term2 + +.. note:: + + NOT must be written in uppercase letters. If written in lowercase as ``not``, it is not treated as an operator but is searched as an ordinary search term "not". Also, placing ``-`` directly before the word to exclude, as in ``term1 -term2``, has the same meaning as NOT. + +Using parentheses ``( )``, you can combine NOT search with other search conditions. For example, to search for documents that contain either "term1" or "term2", but do not contain "term3", enter the following: + +:: + + (term1 OR term2) NOT term3 + +You can also perform a NOT search by specifying a field. In the following example, it searches for documents that contain "term1" in the title field, but do not contain "term2" in the title field. + +:: + + title:term1 NOT title:term2 + +.. note:: + + When the ``fess-webapp-bangs`` plugin is installed, a defined bang such as ``!g`` is no longer an exclusion. It sends the search to another site. See :doc:`search-bangs`. + +Related Topics +-------------- + +- :doc:`search-and` - AND search syntax +- :doc:`search-or` - OR search syntax +- :doc:`special-char` - Special characters and escaping diff --git a/en/15.10/user/search-or.rst b/en/15.10/user/search-or.rst new file mode 100644 index 000000000..19270a62e --- /dev/null +++ b/en/15.10/user/search-or.rst @@ -0,0 +1,38 @@ +============================= +OR Search (Matching Any Word) +============================= + +Use OR search to find documents that contain any of the specified search terms. When multiple words are entered in the search input field, the default is AND search. + +Usage +----- + +To use OR search, specify OR between search terms. OR must be written in uppercase letters with spaces before and after it. + +For example, to search for documents containing either "term1" or "term2", enter the following in the search form: + +:: + + term1 OR term2 + +You can also connect three or more search terms with OR. + +:: + + term1 OR term2 OR term3 + +.. note:: + + OR must be written in uppercase letters. If written in lowercase as ``or``, it is not treated as an operator but is searched as an ordinary search term "or". ``||`` can also be used with the same meaning as OR. + +Using parentheses ``( )``, you can combine OR search with other search conditions. For example, to search for documents that contain either "term1" or "term2", and also contain "term3", enter the following: + +:: + + (term1 OR term2) term3 + +You can also perform an OR search by specifying a field. In the following example, it searches for documents that contain "term1" in the title field, or "term2" in the content field. + +:: + + title:term1 OR content:term2 diff --git a/en/15.10/user/search-proximity.rst b/en/15.10/user/search-proximity.rst new file mode 100644 index 000000000..5a1f6c4c9 --- /dev/null +++ b/en/15.10/user/search-proximity.rst @@ -0,0 +1,70 @@ +================== +Proximity Search +================== +Proximity Search (Word Distance Search) +========================================= + +Proximity search finds documents in which the words of a phrase appear close to each other, even if they are not directly adjacent. It is useful when other words may appear between the words you are looking for. + +Usage +------- + +Enclose the words in double quotation marks, and add "~" and a number after the closing quotation mark. + +For example, the following search finds documents in which "Fess" and "search" appear within a distance of 3: + +:: + + "Fess search"~3 + +The number is the maximum number of position moves allowed between the words (see "How the Distance Is Counted" below). The larger the number, the farther apart the words may be. + +You can also perform a proximity search on a specific field. In the following example, the title field is searched. + +:: + + title:"Fess search"~3 + +If you omit the number and specify only "~" (for example, ``"Fess search"~``), the phrase is searched as a normal phrase in which the words must be adjacent. A decimal number is truncated to an integer (``~2.5`` is treated as ``~2``). + +Proximity search can be combined with a boost. In the following example, the proximity search is boosted by 2 (see :doc:`search-boost`). + +:: + + "Fess search"~5^2 + +How the Distance Is Counted +----------------------------- + +* The number is the maximum number of position moves allowed between the words. It is counted in tokens produced by the analyzer of the target field, not in characters or whitespace-separated words. For English text, it is roughly the number of words between the terms. Words removed as stop words during analysis are still counted. +* The words may appear in a different order, but a reversed order requires a larger number. For example, a document containing "quick brown fox" matches ``"quick fox"~1``, but it matches ``"fox quick"`` only with ``~3`` or larger. + +:: + + "quick fox"~1 + "fox quick"~3 + +Japanese and Other CJK Text +----------------------------- + +For Japanese and other CJK text, the unit in which the distance is counted depends on the field. + +* On the general title and content fields, the distance is close to the number of characters between the words. +* On the language-specific fields, the distance is counted in morphological tokens, and removed particles are also counted. + +Because of this, separate the words with spaces and specify a generous number. + +:: + + "全文 検索"~5 + "大阪 おいしい"~10 + +A string without spaces (for example, ``"大阪おいしい"~10``) may not work as a proximity search between the words as expected, because on the general fields it is matched as one continuous string. Separate the words with spaces. The distance cannot be converted exactly into a number of characters, so start with a generous number and narrow it down while checking the results. + +Related Topics +---------------- + +- :doc:`search-fuzzy` - Fuzzy search +- :doc:`search-boost` - Boost search +- :doc:`search-field` - Field-specified search +- :doc:`special-char` - Special characters and escaping diff --git a/en/15.10/user/search-range.rst b/en/15.10/user/search-range.rst new file mode 100644 index 000000000..8e481dacb --- /dev/null +++ b/en/15.10/user/search-range.rst @@ -0,0 +1,71 @@ +====================== +Range-Specified Search +====================== + +When a field stores data that supports range specification, such as numeric values or dates and times, you can perform a range-specified search on that field. + +Usage +----- + +To perform a range-specified search, enter "field_name:[value TO value]" in the search form. Use uppercase half-width ``TO`` to separate the range. + +For example, to search for documents in the content_length field with a size ranging from 1 kilobyte to 10 kilobytes, enter the following in the search form: + +:: + + content_length:[1000 TO 10000] + +Square brackets ``[ ]`` are inclusive of the range boundaries (greater than or equal to / less than or equal to), while curly braces ``{ }`` are exclusive of the range boundaries (greater than / less than). You can also combine the two. For example, ``content_length:{1000 TO 10000]`` represents documents greater than 1000 and less than or equal to 10000. + +Setting one side to ``*`` represents an open range with only an upper or lower bound specified. ``content_length:[1000 TO *]`` represents 1000 or greater, and ``content_length:[* TO 10000]`` represents 10000 or less. + +Range-specified search is available only for fields that are registered as search targets. By default, you can perform range-specified searches on fields such as content_length, last_modified, timestamp, click_count, and favorite_count. + +Time Range Search +------------------ + +To perform a time (date and time) range-specified search, enter "last_modified:[datetime1 TO datetime2]" (datetime1 < datetime2) in the search form. Note that if datetime1 is later than datetime2, this does not result in an error; the search simply returns zero results. + +Specify the date and time in ISO 8601 format. The format is ``YYYY-MM-DDThh:mm:ss.SSSZ``, and everything from the time onward can be omitted. + +.. list-table:: + :header-rows: 1 + + * - Specification + - Example + * - Date only + - 2012-12-02 + * - Date and time (hours, minutes, seconds) + - 2012-12-02T10:45:23Z + * - Date and time (including milliseconds) + - 2012-12-02T10:45:23.235Z + +For specifying a date and time, you can use date/time arithmetic based on the current date and time. The available symbols are as follows. + +.. list-table:: + :header-rows: 1 + + * - Symbol + - Meaning + * - ``now`` + - Current date and time + * - ``y`` / ``M`` / ``w`` / ``d`` / ``h`` / ``m`` / ``s`` + - Year / Month / Week / Day / Hour / Minute / Second + * - ``+`` / ``-`` + - Addition / Subtraction + * - ``/`` + - Rounding (rounds to the unit that follows ``/``) + +When basing the value on now or a specific date and time, you can append symbols such as +, - (addition, subtraction) or / (rounding). However, when basing the value on a specific date and time instead of now, you need to insert ``||`` between the date/time and the symbol (example: ``2016-01-01||+1M/d``). + +``/`` is a symbol that rounds to the unit following ``/``. ``now-1d/d`` represents 00:00 on the previous day, one day subtracted from today's 00:00, regardless of what time it is executed today. + +Note that these date/time calculations are evaluated on the search engine (OpenSearch) side and are valid only for fields of a date/time type. + +For example, to search for documents in the last_modified field that were updated within the 30 days up to the current date and time (assumed to be February 21, 2016, 20:00), enter the following in the search form: + +:: + + last_modified:[now-30d TO now] + +If the current date and time is February 21, 2016, 20:00 (UTC), the above roughly corresponds to the range ``[2016-01-22T20:00:00Z TO 2016-02-21T20:00:00Z]``. diff --git a/en/15.10/user/search-sort.rst b/en/15.10/user/search-sort.rst new file mode 100644 index 000000000..b76dbf1e0 --- /dev/null +++ b/en/15.10/user/search-sort.rst @@ -0,0 +1,76 @@ +=========== +Sort Search +=========== + +You can sort search results by specifying fields such as search date and time. + +Sort Target Fields +------------------ + +By default, you can specify the following fields for sorting: + +.. list-table:: + :header-rows: 1 + + * - Field Name + - Description + * - created + - Crawled date and time + * - content_length + - Crawled document size + * - last_modified + - Last modified date and time of the crawled document + * - filename + - File name + * - score + - Score value + * - timestamp + - Date and time when the document was indexed + * - click_count + - Number of times the document was clicked + * - favorite_count + - Number of times the document was favorited + +Table: Sort Target Field List + + +You can also add your own fields as sort targets. To do so, specify the field names as a comma-separated list in ``query.additional.sort.fields`` in ``fess_config.properties`` (empty by default). The fields specified here are added to the standard fields listed above and become available for sorting. Note that a field to be sorted on must already be registered (indexed) in the index. + +Usage +----- + +You can select sort conditions when searching. Sort conditions can be selected in the search options dialog displayed by clicking the Options button. + +|image0| + +To sort using the search field, enter "sort:field_name" in the search form, separating sort and the field name with a colon (:). + +The following sorts documents containing fess by document size in ascending order: + +:: + + fess sort:content_length + +To sort in descending order, append ``.desc`` to the field name: + +:: + + fess sort:content_length.desc + +The suffix that can be appended to a field name is ``.asc`` (ascending) or ``.desc`` (descending); if it is omitted, ascending order is used. + +To sort by multiple fields, specify them separated by commas as follows. The field specified first takes priority, and documents that have the same value for it are then ordered by the next field: + +:: + + fess sort:content_length.desc,last_modified + +.. note:: + Specifying a field name that is not in the sort target field list, or a sort order other than ``asc`` or ``desc``, in ``sort:`` in the search terms does not cause an error. + Instead, ``sort:`` is not treated as a sort condition, and the search is run again with the symbols in the whole search term (such as ``:``) treated as ordinary characters. + The results are not sorted, and in most cases no documents are found. + + Specifying the same value in the ``sort`` parameter of the search API results in an error (400 Bad Request). + +.. |image0| image:: ../../../resources/images/en/15.10/user/search-sort-1.png +.. pdf :width: 300 px diff --git a/en/15.10/user/search-wildcard.rst b/en/15.10/user/search-wildcard.rst new file mode 100644 index 000000000..3f232255e --- /dev/null +++ b/en/15.10/user/search-wildcard.rst @@ -0,0 +1,51 @@ +================ +Wildcard Search +================ + +You can use single-character or multiple-character wildcards within search terms. ? can be specified as a single-character wildcard, and \* can be specified as a multiple-character wildcard. Wildcards apply to words. Wildcard searches on phrases are not supported. + +Usage +----- + +To use a single-character wildcard, use ? as follows: + +:: + + te?t + +In the above case, this matches any single character at the position of ?, as in text or test. + +To use a multiple-character wildcard, use \* as follows: + +:: + + test* + +In the above case, this matches zero or more arbitrary characters at the position of \*, as in test, tests, or tester. You can also use it in the middle of a search term, as shown below: + +:: + + te*t + +Furthermore, you can use a wildcard at the beginning of a search term, as shown below: + +:: + + *test + +You can also perform a wildcard search on a specific field. In the following example, documents containing a word in the title field that starts with te and ends with t are searched for. + +:: + + title:te*t + +If you do not specify a field, wildcard search is performed on the title and content fields. + +Usage Conditions +---------------- + +Please note the following points when using wildcard search. + +* Wildcards match strings (tokens) registered in the index. Since the search term is not re-analyzed, if the index was created using bi-gram or similar methods, Japanese text is treated as fixed-length strings without meaning, and wildcards in Japanese will not work as expected. When using wildcards in Japanese, use them on fields that utilize morphological analysis. +* Patterns that contain a wildcard (``*`` or ``?``) at the beginning or in the middle of the search term are case-sensitive. Since words registered in the index are usually converted to lowercase, use lowercase letters in your patterns. For example, ``Te*t``, ``Te?t`` and ``*Test`` do not match ``test``, which is registered in lowercase. On the other hand, a pattern with ``*`` only at the end (such as ``Test*``) is analyzed as a prefix match with the search term converted to lowercase, so ``Test*`` also matches ``test``. +* A search with a wildcard at the beginning (for example, ``*test``) scans all words in the index, so it may take longer to process. diff --git a/en/15.10/user/special-char.rst b/en/15.10/user/special-char.rst new file mode 100644 index 000000000..78c0db554 --- /dev/null +++ b/en/15.10/user/special-char.rst @@ -0,0 +1,89 @@ +================== +Special Characters +================== + +The following characters have a special meaning in the search query syntax, so they are treated as special characters in search terms. To use these characters as literal search characters, you need to escape them. + +:: + + + - && || ! ( ) { } [ ] ^ " ~ * ? : \ / + +These characters are used to invoke search features such as required/prohibited terms (``+`` ``-``), boolean operators (``&&`` ``||`` ``!``), grouping (``( )``), range search (``[ ]`` ``{ }``), boost search (``^``), phrase search (``"``), fuzzy search and proximity search (``~``), wildcard search (``*`` ``?``), and field search (``:``). + +For example, searching directly for a "/" or ":" in a URL or file path, or a "+" or "-" in program code, can produce unexpected search results. See below for how to escape these characters. + +List of Special Characters +--------------------------- + +.. list-table:: + :header-rows: 1 + + * - Special Character + - Meaning + - Related + * - ``+`` ``-`` + - Specifies required or prohibited terms (AND search / NOT search) + - :doc:`search-and` / :doc:`search-not` + * - ``&&`` ``||`` + - AND search / OR search + - :doc:`search-and` / :doc:`search-or` + * - ``!`` + - NOT search (exclusion search) + - :doc:`search-not` + * - ``( )`` + - Groups search conditions + - :doc:`advanced-search` + * - ``[ ]`` ``{ }`` + - Range search (``[ ]`` includes the boundary values, ``{ }`` excludes them) + - :doc:`search-range` + * - ``^`` + - Boost search (weighting) + - :doc:`search-boost` + * - ``"`` + - Phrase search (treats the enclosed text as a single phrase; can also be used instead of escaping) + - :doc:`advanced-search` + * - ``~`` + - Fuzzy search (after a word) / proximity search (after a phrase) + - :doc:`search-fuzzy` / :doc:`search-proximity` + * - ``*`` ``?`` + - Wildcard search + - :doc:`search-wildcard` + * - ``:`` + - Specifies the search field + - :doc:`search-field` + * - ``\`` + - Escape character + - (this page) + * - ``/`` + - Slash (must be escaped when it appears in a URL, etc.) + - :doc:`search-field` + + +Usage +----- + +To treat a special character as a literal search character, use one of the following methods. + +* Put ``\`` immediately before the character to escape it. The single character that follows is treated as a normal character instead of query syntax. +* Enclose the search term in ``"``. The enclosed string is treated as a phrase search, and the special characters inside it are not interpreted as query syntax. Note, however, that because it becomes a phrase search, features such as wildcard search (``*`` ``?``) are not available. + +:: + + aaa\/bbb + "aaa/bbb" + +For example, if you want to search for "C++" as a search term, escape it as follows. + +:: + + C\+\+ + "C++" + +Related Topics +--------------- + +- :doc:`search-field` - Field-specified search +- :doc:`search-wildcard` - Wildcard search +- :doc:`search-fuzzy` - Fuzzy search +- :doc:`search-proximity` - Proximity search +- :doc:`advanced-search` - Advanced search options diff --git a/es/15.10/admin/accesstoken-guide.rst b/es/15.10/admin/accesstoken-guide.rst new file mode 100644 index 000000000..49fbe9404 --- /dev/null +++ b/es/15.10/admin/accesstoken-guide.rst @@ -0,0 +1,80 @@ +==================== +Token de Acceso +==================== + +Descripción general +=================== + +La página de configuración de tokens de acceso gestiona los tokens de acceso. + +Método de gestión +================== + +Método de visualización +----------------------- + +Para abrir la página de lista de configuración de tokens de acceso que se muestra a continuación, haga clic en [Sistema > Token de acceso] en el menú izquierdo. + +|image0| + +Para editar, haga clic en el nombre de la configuración. + +Crear configuración +------------------- + +Para abrir la página de configuración de token de acceso, haga clic en el botón de nueva creación. + +|image1| + +Parámetros de configuración +---------------------------- + +Nombre +:::::: + +Especifique un nombre para describir este token de acceso. + +Permisos +:::::::: + +Configure los permisos del token de acceso. +Descríbalo en el formato "{user\ |group|\ role}nombre". +Por ejemplo, para que los usuarios que pertenecen al grupo developer vean los resultados de búsqueda, configure el permiso como "{group}developer". + +.. warning:: + + Un token de acceso con el permiso ``{role}admin-api`` (almacenado como ``Radmin-api``) puede usar todos los endpoints de la Admin API; consulte :doc:`../api/admin/api-admin-overview`. Un usuario con el rol ``admin-accesstoken`` puede emitir un token de este tipo, y un usuario con ``admin-accesstoken-view`` puede mostrar los valores de los tokens, por lo que debe tratar ambos roles como equivalentes al rol de administrador y concederlos únicamente a operadores de confianza. + +Nombre del parámetro +:::::::::::::::::::: + +Especifique el nombre del parámetro de solicitud al especificar permisos como consulta de búsqueda. + +.. warning:: + + La funcionalidad de nombre de parámetro está diseñada únicamente para su uso en entornos internos de confianza. + Cuando esta funcionalidad está habilitada, se pueden especificar permisos adicionales a través de parámetros de URL. + Sin embargo, en entornos accesibles externamente o cuando se expone como una API pública, + usuarios malintencionados pueden manipular los parámetros de URL para escalar a privilegios que no deberían tener. + + Tenga en cuenta lo siguiente: + + * Use esta funcionalidad solo cuando Fess esté integrado dentro de otra aplicación o servicio que controle completamente las solicitudes entrantes. + * No configure un nombre de parámetro cuando Fess esté expuesto a redes no confiables. + * Asegúrese de que los parámetros de URL no puedan ser manipulados por usuarios externos al usar tokens de acceso. + +Fecha de vencimiento +:::::::::::::::::::: + +Especifique la fecha de vencimiento del token de acceso. + +Eliminar configuración +---------------------- + +Haga clic en el nombre de la configuración en la página de lista y haga clic en el botón de eliminar para que aparezca una pantalla de confirmación. +Al presionar el botón de eliminar, se eliminará la configuración. + + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/accesstoken-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/accesstoken-2.png diff --git a/es/15.10/admin/backup-guide.rst b/es/15.10/admin/backup-guide.rst new file mode 100644 index 000000000..ed43f60ac --- /dev/null +++ b/es/15.10/admin/backup-guide.rst @@ -0,0 +1,114 @@ +================== +Copia de Seguridad +================== + +Descripción general +=================== + +La página de copia de seguridad le permite descargar y cargar la información de configuración de |Fess|. + +Descarga +-------- + +|Fess| mantiene la información de configuración como índice. +Para descargar, haga clic en el nombre del índice. + +|image0| + +.. note:: + + Los archivos de diccionario (sinónimos, palabras vacías, etc.) no forman parte de la copia de seguridad. + Se guardan en el directorio de diccionarios del motor de búsqueda (``FESS_DICTIONARY_PATH``), + por lo que debe copiarlos aparte si los necesita. + +fess_config.bulk +:::::::::::::::: + +fess_config.bulk contiene la información de configuración de |Fess|. + +fess_basic_config.bulk +:::::::::::::::::::::: + +fess_basic_config.bulk contiene la información de configuración de |Fess| excluyendo la información de rastreo, las URL con falla, los registros de tareas, la cola de miniaturas, las etiquetas de usuario y datos similares. + +fess_user.bulk +:::::::::::::: + +fess_user.bulk contiene información de usuarios, roles y grupos. + +system.properties +::::::::::::::::: + +system.properties contiene información de configuración general. + +fess.json +::::::::: + +fess.json contiene información de configuración del índice fess. + +doc.json +:::::::: + +doc.json contiene información de mapeo del índice fess. + +chat_log.ndjson +::::::::::::::: + +chat_log.ndjson contiene información de los registros de uso del chat con IA. + +click_log.ndjson +:::::::::::::::: + +click_log.ndjson contiene información de registros de clics. + +favorite_log.ndjson +::::::::::::::::::: + +favorite_log.ndjson contiene información de registros de favoritos. + +search_log.ndjson +::::::::::::::::: + +search_log.ndjson contiene información de registros de búsqueda. + +user_info.ndjson +:::::::::::::::: + +user_info.ndjson contiene información de usuarios de búsqueda. + +Carga +----- + +Puede cargar e importar información de configuración. +Los archivos que se pueden restaurar son los siguientes: + +- ``*.bulk`` +- ``system.properties`` +- ``fess.json`` y ``doc.json``: sustituyen los archivos de definición de índice que usa |Fess|. La configuración y el mapeo de un índice existente no se modifican en ese momento. +- ``gsa*.xml``: un archivo de configuración de Google Search Appliance. Se importa como configuración de rastreo web, configuración de rastreo de archivos y etiquetas. + +Los archivos ``*.ndjson`` (registros de búsqueda y otros registros) no se pueden cargar para restaurarlos. + +Un documento de un archivo \*.bulk que tiene ``updatedTime`` solo se escribe si el documento +almacenado no existe, no tiene ``updatedTime`` o es más antiguo. Un documento que no es más +reciente se omite y se registra con nivel INFO en ``fess.log``, de modo que una restauración no +deshace los cambios hechos después de la copia de seguridad y los trabajos programados que incluye +la versión instalada (``updatedTime`` 0) se conservan tal cual. Los documentos sin ``updatedTime`` +siempre se escriben. + +.. note:: + + La omisión se registra con nivel INFO, por lo que con el nivel de registro predeterminado (``warn``) no se escribe en ``fess.log``. Para ver estas entradas, cambie el nivel de registro a ``info`` antes de la restauración. Puede cambiarlo en "Nivel de Registro" de [Sistema > General] en la pantalla de administración (vuelve al valor configurado al reiniciar |Fess|) o, en Linux, con ``FESS_LOG_LEVEL=info``. Consulte :doc:`../config/admin-logging` para más detalles. + +.. note:: + + |Fess| 15.10 guarda el ``password`` de la autenticación web y de archivos cifrado con la clave de cifrado de la + aplicación (``app.cipher.key`` de ``fess_config.properties``), por lo que ``fess_basic_config.bulk`` y + ``fess_config.bulk`` contienen los valores cifrados. Al restaurar una copia de seguridad en otra instalación, + traslade la misma ``app.cipher.key``. Con una clave distinta, los rastreos que usan estas credenciales fallan con un + error. Una copia de seguridad creada antes de 15.10 las contiene en texto sin cifrar y sigue funcionando. + + Los demás valores de un archivo ``*.bulk`` no están cifrados, así que conserve estos archivos como archivos + confidenciales. + + .. |image0| image:: ../../../resources/images/en/15.10/admin/backup-1.png diff --git a/es/15.10/admin/badword-guide.rst b/es/15.10/admin/badword-guide.rst new file mode 100644 index 000000000..137a2d914 --- /dev/null +++ b/es/15.10/admin/badword-guide.rst @@ -0,0 +1,85 @@ +================== +Palabra no deseada +================== + +Descripción general +=================== + +Aquí se explica la configuración de palabras excluidas de sugerencias. +Las sugerencias se muestran según el término de búsqueda, pero puede configurar para que esas palabras no se muestren en las sugerencias. + + +Método de gestión +================== + +Método de visualización +----------------------- + +Para abrir la página de lista de configuración de palabras excluidas de sugerencias que se muestra a continuación, haga clic en [Sugerir > Palabra no deseada] en el menú izquierdo. + +|image0| + +Para editar, haga clic en el nombre de la configuración. + +Crear configuración +------------------- + +Para abrir la página de creación de palabra excluida de sugerencia, haga clic en el botón de nueva creación. + +|image1| + +Parámetros de configuración +---------------------------- + +Palabra no deseada +::::::::::::::::::: + +Registre palabras prohibidas. +Las palabras registradas aquí no se mostrarán en las sugerencias. + +Eliminar configuración +---------------------- + +Haga clic en el nombre de la configuración en la página de lista y haga clic en el botón de eliminar para que aparezca una pantalla de confirmación. +Al presionar el botón de eliminar, se eliminará la configuración. + +Descarga +======== + +Descarga las palabras registradas en formato CSV. + +|image2| + +Contenido del CSV +----------------- + +La primera línea es el encabezado. +Desde la segunda línea en adelante se describen las palabras excluidas. + +:: + +"BadWord" +"検索エンジン" + +Carga +===== + +Registra palabras en formato CSV. + +|image3| + +Contenido del CSV +----------------- + +La primera línea es el encabezado. +Desde la segunda línea en adelante se describen las palabras excluidas. + +:: + +"BadWord" +"検索エンジン" + +.. |image0| image:: ../../../resources/images/en/15.10/admin/badword-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/badword-2.png +.. |image2| image:: ../../../resources/images/en/15.10/admin/badword-3.png +.. |image3| image:: ../../../resources/images/en/15.10/admin/badword-4.png diff --git a/es/15.10/admin/boostdoc-guide.rst b/es/15.10/admin/boostdoc-guide.rst new file mode 100644 index 000000000..fc4ece209 --- /dev/null +++ b/es/15.10/admin/boostdoc-guide.rst @@ -0,0 +1,83 @@ +======================= +Impulso de Documento +======================= + +Descripción general +=================== + +Aquí se explica la configuración relacionada con el impulso de documento. +Al configurar el impulso de documento, puede posicionar documentos en la parte superior de los resultados de búsqueda independientemente del término de búsqueda. + +Método de gestión +================== + +Método de visualización +----------------------- + +Para abrir la página de lista de configuración de impulso de documento que se muestra a continuación, haga clic en [Rastreador > Impulso de documento] en el menú izquierdo. + +|image0| + +Para editar, haga clic en el nombre de la configuración. + +Crear configuración +------------------- + +Para abrir la página de configuración de impulso de documento, haga clic en el botón de nueva creación. + +|image1| + +Parámetros de configuración +---------------------------- + +Condición +::::::::: + +Especifique la condición de los documentos que desea posicionar en la parte superior. +Por ejemplo, si desea mostrar en la parte superior las URL que contienen https://www.n2sm.net/, describa url.matches("https://www.n2sm.net/.\*"). +Las condiciones se escriben en la sintaxis del motor de scripting especificado en «Tipo de Script» a continuación. + +Expresión de impulso +:::::::::::::::::::: + +Especifique el valor de ponderación del documento. +Las expresiones se escriben en la sintaxis del motor de scripting especificado en «Tipo de Script» a continuación. + +Tipo de Script +:::::::::::::: + +Especifique el motor de scripting utilizado para evaluar la condición y la expresión de impulso. +Las configuraciones nuevas se rellenan con ``javascript``. Para seleccionar ``groovy`` se requiere +el plugin ``fess-script-groovy``. Si se deja en blanco, las expresiones se evalúan como Groovy. + +.. warning:: + + Con JavaScript, escriba la condición y la expresión de impulso como expresiones puras sin + punto y coma final. Un texto que solo puede analizarse como bloque de sentencias se evalúa + como ``null`` salvo que contenga un ``return`` explícito. Consulte + :ref:`javascript-statement-null` (en :doc:`../config/scripting-javascript`). + +Orden de clasificación +::::::::::::::::::::::: + +Configure el orden de clasificación del impulso de documento. + +Cuándo se aplican las reglas +---------------------------- + +Las reglas de impulso de documentos se evalúan cuando un rastreo web o un rastreo de archivos registra un documento en el índice. No se aplican a los rastreos de almacenes de datos. +Agregar, cambiar o eliminar una regla no modifica el impulso de los documentos que ya están en el índice. + +Si "Comprobar fecha de última modificación" en [Sistema > General] está habilitado (valor predeterminado), un documento cuyo contenido no ha cambiado no se vuelve a registrar en el índice en un nuevo rastreo, por lo que su impulso no se vuelve a evaluar. +Para aplicar una regla nueva o modificada a los documentos existentes, elimínelos del índice (consulte :doc:`searchlist-guide`) y vuelva a rastrear. +Un documento que se registra de nuevo, por ejemplo porque su contenido ha cambiado, se evalúa en ese momento. +Si "Comprobar fecha de última modificación" está deshabilitado, todos los documentos se vuelven a registrar en cada rastreo, por lo que las reglas se evalúan cada vez. + +Eliminar configuración +---------------------- + +Haga clic en el nombre de la configuración en la página de lista y haga clic en el botón de eliminar para que aparezca una pantalla de confirmación. Al presionar el botón de eliminar, se eliminará la configuración. + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/boostdoc-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/boostdoc-2.png diff --git a/es/15.10/admin/crawlinginfo-guide.rst b/es/15.10/admin/crawlinginfo-guide.rst new file mode 100644 index 000000000..bca066ed3 --- /dev/null +++ b/es/15.10/admin/crawlinginfo-guide.rst @@ -0,0 +1,93 @@ +======================= +Información de Rastreo +======================= + +Descripción general +=================== + +Los resultados de ejecución del rastreo se registran y la información de rastreo se puede verificar en esta pantalla de administración. + +Método de gestión +================== + +Lista +===== + +Cada vez que se ejecuta un rastreo, se registra como información de rastreo. +En la lista puede verificar el nombre de sesión del rastreo ejecutado y la hora de ejecución. +Si desea verificar los detalles de la información de rastreo, haga clic en la información de rastreo objetivo. + +|image0| + +Detalles +======== + +Al hacer clic en el ID de sesión de la información de rastreo en la lista, se muestran los detalles de la información de rastreo objetivo. + +|image1| + +Lista de elementos +------------------ + +ID de sesión +:::::::::::: + +ID de sesión en el momento de la ejecución del rastreo. + +Hora de inicio del rastreador +:::::::::::::::::::::::::::::: + +Hora en la que comenzó todo el rastreo. + +Hora de inicio del rastreo (Web/Archivo) +::::::::::::::::::::::::::::::::::::::::: + +Hora en la que comenzó el rastreo web y del sistema de archivos. + +Hora de inicio del rastreo (Almacén de datos) +:::::::::::::::::::::::::::::::::::::::::::::: + +Hora en la que comenzó el rastreo del almacén de datos. + +Hora de finalización del rastreo (Web/Archivo) +::::::::::::::::::::::::::::::::::::::::::::::: + +Hora en la que finalizó el rastreo web y del sistema de archivos. + +Tiempo de ejecución del rastreo (Almacén de datos) +::::::::::::::::::::::::::::::::::::::::::::::::::: + +Tiempo de ejecución del rastreo del almacén de datos (milisegundos). + +Tiempo de ejecución de indexación (Almacén de datos) +::::::::::::::::::::::::::::::::::::::::::::::::::::: + +Tiempo que se tardó en indexar los resultados del rastreo web y del sistema de archivos (milisegundos). + +Tamaño del índice (Almacén de datos) +::::::::::::::::::::::::::::::::::::: + +Número de documentos indexados. + +Hora de finalización del rastreo (Almacén de datos) +:::::::::::::::::::::::::::::::::::::::::::::::::::: + +Hora en la que finalizó el rastreo del almacén de datos. + +Estado del rastreador +::::::::::::::::::::: + +Si el rastreo tuvo éxito o no. + +Hora de finalización del rastreador +:::::::::::::::::::::::::::::::::::: + +Hora en la que finalizó todo el rastreo. + +Tiempo de ejecución del rastreador +::::::::::::::::::::::::::::::::::: + +Tiempo de ejecución de todo el rastreo (milisegundos). + +.. |image0| image:: ../../../resources/images/en/15.10/admin/crawlinginfo-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/crawlinginfo-2.png diff --git a/es/15.10/admin/dashboard-guide.rst b/es/15.10/admin/dashboard-guide.rst new file mode 100644 index 000000000..c8ba106e4 --- /dev/null +++ b/es/15.10/admin/dashboard-guide.rst @@ -0,0 +1,58 @@ +================== +Panel de Control +================== + +Descripción general +=================== + +El panel de control proporciona una herramienta de administración web para gestionar el clúster e índices de OpenSearch a los que accede |Fess|. + +|image0| + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: Índices gestionados por |Fess| + :header-rows: 1 + + * - Nombre del índice + - Descripción + * - fess.yyyyMMddHHmmssSSS + - Documentos indexados + * - fess_log + - Registro de accesos + * - fess.suggest.yyyyMMddHHmmssSSS + - Palabras de sugerencia + * - fess_config + - Configuración de |Fess| + * - fess_user + - Datos de usuarios/roles/grupos + * - configsync + - Configuración de diccionarios + * - fess_suggest + - Metadatos de sugerencias + * - fess_suggest_array + - Metadatos de sugerencias + * - fess_suggest_badword + - Lista de palabras prohibidas en sugerencias + * - fess_suggest_analyzer + - Metadatos de sugerencias + * - fess_crawler + - Información de rastreo + +La parte que sigue a ``fess.`` y ``fess.suggest.`` es la fecha y hora de creación del índice (17 dígitos, ``yyyyMMddHHmmssSSS``). + +Los nombres de índices que comienzan con un punto (.) son índices del sistema y no se muestran. +Para mostrar también los índices del sistema, active la casilla de verificación "Special". + +Verificar el número de documentos indexados +============================================ + +El número de documentos indexados se muestra en el índice fess, como se muestra en la figura siguiente. + +|image1| + +Al hacer clic en el icono de la esquina superior derecha de cada índice, se muestra un menú de operaciones para el índice. +Si desea eliminar documentos indexados, elimínelos desde la pantalla de búsqueda administrativa. Tenga cuidado de no eliminarlos con "eliminar el índice". + +.. |image0| image:: ../../../resources/images/en/15.10/admin/dashboard-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/dashboard-2.png +.. pdf :width: 400 px diff --git a/es/15.10/admin/dataconfig-guide.rst b/es/15.10/admin/dataconfig-guide.rst new file mode 100644 index 000000000..261328e20 --- /dev/null +++ b/es/15.10/admin/dataconfig-guide.rst @@ -0,0 +1,407 @@ +=========================== +Rastreo de Almacén de Datos +=========================== + +Descripción general +=================== + +El rastreo del almacén de datos registra diversas fuentes de datos distintas de sitios web o archivos, como bases de datos relacionales (MySQL, PostgreSQL, Oracle) y archivos CSV, en el índice de |Fess| para la búsqueda de texto completo. Las fuentes de datos admitidas se pueden ampliar mediante complementos conectores de almacén de datos. + +|Fess| puede rastrear fuentes de datos como bases de datos y CSV. +Aquí se explica la configuración del almacén de datos necesaria para ello. + +Método de gestión +================== + +Método de visualización +----------------------- + +Para abrir la página de lista para configurar el almacén de datos que se muestra a continuación, haga clic en [Rastreador > Almacén de datos] en el menú izquierdo. + +|image0| + +Para editar, haga clic en el nombre de la configuración. + +Crear configuración +------------------- + +Para abrir la página de configuración del almacén de datos, haga clic en el botón de nueva creación. + +|image1| + +Parámetros de configuración +---------------------------- + +Nombre +:::::: + +Especifique el nombre de la configuración de rastreo. + +Nombre del manejador +:::::::::::::::::::: + +Es el nombre del manejador que procesa el almacén de datos. + +* DatabaseDataStore: Rastrea bases de datos +* CsvDataStore: Rastrea archivos CSV/TSV +* CsvListDataStore: Rastrea archivos CSV que describen rutas de archivos a indexar + +La lista desplegable del nombre del manejador solo muestra los manejadores proporcionados por los complementos conectores de almacén de datos instalados (``fess-ds-*``). +Si no hay ningún complemento instalado, no hay ningún manejador que seleccionar. +Para otros manejadores, consulte las páginas de conectores que se enumeran en :doc:`../config/datastore/ds-overview`. +Tenga en cuenta que ``EsDataStore`` (el complemento ``fess-ds-elasticsearch``), descrito en la documentación de versiones anteriores, no se publica desde la versión 15.6.0 y no está disponible en la 15.10. + +.. note:: + + ``DatabaseDataStore`` es proporcionado por el complemento conector de base de datos ( ``fess-ds-db`` ), y ``CsvDataStore`` / ``CsvListDataStore`` son proporcionados por el complemento conector de CSV ( ``fess-ds-csv`` ). Para ver la lista completa de conectores disponibles, consulte :doc:`../config/datastore/ds-overview`. + +Parámetros +:::::::::: + +Especifique los parámetros relacionados con el almacén de datos. + +El parámetro ``script_type`` selecciona el motor de scripting utilizado para evaluar +el campo Script descrito a continuación. Las configuraciones nuevas se rellenan con +``script_type=javascript``. Si no se especifica ``script_type``, el script se evalúa como Groovy. + +Script +:::::: + +Especifique en qué campos configurar los valores obtenidos del almacén de datos, etc. +Las expresiones se escriben en la sintaxis del motor de scripting seleccionado mediante +``script_type`` (JavaScript de forma predeterminada). + +.. warning:: + + Con JavaScript, escriba cada línea como una expresión pura sin punto y coma final. Una línea + que solo puede analizarse como bloque de sentencias —cualquiera con punto y coma final, o una + declaración ``let`` / ``const``— se evalúa como ``null`` salvo que contenga un ``return`` + explícito, y un mapeo que se evalúa como ``null`` simplemente no establece ese campo. No hay + ningún error ni ninguna línea de registro; el único síntoma es un campo que se queda vacío en + silencio. Consulte :ref:`javascript-statement-null` + (en :doc:`../config/scripting-javascript`). + +Valor de impulso +:::::::::::::::: + +Especifique el valor de impulso de los documentos al rastrear con esta configuración. + +Permisos +:::::::: + +Especifique el permiso para esta configuración. +La forma de especificar permisos es, por ejemplo, para mostrar resultados de búsqueda a usuarios que pertenecen al grupo developer, especifique {group}developer. +La especificación por usuario es {user}nombre_usuario, la especificación por rol es {role}nombre_rol, y la especificación por grupo es {group}nombre_grupo. + +Host virtual +:::::::::::: + +Especifique el nombre de host del host virtual. +Para más detalles, consulte :doc:`Host virtual en la guía de configuración <../config/security-virtual-host>`. + +Estado +:::::: + +Especifique si desea utilizar esta configuración de rastreo. + +Descripción +::::::::::: + +Puede ingresar una descripción. + +Eliminar configuración +---------------------- + +Haga clic en el nombre de la configuración en la página de lista y haga clic en el botón de eliminar para que aparezca una pantalla de confirmación. +Al presionar el botón de eliminar, se eliminará la configuración. + +Ejemplo +======= + +DatabaseDataStore +----------------- + +Se explicará el rastreo de bases de datos. + +Como ejemplo, se explicará asumiendo que existe la siguiente tabla en una base de datos llamada testdb en MySQL, y que se puede conectar con el nombre de usuario hoge y la contraseña fuga. + +:: + + CREATE TABLE doc ( + id BIGINT NOT NULL AUTO_INCREMENT, + title VARCHAR(100) NOT NULL, + content VARCHAR(255) NOT NULL, + latitude VARCHAR(20), + longitude VARCHAR(20), + versionNo INTEGER NOT NULL, + PRIMARY KEY (id) + ); + +Aquí, se insertarán los siguientes datos. + +:: + + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 1', 'コンテンツ 1 です．', '37.77493', ' -122.419416', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 2', 'コンテンツ 2 です．', '34.701909', '135.494977', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 3', 'コンテンツ 3 です．', '-33.868901', '151.207091', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 4', 'コンテンツ 4 です．', '51.500152', '-0.113736', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 5', 'コンテンツ 5 です．', '35.681137', '139.766084', 1); + +Parámetros +:::::::::: + +Un ejemplo de configuración de parámetros sería el siguiente. + +:: + + driver=com.mysql.jdbc.Driver + url=jdbc:mysql://localhost:3306/testdb?useUnicode=true&characterEncoding=UTF-8 + username=hoge + password=fuga + sql=select * from doc + +Los parámetros están en formato "clave=valor". La descripción de las claves es la siguiente. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - driver + - Nombre de la clase del controlador + * - url + - URL + * - username + - Nombre de usuario para conectarse a la BD + * - password + - Contraseña para conectarse a la BD + * - sql + - Sentencia SQL para obtener el objeto del rastreo + +Tabla: Ejemplo de parámetros de configuración de BD + + +Script +:::::: + +Un ejemplo de configuración de script sería el siguiente. + +:: + + url="http://SERVERNAME/" + id + host="SERVERNAME" + site="SERVERNAME" + title=title + content=content + cache=content + digest=content + anchor= + content_length=content.length() + last_modified=new java.util.Date() + location=latitude + "," + longitude + latitude=latitude + longitude=longitude + +Los parámetros están en formato "clave=valor". La descripción de las claves es la siguiente. + +En el lado del valor, se describe en la sintaxis del motor de scripting seleccionado mediante ``script_type``. +Las cadenas deben encerrarse entre comillas dobles. Si accede por nombre de columna de la base de datos, será ese valor. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - url + - URL (Configure una URL que pueda acceder a los datos según su entorno) + * - host + - Nombre de host + * - site + - Ruta del sitio + * - title + - Título + * - content + - Contenido del documento (cadena objeto de indexación) + * - cache + - Caché del documento (no es objeto de indexación) + * - digest + - Parte del resumen que se muestra en los resultados de búsqueda + * - anchor + - Enlaces contenidos en el documento (normalmente no es necesario especificarlo) + * - content_length + - Longitud del documento + * - last_modified + - Fecha de última actualización del documento + +Tabla: Contenido de configuración del script + + +Controlador +::::::::::: + +Se necesita un controlador para conectarse a la base de datos. Coloque el archivo jar en app/WEB-INF/lib. + +CsvDataStore +------------ + +Se explicará el rastreo de archivos CSV. + +Por ejemplo, genere el archivo test.csv en el directorio /home/taro/csv con el siguiente contenido. +La codificación del archivo debe ser Shift_JIS. + +:: + + 1,タイトル 1,テスト1です。 + 2,タイトル 2,テスト2です。 + 3,タイトル 3,テスト3です。 + 4,タイトル 4,テスト4です。 + 5,タイトル 5,テスト5です。 + 6,タイトル 6,テスト6です。 + 7,タイトル 7,テスト7です。 + 8,タイトル 8,テスト8です。 + 9,タイトル 9,テスト9です。 + + +Parámetros +:::::::::: + +Un ejemplo de configuración de parámetros sería el siguiente. + +:: + + directories=/home/taro/csv + fileEncoding=Shift_JIS + +Los parámetros están en formato "clave=valor". La descripción de las claves es la siguiente. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - directories + - Directorio que contiene archivos CSV (.csv o .tsv) + * - files + - Archivo CSV (si se especifica directamente) + * - fileEncoding + - Codificación del archivo CSV + * - separatorCharacter + - Carácter separador + + +Tabla: Ejemplo de parámetros de configuración de archivo CSV + + +Script +:::::: + +Un ejemplo de configuración de script sería el siguiente. + +:: + + url="http://SERVERNAME/" + cell1 + host="SERVERNAME" + site="SERVERNAME" + title=cell2 + content=cell3 + cache=cell3 + digest=cell3 + anchor= + content_length=cell3.length() + last_modified=new java.util.Date() + +Los parámetros están en formato "clave=valor". +Las claves son las mismas que en el caso del rastreo de bases de datos. +Los datos dentro del archivo CSV se mantienen en cell[número] (el número comienza desde 1). +Si no hay datos en una celda del archivo CSV, puede ser nulo. + +CsvListDataStore +---------------- + +Se utiliza al rastrear una gran cantidad de archivos. +Al colocar un archivo CSV que describe las rutas de los archivos actualizados y rastrear solo las rutas especificadas, puede acortar el tiempo de ejecución del rastreo. + +El formato para describir las rutas es el siguiente. + +:: + + [acción][ruta] + +Especifique una de las siguientes acciones: + +* create: Se creó el archivo +* modify: Se actualizó el archivo +* delete: Se eliminó el archivo + +Por ejemplo, genere el archivo test.csv en el directorio /home/taro/csv con el siguiente contenido. +La codificación del archivo debe ser Shift_JIS. + +Describa las rutas con la misma notación que cuando especifica rutas objetivo de rastreo en el rastreo de archivos. +Especifique como "file:/[ruta]" o "smb://[ruta]" de la siguiente manera. + +:: + + modify,smb://servername/data/testfile1.txt + modify,smb://servername/data/testfile2.txt + modify,smb://servername/data/testfile3.txt + modify,smb://servername/data/testfile4.txt + modify,smb://servername/data/testfile5.txt + modify,smb://servername/data/testfile6.txt + modify,smb://servername/data/testfile7.txt + modify,smb://servername/data/testfile8.txt + modify,smb://servername/data/testfile9.txt + modify,smb://servername/data/testfile10.txt + + +Parámetros +:::::::::: + +Un ejemplo de configuración de parámetros sería el siguiente. + +:: + + directories=/home/taro/csv + fileEncoding=Shift_JIS + +Los parámetros están en formato "clave=valor". La descripción de las claves es la siguiente. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - directories + - Directorio que contiene archivos CSV (.csv o .tsv) + * - fileEncoding + - Codificación del archivo CSV + * - separatorCharacter + - Carácter separador + + +Tabla: Ejemplo de parámetros de configuración de archivo CSV + + +Script +:::::: + +Un ejemplo de configuración de script sería el siguiente. + +:: + + event_type=cell1 + url=cell2 + +Los parámetros están en formato "clave=valor". +Las claves son las mismas que en el caso del rastreo de bases de datos. + +Si se requiere autenticación en el destino del rastreo, también es necesario configurar lo siguiente. + +:: + + crawler.file.auth=example + crawler.file.auth.example.scheme=SAMBA + crawler.file.auth.example.username=username + crawler.file.auth.example.password=password + +Páginas Relacionadas +==================== + +- :doc:`../config/datastore/index` +- :doc:`../config/datastore/ds-database` +- :doc:`../config/datastore/ds-overview` +- :doc:`../config/crawler-basic` + +.. |image0| image:: ../../../resources/images/en/15.10/admin/dataconfig-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/dataconfig-2.png diff --git a/es/15.10/admin/dict-guide.rst b/es/15.10/admin/dict-guide.rst new file mode 100644 index 000000000..eeb871622 --- /dev/null +++ b/es/15.10/admin/dict-guide.rst @@ -0,0 +1,170 @@ +============ +Diccionario +============ + +Descripción general +=================== + +Aquí se explica la configuración relacionada con los diccionarios. + +Realice cambios en los diccionarios después de comprender las especificaciones de cada diccionario. +Si la modificación del diccionario falla, es posible que no se pueda acceder al índice. + +.. note:: + + Si ``search_engine.type`` es ``vanilla`` o ``aws`` (es decir, si OpenSearch no tiene los plugins de CodeLibs), la gestión de diccionarios no está disponible. Consulte :doc:`../config/search-engine-type`. + +Lista +===== + +Para abrir la página de lista de diccionarios administrables que se muestra a continuación, haga clic en [Sistema > Diccionario] en el menú izquierdo. + + +|image0| + + +Alcance de cada diccionario y cuándo surte efecto +================================================= + +Cada diccionario se aplica a campos distintos y surte efecto en un momento +distinto. Si ha editado un diccionario y los resultados de búsqueda no cambian, +consulte primero esta tabla. + +.. list-table:: + :header-rows: 1 + :widths: 22 26 28 24 + + * - Diccionario + - Archivo + - Campos a los que se aplica + - Cuándo surte efecto + * - Kuromoji + - ``ja/kuromoji.txt`` + - Solo los campos ``_ja``, como ``content_ja`` + - Al indexar (es necesario volver a rastrear) + * - Sinónimos + - ``synonym.txt`` + - ``content`` y ``title`` + - Al buscar (no es necesario volver a rastrear) + * - Mapeo (común a todos los idiomas) + - ``mapping.txt`` + - ``content`` y ``title`` + - Al indexar (es necesario volver a rastrear) + * - Mapeo (por idioma) + - ``ja/mapping.txt`` + - Solo los campos ``_ja``, como ``content_ja`` + - Al indexar (es necesario volver a rastrear) + * - Protwords + - ``en/protwords.txt`` + - ``content`` y ``title`` + - Al indexar y al buscar + * - Palabras vacías + - ``en/stopwords.txt`` + - ``content`` y ``title`` + - Al indexar y al buscar + * - Sobrescritura de stemmer + - ``en/stemmer_override.txt`` + - ``content`` y ``title`` + - Al indexar y al buscar + +.. note:: + + Un analizador se construye cuando se abre el índice, de modo que actualizar + un archivo de diccionario no surte efecto **hasta que el índice se cierra y + se vuelve a abrir**. Además, un diccionario que se aplica al indexar no se + aplica de forma retroactiva a los documentos ya indexados: esos documentos + deben rastrearse de nuevo. + Consulte :ref:`dict-apply-changes` para saber cómo aplicar un cambio. + +.. warning:: + + El diccionario de sustitución de caracteres que se aplica a ``content``, el + campo con el que se responde la mayoría de las búsquedas, es el + ``mapping.txt`` de la **raíz**, no ``ja/mapping.txt``. Comparten el nombre + Mapeo, pero son archivos distintos. + +.. _dict-apply-changes: + +Aplicar los cambios de diccionario +---------------------------------- + +Guardar un diccionario no cambia los resultados de búsqueda, por mucho que espere. El plugin +configsync de OpenSearch escribe los diccionarios guardados en sus archivos aproximadamente una vez +por minuto, pero un analizador lee sus diccionarios solo cuando se abre el índice, de modo que un +índice que ya está abierto sigue usando los anteriores. Después de editar diccionarios, recargue el +índice de documentos: + +1. Abra [Información del sistema > Mantenimiento] en el menú izquierdo. +2. Haga clic en [Recargar] en «Recargar índice de documentos». + +El botón escribe primero los diccionarios guardados en sus archivos y después cierra y vuelve a +abrir el índice al que apunta el alias ``fess.update``, por lo que no es necesario esperar a la +escritura periódica. Un diccionario que se aplica al buscar, como un sinónimo, surte efecto en +cuanto el índice vuelve a estar abierto. Para un diccionario que se aplica al indexar, rastree +además de nuevo los documentos afectados. + +.. warning:: + + Mientras el índice está cerrado, y hasta que sus fragmentos se vuelven a asignar después de + abrirlo, no se puede buscar en el índice: las búsquedas fallan o no devuelven resultados. + Cuanto mayor es el índice, más tarda, así que recárguelo en un momento de poca actividad. + +Para hacer lo mismo desde un script sin la pantalla de administración, envíe las mismas operaciones +a OpenSearch:: + + curl -X POST "localhost:9200/_configsync/flush" + curl -X POST "localhost:9200/fess.update/_close" + curl -X POST "localhost:9200/fess.update/_open" + +``_configsync/flush`` escribe de inmediato los diccionarios guardados en sus archivos. Sin esta +llamada, espere al menos un minuto después de guardar antes de cerrar el índice. + +El diccionario de usuario de Kuromoji y los resultados de búsqueda +------------------------------------------------------------------- + +El campo ``content`` se analiza con el tokenizador estándar y ``cjk_bigram``, +por lo que no depende de cómo Kuromoji segmente una palabra. Registrar una +palabra compuesta japonesa en el diccionario de usuario de Kuromoji y volver a +rastrear no cambia, por tanto, lo que devuelve una búsqueda contra ``content``. +El registro se refleja en ``content_ja``, que se añade a la consulta según el +idioma de la petición. + +Kuromoji +======== + +Administra el diccionario para el análisis morfológico del japonés. +ja/kuromoji.txt es el archivo de diccionario para el análisis morfológico del japonés. + +Sinónimos +========= + +Administra el diccionario de sinónimos. +synonym.txt es el archivo de diccionario de sinónimos utilizado comúnmente en todos los idiomas. + +Mapeo +===== + +Administra el diccionario de sustitución de caracteres. +mapping.txt es el archivo de diccionario de sustitución de palabras común a todos los idiomas o para cada idioma. + +Protwords +========= + +Administra el diccionario de palabras protegidas. +protwords.txt se coloca para cada idioma y es un archivo de lista de palabras que se excluirán del stemming, etc. + +Palabras vacías +=============== + +Administra el diccionario de palabras vacías. +stopwords.txt se coloca para cada idioma y es un archivo de lista de palabras que se excluirán al crear el índice. + +Anulación de Stemmer +==================== + +Administra el diccionario de anulación de Stemmer. +stemmer_override.txt se coloca para cada idioma y es un archivo de diccionario de sustitución de palabras para anular el procesamiento de stemming. + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/dict-1.png + :height: 940px diff --git a/es/15.10/admin/docreport-guide.rst b/es/15.10/admin/docreport-guide.rst new file mode 100644 index 000000000..59cdff65f --- /dev/null +++ b/es/15.10/admin/docreport-guide.rst @@ -0,0 +1,71 @@ +===================== +Informe de documentos +===================== + +Descripción general +=================== + +La página Informe de documentos ayuda a ordenar servidores de archivos rastreados y similares. Muestra +los documentos con el mismo contenido y los que llevan mucho tiempo sin modificarse, y cada lista se +puede descargar como CSV. + +Para abrir la página, seleccione [Información del sistema > Informe de documentos] en el menú +izquierdo. Para verla se necesita el rol ``admin-docreport`` o ``admin-docreport-view``. La página +solo muestra y descarga informes; no modifica ningún documento. + +Ambas pestañas se pueden acotar con "Prefijo de URL", por ejemplo ``smb://server/share/``. + +Duplicados +========== + +Los documentos con el mismo contenido, o casi el mismo, se agrupan, empezando por el grupo más +grande. Los grupos usan la firma de contenido calculada al indexar (``content_minhash_bits``, la +misma que agrupa los resultados de búsqueda duplicados), por lo que no hace falta reindexar. Se +excluyen los documentos cuyo contenido no tiene palabras (como los archivos vacíos). + +La pantalla muestra hasta ``docreport.duplicate.group.size`` (predeterminado: 100) grupos y hasta +``docreport.duplicate.docs.size`` (predeterminado: 10) documentos por grupo. Use [Descargar CSV] para +obtener todos los grupos. El CSV lee todos los grupos, incluso en un índice grande, con las columnas +``group, groupSize, url, title, filename, contentLength, lastModified, owner, lastModifier, clickCount, docId``. + +.. note:: + + El informe de duplicados necesita la firma de contenido, que las definiciones de índice para un OpenSearch sin los plugins de CodeLibs (``search_engine.type`` con ``vanilla``, ``aws`` o el obsoleto ``cloud``) no calculan. Con estos tipos se oculta la pestaña «Duplicados» y solo está disponible el informe de documentos inactivos. Consulte :doc:`../config/search-engine-type`. + +Documentos inactivos +==================== + +Se muestran, del más antiguo al más reciente, los documentos cuya última modificación es anterior al +número de días indicado ("Sin modificar durante (días)", 365 de forma predeterminada según +``docreport.dormant.days``). Los documentos sin fecha de última modificación no se muestran. Con +"Nunca abiertos desde los resultados de búsqueda" se excluyen los documentos en los que se ha hecho +clic desde los resultados de búsqueda. + +La pantalla muestra el número de documentos coincidentes, su tamaño total y una lista paginada. La +paginación se detiene en ``indexer.max.result.window.size``; use [Descargar CSV] para obtener los +documentos que quedan más allá. + +Configuración +============= + +Los siguientes ajustes de ``fess_config.properties`` ajustan el informe. + +.. list-table:: + :header-rows: 1 + :widths: 40 45 15 + + * - Propiedad + - Descripción + - Predeterminado + * - ``docreport.duplicate.group.size`` + - Número máximo de grupos de duplicados que muestra la pantalla + - ``100`` + * - ``docreport.duplicate.docs.size`` + - Número máximo de documentos que la pantalla muestra por grupo + - ``10`` + * - ``docreport.duplicate.export.page.size`` + - Número de firmas de contenido leídas por solicitud al descargar el CSV + - ``10000`` + * - ``docreport.dormant.days`` + - Número predeterminado de días desde la última modificación a partir del cual un documento está inactivo + - ``365`` diff --git a/es/15.10/admin/duplicatehost-guide.rst b/es/15.10/admin/duplicatehost-guide.rst new file mode 100644 index 000000000..4e4d1cd2c --- /dev/null +++ b/es/15.10/admin/duplicatehost-guide.rst @@ -0,0 +1,59 @@ +================== +Host Duplicado +================== + +Descripción general +=================== + +Aquí se explica la configuración relacionada con los hosts duplicados. +Los hosts duplicados se utilizan cuando desea tratar diferentes nombres de host como iguales durante el rastreo. +Por ejemplo, se puede utilizar cuando desea tratar www.example.com y example.com como el mismo sitio. + +Método de gestión +================== + +Método de visualización +----------------------- + +Para abrir la página de lista para configurar hosts duplicados que se muestra a continuación, haga clic en [Rastreador > Host duplicado] en el menú izquierdo. + +|image0| + +Para editar, haga clic en el nombre de la configuración. + +Crear configuración +------------------- + +Para abrir la página de configuración de host duplicado, haga clic en el botón de nueva creación. + +|image1| + +Parámetros de configuración +---------------------------- + +Nombre regular +:::::::::::::: + +Especifique el nombre de host regular. Los nombres de host duplicados se reemplazan con el nombre de host regular. + +Nombre duplicado +:::::::::::::::: + +Especifique el nombre de host duplicado. Especifique el nombre de host que desea reemplazar. + +.. note:: + + Una URL cuyo nombre de host coincide con un nombre duplicado se sustituye por la URL del nombre regular antes del rastreo. Esto se aplica tanto a las URL escritas en "URLs" (las URL iniciales) de la configuración de rastreo como a las URL de los enlaces encontrados durante el rastreo. + Por ello, "URLs a incluir en el rastreo" y "URLs a excluir del rastreo" de la configuración de rastreo se evalúan sobre la URL ya sustituida. Escríbalas con el nombre de host del nombre regular. + + Por ejemplo, si el nombre regular es ``example.com`` y el nombre duplicado es ``www.example.com``, escribir solo ``https://www.example.com/.*`` en "URLs a incluir en el rastreo" deja fuera la URL inicial tras la sustitución (``https://example.com/``). + En ese caso no se registra ningún documento en el índice y no se genera ni un error ni un mensaje de registro. + +Eliminar configuración +---------------------- + +Haga clic en el nombre de la configuración en la página de lista y haga clic en el botón de eliminar para que aparezca una pantalla de confirmación. +Al presionar el botón de eliminar, se eliminará la configuración. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/duplicatehost-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/duplicatehost-2.png diff --git a/es/15.10/admin/elevateword-guide.rst b/es/15.10/admin/elevateword-guide.rst new file mode 100644 index 000000000..a66bc7701 --- /dev/null +++ b/es/15.10/admin/elevateword-guide.rst @@ -0,0 +1,106 @@ +================== +Palabra Adicional +================== + +Descripción general +=================== + +Aquí se explica la configuración de candidatos de palabras adicionales para sugerencias. Las sugerencias se muestran según el término de búsqueda, pero puede agregar esas palabras. + +Método de gestión +================== + +Método de visualización +----------------------- + +Para abrir la página de lista para configurar palabras adicionales que se muestra a continuación, haga clic en [Sugerir > Palabra elevada] en el menú izquierdo. + +|image0| + +Para editar, haga clic en el nombre de la configuración. + +Crear configuración +------------------- + +Para abrir la página de configuración de palabra adicional, haga clic en el botón de nueva creación. + +|image1| + +Parámetros de configuración +---------------------------- + +Palabra +::::::: + +Especifique la palabra que se mostrará como candidata de sugerencia. + +Lectura +::::::: + +Especifique la lectura de la palabra candidata de sugerencia. + +Permisos +:::::::: + +Configure la información de rol para la palabra. +La sugerencia solo se mostrará a los usuarios que tengan el rol configurado. + +Etiqueta +:::::::: + +Configure la etiqueta para la palabra. +Si se selecciona una etiqueta diferente a la configurada, no se mostrará en la sugerencia. + +Valor de impulso +:::::::::::::::: + +Configure el valor de impulso para la palabra. + +Eliminar configuración +---------------------- + +Haga clic en el nombre de la configuración en la página de lista y haga clic en el botón de eliminar para que aparezca una pantalla de confirmación. +Al presionar el botón de eliminar, se eliminará la configuración. + + +Descarga +======== + +Descarga las palabras registradas en formato CSV. + +|image2| + +Contenido del CSV +----------------- + +La primera línea es el encabezado. +Desde la segunda línea en adelante se describen las palabras adicionales. + +:: + +"SuggestWord","Reading","Role","Label","Boost" +"fess","ふぇす","role1","label1","100" + +Carga +===== + +Registra palabras en formato CSV. + +|image3| + +Contenido del CSV +----------------- + +La primera línea es el encabezado. +Desde la segunda línea en adelante se describen las palabras adicionales. + +:: + +"SuggestWord","Reading","Role","Label","Boost" +"fess","ふぇす","role1","label1","100" + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/elevateword-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/elevateword-2.png +.. |image2| image:: ../../../resources/images/en/15.10/admin/elevateword-3.png +.. |image3| image:: ../../../resources/images/en/15.10/admin/elevateword-4.png diff --git a/es/15.10/admin/esreq-guide.rst b/es/15.10/admin/esreq-guide.rst new file mode 100644 index 000000000..e1a40457f --- /dev/null +++ b/es/15.10/admin/esreq-guide.rst @@ -0,0 +1,53 @@ +======================== +Solicitud a OpenSearch +======================== + +Descripción general +=================== + +Esta página envía a OpenSearch una solicitud escrita en un archivo JSON. + +|image0| + +Esta página no aparece en el menú. +Para mostrarla, inicie sesión como administrador e ingrese ``/admin/sereq/`` como la ruta de la URL. +Para enviar una solicitud se necesita el rol ``admin`` (administradores) o el rol ``admin-sereq``. + +Método de operación +=================== + +Envío de solicitud +------------------ + +Cree como archivo JSON la solicitud que desea enviar a OpenSearch, seleccione ese archivo como "Archivo de solicitud" y haga clic en el botón "Enviar" para enviar la solicitud a OpenSearch. +La respuesta se descarga como un archivo. + +Parámetros de configuración +--------------------------- + +Archivo de solicitud +:::::::::::::::::::: + +Especifique el archivo que contiene la solicitud. + +Escriba en la primera línea `` ``, separados por un único espacio, y en las líneas siguientes el cuerpo de la solicitud (por ejemplo, un DSL de consulta). +El método puede ser GET, POST, PUT o DELETE. La ruta es la ruta en OpenSearch y se puede omitir la ``/`` inicial. +Por ejemplo, el contenido del archivo sería el siguiente. + +:: + + POST /_search + { + "query": { + "match_all": {} + } + } + +Los saltos de línea del cuerpo se eliminan y las líneas se unen antes de enviar la solicitud. Por ello no se puede enviar una solicitud cuyo cuerpo tenga un documento JSON por línea, como ``_bulk``. + +.. warning:: + + Una solicitud con el método PUT o DELETE también se envía a OpenSearch tal cual. + Según el contenido del archivo, puede modificar o eliminar los índices que utiliza |Fess| y provocar pérdida de datos. Compruebe el contenido con atención antes de enviarlo. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/esreq-1.png diff --git a/es/15.10/admin/failureurl-guide.rst b/es/15.10/admin/failureurl-guide.rst new file mode 100644 index 000000000..fff5d57e0 --- /dev/null +++ b/es/15.10/admin/failureurl-guide.rst @@ -0,0 +1,66 @@ +============ +URL de fallo +============ + +Descripción general +=================== + +Aquí se explica sobre las URL de fallo. +Las URL que no se pudieron obtener durante el rastreo se registran y se pueden verificar como URL de fallo. + +Método de gestión +================== + +Método de visualización +----------------------- + +Para abrir la página de lista para verificar las URL de fallo, haga clic en [Información del sistema > URL de fallo] en el menú izquierdo. + +|image0| + +Al hacer clic en el enlace de verificación de URL de fallo, se muestran los detalles. + +Detalles de URL de fallo +========================== + +Los detalles de URL de fallo registran las excepciones que ocurrieron durante el rastreo. + +|image1| + +Contenido de los detalles +-------------------------- + +URL +::: + +URL en la que ocurrió la excepción. + +Nombre del hilo +::::::::::::::: + +Nombre del hilo que estaba ejecutando el rastreo. +Se puede utilizar al verificar archivos de registro. + +Tipo +:::: + +Tipo de excepción. + +Registro +:::::::: + +Contenido de la excepción. + +Número de errores +::::::::::::::::: + +Número de veces que ocurrió esta excepción. + +Fecha del último acceso +::::::::::::::::::::::: + +Hora en la que ocurrió esta excepción. + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/failureurl-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/failureurl-2.png diff --git a/es/15.10/admin/fileauth-guide.rst b/es/15.10/admin/fileauth-guide.rst new file mode 100644 index 000000000..dcd5608ed --- /dev/null +++ b/es/15.10/admin/fileauth-guide.rst @@ -0,0 +1,85 @@ +========================== +Autenticación de Archivos +========================== + +Descripción general +=================== + +Aquí se explica el método de configuración cuando se requiere autenticación de archivos para el rastreo dirigido a archivos. +|Fess| admite la autenticación para FTP o carpetas compartidas de Windows. + +Método de gestión +================== + +Método de visualización +----------------------- + +Para abrir la página de lista para configurar la autenticación de archivos que se muestra a continuación, haga clic en [Rastreador > Autenticación de archivos] en el menú izquierdo. + +|image0| + +Para editar, haga clic en el nombre de la configuración. + +Crear configuración +------------------- + +Para abrir la página de configuración de autenticación de archivos, haga clic en el botón de nueva creación. + +|image1| + +Parámetros de configuración +---------------------------- + +Nombre de host +:::::::::::::: + +Especifique el nombre de host del sitio que requiere autenticación. +Utilice el mismo nombre que el nombre de host de la URL que se va a rastrear. Esta autenticación no se utiliza para una URL escrita con otro nombre (por ejemplo, una dirección IP en lugar de un alias). + +Puerto +:::::: + +Especifique el puerto del sitio que requiere autenticación. +Si se deja en blanco, la lista muestra "Cualquiera". El significado de un puerto en blanco depende del esquema. + +* FTP: Se utiliza para URL con cualquier puerto (una URL sin puerto se trata como el puerto 21). +* SAMBA: Se utiliza solo para URL que no incluyen un puerto (``smb://servidor/recurso/``). No se utiliza para una URL que incluye un puerto, como ``smb://servidor:445/recurso/``. Para rastrear una URL que incluye un puerto, especifique aquí el mismo puerto. + +Esquema +::::::: + +Seleccione el método de autenticación. +Puede utilizar FTP o SAMBA (autenticación de carpeta compartida de Windows). + +Nombre de usuario +::::::::::::::::: + +Especifique el nombre de usuario para iniciar sesión en el sitio de autenticación. + +Contraseña +:::::::::: + +Especifique la contraseña para iniciar sesión en el sitio de autenticación. + +Parámetros +:::::::::: + +Configure si hay valores de configuración necesarios para iniciar sesión en el sitio de autenticación. Para SAMBA, puede configurar el valor de domain. Si desea configurarlo, descríbalo de la siguiente manera: + +:: + + domain=FUGA + +Configuración de rastreo de archivos +::::::::::::::::::::::::::::::::::::: + +Especifique la configuración de rastreo que utilizará esta configuración de autenticación. + +Eliminar configuración +---------------------- + +Haga clic en el nombre de la configuración en la página de lista y haga clic en el botón de eliminar para que aparezca una pantalla de confirmación. +Al presionar el botón de eliminar, se eliminará la configuración. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/fileauth-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/fileauth-2.png diff --git a/es/15.10/admin/fileconfig-guide.rst b/es/15.10/admin/fileconfig-guide.rst new file mode 100644 index 000000000..368a410ff --- /dev/null +++ b/es/15.10/admin/fileconfig-guide.rst @@ -0,0 +1,262 @@ +=================================================================== +Rastreo de Sistema de Archivos (Búsqueda en Servidores de Archivos) +=================================================================== + +Descripción general +=================== + +El rastreo de archivos (Rastreo de Sistema de Archivos) permite registrar en el índice de |Fess| los documentos almacenados en servidores de archivos corporativos, carpetas compartidas de Windows o almacenamiento en la nube, para que puedan localizarse mediante búsqueda de texto completo (búsqueda en servidores de archivos). Es compatible con numerosos formatos de archivo, como Word, Excel, PowerPoint y PDF. + +La página de configuración de rastreo de archivos le permite administrar la configuración para rastrear archivos en el sistema de archivos o en carpetas compartidas en la red. + +El objetivo del rastreo se determina según el protocolo especificado en la «Ruta»: + +- ``file:/`` … sistema de archivos local o unidad montada +- ``smb://`` … servidor de archivos o carpeta compartida de Windows (SMB/CIFS) +- ``smb1://`` … servidor de archivos o carpeta compartida de Windows mediante el antiguo protocolo SMB1 +- ``ftp://`` … servidor FTP +- ``s3://`` … bucket de Amazon S3 (requiere el plugin ``fess-storage-s3``) +- ``gcs://`` … bucket de Google Cloud Storage (requiere el plugin ``fess-storage-gcs``) + +Método de gestión +================== + +Método de visualización +----------------------- + +Para abrir la página de lista para configurar el rastreo de archivos que se muestra a continuación, haga clic en [Rastreador > Sistema de archivos] en el menú izquierdo. + +|image0| + +Para editar, haga clic en el nombre de la configuración. + +Crear configuración +------------------- + +Para abrir la página de configuración de rastreo de archivos, haga clic en el botón de nueva creación. + +|image1| + +Parámetros de configuración +---------------------------- + +Nombre +:::::: + +Es el nombre de la configuración. + +Ruta +:::: + +En esta ruta, especifique dónde comenzar el rastreo (ejemplo: file:/, smb://, s3://, gcs://). + +Rutas a rastrear +:::::::::::::::: + +Las rutas que coincidan con la expresión regular (formato Java) especificada en este elemento serán objeto del rastreador de |Fess|. + +Rutas excluidas del rastreo +:::::::::::::::::::::::::::: + +Las rutas que coincidan con la expresión regular (formato Java) especificada en este elemento no serán objeto del rastreador de |Fess|. + +Rutas a buscar +:::::::::::::: + +Las rutas que coincidan con la expresión regular (formato Java) especificada en este elemento serán objeto de búsqueda. + +Rutas excluidas de la búsqueda +::::::::::::::::::::::::::::::: + +Las rutas que coincidan con la expresión regular (formato Java) especificada en este elemento no serán objeto de búsqueda. + +Parámetros de configuración +:::::::::::::::::::::::::::: + +Puede especificar información de configuración de rastreo. + +En el rastreo de rutas que comienzan con ``file:`` (sistema de archivos local o montado), ``client.followSymlink`` especifica si se siguen los enlaces simbólicos. El valor predeterminado es ``true`` (se siguen). Con ``false``, los enlaces simbólicos se omiten y los archivos a los que apuntan no se rastrean a través del enlace (cada enlace omitido se registra con nivel INFO en ``fess-crawler.log``). Al seguir un enlace, el archivo de destino se registra por segunda vez con los permisos de la configuración que contiene el enlace; por ello, considere ``false`` si rastrea un recurso compartido que pueden leer más usuarios que el árbol al que apuntan sus enlaces. + +:: + + client.followSymlink=false + +Profundidad +::::::::::: + +Especifique la profundidad de la estructura del sistema de archivos a rastrear. + +Número máximo de accesos +::::::::::::::::::::::::: + +Especifique el número de rutas a indexar. + +Número de hilos +::::::::::::::: + +Especifique el número de hilos a utilizar para esta configuración. + +Intervalo +::::::::: + +Especifique el tiempo de espera cada vez que un hilo rastrea una ruta. + +Valor de impulso +:::::::::::::::: + +El valor de impulso es la prioridad de los documentos indexados por esta configuración. + +Permisos +:::::::: + +Especifique el permiso para esta configuración. +La forma de especificar permisos es, por ejemplo, para mostrar resultados de búsqueda a usuarios que pertenecen al grupo developer, especifique {group}developer. +La especificación por usuario es {user}nombre_usuario, la especificación por rol es {role}nombre_rol, y la especificación por grupo es {group}nombre_grupo. + +Host virtual +:::::::::::: + +Especifique el nombre de host del host virtual. +Para más detalles, consulte :doc:`Host virtual en la guía de configuración <../config/security-virtual-host>`. + +Estado +:::::: + +Cuando esta configuración está habilitada, el trabajo del rastreador predeterminado realizará el rastreo incluyendo esta configuración. + +Descripción +::::::::::: + +Puede ingresar una descripción. + +Eliminar configuración +---------------------- + +Haga clic en el nombre de la configuración en la página de lista y haga clic en el botón de eliminar para que aparezca una pantalla de confirmación. Al presionar el botón de eliminar, se eliminará la configuración. + +Ejemplo +======= + +Rastrear archivos locales +-------------------------- + +Para rastrear archivos bajo /home/share, la configuración sería la siguiente. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - Nombre + - Valor + * - Nombre + - Directorio compartido + * - Ruta + - file:/home/share + +Los otros parámetros pueden usar la configuración predeterminada. + +Rastrear carpeta compartida de Windows +--------------------------------------- + +Para rastrear archivos bajo \\SERVER\SharedFolder, la configuración sería la siguiente. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - Nombre + - Valor + * - Nombre + - Carpeta compartida + * - Ruta + - smb://SERVER/SharedFolder/ + +Si se requiere nombre de usuario/contraseña para acceder a la carpeta compartida, es necesario crear una configuración de autenticación de archivos desde [Rastreador > Autenticación de archivos] en el menú izquierdo. +En ese caso, la configuración sería la siguiente. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - Nombre + - Valor + * - Nombre de host + - SERVER + * - Esquema + - SAMBA + * - Nombre de usuario + - (Ingrese) + * - Contraseña + - (Ingrese) + +Rastrear buckets de Amazon S3 +----------------------------- + +Para rastrear archivos en el bucket my-bucket, la configuración sería la siguiente. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - Nombre + - Valor + * - Nombre + - Bucket S3 + * - Ruta + - s3://my-bucket/ + +El acceso a S3 requiere credenciales de autenticación. Agregue lo siguiente en "Parámetros de configuración": + +:: + + client.endpoint=https://s3.ap-northeast-1.amazonaws.com + client.accessKey=SU_CLAVE_DE_ACCESO + client.secretKey=SU_CLAVE_SECRETA + client.region=ap-northeast-1 + +.. note:: + La compatibilidad con Amazon S3 y el almacenamiento compatible con S3 proviene del plugin + ``fess-storage-s3``, que no forma parte de la distribución. Instálelo desde la página + **Sistema > Plugin** de la pantalla de administración o con + ``bin/fess-setup install plugin fess-storage-s3``. + +Rastrear buckets de Google Cloud Storage +----------------------------------------- + +Para rastrear archivos en el bucket my-gcs-bucket, la configuración sería la siguiente. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - Nombre + - Valor + * - Nombre + - Bucket GCS + * - Ruta + - gcs://my-gcs-bucket/ + +El acceso a GCS requiere credenciales de autenticación. Agregue lo siguiente en "Parámetros de configuración": + +:: + + client.projectId=su-id-de-proyecto + client.credentialsFile=/ruta/a/service-account.json + +.. note:: + La compatibilidad con Google Cloud Storage proviene del plugin ``fess-storage-gcs``, que no + forma parte de la distribución. Instálelo desde la página **Sistema > Plugin** de la + pantalla de administración o con ``bin/fess-setup install plugin fess-storage-gcs``. + +Páginas Relacionadas +==================== + +- :doc:`../config/crawler-basic` +- :doc:`fileauth-guide` +- :doc:`../config/datastore/ds-overview` +- :doc:`../config/search-basic` +- :doc:`../user/index` + +.. |image0| image:: ../../../resources/images/en/15.10/admin/fileconfig-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/fileconfig-2.png +.. pdf :height: 940 px diff --git a/es/15.10/admin/general-guide.rst b/es/15.10/admin/general-guide.rst new file mode 100644 index 000000000..f8c736e1e --- /dev/null +++ b/es/15.10/admin/general-guide.rst @@ -0,0 +1,684 @@ +======= +General +======= + +Descripción general +=================== + +En esta página de administración, puede gestionar la configuración de |Fess|. +Puede cambiar varias configuraciones de |Fess| sin necesidad de reiniciarlo. + +Contenido de la configuración +============================== + +Sistema +------- + +|image0| + +Respuesta JSON +:::::::::::::: + +Especifique si desea habilitar la API JSON. + +Requiere inicio de sesión +::::::::::::::::::::::::: + +Especifique si desea hacer que el inicio de sesión sea obligatorio para la función de búsqueda. + +Mostrar enlace de inicio de sesión +::::::::::::::::::::::::::::::::::: + +Configure si desea mostrar el enlace a la página de inicio de sesión en la pantalla de búsqueda. + +Contraer resultados duplicados +::::::::::::::::::::::::::::::: + +Configure si desea habilitar la contracción de resultados duplicados. + +Si ``search_engine.type`` es ``vanilla`` o ``aws``, este elemento no se muestra y la contracción queda siempre desactivada (consulte :doc:`../config/search-engine-type`). + +Mostrar miniatura +:::::::::::::::::: + +Configure si desea habilitar la visualización de miniaturas. + +Propiedades del sistema +::::::::::::::::::::::: + +Configura las propiedades del sistema de |Fess|. +Especifique en formato ``clave=valor``, una por línea. + +Valor de etiqueta por defecto +::::::::::::::::::::::::::::: + +Describa el valor de etiqueta que se agregará a las condiciones de búsqueda de forma predeterminada. +Si especifica por rol o grupo, añada "role:" o "group:" como en "role:admin=label1". + +Valor de ordenación por defecto +:::::::::::::::::::::::::::::::: + +Describa el valor de ordenamiento que se agregará a las condiciones de búsqueda de forma predeterminada. +Si especifica por rol o grupo, añada "role:" o "group:" como en "role:admin=content_length.desc". + +Host virtual +:::::::::::: + +Configure el host virtual. +Para más detalles, consulte :doc:`Host virtual en la guía de configuración <../config/security-virtual-host>`. + +Respuesta de palabras populares +:::::::::::::::::::::::::::::::: + +Especifique si desea habilitar la API de palabras populares. + +Codificación de archivo CSV +::::::::::::::::::::::::::: + +Especifique la codificación de los archivos CSV que se descargarán. + +Añadir parámetro de búsqueda +:::::::::::::::::::::::::::: + +Habilite esto si desea pasar parámetros a la visualización de resultados de búsqueda. + +Proxy de archivos de búsqueda +::::::::::::::::::::::::::::: + +Especifique si desea habilitar el proxy de archivos para los resultados de búsqueda. + +Usar configuración regional del navegador +:::::::::::::::::::::::::::::::::::::::::: + +Especifique si desea usar la configuración regional del navegador para la búsqueda. + +Tipo de SSO +::::::::::: + +Especifica el tipo de inicio de sesión único (Single Sign-On). + +- **Ninguno**: No usar SSO +- **OpenID Connect**: Usar OpenID Connect (requiere el plugin ``fess-sso-oidc``) +- **SAML**: Usar SAML (requiere el plugin ``fess-sso-saml``) +- **SPNEGO**: Usar SPNEGO (requiere el plugin ``fess-sso-spnego``) +- **Entra ID**: Usar Microsoft Entra ID (requiere el plugin ``fess-sso-entraid``) + +Rastreador +---------- + +|image1| + +Comprobar fecha de última modificación +::::::::::::::::::::::::::::::::::::::: + +Habilite esto para realizar rastreo diferencial. + +Para las URL HTTP/HTTPS, cuando el ``Last-Modified`` de la respuesta HEAD no permite decidir (no hay +fecha de modificación en el índice, la respuesta HEAD no tiene ``Last-Modified`` o el HEAD devuelve un +estado distinto de 200/404), el GET se envía como GET condicional con ``If-None-Match`` (el ``ETag`` +indexado) y/o ``If-Modified-Since``. Una página que responde ``304 Not Modified`` se trata como una +página sin cambios y no se vuelve a obtener. Para obtener todo de nuevo, por ejemplo tras cambiar la +configuración de rastreo, desactive esta opción durante un rastreo. + +Configuración de rastreadores simultáneos +:::::::::::::::::::::::::::::::::::::::::: + +Especifique el número de configuraciones de rastreo que se ejecutarán simultáneamente. + +Agente de usuario +::::::::::::::::: + +Especifica el nombre del agente de usuario utilizado por el rastreador. + +Eliminar documentos anteriores +::::::::::::::::::::::::::::::: + +Especifique el período de validez de los documentos en días. Un documento registrado o actualizado por un rastreo caduca esa cantidad de días después del inicio del rastreo, y la validez de un documento que vuelve a encontrarse en el siguiente rastreo se prolonga. El trabajo Doc Purger del programador de tareas (se ejecuta cada minuto de forma predeterminada) elimina del índice los documentos caducados. + +El valor predeterminado es ``3`` y los valores permitidos van de ``-1`` a ``1000``. Con ``-1`` no se establece caducidad en los documentos registrados o actualizados por rastreos posteriores (una caducidad ya establecida no se prolonga). + +Tipos de error a ignorar +::::::::::::::::::::::::: + +Las URL con fallas que excedan el umbral se excluyen del rastreo, pero los nombres de excepción especificados aquí seguirán siendo objeto de rastreo incluso si exceden el umbral de URL con fallas. + +Umbral de recuento de fallos +:::::::::::::::::::::::::::: + +Si un documento objeto de rastreo se registra en las URL con fallas más veces que el número especificado aquí, se excluirá del próximo rastreo. + +Registro +-------- + +Registro de búsqueda +:::::::::::::::::::: + +Especifique si desea habilitar el registro de búsquedas. + +Registro de usuario +::::::::::::::::::: + +Especifique si desea habilitar el registro de usuarios. + +Registro de favoritos +::::::::::::::::::::: + +Especifique si desea habilitar el registro de favoritos. + +Eliminar registros de búsqueda anteriores +:::::::::::::::::::::::::::::::::::::::::: + +Elimina los registros de búsqueda anteriores al número de días especificado. El valor predeterminado es ``-1``; con ``-1`` los registros no se eliminan y se conservan indefinidamente. +Los registros de clics, de favoritos y de chat también se eliminan con este mismo número de días. + +Eliminar registros de trabajos anteriores +:::::::::::::::::::::::::::::::::::::::::: + +Elimina los registros de trabajo anteriores al número de días especificado. El valor predeterminado es ``-1``; con ``-1`` no se eliminan. + +Eliminar registros de usuarios anteriores +:::::::::::::::::::::::::::::::::::::::::: + +Elimina los registros de usuario anteriores al número de días especificado. El valor predeterminado es ``-1``; con ``-1`` no se eliminan. + +Nombre del bot para eliminar registros +::::::::::::::::::::::::::::::::::::::: + +Especifique los nombres de bots que se excluirán de los registros de búsqueda. + +Nivel de registro +::::::::::::::::: + +Especifique el nivel de registro para fess.log. + +Sugerir +------- + +Sugerir por término de búsqueda +:::::::::::::::::::::::::::::::: + +Especifique si desea generar candidatos de sugerencia a partir de los registros de búsqueda. + +Sugerir por documentos +:::::::::::::::::::::: + +Especifique si desea generar candidatos de sugerencia a partir de los documentos indexados. + +Eliminar información de sugerencias anterior +::::::::::::::::::::::::::::::::::::::::::::: + +Elimina los datos de sugerencias anteriores al número de días especificado. + +LDAP +---- + +|image2| + +URL de LDAP +::::::::::: + +Especifique la URL del servidor LDAP. + +DN base +::::::: + +Especifique el nombre distinguido base para iniciar sesión en la pantalla de búsqueda. + +DN de enlace +:::::::::::: + +Especifique el DN de enlace del administrador. + +Contraseña +:::::::::: + +Especifique la contraseña del DN de enlace. + +DN de usuario +::::::::::::: + +Especifique el nombre distinguido del usuario. + +Filtro de cuenta +:::::::::::::::: + +Especifique el Common Name o uid del usuario. + +Filtro de grupo +::::::::::::::: + +Especifique las condiciones de filtro para los grupos que desea obtener. + +Atributo memberOf +::::::::::::::::: + +Especifique el nombre del atributo memberOf disponible en el servidor LDAP. +Para Active Directory, es memberOf. +Para otros servidores LDAP, puede ser isMemberOf. + +Autenticación de seguridad +:::::::::::::::::::::::::: + +Especifica el método de autenticación de seguridad LDAP (ej.: simple). + +Fábrica de contexto inicial +:::::::::::::::::::::::::::: + +Especifica la clase de fábrica de contexto inicial LDAP (ej.: com.sun.jndi.ldap.LdapCtxFactory). + +OpenID Connect +-------------- + +|image3| + +ID de cliente +::::::::::::: + +Especifica el ID de cliente del proveedor de OpenID Connect. + +Secreto de cliente +:::::::::::::::::: + +Especifica el secreto de cliente del proveedor de OpenID Connect. + +URL del servidor de autorización +::::::::::::::::::::::::::::::::: + +Especifica la URL del servidor de autorización para OpenID Connect. + +URL del servidor de tokens +:::::::::::::::::::::::::: + +Especifica la URL del servidor de tokens para OpenID Connect. + +URL de redirección +:::::::::::::::::: + +Especifica la URL de redirección para OpenID Connect. + +Alcance +::::::: + +Especifica el alcance para OpenID Connect. + +URL base +:::::::: + +Especifica la URL base para OpenID Connect. + +Grupos por defecto +:::::::::::::::::: + +Especifica los grupos por defecto que se asignarán a los usuarios durante la autenticación OpenID Connect. + +Roles por defecto +::::::::::::::::: + +Especifica los roles por defecto que se asignarán a los usuarios durante la autenticación OpenID Connect. + +SAML +---- + +|image4| + +ID de entidad del IdP +::::::::::::::::::::: + +Especifica el ID de entidad del IdP (Identity Provider). + +URL SSO del IdP +::::::::::::::: + +Especifica la URL del servicio de inicio de sesión único del IdP. + +URL SLO del IdP +::::::::::::::: + +Especifica la URL del servicio de cierre de sesión único del IdP. + +Certificado X.509 del IdP +::::::::::::::::::::::::: + +Especifica el certificado de clave pública X.509 para la verificación de firma de aserción SAML del IdP. +Especifique solo el contenido codificado en Base64 sin las líneas ``-----BEGIN CERTIFICATE-----`` y ``-----END CERTIFICATE-----``. + +URL base del SP +::::::::::::::: + +Especifica la URL base del proveedor de servicios SAML. + +ID de entidad del SP +:::::::::::::::::::: + +Especifica el ID de entidad del SP (Service Provider). +Se configura automáticamente cuando se establece la ``URL base del SP``. + +URL ACS del SP +:::::::::::::: + +Especifica la URL del Assertion Consumer Service (ACS) que recibe las aserciones SAML. +Se configura automáticamente cuando se establece la ``URL base del SP``. + +URL SLO del SP +:::::::::::::: + +Especifica la URL del servicio de cierre de sesión único del SP. +Se configura automáticamente cuando se establece la ``URL base del SP``. + +Formato NameID del SP +::::::::::::::::::::: + +Especifica el formato NameID utilizado en las aserciones SAML. + +Nombre de atributo de grupo +:::::::::::::::::::::::::::: + +Especifica el nombre del atributo para obtener grupos de la respuesta SAML. + +Nombre de atributo de rol +::::::::::::::::::::::::: + +Especifica el nombre del atributo para obtener roles de la respuesta SAML. + +Grupos por defecto +:::::::::::::::::: + +Especifica los grupos por defecto que se asignarán a los usuarios durante la autenticación SAML. + +Roles por defecto +::::::::::::::::: + +Especifica los roles por defecto que se asignarán a los usuarios durante la autenticación SAML. + +SPNEGO +------ + +|image5| + +.. note:: + La configuración de SPNEGO se comparte a nivel de proceso dentro de la biblioteca subyacente, por lo que es necesario reiniciar |Fess| para aplicar los cambios. + +Configuración Krb5 +::::::::::::::::::: + +Especifica la ruta al archivo de configuración de Kerberos 5. + +Configuración de inicio de sesión +:::::::::::::::::::::::::::::::::: + +Especifica la ruta al archivo de configuración de inicio de sesión JAAS (Java Authentication and Authorization Service). + +Módulo de cliente de inicio de sesión +:::::::::::::::::::::::::::::::::::::: + +Especifica el nombre del módulo de inicio de sesión del cliente JAAS. + +Módulo de servidor de inicio de sesión +::::::::::::::::::::::::::::::::::::::: + +Especifica el nombre del módulo de inicio de sesión del servidor JAAS. + +Nombre de usuario de preautenticación +:::::::::::::::::::::::::::::::::::::: + +Especifica el nombre de usuario para la preautenticación SPNEGO. +Si el nombre de usuario y la contraseña se dejan vacíos, se habilita el inicio de sesión del servidor basado en keytab. + +Contraseña de preautenticación +::::::::::::::::::::::::::::::: + +Especifica la contraseña para la preautenticación SPNEGO. + +Permitir autenticación básica +::::::::::::::::::::::::::::: + +Especifique si desea permitir la autenticación básica como alternativa. + +Permitir autenticación básica no segura +:::::::::::::::::::::::::::::::::::::::: + +Especifique si desea permitir la autenticación básica a través de conexiones no seguras (HTTP). +Esto está deshabilitado de forma predeterminada para evitar que las credenciales se envíen en texto claro (la autenticación básica sigue estando disponible en las conexiones HTTPS). + +Solicitud NTLM +::::::::::::::: + +Especifique si desea habilitar la solicitud NTLM. + +Permitir localhost +:::::::::::::::::: + +Especifique si desea permitir el acceso desde localhost. +Esto está deshabilitado de forma predeterminada por motivos de seguridad, ya que si se habilita, las solicitudes desde el mismo host se autentican como el usuario del sistema operativo del servidor sin verificación Kerberos. + +Permitir delegación +::::::::::::::::::: + +Especifique si desea permitir la delegación Kerberos. + +Nivel de registrador +:::::::::::::::::::: + +Especifica el nivel de salida de registro para la autenticación SPNEGO como valor numérico de 0 a 7. +Si se deja vacío o se establece un valor no numérico, el nivel de registro se detecta automáticamente. + +Entra ID +-------- + +|image6| + +Inquilino (ID o dominio) +:::::::::::::::::::::::: + +Especifica el ID de inquilino o dominio para Microsoft Entra ID. + +Autoridad +::::::::: + +Especifica la URL de autoridad para Microsoft Entra ID. + +ID de cliente +::::::::::::: + +Especifica el ID de aplicación (cliente) para Microsoft Entra ID. + +Secreto de cliente +:::::::::::::::::: + +Especifica el secreto de cliente para Microsoft Entra ID. + +URL de respuesta +:::::::::::::::: + +Especifica la URL de respuesta (redirección) para Microsoft Entra ID. + +TTL de estado +::::::::::::: + +Especifica el tiempo de vida (TTL) del estado de autenticación. + +Campos de permisos +:::::::::::::::::: + +Especifica los campos para obtener información de permisos de Entra ID. + +Grupos por defecto +:::::::::::::::::: + +Especifica los grupos por defecto que se asignarán a los usuarios durante la autenticación Entra ID. + +Roles por defecto +::::::::::::::::: + +Especifica los roles por defecto que se asignarán a los usuarios durante la autenticación Entra ID. + +Usar servicio de dominio +:::::::::::::::::::::::: + +Especifique si desea utilizar el servicio de dominio de Entra ID. + +Aviso +----- + +|image7| + +.. note:: + + Los avisos aceptan HTML. Cuando un tema de búsqueda muestra un aviso, solo se conservan las etiquetas y los atributos de una lista de permitidos: se eliminan los elementos `` + + + +Si su sitio ya utiliza jQuery, no es necesario agregar el elemento script de jQuery. + +La funcionalidad de sugerencias utiliza la API de sugerencias de |Fess| (``/api/v2/suggest-words``). +Cambie ``url`` para que coincida con la URL del servidor |Fess| que haya configurado. + +Las principales opciones que se pueden especificar para ``suggestor`` son las siguientes. + +.. list-table:: Principales opciones de suggestor + :header-rows: 1 + :widths: 25 75 + + * - Opción + - Descripción + * - ``ajaxinfo.url`` + - La URL de la API de sugerencias. Especifique ``/api/v2/suggest-words`` de su servidor |Fess|. + * - ``ajaxinfo.fn`` + - Un arreglo de nombres de campos de los que obtener sugerencias. Puede usar el valor predeterminado ``["_default", "content", "title"]`` tal cual. + * - ``ajaxinfo.num`` + - El número máximo de candidatos de sugerencia que se muestran. + * - ``ajaxinfo.lang`` + - El idioma utilizado para acotar los candidatos de sugerencia (opcional). + * - ``minterm`` + - El número mínimo de caracteres de entrada antes de solicitar sugerencias. + * - ``adjustWidthVal`` + - El valor (en píxeles) que se suma al ancho del campo de entrada para ajustar el ancho del cuadro de sugerencias. + * - ``searchForm`` + - El elemento del formulario de búsqueda que se envía cuando se selecciona un candidato. + * - ``boxCssInfo`` + - El CSS aplicado al cuadro de sugerencias. + * - ``listSelectedCssInfo`` + - El CSS aplicado al candidato seleccionado (opcional). + * - ``listDeselectedCssInfo`` + - El CSS aplicado a los candidatos no seleccionados (opcional). + +Especifique un valor para "z-index" que no se superponga con otros elementos. + +.. note:: + Cuando el formulario de búsqueda se coloca en una página cuyo dominio difiere del servidor |Fess|, la solicitud a la API de sugerencias se convierte en una solicitud de origen cruzado (cross-origin). + |Fess| permite todos los orígenes de forma predeterminada (``api.cors.allow.origin=*``), por lo que funciona tal cual. + Para restringir el acceso, cambie ``api.cors.allow.origin`` en ``fess_config.properties``. + +.. note:: + ``/api/v2/suggest-words`` es la API proporcionada por el propio |Fess|. + El endpoint ``/api/v1/suggest-words`` utilizado en versiones anteriores ya no es proporcionado por el núcleo de |Fess|, y se debe instalar el complemento ``fess-webapp-v1-api`` para usarlo. + Para nuevas instalaciones, utilice ``/api/v2/suggest-words``. diff --git a/es/15.10/config/search-geosearch.rst b/es/15.10/config/search-geosearch.rst new file mode 100644 index 000000000..d93e209fc --- /dev/null +++ b/es/15.10/config/search-geosearch.rst @@ -0,0 +1,353 @@ +============================ +Búsqueda por Geolocalización +============================ + +Descripción General +=================== + +|Fess| puede ejecutar búsquedas especificando rangos geográficos en documentos que contienen información de ubicación de latitud y longitud. +Con esta funcionalidad, puede buscar documentos dentro de una cierta distancia desde un punto específico, +o construir un sistema de búsqueda integrado con servicios de mapas como Google Maps. + +Internamente, se utiliza la consulta geo-distance de OpenSearch para filtrar los documentos +que se encuentran dentro de la distancia especificada desde el punto central indicado. + +Casos de Uso +============ + +La búsqueda por geolocalización se puede utilizar para los siguientes propósitos: + +- Búsqueda de tiendas: Buscar tiendas cercanas a la ubicación actual del usuario +- Búsqueda de propiedades: Buscar propiedades dentro de una cierta distancia de una estación o instalación específica +- Búsqueda de eventos: Buscar información de eventos alrededor de una ubicación especificada +- Búsqueda de instalaciones: Búsqueda de proximidad de atracciones turísticas e instalaciones públicas + +Métodos de Configuración +======================== + +Configuración Durante la Generación del Índice +----------------------------------------------- + +Definición del Campo de Ubicación +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +En |Fess|, el campo ``location`` está definido por defecto para almacenar información de ubicación. +Este campo está configurado como tipo ``geo_point`` de OpenSearch. + +Formato de Registro de Información de Ubicación +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Durante la generación del índice, configure la latitud y longitud separadas por comas en el campo ``location``. + +**Formato:** + +:: + + latitud,longitud + +**Ejemplo:** + +:: + + 45.17614,-93.87341 + +.. note:: + La latitud se especifica en el rango de -90 a 90, y la longitud en el rango de -180 a 180. + +Ejemplo de Configuración en Rastreo de Almacén de Datos +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Al utilizar el rastreo de almacén de datos, configure la latitud y longitud en el campo ``location`` +desde una fuente de datos que contiene información de ubicación. + +**Ejemplo: Obtención desde Base de Datos** + +Si la latitud y la longitud se almacenan en columnas separadas, combínelas en una cadena separada por comas mediante SQL. +En los parámetros del almacén de datos cada línea es un elemento, por lo que escriba el SQL en una sola línea a continuación de ``sql=`` +(si lo divide en varias líneas, solo el ``SELECT`` de la primera línea se trata como SQL y se produce un error de sintaxis). + +:: + + sql=SELECT id, name, address, CONCAT(latitude, ',', longitude) AS location FROM stores + +En el script de configuración del almacén de datos, mapee el valor obtenido al campo ``location``. +En el almacén de datos de base de datos, los nombres de las columnas del SQL (incluidos los alias definidos con ``AS``) se convierten directamente en los nombres de variable del script. +No lleva un prefijo como ``data.``. + +:: + + location=location + +Adición de Información de Ubicación mediante Script +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +También puede agregar dinámicamente información de ubicación a documentos utilizando la funcionalidad de script en la configuración de rastreo (JavaScript de forma predeterminada; también se puede seleccionar Groovy). +Asigne el valor directamente al nombre del campo. + +:: + + // Configurar latitud y longitud en el campo location + location="35.681236,139.767125" + +Para más detalles sobre los scripts, consulte :doc:`scripting-overview`. + +Configuración Durante la Búsqueda +---------------------------------- + +Para ejecutar una búsqueda por geolocalización, especifique el punto central y el rango de búsqueda mediante parámetros de solicitud. + +Parámetros de Solicitud +~~~~~~~~~~~~~~~~~~~~~~~~ + +El nombre de los parámetros de búsqueda por geolocalización sigue el formato ``geo..point`` +y ``geo..distance``. En ```` se utiliza el nombre del campo configurado en +``query.geo.fields`` (por defecto, ``location``). + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Nombre del Parámetro + - Descripción + * - ``geo.location.point`` + - Latitud y longitud del punto central de búsqueda (separadas por comas; ejemplo: ``35.681236,139.767125``) + * - ``geo.location.distance`` + - Radio de búsqueda desde el punto central (con unidad; ejemplo: ``10km``) + +.. note:: + ``point`` y ``distance`` deben especificarse juntos. Un ``point`` sin ``distance`` será ignorado. + Además, el valor de ``point`` debe estar compuesto por dos valores numéricos en formato "latitud,longitud"; + si el formato es incorrecto, se producirá un error. + +.. note:: + La búsqueda geográfica funciona como un filtro sobre el término de búsqueda ``q``. Si ``q`` está vacío, la búsqueda no se ejecuta + y el resultado es de 0 elementos. Especifique un término de búsqueda en las solicitudes de búsqueda geográfica. + +.. note:: + Si se especifican varios ``point`` para el mismo campo, se tratarán como condición OR (dentro de cualquiera de los rangos). + Si se especifican para campos distintos, se tratarán como condición AND (dentro de todos los rangos). + +Unidades de Distancia +~~~~~~~~~~~~~~~~~~~~~~ + +Puede utilizar las siguientes unidades para la distancia: + +- ``km``: Kilómetros +- ``m``: Metros +- ``mi``: Millas +- ``yd``: Yardas + +.. note:: + El valor de la distancia se pasa directamente a OpenSearch, por lo que también pueden utilizarse otras unidades + compatibles con OpenSearch (como ``cm``, ``mm``, ``ft``, ``in``, ``nmi``, entre otras). + +Orden de los Resultados de Búsqueda +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +La búsqueda por geolocalización actúa como un **filtro** que restringe los resultados a los documentos +dentro del rango especificado. No afecta la puntuación de búsqueda (relevancia) ni ordena los resultados +por proximidad al punto central. Los resultados se devuelven en el orden habitual por relevancia +(o según el orden especificado con el parámetro ``sort``). + +.. note:: + |Fess| no admite la ordenación por distancia (ordenar por proximidad). + Si desea mostrar los resultados ordenados por distancia, utilice las coordenadas incluidas en la respuesta + para ordenarlos en el lado del cliente. + +Ejemplos de Búsqueda +==================== + +Búsqueda Básica +--------------- + +Para buscar documentos dentro de un radio de 10km desde la Estación de Tokio (35.681236, 139.767125): + +:: + + http://localhost:8080/search?q=palabra_clave&geo.location.point=35.681236,139.767125&geo.location.distance=10km + +Búsqueda Alrededor de la Ubicación Actual +------------------------------------------ + +Para buscar dentro de 1km desde la ubicación actual del usuario: + +:: + + http://localhost:8080/search?q=restaurante&geo.location.point=35.681236,139.767125&geo.location.distance=1km + +Uso con API +----------- + +La búsqueda por geolocalización también se puede utilizar con la API de búsqueda JSON v2 (``/api/v2/search``). +Especifique ``geo.location.point`` y ``geo.location.distance`` como parámetros de solicitud. + +:: + + curl "http://localhost:8080/api/v2/search?q=hotel&geo.location.point=35.681236,139.767125&geo.location.distance=5km" + +Los resultados de búsqueda se devuelven en el arreglo ``response.data`` del envelope común. Para más detalles sobre la API, +consulte :doc:`../api/api-search` y :doc:`../api/api-overview`. + +.. note:: + El campo ``location`` no se incluye en la respuesta de la API de forma predeterminada. Si desea incluir + las coordenadas en los resultados de búsqueda, agregue las siguientes dos configuraciones a ``fess_config.properties`` y reinicie |Fess|. + ``query.additional.response.fields`` añade el campo que se obtiene del motor de búsqueda y + ``query.additional.api.response.fields`` permite que el campo se incluya en la respuesta de la API. + Con solo una de las dos, ``location`` no se incluye en la respuesta. + + :: + + query.additional.response.fields=location + query.additional.api.response.fields=location + +Personalización del Nombre del Campo +===================================== + +Cambio del Nombre de Campo Predeterminado +------------------------------------------ + +Para cambiar el nombre del campo utilizado en la búsqueda por geolocalización, +modifique la siguiente configuración en ``fess_config.properties``. + +:: + + query.geo.fields=location + +Para especificar múltiples nombres de campo, sepárelos con comas. + +:: + + query.geo.fields=location,geo_point,coordinates + +.. note:: + - El nombre del parámetro de solicitud está vinculado al nombre del campo configurado. Por ejemplo, + si configura ``query.geo.fields=coordinates``, deberá especificar ``geo.coordinates.point`` y + ``geo.coordinates.distance``. + - Cada campo especificado aquí debe estar definido como tipo ``geo_point`` en el mapeo del índice. + +Ejemplos de Implementación +=========================== + +Implementación en Aplicación Web +--------------------------------- + +Ejemplo de búsqueda obteniendo la ubicación actual con JavaScript: + +.. code-block:: javascript + + // Obtener la ubicación actual con la API de Geolocation del navegador + navigator.geolocation.getCurrentPosition(function(position) { + const latitude = position.coords.latitude; + const longitude = position.coords.longitude; + const distance = "5km"; + + // Construir la URL de búsqueda (el término de búsqueda q no se puede omitir) + const searchUrl = `/search?q=${encodeURIComponent('tienda')}&geo.location.point=${latitude},${longitude}&geo.location.distance=${distance}`; + + // Ejecutar búsqueda + window.location.href = searchUrl; + }); + +Integración con Google Maps +----------------------------- + +Ejemplo de visualización de resultados de búsqueda con marcadores en Google Maps: + +.. note:: + Este ejemplo hace referencia al campo ``location`` de los resultados de búsqueda. Es necesario configurar + previamente ``query.additional.response.fields=location`` y ``query.additional.api.response.fields=location`` para incluir las coordenadas en la respuesta. + +.. code-block:: javascript + + // Inicializar el mapa + const map = new google.maps.Map(document.getElementById('map'), { + center: {lat: 35.681236, lng: 139.767125}, + zoom: 13 + }); + + // Ejecutar búsqueda por geolocalización con la API de búsqueda v2 de Fess + fetch('/api/v2/search?q=tienda&geo.location.point=35.681236,139.767125&geo.location.distance=5km') + .then(response => response.json()) + .then(json => { + // Mostrar los resultados (arreglo response.data) como marcadores + json.response.data.forEach(doc => { + if (doc.location) { + const [lat, lng] = doc.location.split(',').map(Number); + new google.maps.Marker({ + position: {lat: lat, lng: lng}, + map: map, + title: doc.title + }); + } + }); + }); + +Optimización del Rendimiento +============================= + +Verificación de la Configuración del Índice +-------------------------------------------- + +El campo de información de ubicación está definido como tipo ``geo_point`` en +``app/WEB-INF/classes/fess_indices/fess/doc.json`` de la instalación. + +:: + + "location": { + "type": "geo_point" + } + +Los campos de tipo ``geo_point`` se indexan mediante un árbol BKD, por lo que las consultas +geo-distance se ejecutan de forma eficiente. + +Optimización del Rango de Búsqueda y Respuesta +----------------------------------------------- + +Al aumentar el radio de búsqueda, aumenta el número de documentos dentro del rango, +lo que puede incrementar el tiempo de recuperación y representación de los resultados. + +- Configure un radio de búsqueda apropiado según el propósito de uso. +- Si maneja muchos resultados, como en la visualización de mapas, ajuste el tamaño de página + (parámetro ``num``) para limitar la cantidad de resultados obtenidos. + +Solución de Problemas +====================== + +La Búsqueda por Geolocalización No Funciona +-------------------------------------------- + +1. Verifique que los datos estén correctamente almacenados en el campo ``location``. +2. Verifique que el formato de latitud y longitud sea correcto (separado por comas con ``latitud,longitud``; si no hay exactamente dos valores, se producirá un error). +3. Verifique que ``location`` esté definido como tipo ``geo_point`` en el mapeo del índice de OpenSearch. +4. Verifique que se estén especificando tanto ``point`` como ``distance`` (un ``point`` sin ``distance`` será ignorado). + +No Se Devuelven Resultados de Búsqueda +--------------------------------------- + +1. Verifique que existan documentos dentro del rango de distancia especificado. +2. Verifique que los valores de latitud y longitud estén dentro del rango correcto (latitud: -90 a 90, longitud: -180 a 180). +3. Verifique que la unidad de distancia esté especificada correctamente. + +La Información de Ubicación No Aparece en la Respuesta de la API +----------------------------------------------------------------- + +El campo ``location`` no se incluye en la respuesta de la API de forma predeterminada. +Para incluir las coordenadas en los resultados de búsqueda, configure en ``fess_config.properties`` +tanto ``query.additional.response.fields=location`` como ``query.additional.api.response.fields=location`` +y reinicie |Fess|. + +La Información de Ubicación No Se Registra Correctamente +--------------------------------------------------------- + +1. Verifique que el campo ``location`` esté configurado correctamente durante el rastreo. +2. Verifique que la latitud y la longitud de la fuente de datos se obtengan correctamente. +3. Al configurar la información de ubicación mediante script, verifique que el formato de cadena sea ``latitud,longitud``. + +Información de Referencia +========================== + +Para obtener detalles sobre la búsqueda por geolocalización, consulte los siguientes recursos: + +- `OpenSearch Geo Queries `_ +- `OpenSearch Geo Point `_ +- `Geolocation API (MDN) `_ diff --git a/es/15.10/config/search-scroll.rst b/es/15.10/config/search-scroll.rst new file mode 100644 index 000000000..51789434f --- /dev/null +++ b/es/15.10/config/search-scroll.rst @@ -0,0 +1,452 @@ +========================================== +Obtención Masiva de Resultados de Búsqueda +========================================== + +Descripción General +=================== + +En las búsquedas normales de |Fess|, solo se muestra un número limitado de resultados de búsqueda mediante la función de paginación. +Si desea obtener todos los resultados de búsqueda de una sola vez, utilice la función de Búsqueda Scroll (Scroll Search). + +Esta función es útil cuando necesita procesar todos los resultados de búsqueda, como en exportaciones masivas de datos, copias de seguridad y análisis de grandes volúmenes de datos. + +Casos de Uso +============ + +La búsqueda scroll es adecuada para los siguientes propósitos: + +- Exportación completa de resultados de búsqueda +- Obtención de grandes volúmenes de datos para análisis +- Obtención de datos en procesos por lotes +- Sincronización de datos con sistemas externos +- Recopilación de datos para generación de informes + +.. warning:: + La búsqueda scroll devuelve grandes volúmenes de datos, por lo que consume más recursos del servidor en comparación con las búsquedas normales. Habilítela solo cuando sea necesario. + +Método de Configuración +======================= + +Habilitación de la Búsqueda Scroll +------------------------------------ + +Por defecto, la búsqueda scroll está deshabilitada por motivos de seguridad y rendimiento. +Para habilitarla, modifique la siguiente configuración en ``app/WEB-INF/classes/fess_config.properties`` (en paquetes RPM/DEB, +``/etc/fess/fess_config.properties``). + +:: + + api.search.scroll=true + +.. note:: + Después de cambiar la configuración, es necesario reiniciar |Fess|. + +Duración del Contexto de Scroll +--------------------------------- + +La duración del contexto de scroll de la búsqueda scroll está fijada internamente en |Fess| en ``1m`` (1 minuto). +Este valor no se puede cambiar desde ``fess_config.properties``. + +.. note:: + Existe una configuración llamada ``index.scroll.search.timeout``, pero esta se utiliza para operaciones internas que implican actualización o eliminación del índice (update by query / delete by query) y no afecta al tiempo de espera de esta función (scroll de búsqueda). + +Configuración de Campos de Respuesta +-------------------------------------- + +Puede personalizar los campos que se incluyen en la respuesta de los resultados de búsqueda. +Por defecto, se devuelven muchos campos, pero puede especificar campos adicionales. + +:: + + query.additional.scroll.response.fields=content + query.additional.api.response.fields=content + +Al especificar múltiples campos, enumérelos separados por comas. + +.. note:: + El campo ``content`` no está incluido en la respuesta predeterminada. Para obtener el texto + completo se necesitan las dos configuraciones anteriores. ``query.additional.scroll.response.fields`` + añade el campo a los que se obtienen del índice, y ``query.additional.api.response.fields`` lo añade a los + campos que la API puede devolver. Con solo una de ellas, ``content`` no se emite. + +Método de Uso +============= + +Uso Básico +---------- + +Para acceder a la búsqueda scroll, utilice la siguiente URL. + +:: + + http://localhost:8080/api/v2/documents/all?q=palabra_clave_búsqueda + +Los resultados de búsqueda se devuelven en formato NDJSON (Newline Delimited JSON). +Cada línea representa un documento en formato JSON. + +**Ejemplo:** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=Fess" + +Parámetros de Solicitud +------------------------ + +En la búsqueda scroll, puede utilizar los siguientes parámetros. + +.. note:: + La búsqueda scroll solo admite el método GET. Con los métodos que modifican el estado, como ``POST``, + la validación del token CSRF se realiza primero, por lo que una solicitud sin una cabecera + ``X-Fess-CSRF-Token`` válida recibe ``403 Forbidden`` (``forbidden``) (consulte :doc:`../api/api-overview`). + Con un token válido se devuelve ``405 Method Not Allowed`` (``method_not_allowed``). + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Nombre del Parámetro + - Descripción + * - ``q`` + - Consulta de búsqueda (obligatorio) + * - ``num`` + - Número de registros a obtener en cada scroll (predeterminado: 10, máximo: 100) + * - ``fields.label`` + - Filtrado por etiqueta + +.. note:: + El valor máximo de ``num`` se controla mediante ``paging.search.page.max.size`` (predeterminado: 100). + Si se especifica un valor superior al máximo, se recortará automáticamente al valor máximo. + El valor predeterminado se toma de ``paging.search.page.size`` (predeterminado: 10). + Si se especifica un valor de 0 o inferior en ``num``, se devuelve un error (``INVALID_REQUEST``). + +Especificación de Consulta de Búsqueda +--------------------------------------- + +Puede especificar consultas de búsqueda de la misma manera que en las búsquedas normales. + +**Ejemplo: Búsqueda por palabra clave** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=motor_búsqueda" + +**Ejemplo: Búsqueda con campo especificado** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=title:Fess" + +**Ejemplo: Obtención completa (sin condiciones de búsqueda)** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=*:*" + +Especificación del Número de Registros a Obtener +-------------------------------------------------- + +Puede cambiar el número de registros a obtener en cada scroll. + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=Fess&num=100" + +.. note:: + Si el parámetro ``num`` es demasiado grande, aumentará el uso de memoria. + El valor máximo predeterminado es 100. Si necesita un valor mayor, + modifique la configuración ``paging.search.page.max.size``. + +Filtrado por Etiqueta +---------------------- + +Puede obtener solo los documentos que pertenecen a una etiqueta específica. + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=*:*&fields.label=public" + +Acerca del Control de Acceso +------------------------------ + +.. note:: + En la búsqueda scroll, al igual que en las búsquedas normales, se aplica el control de acceso basado en roles (RBAC). + Solo se devuelven los documentos a los que se puede acceder según la información de roles de la solicitud, + por lo que los documentos sin permiso de visualización no se incluyen en los resultados. + +.. warning:: + El endpoint de la búsqueda scroll no requiere autenticación de forma predeterminada (cualquiera puede acceder a él). + Sin embargo, los documentos devueltos son filtrados por el control de acceso basado en roles descrito anteriormente. + Si desea restringir el acceso al propio endpoint, configure restricciones de dirección IP o + autenticación mediante un proxy inverso u otro mecanismo. + +Formato de Respuesta +==================== + +Formato NDJSON +-------------- + +La respuesta de la búsqueda scroll se devuelve en formato NDJSON (Newline Delimited JSON). +El Content-Type es ``application/x-ndjson; charset=UTF-8``. +Cada línea representa un documento envuelto en el formato ``{"data": {...}}``. + +**Ejemplo:** + +:: + + {"data":{"url":"http://example.com/page1","title":"Page 1","digest":"..."}} + {"data":{"url":"http://example.com/page2","title":"Page 2","digest":"..."}} + {"data":{"url":"http://example.com/page3","title":"Page 3","digest":"..."}} + +.. note:: + Cada documento se almacena bajo la clave ``data``. En el lado del cliente, tras parsear cada línea, + acceda al valor de la clave ``data``. + +Comportamiento ante Errores +----------------------------- + +Si se produce un error en el servidor después de que ha comenzado el envío del stream, se emite +en la última línea de la respuesta la siguiente línea terminadora de error: + +:: + + {"error":{"code":"internal_error","message":"stream error"}} + +.. note:: + En el lado del cliente, puede determinar si el stream se completó correctamente o si se produjo + un error intermedio en el servidor verificando si la última línea contiene la clave ``error``. + Tenga en cuenta que si la escritura de la propia línea terminadora de error falla, no se emite + dicha línea y el stream finaliza de forma incompleta, por lo que trate también las desconexiones + inesperadas como errores. + +Campos de Respuesta +-------------------- + +Campos incluidos por defecto: + +- ``score``: Puntuación de búsqueda +- ``_id``: ID del documento (ID de documento de OpenSearch) +- ``doc_id``: ID del documento (interno de |Fess|) +- ``boost``: Valor de boost +- ``content_length``: Longitud del contenido +- ``host``: Nombre del host +- ``site``: Sitio +- ``last_modified``: Fecha y hora de la última modificación +- ``timestamp``: Marca de tiempo +- ``mimetype``: Tipo MIME +- ``filetype``: Tipo de archivo +- ``filename``: Nombre de archivo +- ``created``: Fecha y hora de creación +- ``title``: Título +- ``digest``: Extracto del contenido +- ``url``: URL del documento +- ``thumbnail``: Miniatura +- ``click_count``: Número de clics +- ``favorite_count``: Número de favoritos +- ``has_cache``: Disponibilidad de caché +- ``content_title``: Título para visualización +- ``content_description``: Extracto del contenido para visualización +- ``url_link``: URL de enlace para visualización +- ``site_path``: Ruta del sitio + +.. note:: + Los campos efectivamente emitidos se limitan a los campos permitidos como respuesta de la API. + Los campos sin valor no se emiten. + +.. note:: + ``content`` (texto completo) no está incluido por defecto. + Se emite si se agrega tanto a ``query.additional.scroll.response.fields`` como a + ``query.additional.api.response.fields`` (consulte Configuración de Campos de Respuesta). + +Ejemplos de Procesamiento de Datos +==================================== + +Ejemplo de Procesamiento en Python +------------------------------------- + +.. code-block:: python + + import requests + import json + + # Ejecutar búsqueda scroll + url = "http://localhost:8080/api/v2/documents/all" + params = { + "q": "Fess", + "num": 100 + } + + response = requests.get(url, params=params, stream=True) + + # Procesar respuesta NDJSON línea por línea + for line in response.iter_lines(): + if line: + record = json.loads(line) + if "error" in record: + # Se produjo un error durante el stream + print("stream error:", record["error"]) + break + doc = record["data"] + print(f"Title: {doc.get('title')}") + print(f"URL: {doc.get('url')}") + print("---") + +Guardar en Archivo +------------------ + +Ejemplo de cómo guardar los resultados de búsqueda en un archivo: + +.. code-block:: bash + + curl "http://localhost:8080/api/v2/documents/all?q=*:*" > all_documents.ndjson + +Conversión a CSV +---------------- + +Ejemplo de conversión a CSV utilizando el comando jq: + +.. code-block:: bash + + curl "http://localhost:8080/api/v2/documents/all?q=Fess" | \ + jq -r '.data | [.url, .title, .score] | @csv' > results.csv + +Análisis de Datos +----------------- + +Ejemplo de análisis de datos obtenidos: + +.. code-block:: python + + import json + import pandas as pd + + # Leer archivo NDJSON (extrayendo la clave data de cada línea) + documents = [] + with open('all_documents.ndjson', 'r') as f: + for line in f: + record = json.loads(line) + if "data" in record: + documents.append(record["data"]) + + # Convertir a DataFrame + df = pd.DataFrame(documents) + + # Estadísticas básicas + print(f"Total documents: {len(df)}") + print(f"Average score: {df['score'].mean()}") + + # Análisis de dominios de URL + df['domain'] = df['url'].apply(lambda x: x.split('/')[2]) + print(df['domain'].value_counts()) + +Rendimiento y Mejores Prácticas +================================= + +Uso Eficiente +------------- + +1. **Configuración Apropiada del Parámetro num** + + - Si es demasiado pequeño, aumenta la sobrecarga de comunicación + - Si es demasiado grande, aumenta el uso de memoria + - Máximo predeterminado: 100 + +2. **Optimización de Condiciones de Búsqueda** + + - Especifique condiciones de búsqueda para obtener solo los documentos necesarios + - Ejecute la obtención completa solo cuando sea realmente necesario + +3. **Uso en Horarios de Baja Demanda** + + - Ejecute la obtención de grandes volúmenes de datos durante períodos de baja carga del sistema + +4. **Uso en Procesos por Lotes** + + - Ejecute sincronizaciones de datos periódicas como trabajos por lotes + +Optimización del Uso de Memoria +--------------------------------- + +Al procesar grandes volúmenes de datos, utilice procesamiento en streaming para reducir el uso de memoria. + +.. code-block:: python + + import requests + import json + + url = "http://localhost:8080/api/v2/documents/all" + params = {"q": "*:*", "num": 100} + + # Procesar en streaming + with requests.get(url, params=params, stream=True) as response: + for line in response.iter_lines(decode_unicode=True): + if line: + record = json.loads(line) + if "error" in record: + break + # Procesar documento + process_document(record["data"]) + +Consideraciones de Seguridad +============================== + +Restricciones de Acceso +------------------------ + +Dado que la búsqueda scroll devuelve grandes volúmenes de datos, configure restricciones de acceso apropiadas. +El endpoint en sí no requiere autenticación de forma predeterminada, por lo que considere las siguientes +medidas según sea necesario. + +1. **Restricción por Dirección IP** + + Permitir acceso solo desde direcciones IP específicas + +2. **Autenticación de API** + + Utilizar tokens de API o autenticación básica mediante un proxy inverso u otro mecanismo + +3. **Control de Acceso Basado en Roles** + + Los documentos devueltos son filtrados por el control de acceso basado en roles de |Fess| + +Limitación de Tasa +------------------- + +Se recomienda configurar limitación de tasa en el proxy inverso para evitar accesos excesivos. + +Solución de Problemas +====================== + +La Búsqueda Scroll No Está Disponible +--------------------------------------- + +1. Verifique que ``api.search.scroll`` esté configurado como ``true``. +2. Verifique que haya reiniciado |Fess|. +3. Revise los registros de errores. + +Se Produce un Error de Tiempo de Espera +----------------------------------------- + +1. Reduzca el parámetro ``num`` para distribuir el procesamiento. +2. Refine las condiciones de búsqueda para reducir la cantidad de datos obtenidos. + +Error de Memoria Insuficiente +------------------------------ + +1. Reduzca el parámetro ``num``. +2. Aumente el tamaño de memoria heap de |Fess|. +3. Verifique el tamaño de memoria heap de OpenSearch. + +La Respuesta Está Vacía +------------------------ + +1. Verifique que la consulta de búsqueda sea correcta. +2. Verifique que las etiquetas o condiciones de filtro especificadas sean correctas. +3. Los documentos sin permiso de visualización no se incluyen en los resultados debido al control de acceso basado en roles. Verifique la configuración de roles de la solicitud. + +Información de Referencia +========================== + +- :doc:`search-basic` - Detalles de la función de búsqueda +- :doc:`search-advanced` - Configuración relacionada con la búsqueda +- `OpenSearch Scroll API `_ diff --git a/es/15.10/config/search-semantic.rst b/es/15.10/config/search-semantic.rst new file mode 100644 index 000000000..70d0e7a3c --- /dev/null +++ b/es/15.10/config/search-semantic.rst @@ -0,0 +1,987 @@ +================================================================= +Búsqueda Semántica (Chunking de Contenido + Búsqueda Vectorial) +================================================================= + +Descripción general +==================== + +En |Fess| 15.10, la **función de chunking de contenido** — que divide el cuerpo de los documentos +en chunks y genera y almacena un vector de embedding para cada chunk — se ha integrado en el +núcleo. Los vectores generados se utilizan para dos propósitos: + +- **Búsqueda semántica**: una búsqueda híbrida que combina la búsqueda por palabras clave (BM25) + y la búsqueda vectorial mediante Rank Fusion. Los documentos que son semánticamente cercanos a + la consulta pueden coincidir incluso sin una superposición exacta de palabras clave. +- **Modo de búsqueda IA (RAG)**: al generar una respuesta, solo se seleccionan como contexto del + LLM los chunks semánticamente más cercanos a la pregunta, lo que mejora la calidad de la + respuesta y la eficiencia de tokens. + +Todo esto está deshabilitado de forma predeterminada. A menos que lo habilite, |Fess| continúa +funcionando exactamente igual que antes, utilizando únicamente la búsqueda por palabras clave. Si +está actualizando |Fess| desde la versión 15.7 o anterior, o si utilizaba el plugin +``fess-webapp-semantic-search``, consulte :ref:`semantic-search-migration`. + +Flujo de procesamiento +------------------------ + +1. El rastreador indexa los documentos como de costumbre (en este momento no existen chunks). +2. El trabajo del programador **Content Chunk Vector Indexer** busca documentos no procesados, + divide su contenido (el campo ``content``) en chunks, genera vectores de embedding y los + almacena en el campo ``content_chunk_vector``. En ese momento, el propio campo ``content`` + también se reescribe como el array de chunks (``content_length`` conserva su valor original). +3. El resultado de ese procesamiento se registra en el campo ``content_chunk_status`` + (descrito más abajo). +4. Cuando ``content_chunker.search.enabled=true``, el buscador semántico participa en Rank + Fusion en el momento de la búsqueda. + +Requisitos previos +==================== + +- **OpenSearch con el plugin k-NN**: En |Fess| 15.10, el mapeo del índice de búsqueda + (``fess.search``) siempre incluye el campo ``content_chunk_vector`` (de tipo ``nested``, cuyo + subcampo ``vector`` es el tipo ``knn_vector`` para ANN), y la configuración del índice siempre + incluye ``index.knn: true``, independientemente de si la función de chunking de contenido está + habilitada. Como resultado, si OpenSearch no tiene instalado el plugin k-NN, la creación de un + nuevo índice falla directamente y |Fess| no puede arrancar. + + .. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Configuración + - Compatibilidad con el plugin k-NN + * - Docker (``ghcr.io/codelibs/fess-opensearch``), los paquetes RPM/DEB (que siempre se + conectan a un OpenSearch externo instalado por separado) u otro OpenSearch externo + (distribución estándar) + - Totalmente compatible, incluyendo ``faiss``. + * - La **distribución mínima** de un OpenSearch externo + - **No compatible.** No incluye el plugin k-NN, por lo que la creación de un nuevo índice + falla. + + ``nmslib`` nunca es un valor aceptado para ``content_chunker.search.knn.engine`` en ninguna de + las configuraciones anteriores: ``content_chunk_vector`` es un campo ``nested``, y el plugin + k-NN solo admite campos nested con los motores ``lucene``/``faiss`` (``nmslib`` también está + obsoleto y restringido a partir de OpenSearch 3.0). Si se establece, se aplica el valor + predeterminado ``lucene`` con una advertencia; consulte la Referencia de configuración más abajo + para conocer los valores aceptados del resto de ajustes ANN. + +- **Versión de OpenSearch de un clúster externo**: la configuración del índice ``fess.search`` + incluida siempre envía ``index.knn`` y ``knn.derived_source.enabled`` (en + ``fess_indices/fess.json`` y en ``fess_indices/_vanilla/fess.json``, que usan ``vanilla``, ``aws`` y el obsoleto ``cloud``). Este último es un ajuste + relativamente reciente del plugin k-NN, y en un OpenSearch antiguo que no lo reconoce la + creación del índice falla, esté o no instalado el plugin k-NN. Consulte + :doc:`../install/prerequisites` para conocer las versiones de OpenSearch compatibles con + |Fess| 15.10. + +- **Proveedor de embedding**: use uno de los siguientes. + +.. list-table:: + :header-rows: 1 + :widths: 20 25 55 + + * - Valor de configuración + - Proporcionado por + - Descripción + * - ``opensearch`` + - Núcleo de |Fess| (integrado) + - Utiliza un modelo de embedding desplegado en OpenSearch ML Commons. No requiere plugin + adicional. Configuración predeterminada. + * - ``ollama`` + - Plugin ``fess-llm-ollama`` + - Utiliza un modelo de embedding de Ollama (p. ej., ``nomic-embed-text``). + * - ``openai`` + - Plugin ``fess-llm-openai`` + - Utiliza la API de embeddings de OpenAI. + * - ``gemini`` + - Plugin ``fess-llm-gemini`` + - Utiliza la API de embeddings de Google Gemini. + * - ``bedrock`` + - Plugin ``fess-llm-bedrock`` + - Utiliza Amazon Titan Text Embeddings V2 o Cohere Embed a través de Amazon Bedrock. + * - ``none`` + - Núcleo de |Fess| (integrado) + - Solo divide los documentos en chunks; no se genera ningún vector (modo solo chunking). + +Referencia de configuración +============================== + +Todas las configuraciones ``content_chunker.*`` residen en un único canal: las **propiedades del +sistema** (``system.properties``). Configúrelas en ``app/WEB-INF/conf/system.properties`` (en +RPM/DEB, ``/etc/fess/system.properties``; en Docker, ``/opt/fess/system.properties``), o +proporcione un valor inicial con la opción de inicio ``-Dfess.system.``. Los valores se +recargan en tiempo de ejecución, por lo que la mayoría de las configuraciones surten efecto +inmediatamente después de cambiarlas. La única excepción es habilitar +``content_chunker.search.enabled`` (``false`` → ``true``): dado que el buscador semántico solo se +registra al iniciar, **este cambio requiere un reinicio para surtir efecto**. + +.. note:: + + Las claves ``content_chunker.*`` solo se leen desde el canal ``system.properties``. Escribirlas + en ``fess_config.properties`` o en ``-Dfess.config.`` no surte ningún efecto, así que + configúrelas siempre en ``system.properties``. Tenga además en cuenta que la pantalla de + administración **Información del sistema > Información de configuración** es una vista de + **solo lectura** de los valores actuales: desde ella no se pueden establecer las claves + ``content_chunker.*``. + +Configuraciones en system.properties +--------------------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 40 15 45 + + * - Propiedad + - Predeterminado + - Descripción + * - ``content_chunker.enabled`` + - ``false`` + - Interruptor principal de toda la función de chunking de contenido + * - ``content_chunker.chunker.name`` + - ``length`` + - Método de chunking + * - ``content_chunker.length.chunk_size`` + - ``800`` + - Número objetivo de caracteres por chunk. Con la división consciente de límites activada + (valor predeterminado) se trata de un objetivo y no de un máximo estricto: un chunk puede + ser hasta ``boundary.lookback_percent`` más corto y hasta ``max(lookahead, 32)`` caracteres + más largo (de 640 a 840 caracteres con los valores predeterminados). Reserve ese margen + frente al límite de tokens del modelo de embeddings + * - ``content_chunker.length.overlap`` + - ``0`` + - Número de caracteres que se superponen entre chunks. El punto de reinicio también se + ajusta a un límite, y ese ajuste solo puede adelantarlo, por lo que la superposición + efectiva queda entre este valor y el doble de este valor + * - ``content_chunker.length.boundary.enabled`` + - ``true`` + - Desplaza cada corte a un límite de texto razonable en lugar de cortar exactamente a + los ``chunk_size`` caracteres. Los candidatos se agrupan en niveles y gana el más cercano + del nivel más alto presente: salto de línea o fin de frase; si no, separador de cláusula o + espacio; si no, cambio de sistema de escritura. Con ``false`` se recupera el + comportamiento anterior de longitud fija + * - ``content_chunker.length.boundary.lookback_percent`` + - ``20`` + - Hasta dónde se puede buscar un límite antes del corte ideal, como porcentaje de + ``chunk_size`` (0-50) + * - ``content_chunker.length.boundary.lookahead_percent`` + - ``5`` + - Hasta dónde se puede buscar un fin de frase o un salto de línea después del corte + ideal, como porcentaje de ``chunk_size`` (0-25). Solo se usa si no se encontró nada + antes del corte + * - ``content_chunker.max_chunks_per_document`` + - ``1000`` + - Número máximo de chunks por documento. Los documentos que superan este valor se marcan + como ``skipped`` y no reciben embeddings. Como la división consciente de + límites acorta los chunks, un documento genera entre un 3 % y un 25 % más de chunks que + con longitud fija, por lo que un corpus de documentos muy grandes puede necesitar un valor + mayor aquí + * - ``content_chunker.embedding.name`` + - ``opensearch`` + - Proveedor de embedding (``opensearch`` / ``ollama`` / ``openai`` / ``gemini`` / ``bedrock`` / ``none``) + * - ``content_chunker.embedding.dimension`` + - ``768`` + - Dimensión del vector de embedding. Este valor se utiliza al crear el mapeo, por lo que + **debe** coincidir con la dimensión del modelo de embedding que utilice. Este valor tiene + dos rutas de lectura, con comportamientos distintos. Al crear el mapeo del índice, si el + valor no está establecido se aplica ``768`` **sin ninguna advertencia**, y si está vacío, + no es numérico, es 0 o negativo, o supera ``16000`` (el máximo propio del plugin k-NN), se + aplica ``768`` con una advertencia. En cambio, al ejecutar el + proceso de embedding no hay ningún valor de respaldo: un valor sin establecer, no numérico + o 0 o negativo produce un error. Un valor superior a ``16000`` no se rechaza en tiempo de + ejecución, por lo que solo el mapeo acaba creado con ``768`` y se produce un desajuste de + dimensión. La dimensión del mapeo no se puede cambiar una vez creado el índice; para + recuperarse de un índice creado con el valor sin establecer, consulte *Si el índice se creó + sin dimensión* en *Notas* + * - ``content_chunker.job.concurrency`` + - ``2`` + - Número de workers paralelos para el trabajo del indexador + * - ``content_chunker.job.bulk_size`` + - ``20`` + - Número de documentos obtenidos y escritos por lote + * - ``content_chunker.job.max_documents_per_run`` + - ``-1``\ (ilimitado) + - Número máximo de documentos procesados por ejecución del trabajo. Cualquier valor de + ``0`` o menor se trata como ilimitado + * - ``content_chunker.job.retry_failed`` + - ``false`` + - Cuando se establece en ``true``, los documentos que finalizaron la ejecución anterior con + ``content_chunk_status=fail`` también se incluyen en el objetivo de procesamiento de la + siguiente ejecución. No existe reintento automático ni seguimiento del número de + intentos; el flujo de trabajo previsto es corregir la causa subyacente y luego habilitar + esto temporalmente para reintentar + * - ``content_chunker.chat.top_k`` + - ``3`` + - Número de chunks seleccionados cuando el modo de búsqueda IA genera una respuesta + * - ``content_chunker.search.enabled`` + - ``false`` + - Integración con Rank Fusion para la búsqueda semántica (**habilitarlo requiere un + reinicio**) + * - ``content_chunker.search.min_score`` + - (sin establecer) + - Similitud de coseno mínima (0-1) requerida para incluir un resultado. Sin este valor no + hay corte. En el modo ``ann``, si ``search.knn.space_type`` no es ``cosinesimil`` no se + puede definir un corte basado en el coseno, por lo que se omite con una advertencia + * - ``content_chunker.search.knn.method`` + - ``hnsw`` + - Método de índice ANN. Actualmente ``hnsw`` es el único valor aceptado; cualquier otro valor + aplica el valor predeterminado ``hnsw`` con una advertencia (se refleja en el mapeo; + cambiarlo requiere recrear el índice) + * - ``content_chunker.search.knn.engine`` + - ``lucene`` + - Motor ANN. Solo se aceptan ``lucene`` o ``faiss`` (véase Requisitos previos más arriba); + cualquier otro valor aplica el valor predeterminado ``lucene`` con una advertencia (se + refleja en el mapeo; cambiarlo requiere recrear el índice) + * - ``content_chunker.search.knn.space_type`` + - ``cosinesimil`` + - Espacio de distancia. Solo se aceptan ``cosinesimil``, ``innerproduct`` o ``l2``; cualquier + otro valor aplica el valor predeterminado ``cosinesimil`` con una advertencia (se refleja + en el mapeo; cambiarlo requiere recrear el índice) + * - ``content_chunker.search.knn.k`` + - ``100`` + - Número de vecinos recuperados por shard en la consulta ANN. Cuando la fusión la realiza + |Fess|, el valor efectivo nunca baja de ``rank.fusion.window_size`` dividido por el número + de buscadores (200 / 2 = 100 de forma predeterminada), por lo que un valor menor no tiene + efecto. Cuando la fusión la realiza el motor de búsqueda, este valor se usa tal cual + * - ``content_chunker.search.knn.param.ef_search`` + - (sin establecer) + - El parámetro ``ef_search`` para las consultas ANN + +.. note:: + + Con ``content_chunker.length.boundary.enabled=true`` (valor predeterminado), + ``content_chunker.length.chunk_size`` pasa a ser un objetivo en lugar de un límite estricto: + cada corte se desplaza hasta el candidato más cercano del nivel más alto presente en la + ventana de búsqueda. Un salto de línea o un fin de frase gana a cualquier separador de + cláusula o espacio por muy atrás que quede este, y esos ganan a un cambio de sistema de + escritura. Solo se desplaza el punto de corte; no se pierde ningún carácter, por lo que + concatenar los chunks de un documento sigue reproduciendo exactamente su contenido. La + búsqueda hacia adelante puede superar ``chunk_size`` en hasta + ``content_chunker.length.boundary.lookahead_percent``. Puede producirse un segundo exceso, + independiente, de hasta 32 caracteres cuando un corte caería en medio de un clúster de + grafemas (una marca combinante, un selector de variación o una secuencia de emojis unida por + un conector de ancho cero; ZWJ); este ignora ``lookahead_percent`` y puede ocurrir incluso con + ``0``. Los dos tipos de exceso nunca se producen en el mismo corte, de modo que con los + valores predeterminados un chunk va de 640 a 840 caracteres. Como los chunks resultan más + cortos en promedio, un documento genera entre un 3 % y un 25 % más de chunks que con longitud + fija (véase ``content_chunker.max_chunks_per_document``). Establecer + ``content_chunker.length.boundary.enabled`` en ``false``, o ambos porcentajes en ``0``, + reproduce exactamente el comportamiento anterior de longitud fija. Cambiar cualquiera de estos + ajustes solo afecta a los documentos divididos a partir de ese momento: un documento ya + almacenado como array de chunks conserva sus límites hasta que se vuelve a rastrear. + +.. note:: + + ``content_chunker.length.chunk_size`` se especifica en caracteres, pero un modelo de embedding + solo puede asimilar texto hasta su límite de tokens. |Fess| no trunca el texto sometido al + embedding, por lo que la parte que supera ese límite puede no quedar reflejada en el vector. + Elija ``chunk_size`` según el límite de entrada del modelo que utilice. Por ejemplo, medido + con ``paraphrase-multilingual-MiniLM-L12-v2`` (128 tokens como máximo), la parte reflejada en + el vector fue de unos 440 caracteres en inglés y unos 210 caracteres en japonés (varía según + el texto). Con este modelo, la parte final de un chunk con el valor predeterminado + ``chunk_size=800`` no queda reflejada en el vector. + +.. note:: + + Los parámetros HNSW ``m`` y ``ef_construction`` están codificados de forma fija en + ``doc.json`` (``m=16`` / ``ef_construction=100``) y no se pueden cambiar mediante + configuración. + +Configuración de conexión para el proveedor opensearch +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Configuración de conexión para el proveedor integrado ``opensearch`` (OpenSearch ML Commons). +Estos se establecen en el mismo archivo ``system.properties`` que se indicó anteriormente. + +.. list-table:: + :header-rows: 1 + :widths: 50 20 30 + + * - Propiedad + - Predeterminado + - Descripción + * - ``content_chunker.embedding.opensearch.model.id`` + - (requerido) + - ID del modelo ya desplegado en ML Commons + * - ``content_chunker.embedding.opensearch.api.url`` + - Dirección del motor de búsqueda + - Endpoint de la API de ML Commons. Sin establecer, se usa de forma predeterminada el motor + de búsqueda que |Fess| ya está utilizando (p. ej., ``http://localhost:9200``) + * - ``content_chunker.embedding.opensearch.username`` / ``password`` + - Credenciales del motor de búsqueda + - Sin establecer, recurre a las credenciales utilizadas para la conexión al motor de + búsqueda — pero solo mientras ``api.url`` no esté configurado (es decir, el destino es el + mismo clúster que |Fess| ya utiliza). Una vez configurado ``api.url``, este mecanismo de + respaldo no se aplica. + * - ``content_chunker.embedding.opensearch.timeout`` + - ``60000`` + - Tiempo de espera de la solicitud (ms) + * - ``content_chunker.embedding.opensearch.connect.timeout`` + - ``5000`` + - Tiempo de espera de conexión (ms) + * - ``content_chunker.embedding.opensearch.retry.max`` + - ``3`` + - Número máximo de intentos, incluido el primero, para errores transitorios (429, 5xx, + etc.). No es el número de reintentos: ``3`` significa como máximo tres solicitudes en + total, con dos esperas entre ellas. Un valor de ``1`` o menor significa que no hay + reintento + * - ``content_chunker.embedding.opensearch.retry.base.delay.ms`` + - ``2000`` + - Retraso base de reintento (ms) + * - ``content_chunker.embedding.opensearch.availability.check.interval`` + - ``60`` + - Intervalo entre verificaciones de disponibilidad del proveedor (segundos) + * - ``content_chunker.embedding.opensearch.document.prefix`` / ``query.prefix`` + - (vacío) + - Prefijo antepuesto al texto del documento/consulta antes del embedding + +.. warning:: + + El contenido de ``system.properties`` se puede consultar en la pantalla de administración + **Información del sistema > Información de configuración**, en el panel **Propiedades de la + aplicación**. Allí, ``content_chunker.embedding.opensearch.password`` aparece enmascarado como + ``XXXXXXXX``, pero ``username`` se muestra tal cual. Además, los valores indicados con + ``-Dfess.system.`` se muestran **sin enmascarar** en el panel **Propiedades del sistema** + de esa misma pantalla, así que escriba las credenciales en ``system.properties`` y no en las + opciones de inicio. + +Otros proveedores (ollama / openai / gemini / bedrock) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +El proveedor ``ollama`` (plugin ``fess-llm-ollama``) utiliza el mismo estilo de configuración +bajo el prefijo ``content_chunker.embedding.ollama.`` (``api.url`` es ``http://localhost:11434`` +de forma predeterminada, ``model`` es ``embeddinggemma`` de forma predeterminada, y +``document.prefix`` / ``query.prefix`` son ``title: none | text:`` / +``task: search result | query:`` de forma predeterminada respectivamente). Si utiliza un modelo +del estilo de ``nomic-embed-text``, establezca explícitamente ``search_document:`` / +``search_query:`` en ``document.prefix`` / ``query.prefix``. Estos prefijos se concatenan con el +texto que se va a incrustar tal cual (los espacios circundantes no se recortan), por lo que tanto +los valores predeterminados anteriores como ``search_document:`` / ``search_query:`` +**incluyen un espacio final**. Recuerde el espacio separador si define un prefijo usted mismo. +Los proveedores ``openai`` y +``gemini`` se configuran de la misma manera, bajo los prefijos +``content_chunker.embedding.openai.`` y ``content_chunker.embedding.gemini.`` respectivamente. +Consulte la documentación de cada plugin para obtener la lista completa de configuraciones. +El proveedor ``bedrock`` utiliza el prefijo ``content_chunker.embedding.bedrock.``, y +``content_chunker.embedding.dimension`` debe ser un tamaño que produzca el modelo configurado; +consulte :doc:`llm-bedrock`. + +Procedimiento de configuración (ejemplo con el proveedor opensearch) +======================================================================== + +Esta sección recorre un ejemplo de configuración utilizando el proveedor integrado ``opensearch`` +(ML Commons). + +1. Desplegar el modelo de embedding +-------------------------------------- + +Registre y despliegue un modelo de embedding en OpenSearch ML Commons. En un clúster de un solo +nodo, primero debe aplicar la siguiente configuración. + +.. code-block:: bash + + curl -XPUT "http://localhost:9200/_cluster/settings" \ + -H "Content-Type: application/json" -d ' + {"persistent": {"plugins.ml_commons.only_run_on_ml_node": false}}' + +Registre y despliegue el modelo (ejemplo: un modelo de embedding de oraciones de 384 +dimensiones): + +.. code-block:: bash + + # Registrar el modelo (obtenga model_id del task_id de la respuesta) + curl -XPOST "http://localhost:9200/_plugins/_ml/models/_register" \ + -H "Content-Type: application/json" -d ' + { + "name": "huggingface/sentence-transformers/all-MiniLM-L6-v2", + "version": "1.0.2", + "model_format": "TORCH_SCRIPT" + }' + + # Comprobar que la tarea ha terminado y obtener el model_id + # (cuando state pasa a COMPLETED, la respuesta incluye model_id) + curl "http://localhost:9200/_plugins/_ml/tasks/" + + # Desplegar + curl -XPOST "http://localhost:9200/_plugins/_ml/models//_deploy" + + # Verificar estado: model_state debería ser DEPLOYED + curl "http://localhost:9200/_plugins/_ml/models/" + +.. note:: + + Un modelo que aún esté en estado ``REGISTERED`` no se puede usar. Asegúrese de desplegarlo y + confirmar que ``model_state`` pase a ``DEPLOYED``. + +2. Configurar |Fess| +----------------------- + +``app/WEB-INF/conf/system.properties`` (en RPM/DEB, ``/etc/fess/system.properties``; en Docker, +``/opt/fess/system.properties``. Todo lo siguiente va en ese mismo archivo):: + + content_chunker.enabled=true + content_chunker.embedding.name=opensearch + content_chunker.embedding.dimension=384 + content_chunker.embedding.opensearch.model.id= + +Si además desea utilizar la búsqueda semántica, añada también lo siguiente:: + + content_chunker.search.enabled=true + +Reinicie |Fess| después de realizar estos cambios. + +3. Recrear el índice (al habilitar en una instalación existente) +---------------------------------------------------------------------- + +El mapeo del campo ``content_chunk_vector`` — incluyendo la dimensión y la configuración del +método ANN que configuró — se aplica **en el momento en que se crea de nuevo el índice** +``fess.search``. + +- **Instalaciones nuevas**: si aplica la configuración anterior a ``system.properties`` antes de + iniciar |Fess| por primera vez, el mapeo correcto se aplica automáticamente cuando se crea el + índice por primera vez, por lo que este paso no es necesario. +- **Si ya existe un índice** (es decir, si ya ha iniciado |Fess| al menos una vez): el índice en + ejecución no adopta el nuevo mapeo automáticamente, y un mapeo existente no se puede modificar + posteriormente. Recree el índice de la siguiente manera: + + Abra **Información del sistema > Mantenimiento**, y en **Reindexación** ejecútela con la + opción **Actualizar alias** habilitada. + + A continuación, puede confirmar que el índice recreado incluye ``index.knn: true`` en la + configuración del índice y un mapeo de ``content_chunk_vector`` con la dimensión y la + configuración del método ANN que estableció (``index.knn`` se aplica a la configuración del + índice y la configuración del método ANN al mapeo: son destinos distintos). + +.. warning:: + + La reindexación se ejecuta como una operación en segundo plano asíncrona, y la interfaz de + administración no muestra ninguna notificación de finalización. ``_cat/indices`` solo muestra + que el nuevo índice existe (estado, número de documentos, etc.) — no muestra a qué índice + apuntan los alias. Antes de continuar con el trabajo del indexador que se describe a + continuación, compruebe en su lugar ``_cat/aliases`` y confirme que tanto ``fess.search`` como + ``fess.update`` apuntan al nuevo índice; el registro de |Fess| solo registra una advertencia en + caso de fallo, por lo que un registro silencioso no es prueba de éxito, solo la ausencia de un + fallo conocido. El índice antiguo (el índice físico al que apuntaba anteriormente el alias + ``fess.search``, con el nombre ``fess.``) no se elimina automáticamente; elimínelo + manualmente cuando ya no lo necesite. Mientras existan ambos índices, espere que el uso de + disco del índice sea aproximadamente el doble de lo habitual. + +4. Habilitar el trabajo del indexador +------------------------------------------ + +El chunking y la generación de embeddings se realizan mediante el trabajo del programador +**Content Chunk Vector Indexer** (ID: ``content-chunk-vector-indexer``; deshabilitado de forma +predeterminada; programado como ``0 13 * * *``). + +Habilite este trabajo en **Sistema > Programador**, y luego ejecútelo una vez con **Iniciar +ahora**. A partir de ahí, los documentos no procesados se procesan según la programación +configurada (de forma predeterminada, todos los días a las 13:00), con independencia de que un +rastreo haya terminado o no. Este trabajo no está encadenado al trabajo de rastreo, así que si +desea procesarlos justo después de un rastreo, programe este trabajo a una hora posterior a la +hora prevista de finalización del rastreo. + +.. note:: + + En una implementación multinodo, recomendamos anclar este trabajo para que se ejecute + exactamente en un nodo. Ejecutarlo en todos los nodos a la vez no rompe la corrección, pero + cada nodo procesa y embebe los mismos documentos de forma redundante, multiplicando la carga + y el coste en su proveedor de embedding por el número de nodos. + + Anclarlo requiere **ambas** de las siguientes configuraciones — una sola de ellas no ancla el + trabajo. + + 1. **En el nodo donde desea ejecutar el trabajo**: establezca + ``scheduler.target.name=`` en + ``app/WEB-INF/classes/fess_config.properties`` (en RPM/DEB, + ``/etc/fess/fess_config.properties``; o mediante + ``-Dfess.config.scheduler.target.name=``), y luego reinicie ese nodo. + (El valor predeterminado está vacío; deje todos los demás nodos con el valor + predeterminado.) + 2. En la interfaz de administración, en **Sistema > Programador**, abra el trabajo Content + Chunk Vector Indexer y cambie su campo **Objetivo** de ``all`` al mismo identificador que + estableció en el paso 1, y luego guarde. + + Consulte :doc:`../admin/scheduler-guide` para saber qué significa el campo **Objetivo**. + Establecer ``scheduler.target.name`` por sí solo no ancla el trabajo si el campo + **Objetivo** se deja en ``all``: **no quedará anclado**. ``all`` se trata como un valor + especial que siempre coincide, por lo que solo el paso 1 o solo el paso 2 no son suficientes — + debe realizar ambos. + +.. warning:: + + Una vez anclado el trabajo, pulse **Iniciar ahora** también **desde la interfaz de + administración del nodo en el que estableció el identificador en el paso 1**. Si lo pulsa en + un nodo que no es el destino, la pantalla muestra igualmente el mensaje de éxito ("Se ha + iniciado el trabajo …"), pero el trabajo **no se ejecuta**, porque el campo **Objetivo** no + coincide (en el registro de ese nodo solo aparece una línea ``Ignoring job`` de nivel INFO). + +5. Verificar el estado de procesamiento +-------------------------------------------- + +Puede verificar el resultado de cada documento en su campo ``content_chunk_status``. + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Valor + - Significado + * - (campo ausente) + - Aún no procesado (se recogerá en la próxima ejecución del trabajo). Los documentos + también vuelven a este estado después de ser rastreados nuevamente + * - ``done`` + - Chunking y generación de vectores completados + * - ``chunked`` + - Solo chunking completado (modo solo chunking). Además del caso + ``embedding.name=none``, este estado también se produce cuando el plugin del proveedor + indicado en ``embedding.name`` no está instalado + * - ``skipped`` + - Procesamiento omitido. Incluye los documentos cuyo cuerpo está vacío (también si solo + contiene espacios en blanco), los documentos para los que no se generó ningún chunk y los + que superan ``max_chunks_per_document``. Si ``content_chunker.chunker.name`` indica un + chunker que no existe, no se encuentra ningún chunker y no se genera ningún chunk, por lo + que todos los documentos acaban en este estado. Es un estado terminal: volver a ejecutar + el trabajo no vuelve a procesar el documento + * - ``fail`` + - Procesamiento fallido (revise los registros). Es un estado terminal: de forma + predeterminada, volver a ejecutar el trabajo no vuelve a procesar el documento. Establezca + ``content_chunker.job.retry_failed`` en ``true`` para procesarlo de nuevo + +Puede verificar la distribución de estados consultando directamente el motor de búsqueda:: + + curl -XPOST "http://localhost:9200/fess.search/_search" \ + -H "Content-Type: application/json" -d ' + {"size": 0, "aggs": {"status": {"terms": {"field": "content_chunk_status", "missing": "pending"}}}}' + +Gracias a la opción ``missing``, los documentos que no tienen ``content_chunk_status`` (es decir, +los que aún no se han procesado) se agrupan en un bucket con la clave ``pending``. + +Evalúe el estado del trabajo de chunking según esta distribución de ``content_chunk_status``. Si +``pending`` disminuye y ``done`` (``chunked`` en el modo solo chunking) aumenta con cada +ejecución del trabajo, el trabajo avanza. Si aparece ``fail``, revise los registros de |Fess| +para conocer la causa. ``skipped`` es normal para documentos como los de cuerpo vacío, pero si +casi todos los documentos están en ``skipped``, sospeche de un valor incorrecto de +``content_chunker.chunker.name`` (cuando no se encuentra ningún chunker, se registra un mensaje +WARN ``Chunker not found``). + +.. warning:: + + Corregir la configuración no revierte por sí solo ``skipped`` ni ``fail``. Un documento + ``skipped`` no se recoge al volver a ejecutar el trabajo (un documento rastreado de nuevo + vuelve al estado sin procesar), y un documento ``fail`` solo se procesa de nuevo cuando + ``content_chunker.job.retry_failed`` es ``true``. Por ejemplo, si el trabajo se ejecutó con un + ``content_chunker.chunker.name`` incorrecto y todos los documentos pasaron a ``skipped``, + corrija el nombre, elimine ``content_chunk_status`` como se muestra a continuación y vuelva a + ejecutar el trabajo (el campo ``content`` de un documento ``skipped`` no se ha reescrito, por + lo que se puede procesar tal cual):: + + curl -XPOST "http://localhost:9200/fess.search/_update_by_query" \ + -H "Content-Type: application/json" -d ' + { + "query": {"term": {"content_chunk_status": "skipped"}}, + "script": {"source": "ctx._source.remove(\"content_chunk_status\")"} + }' + +Comportamiento de la búsqueda semántica +========================================== + +Establecer ``content_chunker.search.enabled=true`` registra el buscador semántico con Rank +Fusion, que luego fusiona los resultados de la búsqueda por palabras clave con los resultados de +la búsqueda vectorial. (Consulte :doc:`rank-fusion` para saber cómo funciona Rank Fusion.) +De forma predeterminada, |Fess| realiza la fusión por sí mismo; si establece +``rank.fusion.engine.enabled=true``, la realiza OpenSearch en su lugar (consulte +:ref:`rank-fusion-engine`). +En el momento de la búsqueda también se consulta ``content_chunker.enabled``: si +``content_chunker.enabled=false`` o ``content_chunker.embedding.name=none``, la búsqueda +semántica no se ejecuta aunque el buscador ya esté registrado (esta comprobación se realiza en +cada solicitud, por lo que no hace falta reiniciar). + +.. warning:: + + Dado que el buscador semántico se registra al iniciar, **habilitarlo requiere un reinicio**. + Deshabilitarlo (volver a establecer el valor en ``false``) se evalúa por solicitud, por lo que + surte efecto de inmediato. + +Modo exact y modo ann +------------------------ + +El método de búsqueda se elige automáticamente según el estado del índice. + +.. list-table:: + :header-rows: 1 + :widths: 12 44 44 + + * - Modo + - Condición + - Características + * - ``ann`` + - Un índice que tiene configuración de ``index.knn`` y método ANN + - Búsqueda aproximada del vecino más cercano usando HNSW. Adecuado para índices grandes + * - ``exact`` + - Cualquier otro caso (un índice al que le falta ``index.knn`` o la configuración del método + ANN, incluido el caso en que falla la comprobación del estado del índice) + - Cálculo exacto de similitud de coseno contra cada vector. Adecuado para índices pequeños + a medianos + +Cualquier índice ``fess.search`` creado nuevo bajo |Fess| 15.10 siempre tiene configuración de +``index.knn`` y de método ANN, independientemente del valor de +``content_chunker.search.enabled`` — por lo que normalmente siempre se usa el modo ``ann``. El +modo ``exact`` es un mecanismo de respaldo para índices más antiguos creados antes de que +existiera este mecanismo. Dado que la configuración k-NN no se puede añadir a un índice existente +posteriormente, cambiar un índice en modo ``exact`` al modo ``ann`` requiere recrear el índice +(consulte :ref:`semantic-search-migration`). Tenga en cuenta que el resultado de esta +comprobación se almacena en caché durante 60 segundos, por lo que justo después de recrear el +índice el cambio puede tardar hasta 60 segundos en reflejarse. + +Corte de puntuación +---------------------- + +Establecer ``content_chunker.search.min_score`` en una similitud de coseno (0-1) excluye de los +resultados de la búsqueda semántica los documentos cuyo mejor chunk no alcanza ese valor (la +puntuación de un documento es la de su mejor chunk, de modo que el corte actúa a nivel de +documento, no de chunk individual). Úselo para controlar el número de resultados cuando las +consultas sin superposición de vocabulario coinciden de forma demasiado amplia:: + + content_chunker.search.min_score=0.4 + +El valor configurado se interpreta como similitud de coseno tanto en el modo ``exact`` como en el +modo ``ann`` (internamente se convierte a la escala de puntuación de cada modo). + +.. note:: + + Este corte solo se aplica cuando ``content_chunker.search.knn.space_type`` es + ``cosinesimil`` (el valor predeterminado). En un índice en modo ``ann`` configurado con + ``innerproduct`` o ``l2`` no se puede definir la similitud de coseno, por lo que el corte se + omite y se registra una advertencia en cada una de esas búsquedas. + +Limitaciones +-------------- + +- Las condiciones con campo de la consulta (``label:``, ``site:``, ``filetype:``, rangos sobre + ``timestamp`` / ``last_modified``, etc.) se separan del texto que se convierte en embedding y se + aplican a la búsqueda vectorial como filtros. La consulta se examina ya **ensamblada**, por lo + que las operaciones que añaden internamente este tipo de condiciones - seleccionar una etiqueta, + filtrar mediante facetas, o el tipo de archivo, el sitio y el rango de fechas de la búsqueda + avanzada, incluidas las condiciones pasadas mediante los parámetros ``ex_q`` y ``fields.*`` - + siguen ejecutando la búsqueda semántica, acotada por las mismas condiciones que la búsqueda por + palabras clave. +- **La búsqueda semántica se omite** para las siguientes consultas, y solo se ejecuta la búsqueda + por palabras clave. + + - Un criterio de ordenación (el pseudocampo ``sort:``, o el parámetro ``sort``, que también se + añade internamente como ``sort:...``) + - Una frase (``"..."``), un comodín (``*`` ``?``), una búsqueda difusa (``~``) o un rango sobre + palabras que no indican ningún campo, incluida la frase de la búsqueda avanzada. El ``?`` de + medio ancho (ASCII) se interpreta como comodín, por lo que una pregunta en lenguaje natural + terminada en signo de interrogación ASCII, como «¿Qué es …?», también se omite (el ``？`` de + ancho completo no se ve afectado). + - Excluir una palabra (``-palabra``, ``NOT palabra``, incluidos los términos excluidos de la + búsqueda avanzada) o potenciarla (``palabra^2``) + - Una consulta cuyas condiciones no pueden separarse como filtro, como una palabra y una + condición unidas con ``OR`` + - ``allintitle:`` / ``allinurl:`` + - Una consulta que solo tiene condiciones, sin palabras que convertir en embedding + - Una consulta que no se puede analizar + +- También se omite cuando se combina con la búsqueda por geolocalización (un filtro geo) o la + búsqueda de documentos similares. +- El tratamiento de las páginas profundas depende de dónde se realiza la fusión. + + - Cuando la fusión la realiza |Fess| (el comportamiento predeterminado), el límite lo determina + ``rank.fusion.window_size`` (predeterminado ``200``); con los valores predeterminados, todos + los resultados a partir del número 101 provienen solo de la búsqueda por palabras clave. + - Cuando la fusión la realiza el motor de búsqueda (``rank.fusion.engine.enabled=true``), se + fusionan todas las páginas, pero la paginación se detiene en ``rank.fusion.pagination_depth`` + resultados (predeterminado ``1000``); no se puede solicitar una página posterior. + + Consulte :doc:`rank-fusion` para más detalles. +- Si el proveedor de embedding no está disponible o se produce un error de búsqueda, |Fess| + vuelve automáticamente a los resultados basados solo en palabras clave (la búsqueda en sí nunca + falla como resultado). +- El control de acceso basado en roles y en el host virtual también se aplica a los resultados de + la búsqueda semántica. + +Integración con el modo de búsqueda IA +========================================== + +Cuando el modo de búsqueda IA (:doc:`rag-chat`, ``rag.chat.enabled=true``) está habilitado, para +los documentos cuyo ``content_chunk_status`` es ``done``, la generación de respuestas calcula la +similitud con cada chunk y usa solo los ``content_chunker.chat.top_k`` chunks más relevantes +(predeterminado: ``3``) como contexto del LLM. + +Lo que se convierte en embedding en ese momento no es la frase del usuario tal cual, sino **la +consulta de búsqueda que genera el LLM en la fase de detección de la intención** (si se produce +una nueva búsqueda, se utiliza la consulta regenerada). Cuando no se genera ninguna consulta de +búsqueda —por ejemplo, si se pide el resumen de un documento— no se realiza ninguna selección de +chunks. + +Como resultado, incluso para documentos largos solo se pasan al LLM las partes relevantes, lo +que puede mejorar la precisión de la respuesta y reducir el uso de tokens. En los documentos +cuyo ``content_chunk_status`` es ``chunked`` (tienen chunks pero no vectores), la selección de +chunks se realiza por coincidencia de palabras clave (resaltado) en lugar de por cálculo de +similitud. Los documentos con ``skipped`` / ``fail`` y los que aún no se han procesado siguen +usando el cuerpo completo (o un fragmento resaltado) como antes. + +Este comportamiento es independiente de ``content_chunker.search.enabled``, pero requiere que +``content_chunker.enabled`` esté habilitado. Tenga en cuenta además que el texto resultante de +concatenar los chunks seleccionados también se trunca según +``rag.chat.content.fulltext.max.length`` (predeterminado ``3000``), por lo que aumentar +``content_chunker.chat.top_k`` o ``content_chunker.length.chunk_size`` no hace que el número de +caracteres entregado al LLM supere ese límite. + +.. _semantic-search-migration: + +Migración desde la versión 15.7 o anterior +============================================== + +Si está actualizando |Fess| desde la versión 15.7 o anterior, su situación corresponde a uno de +los cuatro patrones siguientes, según cómo utilice actualmente estas funciones. Siga las +instrucciones del patrón que se aplique a su caso. + +Instalaciones nuevas +----------------------- + +No se necesita trabajo adicional. Si desea usar la búsqueda vectorial, simplemente configure +``system.properties`` según la sección *Referencia de configuración* de esta página antes de +iniciar |Fess| por primera vez; el mapeo correcto se aplica automáticamente cuando se crea el +índice por primera vez. (Consulte *Procedimiento de configuración* más arriba para los pasos +concretos.) + +.. note:: + + Si ya ha iniciado |Fess| al menos una vez (es decir, el índice ya existe), siga en su lugar + uno de los patrones para *usuarios existentes* que se indican más abajo. + +Usuarios existentes que no desean la búsqueda vectorial +----------------------------------------------------------- + +No se necesita ningún trabajo. ``content_chunker.enabled`` y +``content_chunker.search.enabled`` son ambos ``false`` de forma predeterminada, por lo que sus +resultados de búsqueda y el comportamiento del índice existente no cambian después de la +actualización. El nuevo trabajo del programador **Content Chunk Vector Indexer** se registra +automáticamente al iniciar, pero como está deshabilitado de forma predeterminada nunca se +ejecuta, y el buscador semántico nunca se registra con Rank Fusion (este trabajo se registra en +cada arranque, así que si lo elimina desde la interfaz de administración se vuelve a crear +—deshabilitado— en el siguiente arranque). + +.. note:: + + Aunque no utilice la búsqueda vectorial, cualquier **creación de un índice nuevo** (incluida + la reindexación) a partir de |Fess| 15.10 aplica el mapeo que contiene + ``content_chunk_vector`` (de tipo ``knn_vector``) y ``index.knn: true``. En una configuración + en la que OpenSearch no tiene instalado el plugin k-NN, la creación del índice falla en ese + momento. Consulte *Requisitos previos* en esta misma página para más detalles. + +Usuarios existentes que desean habilitar la búsqueda vectorial +-------------------------------------------------------------------- + +El índice en ejecución no adopta el nuevo mapeo automáticamente, por lo que se requieren los +siguientes pasos. + +1. Aplique la configuración a ``system.properties`` como se describe en *Referencia de + configuración* en esta página (consulte *Procedimiento de configuración* más arriba para los + pasos concretos al usar el proveedor opensearch). +2. Reinicie |Fess|. +3. En la interfaz de administración, ejecute la **Reindexación** en **Información del sistema > + Mantenimiento** con la opción **Actualizar alias** habilitada. Esto se ejecuta en segundo plano + sin notificación de finalización. ``_cat/indices`` solo muestra que el nuevo índice existe, no + si los alias ya cambiaron — compruebe en su lugar ``_cat/aliases`` y confirme que + ``fess.search``/``fess.update`` apuntan al nuevo índice (el registro de |Fess| solo advierte en + caso de fallo, así que el silencio no es prueba de éxito). El índice antiguo no se elimina + automáticamente (elimínelo manualmente cuando ya no lo necesite), y el uso de disco del índice + se duplica aproximadamente hasta entonces. +4. Solo después de confirmar que el cambio de alias anterior ha finalizado, habilite y ejecute el + trabajo Content Chunk Vector Indexer en **Sistema > Programador** (no necesita volver a + rastrear: el trabajo lee ``content`` desde el ``_source`` del índice existente para dividirlo + en chunks y generar los embeddings). + +.. note:: + + Si en el paso 1 aplica también ``content_chunker.search.enabled=true``, entre el reinicio del + paso 2 y la finalización del paso 4 cada búsqueda generará únicamente el embedding de la + consulta, sin que ese trabajo se refleje en los resultados. Si utiliza un proveedor facturado + por uso, como ``openai``, ``gemini`` o ``bedrock``, aplique ``content_chunker.search.enabled=true`` y + reinicie una vez completado el paso 4. + +Si estaba utilizando el plugin fess-webapp-semantic-search +------------------------------------------------------------------ + +El plugin ``fess-webapp-semantic-search``, que proporcionaba la búsqueda semántica en |Fess| +15.7 y versiones anteriores, se ha incorporado al núcleo en la versión 15.10 y ahora es +**innecesario (obsoleto)**. Además de los pasos descritos en *Usuarios existentes que desean +habilitar la búsqueda vectorial* anteriores, también debe hacer lo siguiente. + +1. **Eliminar el plugin**: elimine ``fess-webapp-semantic-search-*.jar`` de + ``app/WEB-INF/plugin/`` (en Docker, excúyalo de ``FESS_PLUGINS``). + +2. **Eliminar la configuración antigua**: elimine todas las opciones de inicio + ``-Dfess.semantic_search.*``. Además, si había especificado + ``-Drank.fusion.searchers=default,semantic`` para el plugin antiguo, elimínelo también. + Dejarlo excluye al nuevo buscador semántico (``semantic_chunk``) de Rank Fusion y registra + una advertencia al iniciar. + +3. **Desvincular la pipeline de ingesta antigua**: si había configurado + ``-Dfess.semantic_search.pipeline``, el plugin antiguo incrusta ``default_pipeline`` (una + pipeline de ingesta para la búsqueda neuronal) en la configuración del índice al crearlo. + **Eliminar el plugin no elimina la pipeline** — permanece adjunta al índice y sigue + ejecutándose —, por lo que debe desvincularla **antes** de ejecutar la reindexación descrita + en *Usuarios existentes que desean habilitar la búsqueda vectorial*. El índice nuevo que + resulta de la reindexación ya no lleva ese ajuste, así que hacerlo después no sirve de nada. + Compruebe con ``_cat/aliases`` a qué ``fess.`` apunta ``fess.search`` e indique el + nombre del índice real, no el del alias:: + + curl -XPUT "http://localhost:9200/fess./_settings" \ + -H "Content-Type: application/json" -d ' + {"index": {"default_pipeline": "_none"}}' + + Aunque la desvincule de la configuración del índice, la propia pipeline de ingesta permanece + en el motor de búsqueda. Si no va a volver a utilizarla, elimínela:: + + curl -XDELETE "http://localhost:9200/_ingest/pipeline/" + +4. **Añadir la nueva configuración**: configure ``content_chunker.*`` en + ``system.properties`` como se describe en *Referencia de configuración* en esta página. Si + continúa utilizando su modelo de ML Commons existente, establezca + ``content_chunker.embedding.name=opensearch`` y coloque su ``model_id`` existente en + ``content_chunker.embedding.opensearch.model.id``. + +5. **Recrear el índice y ejecutar el trabajo**: el campo vectorial que almacenaba el plugin + antiguo (``content_vector`` en la configuración predeterminada) y el campo + ``content_chunk_vector`` que utiliza la nueva función del núcleo son campos distintos, por lo + que los vectores antiguos no se pueden aprovechar con la nueva función. En cambio, la + reindexación copia ``_source`` tal cual, así que esos vectores antiguos sí se duplican en el + índice nuevo y siguen consumiendo disco a través del mapeo dinámico. Se recomienda eliminarlos + **antes** de la reindexación (si cambió el nombre del campo, adapte el ejemplo):: + + curl -XPOST "http://localhost:9200/fess.search/_update_by_query" \ + -H "Content-Type: application/json" -d ' + { + "query": {"exists": {"field": "content_vector"}}, + "script": {"source": "ctx._source.remove(\"content_vector\")"} + }' + + A continuación, ejecute la **Reindexación** en **Información del sistema > Mantenimiento**, y + luego habilite y ejecute el trabajo Content Chunk Vector Indexer para regenerar los vectores. + +Notas +======= + +Cambiar el modelo de embedding (dimensión) +---------------------------------------------- + +Para cambiar a un modelo de embedding con una dimensión diferente, siga este orden. + +1. Elimine los vectores antiguos existentes. Si reindexa con vectores de la dimensión antigua + todavía presentes, el nuevo mapeo no los acepta y esos documentos no se copian al índice + nuevo, mientras el proceso sigue adelante. Como |Fess| solo comprueba el estado HTTP de la + reindexación, la interfaz de administración no muestra ningún error y aun así se pierden + documentos:: + + curl -XPOST "http://localhost:9200/fess.search/_update_by_query" \ + -H "Content-Type: application/json" -d ' + { + "query": {"exists": {"field": "content_chunk_status"}}, + "script": {"source": "ctx._source.remove(\"content_chunk_vector\"); ctx._source.remove(\"content_chunk_status\")"} + }' + + .. note:: + + También puede indicar como destino ``fess.update`` (el alias de actualización desde el que + la reindexación lee los documentos). Además, esta operación deja el campo ``content`` como + un array de chunks: en la siguiente ejecución del trabajo se vuelve a concatenar y a + dividir, por lo que si ha establecido ``content_chunker.length.overlap`` en un valor + distinto de 0, las partes solapadas quedarán duplicadas en la nueva división. Si eso le + preocupa, vuelva a rastrear los documentos afectados. + +2. Cambie ``content_chunker.embedding.dimension`` y la configuración del modelo de su proveedor. +3. Recree el índice siguiendo *3. Recrear el índice (al habilitar en una instalación existente)* + del *Procedimiento de configuración*, y vuelva a ejecutar el trabajo del indexador. + +Cambio a otro modelo con la misma dimensión +---------------------------------------------- + +Si cambia la configuración del modelo de embedding, como +``content_chunker.embedding.opensearch.model.id``, a otro modelo con la misma dimensión, |Fess| +lo acepta sin ningún error ni advertencia. Solo se comprueba la dimensión, y el modelo que +creó los vectores no se registra en el índice. Los vectores almacenados fueron creados entonces +por el modelo antiguo y los vectores de consulta, al buscar, por el nuevo; ambos viven en +espacios vectoriales distintos, por lo que la relevancia de los resultados de búsqueda se +degrada. La distribución de los valores de similitud del coseno también difiere de un modelo a +otro, por lo que un ``content_chunker.search.min_score`` ajustado para el modelo antiguo puede +resultar demasiado estricto para el nuevo y descartar la mayoría de los resultados. + +Para cambiar de modelo, configure el nuevo modelo, elimine ``content_chunk_vector`` y +``content_chunk_status`` con el mismo ``_update_by_query`` del paso 1 de *Cambiar el modelo de +embedding (dimensión)* más arriba, y vuelva a ejecutar el trabajo del indexador para regenerar +los vectores de todos los documentos (no es necesario recrear el índice, porque la dimensión es +la misma). Si ha establecido ``content_chunker.search.min_score``, revíselo con el nuevo modelo. + +Si el índice se creó sin dimensión +------------------------------------ + +Si el índice ``fess.search`` se crea mientras ``content_chunker.embedding.dimension`` no está +establecido, el mapeo de ``content_chunk_vector`` recibe una dimensión de ``768`` sin ninguna +advertencia, y no se puede cambiar después. Si a continuación ejecuta el trabajo del indexador, +no se puede leer la dimensión al generar los embeddings, lo cual es un error, por lo que los +documentos pasan a ``fail``. + +- Si el modelo que utiliza tiene una dimensión de ``768``, establezca + ``content_chunker.embedding.dimension=768``. Coincide con el mapeo, por lo que no es necesario + recrear el índice. +- En caso contrario, establezca la dimensión correcta. Mientras el mapeo (``768``) y el valor + configurado discrepen, el trabajo del indexador registra un ERROR y omite la ejecución. Recree + el índice con el mismo método del paso 3 de *Cambiar el modelo de embedding (dimensión)* más + arriba. + +En ambos casos, los documentos que ya están en ``fail`` no se vuelven a procesar +automáticamente. Si recrea el índice, el ``_update_by_query`` del paso 1 de *Cambiar el modelo de +embedding (dimensión)* también elimina ``content_chunk_status``. Si no lo recrea, establezca +temporalmente ``content_chunker.job.retry_failed`` en ``true`` y vuelva a ejecutar el trabajo. + +Uso de disco +-------------- + +Los vectores de chunks se conservan en ``_source`` además de las estructuras del índice de +búsqueda, por lo que cada documento consume espacio de disco adicional proporcional a su número +de chunks multiplicado por la dimensión del vector. Si el espacio en disco se convierte en un +problema, ajuste ``content_chunker.length.chunk_size`` o +``content_chunker.max_chunks_per_document``. + +Modo solo chunking +--------------------- + +Establecer ``content_chunker.embedding.name=none`` realiza solo el chunking, sin generar +vectores de embedding (``content_chunk_status`` pasa a ``chunked``). Esto le permite ejecutar el +chunking con antelación, antes de que su proveedor de embedding esté listo; una vez que configure +un proveedor más adelante y vuelva a ejecutar el trabajo, se generan vectores para los chunks ya +almacenados, sin volver a dividirlos. + +Configuración de memoria para corpus grandes +------------------------------------------------- + +La JVM hija del trabajo del indexador se inicia con ``jvm.chunk.options`` en +``fess_config.properties`` (opciones de JVM que por defecto incluyen ``-Xms128m -Xmx1g``). Dado +que ``content_chunker.job.max_documents_per_run`` es ilimitado de forma predeterminada, una sola +ejecución mantiene en memoria todos los ID de documentos pendientes. Cada ID de documento es un +resumen SHA-512 (128 caracteres) y ocupa unos 200 bytes en el heap; el propio procesamiento de +chunks consume además entre 200 y 250 MB. Por eso, a partir de **un corpus de entre 1 y 2 +millones de documentos**, aumente el valor de ``-Xmx`` en ``jvm.chunk.options`` o establezca un +valor finito en ``content_chunker.job.max_documents_per_run`` para repartir el trabajo en varias +ejecuciones. ``jvm.chunk.options`` se sobrescribe en +``app/WEB-INF/classes/fess_config.properties`` (en RPM/DEB, +``/etc/fess/fess_config.properties``); consulte :doc:`setup-memory` para entender cómo funcionan +las opciones de JVM. + +El mismo valor predeterminado ilimitado tiene una consecuencia de costo con un proveedor de +embedding facturado por uso (``openai``, ``gemini``, ``bedrock``): la primera ejecución del indexador genera +los embeddings de todo el corpus existente de una sola vez y factura todo eso de golpe. Establezca +un valor finito para ``content_chunker.job.max_documents_per_run`` para repartir ese costo entre +varias ejecuciones. + +Referencias +============= + +- :doc:`rank-fusion` - Configuración de Rank Fusion (búsqueda híbrida) +- :doc:`rag-chat` - Configuración del modo de búsqueda IA +- :doc:`llm-overview` - Descripción general de la integración LLM +- :doc:`llm-ollama` - Configuración de Ollama +- :doc:`setup-memory` - Configuración de memoria de la JVM +- :doc:`../install/upgrade` - Procedimiento de actualización diff --git a/es/15.10/config/security-role.rst b/es/15.10/config/security-role.rst new file mode 100644 index 000000000..2b07a3ad3 --- /dev/null +++ b/es/15.10/config/security-role.rst @@ -0,0 +1,72 @@ +========================================== +Configuración de Búsqueda Basada en Roles +========================================== + +Acerca de la Búsqueda Basada en Roles +====================================== + +|Fess| puede filtrar los resultados de búsqueda según la información de autenticación de usuarios autenticados a través de cualquier sistema de autenticación. +Por ejemplo, el usuario A con el rol 'a' verá en los resultados de búsqueda la información asociada al rol 'a', mientras que el usuario B sin el rol 'a' no verá esa información al realizar búsquedas. +Al utilizar esta funcionalidad, es posible implementar búsquedas segmentadas por departamento o cargo del usuario que ha iniciado sesión en entornos de portal o inicio de sesión único (SSO). + +|Fess| puede obtener la información de roles desde las siguientes fuentes: + +- Parámetros de solicitud + +- Encabezados de solicitud + +- Cookies + +- Información de autenticación de |Fess| + +En portales y sistemas de inicio de sesión único basados en agentes, la información de roles se puede obtener almacenando la información de autenticación mediante cookies para el dominio y ruta donde se ejecuta |Fess| durante la autenticación. +Además, en sistemas de inicio de sesión único basados en proxy inverso, la información de roles se puede obtener agregando la información de autenticación a los parámetros de solicitud o encabezados de solicitud al acceder a |Fess|. + +.. note:: + La obtención de roles desde parámetros de solicitud, encabezados de solicitud y cookies está deshabilitada de forma predeterminada. + Para utilizarlas, es necesario configurar el componente ``roleQueryHelper`` en ``app/WEB-INF/classes/fess.xml`` con los nombres de clave de referencia (``parameterKey``, ``headerKey``, ``cookieKey``), el cifrado de valores (``encryptedParameterValue``, etc.) y los separadores (``valueSeparator``, ``roleSeparator``). + De forma predeterminada, solo está habilitada la búsqueda basada en roles que utiliza la información de autenticación de |Fess|. + +Configuración de Búsqueda Basada en Roles +========================================== + +En esta sección se explica cómo configurar la búsqueda basada en roles utilizando la información de autenticación de |Fess|. + +Configuración en la Interfaz de Administración de |Fess| +--------------------------------------------------------- + +Inicie |Fess| e inicie sesión como administrador. +Cree roles y usuarios. +Por ejemplo, cree el rol "Role1" en la pantalla de administración de roles y luego cree un usuario perteneciente a Role1 en la pantalla de administración de usuarios. +Si desea asignar permisos por grupo, cree un grupo en la pantalla de administración de grupos y asígnelo al usuario. + +A continuación, en la configuración de rastreo, escriba ``{role}Role1`` en el campo de permisos y guarde. +Para especificar a nivel de usuario puede escribir ``{user}username``, y para especificar a nivel de grupo puede escribir ``{group}groupname``. +Si especifica varios permisos, sepárelos con saltos de línea. + +Después de esto, al rastrear con esta configuración de rastreo, se creará un índice en el que solo los usuarios pertenecientes al rol, usuario o grupo especificado podrán realizar búsquedas. +Al usuario que haya iniciado sesión se le asignarán automáticamente los permisos ``{user}username`` (que lo identifica a sí mismo), ``{role}`` (del rol al que pertenece) y ``{group}`` (del grupo al que pertenece), y estos se compararán con los permisos establecidos en los documentos. + +.. note:: + Si desea denegar explícitamente el acceso desde un rol, usuario o grupo específico, añada ``(deny)`` como prefijo, por ejemplo ``(deny){role}Role1`` (si se utiliza ``(allow)``, el acceso se permite, lo que equivale a no especificar nada). + +.. note:: + Cuando se integra con LDAP o inicio de sesión único, la información de roles y grupos del usuario se obtiene desde el proveedor de autenticación y se trata de igual forma como permisos. + El comportamiento durante la integración con LDAP puede controlarse mediante ``ldap.role.search.user.enabled``, ``ldap.role.search.group.enabled`` y ``ldap.role.search.role.enabled`` en ``fess_config.properties`` (el valor predeterminado de todos ellos es ``true``). + +Inicio de Sesión +---------------- + +Cierre sesión desde la interfaz de administración. +Inicie sesión con un usuario que pertenezca a Role1. +Si el inicio de sesión es exitoso, será redirigido a la página principal de búsqueda. + +Al realizar una búsqueda normal, solo se mostrarán los resultados asociados al rol Role1 en la configuración de rastreo. + +Además, las búsquedas realizadas sin haber iniciado sesión se consideran búsquedas realizadas por el usuario guest. +Para los documentos que desea mostrar a usuarios no autenticados, establezca ``{role}guest`` en el campo de permisos de la configuración de rastreo (el valor predeterminado se define mediante ``role.search.guest.permissions``). + +Cierre de Sesión +---------------- + +Al iniciar sesión con un usuario que no sea administrador, puede cerrar sesión seleccionando la opción de cierre de sesión en la pantalla de búsqueda. diff --git a/es/15.10/config/security-virtual-host.rst b/es/15.10/config/security-virtual-host.rst new file mode 100644 index 000000000..353589dd1 --- /dev/null +++ b/es/15.10/config/security-virtual-host.rst @@ -0,0 +1,91 @@ +============ +Host Virtual +============ + +Acerca del Host Virtual +======================= + +|Fess| puede mostrar diferentes resultados de búsqueda según el nombre de host (valor del encabezado HTTP ``Host``) utilizado para acceder al sistema. +Es posible publicar un único servidor |Fess| con múltiples nombres de host y ofrecer distintos objetivos de búsqueda (configuraciones de rastreo) y diseños de página para cada host virtual. +La pantalla de búsqueda también puede tener un aspecto distinto para cada host: para ese host se utiliza el tema estático cuyo nombre coincide con el nombre del host virtual. + +La función de host virtual está deshabilitada (sin configurar) de forma predeterminada. Siga los pasos a continuación para configurarla. + +Configuración del Sistema +------------------------- + +Configure la "Configuración General" en :doc:`Guía del Administrador > Configuración General <../admin/general-guide>` para definir la correspondencia entre el nombre de host de origen del acceso y el nombre del host virtual. El nombre del host virtual configurado aquí se especifica en la configuración de rastreo. + +**Formato** + +Defina un host virtual por línea con el siguiente formato: + +:: + + nombre_encabezado:valor_encabezado=nombre_host_virtual + +.. list-table:: + + * - *nombre_encabezado* + - Nombre del encabezado de solicitud HTTP utilizado para la determinación. Normalmente se especifica ``Host``. También puede especificarse ``X-Forwarded-Host`` cuando el acceso se realiza a través de un proxy inverso. + * - *valor_encabezado* + - Nombre de host (con ``nombre_host:número_puerto`` si es necesario) incluido en el encabezado anterior. Este host virtual se aplica cuando el valor coincide exactamente (sin distinción entre mayúsculas y minúsculas) con el valor del encabezado enviado por el cliente en el momento del acceso. + * - *nombre_host_virtual* + - Nombre del host virtual que se especifica en la configuración de rastreo + +**Ejemplo** + +:: + + Host:abc.example.com=host1 + Host:192.168.1.123:8080=host2 + +.. note:: + + La determinación se realiza mediante una comparación de cadenas con el valor del encabezado de solicitud, no mediante la resolución de nombres de host (DNS). + El encabezado ``Host`` enviado por el navegador no incluye el número de puerto cuando el acceso se realiza por el puerto estándar (80 para HTTP, 443 para HTTPS); para otros puertos, incluye el número de puerto con el formato ``nombre_host:número_puerto``. + Por lo tanto, si publica el servicio en un puerto no estándar, especifique el número de puerto de forma explícita, como en ``Host:abc.example.com:8080=host1``. + +.. note:: + + Solo se pueden usar caracteres alfanuméricos y guiones bajos ( ``a-z`` , ``A-Z`` , ``0-9`` , ``_`` ) en los nombres de host virtual. + Los demás caracteres se eliminan automáticamente. + + Además, los siguientes nombres están reservados y no se pueden usar como nombres de host virtual: + ``admin`` , ``common`` , ``error`` , ``login`` , ``profile`` + +Diseño de página por host virtual +--------------------------------- + +Para que un host virtual tenga su propia pantalla de búsqueda, instale un tema estático cuyo ``name`` en ``theme.yml`` sea el nombre del host virtual en minúsculas (por ejemplo ``host1``). +Las solicitudes que coinciden con el host virtual se sirven con ese tema; cualquier otra solicitud se sirve con el tema predeterminado. +No es necesario establecer el tema como predeterminado. Consulte :ref:`theme-customize-bundled` para saber cómo crear un tema a partir del tema incluido, y :doc:`../admin/theme-guide` para saber cómo instalarlo. + +.. note:: + + Desde |Fess| 15.10, al guardar la configuración ya no se generan archivos JSP en ``WEB-INF/view/nombre_host_virtual``. + La pantalla de inicio de sesión (``/login/``) es la misma para todos los hosts virtuales (``WEB-INF/view/admin/login/``) y no se puede cambiar por host virtual. + El aspecto de cada host virtual se cambia con un tema estático con el mismo nombre que el host virtual, como se describe arriba. + + +Configuración de Rastreo +------------------------ + +Especifique el "Host Virtual" en la configuración de rastreo web, la configuración de rastreo de archivos o la configuración de rastreo de almacén de datos. +Para "Host Virtual", especifique uno de los nombres de host virtual configurados en la configuración del sistema. También es posible especificar múltiples hosts virtuales en una sola configuración de rastreo (uno por línea). + +En las búsquedas realizadas desde un host virtual, solo se muestran en los resultados los documentos de la configuración de rastreo que tiene asignado ese host virtual. +En los accesos que no coinciden con ningún host virtual (acceso normal sin host virtual configurado), este filtrado no se aplica y se muestran todos los resultados de búsqueda de forma habitual. + +**Ejemplo** + +.. list-table:: + + * - *Host Virtual* + - ``host1`` + + +Etiquetas de usuario +-------------------- + +Las etiquetas que los usuarios con sesión iniciada ponen en los resultados de búsqueda (Mis etiquetas) también siguen al host virtual, cuando la función de etiquetas está habilitada. Una etiqueta creada en un host virtual solo se lista y se puede usar en ese host virtual. Una solicitud que no coincide con ningún host virtual ve todas las etiquetas. Una etiqueta que tiene host virtual se pone solo en los documentos de la configuración de rastreo que tiene ese host virtual. Para obtener más información, consulte :doc:`../admin/tagtype-guide` y :doc:`../api/api-tag`. diff --git a/es/15.10/config/setup-memory.rst b/es/15.10/config/setup-memory.rst new file mode 100644 index 000000000..6dadb7938 --- /dev/null +++ b/es/15.10/config/setup-memory.rst @@ -0,0 +1,438 @@ +===================== +Configuración de Memoria +===================== + +Descripción General +=================== + +En aplicaciones Java, es necesario configurar la memoria heap máxima utilizada por cada proceso. +En |Fess|, la configuración de memoria se realiza para cada uno de los siguientes tres componentes: + +- Aplicación Web Fess +- Proceso del Rastreador +- OpenSearch + +Una configuración de memoria apropiada permite mejorar el rendimiento y lograr una operación estable. + +Configuración de Memoria de la Aplicación Web Fess +=================================================== + +Cuándo es Necesaria la Configuración +------------------------------------- + +Considere ajustar el tamaño de memoria en los siguientes casos: + +- Se registran errores OutOfMemory en ``fess.log`` +- Es necesario procesar un gran número de accesos simultáneos +- Las operaciones de la pantalla de administración son lentas o se produce timeout + +El tamaño de memoria predeterminado es suficiente para uso general, pero se requiere incremento en entornos de alta carga. + +Configuración mediante Variables de Entorno +-------------------------------------------- + +Configure la variable de entorno ``FESS_HEAP_SIZE``. + +:: + + export FESS_HEAP_SIZE=2g + +Unidades: + +- ``m``: megabytes +- ``g``: gigabytes + +Control Detallado de Memoria +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``FESS_HEAP_SIZE`` establece ``-Xms`` y ``-Xmx`` al mismo valor. Para controlar el tamaño de heap inicial y máximo de forma independiente, use las variables de entorno ``FESS_MIN_MEM`` y ``FESS_MAX_MEM``. + +:: + + export FESS_MIN_MEM=256m + export FESS_MAX_MEM=2g + +.. list-table:: Configuración de Memoria Predeterminada por Plataforma + :header-rows: 1 + :widths: 30 35 35 + + * - Plataforma + - FESS_MIN_MEM (Predeterminado) + - FESS_MAX_MEM (Predeterminado) + * - Linux + - 256m + - 2g + * - Windows + - 256m + - 1g + +.. note:: + Cuando se establece ``FESS_HEAP_SIZE``, ``FESS_MIN_MEM`` y ``FESS_MAX_MEM`` se ignoran. + +.. note:: + En los paquetes RPM/DEB, el archivo de entorno (``/etc/sysconfig/fess``, o ``/etc/default/fess`` en DEB) establece ``FESS_HEAP_SIZE=512m``. Por ello, el heap queda fijado en 512m en lugar de los valores predeterminados de la tabla anterior. Para cambiar el tamaño del heap, modifique este valor de ``FESS_HEAP_SIZE``. + +Para Paquetes RPM/DEB +---------------------- + +Para instalación con paquete RPM, edite ``/etc/sysconfig/fess``. + +:: + + FESS_HEAP_SIZE=2g + +Para paquetes DEB, edite ``/etc/default/fess``. + +:: + + FESS_HEAP_SIZE=2g + +.. warning:: + Después de cambiar el tamaño de memoria, es necesario reiniciar el servicio |Fess|. + +Tamaños de Memoria Recomendados +-------------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 30 30 40 + + * - Entorno + - Tamaño Heap Recomendado + - Observaciones + * - Entorno de Desarrollo/Prueba + - 512m〜1g + - Índice de pequeña escala + * - Entorno de Producción Pequeño + - 1g〜2g + - Decenas a cientos de miles de documentos + * - Entorno de Producción Mediano + - 2g〜4g + - Cientos de miles a millones de documentos + * - Entorno de Producción Grande + - 4g〜8g + - Millones o más documentos + +Configuración de Memoria del Rastreador +======================================== + +Cuándo es Necesaria la Configuración +------------------------------------- + +Es necesario aumentar el tamaño de memoria del rastreador en los siguientes casos: + +- Al aumentar el número de rastreos paralelos +- Al rastrear archivos grandes +- Cuando ocurren errores OutOfMemory durante la ejecución del rastreo + +Método de Configuración +------------------------ + +Edite ``app/WEB-INF/classes/fess_config.properties`` o ``/etc/fess/fess_config.properties``. + +``jvm.crawler.options`` es un único ajuste que enumera las opciones de JVM del proceso del rastreador, separadas por saltos de línea (``\n``). Al cambiar el valor se sustituyen todas las opciones predeterminadas, por lo que, si escribe solo ``-Xmx512m``, también se pierden las demás opciones predeterminadas, como ``-Dfile.encoding=UTF-8`` y los ajustes de G1GC. Conserve el valor predeterminado indicado en ``fess_config.properties`` y cambie únicamente las líneas del tamaño del heap. + +Por ejemplo, para cambiar el heap máximo a 1GB, modifique la línea ``-Xmx512m`` del valor predeterminado como sigue. + +:: + + -Xms128m\n\ + -Xmx1g\n\ + +.. note:: + Esta configuración se aplica por unidad de proceso del rastreador (por unidad de trabajo del programador). + Si ejecuta múltiples trabajos de rastreo simultáneamente, cada trabajo utilizará la memoria especificada. + +Configuración Recomendada +-------------------------- + +- **Rastreo Web normal**: 512m〜1g +- **Rastreo paralelo masivo**: 1g〜2g +- **Rastreo de archivos grandes**: 2g〜4g + +Opciones Detalladas de JVM +--------------------------- + +Las opciones detalladas de JVM para el rastreador se pueden configurar en ``jvm.crawler.options``. +La configuración predeterminada incluye las siguientes optimizaciones. + +**Opciones principales:** + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - Opción + - Descripción + * - ``-Xms128m -Xmx512m`` + - Tamaño heap inicial y máximo + * - ``-XX:MaxMetaspaceSize=128m`` + - Tamaño máximo de Metaspace + * - ``-XX:+UseG1GC`` + - Uso del recolector de basura G1 + * - ``-XX:MaxGCPauseMillis=60000`` + - Objetivo máximo de tiempo de pausa de GC (60 segundos), objetivo relajado para cargas de trabajo del rastreador (el valor típico es ~200ms) + * - ``-XX:-HeapDumpOnOutOfMemoryError`` + - Desactivar heap dump en OutOfMemory + +Configuración de Memoria de OpenSearch +======================================= + +Consideraciones Importantes +---------------------------- + +Para OpenSearch, es necesario considerar los siguientes dos puntos al configurar la memoria: + +1. **Memoria Heap Java**: Utilizada por el proceso de OpenSearch +2. **Caché del Sistema de Archivos del SO**: Importante para el rendimiento de búsqueda + +.. warning:: + Si hace la memoria heap Java demasiado grande, disminuirá la memoria disponible + para la caché del sistema de archivos del SO, reduciendo el rendimiento de búsqueda. + +Método de Configuración +------------------------ + +Entorno Linux +~~~~~~~~~~~~~ + +La memoria heap de OpenSearch se configura editando el archivo ``config/jvm.options``: + +:: + + -Xms2g + -Xmx2g + +.. note:: + Se recomienda configurar el tamaño heap mínimo (``-Xms``) y el tamaño heap máximo (``-Xmx``) al mismo valor. + +.. note:: + La variable de entorno ``OPENSEARCH_HEAP_SIZE`` está obsoleta en OpenSearch 3.x y puede no tener efecto. + Si necesita configurar el heap mediante una variable de entorno, use ``OPENSEARCH_JAVA_OPTS``: + + :: + + export OPENSEARCH_JAVA_OPTS="-Xms2g -Xmx2g" + +Entorno Windows +~~~~~~~~~~~~~~~ + +Edite el archivo ``config\jvm.options``. + +:: + + -Xms2g + -Xmx2g + +Tamaños de Memoria Recomendados +-------------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 30 30 40 + + * - Tamaño del Índice + - Tamaño Heap Recomendado + - Memoria Total Recomendada + * - 〜10GB + - 2g + - 4GB o más + * - 10GB〜50GB + - 4g + - 8GB o más + * - 50GB〜100GB + - 8g + - 16GB o más + * - 100GB o más + - 16g〜31g + - 32GB o más + +.. warning:: + No configure la memoria heap de OpenSearch por encima de 32GB. + Superar 32GB desactiva Compressed OOP y reduce la eficiencia de memoria. + +Mejores Prácticas +----------------- + +1. **Asignar el 50% de la memoria física al heap** + + Asigne aproximadamente el 50% de la memoria física del servidor al heap de OpenSearch. + El resto se utiliza para el SO y la caché del sistema de archivos. + +2. **Máximo de 31GB** + + El tamaño heap debe ser hasta 31GB como máximo; si se necesita más, aumente el número de nodos. + +3. **Verificación en Entorno de Producción** + + Consulte la documentación oficial de OpenSearch y realice la configuración óptima según su entorno. + +Configuración de Memoria para Procesamiento de Sugerencias y Miniaturas +======================================================================== + +Proceso de Generación de Sugerencias +------------------------------------- + +La configuración de memoria para el proceso de generación de sugerencias se configura en ``jvm.suggest.options``. + +Al igual que en el rastreador, este ajuste contiene todas las opciones predeterminadas, así que cambie solo la línea ``-Xmx256m`` y conserve las demás. + +Por defecto se utiliza la siguiente configuración: + +- Heap inicial: 128MB +- Heap máximo: 256MB +- Metaspace máximo: 128MB + +Proceso de Generación de Miniaturas +------------------------------------ + +La configuración de memoria para el proceso de generación de miniaturas se configura en ``jvm.thumbnail.options``. + +Al igual que en el rastreador, este ajuste contiene todas las opciones predeterminadas, así que cambie solo la línea ``-Xmx256m`` y conserve las demás. + +Por defecto se utiliza la siguiente configuración: + +- Heap inicial: 128MB +- Heap máximo: 256MB +- Metaspace máximo: 128MB + +.. note:: + Si procesa imágenes grandes en la generación de miniaturas, es necesario aumentar la memoria. + +Monitoreo y Ajuste de Memoria +============================== + +Verificación del Uso de Memoria +-------------------------------- + +Uso de Memoria de Fess +~~~~~~~~~~~~~~~~~~~~~~~ + +Puede verificar en "Información del Sistema" en la pantalla de administración. + +O utilice herramientas de monitoreo de JVM: + +:: + + jps -l # Verificar proceso de Fess + jstat -gcutil 1000 # Mostrar estadísticas de GC cada segundo + +Uso de Memoria de OpenSearch +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + curl -X GET "localhost:9200/_nodes/stats/jvm?pretty" + curl -X GET "localhost:9200/_cat/nodes?v&h=heap.percent,ram.percent" + +Síntomas de Falta de Memoria +----------------------------- + +Si aparecen los siguientes síntomas, es posible que haya falta de memoria. + +**Aplicación Web Fess:** + +- Respuesta lenta +- ``OutOfMemoryError`` registrado en logs +- El proceso termina inesperadamente + +**Rastreador:** + +- El rastreo se detiene a mitad +- ``OutOfMemoryError`` registrado en ``fess-crawler.log`` +- Falla el rastreo de archivos grandes + +**OpenSearch:** + +- Búsqueda lenta +- Creación de índice lenta +- Ocurre error ``circuit_breaker_exception`` + +Procedimiento de Ajuste +------------------------ + +1. **Verificar el uso actual de memoria** + + Monitoree el uso de memoria de cada componente. + +2. **Identificar el cuello de botella** + + Identifique qué componente tiene falta de memoria. + +3. **Aumentar gradualmente** + + En lugar de aumentar mucho de una vez, aumente en incrementos del 25-50% y verifique el efecto. + +4. **Considerar el equilibrio del sistema completo** + + Asegúrese de que el total de memoria de cada componente no exceda la memoria física. + +5. **Monitoreo continuo** + + Monitoree continuamente el uso de memoria y ajuste según sea necesario. + +Contramedidas para Fugas de Memoria +------------------------------------ + +Si se sospecha una fuga de memoria: + +1. **Obtener heap dump** + +:: + + jmap -dump:format=b,file=heap.bin + +2. **Análisis del heap dump** + + Analice con herramientas como Eclipse Memory Analyzer (MAT). + +3. **Reportar el problema** + + Si descubre una fuga de memoria, repórtela en GitHub Issues. + +Solución de Problemas +====================== + +Ocurre OutOfMemoryError +------------------------ + +**Aplicación Web Fess:** + +1. Aumente ``FESS_HEAP_SIZE``. +2. Limite el número de accesos simultáneos. +3. Reduzca el nivel de log para disminuir el uso de memoria por salida de logs. + +**Rastreador:** + +1. Aumente ``-Xmx`` en ``jvm.crawler.options``. +2. Reduzca el número de rastreos paralelos. +3. Ajuste la configuración de rastreo para excluir archivos grandes. + +**OpenSearch:** + +1. Aumente el tamaño heap (hasta 31GB como máximo). +2. Revise el número de shards del índice. +3. Verifique la complejidad de las consultas. + +Tiempo de Pausa Largo por GC +----------------------------- + +1. Ajuste la configuración de G1GC. +2. Configure el tamaño heap apropiadamente (GC frecuente si es demasiado grande o demasiado pequeño). +3. Considere actualizar a una versión más reciente de Java. + +El Rendimiento No Mejora Después de Configurar la Memoria +---------------------------------------------------------- + +1. Verifique otros recursos como CPU, I/O de disco, red. +2. Realice optimización del índice. +3. Revise las consultas y la configuración de rastreo. + +Información de Referencia +========================== + +- :doc:`setup-port-network` - Configuración de Puerto y Red +- :doc:`crawler-advanced` - Configuración Avanzada del Rastreador +- :doc:`admin-logging` - Configuración de Logs +- `OpenSearch Memory Settings `_ +- `Java GC Tuning `_ diff --git a/es/15.10/config/setup-port-network.rst b/es/15.10/config/setup-port-network.rst new file mode 100644 index 000000000..fac1c67f8 --- /dev/null +++ b/es/15.10/config/setup-port-network.rst @@ -0,0 +1,461 @@ +================================ +Configuración de Puerto y Red +================================ + +Descripción General +=================== + +Esta sección describe la configuración relacionada con la red en |Fess|. +Abarca configuraciones de conexión de red como cambios de números de puerto, configuración de proxy y configuración de comunicación HTTP. + +Configuración de Puertos Utilizados +==================================== + +Puertos Predeterminados +----------------------- + +|Fess| utiliza los siguientes puertos por defecto. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Servicio + - Número de Puerto + * - Aplicación Web Fess + - 8080 + * - OpenSearch (HTTP) + - 9200 + * - OpenSearch (Transport) + - 9300 + +Cambio de Puerto de la Aplicación Web Fess +------------------------------------------- + +Configuración en Entorno Linux +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Para cambiar el número de puerto en entorno Linux, edite ``bin/fess.in.sh``. + +:: + + FESS_JAVA_OPTS="$FESS_JAVA_OPTS -Dfess.port=8080" + +Por ejemplo, para usar el puerto 80: + +:: + + FESS_JAVA_OPTS="$FESS_JAVA_OPTS -Dfess.port=80" + +.. note:: + Para usar números de puerto inferiores a 1024, se requieren privilegios de root o la configuración de permisos apropiada (CAP_NET_BIND_SERVICE). + +Configuración mediante Variables de Entorno +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +También puede especificar el número de puerto mediante una variable de entorno. + +:: + + export FESS_PORT=8080 + +.. warning:: + La variable de entorno ``FESS_PORT`` solo está disponible en Linux. En Windows, edite ``-Dfess.port`` directamente en ``bin\fess.in.bat``. + +Para Paquetes RPM/DEB +~~~~~~~~~~~~~~~~~~~~~~ + +Para paquetes RPM edite ``/etc/sysconfig/fess``, para paquetes DEB edite ``/etc/default/fess``. + +:: + + FESS_PORT=8080 + +Configuración en Entorno Windows +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +En entornos Windows, edite ``bin\fess.in.bat``. + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.port=8080 + +Al Registrar como Servicio de Windows +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Si utiliza el registro como servicio en entorno Windows, cambie también la configuración de puerto en ``bin\service.bat``. +Consulte :doc:`setup-windows-service` para más detalles. + +Configuración de Ruta de Contexto +---------------------------------- + +Si publica |Fess| en un subdirectorio, puede configurar la ruta de contexto. + +En Linux: + +:: + + export FESS_CONTEXT_PATH=/search + +En Windows: + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.context.path=/search + +.. warning:: + La variable de entorno ``FESS_CONTEXT_PATH`` solo está disponible en Linux. En Windows, use ``-Dfess.context.path`` directamente en ``FESS_JAVA_OPTS``. + +Con esta configuración, podrá acceder mediante ``http://localhost:8080/search/``. + +.. warning:: + Si cambia la ruta de contexto, también debe configurar apropiadamente las rutas de los archivos estáticos. + +Configuración de Proxy +====================== + +Descripción General +------------------- + +Al rastrear sitios externos desde dentro de una intranet o al acceder a APIs externas, +las comunicaciones pueden ser bloqueadas por un firewall. +En tales entornos, es necesario configurar la comunicación a través de un servidor proxy. + +Configuración de Proxy para el Rastreador +------------------------------------------ + +Configuración Básica +~~~~~~~~~~~~~~~~~~~~ + +En la configuración de rastreo de la pantalla de administración, especifique los parámetros de configuración de la siguiente manera. + +:: + + client.proxyHost=proxy.example.com + client.proxyPort=8080 + +Configuración de Proxy con Autenticación +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Si el servidor proxy requiere autenticación, agregue lo siguiente. + +:: + + client.proxyHost=proxy.example.com + client.proxyPort=8080 + client.proxyUsername=proxyuser + client.proxyPassword=proxypass + +Exclusión de Hosts Específicos del Proxy +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +La configuración de proxy del rastreador no soporta nonProxyHosts. +Para excluir hosts específicos del proxy, utilice la variable de entorno ``FESS_NON_PROXY_HOSTS``. +Esta configuración se convierte en la propiedad del sistema Java ``http.nonProxyHosts`` y se aplica a toda la comunicación HTTP de Fess. + +:: + + FESS_NON_PROXY_HOSTS=localhost|*.local|192.168.* + +Configuración de Proxy Predeterminado del Rastreador +----------------------------------------------------- + +Para establecer un proxy predeterminado cuando ``client.proxyHost`` no se especifica en las configuraciones individuales de rastreo, configure en ``fess_config.properties``. +Esta configuración se aplica al proxy predeterminado del rastreador, así como a la comunicación HTTP de la integración con LLM y a las descargas de complementos. Sin embargo, no se aplica a la comunicación de algunas bibliotecas de Java, como la autenticación SSO. Para aplicar un proxy a toda la aplicación Fess (incluida la autenticación SSO), utilice las variables de entorno descritas más adelante (``FESS_PROXY_HOST``, etc.). + +:: + + http.proxy.host=proxy.example.com + http.proxy.port=8080 + http.proxy.username=proxyuser + http.proxy.password=proxypass + +.. warning:: + Las contraseñas se almacenan sin cifrar. Configure los permisos de archivo apropiados. + +.. note:: + Las configuraciones ``http.proxy.*`` no se aplican a la autenticación SSO, etc. Para usar un proxy en toda la aplicación Fess, incluida la autenticación SSO (comunicación HTTP a nivel de toda la JVM), defina las variables de entorno ``FESS_PROXY_HOST`` y ``FESS_PROXY_PORT``. Para más detalles, consulte «Configuración del proxy mediante variables de entorno» más adelante. + +Configuración de Proxy mediante Variables de Entorno +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Cuando las bibliotecas Java como la autenticación SSO necesitan usar un proxy, debe configurarlo mediante variables de entorno. +Estas variables de entorno se convierten en propiedades del sistema Java (``http.proxyHost``, ``https.proxyHost``, etc.). + +:: + + FESS_PROXY_HOST=proxy.example.com + FESS_PROXY_PORT=8080 + FESS_NON_PROXY_HOSTS=localhost|*.local|192.168.* + +Para paquetes RPM, configure en ``/etc/sysconfig/fess``. Para paquetes DEB, configure en ``/etc/default/fess``. + +.. note:: + Las configuraciones ``http.proxy.*`` en ``fess_config.properties`` se utilizan para el proxy predeterminado del rastreador, así como para la integración con LLM y las descargas de complementos. Para usar un proxy en toda la aplicación Fess, incluida la autenticación SSO (comunicación HTTP a nivel de toda la JVM), defina las variables de entorno anteriores. + +Configuración de Comunicación HTTP +=================================== + +Límites de Carga de Archivos +----------------------------- + +Puede limitar el tamaño de carga de archivos desde la pantalla de administración. + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - Elemento de Configuración + - Descripción + * - ``http.fileupload.max.size`` + - Tamaño máximo de carga de archivo (predeterminado: 262144000 bytes = 250MB) + * - ``http.fileupload.threshold.size`` + - Tamaño umbral para mantener en memoria (predeterminado: 262144 bytes = 256KB) + * - ``http.fileupload.max.file.count`` + - Número de archivos que se pueden cargar a la vez (predeterminado: 10) + +Ejemplo de configuración en ``fess_config.properties``: + +:: + + http.fileupload.max.size=524288000 + http.fileupload.threshold.size=524288 + http.fileupload.max.file.count=20 + +Configuración de Conexión de OpenSearch +---------------------------------------- + +Puede configurar la URL de conexión de OpenSearch y el intervalo de comprobación de estado (heartbeat). + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - Elemento de Configuración + - Descripción + * - ``search_engine.http.url`` + - URL de OpenSearch (predeterminado: http://localhost:9200). La variable de entorno ``SEARCH_ENGINE_HTTP_URL`` tiene prioridad (véase más abajo). + * - ``search_engine.heartbeat_interval`` + - Intervalo de verificación de estado (milisegundos, predeterminado: 10000) + +Cambio de Destino de Conexión de OpenSearch +-------------------------------------------- + +La URL a la que se conecta |Fess| se especifica con la variable de entorno +``SEARCH_ENGINE_HTTP_URL``. Tiene prioridad sobre ``search_engine.http.url`` de +``fess_config.properties``. El ``bin/fess.in.sh`` del paquete ZIP y el archivo +de entorno de los paquetes RPM/DEB asignan a esta variable +``http://localhost:9200`` de forma predeterminada, por lo que cambiar +``search_engine.http.url`` no cambia el destino de la conexión. + +Dónde se establece depende del tipo de instalación: + +- Paquete ZIP: edite la línea ``SEARCH_ENGINE_HTTP_URL`` de + ``bin/fess.in.sh`` o exporte ``SEARCH_ENGINE_HTTP_URL`` en el entorno que + inicia |Fess| (consulte :doc:`../install/install-linux`). +- Paquete RPM/DEB: ``SEARCH_ENGINE_HTTP_URL`` en ``/etc/sysconfig/fess`` (RPM) + o ``/etc/default/fess`` (DEB). +- Docker: la variable de entorno del contenedor ``SEARCH_ENGINE_HTTP_URL`` + (consulte :doc:`../install/install-docker`). +- Paquete ZIP en Windows: la línea ``-Dfess.search_engine.http_address`` de + ``bin\fess.in.bat`` (consulte :doc:`../install/install-windows`). + +:: + + SEARCH_ENGINE_HTTP_URL=http://opensearch-cluster.example.com:9200 + +Conexión a Múltiples Nodos +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Para conectarse a varios nodos de OpenSearch, separe las URL con comas. Si +algunos de los nodos están detenidos, |Fess| se conecta a los restantes. + +:: + + SEARCH_ENGINE_HTTP_URL=http://node1:9200,http://node2:9200,http://node3:9200 + +Configuración de Conexión SSL/TLS +---------------------------------- + +Para conectarse a OpenSearch mediante HTTPS, especifique una URL ``https://`` +de la misma manera que arriba: + +:: + + SEARCH_ENGINE_HTTP_URL=https://opensearch.example.com:9200 + +Configure el certificado de la CA y las credenciales en +``fess_config.properties``: + +:: + + search_engine.http.ssl.certificate_authorities=/path/to/ca.crt + search_engine.username=admin + search_engine.password=admin_password + +.. note:: + Para verificar certificados, especifique la ruta al certificado CA en ``certificate_authorities``. + +Configuración de Host Virtual +============================== + +Descripción General +------------------- + +Puede diferenciar los resultados de búsqueda según el nombre de host con el que se accede a |Fess|. +Consulte :doc:`security-virtual-host` para más detalles. + +Configuración Básica +-------------------- + +Configure los hosts virtuales desde la interfaz de administración «Sistema > General» (``virtual.host.headers``). Especifique un host virtual por línea con el formato ``Host:nombredehost[:puerto]=nombredehostvirtual``. El valor predeterminado está vacío (sin definir) y la función de host virtual está deshabilitada. + +:: + + Host:search1.example.com=site1 + Host:search2.example.com=site2 + +.. note:: + El valor de ``virtual.host.headers`` NO es una lista de nombres de encabezado como ``X-Forwarded-Host,Host``. Cada línea describe una correspondencia con el formato ``NombreDeEncabezado:ValorDeEncabezado=nombredehostvirtual``. Para el formato detallado y las restricciones, consulte :doc:`security-virtual-host`. + +Integración con Proxy Inverso +============================== + +Ejemplo de Configuración de Nginx +---------------------------------- + +:: + + server { + listen 80; + server_name search.example.com; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Host $host; + } + } + +Ejemplo de Configuración de Apache +----------------------------------- + +:: + + + ServerName search.example.com + + ProxyPreserveHost On + ProxyPass / http://localhost:8080/ + ProxyPassReverse / http://localhost:8080/ + + RequestHeader set X-Forwarded-Proto "http" + RequestHeader set X-Forwarded-Host "search.example.com" + + +Terminación SSL/TLS +------------------- + +Ejemplo de configuración para terminación SSL/TLS en el proxy inverso (Nginx): + +:: + + server { + listen 443 ssl http2; + server_name search.example.com; + + ssl_certificate /path/to/cert.pem; + ssl_certificate_key /path/to/key.pem; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto https; + proxy_set_header X-Forwarded-Host $host; + } + } + +Configuración de Firewall +========================== + +Apertura de Puertos Necesarios +------------------------------- + +Para hacer |Fess| accesible desde el exterior, abra los siguientes puertos. + +**Ejemplo de configuración de iptables:** + +:: + + # Aplicación Web Fess + iptables -A INPUT -p tcp --dport 8080 -j ACCEPT + + # Para acceso HTTPS (vía proxy inverso) + iptables -A INPUT -p tcp --dport 443 -j ACCEPT + +**Ejemplo de configuración de firewalld:** + +:: + + # Aplicación Web Fess + firewall-cmd --permanent --add-port=8080/tcp + firewall-cmd --reload + +Configuración de Grupo de Seguridad (Entornos en la Nube) +---------------------------------------------------------- + +En entornos de nube como AWS, GCP, Azure, abra los puertos apropiados +con grupos de seguridad o ACLs de red. + +Configuración recomendada: +- Entrada: Puertos 80/443 (vía proxy inverso HTTP) +- Puerto 8080 restringido solo para acceso interno +- Puertos 9200/9300 de OpenSearch restringidos solo para acceso interno + +Solución de Problemas +====================== + +No se Puede Acceder Después de Cambiar el Puerto +------------------------------------------------- + +1. Verifique que haya reiniciado |Fess|. +2. Verifique que el puerto correspondiente esté abierto en el firewall. +3. Verifique errores en el archivo de log (``fess.log``). + +No se Puede Rastrear a Través del Proxy +---------------------------------------- + +1. Verifique que el nombre de host y puerto del servidor proxy sean correctos. +2. Si el servidor proxy requiere autenticación, configure el nombre de usuario y contraseña. +3. Verifique que los intentos de conexión se registren en los logs del servidor proxy. +4. Verifique que la configuración de ``nonProxyHosts`` sea apropiada. + +No se Puede Conectar a OpenSearch +---------------------------------- + +1. Verifique que OpenSearch esté en ejecución. +2. Verifique que la configuración de ``search_engine.http.url`` sea correcta. +3. Verifique la conexión de red: ``curl http://localhost:9200`` +4. Verifique errores en los logs de OpenSearch. + +No Funciona Correctamente al Acceder Vía Proxy Inverso +------------------------------------------------------- + +1. Verifique que el encabezado ``X-Forwarded-Host`` esté configurado correctamente. +2. Verifique que el encabezado ``X-Forwarded-Proto`` esté configurado correctamente. +3. Verifique que la ruta de contexto esté configurada correctamente. +4. Verifique errores en los logs del proxy inverso. + +Información de Referencia +========================== + +- :doc:`setup-memory` - Configuración de Memoria +- :doc:`setup-windows-service` - Configuración de Servicio de Windows +- :doc:`security-virtual-host` - Configuración de Host Virtual +- :doc:`crawler-advanced` - Configuración Avanzada del Rastreador +- `OpenSearch Configuration `_ diff --git a/es/15.10/config/setup-windows-service.rst b/es/15.10/config/setup-windows-service.rst new file mode 100644 index 000000000..cbb937d46 --- /dev/null +++ b/es/15.10/config/setup-windows-service.rst @@ -0,0 +1,134 @@ +==================================== +Registro como Servicio de Windows +==================================== + +Registro como Servicio de Windows +================================== + +Puede registrar |Fess| como un servicio de Windows. Al registrarlo como servicio, |Fess| puede iniciarse automáticamente al arrancar el sistema. +Para ejecutar |Fess|, es necesario que OpenSearch esté en ejecución. +Aquí se asume que |Fess| está instalado en ``c:\opt\fess`` y OpenSearch en ``c:\opt\opensearch`` (ajuste las rutas según su entorno). + +.. note:: + |Fess| y OpenSearch solo admiten la versión de 64 bits. + +Preparación Previa +------------------ + +Configure ``JAVA_HOME`` como variable de entorno del sistema. Si ``JAVA_HOME`` no está definida, ``service.bat`` finalizará con un error. + +Registrar OpenSearch como Servicio +----------------------------------- + +Abra el símbolo del sistema con privilegios de administrador y ejecute ``c:\opt\opensearch\bin\opensearch-service.bat``. + +:: + + > cd c:\opt\opensearch\bin + > opensearch-service.bat install + ... + The service 'opensearch-service-x64' has been installed. + +Para más detalles, consulte la `documentación de OpenSearch `_. + +Configuración de |Fess| +------------------------ + +El servicio se registra mediante ``c:\opt\fess\bin\service.bat``. Al registrarlo, ``service.bat`` lee ``bin\fess.in.bat`` y aplica su contenido a las opciones de inicio de |Fess|. +Agregue la configuración de conexión a OpenSearch en ``c:\opt\fess\bin\fess.in.bat``. + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200 + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=c:/opt/opensearch/config/dictionary/ + +.. note:: + - En ``fess.search_engine.http_address`` especifique el destino de conexión del servicio OpenSearch registrado. Si no se configura esta opción, |Fess| no podrá encontrar el destino de conexión y no se iniciará; informará de que no hay ninguna dirección de motor de búsqueda configurada. + - Si OpenSearch se ejecuta en un host diferente, cambie el nombre de host o la dirección IP según corresponda. + - Utilice ``/`` como separador de ruta. + +El número de puerto predeterminado para la pantalla de búsqueda y la pantalla de administración de |Fess| es ``8080``. Para cambiar a otro puerto, edite ``-Dfess.port`` en ``c:\opt\fess\bin\fess.in.bat``. + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.port=80 + +.. note:: + Al registrar como servicio, ``-Dfess.port=8080`` también está codificado en ``FESS_PARAMS`` dentro de ``bin\service.bat``. Este valor tiene prioridad sobre la configuración de ``fess.in.bat``, por lo que al cambiar el puerto también debe editar ``FESS_PARAMS`` en ``service.bat`` de la misma manera. + +Personalización del Servicio (opcional) +----------------------------------------- + +Es posible modificar la configuración del servicio estableciendo variables de entorno antes de ejecutar ``service.bat install``. Las principales variables de entorno son las siguientes. + +.. list-table:: + :header-rows: 1 + + * - Variable de entorno + - Descripción + * - ``FESS_START_TYPE`` + - Tipo de inicio (``auto`` o ``manual``). El valor predeterminado es ``manual``. + * - ``FESS_HEAP_SIZE`` + - Tamaño del heap (por ejemplo: ``1g``). Para especificar el tamaño mínimo y máximo del heap de forma individual, use ``FESS_MIN_MEM`` (predeterminado ``256m``) y ``FESS_MAX_MEM`` (predeterminado ``1g``). + * - ``SERVICE_USERNAME`` / ``SERVICE_PASSWORD`` + - Cuenta de Windows bajo la que se ejecuta el servicio. + * - ``SERVICE_DISPLAY_NAME`` + - Nombre para mostrar del servicio. + * - ``SERVICE_DESCRIPTION`` + - Descripción del servicio. + +Método de Registro +------------------ + +Ejecute ``c:\opt\fess\bin\service.bat`` desde el símbolo del sistema con privilegios de administrador. + +:: + + > cd c:\opt\fess\bin + > service.bat install + ... + The service 'fess-service-x64' has been installed. + +Configuración del Servicio +--------------------------- + +Al iniciar el servicio manualmente, inicie primero el servicio de OpenSearch y luego el servicio de |Fess|. +Para que se inicie automáticamente al arrancar el sistema, configure el tipo de inicio y las dependencias. + +1. En la configuración general del servicio, establezca el tipo de inicio como "Automático (Inicio retrasado)". +2. La dependencia del servicio se configura en el registro. + +Agregue la siguiente clave y valor en el Editor del Registro (regedit). + +.. list-table:: + + * - *Clave* + - ``Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\fess-service-x64\DependOnService`` + * - *Valor* + - ``opensearch-service-x64`` + +Una vez agregado, opensearch-service-x64 se mostrará en las dependencias de las propiedades del servicio de |Fess|. + +.. note:: + Si establece la variable de entorno ``FESS_START_TYPE=auto`` antes de ejecutar ``service.bat install``, el servicio se registrará con el tipo de inicio "Automático". Sin embargo, "Automático (Inicio retrasado)" y la configuración de dependencias no pueden realizarse mediante ``service.bat``, por lo que deberá configurarlos siguiendo el procedimiento indicado anteriormente. + +Gestión del Servicio +--------------------- + +Con ``service.bat`` puede administrar el servicio mediante los siguientes comandos. + +.. list-table:: + :header-rows: 1 + + * - Comando + - Descripción + * - ``service.bat install`` + - Registra el servicio. + * - ``service.bat remove`` + - Elimina el servicio. + * - ``service.bat start`` + - Inicia el servicio. + * - ``service.bat stop`` + - Detiene el servicio. + * - ``service.bat manager`` + - Inicia la interfaz gráfica de administración del servicio. diff --git a/es/15.10/config/sso-entraid.rst b/es/15.10/config/sso-entraid.rst new file mode 100644 index 000000000..42fe1c919 --- /dev/null +++ b/es/15.10/config/sso-entraid.rst @@ -0,0 +1,436 @@ +========================================== +Configuración de SSO con Entra ID +========================================== + +Descripción general +=================== + +|Fess| soporta autenticación Single Sign-On (SSO) utilizando Microsoft Entra ID (anteriormente Azure AD). +Al utilizar la autenticación de Entra ID, puede integrar la información de usuario y la información de grupo de su entorno Microsoft 365 con la búsqueda basada en roles de |Fess|. + +.. note:: + La compatibilidad con la autenticación de Entra ID proviene del plugin ``fess-sso-entraid``, + que no forma parte de la distribución. Instálelo desde la página **Sistema > Plugin** de la + pantalla de administración o con ``bin/fess-setup install plugin fess-sso-entraid``. + Hasta entonces, con ``sso.type=entraid`` (o el antiguo ``aad``) toda petición a ``/sso/`` + solo se redirige de vuelta a la página de inicio de sesión. + +Cómo funciona la autenticación de Entra ID +------------------------------------------ + +En la autenticación de Entra ID, |Fess| opera como un cliente OAuth 2.0/OpenID Connect y colabora con Microsoft Entra ID para la autenticación. + +1. El usuario accede al endpoint SSO de |Fess| (``/sso/``) +2. |Fess| redirige al endpoint de autorización de Entra ID +3. El usuario se autentica con Entra ID (inicio de sesión de Microsoft) +4. Entra ID redirige el código de autorización a |Fess| +5. |Fess| utiliza el código de autorización para obtener un token de acceso +6. El usuario inicia sesión +7. En segundo plano, |Fess| utiliza la API de Microsoft Graph para recuperar la información de grupo y rol del usuario, y la aplica a la búsqueda basada en roles en cuanto finaliza la resolución + +.. note:: + A partir de |Fess| 15.10, la respuesta de autorización del paso 4 se devuelve como una solicitud + GET, ya que |Fess| solicita ``response_mode=query`` al endpoint de autorización. Hasta la + versión 15.7 se devolvía mediante un POST entre sitios, y el valor por defecto incluido + ``tomcat.sameSiteCookies = lax`` no envía la cookie de sesión en ese caso, por lo que era + necesario ``tomcat.sameSiteCookies = none`` como solución alternativa. Si configuró ``none`` + únicamente por ese motivo, puede volver al valor por defecto. + +Para la integración con la búsqueda basada en roles, consulte :doc:`security-role`. + +Prerrequisitos +============== + +Antes de configurar la autenticación de Entra ID, verifique los siguientes prerrequisitos: + +- |Fess| 15.10 o superior está instalado +- Un tenant de Microsoft Entra ID (Azure AD) está disponible +- |Fess| es accesible a través de HTTPS (requerido para entornos de producción) +- Tiene permiso para registrar aplicaciones en Entra ID + +Configuración básica +==================== + +Habilitar SSO +------------- + +Para habilitar la autenticación de Entra ID, agregue la siguiente configuración en ``app/WEB-INF/conf/system.properties``: + +:: + + sso.type=entraid + +Configuración requerida +----------------------- + +Configure la información obtenida de Entra ID. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propiedad + - Descripción + - Por defecto + * - ``entraid.tenant`` + - ID del tenant (ej: ``xxx.onmicrosoft.com``) + - (Requerido) + * - ``entraid.client.id`` + - ID de aplicación (Cliente) + - (Requerido) + * - ``entraid.client.secret`` + - Valor del secreto del cliente + - (Requerido) + * - ``entraid.reply.url`` + - URI de redirección (URL de callback) + - Usa la URL de la solicitud + +.. note:: + En lugar del prefijo ``entraid.*``, también puede usar el prefijo legacy ``aad.*`` para compatibilidad con versiones anteriores. + +Configuración opcional +---------------------- + +Las siguientes configuraciones pueden agregarse según sea necesario. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propiedad + - Descripción + - Por defecto + * - ``entraid.authority`` + - URL del servidor de autenticación + - ``https://login.microsoftonline.com/`` + * - ``entraid.state.ttl`` + - Tiempo de vida del state (segundos) + - ``3600`` + * - ``entraid.response.mode`` + - Forma en que se devuelve la respuesta de autorización. Puede ser ``query`` o ``form_post``. + - ``query`` + * - ``entraid.default.groups`` + - Grupos por defecto (separados por comas). Se aplican a todos los usuarios de Entra ID. + - (Ninguno) + * - ``entraid.default.roles`` + - Roles por defecto (separados por comas). Se aplican a todos los usuarios de Entra ID. + - (Ninguno) + * - ``entraid.permission.fields`` + - Campos de grupo/rol (separados por comas) que se utilizan adicionalmente como valores de permiso. El ID de grupo/rol (GUID) siempre se usa como permiso, y los valores de los campos especificados aquí (ej: ``mail``) se agregan. Solo pueden utilizarse campos cuyo valor sea una cadena de texto. Microsoft Graph devuelve un campo como ``securityEnabled`` en forma de booleano y ``groupTypes`` en forma de lista, y ninguno de los dos puede convertirse en un valor de permiso, por lo que un campo así se ignora y se escribe en el registro una advertencia que indica su nombre. + - ``mail`` + * - ``entraid.use.ds`` + - Integración con el servicio de dominio. Cuando es ``true``, para los valores de permiso en formato ``name@domain``, la parte local (``name``) con la parte del dominio eliminada también se agrega como permiso. Esto se aplica no solo a los grupos y roles, sino también al propio usuario que ha iniciado sesión: la parte local de su nombre principal de usuario (UPN) se agrega como permiso a nivel de usuario. Por lo tanto, establecerlo en ``false`` elimina también ese permiso a nivel de usuario, no solo los de los grupos. + - ``true`` + +.. note:: + + El ID de grupo/rol (GUID) siempre se usa como permiso, pero solo los grupos habilitados para + correo tienen un valor ``mail``. Los grupos de Microsoft 365 están habilitados para correo, por + lo que su nombre también se registra como permiso. **Los grupos de seguridad no están + habilitados para correo, por lo que con el valor predeterminado solo su GUID se convierte en un + permiso.** Si los derechos de acceso del sistema de archivos indican un grupo de seguridad, los + permisos no coinciden y esos documentos no aparecen en los resultados de búsqueda. + + En ese caso, agregue ``displayName``, que todos los grupos tienen: + + .. code-block:: properties + + entraid.permission.fields=mail,displayName + + ``displayName`` no está calificado por dominio ni es único, por lo que no forma parte del valor + predeterminado. Por ejemplo, si Entra ID tiene un grupo llamado ``Administrators``, también + coincidirá con documentos cuyos derechos de acceso indiquen el grupo integrado de Windows + ``Administrators``. Antes de agregarlo, compruebe que los nombres no entren en conflicto con los + que ya se usan en sus derechos de acceso. + +.. note:: + Con el valor por defecto ``query``, el código de autorización se incluye en la cadena de + consulta de la URL de callback. ``form_post`` mantiene el código fuera de la URL y, por lo + tanto, fuera del historial del navegador y de los registros de acceso de cualquier proxy + frontal o WAF, pero convierte el callback en un POST entre sitios y requiere + ``tomcat.sameSiteCookies = none``. Sin esa configuración, la cookie de sesión no se devuelve y + el inicio de sesión falla. Además, los navegadores solo aceptan ``none`` en una cookie que + también tenga el atributo ``Secure``, por lo que ``form_post`` exige servir |Fess| mediante + HTTPS: sobre HTTP simple el navegador ni siquiera almacena la cookie de sesión y el inicio de + sesión sigue fallando. Por ello, la mayoría de las instalaciones deberían mantener el valor por + defecto. Cualquier otro valor se ignora con una advertencia y se utiliza ``query``. + +.. warning:: + + ``entraid.default.groups`` y ``entraid.default.roles`` son valores globales únicos, sin ámbito + por usuario. |Fess| los aplica a todos los usuarios de Entra ID al iniciar sesión y vuelve a + aplicarlos en cada resolución posterior, por lo que Microsoft Graph nunca los retira. En + particular, no ponga nunca el rol de administrador de |Fess| — ``admin`` con el valor + ``authentication.admin.roles`` que se incluye — en ``entraid.default.roles``: eso concede a + todos los usuarios del inquilino acceso permanente a las pantallas de administración. + +Configuración del lado de Entra ID +================================== + +Registro de aplicación en Azure Portal +-------------------------------------- + +1. Inicie sesión en `Azure Portal `_ + +2. Seleccione **Microsoft Entra ID** + +3. Vaya a **Administrar** → **Registros de aplicaciones** → **Nuevo registro** + +4. Registre la aplicación: + + .. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Configuración + - Valor + * - Nombre + - Cualquier nombre (ej: Fess SSO) + * - Tipos de cuenta compatibles + - "Solo cuentas en este directorio organizativo" + * - Plataforma + - Web + * - URI de redirección + - ``https:///sso/`` + +5. Haga clic en **Registrar** + +Crear un secreto de cliente +--------------------------- + +1. En la página de detalles de la aplicación, haga clic en **Certificados y secretos** + +2. Haga clic en **Nuevo secreto de cliente** + +3. Establezca una descripción y una fecha de expiración, luego haga clic en **Agregar** + +4. Copie y guarde el **Valor** generado (este valor no se mostrará nuevamente) + +.. warning:: + El valor del secreto del cliente solo se muestra inmediatamente después de la creación. + Asegúrese de registrarlo antes de salir de la página. + +Configurar permisos de API +-------------------------- + +1. Haga clic en **Permisos de API** en el menú izquierdo + +2. Haga clic en **Agregar un permiso** + +3. Seleccione **Microsoft Graph** + +4. Seleccione **Permisos delegados** + +5. Agregue el siguiente permiso: + + - ``User.Read`` - Requerido para recuperar las pertenencias a grupos del usuario que ha iniciado sesión (``/me/memberOf``). Se concede por defecto al crear el registro de la aplicación + - ``GroupMember.Read.All`` - Requerido para leer atributos del grupo, como su nombre, y para resolver los grupos anidados + +6. Haga clic en **Agregar permisos** + +7. Haga clic en **Conceder consentimiento de administrador para ** + +.. note:: + El consentimiento del administrador requiere privilegios de administrador del tenant. + +.. note:: + En lugar de ``GroupMember.Read.All`` también se pueden conceder ``Group.Read.All`` o + ``Directory.Read.All``: la lectura de los atributos del grupo y la resolución de los grupos + anidados siguen funcionando. Sin embargo, ``/me/memberOf`` no está autorizado por + ``Group.Read.All``, por lo que ``User.Read`` es necesario en cualquier caso. + +.. note:: + Los permisos anteriores no cubren el ``displayName`` de un rol de directorio: Microsoft Graph + lo devuelve como null. Por lo tanto, indicar ``displayName`` en ``entraid.permission.fields`` + no aporta nada para un rol de directorio y solo el ID (GUID) del rol se convierte en un + permiso. Para usar los nombres de rol como valores de permiso, conceda además + ``RoleManagement.Read.Directory`` (o ``Directory.Read.All``). + +.. note:: + |Fess| solicita el ámbito ``https://graph.microsoft.com/.default`` al adquirir un token. + Desde la versión 15.10, también se envía ``openid profile offline_access https://graph.microsoft.com/.default`` al endpoint de autorización, de modo que el consentimiento se solicita para el mismo conjunto. + Esto significa que se utilizan todos los permisos de acceso configurados y para los que se ha dado consentimiento en el registro de la aplicación. + Por lo tanto, para recuperar información de grupos, debe agregar los permisos indicados anteriormente al registro de la aplicación y otorgar el consentimiento del administrador. + +Información a obtener +--------------------- + +La siguiente información se utiliza para la configuración de Fess: + +- **ID de aplicación (Cliente)**: En la página Información general, como "ID de aplicación (cliente)" +- **ID del tenant**: En la página Información general, como "ID de directorio (tenant)" o en formato ``xxx.onmicrosoft.com`` +- **Valor del secreto del cliente**: El valor creado en Certificados y secretos + +Mapeo de grupos y roles +======================= + +Con la autenticación de Entra ID, |Fess| recupera automáticamente los grupos y roles a los que pertenece un usuario utilizando la API de Microsoft Graph. +Los IDs de grupo y nombres de grupo recuperados pueden usarse para la búsqueda basada en roles de |Fess|. + +Grupos anidados +--------------- + +|Fess| recupera no solo los grupos a los que los usuarios pertenecen directamente, sino también los grupos padre a los que estos pertenecen (grupos anidados). +Tanto la búsqueda de la pertenencia directa como la búsqueda de grupos padre se ejecutan en la misma tarea en segundo plano después del inicio de sesión, de modo que el inicio de sesión nunca se ve retrasado por Microsoft Graph. +La búsqueda de grupos padre utiliza la operación ``getMemberGroups`` de Microsoft Graph, que resuelve de forma transitiva: una sola llamada por cada grupo asignado directamente devuelve todos los grupos que están por encima de él, sea cual sea la profundidad del anidamiento. Los resultados obtenidos se almacenan en caché durante un período determinado. +Cuando esa tarea en segundo plano finaliza, los permisos del usuario se recalculan. + +Configuración de grupos por defecto +----------------------------------- + +Para asignar grupos comunes a todos los usuarios de Entra ID: + +:: + + entraid.default.groups=authenticated_users,entra_users + +Ejemplos de configuración +========================= + +Configuración mínima (para pruebas) +----------------------------------- + +El siguiente es un ejemplo de configuración mínima para verificación en un entorno de pruebas. + +:: + + # Habilitar SSO + sso.type=entraid + + # Configuración de Entra ID + entraid.tenant=yourcompany.onmicrosoft.com + entraid.client.id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + entraid.client.secret=your-client-secret-value + entraid.reply.url=http://localhost:8080/sso/ + +Configuración recomendada (para producción) +------------------------------------------- + +El siguiente es un ejemplo de configuración recomendada para entornos de producción. + +:: + + # Habilitar SSO + sso.type=entraid + + # Configuración de Entra ID + entraid.tenant=yourcompany.onmicrosoft.com + entraid.client.id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + entraid.client.secret=your-client-secret-value + entraid.reply.url=https://fess.example.com/sso/ + + # Grupos por defecto (opcional) + entraid.default.groups=authenticated_users + +Configuración legacy (compatibilidad con versiones anteriores) +-------------------------------------------------------------- + +Para compatibilidad con versiones anteriores, también se puede usar el prefijo ``aad.*``. +Cuando cada propiedad ``entraid.*`` no está configurada, se utiliza el valor de la propiedad ``aad.*`` correspondiente. +Además, ``sso.type=aad`` se trata de la misma forma que ``sso.type=entraid``. + +:: + + # Habilitar SSO (también se puede usar sso.type=aad) + sso.type=entraid + + # Claves de configuración legacy + aad.tenant=yourcompany.onmicrosoft.com + aad.client.id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + aad.client.secret=your-client-secret-value + aad.reply.url=https://fess.example.com/sso/ + +Solución de problemas +===================== + +Problemas comunes y soluciones +------------------------------ + +No se puede regresar a Fess después de la autenticación +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verifique que la URI de redirección esté configurada correctamente en el registro de aplicaciones del portal Azure +- Asegúrese de que el valor de ``entraid.reply.url`` coincida exactamente con la configuración del portal Azure +- Verifique que el protocolo (HTTP/HTTPS) coincida +- Verifique que la URI de redirección termine con ``/`` +- Si ``entraid.response.mode`` está establecido en ``form_post``, verifique tanto que + ``tomcat.sameSiteCookies = none`` esté configurado como que |Fess| se sirva mediante HTTPS. Con el + valor por defecto ``lax``, el navegador no envía la cookie de sesión en el POST entre sitios del + callback; con ``none`` sobre HTTP simple, el navegador no almacena esa cookie en absoluto, porque + ``none`` exige el atributo ``Secure``. En ambos casos el inicio de sesión falla una sola vez: el + navegador vuelve a la pantalla de inicio de sesión mostrando "Error en el proceso de inicio de + sesión SSO." y en el registro se escribe una advertencia con el texto + ``Failed to process SSO login: could not validate state`` + +Ocurren errores de autenticación +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verifique que el ID del tenant, ID de cliente y secreto del cliente estén configurados correctamente +- Verifique que el secreto del cliente no haya expirado +- Verifique que se haya otorgado el consentimiento del administrador para los permisos de API + +No se puede recuperar la información de grupo +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verifique que se hayan otorgado los permisos ``User.Read`` y ``GroupMember.Read.All`` + (``GroupMember.Read.All`` puede sustituirse por ``Group.Read.All`` o ``Directory.Read.All``, + pero ``/me/memberOf`` sigue requiriendo ``User.Read``) +- Verifique que se haya otorgado el consentimiento del administrador +- Verifique que el usuario pertenezca a grupos en Entra ID +- Si no se pueden resolver los grupos padre anidados, se registra la advertencia + ``Not allowed to read the parent groups of ...``. En ese caso, otorgue ``GroupMember.Read.All`` +- |Fess| resuelve la pertenencia a grupos y roles del usuario en segundo plano una vez completado + el inicio de sesión, de modo que este nunca espera a Microsoft Graph. Hasta que la resolución + termina, el usuario solo tiene su propio permiso a nivel de usuario y lo que aporten + ``entraid.default.groups`` y ``entraid.default.roles``. Si no se ha configurado ninguno de los + dos —el valor por defecto que se incluye—, una búsqueda hecha en esa ventana no devuelve ningún + documento: ``role.search.default.permissions`` está vacío de fábrica, y una configuración de + rastreo creada con el valor ``role.search.default.display.permissions`` que se incluye concede + ``{role}guest``, rol que un usuario con la sesión iniciada no tiene. La ventana dura hasta + aproximadamente un segundo de retardo de planificación más las propias llamadas a Microsoft + Graph — una para las pertenencias directas y luego una más por cada uno de esos grupos para + recorrer los grupos anidados, emitidas una tras otra con la caché fría —, por lo que crece con + el número de grupos a los que pertenece el usuario. Mientras tanto, la pantalla de búsqueda + indica al usuario que sus permisos de grupo y rol todavía se están cargando y le pide que + repita la búsqueda en unos instantes +- Si la resolución no se completa del todo, la pantalla de búsqueda indica al usuario que sus + permisos de grupo y rol no se pudieron cargar por completo, le pide que cierre la sesión y + vuelva a iniciarla, y que contacte con el administrador si el problema persiste. Lo de «por + completo» es deliberado: la resolución solo se considera correcta si han tenido éxito tanto la + consulta de pertenencias directas como el recorrido de los grupos anidados, así que un usuario + que tiene sus grupos directos pero no sus grupos padre también recibe ese mensaje. Hay un caso + exento, y es precisamente el que describe el punto anterior: cuando Microsoft Graph rechaza la + consulta de grupos anidados con ``Authorization_RequestDenied`` porque nunca se otorgó + ``GroupMember.Read.All``, |Fess| lo interpreta como una respuesta que significa que el grupo no + tiene grupos padre, y no como un fallo. La resolución se considera entonces correcta y **no se + muestra ningún mensaje**, aunque falten los permisos de los grupos padre. La única señal es la + advertencia ``Not allowed to read the parent groups of ...`` en el registro, así que conviene + buscarla siempre que se utilicen grupos anidados. La causa + habitual del caso parcial es la limitación de peticiones: un solo HTTP 429 o 503 de Microsoft + Graph hace que |Fess| espere el tiempo que pida la cabecera ``Retry-After`` (60 segundos si no + indica nada utilizable, 60 minutos como máximo), y durante ese tiempo se omite toda consulta de + grupos anidados en la instancia entera de |Fess| mientras las consultas directas siguen + respondiendo. El fallo no es necesariamente definitivo: + la resolución se reintenta cada vez que se renueva el token de acceso, y un éxito posterior hace + desaparecer el mensaje y restaura los permisos que faltaban. Cerrar la sesión y volver a + iniciarla lo reintenta de inmediato — abrir la URL de inicio de sesión SSO con la sesión aún + iniciada solo redirige de vuelta a la pantalla de búsqueda + +Configuración de depuración +--------------------------- + +Para investigar problemas, puede mostrar logs detallados relacionados con Entra ID ajustando el nivel de log de |Fess|. + +En ``app/WEB-INF/classes/log4j2.xml``, puede agregar el siguiente logger para cambiar el nivel de log: + +:: + + + +Referencia +========== + +- :doc:`security-role` - Configuración de búsqueda basada en roles +- :doc:`sso-saml` - Configuración de SSO con autenticación SAML +- :doc:`sso-oidc` - Configuración de SSO con autenticación OpenID Connect + diff --git a/es/15.10/config/sso-oidc.rst b/es/15.10/config/sso-oidc.rst new file mode 100644 index 000000000..0ef7d86f7 --- /dev/null +++ b/es/15.10/config/sso-oidc.rst @@ -0,0 +1,331 @@ +========================================== +Configuración de SSO con OpenID Connect +========================================== + +Descripción general +=================== + +|Fess| soporta autenticación Single Sign-On (SSO) utilizando OpenID Connect (OIDC). +OpenID Connect es un protocolo de autenticación basado en OAuth 2.0 que utiliza ID Tokens (JWT) para la autenticación de usuarios. +Al utilizar autenticación OpenID Connect, la información del usuario autenticada por un OpenID Provider (OP) puede integrarse con |Fess|. + +.. note:: + La compatibilidad con la autenticación OpenID Connect proviene del plugin ``fess-sso-oidc``, + que no forma parte de la distribución. Instálelo desde la página **Sistema > Plugin** de la + pantalla de administración o con ``bin/fess-setup install plugin fess-sso-oidc``. El plugin + se llama ``fess-sso-oidc`` mientras que el valor de ``sso.type`` sigue siendo ``oic``. + Hasta entonces, con ``sso.type=oic`` toda petición a ``/sso/`` solo se redirige de vuelta a + la página de inicio de sesión. + +Cómo funciona la autenticación OpenID Connect +---------------------------------------------- + +En la autenticación OpenID Connect, |Fess| opera como Relying Party (RP) y colabora con un OpenID Provider (OP) externo para la autenticación. + +1. El usuario accede al endpoint SSO de |Fess| (``/sso/``) +2. |Fess| redirige al endpoint de autorización del OP +3. El usuario se autentica en el OP +4. El OP redirige el código de autorización a |Fess| +5. |Fess| utiliza el código de autorización para obtener un ID Token del endpoint de token +6. |Fess| comprueba los claims del ID Token (JWT), obtiene la información del usuario e inicia sesión del usuario + +.. note:: + |Fess| utiliza el flujo de código de autorización (Authorization Code Flow). El ID Token se obtiene directamente desde el endpoint de token a través de un canal de retaguardia (comunicación servidor a servidor) entre |Fess| y el OP, sin pasar por el navegador. + |Fess| decodifica el ID Token y extrae los claims (como ``email`` y ``groups``) para construir la información del usuario, pero no realiza la verificación criptográfica de la firma JWT. OpenID Connect Core lo permite porque el token se recibe directamente del endpoint de token a través de TLS, por lo que la URL del endpoint de token (``oic.token.server.url``) debe ser HTTPS. ``http`` solo se acepta para ``localhost``, ``127.x.x.x`` y ``::1``. + |Fess| sí comprueba los claims: ``aud`` debe contener ``oic.client.id`` (y ``azp``, si está presente, debe ser igual a este valor), ``exp`` debe estar presente y no haber expirado (se tolera un desfase horario de hasta 300 segundos), y el claim ``iss`` debe ser igual a ``oic.issuer`` cuando esa clave está definida. Sin ``oic.issuer``, ``iss`` no se comprueba y se registra una advertencia en el primer inicio de sesión tras cada arranque. ``nonce`` y PKCE no se utilizan. + +Para la integración con búsqueda basada en roles, consulte :doc:`security-role`. + +Prerrequisitos +============== + +Antes de configurar la autenticación OpenID Connect, verifique los siguientes prerrequisitos: + +- |Fess| 15.10 o superior está instalado +- Un proveedor compatible con OpenID Connect (OP) está disponible +- |Fess| es accesible a través de HTTPS (requerido para entornos de producción) +- Tiene permiso para registrar |Fess| como cliente (RP) en el lado del OP + +Ejemplos de proveedores soportados: + +- Microsoft Entra ID (Azure AD) +- Google Workspace / Google Cloud Identity +- Okta +- Keycloak +- Auth0 +- Otros proveedores compatibles con OpenID Connect + +Configuración básica +==================== + +Habilitar SSO +------------- + +Para habilitar la autenticación OpenID Connect, agregue la siguiente configuración en ``app/WEB-INF/conf/system.properties``: + +:: + + sso.type=oic + +.. note:: + Los ajustes de ``sso.type`` y los de ``oic.*`` descritos a continuación, excepto ``oic.issuer``, también pueden configurarse y modificarse desde la página "Sistema > General" de la pantalla de administración. + Los cambios realizados en la pantalla de administración se guardan en ``system.properties`` y se conservan tras el reinicio. + ``oic.issuer`` solo puede definirse en ``system.properties``. + +Configuración del proveedor +--------------------------- + +Configure la información obtenida de su OP. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propiedad + - Descripción + - Por defecto + * - ``oic.auth.server.url`` + - URL del endpoint de autorización + - ``https://accounts.google.com/o/oauth2/auth`` + * - ``oic.token.server.url`` + - URL del endpoint de token + - ``https://accounts.google.com/o/oauth2/token`` + * - ``oic.issuer`` + - Identificador del emisor (opcional). Si se define, el claim ``iss`` del ID Token debe ser exactamente igual a este valor (una barra final cuenta) + - (vacío: no se comprueba ``iss``) + +.. note:: + Estas URLs y el emisor se pueden obtener del endpoint Discovery del OP (``/.well-known/openid-configuration``); el emisor es su valor ``issuer``. + + La URL del endpoint de token (``oic.token.server.url``) debe ser HTTPS. ``http`` solo se acepta cuando el host es ``localhost`` (sin distinguir mayúsculas y minúsculas), una dirección IPv4 con la forma ``127.x.x.x`` o ``::1``. El host se compara tal como está escrito y nunca se resuelve, por lo que un nombre de servicio de Docker Compose (como ``http://keycloak:8080/...``) o un nombre de host interno se rechaza con ``http`` aunque apunte a la misma máquina. + + Solo se comprueba el endpoint de token, no el endpoint de autorización (``oic.auth.server.url``). La comprobación se realiza en el inicio de sesión, no al arrancar. Definir ``oic.issuer`` no relaja esta regla; solo activa la comprobación del claim ``iss``. + +Configuración del cliente +------------------------- + +Configure la información del cliente registrada con el OP. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propiedad + - Descripción + - Por defecto + * - ``oic.client.id`` + - ID de cliente + - (vacío) + * - ``oic.client.secret`` + - Secreto del cliente + - (vacío) + * - ``oic.scope`` + - Scopes solicitados + - (vacío) + +.. note:: + El scope debe incluir al menos ``openid``. + Para recuperar la dirección de correo electrónico del usuario, especifique ``openid email``. + +Configuración de URL de redirección +------------------------------------ + +Configure la URL de callback después de la autenticación. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propiedad + - Descripción + - Por defecto + * - ``oic.redirect.url`` + - URL de redirección (URL de callback) + - ``{oic.base.url}/sso/`` + * - ``oic.base.url`` + - URL base de |Fess| + - ``http://localhost:8080`` + +.. note:: + Si ``oic.redirect.url`` se omite, se construye automáticamente a partir de ``oic.base.url``. + Para entornos de producción, configure ``oic.base.url`` con una URL HTTPS. + +Configuración de atributos de usuario +-------------------------------------- + +Configure los grupos y roles por defecto que se asignarán a los usuarios autenticados con OIDC. +El ID de usuario, los grupos y los roles se determinan de la siguiente manera: + +- **ID de usuario**: se obtiene del claim ``email`` del ID Token (JWT). Por este motivo, en la práctica es necesario incluir ``email`` en el scope (si no se puede obtener el claim ``email``, el inicio de sesión no funcionará correctamente). +- **Grupos**: se obtienen del claim ``groups`` del ID Token. Si el claim ``groups`` no existe, se utiliza el valor de ``oic.default.groups``. Un array ``groups`` vacío se considera presente, por lo que no se utiliza ``oic.default.groups`` y el usuario se trata como si no tuviera grupos. +- **Roles**: siempre se utiliza el valor de ``oic.default.roles`` (no existe mecanismo para obtener roles desde los claims del ID Token). + +.. note:: + |Fess| utiliza directamente los valores del claim ``groups``: no realiza ninguna consulta al + directorio ni expande los grupos anidados (transitivos). Por lo tanto, que aparezcan los grupos + padre depende únicamente de la configuración de claims del OP, a diferencia de + :doc:`sso-entraid`, donde |Fess| resuelve los grupos padre mediante la API de Microsoft Graph. + El valor del claim se convierte literalmente en el permiso de búsqueda. Si el OP está configurado + para emitir rutas de grupo completas, envía valores como ``/padre/hijo``, que no coinciden con los + documentos etiquetados solo con el nombre del grupo. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propiedad + - Descripción + - Por defecto + * - ``oic.default.groups`` + - Grupos por defecto (separados por comas) + - (vacío) + * - ``oic.default.roles`` + - Roles por defecto (separados por comas) + - (vacío) + +.. note:: + Si utiliza búsqueda basada en roles, debe asignar los grupos o roles apropiados al usuario. + Para más detalles, consulte :doc:`security-role`. + +Configuración del lado del OP +============================== + +Al registrar |Fess| como cliente (RP) en el lado del OP, configure la siguiente información: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Configuración + - Valor + * - Tipo de aplicación + - Aplicación web + * - URI de redirección / URL de callback + - ``https:///sso/`` + * - Scopes permitidos + - ``openid`` y scopes requeridos (``email``, ``profile``, etc.) + +Información a obtener del OP +----------------------------- + +Obtenga la siguiente información de la pantalla de configuración o endpoint Discovery del OP para usar en la configuración de |Fess|: + +- **Endpoint de autorización (Authorization Endpoint)**: URL para iniciar la autenticación del usuario +- **Endpoint de token (Token Endpoint)**: URL para obtener tokens +- **Issuer** (opcional): valor ``issuer`` del documento Discovery, utilizado para ``oic.issuer`` +- **ID de cliente**: Identificador de cliente emitido por el OP +- **Secreto del cliente**: Clave secreta utilizada para la autenticación del cliente + +.. note:: + La mayoría de los OP le permiten verificar las URLs de los endpoints de autorización y token desde el + endpoint Discovery (``https:///.well-known/openid-configuration``). + +Ejemplos de configuración +========================= + +Configuración mínima (para pruebas) +------------------------------------- + +El siguiente es un ejemplo de configuración mínima para verificación en un entorno de pruebas. + +:: + + # Habilitar SSO + sso.type=oic + + # Configuración del proveedor (establecer valores obtenidos del OP) + oic.auth.server.url=https://op.example.com/authorize + oic.token.server.url=https://op.example.com/token + + # Configuración del cliente + oic.client.id=your-client-id + oic.client.secret=your-client-secret + oic.scope=openid email + + # URL de redirección (entorno de pruebas) + oic.redirect.url=http://localhost:8080/sso/ + +Configuración recomendada (para producción) +-------------------------------------------- + +El siguiente es un ejemplo de configuración recomendada para entornos de producción. + +:: + + # Habilitar SSO + sso.type=oic + + # Configuración del proveedor + oic.auth.server.url=https://op.example.com/authorize + oic.token.server.url=https://op.example.com/token + + # Issuer (el valor "issuer" del documento Discovery) + oic.issuer=https://op.example.com + + # Configuración del cliente + oic.client.id=your-client-id + oic.client.secret=your-client-secret + oic.scope=openid email profile + + # URL base (usar HTTPS para producción) + oic.base.url=https://fess.example.com + +Solución de problemas +===================== + +Problemas comunes y soluciones +-------------------------------- + +No se puede regresar a |Fess| después de la autenticación +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verifique que la URI de redirección esté configurada correctamente en el lado del OP +- Asegúrese de que el valor de ``oic.redirect.url`` o ``oic.base.url`` coincida con la configuración del OP +- Verifique que el protocolo (HTTP/HTTPS) coincida + +Ocurren errores de autenticación +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verifique que el ID de cliente y el secreto del cliente estén configurados correctamente +- Asegúrese de que el scope incluya ``openid`` +- Verifique que la URL del endpoint de autorización y la URL del endpoint de token sean correctas +- Si el inicio de sesión falla, ``fess.log`` contiene una advertencia ``Failed to process the OpenID Connect callback:`` seguida del motivo +- ``The ID token was not issued for this client``: el claim ``aud`` del ID Token no es ``oic.client.id``; verifique el ID de cliente +- ``The ID token has expired``: los relojes del host de |Fess| y del OP difieren en más de 300 segundos; sincronice la hora (NTP) +- ``The ID token was not issued by the configured issuer``: ``oic.issuer`` difiere del ``iss`` que muestra el mensaje; copie exactamente el valor ``issuer`` del documento Discovery +- ``oic.token.server.url must be https``: utilice una URL de endpoint de token HTTPS (``http`` solo funciona con ``localhost``, ``127.x.x.x`` y ``::1``; ``http`` hacia el nombre de un servicio de Docker Compose o un nombre de host interno también se rechaza) + +No se puede recuperar información del usuario +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Asegúrese de que el scope incluya los permisos requeridos (``email``, ``profile``, etc.) +- Verifique que los scopes requeridos estén permitidos para el cliente en el lado del OP +- Con Microsoft Entra ID, el claim ``groups`` contiene los ``ObjectId`` (GUID) de los grupos salvo + que se seleccione otro atributo de origen, por lo que los valores no coincidirán con los nombres + de grupo +- Microsoft Entra ID omite por completo el claim ``groups`` cuando el usuario pertenece a más de + 200 grupos (los grupos anidados cuentan para este límite), y entonces |Fess| recurre a + ``oic.default.groups`` + +Configuración de depuración +----------------------------- + +Para investigar problemas, puede mostrar logs detallados relacionados con OpenID Connect ajustando el nivel de log de |Fess|. + +En ``app/WEB-INF/classes/log4j2.xml``, puede agregar el siguiente logger para cambiar el nivel de log: + +:: + + + +.. warning:: + Con este logger en DEBUG, los claims del ID Token (como ``email`` y ``groups``) se escriben en el + archivo de log. Restaure el nivel de log cuando termine la investigación y trate la salida del log + en consecuencia. + +Referencia +========== + +- :doc:`security-role` - Configuración de búsqueda basada en roles +- :doc:`sso-saml` - Configuración de SSO con autenticación SAML +- :doc:`sso-entraid` - Configuración de SSO específica para Microsoft Entra ID (si utiliza Entra ID, también puede usar la configuración dedicada en lugar de la configuración genérica de OpenID Connect) diff --git a/es/15.10/config/sso-saml.rst b/es/15.10/config/sso-saml.rst new file mode 100644 index 000000000..4cd7d124b --- /dev/null +++ b/es/15.10/config/sso-saml.rst @@ -0,0 +1,655 @@ +============================================= +Configuración de SSO con autenticación SAML +============================================= + +Descripción general +=================== + +|Fess| soporta autenticación Single Sign-On (SSO) utilizando SAML (Security Assertion Markup Language) 2.0. +Al utilizar autenticación SAML, la información del usuario autenticada por un IdP (Identity Provider) puede integrarse con |Fess|, permitiendo mostrar resultados de búsqueda basados en los permisos del usuario cuando se combina con la búsqueda basada en roles. + +.. note:: + La compatibilidad con la autenticación SAML proviene del plugin ``fess-sso-saml``, que no + forma parte de la distribución. Instálelo desde la página **Sistema > Plugin** de la + pantalla de administración o con ``bin/fess-setup install plugin fess-sso-saml``. + Hasta entonces, con ``sso.type=saml`` toda petición a ``/sso/`` solo se redirige de vuelta a + la página de inicio de sesión. + +Cómo funciona la autenticación SAML +----------------------------------- + +En la autenticación SAML, |Fess| opera como un SP (Service Provider) y colabora con un IdP externo para la autenticación. + +1. El usuario accede al endpoint SSO de |Fess| (``/sso/``) +2. |Fess| redirige la solicitud de autenticación al IdP +3. El usuario se autentica en el IdP +4. El IdP envía la aserción SAML a |Fess| +5. |Fess| valida la aserción e inicia sesión del usuario + +.. note:: + Solo se admite el inicio de sesión iniciado por el SP, que comienza en el endpoint SSO de |Fess| + (``/sso/``) tal como se describe arriba. |Fess| vincula cada respuesta SAML al identificador de la + AuthnRequest que envió, por lo que una respuesta iniciada por el IdP (no solicitada), por ejemplo + desde un icono de |Fess| en el panel de Okta o en el portal «Mis aplicaciones» de Microsoft Entra + ID, no tiene ninguna AuthnRequest con la que emparejarse y se rechaza. Si coloca un icono en el + lado del IdP, haga que apunte al endpoint ``/sso/`` de |Fess|. + + Tenga en cuenta que en 15.7 el inicio de sesión iniciado por el IdP funcionaba de forma incidental + cuando se establecía ``tomcat.sameSiteCookies=none``: |Fess| devolvía al IdP la respuesta que no + podía emparejar y el IdP entregaba de inmediato una aserción solicitada. En 15.10 ya no se devuelve + la respuesta, por lo que el inicio de sesión iniciado por el IdP no funciona. + +Para la integración con búsqueda basada en roles, consulte :doc:`security-role`. + +Prerrequisitos +============== + +Antes de configurar la autenticación SAML, verifique los siguientes prerrequisitos: + +- |Fess| 15.10 o superior está instalado +- Un IdP (Identity Provider) compatible con SAML 2.0 está disponible +- |Fess| es accesible a través de HTTPS (requerido para entornos de producción) +- Tiene permiso para registrar |Fess| como SP en el lado del IdP + +Ejemplos de IdP soportados: + +- Microsoft Entra ID (Azure AD) +- Okta +- Google Workspace +- Keycloak +- OneLogin +- Otros IdP compatibles con SAML 2.0 + +Configuración básica +==================== + +Habilitar SSO +------------- + +Para habilitar la autenticación SAML, agregue la siguiente configuración en ``app/WEB-INF/conf/system.properties``: + +:: + + sso.type=saml + +.. note:: + ``sso.type`` y la configuración SAML básica (información del IdP, información del SP, mapeo de atributos de usuario) también pueden configurarse desde la página «Sistema > General» del panel de administración. + Los cambios realizados en el panel de administración se guardan en ``system.properties`` y se conservan tras el reinicio. + Sin embargo, los ajustes de seguridad como firma/cifrado y el certificado/clave privada del SP no pueden configurarse desde el panel de administración, por lo que deben escribirse directamente en ``system.properties``. + +.. note:: + Los ajustes que comienzan por ``saml.`` se leen únicamente de ``system.properties``. + Las propiedades de sistema de la JVM, como ``-Dsaml.security....`` o ``-Dfess.saml.security....``, no se consultan. + En particular, ``saml.security.*``, ``saml.strict`` y ``saml.debug`` tampoco tienen ningún campo en el panel de administración, + por lo que escribirlos directamente en ``system.properties`` es la única forma de configurarlos. + +Configuración de la cookie de sesión +------------------------------------ + +El IdP devuelve la aserción a |Fess| mediante un **POST entre sitios**. Una cookie ``SameSite=Lax`` no se envía en ese tipo de petición, por lo que el inicio de sesión SAML no se completa con el valor predeterminado que incluye |Fess|. + +Cambie ``tomcat.sameSiteCookies`` a ``none`` en ``tomcat_config.properties``. Este archivo se encuentra en ``lib/classes/`` en el paquete ZIP y en ``/etc/fess/`` en los paquetes DEB/RPM. + +:: + + tomcat.sameSiteCookies = none + +.. warning:: + Los navegadores solo aceptan ``none`` en una cookie que además tenga el atributo ``Secure``, por lo que |Fess| debe servirse mediante HTTPS. Sobre HTTP simple, esta opción impide iniciar sesión en |Fess|. + +.. note:: + El valor predeterminado ``lax`` está pensado para los métodos de SSO cuya respuesta vuelve como redirección (GET). El enlace HTTP-POST de SAML no lo es, por lo que este cambio solo es necesario al usar SAML. |Fess| debe reiniciarse tras cambiar la configuración. + +Configuración del SP (Service Provider) +--------------------------------------- + +Para configurar |Fess| como SP, especifique la URL base del SP. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propiedad + - Descripción + - Por defecto + * - ``saml.sp.base.url`` + - URL base del SP + - ``http://localhost:8080`` + +.. note:: + El valor por defecto de ``saml.sp.base.url`` es ``http://localhost:8080``. + Fuera de entornos de prueba, establezca siempre la URL utilizada para acceder a |Fess| externamente (HTTPS en producción). + +Esta configuración configura automáticamente los siguientes endpoints: + +- **Entity ID**: ``{saml.sp.base.url}/sso/metadata`` +- **ACS URL**: ``{saml.sp.base.url}/sso/`` +- **SLO URL**: ``{saml.sp.base.url}/sso/logout`` + +Ejemplo:: + + saml.sp.base.url=https://fess.example.com + +Configuración de URL individual +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Normalmente, al configurar ``saml.sp.base.url`` cada URL de endpoint se configura automáticamente, pero si es necesario puede anular las URLs individuales explícitamente con las siguientes propiedades. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propiedad + - Descripción + - Por defecto + * - ``saml.sp.entityid`` + - Entity ID del SP + - ``{saml.sp.base.url}/sso/metadata`` + * - ``saml.sp.assertion_consumer_service.url`` + - URL del servicio Assertion Consumer + - ``{saml.sp.base.url}/sso/`` + * - ``saml.sp.single_logout_service.url`` + - URL del servicio Single Logout + - ``{saml.sp.base.url}/sso/logout`` + +Configuración del IdP (Identity Provider) +----------------------------------------- + +Configure la información obtenida de su IdP. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propiedad + - Descripción + - Por defecto + * - ``saml.idp.entityid`` + - Entity ID del IdP + - (Requerido) + * - ``saml.idp.single_sign_on_service.url`` + - URL del servicio SSO del IdP + - (Requerido) + * - ``saml.idp.x509cert`` + - Certificado X.509 de firma del IdP (codificado en Base64, sin saltos de línea) + - (Requerido) + * - ``saml.idp.single_logout_service.url`` + - URL del servicio SLO del IdP + - (Opcional) + +.. note:: + Para ``saml.idp.x509cert``, especifique solo el contenido codificado en Base64 del certificado en una sola línea sin saltos de línea. + No incluya las líneas ``-----BEGIN CERTIFICATE-----`` y ``-----END CERTIFICATE-----``. + +Obtener metadatos del SP +------------------------ + +Después de iniciar |Fess|, puede obtener los metadatos del SP en formato XML desde el endpoint ``/sso/metadata``. + +:: + + https://fess.example.com/sso/metadata + +Importe estos metadatos en su IdP, o registre manualmente el SP en el lado del IdP usando el contenido de los metadatos. + +.. note:: + Para obtener los metadatos, primero debe completar la configuración SAML básica (``sso.type=saml`` y ``saml.sp.base.url``) e iniciar |Fess|. + +Configuración del lado del IdP +============================== + +Al registrar |Fess| como SP en el lado del IdP, configure la siguiente información: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Configuración + - Valor + * - ACS URL / Reply URL + - ``https:///sso/`` + * - Entity ID / Audience URI + - ``https:///sso/metadata`` + * - Name ID Format + - ``urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`` (Recomendado) + +Información a obtener del IdP +----------------------------- + +Obtenga la siguiente información de la pantalla de configuración o metadatos de su IdP para usar en la configuración de |Fess|: + +- **Entity ID del IdP**: URI que identifica al IdP +- **URL SSO (HTTP-Redirect)**: URL del endpoint de Single Sign-On +- **Certificado X.509**: Certificado de clave pública usado para verificación de firma de la aserción SAML + +Mapeo de atributos de usuario +============================= + +Puede mapear los atributos de usuario obtenidos de las aserciones SAML a grupos y roles de |Fess|. + +Configuración de atributos de grupo +----------------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propiedad + - Descripción + - Por defecto + * - ``saml.attribute.group.name`` + - Nombre del atributo que contiene información de grupo + - ``memberOf`` + * - ``saml.default.groups`` + - Grupos por defecto (separados por comas) + - (Ninguno) + +Ejemplo:: + + saml.attribute.group.name=groups + saml.default.groups=user + +.. note:: + |Fess| utiliza directamente los valores de grupo de la aserción: no realiza ninguna consulta al + directorio ni expande los grupos anidados (transitivos). Por lo tanto, que aparezcan los grupos + padre depende únicamente de la configuración de claims del IdP, a diferencia de + :doc:`sso-entraid`, donde |Fess| resuelve los grupos padre mediante la API de Microsoft Graph. + +Configuración de atributos de rol +--------------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propiedad + - Descripción + - Por defecto + * - ``saml.attribute.role.name`` + - Nombre del atributo que contiene información de rol + - (Ninguno) + * - ``saml.default.roles`` + - Roles por defecto (separados por comas) + - (Ninguno) + +Ejemplo:: + + saml.attribute.role.name=roles + saml.default.roles=viewer + +.. note:: + Si los atributos no pueden obtenerse del IdP, se usarán los valores por defecto. + Al usar búsqueda basada en roles, configure los grupos o roles apropiados. + +.. warning:: + Cuando se configura ``saml.attribute.role.name``, los valores de atributo enviados por el IdP se + convierten directamente en roles de |Fess|. Como ``authentication.admin.roles`` en + ``fess_config.properties`` tiene el valor predeterminado ``admin``, cualquier usuario cuyo + atributo de rol contenga ``admin`` obtiene privilegios de administrador en |Fess|. Compruebe + quién puede controlar el atributo de rol en el IdP y, si es necesario, cambie + ``authentication.admin.roles`` por otro nombre. + +IdP que repiten un nombre de atributo +------------------------------------- + +Si el IdP reparte el mismo nombre de atributo entre varios elementos ````, |Fess| +rechaza la aserción y el inicio de sesión falla. + +Keycloak envía aserciones con esta forma de manera predeterminada: sus mapeadores de roles y grupos +emiten un elemento ```` por cada valor salvo que se active su opción ``single``, y toda +cuenta de Keycloak tiene varios roles de reino predeterminados. + +Hay dos soluciones: + +- Agrupar los valores en un solo elemento en el IdP (en Keycloak, active la opción ``single`` de los + mapeadores) +- Aceptar las repeticiones en |Fess| y fusionar sus valores + +.. list-table:: + :header-rows: 1 + :widths: 45 40 15 + + * - Propiedad + - Descripción + - Por defecto + * - ``saml.security.allow_duplicated_attribute_name`` + - Permite el mismo nombre de atributo en varios elementos y fusiona sus valores + - ``false`` + +Ejemplo:: + + saml.security.allow_duplicated_attribute_name=true + +Configuración de seguridad +========================== + +Para entornos de producción, se recomienda habilitar las siguientes configuraciones de seguridad. + +.. note:: + Si permanecen configuraciones no recomendadas, se escribe en el registro una advertencia + ``Insecure SAML settings: ...`` al cargar la configuración SAML. + +Configuración de firma +---------------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propiedad + - Descripción + - Por defecto + * - ``saml.security.authnrequest_signed`` + - Firmar solicitudes de autenticación + - ``false`` + * - ``saml.security.want_messages_signed`` + - Requerir firmas de mensajes + - ``false`` + * - ``saml.security.want_assertions_signed`` + - Requerir firmas de aserciones + - ``false`` + * - ``saml.security.logoutrequest_signed`` + - Firmar solicitudes de cierre de sesión + - ``false`` + * - ``saml.security.logoutresponse_signed`` + - Firmar respuestas de cierre de sesión + - ``false`` + * - ``saml.security.reject_deprecated_alg`` + - Rechazar algoritmos de firma obsoletos como SHA-1 + - ``false`` + +.. warning:: + Las funciones de seguridad están deshabilitadas por defecto. + Para entornos de producción, se recomienda encarecidamente configurar al menos ``saml.security.want_assertions_signed=true``. + +.. note:: + Mientras ``saml.security.reject_deprecated_alg`` sea ``false``, también se aceptan aserciones y + mensajes firmados con SHA-1 (``rsa-sha1`` y ``dsa-sha1``). No está habilitado por defecto porque + activarlo hace que se rechacen los IdP que siguen firmando con SHA-1. + Confirme que su IdP firma con SHA-256 o superior y, a continuación, configure + ``saml.security.reject_deprecated_alg=true``. + +.. warning:: + Cuando se configura el cierre de sesión único (``saml.idp.single_logout_service.url``), establezca + siempre también ``saml.security.want_messages_signed=true``. + Mientras sea ``false``, se acepta una LogoutRequest sin firma, por lo que una URL manipulada puede + terminar la sesión de un usuario autenticado. + El impacto es un cierre de sesión forzado (denegación de servicio), no una apropiación de la cuenta. + +Configuración de cifrado +------------------------ + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propiedad + - Descripción + - Por defecto + * - ``saml.security.want_assertions_encrypted`` + - Requerir cifrado de aserciones + - ``false`` + * - ``saml.security.want_nameid_encrypted`` + - Requerir cifrado de NameID + - ``false`` + * - ``saml.security.allowed_key_transport_algorithms`` + - Algoritmos de transporte de clave aceptados al descifrar una aserción (URI separados por comas) + - (vacío: se acepta cualquier algoritmo) + +.. note:: + |Fess| valida las respuestas cifradas con XML Encryption 1.1. Keycloak actual, por ejemplo, + usa ``http://www.w3.org/2009/xmlenc11#rsa-oaep`` e incluye un elemento ```` en + su respuesta; una respuesta así se acepta con la validación de esquema activada. Las + versiones anteriores la rechazaban con + ``Invalid SAML Response. Not match the saml-schema-protocol-2.0.xsd``. Si se estableció + ``saml.security.want_xml_validation=false`` como solución alternativa, elimínelo. + +.. note:: + Establezca ``saml.security.allowed_key_transport_algorithms`` siempre que haya una clave + privada de SP configurada. Mientras no se establezca, se acepta cualquier algoritmo de + transporte de clave, incluido el antiguo ``http://www.w3.org/2001/04/xmlenc#rsa-1_5``. El + punto final del consumidor de aserciones es anónimo y el descifrado se ejecuta antes de + validar la respuesta, por lo que quien llame sin autenticarse puede hacer que la clave + privada del SP descifre un texto cifrado de su elección. Mientras sea así, |Fess| informa + ``key_transport_algorithms_not_restricted`` en la línea ``Insecure SAML settings`` al + arrancar. Restrínjalo a lo que el IdP utiliza realmente:: + + saml.security.allowed_key_transport_algorithms=http://www.w3.org/2009/xmlenc11#rsa-oaep + +Configuración del certificado y clave privada del SP +---------------------------------------------------- + +Cuando el SP firma solicitudes de autenticación o mensajes de cierre de sesión (p. ej., ``saml.security.authnrequest_signed``), o solicita el cifrado de aserciones o NameID (p. ej., ``saml.security.want_assertions_encrypted``), debe configurar la clave privada y el certificado X.509 del SP. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propiedad + - Descripción + - Por defecto + * - ``saml.sp.x509cert`` + - Certificado X.509 del SP (codificado en Base64, sin saltos de línea) + - (vacío) + * - ``saml.sp.privatekey`` + - Clave privada del SP (codificada en Base64, sin saltos de línea) + - (vacío) + +.. note:: + Para ``saml.sp.x509cert`` y ``saml.sp.privatekey``, al igual que con ``saml.idp.x509cert``, especifique el contenido codificado en Base64 en una sola línea sin saltos de línea (no incluya las líneas ``-----BEGIN ...-----`` y ``-----END ...-----``). + Al habilitar la firma/cifrado, registre también el certificado del SP en el lado del IdP. El certificado del SP se publica en los metadatos del SP en ``/sso/metadata``. + +Otras configuraciones de seguridad +---------------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propiedad + - Descripción + - Por defecto + * - ``saml.strict`` + - Modo estricto (realizar validación estricta) + - ``true`` + * - ``saml.security.want_xml_validation`` + - Validar el esquema XML de los mensajes + - ``true`` + * - ``saml.security.signature_algorithm`` + - Algoritmo de firma + - ``http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`` + * - ``saml.security.requested_authncontext`` + - Contexto de autenticación solicitado + - ``urn:oasis:names:tc:SAML:2.0:ac:classes:Password`` + * - ``saml.sp.nameidformat`` + - Formato del NameID + - ``urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`` + +.. note:: + |Fess| utiliza internamente una biblioteca SAML (java-saml), y las propiedades que comienzan con ``saml.`` se mapean a los ajustes correspondientes de la biblioteca (prefijo ``onelogin.saml2.``). + Por lo tanto, además de los listados aquí, puede especificar ajustes detallados en ``system.properties``, como bindings (p. ej., ``saml.sp.assertion_consumer_service.binding``), información de organización (``saml.organization.*``) e información de contacto (``saml.contacts.*``). + +Expiración del AuthnRequest +=========================== + +|Fess| envía una AuthnRequest al IdP por cada acceso a ``/sso/`` y registra su identificador en la sesión. +La respuesta SAML devuelta por el IdP se valida frente al identificador registrado. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propiedad + - Descripción + - Por defecto + * - ``saml.request.id.ttl`` + - Tiempo durante el que se conserva el identificador de una AuthnRequest sin respuesta (segundos) + - ``3600`` + +El identificador registrado se descarta una vez transcurrido este periodo. +Si expira (por ejemplo, porque se dejó abierta la página de inicio de sesión del IdP), la aserción devuelta no puede emparejarse y el inicio de sesión falla una sola vez. + +Ejemplos de configuración +========================= + +Configuración mínima (para pruebas) +----------------------------------- + +El siguiente es un ejemplo de configuración mínima para verificación en un entorno de pruebas. + +:: + + # Habilitar SSO + sso.type=saml + + # Configuración SP + saml.sp.base.url=https://fess.example.com + + # Configuración IdP (establecer valores obtenidos de la consola de administración del IdP) + saml.idp.entityid=https://idp.example.com/saml/metadata + saml.idp.single_sign_on_service.url=https://idp.example.com/saml/sso + saml.idp.x509cert=MIIDpDCCAoygAwIBAgI...(certificado codificado en Base64) + + # Grupos por defecto + saml.default.groups=user + +Configuración recomendada (para producción) +------------------------------------------- + +El siguiente es un ejemplo de configuración recomendada para entornos de producción. + +:: + + # Habilitar SSO + sso.type=saml + + # Configuración SP + saml.sp.base.url=https://fess.example.com + + # Configuración IdP + saml.idp.entityid=https://idp.example.com/saml/metadata + saml.idp.single_sign_on_service.url=https://idp.example.com/saml/sso + saml.idp.single_logout_service.url=https://idp.example.com/saml/logout + saml.idp.x509cert=MIIDpDCCAoygAwIBAgI...(certificado codificado en Base64) + + # Mapeo de atributos de usuario + saml.attribute.group.name=groups + saml.attribute.role.name=roles + saml.default.groups=user + + # Configuración de seguridad (recomendado para producción) + saml.security.want_assertions_signed=true + saml.security.want_messages_signed=true + + # Habilitar tras confirmar que el IdP firma con SHA-256 o superior + saml.security.reject_deprecated_alg=true + +Solución de problemas +===================== + +Problemas comunes y soluciones +------------------------------ + +No se puede regresar a Fess después de la autenticación +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verifique que la URL ACS esté configurada correctamente en el lado del IdP +- Asegúrese de que el valor de ``saml.sp.base.url`` coincida con la configuración del IdP +- La aserción SAML llega como un POST entre sitios desde el IdP. Cuando + ``tomcat.sameSiteCookies`` en ``tomcat_config.properties`` es ``lax`` (el valor predeterminado), el + navegador no envía la cookie de sesión con ella y el inicio de sesión falla una sola vez. + En ese caso, configure ``tomcat.sameSiteCookies = none`` (``SameSite=None`` requiere HTTPS) +- Si el inicio de sesión tardó demasiado en el IdP, el identificador de AuthnRequest ya no está + disponible cuando llega la aserción, por lo que el inicio de sesión falla una sola vez y hay que + empezarlo de nuevo +- |Fess| no define ``session-timeout`` en ``app/WEB-INF/web.xml``, por lo que se aplica el valor + predeterminado del contenedor de servlets, 30 minutos, más corto que los 3600 segundos de + ``saml.request.id.ttl``, y la sesión se descarta antes. Aumentar solo ``saml.request.id.ttl`` no da + a los usuarios más tiempo para completar el inicio de sesión en el IdP, así que amplíe también el + tiempo de espera de la sesión + +La validación de Destination falla detrás de un proxy inverso +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Cuando |Fess| se ejecuta detrás de un proxy inverso o balanceador de carga que termina TLS, la +validación de la aserción puede fallar aunque ``saml.sp.base.url`` esté configurado correctamente. + +El atributo ``Destination`` de la aserción se compara con la URL de la solicitud tal como llega a +|Fess|, que detrás de un proxy que termina TLS es una URL interna ``http://`` y no la externa a la +que el IdP envió la aserción. ``saml.sp.base.url`` no se utiliza para esta comparación, por lo que +configurarlo por sí solo no resuelve el problema. + +Configure ``saml.debug=true`` para que el motivo se escriba en el registro: + +:: + + The response was received at http://... instead of https://fess.example.com/sso/ + +Ajuste la configuración del conector en ``tomcat_config.properties`` al esquema y puerto visibles desde +el exterior. Estos ajustes se distribuyen comentados: + +:: + + tomcat.secure=true + tomcat.scheme=https + tomcat.proxyPort=443 + +Configure además el proxy inverso para que transmita a |Fess| la cabecera ``Host`` original, ya que la +parte del nombre de host de la URL de solicitud se construye a partir de esa cabecera. Es necesario +reiniciar |Fess| después de modificar ``tomcat_config.properties``. + +La misma validación se aplica a los mensajes de cierre de sesión único, así que configúrelo también si +utiliza SLO. + +Error de verificación de firma +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verifique que el certificado del IdP esté configurado correctamente +- Asegúrese de que el certificado no haya expirado +- El certificado debe especificarse solo como contenido codificado en Base64, sin saltos de línea + +El inicio de sesión falla por un nombre de atributo repetido +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Si el registro contiene una advertencia que comienza por ``The IdP repeated an attribute name in + the SAML assertion``, el IdP está repartiendo el mismo nombre de atributo entre varios elementos + ```` +- La aserción en sí superó la validación, por lo que el certificado y el desfase horario no son la causa +- Agrupe los atributos en el IdP o establezca ``saml.security.allow_duplicated_attribute_name=true`` + +Grupos/roles de usuario no reflejados +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verifique que los atributos estén configurados correctamente en el lado del IdP +- Asegúrese de que el valor de ``saml.attribute.group.name`` coincida con el nombre del atributo enviado por el IdP +- Con Microsoft Entra ID, el claim de grupos contiene los ``ObjectId`` (GUID) de los grupos salvo + que se seleccione otro atributo de origen, por lo que los valores no coincidirán con los nombres + de grupo +- Microsoft Entra ID omite por completo el claim de grupos cuando el usuario pertenece a más de 150 + grupos (los grupos anidados cuentan para este límite), y entonces |Fess| recurre a + ``saml.default.groups`` +- Habilite el modo de depuración para inspeccionar el contenido de la aserción SAML + +Configuración de depuración +--------------------------- + +Para investigar problemas, puede habilitar el modo de depuración con la siguiente configuración: + +:: + + saml.debug=true + +Al configurar ``saml.debug=true``, se imprime en el registro la razón detallada cuando falla la autenticación SAML. + +También puede obtener registros SAML detallados agregando el siguiente logger a ``app/WEB-INF/classes/log4j2.xml``: + +:: + + + +Referencia +========== + +- :doc:`security-role` - Configuración de búsqueda basada en roles +- :doc:`sso-oidc` - Configuración de SSO con OpenID Connect +- :doc:`sso-entraid` - Configuración de SSO exclusiva para Microsoft Entra ID diff --git a/es/15.10/config/sso-spnego.rst b/es/15.10/config/sso-spnego.rst new file mode 100644 index 000000000..b2a0fd30d --- /dev/null +++ b/es/15.10/config/sso-spnego.rst @@ -0,0 +1,496 @@ +==================================================== +Configuración de SSO con Auth Integrada de Windows +==================================================== + +Descripción general +=================== + +|Fess| soporta autenticación Single Sign-On (SSO) utilizando Autenticación Integrada de Windows (SPNEGO/Kerberos). +Al utilizar la Autenticación Integrada de Windows, los usuarios que han iniciado sesión en una computadora unida al dominio Windows pueden acceder a |Fess| sin operaciones de inicio de sesión adicionales. + +.. note:: + La compatibilidad con la Autenticación Integrada de Windows proviene del plugin + ``fess-sso-spnego``, que no forma parte de la distribución. Instálelo desde la página + **Sistema > Plugin** de la pantalla de administración o con + ``bin/fess-setup install plugin fess-sso-spnego``. + Hasta entonces, con ``sso.type=spnego`` toda petición a ``/sso/`` solo se redirige de vuelta + a la página de inicio de sesión. + +Cómo funciona la Autenticación Integrada de Windows +---------------------------------------------------- + +En la Autenticación Integrada de Windows, |Fess| utiliza el protocolo SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) para la autenticación Kerberos. + +1. El usuario inicia sesión en el dominio Windows +2. El usuario accede a |Fess| +3. |Fess| envía un desafío SPNEGO +4. El navegador obtiene un ticket Kerberos y lo envía al servidor +5. |Fess| valida el ticket y recupera el nombre de usuario +6. La información de grupo del usuario se recupera vía LDAP +7. El usuario inicia sesión y la información de grupo se aplica a la búsqueda basada en roles + +Para la integración con la búsqueda basada en roles, consulte :doc:`security-role`. + +Prerrequisitos +============== + +Antes de configurar la Autenticación Integrada de Windows, verifique los siguientes prerrequisitos: + +- |Fess| 15.10 o superior está instalado +- Un servidor Active Directory (AD) está disponible +- El servidor |Fess| es accesible desde el dominio AD +- Tiene permiso para configurar Nombres de Principal de Servicio (SPN) en AD +- Una cuenta para recuperar información de usuario vía LDAP está disponible + +Configuración del lado de Active Directory +========================================== + +Registro del Nombre de Principal de Servicio (SPN) +--------------------------------------------------- + +Necesita registrar un SPN para |Fess| en Active Directory. +Abra un símbolo del sistema en una computadora Windows unida al dominio AD y ejecute el comando ``setspn``. + +:: + + setspn -S HTTP/ + +Ejemplo: + +:: + + setspn -S HTTP/fess-server.example.local svc_fess + +Para verificar el registro: + +:: + + setspn -L + +.. note:: + Después de registrar el SPN, si ejecutó el comando en el servidor Fess, cierre sesión en Windows y vuelva a iniciar sesión. + +Configuración básica +==================== + +Habilitar SSO +------------- + +Para habilitar la Autenticación Integrada de Windows, agregue la siguiente configuración en ``app/WEB-INF/conf/system.properties``: + +:: + + sso.type=spnego + +Archivo de configuración de Kerberos +------------------------------------- + +Cree ``app/WEB-INF/classes/krb5.conf`` con la configuración de Kerberos. + +:: + + [libdefaults] + default_realm = EXAMPLE.LOCAL + default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + + [realms] + EXAMPLE.LOCAL = { + kdc = AD-SERVER.EXAMPLE.LOCAL + default_domain = EXAMPLE.LOCAL + } + + [domain_realm] + example.local = EXAMPLE.LOCAL + .example.local = EXAMPLE.LOCAL + +.. note:: + Reemplace ``EXAMPLE.LOCAL`` con su nombre de dominio AD (en mayúsculas) y ``AD-SERVER.EXAMPLE.LOCAL`` con el nombre de host de su servidor AD. + +.. warning:: + Un ticket de servicio cifrado con un tipo que no aparece en ``permitted_enctypes`` es rechazado por + el aceptador de Kerberos con ``encryption type not in permitted_enctypes list``. + Active Directory suele emitir tickets de servicio AES256, por lo que AES256 debe estar incluido. + +.. note:: + RC4 (``rc4-hmac``), 3DES y DES están deshabilitados de forma predeterminada en Java 17 y posteriores, + por lo que incluirlos no tiene efecto; el ejemplo anterior especifica solo AES. + ``aes256-cts-hmac-sha384-192`` y ``aes128-cts-hmac-sha256-128`` son los tipos AES-SHA2 (RFC 8009) + compatibles con Windows Server 2025. + Una cuenta de servicio que solo tiene una clave RC4 no puede usarse para la autenticación Kerberos; + restablezca su contraseña para que se generen claves AES. + +Archivo de configuración de inicio de sesión +--------------------------------------------- + +Cree ``app/WEB-INF/classes/auth_login.conf`` con la configuración de inicio de sesión JAAS. + +:: + + spnego-client { + com.sun.security.auth.module.Krb5LoginModule required; + }; + + spnego-server { + com.sun.security.auth.module.Krb5LoginModule required + storeKey=true + isInitiator=false; + }; + +.. note:: + Los nombres de archivo predeterminados para ``krb5.conf`` y ``auth_login.conf`` están definidos en ``spnego.krb5.conf`` y ``spnego.login.conf`` respectivamente, pero los archivos en sí deben crearse obligatoriamente. + SPNEGO se inicializa en el primer inicio de sesión, por lo que |Fess| arranca aunque falten estos archivos, pero el inicio de sesión SSO falla. + +Configuración requerida +----------------------- + +Agregue la siguiente configuración a ``app/WEB-INF/conf/system.properties``. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propiedad + - Descripción + - Por defecto + * - ``spnego.preauth.username`` + - Nombre de usuario de conexión AD + - (Requerido salvo que se use un keytab) + * - ``spnego.preauth.password`` + - Contraseña de conexión AD + - (Requerido salvo que se use un keytab) + * - ``spnego.krb5.conf`` + - Ruta del archivo de configuración de Kerberos + - ``krb5.conf`` + * - ``spnego.login.conf`` + - Ruta del archivo de configuración de inicio de sesión + - ``auth_login.conf`` + +.. note:: + Si deja vacíos tanto ``spnego.preauth.username`` como ``spnego.preauth.password``, el módulo de + inicio de sesión del servidor utiliza un keytab. + Si no desea almacenar la contraseña de la cuenta de servicio de AD en un archivo de configuración + de |Fess|, cree un keytab y configure ``spnego-server`` en ``auth_login.conf`` de la siguiente manera. + + :: + + spnego-server { + com.sun.security.auth.module.Krb5LoginModule required + useKeyTab=true + keyTab="/var/lib/fess/fess.keytab" + principal="HTTP/fess-server.example.local@EXAMPLE.LOCAL" + storeKey=true + isInitiator=false; + }; + +Configuración opcional +---------------------- + +Las siguientes configuraciones pueden agregarse según sea necesario. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propiedad + - Descripción + - Por defecto + * - ``spnego.login.client.module`` + - Nombre del módulo cliente + - ``spnego-client`` + * - ``spnego.login.server.module`` + - Nombre del módulo servidor + - ``spnego-server`` + * - ``spnego.allow.basic`` + - Permitir autenticación Basic + - ``true`` + * - ``spnego.allow.unsecure.basic`` + - Permitir autenticación Basic no segura + - ``false`` + * - ``spnego.prompt.ntlm`` + - Retroceder a autenticación Basic cuando se recibe un token NTLM + - ``true`` + * - ``spnego.allow.localhost`` + - Permitir acceso desde localhost + - ``false`` + * - ``spnego.allow.delegation`` + - Permitir delegación + - ``false`` + * - ``spnego.allowed.realms`` + - Reinos Kerberos aceptados además del reino del servidor (separados por comas) + - (Ninguno) + * - ``spnego.logger.level`` + - Nivel de log interno de la biblioteca SPNEGO (``1`` =FINEST, ``2`` =FINER, ``3`` =FINE, ``4`` =CONFIG, ``6`` =WARNING, ``7`` =SEVERE; cualquier otro valor, incluidos ``0`` y ``5``, se trata como INFO) + - (Automático) + +.. warning:: + ``spnego.allow.unsecure.basic=true`` puede enviar credenciales codificadas en Base64 sobre conexiones no cifradas. + Para entornos de producción, se recomienda encarecidamente establecer esto en ``false`` y usar HTTPS. + +.. note:: + Con ``spnego.allow.unsecure.basic=false`` (valor predeterminado), la autenticación básica solo + se ofrece en las peticiones en las que ``HttpServletRequest#isSecure()`` devuelve ``true``. + Si TLS se termina en un proxy inverso y la petición se reenvía a |Fess| por HTTP, ese valor es + ``false``, por lo que un cliente que no puede obtener un tique de Kerberos y recurre a NTLM no + puede iniciar sesión. Establezca ``tomcat.secure=true`` en ``tomcat_config.properties`` para + indicar a |Fess| que la petición llegó por HTTPS. Ese archivo se encuentra en ``lib/classes/`` + en la distribución ZIP y en ``/etc/fess/`` en los paquetes DEB/RPM, y hay que reiniciar |Fess| + después de modificarlo. + +.. warning:: + En |Fess| 15.10, un inicio de sesión se rechaza de forma predeterminada cuando el reino del + principal del cliente difiere del reino del servidor. Si los usuarios inician sesión desde un + dominio secundario de un árbol de dominios de AD o desde un bosque de confianza, indique esos + reinos en ``spnego.allowed.realms``, separados por comas. De lo contrario, los usuarios que + podían iniciar sesión hasta la versión 15.7 son rechazados con + ``Kerberos realm is not allowed``. + +.. warning:: + |Fess| identifica a un usuario por la parte del principal anterior a ``@``, por lo que el reino + no forma parte del nombre de usuario. Cuando indica reinos adicionales en + ``spnego.allowed.realms``, los usuarios que comparten un nombre de cuenta entre reinos — por + ejemplo, ``alice@CORP.EXAMPLE.COM`` y ``alice@PARTNER.EXAMPLE.COM`` — pasan a ser el mismo + usuario de |Fess| y comparten sus grupos, roles y permisos sobre los documentos. Añada un reino + solo cuando el nombre de cuenta identifique exactamente a una persona en todos los reinos que + indique. + +.. note:: + La lista de permitidos también se aplica al retroceso a la autenticación Basic. Si un usuario + introduce un nombre con la forma ``user@REALM``, ese reino se comprueba contra + ``spnego.allowed.realms`` y el inicio de sesión se rechaza cuando no está permitido. Un nombre + de cuenta simple, o la forma ``DOMAIN\user``, no indica ningún reino y se autentica en el reino + predeterminado de ``krb5.conf``. Como un inicio de sesión Basic se autentica directamente contra + el reino que el usuario escribe, mantenga la lista de permitidos al mínimo y considere + establecer ``spnego.allow.basic`` en ``false`` si confía en ella como límite de seguridad. + +.. note:: + Cuando ``spnego.prompt.ntlm=true`` (valor predeterminado), ``spnego.allow.basic`` también debe ser ``true``. + Si establece ``spnego.allow.basic=false``, debe establecer también ``spnego.prompt.ntlm=false``. + Si no se cumple esta condición, se producirá un error durante la inicialización de SPNEGO. + +.. note:: + ``spnego.logger.level`` controla el nivel de log del logger interno de la biblioteca SPNEGO (el logger llamado ``Spnego`` de ``java.util.logging``). + Si no se especifica, el nivel se determina automáticamente en función del nivel de log de |Fess|. + +Configuración LDAP +================== + +La configuración LDAP es requerida para recuperar información de grupo de usuarios autenticados vía Autenticación Integrada de Windows. +Configure los ajustes LDAP en el panel de administración de |Fess| bajo "Sistema" -> "General". + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Elemento + - Ejemplo + * - URL LDAP + - ``ldap://AD-SERVER.example.local:389`` + * - Base DN + - ``dc=example,dc=local`` + * - Bind DN + - ``svc_fess@example.local`` + * - Contraseña + - Contraseña del usuario de acceso AD + * - User DN + - ``%s@example.local`` + * - Filtro de cuenta + - ``(&(objectClass=user)(sAMAccountName=%s))`` + * - Atributo memberOf + - ``memberOf`` + +.. note:: + |Fess| lee el atributo ``memberOf`` del usuario con un solo nivel de profundidad, por lo que los + grupos anidados (un grupo que es miembro de otro grupo) no se expanden de forma predeterminada. + Para reflejar los grupos anidados de AD, establezca ``(member:1.2.840.113556.1.4.1941:=%s)`` como + Filtro de grupo (``ldap.group.filter``) en «Sistema» → «General» de la interfaz de administración. + La expansión se ejecuta de forma asíncrona tras el inicio de sesión, por lo que la entrada de + inicio de sesión del registro de auditoría solo contiene los grupos resueltos hasta ese momento. + +Configuración del navegador +============================ + +Se requieren configuraciones del navegador del cliente para usar la Autenticación Integrada de Windows. + +Internet Explorer / Microsoft Edge +----------------------------------- + +1. Abrir Opciones de Internet +2. Seleccionar la pestaña "Seguridad" +3. Hacer clic en "Sitios" para la zona "Intranet local" +4. Hacer clic en "Opciones avanzadas" y agregar la URL de Fess +5. Hacer clic en "Nivel personalizado" para la zona "Intranet local" +6. Bajo "Autenticación de usuario" -> "Inicio de sesión", seleccionar "Inicio de sesión automático solo en la zona Intranet" +7. En la pestaña "Opciones avanzadas", marcar "Habilitar autenticación integrada de Windows" + +Google Chrome +------------- + +Chrome normalmente usa la configuración de Opciones de Internet de Windows. +Si se necesita configuración adicional, configure ``AuthServerAllowlist`` vía Política de Grupo o registro. + +Mozilla Firefox +--------------- + +1. Ingresar ``about:config`` en la barra de direcciones +2. Buscar ``network.negotiate-auth.trusted-uris`` +3. Establecer la URL o dominio del servidor Fess (ej: ``https://fess-server.example.local``) + +Ejemplos de configuración +========================== + +Configuración mínima (para pruebas) +------------------------------------ + +El siguiente es un ejemplo de configuración mínima para un entorno de pruebas. + +``app/WEB-INF/conf/system.properties``: + +:: + + # Habilitar SSO + sso.type=spnego + + # Configuración SPNEGO + spnego.preauth.username=svc_fess + spnego.preauth.password=your-password + +``app/WEB-INF/classes/krb5.conf``: + +:: + + [libdefaults] + default_realm = EXAMPLE.LOCAL + default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + + [realms] + EXAMPLE.LOCAL = { + kdc = AD-SERVER.EXAMPLE.LOCAL + default_domain = EXAMPLE.LOCAL + } + + [domain_realm] + example.local = EXAMPLE.LOCAL + .example.local = EXAMPLE.LOCAL + +``app/WEB-INF/classes/auth_login.conf``: + +:: + + spnego-client { + com.sun.security.auth.module.Krb5LoginModule required; + }; + + spnego-server { + com.sun.security.auth.module.Krb5LoginModule required + storeKey=true + isInitiator=false; + }; + +Configuración recomendada (para producción) +-------------------------------------------- + +El siguiente es un ejemplo de configuración recomendada para entornos de producción. + +``app/WEB-INF/conf/system.properties``: + +:: + + # Habilitar SSO + sso.type=spnego + + # Configuración SPNEGO + spnego.preauth.username=svc_fess + spnego.preauth.password=your-secure-password + spnego.krb5.conf=krb5.conf + spnego.login.conf=auth_login.conf + + # Configuración de seguridad (producción) + spnego.allow.basic=false + spnego.allow.unsecure.basic=false + spnego.prompt.ntlm=false + spnego.allow.localhost=false + +.. note:: + Al establecer ``spnego.allow.basic=false``, también debe establecer ``spnego.prompt.ntlm=false``. + Como ``spnego.prompt.ntlm`` es ``true`` de forma predeterminada, omitir esta configuración provocará un error durante la inicialización. + +Solución de problemas +===================== + +Problemas comunes y soluciones +------------------------------- + +Aparece el diálogo de autenticación +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verifique que el servidor Fess está agregado a la zona Intranet local en la configuración del navegador +- Verifique que "Habilitar autenticación integrada de Windows" está habilitado +- Verifique que el SPN está correctamente registrado (``setspn -L ``) + +Ocurren errores de autenticación +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verifique que el nombre de dominio (mayúsculas) y el nombre del servidor AD en ``krb5.conf`` son correctos +- Verifique que ``spnego.preauth.username`` y ``spnego.preauth.password`` son correctos +- Verifique la conectividad de red al servidor AD + +No se puede recuperar la información de grupo +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Verifique que la configuración LDAP es correcta +- Verifique que el Bind DN y la contraseña son correctos +- Verifique que el usuario pertenece a grupos en AD + +El inicio de sesión devuelve HTTP 400 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Para un usuario que pertenece a muchos grupos, el ticket Kerberos (PAC) crece y la cabecera +``Authorization`` puede superar el límite predeterminado de Tomcat de 8 KB, que se responde con 400. +La petición nunca llega a |Fess|, por lo que no se registra nada en el log. +Aumente el límite en ``tomcat_config.properties``. + +:: + + tomcat.maxHttpHeaderSize=65536 + +La autenticación falla tras cambiar la contraseña de la cuenta de servicio +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +La credencial del servidor se obtiene una sola vez en el primer inicio de sesión y se almacena en +caché durante toda la vida del proceso. +Reinicie |Fess| después de cambiar la contraseña de la cuenta de servicio en AD o de sustituir el +keytab. También es necesario reiniciar tras modificar cualquier ajuste ``spnego.*``. + +Configuración de depuración +----------------------------- + +Para investigar problemas, puede mostrar logs detallados relacionados con SPNEGO. + +Para obtener el log detallado interno de la biblioteca SPNEGO, agregue lo siguiente a ``app/WEB-INF/conf/system.properties``. +``spnego.logger.level=1`` produce el log más detallado (FINEST). + +:: + + spnego.logger.level=1 + +Para obtener el log detallado del procesamiento de integración SPNEGO del lado de |Fess| (paquete ``org.codelibs.fess.sso.spnego``), agregue el siguiente logger a ``app/WEB-INF/classes/log4j2.xml``: + +:: + + + +.. note:: + Los logs de la propia biblioteca SPNEGO se emiten mediante ``java.util.logging`` y se controlan con ``spnego.logger.level``, no a través de ``log4j2.xml``. + Los logs del procesamiento de integración del lado de |Fess| se controlan con el logger de ``log4j2.xml``. + +Referencia +========== + +- :doc:`security-role` - Configuración de búsqueda basada en roles +- :doc:`sso-saml` - Configuración de SSO con autenticación SAML +- :doc:`sso-oidc` - Configuración de SSO con autenticación OpenID Connect +- :doc:`sso-entraid` - Configuración de SSO con Microsoft Entra ID diff --git a/es/15.10/dev/datastore-plugin.rst b/es/15.10/dev/datastore-plugin.rst new file mode 100644 index 000000000..6e665e9f5 --- /dev/null +++ b/es/15.10/dev/datastore-plugin.rst @@ -0,0 +1,577 @@ +========================================= +Desarrollo de Plugins de Almacén de Datos +========================================= + +Visión General +============== + +Al desarrollar un plugin de almacén de datos, puede agregar a |Fess| la +funcionalidad de obtener contenido desde nuevas fuentes de datos. El almacén +de datos obtiene registros de sistemas externos, como bases de datos, API o +archivos, los convierte en campos de índice de acuerdo con el script de +mapeo configurado en la consola de administración, y los registra en el +índice de |Fess|. + +Todos los conectores públicos (``fess-ds-*``), como CSV, JSON, bases de +datos, Git y diversos servicios en la nube, están implementados con este +mecanismo. Como plantilla de implementación se publica +`fess-ds-example `__, por lo +que, al crear un nuevo conector, resulta sencillo comenzar copiando este +proyecto. + +Estructura Básica +================== + +El plugin de almacén de datos se compone de los siguientes tres elementos: + +- Crear una clase que herede de ``AbstractDataStore`` +- Implementar los dos métodos ``getName()`` y ``storeData()`` +- Registrarla como componente en ``fess_ds++.xml`` + +Implementación Mínima +--------------------- + +.. code-block:: java + + package org.codelibs.fess.ds.example; + + import java.util.Map; + + import org.codelibs.fess.ds.AbstractDataStore; + import org.codelibs.fess.ds.callback.IndexUpdateCallback; + import org.codelibs.fess.entity.DataStoreParams; + import org.codelibs.fess.opensearch.config.exentity.DataConfig; + + public class ExampleDataStore extends AbstractDataStore { + + @Override + protected String getName() { + // Se utiliza como nombre del manejador. La convención es devolver el nombre simple de la clase + return this.getClass().getSimpleName(); + } + + @Override + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { + + // Implementar aquí la obtención y el procesamiento de los datos + } + } + +.. note:: + + Tanto ``getName()`` como ``storeData()`` son métodos abstractos + ``protected``. Tenga en cuenta que, en |Fess| 15.x, el paquete de + ``DataConfig`` es ``org.codelibs.fess.opensearch.config.exentity`` (el + anterior ``org.codelibs.fess.es.config.exentity`` ha quedado obsoleto). + +Registro del Componente +----------------------- + +Para que |Fess| reconozca el almacén de datos creado, registre el +componente en ``src/main/resources/fess_ds++.xml``. + +.. code-block:: xml + + + + + + + + + +Mediante ````, tras la creación del +componente se invoca automáticamente el método ``register()`` que posee +``AbstractDataStore``, y este se registra a sí mismo en +``DataStoreFactory``. El nombre registrado en este momento es el valor +devuelto por ``getName()`` (``ExampleDataStore`` en el ejemplo anterior), y +es el que se selecciona como «nombre del manejador» en la configuración del +almacén de datos de la consola de administración. + +AbstractDataStore +================= + +Métodos Principales +-------------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 20 45 + + * - Método + - Categoría + - Descripción + * - ``getName()`` + - Implementación (obligatoria) + - Método abstracto que devuelve el nombre del manejador del almacén de + datos. La convención es devolver ``getClass().getSimpleName()`` + * - ``storeData()`` + - Implementación (obligatoria) + - Método abstracto que obtiene, convierte y registra los datos en el + índice + * - ``register()`` + - Heredado (normalmente no requiere cambios) + - Se invoca automáticamente desde el ``postConstruct`` de + ``fess_ds++.xml`` y se registra en ``DataStoreFactory`` + * - ``store()`` + - Heredado (invocado por el framework) + - Punto de entrada invocado por el framework. Prepara + ``defaultDataMap`` y otros datos, y llama a ``storeData()`` + * - ``convertValue()`` + - Heredado (auxiliar) + - Evalúa con el motor de scripts el valor (plantilla) de ``scriptMap`` + * - ``getScriptType()`` + - Heredado (auxiliar) + - Obtiene el parámetro ``script_type`` (el valor predeterminado es + Groovy) + * - ``getReadInterval()`` + - Heredado (auxiliar) + - Obtiene el parámetro ``readInterval`` (en milisegundos) + * - ``sleep()`` + - Heredado (auxiliar) + - Duerme durante los milisegundos indicados (se utiliza para esperar + entre registros) + +Parámetros de storeData +----------------------- + +Parámetros que se pasan al método ``storeData()``: + +.. list-table:: + :header-rows: 1 + :widths: 25 35 40 + + * - Parámetro + - Tipo + - Descripción + * - ``dataConfig`` + - ``DataConfig`` + - Configuración del almacén de datos (ID, nombre del manejador, + parámetros, scripts, etc.) + * - ``callback`` + - ``IndexUpdateCallback`` + - Callback para registrar en el índice los documentos generados + * - ``paramMap`` + - ``DataStoreParams`` + - Valores configurados en el campo «Parámetros» de la consola de + administración. Se accede a ellos mediante ``getAsString(key)``, + ``getAsString(key, default)``, ``get(key)``, ``asMap()`` y + ``containsKey(key)`` + * - ``scriptMap`` + - ``Map`` + - Configuración del campo «Script» de la consola de administración. + La clave es el nombre del campo de índice, y el valor es la + plantilla de script que se evalúa + * - ``defaultDataMap`` + - ``Map`` + - Valores predeterminados de campo para cada documento (ID de + configuración, boost, role, mimetype, host virtual, etc.). El + framework los prepara + +.. warning:: + + El tipo de ``paramMap`` no es ``Map``, sino + ``DataStoreParams``. Dado que ``DataStoreParams`` no implementa + ``Map``, utilice ``getAsString()``, que devuelve una cadena, en lugar + de ``get()`` para obtener los valores. + +Flujo de Procesamiento de Datos +-------------------------------- + +La implementación de ``storeData()`` procesa los datos siguiendo este +flujo. + +#. Obtener los registros de origen desde el sistema externo. +#. Combinar los campos del registro de origen con ``paramMap.asMap()`` + para construir ``resultMap`` (el script se evalúa sobre este + ``resultMap``). +#. Evaluar cada entrada de ``scriptMap`` con + ``convertValue(scriptType, template, resultMap)`` y almacenar el + resultado en ``dataMap``. Es importante que el mapeo no se codifique de + forma fija en el código, sino que lo defina el administrador en el + campo «Script». +#. Invocar ``callback.store(paramMap, dataMap)`` para registrar el + documento en el índice. + +Ejemplo de Implementación +========================== + +Almacén de Datos Simple +----------------------- + +Ejemplo que obtiene registros desde una API externa y los registra en el +índice. + +.. code-block:: java + + @Override + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { + + // Obtener los parámetros (en DataStoreParams se usa getAsString) + final String apiUrl = paramMap.getAsString("api.url"); + final String apiKey = paramMap.getAsString("api.key"); + + // Tipo de evaluación del script (el valor predeterminado es Groovy) + final String scriptType = getScriptType(paramMap); + // Tiempo de espera entre registros (milisegundos) + final long readInterval = getReadInterval(paramMap); + + try { + // Obtener los datos del sistema externo + final List> records = fetchRecords(apiUrl, apiKey); + + for (final Map record : records) { + // Copiar los campos predeterminados para inicializar dataMap + final Map dataMap = new HashMap<>(defaultDataMap); + + // Construir resultMap combinando los parámetros y el registro de origen + // (el script se evalúa sobre este resultMap) + final Map resultMap = new LinkedHashMap<>(paramMap.asMap()); + resultMap.putAll(record); + + // Evaluar cada entrada de scriptMap para generar los campos de índice + for (final Map.Entry entry : scriptMap.entrySet()) { + final Object value = convertValue(scriptType, entry.getValue(), resultMap); + if (value != null) { + dataMap.put(entry.getKey(), value); + } + } + + // Registrar en el índice + callback.store(paramMap, dataMap); + + if (readInterval > 0) { + sleep(readInterval); + } + } + } catch (final Exception e) { + throw new DataStoreException("Failed to crawl data from " + apiUrl, e); + } + } + +``fetchRecords()`` es un método propio que obtiene la lista de registros +del sistema externo. Los nombres de los campos de cada registro obtenido +(``Map``) son los nombres que se pueden referenciar desde +los scripts de ``scriptMap``. ``DataStoreException`` es una clase del +paquete ``org.codelibs.fess.exception``. + +Soporte de Paginación +---------------------- + +Cuando se manejan grandes volúmenes de datos, el procesamiento se realiza +obteniendo los registros página por página. Si se extrae el procesamiento +por registro (la construcción de ``resultMap``, la evaluación de +``scriptMap`` y la llamada a ``callback.store()``) a un método como +``processRecord()``, es posible separarlo de la lógica de obtención. + +.. code-block:: java + + int offset = 0; + final int pageSize = 100; + + while (true) { + final List> records = fetchRecords(apiUrl, apiKey, offset, pageSize); + + if (records.isEmpty()) { + break; + } + + for (final Map record : records) { + processRecord(record, callback, paramMap, scriptMap, defaultDataMap); + } + + offset += pageSize; + } + +Implementación de Autenticación +================================ + +La autenticación con el sistema externo se implementa en el lado del +conector. A continuación se muestra un ejemplo de implementación con una +biblioteca cliente HTTP habitual; no se trata de una API proporcionada por +|Fess|. Incluya la biblioteca que utilice como dependencia del plugin. + +OAuth 2.0 +--------- + +.. code-block:: java + + protected String getAccessToken(final String clientId, final String clientSecret, final String refreshToken) { + // Ejemplo de obtención de un token de acceso mediante el token de actualización + final OkHttpClient client = new OkHttpClient(); + + final RequestBody body = new FormBody.Builder() + .add("grant_type", "refresh_token") + .add("client_id", clientId) + .add("client_secret", clientSecret) + .add("refresh_token", refreshToken) + .build(); + + final Request request = new Request.Builder() + .url("https://oauth.example.com/token") + .post(body) + .build(); + + try (Response response = client.newCall(request).execute()) { + final JsonNode json = objectMapper.readTree(response.body().string()); + return json.get("access_token").asText(); + } + } + +Autenticación con Clave API +---------------------------- + +.. code-block:: java + + protected Response callApi(final String url, final String apiKey) { + final Request request = new Request.Builder() + .url(url) + .addHeader("Authorization", "Bearer " + apiKey) + .build(); + + return httpClient.newCall(request).execute(); + } + +Manejo de Errores +================= + +Para errores fatales que deben interrumpir el procesamiento, lance +``DataStoreException``. + +.. code-block:: java + + @Override + protected void storeData(...) { + try { + // Procesamiento + } catch (final AuthenticationException e) { + logger.error("Authentication failed. Check your credentials.", e); + throw new DataStoreException("Authentication failed", e); + } catch (final RateLimitException e) { + logger.warn("Rate limit exceeded. Waiting..."); + sleep(60000L); + // Lógica de reintento + } catch (final Exception e) { + logger.error("Unexpected error occurred", e); + throw new DataStoreException("Failed to crawl data", e); + } + } + +.. note:: + + En conectores reales, como ``fess-ds-example``, para evitar que el + error de un solo registro detenga todo el rastreo, se captura + ``CrawlingAccessException`` a nivel de registro y se registra la URL + con error en ``FailureUrlService``. Además, se controla si se debe + interrumpir todo el rastreo mediante el indicador de interrupción de + ``DataStoreCrawlingException``. Si desea implementar un conector + robusto, consulte la implementación de ``ExampleDataStore``. + +Pruebas +======= + +Pruebas Unitarias +------------------ + +Los plugins de |Fess| se prueban utilizando ``LastaDiTestCase`` de +UTFlute. Las pruebas se escriben con JUnit 5 (Jupiter). Al sustituir +``IndexUpdateCallback`` por una implementación que recopila los +``dataMap`` registrados, es posible verificar el resultado del mapeo sin +utilizar bibliotecas de mocks. + +.. code-block:: java + + public class ExampleDataStoreTest extends LastaDiTestCase { + + public ExampleDataStore dataStore; + + @Override + protected String prepareConfigFile() { + return "test_app.xml"; + } + + @Override + public void setUp(final TestInfo testInfo) throws Exception { + super.setUp(testInfo); + dataStore = new ExampleDataStore(); + } + + @Test + public void test_getName() { + assertEquals("ExampleDataStore", dataStore.getName()); + } + + @Test + public void test_storeData() { + final TestIndexUpdateCallback callback = new TestIndexUpdateCallback(); + final DataStoreParams paramMap = new DataStoreParams(); + + final Map scriptMap = new HashMap<>(); + scriptMap.put("title", "title"); + + dataStore.storeData(new DataConfig(), callback, paramMap, scriptMap, new HashMap<>()); + + assertFalse(callback.getDataMapList().isEmpty()); + } + + // Callback de prueba que recopila los dataMap registrados + private static class TestIndexUpdateCallback implements IndexUpdateCallback { + private final List> dataMapList = new ArrayList<>(); + + @Override + public void store(final DataStoreParams paramMap, final Map dataMap) { + dataMapList.add(new HashMap<>(dataMap)); + } + + @Override + public long getExecuteTime() { + return 0; + } + + @Override + public long getDocumentSize() { + return dataMapList.size(); + } + + @Override + public void commit() { + // No hace nada + } + + public List> getDataMapList() { + return dataMapList; + } + } + } + +.. note:: + + ``setUp`` ya tiene la anotación ``@BeforeEach`` en la clase base, por + lo que no es necesario volver a añadir anotaciones de ciclo de vida al + sobrescribirlo. Cada método de prueba debe llevar la anotación + ``@Test`` (``org.junit.jupiter.api.Test``). + +Construcción e Instalación +=========================== + +pom.xml +------- + +El plugin se construye como un jar que utiliza ``fess-parent`` como POM +padre. Las dependencias de ``fess`` y ``opensearch`` se marcan como +``provided``, ya que en tiempo de ejecución las proporciona el propio +|Fess|. + +.. code-block:: xml + + + 4.0.0 + org.codelibs.fess + fess-ds-example + 15.10.0 + jar + + + org.codelibs.fess + fess-parent + 15.10.0 + + + + + + org.codelibs.fess + fess + provided + + + org.opensearch + opensearch + provided + + + + +Para las pruebas se utilizan JUnit 5 y +``org.dbflute.utflute:utflute-lastaflute``. + +Construcción +------------ + +.. code-block:: bash + + mvn clean package + +Se generará ``fess-ds-example-15.10.0.jar`` en el directorio ``target/``. + +Instalación +----------- + +Instale el JAR generado en |Fess| y reinicie |Fess|. Para más detalles +sobre el procedimiento de instalación, consulte +:doc:`../admin/plugin-guide`. Después de la instalación, cree una nueva +configuración desde «Rastreador > Almacén de Datos» en la consola de +administración y especifique en «Nombre del manejador» el nombre que +devuelve ``getName()`` (``ExampleDataStore`` en este ejemplo). + +Ejemplo de Configuración +======================== + +Ejemplo de configuración en la consola de administración: + +Parámetros +---------- + +En el campo «Parámetros» se describen las claves y los valores que el +conector lee desde ``paramMap``. + +:: + + api.url=https://api.example.com/v1 + api.key=your_api_key + +Script +------ + +En el campo «Script» se describe el mapeo con el formato +``lado izquierdo=lado derecho``. El lado izquierdo es el nombre del campo +de índice, y el lado derecho es un script (JavaScript en una configuración +recién creada; una configuración que no tiene registrado un tipo de script se +trata como Groovy) +que referencia un campo del registro de origen. A continuación se muestra +un ejemplo para el caso en que el registro de origen tiene los campos +``url``, ``title``, ``content``, ``updated_at`` y ``content_type``. + +:: + + url=url + title=title + content=content + last_modified=updated_at + mimetype=content_type + +.. note:: + + Los nombres de campo que se pueden referenciar en el lado derecho + dependen de los valores que el conector almacena en ``resultMap`` (los + valores de ``paramMap`` y los campos del registro de origen). En + conectores existentes, como CSV o JSON, puede añadirse un prefijo + propio como ``data.*``, por lo que debe consultar la documentación de + cada conector. + +Información de Referencia +========================== + +- :doc:`plugin-architecture` - Arquitectura de plugins +- :doc:`../admin/plugin-guide` - Instalación de plugins +- :doc:`../config/datastore/ds-overview` - Descripción general de los + conectores de almacén de datos +- `fess-ds-example `__ - + Plantilla de implementación de plugins de almacén de datos +- `GitHub: fess-ds-* `__ - Ejemplos + de conectores públicos diff --git a/es/15.10/dev/index.rst b/es/15.10/dev/index.rst new file mode 100644 index 000000000..c12ab3c24 --- /dev/null +++ b/es/15.10/dev/index.rst @@ -0,0 +1,27 @@ +================================== +Documentacion de Desarrollo de |Fess| +================================== + +Esta es la documentacion para el desarrollo de extensiones de |Fess|. + +.. toctree:: + :maxdepth: 2 + :caption: Vision General + + overview + +.. toctree:: + :maxdepth: 2 + :caption: Desarrollo de Plugins + + plugin-architecture + datastore-plugin + script-engine-plugin + webapp-plugin + ingest-plugin + +.. toctree:: + :maxdepth: 2 + :caption: Personalizacion + + theme-development diff --git a/es/15.10/dev/ingest-plugin.rst b/es/15.10/dev/ingest-plugin.rst new file mode 100644 index 000000000..7bcc7c9a7 --- /dev/null +++ b/es/15.10/dev/ingest-plugin.rst @@ -0,0 +1,182 @@ +================================== +Plugin Ingest +================================== + +Visión General +============== + +Los plugins Ingest proporcionan la funcionalidad de procesar y transformar +datos justo antes de que los documentos se registren en el índice. Cada +documento obtenido mediante el rastreo pasa por los Ingester registrados +antes de enviarse al índice. + +Casos de Uso +============ + +- Normalización de texto (conversión de ancho completo/medio, ajuste de + espacios en blanco, etc.) +- Adición de metadatos y campos personalizados +- Enmascaramiento de información sensible +- Conversión de valores (por ejemplo: decodificación de embeddings + vectoriales codificados) + +Clase Ingester +============== + +La funcionalidad de Ingest se implementa heredando de la clase abstracta +``org.codelibs.fess.ingest.Ingester``. ``Ingester`` proporciona métodos +``process`` que se invocan según el tipo de rastreo y la etapa de +procesamiento. Dado que todas las implementaciones por defecto devuelven +el ``target`` recibido tal cual (sin hacer nada), solo es necesario +sobrescribir los métodos que se necesiten. + +- ``protected Map process(Map target)`` + + Es el destino común de delegación de las dos versiones de métodos + ``Map``. Si se sobrescribe, se aplica tanto a los documentos del + rastreo de almacén de datos como a los del rastreo web/de archivos + (durante el registro en el índice). Para la mayoría de los casos de + uso, basta con sobrescribir únicamente este método. + +- ``public Map process(Map target, DataStoreParams params)`` + + Se invoca durante el rastreo de almacén de datos. Por defecto, + delega en ``process(target)``. + +- ``public Map process(Map target, AccessResult accessResult)`` + + Se invoca durante el registro en el índice del rastreo web/de + archivos. Por defecto, delega en ``process(target)``. + +- ``public ResultData process(ResultData target, ResponseData responseData)`` + + Se invoca durante el procesamiento de la respuesta del rastreo + web/de archivos (antes de guardar el resultado de acceso). Por + defecto, devuelve el ``target`` tal cual. + +Orden de ejecución (priority) +----------------------------- + +Cuando hay varios Ingester registrados, se ejecutan en orden ascendente +del campo ``priority`` (los valores más pequeños se ejecutan primero). +El valor por defecto es ``99``. Se puede establecer directamente en el +constructor o modificar mediante ``setPriority(int)``. + +.. code-block:: java + + public int getPriority() + public void setPriority(final int priority) + +Ejemplo de Implementación +========================= + +Ejemplo que sobrescribe ``process(Map)`` para normalizar +el contenido y añadir un campo personalizado: + +.. code-block:: java + + package org.codelibs.fess.ingest.example; + + import java.util.Map; + + import org.codelibs.fess.ingest.Ingester; + + public class ExampleIngester extends Ingester { + + public ExampleIngester() { + // Establece el orden de ejecución (los valores más pequeños se ejecutan primero; el valor por defecto es 99) + setPriority(50); + } + + @Override + protected Map process(final Map target) { + // Normalización del contenido + final Object content = target.get("content"); + if (content instanceof String) { + target.put("content", ((String) content).trim().replaceAll("\\s+", " ")); + } + + // Adición de un campo personalizado + target.put("ingested_by", ExampleIngester.class.getSimpleName()); + + // Devuelve el documento procesado + return target; + } + } + +.. note:: + + Si el método ``process`` devuelve ``null``, el registro en el + índice fallará. Como no existe un mecanismo para omitir documentos, + asegúrese siempre de devolver ``target``. + +Registro +======== + +Los Ingester se registran a través del contenedor DI. El plugin debe +incluir ``fess_ingest++.xml``. El sufijo ``++`` al final del nombre del +archivo es una convención de fusión que añade la configuración a +``fess_ingest.xml`` (que define ``ingestFactory``, encargado de +gestionar los Ingester) del núcleo de |Fess|. + +.. code-block:: xml + + + + + + + + + +Gracias a ````, tras crear el componente +se invoca ``Ingester#register()``, con lo que se registra a sí mismo en +``ingestFactory``. + +No existen elementos de configuración relacionados con la +funcionalidad de Ingest en ``fess_config.properties``. La activación o +desactivación depende de si el plugin está instalado, y el orden de +ejecución se controla mediante ``priority``. + +Flujo de Ejecución +================== + +Los Ingester se invocan en orden ascendente de ``priority`` justo antes +de que el documento procesado se envíe al índice, en los siguientes +puntos: + +- **Rastreo de almacén de datos**: se invoca + ``process(Map, DataStoreParams)`` justo antes de enviar el documento. +- **Rastreo web/de archivos (procesamiento de la respuesta)**: se + invoca ``process(ResultData, ResponseData)`` antes de guardar el + resultado del rastreo. +- **Rastreo web/de archivos (registro en el índice)**: se invoca + ``process(Map, AccessResult)`` justo antes de enviar el documento. + +En cualquiera de estos puntos, si un Ingester lanza una excepción, se +emite un registro de advertencia y el procesamiento continúa (el +registro en el índice de ese documento no se interrumpe). + +.. note:: + + Dado que los Ingester se registran en el entorno de ejecución del + rastreador (``ingestFactory``), funcionan como parte del proceso + de rastreo. + +Implementación de Referencia +============================ + +Como referencia de implementación, los siguientes plugins están +publicados en `CodeLibs `__ en GitHub: + +- ``fess-ingest-example`` - Implementación de ejemplo con la + configuración mínima +- ``fess-webapp-multimodal`` - Plugin que incluye ``EmbeddingIngester``, + encargado de decodificar embeddings vectoriales + +Información de Referencia +========================== + +- :doc:`plugin-architecture` - Arquitectura de plugins diff --git a/es/15.10/dev/overview.rst b/es/15.10/dev/overview.rst new file mode 100644 index 000000000..e36087c61 --- /dev/null +++ b/es/15.10/dev/overview.rst @@ -0,0 +1,238 @@ +======================================================= +Visión General de la Documentación para Desarrolladores +======================================================= + +Visión General +============== + +Esta sección explica el desarrollo de extensiones para |Fess|. +Proporciona información para extender |Fess|, incluyendo el desarrollo de plugins, +la creación de conectores personalizados y la personalización de temas. + +Audiencia Objetivo +================== + +- Desarrolladores que desean crear funciones personalizadas para |Fess| +- Desarrolladores que desean crear plugins +- Desarrolladores que desean comprender el código fuente de |Fess| + +Conocimientos Previos +--------------------- + +- Conocimientos básicos de Java 21 +- Conceptos básicos de Maven (sistema de compilación) +- Experiencia en desarrollo de aplicaciones web +- Conocimientos básicos de OpenSearch (|Fess| utiliza OpenSearch como motor de búsqueda) + +Entorno de Desarrollo +===================== + +Entorno Recomendado +------------------- + +- **JDK**: OpenJDK 21 o superior +- **IDE**: IntelliJ IDEA / Eclipse / VS Code +- **Herramienta de compilación**: Maven (no se exige una versión mínima para la compilación, pero se recomienda una versión 3.x reciente compatible con Java 21) +- **Git**: Control de versiones +- **OpenSearch**: Backend del motor de búsqueda (si se inicia desde el IDE, los módulos y plugins necesarios se descargan durante la compilación) + +Configuración Inicial +--------------------- + +|Fess| se compila como un proyecto Maven. Durante el desarrollo, lo más sencillo es iniciarlo desde el IDE. + +1. Obtención del código fuente: + + :: + + git clone https://github.com/codelibs/fess.git + +2. Importación al IDE: + + Importe el directorio obtenido al IDE como un proyecto Maven. + +3. Descarga de los módulos y plugins de OpenSearch: + + Solo la primera vez, utilice el siguiente comando para obtener en el directorio ``plugins`` + los módulos y plugins del motor de búsqueda. + + :: + + mvn antrun:run + +4. Inicio del servidor de desarrollo (desde el IDE): + + Ejecute o depure ``org.codelibs.fess.FessBoot`` en el IDE y abra + http://localhost:8080/ en el navegador. + La pantalla de administración está en http://localhost:8080/admin/ (cuenta inicial: ``admin`` / ``admin``). + +5. Compilación del paquete (creación de la distribución): + + Si necesita un paquete de distribución, ejecute el objetivo ``package``. + Los artefactos se generan en ``target/releases`` (agregue ``-DskipTests`` para omitir las pruebas unitarias). + + :: + + mvn package + + Al descomprimir la distribución generada, dispondrá del script de inicio ``bin/fess``. + + :: + + unzip target/releases/fess-*.zip + ./fess-*/bin/fess + +.. note:: + + El script de inicio ``bin/fess`` se incluye en el paquete de distribución (zip/rpm/deb). + Con solo ejecutar ``mvn package`` en el árbol del código fuente, no se genera ``bin/fess`` + directamente en la raíz del repositorio. + Para desarrollar desde el código fuente, ejecute ``FessBoot`` en el IDE como se indicó + anteriormente, o utilice el ``bin/fess`` de la distribución descomprimida. + +Visión General de la Arquitectura +================================= + +|Fess| está compuesto por los siguientes componentes principales: + +Estructura de Componentes +------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Componente + - Descripción + * - Capa Web + - Implementación MVC mediante el framework LastaFlute + * - Capa de Servicios + - Lógica de negocio + * - Capa de Acceso a Datos + - Acceso a OpenSearch con seguridad de tipos mediante DBFlute (ESFlute/FreeGen) + * - Rastreador + - Recopilación de contenido mediante la biblioteca fess-crawler + * - Motor de Búsqueda + - Búsqueda de texto completo mediante OpenSearch + +Frameworks Principales +---------------------- + +- **LastaFlute**: Framework web (acciones, formularios, validación) +- **DBFlute**: Framework de acceso a datos. Las clases de acceso con seguridad de tipos para + OpenSearch (``Bhv`` / ``ConditionBean``) se generan mediante la función FreeGen de DBFlute + y las plantillas de ESFlute (para regenerarlas, ejecute ``mvn dbflute:freegen``) +- **Lasta Di**: Contenedor de inyección de dependencias + +Estructura de Directorios +========================= + +:: + + fess/ + ├── src/main/java/org/codelibs/fess/ + │ ├── app/ + │ │ ├── web/ # Controladores (Action) + │ │ ├── service/ # Servicios + │ │ ├── logic/ # Lógica + │ │ └── pager/ # Paginación + │ ├── api/ # REST API (api/v2, etc.) + │ ├── helper/ # Clases auxiliares + │ ├── crawler/ # Relacionado con el rastreador + │ ├── indexer/ # Procesamiento de indexación + │ ├── opensearch/ # Acceso a OpenSearch (generado por ESFlute/FreeGen) + │ ├── llm/ # Integración con LLM + │ ├── ds/ # Conectores de almacén de datos + │ ├── ingest/ # Ingest (procesamiento de datos durante la indexación) + │ ├── script/ # Motor de scripts + │ ├── entity/ # Entidades + │ └── mylasta/ # Configuración de LastaFlute (DI, mensajes, configuración con seguridad de tipos) + ├── src/main/resources/ + │ ├── fess_config.properties # Configuración + │ └── fess_*.xml # Configuración DI (app.xml, fess_ds.xml, etc.) + └── src/main/webapp/ + └── WEB-INF/view/ # JSP de la administración y del inicio de sesión + +Puntos de Extensión +=================== + +|Fess| ofrece los siguientes puntos de extensión: + +Plugins +------- + +Puede agregar funciones utilizando plugins. + +- **Plugin de almacén de datos**: Rastreo desde nuevas fuentes de datos (extiende ``AbstractDataStore``) +- **Plugin de motor de scripts**: Compatibilidad con nuevos lenguajes de script (implementa ``ScriptEngine``) +- **Plugin de aplicación web**: Extensión de la interfaz web (sobrescritura de componentes de Lasta Di y fusión de recursos) +- **Plugin Ingest**: Procesamiento de datos durante la indexación (extiende ``Ingester``) + +Detalles: :doc:`plugin-architecture` + +.. note:: + + El propio |Fess| se empaqueta como ``war``. Al compilar plugins localmente, si no se puede + resolver |Fess| como dependencia, cambie temporalmente ```` en ``pom.xml`` a ``jar``, + ejecute ``mvn clean install -DskipTests`` y luego vuelva a cambiarlo a ``war``. + +Temas +----- + +Puede personalizar el diseño de la pantalla de búsqueda. + +Detalles: :doc:`theme-development` + +Configuración +------------- + +Puede personalizar muchos comportamientos mediante ``fess_config.properties``. + +Detalles: :doc:`../config/intro` + +Desarrollo de Plugins +===================== + +Para obtener más detalles sobre el desarrollo de plugins, consulte lo siguiente: + +- :doc:`plugin-architecture` - Arquitectura de plugins +- :doc:`datastore-plugin` - Desarrollo de plugins de almacén de datos +- :doc:`script-engine-plugin` - Plugin de motor de scripts +- :doc:`webapp-plugin` - Plugin de aplicación web +- :doc:`ingest-plugin` - Plugin Ingest + +Desarrollo de Temas +=================== + +- :doc:`theme-development` - Personalización de temas + +Mejores Prácticas +================= + +Convenciones de Codificación +---------------------------- + +- Seguir el estilo de código existente de |Fess| +- Formatear el código con ``mvn formatter:format`` +- Agregar encabezados de licencia con ``mvn license:format`` + +Pruebas +------- + +- Pruebas unitarias (``*Test.java``): se ejecutan con ``mvn test`` en el perfil ``build`` predeterminado +- Pruebas de integración (``*Tests.java``): se ejecutan con ``mvn test -P integrationTests``. + Para ejecutar las pruebas de integración se necesita un servidor |Fess| en ejecución y OpenSearch + +Registro +-------- + +- Utiliza Log4j2 +- ``logger.debug()`` / ``logger.info()`` / ``logger.warn()`` / ``logger.error()`` +- No registrar información sensible en los registros + +Recursos +======== + +- `Repositorio de GitHub `__ +- `Seguimiento de problemas `__ +- `Discusiones `__ diff --git a/es/15.10/dev/plugin-architecture.rst b/es/15.10/dev/plugin-architecture.rst new file mode 100644 index 000000000..60b391848 --- /dev/null +++ b/es/15.10/dev/plugin-architecture.rst @@ -0,0 +1,391 @@ +========================== +Arquitectura de Plugins +========================== + +Visión General +============== + +El sistema de plugins de |Fess| permite ampliar la funcionalidad +principal. Los plugins se distribuyen como archivos JAR y, al añadirse +al classpath, el contenedor DI (Lasta Di) carga los componentes y los +registra en la fábrica o el gestor correspondiente. + +Tipos de Plugins +================ + +|Fess| determina el tipo de plugin según el prefijo del nombre del +artefacto (``PluginHelper.ArtifactType``). Los tipos principales son los +siguientes: + +.. list-table:: + :header-rows: 1 + :widths: 20 25 55 + + * - Tipo + - Prefijo + - Descripción + * - Almacén de datos + - ``fess-ds-*`` + - Obtención de contenido desde nuevas fuentes de datos (Box, Slack, + Git, etc.) + * - Aplicación web + - ``fess-webapp-*`` + - Ampliación de la interfaz web o de las funciones de búsqueda + * - Motor de scripts + - ``fess-script-*`` + - Soporte para nuevos lenguajes de script + * - Ingest + - ``fess-ingest-*`` + - Procesamiento de documentos durante el registro en el índice + * - Miniatura + - ``fess-thumbnail-*`` + - Adición de métodos de generación de miniaturas + * - LLM + - ``fess-llm-*`` + - Adición de proveedores de LLM utilizados en RAG/chat + * - Rastreador + - ``fess-crawler-*`` + - Ampliación de clientes de rastreador + * - Almacenamiento + - ``fess-storage-*`` + - Adición de backends de almacenamiento de objetos para el rastreo y la función de almacenamiento + * - SSO + - ``fess-sso-*`` + - Adición de métodos de autenticación Single Sign-On seleccionados mediante ``sso.type`` + +.. note:: + + El tipo ``fess-theme-*`` (tema JAR), que proporcionaba JSP, se eliminó en 15.10. + El aspecto de la pantalla de búsqueda se cambia con un tema estático, no con un plugin + (consulte :doc:`theme-development`). + +Estructura del Plugin +====================== + +Estructura Básica +----------------- + +Tomando como ejemplo `fess-ds-example +`__, la plantilla de +implementación de un plugin de almacén de datos, un plugin se compone de +una «clase de implementación» y un «archivo de registro DI»: + +:: + + fess-ds-example/ + ├── pom.xml + └── src/main/ + ├── java/org/codelibs/fess/ds/example/ + │ └── ExampleDataStore.java # Implementación del almacén de datos + └── resources/ + └── fess_ds++.xml # Registro de componentes DI + +Ejemplo de pom.xml +------------------ + +Los plugins se construyen como jar con ``fess-parent`` como POM padre. +Las bibliotecas que se proporcionan en tiempo de ejecución desde el +propio |Fess|, como ``fess`` u ``opensearch``, se declaran con el ámbito +``provided``. El número de versión y la configuración de compilación +(formateador, cabeceras de licencia, etc.) se heredan del POM padre. + +.. code-block:: xml + + + + 4.0.0 + + org.codelibs.fess + fess-ds-example + 15.10.0 + jar + + + org.codelibs.fess + fess-parent + 15.10.0 + + + + + + org.codelibs.fess + fess + provided + + + org.opensearch + opensearch + provided + + + + +.. note:: + + En las ramas en desarrollo, la versión llevará el sufijo + ``-SNAPSHOT``, como en ``15.10.0-SNAPSHOT``. Las bibliotecas de + dependencia propias del plugin se declaran como dependencias Maven + normales. Puesto que no están incluidas en el propio |Fess|, deben + distribuirse junto con el plugin. + +Registro del Plugin +==================== + +Registro en el Contenedor DI +----------------------------- + +Los plugins registran sus componentes mediante un archivo de +configuración DI cuyo nombre termina en ``++``, como ``fess_ds++.xml``. +Lasta Di combina automáticamente los archivos con el sufijo ``++`` +encontrados en el classpath con el archivo de configuración +correspondiente del propio |Fess| (en este ejemplo, ``fess_ds.xml``). +Gracias a este mecanismo, el plugin puede añadir sus propios componentes +sin modificar los archivos del propio |Fess|. + +.. code-block:: xml + + + + + + + + + +Según el tipo de plugin, el archivo de destino de la fusión varía. Por +ejemplo, el motor de scripts utiliza ``fess_se++.xml``, Ingest utiliza +``fess_ingest++.xml``, los proveedores de LLM utilizan +``fess_llm++.xml``, y las aplicaciones web utilizan ``app++.xml``. + +Inicialización del Componente +------------------------------- + +```` es una configuración del ciclo de +vida de Lasta Di que especifica el método que se invoca tras la creación +del componente. En el caso de un almacén de datos, se invoca el método +``register()`` que posee ``AbstractDataStore``, y este se registra a sí +mismo en ``DataStoreFactory``: + +.. code-block:: java + + // Implementación de AbstractDataStore (normalmente no requiere sobrescritura) + public void register() { + ComponentUtil.getDataStoreFactory().add(getName(), this); + } + +.. note:: + + Esto no es la anotación ``@PostConstruct`` de Java, sino una + inicialización mediante el elemento ```` del archivo + de configuración DI. El nombre que se registra es el valor devuelto + por ``getName()``, y es el nombre que se selecciona al elegir el + plugin en la consola de administración. + +Ciclo de Vida del Plugin +========================== + +Inicialización +--------------- + +1. El JAR del plugin se añade al classpath. +2. El contenedor DI combina ``fess_*++.xml`` y crea los componentes. +3. Se invoca el método especificado en ```` (por ejemplo, + ``register``). +4. El plugin se registra en la fábrica o el gestor correspondiente. + +Finalización +------------- + +1. Al finalizar el contenedor DI, se invoca el método especificado en + ```` (si está definido). +2. Limpieza de recursos. + +.. note:: + + En el caso de un almacén de datos, ``AbstractDataStore.stop()`` + activa un indicador de detención en el rastreo en curso, y el bucle + de procesamiento de registros finaliza de forma segura. + +Dependencias +============ + +Dependencia con el Núcleo de Fess +----------------------------------- + +Puesto que las clases del propio |Fess| están presentes en el classpath +del servidor en tiempo de ejecución, se declaran como dependencia con el +ámbito ``provided`` (no se incluyen en el JAR del plugin). + +.. code-block:: xml + + + org.codelibs.fess + fess + provided + + +Bibliotecas Externas +---------------------- + +Los plugins pueden incluir sus propias bibliotecas de dependencia: + +.. code-block:: xml + + + com.example + example-sdk + 1.0.0 + + +Puesto que estas no están incluidas en el propio |Fess|, deben +distribuirse junto con el plugin. + +Obtención de la Configuración +================================ + +Obtención de Parámetros y de FessConfig +------------------------------------------ + +En el método ``storeData()`` del almacén de datos, los parámetros +configurados en la consola de administración se obtienen desde +``DataStoreParams``. Para obtener los valores, utilice +``getAsString()`` (dado que ``DataStoreParams`` no implementa ``Map``, +``get()`` no devuelve una cadena). Además, los valores de configuración +de |Fess| se pueden obtener desde ``ComponentUtil.getFessConfig()``: + +.. code-block:: java + + public class ExampleDataStore extends AbstractDataStore { + + @Override + protected String getName() { + // Se utiliza como nombre del manejador. La convención es devolver el nombre simple de la clase + return this.getClass().getSimpleName(); + } + + @Override + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { + + // Obtención de los parámetros + final String apiKey = paramMap.getAsString("api.key"); + final String baseUrl = paramMap.getAsString("base.url"); + + // Obtención de FessConfig + final FessConfig fessConfig = ComponentUtil.getFessConfig(); + } + } + +Para más detalles sobre la implementación de ``storeData()`` (el flujo +de obtención de datos, evaluación de scripts y registro en el índice), +consulte :doc:`datastore-plugin`. + +Construcción e Instalación +============================= + +Construcción +------------- + +:: + + mvn clean package + +En el directorio ``target/`` se generará un archivo JAR (por ejemplo, +``fess-ds-example-15.10.0.jar``). + +Instalación +------------ + +1. **Desde la consola de administración**: + + - Abra «Sistema» → «Plugin» → «Instalar» + - Seleccione de la lista del repositorio de plugins, o suba el + archivo JAR compilado para instalarlo + +2. **Manual**: + + - Copie el archivo JAR al directorio ``app/WEB-INF/plugin/`` + - Reinicie |Fess| + +Para más detalles sobre el procedimiento de instalación, consulte +:doc:`../admin/plugin-guide`. + +Depuración +========== + +Salida de Logs +--------------- + +|Fess| utiliza Log4j2. El logger se obtiene mediante +``LogManager.getLogger()``: + +.. code-block:: java + + private static final Logger logger = LogManager.getLogger(ExampleDataStore.class); + + public void someMethod() { + logger.debug("Debug message"); + logger.info("Info message"); + } + +.. note:: + + No registre en los logs información sensible, como contraseñas o + tokens. + +Modo de Desarrollo +-------------------- + +Durante el desarrollo, puede depurar |Fess| iniciándolo desde el IDE: + +1. Ejecute en modo depuración la clase ``org.codelibs.fess.FessBoot``. +2. Incluya el código fuente del plugin en el proyecto. +3. Establezca puntos de interrupción. + +Lista de Plugins Públicos +============================ + +En el proyecto |Fess| se publican numerosos plugins. A continuación se +muestran algunos ejemplos representativos (esta lista no es exhaustiva): + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Plugin + - Descripción + * - ``fess-ds-box`` + - Conector de Box + * - ``fess-ds-dropbox`` + - Conector de Dropbox + * - ``fess-ds-slack`` + - Conector de Slack + * - ``fess-ds-atlassian`` + - Conector de JIRA / Confluence + * - ``fess-ds-git`` + - Conector de repositorios Git + * - ``fess-llm-openai`` + - Proveedor de LLM OpenAI + +Además de estos, también se publican conectores de almacén de datos como +``fess-ds-csv`` / ``fess-ds-db`` / ``fess-ds-json`` / +``fess-ds-microsoft365`` / ``fess-ds-sharepoint``, y proveedores de LLM +como ``fess-llm-ollama`` / ``fess-llm-gemini`` / ``fess-llm-bedrock``. Estos plugins se +publican en `GitHub `__ como referencia +para el desarrollo. + +Información de Referencia +============================ + +- :doc:`datastore-plugin` - Desarrollo de plugins de almacén de datos +- :doc:`script-engine-plugin` - Plugin de motor de scripts +- :doc:`webapp-plugin` - Plugin de aplicación web +- :doc:`ingest-plugin` - Plugin de Ingest +- :doc:`theme-development` - Personalización de temas +- :doc:`../admin/plugin-guide` - Instalación de plugins diff --git a/es/15.10/dev/script-engine-plugin.rst b/es/15.10/dev/script-engine-plugin.rst new file mode 100644 index 000000000..8cda14b72 --- /dev/null +++ b/es/15.10/dev/script-engine-plugin.rst @@ -0,0 +1,61 @@ +================================== +Plugin de Motor de Scripts +================================== + +Visión General +============== + +Al desarrollar un plugin de motor de scripts, puede agregar soporte para +nuevos lenguajes de script a |Fess|. + +Implementación Básica +===================== + +Implemente la interfaz ``ScriptEngine``: + +.. code-block:: java + + package org.codelibs.fess.script.example; + + import org.codelibs.fess.script.ScriptEngine; + import java.util.Map; + + public class ExampleScriptEngine implements ScriptEngine { + + @Override + public String getName() { + return "example"; + } + + @Override + public Object evaluate(String script, Map params) { + // Logica de evaluacion del script + return executeScript(script, params); + } + } + +Registro +======== + +.. code-block:: java + + @PostConstruct + public void register() { + ComponentUtil.getScriptEngineManager().add(this); + } + +Ejemplo de Uso +============== + +Seleccione como tipo de script en la pantalla de administración: + +:: + + scriptType=example + scriptData=your script here + +Información de Referencia +========================= + +- :doc:`plugin-architecture` - Arquitectura de plugins +- :doc:`../config/scripting-overview` - Visión general de scripting diff --git a/es/15.10/dev/theme-development.rst b/es/15.10/dev/theme-development.rst new file mode 100644 index 000000000..26b01e36f --- /dev/null +++ b/es/15.10/dev/theme-development.rst @@ -0,0 +1,364 @@ +=========================== +Guía de Desarrollo de Temas +=========================== + +Visión General +============== + +En |Fess| 15.10, la pantalla de búsqueda es siempre un tema estático. +Un tema estático es una SPA (Single Page Application, aplicación de +página única) independiente que utiliza la API ``/api/v2/*``. El tema +se distribuye como un archivo ZIP, que se sube y se activa desde la +consola de administración. Cuando no hay ningún tema seleccionado, +|Fess| utiliza ``bootstrap``, el tema estático incluido con él. + +Para cambiar el aspecto de la pantalla de búsqueda, instale otro tema +(consulte :doc:`../admin/theme-guide`) o cree el suyo propio: la forma +más rápida es copiar el tema incluido y modificar la copia, como se +describe en `Personalización del Tema Incluido`_. + +.. note:: + + Los temas estáticos están disponibles a partir de |Fess| 15.7 y se + convirtieron en la pantalla de búsqueda predeterminada en 15.10. Los + plugins de tema JAR, que sustituían las JSP de la pantalla de + búsqueda, se eliminaron en 15.10; consulte + `Plugin de Tema JAR (eliminado en 15.10)`_. + +Tema Estático +============= + +Un tema estático es un conjunto de recursos estáticos que incluye el +manifiesto ``theme.yml`` y el archivo ``index.html``. El propio tema se +implementa como una aplicación frontend que invoca la API +``/api/v2/*`` de |Fess|. + +Estructura +---------- + +Un tema estático tiene la siguiente estructura de directorios. + +:: + + example/ + ├── theme.yml # Manifiesto (obligatorio) + ├── index.html # HTML de entrada de la SPA + ├── assets/ # Recursos estáticos como JavaScript y CSS + │ └── styles.css + ├── i18n/ # Mensajes multilingües (messages..json) + │ └── messages.en.json + ├── help/ # Definiciones de ayuda (.json) + │ └── en.json + └── thumbnail.png # Imagen de vista previa (opcional) + +Manifiesto (theme.yml) +---------------------- + +``theme.yml`` es el manifiesto obligatorio que debe colocarse en la raíz +del ZIP. A continuación se muestra un ejemplo de configuración mínima. + +.. code-block:: yaml + + apiVersion: fess.codelibs.org/v1 + kind: StaticTheme + name: example + displayName: "Example Theme" + version: "15.10.0" + minFessVersion: "15.10" + entry: index.html + spaFallback: true + +Los campos que se pueden especificar son los siguientes. + +.. list-table:: + :header-rows: 1 + :widths: 22 12 66 + + * - Campo + - Obligatorio + - Descripción + * - ``apiVersion`` + - Obligatorio + - Valor fijo ``fess.codelibs.org/v1``. + * - ``kind`` + - Obligatorio + - Valor fijo ``StaticTheme``. + * - ``name`` + - Obligatorio + - Nombre del tema. Debe coincidir con + ``^[a-z0-9][a-z0-9_-]{0,63}$``. Se utiliza como nombre del + directorio del tema que se expande bajo ``themes/`` (al subir el + archivo, este se determina automáticamente a partir de + ``name``) y como URL de distribución (``/themes//``). + * - ``displayName`` + - Obligatorio + - Nombre que se muestra en la consola de administración. + * - ``version`` + - Obligatorio + - Formato de versionado semántico (ejemplo: ``15.10.0``, + ``15.10.1-beta.1``). Por convención, ``major.minor`` es la línea de |Fess| a la + que está destinado el tema, de modo que la versión por sí sola responde para + qué |Fess| es un tema. + * - ``author`` + - Opcional + - Nombre del autor. + * - ``description`` + - Opcional + - Descripción del tema. + * - ``license`` + - Opcional + - Licencia. + * - ``homepage`` + - Opcional + - URL de la página de inicio. + * - ``minFessVersion`` + - Opcional + - Versión mínima de |Fess| compatible con el tema. Manténgala igual al + ``major.minor`` de ``version``. No existe ``maxFessVersion``: consulte + `Publicación`_. + * - ``supportedLocales`` + - Opcional + - Lista de configuraciones regionales admitidas (ejemplo: + ``[en, ja, de]``). + * - ``entry`` + - Opcional + - HTML de entrada de la SPA. El valor predeterminado es + ``index.html``. + * - ``spaFallback`` + - Opcional + - Obsoleto. Se acepta por compatibilidad, pero ya no se lee: desde + 15.10 el HTML de entrada se sirve siempre para las rutas de la + pantalla de búsqueda. + +.. note:: + + Al subir el archivo desde un ZIP, el nombre del directorio de + destino de la expansión se determina automáticamente a partir de + ``name``. Si coloca el tema manualmente en el directorio + ``themes/``, haga que el nombre del directorio coincida con + ``name``. Los temas que no coincidan se ignorarán al volver a + escanear. + +.. note:: + + La miniatura de vista previa se coloca en la raíz del tema con el + nombre fijo ``thumbnail.png`` (se muestra en la lista de temas de la + consola de administración). Esta imagen no se reconoce mediante un + campo del manifiesto, sino por el nombre del archivo. Se recomienda + que el tamaño no supere 512 KB y que las dimensiones no superen + 512×512 píxeles. + +Distribución y API +------------------ + +- Los temas estáticos se distribuyen bajo ``/themes//`` (donde + ```` es el ``name`` de ``theme.yml``). +- Se devuelve el HTML de entrada (por defecto ``index.html``) en cada + una de las rutas ``/``, ``/search``, ``/advance``, ``/help``, + ``/error``, ``/profile``, ``/cache`` y ``/chat``, y el enrutamiento + posterior lo gestiona la SPA. Desde 15.10 esto ocurre sea cual sea el + valor de ``spaFallback``; el campo ya no se lee. +- Los errores también los muestra el tema: cuando una solicitud falla, + el navegador recibe el HTML de entrada del tema en la URL solicitada, + con el código de estado HTTP real. +- La consola de administración (``/admin/*``), ``/api/*``, la pantalla + de inicio de sesión, etc., quedan fuera del alcance de los temas + estáticos y son gestionados por el propio |Fess|. +- ``{{themePath}}`` en el HTML de entrada se sustituye por + ``themes/`` al servir la página. Haga referencia a los archivos + del propio tema desde ``index.html`` como + ``{{themePath}}/assets/styles.css``, etc. Así el nombre del tema no + aparece en la página y el tema carga sus propios archivos con + cualquier nombre con el que se instale. +- El HTML de entrada se sirve con un encabezado + ``Content-Security-Policy`` que solo permite scripts, estilos, + imágenes y conexiones procedentes del propio |Fess| (se permiten los + estilos en línea, pero no los scripts en línea). Por lo tanto, las + fuentes o los scripts de una CDN externa no se cargan; inclúyalos en + el tema. +- La ``Content-Security-Policy`` del HTML de entrada contiene + ``frame-ancestors 'none'`` y la respuesta incluye también + ``X-Frame-Options: DENY``, por lo que la página no se muestra dentro del + marco de otra página. El valor de ``frame-ancestors`` se puede cambiar con + ``theme.index.frame.ancestors`` en ``fess_config.properties`` + (predeterminado: ``'none'``). Un valor vacío omite ``frame-ancestors`` + (``X-Frame-Options: DENY`` se sigue enviando). Con + ``frame-ancestors 'none'``, los navegadores basados en WebKit, como Safari, + dejan en blanco los marcos que un tema muestra desde una URL ``blob:`` + (la vista previa de un PDF o la copia en caché). Deje el valor vacío para + mostrarlos. +- La SPA del tema obtiene datos como los resultados de búsqueda y el + chat a través de la API ``/api/v2/*``. + +Empaquetado +----------- + +Si utiliza ``scripts/package.sh`` del repositorio `fess-themes +`__, puede empaquetar el tema +en un ZIP para su distribución. + +:: + + ./scripts/package.sh example + +Se genera ``dist/example-.zip`` (donde ```` es el +``version`` de ``theme.yml``). + +.. note:: + + ``theme.yml`` debe colocarse en la raíz del ZIP. Si se coloca en un + subdirectorio, no se reconocerá al subirlo. + +Publicación +----------- + +Los temas que desarrolla el proyecto |Fess| se publican en +https://maven.codelibs.org/release/org/codelibs/fess/themes/ , en +``//-.zip`` con un ``.sha1`` al lado y un +``maven-metadata.xml`` por tema que lista las versiones publicadas. +``bin/fess-setup install theme `` lee esos metadatos para elegir la versión construida para +el |Fess| en ejecución. + +Versione un tema según la línea de |Fess| a la que está destinado y suba la versión siempre que +cambie lo que entrega el archivo. Una versión publicada no se sobrescribe nunca, así que un cambio +que conserve su versión sencillamente no se distribuye. + +Por lo mismo no hay en el manifiesto ningún campo de límite superior. Como un archivo publicado no +cambia nunca, no podría añadirse más tarde un límite para un tema que deja de funcionar en un +|Fess| más nuevo. No publicar ese tema para la línea nueva dice lo mismo, en el momento en que se +sabe. + +.. note:: + + Enumere las versiones publicadas a partir de ``maven-metadata.xml`` y no de un listado de + directorio. El índice de directorio se genera periódicamente, de modo que un tema recién + publicado puede leerse por sus metadatos antes de aparecer en ningún listado. + +Instalación y Activación +------------------------ + +1. Abra «Sistema» → «Tema» (``/admin/theme/``) en la consola de + administración. +2. Suba el archivo ZIP creado. Un tema publicado también puede instalarse desde la + línea de comandos con ``bin/fess-setup install theme ``; consulte + :doc:`../install/fess-setup`. +3. En la página de la lista, seleccione el tema deseado en el menú + desplegable «Tema predeterminado» y pulse el botón «Establecer» para + activarlo. + +El mecanismo de activación es el siguiente. + +- Al pulsar el botón «Establecer», el nombre del tema seleccionado se + guarda en la propiedad del sistema ``theme.default`` y se convierte + en el tema predeterminado de todo el sistema. +- Si el nombre del tema coincide con la clave de un host virtual, el + tema solo se aplica al acceder a ese host virtual. Esto permite + cambiar de tema según el host virtual. +- Si actualiza directamente el directorio ``themes/`` en el disco, + puede volver a escanearlo con «Recargar». + +.. note:: + + La subida del ZIP tiene límites como el tamaño del archivo, el + tamaño total tras la expansión y el número de entradas, que se + pueden ajustar mediante las propiedades ``theme.*`` de + ``fess_config.properties`` (por ejemplo, ``theme.upload.max.size`` + tiene un valor predeterminado de 50MB y ``theme.directory.path`` + tiene un valor predeterminado de ``themes``). Durante la expansión + se realizan comprobaciones para prevenir ataques de tipo ZIP Slip y + zip bomb. + +.. _theme-customize-bundled: + +Personalización del Tema Incluido +--------------------------------- + +El tema incluido ``bootstrap`` se encuentra en ``app/themes/bootstrap/`` +de la instalación de |Fess| (``/usr/share/fess/app/themes/bootstrap/`` +en los paquetes RPM/DEB). No lo edite directamente: una actualización +lo reemplaza, y el nombre ``bootstrap`` está reservado para él, por lo +que no se puede eliminar ni reemplazar mediante una subida. En su +lugar, cópielo con otro nombre. + +1. Copie el directorio, por ejemplo a ``mytheme``:: + + $ cp -r app/themes/bootstrap /tmp/mytheme + +2. En ``theme.yml``, cambie ``name`` a ``mytheme`` y cambie + ``displayName``. ``name`` debe coincidir con el nombre del + directorio. + +3. Deje ``index.html`` como está. El ``index.html`` incluido hace + referencia a sus propios archivos, como la hoja de estilos, los + logotipos y el script, como ``{{themePath}}/assets/...``, y |Fess| + sustituye ``{{themePath}}`` por ``themes/`` (el ``name`` de + ``theme.yml``) al servir la página. Por eso basta con cambiar el nombre + para que la copia cargue sus propios archivos. Si añade un archivo al + que hace referencia ``index.html``, escriba también su URL como + ``{{themePath}}/assets/...``. + +4. Realice sus cambios: + + - Colores y diseño: ``assets/styles.css``. + - Logotipos: ``assets/logo-head.png`` (encabezado) y + ``assets/logo.png`` (página inicial de búsqueda). + - Textos, como el pie de página (``footer.copyright_org``): los + archivos ``i18n/messages..json``, uno por idioma. + - Estructura de la página: ``index.html``. + +5. Empaquete el directorio como un ZIP con ``theme.yml`` en su raíz y + súbalo en «Sistema» → «Tema» de la consola de administración:: + + $ cd /tmp/mytheme && zip -r ../mytheme.zip . + + Como alternativa, coloque el directorio en ``app/themes/`` y pulse + «Recargar» en la misma página. + +6. Seleccione ``mytheme`` como tema predeterminado en esa página. + +.. note:: + + Después de cada actualización de |Fess|, sustituya la copia por una + nueva copia del tema incluido y vuelva a aplicar sus cambios, ya que + el tema incluido sigue la API ``/api/v2/*`` de su versión de |Fess|. + +Plugin de Tema JAR (eliminado en 15.10) +====================================== + +El tipo de plugin de tema JAR, que empaquetaba JSP, CSS e imágenes en un +JAR ``fess-theme-*`` y los aplicaba como el tema con el mismo nombre que +la clave del host virtual, se eliminó en |Fess| 15.10. 15.10 no expande +los temas JAR ni los utiliza en ninguna pantalla. + +- Si lo instala desde «Sistema» → «Plugin» en la consola de + administración, solo se coloca en ``app/WEB-INF/plugin/`` como un JAR + de propósito general del tipo ``jar`` y no cambia ninguna pantalla. + Un ``fess-theme-*.jar`` que haya quedado de una versión anterior se + muestra de la misma manera y se puede eliminar desde esa pantalla o + con ``bin/fess-setup remove plugin ``. +- ``bin/fess-setup`` no muestra ``fess-theme-*`` en la lista ni lo + instala. + +Traslade a un tema estático los cambios que hacía con un tema JAR. + +- Para los colores, el diseño y el logotipo de la pantalla de búsqueda, + copie el tema incluido y modifíquelo (consulte + `Personalización del Tema Incluido`_). +- Si cambiaba el aspecto por host virtual, instale un tema estático con + el mismo nombre que el host virtual (consulte + :doc:`../config/security-virtual-host`). +- La pantalla de inicio de sesión (``/login/``) es la misma para todos + los hosts virtuales y no se puede cambiar con un tema. + +Ejemplos de Temas Existentes +============================ + +- `fess-themes `__ - + Colección de temas estáticos (incluye varios temas estáticos como + ``codesearch`` y ``docsearch``) + +Información de Referencia +========================= + +- :doc:`plugin-architecture` - Arquitectura de plugins +- :doc:`../admin/plugin-guide` - Instalación de plugins diff --git a/es/15.10/dev/webapp-plugin.rst b/es/15.10/dev/webapp-plugin.rst new file mode 100644 index 000000000..645676149 --- /dev/null +++ b/es/15.10/dev/webapp-plugin.rst @@ -0,0 +1,337 @@ +================================== +Plugin de Aplicación Web +================================== + +Visión General +============== + +Los plugins de aplicación web (``fess-webapp-*``) son plugins que amplían +la aplicación web de |Fess|. A diferencia de otros tipos de plugins, no +añaden directamente clases Action ni JSP, sino que amplían la +funcionalidad **añadiendo o sustituyendo componentes** en el contenedor +DI (Lasta Di). Los usos representativos son los siguientes: + +- Adición de nuevos componentes (helpers, servicios, etc.) +- Sustitución de componentes del núcleo de |Fess| (mediante subclases) +- Adición de endpoints de API REST (``WebApiManager``) +- Ampliación del comportamiento de búsqueda (comandos de consulta, + fusión de rangos, etc.) + +.. note:: + + Los plugins de aplicación web se distribuyen como JAR, y sus clases + internas y archivos de configuración DI se cargan en el classpath de + la aplicación web de |Fess|. No permiten añadir vistas JSP. Si desea + personalizar el diseño de la pantalla de búsqueda, consulte + :doc:`theme-development`. + +Estructura Básica +================= + +Tomando como ejemplo `fess-webapp-example +`__, la plantilla de +implementación de un plugin de aplicación web, un plugin se compone de +una «clase de implementación» y un «archivo de registro DI»: + +:: + + fess-webapp-example/ + ├── pom.xml + └── src/main/ + ├── java/org/codelibs/fess/webapp/example/helper/ + │ ├── ExampleHelper.java # Componente a añadir + │ └── CustomSystemHelper.java # Sustitución de un componente del núcleo + └── resources/ + ├── app++.xml # Adición de componentes (fusión) + └── fess+systemHelper.xml # Sustitución de componentes + +.. note:: + + El paquete de las clases de implementación utiliza + ``org.codelibs.fess.webapp.``. Los archivos de + configuración DI se colocan en ``src/main/resources/``. A diferencia + de los plugins de almacén de datos, no incluyen ``src/main/webapp/`` + ni JSP. + +pom.xml y el Manifiesto +======================= + +Los plugins de aplicación web se construyen como jar con ``fess-parent`` +como POM padre. Las bibliotecas ``fess`` y ``opensearch``, que son +proporcionadas en tiempo de ejecución por el propio |Fess|, se declaran +con el ámbito ``provided``, mientras que las bibliotecas necesarias en +tiempo de ejecución, como ``lastaflute``, ``dbflute-runtime`` y +``corelib``, se declaran con el ámbito habitual. + +Lo más importante en un plugin de aplicación web es añadir +``Fess-WebAppJar: true`` al manifiesto del JAR. Gracias a esta +declaración, |Fess| monta las clases del plugin y sus archivos de +configuración DI en el cargador de clases de la aplicación web. Esta +configuración se realiza con ``maven-jar-plugin``: + +.. code-block:: xml + + + + + maven-jar-plugin + + + + true + + + + + + + +.. warning:: + + Si no se añade ``Fess-WebAppJar: true``, las clases del plugin y los + archivos de configuración DI no se cargarán en el classpath de la + aplicación web, y la adición o sustitución de componentes no surtirá + efecto. + +Para conocer la configuración completa de pom.xml (el POM padre, la +forma de declarar las dependencias, etc.), consulte +:doc:`plugin-architecture`. + +Patrones de Extensión +====================== + +Adición de Componentes (app++.xml) +----------------------------------- + +La forma más básica de extensión es añadir sus propios componentes. +Lasta Di **fusiona** el archivo ``app++.xml`` presente en el classpath +con el espacio de nombres ``app`` construido a partir del ``app.xml`` +del propio |Fess| (el sufijo ``++`` es la convención para la fusión +aditiva). Dado que los componentes añadidos utilizan nombres que no +existen en el propio |Fess|, no se sobrescribe nada. + +.. code-block:: xml + + + + + + + + +En la implementación del componente, utilice ``@PostConstruct`` para la +inicialización, y reutilice los componentes del propio |Fess| +obteniéndolos mediante ``ComponentUtil`` (no los copie ni los +sobrescriba): + +.. code-block:: java + + package org.codelibs.fess.webapp.example.helper; + + import org.codelibs.fess.helper.SystemHelper; + import org.codelibs.fess.util.ComponentUtil; + + import jakarta.annotation.PostConstruct; + + public class ExampleHelper { + + protected String pluginName = "fess-webapp-example"; + + @PostConstruct + public void init() { + // Procesamiento de inicialización invocado una sola vez tras la creación por DI + } + + public String getPluginLabel() { + // Reutiliza el SystemHelper del núcleo para obtener la versión de Fess en ejecución + final SystemHelper systemHelper = ComponentUtil.getSystemHelper(); + final String version = systemHelper != null ? systemHelper.getProductVersion() : "unknown"; + return pluginName + " (Fess " + version + ")"; + } + } + +.. tip:: + + Considere primero esta opción de «adición de componentes». A menos + que sea necesario modificar la funcionalidad del núcleo, es más + segura y ofrece mejor mantenibilidad que la sustitución. + +Sustitución de Componentes del Núcleo (fess+componentName.xml) +------------------------------------------------------------------ + +Si desea modificar el comportamiento de un componente del propio +|Fess|, cree una subclase de la clase de destino y **vuelva a +registrarla con el mismo nombre de componente** en un archivo de +configuración DI denominado ``+.xml``. Por +ejemplo, dado que ``systemHelper`` está declarado en ``fess.xml`` del +propio |Fess|, el archivo de sustitución será ``fess+systemHelper.xml`` +(no ``app+systemHelper.xml``). + +.. code-block:: java + + package org.codelibs.fess.webapp.example.helper; + + import java.nio.file.Path; + + import org.codelibs.fess.helper.SystemHelper; + + public class CustomSystemHelper extends SystemHelper { + + @Override + protected void parseProjectProperties(final Path propPath) { + try { + super.parseProjectProperties(propPath); + } catch (final Exception e) { + // Procesamiento propio + } + System.setProperty("fess.webapp.plugin", "true"); + } + } + +.. warning:: + + La sustitución (con un único ``+``) reemplaza **por completo** la + definición del componente. Por ello, el archivo de sustitución debe + incluir todos los elementos ```` que realiza la + definición del núcleo (por ejemplo, ``queryHelper`` en ``app.xml``). + Esto debe sincronizarse en cada versión de |Fess|. Si el archivo + sigue llamando a un método que se eliminó del núcleo, la + inicialización de esa definición de componente falla con + ``BeanMethodNotFoundException``. Por ejemplo, en 15.10 se eliminó + ``addDesignJspFileName`` de ``systemHelper``, por lo que un archivo + de sustitución que lo llame falla. Este coste de mantenimiento es la + razón por la que se recomienda la adición en lugar de la sustitución. + +Adición de una API REST (fess_api++.xml) +------------------------------------------- + +Para añadir un nuevo endpoint de API REST, implemente +``WebApiManager``. Herede de ``BaseApiManager`` y regístrese a sí mismo +en ``WebApiManagerFactory`` mediante ``@PostConstruct``. El gestor de +API registrado es invocado por ``WebApiFilter`` en cada solicitud. +Registre el componente en ``fess_api++.xml``: + +.. code-block:: xml + + + + + + + + +.. code-block:: java + + package org.codelibs.fess.webapp.example.api; + + import java.io.IOException; + + import org.codelibs.fess.api.BaseApiManager; + import org.codelibs.fess.util.ComponentUtil; + + import jakarta.annotation.PostConstruct; + import jakarta.servlet.FilterChain; + import jakarta.servlet.ServletException; + import jakarta.servlet.http.HttpServletRequest; + import jakarta.servlet.http.HttpServletResponse; + + public class ExampleApiManager extends BaseApiManager { + + public ExampleApiManager() { + // Prefijo de la ruta que gestiona este manejador + setPathPrefix("/api/example"); + } + + @PostConstruct + public void register() { + ComponentUtil.getWebApiManagerFactory().add(this); + } + + @Override + public boolean matches(final HttpServletRequest request) { + // Determina si este manejador procesa la solicitud + return request.getServletPath().startsWith(pathPrefix); + } + + @Override + public void process(final HttpServletRequest request, final HttpServletResponse response, + final FilterChain chain) throws IOException, ServletException { + // Procesamiento de la solicitud y escritura de la respuesta + } + + @Override + protected void writeHeaders(final HttpServletResponse response) { + // Configuración de las cabeceras de la respuesta (según sea necesario) + } + } + +Como ejemplos de implementación, resultan útiles como referencia +`fess-webapp-v1-api `__, +que proporciona ``/api/v1``, y `fess-webapp-classic-api +`__, que +proporciona ``/json`` y ``/suggest``. + +Personalización de la Pantalla de Búsqueda +============================================ + +Los plugins de aplicación web no pueden añadir vistas JSP. Esto se debe +a que las vistas JSP se ubican en ``WEB-INF/view/`` del WAR del propio +|Fess|, mientras que el JAR del plugin se monta en el classpath +(``WEB-INF/classes``). Si desea modificar el diseño de la pantalla de +búsqueda, utilice un tema estático. El tema estático personaliza el +diseño de la pantalla de búsqueda (HTML/CSS/JavaScript). Consulte +:doc:`theme-development`. + +Construcción e Instalación +============================ + +:: + + mvn clean package + +En el directorio ``target/`` se generará un archivo JAR (por ejemplo, +``fess-webapp-example-15.10.0.jar``). El JAR generado se puede instalar +desde la consola de administración, o bien colocarlo en el directorio +``app/WEB-INF/plugin/`` y reiniciar |Fess|. Para más detalles sobre el +procedimiento de instalación, consulte :doc:`../admin/plugin-guide`. + +Ejemplos de Plugins Públicos +============================== + +En el proyecto |Fess| se publican los siguientes plugins de aplicación +web. Se publican en `GitHub `__ como +referencia para el desarrollo: + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Plugin + - Descripción + * - ``fess-webapp-example`` + - Plantilla de implementación de plugins + * - ``fess-webapp-v1-api`` + - API REST ``/api/v1`` + * - ``fess-webapp-classic-api`` + - API REST heredada ``/json`` / ``/suggest`` + * - ``fess-webapp-mcp`` + - Servidor MCP (Model Context Protocol) + * - ``fess-webapp-bangs`` + - Bangs al estilo de DuckDuckGo (``!g``) que envían una búsqueda a otro sitio + * - ``fess-webapp-semantic-search`` + - Búsqueda neuronal/búsqueda vectorial (obsoleto; reemplazado por la integración en el + núcleo en la 15.10) + * - ``fess-webapp-multimodal`` + - Búsqueda multimodal (imágenes y texto) + +Información de Referencia +=========================== + +- :doc:`plugin-architecture` - Arquitectura de plugins +- :doc:`theme-development` - Personalización de temas +- :doc:`../admin/plugin-guide` - Instalación de plugins +- :doc:`overview` - Visión general de documentación para desarrolladores diff --git a/es/15.10/install/fess-setup.rst b/es/15.10/install/fess-setup.rst new file mode 100644 index 000000000..155660e61 --- /dev/null +++ b/es/15.10/install/fess-setup.rst @@ -0,0 +1,348 @@ +================== +Comando fess-setup +================== + +``bin/fess-setup`` (``bin\fess-setup.bat`` en Windows) se incluye con el paquete ZIP de |Fess|. +Instala lo que |Fess| necesita pero no incluye: OpenSearch con los plugins que requiere |Fess|, +Node.js para los plugins de Playwright, los plugins de |Fess| y los temas estáticos. También informa sobre el estado +de una instalación. + +Ejecútelo desde el directorio de |Fess|. Sin argumentos, muestra la lista de comandos. + +:: + + $ cd /path/to/fess-15.10.0 + $ bin/fess-setup [options] + +Códigos de Salida +================= + +.. list-table:: + :header-rows: 1 + :widths: 15 85 + + * - Código + - Significado + * - ``0`` + - El comando se completó correctamente. + * - ``1`` + - El comando falló: por ejemplo, falló una descarga, la versión solicitada no existe, + OpenSearch no publica ninguna versión para esta plataforma o ``check`` detectó un problema. + * - ``2`` + - La línea de comandos es incorrecta: un comando desconocido o falta un argumento, como el + nombre de un plugin. + +Instalación de OpenSearch y Node.js +=================================== + +install opensearch +------------------ + +:: + + $ bin/fess-setup install opensearch [--dest ] [--version ] [--keep-bundled-plugins] + +Descarga la versión de OpenSearch compatible con este |Fess| en ``opensearch/`` dentro del +directorio de |Fess|, instala los cuatro plugins que requiere |Fess| (``opensearch-analysis-fess``, +``opensearch-analysis-extension``, ``opensearch-minhash`` y ``opensearch-configsync``) y añade la +siguiente configuración a su ``config/opensearch.yml``: + +- ``configsync.config_path``, con el directorio ``config/dictionary`` de ese OpenSearch como valor +- ``plugins.security.disabled: true`` + +Además, elimina los plugins incluidos ``opensearch-security-analytics`` y +``opensearch-performance-analyzer``, que |Fess| no utiliza; el OpenSearch de la imagen Docker +tampoco los incluye. Si la descarga no incluye alguno de ellos, se omite. + +Una opción que ``opensearch.yml`` ya contiene no se vuelve a añadir, y +``plugins.security.disabled: true`` no se añade si el archivo contiene cualquier opción +``plugins.security.*``. Si el directorio de OpenSearch ya existe, se omite la descarga, de modo que +volver a ejecutar el comando sobre una instalación existente solo añade las opciones que faltan. + +El comando muestra cada opción que ha añadido y, a continuación, indica si ``bin/fess.in.sh`` +encuentra este OpenSearch por sí mismo. Lo encuentra cuando es el único OpenSearch con un +directorio ``config/dictionary`` dentro de ``opensearch/`` en el directorio de |Fess|: en ese caso +``bin/fess.in.sh`` (``bin\fess.in.bat`` en Windows) establece ``FESS_DICTIONARY_PATH`` en ese +directorio, y no hace falta configurar nada más para un OpenSearch en el mismo host. En caso +contrario, el comando muestra los valores de ``SEARCH_ENGINE_HTTP_URL`` y ``FESS_DICTIONARY_PATH`` +que debe establecer, tal como se describe en :doc:`install-linux` o :doc:`install-windows`. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Opción + - Descripción + * - ``--dest `` + - El directorio en el que extraer OpenSearch, en lugar de ``opensearch/`` dentro del + directorio de |Fess|. ``bin/fess.in.sh`` no busca OpenSearch fuera de ese directorio. + * - ``--version `` + - La versión de OpenSearch que se instala. Los plugins se instalan en la misma versión. + * - ``--keep-bundled-plugins`` + - Conserva los plugins incluidos (``opensearch-security-analytics`` y ``opensearch-performance-analyzer``) en lugar de eliminarlos, y deja la descarga tal como se distribuye. + +OpenSearch publica versiones oficiales solo para Linux y Windows. En otras plataformas, como macOS, +el comando termina con el código ``1`` antes de descargar nada y sugiere instalar OpenSearch con +Homebrew y añadir los plugins con ``install opensearch-plugins``, o bien utilizar Docker. + +.. warning:: + + Con ``plugins.security.disabled: true``, OpenSearch acepta peticiones sin autenticación. + OpenSearch solo escucha en la dirección de loopback a menos que se establezca ``network.host``. + Antes de que escuche en cualquier otra dirección, configure en su lugar el plugin de seguridad; + consulte :doc:`security`. + +install opensearch-plugins +-------------------------- + +:: + + $ bin/fess-setup install opensearch-plugins --opensearch-home [--version ] + +Instala los cuatro plugins que requiere |Fess| en un OpenSearch que ya tenga, en lugar de ejecutar +cuatro veces su ``bin/opensearch-plugin install``. ``--opensearch-home`` es el directorio de +instalación de OpenSearch y es obligatorio. ``--version`` establece la versión de los plugins, que +debe coincidir con la versión de OpenSearch. + +Este comando no modifica ``opensearch.yml``. Añada usted mismo ``configsync.config_path`` y el +resto de la configuración, tal como se describe en :doc:`install-linux` o :doc:`install-windows`. + +install nodejs +-------------- + +:: + + $ bin/fess-setup install nodejs [--dest ] [--version ] + +Descarga Node.js, que necesitan los plugins de Playwright (``fess-crawler-playwright`` para el +rastreador de Playwright y ``fess-thumbnail-playwright`` para las miniaturas), en ``nodejs/`` dentro +del directorio de |Fess|. ``bin/fess.in.sh`` (``bin\fess.in.bat`` en Windows) lo encuentra allí y establece +``PLAYWRIGHT_NODEJS_PATH``. Con ``--dest`` fuera del directorio de |Fess|, el comando muestra en su +lugar la línea ``PLAYWRIGHT_NODEJS_PATH`` que debe añadir a ``bin/fess.in.sh``. ``--version`` +selecciona otra versión de Node.js. Consulte :doc:`../config/crawler-advanced` para el rastreador de +Playwright. + +Gestión de Plugins +================== + +Estos comandos trabajan sobre el directorio de plugins ``app/WEB-INF/plugin`` de la instalación de +|Fess|. Reinicie |Fess| después de instalar, actualizar o eliminar plugins. Los plugins también se +pueden gestionar desde la página Sistema > Plugin de la pantalla de administración; consulte +:doc:`../admin/plugin-guide`. + +``install plugin``, ``list plugins``, ``list installed``, ``upgrade plugins``, ``remove plugin`` y ``check`` aceptan ``--dest ``. Indica el directorio de plugins que se usa en lugar de ``app/WEB-INF/plugin``: el directorio que contiene los jar de los plugins, no su directorio padre. Una ruta relativa se resuelve desde el directorio actual, no desde el directorio de |Fess|. En ``install opensearch`` e ``install nodejs``, en cambio, ``--dest`` es el directorio en el que se extrae el archivo. + +``install plugin``, ``list plugins`` y ``upgrade plugins`` aceptan ``--repository ``. Con esta +opción, la lista de versiones, los jar y sus sumas de comprobación se obtienen de ese único +repositorio Maven, como un espejo interno, en lugar de los repositorios predeterminados de +versiones publicadas y de snapshots y de GitHub. + +``--repository`` también acepta una URL que empiece por ``file:///``. En un servidor sin acceso a +Internet, coloque una copia del repositorio Maven en el servidor e indique ese directorio. Indique el +directorio que contiene el directorio de cada plugin (``/maven-metadata.xml``, etc.), es decir, +el lugar que corresponde a ``https://maven.codelibs.org/release/org/codelibs/fess/`` del repositorio +predeterminado. Las versiones se resuelven y las sumas de comprobación se verifican igual que con un +repositorio HTTP. + +:: + + $ bin/fess-setup install plugin fess-ds-csv --repository file:///opt/maven-repo/org/codelibs/fess/ + +Un esquema distinto de ``http``, ``https`` y ``file``, o una URL sin esquema, se rechaza con un error +de una línea. + +install plugin +-------------- + +:: + + $ bin/fess-setup install plugin [:]... [--version ] [--repository ] [--dest ] + +Instala uno o varios plugins de |Fess|, por ejemplo ``fess-script-groovy`` o ``fess-ds-git``. Un +nombre sin versión instala la versión más reciente compilada para este |Fess|. +``:`` fija la versión de ese plugin, y ``--version`` es la versión para todos los +nombres que no indican una propia. La versión instalada anteriormente de un plugin se elimina una +vez instalada la nueva. + +Cada jar se obtiene de la release de GitHub del plugin, o del repositorio Maven cuando la release +no contiene ese archivo, y se verifica con la suma de comprobación SHA-1 que publica el repositorio +Maven. Una versión de desarrollo de |Fess| también instala las compilaciones snapshot de su propia +línea, y les da preferencia. + +Consulte :doc:`../admin/plugin-guide` para ver ejemplos. + +Solo se pueden instalar los tipos de plugin que |Fess| carga: nombres que empiezan por ``fess-ds-``, +``fess-ingest-``, ``fess-script-``, ``fess-webapp-``, ``fess-thumbnail-``, ``fess-crawler-``, +``fess-llm-``, ``fess-storage-`` o ``fess-sso-``, los mismos que muestra ``list plugins``. Cualquier +otro nombre (``fess-theme-*`` o una biblioteca como ``fess`` o ``fess-crawler``) se rechaza con un error +de una línea y el código de salida 2 antes de descargar nada. Si se rechaza uno de varios nombres, no +se instala ninguno. Instale un tema estático con ``install theme``. + +list plugins +------------ + +:: + + $ bin/fess-setup list plugins [--repository ] [--dest ] + +Lista los plugins publicados para este |Fess| y marca los instalados con +``(installed: )``. Los plugins que están instalados pero no publicados en el repositorio, +como un jar compilado localmente, se listan por separado. Una versión de desarrollo de |Fess| lista +también el repositorio de snapshots. + +list installed +-------------- + +:: + + $ bin/fess-setup list installed [--dest ] + +Lista los plugins instalados y sus versiones, sin consultar el repositorio. + +upgrade plugins +--------------- + +:: + + $ bin/fess-setup upgrade plugins [--repository ] [--dest ] + +Vuelve a instalar cada plugin instalado en la versión adecuada para este |Fess|. Un plugin que ya +está en esa versión se deja como está. Los plugins de ``app/WEB-INF/plugin`` se compilan para una +versión concreta de |Fess|, así que ejecute este comando después de actualizar |Fess|. + +remove plugin +------------- + +:: + + $ bin/fess-setup remove plugin ... [--dest ] + +Elimina los jar instalados de los plugins indicados. Un nombre que no está instalado se notifica y +no cambia el código de salida. + +.. _fess-setup-offline: + +Entornos sin conexión a Internet +-------------------------------- + +``install plugin``, ``list plugins`` y ``upgrade plugins`` obtienen los plugins de repositorios en +Internet. La pantalla de instalación de la página Sistema > Plugin de la pantalla de administración +también obtiene de los repositorios (``plugin.repositories``) la lista de plugins que se pueden +instalar, por lo que no puede mostrar la lista en un entorno sin conexión al exterior. + +En un entorno así, lleve los jar de los plugins e instálelos de esta forma: + +1. En un entorno con conexión a Internet, descargue el paquete ZIP de |Fess| y los jar de los plugins + necesarios. Los jar se pueden obtener de + ``https://maven.codelibs.org/release/org/codelibs/fess///-.jar``. + Elija la versión que corresponde a este |Fess| (15.10.x para |Fess| 15.10). +2. En el entorno de destino, descomprima el ZIP y coloque los jar en ``app/WEB-INF/plugin/``. + También puede subirlos, después de iniciar |Fess|, desde la pestaña «Local» de la pantalla de + instalación de plugins de la pantalla de administración (consulte :doc:`../admin/plugin-guide`). +3. Inicie |Fess|. Si colocó los jar con |Fess| en ejecución, reinícielo. + +En lugar de llevar cada jar, también puede copiar la parte necesaria del repositorio Maven (los +directorios ``org/codelibs/fess//``) al servidor e instalar con ``install plugin`` y +``--repository file:///...``. En este caso también se verifican las sumas de comprobación. + +Gestión de Temas +================ + +Estos comandos actúan sobre el directorio de temas ``app/themes`` de la instalación de |Fess|. +Reinicie |Fess| después de instalar o eliminar un tema, o pulse [Recargar] en la página +Sistema > Tema. Los temas también pueden subirse desde esa página; consulte +:doc:`../admin/theme-guide`. + +``install theme``, ``list themes`` y ``remove theme`` aceptan ``--dest `` de la misma forma e indican el directorio de temas que se usa en lugar de ``app/themes``. + +La versión de un tema indica la línea de |Fess| a la que está destinado: ``15.10.0`` es un tema +para |Fess| 15.10. Por eso un nombre sin versión se resuelve al tema construido para este |Fess|, +igual que ocurre con un plugin. + +install theme +------------- + +:: + + $ bin/fess-setup install theme [:]... [--version ] [--repository ] [--dest ] + +Instala uno o varios temas estáticos, por ejemplo ``docuforge`` o ``voicebox``. Un nombre sin +versión instala la más reciente construida para este |Fess|. ``:`` fija la versión +de ese tema, y ``--version`` es la versión para todos los nombres que no lleven una propia. + +El archivo se comprueba contra la suma SHA-1 que publica el repositorio Maven y se extrae en +``app/themes/``. Un tema ya instalado con ese nombre se conserva como copia de seguridad +durante el mismo periodo que uno reemplazado desde la pantalla de administración (7 días por +omisión, ``theme.upload.attic.retention.days``). + +La descarga, la extracción y la comprobación del manifiesto ocurren antes de tocar nada +instalado, de modo que un tema que ya esté ahí sobrevive a una instalación fallida. Se rechaza un +archivo cuyo ``theme.yml`` nombre un tema distinto. + +list themes +----------- + +:: + + $ bin/fess-setup list themes [--repository ] [--dest ] + +Lista los temas publicados para este |Fess| y marca los instalados con +``(installed: )``. Los temas instalados que el repositorio no lista aparecen por +separado. + +La lista se lee del índice de directorio del repositorio, que se genera periódicamente. Cuando no +puede leerse, el comando informa de la URL que intentó y sigue listando los temas instalados: un +tema puede instalarse nombrándolo, figure o no en el índice. + +remove theme +------------ + +:: + + $ bin/fess-setup remove theme ... [--dest ] + +Elimina de ``app/themes`` los temas indicados y conserva cada uno como copia de seguridad durante +el periodo de retención. Un nombre que no esté instalado se informa y no cambia el código de +salida. + +Si el tema eliminado era el predeterminado, |Fess| vuelve al tema ``bootstrap`` incluido hasta que +se elija otro. + +Comprobación de una Instalación +=============================== + +list +---- + +:: + + $ bin/fess-setup list + +Muestra los componentes que descarga ``install``, ``opensearch`` y ``nodejs``, con la versión de +cada uno. + +check +----- + +:: + + $ bin/fess-setup check [--url ] [--playwright] [--dest ] + +Informa sobre la instalación, con una línea por comprobación, marcada como ``OK``, ``WARN`` o +``FAIL``: + +- El motor de búsqueda: si es accesible, su versión (una advertencia si los nodos indican versiones + distintas), si los cuatro plugins que requiere |Fess| están instalados en él y si ``configsync`` + responde. +- |Fess|: si el directorio de plugins existe y admite escritura, cada plugin instalado (un fallo + para un plugin compilado para otra versión de |Fess| y para un plugin instalado en dos + versiones) y si Node.js está instalado en ``nodejs/`` dentro del directorio de + |Fess|. + +La URL del motor es ``--url``; si no se indica, la variable de entorno ``SEARCH_ENGINE_HTTP_URL``; +y si tampoco existe, ``http://localhost:9200``. ``bin/fess-setup`` no lee ``bin/fess.in.sh``, así +que indique ``--url`` cuando OpenSearch esté en otro lugar. La ausencia de Node.js solo se +notifica, salvo que se indique ``--playwright``, que la convierte en un fallo. + +El comando termina con el código ``0`` cuando ninguna comprobación ha fallado, aunque alguna haya +producido advertencias, y con el código ``1`` en caso contrario. diff --git a/es/15.10/install/index.rst b/es/15.10/install/index.rst new file mode 100644 index 000000000..700d8f26d --- /dev/null +++ b/es/15.10/install/index.rst @@ -0,0 +1,25 @@ +Guía de Instalación de |Fess| +============================= + +Cómo instalar y ejecutar |Fess| en Linux, Windows o Docker, con los +requisitos previos, la configuración de seguridad, la actualización y +la resolución de problemas. + +.. toctree:: + :maxdepth: 2 + :caption: Índice de Contenidos + + intro + prerequisites + install + install-linux + install-windows + install-docker + fess-setup + run + security + upgrade + uninstall + troubleshooting + + diff --git a/es/15.10/install/install-docker.rst b/es/15.10/install/install-docker.rst new file mode 100644 index 000000000..918fd0f95 --- /dev/null +++ b/es/15.10/install/install-docker.rst @@ -0,0 +1,628 @@ +================================== +Instalación con Docker (Detalles) +================================== + +Esta página describe los procedimientos de instalación de |Fess| utilizando Docker y Docker Compose. +Usar Docker permite construir un entorno |Fess| de manera fácil y rápida. + +Requisitos Previos +=================== + +- Cumplir con los requisitos del sistema descritos en :doc:`prerequisites` +- Docker 20.10 o posterior instalado +- Docker Compose 2.0 o posterior instalado + +Verificación de la Instalación de Docker +========================================= + +Verifique las versiones de Docker y Docker Compose con los siguientes comandos. + +:: + + $ docker --version + $ docker compose version + +.. note:: + + Si está usando una versión antigua de Docker Compose, use el comando ``docker-compose``. + Este documento utiliza el nuevo formato de comando ``docker compose``. + +Acerca de las Imágenes Docker +============================== + +Al iniciar |Fess| con Docker Compose, se ejecutan los siguientes dos contenedores: + +- **Fess** (``fess01``): El sistema de búsqueda de texto completo en sí +- **OpenSearch** (``search01``): El motor de búsqueda + +La imagen Docker oficial está publicada en `GitHub Container Registry `__. +Los archivos Compose y los procedimientos de inicio se gestionan en el repositorio `docker-fess `__. + +Paso 1: Obtención del Archivo Docker Compose +============================================= + +Se requieren los siguientes archivos para iniciar con Docker Compose. + +Método 1: Descargar Archivos Individualmente +---------------------------------------------- + +Descargue los siguientes archivos: + +:: + + $ mkdir fess-docker + $ cd fess-docker + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose.yaml + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose-opensearch3.yaml + +Método 2: Clonar el Repositorio con Git +------------------------------------------ + +Si Git está instalado, también puede clonar todo el repositorio: + +:: + + $ git clone --depth 1 --branch v15.10.0 https://github.com/codelibs/docker-fess.git + $ cd docker-fess/compose + +Paso 2: Verificación del Archivo Docker Compose +================================================ + +Contenido de ``compose.yaml`` +------------------------------- + +``compose.yaml`` contiene la configuración de Fess en sí (servicio ``fess01``). + +Elementos de configuración principales: + +- **Número de puerto**: Puerto de la interfaz web de Fess (predeterminado: 8080) +- **Variables de entorno**: El destino de conexión de OpenSearch (``SEARCH_ENGINE_HTTP_URL``), la ruta del archivo de diccionario (``FESS_DICTIONARY_PATH``), entre otras +- **Orden de inicio**: Se configura ``depends_on`` para que el inicio ocurra una vez que OpenSearch (``search01``) esté en un estado saludable + +Contenido de ``compose-opensearch3.yaml`` +--------------------------------------------- + +``compose-opensearch3.yaml`` contiene la configuración del motor de búsqueda (servicio ``search01``, OpenSearch). + +Elementos de configuración principales: + +- **Imagen de OpenSearch**: La imagen de OpenSearch que se utiliza (``ghcr.io/codelibs/fess-opensearch``) +- **Configuración de memoria**: Tamaño del heap de JVM +- **Volumen**: Volúmenes para la persistencia de datos (``search01_data``: datos de índice, ``search01_dictionary``: archivos de diccionario) + +Personalización de la Configuración (Opcional) +------------------------------------------------- + +Si desea cambiar la configuración predeterminada, edite ``compose.yaml``. + +Ejemplo: para cambiar el número de puerto:: + + services: + fess01: + ports: + - "9080:8080" # Mapear al puerto 9080 del host + +Ejemplo: para cambiar la configuración de memoria:: + + services: + fess01: + environment: + - "FESS_HEAP_SIZE=2g" # Establecer el tamaño del heap de Fess en 2GB + +Tipos de imagen y miniaturas +---------------------------- + +Las imágenes Docker de |Fess| existen en varios tipos que se distinguen por un sufijo en la etiqueta (``-noble``, ``-al2023``, etc.). La imagen predeterminada sin sufijo (basada en Alpine) no incluye las herramientas externas que crean las miniaturas de imágenes, archivos PDF y documentos de Office (ImageMagick, poppler-utils, unoconv y LibreOffice). Con esta imagen, solo las páginas HTML obtienen miniaturas; no se generan miniaturas de imágenes, archivos PDF ni documentos de Office. + +Si necesita estas miniaturas, indique en ``image`` de ``compose.yaml`` una etiqueta con el sufijo ``-noble``, que incluye las herramientas. + +:: + + services: + fess01: + image: ghcr.io/codelibs/fess:15.10.0-noble + +La siguiente tabla muestra qué admite cada imagen. + +.. list-table:: + :header-rows: 1 + :widths: 40 30 30 + + * - Etiqueta + - Imágenes y PDF + - Documentos de Office + * - ``15.10.0-noble`` + - Se genera + - Se genera + * - ``15.10.0-al2023`` + - Se genera + - No se genera + * - ``15.10.0``, ``15.10.0-slim``, ``15.10.0-slim-noble``, ``15.10.0-slim-al2023`` + - No se genera + - No se genera + +Con cualquier imagen, la miniatura de una página HTML se crea a partir de una imagen de la propia página. Para que se muestren las miniaturas, active también la visualización de miniaturas en la configuración general de la pantalla de administración. Consulte :doc:`../config/crawler-thumbnail` para más detalles. + +Paso 3: Inicio del Contenedor Docker +===================================== + +Inicio Básico +-------------- + +Inicie Fess y OpenSearch con el siguiente comando: + +:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +.. note:: + + - Especifique múltiples archivos Compose con la opción ``-f`` + - Ejecute en segundo plano con la opción ``-d`` + +Verificación de registros de inicio:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f + +Puede salir de la visualización de registros con ``Ctrl+C``. + +Verificación del Inicio +------------------------- + +Verifique el estado de los contenedores:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps + +Verifique que los siguientes contenedores estén en ejecución: + +- ``fess01`` +- ``search01`` + +.. tip:: + + El inicio puede tardar varios minutos. Primero OpenSearch (``search01``) debe alcanzar un estado saludable, + y luego se inicia Fess (``fess01``). + Verifique el estado de cada contenedor con ``docker compose ... ps``; una vez que ``fess01`` esté en + ejecución, podrá acceder a http://localhost:8080/ desde el navegador. + +Paso 4: Acceso desde el Navegador +================================== + +Una vez completado el inicio, acceda a las siguientes URL: + +- **Pantalla de búsqueda**: http://localhost:8080/ +- **Pantalla de administración**: http://localhost:8080/admin + +La pantalla de búsqueda es ``bootstrap``, el tema estático incluido con |Fess|. Para cambiar su aspecto, +consulte :doc:`../admin/theme-guide`. + +Cuenta de administrador predeterminada: + +- Nombre de usuario: ``admin`` +- Contraseña: ``admin`` + +.. warning:: + + **Nota Importante sobre Seguridad** + + Asegúrese de cambiar la contraseña de administrador en entornos de producción. + Para más detalles, consulte :doc:`security`. + +Habilitación del Modo de Búsqueda con IA (Plugins LLM) +======================================================== + +A partir de |Fess| 15.10, la función de modo de búsqueda con IA (RAG Chat) se separó en los plugins +``fess-llm-*``. El repositorio oficial `docker-fess `__ incluye +archivos overlay para los principales proveedores de LLM. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Overlay + - Uso + * - ``compose-ollama.yaml`` + - Ollama (LLM local, inicia un servicio ``ollama01`` adicional) + * - ``compose-gemini.yaml`` + - Google Gemini (API en la nube) + * - ``compose-openai.yaml`` + - OpenAI (API en la nube) + +Cada overlay obtiene automáticamente el plugin correspondiente mediante ``FESS_PLUGINS`` y habilita RAG Chat +configurando ``-Dfess.config.rag.chat.enabled=true`` en ``FESS_JAVA_OPTS``. +En el caso de Gemini y OpenAI, que utilizan API en la nube, además se especifica el proveedor a usar mediante +``-Dfess.system.rag.llm.name``, y se configuran la clave de API (``rag.llm..api.key``) y el modelo +(``rag.llm..model``). +En Ollama se utiliza tal cual el valor predeterminado de ``rag.llm.name`` (``ollama``), por lo que no se +especifica explícitamente, y se configura el destino de conexión (``rag.llm.ollama.api.url``). + +Ejemplo de uso de Gemini:: + + $ export GEMINI_API_KEY="AIzaSy..." + $ docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-gemini.yaml up -d + +Ejemplo de uso de OpenAI:: + + $ export OPENAI_API_KEY="sk-..." + $ docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-openai.yaml up -d + +.. note:: + + El modelo utilizado se puede cambiar mediante las variables de entorno ``GEMINI_MODEL`` y ``OPENAI_MODEL`` + (los valores predeterminados son ``gemini-2.5-flash`` y ``gpt-5-mini``, respectivamente). + +Ejemplo de uso de Ollama:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-ollama.yaml up -d + $ docker exec -it ollama01 ollama pull gpt-oss:20b + +.. warning:: + + El servicio ``ollama01`` de ``compose-ollama.yaml`` está definido para usar una GPU NVIDIA de forma + predeterminada (se requiere `NVIDIA Container Toolkit `__). + Si va a ejecutarlo en un entorno sin GPU, elimine o comente el bloque ``deploy:`` de + ``compose-ollama.yaml`` (la especificación de GPU bajo ``reservations``). + +.. tip:: + + Después del inicio, en la pantalla de configuración "Sistema > General" del panel de administración, + puede cambiar el proveedor de LLM a utilizar (``rag.llm.name``) y la configuración específica de cada + proveedor. Sin embargo, estos cambios se guardan en el archivo de configuración dentro del contenedor, + por lo que se perderán si se recrea el contenedor (``docker compose down`` seguido de ``up``). + Para hacer persistente la configuración, especifíquela mediante ``FESS_JAVA_OPTS`` en el archivo Compose, + como en los ejemplos anteriores. + +Persistencia de Datos +====================== + +Todos los datos de |Fess| (índices, documentos rastreados, información de usuarios, configuración, etc.) se +almacenan en OpenSearch. +Dado que estos datos se persisten en los volúmenes de OpenSearch, se conservan aunque se eliminen los +contenedores. +El propio contenedor de Fess (``fess01``) no mantiene estado y no tiene un volumen dedicado. + +Verificación de volúmenes:: + + $ docker volume ls + +Volúmenes principales definidos en ``compose-opensearch3.yaml``: + +- ``search01_data``: Datos de índice de OpenSearch (incluye todos los datos de Fess) +- ``search01_dictionary``: Archivos de diccionario + +.. note:: + + Los nombres de los volúmenes de Docker Compose llevan como prefijo el nombre del proyecto (de forma + predeterminada, el nombre del directorio donde se encuentra el archivo Compose). + Por ejemplo, si se inicia desde el directorio ``compose``, el nombre real del volumen sería algo como + ``compose_search01_data``. + +.. important:: + + Los volúmenes no se eliminan aunque se eliminen los contenedores. + Para eliminar los volúmenes, es necesario ejecutar explícitamente el comando ``docker volume rm``. + +Detención del Contenedor Docker +================================ + +Para detener contenedores:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop + +Para detener y eliminar contenedores:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +.. warning:: + + El comando ``down`` elimina los contenedores, pero no los volúmenes. + Si también desea eliminar los volúmenes (como ``search01_data``), agregue la opción ``-v``:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down -v + + **Precaución**: Ejecutar este comando eliminará todos los datos almacenados en OpenSearch. + +Configuración Avanzada +======================= + +Personalización de Variables de Entorno +---------------------------------------- + +Es posible realizar configuraciones detalladas agregando o modificando variables de entorno en ``compose.yaml``. + +Variables de entorno principales: + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Variable de Entorno + - Descripción + * - ``FESS_HEAP_SIZE`` + - Tamaño del heap de JVM de Fess (valor predeterminado de la imagen Docker: 512m) + * - ``FESS_JAVA_OPTS`` + - Especificación de opciones JVM adicionales (por ejemplo, sobrescribir configuraciones mediante ``-Dfess.config.*``) + * - ``FESS_PLUGINS`` + - Plugins que se instalan automáticamente al iniciar (formato ``name:version`` separado por espacios; ejemplo: ``fess-ds-wikipedia:15.10.0``) + * - ``SEARCH_ENGINE_HTTP_URL`` + - Punto de conexión HTTP de OpenSearch (valor predeterminado en ``compose.yaml``: ``http://search01:9200``) + * - ``SEARCH_ENGINE_TYPE`` + - El tipo de motor de búsqueda (``default``, ``vanilla`` o ``aws``). ``vanilla`` requiere una imagen de Fess 15.10 o posterior; con imágenes anteriores utilice ``cloud`` (consulte :doc:`../config/search-engine-type`). En las imágenes 15.8, solo la variante ``-noble`` transmite el valor a Fess. + * - ``SEARCH_ENGINE_USERNAME`` / ``SEARCH_ENGINE_PASSWORD`` + - Credenciales para conectarse a un OpenSearch con autenticación habilitada + * - ``FESS_DICTIONARY_PATH`` + - Ruta del archivo de diccionario (directorio compartido con OpenSearch) + * - ``FESS_PORT`` + - Puerto en el que Fess escucha dentro del contenedor (valor predeterminado: 8080) + +Ejemplo:: + + services: + fess01: + environment: + - "FESS_HEAP_SIZE=4g" + +.. note:: + + Si desea cambiar la zona horaria, especifíquela en ``FESS_JAVA_OPTS`` como ``-Duser.timezone=Asia/Tokyo``. + +Cómo Aplicar Archivos de Configuración +---------------------------------------- + +La configuración detallada de |Fess| se describe en el archivo ``fess_config.properties``. +En la imagen Docker, ``fess_config.properties`` se encuentra ubicado en ``/etc/fess`` dentro del contenedor. +Para reflejar la configuración en un entorno Docker, existen los siguientes métodos. + +Método 1: Montar Archivos de Configuración +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``/etc/fess`` también contiene otros archivos de configuración necesarios para el funcionamiento de Fess, por +lo que si se reemplaza este directorio directamente mediante un montaje, el inicio fallará. +En su lugar, se utiliza el directorio de anulación ``/opt/fess``, que se añade al principio del classpath +(está vacío de forma predeterminada). + +1. Cree en el host un directorio para preparar el archivo de configuración:: + + $ mkdir -p /path/to/fess-config + +2. Obtenga la plantilla del archivo de configuración (solo la primera vez):: + + $ curl -o /path/to/fess-config/fess_config.properties https://raw.githubusercontent.com/codelibs/fess/refs/tags/fess-15.10.0/src/main/resources/fess_config.properties + +3. Edite ``/path/to/fess-config/fess_config.properties`` y escriba la configuración necesaria:: + + # Ejemplo + crawler.document.cache.enabled=false + adaptive.load.control=20 + query.facet.fields=label,host + +4. Agregue el montaje de volumen al servicio ``fess01`` en ``compose.yaml``:: + + services: + fess01: + volumes: + - /path/to/fess-config/fess_config.properties:/opt/fess/fess_config.properties + +5. Inicie el contenedor:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +.. note:: + + ``/opt/fess`` se añade al principio del classpath, por lo que el archivo ``fess_config.properties`` + colocado aquí tiene prioridad sobre el ``/etc/fess/fess_config.properties`` incluido en la imagen. + Los archivos de propiedades se cargan como un todo y no se combinan elemento por elemento. + Un elemento que falta en su archivo no impide el inicio de |Fess|: se utiliza el valor predeterminado incluido en su versión y se registra una advertencia por cada elemento. + Por lo tanto, también funciona un archivo que contenga solo los elementos que desea cambiar. Para evitar las advertencias, parta del archivo completo, como en el paso 2. + Si solo desea cambiar algunos elementos, utilice el "Método 2" a continuación. + Si un elemento se define tanto en este archivo como con ``-Dfess.config.`` (Método 2), se utiliza el valor definido con ``-D``. + +Método 2: Configuración mediante Propiedades del Sistema +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Los elementos de configuración de ``fess_config.properties`` se pueden sobrescribir como propiedades del +sistema mediante variables de entorno. + +Los elementos de configuración descritos en ``fess_config.properties`` (por ejemplo, +``crawler.document.cache.enabled=false``) se especifican en el formato +``-Dfess.config.nombre_del_elemento=valor``. + +Agregue ``FESS_JAVA_OPTS`` a las variables de entorno del servicio ``fess01`` en ``compose.yaml``:: + + services: + fess01: + environment: + - "FESS_JAVA_OPTS=-Dfess.config.crawler.document.cache.enabled=false -Dfess.config.adaptive.load.control=20 -Dfess.config.query.facet.fields=label,host" + +.. note:: + + La parte que sigue a ``-Dfess.config.`` corresponde al nombre del elemento de configuración en + ``fess_config.properties``. + Si solo desea sobrescribir algunos elementos, este método es más sencillo. + +Conexión a OpenSearch Externo +------------------------------ + +Si desea utilizar un clúster de OpenSearch existente, inicie solo con ``compose.yaml`` sin usar +``compose-opensearch3.yaml``, y cambie el destino de conexión. + +1. Inicie sin especificar ``compose-opensearch3.yaml``:: + + $ docker compose -f compose.yaml up -d + +2. Configure el destino de conexión en el servicio ``fess01`` de ``compose.yaml``:: + + environment: + - "SEARCH_ENGINE_HTTP_URL=http://your-opensearch-host:9200" + +.. note:: + + Si se conecta a un OpenSearch con autenticación habilitada, especifique también + ``SEARCH_ENGINE_USERNAME`` y ``SEARCH_ENGINE_PASSWORD``. + +Otros Overlays y Configuraciones +================================= + +El repositorio ``docker-fess`` incluye, además de lo anterior, archivos Compose y directorios para otros usos. + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Archivo / Directorio + - Uso + * - ``compose-dashboards3.yaml`` + - Agrega OpenSearch Dashboards (puerto 5601, para visualización de datos) + * - ``compose-minio.yaml`` + - Agrega MinIO (almacenamiento de objetos) y lo utiliza como destino de almacenamiento para la función de almacenamiento de Fess + * - ``vanilla/`` + - Configuración que combina con un OpenSearch puro sin los plugins de CodeLibs (``SEARCH_ENGINE_TYPE=vanilla``; requiere una imagen de Fess 15.10 o posterior, con imágenes anteriores utilice ``cloud``). Algunas funciones, como la gestión de diccionarios, no están disponibles (consulte :doc:`../config/search-engine-type`) + * - ``snapshot/`` + - Configuración que utiliza imágenes de desarrollo (snapshot) (incluye configuraciones de clúster y combinaciones con Elasticsearch 8) + * - ``multi-instance/`` + - Configuración que inicia múltiples instancias de Fess compartiendo un solo OpenSearch + +Configuración de Red Docker +----------------------------- + +Si se integra con múltiples servicios, puede usar una red personalizada. + +Ejemplo:: + + networks: + fess-network: + driver: bridge + + services: + fess01: + networks: + - fess-network + +Operación en Producción con Docker Compose +=========================================== + +Configuraciones recomendadas al usar Docker Compose en entornos de producción: + +1. **Configuración de límites de recursos**:: + + deploy: + resources: + limits: + cpus: '2.0' + memory: 4G + reservations: + cpus: '1.0' + memory: 2G + +2. **Configuración de política de reinicio**:: + + restart: unless-stopped + +3. **Configuración de registros**:: + + logging: + driver: "json-file" + options: + max-size: "10m" + max-file: "3" + +4. **Habilitación de configuración de seguridad** + + Habilite el plugin de seguridad de OpenSearch y configure la autenticación apropiada. + Para más detalles, consulte :doc:`security`. + +Solución de Problemas +====================== + +Los Contenedores no Inician +---------------------------- + +1. Verificar registros:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs + +2. Verificar conflictos de puertos:: + + $ sudo ss -tuln | grep 8080 + $ sudo ss -tuln | grep 9200 + +3. Verificar espacio en disco:: + + $ df -h + +Errores de Memoria Insuficiente +-------------------------------- + +Si OpenSearch no inicia por falta de memoria, es necesario aumentar ``vm.max_map_count``. + +En Linux:: + + $ sudo sysctl -w vm.max_map_count=262144 + +Para configurar permanentemente:: + + $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf + $ sudo sysctl -p + +Inicialización de Datos +------------------------ + +Para eliminar todos los datos y volver al estado inicial:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down -v + $ docker volume prune + +.. warning:: + + Ejecutar este comando eliminará todos los datos completamente. + +Próximos Pasos +=============== + +Después de completar la instalación, consulte la siguiente documentación: + +- :doc:`run` - Inicio de |Fess| y configuración inicial +- :doc:`security` - Configuración de seguridad para entornos de producción +- :doc:`troubleshooting` - Solución de problemas + +Preguntas Frecuentes +===================== + +P: ¿Cuánto espacio en disco se necesita para descargar las imágenes? +------------------------------------------------------------------------ + +R: Las imágenes de Fess y OpenSearch se descargan la primera vez que se inician, y en conjunto requieren +aproximadamente varios GB de espacio en disco. +Dependiendo del entorno de red, la descarga puede tardar cierto tiempo. + +P: ¿Es posible operar en Kubernetes? +-------------------------------------- + +R: Sí, es posible. Puede convertir el archivo Docker Compose en manifiestos de Kubernetes usando herramientas +como ``kompose``, o crear sus propios manifiestos para operar (no se ofrece un chart oficial de Helm). + +P: ¿Cómo se actualizan los contenedores? +------------------------------------------ + +R: Actualice siguiendo estos pasos: + +1. Obtenga los archivos Compose más recientes +2. Detenga los contenedores:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +3. Obtenga nuevas imágenes:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull + +4. Inicie los contenedores:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +P: ¿Es posible una configuración de múltiples nodos? +------------------------------------------------------- + +R: Sí, es posible. Puede configurar OpenSearch con múltiples nodos tomando como referencia +``snapshot/compose-cluster.yaml`` del repositorio ``docker-fess``, o configurar múltiples instancias de Fess +que comparten un solo OpenSearch tomando como referencia ``multi-instance/``. +Sin embargo, para entornos de producción se recomienda usar herramientas de orquestación como Kubernetes. diff --git a/es/15.10/install/install-linux.rst b/es/15.10/install/install-linux.rst new file mode 100644 index 000000000..143538be5 --- /dev/null +++ b/es/15.10/install/install-linux.rst @@ -0,0 +1,575 @@ +======================================================== +Instalación en Linux (Procedimientos Detallados) +======================================================== + +Esta página describe los procedimientos de instalación de |Fess| en entornos Linux. +Es compatible con los formatos de paquete ZIP, RPM y DEB. + +.. note:: + + |Fess| no incluye un motor de búsqueda. Se requiere un servidor OpenSearch, que los + pasos siguientes configuran. + +Requisitos Previos +=================== + +- Cumplir con los requisitos del sistema descritos en :doc:`prerequisites` +- Java 21 instalado +- OpenSearch 3.9.0 disponible (o nueva instalación) + +Selección del Método de Instalación +===================================== + +En entornos Linux, puede seleccionar entre los siguientes métodos de instalación: + +.. list-table:: + :header-rows: 1 + :widths: 20 40 40 + + * - Método + - Entorno Recomendado + - Características + * - ZIP + - Entorno de desarrollo, entornos que requieren personalización + - Expandible en cualquier directorio + * - RPM + - Sistemas basados en RHEL, CentOS, Fedora + - Gestión de servicios posible con systemd + * - DEB + - Sistemas basados en Debian, Ubuntu + - Gestión de servicios posible con systemd + +Configuración del Sistema para Ejecutar OpenSearch +===================================================== + +Para que OpenSearch funcione de manera estable en Linux, configure los siguientes parámetros del kernel y límites de recursos. +Estos son necesarios principalmente para la versión TAR.GZ (cuando OpenSearch se instala manualmente). +En las versiones RPM / DEB, los paquetes de OpenSearch y |Fess| configuran el número de descriptores de archivo, entre otros, a través de systemd, pero dado que ``vm.max_map_count`` es una configuración del kernel del lado del host, verifíquela con cualquiera de los dos métodos. + +Número Máximo de Mapas de Memoria Virtual +-------------------------------------------- + +Dado que OpenSearch utiliza numerosos mapas de memoria, configure ``vm.max_map_count`` en ``262144`` o más. + +Para configurarlo de forma temporal:: + + $ sudo sysctl -w vm.max_map_count=262144 + +Para configurarlo de forma permanente:: + + $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf + $ sudo sysctl -p + +Número de Descriptores de Archivo +-------------------------------------------- + +Cuando ejecute OpenSearch manualmente (versión TAR.GZ), configure el límite superior del número de descriptores de archivo del usuario que ejecuta OpenSearch en ``65535`` o más. + +Agregue lo siguiente a ``/etc/security/limits.conf`` (reemplace ``opensearch`` por el nombre del usuario que ejecuta OpenSearch):: + + opensearch - nofile 65535 + +.. note:: + + En las versiones RPM / DEB, esta configuración no es necesaria, ya que el límite superior del número de descriptores de archivo se establece en la definición del servicio systemd. + +Instalación con Versión ZIP +================================= + +Paso 1: Instalación de OpenSearch +------------------------------------ + +.. important:: + + Instale y ejecute OpenSearch con un usuario normal, no como ``root``: OpenSearch se niega a + iniciarse como ``root``. Ejecute también ``bin/fess-setup`` con ese usuario, para que los + archivos que extrae pertenezcan a ese usuario. Consulte :doc:`run` si ya se ha rechazado un + inicio como ``root``. + +.. tip:: + + ``bin/fess-setup``, incluido con |Fess|, realiza los pasos 1 a 3 siguientes en una sola orden. + Descarga y extrae OpenSearch en ``opensearch/`` dentro del directorio de |Fess|, instala los + plugins necesarios y añade ``configsync.config_path`` y ``plugins.security.disabled: true`` a + su ``config/opensearch.yml``. Extraiga primero el ZIP de |Fess|, tal como se describe en el + Paso 2. + + :: + + $ cd /path/to/fess-15.10.0 + $ bin/fess-setup install opensearch + + ``bin/fess.in.sh`` encuentra un OpenSearch instalado de esta forma y establece + ``FESS_DICTIONARY_PATH`` por sí mismo, por lo que "Configuración de Fess" en el Paso 2 no + requiere cambios mientras OpenSearch se ejecute en el mismo host. El comando muestra la + configuración que ha añadido y si ``bin/fess.in.sh`` encuentra la instalación. Lea la + advertencia del paso 3 antes de que OpenSearch escuche en cualquier dirección distinta de + ``localhost``. + + Siga los pasos siguientes para revisarlos uno a uno, o cuando utilice un OpenSearch que ya + tenga. Para instalar únicamente los plugins en un OpenSearch existente, utilice + ``bin/fess-setup install opensearch-plugins --opensearch-home /path/to/opensearch``. + Consulte :doc:`fess-setup` para ver todos los comandos. + +.. note:: + + OpenSearch no publica ninguna versión para macOS, por lo que en macOS + ``bin/fess-setup install opensearch`` termina con un error. Instale OpenSearch con Homebrew y + añada los plugins con ``bin/fess-setup install opensearch-plugins``, o bien utilice + :doc:`install-docker`:: + + $ brew install opensearch + $ bin/fess-setup install opensearch-plugins --opensearch-home $(brew --prefix opensearch) + + A continuación, configure ese OpenSearch como en el paso 3 y establezca + ``FESS_DICTIONARY_PATH`` tal como se describe en "Configuración de Fess" en el Paso 2. + +1. Descarga de OpenSearch + + Descargue la versión TAR.GZ desde `Download OpenSearch `__. + + :: + + $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.9.0/opensearch-3.9.0-linux-x64.tar.gz + $ tar -xzf opensearch-3.9.0-linux-x64.tar.gz + $ cd opensearch-3.9.0 + + En un equipo arm64 (aarch64), reemplace ``linux-x64`` por ``linux-arm64`` en los nombres de archivo anteriores (por ejemplo, ``opensearch-3.9.0-linux-arm64.tar.gz``). + + .. note:: + + En este ejemplo se utiliza OpenSearch 3.9.0. + |Fess| 15.10 es compatible con OpenSearch 3.9.0. + +2. Instalación de plugins de OpenSearch + + Instale los plugins que requiere |Fess|. + + :: + + $ cd /path/to/opensearch-3.9.0 + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + + .. important:: + + Las versiones de los plugins deben coincidir con la versión de OpenSearch. + En el ejemplo anterior, se especifica 3.9.0 para todos. + + Los cuatro plugins de |Fess| se publican en maven.codelibs.org, por lo que se instalan + mediante su URL. La forma ``groupId:artifactId:version`` de ``opensearch-plugin install`` solo + busca en Maven Central. + +3. Configuración de OpenSearch + + Agregue la siguiente configuración a ``config/opensearch.yml``. + + :: + + # Ruta para sincronización de configuración (especificar ruta absoluta) + configsync.config_path: /path/to/opensearch-3.9.0/config/dictionary/ + + # Desactivación del plugin de seguridad (solo entorno de desarrollo) + plugins.security.disabled: true + + .. important:: + + Especifique en ``configsync.config_path`` un directorio dentro del directorio de configuración de OpenSearch (``/path/to/opensearch-3.9.0/config/`` en este ejemplo). + OpenSearch 3.8.0 y versiones posteriores rechazan la creación de índices cuando los archivos de diccionario están fuera del directorio de configuración. + Si especifica un directorio fuera del directorio de configuración, como ``/path/to/opensearch-3.9.0/data/config/``, |Fess| no puede crear sus índices y no se inicia. + + .. warning:: + + **Nota Importante sobre Seguridad** + + ``plugins.security.disabled: true`` debe usarse únicamente en entornos de desarrollo o de prueba. + En entornos de producción, habilite el plugin de seguridad de OpenSearch y configure adecuadamente la autenticación y la autorización. + Si habilita el plugin de seguridad en OpenSearch 2.12 o posterior, es necesario configurar la contraseña de administrador (variable de entorno ``OPENSEARCH_INITIAL_ADMIN_PASSWORD``) en el primer inicio. + Para más detalles, consulte :doc:`security`. + + .. tip:: + + Ajuste otras configuraciones, como el nombre del clúster y la configuración de red, según su entorno. + Ejemplo de configuración:: + + cluster.name: fess-cluster + node.name: fess-node-1 + network.host: 0.0.0.0 + discovery.type: single-node + + .. tip:: + + El tamaño de heap de OpenSearch se configura mediante ``-Xms`` / ``-Xmx`` en ``config/jvm.options``. + Se recomienda especificar el mismo valor en ``-Xms`` y ``-Xmx``, tomando como referencia la mitad o menos de la memoria física disponible, y menos de 32 GB. + +Paso 2: Instalación de Fess +------------------------------ + +1. Descarga y extracción de Fess + + Descargue la versión ZIP desde el `sitio de descargas `__. + + :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.zip + $ unzip fess-15.10.0.zip + $ cd fess-15.10.0 + + .. note:: + + Seleccione un directorio que no contenga espacios en la ruta (también en macOS). Si la ruta contiene un espacio, ``bin/fess`` no se inicia y muestra ``Could not find or load main class``. + +2. Configuración de Fess + + La información de conexión a OpenSearch está en ``bin/fess.in.sh``. Con un OpenSearch que + ``bin/fess-setup install opensearch`` instaló en ``opensearch/`` dentro del directorio de |Fess| + y que se ejecuta en el mismo host, este archivo no requiere cambios: ``SEARCH_ENGINE_HTTP_URL`` + tiene como valor predeterminado ``http://localhost:9200``, y ``FESS_DICTIONARY_PATH`` se + establece en el directorio ``config/dictionary`` de ese OpenSearch. + + Edite ``bin/fess.in.sh`` en cualquiera de los siguientes casos: + + - OpenSearch se instaló de otra forma, como con los pasos 1 a 3 anteriores o con Homebrew, o con + ``--dest`` fuera del directorio de |Fess|. + - ``opensearch/`` dentro del directorio de |Fess| contiene más de un OpenSearch instalado por + ``bin/fess-setup``, por ejemplo dos versiones. ``bin/fess.in.sh`` no puede saber cuál está en + uso, así que muestra una advertencia y deja ``FESS_DICTIONARY_PATH`` sin establecer. + - OpenSearch se ejecuta en otro host o puerto. + + :: + + $ vi bin/fess.in.sh + + Cerca del principio del archivo, elimine el ``#`` inicial de la línea ``FESS_DICTIONARY_PATH`` y + establezca la ruta, y cambie la URL de la línea ``SEARCH_ENGINE_HTTP_URL`` si es necesario. + + Antes del cambio (estado predeterminado, sin las líneas de comentario):: + + SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://localhost:9200} + #FESS_DICTIONARY_PATH=/var/lib/opensearch/config/ + + Después del cambio:: + + SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://localhost:9200} + FESS_DICTIONARY_PATH=/path/to/opensearch-3.9.0/config/dictionary/ + + .. note:: + + - Configure ``FESS_DICTIONARY_PATH`` con la misma ruta que especificó en ``configsync.config_path`` dentro de ``opensearch.yml`` de OpenSearch. Sin ella, |Fess| no puede crear sus índices y no se inicia. + - Si ejecuta OpenSearch en otro host, cambie la URL de la línea ``SEARCH_ENGINE_HTTP_URL`` por la de ese host. Ejemplo: ``SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://192.168.1.100:9200}``. En ese caso, ``FESS_DICTIONARY_PATH`` es el ``configsync.config_path`` de ese servidor. + - En lugar de editar el archivo, puede exportar ambas variables en el entorno desde el que se inicia |Fess|. Un ``SEARCH_ENGINE_HTTP_URL`` exportado tiene prioridad sobre la URL del archivo, y un ``FESS_DICTIONARY_PATH`` exportado se utiliza mientras su línea en el archivo siga comentada. + - No agregue una nueva línea ``SEARCH_ENGINE_HTTP_URL=...``; en su lugar, edite la línea existente. + + .. tip:: + + Para cambiar el tamaño de heap de |Fess|, edite ``FESS_MIN_MEM`` (predeterminado: ``256m``) y ``FESS_MAX_MEM`` (predeterminado: ``2g``) en ``bin/fess.in.sh``, o configure la variable de entorno ``FESS_HEAP_SIZE``. + +3. Verificación de la instalación + + Verifique que el archivo de configuración se haya editado correctamente:: + + $ grep "SEARCH_ENGINE_HTTP_URL" bin/fess.in.sh + $ grep "FESS_DICTIONARY_PATH" bin/fess.in.sh + + Una vez que OpenSearch esté en ejecución, ``bin/fess-setup check`` informa de si es accesible, + si tiene los plugins que requiere |Fess| y si ``configsync`` responde. Termina con el código + ``0`` cuando ninguna comprobación ha fallado. Indique ``--url`` cuando OpenSearch no esté en + ``http://localhost:9200``. + +Paso 3: Inicio +------------------ + +Para conocer los procedimientos de inicio, consulte :doc:`run`. + +Instalación con Versión RPM +============================== + +La versión RPM se utiliza en distribuciones Linux basadas en RPM, como Red Hat Enterprise Linux, CentOS, Fedora, entre otras. + +Paso 1: Instalación de OpenSearch +------------------------------------ + +1. Descarga e instalación del RPM de OpenSearch + + Descargue e instale el paquete RPM desde `Download OpenSearch `__. + + :: + + $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.9.0/opensearch-3.9.0-linux-x64.rpm + $ sudo rpm -ivh opensearch-3.9.0-linux-x64.rpm + + En un equipo arm64 (aarch64), reemplace ``linux-x64`` por ``linux-arm64`` en los nombres de archivo anteriores (por ejemplo, ``opensearch-3.9.0-linux-arm64.rpm``). + + Alternativamente, también puede agregar un repositorio para instalarlo. + Para más detalles, consulte `Installing OpenSearch `__. + +2. Instalación de plugins de OpenSearch + + :: + + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + +3. Configuración de OpenSearch + + Agregue la siguiente configuración a ``/etc/opensearch/opensearch.yml``. + + :: + + $ sudo vi /etc/opensearch/opensearch.yml + + Configuración a agregar:: + + configsync.config_path: /etc/opensearch/dictionary/ + plugins.security.disabled: true + + Cree el directorio para los archivos de diccionario:: + + $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary + + .. important:: + + Especifique en ``configsync.config_path`` un directorio dentro del directorio de configuración de OpenSearch ``/etc/opensearch/``. + OpenSearch 3.8.0 y versiones posteriores rechazan la creación de índices cuando los archivos de diccionario están fuera del directorio de configuración. + Si especifica un directorio fuera del directorio de configuración, como ``/var/lib/opensearch/data/config/``, |Fess| no puede crear sus índices y no se inicia. + + .. warning:: + + No utilice ``plugins.security.disabled: true`` en entornos de producción. + Consulte :doc:`security` para configurar la seguridad de manera adecuada. + +Paso 2: Instalación de Fess +------------------------------ + +1. Instalación del RPM de Fess + + Descargue e instale el paquete RPM desde el `sitio de descargas `__. + + :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.rpm + $ sudo rpm -ivh fess-15.10.0.rpm + +2. Configuración de Fess + + En la versión RPM, edite el archivo de configuración de variables de entorno ``/etc/sysconfig/fess``. + Este archivo se conserva incluso al actualizar el paquete (no edite directamente ``/usr/share/fess/bin/fess.in.sh``, ya que se sobrescribe durante la actualización). + + :: + + $ sudo vi /etc/sysconfig/fess + + Configure la información de conexión a OpenSearch. El valor predeterminado de ``FESS_DICTIONARY_PATH``, ``/var/lib/opensearch/config/``, difiere de ``configsync.config_path`` del paso 3, así que cámbielo como se indica a continuación. Cambie ``SEARCH_ENGINE_HTTP_URL`` según sea necesario:: + + SEARCH_ENGINE_HTTP_URL=http://localhost:9200 + FESS_DICTIONARY_PATH=/etc/opensearch/dictionary/ + + .. note:: + + Especifique en ``FESS_DICTIONARY_PATH`` la misma ruta que en ``configsync.config_path`` de ``opensearch.yml``. + +3. Registro y habilitación del servicio + + Habilite el servicio utilizando systemd (systemd es el estándar en RHEL 8 y posteriores, y CentOS 8 y posteriores):: + + $ sudo systemctl daemon-reload + $ sudo systemctl enable opensearch.service + $ sudo systemctl enable fess.service + + .. note:: + + El servicio de |Fess| depende del servicio de OpenSearch, por lo que es necesario iniciar OpenSearch primero. + + .. note:: + + En entornos tradicionales que no utilizan systemd, puede registrar |Fess| con ``chkconfig``:: + + $ sudo /sbin/chkconfig --add fess + +Paso 3: Inicio +------------------ + +Para conocer los procedimientos de inicio, consulte :doc:`run`. + +Instalación con Versión DEB +============================== + +La versión DEB se utiliza en distribuciones Linux basadas en DEB, como Debian, Ubuntu, entre otras. + +Paso 1: Instalación de OpenSearch +------------------------------------ + +1. Descarga e instalación del DEB de OpenSearch + + Descargue e instale el paquete DEB desde `Download OpenSearch `__. + + :: + + $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.9.0/opensearch-3.9.0-linux-x64.deb + $ sudo dpkg -i opensearch-3.9.0-linux-x64.deb + + En un equipo arm64 (aarch64), reemplace ``linux-x64`` por ``linux-arm64`` en los nombres de archivo anteriores (por ejemplo, ``opensearch-3.9.0-linux-arm64.deb``). + + Alternativamente, también puede agregar un repositorio para instalarlo. + Para más detalles, consulte `Installing OpenSearch `__. + +2. Instalación de plugins de OpenSearch + + :: + + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + +3. Configuración de OpenSearch + + Agregue la siguiente configuración a ``/etc/opensearch/opensearch.yml``. + + :: + + $ sudo vi /etc/opensearch/opensearch.yml + + Configuración a agregar:: + + configsync.config_path: /etc/opensearch/dictionary/ + plugins.security.disabled: true + + Cree el directorio para los archivos de diccionario:: + + $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary + + .. important:: + + Especifique en ``configsync.config_path`` un directorio dentro del directorio de configuración de OpenSearch ``/etc/opensearch/``. + OpenSearch 3.8.0 y versiones posteriores rechazan la creación de índices cuando los archivos de diccionario están fuera del directorio de configuración. + Si especifica un directorio fuera del directorio de configuración, como ``/var/lib/opensearch/data/config/``, |Fess| no puede crear sus índices y no se inicia. + + .. warning:: + + No utilice ``plugins.security.disabled: true`` en entornos de producción. + Consulte :doc:`security` para configurar la seguridad de manera adecuada. + +Paso 2: Instalación de Fess +------------------------------ + +1. Instalación del DEB de Fess + + Descargue e instale el paquete DEB desde el `sitio de descargas `__. + + :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.deb + $ sudo dpkg -i fess-15.10.0.deb + +2. Configuración de Fess + + En la versión DEB, edite el archivo de configuración de variables de entorno ``/etc/default/fess``. + Este archivo se conserva incluso al actualizar el paquete (no edite directamente ``/usr/share/fess/bin/fess.in.sh``, ya que se sobrescribe durante la actualización). + + :: + + $ sudo vi /etc/default/fess + + Configure la información de conexión a OpenSearch. El valor predeterminado de ``FESS_DICTIONARY_PATH``, ``/var/lib/opensearch/config/``, difiere de ``configsync.config_path`` del paso 3, así que cámbielo como se indica a continuación. Cambie ``SEARCH_ENGINE_HTTP_URL`` según sea necesario:: + + SEARCH_ENGINE_HTTP_URL=http://localhost:9200 + FESS_DICTIONARY_PATH=/etc/opensearch/dictionary/ + + .. note:: + + Especifique en ``FESS_DICTIONARY_PATH`` la misma ruta que en ``configsync.config_path`` de ``opensearch.yml``. + +3. Registro y habilitación del servicio + + Habilite el servicio utilizando systemd:: + + $ sudo systemctl daemon-reload + $ sudo systemctl enable opensearch.service + $ sudo systemctl enable fess.service + + .. note:: + + El servicio de |Fess| depende del servicio de OpenSearch, por lo que es necesario iniciar OpenSearch primero. + +Paso 3: Inicio +------------------ + +Para conocer los procedimientos de inicio, consulte :doc:`run`. + +Verificación Posterior a la Instalación +========================================== + +Después de completar la instalación, verifique lo siguiente: + +1. **Verificación de los archivos de configuración** + + - Archivo de configuración de OpenSearch (opensearch.yml) + - Archivo de configuración de |Fess| + + - Versión ZIP: ``bin/fess.in.sh`` + - Versión RPM: ``/etc/sysconfig/fess`` + - Versión DEB: ``/etc/default/fess`` + +2. **Permisos de directorio** + + Verifique que exista el directorio especificado en la configuración (``configsync.config_path`` / ``FESS_DICTIONARY_PATH``) y que tenga los permisos apropiados. + + Para la versión ZIP:: + + $ ls -ld /path/to/opensearch-3.9.0/config/dictionary/ + + Para las versiones RPM/DEB:: + + $ sudo ls -ld /etc/opensearch/dictionary/ + +3. **Verificación de los parámetros del kernel** + + :: + + $ sysctl vm.max_map_count + + Confirme que el valor sea ``262144`` o superior. + +4. **Verificación de la versión de Java** + + :: + + $ java -version + + Verifique que esté instalado Java 21 o posterior. + +Próximos Pasos +================= + +Después de completar la instalación, consulte la siguiente documentación: + +- :doc:`run` - Inicio de |Fess| y configuración inicial +- :doc:`security` - Configuración de seguridad para entornos de producción +- :doc:`troubleshooting` - Solución de problemas + +Preguntas Frecuentes +======================= + +P: ¿Funciona con otras versiones de OpenSearch? +-------------------------------------------------- + +R: |Fess| depende de una versión específica de OpenSearch. +Para garantizar la compatibilidad de los plugins, se recomienda encarecidamente utilizar la versión recomendada (3.9.0). +Si utiliza otra versión, también deberá ajustar adecuadamente las versiones de los plugins. + +P: ¿Se puede compartir el mismo OpenSearch entre varias instancias de Fess? +-------------------------------------------------------------------------------- + +R: Es posible, pero no se recomienda. Se recomienda preparar un clúster de OpenSearch dedicado para cada instancia de Fess. +Si comparte OpenSearch entre varias instancias de Fess, tenga cuidado con las colisiones de nombres de índice. + +P: ¿Cómo configurar OpenSearch en modo clúster? +-------------------------------------------------- + +R: Consulte la documentación oficial de OpenSearch `Cluster formation `__. +Para configurar un clúster, debe eliminar la configuración ``discovery.type: single-node`` y agregar la configuración de clúster apropiada. diff --git a/es/15.10/install/install-windows.rst b/es/15.10/install/install-windows.rst new file mode 100644 index 000000000..42a2473f0 --- /dev/null +++ b/es/15.10/install/install-windows.rst @@ -0,0 +1,363 @@ +==================================================== +Instalación en Windows (Procedimientos Detallados) +==================================================== + +Esta página describe los procedimientos de instalación de |Fess| en entornos Windows. +Describe el método de instalación utilizando el paquete ZIP. + +.. note:: + + |Fess| no incluye un motor de búsqueda. Se requiere un servidor OpenSearch, que los + pasos siguientes configuran. + +Requisitos Previos +================== + +- Cumplir con los requisitos del sistema descritos en :doc:`prerequisites` +- Java 21 instalado +- OpenSearch 3.9.0 disponible (o nueva instalación) +- Variable de entorno ``JAVA_HOME`` de Windows configurada apropiadamente + +Verificación de la Instalación de Java +======================================= + +Abra el Símbolo del sistema o PowerShell y verifique la versión de Java con el siguiente comando. + +En caso de Símbolo del sistema:: + + C:\> java -version + +En caso de PowerShell:: + + PS C:\> java -version + +Verifique que se muestre Java 21 o posterior. + +Configuración de Variables de Entorno +====================================== + +1. Configuración de la variable de entorno ``JAVA_HOME`` + + Configure el directorio donde está instalado Java como ``JAVA_HOME``. + + Ejemplo:: + + JAVA_HOME=C:\Program Files\Eclipse Adoptium\jdk-21.0.1.12-hotspot + +2. Agregar a la variable de entorno ``PATH`` + + Agregue ``%JAVA_HOME%\bin`` a la variable de entorno ``PATH``. + +.. tip:: + + Método para configurar variables de entorno: + + 1. Abra "Configuración" desde el menú "Inicio" + 2. Haga clic en "Sistema" → "Acerca de" → "Configuración avanzada del sistema" + 3. Haga clic en el botón "Variables de entorno" + 4. Configure en "Variables de entorno del sistema" o "Variables de entorno del usuario" + +Paso 1: Instalación de OpenSearch +================================== + +.. tip:: + + ``bin\fess-setup``, incluido con |Fess|, realiza los pasos siguientes en una sola orden. + Descarga y extrae OpenSearch en ``opensearch\`` dentro del directorio de |Fess|, instala los + plugins necesarios y añade ``configsync.config_path`` y ``plugins.security.disabled: true`` a + su ``config\opensearch.yml``. Extraiga primero el ZIP de |Fess|, tal como se describe en el + Paso 2. + + :: + + > cd C:\fess-15.10.0 + > bin\fess-setup install opensearch + + ``bin\fess.in.bat`` encuentra un OpenSearch instalado de esta forma y pasa su directorio + ``config\dictionary`` a |Fess|, por lo que "Configuración de Fess" en el Paso 2 no requiere + cambios mientras OpenSearch se ejecute en el mismo host. El comando muestra la configuración que + ha añadido y si ``bin\fess.in.bat`` encuentra la instalación. Lea la advertencia de + "Configuración de OpenSearch" antes de que OpenSearch escuche en cualquier dirección distinta de + ``localhost``. + + Siga los pasos siguientes para revisarlos uno a uno, o cuando utilice un OpenSearch que ya + tenga. Para instalar únicamente los plugins en un OpenSearch existente, utilice + ``bin\fess-setup install opensearch-plugins --opensearch-home C:\opensearch-3.9.0``. + Consulte :doc:`fess-setup` para ver todos los comandos. + +Descarga de OpenSearch +----------------------- + +1. Descargue el paquete ZIP para Windows desde `Download OpenSearch `__. + +2. Extraiga el archivo ZIP descargado en cualquier directorio. + + Ejemplo:: + + C:\opensearch-3.9.0 + + .. note:: + + Se recomienda seleccionar un directorio que no contenga caracteres japoneses o espacios en la ruta. + +Instalación de Plugins de OpenSearch +-------------------------------------- + +Abra el Símbolo del sistema **con privilegios de administrador** y ejecute los siguientes comandos. + +:: + + C:\> cd C:\opensearch-3.9.0 + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + +.. important:: + + Las versiones de los plugins deben coincidir con la versión de OpenSearch. + En el ejemplo anterior, se especifica 3.9.0 para todos. + + Los cuatro plugins de |Fess| se publican en maven.codelibs.org, por lo que se instalan mediante + su URL. La forma ``groupId:artifactId:version`` de ``opensearch-plugin install`` solo busca en + Maven Central. + +Configuración de OpenSearch +----------------------------- + +Abra ``config\opensearch.yml`` con un editor de texto y agregue la siguiente configuración. + +:: + + # Ruta para sincronización de configuración (especificar ruta absoluta) + configsync.config_path: C:/opensearch-3.9.0/config/dictionary/ + + # Desactivación del plugin de seguridad (solo entorno de desarrollo) + plugins.security.disabled: true + +.. warning:: + + **Nota Importante sobre Seguridad** + + ``plugins.security.disabled: true`` debe usarse solo en entornos de desarrollo o prueba. + En entornos de producción, habilite el plugin de seguridad de OpenSearch y configure apropiadamente la autenticación y autorización. + Para más detalles, consulte :doc:`security`. + +.. note:: + + En Windows, use ``/`` en lugar de ``\`` como separador de ruta. + Escriba ``C:/opensearch-3.9.0/config/dictionary/`` en lugar de ``C:\opensearch-3.9.0\config\dictionary\``. + +.. important:: + + Especifique en ``configsync.config_path`` un directorio dentro del directorio de configuración de OpenSearch (``C:/opensearch-3.9.0/config/`` en este ejemplo). + OpenSearch 3.8.0 y versiones posteriores rechazan la creación de índices cuando los archivos de diccionario están fuera del directorio de configuración. + Si especifica un directorio fuera del directorio de configuración, como ``C:/opensearch-3.9.0/data/config/``, |Fess| no puede crear sus índices y no se inicia. + +.. tip:: + + Otras configuraciones recomendadas:: + + cluster.name: fess-cluster + node.name: fess-node-1 + network.host: 0.0.0.0 + discovery.type: single-node + +.. tip:: + + El tamaño del heap de OpenSearch se configura con ``-Xms`` / ``-Xmx`` en ``config\jvm.options``. + Se recomienda establecer el mismo valor para ``-Xms`` y ``-Xmx``, usando como referencia la mitad o menos de la memoria física disponible, sin superar 32 GB. + +Paso 2: Instalación de Fess +============================= + +Descarga de Fess +----------------- + +1. Descargue el paquete ZIP para Windows desde el `sitio de descargas `__. + +2. Extraiga el archivo ZIP descargado en cualquier directorio. + + Ejemplo:: + + C:\fess-15.10.0 + + .. note:: + + Se recomienda seleccionar un directorio que no contenga caracteres japoneses o espacios en la ruta. + +Configuración de Fess +---------------------- + +Con un OpenSearch que ``bin\fess-setup install opensearch`` instaló en ``opensearch\`` dentro del +directorio de |Fess| y que se ejecuta en el mismo host, no es necesario configurar nada aquí. En +caso contrario, por ejemplo cuando OpenSearch se instaló con los pasos anteriores, se ejecuta en +otro host, o ``opensearch\`` contiene más de un OpenSearch instalado por ``bin\fess-setup``, +configure la conexión de la siguiente manera. + +Abra ``bin\fess.in.bat`` con un editor de texto. +Cerca del final de este archivo encontrará una sección de configuración para conectarse a un clúster OpenSearch externo, que ya está preparada en forma de comentario. + +Estado antes del cambio (estado predeterminado):: + + REM External opensearch cluster + REM set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200 + REM set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=C:/opensearch/config/dictionary + +Elimine el ``REM `` del inicio de las dos líneas inferiores para descomentarlas, y cambie el valor de ``fess.dictionary.path`` a la ruta de sincronización de configuración de OpenSearch. + +Estado después del cambio:: + + REM External opensearch cluster + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200 + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=C:/opensearch-3.9.0/config/dictionary/ + +.. note:: + + - En ``fess.dictionary.path``, establezca la misma ruta que la indicada en ``configsync.config_path`` dentro de ``opensearch.yml`` de OpenSearch. + - Si está ejecutando OpenSearch en otro host, cambie el nombre de host o la dirección IP en ``fess.search_engine.http_address`` al valor apropiado. + - Use ``/`` como separador de ruta. |Fess| inserta la ruta en la configuración de los índices, donde se pierde cualquier ``\``, por lo que una ruta escrita con ``\`` no se encuentra. + - En lugar de agregar nuevas líneas ``set FESS_JAVA_OPTS=...``, descomente y edite las líneas de comentario existentes. Especificar la misma opción de forma duplicada puede causar comportamientos no deseados. + +.. tip:: + + Para cambiar el tamaño del heap de |Fess|, edite ``FESS_MIN_MEM`` (predeterminado: ``256m``) y ``FESS_MAX_MEM`` (predeterminado: ``1g``) en ``bin\fess.in.bat``, o establezca la variable de entorno ``FESS_HEAP_SIZE``. + +Verificación de la Instalación +-------------------------------- + +Verifique que los archivos de configuración se hayan editado correctamente. + +En el Símbolo del sistema:: + + C:\> findstr "fess.search_engine.http_address" C:\fess-15.10.0\bin\fess.in.bat + C:\> findstr "fess.dictionary.path" C:\fess-15.10.0\bin\fess.in.bat + +Paso 3: Inicio +============== + +Para los procedimientos de inicio, consulte :doc:`run`. + +Registro como Servicio de Windows (Opcional) +============================================= + +Al registrar |Fess| como servicio de Windows, se puede configurar para que se inicie automáticamente al arrancar el sistema. + +|Fess| incluye el script ``bin\service.bat`` para registrar el servicio de Windows. +Este script utiliza Apache Commons Daemon (procrun), por lo que no es necesario preparar herramientas de terceros como NSSM por separado. + +.. note:: + + Antes de ejecutar ``service.bat``, asegúrese de que la variable de entorno ``JAVA_HOME`` esté configurada correctamente. + +Registro del Servicio de |Fess| +--------------------------------- + +Abra el Símbolo del sistema **con privilegios de administrador** y ejecute los siguientes comandos. + +1. Registro del servicio:: + + C:\> cd C:\fess-15.10.0 + C:\fess-15.10.0> bin\service.bat install + + De forma predeterminada, el servicio se registra con el ID ``fess-service-x64`` en entornos de 64 bits, o ``fess-service-x86`` en entornos de 32 bits. + Para especificar el ID del servicio explícitamente, indíquelo como argumento: ``bin\service.bat install ``. + +2. Inicio y detención del servicio:: + + C:\fess-15.10.0> bin\service.bat start + C:\fess-15.10.0> bin\service.bat stop + +3. Verificación y modificación de la configuración del servicio (GUI):: + + C:\fess-15.10.0> bin\service.bat manager + +4. Eliminación del servicio:: + + C:\fess-15.10.0> bin\service.bat remove + +.. note:: + + - Como ``service.bat`` carga internamente ``bin\fess.in.bat``, la configuración de conexión a OpenSearch externo realizada en "Configuración de Fess" también se aplica al servicio. + - El tipo de inicio predeterminado es "Manual". Para que se inicie automáticamente al arrancar el sistema, establezca la variable de entorno ``FESS_START_TYPE`` en ``auto`` antes de registrar el servicio, o cambie el tipo de inicio a "Automático" en la herramienta de administración de servicios (``services.msc``) después del registro. + - Con ``service.bat`` solo se puede registrar el servicio de |Fess|. Para registrar OpenSearch como servicio, consulte los procedimientos proporcionados por OpenSearch. + +Configuración del Cortafuegos +============================== + +Abra los puertos necesarios en el Firewall de Windows Defender. + +1. Abra "Panel de control" → "Firewall de Windows Defender" → "Configuración avanzada" + +2. Cree una nueva regla en "Reglas de entrada" + + - Tipo de regla: Puerto + - Protocolo y puerto: TCP, 8080 + - Acción: Permitir conexión + - Nombre: Fess Web Interface + +O ejecute en PowerShell:: + + PS C:\> New-NetFirewallRule -DisplayName "Fess Web Interface" -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow + +Solución de Problemas +====================== + +Conflicto de Números de Puerto +------------------------------- + +Si los puertos 8080 o 9200 ya están en uso, puede verificarlo con el siguiente comando:: + + C:\> netstat -ano | findstr :8080 + C:\> netstat -ano | findstr :9200 + +Cambie el número de puerto en uso o detenga el proceso que está en conflicto. + +Limitación de Longitud de Ruta +------------------------------- + +En Windows, existe una limitación en la longitud de la ruta. Se recomienda instalar en una ruta lo más corta posible. + +Ejemplo:: + + C:\opensearch (recomendado) + C:\Program Files\opensearch-3.9.0 (no recomendado - ruta larga) + +Java no Reconocido +------------------ + +Si aparece un error al ejecutar el comando ``java -version``: + +1. Verifique que la variable de entorno ``JAVA_HOME`` esté configurada correctamente +2. Verifique que ``%JAVA_HOME%\bin`` esté incluido en la variable de entorno ``PATH`` +3. Reinicie el Símbolo del sistema para reflejar la configuración + +Próximos Pasos +============== + +Después de completar la instalación, consulte la siguiente documentación: + +- :doc:`run` - Inicio de |Fess| y configuración inicial +- :doc:`security` - Configuración de seguridad para entornos de producción +- :doc:`troubleshooting` - Solución de problemas + +Preguntas Frecuentes +===================== + +P: ¿Se recomienda la operación en Windows Server? +-------------------------------------------------- + +R: Sí, la operación en Windows Server es posible. +Al operar en Windows Server, regístrelo como servicio de Windows y configure el monitoreo apropiado. + +P: ¿Cuál es la diferencia entre las versiones de 64 bits y 32 bits? +-------------------------------------------------------------------- + +R: |Fess| y OpenSearch solo admiten la versión de 64 bits. +No funcionan en Windows de 32 bits. + +P: ¿Qué hacer si la ruta contiene japonés? +------------------------------------------- + +R: En la medida de lo posible, instale en una ruta que no contenga caracteres japoneses o espacios. +Si es absolutamente necesario usar una ruta con japonés, es necesario escapar apropiadamente la ruta en el archivo de configuración. diff --git a/es/15.10/install/install.rst b/es/15.10/install/install.rst new file mode 100644 index 000000000..23cea3122 --- /dev/null +++ b/es/15.10/install/install.rst @@ -0,0 +1,247 @@ +==================================== +Selección del Método de Instalación +==================================== + +Esta página describe una descripción general de los métodos de instalación de |Fess|. +Seleccione el método de instalación apropiado según su entorno. + +.. note:: + + |Fess| no incluye un motor de búsqueda. Todos los métodos de instalación + siguientes requieren un servidor OpenSearch independiente. + +Verificación de Requisitos Previos +=================================== + +Antes de comenzar la instalación, verifique los requisitos del sistema. + +Para más detalles, consulte :doc:`prerequisites`. + +Comparación de Métodos de Instalación +====================================== + +|Fess| se puede instalar mediante los siguientes métodos. Seleccione según su entorno y propósito. + +.. list-table:: + :header-rows: 1 + :widths: 15 25 30 30 + + * - Método + - SO Objetivo + - Uso Recomendado + - Documentación Detallada + * - Docker + - Linux, Windows, macOS + - Entorno de desarrollo/evaluación, configuración rápida + - :doc:`install-docker` + * - ZIP + - Linux, macOS + - Entornos que requieren personalización + - :doc:`install-linux` + * - RPM + - RHEL, CentOS, Fedora + - Entorno de producción (basado en RPM) + - :doc:`install-linux` + * - DEB + - Debian, Ubuntu + - Entorno de producción (basado en DEB) + - :doc:`install-linux` + * - ZIP + - Windows + - Desarrollo/producción en entorno Windows + - :doc:`install-windows` + +Características de Cada Método de Instalación +============================================== + +Versión Docker +-------------- + +**Ventajas:** + +- Configuración más rápida posible +- No se requiere gestión de dependencias +- Ideal para construir entornos de desarrollo +- Fácil inicio y detención de contenedores + +**Desventajas:** + +- Se requiere conocimiento de Docker + +**Entorno Recomendado:** Entornos de desarrollo, evaluación, POC y producción + +Para más detalles: :doc:`install-docker` + +Versión de Paquetes Linux (ZIP/RPM/DEB) +------------------------------------------- + +**Ventajas:** + +- Alto rendimiento en entorno nativo +- Gestión como servicio del sistema (RPM/DEB) +- Personalización detallada posible + +**Desventajas:** + +- Se requiere instalación manual de Java y OpenSearch +- Requiere esfuerzo de configuración + +**Entorno Recomendado:** Entorno de producción (se recomienda RPM/DEB para gestión como servicio del sistema), entornos que requieren personalización + +Para más detalles: :doc:`install-linux` + +Versión Windows (ZIP) +--------------------- + +**Ventajas:** + +- Funciona en entorno nativo de Windows +- No se requiere instalador + +**Desventajas:** + +- Se requiere instalación manual de Java y OpenSearch +- Requiere esfuerzo de configuración + +**Entorno Recomendado:** Desarrollo/evaluación en entorno Windows, operación de producción en Windows Server + +Para más detalles: :doc:`install-windows` + +Flujo Básico de Instalación +============================ + +El flujo básico es el mismo para todos los métodos de instalación. + +1. **Verificación de Requisitos del Sistema** + + Consulte :doc:`prerequisites` para verificar que se cumplen los requisitos del sistema. + +2. **Descarga del Software** + + Descargue |Fess| desde el `sitio de descargas `__. + + Para la versión Docker, obtenga el archivo Docker Compose. + +3. **Configuración de OpenSearch** + + Para versiones que no sean Docker, debe configurar OpenSearch por separado. + + - Instalación de OpenSearch 3.9.0 + - Instalación de plugins requeridos + - Edición de archivos de configuración + +4. **Configuración de Fess** + + - Instalación de Fess + - Edición de archivos de configuración (como información de conexión a OpenSearch) + +5. **Inicio y Verificación** + + - Inicio del servicio + - Verificación de funcionamiento accediendo desde el navegador + + Para más detalles, consulte :doc:`run`. + +Componentes Necesarios +======================= + +Para ejecutar |Fess|, se requieren los siguientes componentes. + +Fess Principal +-------------- + +El cuerpo del sistema de búsqueda de texto completo. Proporciona funciones como interfaz Web, rastreador e indexador. + +OpenSearch +---------- + +Se utiliza OpenSearch como motor de búsqueda. + +- **Versión Compatible**: OpenSearch 3.9.0 +- **Plugins Requeridos**: + + - opensearch-analysis-fess + - opensearch-analysis-extension + - opensearch-minhash + - opensearch-configsync + +.. important:: + + Es necesario que coincidan las versiones de OpenSearch y los plugins. + La falta de coincidencia de versiones causa errores de inicio y comportamiento inesperado. + +``bin/fess-setup install opensearch`` prepara OpenSearch con estos plugins en Linux y Windows. Consulte :doc:`install-linux` para más detalles, incluido macOS, donde OpenSearch debe instalarse de otra forma, y :doc:`fess-setup` para ver todos los comandos. + +.. note:: + + Si utiliza un OpenSearch en el que no puede instalar estos plugins, como un servicio gestionado, establezca ``search_engine.type`` en ``vanilla`` (|Fess| 15.10 y posteriores). En ese caso algunas funciones, como la gestión de diccionarios, no están disponibles. Consulte :doc:`../config/search-engine-type`. + +Java (excepto versión Docker) +------------------------------ + +Para las versiones ZIP/RPM/DEB, se requiere Java 21 o posterior. + +- Recomendado: `Eclipse Temurin `__ +- También se puede usar OpenJDK 21 o posterior + +.. note:: + + Para la versión Docker, Java está incluido en la imagen Docker, por lo que no es necesario instalarlo por separado. + +Próximos Pasos +============== + +Verifique los requisitos del sistema y seleccione el método de instalación apropiado. + +1. :doc:`prerequisites` - Verificación de requisitos del sistema +2. Selección del método de instalación: + + - :doc:`install-docker` - Instalación con Docker + - :doc:`install-linux` - Instalación en Linux + - :doc:`install-windows` - Instalación en Windows + +3. :doc:`run` - Inicio de |Fess| y configuración inicial +4. :doc:`security` - Configuración de seguridad (en caso de entorno de producción) + +Preguntas Frecuentes +===================== + +P: ¿Es OpenSearch obligatorio? +------------------------------- + +R: Sí, es obligatorio. |Fess| utiliza OpenSearch como motor de búsqueda. +Para la versión Docker, se configura automáticamente, pero para otros métodos, debe instalarlo manualmente. + +P: ¿Se puede actualizar desde versiones anteriores? +---------------------------------------------------- + +R: Sí, es posible. Para más detalles, consulte :doc:`upgrade`. + +P: ¿Se puede configurar con múltiples servidores? +-------------------------------------------------- + +R: Sí, es posible. Puede ejecutar Fess y OpenSearch en servidores separados. +Además, al configurar OpenSearch en clúster, es posible lograr alta disponibilidad y mejora del rendimiento. + +Descargas +========= + +|Fess| y los componentes relacionados se pueden descargar desde: + +- **Fess**: `Sitio de descargas `__ +- **OpenSearch**: `Download OpenSearch `__ +- **Java (Adoptium)**: `Adoptium `__ +- **Docker**: `Get Docker `__ + +Información de Versión +======================= + +Este documento está dirigido a las siguientes versiones: + +- **Fess**: 15.10.0 +- **OpenSearch**: 3.9.0 +- **Java**: 21 o posterior +- **Docker**: 20.10 o posterior +- **Docker Compose**: 2.0 o posterior + +Para documentación de versiones anteriores, consulte la documentación de cada versión. diff --git a/es/15.10/install/intro.rst b/es/15.10/install/intro.rst new file mode 100644 index 000000000..bf2c95145 --- /dev/null +++ b/es/15.10/install/intro.rst @@ -0,0 +1,70 @@ +============================= +Introducción a la instalación +============================= + +Acerca de este Documento +========================= + +Esta guía de instalación describe los procedimientos de instalación, inicio, actualización y desinstalación de |Fess|. +Seleccione el método de instalación apropiado según su entorno. + +Audiencia Objetivo +================== + +Este documento está dirigido a usuarios responsables de la instalación y desinstalación de |Fess|. + +Antes de Leer +============= + +Este documento presenta el método de instalación de |Fess|. Se requieren los siguientes conocimientos: + +- Conocimientos básicos de administración de servidores +- Operaciones de línea de comandos en Linux o Windows +- Configuración básica de redes y cortafuegos +- Conocimientos básicos de Docker (si utiliza la versión Docker) + +Estructura del Documento +========================= + +Esta guía de instalación está organizada en las siguientes secciones: + +- **Requisitos del Sistema**: Requisitos de hardware y software necesarios para ejecutar |Fess| +- **Instalación**: Procedimientos de instalación por plataforma + + - Selección del método de instalación (descripción general y comparación) + - Instalación para Linux (ZIP/RPM/DEB) + - Instalación para Windows (ZIP) + - Instalación para Docker + +- **Inicio, Detención y Configuración Inicial**: Inicio, detención y configuración inicial del servidor |Fess| +- **Configuración de Seguridad**: Configuraciones de seguridad recomendadas para entornos de producción +- **Actualización**: Procedimientos de actualización desde versiones anteriores a la última versión +- **Desinstalación**: Procedimientos de desinstalación completa de |Fess| +- **Solución de Problemas**: Problemas comunes y soluciones + +Acceso en Línea +=============== + +Para descargas, servicios profesionales, soporte y otra información para desarrolladores, visite: + +- Sitio del Proyecto: `https://fess.codelibs.org/ `__ + +Contacto de Soporte Técnico +============================ + +Para preguntas técnicas o problemas relacionados con este producto, visite: + +- Issues: `https://github.com/codelibs/fess/issues `__ + +Soporte Comercial +----------------- + +Si necesita soporte comercial, como asistencia técnica o mantenimiento de este producto, consulte a `N2SM, Inc. `__ + +Cómo Enviar Comentarios y Sugerencias +====================================== + +Si tiene problemas o mejoras, envíelos desde aquí. + +- Problemas del Producto: `https://github.com/codelibs/fess/issues `__ +- Problemas de Documentación: `https://github.com/codelibs/fess-docs/issues `__ diff --git a/es/15.10/install/prerequisites.rst b/es/15.10/install/prerequisites.rst new file mode 100644 index 000000000..3a6ceaf34 --- /dev/null +++ b/es/15.10/install/prerequisites.rst @@ -0,0 +1,185 @@ +==================== +Requisitos del Sistema +==================== + +Esta página describe los requisitos de hardware y software necesarios para ejecutar |Fess|. + +Requisitos de Hardware +====================== + +Requisitos Mínimos +------------------ + +Los siguientes son los requisitos mínimos para entornos de evaluación y desarrollo: + +- CPU: 2 núcleos o más +- Memoria: 4GB o más +- Espacio en Disco: 10GB o más de espacio libre + +Requisitos Recomendados +----------------------- + +Para entornos de producción, se recomiendan las siguientes especificaciones: + +- CPU: 4 núcleos o más +- Memoria: 8GB o más (escalar según el tamaño del índice) +- Espacio en Disco: + + - Área del Sistema: 20GB o más + - Área de Datos: 3 veces el tamaño del índice o más (incluyendo réplicas) + +- Red: 1Gbps o más + +.. note:: + + Si el tamaño del índice aumenta significativamente o ejecuta rastreos frecuentes, + escale apropiadamente la memoria y el espacio en disco. + +Requisitos de Software +====================== + +Sistema Operativo +----------------- + +|Fess| funciona en los siguientes sistemas operativos: + +**Linux** + +- Red Hat Enterprise Linux 8 o posterior +- CentOS 8 o posterior +- Ubuntu 20.04 LTS o posterior +- Debian 11 o posterior +- Otras distribuciones de Linux (entornos donde se pueda ejecutar Java 21) + +**Windows** + +- Windows Server 2019 o posterior +- Windows 10 o posterior + +**Otros** + +- macOS 11 (Big Sur) o posterior (recomendado solo para entornos de desarrollo; OpenSearch no publica una versión para macOS, instálelo con Homebrew o Docker) +- Entornos donde se pueda ejecutar Docker + +Software Requerido +------------------ + +Dependiendo del método de instalación, se requiere el siguiente software: + +Versión ZIP/RPM/DEB +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- **Java 21**: Se recomienda `Eclipse Temurin `__ + + - OpenJDK 21 o posterior + - Eclipse Temurin 21 o posterior + +- **OpenSearch 3.9.0**: Obligatorio. |Fess| no se inicia con un motor anterior a OpenSearch 3 + + - Versión compatible: OpenSearch 3.9.0 + - Tenga cuidado con la compatibilidad de plugins en otras versiones + +Versión Docker +~~~~~~~~~~~~~~ + +- **Docker**: 20.10 o posterior +- **Docker Compose**: 2.0 o posterior + +Requisitos de Red +================= + +Puertos Necesarios +------------------ + +Los puertos principales utilizados por |Fess| son los siguientes: + +.. list-table:: + :header-rows: 1 + :widths: 15 15 50 + + * - Puerto + - Protocolo + - Uso + * - 8080 + - HTTP + - Interfaz Web de |Fess| (pantalla de búsqueda y administración) + * - 9200 + - HTTP + - API HTTP de OpenSearch (comunicación de |Fess| a OpenSearch) + * - 9300 + - TCP + - Comunicación de transporte de OpenSearch (durante configuración en clúster) + +.. warning:: + + En entornos de producción, se recomienda encarecidamente restringir el acceso directo externo a los puertos 9200 y 9300. + Estos puertos deben usarse solo para comunicación interna entre |Fess| y OpenSearch. + +Configuración del Cortafuegos +------------------------------ + +Si necesita hacer |Fess| accesible desde el exterior, debe abrir el puerto 8080. + +**Linux (en caso de firewalld)** + +:: + + $ sudo firewall-cmd --permanent --add-port=8080/tcp + $ sudo firewall-cmd --reload + +**Linux (en caso de iptables)** + +:: + + $ sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT + $ sudo iptables-save + +Requisitos del Navegador +========================= + +Para las pantallas de administración y búsqueda de |Fess|, se recomiendan los siguientes navegadores: + +- Google Chrome (última versión) +- Mozilla Firefox (última versión) +- Microsoft Edge (última versión) +- Safari (última versión) + +.. note:: + + Internet Explorer no es compatible. + +Lista de Verificación de Requisitos Previos +============================================ + +Antes de la instalación, verifique los siguientes elementos: + +.. list-table:: + :header-rows: 1 + :widths: 50 50 + + * - Elemento de Verificación + - Estado + * - ¿Se cumplen los requisitos de hardware? + - □ + * - ¿Está instalado Java 21? (excepto versión Docker) + - □ + * - ¿Está instalado Docker? (versión Docker) + - □ + * - ¿Están disponibles los puertos necesarios? + - □ + * - ¿Es apropiada la configuración del cortafuegos? + - □ + * - ¿Hay suficiente espacio libre en disco? + - □ + * - ¿Es normal la conexión de red? (si va a rastrear sitios externos) + - □ + +Próximos Pasos +============== + +Después de verificar los requisitos del sistema, proceda con los procedimientos de instalación según su entorno: + +- :doc:`install-linux` - Instalación para Linux (ZIP/RPM/DEB) +- :doc:`install-windows` - Instalación para Windows (ZIP) +- :doc:`install-docker` - Instalación para Docker +- :doc:`install` - Descripción general de los métodos de instalación diff --git a/es/15.10/install/run.rst b/es/15.10/install/run.rst new file mode 100644 index 000000000..31e451279 --- /dev/null +++ b/es/15.10/install/run.rst @@ -0,0 +1,516 @@ +========================================== +Inicio, Detención y Configuración Inicial +========================================== + +Esta página describe los procedimientos de inicio, detención y configuración inicial del servidor |Fess|. + +.. important:: + + Antes de iniciar |Fess|, asegúrese de iniciar OpenSearch. + Si OpenSearch no está en ejecución, |Fess| no funcionará correctamente. + +Métodos de Inicio +================== + +Los procedimientos de inicio varían según el método de instalación. + +En Caso de Versión ZIP +-------------------------- + +Inicio de OpenSearch +~~~~~~~~~~~~~~~~~~~~ + +:: + + $ cd /path/to/opensearch-3.9.0 + $ ./bin/opensearch + +Para iniciar en segundo plano:: + + $ ./bin/opensearch -d + +.. note:: + + ``bin/fess-setup install opensearch`` coloca OpenSearch en ``opensearch/opensearch-3.9.0`` + dentro del directorio de |Fess|. + +.. important:: + + Inicie OpenSearch con un usuario normal. Se niega a ejecutarse como ``root`` y termina con + ``can not run opensearch as root``. Aun así, el inicio rechazado deja archivos como + ``config/opensearch.keystore`` con ``root`` como propietario, y el siguiente inicio con un + usuario normal falla con ``AccessDeniedException``. Devuelva el directorio de OpenSearch a ese + usuario antes de volver a iniciarlo, por ejemplo:: + + $ sudo chown -R /path/to/opensearch-3.9.0 + +Inicio de Fess +~~~~~~~~~~~~~~ + +:: + + $ cd /path/to/fess-15.10.0 + $ ./bin/fess + +Para iniciar en segundo plano:: + + $ ./bin/fess -d + +.. note:: + + El inicio puede tardar varios minutos. + Puede verificar el estado de inicio en los archivos de registro del directorio ``logs/``: ``fess.log`` + contiene los mensajes de |Fess| y ``server_0.log`` los del Tomcat integrado (incluido el mensaje de + finalización del inicio). + +En Caso de Versión ZIP (Windows) +--------------------------------- + +Inicio de OpenSearch +~~~~~~~~~~~~~~~~~~~~ + +1. Abra el directorio de instalación de OpenSearch +2. Haga doble clic en ``opensearch.bat`` dentro de la carpeta ``bin`` + +O desde el Símbolo del sistema:: + + C:\> cd C:\opensearch-3.9.0 + C:\opensearch-3.9.0> bin\opensearch.bat + +Inicio de Fess +~~~~~~~~~~~~~~ + +1. Abra el directorio de instalación de Fess +2. Haga doble clic en ``fess.bat`` dentro de la carpeta ``bin`` + +O desde el Símbolo del sistema:: + + C:\> cd C:\fess-15.10.0 + C:\fess-15.10.0> bin\fess.bat + +En Caso de Versión RPM/DEB (chkconfig) +--------------------------------------- + +Inicio de OpenSearch:: + + $ sudo service opensearch start + +Inicio de Fess:: + + $ sudo service fess start + +Verificación del estado de inicio:: + + $ sudo service fess status + +En Caso de Versión RPM/DEB (systemd) +------------------------------------- + +Inicio de OpenSearch:: + + $ sudo systemctl start opensearch.service + +Inicio de Fess:: + + $ sudo systemctl start fess.service + +Verificación del estado de inicio:: + + $ sudo systemctl status fess.service + +Habilitar inicio automático del servicio:: + + $ sudo systemctl enable opensearch.service + $ sudo systemctl enable fess.service + +En Caso de Versión Docker +-------------------------- + +.. note:: + + ``compose.yaml`` y ``compose-opensearch3.yaml`` no se incluyen con |Fess|. Son proporcionados por el proyecto docker-fess (https://github.com/codelibs/docker-fess); obtenga el repositorio y ejecute los siguientes comandos dentro del directorio ``compose``. + +Iniciar usando Docker Compose:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +Verificación del estado de inicio:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps + +Verificación de registros:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01 + +Verificación del Inicio +======================== + +Verifique que |Fess| se haya iniciado normalmente. + +Verificación de Salud +--------------------- + +Acceda a la siguiente URL desde un navegador o usando el comando curl:: + + http://localhost:8080/ + +Si se ha iniciado normalmente, se mostrará la pantalla de búsqueda de Fess. + +Verificación desde la línea de comandos:: + + $ curl -I http://localhost:8080/ + +Si devuelve ``HTTP/1.1 200 OK``, se ha iniciado normalmente. + +Verificación de Registros +-------------------------- + +Verifique el registro de inicio para confirmar que no hay errores. + +Para versiones ZIP:: + + $ tail -f /path/to/fess-15.10.0/logs/fess.log + +Para versiones RPM/DEB:: + + $ sudo tail -f /var/log/fess/fess.log + +O usando journalctl:: + + $ sudo journalctl -u fess.service -f + +Para versión Docker:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01 + +.. tip:: + + Cuando el inicio se completa correctamente, se escribe un mensaje de finalización de inicio como el siguiente en ``server_0.log``, dentro del directorio de registros (``logs/`` en la versión ZIP, ``/var/log/fess/`` en la versión RPM/DEB). No aparece en la consola ni en ``fess.log``:: + + ...Booting the Tomcat: port=8080 contextPath= + ... + Boot successful: url -> http://localhost:8080 + +Acceso desde el Navegador +========================== + +Acceda a la interfaz Web visitando las siguientes URL. + +Pantalla de Búsqueda +--------------------- + +**URL**: http://localhost:8080/ + +Se mostrará la pantalla de búsqueda de Fess. En el estado inicial, como no se ha realizado ninguna configuración de rastreo, no se mostrarán resultados de búsqueda. + +La pantalla de búsqueda es ``bootstrap``, el tema estático incluido con |Fess|. Para cambiar su aspecto, +instale otro tema desde "Sistema" > "Tema" en la pantalla de administración o con +``bin/fess-setup install theme `` (consulte :doc:`fess-setup`), o copie el tema incluido y +modifique la copia (consulte :ref:`theme-customize-bundled`). + +Pantalla de Administración +--------------------------- + +**URL**: http://localhost:8080/admin + +Cuenta de administrador predeterminada: + +- **Nombre de usuario**: ``admin`` +- **Contraseña**: ``admin`` + +.. warning:: + + **Nota Importante sobre Seguridad** + + Asegúrese de cambiar la contraseña predeterminada. + Especialmente en entornos de producción, se recomienda encarecidamente cambiar la contraseña inmediatamente después del primer inicio de sesión. + +Configuración Inicial +===================== + +Después de iniciar sesión en la pantalla de administración, realice la siguiente configuración inicial. + +Paso 1: Cambio de Contraseña de Administrador +---------------------------------------------- + +1. Inicie sesión en la pantalla de administración (http://localhost:8080/admin) +2. Haga clic en "Usuario" → "Usuario" en el menú izquierdo +3. Haga clic en el usuario ``admin`` +4. Ingrese una nueva contraseña en el campo "Contraseña" +5. Vuelva a ingresar la misma contraseña en el campo "Contraseña (confirmar)" +6. Haga clic en el botón "Actualizar" + +.. important:: + + Se recomienda que la contraseña cumpla con las siguientes condiciones: + + - 8 caracteres o más (la longitud mínima requerida está definida por ``password.min.length``) + - Combinar letras mayúsculas, minúsculas, números y símbolos + - Difícil de adivinar + + De forma predeterminada, solo se exige la longitud mínima (8 caracteres); no se impone ninguna combinación de tipos de caracteres. Los requisitos de tipos de caracteres pueden habilitarse con configuraciones como ``password.require.uppercase``. + +Paso 2: Creación de Configuración de Rastreo +--------------------------------------------- + +Cree una configuración para rastrear sitios o sistemas de archivos que desee buscar. + +1. Haga clic en "Rastreador" → "Web" en el menú izquierdo +2. Haga clic en el botón "Crear nuevo" +3. Ingrese la información necesaria: + + - **Nombre**: Nombre de la configuración de rastreo (ejemplo: Sitio web de la empresa) + - **URL**: URL del objetivo de rastreo (ejemplo: https://www.example.com/). Para especificar varias URL, introduzca una URL por línea + - **Número máximo de accesos**: Número máximo de documentos a rastrear (opcional) + - **Intervalo**: Tiempo de espera entre accesos (milisegundos; valor predeterminado: ``10000``) + + .. note:: + + Los demás elementos (como el agente de usuario, el número de hilos y la profundidad) utilizan sus valores predeterminados cuando se dejan en blanco. + +4. Haga clic en el botón "Crear" + +Paso 3: Ejecución del Rastreo +------------------------------ + +1. Haga clic en "Sistema" → "Programador" en el menú izquierdo +2. Abra el trabajo "Default Crawler" y haga clic en el botón "Iniciar ahora" +3. Espere hasta que se complete el rastreo (puede verificar el progreso en el panel de control) + +Paso 4: Verificación de la Búsqueda +------------------------------------ + +1. Acceda a la pantalla de búsqueda (http://localhost:8080/) +2. Ingrese una palabra clave de búsqueda +3. Verifique que se muestren los resultados de búsqueda + +.. note:: + + El rastreo puede tardar tiempo. + Para sitios grandes, puede tardar desde varias horas hasta varios días. + +Otras Configuraciones Recomendadas +=================================== + +Si va a operar en un entorno de producción, considere también las siguientes configuraciones. + +Configuración Principal mediante Variables de Entorno +------------------------------------------------------ + +La configuración del número de puerto, el tamaño del montón JVM y la URL de conexión a OpenSearch puede modificarse mediante variables de entorno. Edite ``bin/fess.in.sh`` para la edición ZIP, ``/etc/sysconfig/fess`` para la edición RPM y ``/etc/default/fess`` para la edición DEB. Es necesario reiniciar |Fess| tras realizar cambios. + +.. list-table:: + :header-rows: 1 + :widths: 30 25 45 + + * - Variable de entorno + - Valor predeterminado + - Descripción + * - ``FESS_PORT`` + - ``8080`` + - Puerto HTTP en el que |Fess| escucha. + * - ``FESS_HEAP_SIZE`` + - (sin definir) + - Tamaño del montón JVM. Establece el mismo valor para el mínimo y el máximo. Cuando no está definido, se utiliza un mínimo de ``256m`` y un máximo de ``2g`` (la edición ZIP para Windows utiliza un máximo de ``1g``); la edición RPM/DEB utiliza ``512m``. + * - ``SEARCH_ENGINE_HTTP_URL`` + - ``http://localhost:9200`` + - URL del OpenSearch al que conectarse. En la versión ZIP, ``bin/fess.in.sh`` establece este valor de forma predeterminada. Exporte la variable, o edite ``bin/fess.in.sh``, cuando OpenSearch se ejecute en un puerto o host diferente. La edición RPM/DEB lo establece en el archivo de entorno del paquete. + * - ``FESS_LOG_LEVEL`` + - ``warn`` + - Nivel de registro de |Fess|. + * - ``FESS_HEAP_NEWSIZE`` + - (sin definir) + - Tamaño de la generación joven del montón JVM (``-Xmn``), por ejemplo ``256m``. Si no está definido, la JVM lo decide. + * - ``FESS_TEMP_PATH`` + - ``temp`` en el directorio de |Fess| (edición RPM/DEB: ``/var/tmp/fess``) + - Directorio de archivos temporales, incluido el directorio de trabajo del Tomcat integrado. El usuario que ejecuta |Fess| debe poder escribir en él. + * - ``FESS_CONF_PATH`` + - (sin definir) (edición RPM/DEB: ``/etc/fess``) + - Directorio que contiene los archivos de configuración. ``bin/fess`` lo coloca al principio del classpath y se lo pasa a |Fess| como ``-Dfess.conf.path``. De los archivos como ``tomcat_config.properties`` de ``lib/classes``, tiene prioridad el de este directorio. Sin embargo, en la edición ZIP la aplicación web lee primero los archivos de ``app/WEB-INF/classes``, por lo que un ``fess_config.properties`` colocado en este directorio no sobrescribe los valores del ``fess_config.properties`` de ``app/WEB-INF/classes`` (los procesos hijos, como el rastreador, leen este directorio antes que ``WEB-INF/classes``). En la edición ZIP, edite el archivo de ``app/WEB-INF/classes`` para modificar ``fess_config.properties``. La edición RPM/DEB no incluye ``fess_config.properties`` en ``app/WEB-INF/classes`` y utiliza únicamente el de ``/etc/fess``. + * - ``FESS_USE_IPV4`` + - (sin definir) + - Con cualquier valor no vacío, la JVM utiliza solo la pila IPv4 (``-Djava.net.preferIPv4Stack=true``). + * - ``FESS_USE_GC_LOGGING`` + - (sin definir) + - Con cualquier valor no vacío, la JVM escribe su registro del recolector de basura en ``gc-fess.log`` dentro del directorio de registros (hasta 5 archivos de 64 MB). + +.. note:: + + Las variables de entorno que lee el archivo ``bin\fess.in.bat`` de la edición ZIP para Windows son, de las de la tabla, + ``FESS_HEAP_SIZE``, ``FESS_HEAP_NEWSIZE``, ``FESS_USE_IPV4`` y ``FESS_USE_GC_LOGGING``, + además de las siguientes variables que no figuran en la tabla. + + - ``FESS_MIN_MEM``, ``FESS_MAX_MEM``: especifican por separado el tamaño mínimo y máximo del montón (se ignoran si se define ``FESS_HEAP_SIZE``). + - ``FESS_DIRECT_SIZE``: límite de la memoria directa (``-XX:MaxDirectMemorySize``). + - ``FESS_DICTIONARY_PATH``: directorio ``config\dictionary`` de OpenSearch. + - ``FESS_PROXY_HOST``, ``FESS_PROXY_PORT``, ``FESS_NON_PROXY_HOSTS``: configuración del proxy. + - ``FESS_JAVA_OPTS``: ``fess.in.bat`` añade estas opciones de la JVM después de los valores ya configurados. + - ``PLAYWRIGHT_NODEJS_PATH``: ejecutable de Node.js que utiliza el plugin de Playwright. + - ``JAVA_HOME``: obligatoria. + + ``FESS_PORT``, ``FESS_LOG_LEVEL``, ``FESS_TEMP_PATH``, ``FESS_CONF_PATH`` y ``SEARCH_ENGINE_HTTP_URL`` + no se leen. Estos valores se escriben directamente en el archivo, por lo que para modificarlos edite ``bin\fess.in.bat`` directamente. + +Configuración del Servidor de Correo +------------------------------------- + +Para recibir notificaciones de fallos y mensajes similares por correo electrónico, configure el servidor SMTP y la dirección del destinatario de notificaciones. + +1. En ``fess_env_web.properties`` y ``fess_env_crawler.properties``, especifique el host y el puerto del servidor SMTP en ``mail.smtp.server.main.host.and.port`` (predeterminado: ``localhost:25``). Los archivos se encuentran en ``app/WEB-INF/classes/`` en el paquete ZIP y en ``/etc/fess/`` en los paquetes RPM/DEB. El proceso web de |Fess| lee el primero, y el rastreador, que envía el correo de finalización del rastreo, lee el segundo; ``fess_env.properties`` no se utiliza. Es necesario reiniciar |Fess| tras el cambio. +2. En la interfaz de administración, haga clic en "Sistema" → "General" en el menú izquierdo. +3. Ingrese la dirección de correo del destinatario en el campo "Correo de notificación". +4. Haga clic en el botón "Actualizar". +5. Puede verificar que el correo se envía correctamente con el botón "Enviar correo de prueba". + +Configuración de Zona Horaria +------------------------------ + +|Fess| utiliza la zona horaria del servidor (SO / JVM). No existe ninguna configuración para cambiar la zona horaria en la interfaz de administración. Para cambiarla, modifique la configuración de zona horaria del SO, o añada la opción JVM ``-Duser.timezone=Asia/Tokyo`` a ``FESS_JAVA_OPTS`` en ``bin/fess.in.sh`` (en Windows, ``bin\fess.in.bat``). + +Ajuste del Nivel de Registro +----------------------------- + +En producción, puede ajustar el nivel de registro para reducir el uso de disco. + +El nivel de registro global de |Fess| puede modificarse con la variable de entorno ``FESS_LOG_LEVEL`` (predeterminado: ``warn``). Para controlar los registradores individuales con mayor detalle, edite el archivo de configuración ``app/WEB-INF/classes/log4j2.xml``. El rastreo, las sugerencias y la generación de miniaturas se ejecutan como procesos independientes, por lo que configure sus niveles de registro individualmente en ``app/WEB-INF/env/{crawler,suggest,thumbnail}/resources/log4j2.xml``. + +Para más detalles, consulte :doc:`../admin/index`. + +Métodos de Detención +===================== + +En Caso de Versión ZIP +------------------------------ + +Detención de Fess +~~~~~~~~~~~~~~~~~ + +Elimine el proceso:: + + $ ps aux | grep fess + $ kill + +O puede detenerlo con ``Ctrl+C`` desde la consola (si está ejecutándose en primer plano). + +Detención de OpenSearch:: + + $ ps aux | grep opensearch + $ kill + +En Caso de Versión RPM/DEB (chkconfig) +--------------------------------------- + +Detención de Fess:: + + $ sudo service fess stop + +Detención de OpenSearch:: + + $ sudo service opensearch stop + +En Caso de Versión RPM/DEB (systemd) +------------------------------------- + +Detención de Fess:: + + $ sudo systemctl stop fess.service + +Detención de OpenSearch:: + + $ sudo systemctl stop opensearch.service + +En Caso de Versión Docker +-------------------------- + +Detención de contenedores:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop + +Detención y eliminación de contenedores:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +.. warning:: + + Agregue la opción ``-v`` al comando ``down`` si también desea eliminar los volúmenes. + En este caso, tenga cuidado ya que se eliminarán todos los datos. + +Métodos de Reinicio +==================== + +En Caso de Versión ZIP +------------------------------ + +Detenga y luego inicie. + +En Caso de Versión RPM/DEB +--------------------------- + +Con chkconfig:: + + $ sudo service fess restart + +Con systemd:: + + $ sudo systemctl restart fess.service + +En Caso de Versión Docker +-------------------------- + +:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml restart + +Solución de Problemas +====================== + +Si no Inicia +------------ + +1. **Verificar que OpenSearch esté en ejecución** + + :: + + $ curl http://localhost:9200/ + + Si OpenSearch no está en ejecución, primero inicie OpenSearch. + +2. **Verificar conflictos de números de puerto** + + :: + + $ sudo ss -tuln | grep 8080 + + Si net-tools está instalado, ``sudo netstat -tuln | grep 8080`` muestra la misma información. + + Si el puerto 8080 ya está en uso, cambie el número de puerto: + + - Edición ZIP: cambie ``FESS_PORT`` en ``bin/fess.in.sh`` + - Edición ZIP (Windows): edite ``-Dfess.port=8080`` directamente en ``bin\fess.in.bat`` + - Edición RPM: cambie ``FESS_PORT`` en ``/etc/sysconfig/fess`` + - Edición DEB: cambie ``FESS_PORT`` en ``/etc/default/fess`` + +3. **Verificar registros** + + Verifique los mensajes de error para identificar el problema. + +4. **Verificar versión de Java** + + :: + + $ java -version + + Verifique que esté instalado Java 21 o posterior. + +Para solución de problemas detallada, consulte :doc:`troubleshooting`. + +Próximos Pasos +============== + +Una vez que |Fess| se haya iniciado normalmente, consulte la siguiente documentación para comenzar la operación: + +- :doc:`../admin/index` - Detalles sobre configuración de rastreo, configuración de búsqueda y configuración del sistema +- :doc:`security` - Configuración de seguridad para entornos de producción +- :doc:`troubleshooting` - Problemas comunes y soluciones +- :doc:`upgrade` - Procedimientos de actualización de versión +- :doc:`uninstall` - Procedimientos de desinstalación diff --git a/es/15.10/install/security.rst b/es/15.10/install/security.rst new file mode 100644 index 000000000..caf438706 --- /dev/null +++ b/es/15.10/install/security.rst @@ -0,0 +1,353 @@ +========================== +Configuración de Seguridad +========================== + +Esta página describe la configuración de seguridad recomendada para operar |Fess| de manera segura en entornos de producción. + +.. danger:: + + **La Seguridad es Extremadamente Importante** + + En entornos de producción, se recomienda encarecidamente implementar todas las configuraciones de seguridad descritas en esta página. + Descuidar la configuración de seguridad aumenta los riesgos de acceso no autorizado, fugas de datos y compromiso del sistema. + +Configuraciones de Seguridad Obligatorias +========================================== + +Cambio de Contraseña de Administrador +-------------------------------------- + +Asegúrese de cambiar la contraseña de administrador predeterminada (``admin`` / ``admin``). + +**Procedimiento:** + +1. Inicie sesión en la pantalla de administración: http://localhost:8080/admin +2. Haga clic en "Usuario" → "Usuario" +3. Seleccione el usuario ``admin`` +4. Configure una contraseña fuerte +5. Haga clic en el botón "Actualizar" + +.. note:: + + Una vez que haya cambiado la contraseña desde ``admin``, no podrá volver a establecerla en un valor simple como ``admin`` (una lista negra de contraseñas de administrador está configurada mediante ``password.invalid.admin.passwords``). También puede cambiar la contraseña inicial del usuario ``admin`` antes del primer inicio estableciendo ``index.user.initial_password`` en ``fess_config.properties``. + +|Fess| ofrece una función integrada que aplica los requisitos de longitud mínima/máxima y de tipos de caracteres de la contraseña. Configure las siguientes propiedades en ``fess_config.properties`` (los valores predeterminados se indican entre paréntesis): + +- ``password.min.length`` (valor predeterminado: ``8``): Longitud mínima. Se recomienda 12 o más. +- ``password.max.length`` (valor predeterminado: ``100``): Longitud máxima. +- ``password.require.uppercase`` (valor predeterminado: ``false``): Requerir letras mayúsculas. +- ``password.require.lowercase`` (valor predeterminado: ``false``): Requerir letras minúsculas. +- ``password.require.digit`` (valor predeterminado: ``false``): Requerir dígitos. +- ``password.require.special.char`` (valor predeterminado: ``false``): Requerir símbolos. + +.. note:: + + De forma predeterminada, la longitud mínima es ``8`` y todos los requisitos de tipo de carácter están deshabilitados. Para reforzar las contraseñas, configure explícitamente las propiedades anteriores. Tenga en cuenta que |Fess| no cuenta con una función de expiración de contraseñas (cambio periódico forzado); si desea aplicar cambios periódicos de contraseña como regla operativa, hágalo manualmente. + +Habilitación del Plugin de Seguridad de OpenSearch +--------------------------------------------------- + +**Procedimiento:** + +1. Elimine o comente la siguiente línea en ``opensearch.yml``:: + + # plugins.security.disabled: true + +2. Configuración del plugin de seguridad:: + + plugins.security.allow_default_init_securityindex: true + plugins.security.authcz.admin_dn: + - CN=admin,OU=SSL,O=Test,L=Test,C=DE + +3. Configuración de certificados TLS/SSL + +4. Reinicie OpenSearch + +5. Configure la conexión con OpenSearch en el lado de |Fess|. + + Especifique la URL de conexión mediante la variable de entorno ``SEARCH_ENGINE_HTTP_URL`` (edite ``bin/fess.in.sh`` o el archivo de entorno del servicio; el valor predeterminado proviene de ``search_engine.http.url`` en ``fess_config.properties``):: + + SEARCH_ENGINE_HTTP_URL=https://opensearch:9200 + + Especifique las credenciales mediante las siguientes propiedades en ``fess_config.properties`` (no existen las variables de entorno ``SEARCH_ENGINE_USERNAME`` / ``SEARCH_ENGINE_PASSWORD``):: + + search_engine.username=admin + search_engine.password= + +Para más detalles, consulte `OpenSearch Security Plugin `__. + +Habilitación de HTTPS +--------------------- + +La comunicación HTTP no está cifrada, lo que conlleva riesgos de escucha y manipulación. Asegúrese de usar HTTPS en entornos de producción. + +**Método 1: Uso de Proxy Inverso (Recomendado)** + +Coloque Nginx o Apache delante de |Fess| para realizar la terminación HTTPS. + +Ejemplo de configuración de Nginx:: + + server { + listen 443 ssl http2; + server_name your-fess-domain.com; + + ssl_certificate /path/to/cert.pem; + ssl_certificate_key /path/to/key.pem; + + ssl_protocols TLSv1.2 TLSv1.3; + ssl_ciphers HIGH:!aNULL:!MD5; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + } + +**Método 2: Configurar HTTPS en Fess Mismo** + +Agregue lo siguiente a ``tomcat_config.properties``:: + + tomcat.secure=true + tomcat.scheme=https + tomcat.SSLEnabled=true + tomcat.certificateKeystoreFile=[ruta al archivo keystore] + tomcat.certificateKeystorePassword=[contraseña especificada al crear el archivo keystore] + tomcat.certificateKeyAlias=[alias del certificado] + tomcat.sslProtocol=[protocolo SSL (ej. TLS)] + tomcat.enabledProtocols=lista de protocolos habilitados (separados por comas) (ej. TLSv1.2,TLSv1.1,TLSv1) + +Configuraciones de Seguridad Recomendadas +========================================== + +Configuración del Cortafuegos +------------------------------ + +Abra solo los puertos necesarios y cierre los puertos innecesarios. + +**Puertos que Deben Abrirse:** + +- **8080** (o 443 para HTTPS): Interfaz Web de |Fess| (si se requiere acceso externo) +- **22**: SSH (solo para administración, desde direcciones IP confiables únicamente) + +**Puertos que Deben Cerrarse:** + +- **9200, 9300**: OpenSearch (solo comunicación interna, bloquear acceso externo) + +Ejemplo de configuración en Linux (firewalld):: + + $ sudo firewall-cmd --permanent --add-service=http + $ sudo firewall-cmd --permanent --add-service=https + $ sudo firewall-cmd --permanent --remove-service=opensearch # en caso de servicio personalizado + $ sudo firewall-cmd --reload + +Restricción de direcciones IP:: + + $ sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="192.168.1.0/24" port port="8080" protocol="tcp" accept' + +Configuración de Control de Acceso +----------------------------------- + +Considere restringir el acceso a la pantalla de administración a direcciones IP específicas. + +Ejemplo de restricción de acceso con Nginx:: + + location /admin { + allow 192.168.1.0/24; + deny all; + + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + } + +Roles y Control de Acceso +-------------------------- + +|Fess| proporciona dos roles integrados: + +- ``admin``: Rol de administrador que puede realizar todas las operaciones, incluida la pantalla de administración. +- ``guest``: Rol asignado a los usuarios no autenticados (anónimos). + +Cualquier otro rol se puede crear libremente desde la pantalla de administración. En |Fess|, un rol es una etiqueta que solo tiene un nombre y se utiliza principalmente para el control de acceso a los resultados de búsqueda (qué documentos puede ver un usuario). La excepción es un rol llamado ``admin-`` seguido del nombre de una pantalla de administración, como ``admin-user`` o ``admin-scheduler``: permite a un usuario abrir esa pantalla, y la forma ``-view``, como ``admin-user-view``, permite el acceso de solo lectura. + +.. warning:: + + Los roles ``admin-*`` permiten repartir las pantallas de administración de uso diario entre varios operadores, pero no constituyen un límite de privilegios. Un usuario con ``admin-user`` puede asignar cualquier rol existente, incluido el rol de administrador, a cualquier usuario; ``admin-accesstoken`` puede emitir un token de acceso con el permiso ``Radmin-api``, que concede acceso a toda la Admin API; ``admin-scheduler`` puede ejecutar trabajos de script en el servidor, y ``admin-plugin`` puede instalar plugins. Trate cada rol ``admin-*`` como equivalente al rol de administrador (``authentication.admin.roles``, valor predeterminado ``admin``) y concédalo únicamente a operadores de confianza. + +Siguiendo el principio de mínimo privilegio, otorgue el rol de administrador (``admin``) únicamente a los usuarios que realizan tareas administrativas y no lo otorgue a los usuarios de búsqueda en general. + +**Procedimiento:** + +1. Haga clic en "Usuario" → "Rol" en la pantalla de administración +2. Cree los roles necesarios +3. Asigne roles a usuarios en "Usuario" → "Usuario" + +Registro de Auditoría +---------------------- + +El historial de operaciones del sistema, como la autenticación y las operaciones administrativas, se registra de forma predeterminada como registro de auditoría. El registro de auditoría se genera mediante el logger ``fess.log.audit`` definido en ``log4j2.xml``, y su destino de salida predeterminado es ``audit.log``. + +Dado que está habilitado de forma predeterminada, no se requiere configuración adicional. Para personalizar el destino de salida o el nivel de registro, edite la siguiente definición en ``log4j2.xml``:: + + + + + +Actualizaciones de Seguridad Periódicas +---------------------------------------- + +Aplique periódicamente actualizaciones de seguridad de |Fess| y OpenSearch. + +**Procedimiento Recomendado:** + +1. Verifique periódicamente la información de seguridad + + - `Información de lanzamiento de Fess `__ + - `Avisos de seguridad de OpenSearch `__ + +2. Valide actualizaciones en entorno de prueba +3. Aplique actualizaciones en entorno de producción + +Protección de Datos +==================== + +Cifrado de Respaldos +--------------------- + +Los datos de respaldo pueden contener información confidencial. Cifre y almacene los archivos de respaldo. + +Ejemplo de respaldo cifrado:: + + $ tar czf fess-backup.tar.gz /var/lib/opensearch /etc/fess + $ gpg --symmetric --cipher-algo AES256 fess-backup.tar.gz + +Mejores Prácticas de Seguridad +=============================== + +Principio de Mínimo Privilegio +------------------------------- + +- No ejecutar Fess y OpenSearch como usuario root +- Ejecutar con cuenta de usuario dedicada +- Otorgar privilegios mínimos del sistema de archivos + +Aislamiento de Red +------------------ + +- Colocar OpenSearch en red privada +- Usar VPN o red privada para comunicación interna +- Colocar solo la interfaz Web de |Fess| en DMZ + +Auditorías de Seguridad Periódicas +----------------------------------- + +- Revisar periódicamente los registros de acceso +- Detectar patrones de acceso anormales +- Realizar escaneos de vulnerabilidades periódicamente + +Configuración de Encabezados de Seguridad +------------------------------------------ + +Según sea necesario, configure encabezados de seguridad en Nginx o Apache:: + + add_header X-Frame-Options "SAMEORIGIN" always; + add_header X-Content-Type-Options "nosniff" always; + add_header X-XSS-Protection "1; mode=block" always; + add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; + add_header Content-Security-Policy "default-src 'self'" always; + +Lista de Verificación de Seguridad +=================================== + +Antes de implementar en entorno de producción, verifique la siguiente lista de verificación: + +Configuración Básica +-------------------- + +- [ ] Contraseña de administrador cambiada +- [ ] HTTPS habilitado +- [ ] Número de puerto predeterminado cambiado (opcional) + +Seguridad de Red +---------------- + +- [ ] Puertos innecesarios cerrados en el cortafuegos +- [ ] Acceso a pantalla de administración restringido por IP (si es posible) +- [ ] Acceso a OpenSearch restringido solo a red interna + +Control de Acceso +----------------- + +- [ ] Roles y permisos de acceso configurados adecuadamente (otorgar el rol de administrador solo a los usuarios necesarios) +- [ ] Cuentas de usuario innecesarias eliminadas +- [ ] Política de contraseñas configurada + +Monitoreo y Registros +---------------------- + +- [ ] Se ha confirmado que el registro de auditoría está habilitado +- [ ] Período de retención de registros configurado +- [ ] Sistema de monitoreo de registros implementado (si es posible) + +Respaldo y Recuperación +------------------------ + +- [ ] Programación periódica de respaldos configurada +- [ ] Datos de respaldo cifrados +- [ ] Procedimientos de restauración validados + +Gestión de Actualizaciones y Parches +------------------------------------- + +- [ ] Sistema para recibir notificaciones de actualizaciones de seguridad implementado +- [ ] Procedimientos de actualización documentados +- [ ] Sistema para validar actualizaciones en entorno de prueba implementado + +Respuesta a Incidentes de Seguridad +==================================== + +Procedimientos de respuesta en caso de incidente de seguridad: + +1. **Detección de Incidente** + + - Verificar registros + - Detectar patrones de acceso anormales + - Verificar comportamiento anormal del sistema + +2. **Respuesta Inicial** + + - Identificar alcance del impacto + - Prevenir expansión del daño (como detener servicios relevantes) + - Preservar evidencia + +3. **Investigación y Análisis** + + - Análisis detallado de registros + - Identificar ruta de intrusión + - Identificar datos que pueden haber sido filtrados + +4. **Recuperación** + + - Corregir vulnerabilidades + - Recuperar sistema + - Fortalecer monitoreo + +5. **Respuesta Posterior** + + - Crear informe de incidente + - Implementar medidas de prevención de recurrencia + - Informar a partes interesadas + +Información de Referencia +========================== + +- `OpenSearch Security Plugin `__ +- `OWASP Top 10 `__ +- `CIS Benchmarks `__ + +Si tiene preguntas o problemas relacionados con la seguridad, contacte: + +- Issues: https://github.com/codelibs/fess/issues +- Soporte Comercial: https://www.n2sm.net/ diff --git a/es/15.10/install/troubleshooting.rst b/es/15.10/install/troubleshooting.rst new file mode 100644 index 000000000..5b1459215 --- /dev/null +++ b/es/15.10/install/troubleshooting.rst @@ -0,0 +1,596 @@ +======================= +Solución de Problemas +======================= + +Esta página describe los problemas comunes y sus soluciones durante la instalación, inicio y operación de |Fess|. + +Problemas Durante la Instalación +================================= + +Java no Reconocido +------------------ + +**Síntoma:** + +:: + + -bash: java: command not found + +O:: + + 'java' is not recognized as an internal or external command + +**Causa:** + +Java no está instalado, o la variable de entorno PATH no está configurada correctamente. + +**Solución:** + +1. Verificar si Java está instalado:: + + $ which java + $ java -version + +2. Si no está instalado, instale Java 21:: + + # Ubuntu/Debian + $ sudo apt-get update + $ sudo apt-get install openjdk-21-jdk + + # RHEL/CentOS + $ sudo yum install java-21-openjdk + + Los repositorios estándar de Debian 12 no incluyen el paquete ``openjdk-21-jdk``. En Debian 12, instale en su lugar Eclipse Temurin 21 siguiendo las instrucciones para Debian de la `guía de instalación de Adoptium para Linux `__. + +3. Configure la variable de entorno JAVA_HOME:: + + $ export JAVA_HOME=/path/to/java + $ export PATH=$JAVA_HOME/bin:$PATH + + Para configurar permanentemente, agregue a ``~/.bashrc`` o ``/etc/profile``. + +Falla la Instalación de Plugin +------------------------------- + +**Síntoma:** + +:: + + ERROR: Plugin installation failed + +**Causa:** + +- Problema de conexión de red +- La versión del plugin no coincide con la versión de OpenSearch +- Problema de permisos + +**Solución:** + +1. Verificar la versión de OpenSearch:: + + $ /path/to/opensearch/bin/opensearch --version + +2. Hacer coincidir la versión del plugin con la versión de OpenSearch:: + + $ /path/to/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + +3. Verificar permisos:: + + $ sudo /path/to/opensearch/bin/opensearch-plugin install ... + +4. Para instalar a través de proxy:: + + $ export ES_JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080" + $ /path/to/opensearch/bin/opensearch-plugin install ... + +Problemas Durante el Inicio +============================ + +Fess no Inicia +-------------- + +**Síntoma:** + +Aparece un error al ejecutar el comando de inicio de Fess, o termina inmediatamente. + +**Elementos a Verificar:** + +1. **Verificar que OpenSearch esté en ejecución**:: + + $ curl http://localhost:9200/ + + Si es normal, se devuelve una respuesta JSON. + + Cuando ningún OpenSearch responde, |Fess| lo reintenta durante aproximadamente un minuto y + después deja de iniciarse, con el siguiente mensaje en la consola y en ``logs/fess.log``:: + + The search engine at http://localhost:9200 did not become available within 60221ms. Check that OpenSearch is running and reachable. If there is none yet, run bin/fess-setup install opensearch to set one up. + + Inicie OpenSearch o compruebe ``SEARCH_ENGINE_HTTP_URL``. Una instalación ZIP nueva no tiene + OpenSearch hasta que se configura uno con ``bin/fess-setup install opensearch``; consulte + :doc:`install-linux`. + +2. **Verificar conflicto de número de puerto**:: + + $ sudo ss -tuln | grep 8080 + + Si el puerto 8080 ya está en uso, cambie el número de puerto en el archivo de configuración. + +3. **Verificar archivo de registro**:: + + $ tail -f /path/to/fess/logs/fess.log + + Identifique la causa a partir de los mensajes de error. + +4. **Verificar versión de Java**:: + + $ java -version + + Verifique que esté instalado Java 21 o posterior. + +5. **Verificar falta de memoria**:: + + $ free -h + + Si falta memoria, ajuste el tamaño del heap o expanda la memoria del sistema. + +OpenSearch no Inicia +--------------------- + +**Síntoma:** + +:: + + ERROR: bootstrap checks failed + +**Causa:** + +La configuración del sistema no cumple con los requisitos de OpenSearch. + +**Solución:** + +1. **Configuración de vm.max_map_count**:: + + $ sudo sysctl -w vm.max_map_count=262144 + + Para configurar permanentemente:: + + $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf + $ sudo sysctl -p + +2. **Aumentar el límite de descriptores de archivo**:: + + $ sudo vi /etc/security/limits.conf + + Agregue lo siguiente:: + + opensearch - nofile 65535 + opensearch - nproc 4096 + +3. **Configuración de bloqueo de memoria**:: + + $ sudo vi /etc/security/limits.conf + + Agregue lo siguiente:: + + opensearch - memlock unlimited + +4. Reinicie OpenSearch:: + + $ sudo systemctl restart opensearch + +No se Puede Crear el Índice (Ruta de los Archivos de Diccionario) +----------------------------------------------------------------- + +**Síntoma:** + +Al acceder a |Fess| se devuelve HTTP 404, y se registra el siguiente error en ``fess.log``:: + + Failed to create index: index=fess, path=fess_indices/fess.json + ... reason=Resource path must be inside config directory: /var/lib/opensearch/data/config/ja/mapping.txt + +**Causa:** + +OpenSearch 3.8.0 y versiones posteriores rechazan la creación de índices cuando los archivos de diccionario están fuera del directorio de configuración de OpenSearch. +``configsync.config_path`` y ``FESS_DICTIONARY_PATH`` apuntan fuera del directorio de configuración (como ``data/config/``). + +**Solución:** + +1. Cambie ``configsync.config_path`` y ``FESS_DICTIONARY_PATH`` a un directorio dentro del directorio de configuración de OpenSearch. + + - Versión RPM/DEB: ``/etc/opensearch/dictionary/`` + - Versión ZIP: ``/path/to/opensearch-3.9.0/config/dictionary/`` + +2. Si tiene archivos de diccionario existentes, cópielos al nuevo directorio. +3. Reinicie OpenSearch y, a continuación, |Fess|. + +Para más detalles, consulte :doc:`install-linux`. + +Conflicto de Número de Puerto +------------------------------ + +**Síntoma:** + +:: + + Address already in use + +**Solución:** + +1. Verificar puerto en uso:: + + $ sudo ss -tuln | grep 8080 + $ sudo lsof -i :8080 + +2. Detenga el proceso en uso, o cambie el número de puerto de Fess + + Para cambiar el número de puerto, consulte :doc:`Configuración de Puerto y Red <../config/setup-port-network>`. + +Problemas de Conexión +====================== + +Fess no Puede Conectarse a OpenSearch +-------------------------------------- + +**Síntoma:** + +Aparecen errores como los siguientes en el registro:: + + Connection refused + o + No route to host + +**Solución:** + +1. **Verificar que OpenSearch esté en ejecución**:: + + $ curl http://localhost:9200/ + +2. **Verificar URL de conexión** + + Verifique que la URL configurada en ``fess.in.sh`` o ``fess.in.bat`` sea correcta:: + + SEARCH_ENGINE_HTTP_URL=http://localhost:9200 + +3. **Verificar cortafuegos**:: + + $ sudo firewall-cmd --list-all + + Verifique que el puerto 9200 esté abierto. + +4. **Verificar conexión de red** + + Si ejecuta OpenSearch en otro host:: + + $ ping opensearch-host + $ telnet opensearch-host 9200 + +No se Puede Acceder a Fess desde el Navegador +---------------------------------------------- + +**Síntoma:** + +No se puede acceder a http://localhost:8080/ desde el navegador. + +**Solución:** + +1. **Verificar que Fess esté en ejecución**:: + + $ ps aux | grep fess + +2. **Intentar acceso en localhost**:: + + $ curl http://localhost:8080/ + +3. **Verificar cortafuegos**:: + + $ sudo firewall-cmd --list-all + + Verifique que el puerto 8080 esté abierto. + +4. **Al acceder desde otro host** + + Verifique que Fess esté escuchando en algo distinto de localhost:: + + $ ss -tuln | grep 8080 + + Si es ``127.0.0.1:8080``, cambie la configuración para escuchar en ``0.0.0.0:8080`` o una dirección IP específica. + +Problemas de Rendimiento +========================= + +La Búsqueda es Lenta +-------------------- + +**Causa:** + +- El tamaño del índice es grande +- Falta de memoria +- E/S de disco lenta +- Consulta compleja + +**Solución:** + +1. **Aumentar tamaño del heap** + + Inicie |Fess| pasando ``FESS_HEAP_SIZE`` como variable de entorno:: + + $ FESS_HEAP_SIZE=4g bin/fess + + Si lo configura en ``bin/fess.in.sh``, escriba ``FESS_HEAP_SIZE=4g`` **antes** de la línea que establece el valor predeterminado de ``FESS_MIN_MEM`` (la línea que determina el tamaño del montón). Si lo añade al final del archivo, no tendrá efecto, porque el tamaño del montón ya se ha determinado en ese punto. En las ediciones RPM/DEB, configúrelo en ``/etc/sysconfig/fess`` (en la edición DEB, ``/etc/default/fess``). + + Ajuste también el tamaño del heap de OpenSearch:: + + export OPENSEARCH_JAVA_OPTS="-Xms4g -Xmx4g" + +2. **Usar SSD** + + Si la E/S de disco es un cuello de botella, migre a SSD. + +3. **Habilitar caché** + + Habilite la caché de consultas en el archivo de configuración. + +El Rastreo es Lento +------------------- + +**Causa:** + +- Intervalo de rastreo largo +- Respuesta lenta del sitio objetivo +- Número reducido de hilos + +**Solución:** + +1. **Ajustar intervalo de rastreo** + + Acorte el "Intervalo" de la configuración de rastreo en la pantalla de administración (en milisegundos). + + .. warning:: + + Si el intervalo es demasiado corto, pondrá carga en el sitio objetivo. Configure un valor apropiado. + +2. **Aumentar número de hilos** + + Aumente en la pantalla de administración el "Número de hilos" de la configuración de rastreo. El valor predeterminado es 1 para el rastreo Web y 5 para el rastreo del sistema de archivos. + +3. **Ajustar valores de tiempo de espera** + + Para sitios con respuesta lenta, aumente los valores de tiempo de espera. + +Problemas de Datos +=================== + +No se Muestran Resultados de Búsqueda +-------------------------------------- + +**Causa:** + +- No se ha creado el índice +- El rastreo ha fallado +- La consulta de búsqueda es incorrecta + +**Solución:** + +1. **Verificar índice**:: + + $ curl http://localhost:9200/_cat/indices?v + + Verifique que exista el índice de |Fess|. + +2. **Verificar registro de rastreo** + + Descargue el registro de rastreo (``fess-crawler.log``) desde "Información del sistema" → "Archivo de registro" de la pantalla de administración y compruebe si hay errores. + +3. **Volver a ejecutar rastreo** + + Ejecute "Default Crawler" desde "Sistema" → "Programador" en la pantalla de administración. + +4. **Simplificar consulta de búsqueda** + + Primero busque con palabras clave simples para verificar si se devuelven resultados. + +El Índice Está Corrupto +----------------------- + +**Síntoma:** + +Ocurren errores durante la búsqueda, o se devuelven resultados inesperados. + +**Solución:** + +1. **Eliminar y recrear índice** + + .. warning:: + + Si elimina el índice, se perderán todos los datos de búsqueda. Asegúrese de hacer un respaldo. + + :: + + $ curl -X DELETE http://localhost:9200/fess* + +2. **Reiniciar Fess** + + Los índices se crean al iniciar |Fess|. Justo después de eliminarlos, también se ha perdido el índice de información de usuarios, por lo que no es posible iniciar sesión en la pantalla de administración (``/api/v2/health`` sigue devolviendo ``200``). Al reiniciar |Fess|, se vuelven a crear los índices, los trabajos predeterminados y el usuario inicial (``admin``). + +3. **Volver a ejecutar rastreo** + + Ejecute "Default Crawler" desde la pantalla de administración para volver a registrar los documentos objeto de búsqueda. + +Problemas Específicos de Docker +================================ + +Los Contenedores no Inician +---------------------------- + +**Síntoma:** + +Los contenedores no inician con ``docker compose up``. + +**Solución:** + +1. **Verificar registros**:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs + +2. **Verificar falta de memoria** + + Aumente la memoria asignada a Docker (desde la configuración de Docker Desktop). + +3. **Verificar conflicto de puertos**:: + + $ docker ps + + Verifique que otros contenedores no estén usando los puertos 8080 o 9200. + +4. **Verificar archivo Docker Compose** + + Verifique que no haya errores de sintaxis en el archivo YAML:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml config + +Los Contenedores Inician pero no se Puede Acceder a Fess +--------------------------------------------------------- + +**Solución:** + +1. **Verificar estado de contenedores**:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps + +2. **Verificar registros**:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs fess + +3. **Verificar configuración de red**:: + + $ docker network ls + $ docker network inspect + +Problemas Específicos de Windows +================================= + +Problema de Ruta +---------------- + +**Síntoma:** + +Ocurren errores si la ruta contiene espacios o japonés. + +**Solución:** + +Instale en un directorio que no contenga espacios o japonés en la ruta. + +Ejemplo:: + + C:\opensearch (recomendado) + C:\Program Files\opensearch (no recomendado) + +No se Puede Registrar como Servicio +------------------------------------ + +**Solución:** + +Use herramientas de terceros como NSSM para registrar como servicio de Windows. + +Para más detalles, consulte :doc:`install-windows`. + +Otros Problemas +=============== + +Cambio de Nivel de Registro +---------------------------- + +Para ver registros detallados, cambie el nivel de registro a DEBUG. + +Edite ``log4j2.xml``:: + + + +Reinicio de Base de Datos +-------------------------- + +Para restablecer la configuración, elimine el índice de OpenSearch:: + + $ curl -X DELETE 'http://localhost:9200/fess_config.*' + +.. warning:: + + Ejecutar este comando eliminará todos los datos de configuración. + +Contraseña de administrador olvidada +------------------------------------ + +Si olvidó la contraseña del administrador, puede restablecerla actualizando directamente el documento del usuario en el índice ``fess_user.user`` de OpenSearch. La contraseña se guarda en el campo ``password`` como un hash con la forma ``{bcrypt}$2a$...``. El cambio surte efecto sin reiniciar |Fess|. + +1. Cree el hash de la nueva contraseña. |Fess| solo acepta hashes bcrypt que empiecen por ``$2a$``, así que sustituya el ``$2y$`` que genera ``htpasswd`` (incluido en el paquete ``apache2-utils`` o ``httpd-tools``) por ``$2a$``. Sustituya ``NewPassword`` por la nueva contraseña:: + + $ HASH=$(htpasswd -bnBC 10 "" 'NewPassword' | tr -d ':\n' | sed 's/^\$2y/$2a/') + +2. Actualice la contraseña en el documento del usuario administrador. El ID del documento del usuario administrador en el estado inicial es ``YWRtaW4=``:: + + $ curl -X POST 'http://localhost:9200/fess_user.user/_update/YWRtaW4=?refresh=true' \ + -H 'Content-Type: application/json' \ + -d "{\"doc\":{\"password\":\"{bcrypt}${HASH}\"}}" + + Para restablecer la contraseña de otro usuario, busque el ``_id`` con ``curl 'http://localhost:9200/fess_user.user/_search?q=name:USUARIO'`` y utilice ese ID. Si la autenticación está habilitada en OpenSearch, añada las credenciales a curl. + +3. Compruebe que puede iniciar sesión en la pantalla de administración con la nueva contraseña. Si la contraseña queda en el historial de comandos, vuelva a establecerla después de iniciar sesión en [Usuario > Usuario]. + +Información de Soporte +====================== + +Si el problema no se resuelve, utilice los siguientes recursos de soporte: + +Soporte de la Comunidad +------------------------ + +- **Issues**: https://github.com/codelibs/fess/issues + + Al informar problemas, incluya la siguiente información: + + - Versión de Fess + - Versión de OpenSearch + - SO y versión + - Mensaje de error (extracto del registro) + - Pasos para reproducir + +- **Foro**: https://discuss.codelibs.org/ + +Soporte Comercial +----------------- + +Si necesita soporte comercial, consulte a N2SM, Inc.: + +- **Web**: https://www.n2sm.net/ + +Recopilación de Información de Depuración +========================================== + +Al informar problemas, es útil recopilar la siguiente información: + +1. **Información de versión** (``bin/fess -v`` está disponible desde la 15.10):: + + $ /path/to/fess/bin/fess -v + $ /path/to/opensearch/bin/opensearch --version + $ java -version + +2. **Información del sistema**:: + + $ uname -a + $ cat /etc/os-release + $ free -h + $ df -h + +3. **Archivos de registro**:: + + $ tar czf fess-logs.tar.gz /path/to/fess/logs/ + +4. **Archivos de configuración** (después de eliminar información confidencial):: + + $ tar czf fess-config.tar.gz /path/to/fess/app/WEB-INF/conf/ + +5. **Estado de OpenSearch**:: + + $ curl http://localhost:9200/_cluster/health?pretty + $ curl http://localhost:9200/_cat/indices?v diff --git a/es/15.10/install/uninstall.rst b/es/15.10/install/uninstall.rst new file mode 100644 index 000000000..a0ef304c1 --- /dev/null +++ b/es/15.10/install/uninstall.rst @@ -0,0 +1,481 @@ +================================ +Procedimientos de Desinstalación +================================ + +Esta página describe los procedimientos para desinstalar completamente |Fess|. + +.. warning:: + + **Notas Importantes Antes de la Desinstalación** + + - La desinstalación eliminará todos los datos + - Si tiene datos importantes, asegúrese de hacer un respaldo + - Para los procedimientos de respaldo, consulte :doc:`upgrade` + +Preparación Antes de la Desinstalación +====================================== + +Obtención de Respaldo +--------------------- + +Haga un respaldo de los datos necesarios: + +1. **Datos de configuración** + + Descargue desde la pantalla de administración en "Sistema" → "Copia de seguridad". + Con esta operación puede exportar de forma conjunta las distintas configuraciones (incluida la configuración de rastreo) y los registros de búsqueda, entre otros. + +2. **Archivos de configuración personalizados** + + Versión ZIP:: + + $ cp -r /path/to/fess/app/WEB-INF/conf /backup/ + $ cp -r /path/to/fess/app/WEB-INF/classes /backup/ + + Versión RPM/DEB:: + + $ sudo cp -r /etc/fess /backup/ + +.. note:: + + La mayor parte del índice y de la configuración de |Fess| se almacena en OpenSearch. + Para hacer un respaldo de los datos del índice, utilice la función de instantáneas (snapshot) de OpenSearch. + Para conocer el procedimiento detallado, consulte :doc:`upgrade`. + +Detención del Servicio +---------------------- + +Antes de desinstalar, detenga todos los servicios. + +Versión ZIP:: + + $ ps aux | grep -E 'fess|opensearch' + $ kill + $ kill + +Versión RPM/DEB:: + + $ sudo systemctl stop fess.service + $ sudo systemctl stop opensearch.service + +Versión Docker:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +Desinstalación de Versión ZIP +==================================== + +Paso 1: Eliminación de Fess +--------------------------- + +Elimine el directorio de instalación:: + + $ rm -rf /path/to/fess-15.10.0 + +Paso 2: Eliminación de OpenSearch +--------------------------------- + +Elimine el directorio de instalación de OpenSearch:: + + $ rm -rf /path/to/opensearch-3.9.0 + +Paso 3: Eliminación del Directorio de Datos (Opcional) +------------------------------------------------------ + +Los datos del índice de |Fess| se almacenan en OpenSearch. +Por defecto se guardan dentro del directorio de instalación de OpenSearch (por ejemplo, ``opensearch-3.9.0/data``), +pero si ha especificado otra ubicación con ``path.data``, elimine también ese directorio:: + + $ rm -rf /path/to/data + +Paso 4: Eliminación del Directorio de Registros (Opcional) +---------------------------------------------------------- + +Elimine los archivos de registro:: + + $ rm -rf /path/to/fess-15.10.0/logs + $ rm -rf /path/to/opensearch-3.9.0/logs + +Desinstalación de Versión RPM +============================= + +Paso 1: Desinstalación de Fess +------------------------------ + +Desinstale el paquete RPM:: + + $ sudo rpm -e fess + +.. note:: + + Durante la desinstalación del paquete de |Fess|, el script de eliminación del paquete + detiene y deshabilita automáticamente el servicio ``fess`` y elimina el usuario y el grupo ``fess``. + Los pasos siguientes se realizan para confirmar que estos se hayan eliminado correctamente o para + eliminar manualmente los datos y los archivos de configuración. + +Paso 2: Desinstalación de OpenSearch +------------------------------------ + +:: + + $ sudo rpm -e opensearch + +Paso 3: Confirmación de la Deshabilitación del Servicio +------------------------------------------------------- + +Normalmente el servicio se deshabilita al eliminar el paquete, pero, por si acaso, para confirmar o deshabilitar ejecute lo siguiente. + +En caso de systemd:: + + $ sudo systemctl disable fess.service + $ sudo systemctl disable opensearch.service + $ sudo systemctl daemon-reload + +En el caso de un entorno antiguo con SysV init (chkconfig):: + + $ sudo /sbin/chkconfig --del fess + $ sudo /sbin/chkconfig --del opensearch + +Paso 4: Eliminación del Directorio de Datos +------------------------------------------- + +.. warning:: + + Al ejecutar esta operación se eliminarán por completo todos los datos del índice. + +Dado que el directorio de datos no se elimina al desinstalar el paquete, elimínelo manualmente:: + + $ sudo rm -rf /var/lib/fess + $ sudo rm -rf /var/lib/opensearch + +Paso 5: Eliminación de Archivos de Configuración +------------------------------------------------ + +Elimine los archivos de configuración y los archivos de configuración de entorno:: + + $ sudo rm -rf /etc/fess + $ sudo rm -rf /etc/sysconfig/fess + $ sudo rm -rf /etc/opensearch + +.. note:: + + En RPM, los archivos de configuración dentro de ``/etc/fess`` pueden quedar con el nombre ``.rpmsave``. + Para eliminarlos por completo, elimínelos manualmente como se indica arriba. + +Paso 6: Eliminación de Archivos de Registro +------------------------------------------- + +:: + + $ sudo rm -rf /var/log/fess + $ sudo rm -rf /var/log/opensearch + +Paso 7: Eliminación del Directorio Temporal (Opcional) +------------------------------------------------------ + +:: + + $ sudo rm -rf /var/tmp/fess + +Paso 8: Eliminación de Usuario y Grupo (Opcional) +------------------------------------------------- + +Normalmente, el usuario y el grupo ``fess`` se eliminan al eliminar el paquete. +Si permanecen, o si desea eliminar el usuario y el grupo de OpenSearch, ejecute lo siguiente:: + + $ sudo userdel fess + $ sudo groupdel fess + $ sudo userdel opensearch + $ sudo groupdel opensearch + +Desinstalación de Versión DEB +============================= + +Paso 1: Desinstalación de Fess +------------------------------ + +Desinstale el paquete DEB:: + + $ sudo dpkg -r fess + +Para eliminar completamente incluyendo los archivos de configuración y los archivos de configuración de entorno, utilice purge:: + + $ sudo dpkg -P fess + +.. note:: + + Con ``dpkg -r`` (remove), los archivos de configuración (conffile) como ``/etc/default/fess`` permanecen. + Si utiliza ``dpkg -P`` (purge), se eliminan estos archivos de configuración junto con el usuario y el grupo ``fess``. + +Paso 2: Desinstalación de OpenSearch +------------------------------------ + +:: + + $ sudo dpkg -r opensearch + +O bien, para eliminar incluyendo los archivos de configuración:: + + $ sudo dpkg -P opensearch + +Paso 3: Confirmación de la Deshabilitación del Servicio +------------------------------------------------------- + +Normalmente el servicio se deshabilita al eliminar el paquete. Por si acaso, para confirmar o deshabilitar ejecute lo siguiente:: + + $ sudo systemctl disable fess.service + $ sudo systemctl disable opensearch.service + $ sudo systemctl daemon-reload + +Paso 4: Eliminación del Directorio de Datos +------------------------------------------- + +.. warning:: + + Al ejecutar esta operación se eliminarán por completo todos los datos del índice. + +:: + + $ sudo rm -rf /var/lib/fess + $ sudo rm -rf /var/lib/opensearch + +Paso 5: Eliminación de Archivos de Configuración (Si no usó dpkg -P) +-------------------------------------------------------------------- + +:: + + $ sudo rm -rf /etc/fess + $ sudo rm -rf /etc/default/fess + $ sudo rm -rf /etc/opensearch + +Paso 6: Eliminación de Archivos de Registro +------------------------------------------- + +:: + + $ sudo rm -rf /var/log/fess + $ sudo rm -rf /var/log/opensearch + +Paso 7: Eliminación de Usuario y Grupo (Opcional) +------------------------------------------------- + +Si no utilizó ``dpkg -P``, el usuario y el grupo ``fess`` permanecen. +Si desea eliminarlos, ejecute lo siguiente:: + + $ sudo userdel fess + $ sudo groupdel fess + $ sudo userdel opensearch + $ sudo groupdel opensearch + +Desinstalación de Versión Docker +================================ + +Paso 1: Eliminación de Contenedores y Red +----------------------------------------- + +Elimine los contenedores y la red creada por Docker Compose (``search_net``):: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +Paso 2: Eliminación de Volúmenes +-------------------------------- + +.. warning:: + + Al ejecutar esta operación se eliminarán por completo todos los datos. + +Los datos de |Fess| (índices, diccionarios, etc.) se almacenan en los volúmenes de OpenSearch. +Primero, verifique la lista de volúmenes:: + + $ docker volume ls + +Elimine los volúmenes relacionados con OpenSearch:: + + $ docker volume rm _search01_data + $ docker volume rm _search01_dictionary + +.. note:: + + Los nombres de los volúmenes llevan como prefijo el nombre del proyecto de Docker Compose (normalmente el nombre + del directorio en el que se ubicó el archivo Compose). Verifique el nombre real con ``docker volume ls``. + +Para eliminar los contenedores y los volúmenes de una sola vez, añada la opción ``-v`` a ``down``:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down -v + +Paso 3: Eliminación de Imágenes (Opcional) +------------------------------------------ + +Si desea eliminar las imágenes Docker para liberar espacio en disco:: + + $ docker images | grep fess + $ docker rmi ghcr.io/codelibs/fess:15.10.0 + $ docker rmi ghcr.io/codelibs/fess-opensearch:3.9.0 + +Paso 4: Eliminación de Archivos Compose +--------------------------------------- + +:: + + $ rm compose.yaml compose-opensearch3.yaml + +Verificación de la Desinstalación +================================= + +Verifique que se hayan eliminado todos los componentes. + +Verificación de Procesos +------------------------ + +:: + + $ ps aux | grep fess + $ ps aux | grep opensearch + +Si no se muestra nada, los procesos están detenidos. + +Verificación de Puertos +----------------------- + +:: + + $ sudo ss -tuln | grep 8080 + $ sudo ss -tuln | grep 9200 + +Verifique que los puertos no estén en uso. + +Verificación de Archivos +------------------------ + +Versión ZIP:: + + $ ls /path/to/fess-15.10.0 # Verifique que el directorio no exista + +Versión RPM/DEB:: + + $ ls /var/lib/fess # Verifique que el directorio no exista + $ ls /etc/fess # Verifique que el directorio no exista + +Versión Docker:: + + $ docker ps -a | grep -E 'fess01|search01' # Verifique que no existan contenedores + $ docker volume ls | grep search01 # Verifique que no existan volúmenes + +Verificación de Paquetes +------------------------ + +Versión RPM:: + + $ rpm -qa | grep fess + $ rpm -qa | grep opensearch + +Versión DEB:: + + $ dpkg -l | grep fess + $ dpkg -l | grep opensearch + +Si no se muestra nada, los paquetes están eliminados. + +Desinstalación Parcial +====================== + +Eliminar Solo Fess y Mantener OpenSearch +---------------------------------------- + +Si OpenSearch se utiliza también en otras aplicaciones, puede eliminar solo Fess. + +1. Detenga Fess +2. Elimine el paquete o el directorio de Fess +3. Elimine el directorio de datos de Fess (``/var/lib/fess``, etc.) +4. Elimine los índices de |Fess| creados dentro de OpenSearch + + Los nombres de los índices de |Fess| comienzan por ``fess`` (``fess.*``, ``fess_config.*``, ``fess_user.*``, ``fess_log.*``, ``fess_crawler.*``, ``fess_suggest*``, etc.). Puede eliminarlos todos a la vez con el siguiente comando. + + :: + + $ curl -X DELETE 'http://localhost:9200/fess*' + + Antes de eliminarlos, compruebe con ``curl 'http://localhost:9200/_cat/indices?v'`` que no existan índices de otras aplicaciones cuyo nombre comience por ``fess``. El índice ``configsync``, que sincroniza los diccionarios, también se puede eliminar si no lo utiliza ninguna otra aplicación. + +5. No elimine OpenSearch + +Eliminar Solo OpenSearch y Mantener Fess +---------------------------------------- + +.. warning:: + + Si elimina OpenSearch, Fess dejará de funcionar. + Cambie la configuración para conectarse a otro clúster de OpenSearch. + +1. Detenga OpenSearch +2. Elimine el paquete o el directorio de OpenSearch +3. Elimine el directorio de datos de OpenSearch (``/var/lib/opensearch``, etc.) +4. Actualice la configuración de Fess para especificar otro clúster de OpenSearch + +Solución de Problemas +===================== + +No se Puede Eliminar el Paquete +------------------------------- + +**Síntoma:** + +Se produce un error con ``rpm -e`` o ``dpkg -r``. + +**Solución:** + +1. Verifique que el servicio esté detenido:: + + $ sudo systemctl stop fess.service + +2. Verifique las dependencias:: + + $ rpm -qa | grep fess + $ dpkg -l | grep fess + +3. Eliminación forzada (último recurso):: + + $ sudo rpm -e --nodeps fess + $ sudo dpkg -r --force-all fess + +No se Puede Eliminar el Directorio +---------------------------------- + +**Síntoma:** + +No se puede eliminar el directorio con ``rm -rf``. + +**Solución:** + +1. Verifique los permisos:: + + $ ls -ld /path/to/directory + +2. Elimine con sudo:: + + $ sudo rm -rf /path/to/directory + +3. Verifique que ningún proceso esté usando archivos:: + + $ sudo lsof | grep /path/to/directory + +Preparación para la Reinstalación +================================= + +Si va a reinstalar después de desinstalar, verifique lo siguiente: + +1. Que todos los procesos estén detenidos +2. Que se hayan eliminado todos los archivos y directorios +3. Que los puertos 8080 y 9200 no estén en uso +4. Que no queden archivos de configuración anteriores + +Para los procedimientos de reinstalación, consulte :doc:`install`. + +Próximos Pasos +============== + +Una vez completada la desinstalación: + +- Para instalar una nueva versión, consulte :doc:`install` +- Para migrar datos, consulte :doc:`upgrade` +- Para considerar soluciones de búsqueda alternativas, consulte el sitio oficial de Fess diff --git a/es/15.10/install/upgrade.rst b/es/15.10/install/upgrade.rst new file mode 100644 index 000000000..cac3fde6c --- /dev/null +++ b/es/15.10/install/upgrade.rst @@ -0,0 +1,1709 @@ +================================ +Procedimientos de Actualización +================================ + +Esta página describe los procedimientos para actualizar |Fess| de versiones anteriores a la versión más reciente. + +.. warning:: + + **Notas Importantes Antes de la Actualización** + + - Asegúrese de hacer un respaldo antes de la actualización + - Se recomienda encarecidamente validar la actualización en un entorno de prueba con anticipación + - El servicio se detendrá durante la actualización, por lo que configure un tiempo de mantenimiento apropiado + - Dependiendo de la versión, el formato del archivo de configuración puede haber cambiado + +Versiones Compatibles +===================== + +Estos procedimientos de actualización son compatibles con actualizaciones entre las siguientes versiones: + +- Fess 14.x → Fess 15.10 +- Fess 15.x → Fess 15.10 + +.. important:: + + |Fess| 14.x es compatible con la serie OpenSearch 2.x, mientras que |Fess| 15.10 es compatible + con OpenSearch 3.9.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. + Para más detalles, verifique las notas de lanzamiento. + +Preparación Antes de la Actualización +====================================== + +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 `__ +- :doc:`prerequisites` - Entorno de ejecución de |Fess| 15.10 (versiones de Java y OpenSearch) + +Planificación del Tiempo de Inactividad +---------------------------------------- + +La actualización requiere la detención del sistema. Planifique el tiempo de inactividad considerando lo siguiente: + +- Tiempo de respaldo: 10 minutos ~ varias horas (según la cantidad de datos) +- Tiempo de actualización: 10 ~ 30 minutos +- Tiempo de verificación de funcionamiento: 30 minutos ~ 1 hora +- Tiempo de reserva: 30 minutos + +**Tiempo de mantenimiento recomendado**: Total 2 ~ 4 horas + +Paso 1: Respaldo de Datos +========================== + +Antes de la actualización, haga un respaldo de todos los datos. + +Respaldo de Datos de Configuración +------------------------------------ + +1. **Respaldo desde la pantalla de administració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 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`` - Í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 + (25 índices en total hasta 15.8; 15.10 añade el índice ``tag_type``, que contiene las etiquetas de + usuario, hasta 26) + - ``fess_user.bulk`` - Usuarios, roles y grupos + - ``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``. Sin embargo, si el origen es 15.10 o posterior y utiliza etiquetas de usuario, descargue también ``fess_config.bulk``: el índice ``tag_type``, que contiene las etiquetas de usuario, no está incluido en ``fess_basic_config.bulk`` (consulte :doc:`../admin/tagtype-guide`). + + .. 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``; 15.10 ofrece también ``chat_log.ndjson``) también + pueden descargarse desde la misma página. + 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** + + Versión ZIP:: + + $ 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:: + + $ 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 ZIP, la configuración + equivalente se encuentra en ``bin/fess.in.sh``. + +3. **Archivos de configuración personalizados** + + Si tiene archivos de configuración personalizados, también haga un respaldo de ellos:: + + $ cp /path/to/fess/app/WEB-INF/classes/log4j2.xml /backup/ + $ cp /path/to/fess/lib/classes/tomcat_config.properties /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 +----------------------------- + +Haga un respaldo de los datos de índice de OpenSearch. + +Método 1: Usar Función de Instantánea (Recomendado) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use la función de instantánea de OpenSearch para hacer un respaldo del índice. + +.. note:: + + Para registrar un repositorio del sistema de archivos (``fs``), es necesario especificar previamente el + directorio de destino del respaldo en ``path.repo`` del archivo ``opensearch.yml`` de OpenSearch + y reiniciar OpenSearch. + +1. Configuración del repositorio:: + + $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup" -H 'Content-Type: application/json' -d' + { + "type": "fs", + "settings": { + "location": "/backup/opensearch/snapshots" + } + }' + +2. Creación de instantánea:: + + $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup/snapshot_1?wait_for_completion=true" + +3. Verificación de instantánea:: + + $ curl -X GET "http://localhost:9200/_snapshot/fess_backup/snapshot_1" + +Método 2: Respaldo de Todo el Directorio +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Después de detener OpenSearch, haga un respaldo del directorio de datos. + +:: + + $ sudo systemctl stop opensearch + $ sudo tar czf /backup/opensearch-data-$(date +%Y%m%d).tar.gz /var/lib/opensearch/data + $ sudo systemctl start opensearch + +Respaldo de Versión Docker +--------------------------- + +Los datos de OpenSearch se almacenan en volúmenes Docker. En ``compose-opensearch3.yaml`` se definen +dos volúmenes: ``search01_data`` para los datos del índice y ``search01_dictionary`` para los archivos +de diccionario. + +.. note:: + + El nombre real del volumen lleva como prefijo el nombre del proyecto Compose (por defecto, el nombre + del directorio donde se encuentra el archivo Compose). Para obtener el nombre exacto, ejecute:: + + $ docker volume ls + +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 + $ 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. + +La versión 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 $(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 + $ sudo systemctl stop opensearch.service + +Versión Docker:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +.. warning:: + + Asegúrese de que |Fess| se haya detenido antes de empezar el Paso 3, y no sustituya el paquete ni + los archivos de un |Fess| que siga en ejecución. Después de sustituir el paquete DEB de un |Fess| + 15.8 en ejecución por el de 15.10, la pantalla de búsqueda respondió ``404`` hasta que se reinició + |Fess|. Para las versiones de los paquetes, compruébelo con ``systemctl status fess.service``. + +Paso 3: Instalación de la Nueva Versión +========================================= + +Los procedimientos varían según el método de instalación. + +Versión ZIP +------------------- + +1. Descargue y extraiga la nueva versión:: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.zip + $ unzip fess-15.10.0.zip + + .. note:: + + La versión archivo de |Fess| se distribuye únicamente en formato ZIP + (no se ofrece ``fess-15.10.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.10.0/app/WEB-INF/conf/ + $ cp /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.10.0/app/WEB-INF/classes/ + $ cp /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.10.0/bin/ + + .. warning:: + + Si se copian enteros, ``fess_config.properties`` y ``fess.in.sh`` conservan sus valores + antiguos, incluidos aquellos cuyo valor predeterminado cambió en 15.10: por ejemplo, los + trabajos creados después usan Groovy de forma predeterminada. Antes de ejecutar las dos + últimas órdenes, compare cada archivo con el de ``fess-15.10.0`` y traslade solo los valores + que haya cambiado usted. Consulte :ref:`upgrade-159-carried-over-config` para saber qué + revisar. + +3. Si tiene personalizaciones, copie también lo siguiente:: + + # Configuración de Tomcat (aquí se conserva el ajuste SAML tomcat.sameSiteCookies=none) + $ cp /path/to/old-fess/lib/classes/tomcat_config.properties /path/to/fess-15.10.0/lib/classes/ + # Plugins instalados + $ cp -r /path/to/old-fess/app/WEB-INF/plugin/. /path/to/fess-15.10.0/app/WEB-INF/plugin/ + # Temas estáticos que haya subido usted (un directorio por tema; nunca bootstrap) + $ cp -r /path/to/old-fess/app/themes/ /path/to/fess-15.10.0/app/themes/ + + .. warning:: + + Sin el ``tomcat_config.properties`` de la instalación antigua, ``tomcat.sameSiteCookies`` + vuelve en silencio al valor predeterminado ``lax`` y el inicio de sesión SAML deja de + funcionar (consulte :ref:`upgrade-159-saml`). El archivo incluido es el mismo en 15.8.0 y en + 15.10, por lo que se puede copiar tal cual. + + .. warning:: + + No copie ``log4j2.xml`` sobre el archivo de 15.10. El archivo de 15.10 mantiene el logger + ``RequestLoggingFilter`` en ``warn``, y un archivo copiado de 15.8 elimina ese ajuste: con el + nivel de registro en DEBUG, las cabeceras de la petición (incluida ``Authorization``) y los + parámetros de la petición (incluida la contraseña escrita en el formulario de inicio de sesión) + se escriben entonces en el registro. Compare los dos archivos con ``diff`` y vuelva a aplicar + sobre el archivo de 15.10 solo los cambios que haya hecho usted. + + .. warning:: + + No copie el directorio ``app/themes/`` completo. También contiene ``bootstrap``, el tema + incluido con |Fess|, y copiarlo sobre el de 15.10 sustituye la pantalla de búsqueda de 15.10 + por la versión 15.8 del tema. Copie solo los directorios de los temas que haya creado usted. + Para un tema publicado por el proyecto |Fess|, instale en su lugar la versión para 15.10 con + ``bin/fess-setup install theme `` (consulte :doc:`fess-setup`). + + .. warning:: + + No copie los JSP editados desde "Diseño" en la pantalla de administración + (``app/WEB-INF/view/``). La pantalla de búsqueda de 15.10 es un tema estático y ya no utiliza + esos JSP; consulte :ref:`upgrade-159-static-theme` para saber dónde van ahora esos cambios. + + .. note:: + + Los plugins copiados de ``app/WEB-INF/plugin/`` se compilaron para la versión antigua. + Después de copiarlos, ejecute ``bin/fess-setup upgrade plugins`` en ``fess-15.10.0`` para + sustituir cada uno por la versión compilada para 15.10; consulte + :ref:`upgrade-plugin-versions`. + +4. Verifique las diferencias de configuración y ajuste según sea necesario + +Versión RPM/DEB +--------------- + +Instale el paquete de la nueva versión:: + + # RPM + $ sudo rpm -Uvh fess-15.10.0.rpm + + # DEB + $ sudo dpkg -i fess-15.10.0.deb + +.. note:: + + 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. Un + ``/etc/fess/fess_config.properties`` que haya modificado conserva sus valores antiguos en 15.10, + igual que un archivo copiado en el procedimiento ZIP; consulte + :ref:`upgrade-159-carried-over-config`. + +.. warning:: + + En la versión DEB, los archivos de ``/etc/fess`` (como ``fess_config.properties`` y + ``tomcat_config.properties``) están registrados como conffile, igual que ``/etc/default/fess``, + ``/etc/init.d/fess`` y ``/usr/lib/systemd/system/fess.service``. En la primera actualización desde + 15.8, ``dpkg`` los trata de la siguiente manera: + + - Un archivo que nunca editó se sustituye por el de 15.10 sin preguntar. + - Si editó un archivo, ``dpkg`` pregunta. Si conserva su archivo (la respuesta predeterminada, o + ``--force-confold``), el archivo de 15.10 se coloca junto a él como ``.dpkg-dist``. + Si instala el archivo nuevo (``Y`` o ``--force-confnew``), su archivo se guarda como + ``.dpkg-old``. + - ``dpkg -i`` y ``apt-get install -y`` se detienen en la primera pregunta cuando nadie puede + responderla. Para una actualización desatendida, indique ``--force-confold`` (``--force-confdef`` + también evita las preguntas), por ejemplo ``sudo dpkg --force-confold -i fess-15.10.0.deb`` o + ``sudo apt-get install -y -o Dpkg::Options::=--force-confold ./fess-15.10.0.deb``. + + Respalde ``/etc/fess`` antes (Paso 1) en cualquier caso. Un archivo que conserve sigue teniendo sus + valores de 15.8, así que compárelo con el archivo ``.dpkg-dist`` en lugar de usarlo tal cual + (consulte :ref:`upgrade-159-carried-over-config`). 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 +-------------- + +1. Obtenga el archivo Compose de la nueva versión:: + + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose.yaml + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose-opensearch3.yaml + +2. Obtenga la nueva imagen:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull + +.. _upgrade-opensearch: + +Paso 4: Actualización de OpenSearch +==================================== + +|Fess| 15.10 es compatible con OpenSearch 3.9.0. Si el OpenSearch al que se conecta es una versión +anterior, actualícelo siguiendo estos procedimientos. + +.. note:: + + Este procedimiento corresponde a los casos en que OpenSearch se gestiona manualmente en las versiones + 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.10 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. + + Una instantánea tomada con OpenSearch 3.9.0 no se puede restaurar en OpenSearch 3.8.0 o anterior. + Conserve la instantánea tomada antes de la actualización por si necesita revertirla. + +1. Instale la nueva versión de OpenSearch + +2. Reinstale los plugins:: + + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + + .. note:: + + La versión de estos plugins debe coincidir con la versión de OpenSearch que se utiliza. + |Fess| 15.10 es compatible con OpenSearch 3.9.0. Si las versiones no coinciden, + la instalación de los plugins fallará. + + Los cuatro plugins de |Fess| se publican en maven.codelibs.org, por lo que se instalan + mediante su URL. La forma ``groupId:artifactId:version`` de ``opensearch-plugin install`` solo + busca en Maven Central. + +3. Mueva el directorio de diccionarios dentro del directorio de configuración de OpenSearch + + OpenSearch 3.8.0 y versiones posteriores rechazan la creación de índices cuando los archivos de diccionario están fuera del directorio de configuración de OpenSearch. + Si, siguiendo las instrucciones anteriores, ``configsync.config_path`` apunta fuera del directorio de configuración, como ``/var/lib/opensearch/data/config/`` (``/path/to/opensearch/data/config/`` en la versión ZIP), + |Fess| no puede crear sus índices y no se inicia. + En la versión RPM/DEB, copie los archivos de diccionario a ``/etc/opensearch/dictionary/`` de la siguiente manera:: + + $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary + $ sudo cp -a /var/lib/opensearch/data/config/. /etc/opensearch/dictionary/ + $ sudo chown -R opensearch:opensearch /etc/opensearch/dictionary + + A continuación, cambie tanto ``configsync.config_path`` en ``/etc/opensearch/opensearch.yml`` como ``FESS_DICTIONARY_PATH`` de |Fess| (``/etc/sysconfig/fess`` en la versión RPM, ``/etc/default/fess`` en la versión DEB) a ``/etc/opensearch/dictionary/``. + En la versión ZIP, utilice ``config/dictionary/`` de OpenSearch. Para más detalles, consulte :doc:`install-linux`. + +4. Inicie OpenSearch:: + + $ sudo systemctl start opensearch.service + +Paso 5: Inicio de la Nueva Versión +==================================== + +Versión ZIP:: + + $ cd /path/to/fess-15.10.0 + $ ./bin/fess -d -p /path/to/fess-15.10.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.10.0/fess.pid)``. + +Versión RPM/DEB:: + + $ sudo systemctl start opensearch.service + $ sudo systemctl start fess.service + +Versión Docker:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +Paso 6: Verificación de Funcionamiento +======================================== + +1. **Verificación de registros** + + Verifique que no haya errores. + + Versión 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. + +3. **Inicio de sesión en la pantalla de administración** + + Acceda a http://localhost:8080/admin e inicie sesión con la cuenta de administrador. + +4. **Verificación de la versión** + + En la pantalla de administración, haga clic en "Información del sistema" → "Información de configuración" + y verifique que ``fess.version`` que se muestra en "Propiedades del sistema" corresponda a la nueva versión. + +5. **Verificación de funcionamiento de búsqueda** + + Ejecute una búsqueda en la pantalla de búsqueda y verifique que se devuelvan resultados normalmente. + +Paso 7: Recreación del Índice (Recomendado) +============================================= + +Para actualizaciones de versión principal, se recomienda recrear el índice. + +.. note:: + + Los pasos siguientes vuelven a ejecutar el rastreo; no actualizan el mapeo del índice + (definiciones de campos). Si necesita una reindexación que actualice el mapeo — por ejemplo, + para habilitar recién la búsqueda por vector de chunks (búsqueda semántica) —, ejecute por + separado la "Reindexación" en "Información del sistema" → "Mantenimiento" en la interfaz de + administración. Consulte :ref:`semantic-search-migration` (:doc:`../config/search-semantic`) + para más detalles. + + Si sigue usando un índice de documentos creado con 15.8 o anterior, consulte también + :ref:`upgrade-reindex-new-fields`. + +.. warning:: + + OpenSearch 3.9.0 rechaza entradas de diccionario que 15.8 aceptaba, como la misma entrada de + ``mapping`` guardada dos veces o un token de ``kuromoji`` que contiene un espacio. Con una + entrada así, la "Reindexación" no crea el nuevo índice de documentos: ``fess.log`` solo dice + ``Failed to create index`` y el índice antiguo sigue atendiendo las búsquedas. Descargue el + diccionario en "Sistema" → "Diccionario", elimine las líneas duplicadas o no válidas, cárguelo de + nuevo y ejecute otra vez la "Reindexación". Consulte :ref:`upgrade-159-api-requests` para ver las + entradas que 15.10 ya no guarda. + +1. Verifique los programas de rastreo existentes +2. Ejecute "Default Crawler" desde "Sistema" → "Programador" +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. + +Actualización de 15.8 a 15.10 +============================ + +Si actualiza desde 15.8, los cambios siguientes no son retrocompatibles. Si actualiza desde 15.7 o +anterior, también se aplican a usted: lea todas las secciones desde "Eliminación del OpenSearch +integrado" hasta "Aplicar los nuevos campos y la normalización de kana a un índice de documentos +existente" (el OpenSearch integrado, el motor de scripting, los plugins de S3 y SSO, el trabajo +Index Exporter, etc.) y, después, "Migración Específica de 15.10" al final de esta página. + +Eliminación del OpenSearch integrado +------------------------------------ + +Hasta 15.8, iniciar ``bin/fess`` sin definir ``SEARCH_ENGINE_HTTP_URL`` hacía que |Fess| +ejecutara un nodo OpenSearch dentro de su propia JVM. Esa configuración desaparece en 15.10: el +motor de búsqueda es siempre un servidor independiente. + +``bin/fess.in.sh`` ahora establece ``SEARCH_ENGINE_HTTP_URL=http://localhost:9200`` de forma +predeterminada. |Fess| no se inicia si no hay ningún OpenSearch accesible. +``bin/fess-setup install opensearch`` instala uno (solo Linux y Windows; OpenSearch no publica +una versión para macOS, así que utilice Homebrew o Docker en ese caso). + +|Fess| también necesita que ``FESS_DICTIONARY_PATH`` coincida con ``configsync.config_path`` en el +``opensearch.yml`` de ese OpenSearch; sin ello, |Fess| no puede crear sus índices. El +``bin/fess.in.sh`` de 15.10 (``bin\fess.in.bat`` en Windows) la establece por sí mismo cuando +``opensearch/`` dentro del directorio de |Fess| contiene exactamente un OpenSearch instalado por +``bin/fess-setup install opensearch``. Para cualquier otro OpenSearch, establézcala tal como se +describe en :doc:`install-linux` o :doc:`install-windows`. + +También se han eliminado: + +- el directorio ``es/`` (``es/modules``, ``es/plugins`` y ``es/data``) +- ``-Dfess.es.dir`` y ``SEARCH_ENGINE_HOME`` +- ``bin/module.xml`` y ``bin/plugin.xml`` +- los valores de reserva de las antiguas claves de configuración ``elasticsearch.*`` + +Un motor anterior a OpenSearch 3 también detiene el inicio, mientras que 15.8 registraba un error +y continuaba. Esas versiones no implementan la ordenación ``_shard_doc`` de la que dependen todas +las operaciones que recorren el conjunto completo de resultados, y por HTTP una petición así se +queda colgada en lugar de fallar. + +.. warning:: + + Los datos de índice de una instalación integrada no se pueden conservar. Construya un nuevo + servidor OpenSearch externo, traslade la configuración con la página de copia de seguridad de + la administración y vuelva a rastrear. La copia de seguridad incluye la configuración de + rastreo, los usuarios y los registros; **no** contiene los documentos rastreados. + +.. note:: + + Dos cosas que debe saber al restaurar una copia de seguridad de 15.8 en el nuevo servidor 15.10: + + - Los trabajos solo se restauran si son más recientes que los del servidor. Por eso los trabajos + incluidos que nunca editó en 15.8 conservan su versión JavaScript de 15.10. Un trabajo que editó + o creó en 15.8 vuelve con el motor de scripts con el que se guardó, que es ``groovy`` en un + trabajo incluido, y sin el plugin ``fess-script-groovy`` falla con ``groovy is not found``. + Instale el plugin o pase esos trabajos a JavaScript; ambas opciones se describen en + :ref:`upgrade-159-script-engine`. + - Las contraseñas y los secretos almacenados en la autenticación web, la configuración de rastreo + y la configuración de almacenes de datos están cifrados con ``app.cipher.key``. Defina el valor + de la instalación antigua en el ``fess_config.properties`` del nuevo servidor, como se describe + en :ref:`upgrade-159-carried-over-config`; de lo contrario, no se pueden descifrar. + +El rastreador de Playwright pasa a un plugin +-------------------------------------------- + +El rastreador de Playwright, y los ejecutables de Node.js que utiliza, ya no forman parte de la +distribución. En ``fess-15.8.0.zip`` (457,1 MiB), el paquete de controladores de Playwright que +contenía los ejecutables de Node.js ocupaba 204,3 MiB. + +Si alguna configuración de rastreo indica el cliente de Playwright, por ejemplo con +``client.crawlerClients=playwright:http://.*`` en sus parámetros de configuración, instale tanto +el plugin como Node.js. El plugin también puede instalarse desde la página +**Sistema > Plugin** de la pantalla de administración. ``bin/fess.in.sh`` detecta Node.js y +establece ``PLAYWRIGHT_NODEJS_PATH``. + +:: + + $ bin/fess-setup install plugin fess-crawler-playwright + $ bin/fess-setup install nodejs + +Sin el plugin, esa configuración se sigue rastreando, pero con el cliente HTTP normal, de modo +que el texto que solo genera JavaScript no se indexa. El trabajo de rastreo termina igualmente +con éxito y no se registra ninguna URL con errores. En cada rastreo, ``fess-crawler.log`` registra +una advertencia por cada configuración de rastreo, con el nombre del plugin y las dos órdenes +anteriores. + +El plugin ``fess-thumbnail-playwright``, que genera miniaturas de páginas HTML con Playwright, +también se ejecuta sobre Node.js. Si lo utiliza, instale Node.js con +``bin/fess-setup install nodejs``; la misma instalación sirve a ambos plugins. + +Si no utiliza ni el rastreador de Playwright ni el plugin ``fess-thumbnail-playwright``, no hay +nada que hacer. + +Google Cloud Storage pasa a un plugin +------------------------------------- + +El SDK de Google Cloud Storage ya no forma parte de la distribución, por lo que el rastreo de +``gcs://`` y el tipo de almacenamiento ``gcs`` provienen ahora del plugin ``fess-storage-gcs``. +Instálelo desde la página **Sistema > Plugin** de la pantalla de administración o con la +orden siguiente. + +:: + + $ bin/fess-setup install plugin fess-storage-gcs + +``gcs`` también ha salido del valor distribuido de ``crawler.file.protocols``, que ahora es +``file,smb,smb1,ftp``; el plugin lo vuelve a añadir al instalarse. Hasta entonces, una +configuración de rastreo de archivos cuya ruta empieza por ``gcs:`` se registra como +advertencia y no recupera nada. Una instalación que se actualiza conserva su propio +``crawler.file.protocols``, por lo que la ruta se sigue aceptando pero ningún cliente de +rastreo la atiende; en una instalación nueva ``gcs:`` no es un protocolo configurado, así que +la pantalla de administración rechaza guardar la ruta y una ruta guardada antes se lee como +ruta de archivo local. La página de almacenamiento también registra una advertencia y muestra +el fallo como un error con el nombre del plugin que hay que instalar, donde antes solo +mostraba una lista de archivos vacía. + +Si no utiliza Google Cloud Storage, no hay nada que hacer. Amazon S3 y el almacenamiento +compatible con S3, como MinIO, han pasado a un plugin de la misma manera; consulte la sección +siguiente. + +Amazon S3 pasa a un plugin +-------------------------- + +El SDK de AWS ya no forma parte de la distribución, por lo que el rastreo de ``s3://`` y los +tipos de almacenamiento ``s3`` y ``s3_compat`` provienen ahora del plugin +``fess-storage-s3``. Instálelo desde la página **Sistema > Plugin** de la pantalla de +administración o con la orden siguiente. + +:: + + $ bin/fess-setup install plugin fess-storage-s3 + +``s3`` también ha salido del valor distribuido de ``crawler.file.protocols``, que ahora es +``file,smb,smb1,ftp``; el plugin lo vuelve a añadir al instalarse. ``storage.type`` sigue +teniendo el valor predeterminado ``auto``, que se resuelve como S3 cuando no hay ningún punto +final configurado, así que la página de almacenamiento de la pantalla de administración no +funciona hasta que se instala el plugin, aunque nunca haya indicado ``s3`` explícitamente. Sus +valores ``storage.*`` se conservan, porque están en ``WEB-INF/conf/system.properties``, y un +``crawler.file.protocols`` existente tampoco se sustituye en la actualización. + +Si no utiliza Amazon S3 ni almacenamiento compatible con S3 como MinIO, no hay nada que hacer. + +La autenticación SSO pasa a plugins +----------------------------------- + +Ninguno de los cuatro autenticadores SSO forma parte ya de la distribución; cada valor de +``sso.type`` proviene ahora de su propio plugin, que incluye la biblioteca de identidad que +necesita: ``saml`` de ``fess-sso-saml``, ``spnego`` de ``fess-sso-spnego``, ``entraid`` (y el +antiguo ``aad``) de ``fess-sso-entraid`` y ``oic`` de ``fess-sso-oidc``. Fíjese en el último +par: el plugin se llama ``fess-sso-oidc`` mientras que el valor de ``sso.type`` sigue siendo +``oic``, el único lugar en el que ambos difieren. Instale el que utilice desde la página +**Sistema > Plugin** de la pantalla de administración o con la orden siguiente. + +:: + + $ bin/fess-setup install plugin fess-sso-saml + +Sus valores de configuración se conservan, porque ``sso.type`` y las claves ``saml.*``, +``spnego.*``, ``entraid.*``, ``aad.*`` y ``oic.*`` están en +``WEB-INF/conf/system.properties``. Además, "Sistema" → "General" de la pantalla de +administración sigue ofreciendo los cuatro tipos y sigue mostrando sus ajustes, porque un +plugin no puede proporcionar un JSP, así que nada en esa pantalla indica que falte un plugin. + +Hasta que se instala el plugin, una petición a ``/sso/`` se redirige de vuelta a la página de +inicio de sesión, que informa de que el inicio de sesión SSO ha fallado, y nadie puede iniciar +sesión mediante SSO. 15.10 registra en ``fess.log`` una advertencia con el nombre del componente +que ha buscado y el del plugin que lo proporciona, donde hasta 15.8 no se registraba nada en +ningún nivel. + +El plugin ``oic`` es más estricto que el autenticador de 15.8. ``oic.token.server.url`` debe ser +HTTPS (``http`` solo para ``localhost``, ``127.x.x.x`` y ``::1``), se comprueban los claims +``aud`` y ``exp`` del ID Token, y ``iss`` se comprueba cuando se define la nueva clave +``oic.issuer``. Para más detalles, consulte :doc:`../config/sso-oidc`. + +En 15.8, ``oic.token.server.url`` podía ser una URL ``http`` de cualquier host. En 15.10, ``http`` hacia el nombre de un servicio de Docker Compose (como ``http://keycloak:8080/...``) o un nombre de host interno se rechaza, aunque apunte a la misma máquina. El inicio de sesión falla y ``fess.log`` registra una advertencia que empieza por ``Failed to process the OpenID Connect callback: oic.token.server.url must be https``. Cambie el endpoint de token a una URL HTTPS antes de actualizar. + +Además, defina ``oic.issuer`` con el valor ``issuer`` del documento Discovery del OP. Si no se define, ``iss`` no se comprueba y se registra una advertencia en el primer inicio de sesión tras el arranque. Definir ``oic.issuer`` no relaja la regla de HTTPS. + +Si no utiliza SSO, es decir, si ``sso.type`` es ``none`` o no está definido, no hay nada que +hacer. + +.. _upgrade-159-script-engine: + +El motor de scripting integrado pasa de Groovy a JavaScript +----------------------------------------------------------- + +Hasta 15.8 el motor de scripting integrado era Groovy y ``job.default.script`` tenía el valor +predeterminado ``groovy``. En 15.10 el motor integrado es JavaScript y el valor predeterminado es +``javascript``. Groovy ya no está integrado: lo proporciona el plugin ``fess-script-groovy``, que +debe estar instalado para que un ``scriptType`` con valor ``groovy`` se pueda resolver. + +Una actualización no cambia el motor almacenado con cada ajuste, y un ajuste guardado antes de 15.10 +que no registra ningún motor cuenta como ``groovy``. Sin el plugin, deja de funcionar lo siguiente: + +- Los trabajos programados guardados como ``groovy``. **Esto incluye los trabajos que creó el + propio 15.8:** Default Crawler, Suggest Indexer, Config Reloader, Log Aggregator, Doc Purger y + los demás trabajos incluidos están guardados como ``groovy``, y al iniciarse 15.10 solo añade los + trabajos incluidos que todavía no existen, así que no los modifica. Cada uno de ellos falla cada + vez que se ejecuta según su programación, de modo que Default Crawler deja de rastrear. La + mayoría de los trabajos incluidos tienen desactivado "Registro", por lo que sus fallos no + aparecen en el registro de trabajos, sino solo como advertencias ``Failed to execute job`` en + ``fess.log``. +- Las configuraciones de rastreo web y de archivos con scripts de campo + (``field.script.``) en "Parámetro de configuración". Todos los documentos de + una configuración así fallan con una ``ScriptEngineException`` y se registran como URL con + errores, mientras que el propio trabajo de rastreo termina correctamente. +- Las configuraciones de almacén de datos con un "Script". Los valores que no son solo un nombre de + parámetro no se pueden evaluar; consulte :doc:`../config/datastore/ds-overview`. +- Las reglas de impulso de documentos. Una regla así no impulsa nada. +- Los mapeos de rutas cuyo "Reemplazo" empieza por ``groovy:``. Un mapeo así no se aplica y las + URL quedan sin cambios. + +Después del primer inicio, busque en ``fess.log`` una advertencia que empiece por +``Settings use the script engine groovy, which is not registered``. |Fess| comprueba los ajustes +anteriores una vez al iniciarse e indica, para cada tipo, cuántos usan un motor que ningún plugin +proporciona. También menciona ``job.default.script`` cuando un ``fess_config.properties`` traído +de 15.8 sigue indicando ``groovy``; en ese caso, los trabajos creados después de la actualización +también usan Groovy (consulte :ref:`upgrade-159-carried-over-config`). Resuélvalo de una de estas +dos maneras: + +- Instale el plugin y reinicie |Fess|. Los scripts de Groovy almacenados se ejecutan entonces sin + cambios y la advertencia deja de registrarse. El plugin también puede instalarse desde + "Sistema" → "Plugin" en la pantalla de administración. + + :: + + $ bin/fess-setup install plugin fess-script-groovy + +- Pase cada ajuste a JavaScript. Primero reescriba la sintaxis que solo acepta Groovy y después + seleccione JavaScript: + + - Trabajos programados: en "Sistema" → "Programador", cambie "Tipo de ejecución" a + ``javascript``. Los scripts de los trabajos incluidos son JavaScript válido tal como están, con + dos excepciones: Thumbnail Purger usa el literal ``long`` de Groovy ``1000L``, que JavaScript + rechaza (escriba ``1000``), e Index Exporter necesita el cambio descrito en + :ref:`upgrade-159-index-exporter`. Un literal de array de JavaScript se convierte + automáticamente en un ``String[]`` de Java, por lo que se omiten las conversiones + ``as String[]`` de la forma Groovy: + + :: + + return container.getComponent("crawlJob").logLevel("info").webConfigIds(["1", "2"]).fileConfigIds(["1"]).dataConfigIds([]).execute(executor); + + - Configuraciones de rastreo web y de archivos: añada ``config.script.type=javascript`` a + "Parámetro de configuración". + - Configuraciones de almacén de datos: añada ``script_type=javascript`` a "Parámetro". + - Reglas de impulso de documentos: cambie "Tipo de Script" a ``javascript``. + - Mapeos de rutas: empiece el "Reemplazo" por ``javascript:`` en lugar de ``groovy:``. + - ``job.default.script``: establézcalo en ``javascript`` en un ``fess_config.properties`` + traído de 15.8. + +``crawler.default.script`` se ha eliminado +------------------------------------------ + +``crawler.default.script`` ya no existe en ``fess_config.properties``. Elimínelo de su +configuración; un valor que permanezca con ese nombre no tiene ningún efecto. + +El protocolo de rastreo ``storage`` se ha eliminado +--------------------------------------------------- + +``storage`` ya no se admite en ``crawler.file.protocols``; el valor incluido es +``file,smb,smb1,ftp``. Utilice ``s3`` en su lugar y cambie a una ruta ``s3:`` cualquier +configuración de rastreo de archivos cuya ruta empiece por ``storage:``. ``s3`` necesita el +plugin ``fess-storage-s3``. + +.. _upgrade-159-index-exporter: + +El trabajo Index Exporter hace referencia a un paquete eliminado +---------------------------------------------------------------- + +15.10 ya no incluye las clases ``org.opensearch``; los constructores de consultas que usan los +scripts de los trabajos están ahora en ``org.codelibs.fesen.opensearch``. El script que 15.8 +guardó para el trabajo Index Exporter hace referencia a +``org.opensearch.index.query.QueryBuilders``, y la actualización no lo sustituye, así que el +trabajo falla incluso con ``fess-script-groovy`` instalado. El trabajo se distribuye desactivado y +sin programación, por lo que solo le afecta si lo ejecuta. Ábralo en "Sistema" → "Programador" y +cambie el paquete de su script por el de 15.10: + +:: + + return new org.codelibs.fess.job.IndexExportJob().query(org.codelibs.fesen.opensearch.index.query.QueryBuilders.matchAllQuery()).execute() + +Cambie de la misma manera cualquier script propio que haga referencia a +``org.opensearch.index.query``. Consulte :doc:`../config/admin-index-export` para ver más ejemplos +de consultas. + +.. _upgrade-159-carried-over-config: + +Archivos de configuración traídos de 15.8 +----------------------------------------- + +El procedimiento ZIP del Paso 3 copia ``fess_config.properties`` y ``bin/fess.in.sh`` de la +instalación antigua, y una actualización RPM conserva un ``/etc/fess/fess_config.properties`` que +haya modificado (el archivo de 15.10 se coloca junto a él como ``fess_config.properties.rpmnew``). +Una actualización DEB hace lo mismo cuando conserva su versión al responder la pregunta (el archivo +de 15.10 se coloca junto a él como ``fess_config.properties.dpkg-dist``). En ambos casos, 15.10 +funciona después con los valores de 15.8, incluidos aquellos cuyo valor distribuido cambió en 15.10. +Revise al menos las claves siguientes. + +.. list-table:: + :header-rows: 1 + + * - Clave + - 15.8.0 + - 15.10 + - Efecto de conservar el valor de 15.8 + * - ``job.default.script`` + - ``groovy`` + - ``javascript`` + - Los trabajos creados en "Sistema" → "Programador" usan ``groovy`` de forma predeterminada y + fallan sin el plugin ``fess-script-groovy``. + * - ``job.template.script`` + - Forma Groovy con ``as String[]`` + - Forma JavaScript + - Un trabajo creado a partir de una configuración de rastreo recibe un script de Groovy. + * - ``crawler.file.protocols`` + - ``file,smb,smb1,ftp,storage,s3,gcs`` + - ``file,smb,smb1,ftp`` + - Una ruta que empieza por ``s3:`` o ``gcs:`` se sigue aceptando sin su plugin y se omite con + una advertencia al rastrear. ``storage`` ya no se admite. + * - ``search_engine.http.url`` + - ``http://localhost:9201`` + - ``http://localhost:9200`` + - Se usa cuando ``SEARCH_ENGINE_HTTP_URL`` no está definido, como en un ``bin/fess.in.sh`` + copiado de 15.8 en el que no lo definió. |Fess| busca entonces OpenSearch en el puerto 9201, + el del OpenSearch integrado que 15.10 eliminó. + * - ``jvm.crawler.options``, ``jvm.thumbnail.options`` + - ``-Djcifs.smb.client.*``, ``-Djcifs.smb1.smb.client.*`` + - ``-Djcifs.client.*`` + - Los tiempos de espera de SMB siguen con los valores predeterminados de jcifs; consulte + :ref:`upgrade-159-jcifs`. + * - ``response.headers`` + - Incluye la fila ``text/html=Content-Security-Policy: reflected-xss block`` + - Fila eliminada + - La página de inicio de sesión, la interfaz de administración y las demás páginas que |Fess| + genera por sí mismo se envían con una cabecera ``Content-Security-Policy: reflected-xss block`` + que ningún navegador reconoce, y la consola del navegador registra + ``Unrecognized Content-Security-Policy directive 'reflected-xss'``. La cabecera no restringe + nada. Elimine la fila, como se describe a continuación. + * - ``app.encrypt.property.pattern`` + - ``.*password|.*key|.*token|.*secret`` + - ``.*password|.*passphrase|.*key|.*token|.*secret`` + - Un parámetro cuyo nombre termina en ``passphrase`` (por ejemplo, ``ssh.passphrase`` de una + configuración de almacén de datos) se guarda en texto plano. Un valor guardado antes sigue en + texto plano hasta que se vuelve a guardar el ajuste con el patrón de 15.10. + * - ``index.backup.log.targets`` + - ``click_log.ndjson,favorite_log.ndjson,search_log.ndjson,user_info.ndjson`` + - ``chat_log.ndjson,click_log.ndjson,favorite_log.ndjson,search_log.ndjson,user_info.ndjson`` + - La página "Información del sistema" → "Copia de seguridad" no ofrece ``chat_log.ndjson``. + * - ``index.export.exclude.fields`` + - ``cache`` + - ``cache,tag`` + - El campo ``tag``, que contiene las etiquetas de usuario, ya no se excluye de los archivos que + escribe el trabajo Index Exporter. + * - ``crawler.default.script``, ``theme.allowed.archive.extensions``, + ``theme.assets.cache.max.age``, ``theme.assets.precompressed``, + ``rag.chat.message.max.length``, ``supported.uploaded.js.extentions``, + ``supported.uploaded.css.extentions``, ``supported.uploaded.media.extentions``, + ``supported.uploaded.files``, ``online.help.name.design`` + - Presentes + - Eliminadas + - Ningún efecto; elimínelas. + +El valor distribuido de ``response.headers`` contiene, de 15.0 a 15.8, la fila +``text/html=Content-Security-Policy: reflected-xss block``. ``reflected-xss`` era una directiva de un +borrador temprano de Content-Security-Policy que los navegadores ya no reconocen, por lo que la +cabecera no restringe nada y solo añade el error a la consola. 15.10 ya no distribuye la fila (las +filas ``X-XSS-Protection`` y ``X-Frame-Options`` no cambian), pero un ``response.headers`` traído de +15.8 la conserva. Elimine solo esa fila de ``response.headers`` en ``fess_config.properties``. El +``\n\`` al final de cada fila continúa el valor en la línea siguiente, así que al borrar la línea +completa las demás quedan intactas:: + + text/html=Content-Security-Policy: reflected-xss block\n\ + +Si define ``response.headers`` con ``-Dfess.config.response.headers``, elimine la misma entrada de ese +valor. + +A un ``bin/fess.in.sh`` copiado de 15.8 también le faltan dos cosas que sí tiene el archivo de +15.10. Deja ``SEARCH_ENGINE_HTTP_URL`` sin definir salvo que lo haya definido usted, mientras que +15.10 define ``http://localhost:9200``, y no busca el Node.js instalado con +``bin/fess-setup install nodejs``, por lo que los plugins de Playwright no encuentran Node.js a +menos que defina ``PLAYWRIGHT_NODEJS_PATH``. + +En lugar de copiar cualquiera de los dos archivos entero, parta del archivo distribuido con 15.10 y +vuelva a aplicar los valores que haya cambiado. ``diff`` los muestra:: + + $ diff /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.10.0/app/WEB-INF/classes/fess_config.properties + $ diff /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.10.0/bin/fess.in.sh + +En una actualización RPM, compare de la misma manera ``/etc/fess/fess_config.properties`` con +``/etc/fess/fess_config.properties.rpmnew``, y en una actualización DEB con +``/etc/fess/fess_config.properties.dpkg-dist``. Un ``fess_config.properties`` que nunca editó se +sustituye por el archivo de 15.10 en una actualización DEB (consulte el Paso 3), así que se parte de +los valores de 15.10. + +``app.cipher.key`` es el único valor que debe trasladar aunque 15.10 no lo haya cambiado. Es la +clave que cifra las contraseñas y los secretos almacenados en los parámetros de la autenticación +web, de las configuraciones de rastreo y de las configuraciones de almacenes de datos. Si la nueva +instalación funciona con una clave distinta de la que los guardó, porque tomó el +``fess_config.properties`` incluido o restauró una copia de seguridad en un servidor nuevo, no se +pueden descifrar: ``fess-crawler.log`` registra una ``CipherFailureException`` y un rastreo que +incluya una configuración así puede no indexar nada. + +.. note:: + + |Fess| 15.10 también guarda el ``password`` de la autenticación web y de archivos cifrado con ``app.cipher.key``, por + lo que ``fess_basic_config.bulk`` y ``fess_config.bulk`` de una copia de seguridad contienen los valores cifrados. + Al restaurar en otra instalación, traslade la misma ``app.cipher.key``; con una clave distinta, los rastreos que usan + estas credenciales fallan con un error. Una copia de seguridad creada antes de 15.10 las contiene en texto sin cifrar + y sigue funcionando (consulte :doc:`../admin/backup-guide`). + +.. _upgrade-159-jcifs: + +Los tiempos de espera de SMB usan los nombres de propiedad de jcifs 3 +--------------------------------------------------------------------- + +jcifs, la biblioteca que |Fess| utiliza para rastrear servidores de archivos SMB, cambió el nombre +de sus propiedades en la versión 3: ``jcifs.smb.client.*`` pasó a ser ``jcifs.client.*``, y los +nombres separados ``jcifs.smb1.smb.client.*`` para SMB1 se unificaron en las mismas propiedades. +Hasta 15.8, ``jvm.crawler.options`` y ``jvm.thumbnail.options`` seguían pasando los nombres +antiguos, que jcifs ignora, por lo que los rastreos SMB se ejecutaban con los valores +predeterminados de jcifs. 15.10 pasa los nombres nuevos: + +:: + + -Djcifs.client.responseTimeout=30000 + -Djcifs.client.soTimeout=35000 + -Djcifs.client.connTimeout=60000 + -Djcifs.client.sessionTimeout=60000 + +Por tanto, los tiempos de espera de conexión y de sesión surten efecto por primera vez y pasan del +valor predeterminado de jcifs de 35 segundos a 60 segundos: un rastreo espera ahora hasta 60 +segundos a un servidor SMB que no responde. Los tiempos de espera de respuesta y de socket +coinciden con los valores predeterminados de jcifs, así que no cambian. + +Si cambió estos tiempos de espera, cambie sus nombres en ambas opciones. Con los nombres antiguos +tampoco tenían efecto en 15.8. Un ``fess_config.properties`` traído de 15.8 conserva los nombres +antiguos y, con ellos, los valores predeterminados de jcifs. + +Se han eliminado cuatro propiedades sin efecto +---------------------------------------------- + +Las siguientes claves ya no existen en ``fess_config.properties``. |Fess| nunca las leyó de ese +archivo, así que un valor que permanezca con estos nombres sigue sin tener efecto. + +- ``theme.allowed.archive.extensions`` +- ``theme.assets.cache.max.age`` +- ``theme.assets.precompressed`` +- ``rag.chat.message.max.length`` + +El límite que establece ``rag.chat.message.max.length`` sigue funcionando, pero se lee como +propiedad del sistema: defínalo en ``app/WEB-INF/conf/system.properties`` o con +``-Dfess.system.rag.chat.message.max.length``, como se describe en :doc:`../config/rag-chat`. + +.. _upgrade-159-static-theme: + +La pantalla de búsqueda es ahora un tema estático +------------------------------------------------- + +La pantalla de búsqueda la sirve el tema estático ``bootstrap``, incluido con |Fess|, salvo que se +seleccione otro tema. Esto se aplica a ``/``, ``/search``, ``/advance``, ``/help``, ``/profile``, +``/cache``, ``/chat`` y a las páginas de error. Hasta 15.8, estas páginas eran JSP salvo que se +hubiera configurado un tema predeterminado. + +El cambio también se produce al actualizar. Una instalación 15.8 que nunca configuró un tema +predeterminado no tiene ``theme.default`` en ``system.properties``, así que después de la +actualización muestra el tema estático; no se escribe nada en la configuración ni se registra nada. +No existe ninguna configuración que recupere la pantalla de búsqueda JSP. Si había configurado un +tema predeterminado en 15.8, esa configuración se conserva; instale la versión para 15.10 del tema +(``bin/fess-setup install theme ``), porque un tema predeterminado que nombra un tema no +instalado recurre a ``bootstrap`` con una advertencia en ``fess.log``. + +Si modificó los JSP, el CSS o las imágenes de la pantalla de búsqueda, mediante "Diseño de página" +en la pantalla de administración o en un plugin de tema JAR, esos cambios ya no se muestran. +Aplíquelos en un tema estático: copie el tema incluido y modifique la copia, como se describe en +:ref:`theme-customize-bundled`, o instale un tema publicado desde "Sistema" > "Tema" en la pantalla +de administración o con ``bin/fess-setup install theme ``. Un aspecto distinto por host +virtual es ahora un tema estático con el nombre del host virtual; consulte +:doc:`../config/security-virtual-host`. + +También desaparecieron estas dos funciones: + +- La pantalla de inicio de sesión por host virtual. Hasta 15.8, al guardar "Sistema" > "General" se + copiaban los JSP, incluida la pantalla de inicio de sesión, en ``WEB-INF/view//``, + y se podían editar por host virtual. 15.10 ya no crea esas copias. La pantalla de inicio de sesión + (``/login/``) sigue siendo un JSP, pero todos los hosts virtuales muestran el mismo, el de + ``WEB-INF/view/admin/login/``. Los JSP copiados anteriormente no se utilizan. +- Los plugins de tema JAR (``fess-theme-*``). Si instala uno, solo se coloca como un JAR de propósito + general del tipo ``jar`` y no cambia ninguna pantalla. Los JAR que queden se pueden eliminar en la + página "Sistema" > "Plugin" o con ``bin/fess-setup remove plugin `` (consulte + :doc:`../dev/theme-development`). + +Si en 15.8 mostraba campos propios en los resultados de búsqueda JSP, añada los mismos campos a +``query.additional.api.response.fields`` además de a ``query.additional.response.fields``. El tema +estático obtiene los resultados de búsqueda de ``/api/v2/search``. ``query.additional.response.fields`` +solo añade los campos que se obtienen del motor de búsqueda, y esta API incluye en la respuesta únicamente +los campos enumerados en ``query.additional.api.response.fields`` (consulte :doc:`../config/search-advanced`). +Modifique también el tema para que muestre esos campos. + +Lo que ven los clientes +~~~~~~~~~~~~~~~~~~~~~~~ + +Ahora los errores se muestran en el mismo lugar, en la URL solicitada y con el código de estado HTTP +real. Un navegador (una solicitud cuyo encabezado ``Accept`` incluye ``text/html``) recibe la página +de error del tema; cualquier otro cliente recibe un cuerpo ``text/plain`` de una línea (por ejemplo +``Not Found.`` para ``404``). Hasta 15.8, la mayoría de los errores respondían con una redirección +``302`` a una página ``/error/...`` que a su vez devolvía ``200``. Revise la monitorización, las +comprobaciones de estado y los clientes que siguen los encabezados ``Location`` o esperan URL +``/error/``. + +.. list-table:: + :header-rows: 1 + + * - Solicitud + - Hasta 15.8 + - 15.10 + * - ``/go/`` sin un parámetro, o para un documento que no existe + - ``200``, o ``302`` a ``/error/`` + - ``400`` o ``404`` + * - ``/thumbnail/`` sin un parámetro, para un documento desconocido o sin miniatura + - ``200`` o ``302`` + - ``400`` o ``404`` + * - ``/sso/metadata`` y ``/sso/logout`` cuando el tipo de SSO configurado no los gestiona + - ``302`` a ``/error/badrequest/`` + - ``400`` + * - ``/api/v1/*``, ``/json`` y cualquier URL desconocida + - ``302`` a ``/error/notfound/`` + - ``404`` + * - Una excepción no capturada, también en la API de administración + - ``302`` a ``/error/systemerror/`` + - ``500`` con el cuerpo ``System Error.`` (no JSON) + * - Las propias ``/error/notfound/``, ``/error/badrequest/``, ``/error/systemerror/`` + - ``200`` + - ``404``, ``400``, ``500`` + +Con ``login.required=true``, las páginas de búsqueda ya no redirigen a un usuario anónimo. Devuelven +``200`` con el tema, que pide al usuario que inicie sesión, y en su lugar se rechazan los datos que +hay detrás: todos los endpoints de ``/api/v2/`` salvo ``/health``, ``/auth/*`` y ``/ui/config``, +incluido ``/api/v2/search``, responden ``401`` hasta que el usuario inicia sesión. ``/go/``, +``/thumbnail/`` y ``/osdd`` siguen redirigiendo al inicio de sesión. Una comprobación que espera una +redirección para una solicitud anónima a ``/`` debe comprobar en su lugar que ``/api/v2/search`` +devuelve ``401``. + +La pantalla de búsqueda también busca a través de ``/api/v2/search``, así que una búsqueda se +registra cuando se llama a esa API, no cuando se solicita ``/search``. Un cliente que no ejecuta +JavaScript recibe la página sin resultados. + +El HTML de la pantalla de búsqueda lleva ``X-Frame-Options: DENY`` y un ``Content-Security-Policy`` con +``frame-ancestors 'none'``, por lo que ninguna otra página puede mostrarlo en un marco. La pantalla de +búsqueda JSP de la 15.8 enviaba ``X-Frame-Options: SAMEORIGIN`` (el valor por defecto de +``response.headers``) y podía mostrarse en un ``iframe`` de una página del mismo origen. Si incrustaba la +pantalla de búsqueda en un ``iframe`` del mismo origen, establezca ``theme.index.frame.ancestors`` en +``fess_config.properties`` (por defecto ``'none'``) en ``'self'``. Para incrustarla desde otro origen, +indique ese origen (consulte :doc:`../dev/theme-development`). + +Se ha eliminado el editor de diseño de página +--------------------------------------------- + +[Sistema > Diseño de página] ya no forma parte de la pantalla de administración, por lo que los +archivos JSP, CSS e imágenes de la pantalla de búsqueda ya no se pueden editar desde allí. Para +cambiar el aspecto de la pantalla de búsqueda, utilice un tema estático (consulte +:ref:`theme-customize-bundled`). + +También se han eliminado las siguientes claves de ``fess_config.properties``. Un valor que +permanezca con estos nombres no se utiliza. + +- ``supported.uploaded.js.extentions`` +- ``supported.uploaded.css.extentions`` +- ``supported.uploaded.media.extentions`` +- ``supported.uploaded.files`` +- ``online.help.name.design`` + +Los roles ``admin-design`` y ``admin-design-view`` ya no otorgan ningún permiso. Un usuario que solo +tenga estos roles llega a la pantalla de búsqueda, y no a la de administración, al iniciar sesión. + +``api.access.token.required`` se ha eliminado +--------------------------------------------- + +``api.access.token.required`` ya no existe en ``fess_config.properties``. Un valor que permanezca con +ese nombre no tiene ningún efecto, incluso en un ``fess_config.properties`` conservado de la 15.8. +Con ``true``, rechazaba toda solicitud a la API de un usuario que no hubiera iniciado sesión. Como +la pantalla de búsqueda ahora busca a través de ``/api/v2/search``, además habría mostrado a los +usuarios anónimos una pantalla de búsqueda sin resultados. + +Una instalación que lo tenía en ``true`` responde ahora a las solicitudes a la API de usuarios +anónimos con los roles de invitado, igual que en la pantalla de búsqueda. Para impedir que los +usuarios anónimos busquen, establezca ``login.required=true``. Los tokens de acceso funcionan como +antes: una solicitud con un token de acceso registrado recibe los permisos de ese token, y una +solicitud con un token no registrado o caducado se rechaza. + +.. _upgrade-159-api-requests: + +Solicitudes que la API ahora rechaza +------------------------------------ + +La 15.10 rechaza las siguientes solicitudes, que la 15.8 aceptaba. Revise los clientes y scripts que escribió +para la 15.8. La API de administración responde a un rechazo con HTTP ``400`` y ``status`` ``1`` en el +cuerpo. + +.. list-table:: + :header-rows: 1 + + * - Solicitud + - Hasta 15.8 + - 15.10 + * - ``/api/v2/search`` con ``facet.field`` o ``facet.query`` y un ``facet.size`` de ``0`` o menos, o un ``facet.size`` o ``facet.minDocCount`` que no es un entero + - ``200``, pero con un resultado vacío: ``record_count`` es ``0`` y ``partial`` es ``true`` + - ``400`` (``invalid_request``). ``facet.size`` debe ser ``1`` o más + * - ``track_total_hits=false``. Con ``query.track.total.hits`` en ``false``, afecta a todas las búsquedas + - ``200``, pero sin resultados + - Se rechaza la búsqueda (``/api/v2/search`` responde ``400`` con ``invalid_request``). ``true`` y los enteros positivos funcionan como antes + * - Una entrada de los diccionarios ``mapping`` o ``kuromoji`` que repite una existente, creada o actualizada mediante la API de administración + - Se guarda. Después falla la carga del diccionario, lo que puede dejar la búsqueda sin servicio + - ``400`` + * - Una entrada del diccionario ``kuromoji`` cuyo ``token`` contiene un espacio, o cuyos ``segmentation`` y ``reading`` tienen un número distinto de partes separadas por espacios, creada o actualizada mediante la API de administración + - Se guarda. La carga del diccionario falla del mismo modo + - ``400`` + * - ``DELETE /api/admin/searchlist/doc/{doc_id}`` que no elimina nada: un ``doc_id`` que no existe, o un valor que no es un ``doc_id``, como el ``_id`` que muestra la lista de documentos + - ``200`` (``status`` ``0``); el documento no se elimina + - ``400`` + * - Un nombre de rol o de grupo en ``roles`` o ``groups`` de un usuario de la API de administración + - Se guarda, pero el nombre no actúa como rol. Con algunos nombres falla la lectura del usuario + - ``400``. Indique el ID del rol o del grupo (el ``id`` que devuelven ``GET /api/admin/role/settings`` y ``GET /api/admin/group/settings``) + * - Un usuario de la API de administración cuya contraseña incumple la política de contraseñas (por ejemplo ``password.min.length``, por defecto ``8``); una creación sin contraseña; un ``confirm_password`` distinto de ``password`` + - Se guarda; el usuario puede iniciar sesión con esa contraseña + - ``400`` + +Las filas de ``/api/v2/documents/all`` ya no llevan ``score``. Hasta la 15.8 cada documento tenía su +puntuación de búsqueda; la 15.10 recorre todo el resultado con un point in time y ``search_after``, que no +produce puntuación. ``/json?type=scroll`` y ``/api/v1/documents/all`` de los plugins de las API antiguas se +comportan igual. Un script que lea ``score`` debe tolerar que falte. + +Las subidas de archivos de la API de administración (los seis diccionarios, ``badword``, ``elevateword`` y +``storage``) se aceptan con ``POST``. La documentación de la 15.8 indicaba ``PUT``, pero un ``PUT`` con +``multipart/form-data`` nunca entrega el archivo, así que tanto en la 15.8 como en la 15.10 falla con el +error de validación de que el archivo es obligatorio. Los endpoints ``PUT`` siguen existiendo; utilice +``POST`` para las subidas. + +``search_engine.type=cloud`` está obsoleto +------------------------------------------ + +La versión 15.10 añade el valor ``vanilla`` a ``search_engine.type`` para un OpenSearch puro sin los plugins de CodeLibs (consulte :doc:`../config/search-engine-type`). ``cloud`` pasa a ser un alias obsoleto de ``vanilla``: sigue funcionando, pero |Fess| registra una advertencia al iniciarse. Cámbielo a ``vanilla`` cuando la instalación ya se ejecute con la 15.10. ``aws`` sigue funcionando como antes. + +* ``vanilla`` requiere la 15.10. |Fess| 15.8 y anteriores no reconocen el valor, así que mantenga ``cloud`` mientras todavía pueda volver a la 15.8. +* Las definiciones de índice de ``aws`` y ``cloud`` se leen ahora de ``fess_indices/_vanilla/``. Los directorios ``fess_indices/_aws/`` y ``fess_indices/_cloud/`` incluidos ya no existen, y un directorio ``fess_indices/_aws/`` o ``fess_indices/_cloud/`` que usted haya añadido ya no se lee. Traslade sus cambios a ``fess_indices/_vanilla/``. Los índices ya existentes no se modifican. +* La configuración de sugerencias que la 15.8 guardó en el motor de búsqueda se migra automáticamente; no tiene que hacer nada. + +El almacén de datos CSV interpreta los campos entrecomillados +------------------------------------------------------------- + +El plugin ``fess-ds-csv`` de 15.10 interpreta las comillas de forma predeterminada. Un campo como +``"Yamada, Taro"`` es una sola columna, mientras que el plugin de 15.8.0 lo dividía en la coma. +Después de ``bin/fess-setup upgrade plugins``, revise las configuraciones de almacén de datos que +leen archivos CSV con campos entrecomillados. Para mantener el comportamiento de 15.8, añada +``quote_disabled=true`` a "Parámetros"; consulte :doc:`../config/datastore/ds-csv`, que también +describe qué ocurre con una comilla sin pareja. + +.. _upgrade-reindex-new-fields: + +Aplicar los nuevos campos y la normalización de kana a un índice de documentos existente +---------------------------------------------------------------------------------------- + +Al iniciarse, 15.10 añade campos nuevos a los índices de configuración, de registros y de usuarios. +En el índice de documentos añade únicamente el campo ``tag`` (``keyword``), que contiene las +etiquetas de usuario; el resto del mapeo y la configuración de análisis no cambian. Si sigue usando +un índice de documentos creado con 15.8 o anterior, los siguientes cambios de 15.10 no tienen efecto. + +- **Propietario y último modificador de un archivo** (``owner``, ``last_modifier``): campos nuevos + que indexan los rastreos del sistema de archivos, SMB y FTP. El índice de documentos existente no + los define, por lo que el primer valor rastreado los mapea dinámicamente como ``text`` y las + búsquedas como ``owner:alice`` o ``facet.field=owner`` no funcionan como se espera. +- **ETag** (``etag``): el campo en el que el rastreador guarda el ETag de una página rastreada, que + 15.10 devuelve como ``If-None-Match`` para no volver a obtener una página sin cambios. El índice de + documentos existente tampoco lo define, por lo que se mapea dinámicamente como ``text`` en lugar + del ``keyword`` no indexado incluido. Las peticiones condicionales siguen funcionando con ese + mapeo. +- **Normalización de variantes de kana y de guiones escritos en lugar de la marca de vocal larga** + (por ejemplo, ``サ―バ－`` se trata como la misma palabra que ``サーバー``): las reglas están en la + configuración de análisis del índice de documentos y en el diccionario ``mapping.txt``, por lo que + un índice existente no las recibe. + +Para aplicar ambos, habilite "Actualizar alias" y "Restablecer diccionarios" en "Información del +sistema" → "Mantenimiento" en la interfaz de administración y ejecute la "Reindexación". La +reindexación copia los documentos existentes a un índice nuevo, por lo que no es necesario volver a +rastrear. + +.. warning:: + + "Restablecer diccionarios" sobrescribe los diccionarios del lado de OpenSearch con los archivos de + diccionario incluidos. Si ha editado sinónimos u otros diccionarios en "Diccionario" de la + interfaz de administración, descárguelos antes y vuelva a aplicarlos después de la reindexación: + elimine las entradas duplicadas o no válidas de los archivos descargados (consulte el Paso 7), + cárguelos y, después, haga clic en [Recargar] en «Recargar índice de documentos» en "Información + del sistema" → "Mantenimiento". Hasta que lo haga, los analizadores del índice de documentos + siguen usando los diccionarios incluidos y un sinónimo restaurado no coincide, por mucho que + espere. Un diccionario que se aplica al indexar también requiere volver a rastrear los + documentos; consulte :ref:`dict-apply-changes`. + +.. note:: + + Los archivos indexados con 15.8 o anterior no tienen valores de propietario ni de último + modificador. El rastreo incremental no vuelve a obtener los archivos sin cambios, así que, para + añadir los valores, deshabilite temporalmente "Comprobar fecha de última modificación" en + "Sistema" → "General" y rastree. + + +Migración Específica de 15.10 +============================== + +Si actualiza desde la versión 15.7 o anterior a la 15.10, 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.10. 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.10, 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. La versión 15.10 añade además ``fess-llm-bedrock`` para Amazon Bedrock. + +Si Utilizaba SPNEGO (Autenticación Integrada de Windows) +-------------------------------------------------------- + +A partir de la versión 15.10, un inicio de sesión SPNEGO se rechaza cuando el reino Kerberos del +principal del cliente difiere del reino del servidor. Si sus usuarios inician sesión desde un +dominio secundario de un árbol de dominios de AD o desde un bosque de confianza, indique esos +reinos, separados por comas, en ``spnego.allowed.realms`` desde "Sistema" → "General" en la +pantalla de administración o en ``app/WEB-INF/conf/system.properties``. De lo contrario, los +usuarios que podían iniciar sesión hasta la versión 15.7 son rechazados con +``Kerberos realm is not allowed``. Consulte :doc:`../config/sso-spnego` para conocer más +detalles. + +Además, en la versión 15.10 los valores predeterminados definidos en el código de +``spnego.allow.unsecure.basic`` y ``spnego.allow.localhost`` cambiaron de ``true`` a ``false``. +Una instalación en la que estas claves no estén presentes en +``app/WEB-INF/conf/system.properties`` adopta el comportamiento más estricto al actualizar. En +particular, con ``spnego.allow.unsecure.basic=false`` la biblioteca SPNEGO solo ofrece la +autenticación básica en las peticiones en las que ``HttpServletRequest#isSecure()`` devuelve +``true``, por lo que, detrás de un proxy inverso que termina TLS y reenvía la petición por HTTP, +los clientes que antes recurrían a la autenticación básica ya no pueden iniciar sesión. En ese +caso, establezca ``tomcat.secure=true`` en ``tomcat_config.properties``; consulte +:doc:`../config/sso-spnego` para conocer más detalles. + +.. warning:: + + Un valor predeterminado definido en el código solo se aplica mientras la clave está ausente, y + "Sistema" → "General" de la pantalla de administración escribe todas las claves ``spnego.*`` + cada vez que se guarda. Por lo tanto, una instalación en la que alguna vez se pulsó Actualizar + en esa pantalla con la versión 15.7 sigue teniendo almacenados + ``spnego.allow.unsecure.basic=true`` y ``spnego.allow.localhost=true``, y actualizar a 15.10 no + la refuerza: mantiene el comportamiento permisivo de forma silenciosa y 15.10 solo registra una + advertencia en ``fess.log`` al inicializar SPNEGO. Abra "Sistema" → "General" (o edite + ``system.properties``) y desactive ambas opciones de forma deliberada. + ``spnego.allow.localhost=true`` es la más peligrosa de las dos: la biblioteca SPNEGO autentica + las peticiones procedentes del mismo host como el usuario del sistema operativo del servidor, + sin ninguna verificación de Kerberos, lo que resulta inseguro detrás de un proxy inverso + situado en el mismo host. + +.. _upgrade-159-saml: + +Si Utilizaba la Autenticación SAML (SSO) +---------------------------------------- + +A partir de la versión 15.10, |Fess| vincula cada respuesta SAML al identificador de la +AuthnRequest que envió, por lo que el SSO iniciado por el IdP (no solicitado) ya no funciona. Un +inicio de sesión que comienza en un icono de |Fess| dentro de un portal del IdP, como el panel de +Okta o el portal "Mis aplicaciones" de Microsoft Entra ID, no tiene ninguna AuthnRequest con la +que emparejarse y se rechaza. Hasta la versión 15.7 funcionaba porque |Fess| devolvía al IdP la +respuesta que no podía emparejar y el IdP entregaba de inmediato una aserción solicitada. Si +coloca un icono en el lado del IdP, haga que apunte al endpoint ``/sso/`` de |Fess| para que el +inicio de sesión lo inicie el SP. + +Además, el IdP devuelve la aserción mediante un POST entre sitios, por lo que +``tomcat.sameSiteCookies`` debe establecerse en ``none`` en ``tomcat_config.properties``. Con el +valor predeterminado ``lax`` que se incluye, la cookie de sesión no se envía en esa petición y el +inicio de sesión SAML no puede completarse. Este archivo se encuentra en ``lib/classes/`` en el +paquete ZIP y en ``/etc/fess/`` en los paquetes DEB/RPM, y es necesario reiniciar |Fess| tras el +cambio. Los navegadores solo aceptan ``none`` en una cookie que además tenga el atributo +``Secure``, por lo que |Fess| debe servirse mediante HTTPS. Hasta la versión 15.7, esta +configuración incorrecta no producía un error claro, sino un bucle interminable de redirecciones +al IdP, así que compruebe el ajuste incluso en un sitio que parecía funcionar; en la versión 15.10 +falla una sola vez en lugar de entrar en bucle. Consulte :doc:`../config/sso-saml` para conocer +más detalles. + +Si Utilizaba Microsoft Entra ID (Azure AD) +------------------------------------------ + +A partir de la versión 15.10, el modo de respuesta solicitado al endpoint de autorización es +``query`` por defecto, en lugar de ``form_post``. Hasta la versión 15.7 el callback se devolvía +como un POST entre sitios, y con el valor por defecto de |Fess| ``tomcat.sameSiteCookies = lax`` +la cookie de sesión no se envía en esa petición, por lo que era necesario +``tomcat.sameSiteCookies = none``. Si estableció ``none`` únicamente por ese motivo, puede volver +al valor por defecto. Para mantener el comportamiento anterior, establezca +``entraid.response.mode=form_post`` y conserve ``tomcat.sameSiteCookies = none``. Los navegadores +solo aceptan ``none`` en una cookie que además tenga el atributo ``Secure``, por lo que esa vía +también exige servir |Fess| mediante HTTPS. + +A partir de la versión 15.10, |Fess| también resuelve la pertenencia a grupos y roles del usuario +en segundo plano una vez completado el inicio de sesión, en lugar de bloquear el inicio de sesión +a la espera de Microsoft Graph. Hasta que la resolución termina — o si no se completa del todo —, +el usuario solo tiene su propio permiso a nivel de usuario y lo que aporten +``entraid.default.groups`` y ``entraid.default.roles``. Si no se ha configurado ninguno de los +dos —el valor por defecto que se incluye—, una búsqueda hecha en esa ventana no devuelve ningún +documento, porque una configuración de rastreo creada con los valores por defecto que se incluyen +concede ``{role}guest`` y un usuario con la sesión iniciada no tiene ese rol. Mientras la +resolución está en curso, la pantalla de búsqueda lo indica, y muestra otro mensaje distinto si no +se completó del todo: la resolución solo se considera correcta si han tenido éxito tanto la +consulta de pertenencias directas como el recorrido de los grupos anidados. La resolución se +reintenta cada vez que se renueva el token de acceso, y un éxito posterior hace desaparecer el +mensaje, por lo que un fallo no es definitivo en una sesión que dura más que el token; para +reintentarlo de inmediato, cierre la sesión y vuelva a iniciarla. Consulte +:doc:`../config/sso-entraid` para conocer más detalles. + +Una consecuencia de resolver en segundo plano: hasta que la resolución llega, los roles resueltos +del usuario todavía no se conocen. Por eso, un administrador es redirigido a la pantalla de +búsqueda en lugar de al panel de administración, y si abre una página del panel de administración +durante esa ventana vuelve a la pantalla de búsqueda. La ventana dura hasta aproximadamente un +segundo de retardo de planificación más las propias llamadas a Microsoft Graph — una para las +pertenencias directas y luego una más por cada uno de esos grupos para recorrer los grupos +anidados, emitidas una tras otra con la caché fría —, por lo que crece con el número de grupos a +los que pertenece el usuario. En esa ventana el acceso solo se deniega, nunca se concede, y no +hace falta ninguna configuración para superarla: la autorización se evalúa de nuevo en cada +petición de la misma sesión, así que una vez terminada la resolución las pantallas de +administración se abren con normalidad, sin volver a iniciar sesión. + +.. warning:: + + No acorte esa ventana poniendo el rol de administrador de |Fess| en ``entraid.default.roles``. + Esa propiedad es un valor global único que |Fess| aplica a todos los usuarios de Entra ID al + iniciar sesión y vuelve a aplicar en cada resolución posterior, por lo que concedería a todos + los usuarios del inquilino permisos permanentes de administrador de |Fess|. + +Si Utiliza LDAP / Active Directory +---------------------------------- + +A partir de 15.10, el nombre de permiso de un grupo o rol es el valor del RDN de la entrada y no un +fragmento del texto del DN. Por tanto, un grupo cuyo CN contiene un carácter que el DN escapa --la +coma es el caso habitual-- obtiene un nombre de permiso distinto al de 15.7. + +.. list-table:: + :header-rows: 1 + + * - DN de la entrada del grupo + - Nombre de permiso hasta 15.7 + - Nombre de permiso en 15.10 + * - ``CN=Sales\, EMEA,CN=Users,...`` + - ``2Sales`` + - ``2Sales, EMEA`` + * - ``CN=Sales\, APAC,CN=Users,...`` + - ``2Sales`` + - ``2Sales, APAC`` + +Hasta 15.7, varios grupos que coincidían hasta la coma se reducían a un mismo nombre de permiso, de +modo que los miembros de ``Sales, EMEA`` y ``Sales, APAC`` podían leer los documentos del otro grupo +y los del grupo ``Sales``. En 15.10 cada uno obtiene su propio nombre de permiso y ese acceso entre +grupos no se produce. + +A cambio, **los documentos indexados con el nombre de permiso antiguo dejan de ser visibles para los +miembros de ese grupo**. Si la configuración de permisos de un rastreo contiene un nombre de permiso +antiguo, actualícelo al nuevo y vuelva a rastrear (o reindexar). Si no utiliza ningún grupo cuyo CN +contenga una coma u otro carácter escapado, ningún nombre de permiso cambia. + +Cambio en ``ldap.role.search.user.enabled`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Hasta 15.7, el permiso derivado del nombre de usuario (``role.search.user.prefix`` seguido del +nombre de usuario) se concedía incluso con ``ldap.role.search.user.enabled=false``. A partir de 15.10 +la opción surte efecto y el permiso no se concede cuando está desactivada. + +En una instalación que la tenga en ``false``, los usuarios pierden tras la actualización el permiso +que lleva su propio nombre, por lo que los documentos asignados a un usuario concreto dejan de +aparecer para ese usuario. Para mantener el comportamiento anterior, restaure el valor +predeterminado ``true``. + +Si Había Modificado las Claves de Configuración de /api/v2 +---------------------------------------------------------- + +En 15.8.0, cuatro claves de configuración perdieron su prefijo ``api.v2.``. Sus valores, valores +predeterminados y comportamiento no cambian, pero **no se conserva ningún alias retrocompatible**: +una configuración que permanezca con su nombre antiguo se ignora sin ninguna advertencia y se +aplica el valor predeterminado incluido. + +.. list-table:: + :header-rows: 1 + + * - Hasta 15.7 + - 15.8.0 en adelante + - Valor predeterminado + * - ``api.v2.chat.stream.keepalive.interval.ms`` + - ``api.chat.stream.keepalive.interval.ms`` + - ``15000`` + * - ``api.v2.param.max.length`` + - ``api.param.max.length`` + - ``1000`` + * - ``api.v2.param.max.array.size`` + - ``api.param.max.array.size`` + - ``100`` + * - ``api.v2.click.max.rt`` + - ``api.click.max.timestamp`` + - ``9999999999999`` + +Si estableció alguna de ellas en ``fess_config.properties`` o como argumento de JVM +``-Dfess.config.``, cámbieles el nombre. Solo se ven afectadas las configuraciones +explícitas; una instalación que nunca las modificó no requiere ninguna acción. + +La primera clave controla con qué frecuencia se envía una trama de keep-alive mientras +``POST /api/v2/chat/stream`` espera al modelo, por lo que el modo de búsqueda con IA es donde se +nota una configuración perdida. La última clave también se renombró por precisión: limita el +valor ``rt`` que puede llevar un registro de clic, que es una marca de tiempo y no un tiempo de +respuesta. + + +.. _upgrade-plugin-versions: + +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|. ``bin/fess-setup upgrade plugins`` lo hace para todos los plugins +instalados: instala la versión compilada para este |Fess| y elimina la anterior. Después, reinicie +|Fess|. A continuación, ``bin/fess-setup check`` informa sobre OpenSearch, sus plugins y los +plugins de |Fess| instalados, y termina con el código 1 cuando algo va mal. No lee +``bin/fess.in.sh``, ``/etc/sysconfig/fess`` ni ``/etc/default/fess``, así que, cuando OpenSearch no +está en ``http://localhost:9200``, indique ``--url`` o defina ``SEARCH_ENGINE_HTTP_URL`` en el shell +que lo ejecuta; de lo contrario, informa de que el motor no es accesible. + +:: + + $ bin/fess-setup upgrade plugins + $ bin/fess-setup check + +``upgrade plugins`` solo trata los plugins que ya están instalados. Instale con +``bin/fess-setup install plugin``, como se indica en las secciones anteriores, los plugins que +sustituyen a partes eliminadas de la distribución en 15.10, como ``fess-script-groovy``. + +Si utiliza ``FESS_PLUGINS`` en la versión Docker, actualice la parte de la versión, por ejemplo a +``fess-ds-wikipedia:15.10.0``. + +Procedimientos de Reversión +============================= + +Si la actualización falla, puede revertir con los siguientes procedimientos. + +Paso 1: Detención de la Nueva Versión +-------------------------------------- + +:: + + $ sudo systemctl stop fess.service + $ sudo systemctl stop opensearch.service + +Paso 2: Restauración de la Versión Antigua +------------------------------------------- + +Restaure los archivos de configuración y datos desde el respaldo. + +Para versión RPM/DEB:: + + $ sudo rpm -Uvh --oldpackage --nodeps fess-.rpm + +O:: + + $ sudo dpkg -i fess-.deb + +.. note:: + + ``--nodeps`` es necesario para el RPM. El paquete 15.8.0 requiere los usuarios y grupos ``fess`` y + ``opensearch``, y sin esa opción ``rpm`` rechaza la reversión con ``Failed dependencies: + group(fess) is needed by fess-15.8.0``. + +.. warning:: + + El paquete DEB 15.8.0 no registra ``/etc/fess/*`` como conffile, por lo que ``dpkg -i`` sobrescribe + los archivos que haya editado, como ``/etc/fess/fess_config.properties``, sin conservar una copia. + Restáurelos desde el respaldo que hizo en el Paso 1. + +Paso 3: Restauración de Datos +------------------------------ + +Restaure desde instantánea. OpenSearch debe estar en ejecución y |Fess| detenido: + +1. Inicie OpenSearch:: + + $ sudo systemctl start opensearch.service + +2. Una instantánea no se puede restaurar sobre un índice que existe, así que elimine antes todos los + índices de Fess, incluidos los creados después de la actualización (por ejemplo, con la + reindexación) y el índice ``configsync`` que crea el plugin de OpenSearch. Si elimina solo los + índices que están en la instantánea, un índice creado por la reindexación se queda, ``fess.search`` + apunta a dos índices y 15.8.0 no se inicia:: + + $ curl "http://localhost:9200/_cat/indices/fess*,configsync?h=index" + $ curl -X DELETE "http://localhost:9200/" + + Ejecute la segunda orden para cada índice que liste la primera. + +3. Restaure la instantánea:: + + $ curl -X POST "http://localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true" + +.. note:: + + El directorio de diccionarios debe existir como antes (``configsync.config_path``, con los + archivos de diccionario). En una máquina que lo haya perdido, la restauración termina, pero los + índices que usan los diccionarios se quedan en rojo. + +O restaure el directorio desde el respaldo (use el nombre del archivo que creó en el Paso 1):: + + $ sudo systemctl stop opensearch + $ sudo rm -rf /var/lib/opensearch/data/* + $ sudo tar xzf /backup/opensearch-data-.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 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 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 +------------------------------------------- + +:: + + $ sudo systemctl start opensearch.service + $ sudo systemctl start fess.service + +Verifique el funcionamiento y confirme que volvió a la normalidad. + +Preguntas Frecuentes +==================== + +P: ¿Se puede actualizar sin tiempo de inactividad? +--------------------------------------------------- + +R: La actualización de Fess requiere la detención del servicio. Para minimizar el tiempo de inactividad, considere: + +- Verificar los procedimientos con anticipación en un entorno de prueba +- Hacer el respaldo con anticipación +- Asegurar suficiente tiempo de mantenimiento + +P: ¿Es necesario actualizar también OpenSearch? +------------------------------------------------ + +R: Cada versión de |Fess| requiere una versión específica de OpenSearch. +|Fess| 15.10 es compatible con OpenSearch 3.9.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.9.0). + +Tenga en cuenta que |Fess| 15.10 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: Para una actualización de versión menor de |Fess| (15.x → 15.10) 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. +- **Si usa la búsqueda por propietario o la normalización de kana con un índice de documentos creado + con 15.8 o anterior**: se necesita una reindexación. Consulte :ref:`upgrade-reindex-new-fields`. + +.. 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 +-------------------------------------------------------------------------- + +R: Verifique lo siguiente: + +1. Verifique que OpenSearch esté en ejecución +2. Verifique que exista el índice (``curl http://localhost:9200/_cat/indices``) +3. Vuelva a ejecutar el rastreo + +Próximos Pasos +============== + +Una vez completada la actualización: + +- :doc:`run` - Verificación de inicio y configuración inicial +- :doc:`security` - Revisión de configuración de seguridad +- :doc:`../config/search-semantic` - Configuración y pasos de migración de la búsqueda por + vector de chunks (búsqueda semántica) +- Verifique las notas de lanzamiento para nuevas funciones diff --git a/es/15.10/user/advanced-search.rst b/es/15.10/user/advanced-search.rst new file mode 100644 index 000000000..17bfd03b6 --- /dev/null +++ b/es/15.10/user/advanced-search.rst @@ -0,0 +1,83 @@ +================= +Búsqueda avanzada +================= + +La pantalla de búsqueda avanzada permite realizar búsquedas más avanzadas combinando varias condiciones. + +Cómo utilizar +------------- + +Se puede acceder a la pantalla de búsqueda avanzada desde el enlace «Búsqueda avanzada» en las opciones de búsqueda de la pantalla de búsqueda. + +|image0| + +Cuando se abre desde la pantalla de resultados de búsqueda, las palabras clave de búsqueda ya ingresadas se trasladan al campo «Contiene todas las palabras». Ingrese las condiciones en cada campo y presione el botón de búsqueda en la parte inferior de la página. Los múltiples campos ingresados se combinan en una única condición de búsqueda. + +Lista de elementos +------------------ + +Contiene todas las palabras +::::::::::::::::::::::::::: + +Busca documentos que contengan todas las palabras ingresadas (búsqueda AND). +Se pueden especificar varias palabras separadas por espacios. + +Coincidencia exacta incluyendo el orden de las palabras +::::::::::::::::::::::::::::::::::::::::::::::::::::::::: + +Busca documentos que contengan exactamente la cadena de texto ingresada, incluido el orden de las palabras (búsqueda de frase). +Dado que toda la cadena, incluidos los espacios, se trata como una única frase, no se puede dividir en palabras individuales para la búsqueda. + +Contiene alguna de las palabras +::::::::::::::::::::::::::::::: + +Busca documentos que contengan alguna de las palabras ingresadas (búsqueda OR). +Se pueden especificar varias palabras separadas por espacios. + +No contiene palabras +:::::::::::::::::::: + +Busca documentos que no contengan las palabras ingresadas. +Se pueden especificar varias palabras separadas por espacios, y todas las palabras especificadas se excluyen de los resultados de búsqueda. + +Número de resultados mostrados +:::::::::::::::::::::::::::::: + +Especifica el número de resultados de búsqueda que se muestran por página. Puede elegir entre 10, 20, 30, 40, 50 o 100. Si no se especifica, se utiliza el número de resultados mostrados predeterminado (valor inicial 10). + +Ordenar +::::::: + +Especifica el criterio para ordenar los resultados de búsqueda. Puede elegir entre Por puntuación, Nombre de archivo, Fecha, Tamaño y Última modificación, cada uno en orden ascendente o descendente. La ordenación por Clics o Favoritos está disponible cuando la función correspondiente está habilitada. + +Idioma preferido +:::::::::::::::: + +Especifica el idioma preferido para los resultados de búsqueda. Se pueden seleccionar varios idiomas. Si se selecciona «Todos los idiomas», no se prioriza ningún idioma específico. + +Etiqueta +:::::::: + +Filtra la búsqueda por etiqueta. Se pueden seleccionar varias etiquetas. No se muestra si no hay etiquetas registradas o si no hay etiquetas que el usuario actual pueda ver. + +Fecha de actualización +:::::::::::::::::::::: + +Filtra la búsqueda por la fecha y hora de actualización del documento. Puede elegir entre Cualquier fecha, Últimas 24 horas, Última semana, Último mes y Último año. + +Formato de archivo +:::::::::::::::::: + +Filtra la búsqueda por el formato de archivo del documento. Puede elegir entre Todos los formatos, HTML, PDF, MS Word, MS Excel y MS PowerPoint. + +Objetivo de búsqueda +:::::::::::::::::::: + +Especifica dónde buscar. Puede elegir entre Página completa, Título de la página y URL de la página. Si se selecciona la opción de título o URL, las palabras ingresadas se buscan únicamente en el título o en la URL respectivamente. + +Sitio o dominio +::::::::::::::: + +Filtra la búsqueda por el sitio o dominio ingresado. Especifíquelo cuando desee buscar únicamente documentos contenidos en un sitio o dominio específico. + +.. |image0| image:: ../../../resources/images/en/15.10/user/advanced-search-1.png diff --git a/es/15.10/user/chat-search.rst b/es/15.10/user/chat-search.rst new file mode 100644 index 000000000..5f3281f6f --- /dev/null +++ b/es/15.10/user/chat-search.rst @@ -0,0 +1,286 @@ +==================== +Modo de búsqueda IA +==================== + +Descripción general +==================== + +La función de modo de búsqueda IA (chat RAG) de |Fess| le permite buscar información en un +formato de conversación natural, además de la búsqueda tradicional por palabras clave. +Al introducir una pregunta, el asistente de IA busca los documentos relacionados y genera +una respuesta fácil de entender basada en su contenido. + +.. note:: + El modo de búsqueda IA está deshabilitado de forma predeterminada. Para poder utilizarlo, + el administrador del sistema debe habilitar la función y configurar previamente un + proveedor de LLM (modelo de lenguaje de gran tamaño). + Consulte :doc:`../config/rag-chat` y :doc:`../config/llm-overview` para obtener información + sobre cómo configurarlo. + +Características del modo de búsqueda IA +========================================= + +Búsqueda en formato de conversación +------------------------------------- + +En lugar de pensar en palabras clave, puede preguntar como en una conversación cotidiana. + +Ejemplos: + +- "Explíqueme cómo instalar Fess" +- "¿Cómo hago para rastrear archivos?" +- "¿Qué hacer cuando no se muestran los resultados de búsqueda?" + +Respuestas que comprenden el contexto +--------------------------------------- + +El asistente de IA analiza la intención de la pregunta, busca los documentos relacionados y +extrae la información necesaria de varios resultados de búsqueda, presentándola de forma +organizada en la respuesta. + +Indicación clara de las fuentes +----------------------------------- + +En la parte inferior de la respuesta se muestra una lista de los documentos en los que se +basa la respuesta, bajo el título "Fuentes". Cada fuente es un enlace numerado; al hacer clic +en él puede consultar directamente el documento original. +Además, el cuerpo de la respuesta puede incluir citas numeradas como ``[1]`` o ``[2]``, que +corresponden a los números de la lista de fuentes. + +Continuidad de la conversación +--------------------------------- + +No es necesario terminar tras una sola pregunta: puede continuar la conversación. +El asistente de IA responde a las preguntas adicionales teniendo en cuenta el contexto de las +preguntas y respuestas anteriores. + +Cómo utilizar la búsqueda con chat +==================================== + +Abrir el modo de búsqueda IA +------------------------------- + +1. Abra la pantalla de búsqueda de |Fess| +2. Haga clic en el enlace "Búsqueda IA" (icono de robot) de la barra de navegación superior +3. Se mostrará la pantalla del modo de búsqueda IA + +.. note:: + El enlace "Búsqueda IA" solo se muestra cuando el modo de búsqueda IA está habilitado y + hay un proveedor de LLM disponible. Si el enlace no aparece, consulte + `Preguntas frecuentes`_. + +Introducir una pregunta +-------------------------- + +1. Introduzca la pregunta en el cuadro de texto de la parte inferior de la pantalla (hasta + 4000 caracteres por pregunta) +2. Haga clic en el botón "Enviar mensaje" (icono de avión de papel) o pulse la tecla Enter +3. El asistente de IA comenzará a generar la respuesta + +.. note:: + Si desea insertar un salto de línea, pulse Shift+Enter en lugar de Enter. + +.. note:: + La generación de la respuesta puede tardar entre varios segundos y algo más de diez + segundos. Mientras se procesa, la etapa actual se muestra mediante un indicador de + progreso (Analizar → Buscar → Evaluar → Obtener → Responder), junto con mensajes como + "Pensando...", "Buscando...", "Verificando resultados...", "Obteniendo documentos..." o + "Generando respuesta...". Cuando la búsqueda finaliza, también se muestra el número de + documentos encontrados. + +Comprobar la respuesta +-------------------------- + +Se muestra la respuesta del asistente de IA. La respuesta incluye la siguiente información: + +- **Cuerpo de la respuesta**: la respuesta a la pregunta (con formato Markdown) +- **Fuentes**: una lista de enlaces a los documentos en los que se basa la respuesta + (enlaces numerados; al hacer clic se abre el documento original en otra pestaña) + +El cuerpo de la respuesta puede incluir números de cita como ``[1]`` o ``[2]``, que +corresponden a los números de la lista de fuentes. +Cada respuesta tiene un botón de copiar que permite copiar su contenido al portapapeles. + +.. note:: + La IA utiliza como base de la respuesta únicamente los documentos superiores que + considera más relevantes entre los resultados de búsqueda. Por este motivo, el número de + fuentes puede ser menor que el número de documentos encontrados en la búsqueda. + +Acotar el ámbito de búsqueda +-------------------------------- + +Según el tema, puede utilizar el botón "Filtro" situado en la parte superior de la pantalla +para acotar el ámbito de búsqueda mediante condiciones como etiquetas, tipo de archivo, fecha +de actualización o tamaño. Esto resulta útil cuando desea consultar a la IA únicamente sobre +un conjunto específico de documentos. + +Continuar la conversación +------------------------------ + +Si tiene preguntas adicionales, puede continuar preguntando sin más: + +- "¿Podría explicarlo con más detalle?" +- "¿Hay otra forma de hacerlo?" +- "Más información sobre XXX" + +El asistente de IA responde teniendo en cuenta el contexto de la conversación anterior. + +Iniciar una nueva conversación +----------------------------------- + +Si desea preguntar sobre otro tema, haga clic en el botón "Nueva conversación" (icono +). +Esto borra el historial de la conversación anterior y le permite iniciar una nueva +conversación. + +Consejos para hacer preguntas eficaces +======================================== + +Hacer preguntas específicas +------------------------------- + +Las preguntas específicas obtienen respuestas más adecuadas que las preguntas ambiguas. + +.. list-table:: + :header-rows: 1 + :widths: 50 50 + + * - Pregunta ambigua + - Pregunta específica + * - ¿Cómo se configura? + - ¿Cómo cambio la configuración de memoria de Fess? + * - Aparece un error + - Al buscar aparece el error "no se encuentra el índice" + * - Sobre el crawling + - ¿Cómo configuro las exclusiones al rastrear un sitio web? + +Incluir información de contexto +----------------------------------- + +Incluir la situación o el propósito ayuda a obtener respuestas más adecuadas. + +Buenos ejemplos: + +- "Estoy ejecutando Fess en un entorno Docker. Quiero cambiar la ubicación donde se guardan + los registros, ¿cómo puedo hacerlo?" +- "Es la primera vez que uso Fess. ¿Qué debo hacer primero?" + +Hacer preguntas paso a paso +------------------------------- + +Los problemas complejos son más fáciles de entender si se preguntan paso a paso. + +1. "¿Puedo rastrear archivos compartidos con Fess?" +2. "Explíqueme cómo conectarme mediante el protocolo SMB" +3. "¿Qué debo hacer si la carpeta compartida requiere autenticación?" + +Preguntas frecuentes +====================== + +P: No se muestra el modo de búsqueda IA +----------------------------------------- + +R: Es posible que el modo de búsqueda IA no esté habilitado. +El enlace "Búsqueda IA" solo se muestra cuando la función está habilitada +(``rag.chat.enabled=true``) y hay un proveedor de LLM (OpenAI, Gemini, Ollama, etc.) +configurado y disponible. Consulte con el administrador del sistema si el modo de búsqueda +IA está habilitado y si el proveedor de LLM está configurado correctamente (para más +información, consulte :doc:`../config/rag-chat`). + +P: La respuesta tarda en mostrarse +-------------------------------------- + +R: Como la IA analiza la pregunta y busca y evalúa los documentos antes de generar la +respuesta, el proceso puede tardar entre varios segundos y algo más de diez segundos. +Mientras se procesa, se muestra la etapa actual ("Pensando...", "Buscando...", +"Verificando resultados...", "Obteniendo documentos...", "Generando respuesta..."). + +P: Las fuentes parecen incorrectas +-------------------------------------- + +R: Haga clic en el enlace de la fuente para verificar el documento original. +Aunque la IA genera las respuestas a partir de los resultados de búsqueda, puede haber +errores de interpretación. Se recomienda confirmar siempre la información importante en el +documento original. + +P: Parece que se ha olvidado la conversación anterior +---------------------------------------------------------- + +R: Es posible que la sesión de la conversación haya expirado. +Si no se realiza ninguna operación durante un período determinado (30 minutos de forma +predeterminada), el historial de la conversación se borra. +Además, como el historial de la conversación se conserva temporalmente en la memoria del +servidor, también se pierde al reiniciar el servidor. +En ese caso, inicie una nueva conversación. + +.. note:: + La "sesión" a la que se hace referencia aquí es la sesión de conversación del modo de + búsqueda IA, distinta de la sesión de inicio de sesión en |Fess|. + +P: No obtengo respuesta para una pregunta concreta +-------------------------------------------------------- + +R: Existen varias causas posibles: + +- No hay información relacionada en los documentos que se están buscando +- La pregunta es ambigua y no permite realizar una búsqueda adecuada +- Se ha alcanzado el límite de tasa (se ha superado el número máximo de solicitudes por + minuto o el número máximo de ejecuciones simultáneas) + +Intente reformular la pregunta o espere un momento antes de volver a intentarlo. + +P: ¿Existe un límite de caracteres para la entrada? +--------------------------------------------------------- + +R: El límite es de 4000 caracteres por pregunta. Debajo del cuadro de texto se muestra un +contador de caracteres, que cambia a una advertencia cuando se acerca al límite. Si la +pregunta es larga, resúmala centrándose en los puntos clave. + +P: ¿Puedo hacer preguntas en idiomas distintos al español? +----------------------------------------------------------- + +R: Sí, en muchos casos puede hacer preguntas también en inglés o en otros idiomas. +La IA intenta responder en el mismo idioma basándose en el idioma de visualización del +navegador o de la pantalla, en la medida de lo posible. No obstante, esto se realiza sobre +una base de mejor esfuerzo, por lo que, dependiendo de la situación, es posible que la +respuesta no se genere en el idioma esperado. + +Notas +====== + +Sobre las respuestas de la IA +--------------------------------- + +- Las respuestas de la IA se generan a partir de los resultados de búsqueda +- No se garantiza la exactitud de las respuestas +- Para decisiones importantes, confirme siempre la información en el documento original + (fuente) +- Para obtener la información más reciente, consulte la documentación oficial + +Sobre la privacidad +------------------------ + +- Las preguntas introducidas se utilizan para la búsqueda y para el procesamiento de IA + realizado por el proveedor de LLM configurado +- Si se configura para utilizar un servicio de LLM externo (como OpenAI o Gemini), el + contenido de la pregunta y los resultados de búsqueda se envían a dicho servicio. Si desea + que el procesamiento se realice únicamente dentro de la organización, consulte con el + administrador sobre el uso de un proveedor que funcione de forma local (como Ollama) +- El historial de la conversación se conserva temporalmente en la memoria del servidor y se + elimina cuando la sesión expira, cuando se ejecuta "Nueva conversación", o cuando se + reinicia el servidor +- Al igual que en la búsqueda, se aplica el control de acceso basado en roles (permisos) y + etiquetas, por lo que los documentos que no se pueden visualizar no forman parte de la + respuesta +- Según la configuración del sistema, es posible que se registren logs + +Información de referencia +============================ + +- :doc:`../config/rag-chat` - Configuración de la función de modo de búsqueda IA (para + administradores) +- :doc:`../config/llm-overview` - Configuración del proveedor de LLM +- :doc:`../api/api-chat` - Chat API (uso mediante programación) +- :doc:`search-and` - Cómo utilizar la búsqueda AND +- :doc:`search-not` - Cómo utilizar la búsqueda NOT +- :doc:`search-field` - Cómo utilizar la búsqueda por campo +- :doc:`advanced-search` - Funciones de búsqueda avanzada diff --git a/es/15.10/user/index.rst b/es/15.10/user/index.rst new file mode 100644 index 000000000..3b200a21d --- /dev/null +++ b/es/15.10/user/index.rst @@ -0,0 +1,29 @@ +Guía de Usuario de |Fess| +========================= + +Cómo escribir consultas de búsqueda en |Fess|: AND, OR y NOT, búsqueda +por campo y por etiqueta, ordenación, comodines, rangos, boosting, +búsqueda difusa, búsqueda de proximidad y búsqueda geográfica. + +.. toctree:: + :maxdepth: 2 + + intro + search-and + search-or + search-not + search-bangs + search-label + search-field + search-sort + search-wildcard + search-range + search-boost + search-fuzzy + search-proximity + search-geo + search-additional + role-search + special-char + advanced-search + chat-search diff --git a/es/15.10/user/intro.rst b/es/15.10/user/intro.rst new file mode 100644 index 000000000..e54b8d075 --- /dev/null +++ b/es/15.10/user/intro.rst @@ -0,0 +1,49 @@ +========================== +Introducción a la búsqueda +========================== + +Público objetivo +================ + +|Fess| es un servidor de búsqueda empresarial que permite realizar búsquedas de texto completo en documentos de sitios web, archivos, bases de datos, entre otros. + +Este documento está dirigido a usuarios que utilizan |Fess|. + +Antes de leer +============= + +Este documento explica cómo realizar búsquedas con |Fess|. Además de la búsqueda básica por palabras clave, también se explica la búsqueda refinada mediante la pantalla de búsqueda avanzada y el modo de búsqueda IA, que permite buscar información de forma natural, como en una conversación. Se requieren conocimientos básicos de operación de computadoras. + +Acceso en línea +=============== + +Para descargas, servicios profesionales, soporte y otra información para desarrolladores, visite: + +- Sitio del proyecto: https://fess.codelibs.org/ + +Contacto para soporte técnico +============================== + +Si tiene preguntas técnicas sobre este producto y no encuentra solución en la documentación, visite: + +- Issues: + `https://github.com/codelibs/fess/issues `__ + +Soporte comercial +----------------- + +Si necesita soporte comercial para este producto, incluyendo asistencia técnica y mantenimiento, consulte con `N2SM, Inc. `__ + +Referencias a sitios web de terceros relacionados +================================================== + +El proyecto |Fess| no se hace responsable de la validez de los sitios web de terceros mencionados en este documento. El proyecto |Fess| no garantiza, ni asume responsabilidad u obligación alguna por el contenido, publicidad, productos, servicios u otros materiales disponibles a través de dichos sitios o recursos. El proyecto |Fess| no será responsable de ningún daño o perjuicio derivado del uso o la confianza en el contenido, publicidad, productos, servicios u otros materiales disponibles a través de dichos sitios o recursos. + +Cómo enviar comentarios y sugerencias +====================================== + +El proyecto |Fess| se esfuerza por mejorar este documento y agradece los comentarios y sugerencias de los lectores. + +- Issues: + `https://github.com/codelibs/fess-docs/issues `__ + diff --git a/es/15.10/user/role-search.rst b/es/15.10/user/role-search.rst new file mode 100644 index 000000000..1c638610c --- /dev/null +++ b/es/15.10/user/role-search.rst @@ -0,0 +1,58 @@ +=================== +Búsqueda por roles +=================== + +|Fess| ofrece una función de gestión de usuarios que permite a los usuarios que han iniciado sesión realizar búsquedas en función de los roles a los que pertenecen. Los usuarios administrados por |Fess| pueden, tras iniciar sesión, utilizar la búsqueda por roles y cambiar su propia contraseña. + +En la búsqueda por roles, se comparan los permisos configurados en el contenido (rol, grupo, usuario) con los permisos que posee el usuario que realiza la búsqueda, y en los resultados de búsqueda solo se muestran los contenidos cuyo acceso está permitido. Para obtener información sobre cómo crear roles y usuarios, así como sobre cómo asignar permisos al contenido, y en general sobre la configuración de la búsqueda basada en roles, consulte :doc:`../config/security-role`. + + +Método de búsqueda +------------------- + +Si se han configurado roles y el contenido se ha rastreado e indexado en ese estado, los resultados de búsqueda se pueden mostrar únicamente a los usuarios que posean ese rol. +Si el usuario ha iniciado sesión, la búsqueda se realiza en función de los roles y grupos a los que pertenece. +Si no ha iniciado sesión, la búsqueda se realiza como usuario guest, y solo se muestran los contenidos publicados para guest. + +.. note:: + La búsqueda de un usuario que ha iniciado sesión se realiza únicamente con los permisos del propio usuario y de los roles y grupos a los que pertenece; no incluye el contenido publicado para guest (``{role}guest``). Por ello, el contenido publicado únicamente para guest se muestra a los visitantes que no han iniciado sesión, pero no a los usuarios que sí la han iniciado (incluidos los usuarios que no tienen ningún rol ni grupo). Para que el contenido también sea visible para los usuarios que han iniciado sesión, configure en los permisos de la configuración de rastreo, además de ``{role}guest``, el rol que tienen esos usuarios (si desea mostrarlo a todos, el rol asignado a todos los usuarios). + +Inicio de sesión +----------------- + +Al hacer clic en el enlace de «Iniciar sesión» que aparece en la parte superior de la pantalla de búsqueda, se muestra la pantalla de inicio de sesión. Al introducir el nombre de usuario y la contraseña e iniciar sesión, se vuelve a la pantalla de búsqueda, y a partir de ese momento las búsquedas se realizan en función de los roles a los que pertenece ese usuario. + +.. note:: + Si se ha integrado con el inicio de sesión único (SSO) o con LDAP, el inicio de sesión se realiza mediante el método de autenticación correspondiente. Además, la visibilidad del enlace de inicio de sesión se puede modificar mediante la configuración. + +Cambio de contraseña +---------------------- + +Después de iniciar sesión, al hacer clic en el nombre de usuario que aparece en la parte superior de la pantalla de búsqueda, se muestra un menú. + +|image0| + +Al hacer clic en «Cambiar contraseña» dentro del menú, se muestra la pantalla de cambio de contraseña. + +|image1| + +Introduzca la contraseña actual, la nueva contraseña y la confirmación de la nueva contraseña (reintroducida), y haga clic en el botón «Actualizar» para actualizar la contraseña. +Al cambiar la contraseña se cierra la sesión, así que vuelva a iniciar sesión con la nueva contraseña. +Esta pantalla es la página ``/profile`` del tema de la pantalla de búsqueda, y la contraseña se cambia con ``POST /api/v2/auth/password`` (consulte :doc:`../api/api-auth`). + +.. note:: + El menú «Cambiar contraseña» solo se muestra para los usuarios administrados por |Fess| (y para los usuarios LDAP a los que se les ha permitido editar). No se muestra para los usuarios autenticados mediante inicio de sesión único. + Es posible que la nueva contraseña deba cumplir una política de contraseñas, como la longitud o los tipos de caracteres permitidos. + +Cerrar sesión +-------------- + +Estando conectado, puede cerrar sesión haciendo clic en el nombre de usuario que aparece en la parte superior de la pantalla de búsqueda y seleccionando «Cerrar sesión» en el menú. +Si el usuario tiene privilegios de administrador, también puede ir a la pantalla de administración seleccionando «Administración» en el mismo menú. + + + +.. |image0| image:: ../../../resources/images/en/15.10/user/role-search-1.png +.. pdf :width: 200 px +.. |image1| image:: ../../../resources/images/en/15.10/user/role-search-2.png +.. pdf :width: 300 px diff --git a/es/15.10/user/search-additional.rst b/es/15.10/user/search-additional.rst new file mode 100644 index 000000000..042b4f49c --- /dev/null +++ b/es/15.10/user/search-additional.rst @@ -0,0 +1,30 @@ +=============================== +Condiciones de búsqueda ocultas +=============================== + +Puede utilizar el parámetro ``ex_q`` cuando desee transportar una condición de búsqueda específica sin mostrar su texto en la pantalla. Las condiciones especificadas en ``ex_q`` no se muestran en el campo de entrada de búsqueda y se conservan incluso cuando la pantalla se actualiza mediante la paginación o el filtrado por facetas. + +En ``ex_q`` puede utilizar la misma sintaxis de consulta que en el término de búsqueda habitual (``q``): el formato ``field:value``, frases, especificaciones de rango, operadores como ``OR``, entre otros. La condición especificada se combina de forma predeterminada con la condición de ``q`` mediante AND al ejecutar la búsqueda. Es decir, los documentos que no coincidan con la condición de ``ex_q`` se excluyen de los resultados de búsqueda. + +Cómo utilizar +------------- + +Al ejecutar una búsqueda (por ejemplo, desde un formulario de búsqueda), agregue el valor de ``ex_q`` como campo de formulario oculto o como parámetro de consulta de la URL, y ejecute la búsqueda. Esto le permite buscar sin mostrar la condición en la pantalla. + +Puede especificar ``ex_q`` varias veces. Como en el siguiente ejemplo, si pasa varios valores de ``ex_q``, cada uno se agrega como condición de búsqueda (los valores vacíos o duplicados se ignoran). + +.. code-block:: none + + /search?q=keyword&ex_q=label:manual&ex_q=filetype:pdf + +Conservación durante la paginación +----------------------------------- + +Fess agrega automáticamente el valor de ``ex_q`` a los enlaces de paginación (como página siguiente y página anterior) y a los enlaces de filtrado por facetas. Por ello, la condición de ``ex_q`` se conserva incluso cuando la pantalla se actualiza mediante estas operaciones. + +Por otro lado, si introduce una palabra clave en el campo de entrada de búsqueda estándar (el cuadro de búsqueda) y vuelve a buscar, ``ex_q`` no se traslada. Si desea que la condición se conserve también a través del cuadro de búsqueda, prepare un campo oculto ``ex_q`` en su propio formulario de búsqueda y envíe ``ex_q`` en cada búsqueda. + +.. note:: + + * Si la longitud de un valor individual de ``ex_q`` supera ``query.max.length`` (valor predeterminado: 1000 caracteres), ese valor se ignora sin generar un error. + * ``ex_q`` puede utilizarse no solo en las búsquedas desde la pantalla web, sino también con la API de búsqueda (``/api/v2``). En la API se aplican el límite máximo de elementos ``ex_q`` por solicitud (``api.v2.param.max.array.size``, valor predeterminado: 100) y el límite máximo de longitud de cada elemento (``api.v2.param.max.length``, valor predeterminado: 1000 caracteres). diff --git a/es/15.10/user/search-and.rst b/es/15.10/user/search-and.rst new file mode 100644 index 000000000..c6c6e598c --- /dev/null +++ b/es/15.10/user/search-and.rst @@ -0,0 +1,46 @@ +============ +Búsqueda AND +============ + +Cuando desea buscar documentos que contengan todos los términos de búsqueda especificados, puede utilizar la búsqueda AND. Si escribe múltiples palabras separadas por espacios en el campo de entrada de búsqueda, por defecto se realizará una búsqueda AND, por lo que puede omitir AND y obtener el mismo resultado. + +Cómo utilizar +------------- + +Para utilizar la búsqueda AND, escriba AND entre los términos de búsqueda. AND +debe escribirse en mayúsculas y requiere espacios antes y después. +AND también se puede omitir. + +Por ejemplo, si desea buscar documentos que contengan "Término1" y "Término2", ingrese lo siguiente en el formulario de búsqueda: + +:: + + Término1 AND Término2 + +Si omite AND y escribe de la siguiente manera, obtendrá el mismo resultado: + +:: + + Término1 Término2 + +También es posible conectar tres o más términos de búsqueda con AND. + +:: + + Término1 AND Término2 AND Término3 + +.. note:: + + AND debe escribirse en mayúsculas. Si se escribe en minúsculas como ``and``, no se trata como un operador, sino que se busca como la palabra de búsqueda habitual "and". ``&&`` también se puede utilizar con el mismo significado que AND. + +Utilizando paréntesis ``( )``, puede combinar la búsqueda AND con otras condiciones de búsqueda. Por ejemplo, si desea buscar documentos que contengan "Término1", y además contengan "Término2" o "Término3", ingrese lo siguiente: + +:: + + Término1 AND (Término2 OR Término3) + +También es posible realizar una búsqueda AND especificando un campo. En el siguiente ejemplo, se buscan documentos que contengan "Término1" en el campo title, y "Término2" en el campo content. + +:: + + title:Término1 AND content:Término2 diff --git a/es/15.10/user/search-bangs.rst b/es/15.10/user/search-bangs.rst new file mode 100644 index 000000000..7d6095b18 --- /dev/null +++ b/es/15.10/user/search-bangs.rst @@ -0,0 +1,80 @@ +========================================= +Búsqueda con bangs (buscar en otro sitio) +========================================= + +Un bang envía una búsqueda a otro sitio en lugar de buscar en |Fess|. Funciona como los bangs de DuckDuckGo: añada ``!`` y una palabra clave corta a la consulta, y |Fess| envía el resto de la consulta al sitio que representa esa palabra clave. + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Consulta + - Destino + * - ``airplane !g`` + - Google, buscando ``airplane`` + * - ``!w Ohm's law`` + - Wikipedia, buscando ``Ohm's law`` + * - ``!g`` + - La página de inicio de Google + * - ``airplane !unknown`` + - |Fess|, como una búsqueda normal (``!`` significa NOT, véase :doc:`search-not`) + +Los bangs los proporciona el plugin ``fess-webapp-bangs``, que requiere |Fess| 15.10 o posterior. Instálelo desde [Sistema > Plugin] en la consola de administración o con ``bin/fess-setup install plugin fess-webapp-bangs`` (véase :doc:`../admin/plugin-guide`) y reinicie |Fess|. + +Cómo se reconoce un bang +======================== + +- Un bang es ``!`` seguido de una palabra clave, escrito como una palabra independiente. La palabra clave no distingue mayúsculas de minúsculas. +- El bang se elimina de la consulta y el resto de la consulta se envía a la URL del bang. +- Si una consulta contiene varios bangs definidos, solo cuenta el primero. +- Una palabra clave que no está definida no es un bang. ``!unknown`` se busca como de costumbre y excluye la palabra ``unknown``. +- ``-g`` y ``NOT g`` siguen excluyendo la palabra ``g``. Solo ``!g`` es un bang. + +La página de búsqueda y ``/api/v2/search`` siguen la redirección: la API devuelve ``redirect_url`` (véase :doc:`../api/api-search`) y el tema ``bootstrap`` incluido con |Fess| navega a esa URL. Otros temas necesitan el mismo tratamiento. + +Los llamadores que no pueden redirigir, como el chat, MCP, las API JSON v1 y clásica y la búsqueda de la consola de administración, no envían la búsqueda a otro sitio. Eliminan el bang y buscan el resto de la consulta. + +Definir bangs +============= + +Los bangs se definen con la propiedad del sistema ``bangs.definitions``. Establézcala en ``app/WEB-INF/conf/system.properties`` o pásela como ``-Dfess.system.bangs.definitions=...``. Un cambio en ``system.properties`` se aplica sin reiniciar |Fess|. + +El valor es una lista de entradas ``palabra_clave=URL`` separadas por espacios en blanco. En la URL, ``{query}`` se sustituye por el resto de la consulta codificado como URL: + +:: + + bangs.definitions=g=https://www.google.com/search?q={query} w=https://en.wikipedia.org/wiki/Special:Search?search={query} + +- Una palabra clave no puede contener espacios en blanco, ``(``, ``)``, ``!``, ``"``, ``=`` ni ``:``. +- Solo se aceptan URL absolutas ``http`` o ``https``. +- Una entrada que no cumple estas reglas no se utiliza. Se escribe una advertencia en el registro de |Fess| y las demás entradas siguen vigentes. +- Si se define dos veces la misma palabra clave, se usa la primera definición. +- Un valor vacío desactiva todos los bangs. + +Cuando ``bangs.definitions`` no está establecida, están disponibles los cinco bangs siguientes: + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Palabra clave + - Sitio + * - ``g`` + - Google + * - ``b`` + - Bing + * - ``ddg`` + - DuckDuckGo + * - ``w`` + - Wikipedia (inglés) + * - ``gh`` + - GitHub + +Al establecer ``bangs.definitions`` se sustituye esta lista. Para conservar los bangs predeterminados y añadir uno más, escriba todas las entradas que necesite. + +Véase también +============= + +- :doc:`search-not` - Búsqueda NOT +- :doc:`special-char` - Caracteres especiales y escape +- :doc:`../api/api-search` - API de búsqueda diff --git a/es/15.10/user/search-boost.rst b/es/15.10/user/search-boost.rst new file mode 100644 index 000000000..f79ffc824 --- /dev/null +++ b/es/15.10/user/search-boost.rst @@ -0,0 +1,46 @@ +================== +Búsqueda con boost +================== + +Búsqueda con boost (búsqueda ponderada) +======================================= + +Cuando desea priorizar un término de búsqueda específico entre los términos de búsqueda, puede utilizar la búsqueda con boost. Al usar la búsqueda con boost, es posible buscar según la importancia de los términos de búsqueda. + +Cómo utilizar +------------- + +Para utilizar la búsqueda con boost, debe especificar el valor de boost (valor de ponderación) en el formato "^valor_de_boost" inmediatamente después del término de búsqueda. No debe haber ningún espacio entre el término de búsqueda y el valor de boost. + +Por ejemplo, si desea buscar "manzana naranja" pero quiere priorizar más "manzana", ingrese lo siguiente en el formulario de búsqueda: + +:: + + manzana^100 naranja + +En este ejemplo, el valor de boost se aplica únicamente a "manzana" y no se aplica a "naranja". + +Valor de boost +-------------- + +El valor de boost se especifica como un número. Puede indicar no solo números enteros, sino también decimales como ``2.5``. + +- Si especifica un valor mayor que 1, el peso de ese término de búsqueda aumenta. +- Si especifica un valor mayor que 0 y menor que 1 (por ejemplo, ``0.5``), el peso de ese término de búsqueda disminuye. + +El valor de boost no determina de forma absoluta la puntuación de los resultados de búsqueda, sino que ajusta el peso relativo respecto a otros términos de búsqueda. + +Combinación con otra sintaxis de búsqueda +----------------------------------------- + +La búsqueda con boost puede combinarse con otra sintaxis de búsqueda. Por ejemplo, también es posible añadir un valor de boost a un término de búsqueda que especifica un campo. + +:: + + title:manzana^100 naranja + +En este ejemplo, como se aplica el operador predeterminado (AND) cuando se escriben varios términos de búsqueda, solo se buscan los documentos que contienen "manzana" en el campo title y que además contienen "naranja". Si desea priorizar los documentos que contienen "manzana" pero conservar también en los resultados los que no la contienen, combine los términos con OR. + +:: + + title:manzana^100 OR naranja diff --git a/es/15.10/user/search-field.rst b/es/15.10/user/search-field.rst new file mode 100644 index 000000000..a1030c01d --- /dev/null +++ b/es/15.10/user/search-field.rst @@ -0,0 +1,136 @@ +================================================= +Búsqueda por campo (acotar por título, URL y más) +================================================= + +Búsqueda con especificación de campos +====================================== + +Al realizar una búsqueda con especificación de campos (búsqueda por campo) dirigida únicamente a un campo concreto, puede acotar los resultados, por ejemplo, buscando solo en el título o solo en la URL. Los resultados rastreados por |Fess| se almacenan en campos individuales como título y contenido. Puede buscar especificando estos campos. Al especificar campos, puede definir condiciones de búsqueda detalladas, como por tipo de documento o por tamaño. + +Campos disponibles +------------------ + +Por defecto, puede buscar especificando los siguientes campos: + +.. list-table:: + :header-rows: 1 + + * - Nombre del campo + - Descripción + - Tipo de dato + * - url + - URL rastreada + - Palabra clave + * - host + - Nombre de host incluido en la URL rastreada + - Palabra clave + * - site + - Cadena de la URL sin el esquema ni la cadena de consulta (nombre de host y ruta). Se busca mediante coincidencia de prefijo + - Palabra clave + * - title + - Título + - Texto + * - content + - Contenido + - Texto + * - content_length + - Tamaño del documento (en bytes) + - Numérico + * - last_modified + - Fecha y hora de la última modificación del documento + - Fecha y hora + * - timestamp + - Fecha y hora de registro del documento (si no se puede obtener la fecha y hora de última modificación, se utiliza la hora de ejecución del rastreo) + - Fecha y hora + * - mimetype + - Tipo MIME del documento (por ejemplo, ``text/html``) + - Palabra clave + * - filetype + - Tipo de archivo determinado a partir del tipo MIME (por ejemplo, ``html``, ``word``, ``pdf``; si no corresponde a ninguno, ``others``) + - Palabra clave + * - filename + - Nombre de archivo al final de la ruta de la URL + - Palabra clave + * - label + - Valor de la etiqueta asignada al documento + - Palabra clave + * - lang + - Código de idioma del documento (por ejemplo, ``ja``, ``en``) + - Palabra clave + * - anchor + - URLs de enlace extraídas de una página HTML (solo en el rastreo web) + - Palabra clave + * - click_count + - Número de clics en el documento + - Numérico + * - favorite_count + - Número de veces que el documento se agregó a favoritos + - Numérico + * - owner + - Nombre de cuenta del propietario del archivo + - Palabra clave + * - last_modifier + - Última persona que modificó el archivo + - Palabra clave + +Tabla: Lista de campos disponibles + +El "tipo de dato" indica la diferencia en el método de búsqueda según cada campo. + +* Palabra clave: se realiza una búsqueda de coincidencia exacta sobre el valor completo. También se puede combinar con la búsqueda con comodines o la búsqueda por prefijo. +* Texto: se realiza una búsqueda de texto completo sobre los términos divididos mediante análisis morfológico, entre otros. Corresponde a campos como title y content. +* Numérico y fecha y hora: se puede utilizar la :doc:`Búsqueda por rango de valores `. + +Si no se especifica ningún campo, la búsqueda se realiza sobre los campos title y content. Según la configuración, también es posible agregar campos adicionales como objetivo de búsqueda. + +.. note:: + Según el objetivo del rastreo, hay campos en los que no se registra ningún valor. Por ejemplo, anchor solo se registra durante el rastreo web. lang se toma del atributo de idioma del HTML o del idioma detectado en el texto del documento; no se registra si no se puede detectar ningún idioma o si el idioma detectado no figura en ``supported.languages``. Además, también se pueden especificar campos como segment (el ID de sesión que representa la unidad de ejecución del rastreo) o doc_id (el ID interno asignado por el sistema), aunque normalmente no se utilizan en las búsquedas habituales. + +owner y last_modifier se registran al rastrear servidores de archivos y similares. owner contiene el +nombre de cuenta del propietario del archivo obtenido en rastreos SMB, de sistema de archivos y FTP +(un valor como ``DOMAIN\alice`` pasa a ser ``alice``). last_modifier contiene el último autor +extraído de un documento de Office o similar y, si no existe, el propietario. No se registra owner +para el HTML de un rastreo web. Busque, por ejemplo, con ``owner:alice`` o +``last_modifier:"Taro Yamada"``. En el tema incluido, la búsqueda avanzada permite indicar el +propietario y el último modificador. Los administradores pueden activar y desactivar estos campos +con ``crawler.document.file.owner.enabled`` y ``crawler.document.file.last.modifier.enabled`` +(ambos ``true`` de forma predeterminada). + +Cuando los archivos HTML son el objetivo de búsqueda, la etiqueta title se registra en el campo title, y el texto debajo de la etiqueta body se registra en el campo content. + +Cómo utilizar +------------- + +Para realizar una búsqueda con especificación de campos, ingrese en el formulario de búsqueda "nombre_del_campo:término_de_búsqueda", separando el nombre del campo y el término de búsqueda con dos puntos (:). + +Para buscar fess como término de búsqueda en el campo title, ingrese lo siguiente: + +:: + + title:fess + +La búsqueda anterior mostrará documentos que contengan fess en el campo title como resultados de búsqueda. + +Para buscar en el campo url, ingrese lo siguiente: + +:: + + url:https\:\/\/fess.codelibs.org\/ja\/15.10\/* + url:"https://fess.codelibs.org/ja/15.10/*" + +El primero permite usar la búsqueda con comodines, por lo que también se puede escribir como ``url:*\/\/fess.codelibs.org\/*``. Dado que los caracteres ":" y "/" que aparecen en la url son caracteres especiales de la consulta de búsqueda, escápelos anteponiendo ``\`` (consulte :doc:`special-char`). El segundo no permite la búsqueda con comodines, pero un término que termine en ``*`` se trata como una búsqueda de prefijo (coincidencia inicial). + +.. tip:: + Si desea buscar por una parte de la URL, puede usar ``inurl:`` para realizar una búsqueda de coincidencia parcial sobre la URL. Por ejemplo, ``inurl:15.10`` busca documentos cuya URL contenga ``15.10``. + +Al especificar campos cuyo valor contiene "/", como mimetype, filetype o site, enciérrelo entre comillas, como en ``mimetype:"text/html"``, o bien escápelo, como en ``mimetype:text\/html``. + +Para conocer la sintaxis de búsqueda relacionada, consulte también :doc:`Búsqueda con comodines `, :doc:`Búsqueda por rango de valores `, :doc:`Búsqueda con ordenamiento ` y :doc:`Caracteres especiales `. + + +Véase también +------------- + +- :doc:`search-range` - Búsqueda por rango de valores +- :doc:`search-wildcard` - Búsqueda con comodines +- :doc:`special-char` - Caracteres especiales diff --git a/es/15.10/user/search-fuzzy.rst b/es/15.10/user/search-fuzzy.rst new file mode 100644 index 000000000..1c0460daf --- /dev/null +++ b/es/15.10/user/search-fuzzy.rst @@ -0,0 +1,67 @@ +================ +Búsqueda difusa +================ + +Búsqueda difusa (búsqueda aproximada) +====================================== + +Cuando desee buscar también palabras que no coincidan exactamente con el término de búsqueda, puede utilizar la búsqueda difusa (búsqueda aproximada). La búsqueda difusa es un método de búsqueda que considera coincidente una palabra registrada en el índice si la diferencia (distancia de edición) con respecto al término de búsqueda se encuentra dentro de un rango determinado. La distancia de edición es el número mínimo de operaciones de inserción, eliminación o sustitución de caracteres necesarias para transformar una palabra en otra. De forma predeterminada, |Fess| utiliza la distancia de Damerau-Levenshtein (optimal string alignment), que, además de estas operaciones, cuenta también el intercambio de dos caracteres adyacentes como una única diferencia. + +Cómo utilizar +-------------- + +Para aplicar la búsqueda difusa, agregue "~" después del término de búsqueda. + +Por ejemplo, si desea realizar una búsqueda difusa de la palabra "fess", puede buscar documentos que contengan palabras similares a "fess" (como "fes") ingresando lo siguiente en el formulario de búsqueda: + +:: + + fess~ + +Si agrega un número después de "~", puede especificar la distancia de edición permitida (cuántos caracteres de diferencia se toleran). Los valores que se pueden especificar son los números enteros 0, 1 o 2. + +:: + + fess~1 + +En el ejemplo anterior, se buscan palabras cuya distancia de edición con respecto a "fess" sea de 1 o menos. + +Si omite el número y especifica únicamente "~", se considera una distancia de edición de 2. El valor máximo de la distancia de edición es 2, por lo que, aunque especifique un valor de 3 o superior, también se tratará como 2. + +También puede realizar una búsqueda difusa especificando un campo. En el siguiente ejemplo, se buscan documentos que contengan, en el campo title, palabras similares a "fess". + +:: + + title:fess~ + +Si no especifica ningún campo, la búsqueda difusa se realiza sobre los campos title y content. + +Condiciones de uso +-------------------- + +Tenga en cuenta los siguientes puntos al utilizar la búsqueda difusa. + +* La búsqueda difusa se aplica a nivel de palabra. No se puede aplicar a frases entre comillas. Además, un número agregado después de una frase (por ejemplo, ``"Fess Search"~2``) no corresponde a una búsqueda difusa, sino a una :doc:`búsqueda de proximidad ` que indica la distancia entre palabras. +* La búsqueda difusa se realiza sobre las palabras registradas en el índice y el término de búsqueda no se vuelve a analizar. Por ello, es posible que no funcione como se espera en textos como el japonés, que se tokeniza mediante bi-gramas o análisis morfológico. La búsqueda difusa es eficaz principalmente con palabras alfanuméricas. +* El término de una búsqueda difusa cuenta la distancia de edición tal cual, incluida la distinción entre mayúsculas y minúsculas. Como las palabras alfabéticas registradas en el índice normalmente se convierten a minúsculas, utilice minúsculas en el término de búsqueda. Por ejemplo, ``Fess~1`` agota la distancia de edición 1 solo con la ``F`` mayúscula inicial, por lo que no da el mismo resultado que ``fess~1``. Además, ``Fess~0`` no coincide con nada, porque no hay en el índice ninguna palabra que coincida con la palabra en mayúsculas ``Fess`` (``fess~0`` en minúsculas es una coincidencia exacta). +* Si agrega "~" (distancia de edición 2) a palabras muy cortas, de 1 o 2 caracteres, también coinciden palabras en las que solo se han sustituido tantos caracteres como casi la longitud de la palabra. Por ejemplo, ``ab~`` coincide con ``ab`` y ``ac`` y también con ``xy``, que difiere en los dos caracteres. Como esto aumenta los resultados no deseados, especifique una distancia de edición pequeña para las palabras cortas, como ``ab~1``. + +.. note:: + + El comportamiento de la búsqueda difusa se puede ajustar en ``fess_config.properties``. + + * ``query.fuzzy.prefix_length`` (valor predeterminado: ``0``): número de caracteres desde el principio que deben coincidir exactamente. Si aumenta este valor, se reduce el margen de tolerancia a errores. + * ``query.fuzzy.expansions`` (valor predeterminado: ``50``): número máximo de palabras que se expanden como candidatas de coincidencia. + * ``query.fuzzy.transpositions`` (valor predeterminado: ``true``): especifica si el intercambio de dos caracteres adyacentes se cuenta como una única edición. Si es ``true``, se utiliza la distancia de Damerau-Levenshtein (optimal string alignment); si es ``false``, se utiliza la distancia de Levenshtein clásica. + +.. note:: + + Incluso en una búsqueda normal sin "~", |Fess| agrega automáticamente, como ayuda adicional, una ligera coincidencia difusa ponderada (``query.boost.fuzzy.*``) para los términos de búsqueda que tengan una longitud igual o superior a un valor determinado (de forma predeterminada, 4 caracteres o más), con el fin de mejorar la relevancia. Esta es una función destinada principalmente a ajustar la clasificación de los resultados de búsqueda y es un mecanismo distinto de la búsqueda difusa mediante "~". Sin embargo, esta coincidencia auxiliar también se incluye en los resultados de búsqueda, por lo que pueden añadirse a los resultados documentos que solo contienen una palabra que difiere en un carácter y no contienen el propio término de búsqueda (los documentos que contienen el propio término de búsqueda aparecen en posiciones superiores). Si desea desactivar este comportamiento, especifique un valor negativo (por ejemplo, ``-1``) en ``query.boost.fuzzy.min.length``. + + +Véase también +============= + +- :doc:`search-wildcard` - Búsqueda con comodines +- :doc:`search-proximity` - Búsqueda de proximidad +- :doc:`special-char` - Caracteres especiales diff --git a/es/15.10/user/search-geo.rst b/es/15.10/user/search-geo.rst new file mode 100644 index 000000000..04476513b --- /dev/null +++ b/es/15.10/user/search-geo.rst @@ -0,0 +1,56 @@ +============================ +Búsqueda por geolocalización +============================ + +Al agregar información de latitud y longitud a cada documento durante la generación del índice, es posible filtrar los resultados de búsqueda según la distancia desde un punto especificado en el momento de la búsqueda. + +Descripción general +------------------- + +La búsqueda por geolocalización incluye en los resultados de búsqueda únicamente los documentos que se encuentran dentro de un radio determinado alrededor de un punto especificado (latitud y longitud). Este filtrado se aplica como un filtro que utiliza la consulta geo_distance de OpenSearch, por lo que no afecta a la puntuación (relevancia). Además, no se admite la ordenación por distancia. + +El campo que almacena la información de ubicación debe estar definido como tipo ``geo_point`` en el mapeo de OpenSearch. Por defecto, el campo ``location`` está preparado como tipo ``geo_point``. Sin embargo, dado que no existe de forma estándar un proceso para almacenar valores en el campo ``location``, es necesario que el propio usuario almacene la información de ubicación mediante el mapeo de campos del rastreo de almacenes de datos, scripts, o la API de registro de documentos en el motor de búsqueda, entre otros métodos. + +Cómo utilizar +------------- + +La búsqueda por geolocalización se especifica agregando los siguientes parámetros a la solicitud de búsqueda. Por defecto, se puede utilizar con el campo ``location``. + +.. list-table:: + :header-rows: 1 + + * - Parámetro + - Descripción + * - ``geo..point`` + - Especifica la latitud y la longitud del punto central en el formato ``latitud,longitud``. El valor se expresa en grados decimales (tipo Double), con dos números separados por una coma. Ejemplo: ``35.681236,139.767125`` + * - ``geo..distance`` + - Especifica la distancia (radio) desde el punto central. Ejemplo: ``10km`` + +Tabla: Parámetros de solicitud + +```` especifica el nombre del campo que almacena la información de ubicación. Solo se pueden especificar los campos registrados en ``query.geo.fields``, que por defecto es ``location``. Para utilizar otros campos, es necesario mapearlos como tipo ``geo_point`` y agregarlos separados por comas en ``query.geo.fields`` dentro de ``fess_config.properties``. + +Por ejemplo, para buscar documentos dentro de un radio de 10km desde el punto de latitud 35.681236 y longitud 139.767125 (cerca de la estación de Tokio), se agregan los siguientes parámetros a la solicitud de búsqueda. + +:: + + geo.location.point=35.681236,139.767125&geo.location.distance=10km + +Unidades de distancia +--------------------- + +El valor de ``geo..distance`` se interpreta como una unidad de distancia de OpenSearch. Además de ``km`` (kilómetros), se pueden utilizar ``mm``, ``cm``, ``m``, ``in``, ``ft``, ``yd``, ``mi`` (millas), ``nmi`` (millas náuticas), entre otras. Si se omite la unidad y solo se especifica un número, se interpreta como metros (por ejemplo, ``500`` equivale a 500 metros). + +Especificación múltiple +----------------------- + +* Si se especifican varios valores de ``geo..point`` para el mismo campo, se buscan los documentos que se encuentren dentro del radio de cualquiera de los puntos (condición OR). +* Si se especifica información de ubicación para diferentes campos, se buscan los documentos que cumplan todas las condiciones (condición AND). + +.. note:: + + Es necesario especificar tanto ``geo..point`` como ``geo..distance``. Si no se especifica ``distance``, la condición de ese ``point`` se ignora. Además, se producirá un error si el valor de ``point`` no tiene el formato ``latitud,longitud`` (dos números separados por una coma) o si no se puede interpretar como números. + +.. note:: + + La búsqueda geográfica es un filtro sobre el término de búsqueda, por lo que, si el término de búsqueda está vacío, la búsqueda no se ejecuta y el resultado es de 0 elementos. Especifique un término de búsqueda en las solicitudes de búsqueda geográfica. diff --git a/es/15.10/user/search-label.rst b/es/15.10/user/search-label.rst new file mode 100644 index 000000000..74a80a3e9 --- /dev/null +++ b/es/15.10/user/search-label.rst @@ -0,0 +1,29 @@ +======================================== +Búsqueda con especificación de etiquetas +======================================== + +Búsqueda con especificación de etiquetas (búsqueda por categorías) +=================================================================== + +Al agregar información de etiquetas para categorizar los documentos objetivo de búsqueda, es posible realizar búsquedas filtradas especificando etiquetas en el momento de la búsqueda. Si utiliza etiquetas, puede limitar el ámbito de búsqueda, por ejemplo, por departamento, sitio o tipo de documento. + +La información de etiquetas se puede registrar en la pantalla de administración, lo que permite buscar por etiquetas en la pantalla de búsqueda. La información de etiquetas disponible se puede seleccionar mediante un menú desplegable en el momento de la búsqueda, permitiendo seleccionar varias etiquetas a la vez; si selecciona varias etiquetas, se incluirán en la búsqueda los documentos que tengan asignada cualquiera de ellas. Si no hay etiquetas registradas, el cuadro desplegable de etiquetas no se mostrará. + +.. note:: + Dado que se pueden configurar permisos para las etiquetas, en el menú desplegable solo se muestran las etiquetas a las que el usuario que realiza la búsqueda tiene acceso permitido. Además, las etiquetas que se muestran pueden variar según el host virtual o la configuración regional (idioma). Por este motivo, aunque haya etiquetas registradas, es posible que no aparezcan en el menú desplegable para determinados usuarios. + +Las etiquetas se definen especificando, mediante una expresión regular sobre la ruta de la URL, los documentos a los que se debe asignar la etiqueta. Para obtener información sobre cómo registrar etiquetas y sus elementos de configuración, consulte :doc:`Guía de administración de etiquetas <../admin/labeltype-guide>`. + +Cómo utilizar +------------- + +Puede seleccionar información de etiquetas en el momento de la búsqueda. La información de etiquetas se puede seleccionar en las opciones de búsqueda que se muestran al presionar el botón de opciones. + +|image0| + +Al configurar etiquetas y crear el índice, puede buscar documentos que tengan configuradas esas etiquetas. Una búsqueda sin especificar etiquetas será una búsqueda completa normal, como de costumbre. + +La asignación de etiquetas a los documentos se realiza comparando la URL del documento con las rutas configuradas para la etiqueta en el momento de rastrear y crear el índice. Por este motivo, si agrega o modifica la definición de una etiqueta (las rutas incluidas o las rutas excluidas), el cambio no se aplicará automáticamente a los documentos que ya estén indexados. Para aplicar el cambio, vuelva a rastrear los documentos correspondientes o ejecute el trabajo "Label Updater" registrado en el programador para actualizar el índice. + +.. |image0| image:: ../../../resources/images/en/15.10/user/search-label-1.png +.. pdf :width: 300 px diff --git a/es/15.10/user/search-not.rst b/es/15.10/user/search-not.rst new file mode 100644 index 000000000..fb5047a74 --- /dev/null +++ b/es/15.10/user/search-not.rst @@ -0,0 +1,45 @@ +==================================== +Búsqueda NOT (búsqueda de exclusión) +==================================== + +Cuando desea buscar documentos que no contengan una palabra específica (búsqueda de exclusión), puede utilizar la búsqueda NOT. Es útil cuando desea excluir palabras clave concretas de los resultados de búsqueda para reducir el ruido. + +Cómo utilizar +------------- + +La búsqueda NOT se realiza agregando NOT antes de la palabra que no desea incluir. NOT +debe escribirse en mayúsculas y requiere espacios antes y después. + +Por ejemplo, si desea buscar documentos que contengan "Término1" pero no contengan "Término2", ingrese lo siguiente y realice la búsqueda: + +:: + + Término1 NOT Término2 + +.. note:: + + NOT debe escribirse en mayúsculas. Si se escribe en minúsculas como ``not``, no se trata como un operador, sino que se busca como la palabra de búsqueda habitual "not". Además, colocar ``-`` justo antes de la palabra que desea excluir, como en ``Término1 -Término2``, tiene el mismo significado que NOT. + +Utilizando paréntesis ``( )``, puede combinar la búsqueda NOT con otras condiciones de búsqueda. Por ejemplo, si desea buscar documentos que contengan "Término1" o "Término2", pero no contengan "Término3", ingrese lo siguiente: + +:: + + (Término1 OR Término2) NOT Término3 + +También es posible realizar una búsqueda NOT especificando un campo. En el siguiente ejemplo, se buscan documentos que contengan "Término1" en el campo title, pero que no contengan "Término2" en el campo title. + +:: + + title:Término1 NOT title:Término2 + + +.. note:: + + Si el plugin ``fess-webapp-bangs`` está instalado, un bang definido como ``!g`` deja de ser una exclusión y envía la búsqueda a otro sitio. Véase :doc:`search-bangs`. + +Véase también +------------- + +- :doc:`search-and` - Búsqueda AND +- :doc:`search-or` - Búsqueda OR +- :doc:`special-char` - Caracteres especiales diff --git a/es/15.10/user/search-or.rst b/es/15.10/user/search-or.rst new file mode 100644 index 000000000..cd5ae42bf --- /dev/null +++ b/es/15.10/user/search-or.rst @@ -0,0 +1,39 @@ +=========================================== +Búsqueda OR (basta con uno de los términos) +=========================================== + +Cuando desea buscar documentos que contengan alguno de los términos de búsqueda, puede utilizar la búsqueda OR. Si escribe múltiples palabras en el campo de entrada de búsqueda, por defecto se realizará una búsqueda AND. + +Cómo utilizar +------------- + +Para utilizar la búsqueda OR, escriba OR entre los términos de búsqueda. OR +debe escribirse en mayúsculas y requiere espacios antes y después. + +Por ejemplo, si desea buscar documentos que contengan "Término1" o "Término2", ingrese lo siguiente en el formulario de búsqueda: + +:: + + Término1 OR Término2 + +También es posible conectar tres o más términos de búsqueda con OR. + +:: + + Término1 OR Término2 OR Término3 + +.. note:: + + OR debe escribirse en mayúsculas. Si se escribe en minúsculas como ``or``, no se trata como un operador, sino que se busca como la palabra de búsqueda habitual "or". ``||`` también se puede utilizar con el mismo significado que OR. + +Utilizando paréntesis ``( )``, puede combinar la búsqueda OR con otras condiciones de búsqueda. Por ejemplo, si desea buscar documentos que contengan "Término1" o "Término2", y además contengan "Término3", ingrese lo siguiente: + +:: + + (Término1 OR Término2) Término3 + +También es posible realizar una búsqueda OR especificando un campo. En el siguiente ejemplo, se buscan documentos que contengan "Término1" en el campo title, o "Término2" en el campo content. + +:: + + title:Término1 OR content:Término2 diff --git a/es/15.10/user/search-proximity.rst b/es/15.10/user/search-proximity.rst new file mode 100644 index 000000000..1d339d19e --- /dev/null +++ b/es/15.10/user/search-proximity.rst @@ -0,0 +1,70 @@ +======================== +Búsqueda de proximidad +======================== +Búsqueda de proximidad (distancia entre palabras) +=================================================== + +La búsqueda de proximidad permite encontrar documentos en los que las palabras de una frase aparecen cerca unas de otras, aunque no estén juntas. Es útil cuando pueden aparecer otras palabras entre las que se están buscando. + +Cómo utilizar +--------------- + +Encierre las palabras entre comillas dobles y agregue "~" y un número después de la comilla de cierre. + +Por ejemplo, la siguiente búsqueda encuentra documentos en los que "Fess" y "búsqueda" aparecen a una distancia de 3 o menos: + +:: + + "Fess búsqueda"~3 + +El número es la cantidad máxima de desplazamientos de posición permitidos entre las palabras (consulte "Cómo se cuenta la distancia" más adelante). Cuanto mayor sea el número, más separadas pueden estar las palabras. + +También puede realizar una búsqueda de proximidad en un campo específico. En el siguiente ejemplo, se busca en el campo title. + +:: + + title:"Fess búsqueda"~3 + +Si omite el número y especifica únicamente "~" (por ejemplo, ``"Fess búsqueda"~``), la frase se busca como una frase normal en la que las palabras deben ser contiguas. Un número decimal se trunca a un entero (``~2.5`` se trata como ``~2``). + +La búsqueda de proximidad se puede combinar con un impulso (boost). En el siguiente ejemplo, la búsqueda de proximidad se multiplica por 2 (consulte :doc:`search-boost`). + +:: + + "Fess búsqueda"~5^2 + +Cómo se cuenta la distancia +----------------------------- + +* El número es la cantidad máxima de desplazamientos de posición permitidos entre las palabras. Se cuenta en tokens generados por el analizador del campo de destino, no en caracteres ni en palabras separadas por espacios. En textos en inglés, equivale aproximadamente al número de palabras que hay entre los términos. Las palabras eliminadas como palabras vacías (stop words) durante el análisis también se cuentan. +* Las palabras pueden aparecer en otro orden, pero el orden inverso requiere un número mayor. Por ejemplo, un documento que contiene "quick brown fox" coincide con ``"quick fox"~1``, pero solo coincide con ``"fox quick"`` a partir de ``~3``. + +:: + + "quick fox"~1 + "fox quick"~3 + +Texto en japonés, chino y coreano (CJK) +----------------------------------------- + +En textos en japonés y otros textos CJK, la unidad en que se cuenta la distancia depende del campo. + +* En los campos generales title y content, la distancia es cercana al número de caracteres que hay entre las palabras. +* En los campos específicos de cada idioma, la distancia se cuenta en tokens morfológicos, y las partículas eliminadas también se cuentan. + +Por ello, separe las palabras con espacios y especifique un número generoso. + +:: + + "全文 検索"~5 + "大阪 おいしい"~10 + +Es posible que una cadena sin espacios (por ejemplo, ``"大阪おいしい"~10``) no funcione como se espera como búsqueda de proximidad entre palabras, ya que en los campos generales se compara como una única cadena continua. Separe las palabras con espacios. La distancia no se puede convertir exactamente en un número de caracteres, por lo que conviene empezar con un número generoso y reducirlo a medida que comprueba los resultados. + +Véase también +=============== + +- :doc:`search-fuzzy` - Búsqueda difusa +- :doc:`search-boost` - Búsqueda con boost +- :doc:`search-field` - Búsqueda con especificación de campos +- :doc:`special-char` - Caracteres especiales diff --git a/es/15.10/user/search-range.rst b/es/15.10/user/search-range.rst new file mode 100644 index 000000000..451d9c267 --- /dev/null +++ b/es/15.10/user/search-range.rst @@ -0,0 +1,71 @@ +============================= +Búsqueda por rango de valores +============================= + +Si un campo almacena datos que permiten especificar un rango, como valores numéricos o fechas y horas, es posible realizar una búsqueda por rango en dicho campo. + +Cómo utilizar +------------- + +Para realizar una búsqueda por rango, introduzca «nombre_de_campo:[valor TO valor]» en el formulario de búsqueda. Para separar el rango se utiliza ``TO`` en mayúsculas. + +Por ejemplo, para buscar documentos cuyo campo content_length esté en el rango de 1 kilobyte a 10 kilobytes, introduzca lo siguiente en el formulario de búsqueda: + +:: + + content_length:[1000 TO 10000] + +Los corchetes ``[ ]`` incluyen los límites del rango (mayor o igual / menor o igual), mientras que las llaves ``{ }`` no incluyen los límites del rango (mayor que / menor que). También se pueden combinar ambos. Por ejemplo, ``content_length:{1000 TO 10000]`` representa los documentos con un valor mayor que 1000 y menor o igual que 10000. + +Si se establece ``*`` en un lado, se representa un rango abierto especificando solo el límite superior o inferior. ``content_length:[1000 TO *]`` representa 1000 o más, y ``content_length:[* TO 10000]`` representa 10000 o menos. + +La búsqueda por rango solo está disponible para los campos registrados como objeto de búsqueda. De forma predeterminada, se puede realizar una búsqueda por rango en campos como content_length, last_modified, timestamp, click_count y favorite_count. + +Búsqueda por rango de tiempo +---------------------------- + +Para realizar una búsqueda por rango de tiempo (fecha y hora), introduzca «last_modified:[fecha_hora1 TO fecha_hora2]» (fecha_hora1 < fecha_hora2) en el formulario de búsqueda. Tenga en cuenta que, si fecha_hora1 es posterior a fecha_hora2, no se produce un error; simplemente el resultado de la búsqueda será de 0 documentos. + +La fecha y hora se especifican en formato ISO 8601. El formato es ``YYYY-MM-DDThh:mm:ss.SSSZ``, y todo lo que va después de la hora se puede omitir. + +.. list-table:: + :header-rows: 1 + + * - Especificación + - Ejemplo + * - Solo año, mes y día + - 2012-12-02 + * - Año, mes, día, hora, minuto y segundo + - 2012-12-02T10:45:23Z + * - Año, mes, día, hora, minuto y segundo (hasta milisegundos) + - 2012-12-02T10:45:23.235Z + +Para especificar la fecha y hora, se puede utilizar el cálculo de fecha y hora basado en la fecha y hora actuales. Los símbolos disponibles son los siguientes. + +.. list-table:: + :header-rows: 1 + + * - Símbolo + - Significado + * - ``now`` + - Fecha y hora actuales + * - ``y`` / ``M`` / ``w`` / ``d`` / ``h`` / ``m`` / ``s`` + - Año / Mes / Semana / Día / Hora / Minuto / Segundo + * - ``+`` / ``-`` + - Suma / Resta + * - ``/`` + - Redondeo (redondea a la unidad que sigue a ``/``) + +Cuando se toma como referencia now o una fecha y hora, se pueden añadir símbolos como +, - (suma, resta) o / (redondeo). Sin embargo, cuando se toma como referencia una fecha y hora específica en lugar de now, es necesario insertar ``||`` entre la fecha y hora y el símbolo (ejemplo: ``2016-01-01||+1M/d``). + +``/`` es un símbolo que redondea a la unidad que sigue a ``/``. ``now-1d/d`` representa las 00:00 del día anterior, es decir, un día menos que las 00:00 de hoy, sin importar a qué hora del día se ejecute. + +Tenga en cuenta que estos cálculos de fecha y hora se evalúan en el motor de búsqueda (OpenSearch) y solo son válidos para campos de tipo fecha y hora. + +Por ejemplo, para buscar en el campo last_modified los documentos actualizados hasta 30 días antes de la fecha y hora actuales (suponiendo que son las 20:00 del 21 de febrero de 2016), introduzca lo siguiente en el formulario de búsqueda: + +:: + + last_modified:[now-30d TO now] + +Si la fecha y hora actuales son las 20:00 del 21 de febrero de 2016 (UTC), lo anterior corresponde aproximadamente al rango ``[2016-01-22T20:00:00Z TO 2016-02-21T20:00:00Z]``. diff --git a/es/15.10/user/search-sort.rst b/es/15.10/user/search-sort.rst new file mode 100644 index 000000000..cdf1607f0 --- /dev/null +++ b/es/15.10/user/search-sort.rst @@ -0,0 +1,76 @@ +======================== +Búsqueda con ordenamiento +======================== + +Puede ordenar los resultados de búsqueda especificando campos como la fecha de búsqueda. + +Campos de ordenamiento +---------------------- + +Por defecto, puede ordenar especificando los siguientes campos: + +.. list-table:: + :header-rows: 1 + + * - Nombre del campo + - Descripción + * - created + - Fecha y hora de rastreo + * - content_length + - Tamaño del documento rastreado + * - last_modified + - Fecha y hora de última modificación del documento rastreado + * - filename + - Nombre del archivo + * - score + - Valor de puntuación + * - timestamp + - Fecha y hora de indexación del documento + * - click_count + - Número de clics en el documento + * - favorite_count + - Número de veces que el documento se agregó a favoritos + +Tabla: Lista de campos de ordenamiento + + +También puede agregar sus propios campos como objetivos de ordenamiento. Para hacerlo, especifique en ``query.additional.sort.fields`` de ``fess_config.properties`` los nombres de los campos que desea usar como objetivos de ordenamiento, separados por comas (el valor inicial está vacío). Los campos especificados aquí se agregan a los campos estándar mencionados anteriormente y quedan disponibles para el ordenamiento. Tenga en cuenta que el campo que se utilice como objetivo de ordenamiento debe estar registrado previamente en el índice. + +Cómo utilizar +------------- + +Puede seleccionar condiciones de ordenamiento en el momento de la búsqueda. Las condiciones de ordenamiento se pueden seleccionar en el diálogo de opciones de búsqueda que se muestra al presionar el botón de opciones. + +|image0| + +Además, para ordenar en el campo de búsqueda, ingrese "sort:nombre_del_campo" separando sort y el nombre del campo con dos puntos (:) en el formulario de búsqueda. + +Lo siguiente busca fess como término de búsqueda y ordena el tamaño del documento en orden ascendente: + +:: + + fess sort:content_length + +Para ordenar en orden descendente, agregue ``.desc`` después del nombre del campo. + +:: + + fess sort:content_length.desc + +El sufijo que se puede especificar después del nombre del campo es ``.asc`` (ascendente) o ``.desc`` (descendente); si se omite, se utilizará el orden ascendente. + +Para ordenar por múltiples campos, especifíquelos separados por comas como se muestra a continuación. El campo especificado primero tiene prioridad, y los documentos que tengan el mismo valor en ese campo se ordenan a continuación según el siguiente campo. + +:: + + fess sort:content_length.desc,last_modified + +.. note:: + Especificar en ``sort:`` dentro de los términos de búsqueda un nombre de campo que no está en la lista de campos de ordenamiento, o un orden distinto de ``asc`` o ``desc``, no produce un error. + En su lugar, ``sort:`` no se trata como condición de ordenamiento, y la búsqueda se vuelve a ejecutar tratando los símbolos de todo el término de búsqueda (como ``:``) como caracteres normales. + Los resultados no se ordenan y, en la mayoría de los casos, no se encuentra ningún documento. + + Si se especifica el mismo valor en el parámetro ``sort`` de la API de búsqueda, se produce un error (400 Bad Request). + +.. |image0| image:: ../../../resources/images/en/15.10/user/search-sort-1.png +.. pdf :width: 300 px diff --git a/es/15.10/user/search-wildcard.rst b/es/15.10/user/search-wildcard.rst new file mode 100644 index 000000000..e9fa0842a --- /dev/null +++ b/es/15.10/user/search-wildcard.rst @@ -0,0 +1,53 @@ +====================== +Búsqueda con comodines +====================== + +Puede utilizar comodines de un carácter o de varios caracteres dentro de los términos de búsqueda. ? se puede especificar como comodín de un carácter, y \* se puede especificar como comodín de varios caracteres. Los comodines se pueden utilizar en palabras. No es posible realizar búsquedas con comodines en oraciones. + +Cómo utilizar +------------- + +Para utilizar un comodín de un carácter, use ? de la siguiente manera: + +:: + + te?t + +En el caso anterior, esto coincide con cualquier carácter individual en la posición de ?, como en text o test. + +Para utilizar un comodín de varios caracteres, use \* de la siguiente manera: + +:: + + test* + +En el caso anterior, esto coincide con cualquier cadena de cero o más caracteres en la posición de \*, como test, tests o tester. Además, + +:: + + te*t + +también se puede utilizar en medio del término de búsqueda. Además, + +:: + + *test + +también se puede utilizar un comodín al principio del término de búsqueda. + +También puede realizar una búsqueda con comodines especificando un campo. En el siguiente ejemplo, se buscan documentos que contengan, en el campo title, una palabra que empiece por te y termine en t. + +:: + + title:te*t + +Si no especifica ningún campo, la búsqueda se realiza sobre los campos title y content. + +Condiciones de uso +------------------ + +Tenga en cuenta los siguientes puntos al utilizar la búsqueda con comodines. + +* Los comodines coinciden con las cadenas de texto (tokens) registradas en el índice. Dado que el término de búsqueda no se vuelve a analizar, si el índice se crea con bi-gram u otros métodos, el japonés se trata como cadenas de longitud fija sin significado, por lo que los comodines en japonés no funcionarán como se espera. Si desea utilizar comodines en japonés, utilícelos en campos que usen análisis morfológico. +* Los patrones que contienen un comodín (``*``, ``?``) al principio o en medio del término de búsqueda distinguen entre mayúsculas y minúsculas. Dado que las palabras registradas en el índice normalmente se convierten a minúsculas, utilice minúsculas en el patrón. Por ejemplo, ``Te*t``, ``Te?t`` y ``*Test`` no coinciden con ``test``, que se registra en minúsculas. En cambio, en los patrones con ``*`` únicamente al final (como ``Test*``), que son una coincidencia por prefijo, el término de búsqueda se convierte a minúsculas al analizarse, por lo que ``Test*`` también coincide con ``test``. +* Una búsqueda con un comodín al principio (por ejemplo, ``*test``) puede tardar en procesarse, ya que recorre todas las palabras del índice. diff --git a/es/15.10/user/special-char.rst b/es/15.10/user/special-char.rst new file mode 100644 index 000000000..370e70d0f --- /dev/null +++ b/es/15.10/user/special-char.rst @@ -0,0 +1,91 @@ +===================== +Caracteres especiales +===================== + +Los siguientes caracteres tienen un significado especial en la sintaxis de las consultas de búsqueda, por lo que se tratan como caracteres especiales en los términos de búsqueda. Para utilizar estos caracteres como caracteres de búsqueda literales, es necesario escaparlos. + +:: + + + - && || ! ( ) { } [ ] ^ " ~ * ? : \ / + +Estos caracteres se utilizan para invocar funciones de búsqueda como términos obligatorios/prohibidos (``+`` ``-``), operadores booleanos (``&&`` ``||`` ``!``), agrupación (``( )``), búsqueda por rango (``[ ]`` ``{ }``), búsqueda con impulso (boost) (``^``), búsqueda de frases (``"``), búsqueda difusa (fuzzy) y búsqueda de proximidad (``~``), búsqueda con comodines (``*`` ``?``) y búsqueda por campo (``:``). + +Por ejemplo, si busca directamente símbolos como "/" o ":" incluidos en una URL o ruta de archivo, o "+" o "-" que aparecen en código de programación, puede obtener resultados de búsqueda no deseados. Consulte a continuación el método de escape. + + +Lista de caracteres especiales y su significado +------------------------------------------------- + +.. list-table:: + :header-rows: 1 + + * - Carácter especial + - Significado + - Página relacionada + * - ``+`` ``-`` + - Indica un término obligatorio o excluido (búsqueda AND / búsqueda NOT) + - :doc:`search-and` / :doc:`search-not` + * - ``&&`` ``||`` + - Búsqueda AND / búsqueda OR + - :doc:`search-and` / :doc:`search-or` + * - ``!`` + - Búsqueda NOT (búsqueda de exclusión) + - :doc:`search-not` + * - ``( )`` + - Agrupación de condiciones de búsqueda + - :doc:`advanced-search` + * - ``[ ]`` ``{ }`` + - Búsqueda por rango (``[ ]`` incluye los límites, ``{ }`` los excluye) + - :doc:`search-range` + * - ``^`` + - Búsqueda con impulso (boost) + - :doc:`search-boost` + * - ``"`` + - Búsqueda de frases (trata el texto entre comillas como una sola unidad; también puede usarse en lugar del escape) + - :doc:`advanced-search` + * - ``~`` + - Búsqueda difusa (tras una palabra) / búsqueda de proximidad (tras una frase) + - :doc:`search-fuzzy` / :doc:`search-proximity` + * - ``*`` ``?`` + - Búsqueda con comodines + - :doc:`search-wildcard` + * - ``:`` + - Especificación del campo de búsqueda + - :doc:`search-field` + * - ``\`` + - Carácter de escape + - (esta página) + * - ``/`` + - Barra (debe escaparse si aparece, por ejemplo, en una URL) + - :doc:`search-field` + + +Cómo utilizar +------------- + +Para tratar un carácter especial como un carácter de búsqueda literal, utilice uno de los siguientes métodos. + +* Coloque ``\`` inmediatamente antes del carácter para escaparlo. El único carácter que sigue se trata como un carácter normal en lugar de sintaxis de consulta. +* Encierre el término de búsqueda entre ``"``. La cadena encerrada se trata como una búsqueda de frase, y los caracteres especiales que contiene no se interpretan como sintaxis de consulta. Tenga en cuenta, sin embargo, que al convertirse en una búsqueda de frase, funciones como la búsqueda con comodines (``*`` ``?``) no están disponibles. + +:: + + aaa\/bbb + "aaa/bbb" + +Por ejemplo, si desea buscar el término "C++" tal como es, puede escaparlo de la siguiente manera: + +:: + + C\+\+ + "C++" + + +Véase también +------------- + +- :doc:`search-field` - Búsqueda con especificación de campos +- :doc:`search-wildcard` - Búsqueda con comodines +- :doc:`search-fuzzy` - Búsqueda difusa +- :doc:`search-proximity` - Búsqueda de proximidad +- :doc:`advanced-search` - Búsqueda avanzada diff --git a/fr/15.10/admin/accesstoken-guide.rst b/fr/15.10/admin/accesstoken-guide.rst new file mode 100644 index 000000000..08801ab4b --- /dev/null +++ b/fr/15.10/admin/accesstoken-guide.rst @@ -0,0 +1,80 @@ +============= +Jeton d'accès +============= + +Présentation +============ + +La page de configuration des jetons d'accès gère les jetons d'accès. + +Gestion +======= + +Affichage +--------- + +Pour ouvrir la page de liste de configuration des jetons d'accès illustrée ci-dessous, cliquez sur [Système > Jeton d'accès] dans le menu de gauche. + +|image0| + +Cliquez sur le nom de la configuration pour la modifier. + +Création de configuration +------------------------- + +Cliquez sur le bouton Nouvelle création pour ouvrir la page de configuration des jetons d'accès. + +|image1| + +Paramètres de configuration +--------------------------- + +Nom +:::: + +Spécifiez un nom pour décrire ce jeton d'accès. + +Permission +:::::::::: + +Configure la permission du jeton d'accès. +Décrivez au format « {user\ |group|\ role}nom ». +Par exemple, pour qu'un utilisateur appartenant au groupe developer affiche les résultats de recherche, configurez la permission « {group}developer ». + +.. warning:: + + Un jeton d'accès disposant de la permission ``{role}admin-api`` (stockée sous la forme ``Radmin-api``) peut utiliser tous les points de terminaison de l'API Admin ; voir :doc:`../api/admin/api-admin-overview`. Un utilisateur disposant du rôle ``admin-accesstoken`` peut émettre un tel jeton, et un utilisateur disposant de ``admin-accesstoken-view`` peut afficher les valeurs des jetons ; traitez donc ces deux rôles comme équivalents au rôle administrateur et accordez-les uniquement à des opérateurs de confiance. + +Nom du paramètre +:::::::::::::::: + +Spécifiez le nom du paramètre de requête pour spécifier la permission comme requête de recherche. + +.. warning:: + + La fonctionnalité de nom de paramètre est conçue uniquement pour une utilisation dans des environnements internes de confiance. + Lorsque cette fonctionnalité est activée, des permissions supplémentaires peuvent être spécifiées via des paramètres d'URL. + Cependant, dans des environnements accessibles de l'extérieur ou exposés comme API publique, + des utilisateurs malveillants peuvent manipuler les paramètres d'URL pour obtenir des privilèges qu'ils ne devraient pas avoir. + + Veuillez noter les points suivants : + + * Utilisez cette fonctionnalité uniquement lorsque Fess est intégré dans une autre application ou service qui contrôle entièrement les requêtes entrantes. + * Ne configurez pas de nom de paramètre lorsque Fess est exposé à des réseaux non fiables. + * Assurez-vous que les paramètres d'URL ne peuvent pas être manipulés par des utilisateurs externes lors de l'utilisation de jetons d'accès. + +Date d'expiration +::::::::::::::::: + +Spécifie la date d'expiration du jeton d'accès. + +Suppression de configuration +---------------------------- + +Cliquez sur le nom de la configuration dans la page de liste, puis cliquez sur le bouton Supprimer pour afficher l'écran de confirmation. +Appuyer sur le bouton Supprimer supprimera la configuration. + + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/accesstoken-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/accesstoken-2.png diff --git a/fr/15.10/admin/backup-guide.rst b/fr/15.10/admin/backup-guide.rst new file mode 100644 index 000000000..ed629dbbe --- /dev/null +++ b/fr/15.10/admin/backup-guide.rst @@ -0,0 +1,115 @@ +========== +Sauvegarde +========== + +Présentation +============ + +La page de sauvegarde permet de télécharger et de téléverser les informations de configuration de |Fess|. + +Téléchargement +-------------- + +|Fess| conserve les informations de configuration sous forme d'index. +Pour télécharger, cliquez sur le nom de l'index. + +|image0| + +.. note:: + + Les fichiers de dictionnaire (synonymes, mots vides, etc.) ne font pas partie de la sauvegarde. + Ils sont stockés dans le répertoire de dictionnaires du moteur de recherche (``FESS_DICTIONARY_PATH``) ; + copiez-les séparément si nécessaire. + +fess_config.bulk +:::::::::::::::: + +fess_config.bulk contient les informations de configuration de |Fess|. + +fess_basic_config.bulk +:::::::::::::::::::::: + +fess_basic_config.bulk contient les informations de configuration de |Fess| à l'exception des informations de crawl, des URL en échec, des journaux de tâches, de la file d'attente des miniatures, des tags utilisateur et de données similaires. + +fess_user.bulk +:::::::::::::: + +fess_user.bulk contient les informations des utilisateurs, rôles et groupes. + +system.properties +::::::::::::::::: + +system.properties contient les informations de configuration générale. + +fess.json +::::::::: + +fess.json contient les informations de configuration de l'index fess. + +doc.json +:::::::: + +doc.json contient les informations de mapping de l'index fess. + +chat_log.ndjson +::::::::::::::: + +chat_log.ndjson contient les informations du journal d'utilisation du chat IA. + +click_log.ndjson +:::::::::::::::: + +click_log.ndjson contient les informations du journal des clics. + +favorite_log.ndjson +::::::::::::::::::: + +favorite_log.ndjson contient les informations du journal des favoris. + +search_log.ndjson +::::::::::::::::: + +search_log.ndjson contient les informations du journal de recherche. + +user_info.ndjson +:::::::::::::::: + +user_info.ndjson contient les informations des utilisateurs de recherche. + +Téléversement +------------- + +Vous pouvez téléverser et importer les informations de configuration. +Les fichiers qui peuvent être restaurés sont les suivants : + +- ``*.bulk`` +- ``system.properties`` +- ``fess.json`` et ``doc.json`` : ils remplacent les fichiers de définition d'index utilisés par |Fess|. Les paramètres et le mappage d'un index existant ne sont pas modifiés sur le moment. +- ``gsa*.xml`` : un fichier de configuration de Google Search Appliance. Il est importé sous forme de configuration de crawl Web, de configuration de crawl de fichiers et d'étiquettes. + +Les fichiers ``*.ndjson`` (journaux de recherche et autres journaux) ne peuvent pas être téléversés pour être restaurés. + +Un document d'un fichier \*.bulk qui possède un ``updatedTime`` n'est écrit que si le document +stocké n'existe pas, n'a pas de ``updatedTime`` ou est plus ancien. Un document qui n'est pas plus +récent est ignoré et consigné au niveau INFO dans ``fess.log`` : une restauration n'annule donc pas +les modifications faites après la sauvegarde, et les jobs planifiés fournis avec la version +installée (``updatedTime`` 0) sont conservés tels quels. Les documents sans ``updatedTime`` sont +toujours écrits. + +.. note:: + + L'omission est consignée au niveau INFO ; avec le niveau de journalisation par défaut (``warn``), elle n'apparaît donc pas dans ``fess.log``. Pour voir ces entrées, passez le niveau de journalisation à ``info`` avant la restauration. Vous pouvez le modifier dans « Niveau de journalisation » sous [Système > Général] dans l'interface d'administration (il revient à la valeur configurée au redémarrage de |Fess|) ou, sous Linux, avec ``FESS_LOG_LEVEL=info``. Voir :doc:`../config/admin-logging` pour plus de détails. + +.. note:: + + |Fess| 15.10 enregistre le ``password`` de l'authentification Web et fichier chiffré avec la clé de chiffrement de + l'application (``app.cipher.key`` dans ``fess_config.properties``) ; ``fess_basic_config.bulk`` et + ``fess_config.bulk`` contiennent donc les valeurs chiffrées. Lorsque vous restaurez une sauvegarde sur une autre + installation, reprenez la même ``app.cipher.key``. Avec une clé différente, les explorations qui utilisent ces + identifiants échouent avec une erreur. Une sauvegarde créée avant la 15.10 les contient en clair et continue de + fonctionner. + + Les autres valeurs d'un fichier ``*.bulk`` ne sont pas chiffrées ; conservez donc ces fichiers comme des fichiers + sensibles. + + .. |image0| image:: ../../../resources/images/en/15.10/admin/backup-1.png diff --git a/fr/15.10/admin/badword-guide.rst b/fr/15.10/admin/badword-guide.rst new file mode 100644 index 000000000..cd132db11 --- /dev/null +++ b/fr/15.10/admin/badword-guide.rst @@ -0,0 +1,85 @@ +=========== +Mots exclus +=========== + +Présentation +============ + +Cette section explique la configuration des mots exclus des suggestions. +Les suggestions sont affichées en fonction des termes de recherche, mais vous pouvez configurer ces mots pour qu'ils ne soient pas affichés dans les suggestions. + + +Gestion +======= + +Affichage +--------- + +Pour ouvrir la page de liste de configuration des mots exclus des suggestions illustrée ci-dessous, cliquez sur [Suggérer > Mot incorrect] dans le menu de gauche. + +|image0| + +Cliquez sur le nom de la configuration pour la modifier. + +Création de configuration +------------------------- + +Pour ouvrir la page de création de mots exclus des suggestions, cliquez sur le bouton Nouvelle création. + +|image1| + +Paramètres de configuration +--------------------------- + +Candidat de suggestion +:::::::::::::::::::::: + +Enregistre les mots NG. +Les mots enregistrés ici ne seront plus affichés dans les suggestions. + +Suppression de configuration +---------------------------- + +Cliquez sur le nom de la configuration dans la page de liste, puis cliquez sur le bouton Supprimer pour afficher l'écran de confirmation. +Appuyer sur le bouton Supprimer supprimera la configuration. + +Téléchargement +============== + +Télécharge les mots enregistrés au format CSV. + +|image2| + +Contenu du CSV +-------------- + +La première ligne est l'en-tête. +Les mots exclus sont listés à partir de la deuxième ligne. + +:: + +"BadWord" +"検索エンジン" + +Téléversement +============= + +Enregistre les mots au format CSV. + +|image3| + +Contenu du CSV +-------------- + +La première ligne est l'en-tête. +Décrivez les mots exclus à partir de la deuxième ligne. + +:: + +"BadWord" +"検索エンジン" + +.. |image0| image:: ../../../resources/images/en/15.10/admin/badword-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/badword-2.png +.. |image2| image:: ../../../resources/images/en/15.10/admin/badword-3.png +.. |image3| image:: ../../../resources/images/en/15.10/admin/badword-4.png diff --git a/fr/15.10/admin/boostdoc-guide.rst b/fr/15.10/admin/boostdoc-guide.rst new file mode 100644 index 000000000..35d68af00 --- /dev/null +++ b/fr/15.10/admin/boostdoc-guide.rst @@ -0,0 +1,83 @@ +================= +Boost de document +================= + +Présentation +============ + +Cette section explique la configuration du boost de document. +En configurant le boost de document, vous pouvez positionner des documents en haut des résultats de recherche indépendamment du terme de recherche. + +Gestion +======= + +Affichage +--------- + +Pour ouvrir la page de liste de configuration du boost de document illustrée ci-dessous, cliquez sur [Robot d'exploration > Boost de document] dans le menu de gauche. + +|image0| + +Cliquez sur le nom de la configuration pour la modifier. + +Création de configuration +------------------------- + +Cliquez sur le bouton Nouvelle création pour ouvrir la page de configuration du boost de document. + +|image1| + +Paramètres de configuration +--------------------------- + +Condition +::::::::: + +Spécifie la condition des documents que vous souhaitez positionner en haut. +Par exemple, pour afficher en haut les URL contenant https://www.n2sm.net/, décrivez url.matches("https://www.n2sm.net/.\*"). +Les conditions sont écrites dans la syntaxe du moteur de script spécifié dans « Type de Script » ci-dessous. + +Expression de boost +::::::::::::::::::: + +Spécifie la valeur de pondération du document. +L'expression est écrite dans la syntaxe du moteur de script spécifié dans « Type de Script » ci-dessous. + +Type de Script +:::::::::::::: + +Spécifie le moteur de script utilisé pour évaluer la condition et l'expression de boost. +Les nouvelles configurations sont préremplies avec ``javascript``. Sélectionner ``groovy`` nécessite +le plugin ``fess-script-groovy``. Si le champ est laissé vide, les expressions sont évaluées en tant que Groovy. + +.. warning:: + + Avec JavaScript, écrivez la condition et l'expression de boost comme des expressions pures + sans point-virgule final. Un texte qui ne peut être analysé qu'en tant que bloc + d'instructions est évalué à ``null`` sauf s'il contient un ``return`` explicite. Voir + :ref:`javascript-statement-null` (dans :doc:`../config/scripting-javascript`). + +Ordre de tri +:::::::::::: + +Configure l'ordre de tri du boost de document. + +Moment d'application des règles +------------------------------- + +Les règles de boost de document sont évaluées lorsqu'une exploration Web ou une exploration de fichiers enregistre un document dans l'index. Elles ne s'appliquent pas aux explorations de magasins de données. +Ajouter, modifier ou supprimer une règle ne change pas le boost des documents déjà présents dans l'index. + +Lorsque « Vérifier la dernière modification » dans [Système > Général] est activé (valeur par défaut), un document dont le contenu n'a pas changé n'est pas enregistré à nouveau dans l'index lors d'une nouvelle exploration, de sorte que son boost n'est pas réévalué. +Pour appliquer une règle nouvelle ou modifiée aux documents existants, supprimez ces documents de l'index (voir :doc:`searchlist-guide`), puis relancez l'exploration. +Un document enregistré à nouveau, par exemple parce que son contenu a été mis à jour, est évalué à ce moment-là. +Si « Vérifier la dernière modification » est désactivé, chaque document est enregistré à nouveau à chaque exploration, et les règles sont donc évaluées à chaque fois. + +Suppression de configuration +---------------------------- + +Cliquez sur le nom de la configuration dans la page de liste, puis cliquez sur le bouton Supprimer pour afficher l'écran de confirmation. Appuyer sur le bouton Supprimer supprimera la configuration. + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/boostdoc-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/boostdoc-2.png diff --git a/fr/15.10/admin/crawlinginfo-guide.rst b/fr/15.10/admin/crawlinginfo-guide.rst new file mode 100644 index 000000000..13e87755c --- /dev/null +++ b/fr/15.10/admin/crawlinginfo-guide.rst @@ -0,0 +1,93 @@ +===================== +Informations de crawl +===================== + +Présentation +============ + +Les résultats d'exécution du crawl sont enregistrés et les informations de crawl peuvent être vérifiées dans cet écran d'administration. + +Gestion +======= + +Liste +===== + +Chaque fois qu'un crawl est exécuté, il est enregistré comme informations de crawl. +Dans la liste, vous pouvez vérifier le nom de session du crawl exécuté et l'heure d'exécution. +Si vous souhaitez vérifier les détails des informations de crawl, cliquez sur les informations de crawl cibles. + +|image0| + +Détails +======= + +En cliquant sur l'ID de session des informations de crawl dans la liste, les détails des informations de crawl cibles s'affichent. + +|image1| + +Liste des éléments +------------------ + +ID de session +::::::::::::: + +ID de session lors de l'exécution du crawl. + +Heure de début du crawler +:::::::::::::::::::::::::: + +Heure de début de l'ensemble du crawl. + +Heure de début du crawl (Web/Fichier) +:::::::::::::::::::::::::::::::::::::: + +Heure de début du crawl Web et du système de fichiers. + +Heure de début du crawl (Magasin de données) +::::::::::::::::::::::::::::::::::::::::::::: + +Heure de début du crawl du magasin de données. + +Heure de fin du crawl (Web/Fichier) +:::::::::::::::::::::::::::::::::::: + +Heure de fin du crawl Web et du système de fichiers. + +Durée d'exécution du crawl (Magasin de données) +:::::::::::::::::::::::::::::::::::::::::::::::: + +Durée d'exécution du crawl du magasin de données (en millisecondes). + +Durée d'exécution de l'indexation (Magasin de données) +::::::::::::::::::::::::::::::::::::::::::::::::::::::: + +Temps nécessaire pour indexer les résultats du crawl Web et du système de fichiers (en millisecondes). + +Taille de l'index (Magasin de données) +::::::::::::::::::::::::::::::::::::::: + +Nombre de documents indexés. + +Heure de fin du crawl (Magasin de données) +::::::::::::::::::::::::::::::::::::::::::: + +Heure de fin du crawl du magasin de données. + +État du crawler +::::::::::::::: + +Si le crawl a réussi ou non. + +Heure de fin du crawler +:::::::::::::::::::::::: + +Heure de fin de l'ensemble du crawl. + +Durée d'exécution du crawler +::::::::::::::::::::::::::::: + +Durée d'exécution de l'ensemble du crawl (en millisecondes). + +.. |image0| image:: ../../../resources/images/en/15.10/admin/crawlinginfo-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/crawlinginfo-2.png diff --git a/fr/15.10/admin/dashboard-guide.rst b/fr/15.10/admin/dashboard-guide.rst new file mode 100644 index 000000000..e4cfb06a7 --- /dev/null +++ b/fr/15.10/admin/dashboard-guide.rst @@ -0,0 +1,58 @@ +=============== +Tableau de bord +=============== + +Présentation +============ + +Le tableau de bord fournit un outil d'administration Web pour gérer les clusters et les index OpenSearch auxquels |Fess| accède. + +|image0| + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: Index gérés par |Fess| + :header-rows: 1 + + * - Nom de l'index + - Description + * - fess.yyyyMMddHHmmssSSS + - Documents indexés + * - fess_log + - Journaux d'accès + * - fess.suggest.yyyyMMddHHmmssSSS + - Mots suggérés + * - fess_config + - Configuration de |Fess| + * - fess_user + - Données utilisateur/rôle/groupe + * - configsync + - Configuration du dictionnaire + * - fess_suggest + - Métadonnées de suggestion + * - fess_suggest_array + - Métadonnées de suggestion + * - fess_suggest_badword + - Liste de mots interdits pour la suggestion + * - fess_suggest_analyzer + - Métadonnées de suggestion + * - fess_crawler + - Informations de crawl + +La partie qui suit ``fess.`` et ``fess.suggest.`` correspond à la date et à l'heure de création de l'index (17 chiffres, ``yyyyMMddHHmmssSSS``). + +Les index dont le nom commence par un point (.) sont des index système et ne sont donc pas affichés. +Pour afficher également les index système, cochez la case « Special ». + +Vérification du nombre de documents indexés +=========================================== + +Le nombre de documents indexés est affiché dans l'index fess comme illustré ci-dessous. + +|image1| + +Cliquer sur l'icône en haut à droite de chaque index affiche un menu d'opérations pour cet index. +Pour supprimer des documents indexés, utilisez l'écran de recherche d'administration. Veillez à ne pas supprimer avec « supprimer l'index ». + +.. |image0| image:: ../../../resources/images/en/15.10/admin/dashboard-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/dashboard-2.png +.. pdf :width: 400 px diff --git a/fr/15.10/admin/dataconfig-guide.rst b/fr/15.10/admin/dataconfig-guide.rst new file mode 100644 index 000000000..2778afb3a --- /dev/null +++ b/fr/15.10/admin/dataconfig-guide.rst @@ -0,0 +1,407 @@ +=========================== +Crawl de magasin de données +=========================== + +Présentation +============ + +Le crawl de magasin de données permet d'enregistrer dans l'index de |Fess| diverses sources de données autres que les sites Web ou les fichiers, telles que les bases de données relationnelles (MySQL, PostgreSQL, Oracle) et les fichiers CSV, pour la recherche en texte intégral. Les sources de données prises en charge peuvent être étendues à l'aide de plugins connecteurs de magasin de données. + +Dans |Fess|, vous pouvez cibler des sources de données telles que des bases de données ou des fichiers CSV pour le crawl. +Cette section explique la configuration du magasin de données nécessaire à cet effet. + +.. note:: + + ``DatabaseDataStore`` est fourni par le plugin connecteur de base de données (``fess-ds-db``), et ``CsvDataStore`` / ``CsvListDataStore`` par le plugin connecteur CSV (``fess-ds-csv``). Pour la liste des connecteurs disponibles, consultez :doc:`../config/datastore/ds-overview`. + +Gestion +======= + +Affichage +--------- + +Pour ouvrir la page de liste pour configurer le magasin de données illustrée ci-dessous, cliquez sur [Robot d'exploration > Magasin de données] dans le menu de gauche. + +|image0| + +Cliquez sur le nom de la configuration pour la modifier. + +Création de configuration +------------------------- + +Cliquez sur le bouton Nouvelle création pour ouvrir la page de configuration du magasin de données. + +|image1| + +Paramètres de configuration +--------------------------- + +Nom +:::: + +Spécifie le nom de la configuration de crawl. + +Nom du gestionnaire +::::::::::::::::::: + +Nom du gestionnaire qui traite le magasin de données. + +* DatabaseDataStore : Crawler une base de données +* CsvDataStore : Crawler des fichiers CSV/TSV cibles +* CsvListDataStore : Crawler un fichier CSV décrivant les chemins de fichiers cibles d'indexation + +La liste déroulante du nom du gestionnaire n'affiche que les gestionnaires fournis par les plugins connecteurs de magasin de données installés (``fess-ds-*``). +Si aucun plugin n'est installé, aucun gestionnaire ne peut être sélectionné. +Pour les autres gestionnaires, consultez les pages des connecteurs listées dans :doc:`../config/datastore/ds-overview`. +Notez que ``EsDataStore`` (le plugin ``fess-ds-elasticsearch``), décrit dans la documentation des versions précédentes, n'est plus publié depuis la version 15.6.0 et n'est pas disponible dans la version 15.10. + +Paramètres +:::::::::: + +Spécifie les paramètres relatifs au magasin de données. + +Le paramètre ``script_type`` sélectionne le moteur de script utilisé pour évaluer +le champ Script ci-dessous. Les nouvelles configurations sont préremplies avec +``script_type=javascript``. Si ``script_type`` n'est pas spécifié, le script est évalué en tant que Groovy. + +Script +:::::: + +Spécifie dans quel champ définir les valeurs obtenues du magasin de données. +Les expressions sont écrites dans la syntaxe du moteur de script sélectionné par +``script_type`` ci-dessus (JavaScript par défaut). + +.. warning:: + + Avec JavaScript, écrivez chaque ligne comme une expression pure sans point-virgule final. Une + ligne qui ne peut être analysée qu'en tant que bloc d'instructions — tout ce qui se termine + par un point-virgule, ou une déclaration ``let`` / ``const`` — est évaluée à ``null`` sauf si + elle contient un ``return`` explicite, et un mapping évalué à ``null`` ne définit tout + simplement pas ce champ. Il n'y a ni erreur ni ligne de journal ; le seul symptôme est un + champ qui se vide silencieusement. Voir :ref:`javascript-statement-null` + (dans :doc:`../config/scripting-javascript`). + +Valeur de boost +::::::::::::::: + +Spécifie la valeur de boost des documents lors du crawl avec cette configuration. + +Permission +:::::::::: + +Spécifie la permission pour cette configuration. +Pour la méthode de spécification de permission, par exemple, pour afficher les résultats de recherche aux utilisateurs appartenant au groupe developer, spécifiez {group}developer. +La spécification par utilisateur est {user}nom_utilisateur, par rôle {role}nom_rôle, par groupe {group}nom_groupe. + +Hôte virtuel +:::::::::::: + +Spécifie le nom d'hôte de l'hôte virtuel. +Pour plus de détails, consultez :doc:`Configuration de l'hôte virtuel dans le guide de configuration <../config/security-virtual-host>`. + +État +:::: + +Spécifie si cette configuration de crawl doit être utilisée. + +Description +::::::::::: + +Vous pouvez saisir une description. + +Suppression de configuration +---------------------------- + +Cliquez sur le nom de la configuration dans la page de liste, puis cliquez sur le bouton Supprimer pour afficher l'écran de confirmation. +Appuyer sur le bouton Supprimer supprimera la configuration. + +Exemples +======== + +DatabaseDataStore +----------------- + +Explication du crawl de base de données. + +À titre d'exemple, supposons qu'il y ait une table comme suit dans une base de données appelée testdb dans MySQL, et qu'elle puisse être connectée avec le nom d'utilisateur hoge et le mot de passe fuga. + +:: + + CREATE TABLE doc ( + id BIGINT NOT NULL AUTO_INCREMENT, + title VARCHAR(100) NOT NULL, + content VARCHAR(255) NOT NULL, + latitude VARCHAR(20), + longitude VARCHAR(20), + versionNo INTEGER NOT NULL, + PRIMARY KEY (id) + ); + +Ici, les données suivantes sont insérées. + +:: + + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 1', 'コンテンツ 1 です．', '37.77493', ' -122.419416', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 2', 'コンテンツ 2 です．', '34.701909', '135.494977', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 3', 'コンテンツ 3 です．', '-33.868901', '151.207091', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 4', 'コンテンツ 4 です．', '51.500152', '-0.113736', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 5', 'コンテンツ 5 です．', '35.681137', '139.766084', 1); + +Paramètres +:::::::::: + +Un exemple de configuration des paramètres est le suivant. + +:: + + driver=com.mysql.jdbc.Driver + url=jdbc:mysql://localhost:3306/testdb?useUnicode=true&characterEncoding=UTF-8 + username=hoge + password=fuga + sql=select * from doc + +Les paramètres sont au format « clé=valeur ». La description des clés est la suivante. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - driver + - Nom de la classe du pilote + * - url + - URL + * - username + - Nom d'utilisateur pour se connecter à la DB + * - password + - Mot de passe pour se connecter à la DB + * - sql + - Instruction SQL pour obtenir les cibles de crawl + +Tableau : Exemple de paramètres de configuration pour DB + + +Script +:::::: + +Un exemple de configuration du script est le suivant. + +:: + + url="http://SERVERNAME/" + id + host="SERVERNAME" + site="SERVERNAME" + title=title + content=content + cache=content + digest=content + anchor= + content_length=content.length() + last_modified=new java.util.Date() + location=latitude + "," + longitude + latitude=latitude + longitude=longitude + +Les paramètres sont au format « clé=valeur ». La description des clés est la suivante. + +Le côté valeur est écrit dans la syntaxe du moteur de script sélectionné par ``script_type``. +Les chaînes doivent être fermées par des guillemets doubles. En accédant par le nom de colonne de la base de données, vous obtenez cette valeur. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - url + - URL (configurez une URL accessible aux données selon votre environnement) + * - host + - Nom d'hôte + * - site + - Chemin du site + * - title + - Titre + * - content + - Contenu du document (chaîne cible d'indexation) + * - cache + - Cache du document (non cible d'indexation) + * - digest + - Partie digest affichée dans les résultats de recherche + * - anchor + - Liens contenus dans le document (généralement pas besoin de spécifier) + * - content_length + - Longueur du document + * - last_modified + - Date de dernière modification du document + +Tableau : Contenu de la configuration du script + + +Pilote +:::::: + +Un pilote est nécessaire pour se connecter à la base de données. Placez le fichier jar dans app/WEB-INF/lib. + +CsvDataStore +------------ + +Explication du crawl ciblant les fichiers CSV. + +Par exemple, créez le fichier test.csv dans le répertoire /home/taro/csv avec le contenu suivant. +L'encodage du fichier est Shift_JIS. + +:: + + 1,タイトル 1,テスト1です。 + 2,タイトル 2,テスト2です。 + 3,タイトル 3,テスト3です。 + 4,タイトル 4,テスト4です。 + 5,タイトル 5,テスト5です。 + 6,タイトル 6,テスト6です。 + 7,タイトル 7,テスト7です。 + 8,タイトル 8,テスト8です。 + 9,タイトル 9,テスト9です。 + + +Paramètres +:::::::::: + +Un exemple de configuration des paramètres est le suivant. + +:: + + directories=/home/taro/csv + fileEncoding=Shift_JIS + +Les paramètres sont au format « clé=valeur ». La description des clés est la suivante. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - directories + - Répertoire contenant les fichiers CSV (.csv ou .tsv) + * - files + - Fichier CSV (en cas de spécification directe) + * - fileEncoding + - Encodage du fichier CSV + * - separatorCharacter + - Caractère de séparation + + +Tableau : Exemple de paramètres de configuration pour fichiers CSV + + +Script +:::::: + +Un exemple de configuration du script est le suivant. + +:: + + url="http://SERVERNAME/" + cell1 + host="SERVERNAME" + site="SERVERNAME" + title=cell2 + content=cell3 + cache=cell3 + digest=cell3 + anchor= + content_length=cell3.length() + last_modified=new java.util.Date() + +Les paramètres sont au format « clé=valeur ». +Les clés sont les mêmes que pour le crawl de base de données. +Les données dans le fichier CSV sont conservées dans cell[nombre] (le nombre commence à 1). +Si aucune donnée n'existe dans la cellule du fichier CSV, elle peut être null. + +CsvListDataStore +---------------- + +Utilisé pour crawler un grand nombre de fichiers. +En plaçant un fichier CSV contenant les chemins des fichiers mis à jour et en ne crawlant que les chemins spécifiés, vous pouvez réduire le temps d'exécution du crawl. + +Le format pour décrire les chemins est le suivant. + +:: + + [action][chemin] + +Pour l'action, spécifiez l'un des suivants : + +* create : Le fichier a été créé +* modify : Le fichier a été mis à jour +* delete : Le fichier a été supprimé + +Par exemple, créez le fichier test.csv dans le répertoire /home/taro/csv avec le contenu suivant. +L'encodage du fichier est Shift_JIS. + +Les chemins sont décrits dans la même notation que lors de la spécification du chemin cible de crawl dans le crawl de fichiers. +Spécifiez comme suit : « file:/[chemin] » ou « smb://[chemin] ». + +:: + + modify,smb://servername/data/testfile1.txt + modify,smb://servername/data/testfile2.txt + modify,smb://servername/data/testfile3.txt + modify,smb://servername/data/testfile4.txt + modify,smb://servername/data/testfile5.txt + modify,smb://servername/data/testfile6.txt + modify,smb://servername/data/testfile7.txt + modify,smb://servername/data/testfile8.txt + modify,smb://servername/data/testfile9.txt + modify,smb://servername/data/testfile10.txt + + +Paramètres +:::::::::: + +Un exemple de configuration des paramètres est le suivant. + +:: + + directories=/home/taro/csv + fileEncoding=Shift_JIS + +Les paramètres sont au format « clé=valeur ». La description des clés est la suivante. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - directories + - Répertoire contenant les fichiers CSV (.csv ou .tsv) + * - fileEncoding + - Encodage du fichier CSV + * - separatorCharacter + - Caractère de séparation + + +Tableau : Exemple de paramètres de configuration pour fichiers CSV + + +Script +:::::: + +Un exemple de configuration du script est le suivant. + +:: + + event_type=cell1 + url=cell2 + +Les paramètres sont au format « clé=valeur ». +Les clés sont les mêmes que pour le crawl de base de données. + +Si une authentification est requise à la destination du crawl, vous devez également configurer ce qui suit. + +:: + + crawler.file.auth=example + crawler.file.auth.example.scheme=SAMBA + crawler.file.auth.example.username=username + crawler.file.auth.example.password=password + +Pages associées +=============== + +- :doc:`../config/datastore/index` +- :doc:`../config/datastore/ds-database` +- :doc:`../config/datastore/ds-overview` +- :doc:`../config/crawler-basic` + +.. |image0| image:: ../../../resources/images/en/15.10/admin/dataconfig-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/dataconfig-2.png diff --git a/fr/15.10/admin/dict-guide.rst b/fr/15.10/admin/dict-guide.rst new file mode 100644 index 000000000..e8b39cc0f --- /dev/null +++ b/fr/15.10/admin/dict-guide.rst @@ -0,0 +1,172 @@ +============ +Dictionnaire +============ + +Présentation +============ + +Cette section explique les paramètres de configuration concernant les dictionnaires. + +Les modifications du dictionnaire doivent être effectuées avec une compréhension des spécifications de chaque dictionnaire. +Un échec lors de la modification du dictionnaire peut rendre l'index inaccessible. + +.. note:: + + Si ``search_engine.type`` vaut ``vanilla`` ou ``aws`` (c'est-à-dire si OpenSearch n'a pas les plugins CodeLibs), la gestion des dictionnaires n'est pas disponible. Voir :doc:`../config/search-engine-type`. + +Liste +===== + +Pour ouvrir la page de liste des dictionnaires gérables illustrée ci-dessous, cliquez sur [Système > Dictionnaire] dans le menu de gauche. + + +|image0| + + +Portée de chaque dictionnaire et moment de prise en compte +=========================================================== + +Chaque dictionnaire s'applique à des champs différents et prend effet à un +moment différent. Si vous avez modifié un dictionnaire et que les résultats de +recherche ne changent pas, commencez par consulter ce tableau. + +.. list-table:: + :header-rows: 1 + :widths: 22 26 28 24 + + * - Dictionnaire + - Fichier + - Champs concernés + - Moment de prise en compte + * - Kuromoji + - ``ja/kuromoji.txt`` + - Uniquement les champs ``_ja``, comme ``content_ja`` + - À l'indexation (un nouveau crawl est nécessaire) + * - Synonymes + - ``synonym.txt`` + - ``content`` et ``title`` + - À la recherche (aucun nouveau crawl nécessaire) + * - Mappage (commun à toutes les langues) + - ``mapping.txt`` + - ``content`` et ``title`` + - À l'indexation (un nouveau crawl est nécessaire) + * - Mappage (par langue) + - ``ja/mapping.txt`` + - Uniquement les champs ``_ja``, comme ``content_ja`` + - À l'indexation (un nouveau crawl est nécessaire) + * - Protwords + - ``en/protwords.txt`` + - ``content`` et ``title`` + - À l'indexation et à la recherche + * - Mots vides + - ``en/stopwords.txt`` + - ``content`` et ``title`` + - À l'indexation et à la recherche + * - Remplacement du stemmer + - ``en/stemmer_override.txt`` + - ``content`` et ``title`` + - À l'indexation et à la recherche + +.. note:: + + Un analyseur est construit à l'ouverture de l'index : la mise à jour d'un + fichier de dictionnaire ne prend donc effet **qu'après la fermeture puis la + réouverture de l'index**. De plus, un dictionnaire qui s'applique à + l'indexation n'est pas appliqué rétroactivement aux documents déjà indexés ; + ceux-ci doivent être crawlés de nouveau. + Pour appliquer une modification, voir :ref:`dict-apply-changes`. + +.. warning:: + + Le dictionnaire de substitution de caractères qui s'applique à ``content``, + le champ auquel répondent la plupart des recherches, est le ``mapping.txt`` + de la **racine**, et non ``ja/mapping.txt``. Ils portent le même nom Mappage + mais ce sont deux fichiers distincts. + +.. _dict-apply-changes: + +Appliquer les modifications d'un dictionnaire +--------------------------------------------- + +Enregistrer un dictionnaire ne modifie pas les résultats de recherche, quel que soit le temps +d'attente. Le plugin configsync d'OpenSearch écrit les dictionnaires enregistrés dans leurs fichiers +environ une fois par minute, mais un analyseur ne lit ses dictionnaires qu'à l'ouverture de +l'index : un index déjà ouvert continue donc d'utiliser les anciens. Après avoir modifié des +dictionnaires, rechargez l'index de documents : + +1. Ouvrez [Informations système > Maintenance] dans le menu de gauche. +2. Cliquez sur [Recharger] sous « Recharger l'index des documents ». + +Le bouton écrit d'abord les dictionnaires enregistrés dans leurs fichiers, puis ferme et rouvre +l'index vers lequel pointe l'alias ``fess.update`` ; il n'est donc pas nécessaire d'attendre +l'écriture périodique. Un dictionnaire qui s'applique à la recherche, comme un synonyme, prend +effet dès que l'index est de nouveau ouvert. Pour un dictionnaire qui s'applique à l'indexation, +crawlez également de nouveau les documents concernés. + +.. warning:: + + Tant que l'index est fermé, et jusqu'à ce que ses shards soient de nouveau affectés après son + ouverture, l'index ne peut pas être interrogé : les recherches échouent ou ne renvoient aucun + résultat. Plus l'index est volumineux, plus cela dure ; rechargez-le donc à un moment calme. + +Pour faire la même chose depuis un script, sans l'écran d'administration, envoyez les mêmes +opérations à OpenSearch : + +:: + + curl -X POST "localhost:9200/_configsync/flush" + curl -X POST "localhost:9200/fess.update/_close" + curl -X POST "localhost:9200/fess.update/_open" + +``_configsync/flush`` écrit immédiatement les dictionnaires enregistrés dans leurs fichiers. Sans +cet appel, attendez au moins une minute après l'enregistrement avant de fermer l'index. + +Le dictionnaire utilisateur Kuromoji et les résultats de recherche +-------------------------------------------------------------------- + +Le champ ``content`` est analysé avec le tokenizer standard et ``cjk_bigram`` ; +il ne dépend donc pas de la façon dont Kuromoji découpe un mot. Enregistrer un +mot composé japonais dans le dictionnaire utilisateur Kuromoji puis relancer un +crawl ne change donc rien à ce que renvoie une recherche sur ``content``. +L'enregistrement se manifeste dans ``content_ja``, qui est ajouté à la requête +selon la langue de la demande. + +Kuromoji +======== + +Gère le dictionnaire pour l'analyse morphologique japonaise. +ja/kuromoji.txt est le fichier de dictionnaire pour l'analyse morphologique japonaise. + +Synonyme +======== + +Gère le dictionnaire de synonymes. +synonym.txt est le fichier de dictionnaire de synonymes utilisé en commun pour toutes les langues. + +Mapping +======= + +Gère le dictionnaire de remplacement de caractères. +mapping.txt est le fichier de dictionnaire de remplacement de mots commun à toutes les langues ou pour chaque langue. + +Protwords +========= + +Gère le dictionnaire de mots protégés. +protwords.txt est placé pour chaque langue et est un fichier de liste de mots à exclure du stemming. + +Mots vides +========== + +Gère le dictionnaire de mots vides. +stopwords.txt est placé pour chaque langue et est un fichier de liste de mots à exclure lors de la création de l'index. + +Remplacement de Stemmer +======================= + +Gère le dictionnaire de remplacement de stemmer. +stemmer_override.txt est placé pour chaque langue et est un fichier de dictionnaire de remplacement de mots pour remplacer le traitement de stemming. + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/dict-1.png + :height: 940px diff --git a/fr/15.10/admin/docreport-guide.rst b/fr/15.10/admin/docreport-guide.rst new file mode 100644 index 000000000..9921775dd --- /dev/null +++ b/fr/15.10/admin/docreport-guide.rst @@ -0,0 +1,73 @@ +==================== +Rapport de documents +==================== + +Présentation +============ + +La page Rapport de documents aide à faire le ménage dans les serveurs de fichiers crawlés et autres. +Elle liste les documents au contenu identique et ceux qui n'ont pas été modifiés depuis longtemps ; +chaque liste peut être téléchargée en CSV. + +Pour ouvrir la page, sélectionnez [Informations système > Rapport de documents] dans le menu de +gauche. La consultation nécessite le rôle ``admin-docreport`` ou ``admin-docreport-view``. La page ne +fait qu'afficher et télécharger des rapports ; elle ne modifie aucun document. + +Les deux onglets peuvent être restreints avec « Préfixe d’URL », par exemple ``smb://server/share/``. + +Doublons +======== + +Les documents au contenu identique ou presque identique sont regroupés, le groupe le plus grand en +premier. Les groupes reposent sur la signature de contenu calculée à l'indexation +(``content_minhash_bits``, la même qui regroupe les résultats de recherche en double) ; aucune +réindexation n'est donc nécessaire. Les documents dont le contenu ne contient aucun mot (comme les +fichiers vides) sont exclus. + +L'écran affiche au plus ``docreport.duplicate.group.size`` (par défaut : 100) groupes et au plus +``docreport.duplicate.docs.size`` (par défaut : 10) documents par groupe. Utilisez [Télécharger le +CSV] pour obtenir tous les groupes. Le CSV lit tous les groupes, même sur un grand index, avec les +colonnes +``group, groupSize, url, title, filename, contentLength, lastModified, owner, lastModifier, clickCount, docId``. + +.. note:: + + Le rapport de doublons a besoin de la signature de contenu, que les définitions d'index pour un OpenSearch sans les plugins CodeLibs (``search_engine.type`` valant ``vanilla``, ``aws`` ou l'ancien ``cloud``) ne calculent pas. Avec ces types, l'onglet « Doublons » est masqué et seul le rapport des documents inactifs est disponible. Voir :doc:`../config/search-engine-type`. + +Documents inactifs +================== + +Les documents dont la dernière modification est antérieure au nombre de jours indiqué (« Non modifiés +depuis (jours) », 365 par défaut d'après ``docreport.dormant.days``) sont listés, du plus ancien au +plus récent. Les documents sans date de dernière modification ne sont pas listés. Avec « Jamais +ouverts depuis les résultats de recherche », les documents cliqués depuis les résultats de recherche +sont exclus. + +L'écran affiche le nombre de documents correspondants, leur taille totale et une liste paginée. La +pagination s'arrête à ``indexer.max.result.window.size`` ; utilisez [Télécharger le CSV] pour obtenir +les documents au-delà. + +Paramètres +========== + +Les réglages suivants de ``fess_config.properties`` ajustent le rapport. + +.. list-table:: + :header-rows: 1 + :widths: 40 45 15 + + * - Propriété + - Description + - Défaut + * - ``docreport.duplicate.group.size`` + - Nombre maximal de groupes de doublons affichés par l’écran + - ``100`` + * - ``docreport.duplicate.docs.size`` + - Nombre maximal de documents listés par groupe à l’écran + - ``10`` + * - ``docreport.duplicate.export.page.size`` + - Nombre de signatures de contenu lues par requête lors du téléchargement du CSV + - ``10000`` + * - ``docreport.dormant.days`` + - Nombre de jours par défaut depuis la dernière modification au-delà duquel un document est inactif + - ``365`` diff --git a/fr/15.10/admin/duplicatehost-guide.rst b/fr/15.10/admin/duplicatehost-guide.rst new file mode 100644 index 000000000..c6bb04dca --- /dev/null +++ b/fr/15.10/admin/duplicatehost-guide.rst @@ -0,0 +1,59 @@ +============== +Hôte en double +============== + +Présentation +============ + +Cette section explique la configuration des hôtes en double. +Les hôtes en double sont utilisés lors du crawl lorsque vous souhaitez traiter différents noms d'hôte comme identiques. +Par exemple, cela peut être utilisé lorsque vous souhaitez traiter www.example.com et example.com comme le même site. + +Gestion +======= + +Affichage +--------- + +Pour ouvrir la page de liste pour configurer les hôtes en double illustrée ci-dessous, cliquez sur [Robot d'exploration > Hôte en double] dans le menu de gauche. + +|image0| + +Cliquez sur le nom de la configuration pour la modifier. + +Création de configuration +------------------------- + +Cliquez sur le bouton Nouvelle création pour ouvrir la page de configuration des hôtes en double. + +|image1| + +Paramètres de configuration +--------------------------- + +Nom régulier +::::::::::::: + +Spécifie le nom d'hôte régulier. Les noms d'hôte en double seront remplacés par le nom d'hôte régulier. + +Nom en double +:::::::::::::: + +Spécifie le nom d'hôte en double. Spécifiez le nom d'hôte que vous souhaitez remplacer. + +.. note:: + + Une URL dont le nom d'hôte correspond à un nom en double est remplacée par l'URL du nom régulier avant l'exploration. Cela concerne les URL saisies dans « URL » (les URL de départ) de la configuration de crawl ainsi que les URL des liens trouvés pendant le crawl. + Par conséquent, « URL incluses » et « URL exclues » de la configuration de crawl sont évaluées sur l'URL après remplacement. Écrivez-les avec le nom d'hôte du nom régulier. + + Par exemple, si le nom régulier est ``example.com`` et le nom en double ``www.example.com``, saisir uniquement ``https://www.example.com/.*`` dans « URL incluses » exclut l'URL de départ après remplacement (``https://example.com/``). + Dans ce cas, aucun document n'est enregistré dans l'index, et aucune erreur ni aucun message de journal n'est produit. + +Suppression de configuration +---------------------------- + +Cliquez sur le nom de la configuration dans la page de liste, puis cliquez sur le bouton Supprimer pour afficher l'écran de confirmation. +Appuyer sur le bouton Supprimer supprimera la configuration. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/duplicatehost-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/duplicatehost-2.png diff --git a/fr/15.10/admin/elevateword-guide.rst b/fr/15.10/admin/elevateword-guide.rst new file mode 100644 index 000000000..6ce364ec1 --- /dev/null +++ b/fr/15.10/admin/elevateword-guide.rst @@ -0,0 +1,106 @@ +============ +Mots ajoutés +============ + +Présentation +============ + +Cette section explique la configuration des candidats de mots ajoutés pour les suggestions. Les suggestions sont affichées en fonction des termes de recherche, et vous pouvez ajouter ces mots. + +Gestion +======= + +Affichage +--------- + +Pour ouvrir la page de liste pour configurer les mots ajoutés illustrée ci-dessous, cliquez sur [Suggérer > Élever un mot] dans le menu de gauche. + +|image0| + +Cliquez sur le nom de la configuration pour la modifier. + +Création de configuration +------------------------- + +Cliquez sur le bouton Nouvelle création pour ouvrir la page de configuration des mots ajoutés. + +|image1| + +Paramètres de configuration +--------------------------- + +Mot +:::: + +Spécifie le mot à afficher comme candidat de suggestion. + +Lecture +::::::: + +Spécifie la lecture phonétique du mot candidat de suggestion. + +Permission +:::::::::: + +Configure les informations de rôle pour le mot. +La suggestion n'est affichée que pour les utilisateurs ayant le rôle configuré. + +Étiquette +::::::::: + +Configure l'étiquette pour le mot. +Si une étiquette autre que celle configurée est sélectionnée, elle ne sera pas affichée dans les suggestions. + +Valeur de boost +::::::::::::::: + +Configure la valeur de boost pour le mot. + +Suppression de configuration +---------------------------- + +Cliquez sur le nom de la configuration dans la page de liste, puis cliquez sur le bouton Supprimer pour afficher l'écran de confirmation. +Appuyer sur le bouton Supprimer supprimera la configuration. + + +Téléchargement +============== + +Télécharge les mots enregistrés au format CSV. + +|image2| + +Contenu du CSV +-------------- + +La première ligne est l'en-tête. +Les mots ajoutés sont listés à partir de la deuxième ligne. + +:: + +"SuggestWord","Reading","Role","Label","Boost" +"fess","ふぇす","role1","label1","100" + +Téléversement +============= + +Enregistre les mots au format CSV. + +|image3| + +Contenu du CSV +-------------- + +La première ligne est l'en-tête. +Décrivez les mots ajoutés à partir de la deuxième ligne. + +:: + +"SuggestWord","Reading","Role","Label","Boost" +"fess","ふぇす","role1","label1","100" + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/elevateword-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/elevateword-2.png +.. |image2| image:: ../../../resources/images/en/15.10/admin/elevateword-3.png +.. |image3| image:: ../../../resources/images/en/15.10/admin/elevateword-4.png diff --git a/fr/15.10/admin/esreq-guide.rst b/fr/15.10/admin/esreq-guide.rst new file mode 100644 index 000000000..2c1d57aa4 --- /dev/null +++ b/fr/15.10/admin/esreq-guide.rst @@ -0,0 +1,53 @@ +====================== +Requête à OpenSearch +====================== + +Présentation +============ + +Cette page envoie à OpenSearch une requête écrite dans un fichier JSON. + +|image0| + +Cette page ne figure pas dans le menu. +Pour l'afficher, connectez-vous en tant qu'administrateur et saisissez ``/admin/sereq/`` comme chemin d'URL. +Le rôle ``admin`` (administrateurs) ou le rôle ``admin-sereq`` est nécessaire pour envoyer une requête. + +Méthode d'opération +=================== + +Envoi de requête +---------------- + +Créez sous forme de fichier JSON la requête que vous souhaitez envoyer à OpenSearch, sélectionnez ce fichier comme « Fichier de requête », puis cliquez sur le bouton « Envoyer » pour envoyer la requête à OpenSearch. +La réponse est téléchargée sous forme de fichier. + +Paramètres de configuration +--------------------------- + +Fichier de requête +:::::::::::::::::: + +Spécifiez le fichier qui contient la requête. + +Écrivez sur la première ligne `` ``, séparés par un seul espace, puis le corps de la requête (par exemple un DSL de requête) sur les lignes suivantes. +La méthode peut être GET, POST, PUT ou DELETE. Le chemin est le chemin sur OpenSearch ; le ``/`` initial peut être omis. +Par exemple, le contenu du fichier serait comme suit. + +:: + + POST /_search + { + "query": { + "match_all": {} + } + } + +Les sauts de ligne du corps sont supprimés et les lignes sont concaténées avant l'envoi. Une requête dont le corps contient un document JSON par ligne, comme ``_bulk``, ne peut donc pas être envoyée. + +.. warning:: + + Une requête dont la méthode est PUT ou DELETE est également envoyée telle quelle à OpenSearch. + Selon le contenu du fichier, elle peut modifier ou supprimer les index utilisés par |Fess| et entraîner une perte de données. Vérifiez soigneusement le contenu avant l'envoi. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/esreq-1.png diff --git a/fr/15.10/admin/failureurl-guide.rst b/fr/15.10/admin/failureurl-guide.rst new file mode 100644 index 000000000..148f1c63e --- /dev/null +++ b/fr/15.10/admin/failureurl-guide.rst @@ -0,0 +1,66 @@ +============ +URL en échec +============ + +Présentation +============ + +Cette section explique les URL en échec. +Les URL qui n'ont pas pu être obtenues lors du crawl sont enregistrées et peuvent être vérifiées comme URL en échec. + +Gestion +======= + +Affichage +--------- + +Pour ouvrir la page de liste pour vérifier les URL en échec, cliquez sur [Informations système > URL en échec] dans le menu de gauche. + +|image0| + +En cliquant sur le lien de vérification de l'URL en échec, les détails s'affichent. + +Détails de l'URL en échec +========================= + +Les détails de l'URL en échec enregistrent les exceptions survenues lors du crawl. + +|image1| + +Contenu des détails +------------------- + +URL +:::: + +URL où l'exception s'est produite. + +Nom du thread +::::::::::::: + +Nom du thread qui exécutait le crawl. +Peut être utilisé lors de la vérification des fichiers journaux. + +Type +:::: + +Type d'exception. + +Journal +::::::: + +Contenu de l'exception. + +Nombre d'erreurs +:::::::::::::::: + +Nombre de fois où cette exception s'est produite. + +Heure du dernier accès +:::::::::::::::::::::: + +Heure à laquelle cette exception s'est produite. + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/failureurl-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/failureurl-2.png diff --git a/fr/15.10/admin/fileauth-guide.rst b/fr/15.10/admin/fileauth-guide.rst new file mode 100644 index 000000000..805d4dee4 --- /dev/null +++ b/fr/15.10/admin/fileauth-guide.rst @@ -0,0 +1,85 @@ +=========================== +Authentification de fichier +=========================== + +Présentation +============ + +Cette section explique la méthode de configuration lorsqu'une authentification de fichier est requise pour le crawl ciblant les fichiers. +|Fess| prend en charge l'authentification FTP ou pour les dossiers partagés Windows. + +Gestion +======= + +Affichage +--------- + +Pour ouvrir la page de liste pour configurer l'authentification de fichier illustrée ci-dessous, cliquez sur [Robot d'exploration > Authentification de fichier] dans le menu de gauche. + +|image0| + +Cliquez sur le nom de la configuration pour la modifier. + +Création de configuration +------------------------- + +Cliquez sur le bouton Nouvelle création pour ouvrir la page de configuration d'authentification de fichier. + +|image1| + +Paramètres de configuration +--------------------------- + +Nom d'hôte +:::::::::: + +Spécifie le nom d'hôte du site nécessitant une authentification. +Utilisez le même nom que le nom d'hôte de l'URL à crawler. Cette authentification n'est pas utilisée pour une URL écrite avec un autre nom (par exemple, une adresse IP au lieu d'un alias). + +Port +:::: + +Spécifie le port du site nécessitant une authentification. +Si le champ est laissé vide, la liste affiche « N'importe lequel ». La signification d'un port vide dépend du schéma. + +* FTP : utilisée pour les URL de n'importe quel port (une URL sans port est traitée comme le port 21). +* SAMBA : utilisée uniquement pour les URL qui ne contiennent pas de port (``smb://serveur/partage/``). Elle n'est pas utilisée pour une URL qui contient un port, comme ``smb://serveur:445/partage/``. Pour crawler une URL contenant un port, indiquez ici le même port. + +Schéma +:::::: + +Sélectionnez la méthode d'authentification. +Vous pouvez utiliser FTP ou SAMBA (authentification de dossier partagé Windows). + +Nom d'utilisateur +::::::::::::::::: + +Spécifie le nom d'utilisateur pour se connecter au site d'authentification. + +Mot de passe +:::::::::::: + +Spécifie le mot de passe pour se connecter au site d'authentification. + +Paramètres +:::::::::: + +Configure s'il existe des valeurs de configuration nécessaires pour se connecter au site d'authentification. Pour SAMBA, vous pouvez définir la valeur de domain. Pour la configurer, décrivez comme suit : + +:: + + domain=FUGA + +Configuration de crawl de fichiers +::::::::::::::::::::::::::::::::::: + +Spécifie la configuration de crawl qui utilisera ces paramètres d'authentification. + +Suppression de configuration +---------------------------- + +Cliquez sur le nom de la configuration dans la page de liste, puis cliquez sur le bouton Supprimer pour afficher l'écran de confirmation. +Appuyer sur le bouton Supprimer supprimera la configuration. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/fileauth-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/fileauth-2.png diff --git a/fr/15.10/admin/fileconfig-guide.rst b/fr/15.10/admin/fileconfig-guide.rst new file mode 100644 index 000000000..aeaf68876 --- /dev/null +++ b/fr/15.10/admin/fileconfig-guide.rst @@ -0,0 +1,263 @@ +================================================================ +Crawl de système de fichiers (recherche sur serveur de fichiers) +================================================================ + +Présentation +============ + +Le crawl de fichiers permet d'enregistrer dans l'index de |Fess| les documents présents sur les serveurs de fichiers internes, les dossiers partagés Windows ou le stockage cloud, afin de les rendre disponibles pour une recherche en texte intégral (recherche sur serveur de fichiers). De nombreux formats de fichiers sont pris en charge, tels que Word, Excel, PowerPoint et PDF. + +La page de configuration de crawl de fichiers permet de gérer la configuration pour crawler les fichiers sur le système de fichiers ou les dossiers partagés sur le réseau. + +Le crawl cible est déterminé par le protocole spécifié dans le « chemin » : + +- ``file:/`` … système de fichiers local ou monté +- ``smb://`` … serveur de fichiers/dossier partagé Windows (SMB/CIFS) +- ``smb1://`` … serveur de fichiers/dossier partagé Windows utilisant l'ancien protocole SMB1 +- ``ftp://`` … serveur FTP +- ``s3://`` … bucket Amazon S3 (nécessite le plugin ``fess-storage-s3``) +- ``gcs://`` … bucket Google Cloud Storage (nécessite le plugin ``fess-storage-gcs``) + +Gestion +======= + +Affichage +--------- + +Pour ouvrir la page de liste pour configurer le crawl de fichiers illustrée ci-dessous, cliquez sur [Robot d'exploration > Système de fichiers] dans le menu de gauche. + +|image0| + +Cliquez sur le nom de la configuration pour la modifier. + +Création de configuration +------------------------- + +Cliquez sur le bouton Nouvelle création pour ouvrir la page de configuration de crawl de fichiers. + +|image1| + +Paramètres de configuration +--------------------------- + +Nom +:::: + +Nom de la configuration. + +Chemin +:::::: + +Ce chemin spécifie l'emplacement de départ du crawl (ex. : file:/, smb://, s3://, gcs://). + +Chemins à crawler +::::::::::::::::: + +Les chemins correspondant à l'expression régulière (format Java) spécifiée dans cet élément seront ciblés par le crawler |Fess|. + +Chemins exclus du crawl +::::::::::::::::::::::: + +Les chemins correspondant à l'expression régulière (format Java) spécifiée dans cet élément ne seront pas ciblés par le crawler |Fess|. + +Chemins à indexer +::::::::::::::::: + +Les chemins correspondant à l'expression régulière (format Java) spécifiée dans cet élément seront ciblés pour la recherche. + +Chemins exclus de l'indexation +::::::::::::::::::::::::::::::: + +Les chemins correspondant à l'expression régulière (format Java) spécifiée dans cet élément ne seront pas ciblés pour la recherche. + +Paramètres de configuration +:::::::::::::::::::::::::::: + +Vous pouvez spécifier les informations de configuration du crawl. + +Lors du crawl de chemins commençant par ``file:`` (système de fichiers local ou monté), ``client.followSymlink`` indique si les liens symboliques sont suivis. La valeur par défaut est ``true`` (les liens sont suivis). Avec ``false``, les liens symboliques sont ignorés et les fichiers vers lesquels ils pointent ne sont pas crawlés via le lien (chaque lien ignoré est consigné au niveau INFO dans ``fess-crawler.log``). Suivre un lien enregistre le fichier cible une seconde fois avec les permissions de la configuration qui contient le lien ; envisagez donc ``false`` si vous crawlez un partage lisible par plus d'utilisateurs que l'arborescence vers laquelle pointent ses liens. + +:: + + client.followSymlink=false + +Profondeur +:::::::::: + +Spécifie la profondeur de la structure du système de fichiers à crawler. + +Nombre maximum d'accès +:::::::::::::::::::::: + +Spécifie le nombre de chemins à indexer. + +Nombre de threads +::::::::::::::::: + +Spécifie le nombre de threads à utiliser pour cette configuration. + +Intervalle +:::::::::: + +Spécifie le temps d'attente pour chaque thread lors du crawl des chemins. + +Valeur de boost +::::::::::::::: + +La valeur de boost est la priorité des documents indexés par cette configuration. + +Permission +:::::::::: + +Spécifie la permission pour cette configuration. +Pour la méthode de spécification de permission, par exemple, pour afficher les résultats de recherche aux utilisateurs appartenant au groupe developer, spécifiez {group}developer. +La spécification par utilisateur est {user}nom_utilisateur, par rôle {role}nom_rôle, par groupe {group}nom_groupe. + +Hôte virtuel +:::::::::::: + +Spécifie le nom d'hôte de l'hôte virtuel. +Pour plus de détails, consultez :doc:`Configuration de l'hôte virtuel dans le guide de configuration <../config/security-virtual-host>`. + +État +:::: + +Lorsque cette configuration est active, la tâche du crawler par défaut effectue le crawl en incluant cette configuration. + +Description +::::::::::: + +Vous pouvez saisir une description. + +Suppression de configuration +---------------------------- + +Cliquez sur le nom de la configuration dans la page de liste, puis cliquez sur le bouton Supprimer pour afficher l'écran de confirmation. Appuyer sur le bouton Supprimer supprimera la configuration. + +Exemples +======== + +Crawler les fichiers locaux +--------------------------- + +Pour crawler les fichiers sous /home/share, la configuration serait la suivante. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - Nom + - Valeur + * - Nom + - Répertoire partagé + * - Chemin + - file:/home/share + +Les autres paramètres peuvent utiliser la configuration par défaut. + +Crawler les dossiers partagés Windows +------------------------------------- + +Pour crawler les fichiers sous \\SERVER\SharedFolder, la configuration serait la suivante. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - Nom + - Valeur + * - Nom + - Dossier partagé + * - Chemin + - smb://SERVER/SharedFolder/ + +Si l'accès au dossier partagé nécessite un nom d'utilisateur/mot de passe, vous devez créer une configuration d'authentification de fichier depuis [Robot d'exploration > Authentification de fichier] dans le menu de gauche. +La configuration serait alors la suivante. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - Nom + - Valeur + * - Nom d'hôte + - SERVER + * - Schéma + - SAMBA + * - Nom d'utilisateur + - (Veuillez saisir) + * - Mot de passe + - (Veuillez saisir) + +Crawler les buckets Amazon S3 +----------------------------- + +Pour crawler les fichiers dans le bucket my-bucket, la configuration serait la suivante. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - Nom + - Valeur + * - Nom + - Bucket S3 + * - Chemin + - s3://my-bucket/ + +L'accès à S3 nécessite des identifiants d'authentification. Ajoutez ce qui suit aux « Paramètres de configuration » : + +:: + + client.endpoint=https://s3.ap-northeast-1.amazonaws.com + client.accessKey=VOTRE_CLE_ACCES + client.secretKey=VOTRE_CLE_SECRETE + client.region=ap-northeast-1 + +.. note:: + La prise en charge d'Amazon S3 et des stockages compatibles S3 provient du plugin + ``fess-storage-s3``, qui ne fait pas partie de la distribution. Installez-le depuis la page + **Système > Plugin** de l'écran d'administration ou avec + ``bin/fess-setup install plugin fess-storage-s3``. + +Crawler les buckets Google Cloud Storage +----------------------------------------- + +Pour crawler les fichiers dans le bucket my-gcs-bucket, la configuration serait la suivante. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - Nom + - Valeur + * - Nom + - Bucket GCS + * - Chemin + - gcs://my-gcs-bucket/ + +L'accès à GCS nécessite des identifiants d'authentification. Ajoutez ce qui suit aux « Paramètres de configuration » : + +:: + + client.projectId=votre-id-projet + client.credentialsFile=/chemin/vers/service-account.json + +.. note:: + La prise en charge de Google Cloud Storage provient du plugin ``fess-storage-gcs``, qui ne + fait pas partie de la distribution. Installez-le depuis la page **Système > Plugin** de + l'écran d'administration ou avec ``bin/fess-setup install plugin fess-storage-gcs``. + +Pages associées +=============== + +- :doc:`../config/crawler-basic` +- :doc:`fileauth-guide` +- :doc:`../config/datastore/ds-overview` +- :doc:`../config/search-basic` +- :doc:`../user/index` + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/fileconfig-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/fileconfig-2.png +.. pdf :height: 940 px diff --git a/fr/15.10/admin/general-guide.rst b/fr/15.10/admin/general-guide.rst new file mode 100644 index 000000000..c332c0029 --- /dev/null +++ b/fr/15.10/admin/general-guide.rst @@ -0,0 +1,684 @@ +======= +Général +======= + +Présentation +============ + +Cette page d'administration vous permet de gérer les paramètres de |Fess|. +Vous pouvez modifier divers paramètres de |Fess| sans redémarrer |Fess|. + +Contenu de la configuration +=========================== + +Système +------- + +|image0| + +Réponse JSON +:::::::::::: + +Spécifie s'il faut activer l'API JSON. + +Connexion requise +::::::::::::::::: + +Spécifie si la connexion est requise pour la fonction de recherche. + +Afficher le lien de connexion +:::::::::::::::::::::::::::::: + +Configure l'affichage du lien vers la page de connexion sur l'écran de recherche. + +Réduire les résultats en double +:::::::::::::::::::::::::::::::: + +Configure l'activation de la réduction des résultats en double. + +Si ``search_engine.type`` vaut ``vanilla`` ou ``aws``, cet élément n'est pas affiché et la réduction reste toujours désactivée (voir :doc:`../config/search-engine-type`). + +Afficher la miniature +::::::::::::::::::::: + +Configure l'activation de l'affichage des vignettes. + +Propriétés système +:::::::::::::::::: + +Configure les propriétés système de |Fess|. +Spécifiez au format ``clé=valeur``, une par ligne. + +Valeur d'étiquette par défaut +:::::::::::::::::::::::::::::: + +Décrit la valeur d'étiquette à ajouter aux critères de recherche par défaut. +Pour spécifier par rôle ou groupe, ajoutez « role: » ou « group: » comme « role:admin=label1 ». + +Valeur de tri par défaut +::::::::::::::::::::::::: + +Décrit la valeur de tri à ajouter aux critères de recherche par défaut. +Pour spécifier par rôle ou groupe, ajoutez « role: » ou « group: » comme « role:admin=content_length.desc ». + +Hôte virtuel +:::::::::::: + +Configure l'hôte virtuel. +Pour plus de détails, consultez :doc:`Configuration de l'hôte virtuel dans le guide de configuration <../config/security-virtual-host>`. + +Réponse de mot populaire +:::::::::::::::::::::::: + +Spécifie s'il faut activer l'API des mots populaires. + +Encodage du fichier CSV +:::::::::::::::::::::::: + +Spécifie l'encodage des fichiers CSV à télécharger. + +Ajouter des paramètres de recherche +:::::::::::::::::::::::::::::::::::: + +Active le passage de paramètres à l'affichage des résultats de recherche. + +Proxy de fichier de recherche +::::::::::::::::::::::::::::: + +Spécifie s'il faut activer le proxy de fichier pour les résultats de recherche. + +Utiliser les paramètres régionaux du navigateur +:::::::::::::::::::::::::::::::::::::::::::::::: + +Spécifie s'il faut utiliser les paramètres régionaux du navigateur pour la recherche. + +Type de SSO +::::::::::: + +Spécifie le type d'authentification unique (Single Sign-On). + +- **Aucun** : Ne pas utiliser le SSO +- **OpenID Connect** : Utiliser OpenID Connect (nécessite le plugin ``fess-sso-oidc``) +- **SAML** : Utiliser SAML (nécessite le plugin ``fess-sso-saml``) +- **SPNEGO** : Utiliser SPNEGO (nécessite le plugin ``fess-sso-spnego``) +- **Entra ID** : Utiliser Microsoft Entra ID (nécessite le plugin ``fess-sso-entraid``) + +Robot d'exploration +------------------- + +|image1| + +Vérifier la dernière modification +:::::::::::::::::::::::::::::::::: + +Active le crawl différentiel. + +Pour les URL HTTP/HTTPS, quand le ``Last-Modified`` de la réponse HEAD ne permet pas de décider +(aucune date de modification dans l'index, pas de ``Last-Modified`` dans la réponse HEAD, ou un statut +HEAD autre que 200/404), le GET est envoyé comme GET conditionnel avec ``If-None-Match`` (l'``ETag`` +indexé) et/ou ``If-Modified-Since``. Une page qui répond ``304 Not Modified`` est traitée comme une +page inchangée et n'est pas récupérée à nouveau. Pour tout récupérer à nouveau, par exemple après +avoir modifié les paramètres de crawl, désactivez ce réglage le temps d'un crawl. + +Configuration du robot d'exploration simultané +::::::::::::::::::::::::::::::::::::::::::::::: + +Spécifie le nombre de configurations de crawl à exécuter simultanément. + +Agent utilisateur +::::::::::::::::: + +Spécifie le nom de l'agent utilisateur utilisé par le robot d'exploration. + +Supprimer les anciens documents +:::::::::::::::::::::::::::::::: + +Spécifie la durée de validité des documents, en jours. Un document enregistré ou mis à jour par un crawl expire ce nombre de jours après le début du crawl, et un document retrouvé lors du crawl suivant voit sa validité prolongée. Le travail Doc Purger du planificateur de tâches (exécuté chaque minute par défaut) supprime de l'index les documents expirés. + +La valeur par défaut est ``3`` et les valeurs autorisées vont de ``-1`` à ``1000``. Avec ``-1``, aucune expiration n'est définie pour les documents enregistrés ou mis à jour par les crawls suivants (une expiration déjà définie n'est pas prolongée). + +Ignorer les types d'échec +::::::::::::::::::::::::: + +Les URL en échec qui dépassent le seuil sont exclues des cibles de crawl, mais les noms d'exception spécifiés ici seront des cibles de crawl même si elles dépassent le seuil. + +Seuil de nombre d'échecs +:::::::::::::::::::::::: + +Si le document cible de crawl est enregistré dans les URL en échec plus que le nombre de fois spécifié ici, il sera exclu du prochain crawl. + +Journalisation +-------------- + +Journal de recherche +:::::::::::::::::::: + +Spécifie s'il faut activer l'enregistrement du journal de recherche. + +Journal utilisateur +::::::::::::::::::: + +Spécifie s'il faut activer l'enregistrement du journal utilisateur. + +Journal des favoris +::::::::::::::::::: + +Spécifie s'il faut activer l'enregistrement du journal des favoris. + +Supprimer les anciens journaux de recherche +::::::::::::::::::::::::::::::::::::::::::: + +Supprime les journaux de recherche antérieurs au nombre de jours spécifié. La valeur par défaut est ``-1`` ; avec ``-1``, les journaux ne sont pas supprimés et sont conservés indéfiniment. +Les journaux de clics, de favoris et de chat sont supprimés selon le même nombre de jours. + +Supprimer les anciens journaux de tâches +:::::::::::::::::::::::::::::::::::::::: + +Supprime les journaux de tâches antérieurs au nombre de jours spécifié. La valeur par défaut est ``-1`` ; avec ``-1``, ils ne sont pas supprimés. + +Supprimer les anciens journaux utilisateur +:::::::::::::::::::::::::::::::::::::::::: + +Supprime les journaux utilisateur antérieurs au nombre de jours spécifié. La valeur par défaut est ``-1`` ; avec ``-1``, ils ne sont pas supprimés. + +Noms de robots pour supprimer les journaux +::::::::::::::::::::::::::::::::::::::::::: + +Spécifie le nom du bot à exclure des journaux de recherche. + +Niveau de journalisation +::::::::::::::::::::::::: + +Spécifie le niveau de journalisation de fess.log. + +Suggérer +-------- + +Suggérer à partir des termes de recherche +:::::::::::::::::::::::::::::::::::::::::: + +Spécifie s'il faut générer des candidats de suggestion à partir des journaux de recherche. + +Suggérer à partir des documents +:::::::::::::::::::::::::::::::: + +Spécifie s'il faut générer des candidats de suggestion à partir des documents indexés. + +Supprimer les anciennes informations de suggestion +::::::::::::::::::::::::::::::::::::::::::::::::::: + +Supprime les données de suggestion antérieures au nombre de jours spécifié. + +LDAP +---- + +|image2| + +URL LDAP +:::::::: + +Spécifie l'URL du serveur LDAP. + +DN de base +:::::::::: + +Spécifie le nom distinctif de base pour se connecter à l'écran de recherche. + +DN de liaison +::::::::::::: + +Spécifie le DN de liaison de l'administrateur. + +Mot de passe +:::::::::::: + +Spécifie le mot de passe du DN de liaison. + +DN de l'utilisateur +::::::::::::::::::: + +Spécifie le nom distinctif de l'utilisateur. + +Filtre de compte +:::::::::::::::: + +Spécifie le nom commun de l'utilisateur, l'uid, etc. + +Filtre de groupe +:::::::::::::::: + +Spécifie les conditions de filtre pour les groupes à récupérer. + +Attribut memberOf +::::::::::::::::: + +Spécifie le nom de l'attribut memberOf disponible sur le serveur LDAP. +Pour Active Directory, c'est memberOf. +Pour d'autres serveurs LDAP, cela peut être isMemberOf. + +Authentification de sécurité +:::::::::::::::::::::::::::: + +Spécifie la méthode d'authentification de sécurité LDAP (ex. : simple). + +Fabrique de contexte initial +::::::::::::::::::::::::::::: + +Spécifie la classe de fabrique de contexte initial LDAP (ex. : com.sun.jndi.ldap.LdapCtxFactory). + +OpenID Connect +-------------- + +|image3| + +ID client +::::::::: + +Spécifie l'ID client du fournisseur OpenID Connect. + +Secret client +::::::::::::: + +Spécifie le secret client du fournisseur OpenID Connect. + +URL du serveur d'autorisation +:::::::::::::::::::::::::::::: + +Spécifie l'URL du serveur d'autorisation pour OpenID Connect. + +URL du serveur de jetons +:::::::::::::::::::::::: + +Spécifie l'URL du serveur de jetons pour OpenID Connect. + +URL de redirection +:::::::::::::::::: + +Spécifie l'URL de redirection pour OpenID Connect. + +Portée +:::::: + +Spécifie la portée pour OpenID Connect. + +URL de base +::::::::::: + +Spécifie l'URL de base pour OpenID Connect. + +Groupes par défaut +:::::::::::::::::: + +Spécifie les groupes par défaut à attribuer aux utilisateurs lors de l'authentification OpenID Connect. + +Rôles par défaut +:::::::::::::::: + +Spécifie les rôles par défaut à attribuer aux utilisateurs lors de l'authentification OpenID Connect. + +SAML +---- + +|image4| + +ID d'entité IdP +::::::::::::::: + +Spécifie l'ID d'entité de l'IdP (Identity Provider). + +URL SSO IdP +::::::::::: + +Spécifie l'URL du service d'authentification unique de l'IdP. + +URL SLO IdP +::::::::::: + +Spécifie l'URL du service de déconnexion unique de l'IdP. + +Certificat X.509 IdP +:::::::::::::::::::: + +Spécifie le certificat de clé publique X.509 pour la vérification de signature d'assertion SAML de l'IdP. +Spécifiez uniquement le contenu encodé en Base64 sans les lignes ``-----BEGIN CERTIFICATE-----`` et ``-----END CERTIFICATE-----``. + +URL de base du SP +::::::::::::::::: + +Spécifie l'URL de base du fournisseur de services SAML. + +ID d'entité SP +:::::::::::::: + +Spécifie l'ID d'entité du SP (Service Provider). +Configuré automatiquement lorsque l'``URL de base du SP`` est définie. + +URL ACS du SP +::::::::::::: + +Spécifie l'URL du service consommateur d'assertions (ACS) qui reçoit les assertions SAML. +Configuré automatiquement lorsque l'``URL de base du SP`` est définie. + +URL SLO du SP +::::::::::::: + +Spécifie l'URL du service de déconnexion unique du SP. +Configuré automatiquement lorsque l'``URL de base du SP`` est définie. + +Format NameID du SP +::::::::::::::::::: + +Spécifie le format NameID utilisé dans les assertions SAML. + +Nom d'attribut de groupe +:::::::::::::::::::::::: + +Spécifie le nom d'attribut pour récupérer les groupes de la réponse SAML. + +Nom d'attribut de rôle +:::::::::::::::::::::: + +Spécifie le nom d'attribut pour récupérer les rôles de la réponse SAML. + +Groupes par défaut +:::::::::::::::::: + +Spécifie les groupes par défaut à attribuer aux utilisateurs lors de l'authentification SAML. + +Rôles par défaut +:::::::::::::::: + +Spécifie les rôles par défaut à attribuer aux utilisateurs lors de l'authentification SAML. + +SPNEGO +------ + +|image5| + +.. note:: + Les paramètres SPNEGO sont partagés au niveau du processus au sein de la bibliothèque sous-jacente ; un redémarrage de |Fess| est donc nécessaire pour appliquer les modifications qui leur sont apportées. + +Configuration Krb5 +::::::::::::::::::: + +Spécifie le chemin vers le fichier de configuration Kerberos 5. + +Configuration de connexion +:::::::::::::::::::::::::: + +Spécifie le chemin vers le fichier de configuration de connexion JAAS (Java Authentication and Authorization Service). + +Module client de connexion +:::::::::::::::::::::::::: + +Spécifie le nom du module de connexion client JAAS. + +Module serveur de connexion +::::::::::::::::::::::::::: + +Spécifie le nom du module de connexion serveur JAAS. + +Nom d'utilisateur de pré-authentification +:::::::::::::::::::::::::::::::::::::::::: + +Spécifie le nom d'utilisateur pour la pré-authentification SPNEGO. +Laisser le nom d'utilisateur et le mot de passe vides active la connexion du serveur basée sur un keytab. + +Mot de passe de pré-authentification +::::::::::::::::::::::::::::::::::::: + +Spécifie le mot de passe pour la pré-authentification SPNEGO. + +Autoriser l'authentification Basic +::::::::::::::::::::::::::::::::::: + +Spécifie s'il faut autoriser l'authentification Basic comme solution de repli. + +Autoriser l'authentification Basic non sécurisée +::::::::::::::::::::::::::::::::::::::::::::::::: + +Spécifie s'il faut autoriser l'authentification Basic sur les connexions non sécurisées (HTTP). +Ceci est désactivé par défaut afin d'éviter que les identifiants ne soient transmis en clair (l'authentification Basic reste proposée sur les connexions HTTPS). + +Invite NTLM +:::::::::::: + +Spécifie s'il faut activer l'invite NTLM. + +Autoriser localhost +::::::::::::::::::: + +Spécifie s'il faut autoriser l'accès depuis localhost. +Ceci est désactivé par défaut pour des raisons de sécurité, car lorsqu'il est activé, les requêtes provenant du même hôte sont authentifiées en tant qu'utilisateur du système d'exploitation du serveur sans vérification Kerberos. + +Autoriser la délégation +::::::::::::::::::::::: + +Spécifie s'il faut autoriser la délégation Kerberos. + +Niveau de journalisation +:::::::::::::::::::::::: + +Spécifie le niveau de sortie du journal pour l'authentification SPNEGO sous forme de valeur numérique de 0 à 7. +Si ce champ est laissé vide ou défini sur une valeur non numérique, le niveau de journalisation est détecté automatiquement. + +Entra ID +-------- + +|image6| + +Locataire (ID ou domaine) +::::::::::::::::::::::::: + +Spécifie l'ID ou le domaine du locataire pour Microsoft Entra ID. + +Autorité +:::::::: + +Spécifie l'URL de l'autorité pour Microsoft Entra ID. + +ID client +::::::::: + +Spécifie l'ID d'application (client) pour Microsoft Entra ID. + +Secret client +::::::::::::: + +Spécifie le secret client pour Microsoft Entra ID. + +URL de réponse +:::::::::::::: + +Spécifie l'URL de réponse (redirection) pour Microsoft Entra ID. + +TTL de l'état +::::::::::::: + +Spécifie la durée de vie (TTL) de l'état d'authentification. + +Champs de permissions +::::::::::::::::::::: + +Spécifie les champs pour récupérer les informations de permissions depuis Entra ID. + +Groupes par défaut +:::::::::::::::::: + +Spécifie les groupes par défaut à attribuer aux utilisateurs lors de l'authentification Entra ID. + +Rôles par défaut +:::::::::::::::: + +Spécifie les rôles par défaut à attribuer aux utilisateurs lors de l'authentification Entra ID. + +Utiliser le service de domaine +::::::::::::::::::::::::::::::: + +Spécifie s'il faut utiliser le service de domaine Entra ID. + +Avis +---- + +|image7| + +.. note:: + + Les avis acceptent le HTML. Lorsqu'un thème de recherche affiche un avis, seules les balises et les attributs d'une liste d'autorisation sont conservés : les éléments `` + + + +Si vous utilisez déjà jQuery sur votre site, il n'est pas nécessaire d'ajouter l'élément script jQuery. + +La fonction de suggestion utilise l'API de suggestion de |Fess| (``/api/v2/suggest-words``). +Modifiez ``url`` pour qu'elle corresponde à l'URL de votre serveur |Fess| configuré. + +Les principales options pouvant être spécifiées pour ``suggestor`` sont les suivantes. + +.. list-table:: Principales options de suggestor + :header-rows: 1 + :widths: 25 75 + + * - Option + - Description + * - ``ajaxinfo.url`` + - L'URL de l'API de suggestion. Spécifiez ``/api/v2/suggest-words`` de votre serveur |Fess|. + * - ``ajaxinfo.fn`` + - Un tableau de noms de champs à partir desquels obtenir des suggestions. Vous pouvez utiliser la valeur par défaut ``["_default", "content", "title"]`` telle quelle. + * - ``ajaxinfo.num`` + - Le nombre maximal de candidats de suggestion affichés. + * - ``ajaxinfo.lang`` + - La langue utilisée pour affiner les candidats de suggestion (facultatif). + * - ``minterm`` + - Le nombre minimal de caractères saisis avant que les suggestions ne soient demandées. + * - ``adjustWidthVal`` + - La valeur (en pixels) ajoutée à la largeur du champ de saisie pour ajuster la largeur de la zone de suggestion. + * - ``searchForm`` + - L'élément du formulaire de recherche qui est envoyé lorsqu'un candidat est sélectionné. + * - ``boxCssInfo`` + - Le CSS appliqué à la zone de suggestion. + * - ``listSelectedCssInfo`` + - Le CSS appliqué au candidat sélectionné (facultatif). + * - ``listDeselectedCssInfo`` + - Le CSS appliqué aux candidats non sélectionnés (facultatif). + +Pour la valeur spécifiée dans "z-index", veuillez spécifier une valeur qui ne chevauche pas avec d'autres éléments. + +.. note:: + Lorsque le formulaire de recherche est placé sur une page dont le domaine diffère du serveur |Fess|, la requête vers l'API de suggestion devient une requête cross-origin. + |Fess| autorise toutes les origines par défaut (``api.cors.allow.origin=*``), elle fonctionne donc telle quelle. + Pour restreindre l'accès, modifiez ``api.cors.allow.origin`` dans ``fess_config.properties``. + +.. note:: + ``/api/v2/suggest-words`` est l'API fournie par |Fess| lui-même. + Le point de terminaison ``/api/v1/suggest-words`` utilisé dans les versions antérieures n'est plus fourni par le cœur de |Fess|, et le plugin ``fess-webapp-v1-api`` doit être installé pour l'utiliser. + Pour les nouvelles installations, utilisez ``/api/v2/suggest-words``. diff --git a/fr/15.10/config/search-geosearch.rst b/fr/15.10/config/search-geosearch.rst new file mode 100644 index 000000000..799853643 --- /dev/null +++ b/fr/15.10/config/search-geosearch.rst @@ -0,0 +1,353 @@ +============================== +Recherche par géolocalisation +============================== + +Aperçu +====== + +|Fess| peut effectuer des recherches avec une zone géographique spécifiée sur des documents contenant des informations de géolocalisation (latitude et longitude). +En utilisant cette fonction, vous pouvez rechercher des documents situés dans une certaine distance d'un point spécifique, +ou créer un système de recherche intégré avec des services de cartographie comme Google Maps. + +En interne, |Fess| utilise la requête geo-distance d'OpenSearch pour filtrer les documents +dont les coordonnées se trouvent dans la distance spécifiée à partir d'un point central. + +Cas d'utilisation +================= + +La recherche par géolocalisation peut être utilisée pour les applications suivantes : + +- Recherche de magasins : Rechercher les magasins proches de la position actuelle de l'utilisateur +- Recherche immobilière : Rechercher des propriétés dans une certaine distance d'une gare ou d'une installation spécifique +- Recherche d'événements : Rechercher des informations sur des événements autour d'un lieu spécifié +- Recherche d'installations : Recherche à proximité de sites touristiques ou d'installations publiques + +Méthode de configuration +======================== + +Configuration lors de la génération de l'index +----------------------------------------------- + +Définition du champ de géolocalisation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Dans |Fess|, le champ ``location`` est défini par défaut pour stocker les informations de géolocalisation. +Ce champ est configuré comme un type ``geo_point`` d'OpenSearch. + +Format d'enregistrement des informations de géolocalisation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Lors de la génération de l'index, définissez la latitude et la longitude séparées par une virgule dans le champ ``location``. + +**Format :** + +:: + + latitude,longitude + +**Exemple :** + +:: + + 45.17614,-93.87341 + +.. note:: + La latitude doit être spécifiée dans la plage de -90 à 90, et la longitude dans la plage de -180 à 180. + +Exemple de configuration pour l'exploration de source de données +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Lors de l'utilisation de l'exploration de source de données, définissez la latitude et la longitude dans le champ ``location`` +à partir d'une source de données contenant des informations de géolocalisation. + +**Exemple : Récupération depuis une base de données** + +Si la latitude et la longitude sont stockées dans des colonnes séparées, concaténez-les en une chaîne séparée par une virgule via SQL. +Les paramètres d'une source de données comptent un élément par ligne : écrivez donc le SQL sur une seule ligne, à la suite de ``sql=`` +(si vous le répartissez sur plusieurs lignes, seul le ``SELECT`` de la première ligne est traité comme SQL, ce qui provoque une erreur de syntaxe). + +:: + + sql=SELECT id, name, address, CONCAT(latitude, ',', longitude) AS location FROM stores + +Dans le script de configuration de la source de données, mappez la valeur récupérée vers le champ ``location``. +Pour la source de données de base de données, les noms de colonnes du SQL (y compris les alias définis avec ``AS``) deviennent directement les noms de variables du script. +Aucun préfixe tel que ``data.`` n'est ajouté. + +:: + + location=location + +Ajout d'informations de géolocalisation via script +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Vous pouvez également ajouter dynamiquement des informations de géolocalisation à un document en utilisant la fonctionnalité de script dans la configuration d'exploration (JavaScript par défaut ; Groovy peut également être sélectionné). +Assignez directement la valeur au nom du champ. + +:: + + // Définir la latitude et la longitude dans le champ location + location="35.681236,139.767125" + +Pour plus de détails sur les scripts, consultez :doc:`scripting-overview`. + +Configuration lors de la recherche +----------------------------------- + +Pour effectuer une recherche par géolocalisation, spécifiez le point central et le rayon de recherche dans les paramètres de la requête. + +Paramètres de requête +~~~~~~~~~~~~~~~~~~~~~ + +Le nom des paramètres de la recherche par géolocalisation suit le format ``geo..point`` et ``geo..distance``. +```` correspond au nom du champ configuré dans ``query.geo.fields`` +(par défaut : ``location``). + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Nom du paramètre + - Description + * - ``geo.location.point`` + - Latitude et longitude du point central de recherche (séparées par une virgule. Exemple : ``35.681236,139.767125``) + * - ``geo.location.distance`` + - Rayon de recherche à partir du point central (avec unité. Exemple : ``10km``) + +.. note:: + ``point`` et ``distance`` doivent être spécifiés ensemble. Un ``point`` sans ``distance`` est ignoré. + De plus, la valeur de ``point`` doit être composée de deux nombres (latitude,longitude) ; un format incorrect + entraîne une erreur. + +.. note:: + La recherche par géolocalisation fonctionne comme un filtre appliqué au terme de recherche ``q``. Si ``q`` est vide, la recherche elle-même n'est pas exécutée + et le résultat est de 0 document. Indiquez donc un terme de recherche dans les requêtes de recherche par géolocalisation. + +.. note:: + Si plusieurs ``point`` sont spécifiés pour le même champ, ils sont traités comme une condition OU (dans l'une des zones). + Si des ``point`` sont spécifiés pour plusieurs champs distincts, ils sont traités comme une condition ET (dans toutes les zones). + +Unités de distance +~~~~~~~~~~~~~~~~~~ + +Les unités suivantes peuvent être utilisées pour la distance : + +- ``km`` : Kilomètres +- ``m`` : Mètres +- ``mi`` : Miles +- ``yd`` : Yards + +.. note:: + La valeur de distance est transmise telle quelle à OpenSearch. Vous pouvez donc également utiliser + toute unité prise en charge par OpenSearch (``cm``, ``mm``, ``ft``, ``in``, ``nmi``, etc.). + +Ordre des résultats de recherche +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +La recherche par géolocalisation fonctionne comme un **filtre** qui restreint les résultats aux documents situés dans la zone spécifiée. +Elle n'affecte pas le score de pertinence et ne trie pas les résultats par distance croissante par rapport au point central. +Les résultats sont retournés dans l'ordre de pertinence habituel (ou dans l'ordre spécifié par le paramètre ``sort``). + +.. note:: + |Fess| ne prend pas en charge le tri par distance (ordre croissant de proximité). + Si vous souhaitez afficher les résultats par ordre de distance, récupérez les coordonnées de latitude/longitude + incluses dans la réponse et effectuez le tri côté client. + +Exemples de recherche +===================== + +Recherche de base +----------------- + +Pour rechercher des documents dans un rayon de 10 km autour de la gare de Tokyo (35.681236, 139.767125) : + +:: + + http://localhost:8080/search?q=mot-clé&geo.location.point=35.681236,139.767125&geo.location.distance=10km + +Recherche autour de la position actuelle +----------------------------------------- + +Pour rechercher dans un rayon de 1 km autour de la position actuelle de l'utilisateur : + +:: + + http://localhost:8080/search?q=restaurant&geo.location.point=35.681236,139.767125&geo.location.distance=1km + +Utilisation avec l'API +----------------------- + +La recherche par géolocalisation peut également être utilisée avec l'API de recherche JSON v2 (``/api/v2/search``). +Spécifiez ``geo.location.point`` et ``geo.location.distance`` en tant que paramètres de requête. + +:: + + curl "http://localhost:8080/api/v2/search?q=hôtel&geo.location.point=35.681236,139.767125&geo.location.distance=5km" + +Les résultats de recherche sont retournés dans le tableau ``response.data`` de l'enveloppe commune. Pour plus de détails sur l'API, consultez :doc:`../api/api-search` +et :doc:`../api/api-overview`. + +.. note:: + Le champ ``location`` n'est pas inclus dans la réponse de l'API par défaut. Pour inclure les coordonnées de latitude/longitude + dans les résultats de recherche, ajoutez les deux paramètres suivants dans ``fess_config.properties`` et redémarrez |Fess|. + ``query.additional.response.fields`` ajoute le champ à récupérer depuis le moteur de recherche, + et ``query.additional.api.response.fields`` autorise le champ à figurer dans la réponse de l'API. + Avec seulement l'un des deux, ``location`` n'est pas inclus dans la réponse. + + :: + + query.additional.response.fields=location + query.additional.api.response.fields=location + +Personnalisation du nom de champ +================================= + +Modification du nom de champ par défaut +----------------------------------------- + +Pour modifier le nom de champ utilisé pour la recherche par géolocalisation, +modifiez le paramètre suivant dans ``fess_config.properties`` : + +:: + + query.geo.fields=location + +Pour spécifier plusieurs noms de champs, séparez-les par des virgules. + +:: + + query.geo.fields=location,geo_point,coordinates + +.. note:: + - Le nom des paramètres de requête est lié au nom du champ configuré. Par exemple, + si vous définissez ``query.geo.fields=coordinates``, spécifiez ``geo.coordinates.point`` et + ``geo.coordinates.distance``. + - Chaque champ spécifié ici doit être défini comme type ``geo_point`` dans le mappage de l'index. + +Exemples d'implémentation +========================== + +Implémentation dans une application web +----------------------------------------- + +Exemple d'obtention de la position actuelle avec JavaScript pour effectuer une recherche : + +.. code-block:: javascript + + // Obtenir la position actuelle avec l'API Geolocation du navigateur + navigator.geolocation.getCurrentPosition(function(position) { + const latitude = position.coords.latitude; + const longitude = position.coords.longitude; + const distance = "5km"; + + // Construction de l'URL de recherche (le terme de recherche q ne peut pas être omis) + const searchUrl = `/search?q=${encodeURIComponent('magasin')}&geo.location.point=${latitude},${longitude}&geo.location.distance=${distance}`; + + // Exécution de la recherche + window.location.href = searchUrl; + }); + +Intégration avec Google Maps +------------------------------ + +Exemple d'affichage des résultats de recherche sous forme de marqueurs sur Google Maps : + +.. note:: + Cet exemple accède au champ ``location`` dans les résultats de recherche. Assurez-vous de configurer + ``query.additional.response.fields=location`` et ``query.additional.api.response.fields=location`` au préalable pour inclure les coordonnées de latitude/longitude + dans la réponse. + +.. code-block:: javascript + + // Initialisation de la carte + const map = new google.maps.Map(document.getElementById('map'), { + center: {lat: 35.681236, lng: 139.767125}, + zoom: 13 + }); + + // Exécution de la recherche par géolocalisation avec l'API de recherche v2 de Fess + fetch('/api/v2/search?q=magasin&geo.location.point=35.681236,139.767125&geo.location.distance=5km') + .then(response => response.json()) + .then(json => { + // Affichage des résultats de recherche (tableau response.data) sous forme de marqueurs + json.response.data.forEach(doc => { + if (doc.location) { + const [lat, lng] = doc.location.split(',').map(Number); + new google.maps.Marker({ + position: {lat: lat, lng: lng}, + map: map, + title: doc.title + }); + } + }); + }); + +Optimisation des performances +============================== + +Vérification de la configuration de l'index +-------------------------------------------- + +Le champ de géolocalisation est défini comme type ``geo_point`` dans +``app/WEB-INF/classes/fess_indices/fess/doc.json`` de l'installation. + +:: + + "location": { + "type": "geo_point" + } + +Les champs de type ``geo_point`` sont indexés sous forme d'arbre BKD, ce qui permet d'exécuter +les requêtes geo-distance de manière efficace. + +Optimisation de la zone de recherche et de la réponse +------------------------------------------------------ + +Plus le rayon de recherche est grand, plus le nombre de documents correspondants augmente, +ce qui peut allonger le temps de récupération et d'affichage des résultats. + +- Définissez un rayon de recherche adapté à votre cas d'utilisation. +- Si vous traitez un grand nombre de résultats (par exemple pour un affichage cartographique), + limitez le nombre de résultats récupérés en ajustant la taille de page (paramètre ``num``). + +Dépannage +========== + +La recherche par géolocalisation ne fonctionne pas +---------------------------------------------------- + +1. Vérifiez que les données sont correctement stockées dans le champ ``location``. +2. Vérifiez que le format de latitude et longitude est correct (deux valeurs séparées par une virgule sous la forme ``latitude,longitude`` ; une erreur est générée si le nombre de valeurs est différent de deux). +3. Vérifiez que ``location`` est défini comme type ``geo_point`` dans le mappage de l'index OpenSearch. +4. Vérifiez que ``point`` et ``distance`` sont tous les deux spécifiés (un ``point`` sans ``distance`` est ignoré). + +Aucun résultat de recherche n'est renvoyé +------------------------------------------ + +1. Vérifiez s'il existe des documents dans la plage de distance spécifiée. +2. Vérifiez que les valeurs de latitude et longitude sont dans les plages correctes (latitude : -90 à 90, longitude : -180 à 180). +3. Vérifiez que l'unité de distance est correctement spécifiée. + +Les informations de géolocalisation ne sont pas incluses dans la réponse de l'API +----------------------------------------------------------------------------------- + +Le champ ``location`` n'est pas inclus dans la réponse de l'API par défaut. +Pour inclure les coordonnées de latitude/longitude dans les résultats de recherche, ajoutez +``query.additional.response.fields=location`` et ``query.additional.api.response.fields=location`` +dans ``fess_config.properties``, puis redémarrez |Fess|. + +Les informations de géolocalisation ne sont pas enregistrées correctement +-------------------------------------------------------------------------- + +1. Vérifiez que le champ ``location`` est correctement défini lors de l'exploration. +2. Vérifiez que la latitude et la longitude sont correctement récupérées depuis la source de données. +3. Si vous définissez des informations de géolocalisation via un script, vérifiez que le format est une chaîne ``latitude,longitude``. + +Informations de référence +========================== + +Pour plus de détails sur la recherche par géolocalisation, consultez les ressources suivantes : + +- `OpenSearch Geo Queries `_ +- `OpenSearch Geo Point `_ +- `API de géolocalisation (MDN) `_ diff --git a/fr/15.10/config/search-scroll.rst b/fr/15.10/config/search-scroll.rst new file mode 100644 index 000000000..334a7d08e --- /dev/null +++ b/fr/15.10/config/search-scroll.rst @@ -0,0 +1,458 @@ +================================================ +Récupération en masse des résultats de recherche +================================================ + +Aperçu +====== + +La recherche normale de |Fess| affiche uniquement un nombre limité de résultats de recherche grâce à la fonction de pagination. +Si vous souhaitez récupérer tous les résultats de recherche en une seule fois, utilisez la fonction de recherche par défilement (Scroll Search). + +Cette fonction est utile lorsque vous devez traiter tous les résultats de recherche, +par exemple pour l'export de données en masse, les sauvegardes ou l'analyse de grandes quantités de données. + +Cas d'utilisation +================= + +La recherche par défilement est adaptée aux utilisations suivantes : + +- Export de tous les résultats de recherche +- Récupération de grandes quantités de données pour l'analyse de données +- Récupération de données dans des traitements par lots +- Synchronisation de données vers des systèmes externes +- Collecte de données pour la génération de rapports + +.. warning:: + La recherche par défilement renvoie de grandes quantités de données et consomme donc + plus de ressources serveur que la recherche normale. Activez-la uniquement si nécessaire. + +Méthode de configuration +======================== + +Activation de la recherche par défilement +------------------------------------------ + +Par défaut, la recherche par défilement est désactivée pour des raisons de sécurité et de performances. +Pour l'activer, modifiez le paramètre suivant dans ``app/WEB-INF/classes/fess_config.properties`` +(ou ``/etc/fess/fess_config.properties`` pour les packages RPM/DEB). + +:: + + api.search.scroll=true + +.. note:: + Après avoir modifié les paramètres, vous devez redémarrer |Fess|. + +Durée de vie du contexte de défilement +--------------------------------------- + +La durée de vie du contexte de défilement est fixée en interne à ``1m`` (1 minute) dans |Fess|. +Cette valeur ne peut pas être modifiée via ``fess_config.properties``. + +.. note:: + Le paramètre ``index.scroll.search.timeout`` existe, mais il est utilisé pour les traitements + internes impliquant la mise à jour ou la suppression d'index (update by query / delete by query). + Il n'a aucun effet sur le délai d'expiration de la présente fonctionnalité (défilement de recherche). + +Configuration des champs de réponse +------------------------------------- + +Vous pouvez personnaliser les champs inclus dans la réponse des résultats de recherche. +Par défaut, de nombreux champs sont renvoyés, mais vous pouvez spécifier des champs supplémentaires. + +:: + + query.additional.scroll.response.fields=content + query.additional.api.response.fields=content + +Pour spécifier plusieurs champs, énumérez-les séparés par des virgules. + +.. note:: + Le champ ``content`` n'est pas inclus par défaut dans la réponse. Pour récupérer le texte + intégral, les deux paramètres ci-dessus sont nécessaires. ``query.additional.scroll.response.fields`` + ajoute le champ à ceux lus dans l'index, et ``query.additional.api.response.fields`` l'ajoute aux champs + que l'API est autorisée à renvoyer. Avec un seul des deux, ``content`` n'est pas émis. + +Méthode d'utilisation +===================== + +Utilisation de base +-------------------- + +L'accès à la recherche par défilement s'effectue via l'URL suivante. + +:: + + http://localhost:8080/api/v2/documents/all?q=mot-clé + +Les résultats de recherche sont renvoyés au format NDJSON (Newline Delimited JSON). +Chaque ligne contient un document au format JSON. + +**Exemple :** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=Fess" + +Paramètres de requête +---------------------- + +Les paramètres suivants peuvent être utilisés pour la recherche par défilement. + +.. note:: + La recherche par défilement ne prend en charge que la méthode GET. Pour les méthodes qui modifient + l'état, comme ``POST``, la vérification du jeton CSRF a lieu en premier : une requête sans en-tête + ``X-Fess-CSRF-Token`` valide reçoit ``403 Forbidden`` (``forbidden``) (voir :doc:`../api/api-overview`). + Avec un jeton valide, ``405 Method Not Allowed`` (``method_not_allowed``) est renvoyé. + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Nom du paramètre + - Description + * - ``q`` + - Requête de recherche (obligatoire) + * - ``num`` + - Nombre d'éléments à récupérer par défilement (par défaut : 10, maximum : 100) + * - ``fields.label`` + - Filtrage par étiquette + +.. note:: + La valeur maximale de ``num`` est contrôlée par ``paging.search.page.max.size`` (par défaut : 100). + Si une valeur supérieure au maximum est spécifiée, elle est automatiquement ramenée au maximum. + La valeur par défaut est celle de ``paging.search.page.size`` (par défaut : 10). + Si une valeur inférieure ou égale à 0 est spécifiée pour ``num``, une erreur (``INVALID_REQUEST``) est renvoyée. + +Spécification de la requête de recherche +----------------------------------------- + +Vous pouvez spécifier une requête de recherche comme dans une recherche normale. + +**Exemple : Recherche par mot-clé** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=moteur de recherche" + +**Exemple : Recherche par champ spécifique** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=title:Fess" + +**Exemple : Récupération de tous les éléments (sans condition de recherche)** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=*:*" + +Spécification du nombre d'éléments à récupérer +------------------------------------------------ + +Vous pouvez modifier le nombre d'éléments récupérés par défilement. + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=Fess&num=100" + +.. note:: + Si le paramètre ``num`` est trop élevé, l'utilisation de la mémoire augmente. + La valeur maximale par défaut est 100. Si vous avez besoin d'une valeur plus élevée, + modifiez le paramètre ``paging.search.page.max.size``. + +Filtrage par étiquette +----------------------- + +Vous pouvez récupérer uniquement les documents appartenant à une étiquette spécifique. + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=*:*&fields.label=public" + +À propos du contrôle d'accès +------------------------------ + +.. note:: + La recherche par défilement applique également le contrôle d'accès basé sur les rôles (RBAC), + comme la recherche normale. Seuls les documents accessibles selon les informations de rôle de la + requête sont renvoyés ; les documents pour lesquels l'utilisateur ne dispose pas de droits de + consultation ne sont pas inclus dans les résultats. + +.. warning:: + Par défaut, l'endpoint de la recherche par défilement ne requiert pas d'authentification + (tout le monde peut y accéder). Cependant, les documents renvoyés sont filtrés par le + contrôle d'accès basé sur les rôles décrit ci-dessus. Si vous souhaitez restreindre l'accès + à l'endpoint lui-même, configurez une restriction par adresse IP ou une authentification + via un proxy inverse. + +Format de réponse +================= + +Format NDJSON +-------------- + +La réponse de la recherche par défilement est renvoyée au format NDJSON (Newline Delimited JSON). +Le Content-Type est ``application/x-ndjson; charset=UTF-8``. +Chaque ligne représente un document encapsulé dans le format ``{"data": {...}}``. + +**Exemple :** + +:: + + {"data":{"url":"http://example.com/page1","title":"Page 1","digest":"..."}} + {"data":{"url":"http://example.com/page2","title":"Page 2","digest":"..."}} + {"data":{"url":"http://example.com/page3","title":"Page 3","digest":"..."}} + +.. note:: + Chaque document est stocké sous la clé ``data``. Côté client, après avoir analysé chaque + ligne, référencez la valeur de la clé ``data``. + +Comportement en cas d'erreur +------------------------------ + +Si une erreur survient côté serveur après le début de l'envoi du flux, une ligne terminatrice +d'erreur est émise sur la dernière ligne de la réponse, comme suit : + +:: + + {"error":{"code":"internal_error","message":"stream error"}} + +.. note:: + Côté client, vous pouvez déterminer si « le flux s'est terminé normalement » ou si + « une erreur est survenue côté serveur en cours de traitement » en vérifiant si la + dernière ligne contient la clé ``error``. Notez que si l'écriture de la ligne + terminatrice d'erreur elle-même échoue, cette ligne ne sera pas émise et le flux + se terminera en cours de route ; traitez donc également les déconnexions inattendues + comme des erreurs. + +Champs de réponse +------------------ + +Champs inclus par défaut : + +- ``score`` : Score de recherche +- ``_id`` : Identifiant du document (identifiant de document OpenSearch) +- ``doc_id`` : Identifiant du document (interne à |Fess|) +- ``boost`` : Valeur de boost +- ``content_length`` : Taille du contenu +- ``host`` : Nom d'hôte +- ``site`` : Site +- ``last_modified`` : Date de dernière modification +- ``timestamp`` : Horodatage +- ``mimetype`` : Type MIME +- ``filetype`` : Type de fichier +- ``filename`` : Nom du fichier +- ``created`` : Date de création +- ``title`` : Titre +- ``digest`` : Extrait du corps du document +- ``url`` : URL du document +- ``thumbnail`` : Miniature +- ``click_count`` : Nombre de clics +- ``favorite_count`` : Nombre de favoris +- ``has_cache`` : Présence du cache +- ``content_title`` : Titre affiché +- ``content_description`` : Extrait affiché du corps du document +- ``url_link`` : URL du lien affiché +- ``site_path`` : Chemin du site + +.. note:: + Les champs effectivement émis sont limités aux champs autorisés dans la réponse de l'API. + Les champs sans valeur ne sont pas émis. + +.. note:: + Le champ ``content`` (texte intégral) n'est pas inclus par défaut. + Il est émis lorsqu'il est ajouté à la fois à ``query.additional.scroll.response.fields`` et à + ``query.additional.api.response.fields`` (voir Configuration des champs de réponse). + +Exemples de traitement de données +================================== + +Exemple de traitement en Python +--------------------------------- + +.. code-block:: python + + import requests + import json + + # Exécution de la recherche par défilement + url = "http://localhost:8080/api/v2/documents/all" + params = { + "q": "Fess", + "num": 100 + } + + response = requests.get(url, params=params, stream=True) + + # Traitement de la réponse NDJSON ligne par ligne + for line in response.iter_lines(): + if line: + record = json.loads(line) + if "error" in record: + # Une erreur est survenue en cours de flux + print("stream error:", record["error"]) + break + doc = record["data"] + print(f"Title: {doc.get('title')}") + print(f"URL: {doc.get('url')}") + print("---") + +Enregistrement dans un fichier +-------------------------------- + +Exemple d'enregistrement des résultats de recherche dans un fichier : + +.. code-block:: bash + + curl "http://localhost:8080/api/v2/documents/all?q=*:*" > all_documents.ndjson + +Conversion en CSV +------------------ + +Exemple de conversion en CSV à l'aide de la commande jq : + +.. code-block:: bash + + curl "http://localhost:8080/api/v2/documents/all?q=Fess" | \ + jq -r '.data | [.url, .title, .score] | @csv' > results.csv + +Analyse de données +------------------- + +Exemple d'analyse des données récupérées : + +.. code-block:: python + + import json + import pandas as pd + + # Lecture du fichier NDJSON (extraction de la clé data de chaque ligne) + documents = [] + with open('all_documents.ndjson', 'r') as f: + for line in f: + record = json.loads(line) + if "data" in record: + documents.append(record["data"]) + + # Conversion en DataFrame + df = pd.DataFrame(documents) + + # Statistiques de base + print(f"Total documents: {len(df)}") + print(f"Average score: {df['score'].mean()}") + + # Analyse des domaines des URL + df['domain'] = df['url'].apply(lambda x: x.split('/')[2]) + print(df['domain'].value_counts()) + +Performances et meilleures pratiques +===================================== + +Méthodes d'utilisation efficaces +---------------------------------- + +1. **Configuration appropriée du paramètre num** + + - Une valeur trop petite augmente la surcharge de communication + - Une valeur trop grande augmente l'utilisation de la mémoire + - Maximum par défaut : 100 + +2. **Optimisation des conditions de recherche** + + - Spécifiez des conditions de recherche pour ne récupérer que les documents nécessaires + - N'effectuez la récupération complète que si vraiment nécessaire + +3. **Utilisation en heures creuses** + + - Exécutez la récupération de grandes quantités de données pendant les périodes de faible charge système + +4. **Utilisation dans des traitements par lots** + + - Exécutez la synchronisation régulière de données en tant que tâches par lots + +Optimisation de l'utilisation de la mémoire +--------------------------------------------- + +Lors du traitement de grandes quantités de données, utilisez le traitement en streaming pour réduire l'utilisation de la mémoire. + +.. code-block:: python + + import requests + import json + + url = "http://localhost:8080/api/v2/documents/all" + params = {"q": "*:*", "num": 100} + + # Traitement en streaming + with requests.get(url, params=params, stream=True) as response: + for line in response.iter_lines(decode_unicode=True): + if line: + record = json.loads(line) + if "error" in record: + break + # Traitement du document + process_document(record["data"]) + +Considérations de sécurité +============================ + +Restrictions d'accès +---------------------- + +Étant donné que la recherche par défilement renvoie de grandes quantités de données, veuillez configurer des restrictions d'accès appropriées. +L'endpoint lui-même ne requiert pas d'authentification par défaut ; envisagez les mesures suivantes si nécessaire. + +1. **Restriction par adresse IP** + + Autoriser l'accès uniquement à partir d'adresses IP spécifiques + +2. **Authentification API** + + Utiliser des jetons API ou l'authentification Basic via un proxy inverse + +3. **Contrôle d'accès basé sur les rôles** + + Les documents renvoyés sont filtrés par le contrôle d'accès basé sur les rôles de |Fess| + +Limitation de débit +--------------------- + +Pour éviter les accès excessifs, il est recommandé de configurer une limitation de débit sur le proxy inverse. + +Dépannage +========== + +La recherche par défilement n'est pas disponible +------------------------------------------------- + +1. Vérifiez que ``api.search.scroll`` est défini sur ``true``. +2. Vérifiez que vous avez redémarré |Fess|. +3. Consultez les journaux d'erreurs. + +Une erreur de délai d'expiration se produit +--------------------------------------------- + +1. Réduisez le paramètre ``num`` pour répartir le traitement. +2. Affinez les conditions de recherche pour réduire la quantité de données récupérées. + +Erreur de mémoire insuffisante +-------------------------------- + +1. Réduisez le paramètre ``num``. +2. Augmentez la taille de la mémoire heap de |Fess|. +3. Vérifiez la taille de la mémoire heap d'OpenSearch. + +La réponse est vide +-------------------- + +1. Vérifiez que la requête de recherche est correcte. +2. Vérifiez que l'étiquette ou les conditions de filtre spécifiées sont correctes. +3. En raison du contrôle d'accès basé sur les rôles, les documents pour lesquels l'utilisateur ne dispose pas de droits de consultation ne sont pas inclus dans les résultats. Vérifiez les paramètres de rôle de la requête. + +Informations de référence +========================== + +- :doc:`search-basic` - Détails de la fonction de recherche +- :doc:`search-advanced` - Paramètres liés à la recherche +- `OpenSearch Scroll API `_ diff --git a/fr/15.10/config/search-semantic.rst b/fr/15.10/config/search-semantic.rst new file mode 100644 index 000000000..a05f3de3c --- /dev/null +++ b/fr/15.10/config/search-semantic.rst @@ -0,0 +1,994 @@ +===================================================================== +Recherche sémantique (chunking de contenu + recherche vectorielle) +===================================================================== + +Aperçu +====== + +Dans |Fess| 15.10, la **fonctionnalité de chunking de contenu** — qui découpe le corps des +documents en chunks et génère puis stocke un vecteur d'embedding pour chaque chunk — a été +intégrée au cœur du produit. Les vecteurs générés sont utilisés à deux fins : + +- **Recherche sémantique** : une recherche hybride qui combine la recherche par mots-clés (BM25) + et la recherche vectorielle via le Rank Fusion. Les documents sémantiquement proches de la + requête peuvent correspondre même sans chevauchement exact de mots-clés. +- **Mode de recherche IA (RAG)** : lors de la génération d'une réponse, seuls les chunks + sémantiquement les plus proches de la question sont sélectionnés comme contexte du LLM, ce qui + améliore la qualité de la réponse et l'efficacité en tokens. + +Tout ceci est désactivé par défaut. Tant que vous ne l'activez pas, |Fess| continue de fonctionner +exactement comme avant, en utilisant uniquement la recherche par mots-clés. Si vous mettez à +niveau |Fess| depuis la version 15.7 ou antérieure, ou si vous utilisiez le plugin +``fess-webapp-semantic-search``, consultez :ref:`semantic-search-migration`. + +Flux de traitement +-------------------- + +1. Le crawler indexe les documents comme d'habitude (aucun chunk n'existe à ce stade). +2. La tâche du planificateur **Content Chunk Vector Indexer** recherche les documents non + traités, découpe leur contenu (le champ ``content``) en chunks, génère les vecteurs + d'embedding et les stocke dans le champ ``content_chunk_vector``. À cette occasion, le champ + ``content`` lui-même est réécrit sous la forme du tableau des chunks (``content_length`` + conserve sa valeur d'origine). +3. Le résultat de ce traitement est enregistré dans le champ ``content_chunk_status`` (décrit + ci-dessous). +4. Lorsque ``content_chunker.search.enabled=true``, le moteur de recherche sémantique participe + au Rank Fusion au moment de la recherche. + +Prérequis +========= + +- **OpenSearch avec le plugin k-NN** : dans |Fess| 15.10, le mapping de l'index de recherche + (``fess.search``) inclut toujours le champ ``content_chunk_vector`` (de type ``nested``, dont + la sous-propriété ``vector`` est le ``knn_vector`` utilisé pour l'ANN), que la fonctionnalité + de chunking de contenu soit activée ou non, et les réglages de l'index incluent toujours + ``index.knn: true``. Par conséquent, si OpenSearch n'a pas le plugin k-NN installé, la création + d'un nouvel index échoue purement et simplement et |Fess| ne peut pas démarrer. + + .. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Configuration + - Prise en charge du plugin k-NN + * - Docker (``ghcr.io/codelibs/fess-opensearch``), les paquets RPM/DEB (qui se connectent + toujours à un OpenSearch externe installé séparément), ou un autre OpenSearch externe + (distribution standard) + - Entièrement pris en charge, y compris ``faiss``. + * - La **distribution minimale** d'un OpenSearch externe + - **Non prise en charge.** Elle n'inclut pas le plugin k-NN, donc la création d'un + nouvel index échoue. + + ``nmslib`` n'est jamais une valeur acceptée pour ``content_chunker.search.knn.engine``, quelle + que soit la configuration ci-dessus : ``content_chunk_vector`` est un champ ``nested``, et le + plugin k-NN ne prend en charge les champs nested qu'avec les moteurs ``lucene``/``faiss`` + (``nmslib`` est en outre déprécié et restreint depuis OpenSearch 3.0). Le définir entraîne un + retour à ``lucene`` avec un avertissement ; consultez la Référence de configuration ci-dessous + pour les autres valeurs acceptées des réglages ANN. + +- **Version d'OpenSearch pour un cluster externe** : les réglages d'index ``fess.search`` + fournis envoient toujours ``index.knn`` et ``knn.derived_source.enabled`` (dans + ``fess_indices/fess.json`` et dans ``fess_indices/_vanilla/fess.json``, utilisé par ``vanilla``, ``aws`` et l'ancien ``cloud``). Ce dernier est un réglage relativement + récent du plugin k-NN : un OpenSearch plus ancien qui ne le reconnaît pas fait échouer la + création de l'index, que le plugin k-NN lui-même soit installé ou non. Pour connaître les + versions d'OpenSearch prises en charge par |Fess| 15.10, consultez + :doc:`../install/prerequisites`. + +- **Fournisseur d'embedding** : utilisez l'un des suivants. + +.. list-table:: + :header-rows: 1 + :widths: 20 25 55 + + * - Valeur de configuration + - Fourni par + - Description + * - ``opensearch`` + - Cœur de |Fess| (intégré) + - Utilise un modèle d'embedding déployé sur OpenSearch ML Commons. Aucun plugin + supplémentaire requis. Réglage par défaut. + * - ``ollama`` + - Plugin ``fess-llm-ollama`` + - Utilise un modèle d'embedding Ollama (par ex. ``nomic-embed-text``). + * - ``openai`` + - Plugin ``fess-llm-openai`` + - Utilise l'API d'embeddings d'OpenAI. + * - ``gemini`` + - Plugin ``fess-llm-gemini`` + - Utilise l'API d'embeddings de Google Gemini. + * - ``bedrock`` + - Plugin ``fess-llm-bedrock`` + - Utilise Amazon Titan Text Embeddings V2 ou Cohere Embed via Amazon Bedrock. + * - ``none`` + - Cœur de |Fess| (intégré) + - Découpe les documents en chunks uniquement ; aucun vecteur n'est généré (mode chunking + seul). + +Référence de configuration +============================ + +Tous les réglages ``content_chunker.*`` résident dans un canal unique : les **propriétés +système** (``system.properties``). Définissez-les dans +``app/WEB-INF/conf/system.properties`` (``/etc/fess/system.properties`` pour les paquets RPM/DEB, +``/opt/fess/system.properties`` sous Docker), ou fournissez une valeur initiale via l'option de +démarrage ``-Dfess.system.``. Les valeurs sont rechargées à l'exécution, de sorte que la +plupart des réglages prennent effet immédiatement après leur modification. La seule exception est +l'activation de ``content_chunker.search.enabled`` (``false`` → ``true``) : le moteur de +recherche sémantique n'étant enregistré qu'au démarrage, **ce changement nécessite un redémarrage +pour prendre effet**. + +.. note:: + + Les clés ``content_chunker.*`` ne sont lues que depuis le canal ``system.properties``. Les + écrire dans ``fess_config.properties`` ou via ``-Dfess.config.`` reste sans effet : + définissez-les impérativement dans ``system.properties``. Notez par ailleurs que l'écran + d'administration **Informations système > Informations de configuration** affiche les valeurs + courantes **en lecture seule** ; il ne permet pas d'y définir les réglages + ``content_chunker.*``. + +Réglages dans system.properties +---------------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 40 15 45 + + * - Propriété + - Défaut + - Description + * - ``content_chunker.enabled`` + - ``false`` + - Interrupteur principal de toute la fonctionnalité de chunking de contenu + * - ``content_chunker.chunker.name`` + - ``length`` + - Méthode de chunking + * - ``content_chunker.length.chunk_size`` + - ``800`` + - Nombre de caractères visé par chunk. Lorsque le découpage aux frontières est activé + (valeur par défaut), il s'agit d'une cible et non d'une limite stricte : un chunk peut être + plus court de ``boundary.lookback_percent`` et plus long de ``max(lookahead, 32)`` + caractères, soit de 640 à 840 caractères avec les valeurs par défaut. Conservez cette marge + par rapport à la limite de tokens du modèle d'embedding + * - ``content_chunker.length.overlap`` + - ``0`` + - Nombre de caractères de chevauchement entre les chunks. Le point de reprise est lui + aussi aligné sur une frontière, et cet alignement ne peut que l'avancer : le chevauchement + effectif est donc compris entre cette valeur et le double de cette valeur + * - ``content_chunker.length.boundary.enabled`` + - ``true`` + - Déplace chaque coupure vers une frontière de texte pertinente au lieu de couper + exactement à ``chunk_size`` caractères. Les candidats sont hiérarchisés et le plus proche + du niveau le plus élevé présent l'emporte : saut de ligne ou fin de phrase, sinon + séparateur de proposition ou espace, sinon changement de système d'écriture. ``false`` + rétablit le comportement précédent à longueur fixe + * - ``content_chunker.length.boundary.lookback_percent`` + - ``20`` + - Distance de recherche d'une frontière avant la coupure idéale, en pourcentage de + ``chunk_size`` (0-50) + * - ``content_chunker.length.boundary.lookahead_percent`` + - ``5`` + - Distance de recherche d'une fin de phrase ou d'un saut de ligne après la coupure + idéale, en pourcentage de ``chunk_size`` (0-25). Utilisé uniquement si rien n'a été trouvé + avant la coupure + * - ``content_chunker.max_chunks_per_document`` + - ``1000`` + - Nombre maximal de chunks par document. Les documents qui dépassent cette limite sont + marqués ``skipped`` et ne reçoivent aucun embedding. Comme le découpage aux + frontières raccourcit les chunks, un document en produit environ 3 % à 25 % de plus qu'avec + une longueur fixe ; un corpus de très gros documents peut donc nécessiter une valeur plus + élevée ici + * - ``content_chunker.embedding.name`` + - ``opensearch`` + - Fournisseur d'embedding (``opensearch`` / ``ollama`` / ``openai`` / ``gemini`` / ``bedrock`` / ``none``) + * - ``content_chunker.embedding.dimension`` + - ``768`` + - Dimension du vecteur d'embedding. Cette valeur est utilisée lors de la création du + mapping, elle **doit** donc correspondre à la dimension du modèle d'embedding utilisé. + Elle est lue par deux chemins distincts, au comportement différent. Lors de la création du + mapping de l'index, une valeur non définie entraîne l'utilisation de ``768`` **sans aucun + avertissement**, et une valeur vide, non numérique, nulle ou négative, ou supérieure à + ``16000`` (le maximum propre au plugin k-NN) entraîne l'utilisation de ``768`` avec un + avertissement. À l'exécution du processus d'embedding, en revanche, il n'y + a aucun repli : une valeur non définie, non numérique, nulle ou négative provoque une + erreur. Une valeur supérieure à ``16000`` n'est pas rejetée à l'exécution, de sorte que + seul le mapping est créé avec ``768``, ce qui aboutit à une incohérence de dimension. La + dimension du mapping ne peut plus être modifiée une fois l'index créé ; pour vous remettre + d'un index créé alors que la valeur n'était pas définie, voir *Si l'index a été créé sans + dimension* dans *Remarques* + * - ``content_chunker.job.concurrency`` + - ``2`` + - Nombre de workers parallèles pour la tâche d'indexation + * - ``content_chunker.job.bulk_size`` + - ``20`` + - Nombre de documents récupérés et écrits par lot + * - ``content_chunker.job.max_documents_per_run`` + - ``-1``\ (illimité) + - Nombre maximal de documents traités par exécution de la tâche. Toute valeur ``0`` ou + inférieure est traitée comme illimitée + * - ``content_chunker.job.retry_failed`` + - ``false`` + - Lorsque défini sur ``true``, les documents dont l'exécution précédente s'est terminée + avec ``content_chunk_status=fail`` sont également inclus dans la cible de traitement de + l'exécution suivante. Il n'y a ni nouvelle tentative automatique ni suivi du nombre de + tentatives ; le flux de travail prévu consiste à corriger la cause sous-jacente, puis à + activer temporairement ce réglage pour réessayer + * - ``content_chunker.chat.top_k`` + - ``3`` + - Nombre de chunks sélectionnés lorsque le mode de recherche IA génère une réponse + * - ``content_chunker.search.enabled`` + - ``false`` + - Intégration au Rank Fusion pour la recherche sémantique (**l'activation nécessite un + redémarrage**) + * - ``content_chunker.search.min_score`` + - (non défini) + - Similarité cosinus minimale (0-1) requise pour qu'un résultat soit inclus. Aucune coupure + si non défini. En mode ``ann``, lorsque ``search.knn.space_type`` vaut autre chose que + ``cosinesimil``, aucun seuil fondé sur le cosinus ne peut être défini : la coupure est + ignorée avec un avertissement + * - ``content_chunker.search.knn.method`` + - ``hnsw`` + - Méthode d'index ANN. ``hnsw`` est actuellement la seule valeur acceptée ; toute autre + valeur entraîne un retour à ``hnsw`` avec un avertissement (reflétée dans le mapping ; la + modifier nécessite de recréer l'index) + * - ``content_chunker.search.knn.engine`` + - ``lucene`` + - Moteur ANN. Seuls ``lucene`` ou ``faiss`` sont acceptés (voir Prérequis ci-dessus) ; toute + autre valeur entraîne un retour à ``lucene`` avec un avertissement (reflété dans le + mapping ; le modifier nécessite de recréer l'index) + * - ``content_chunker.search.knn.space_type`` + - ``cosinesimil`` + - Espace de distance. Seuls ``cosinesimil``, ``innerproduct`` ou ``l2`` sont acceptés ; toute + autre valeur entraîne un retour à ``cosinesimil`` avec un avertissement (reflété dans le + mapping ; le modifier nécessite de recréer l'index) + * - ``content_chunker.search.knn.k`` + - ``100`` + - Nombre de voisins récupérés par shard par la requête ANN. Lorsque |Fess| effectue la + fusion, la valeur effective ne descend jamais sous ``rank.fusion.window_size`` divisé par + le nombre de moteurs (200 / 2 = 100 par défaut) ; une valeur plus petite n'a donc aucun + effet. Lorsque la fusion est effectuée côté moteur de recherche, cette valeur est + utilisée telle quelle + * - ``content_chunker.search.knn.param.ef_search`` + - (non défini) + - Le paramètre ``ef_search`` pour les requêtes ANN + +.. note:: + + Avec ``content_chunker.length.boundary.enabled=true`` (valeur par défaut), + ``content_chunker.length.chunk_size`` devient un objectif plutôt qu'un plafond strict : chaque + coupure se déplace vers le candidat le plus proche du niveau le plus élevé présent dans la + fenêtre de recherche. Un saut de ligne ou une fin de phrase l'emporte sur n'importe quel + séparateur de proposition ou espace, aussi loin en arrière soit-il, et ceux-ci l'emportent sur + un changement de système d'écriture. Seul le point de coupure est déplacé ; aucun caractère + n'est perdu, si bien que la concaténation des chunks d'un document reproduit toujours son + contenu exact. La recherche vers l'avant peut dépasser ``chunk_size`` d'au plus + ``content_chunker.length.boundary.lookahead_percent``. Un second dépassement, indépendant, + pouvant aller jusqu'à 32 caractères peut se produire lorsqu'une coupure tomberait autrement au + milieu d'un cluster de graphèmes (une marque combinante, un sélecteur de variante ou une + séquence d'emojis liée par un jointeur de largeur nulle ; ZWJ) — celui-ci ignore + ``lookahead_percent`` et peut survenir même lorsqu'il vaut ``0``. Les deux types de + dépassement ne se produisent jamais sur la même coupure : avec les valeurs par défaut, un + chunk fait donc de 640 à 840 caractères. Les chunks étant en moyenne plus courts, un document + produit environ 3 % à 25 % de chunks de plus qu'un découpage à longueur fixe (voir + ``content_chunker.max_chunks_per_document``). Régler + ``content_chunker.length.boundary.enabled`` sur ``false``, ou les deux pourcentages sur ``0``, + reproduit exactement le comportement précédent à longueur fixe. La modification de ces + paramètres n'affecte que les documents découpés ensuite : un document déjà stocké sous forme + de tableau de chunks conserve ses frontières jusqu'à ce qu'il soit à nouveau crawlé. + +.. note:: + + ``content_chunker.length.chunk_size`` s'exprime en caractères, mais un modèle d'embedding ne + peut prendre en compte qu'un texte allant jusqu'à sa limite de tokens. |Fess| ne tronque pas le + texte soumis à l'embedding ; la partie au-delà de cette limite peut donc ne pas être reflétée + dans le vecteur. Choisissez ``chunk_size`` d'après la limite d'entrée du modèle utilisé. Par + exemple, mesurée avec ``paraphrase-multilingual-MiniLM-L12-v2`` (128 tokens au maximum), la + partie reflétée dans le vecteur était d'environ 440 caractères en anglais et d'environ 210 + caractères en japonais (cela varie selon le texte). Avec ce modèle, la fin d'un chunk avec la + valeur par défaut ``chunk_size=800`` n'est pas reflétée dans le vecteur. + +.. note:: + + Les paramètres HNSW ``m`` et ``ef_construction`` sont codés en dur dans ``doc.json`` + (``m=16`` / ``ef_construction=100``) et ne peuvent pas être modifiés via la configuration. + +Réglages de connexion pour le fournisseur opensearch +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Réglages de connexion pour le fournisseur intégré ``opensearch`` (OpenSearch ML Commons). +Ceux-ci sont définis dans le même fichier ``system.properties`` que ci-dessus. + +.. list-table:: + :header-rows: 1 + :widths: 50 20 30 + + * - Propriété + - Défaut + - Description + * - ``content_chunker.embedding.opensearch.model.id`` + - (requis) + - ID du modèle déjà déployé sur ML Commons + * - ``content_chunker.embedding.opensearch.api.url`` + - Adresse du moteur de recherche + - Point de terminaison de l'API ML Commons. Si non défini, utilise par défaut le moteur de + recherche déjà utilisé par |Fess| (par ex. ``http://localhost:9200``) + * - ``content_chunker.embedding.opensearch.username`` / ``password`` + - Identifiants du moteur de recherche + - Si non défini, utilise par défaut les identifiants employés pour la connexion au moteur + de recherche — mais uniquement tant que ``api.url`` n'est pas configuré (c'est-à-dire que + la cible est le même cluster que celui déjà utilisé par |Fess|). Une fois ``api.url`` + défini, ce repli ne s'applique plus. + * - ``content_chunker.embedding.opensearch.timeout`` + - ``60000`` + - Délai d'expiration de la requête (ms) + * - ``content_chunker.embedding.opensearch.connect.timeout`` + - ``5000`` + - Délai d'expiration de connexion (ms) + * - ``content_chunker.embedding.opensearch.retry.max`` + - ``3`` + - Nombre maximal de tentatives, première incluse, pour les erreurs transitoires (429, 5xx, + etc.). Ce n'est pas le nombre de nouvelles tentatives : ``3`` signifie au plus trois + requêtes au total, avec deux attentes entre elles. Une valeur de ``1`` ou moins signifie + aucune nouvelle tentative + * - ``content_chunker.embedding.opensearch.retry.base.delay.ms`` + - ``2000`` + - Délai de base entre les tentatives (ms) + * - ``content_chunker.embedding.opensearch.availability.check.interval`` + - ``60`` + - Intervalle entre les vérifications de disponibilité du fournisseur (secondes) + * - ``content_chunker.embedding.opensearch.document.prefix`` / ``query.prefix`` + - (vide) + - Préfixe ajouté au texte du document/de la requête avant l'embedding + +.. warning:: + + Le contenu de ``system.properties`` est consultable sur l'écran d'administration + **Informations système > Informations de configuration**, dans le panneau **Propriétés de + l'application**. ``content_chunker.embedding.opensearch.password`` y est masqué sous la forme + ``XXXXXXXX``, mais ``username`` s'affiche tel quel. De plus, les valeurs fournies via + ``-Dfess.system.`` apparaissent **sans masquage** dans le panneau **Propriétés du + système** du même écran : renseignez donc les identifiants dans ``system.properties`` plutôt + que dans les options de démarrage. + +Autres fournisseurs (ollama / openai / gemini / bedrock) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Le fournisseur ``ollama`` (plugin ``fess-llm-ollama``) utilise le même style de réglages sous le +préfixe ``content_chunker.embedding.ollama.`` (``api.url`` vaut par défaut +``http://localhost:11434``, ``model`` vaut par défaut ``embeddinggemma``, et +``document.prefix`` / ``query.prefix`` valent par défaut respectivement ``title: none | text:`` / +``task: search result | query:``). Si vous utilisez un modèle de la famille +``nomic-embed-text``, définissez explicitement ``document.prefix`` / ``query.prefix`` sur +``search_document:`` / ``search_query:``. Ces préfixes sont concaténés tels quels au texte à +vectoriser (les espaces environnants ne sont pas supprimés) : les valeurs par défaut ci-dessus +comme ``search_document:`` / ``search_query:`` comportent donc toutes **une espace finale**. +Pensez à cette espace de séparation si vous définissez un préfixe vous-même. +Les fournisseurs ``openai`` et ``gemini`` se +configurent de la même manière, sous les préfixes ``content_chunker.embedding.openai.`` et +``content_chunker.embedding.gemini.`` respectivement. Consultez la documentation de chaque plugin +pour la liste complète des réglages. Le fournisseur ``bedrock`` utilise le préfixe +``content_chunker.embedding.bedrock.``, et ``content_chunker.embedding.dimension`` doit être une +taille que le modèle configuré produit ; voir :doc:`llm-bedrock`. + +Procédure de configuration (exemple avec le fournisseur opensearch) +======================================================================== + +Cette section présente un exemple de configuration utilisant le fournisseur intégré +``opensearch`` (ML Commons). + +1. Déployer le modèle d'embedding +------------------------------------ + +Enregistrez et déployez un modèle d'embedding sur OpenSearch ML Commons. Sur un cluster à nœud +unique, vous devez d'abord appliquer le réglage suivant. + +.. code-block:: bash + + curl -XPUT "http://localhost:9200/_cluster/settings" \ + -H "Content-Type: application/json" -d ' + {"persistent": {"plugins.ml_commons.only_run_on_ml_node": false}}' + +Enregistrez et déployez le modèle (exemple : un modèle d'embedding de phrases à 384 +dimensions) : + +.. code-block:: bash + + # Enregistrer le modèle (récupérer model_id depuis le task_id de la réponse) + curl -XPOST "http://localhost:9200/_plugins/_ml/models/_register" \ + -H "Content-Type: application/json" -d ' + { + "name": "huggingface/sentence-transformers/all-MiniLM-L6-v2", + "version": "1.0.2", + "model_format": "TORCH_SCRIPT" + }' + + # Vérifier l'achèvement de la tâche et récupérer model_id (model_id est renvoyé une fois que state vaut COMPLETED) + curl "http://localhost:9200/_plugins/_ml/tasks/" + + # Déployer + curl -XPOST "http://localhost:9200/_plugins/_ml/models//_deploy" + + # Vérifier le statut : model_state doit être DEPLOYED + curl "http://localhost:9200/_plugins/_ml/models/" + +.. note:: + + Un modèle encore au statut ``REGISTERED`` ne peut pas être utilisé. Assurez-vous de le + déployer et de confirmer que ``model_state`` passe à ``DEPLOYED``. + +2. Configurer |Fess| +----------------------- + +``app/WEB-INF/conf/system.properties`` (``/etc/fess/system.properties`` pour les paquets RPM/DEB, +``/opt/fess/system.properties`` sous Docker ; tout ce qui suit va dans le même fichier) :: + + content_chunker.enabled=true + content_chunker.embedding.name=opensearch + content_chunker.embedding.dimension=384 + content_chunker.embedding.opensearch.model.id= + +Si vous souhaitez également utiliser la recherche sémantique, ajoutez aussi ce qui suit :: + + content_chunker.search.enabled=true + +Redémarrez |Fess| après avoir effectué ces changements. + +3. Recréer l'index (lors de l'activation sur un déploiement existant) +---------------------------------------------------------------------- + +Le mapping du champ ``content_chunk_vector`` — y compris la dimension et les réglages de méthode +ANN que vous avez configurés — est appliqué **au moment où l'index** ``fess.search`` **est +recréé**. + +- **Nouvelles installations** : si vous appliquez les réglages ci-dessus à + ``system.properties`` avant de démarrer |Fess| pour la première fois, le mapping correct est + appliqué automatiquement lors de la première création de l'index ; cette étape est donc + inutile. +- **Si un index existe déjà** (c'est-à-dire si vous avez déjà démarré |Fess| au moins une + fois) : l'index en cours d'exécution n'adopte pas automatiquement le nouveau mapping, et un + mapping existant ne peut pas être modifié après coup. Recréez l'index comme suit : + + Ouvrez **Informations système > Maintenance**, et sous **Réindexation**, exécutez-la avec + l'option **Remplacer les alias** activée. + + Vous pouvez ensuite confirmer que l'index recréé comporte ``index.knn: true`` dans ses réglages + d'index, ainsi qu'un mapping ``content_chunk_vector`` portant la dimension et les réglages de + méthode ANN configurés (``index.knn`` est un réglage d'index alors que les réglages de méthode + ANN font partie du mapping : les deux ne s'appliquent pas au même endroit). + +.. warning:: + + La réindexation s'exécute comme une opération asynchrone en arrière-plan, et l'interface + d'administration n'affiche aucune notification de fin. ``_cat/indices`` montre seulement que le + nouvel index existe (état, nombre de documents, etc.) — pas vers quel index pointent les alias. + Avant de passer à la tâche d'indexation décrite ci-dessous, consultez plutôt ``_cat/aliases`` et + vérifiez que ``fess.search`` et ``fess.update`` pointent tous deux vers le nouvel index ; le + journal de |Fess| ne consigne un avertissement qu'en cas d'échec, donc un journal silencieux + n'est pas une preuve de réussite, seulement l'absence d'un échec connu. L'ancien index (l'index + physique vers lequel pointait auparavant l'alias ``fess.search``, nommé ``fess.``) + n'est pas supprimé automatiquement ; supprimez-le manuellement une fois que vous n'en avez plus + besoin. Tant que les deux index existent, prévoyez une utilisation disque des index environ + deux fois plus importante que d'habitude. + +4. Activer la tâche d'indexation +------------------------------------- + +Le chunking et la génération des embeddings sont effectués par la tâche du planificateur +**Content Chunk Vector Indexer** (ID : ``content-chunk-vector-indexer`` ; désactivée par défaut ; +planifiée à ``0 13 * * *``). + +Activez cette tâche dans **Système > Planificateur**, puis exécutez-la une fois avec **Démarrer +maintenant**. Ensuite, les documents non traités sont pris en charge selon la planification +configurée (par défaut tous les jours à 13:00), indépendamment de la fin du crawl. Cette tâche +n'étant pas chaînée à la tâche de crawl, si vous souhaitez que le traitement suive immédiatement +un crawl, planifiez-la après l'heure de fin prévue de la tâche de crawl. + +.. note:: + + Dans un déploiement multi-nœuds, nous recommandons d'épingler cette tâche pour qu'elle + s'exécute sur exactement un nœud. L'exécuter sur chaque nœud simultanément ne compromet pas + l'exactitude, mais chaque nœud traite et embed les mêmes documents de manière redondante, ce + qui multiplie la charge et le coût chez votre fournisseur d'embedding par le nombre de nœuds. + + L'épinglage nécessite **les deux** réglages suivants — l'un sans l'autre n'épingle pas la + tâche. + + 1. **Sur le nœud où vous souhaitez exécuter la tâche** : définissez + ``scheduler.target.name=`` dans + ``app/WEB-INF/classes/fess_config.properties`` (``/etc/fess/fess_config.properties`` pour + les paquets RPM/DEB, ou via ``-Dfess.config.scheduler.target.name=``), puis + redémarrez ce nœud. (La valeur par défaut est vide ; laissez tous les autres nœuds à la + valeur par défaut.) + 2. Dans l'interface d'administration, sous **Système > Planificateur**, ouvrez la tâche + Content Chunk Vector Indexer et changez son champ **Cible** de ``all`` vers le même + identifiant que celui défini à l'étape 1, puis enregistrez. + + Consultez :doc:`../admin/scheduler-guide` pour savoir ce que signifie le champ **Cible**. + Définir uniquement ``scheduler.target.name`` n'épingle pas la tâche si le champ **Cible** + reste sur ``all`` : **elle ne sera pas épinglée**. ``all`` est traité comme une valeur + spéciale qui correspond toujours ; l'étape 1 seule ou l'étape 2 seule ne suffit donc pas — + vous devez effectuer les deux. + +.. warning:: + + Une fois la tâche épinglée, **Démarrer maintenant** doit lui aussi être déclenché **depuis + l'interface d'administration du nœud sur lequel vous avez défini l'identifiant à l'étape 1**. + Si vous cliquez sur **Démarrer maintenant** depuis un autre nœud, l'écran affiche bien un + message indiquant que la tâche a démarré, mais celle-ci n'est pas exécutée en raison de la + non-correspondance du champ **Cible** (le journal de ce nœud se contente d'une ligne + ``Ignoring job`` au niveau INFO). + +5. Vérifier l'état du traitement +------------------------------------- + +Vous pouvez vérifier le résultat pour chaque document dans son champ ``content_chunk_status``. + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Valeur + - Signification + * - (champ absent) + - Pas encore traité (sera pris en charge lors de la prochaine exécution de la tâche). Les + documents reviennent également à cet état après un nouveau crawl + * - ``done`` + - Chunking et génération de vecteurs terminés + * - ``chunked`` + - Chunking seul terminé (mode chunking seul). Cet état survient lorsque + ``embedding.name=none``, mais aussi lorsque le plugin du fournisseur indiqué dans + ``embedding.name`` n'est pas installé + * - ``skipped`` + - Traitement ignoré. Cela concerne les documents dont le corps est vide (y compris + uniquement des espaces), les documents pour lesquels aucun chunk n'a été produit et ceux + qui dépassent ``max_chunks_per_document``. Si ``content_chunker.chunker.name`` désigne un + chunker inexistant, aucun chunker n'est trouvé et aucun chunk n'est produit : tous les + documents se retrouvent alors dans cet état. C'est un état terminal : relancer la tâche ne + retraite pas le document + * - ``fail`` + - Échec du traitement (vérifiez les journaux). C'est un état terminal : par défaut, relancer + la tâche ne retraite pas le document. Définissez ``content_chunker.job.retry_failed`` à + ``true`` pour le retraiter + +Vous pouvez vérifier la répartition des statuts en interrogeant directement le moteur de +recherche :: + + curl -XPOST "http://localhost:9200/fess.search/_search" \ + -H "Content-Type: application/json" -d ' + {"size": 0, "aggs": {"status": {"terms": {"field": "content_chunk_status", "missing": "pending"}}}}' + +Grâce à l'option ``missing``, les documents dépourvus de ``content_chunk_status`` (autrement dit +non traités) sont regroupés dans un bucket portant la clé ``pending``. + +Jugez de l'état de la tâche de chunking d'après cette répartition de ``content_chunk_status``. Si +``pending`` diminue et ``done`` (``chunked`` en mode chunking seul) augmente à chaque exécution de +la tâche, celle-ci progresse. Si ``fail`` apparaît, consultez les journaux de |Fess| pour en +trouver la cause. ``skipped`` est normal pour des documents tels que ceux dont le corps est vide, +mais si presque tous les documents sont ``skipped``, soupçonnez une valeur erronée de +``content_chunker.chunker.name`` (lorsqu'aucun chunker n'est trouvé, un message WARN +``Chunker not found`` est journalisé). + +.. warning:: + + Corriger la configuration n'annule pas à lui seul ``skipped`` ni ``fail``. Un document + ``skipped`` n'est pas pris en charge lorsque la tâche est relancée (un document crawlé à + nouveau revient à l'état non traité), et un document ``fail`` n'est retraité que si + ``content_chunker.job.retry_failed`` vaut ``true``. Par exemple, si la tâche a été exécutée + avec un ``content_chunker.chunker.name`` erroné et que tous les documents sont devenus + ``skipped``, corrigez le nom, supprimez ``content_chunk_status`` comme indiqué ci-dessous, + puis relancez la tâche (le champ ``content`` d'un document ``skipped`` n'a pas été réécrit ; + il peut donc être traité tel quel) :: + + curl -XPOST "http://localhost:9200/fess.search/_update_by_query" \ + -H "Content-Type: application/json" -d ' + { + "query": {"term": {"content_chunk_status": "skipped"}}, + "script": {"source": "ctx._source.remove(\"content_chunk_status\")"} + }' + +Comportement de la recherche sémantique +========================================== + +Définir ``content_chunker.search.enabled=true`` enregistre le moteur de recherche sémantique +auprès du Rank Fusion, qui fusionne ensuite les résultats de la recherche par mots-clés avec ceux +de la recherche vectorielle. (Voir :doc:`rank-fusion` pour le fonctionnement du Rank Fusion.) +Par défaut, |Fess| effectue lui-même la fusion ; définir ``rank.fusion.engine.enabled=true`` +la confie plutôt à OpenSearch (voir :ref:`rank-fusion-engine`). +Au moment de la recherche, ``content_chunker.enabled`` est également consulté : si +``content_chunker.enabled=false`` ou ``content_chunker.embedding.name=none``, la recherche +sémantique n'est pas exécutée, même lorsque le moteur est enregistré (cette évaluation ayant lieu +à chaque requête, aucun redémarrage n'est nécessaire). + +.. warning:: + + Le moteur de recherche sémantique étant enregistré au démarrage, **l'activation nécessite un + redémarrage**. La désactivation (remettre la valeur à ``false``) est évaluée par requête et + prend donc effet immédiatement. + +Mode exact et mode ann +------------------------- + +La méthode de recherche est choisie automatiquement en fonction de l'état de l'index. + +.. list-table:: + :header-rows: 1 + :widths: 12 44 44 + + * - Mode + - Condition + - Caractéristiques + * - ``ann`` + - Un index disposant des réglages ``index.knn`` et de méthode ANN + - Recherche approximative du plus proche voisin utilisant HNSW. Adapté aux grands index + * - ``exact`` + - Tout le reste (un index auquel il manque soit ``index.knn``, soit les réglages de méthode + ANN, y compris lorsque la détection de l'état de l'index échoue) + - Calcul exact de similarité cosinus sur chaque vecteur. Adapté aux index de petite à + moyenne taille + +Tout index ``fess.search`` nouvellement créé sous |Fess| 15.10 dispose toujours des réglages +``index.knn`` et de méthode ANN, quelle que soit la valeur de +``content_chunker.search.enabled`` — le mode ``ann`` est donc normalement toujours utilisé. Le +mode ``exact`` est un repli pour les index plus anciens créés avant l'existence de ce mécanisme. +Les réglages k-NN ne pouvant pas être ajoutés a posteriori à un index existant, faire passer un +index en mode ``exact`` au mode ``ann`` nécessite de recréer l'index (voir +:ref:`semantic-search-migration`). Le résultat de cette détection étant mis en cache pendant +60 secondes, il faut compter jusqu'à 60 secondes après la recréation de l'index pour que le +changement soit pris en compte. + +Seuil de score +----------------- + +Définir ``content_chunker.search.min_score`` sur une similarité cosinus (0-1) exclut des +résultats de la recherche sémantique les documents dont même le chunk le plus similaire +n'atteint pas cette valeur (le score d'un document étant celui de son meilleur chunk, la coupure +s'applique au niveau du document et non du chunk). Utilisez ce réglage pour maîtriser le nombre +de résultats lorsque des requêtes sans chevauchement de vocabulaire correspondent de manière trop +large :: + + content_chunker.search.min_score=0.4 + +La valeur configurée est interprétée comme une similarité cosinus dans les deux modes, ``exact`` +comme ``ann`` (elle est convertie en interne vers l'échelle de score propre à chaque mode). + +.. note:: + + Cette coupure ne s'applique que lorsque ``content_chunker.search.knn.space_type`` vaut + ``cosinesimil`` (la valeur par défaut). Sur un index en mode ``ann`` configuré avec + ``innerproduct`` ou ``l2``, aucune similarité cosinus ne peut être définie : la coupure est + ignorée et un avertissement est consigné pour chacune de ces recherches. + +Limitations +------------- + +- Les conditions portant sur un champ dans la requête (``label:``, ``site:``, ``filetype:``, + plages sur ``timestamp`` / ``last_modified``, etc.) sont séparées du texte à vectoriser et + appliquées à la recherche vectorielle sous forme de filtres. La requête est examinée **après** + son assemblage : les opérations qui ajoutent de telles conditions en interne — la sélection + d'un label, le filtrage par facette, ou le type de fichier, le site et la plage de dates de la + recherche avancée, y compris les conditions transmises via les paramètres ``ex_q`` et + ``fields.*`` — exécutent donc toujours la recherche sémantique, restreinte par les mêmes + conditions que la recherche par mots-clés. +- **La recherche sémantique est ignorée** pour les requêtes suivantes, et seule la recherche par + mots-clés est exécutée. + + - Un critère de tri (le pseudo-champ ``sort:``, ou le paramètre ``sort``, qui est lui aussi + ajouté en interne sous la forme ``sort:...``) + - Une phrase (``"..."``), un caractère générique (``*`` ``?``), une recherche floue (``~``) ou + une plage sur des mots qui ne désignent aucun champ, y compris la phrase de la recherche + avancée. Le ``?`` ASCII étant interprété comme un caractère générique, une phrase en langage + naturel qui se termine par un point d'interrogation ASCII est elle aussi ignorée (le point + d'interrogation pleine chasse ``？`` n'est pas concerné). + - L'exclusion d'un mot (``-mot``, ``NOT mot``, y compris les termes exclus de la recherche + avancée) ou son renforcement (``mot^2``) + - Une requête dont les conditions ne peuvent pas être séparées sous forme de filtre, comme un + mot et une condition reliés par ``OR`` + - ``allintitle:`` / ``allinurl:`` + - Une requête ne contenant que des conditions, sans aucun mot à vectoriser + - Une requête qui ne peut pas être analysée + +- Elle est également ignorée lorsqu'elle est combinée à une recherche par géolocalisation (un + filtre géo) ou à une recherche de documents similaires. +- Le traitement des pages profondes dépend de l'endroit où la fusion est effectuée. + + - Lorsque |Fess| effectue la fusion (par défaut), la limite est déterminée par + ``rank.fusion.window_size`` (par défaut ``200``) ; avec les valeurs par défaut, tous les + résultats à partir du 101e proviennent uniquement de la recherche par mots-clés. + - Lorsque la fusion est effectuée côté moteur de recherche + (``rank.fusion.engine.enabled=true``), toutes les pages sont fusionnées, mais la pagination + s'arrête à ``rank.fusion.pagination_depth`` résultats (par défaut ``1000``) ; une page + au-delà ne peut pas être demandée. + + Voir :doc:`rank-fusion` pour plus de détails. +- Si le fournisseur d'embedding est inaccessible ou qu'une erreur de recherche survient, |Fess| + bascule automatiquement vers des résultats basés uniquement sur les mots-clés (la recherche + elle-même n'échoue jamais de ce fait). +- Le contrôle d'accès basé sur les rôles et les hôtes virtuels s'applique également aux résultats + de la recherche sémantique. + +Intégration avec le mode de recherche IA +============================================ + +Lorsque le mode de recherche IA (:doc:`rag-chat`, ``rag.chat.enabled=true``) est activé, pour les +documents dont le ``content_chunk_status`` est ``done``, la génération de réponse calcule la +similarité avec chaque chunk et n'utilise que les ``content_chunker.chat.top_k`` chunks les plus +pertinents (par défaut : ``3``) comme contexte du LLM. + +Le texte qui fait alors l'objet de l'embedding n'est pas l'énoncé de l'utilisateur, mais **la +requête de recherche générée par le LLM lors de la phase de détermination de l'intention** (en +cas de nouvelle recherche, c'est la requête régénérée qui est utilisée). Lorsqu'aucune requête de +recherche n'est générée — par exemple lorsque l'utilisateur demande le résumé d'un document —, +aucune sélection de chunks n'a lieu. + +Ainsi, même pour les documents longs, seules les parties pertinentes sont transmises au LLM, ce +qui peut améliorer la précision des réponses et réduire l'utilisation de tokens. Pour les +documents dont le ``content_chunk_status`` est ``chunked`` (les chunks existent, mais pas les +vecteurs), la sélection des chunks s'appuie sur la correspondance de mots-clés (surlignage) au +lieu du calcul de similarité. Les documents en ``skipped`` / ``fail`` ainsi que les documents non +traités continuent d'utiliser le corps complet (ou un extrait surligné) comme auparavant. + +Ce comportement est indépendant de ``content_chunker.search.enabled``, mais il nécessite que +``content_chunker.enabled`` soit activé. Notez également que le texte obtenu en concaténant les +chunks sélectionnés est lui aussi tronqué à ``rag.chat.content.fulltext.max.length`` (par défaut +``3000``) : augmenter ``content_chunker.chat.top_k`` ou ``content_chunker.length.chunk_size`` ne +permet donc pas de dépasser cette limite dans ce qui est transmis au LLM. + +.. _semantic-search-migration: + +Migration depuis la version 15.7 ou antérieure +================================================== + +Si vous mettez à niveau |Fess| depuis la version 15.7 ou antérieure, votre situation correspond à +l'un des quatre cas ci-dessous, selon la façon dont vous utilisez actuellement ces +fonctionnalités. Suivez les instructions correspondant à votre cas. + +Nouvelles installations +-------------------------- + +Aucun travail supplémentaire n'est nécessaire. Si vous souhaitez utiliser la recherche +vectorielle, configurez simplement ``system.properties`` selon la section *Référence de +configuration* de cette page avant de démarrer |Fess| pour la première fois ; le mapping correct +est appliqué automatiquement lors de la première création de l'index. (Voir *Procédure de +configuration* ci-dessus pour les étapes concrètes.) + +.. note:: + + Si vous avez déjà démarré |Fess| au moins une fois (c'est-à-dire que l'index existe déjà), + suivez plutôt l'un des cas *utilisateurs existants* ci-dessous. + +Utilisateurs existants ne souhaitant pas la recherche vectorielle +----------------------------------------------------------------------- + +Aucune action n'est nécessaire. ``content_chunker.enabled`` et +``content_chunker.search.enabled`` valent tous deux ``false`` par défaut, de sorte que vos +résultats de recherche et le comportement de l'index existant restent inchangés après la mise à +niveau. La nouvelle tâche du planificateur **Content Chunk Vector Indexer** est enregistrée +automatiquement au démarrage, mais comme elle est désactivée par défaut, elle ne s'exécute +jamais, et le moteur de recherche sémantique n'est jamais enregistré auprès du Rank Fusion. +(Cette tâche étant enregistrée à chaque démarrage, la supprimer depuis l'interface +d'administration la recrée, désactivée, au démarrage suivant.) + +.. note:: + + Même si vous n'utilisez pas la recherche vectorielle, toute **création** d'index sous |Fess| + 15.10 ou ultérieur (réindexation comprise) applique le mapping contenant + ``content_chunk_vector`` (de type ``knn_vector``) ainsi que ``index.knn: true``. Sur une + configuration où OpenSearch n'a pas le plugin k-NN installé, la création de l'index échoue à + ce moment-là. Voir *Prérequis* sur cette page pour plus de détails. + +Utilisateurs existants souhaitant activer la recherche vectorielle +------------------------------------------------------------------------ + +L'index en cours d'exécution n'adopte pas automatiquement le nouveau mapping, les étapes +suivantes sont donc requises. + +1. Appliquez les réglages à ``system.properties`` comme décrit dans *Référence de configuration* + sur cette page (voir *Procédure de configuration* ci-dessus pour les étapes concrètes avec le + fournisseur opensearch). +2. Redémarrez |Fess|. +3. Dans l'interface d'administration, exécutez la **Réindexation** sous **Informations système > + Maintenance** avec l'option **Remplacer les alias** activée. Cette opération s'exécute en + arrière-plan sans notification de fin. ``_cat/indices`` montre seulement que le nouvel index + existe, pas si les alias ont basculé — consultez plutôt ``_cat/aliases`` et vérifiez que + ``fess.search``/``fess.update`` pointent vers le nouvel index (le journal de |Fess| n'avertit + qu'en cas d'échec, le silence n'est donc pas une preuve de réussite). L'ancien index n'est pas + supprimé automatiquement (supprimez-le manuellement une fois que vous n'en avez plus besoin), + et l'utilisation disque des index double environ jusqu'à ce que vous le fassiez. +4. Une fois seulement que vous avez confirmé que le remplacement des alias ci-dessus est terminé, + activez et exécutez la tâche Content Chunk Vector Indexer sous **Système > Planificateur** + (inutile de relancer un crawl : la tâche lit ``content`` depuis le ``_source`` de l'index + existant pour le découper en chunks et l'embedder). + +.. note:: + + Si vous appliquez dès l'étape 1 le réglage ``content_chunker.search.enabled=true``, alors + entre le redémarrage de l'étape 2 et l'achèvement de l'étape 4, chaque recherche calcule + l'embedding de la requête sans que cela se répercute sur les résultats. Avec un fournisseur + facturé à l'usage comme ``openai``, ``gemini`` ou ``bedrock``, appliquez + ``content_chunker.search.enabled=true`` et redémarrez seulement une fois l'étape 4 terminée. + +Si vous utilisiez le plugin fess-webapp-semantic-search +------------------------------------------------------------ + +Le plugin ``fess-webapp-semantic-search``, qui fournissait la recherche sémantique dans |Fess| +15.7 et versions antérieures, a été intégré au cœur en 15.10 et est désormais **inutile +(obsolète)**. En plus des étapes décrites dans *Utilisateurs existants souhaitant activer la +recherche vectorielle* ci-dessus, vous devez également effectuer ce qui suit. + +1. **Supprimer le plugin** : supprimez ``fess-webapp-semantic-search-*.jar`` de + ``app/WEB-INF/plugin/`` (sous Docker, excluez-le de ``FESS_PLUGINS``). + +2. **Supprimer les anciens réglages** : supprimez chaque option de démarrage + ``-Dfess.semantic_search.*``. De plus, si vous aviez spécifié + ``-Drank.fusion.searchers=default,semantic`` pour l'ancien plugin, supprimez-le également. Le + laisser en place exclut le nouveau moteur de recherche sémantique (``semantic_chunk``) du Rank + Fusion et consigne un avertissement au démarrage. + +3. **Détacher l'ancien pipeline d'ingestion** : lorsque ``-Dfess.semantic_search.pipeline`` + était configuré, l'ancien plugin inscrivait ``default_pipeline`` (un pipeline d'ingestion pour + la recherche neuronale) dans les réglages de l'index au moment de la création de celui-ci. + **Supprimer le plugin ne supprime pas le pipeline** — il reste attaché à l'index et continue + de s'exécuter —, vous devez donc le détacher **avant** la réindexation décrite dans + *Utilisateurs existants souhaitant activer la recherche vectorielle*. Le nouvel index issu de + la réindexation ne porte pas ce réglage : l'exécuter après coup n'aurait aucun effet. Repérez + avec ``_cat/aliases`` l'index ``fess.`` vers lequel pointe ``fess.search``, et + ciblez l'index physique plutôt que l'alias :: + + curl -XPUT "http://localhost:9200/fess./_settings" \ + -H "Content-Type: application/json" -d ' + {"index": {"default_pipeline": "_none"}}' + + Détacher le réglage de l'index ne supprime pas le pipeline d'ingestion lui-même, qui reste + présent côté moteur de recherche. Supprimez-le si vous ne comptez plus l'utiliser :: + + curl -XDELETE "http://localhost:9200/_ingest/pipeline/" + +4. **Ajouter les nouveaux réglages** : configurez ``content_chunker.*`` dans + ``system.properties`` comme décrit dans *Référence de configuration* sur cette page. Si vous + continuez à utiliser votre modèle ML Commons existant, définissez + ``content_chunker.embedding.name=opensearch`` et placez son ``model_id`` existant dans + ``content_chunker.embedding.opensearch.model.id``. + +5. **Recréer l'index et exécuter la tâche** : le champ vectoriel que stockait l'ancien plugin + (``content_vector`` dans la configuration par défaut) et le champ ``content_chunk_vector`` + qu'utilise la nouvelle fonctionnalité du cœur sont des champs distincts ; les anciens vecteurs + ne peuvent donc pas être exploités par la nouvelle fonctionnalité. En revanche, la + réindexation recopiant ``_source`` tel quel, ces anciens vecteurs sont bel et bien dupliqués + dans le nouvel index, où ils continuent de consommer de l'espace disque via le mapping + dynamique. Nous recommandons de les supprimer **avant** la réindexation (adaptez le nom du + champ si vous l'aviez modifié) :: + + curl -XPOST "http://localhost:9200/fess.search/_update_by_query" \ + -H "Content-Type: application/json" -d ' + { + "query": {"exists": {"field": "content_vector"}}, + "script": {"source": "ctx._source.remove(\"content_vector\")"} + }' + + Exécutez ensuite la **Réindexation** sous **Informations système > Maintenance**, puis activez + et exécutez la tâche Content Chunk Vector Indexer pour régénérer les vecteurs. + +Remarques +=========== + +Changer de modèle d'embedding (dimension) +-------------------------------------------- + +Pour passer à un modèle d'embedding avec une dimension différente, suivez cet ordre. + +1. Supprimez les anciens vecteurs existants. Si des vecteurs de l'ancienne dimension subsistent + au moment de la réindexation, le nouveau mapping ne peut pas les accepter et les documents + concernés ne sont pas copiés dans le nouvel index, sans que le traitement s'interrompe pour + autant. |Fess| ne vérifiant que le statut HTTP de la réindexation, aucune erreur n'apparaît + dans l'interface d'administration alors même que des documents ont disparu :: + + curl -XPOST "http://localhost:9200/fess.search/_update_by_query" \ + -H "Content-Type: application/json" -d ' + { + "query": {"exists": {"field": "content_chunk_status"}}, + "script": {"source": "ctx._source.remove(\"content_chunk_vector\"); ctx._source.remove(\"content_chunk_status\")"} + }' + + .. note:: + + Vous pouvez tout aussi bien cibler ``fess.update`` (l'alias de mise à jour depuis lequel la + réindexation lit les documents). Notez par ailleurs que cette opération laisse le champ + ``content`` sous la forme d'un tableau de chunks. Celui-ci sera reconcaténé puis redécoupé + lors de la prochaine exécution de la tâche : si ``content_chunker.length.overlap`` est + différent de 0, les parties chevauchantes se retrouveront comptées deux fois dans le + nouveau découpage. Si cela vous pose problème, relancez un crawl sur les documents + concernés. + +2. Modifiez ``content_chunker.embedding.dimension`` et le réglage du modèle pour votre + fournisseur. +3. Recréez l'index en suivant *3. Recréer l'index (lors de l'activation sur un déploiement + existant)* dans *Procédure de configuration*, puis relancez la tâche d'indexation. + +Passer à un autre modèle de même dimension +--------------------------------------------- + +Si vous remplacez le réglage du modèle d'embedding, par exemple +``content_chunker.embedding.opensearch.model.id``, par un autre modèle de même dimension, |Fess| +l'accepte sans aucune erreur ni avertissement. Seule la dimension est vérifiée, et le modèle qui +a créé les vecteurs n'est pas enregistré dans l'index. Les vecteurs stockés ont alors été créés +par l'ancien modèle et les vecteurs de requête, lors de la recherche, par le nouveau ; les deux +vivent dans des espaces vectoriels différents, et la pertinence des résultats de recherche +s'effondre. La distribution des valeurs de similarité cosinus diffère aussi d'un modèle à +l'autre : un ``content_chunker.search.min_score`` réglé pour l'ancien modèle peut être trop +strict pour le nouveau et écarter la plupart des résultats. + +Pour changer de modèle, définissez le nouveau modèle, supprimez ``content_chunk_vector`` et +``content_chunk_status`` avec le même ``_update_by_query`` que dans l'étape 1 de *Changer de +modèle d'embedding (dimension)* ci-dessus, puis relancez la tâche d'indexation pour régénérer les +vecteurs de tous les documents (il n'est pas nécessaire de recréer l'index, car la dimension est +la même). Si vous avez défini ``content_chunker.search.min_score``, réexaminez-le avec le nouveau +modèle. + +Si l'index a été créé sans dimension +-------------------------------------- + +Si l'index ``fess.search`` est créé alors que ``content_chunker.embedding.dimension`` n'est pas +défini, le mapping de ``content_chunk_vector`` reçoit une dimension de ``768`` sans aucun +avertissement, et elle ne peut plus être modifiée ensuite. Si vous exécutez alors la tâche +d'indexation, la dimension ne peut pas être lue lors de l'embedding, ce qui est une erreur : les +documents passent à ``fail``. + +- Si le modèle utilisé a une dimension de ``768``, définissez + ``content_chunker.embedding.dimension=768``. Elle correspond au mapping ; il n'est donc pas + nécessaire de recréer l'index. +- Sinon, définissez la bonne dimension. Tant que le mapping (``768``) et le réglage divergent, + la tâche d'indexation journalise une ERROR et ignore l'exécution. Recréez l'index selon la même + méthode que dans l'étape 3 de *Changer de modèle d'embedding (dimension)* ci-dessus. + +Dans les deux cas, les documents déjà à l'état ``fail`` ne sont pas retraités automatiquement. Si +vous recréez l'index, le ``_update_by_query`` de l'étape 1 de *Changer de modèle d'embedding +(dimension)* supprime aussi ``content_chunk_status``. Si vous ne le recréez pas, définissez +temporairement ``content_chunker.job.retry_failed`` à ``true`` et relancez la tâche. + +Utilisation du disque +------------------------ + +Les vecteurs de chunks sont conservés dans ``_source`` en plus des structures de l'index de +recherche, de sorte que chaque document consomme un espace disque supplémentaire proportionnel à +son nombre de chunks multiplié par la dimension du vecteur. Si l'espace disque devient un +problème, ajustez ``content_chunker.length.chunk_size`` ou +``content_chunker.max_chunks_per_document``. + +Mode chunking seul +--------------------- + +Définir ``content_chunker.embedding.name=none`` effectue uniquement le chunking, sans générer de +vecteurs d'embedding (``content_chunk_status`` devient ``chunked``). Cela vous permet d'exécuter +le chunking à l'avance, avant que votre fournisseur d'embedding ne soit prêt ; une fois qu'un +fournisseur est configuré ultérieurement et que la tâche est relancée, des vecteurs sont générés +pour les chunks déjà stockés, sans les re-découper. + +Réglages mémoire pour les corpus volumineux +------------------------------------------------ + +La JVM enfant de la tâche d'indexation est démarrée avec ``jvm.chunk.options`` dans +``fess_config.properties`` (options JVM incluant par défaut ``-Xms128m -Xmx1g``). Comme +``content_chunker.job.max_documents_per_run`` est illimité par défaut, une seule exécution +conserve tous les ID de documents en attente en mémoire. Un ID de document est un condensat +SHA-512 (128 caractères) et occupe environ 200 octets dans le tas ; le traitement des chunks +lui-même consomme en outre de 200 à 250 Mo. Le seuil réel se situe donc **au-delà de 1 à +2 millions de documents** : augmentez alors la valeur de ``-Xmx`` dans ``jvm.chunk.options``, ou +donnez une valeur finie à ``content_chunker.job.max_documents_per_run`` pour découper le +traitement en plusieurs exécutions. ``jvm.chunk.options`` se redéfinit dans +``app/WEB-INF/classes/fess_config.properties`` (``/etc/fess/fess_config.properties`` pour les +paquets RPM/DEB) ; voir :doc:`setup-memory` pour la configuration des options JVM. + +Cette même valeur par défaut illimitée a aussi une conséquence financière avec un fournisseur +d'embedding facturé à l'usage (``openai``, ``gemini``, ``bedrock``) : la première exécution de la tâche +d'indexation génère les embeddings de tout le corpus existant en une seule fois et facture le +tout d'un coup. Définissez une valeur finie pour ``content_chunker.job.max_documents_per_run`` +afin de répartir ce coût sur plusieurs exécutions. + +Références +============ + +- :doc:`rank-fusion` - Configuration du Rank Fusion (recherche hybride) +- :doc:`rag-chat` - Configuration du mode de recherche IA +- :doc:`llm-overview` - Aperçu de l'intégration LLM +- :doc:`llm-ollama` - Configuration d'Ollama +- :doc:`setup-memory` - Réglages mémoire de la JVM +- :doc:`../install/upgrade` - Procédure de mise à niveau diff --git a/fr/15.10/config/security-role.rst b/fr/15.10/config/security-role.rst new file mode 100644 index 000000000..08027e437 --- /dev/null +++ b/fr/15.10/config/security-role.rst @@ -0,0 +1,72 @@ +=================================================== +Configuration de la recherche basée sur les rôles +=================================================== + +À propos de la recherche basée sur les rôles +============================================= + +|Fess| permet de différencier les résultats de recherche en fonction des informations d'authentification des utilisateurs authentifiés par un système d'authentification arbitraire. +Par exemple, l'utilisateur A avec le rôle a verra les informations du rôle a dans les résultats de recherche, mais l'utilisateur B sans le rôle a ne les verra pas même en effectuant une recherche. +En utilisant cette fonctionnalité, il est possible de réaliser des recherches par département ou par poste pour les utilisateurs connectés dans un portail ou un environnement d'authentification unique. + +La recherche basée sur les rôles de |Fess| peut obtenir les informations de rôle à partir de : + +- Paramètres de requête + +- En-têtes de requête + +- Cookies + +- Informations d'authentification de |Fess| + +Dans les portails et les systèmes d'authentification unique de type agent, les informations de rôle peuvent être obtenues en stockant les informations d'authentification dans les cookies pour le domaine et le chemin où |Fess| est en cours d'exécution lors de l'authentification. +De plus, dans les systèmes d'authentification unique de type proxy inverse, les informations de rôle peuvent être obtenues en ajoutant les informations d'authentification aux paramètres de requête ou aux en-têtes de requête lors de l'accès à |Fess|. + +.. note:: + L'obtention des informations de rôle à partir des paramètres de requête, des en-têtes de requête et des cookies est désactivée par défaut. + Pour les utiliser, il est nécessaire de configurer le nom de la clé référencée (``parameterKey``, ``headerKey``, ``cookieKey``), le chiffrement des valeurs (``encryptedParameterValue``, etc.) et les séparateurs (``valueSeparator``, ``roleSeparator``) dans le composant ``roleQueryHelper`` du fichier ``app/WEB-INF/classes/fess.xml``. + Par défaut, seule la recherche basée sur les rôles utilisant les informations d'authentification de |Fess| est activée. + +Configuration de la recherche basée sur les rôles +================================================== + +Cette section explique comment configurer la recherche basée sur les rôles en utilisant les informations d'authentification de |Fess|. + +Configuration dans l'interface d'administration de |Fess| +--------------------------------------------------------- + +Démarrez |Fess| et connectez-vous en tant qu'administrateur. +Créez des rôles et des utilisateurs. +Par exemple, créez Role1 dans l'écran de gestion des rôles et créez un utilisateur appartenant à Role1 dans l'écran de gestion des utilisateurs. +Si vous souhaitez attribuer des permissions par groupe, créez un groupe dans l'écran de gestion des groupes et attribuez-le aux utilisateurs. + +Ensuite, dans la configuration de l'exploration, saisissez ``{role}Role1`` dans le champ de permission et enregistrez. +Pour spécifier par utilisateur, vous pouvez écrire ``{user}username``, et pour spécifier par groupe, vous pouvez écrire ``{group}groupname``. +Pour spécifier plusieurs permissions, séparez-les par des sauts de ligne. + +Ensuite, en effectuant une exploration avec cette configuration, un index consultable uniquement par les utilisateurs appartenant aux rôles, utilisateurs et groupes spécifiés sera créé. +Les utilisateurs connectés se voient automatiquement attribuer les permissions ``{user}username`` représentant leur propre identité, ``{role}`` pour les rôles auxquels ils appartiennent, et ``{group}`` pour les groupes auxquels ils appartiennent, qui sont ensuite comparées aux permissions définies sur les documents. + +.. note:: + Pour refuser explicitement l'accès à un rôle, un utilisateur ou un groupe particulier, ajoutez le préfixe ``(deny)`` comme dans ``(deny){role}Role1`` (l'ajout de ``(allow)`` signifie autoriser l'accès, ce qui est équivalent à l'absence de spécification). + +.. note:: + En cas d'intégration avec LDAP ou un système d'authentification unique, les informations de rôle et de groupe de l'utilisateur sont obtenues depuis la source d'authentification et traitées de la même manière comme permissions. + Le comportement lors de l'intégration LDAP peut être contrôlé par les propriétés ``ldap.role.search.user.enabled``, ``ldap.role.search.group.enabled`` et ``ldap.role.search.role.enabled`` dans ``fess_config.properties`` (toutes initialisées à ``true`` par défaut). + +Connexion +--------- + +Déconnectez-vous de l'interface d'administration. +Connectez-vous avec un utilisateur appartenant à Role1. +En cas de succès de la connexion, vous serez redirigé vers la page d'accueil de recherche. + +En effectuant une recherche normale, seuls les éléments configurés avec le rôle Role1 dans la configuration de l'exploration seront affichés. + +De plus, une recherche effectuée sans être connecté sera traitée comme une recherche par l'utilisateur invité (guest). +Pour les documents que vous souhaitez afficher aux utilisateurs non connectés, définissez ``{role}guest`` dans le champ de permission de la configuration de l'exploration (la valeur par défaut est définie par ``role.search.guest.permissions``). + +Déconnexion +----------- + +En sélectionnant la déconnexion sur l'écran de recherche alors que vous êtes connecté avec un utilisateur autre que l'administrateur, vous serez déconnecté. diff --git a/fr/15.10/config/security-virtual-host.rst b/fr/15.10/config/security-virtual-host.rst new file mode 100644 index 000000000..0ce49569a --- /dev/null +++ b/fr/15.10/config/security-virtual-host.rst @@ -0,0 +1,91 @@ +================ +Hôtes virtuels +================ + +À propos des hôtes virtuels +============================ + +|Fess| peut différencier les résultats de recherche en fonction du nom d'hôte (valeur de l'en-tête HTTP ``Host``) lors de l'accès. +Il est possible de publier un seul serveur |Fess| sous plusieurs noms d'hôte et de fournir des cibles de recherche (configurations d'exploration) et des designs de page différents pour chaque nom d'hôte. +L'écran de recherche peut aussi avoir une apparence différente pour chaque hôte : un thème statique dont le nom correspond au nom de l'hôte virtuel est utilisé pour cet hôte. + +La fonctionnalité d'hôte virtuel est désactivée par défaut (non configurée). Suivez les étapes ci-dessous pour la configurer. + +Configuration système +--------------------- + +Configurez la correspondance entre le nom d'hôte de l'accédant et le nom d'hôte virtuel dans « Hôte virtuel » de :doc:`Guide administrateur > Configuration générale <../admin/general-guide>`. Spécifiez le nom d'hôte virtuel configuré ici dans la configuration de l'exploration. + +**Format** + +Décrivez un hôte virtuel par ligne selon le format suivant. + +:: + + nom_en-tête:valeur_en-tête=nom_hôte_virtuel + +.. list-table:: + + * - *nom_en-tête* + - Nom de l'en-tête de requête HTTP utilisé pour la correspondance. En général, spécifiez ``Host``. Dans le cas d'un accès via un proxy inverse, vous pouvez également spécifier ``X-Forwarded-Host``. + * - *valeur_en-tête* + - Nom d'hôte (et si nécessaire, au format ``nom_hôte:numéro_port``) contenu dans l'en-tête ci-dessus. L'hôte virtuel est appliqué en cas de correspondance exacte (insensible à la casse) avec la valeur de l'en-tête envoyée par le client lors de l'accès. + * - *nom_hôte_virtuel* + - Nom d'hôte virtuel à spécifier dans la configuration de l'exploration + +**Exemple** + +:: + + Host:abc.example.com=host1 + Host:192.168.1.123:8080=host2 + +.. note:: + + La correspondance est effectuée par comparaison de chaînes de caractères avec la valeur de l'en-tête de requête, et non par résolution de nom d'hôte (DNS). + L'en-tête ``Host`` envoyé par le navigateur ne contient pas le numéro de port lorsque l'accès se fait sur un port standard (80 pour HTTP, 443 pour HTTPS) ; pour tout autre port, le numéro de port est inclus au format ``nom_hôte:numéro_port``. + Par conséquent, si vous publiez sur un port non standard, spécifiez le numéro de port explicitement, par exemple ``Host:abc.example.com:8080=host1``. + +.. note:: + + Seuls les caractères alphanumériques et les tirets bas ( ``a-z`` , ``A-Z`` , ``0-9`` , ``_`` ) peuvent être utilisés dans les noms d'hôtes virtuels. + Les autres caractères sont automatiquement supprimés. + + De plus, les noms suivants sont réservés et ne peuvent pas être utilisés comme noms d'hôtes virtuels : + ``admin`` , ``common`` , ``error`` , ``login`` , ``profile`` + +Design de page par hôte virtuel +------------------------------- + +Pour doter un hôte virtuel de son propre écran de recherche, installez un thème statique dont le ``name`` dans ``theme.yml`` est le nom de l'hôte virtuel en minuscules (par exemple ``host1``). +Une requête correspondant à l'hôte virtuel est servie avec ce thème ; toute autre requête est servie avec le thème par défaut. +Il n'est pas nécessaire de définir ce thème comme thème par défaut. Consultez :ref:`theme-customize-bundled` pour savoir comment créer un thème à partir du thème fourni, et :doc:`../admin/theme-guide` pour savoir comment l'installer. + +.. note:: + + Depuis |Fess| 15.10, l'enregistrement de la configuration ne génère plus de JSP dans ``WEB-INF/view/nom_hôte_virtuel``. + L'écran de connexion (``/login/``) est le même pour tous les hôtes virtuels (``WEB-INF/view/admin/login/``) et ne peut pas être modifié par hôte virtuel. + L'apparence de chaque hôte virtuel se modifie avec un thème statique portant le même nom que l'hôte virtuel, comme décrit ci-dessus. + + +Configuration de l'exploration +------------------------------- + +Spécifiez « Hôte virtuel » dans l'une des configurations suivantes : configuration de l'exploration Web, configuration de l'exploration de fichiers ou configuration de l'exploration de banques de données. +« Hôte virtuel » spécifie l'un des noms d'hôtes virtuels configurés dans la configuration système. Il est également possible de spécifier plusieurs hôtes virtuels pour une même configuration d'exploration (un par ligne). + +Pour une recherche effectuée depuis un hôte virtuel, seuls les documents de la configuration d'exploration pour laquelle cet hôte virtuel est spécifié apparaissent dans les résultats de recherche. +Pour un accès ne correspondant à aucun hôte virtuel (accès normal sans hôte virtuel configuré), aucun filtrage n'est appliqué et tous les résultats de recherche sont affichés normalement. + +**Exemple** + +.. list-table:: + + * - *Hôte virtuel* + - ``host1`` + + +Tags utilisateur +---------------- + +Les tags que les utilisateurs connectés posent sur les résultats de recherche (Mes tags) suivent aussi l'hôte virtuel, lorsque la fonction de tags est activée. Un tag créé sur un hôte virtuel n'est listé et utilisable que sur cet hôte virtuel. Une requête qui ne correspond à aucun hôte virtuel voit tous les tags. Un tag qui a un hôte virtuel n'est posé que sur les documents des paramètres d'exploration qui ont cet hôte virtuel. Pour plus de détails, consultez :doc:`../admin/tagtype-guide` et :doc:`../api/api-tag`. diff --git a/fr/15.10/config/setup-memory.rst b/fr/15.10/config/setup-memory.rst new file mode 100644 index 000000000..a9eeeb38a --- /dev/null +++ b/fr/15.10/config/setup-memory.rst @@ -0,0 +1,437 @@ +================== +Configuration de la mémoire +================== + +Vue d'ensemble +==== + +Pour les applications Java, il est nécessaire de configurer la mémoire heap maximale utilisée par chaque processus. +Dans |Fess|, les paramètres de mémoire sont configurés pour les trois composants suivants. + +- Application web Fess +- Processus de crawl +- OpenSearch + +Une configuration mémoire appropriée permet d'améliorer les performances et d'assurer un fonctionnement stable. + +Configuration de la mémoire de l'application web Fess +====================================== + +Quand configurer +---------------- + +Envisagez d'ajuster la taille de la mémoire dans les cas suivants. + +- Les erreurs OutOfMemory sont enregistrées dans ``fess.log`` +- Vous devez traiter un grand nombre d'accès simultanés +- Les opérations de l'interface d'administration sont lentes ou expirent + +La taille de mémoire par défaut est suffisante pour une utilisation générale, mais une augmentation est nécessaire dans les environnements à forte charge. + +Configuration par variable d'environnement +------------------ + +Définissez la variable d'environnement ``FESS_HEAP_SIZE``. + +:: + + export FESS_HEAP_SIZE=2g + +Unités : + +- ``m`` : mégaoctets +- ``g`` : gigaoctets + +Contrôle Détaillé de la Mémoire +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``FESS_HEAP_SIZE`` définit ``-Xms`` et ``-Xmx`` à la même valeur. Pour contrôler indépendamment les tailles de heap initiale et maximale, utilisez les variables d'environnement ``FESS_MIN_MEM`` et ``FESS_MAX_MEM``. + +:: + + export FESS_MIN_MEM=256m + export FESS_MAX_MEM=2g + +.. list-table:: Configuration Mémoire par Défaut selon la Plateforme + :header-rows: 1 + :widths: 30 35 35 + + * - Plateforme + - FESS_MIN_MEM (Par défaut) + - FESS_MAX_MEM (Par défaut) + * - Linux + - 256m + - 2g + * - Windows + - 256m + - 1g + +.. note:: + Lorsque ``FESS_HEAP_SIZE`` est défini, ``FESS_MIN_MEM`` et ``FESS_MAX_MEM`` sont ignorés. + +.. note:: + Avec les paquets RPM/DEB, le fichier d'environnement (``/etc/sysconfig/fess``, ou ``/etc/default/fess`` pour DEB) définit ``FESS_HEAP_SIZE=512m``. Le heap est donc fixé à 512m au lieu des valeurs par défaut du tableau ci-dessus. Pour modifier la taille du heap, changez cette valeur de ``FESS_HEAP_SIZE``. + +Pour les packages RPM/DEB +------------------------ + +Si vous avez installé avec le package RPM, éditez ``/etc/sysconfig/fess``. + +:: + + FESS_HEAP_SIZE=2g + +Pour le package DEB, éditez ``/etc/default/fess``. + +:: + + FESS_HEAP_SIZE=2g + +.. warning:: + Après avoir modifié la taille de la mémoire, vous devez redémarrer le service |Fess|. + +Tailles de mémoire recommandées +---------------- + +.. list-table:: + :header-rows: 1 + :widths: 30 30 40 + + * - Environnement + - Taille heap recommandée + - Remarques + * - Environnement de développement/test + - 512m〜1g + - Index de petite taille + * - Environnement de production à petite échelle + - 1g〜2g + - Dizaines à centaines de milliers de documents + * - Environnement de production à moyenne échelle + - 2g〜4g + - Centaines de milliers à millions de documents + * - Environnement de production à grande échelle + - 4g〜8g + - Plusieurs millions de documents et plus + +Configuration de la mémoire du crawler +====================== + +Quand configurer +---------------- + +Vous devez augmenter la taille de mémoire du crawler dans les cas suivants. + +- Lorsque vous augmentez le nombre de crawls parallèles +- Lors du crawl de fichiers volumineux +- Lorsque des erreurs OutOfMemory se produisent pendant l'exécution du crawl + +Méthode de configuration +-------- + +Éditez ``app/WEB-INF/classes/fess_config.properties`` ou ``/etc/fess/fess_config.properties``. + +``jvm.crawler.options`` est un paramètre unique qui énumère les options JVM du processus du crawler, séparées par des retours à la ligne (``\n``). Modifier la valeur remplace toutes les options par défaut : si vous n'écrivez que ``-Xmx512m``, les autres options par défaut, comme ``-Dfile.encoding=UTF-8`` et les réglages G1GC, sont également perdues. Conservez la valeur par défaut indiquée dans ``fess_config.properties`` et ne modifiez que les lignes relatives à la taille du heap. + +Par exemple, pour porter le heap maximal à 1 Go, modifiez comme suit la ligne ``-Xmx512m`` de la valeur par défaut. + +:: + + -Xms128m\n\ + -Xmx1g\n\ + +.. note:: + Ce paramètre est appliqué par processus de crawl (par tâche du planificateur). + Si vous exécutez plusieurs tâches de crawl simultanément, chaque tâche utilisera la mémoire spécifiée. + +Paramètres recommandés +-------- + +- **Crawl web normal** : 512m〜1g +- **Crawl parallèle intensif** : 1g〜2g +- **Crawl de fichiers volumineux** : 2g〜4g + +Options JVM détaillées +------------------ + +Les options JVM détaillées pour le crawler peuvent être configurées avec ``jvm.crawler.options``. +Les paramètres par défaut incluent les optimisations suivantes. + +**Options principales :** + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - Option + - Description + * - ``-Xms128m -Xmx512m`` + - Taille heap initiale et maximale + * - ``-XX:MaxMetaspaceSize=128m`` + - Taille maximale du Metaspace + * - ``-XX:+UseG1GC`` + - Utilisation du collecteur de déchets G1 + * - ``-XX:MaxGCPauseMillis=60000`` + - Objectif de temps de pause GC maximal (60s), assoupli pour les charges de travail du crawler (~200ms en général) + * - ``-XX:-HeapDumpOnOutOfMemoryError`` + - Désactivation du dump heap lors d'OutOfMemory + +Configuration de la mémoire OpenSearch +======================= + +Considérations importantes +-------------- + +Pour OpenSearch, vous devez configurer la mémoire en tenant compte des deux points suivants. + +1. **Mémoire heap Java** : Utilisée par le processus OpenSearch +2. **Cache du système de fichiers OS** : Important pour les performances de recherche + +.. warning:: + Si vous augmentez trop la mémoire heap Java, la mémoire disponible pour + le cache du système de fichiers OS diminue, ce qui peut dégrader les performances de recherche. + +Méthode de configuration +-------- + +Environnement Linux +~~~~~~~~~ + +La méthode recommandée pour configurer la mémoire heap OpenSearch est d'éditer ``config/jvm.options`` : + +:: + + -Xms2g + -Xmx2g + +.. note:: + Il est recommandé de définir la taille heap minimale (``-Xms``) et maximale (``-Xmx``) à la même valeur. + +.. note:: + La variable d'environnement ``OPENSEARCH_HEAP_SIZE`` est obsolète. Utilisez ``OPENSEARCH_JAVA_OPTS`` à la place si vous avez besoin de définir la mémoire via une variable d'environnement : + + :: + + export OPENSEARCH_JAVA_OPTS="-Xms2g -Xmx2g" + +Environnement Windows +~~~~~~~~~~~ + +Éditez le fichier ``config\jvm.options``. + +:: + + -Xms2g + -Xmx2g + +Tailles de mémoire recommandées +---------------- + +.. list-table:: + :header-rows: 1 + :widths: 30 30 40 + + * - Taille de l'index + - Taille heap recommandée + - Mémoire totale recommandée + * - 〜10GB + - 2g + - 4 Go ou plus + * - 10GB〜50GB + - 4g + - 8 Go ou plus + * - 50GB〜100GB + - 8g + - 16 Go ou plus + * - 100 Go et plus + - 16g〜31g + - 32 Go ou plus + +.. warning:: + Ne configurez pas la mémoire heap OpenSearch au-delà de 32 Go. + Au-delà de 32 Go, Compressed OOP est désactivé, ce qui réduit l'efficacité de la mémoire. + +Bonnes pratiques +------------------ + +1. **Allouer 50% de la mémoire physique au heap** + + Allouez environ 50% de la mémoire physique du serveur au heap OpenSearch. + Le reste est utilisé pour l'OS et le cache du système de fichiers. + +2. **Maximum 31 Go** + + La taille heap doit être limitée à 31 Go maximum. Si vous avez besoin de plus, augmentez le nombre de nœuds. + +3. **Vérification en production** + + Consultez la documentation officielle OpenSearch pour optimiser la configuration selon votre environnement. + +Configuration de la mémoire pour les processus de suggestion et de miniature +====================================== + +Processus de génération de suggestions +---------------------- + +Les paramètres de mémoire pour le processus de génération de suggestions sont configurés avec ``jvm.suggest.options``. + +Comme pour le crawler, ce paramètre contient toutes les options par défaut : ne modifiez que la ligne ``-Xmx256m`` et conservez les autres. + +Par défaut, les paramètres suivants sont utilisés : + +- Heap initial : 128 Mo +- Heap maximal : 256 Mo +- Metaspace maximal : 128 Mo + +Processus de génération de miniatures +---------------------- + +Les paramètres de mémoire pour le processus de génération de miniatures sont configurés avec ``jvm.thumbnail.options``. + +Comme pour le crawler, ce paramètre contient toutes les options par défaut : ne modifiez que la ligne ``-Xmx256m`` et conservez les autres. + +Par défaut, les paramètres suivants sont utilisés : + +- Heap initial : 128 Mo +- Heap maximal : 256 Mo +- Metaspace maximal : 128 Mo + +.. note:: + Si vous traitez de grandes images lors de la génération de miniatures, vous devrez augmenter la mémoire. + +Surveillance et optimisation de la mémoire +======================== + +Vérification de l'utilisation de la mémoire +-------------------- + +Utilisation de la mémoire Fess +~~~~~~~~~~~~~~~~~~~~~ + +Vous pouvez vérifier dans « Informations système » de l'interface d'administration. + +Ou utilisez les outils de surveillance JVM : + +:: + + jps -l # Vérifier le processus Fess + jstat -gcutil 1000 # Afficher les statistiques GC toutes les secondes + +Utilisation de la mémoire OpenSearch +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + curl -X GET "localhost:9200/_nodes/stats/jvm?pretty" + curl -X GET "localhost:9200/_cat/nodes?v&h=heap.percent,ram.percent" + +Signes de manque de mémoire +---------------- + +Si les symptômes suivants apparaissent, il peut y avoir un manque de mémoire. + +**Application web Fess :** + +- Réponses lentes +- ``OutOfMemoryError`` enregistré dans les journaux +- Arrêt inattendu du processus + +**Crawler :** + +- Le crawl s'arrête en cours d'exécution +- ``OutOfMemoryError`` enregistré dans ``fess-crawler.log`` +- Échec du crawl de fichiers volumineux + +**OpenSearch :** + +- Recherche lente +- Création d'index lente +- Erreurs ``circuit_breaker_exception`` + +Procédure d'optimisation +---------------- + +1. **Vérifier l'utilisation actuelle de la mémoire** + + Surveillez l'utilisation de la mémoire de chaque composant. + +2. **Identifier les goulots d'étranglement** + + Identifiez quel composant manque de mémoire. + +3. **Augmenter progressivement** + + N'augmentez pas de manière excessive en une fois, augmentez de 25-50% et vérifiez l'effet. + +4. **Considérer l'équilibre global du système** + + Assurez-vous que la mémoire totale de tous les composants ne dépasse pas la mémoire physique. + +5. **Surveillance continue** + + Surveillez en continu l'utilisation de la mémoire et ajustez si nécessaire. + +Prévention des fuites mémoire +---------------- + +En cas de suspicion de fuite mémoire : + +1. **Obtenir un dump heap** + +:: + + jmap -dump:format=b,file=heap.bin + +2. **Analyser le dump heap** + + Analysez avec des outils comme Eclipse Memory Analyzer (MAT). + +3. **Signaler le problème** + + Si vous découvrez une fuite mémoire, signalez-la sur GitHub Issues. + +Dépannage +====================== + +OutOfMemoryError se produit +--------------------------- + +**Application web Fess :** + +1. Augmentez ``FESS_HEAP_SIZE``. +2. Limitez le nombre d'accès simultanés. +3. Réduisez le niveau de journalisation pour diminuer l'utilisation de la mémoire par les journaux. + +**Crawler :** + +1. Augmentez ``-Xmx`` dans ``jvm.crawler.options``. +2. Réduisez le nombre de crawls parallèles. +3. Ajustez la configuration du crawl pour exclure les fichiers volumineux. + +**OpenSearch :** + +1. Augmentez la taille heap (jusqu'à 31 Go maximum). +2. Revoyez le nombre de shards de l'index. +3. Vérifiez la complexité des requêtes. + +Temps d'arrêt GC prolongé +---------------------- + +1. Ajustez les paramètres G1GC. +2. Configurez correctement la taille heap (un GC fréquent se produit si elle est trop grande ou trop petite). +3. Envisagez de mettre à jour vers une version Java plus récente. + +Les performances ne s'améliorent pas après la configuration de la mémoire +------------------------------ + +1. Vérifiez d'autres ressources comme le CPU, les E/S disque et le réseau. +2. Optimisez l'index. +3. Revoyez les paramètres de requête et de crawl. + +Informations de référence +======== + +- :doc:`setup-port-network` - Configuration du port et du réseau +- :doc:`crawler-advanced` - Configuration avancée du crawler +- :doc:`admin-logging` - Configuration des journaux +- `OpenSearch Memory Settings `_ +- `Java GC Tuning `_ diff --git a/fr/15.10/config/setup-port-network.rst b/fr/15.10/config/setup-port-network.rst new file mode 100644 index 000000000..1e0bc9fa6 --- /dev/null +++ b/fr/15.10/config/setup-port-network.rst @@ -0,0 +1,470 @@ +====================== +Configuration du port et du réseau +====================== + +Vue d'ensemble +==== + +Cette section décrit les paramètres liés au réseau de |Fess|. +Elle couvre les paramètres relatifs aux connexions réseau, tels que la modification des numéros de port, la configuration du proxy et les paramètres de communication HTTP. + +Configuration des ports utilisés +================ + +Ports par défaut +---------------- + +|Fess| utilise les ports suivants par défaut. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Service + - Numéro de port + * - Application web Fess + - 8080 + * - OpenSearch (HTTP) + - 9200 + * - OpenSearch (Transport) + - 9300 + +Modification du port de l'application web Fess +-------------------------------------- + +Configuration sous Linux +~~~~~~~~~~~~~~~~~ + +Pour modifier le numéro de port sous Linux, éditez ``bin/fess.in.sh``. + +:: + + FESS_JAVA_OPTS="$FESS_JAVA_OPTS -Dfess.port=8080" + +Par exemple, pour utiliser le port 80 : + +:: + + FESS_JAVA_OPTS="$FESS_JAVA_OPTS -Dfess.port=80" + +.. note:: + Pour utiliser un numéro de port inférieur ou égal à 1024, vous devez disposer des privilèges root ou d'une configuration de privilèges appropriée (CAP_NET_BIND_SERVICE). + +Configuration par variable d'environnement +~~~~~~~~~~~~~~~~~~ + +Vous pouvez également spécifier le numéro de port via une variable d'environnement. + +:: + + export FESS_PORT=8080 + +.. warning:: + La variable d'environnement ``FESS_PORT`` n'est disponible que sous Linux. Sous Windows, modifiez ``-Dfess.port`` directement dans ``bin\fess.in.bat``. + +Pour les packages RPM/DEB +~~~~~~~~~~~~~~~~~~~~~~~~ + +Pour le package RPM, éditez ``/etc/sysconfig/fess``, et pour le package DEB, éditez ``/etc/default/fess``. + +:: + + FESS_PORT=8080 + +Configuration sous Windows +~~~~~~~~~~~~~~~~~~~ + +Sous Windows, éditez ``bin\fess.in.bat``. + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.port=8080 + +Lors de l'enregistrement en tant que service Windows +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Lorsque vous utilisez un enregistrement en tant que service sous Windows, modifiez également les paramètres de port dans ``bin\service.bat``. +Consultez :doc:`setup-windows-service` pour plus de détails. + +Configuration du chemin de contexte +---------------------- + +Si vous publiez |Fess| dans un sous-répertoire, vous pouvez configurer le chemin de contexte. + +**Sous Linux :** + +:: + + FESS_JAVA_OPTS="$FESS_JAVA_OPTS -Dfess.context.path=/search" + +Ou via la variable d'environnement : + +:: + + export FESS_CONTEXT_PATH=/search + +**Sous Windows :** + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.context.path=/search + +Avec cette configuration, vous pourrez accéder à ``http://localhost:8080/search/``. + +.. warning:: + La variable d'environnement ``FESS_CONTEXT_PATH`` n'est disponible que sous Linux. Sous Windows, utilisez ``-Dfess.context.path`` dans ``bin\fess.in.bat``. + +.. warning:: + Si vous modifiez le chemin de contexte, vous devez également configurer correctement le chemin des fichiers statiques. + +Configuration du proxy +============ + +Vue d'ensemble +---- + +Lors du crawl de sites externes depuis un intranet ou de l'accès à des API externes, +les communications peuvent être bloquées par un pare-feu. +Dans de tels environnements, il est nécessaire de configurer la communication via un serveur proxy. + +Configuration du proxy pour le crawler +-------------------------- + +Configuration de base +~~~~~~~~ + +Dans l'interface d'administration, spécifiez dans les paramètres de configuration du crawl comme suit. + +:: + + client.proxyHost=proxy.example.com + client.proxyPort=8080 + +Configuration d'un proxy avec authentification +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Si le serveur proxy nécessite une authentification, ajoutez ce qui suit. + +:: + + client.proxyHost=proxy.example.com + client.proxyPort=8080 + client.proxyUsername=proxyuser + client.proxyPassword=proxypass + +Exclusion d'hôtes spécifiques du proxy +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Les paramètres de proxy du crawler ne prennent pas en charge nonProxyHosts. +Pour exclure des hôtes spécifiques du proxy, utilisez la variable d'environnement ``FESS_NON_PROXY_HOSTS``. +Ce paramètre est converti en propriété système Java ``http.nonProxyHosts`` et s'applique à toutes les communications HTTP de Fess. + +:: + + FESS_NON_PROXY_HOSTS=localhost|*.local|192.168.* + +Configuration du proxy par défaut du crawler +------------------------------ + +Pour définir un proxy par défaut lorsque ``client.proxyHost`` n'est pas spécifié dans les configurations de crawl individuelles, configurez dans ``fess_config.properties``. +Ce paramètre s'applique au proxy par défaut du robot d'exploration, ainsi qu'à la communication HTTP de l'intégration LLM et aux téléchargements de plugins. En revanche, il ne s'applique pas à la communication de certaines bibliothèques Java telles que l'authentification SSO. Pour appliquer un proxy à l'ensemble de l'application Fess (y compris l'authentification SSO), utilisez les variables d'environnement décrites ci-dessous (``FESS_PROXY_HOST``, etc.). + +:: + + http.proxy.host=proxy.example.com + http.proxy.port=8080 + http.proxy.username=proxyuser + http.proxy.password=proxypass + +.. warning:: + Les mots de passe sont stockés sans chiffrement. Configurez les permissions de fichier appropriées. + +.. note:: + Les paramètres ``http.proxy.*`` ne s'appliquent pas à l'authentification SSO, etc. Pour utiliser un proxy pour l'ensemble de l'application Fess, y compris l'authentification SSO (communication HTTP à l'échelle de la JVM), définissez les variables d'environnement ``FESS_PROXY_HOST`` et ``FESS_PROXY_PORT``. Pour plus de détails, voir « Configuration du proxy via les variables d'environnement » ci-dessous. + +Configuration du proxy via les variables d'environnement +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Lorsque les bibliothèques Java telles que l'authentification SSO doivent utiliser un proxy, vous devez le configurer via des variables d'environnement. +Ces variables d'environnement sont converties en propriétés système Java (``http.proxyHost``, ``https.proxyHost``, etc.). + +:: + + FESS_PROXY_HOST=proxy.example.com + FESS_PROXY_PORT=8080 + FESS_NON_PROXY_HOSTS=localhost|*.local|192.168.* + +Pour les packages RPM, configurez dans ``/etc/sysconfig/fess``. Pour les packages DEB, configurez dans ``/etc/default/fess``. + +.. note:: + Les paramètres ``http.proxy.*`` de ``fess_config.properties`` sont utilisés pour le proxy par défaut du robot d'exploration, ainsi que pour l'intégration LLM et les téléchargements de plugins. + Pour utiliser un proxy pour l'ensemble de l'application Fess, y compris l'authentification SSO (communication HTTP à l'échelle de la JVM), définissez les variables d'environnement ci-dessus. + +Configuration de la communication HTTP +============ + +Limitation du téléchargement de fichiers +-------------------------- + +Vous pouvez limiter la taille des fichiers téléchargés depuis l'interface d'administration. + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - Élément de configuration + - Description + * - ``http.fileupload.max.size`` + - Taille maximale de téléchargement de fichier (par défaut : 262144000 octets = 250 Mo) + * - ``http.fileupload.threshold.size`` + - Taille de seuil pour la conservation en mémoire (par défaut : 262144 octets = 256 Ko) + * - ``http.fileupload.max.file.count`` + - Nombre de fichiers pouvant être téléchargés en une fois (par défaut : 10) + +Exemple de configuration dans ``fess_config.properties`` : + +:: + + http.fileupload.max.size=524288000 + http.fileupload.threshold.size=524288 + http.fileupload.max.file.count=20 + +Paramètres de connexion OpenSearch +----------------------------------- + +Vous pouvez configurer l'URL de connexion à OpenSearch et l'intervalle de vérification d'état (heartbeat). + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - Élément de configuration + - Description + * - ``search_engine.http.url`` + - URL d'OpenSearch (par défaut : http://localhost:9200). La variable d'environnement ``SEARCH_ENGINE_HTTP_URL`` est prioritaire (voir ci-dessous). + * - ``search_engine.heartbeat_interval`` + - Intervalle de vérification de santé (millisecondes, par défaut : 10000) + +Modification de la destination de connexion OpenSearch +---------------------- + +L'URL à laquelle |Fess| se connecte se définit avec la variable +d'environnement ``SEARCH_ENGINE_HTTP_URL``. Elle est prioritaire sur +``search_engine.http.url`` dans ``fess_config.properties``. Le +``bin/fess.in.sh`` du paquet ZIP et le fichier d'environnement des paquets +RPM/DEB définissent cette variable à ``http://localhost:9200`` par défaut ; +modifier ``search_engine.http.url`` ne change donc pas la destination de la +connexion. + +L'endroit où la définir dépend du mode d'installation : + +- Paquet ZIP : modifiez la ligne ``SEARCH_ENGINE_HTTP_URL`` de + ``bin/fess.in.sh``, ou exportez ``SEARCH_ENGINE_HTTP_URL`` dans + l'environnement qui démarre |Fess| (voir :doc:`../install/install-linux`). +- Paquet RPM/DEB : ``SEARCH_ENGINE_HTTP_URL`` dans ``/etc/sysconfig/fess`` + (RPM) ou ``/etc/default/fess`` (DEB). +- Docker : la variable d'environnement du conteneur ``SEARCH_ENGINE_HTTP_URL`` + (voir :doc:`../install/install-docker`). +- Paquet ZIP sous Windows : la ligne ``-Dfess.search_engine.http_address`` de + ``bin\fess.in.bat`` (voir :doc:`../install/install-windows`). + +:: + + SEARCH_ENGINE_HTTP_URL=http://opensearch-cluster.example.com:9200 + +Connexion à plusieurs nœuds +~~~~~~~~~~~~~~~~~~ + +Pour se connecter à plusieurs nœuds OpenSearch, séparez les URL par des +virgules. Si certains nœuds sont arrêtés, |Fess| se connecte aux nœuds +restants. + +:: + + SEARCH_ENGINE_HTTP_URL=http://node1:9200,http://node2:9200,http://node3:9200 + +Configuration de la connexion SSL/TLS +----------------- + +Pour se connecter à OpenSearch via HTTPS, indiquez une URL ``https://`` de la +même manière que ci-dessus : + +:: + + SEARCH_ENGINE_HTTP_URL=https://opensearch.example.com:9200 + +Définissez le certificat de l'autorité de certification et les identifiants +dans ``fess_config.properties`` : + +:: + + search_engine.http.ssl.certificate_authorities=/path/to/ca.crt + search_engine.username=admin + search_engine.password=admin_password + +.. note:: + Pour effectuer la vérification du certificat, spécifiez le chemin du certificat CA dans ``certificate_authorities``. + +Configuration de l'hôte virtuel +============== + +Vue d'ensemble +---- + +Vous pouvez différencier les résultats de recherche en fonction du nom d'hôte utilisé pour accéder à |Fess|. +Consultez :doc:`security-virtual-host` pour plus de détails. + +Configuration de base +-------- + +Configurez les hôtes virtuels depuis l'interface d'administration « Système > Général » (``virtual.host.headers``). Spécifiez un hôte virtuel par ligne au format ``Host:nomdhote[:port]=nomdhotevirtuel``. La valeur par défaut est vide (non définie) et la fonction d'hôte virtuel est désactivée. + +:: + + Host:search1.example.com=site1 + Host:search2.example.com=site2 + +.. note:: + La valeur de ``virtual.host.headers`` n'est PAS une liste de noms d'en-tête tels que ``X-Forwarded-Host,Host``. Chaque ligne décrit une correspondance au format ``NomDEnTête:ValeurDEnTête=nomdhotevirtuel``. Pour le format détaillé et les contraintes, voir :doc:`security-virtual-host`. + +Intégration avec un reverse proxy +======================== + +Exemple de configuration Nginx +-------------- + +:: + + server { + listen 80; + server_name search.example.com; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Host $host; + } + } + +Exemple de configuration Apache +--------------- + +:: + + + ServerName search.example.com + + ProxyPreserveHost On + ProxyPass / http://localhost:8080/ + ProxyPassReverse / http://localhost:8080/ + + RequestHeader set X-Forwarded-Proto "http" + RequestHeader set X-Forwarded-Host "search.example.com" + + +Terminaison SSL/TLS +----------- + +Exemple de configuration pour la terminaison SSL/TLS sur le reverse proxy (Nginx) : + +:: + + server { + listen 443 ssl http2; + server_name search.example.com; + + ssl_certificate /path/to/cert.pem; + ssl_certificate_key /path/to/key.pem; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto https; + proxy_set_header X-Forwarded-Host $host; + } + } + +Configuration du pare-feu +==================== + +Ouverture des ports nécessaires +------------------ + +Pour rendre |Fess| accessible depuis l'extérieur, ouvrez les ports suivants. + +**Exemple de configuration iptables :** + +:: + + # Application web Fess + iptables -A INPUT -p tcp --dport 8080 -j ACCEPT + + # Pour accès HTTPS (via reverse proxy) + iptables -A INPUT -p tcp --dport 443 -j ACCEPT + +**Exemple de configuration firewalld :** + +:: + + # Application web Fess + firewall-cmd --permanent --add-port=8080/tcp + firewall-cmd --reload + +Configuration du groupe de sécurité (environnements cloud) +------------------------------------------ + +Dans les environnements cloud comme AWS, GCP ou Azure, ouvrez les ports appropriés +avec les groupes de sécurité ou les ACL réseau. + +Configuration recommandée : +- Entrant : ports 80/443 (via reverse proxy HTTP) +- Restreindre l'accès au port 8080 uniquement depuis l'interne +- Restreindre l'accès aux ports 9200/9300 d'OpenSearch uniquement depuis l'interne + +Dépannage +====================== + +Impossible d'accéder après modification du port +------------------------------ + +1. Vérifiez si vous avez redémarré |Fess|. +2. Vérifiez si le port correspondant est ouvert dans le pare-feu. +3. Vérifiez les erreurs dans le fichier journal (``fess.log``). + +Impossible de crawler via le proxy +------------------------------ + +1. Vérifiez si le nom d'hôte et le port du serveur proxy sont corrects. +2. Si le serveur proxy nécessite une authentification, configurez le nom d'utilisateur et le mot de passe. +3. Vérifiez si les tentatives de connexion sont enregistrées dans les journaux du serveur proxy. +4. Vérifiez si la configuration de ``nonProxyHosts`` est appropriée. + +Impossible de se connecter à OpenSearch +------------------------- + +1. Vérifiez si OpenSearch est démarré. +2. Vérifiez si la configuration de ``search_engine.http.url`` est correcte. +3. Vérifiez la connexion réseau : ``curl http://localhost:9200`` +4. Vérifiez les erreurs dans les journaux d'OpenSearch. + +Fonctionnement anormal lors de l'accès via reverse proxy +---------------------------------------------------- + +1. Vérifiez si l'en-tête ``X-Forwarded-Host`` est correctement configuré. +2. Vérifiez si l'en-tête ``X-Forwarded-Proto`` est correctement configuré. +3. Vérifiez si le chemin de contexte est correctement configuré. +4. Vérifiez les erreurs dans les journaux du reverse proxy. + +Informations de référence +======== + +- :doc:`setup-memory` - Configuration de la mémoire +- :doc:`setup-windows-service` - Configuration du service Windows +- :doc:`security-virtual-host` - Configuration de l'hôte virtuel +- :doc:`crawler-advanced` - Configuration avancée du crawler +- `OpenSearch Configuration `_ diff --git a/fr/15.10/config/setup-windows-service.rst b/fr/15.10/config/setup-windows-service.rst new file mode 100644 index 000000000..0f96ab1c1 --- /dev/null +++ b/fr/15.10/config/setup-windows-service.rst @@ -0,0 +1,134 @@ +========================================== +Enregistrement en tant que service Windows +========================================== + +Enregistrement en tant que service Windows +========================================== + +|Fess| peut être enregistré en tant que service Windows. L'enregistrement en tant que service permet de démarrer automatiquement |Fess| au démarrage du système. +Pour exécuter |Fess|, OpenSearch doit être démarré au préalable. +Nous supposons ici que |Fess| est installé dans ``c:\opt\fess`` et OpenSearch dans ``c:\opt\opensearch`` (adaptez les chemins à votre environnement). + +.. note:: + |Fess| et OpenSearch ne prennent en charge que les versions 64 bits. + +Préparation préalable +--------------------- + +Veuillez définir ``JAVA_HOME`` comme variable d'environnement système. ``service.bat`` se termine avec une erreur si ``JAVA_HOME`` n'est pas défini. + +Enregistrement d'OpenSearch en tant que service +----------------------------------------------- + +Ouvrez une invite de commandes avec des droits d'administrateur et exécutez ``c:\opt\opensearch\bin\opensearch-service.bat``. + +:: + + > cd c:\opt\opensearch\bin + > opensearch-service.bat install + ... + The service 'opensearch-service-x64' has been installed. + +Pour plus de détails, consultez la `documentation OpenSearch `_. + +Configuration de |Fess| +----------------------- + +Le service est enregistré depuis ``c:\opt\fess\bin\service.bat``. Lors de l'enregistrement, ``service.bat`` lit ``bin\fess.in.bat`` et applique son contenu aux options de démarrage de |Fess|. +Ajoutez la configuration de connexion à OpenSearch dans ``c:\opt\fess\bin\fess.in.bat``. + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200 + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=c:/opt/opensearch/config/dictionary/ + +.. note:: + - ``fess.search_engine.http_address`` permet de spécifier la destination de connexion du service OpenSearch enregistré. Sans cette configuration, |Fess| ne peut pas trouver la destination de connexion et ne démarre pas ; il signale qu'aucune adresse de moteur de recherche n'est configurée. + - Si vous exécutez OpenSearch sur un hôte différent, modifiez le nom d'hôte ou l'adresse IP en conséquence. + - Utilisez ``/`` comme séparateur de chemin. + +Le numéro de port par défaut pour l'interface de recherche et d'administration de |Fess| est ``8080``. Pour le changer, modifiez ``-Dfess.port`` dans ``c:\opt\fess\bin\fess.in.bat``. + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.port=80 + +.. note:: + Lors de l'enregistrement en tant que service, ``-Dfess.port=8080`` est également codé en dur dans ``FESS_PARAMS`` dans ``bin\service.bat``. Cette valeur est prioritaire sur la configuration de ``fess.in.bat``. Par conséquent, lors du changement de port, modifiez également ``FESS_PARAMS`` dans ``service.bat``. + +Personnalisation du service (facultatif) +---------------------------------------- + +Vous pouvez modifier la configuration du service en définissant des variables d'environnement avant d'exécuter ``service.bat install``. Les principales variables d'environnement sont les suivantes. + +.. list-table:: + :header-rows: 1 + + * - Variable d'environnement + - Description + * - ``FESS_START_TYPE`` + - Type de démarrage (``auto`` ou ``manual``). La valeur par défaut est ``manual``. + * - ``FESS_HEAP_SIZE`` + - Taille du tas (ex. : ``1g``). Pour spécifier séparément la taille minimale et maximale du tas, utilisez ``FESS_MIN_MEM`` (valeur par défaut ``256m``) et ``FESS_MAX_MEM`` (valeur par défaut ``1g``). + * - ``SERVICE_USERNAME`` / ``SERVICE_PASSWORD`` + - Compte Windows sous lequel le service s'exécute. + * - ``SERVICE_DISPLAY_NAME`` + - Nom d'affichage du service. + * - ``SERVICE_DESCRIPTION`` + - Description du service. + +Procédure d'enregistrement +--------------------------- + +Exécutez ``c:\opt\fess\bin\service.bat`` depuis une invite de commandes avec des droits d'administrateur. + +:: + + > cd c:\opt\fess\bin + > service.bat install + ... + The service 'fess-service-x64' has been installed. + +Configuration du service +------------------------ + +Pour démarrer le service manuellement, démarrez d'abord le service OpenSearch, puis démarrez le service |Fess|. +Pour un démarrage automatique au démarrage du système, configurez le type de démarrage et les dépendances. + +1. Dans les paramètres généraux du service, définissez le type de démarrage sur « Automatique (début différé) ». +2. Les dépendances du service sont configurées dans le registre. + +Ajoutez la clé et la valeur suivantes dans l'éditeur de registre (regedit). + +.. list-table:: + + * - *Clé* + - ``Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\fess-service-x64\DependOnService`` + * - *Valeur* + - ``opensearch-service-x64`` + +Une fois ajouté, opensearch-service-x64 apparaîtra dans les dépendances des propriétés du service |Fess|. + +.. note:: + En définissant la variable d'environnement ``FESS_START_TYPE=auto`` avant ``service.bat install``, vous pouvez enregistrer le type de démarrage sur « Automatique ». Cependant, « Automatique (début différé) » et la configuration des dépendances ne peuvent pas être effectués via ``service.bat`` ; veuillez les configurer selon la procédure décrite ci-dessus. + +Gestion du service +------------------ + +Avec ``service.bat``, vous pouvez gérer le service à l'aide des commandes suivantes. + +.. list-table:: + :header-rows: 1 + + * - Commande + - Description + * - ``service.bat install`` + - Enregistre le service. + * - ``service.bat remove`` + - Supprime le service. + * - ``service.bat start`` + - Démarre le service. + * - ``service.bat stop`` + - Arrête le service. + * - ``service.bat manager`` + - Lance l'interface graphique de gestion du service. diff --git a/fr/15.10/config/sso-entraid.rst b/fr/15.10/config/sso-entraid.rst new file mode 100644 index 000000000..60aa8227c --- /dev/null +++ b/fr/15.10/config/sso-entraid.rst @@ -0,0 +1,441 @@ +======================================= +Configuration SSO avec Entra ID +======================================= + +Aperçu +====== + +|Fess| prend en charge l'authentification Single Sign-On (SSO) en utilisant Microsoft Entra ID (anciennement Azure AD). +En utilisant l'authentification Entra ID, vous pouvez intégrer les informations utilisateur et les informations de groupe de votre environnement Microsoft 365 avec la recherche basée sur les rôles de |Fess|. + +.. note:: + La prise en charge de l'authentification Entra ID provient du plugin ``fess-sso-entraid``, + qui ne fait pas partie de la distribution. Installez-le depuis la page + **Système > Plugin** de l'écran d'administration ou avec + ``bin/fess-setup install plugin fess-sso-entraid``. + Jusque-là, avec ``sso.type=entraid`` (ou l'ancien ``aad``), toute requête vers ``/sso/`` est + simplement redirigée vers la page de connexion. + +Fonctionnement de l'authentification Entra ID +--------------------------------------------- + +Dans l'authentification Entra ID, |Fess| opère en tant que client OAuth 2.0/OpenID Connect et collabore avec Microsoft Entra ID pour l'authentification. + +1. L'utilisateur accède au point de terminaison SSO de |Fess| (``/sso/``) +2. |Fess| redirige vers le point de terminaison d'autorisation d'Entra ID +3. L'utilisateur s'authentifie auprès d'Entra ID (connexion Microsoft) +4. Entra ID redirige le code d'autorisation vers |Fess| +5. |Fess| utilise le code d'autorisation pour obtenir un jeton d'accès +6. L'utilisateur est connecté +7. En arrière-plan, |Fess| utilise l'API Microsoft Graph pour récupérer les informations de groupe et de rôle de l'utilisateur, et les applique à la recherche basée sur les rôles une fois la résolution terminée + +.. note:: + À partir de |Fess| 15.10, la réponse d'autorisation de l'étape 4 est renvoyée via une requête + GET, car |Fess| demande ``response_mode=query`` au point de terminaison d'autorisation. + Jusqu'à la version 15.7, elle était renvoyée via un POST inter-sites, et la valeur par défaut + fournie ``tomcat.sameSiteCookies = lax`` n'envoie pas le cookie de session dans ce cas ; + ``tomcat.sameSiteCookies = none`` était donc nécessaire comme contournement. Si vous avez + défini ``none`` uniquement pour cette raison, vous pouvez revenir à la valeur par défaut. + +Pour l'intégration avec la recherche basée sur les rôles, consultez :doc:`security-role`. + +Prérequis +========= + +Avant de configurer l'authentification Entra ID, vérifiez les prérequis suivants : + +- |Fess| 15.10 ou supérieur est installé +- Un tenant Microsoft Entra ID (Azure AD) est disponible +- |Fess| est accessible via HTTPS (requis pour les environnements de production) +- Vous avez la permission d'enregistrer des applications dans Entra ID + +Configuration de base +===================== + +Activation du SSO +----------------- + +Pour activer l'authentification Entra ID, ajoutez le paramètre suivant dans ``app/WEB-INF/conf/system.properties`` : + +:: + + sso.type=entraid + +Paramètres requis +----------------- + +Configurez les informations obtenues d'Entra ID. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propriété + - Description + - Valeur par défaut + * - ``entraid.tenant`` + - ID du tenant (ex: ``xxx.onmicrosoft.com``) + - (Requis) + * - ``entraid.client.id`` + - ID d'application (Client) + - (Requis) + * - ``entraid.client.secret`` + - Valeur du secret client + - (Requis) + * - ``entraid.reply.url`` + - URI de redirection (URL de callback) + - Utilise l'URL de la requête + +.. note:: + Au lieu du préfixe ``entraid.*``, vous pouvez également utiliser le préfixe legacy ``aad.*`` pour la rétrocompatibilité. + +Paramètres optionnels +--------------------- + +Les paramètres suivants peuvent être ajoutés si nécessaire. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propriété + - Description + - Valeur par défaut + * - ``entraid.authority`` + - URL du serveur d'authentification + - ``https://login.microsoftonline.com/`` + * - ``entraid.state.ttl`` + - Durée de vie du state (secondes) + - ``3600`` + * - ``entraid.response.mode`` + - Mode de renvoi de la réponse d'autorisation. Soit ``query``, soit ``form_post``. + - ``query`` + * - ``entraid.default.groups`` + - Groupes par défaut (séparés par des virgules). Appliqués à tous les utilisateurs Entra ID. + - (Aucun) + * - ``entraid.default.roles`` + - Rôles par défaut (séparés par des virgules). Appliqués à tous les utilisateurs Entra ID. + - (Aucun) + * - ``entraid.permission.fields`` + - Champs de groupe/rôle (séparés par des virgules) à utiliser en plus comme valeurs de permission. L'ID (GUID) du groupe/rôle est toujours utilisé comme permission, et les valeurs des champs indiqués ici (ex : ``mail``) sont ajoutées. Seuls les champs dont la valeur est une chaîne de caractères peuvent être utilisés. Microsoft Graph renvoie un champ tel que ``securityEnabled`` sous forme de booléen et ``groupTypes`` sous forme de liste ; ni l'un ni l'autre ne peut devenir une valeur de permission, un tel champ est donc ignoré et un avertissement mentionnant son nom est écrit dans le journal. + - ``mail`` + * - ``entraid.use.ds`` + - Intégration avec le service de domaine. Quand ``true``, pour les valeurs de permission au format ``name@domain``, la partie locale (``name``) sans la partie domaine est également ajoutée comme permission. Cela s'applique non seulement aux groupes et aux rôles, mais aussi à l'utilisateur connecté lui-même : la partie locale de son nom principal d'utilisateur (UPN) est ajoutée comme permission au niveau utilisateur. Le passage à ``false`` supprime donc également cette permission au niveau utilisateur, et pas seulement celles des groupes. + - ``true`` + +.. note:: + + L'ID (GUID) du groupe/rôle est toujours utilisé comme permission, mais seuls les groupes à + extension messagerie possèdent une valeur ``mail``. Les groupes Microsoft 365 sont à extension + messagerie, leur nom est donc également enregistré comme permission. **Les groupes de sécurité + ne sont pas à extension messagerie : avec la valeur par défaut, seul leur GUID devient une + permission.** Si les droits d'accès du système de fichiers désignent un groupe de sécurité, les + permissions ne correspondent pas et ces documents n'apparaissent pas dans les résultats de + recherche. + + Dans ce cas, ajoutez ``displayName``, que tous les groupes possèdent : + + .. code-block:: properties + + entraid.permission.fields=mail,displayName + + ``displayName`` n'est ni qualifié par domaine ni unique, c'est pourquoi il ne figure pas dans la + valeur par défaut. Par exemple, si Entra ID contient un groupe nommé ``Administrators``, il + correspondra aussi aux documents dont les droits d'accès désignent le groupe Windows intégré + ``Administrators``. Avant de l'ajouter, vérifiez que les noms n'entrent pas en conflit avec ceux + déjà utilisés dans vos droits d'accès. + +.. note:: + Avec la valeur par défaut ``query``, le code d'autorisation figure dans la chaîne de requête de + l'URL de callback. ``form_post`` maintient le code hors de l'URL, et donc hors de l'historique + du navigateur et des journaux d'accès des proxys frontaux ou d'un WAF, mais il transforme le + callback en un POST inter-sites et nécessite ``tomcat.sameSiteCookies = none``. Sans ce + paramètre, le cookie de session n'est pas renvoyé et la connexion échoue. Les navigateurs + n'acceptent en outre ``none`` que sur un cookie portant également l'attribut ``Secure`` : + ``form_post`` impose donc de servir |Fess| en HTTPS. En HTTP simple, le navigateur n'enregistre + pas du tout le cookie de session et la connexion échoue malgré tout. La plupart des + installations doivent donc conserver la valeur par défaut. Toute autre valeur est ignorée avec + un avertissement et ``query`` est utilisé. + +.. warning:: + + ``entraid.default.groups`` et ``entraid.default.roles`` sont des valeurs globales uniques, sans + portée par utilisateur. |Fess| les applique à tous les utilisateurs Entra ID lors de la + connexion et les réapplique à chaque résolution ultérieure, si bien que Microsoft Graph ne les + retire jamais. En particulier, ne placez jamais le rôle d'administrateur |Fess| — ``admin`` avec + la valeur ``authentication.admin.roles`` livrée — dans ``entraid.default.roles`` : cela + accorderait à tous les utilisateurs du locataire un accès permanent aux écrans + d'administration. + +Configuration côté Entra ID +=========================== + +Enregistrement de l'application dans le portail Azure +----------------------------------------------------- + +1. Connectez-vous au `Portail Azure `_ + +2. Sélectionnez **Microsoft Entra ID** + +3. Allez dans **Gérer** → **Inscriptions d'applications** → **Nouvelle inscription** + +4. Enregistrez l'application : + + .. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Paramètre + - Valeur + * - Nom + - Tout nom (ex: Fess SSO) + * - Types de comptes pris en charge + - "Comptes de cet annuaire d'organisation uniquement" + * - Plateforme + - Web + * - URI de redirection + - ``https:///sso/`` + +5. Cliquez sur **Inscrire** + +Création d'un secret client +--------------------------- + +1. Sur la page de détails de l'application, cliquez sur **Certificats et secrets** + +2. Cliquez sur **Nouveau secret client** + +3. Définissez une description et une date d'expiration, puis cliquez sur **Ajouter** + +4. Copiez et sauvegardez la **Valeur** générée (cette valeur ne sera plus affichée) + +.. warning:: + La valeur du secret client n'est affichée qu'immédiatement après la création. + Assurez-vous de l'enregistrer avant de quitter la page. + +Configuration des autorisations d'API +------------------------------------- + +1. Cliquez sur **Autorisations d'API** dans le menu de gauche + +2. Cliquez sur **Ajouter une autorisation** + +3. Sélectionnez **Microsoft Graph** + +4. Sélectionnez **Autorisations déléguées** + +5. Ajoutez l'autorisation suivante : + + - ``User.Read`` - Requis pour récupérer les appartenances aux groupes de l'utilisateur connecté (``/me/memberOf``). Accordé par défaut lors de la création de l'inscription d'application + - ``GroupMember.Read.All`` - Requis pour lire les attributs de groupe tels que le nom du groupe et pour résoudre les groupes imbriqués + +6. Cliquez sur **Ajouter des autorisations** + +7. Cliquez sur **Accorder le consentement administrateur pour ** + +.. note:: + Le consentement administrateur nécessite des privilèges d'administrateur de tenant. + +.. note:: + ``Group.Read.All`` ou ``Directory.Read.All`` peuvent être accordés à la place de + ``GroupMember.Read.All`` : la lecture des attributs de groupe et la résolution des groupes + imbriqués fonctionnent également. En revanche, ``/me/memberOf`` n'est pas autorisé par + ``Group.Read.All``, si bien que ``User.Read`` reste nécessaire dans tous les cas. + +.. note:: + Les autorisations ci-dessus ne couvrent pas le ``displayName`` d'un rôle d'annuaire : + Microsoft Graph le renvoie à null. Indiquer ``displayName`` dans + ``entraid.permission.fields`` n'apporte donc rien pour un rôle d'annuaire, et seul + l'identifiant (GUID) du rôle devient une autorisation. Pour utiliser les noms de rôle comme + valeurs d'autorisation, accordez également ``RoleManagement.Read.Directory`` (ou + ``Directory.Read.All``). + +.. note:: + |Fess| demande le scope ``https://graph.microsoft.com/.default`` lors de l'acquisition d'un jeton. + Depuis la version 15.10, ``openid profile offline_access https://graph.microsoft.com/.default`` est également envoyé au point de terminaison d'autorisation, afin que le consentement soit demandé pour le même ensemble. + Cela signifie que toutes les autorisations d'accès configurées et consenties sur l'inscription d'application sont utilisées. + Par conséquent, pour récupérer les informations de groupe, vous devez ajouter les autorisations ci-dessus à l'inscription d'application et accorder le consentement administrateur. + +Informations à obtenir +---------------------- + +Les informations suivantes sont utilisées pour la configuration de Fess : + +- **ID d'application (Client)** : Sur la page Vue d'ensemble, sous "ID d'application (client)" +- **ID du tenant** : Sur la page Vue d'ensemble, sous "ID de répertoire (tenant)" ou au format ``xxx.onmicrosoft.com`` +- **Valeur du secret client** : La valeur créée dans Certificats et secrets + +Mappage des groupes et rôles +============================ + +Avec l'authentification Entra ID, |Fess| récupère automatiquement les groupes et rôles auxquels un utilisateur appartient en utilisant l'API Microsoft Graph. +Les ID de groupe et noms de groupe récupérés peuvent être utilisés pour la recherche basée sur les rôles de |Fess|. + +Groupes imbriqués +----------------- + +|Fess| récupère non seulement les groupes auxquels les utilisateurs appartiennent directement, mais aussi les groupes parents auxquels ceux-ci appartiennent (groupes imbriqués). +La recherche de l'appartenance directe et la recherche des groupes parents s'exécutent toutes deux dans la même tâche en arrière-plan après la connexion, si bien que la connexion elle-même n'est jamais ralentie par Microsoft Graph. +La recherche des groupes parents utilise l'opération ``getMemberGroups`` de Microsoft Graph, qui résout de manière transitive : un seul appel par groupe directement attribué renvoie tous les groupes situés au-dessus de lui, quelle que soit la profondeur de l'imbrication. Les résultats récupérés sont mis en cache pendant une certaine durée. Lorsque cette tâche en arrière-plan est terminée, les permissions de l'utilisateur sont recalculées. + +Paramètres de groupe par défaut +------------------------------- + +Pour attribuer des groupes communs à tous les utilisateurs Entra ID : + +:: + + entraid.default.groups=authenticated_users,entra_users + +Exemples de configuration +========================= + +Configuration minimale (pour les tests) +--------------------------------------- + +Voici un exemple de configuration minimale pour vérification dans un environnement de test. + +:: + + # Activer SSO + sso.type=entraid + + # Paramètres Entra ID + entraid.tenant=yourcompany.onmicrosoft.com + entraid.client.id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + entraid.client.secret=your-client-secret-value + entraid.reply.url=http://localhost:8080/sso/ + +Configuration recommandée (pour la production) +---------------------------------------------- + +Voici un exemple de configuration recommandée pour les environnements de production. + +:: + + # Activer SSO + sso.type=entraid + + # Paramètres Entra ID + entraid.tenant=yourcompany.onmicrosoft.com + entraid.client.id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + entraid.client.secret=your-client-secret-value + entraid.reply.url=https://fess.example.com/sso/ + + # Groupes par défaut (optionnel) + entraid.default.groups=authenticated_users + +Configuration legacy (rétrocompatibilité) +----------------------------------------- + +Pour la compatibilité avec les versions antérieures, le préfixe ``aad.*`` peut également être utilisé. +Quand une propriété ``entraid.*`` n'est pas définie, la valeur de la propriété ``aad.*`` correspondante est utilisée. De plus, ``sso.type=aad`` est traité de la même manière que ``sso.type=entraid``. + +:: + + # Activer SSO (sso.type=aad peut également être utilisé) + sso.type=entraid + + # Clés de configuration legacy + aad.tenant=yourcompany.onmicrosoft.com + aad.client.id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + aad.client.secret=your-client-secret-value + aad.reply.url=https://fess.example.com/sso/ + +Dépannage +========= + +Problèmes courants et solutions +------------------------------- + +Impossible de revenir à Fess après l'authentification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Vérifiez que l'URI de redirection est correctement configurée dans l'inscription de l'application du portail Azure +- Assurez-vous que la valeur de ``entraid.reply.url`` correspond exactement à la configuration du portail Azure +- Vérifiez que le protocole (HTTP/HTTPS) correspond +- Vérifiez que l'URI de redirection se termine par ``/`` +- Si ``entraid.response.mode`` est défini sur ``form_post``, vérifiez à la fois que + ``tomcat.sameSiteCookies = none`` est configuré et que |Fess| est servi en HTTPS. Avec la valeur + par défaut ``lax``, le navigateur n'envoie pas le cookie de session avec le POST inter-sites du + callback ; avec ``none`` en HTTP simple, le navigateur n'enregistre pas du tout ce cookie, car + ``none`` exige l'attribut ``Secure``. Dans les deux cas, la connexion échoue une seule fois : le + navigateur revient à la page de connexion en affichant "Le processus de connexion SSO a échoué." + et un avertissement indiquant ``Failed to process SSO login: could not validate state`` est écrit + dans le journal + +Des erreurs d'authentification se produisent +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Vérifiez que l'ID du tenant, l'ID client et le secret client sont correctement configurés +- Vérifiez que le secret client n'a pas expiré +- Vérifiez que le consentement administrateur a été accordé pour les autorisations d'API + +Impossible de récupérer les informations de groupe +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Vérifiez que les autorisations ``User.Read`` et ``GroupMember.Read.All`` ont été accordées + (``GroupMember.Read.All`` peut être remplacé par ``Group.Read.All`` ou ``Directory.Read.All``, + mais ``/me/memberOf`` exige toujours ``User.Read``) +- Vérifiez que le consentement administrateur a été accordé +- Vérifiez que l'utilisateur appartient à des groupes dans Entra ID +- Si les groupes parents imbriqués ne peuvent pas être résolus, l'avertissement + ``Not allowed to read the parent groups of ...`` est journalisé. Accordez alors + ``GroupMember.Read.All`` +- |Fess| résout l'appartenance aux groupes et rôles de l'utilisateur en arrière-plan une fois la + connexion terminée, si bien que la connexion elle-même n'attend jamais Microsoft Graph. Tant que + la résolution n'est pas terminée, l'utilisateur ne dispose que de sa propre autorisation au + niveau utilisateur et de ce qu'apportent ``entraid.default.groups`` et + ``entraid.default.roles``. Si aucun des deux n'est défini — la valeur livrée par défaut —, une + recherche effectuée pendant cette fenêtre ne renvoie aucun document : + ``role.search.default.permissions`` est vide d'origine, et une configuration d'exploration créée + avec la valeur ``role.search.default.display.permissions`` livrée accorde ``{role}guest``, rôle + que ne possède pas un utilisateur connecté. La fenêtre dure jusqu'à environ une seconde de délai + de planification, plus les appels à Microsoft Graph eux-mêmes — un pour les appartenances + directes, puis un de plus pour chacun de ces groupes afin de parcourir les groupes imbriqués, + émis les uns après les autres avec un cache froid — : elle croît donc avec le nombre de groupes + auxquels appartient l'utilisateur. Pendant ce temps, l'écran de recherche indique à + l'utilisateur que ses autorisations de groupe et de rôle sont en cours de chargement et l'invite + à relancer la recherche dans un instant +- Si la résolution n'aboutit pas entièrement, l'écran de recherche indique à l'utilisateur que ses + autorisations de groupe et de rôle n'ont pas pu être entièrement chargées, l'invite à se + déconnecter puis à se reconnecter, et à contacter l'administrateur si le problème persiste. + « Entièrement » est délibéré : la résolution n'est considérée comme réussie que si la requête + des appartenances directes et le parcours des groupes imbriqués ont tous deux abouti ; un + utilisateur qui possède ses groupes directs mais pas ses groupes parents reçoit donc aussi ce + message. Un cas fait exception, et c'est celui que décrit le point précédent : lorsque + Microsoft Graph refuse la recherche des groupes imbriqués avec ``Authorization_RequestDenied`` + parce que ``GroupMember.Read.All`` n'a jamais été accordé, |Fess| l'interprète non pas comme un + échec, mais comme une réponse signifiant que le groupe n'a pas de groupe parent. La résolution + est alors considérée comme réussie et **aucun message n'est affiché**, bien que les + autorisations des groupes parents manquent. Le seul indice est l'avertissement + ``Not allowed to read the parent groups of ...`` dans le journal ; vérifiez donc sa présence dès + que des groupes imbriqués sont utilisés. La cause habituelle du cas partiel est la limitation de + débit : un seul HTTP 429 ou 503 + de Microsoft Graph fait patienter |Fess| aussi longtemps que l'exige l'en-tête ``Retry-After`` + (60 secondes s'il n'indique rien d'exploitable, 60 minutes au maximum), et pendant ce temps + toute recherche de groupes imbriqués est ignorée dans l'ensemble de l'instance |Fess| alors que + les requêtes directes continuent de répondre. L'échec + n'est pas nécessairement définitif : la résolution est relancée à chaque renouvellement du jeton + d'accès, et une réussite ultérieure fait disparaître le message et restaure les autorisations + manquantes. Se déconnecter puis se reconnecter relance la résolution immédiatement — ouvrir + l'URL de connexion SSO alors qu'il est encore connecté ne fait que le rediriger vers l'écran de + recherche + +Paramètres de débogage +---------------------- + +Pour investiguer les problèmes, vous pouvez afficher des logs détaillés liés à Entra ID en ajustant le niveau de log de |Fess|. + +Dans ``app/WEB-INF/classes/log4j2.xml``, vous pouvez ajouter le logger suivant pour changer le niveau de log : + +:: + + + +Référence +========= + +- :doc:`security-role` - Configuration de la recherche basée sur les rôles +- :doc:`sso-saml` - Configuration SSO avec authentification SAML +- :doc:`sso-oidc` - Configuration SSO avec authentification OpenID Connect diff --git a/fr/15.10/config/sso-oidc.rst b/fr/15.10/config/sso-oidc.rst new file mode 100644 index 000000000..3b8662d19 --- /dev/null +++ b/fr/15.10/config/sso-oidc.rst @@ -0,0 +1,333 @@ +====================================== +Configuration SSO avec OpenID Connect +====================================== + +Vue d'ensemble +============== + +|Fess| prend en charge l'authentification Single Sign-On (SSO) utilisant OpenID Connect (OIDC). +OpenID Connect est un protocole d'authentification basé sur OAuth 2.0 qui utilise des ID Tokens (JWT) pour l'authentification des utilisateurs. +En utilisant l'authentification OpenID Connect, les informations utilisateur authentifiées par un OpenID Provider (OP) peuvent être intégrées avec |Fess|. + +.. note:: + La prise en charge de l'authentification OpenID Connect provient du plugin + ``fess-sso-oidc``, qui ne fait pas partie de la distribution. Installez-le depuis la page + **Système > Plugin** de l'écran d'administration ou avec + ``bin/fess-setup install plugin fess-sso-oidc``. Le plugin s'appelle ``fess-sso-oidc`` alors + que la valeur de ``sso.type`` reste ``oic``. + Jusque-là, avec ``sso.type=oic``, toute requête vers ``/sso/`` est simplement redirigée vers + la page de connexion. + +Fonctionnement de l'authentification OpenID Connect +---------------------------------------------------- + +Dans l'authentification OpenID Connect, |Fess| fonctionne comme une Relying Party (RP) et collabore avec un OpenID Provider (OP) externe pour l'authentification. + +1. L'utilisateur accède au endpoint SSO de |Fess| (``/sso/``) +2. |Fess| redirige vers le endpoint d'autorisation de l'OP +3. L'utilisateur s'authentifie auprès de l'OP +4. L'OP redirige le code d'autorisation vers |Fess| +5. |Fess| utilise le code d'autorisation pour obtenir un ID Token depuis le endpoint de token +6. |Fess| vérifie les claims de l'ID Token (JWT), en extrait les informations utilisateur et connecte l'utilisateur + +.. note:: + |Fess| utilise le flux de code d'autorisation (Authorization Code Flow). L'ID Token est obtenu directement depuis le endpoint de token via un canal arrière (communication serveur à serveur) entre |Fess| et l'OP, sans passer par le navigateur. + |Fess| décode l'ID Token pour extraire les claims (``email``, ``groups``, etc.) et constituer les informations utilisateur, mais ne procède pas à la vérification cryptographique de la signature JWT. OpenID Connect Core l'autorise, car le token est reçu directement depuis le endpoint de token via TLS ; l'URL du endpoint de token (``oic.token.server.url``) doit donc être en HTTPS. ``http`` n'est accepté que pour ``localhost``, ``127.x.x.x`` et ``::1``. + |Fess| vérifie en revanche les claims : ``aud`` doit contenir ``oic.client.id`` (et ``azp``, lorsqu'il est présent, doit lui être égal), ``exp`` doit être présent et ne pas être dépassé (un décalage d'horloge pouvant atteindre 300 secondes est toléré), et ``iss`` doit être égal à ``oic.issuer`` lorsque cette clé est définie. Sans ``oic.issuer``, ``iss`` n'est pas vérifié et un avertissement est journalisé lors de la première connexion après chaque démarrage. ``nonce`` et PKCE ne sont pas utilisés. + +Pour l'intégration avec la recherche basée sur les rôles, voir :doc:`security-role`. + +Prérequis +========= + +Avant de configurer l'authentification OpenID Connect, vérifiez les prérequis suivants : + +- |Fess| 15.10 ou supérieur est installé +- Un fournisseur compatible OpenID Connect (OP) est disponible +- |Fess| est accessible via HTTPS (requis pour les environnements de production) +- Vous avez la permission d'enregistrer |Fess| comme client (RP) côté OP + +Exemples de fournisseurs pris en charge : + +- Microsoft Entra ID (Azure AD) +- Google Workspace / Google Cloud Identity +- Okta +- Keycloak +- Auth0 +- Autres fournisseurs compatibles OpenID Connect + +Configuration de base +===================== + +Activation du SSO +----------------- + +Pour activer l'authentification OpenID Connect, ajoutez le paramètre suivant dans ``app/WEB-INF/conf/system.properties`` : + +:: + + sso.type=oic + +.. note:: + ``sso.type`` ainsi que les paramètres ``oic.*`` décrits ci-après, à l'exception de ``oic.issuer``, peuvent également être configurés et modifiés depuis la page « Système > Général » de l'interface d'administration. + Les paramètres modifiés dans l'interface d'administration sont enregistrés dans ``system.properties`` et sont conservés après redémarrage. + ``oic.issuer`` ne peut être défini que dans ``system.properties``. + +Configuration du fournisseur +---------------------------- + +Configurez les informations obtenues de votre OP. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propriété + - Description + - Par défaut + * - ``oic.auth.server.url`` + - URL du endpoint d'autorisation + - ``https://accounts.google.com/o/oauth2/auth`` + * - ``oic.token.server.url`` + - URL du endpoint de token + - ``https://accounts.google.com/o/oauth2/token`` + * - ``oic.issuer`` + - Identifiant de l'émetteur (optionnel). Lorsqu'il est défini, le claim ``iss`` de l'ID Token doit lui être strictement égal (une barre oblique finale compte) + - (vide : ``iss`` n'est pas vérifié) + +.. note:: + Ces URLs et l'émetteur peuvent être obtenus depuis le endpoint Discovery de l'OP (``/.well-known/openid-configuration``) ; l'émetteur correspond à sa valeur ``issuer``. + + L'URL du endpoint de token (``oic.token.server.url``) doit être en HTTPS. ``http`` n'est accepté que si l'hôte est ``localhost`` (sans distinction de casse), une adresse IPv4 de la forme ``127.x.x.x`` ou ``::1``. L'hôte est comparé tel qu'il est écrit et n'est jamais résolu ; un nom de service Docker Compose (par exemple ``http://keycloak:8080/...``) ou un nom d'hôte interne est donc refusé en ``http``, même s'il désigne la même machine. + + Seul le endpoint de token est contrôlé, pas le endpoint d'autorisation (``oic.auth.server.url``). Le contrôle a lieu à la connexion, pas au démarrage. Définir ``oic.issuer`` n'assouplit pas cette règle ; cela active seulement la vérification du claim ``iss``. + +Configuration du client +----------------------- + +Configurez les informations client enregistrées auprès de l'OP. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propriété + - Description + - Par défaut + * - ``oic.client.id`` + - ID client + - (vide) + * - ``oic.client.secret`` + - Secret client + - (vide) + * - ``oic.scope`` + - Scopes demandés + - (vide) + +.. note:: + Le scope doit inclure au moins ``openid``. + Pour récupérer l'adresse e-mail de l'utilisateur, spécifiez ``openid email``. + +Configuration de l'URL de redirection +-------------------------------------- + +Configurez l'URL de callback après l'authentification. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propriété + - Description + - Par défaut + * - ``oic.redirect.url`` + - URL de redirection (URL de callback) + - ``{oic.base.url}/sso/`` + * - ``oic.base.url`` + - URL de base de |Fess| + - ``http://localhost:8080`` + +.. note:: + Si ``oic.redirect.url`` est omis, il est automatiquement construit à partir de ``oic.base.url``. + Pour les environnements de production, définissez ``oic.base.url`` sur une URL HTTPS. + +Configuration des attributs utilisateur +---------------------------------------- + +Configurez les groupes et rôles par défaut à attribuer aux utilisateurs authentifiés via OIDC. +L'identifiant utilisateur, les groupes et les rôles sont déterminés comme suit : + +- **Identifiant utilisateur** : extrait du claim ``email`` de l'ID Token (JWT). Pour cette raison, le scope doit en pratique inclure ``email`` (si le claim ``email`` ne peut pas être obtenu, la connexion ne s'effectuera pas correctement). +- **Groupes** : extraits du claim ``groups`` de l'ID Token. Si le claim ``groups`` est absent, la valeur de ``oic.default.groups`` est utilisée. Un tableau ``groups`` vide est considéré comme présent : ``oic.default.groups`` n'est alors pas utilisé et l'utilisateur est traité comme n'ayant aucun groupe. +- **Rôles** : la valeur de ``oic.default.roles`` est toujours utilisée (il n'existe pas de mécanisme permettant d'extraire les rôles depuis les claims de l'ID Token). + +.. note:: + |Fess| utilise telles quelles les valeurs du claim ``groups`` : aucune interrogation de + l'annuaire n'est effectuée et les groupes imbriqués (transitifs) ne sont pas développés. + La présence des groupes parents dépend donc uniquement de la configuration des claims de l'OP, + contrairement à :doc:`sso-entraid`, où |Fess| résout les groupes parents en utilisant l'API + Microsoft Graph. + La valeur du claim devient telle quelle la permission de recherche. Si l'OP est configuré pour + émettre les chemins de groupe complets, il envoie des valeurs comme ``/parent/enfant``, qui ne + correspondent pas aux documents étiquetés avec le seul nom du groupe. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propriété + - Description + - Par défaut + * - ``oic.default.groups`` + - Groupes par défaut (séparés par des virgules) + - (vide) + * - ``oic.default.roles`` + - Rôles par défaut (séparés par des virgules) + - (vide) + +.. note:: + Pour utiliser la recherche basée sur les rôles, vous devez attribuer des groupes ou des rôles appropriés aux utilisateurs. + Pour plus de détails, voir :doc:`security-role`. + +Configuration côté OP +===================== + +Lors de l'enregistrement de |Fess| comme client (RP) côté OP, configurez les informations suivantes : + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Paramètre + - Valeur + * - Type d'application + - Application web + * - URI de redirection / URL de callback + - ``https:///sso/`` + * - Scopes autorisés + - ``openid`` et les scopes requis (``email``, ``profile``, etc.) + +Informations à obtenir de l'OP +------------------------------- + +Obtenez les informations suivantes depuis l'écran de configuration ou le endpoint Discovery de l'OP pour la configuration de |Fess| : + +- **Endpoint d'autorisation (Authorization Endpoint)** : URL pour initier l'authentification utilisateur +- **Endpoint de token (Token Endpoint)** : URL pour obtenir les tokens +- **Issuer** (optionnel) : valeur ``issuer`` du document Discovery, utilisée pour ``oic.issuer`` +- **ID client** : Identifiant client émis par l'OP +- **Secret client** : Clé secrète utilisée pour l'authentification du client + +.. note:: + La plupart des OP vous permettent de vérifier les URLs des endpoints d'autorisation et de token depuis le + endpoint Discovery (``https:///.well-known/openid-configuration``). + +Exemples de configuration +========================= + +Configuration minimale (pour les tests) +---------------------------------------- + +Voici un exemple de configuration minimale pour la vérification dans un environnement de test. + +:: + + # Activer SSO + sso.type=oic + + # Configuration du fournisseur (définir les valeurs obtenues de l'OP) + oic.auth.server.url=https://op.example.com/authorize + oic.token.server.url=https://op.example.com/token + + # Configuration du client + oic.client.id=your-client-id + oic.client.secret=your-client-secret + oic.scope=openid email + + # URL de redirection (environnement de test) + oic.redirect.url=http://localhost:8080/sso/ + +Configuration recommandée (pour la production) +----------------------------------------------- + +Voici un exemple de configuration recommandée pour les environnements de production. + +:: + + # Activer SSO + sso.type=oic + + # Configuration du fournisseur + oic.auth.server.url=https://op.example.com/authorize + oic.token.server.url=https://op.example.com/token + + # Issuer (la valeur « issuer » du document Discovery) + oic.issuer=https://op.example.com + + # Configuration du client + oic.client.id=your-client-id + oic.client.secret=your-client-secret + oic.scope=openid email profile + + # URL de base (utiliser HTTPS pour la production) + oic.base.url=https://fess.example.com + +Dépannage +========= + +Problèmes courants et solutions +-------------------------------- + +Impossible de retourner à |Fess| après l'authentification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Vérifiez que l'URI de redirection est correctement configurée côté OP +- Assurez-vous que la valeur de ``oic.redirect.url`` ou ``oic.base.url`` correspond à la configuration de l'OP +- Vérifiez que le protocole (HTTP/HTTPS) correspond + +Des erreurs d'authentification se produisent +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Vérifiez que l'ID client et le secret client sont correctement configurés +- Assurez-vous que le scope inclut ``openid`` +- Vérifiez que l'URL du endpoint d'autorisation et l'URL du endpoint de token sont correctes +- Si la connexion échoue, ``fess.log`` contient un avertissement ``Failed to process the OpenID Connect callback:`` suivi du motif +- ``The ID token was not issued for this client`` : le claim ``aud`` de l'ID Token n'est pas ``oic.client.id`` ; vérifiez l'ID client +- ``The ID token has expired`` : les horloges de l'hôte |Fess| et de l'OP diffèrent de plus de 300 secondes ; synchronisez l'heure (NTP) +- ``The ID token was not issued by the configured issuer`` : ``oic.issuer`` diffère du ``iss`` indiqué dans le message ; copiez exactement la valeur ``issuer`` du document Discovery +- ``oic.token.server.url must be https`` : utilisez une URL de endpoint de token en HTTPS (``http`` ne fonctionne que pour ``localhost``, ``127.x.x.x`` et ``::1`` ; ``http`` vers un nom de service Docker Compose ou un nom d'hôte interne est également refusé) + +Impossible de récupérer les informations utilisateur +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Assurez-vous que le scope inclut les permissions requises (``email``, ``profile``, etc.) +- Vérifiez que les scopes requis sont autorisés pour le client côté OP +- Avec Microsoft Entra ID, le claim ``groups`` contient les ``ObjectId`` (GUID) des groupes, sauf + si un autre attribut source est sélectionné ; les valeurs ne correspondent donc pas aux noms de + groupe +- Microsoft Entra ID omet entièrement le claim ``groups`` lorsque l'utilisateur appartient à plus + de 200 groupes (les groupes imbriqués comptent dans cette limite) ; |Fess| se rabat alors sur + ``oic.default.groups`` + +Configuration de débogage +-------------------------- + +Pour investiguer les problèmes, vous pouvez afficher des logs détaillés liés à OpenID Connect en ajustant le niveau de log de |Fess|. + +Dans ``app/WEB-INF/classes/log4j2.xml``, vous pouvez ajouter le logger suivant pour changer le niveau de log : + +:: + + + +.. warning:: + Avec ce logger en DEBUG, les claims de l'ID Token (``email``, ``groups``, etc.) sont écrits dans + le fichier de log. Rétablissez le niveau de log une fois l'investigation terminée et traitez la + sortie de log en conséquence. + +Référence +========= + +- :doc:`security-role` - Configuration de la recherche basée sur les rôles +- :doc:`sso-saml` - Configuration SSO avec authentification SAML +- :doc:`sso-entraid` - Configuration SSO dédiée à Microsoft Entra ID (si vous utilisez Entra ID, vous pouvez opter pour cette configuration dédiée plutôt que la configuration OpenID Connect générique) diff --git a/fr/15.10/config/sso-saml.rst b/fr/15.10/config/sso-saml.rst new file mode 100644 index 000000000..bfd5a6618 --- /dev/null +++ b/fr/15.10/config/sso-saml.rst @@ -0,0 +1,655 @@ +============================================ +Configuration SSO avec authentification SAML +============================================ + +Aperçu +====== + +|Fess| prend en charge l'authentification Single Sign-On (SSO) utilisant SAML (Security Assertion Markup Language) 2.0. +En utilisant l'authentification SAML, les informations utilisateur authentifiées par un IdP (Identity Provider) peuvent être intégrées à |Fess|, permettant l'affichage de résultats de recherche basés sur les permissions utilisateur lorsqu'elle est combinée avec la recherche basée sur les rôles. + +.. note:: + La prise en charge de l'authentification SAML provient du plugin ``fess-sso-saml``, qui ne + fait pas partie de la distribution. Installez-le depuis la page **Système > Plugin** de + l'écran d'administration ou avec ``bin/fess-setup install plugin fess-sso-saml``. + Jusque-là, avec ``sso.type=saml``, toute requête vers ``/sso/`` est simplement redirigée + vers la page de connexion. + +Fonctionnement de l'authentification SAML +----------------------------------------- + +Dans l'authentification SAML, |Fess| fonctionne comme un SP (Service Provider) et collabore avec un IdP externe pour l'authentification. + +1. L'utilisateur accède au point d'accès SSO de |Fess| (``/sso/``) +2. |Fess| redirige la demande d'authentification vers l'IdP +3. L'utilisateur s'authentifie auprès de l'IdP +4. L'IdP envoie l'assertion SAML à |Fess| +5. |Fess| valide l'assertion et connecte l'utilisateur + +.. note:: + Seule la connexion initiée par le SP, qui démarre au point d'accès SSO de |Fess| (``/sso/``) comme + décrit ci-dessus, est prise en charge. |Fess| associe chaque réponse SAML à l'identifiant de + l'AuthnRequest qu'il a émise ; une réponse initiée par l'IdP (non sollicitée), par exemple depuis + une vignette |Fess| dans le tableau de bord Okta ou dans le portail « Mes applications » de + Microsoft Entra ID, n'a donc aucune AuthnRequest correspondante et est rejetée. Si vous placez une + vignette côté IdP, faites-la pointer vers le point d'accès ``/sso/`` de |Fess|. + + Notez qu'en 15.7, une connexion initiée par l'IdP fonctionnait incidemment lorsque + ``tomcat.sameSiteCookies=none`` était défini : |Fess| renvoyait à l'IdP la réponse qu'il ne pouvait + pas associer, et l'IdP retournait immédiatement une assertion sollicitée. En 15.10, ce renvoi n'a + plus lieu, si bien que la connexion initiée par l'IdP ne fonctionne pas. + +Pour l'intégration avec la recherche basée sur les rôles, voir :doc:`security-role`. + +Prérequis +========= + +Avant de configurer l'authentification SAML, vérifiez les prérequis suivants : + +- |Fess| 15.10 ou supérieur est installé +- Un IdP (Identity Provider) compatible SAML 2.0 est disponible +- |Fess| est accessible via HTTPS (requis pour les environnements de production) +- Vous avez la permission d'enregistrer |Fess| comme SP côté IdP + +Exemples d'IdP pris en charge : + +- Microsoft Entra ID (Azure AD) +- Okta +- Google Workspace +- Keycloak +- OneLogin +- Autres IdP compatibles SAML 2.0 + +Configuration de base +===================== + +Activation du SSO +----------------- + +Pour activer l'authentification SAML, ajoutez le paramètre suivant dans ``app/WEB-INF/conf/system.properties`` : + +:: + + sso.type=saml + +.. note:: + ``sso.type`` ainsi que les paramètres SAML de base (informations IdP, informations SP, mappage des attributs utilisateur) peuvent également être configurés depuis la page « Système > Général » de l'interface d'administration. + Les paramètres modifiés dans l'interface d'administration sont enregistrés dans ``system.properties`` et persistent après redémarrage. + Cependant, les paramètres de sécurité tels que la signature/le chiffrement ainsi que le certificat SP et la clé privée ne peuvent pas être configurés dans l'interface d'administration ; écrivez-les directement dans ``system.properties``. + +.. note:: + Les paramètres commençant par ``saml.`` sont lus uniquement depuis ``system.properties``. + Les propriétés système de la JVM telles que ``-Dsaml.security....`` ou ``-Dfess.saml.security....`` ne sont pas consultées. + En particulier, ``saml.security.*``, ``saml.strict`` et ``saml.debug`` n'ont pas non plus de champ dans l'interface d'administration : + les écrire directement dans ``system.properties`` est le seul moyen de les définir. + +Configuration du cookie de session +---------------------------------- + +L'IdP renvoie l'assertion à |Fess| via un **POST intersites**. Un cookie ``SameSite=Lax`` n'est pas envoyé sur une telle requête, si bien que la connexion SAML n'aboutit pas avec la valeur par défaut livrée avec |Fess|. + +Remplacez ``tomcat.sameSiteCookies`` par ``none`` dans ``tomcat_config.properties``. Ce fichier se trouve dans ``lib/classes/`` pour le paquet ZIP et dans ``/etc/fess/`` pour les paquets DEB/RPM. + +:: + + tomcat.sameSiteCookies = none + +.. warning:: + Les navigateurs n'acceptent ``none`` que sur un cookie portant également l'attribut ``Secure``. |Fess| doit donc être servi en HTTPS. En HTTP simple, ce réglage rend la connexion à |Fess| impossible. + +.. note:: + La valeur par défaut ``lax`` est prévue pour les méthodes SSO dont le rappel revient sous forme de redirection (GET). La liaison HTTP-POST de SAML n'en fait pas partie, ce changement n'est donc nécessaire qu'avec SAML. |Fess| doit être redémarré après la modification. + +Configuration du SP (Service Provider) +-------------------------------------- + +Pour configurer |Fess| comme SP, spécifiez l'URL de base du SP. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propriété + - Description + - Par défaut + * - ``saml.sp.base.url`` + - URL de base du SP + - ``http://localhost:8080`` + +.. note:: + La valeur par défaut de ``saml.sp.base.url`` est ``http://localhost:8080``. + En dehors des environnements de test, définissez toujours l'URL utilisée pour accéder à |Fess| depuis l'extérieur (HTTPS en production). + +Ce paramètre configure automatiquement les points d'accès suivants : + +- **Entity ID** : ``{saml.sp.base.url}/sso/metadata`` +- **ACS URL** : ``{saml.sp.base.url}/sso/`` +- **SLO URL** : ``{saml.sp.base.url}/sso/logout`` + +Exemple :: + + saml.sp.base.url=https://fess.example.com + +Configuration d'URL individuelle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +En principe, la configuration de ``saml.sp.base.url`` permet de configurer automatiquement chaque URL de point d'accès, mais vous pouvez si nécessaire surcharger les URL individuelles explicitement avec les propriétés suivantes. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propriété + - Description + - Par défaut + * - ``saml.sp.entityid`` + - Entity ID du SP + - ``{saml.sp.base.url}/sso/metadata`` + * - ``saml.sp.assertion_consumer_service.url`` + - URL du service Assertion Consumer + - ``{saml.sp.base.url}/sso/`` + * - ``saml.sp.single_logout_service.url`` + - URL du service Single Logout + - ``{saml.sp.base.url}/sso/logout`` + +Configuration de l'IdP (Identity Provider) +------------------------------------------ + +Configurez les informations obtenues de votre IdP. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propriété + - Description + - Par défaut + * - ``saml.idp.entityid`` + - Entity ID de l'IdP + - (Requis) + * - ``saml.idp.single_sign_on_service.url`` + - URL du service SSO de l'IdP + - (Requis) + * - ``saml.idp.x509cert`` + - Certificat X.509 de signature de l'IdP (encodé en Base64, sans sauts de ligne) + - (Requis) + * - ``saml.idp.single_logout_service.url`` + - URL du service SLO de l'IdP + - (Optionnel) + +.. note:: + Pour ``saml.idp.x509cert``, spécifiez uniquement le contenu encodé en Base64 du certificat sur une seule ligne sans sauts de ligne. + N'incluez pas les lignes ``-----BEGIN CERTIFICATE-----`` et ``-----END CERTIFICATE-----``. + +Récupération des métadonnées SP +------------------------------- + +Après le démarrage de |Fess|, vous pouvez récupérer les métadonnées SP au format XML depuis le point d'accès ``/sso/metadata``. + +:: + + https://fess.example.com/sso/metadata + +Importez ces métadonnées dans votre IdP, ou enregistrez manuellement le SP côté IdP en utilisant le contenu des métadonnées. + +.. note:: + Pour récupérer les métadonnées, vous devez d'abord compléter la configuration SAML de base (``sso.type=saml`` et ``saml.sp.base.url``) et démarrer |Fess|. + +Configuration côté IdP +====================== + +Lors de l'enregistrement de |Fess| comme SP côté IdP, configurez les informations suivantes : + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Paramètre + - Valeur + * - ACS URL / Reply URL + - ``https:///sso/`` + * - Entity ID / Audience URI + - ``https:///sso/metadata`` + * - Name ID Format + - ``urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`` (Recommandé) + +Informations à obtenir de l'IdP +------------------------------- + +Obtenez les informations suivantes depuis l'écran de configuration ou les métadonnées de votre IdP pour la configuration de |Fess| : + +- **Entity ID de l'IdP** : URI identifiant l'IdP +- **URL SSO (HTTP-Redirect)** : URL du point d'accès Single Sign-On +- **Certificat X.509** : Certificat de clé publique utilisé pour la vérification de signature de l'assertion SAML + +Mappage des attributs utilisateur +================================= + +Vous pouvez mapper les attributs utilisateur obtenus des assertions SAML aux groupes et rôles |Fess|. + +Configuration des attributs de groupe +------------------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propriété + - Description + - Par défaut + * - ``saml.attribute.group.name`` + - Nom de l'attribut contenant les informations de groupe + - ``memberOf`` + * - ``saml.default.groups`` + - Groupes par défaut (séparés par des virgules) + - (Aucun) + +Exemple :: + + saml.attribute.group.name=groups + saml.default.groups=user + +.. note:: + |Fess| utilise telles quelles les valeurs de groupe de l'assertion : aucune interrogation de + l'annuaire n'est effectuée et les groupes imbriqués (transitifs) ne sont pas développés. + La présence des groupes parents dépend donc uniquement de la configuration des claims de l'IdP, + contrairement à :doc:`sso-entraid`, où |Fess| résout les groupes parents en utilisant l'API + Microsoft Graph. + +Configuration des attributs de rôle +----------------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propriété + - Description + - Par défaut + * - ``saml.attribute.role.name`` + - Nom de l'attribut contenant les informations de rôle + - (Aucun) + * - ``saml.default.roles`` + - Rôles par défaut (séparés par des virgules) + - (Aucun) + +Exemple :: + + saml.attribute.role.name=roles + saml.default.roles=viewer + +.. note:: + Si les attributs ne peuvent pas être obtenus de l'IdP, les valeurs par défaut seront utilisées. + Lors de l'utilisation de la recherche basée sur les rôles, configurez les groupes ou rôles appropriés. + +.. warning:: + Lorsque ``saml.attribute.role.name`` est défini, les valeurs d'attribut envoyées par l'IdP + deviennent telles quelles des rôles |Fess|. Comme ``authentication.admin.roles`` dans + ``fess_config.properties`` vaut ``admin`` par défaut, tout utilisateur dont l'attribut de rôle + contient ``admin`` obtient les privilèges d'administrateur de |Fess|. Vérifiez qui peut contrôler + l'attribut de rôle côté IdP et, si nécessaire, remplacez ``authentication.admin.roles`` par un + autre nom. + +IdP qui répètent un nom d'attribut +---------------------------------- + +Si l'IdP répartit le même nom d'attribut sur plusieurs éléments ````, |Fess| refuse +l'assertion et la connexion échoue. + +Keycloak envoie par défaut des assertions de cette forme : ses mappeurs de rôles et de groupes +émettent un élément ```` par valeur tant que leur option ``single`` n'est pas activée, et +tout compte Keycloak possède plusieurs rôles de royaume par défaut. + +Deux solutions sont possibles : + +- Regrouper les valeurs dans un seul élément côté IdP (dans Keycloak, activez l'option ``single`` + des mappeurs) +- Accepter les répétitions dans |Fess| et fusionner leurs valeurs + +.. list-table:: + :header-rows: 1 + :widths: 45 40 15 + + * - Propriété + - Description + - Par défaut + * - ``saml.security.allow_duplicated_attribute_name`` + - Autorise le même nom d'attribut sur plusieurs éléments et fusionne leurs valeurs + - ``false`` + +Exemple :: + + saml.security.allow_duplicated_attribute_name=true + +Configuration de sécurité +========================= + +Pour les environnements de production, il est recommandé d'activer les paramètres de sécurité suivants. + +.. note:: + Si des paramètres déconseillés subsistent, un avertissement ``Insecure SAML settings: ...`` est + écrit dans le journal lors du chargement des paramètres SAML. + +Paramètres de signature +----------------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propriété + - Description + - Par défaut + * - ``saml.security.authnrequest_signed`` + - Signer les demandes d'authentification + - ``false`` + * - ``saml.security.want_messages_signed`` + - Exiger les signatures de messages + - ``false`` + * - ``saml.security.want_assertions_signed`` + - Exiger les signatures d'assertions + - ``false`` + * - ``saml.security.logoutrequest_signed`` + - Signer les demandes de déconnexion + - ``false`` + * - ``saml.security.logoutresponse_signed`` + - Signer les réponses de déconnexion + - ``false`` + * - ``saml.security.reject_deprecated_alg`` + - Rejeter les algorithmes de signature obsolètes tels que SHA-1 + - ``false`` + +.. warning:: + Les fonctionnalités de sécurité sont désactivées par défaut. + Pour les environnements de production, il est fortement recommandé de définir au moins ``saml.security.want_assertions_signed=true``. + +.. note:: + Tant que ``saml.security.reject_deprecated_alg`` vaut ``false``, les assertions et messages signés + avec SHA-1 (``rsa-sha1`` et ``dsa-sha1``) sont également acceptés. Ce paramètre n'est pas activé par + défaut, car son activation entraîne le rejet des IdP qui signent encore avec SHA-1. + Vérifiez que votre IdP signe avec SHA-256 ou plus fort, puis définissez + ``saml.security.reject_deprecated_alg=true``. + +.. warning:: + Lorsque la déconnexion unique est configurée (``saml.idp.single_logout_service.url``), définissez + impérativement aussi ``saml.security.want_messages_signed=true``. + Tant que ce paramètre vaut ``false``, une LogoutRequest sans signature est acceptée : une URL + forgée peut donc mettre fin à la session d'un utilisateur authentifié. + L'impact est une déconnexion forcée (déni de service), et non une prise de contrôle du compte. + +Paramètres de chiffrement +------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propriété + - Description + - Par défaut + * - ``saml.security.want_assertions_encrypted`` + - Exiger le chiffrement des assertions + - ``false`` + * - ``saml.security.want_nameid_encrypted`` + - Exiger le chiffrement du NameID + - ``false`` + * - ``saml.security.allowed_key_transport_algorithms`` + - Algorithmes de transport de clé acceptés lors du déchiffrement d'une assertion (URI séparés par des virgules) + - (vide : tous les algorithmes sont acceptés) + +.. note:: + |Fess| valide les réponses chiffrées avec XML Encryption 1.1. Keycloak actuel, par exemple, + utilise ``http://www.w3.org/2009/xmlenc11#rsa-oaep`` et inclut un élément ```` + dans sa réponse ; une telle réponse est acceptée avec la validation de schéma activée. Les + versions antérieures la rejetaient avec + ``Invalid SAML Response. Not match the saml-schema-protocol-2.0.xsd``. Si + ``saml.security.want_xml_validation=false`` avait été défini pour contourner ce problème, + supprimez ce paramètre. + +.. note:: + Définissez ``saml.security.allowed_key_transport_algorithms`` dès qu'une clé privée de SP + est configurée. Tant qu'il n'est pas défini, tous les algorithmes de transport de clé sont + acceptés, y compris l'ancien ``http://www.w3.org/2001/04/xmlenc#rsa-1_5``. Le point de + terminaison du consommateur d'assertions est anonyme et le déchiffrement s'exécute avant la + validation de la réponse : un appelant non authentifié peut donc faire déchiffrer par la clé + privée du SP un texte chiffré de son choix. Dans ce cas, |Fess| signale + ``key_transport_algorithms_not_restricted`` dans la ligne ``Insecure SAML settings`` au + démarrage. Limitez le paramètre à ce que l'IdP utilise réellement:: + + saml.security.allowed_key_transport_algorithms=http://www.w3.org/2009/xmlenc11#rsa-oaep + +Configuration du certificat SP et de la clé privée +--------------------------------------------------- + +Lorsque le SP signe les demandes d'authentification ou les messages de déconnexion (par ex. ``saml.security.authnrequest_signed``), ou demande le chiffrement des assertions ou du NameID (par ex. ``saml.security.want_assertions_encrypted``), vous devez configurer la clé privée et le certificat X.509 du SP. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propriété + - Description + - Par défaut + * - ``saml.sp.x509cert`` + - Certificat X.509 du SP (encodé en Base64, sans sauts de ligne) + - + * - ``saml.sp.privatekey`` + - Clé privée du SP (encodée en Base64, sans sauts de ligne) + - + +.. note:: + Pour ``saml.sp.x509cert`` et ``saml.sp.privatekey``, comme pour ``saml.idp.x509cert``, spécifiez le contenu encodé en Base64 sur une seule ligne sans sauts de ligne (n'incluez pas les lignes ``-----BEGIN ...-----`` et ``-----END ...-----``). + Lorsque vous activez la signature/le chiffrement, enregistrez également le certificat SP côté IdP. Le certificat SP est publié dans les métadonnées SP à l'adresse ``/sso/metadata``. + +Autres paramètres de sécurité +----------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propriété + - Description + - Par défaut + * - ``saml.strict`` + - Mode strict (effectuer une validation stricte) + - ``true`` + * - ``saml.security.want_xml_validation`` + - Valider le schéma XML des messages + - ``true`` + * - ``saml.security.signature_algorithm`` + - Algorithme de signature + - ``http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`` + * - ``saml.security.requested_authncontext`` + - Contexte d'authentification demandé + - ``urn:oasis:names:tc:SAML:2.0:ac:classes:Password`` + * - ``saml.sp.nameidformat`` + - Format du NameID + - ``urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`` + +.. note:: + |Fess| utilise en interne une bibliothèque SAML (java-saml), et les propriétés commençant par ``saml.`` sont mappées aux paramètres correspondants de la bibliothèque (préfixe ``onelogin.saml2.``). + Ainsi, en plus de celles répertoriées ici, vous pouvez spécifier des paramètres détaillés dans ``system.properties`` tels que les liaisons (par ex. ``saml.sp.assertion_consumer_service.binding``), les informations d'organisation (``saml.organization.*``) et les informations de contact (``saml.contacts.*``). + +Expiration de l'AuthnRequest +============================ + +|Fess| envoie une AuthnRequest à l'IdP à chaque accès à ``/sso/`` et enregistre son identifiant dans la session. +La réponse SAML renvoyée par l'IdP est validée par rapport à l'identifiant enregistré. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propriété + - Description + - Par défaut + * - ``saml.request.id.ttl`` + - Durée pendant laquelle l'identifiant d'une AuthnRequest restée sans réponse est conservé (secondes) + - ``3600`` + +L'identifiant enregistré est écarté une fois ce délai écoulé. +S'il expire (par exemple parce que la page de connexion de l'IdP est restée ouverte), l'assertion renvoyée ne peut pas être associée et la connexion échoue une seule fois. + +Exemples de configuration +========================= + +Configuration minimale (pour les tests) +--------------------------------------- + +Voici un exemple de configuration minimale pour la vérification dans un environnement de test. + +:: + + # Activer SSO + sso.type=saml + + # Configuration SP + saml.sp.base.url=https://fess.example.com + + # Configuration IdP (définir les valeurs obtenues de la console d'administration IdP) + saml.idp.entityid=https://idp.example.com/saml/metadata + saml.idp.single_sign_on_service.url=https://idp.example.com/saml/sso + saml.idp.x509cert=MIIDpDCCAoygAwIBAgI...(certificat encodé en Base64) + + # Groupes par défaut + saml.default.groups=user + +Configuration recommandée (pour la production) +---------------------------------------------- + +Voici un exemple de configuration recommandée pour les environnements de production. + +:: + + # Activer SSO + sso.type=saml + + # Configuration SP + saml.sp.base.url=https://fess.example.com + + # Configuration IdP + saml.idp.entityid=https://idp.example.com/saml/metadata + saml.idp.single_sign_on_service.url=https://idp.example.com/saml/sso + saml.idp.single_logout_service.url=https://idp.example.com/saml/logout + saml.idp.x509cert=MIIDpDCCAoygAwIBAgI...(certificat encodé en Base64) + + # Mappage des attributs utilisateur + saml.attribute.group.name=groups + saml.attribute.role.name=roles + saml.default.groups=user + + # Paramètres de sécurité (recommandés pour la production) + saml.security.want_assertions_signed=true + saml.security.want_messages_signed=true + + # À activer après avoir vérifié que l'IdP signe avec SHA-256 ou plus fort + saml.security.reject_deprecated_alg=true + +Dépannage +========= + +Problèmes courants et solutions +------------------------------- + +Impossible de retourner à Fess après l'authentification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Vérifiez que l'URL ACS est correctement configurée côté IdP +- Assurez-vous que la valeur de ``saml.sp.base.url`` correspond à la configuration de l'IdP +- L'assertion SAML arrive sous forme de POST intersite depuis l'IdP. Lorsque + ``tomcat.sameSiteCookies`` dans ``tomcat_config.properties`` vaut ``lax`` (la valeur par défaut), + le navigateur n'envoie pas le cookie de session avec cette requête et la connexion échoue une seule + fois. Dans ce cas, définissez ``tomcat.sameSiteCookies = none`` (``SameSite=None`` nécessite HTTPS) +- Si la connexion a pris trop de temps chez l'IdP, l'identifiant d'AuthnRequest n'est plus présent + lorsque l'assertion revient : la connexion échoue une seule fois et doit être recommencée +- |Fess| ne définit pas ``session-timeout`` dans ``app/WEB-INF/web.xml`` ; la valeur par défaut du + conteneur de servlets, 30 minutes, s'applique donc, et elle est plus courte que les 3600 secondes + de ``saml.request.id.ttl``, si bien que la session est écartée en premier. Augmenter uniquement + ``saml.request.id.ttl`` ne laisse pas plus de temps aux utilisateurs pour terminer la connexion + chez l'IdP : allongez aussi le délai d'expiration de session + +La validation de Destination échoue derrière un proxy inverse +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Lorsque |Fess| s'exécute derrière un proxy inverse ou un répartiteur de charge qui termine TLS, la +validation de l'assertion peut échouer même si ``saml.sp.base.url`` est correctement défini. + +L'attribut ``Destination`` de l'assertion est comparé à l'URL de la requête telle qu'elle parvient +à |Fess| : derrière un proxy qui termine TLS, il s'agit d'une URL interne en ``http://`` et non de +l'URL externe à laquelle l'IdP a envoyé l'assertion. ``saml.sp.base.url`` n'intervient pas dans +cette comparaison ; le définir seul ne résout donc pas le problème. + +Définissez ``saml.debug=true`` pour que la raison soit écrite dans le journal : + +:: + + The response was received at http://... instead of https://fess.example.com/sso/ + +Alignez les paramètres du connecteur dans ``tomcat_config.properties`` sur le schéma et le port +visibles depuis l'extérieur. Ces paramètres sont livrés commentés : + +:: + + tomcat.secure=true + tomcat.scheme=https + tomcat.proxyPort=443 + +Configurez également le proxy inverse pour qu'il transmette l'en-tête ``Host`` d'origine à |Fess|, car +la partie nom d'hôte de l'URL de requête est construite à partir de cet en-tête. |Fess| doit être +redémarré après modification de ``tomcat_config.properties``. + +La même validation s'applique aux messages de déconnexion unique ; configurez-la également si vous +utilisez le SLO. + +Erreur de vérification de signature +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Vérifiez que le certificat IdP est correctement configuré +- Assurez-vous que le certificat n'a pas expiré +- Le certificat doit être spécifié uniquement comme contenu encodé en Base64, sans sauts de ligne + +La connexion échoue en raison d'un nom d'attribut répété +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Si le journal contient un avertissement commençant par ``The IdP repeated an attribute name in the + SAML assertion``, l'IdP répartit le même nom d'attribut sur plusieurs éléments ```` +- L'assertion elle-même a passé la validation : le certificat et le décalage d'horloge ne sont pas en cause +- Regroupez les attributs côté IdP ou définissez ``saml.security.allow_duplicated_attribute_name=true`` + +Groupes/rôles utilisateur non reflétés +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Vérifiez que les attributs sont correctement configurés côté IdP +- Assurez-vous que la valeur de ``saml.attribute.group.name`` correspond au nom d'attribut envoyé par l'IdP +- Avec Microsoft Entra ID, le claim de groupes contient les ``ObjectId`` (GUID) des groupes, sauf + si un autre attribut source est sélectionné ; les valeurs ne correspondent donc pas aux noms de + groupe +- Microsoft Entra ID omet entièrement le claim de groupes lorsque l'utilisateur appartient à plus + de 150 groupes (les groupes imbriqués comptent dans cette limite) ; |Fess| se rabat alors sur + ``saml.default.groups`` +- Activez le mode débogage pour inspecter le contenu de l'assertion SAML + +Paramètres de débogage +---------------------- + +Pour investiguer les problèmes, vous pouvez activer le mode débogage avec le paramètre suivant : + +:: + + saml.debug=true + +La configuration ``saml.debug=true`` enregistre dans le journal la raison détaillée lorsque l'authentification SAML échoue. + +Vous pouvez également afficher des journaux détaillés liés à SAML en ajoutant le logger suivant dans ``app/WEB-INF/classes/log4j2.xml`` : + +:: + + + +Référence +========= + +- :doc:`security-role` - Configuration de la recherche basée sur les rôles +- :doc:`sso-oidc` - À propos de la configuration SSO avec OpenID Connect +- :doc:`sso-entraid` - À propos de la configuration SSO dédiée à Microsoft Entra ID diff --git a/fr/15.10/config/sso-spnego.rst b/fr/15.10/config/sso-spnego.rst new file mode 100644 index 000000000..a2b4f8cb1 --- /dev/null +++ b/fr/15.10/config/sso-spnego.rst @@ -0,0 +1,498 @@ +=================================================== +Configuration SSO avec Auth Intégrée Windows +=================================================== + +Aperçu +====== + +|Fess| prend en charge l'authentification Single Sign-On (SSO) en utilisant l'authentification intégrée Windows (SPNEGO/Kerberos). +En utilisant l'authentification intégrée Windows, les utilisateurs connectés à un ordinateur membre d'un domaine Windows peuvent accéder à |Fess| sans opérations de connexion supplémentaires. + +.. note:: + La prise en charge de l'authentification intégrée Windows provient du plugin + ``fess-sso-spnego``, qui ne fait pas partie de la distribution. Installez-le depuis la page + **Système > Plugin** de l'écran d'administration ou avec + ``bin/fess-setup install plugin fess-sso-spnego``. + Jusque-là, avec ``sso.type=spnego``, toute requête vers ``/sso/`` est simplement redirigée + vers la page de connexion. + +Fonctionnement de l'authentification intégrée Windows +----------------------------------------------------- + +Dans l'authentification intégrée Windows, |Fess| utilise le protocole SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) pour l'authentification Kerberos. + +1. L'utilisateur se connecte au domaine Windows +2. L'utilisateur accède à |Fess| +3. |Fess| envoie un défi SPNEGO +4. Le navigateur obtient un ticket Kerberos et l'envoie au serveur +5. |Fess| valide le ticket et récupère le nom d'utilisateur +6. Les informations de groupe de l'utilisateur sont récupérées via LDAP +7. L'utilisateur est connecté et les informations de groupe sont appliquées à la recherche basée sur les rôles + +Pour l'intégration avec la recherche basée sur les rôles, consultez :doc:`security-role`. + +Prérequis +========= + +Avant de configurer l'authentification intégrée Windows, vérifiez les prérequis suivants : + +- |Fess| 15.10 ou supérieur est installé +- Un serveur Active Directory (AD) est disponible +- Le serveur |Fess| est accessible depuis le domaine AD +- Vous avez la permission de configurer les noms de principal de service (SPN) dans AD +- Un compte pour récupérer les informations utilisateur via LDAP est disponible + +Configuration côté Active Directory +=================================== + +Enregistrement du nom de principal de service (SPN) +--------------------------------------------------- + +Vous devez enregistrer un SPN pour |Fess| dans Active Directory. +Ouvrez une invite de commandes sur un ordinateur Windows membre du domaine AD et exécutez la commande ``setspn``. + +:: + + setspn -S HTTP/ + +Exemple : + +:: + + setspn -S HTTP/fess-server.example.local svc_fess + +Pour vérifier l'enregistrement : + +:: + + setspn -L + +.. note:: + Après l'enregistrement du SPN, si vous avez exécuté la commande sur le serveur Fess, déconnectez-vous de Windows et reconnectez-vous. + +Configuration de base +===================== + +Activation du SSO +----------------- + +Pour activer l'authentification intégrée Windows, ajoutez le paramètre suivant dans ``app/WEB-INF/conf/system.properties`` : + +:: + + sso.type=spnego + +Fichier de configuration Kerberos +--------------------------------- + +Créez ``app/WEB-INF/classes/krb5.conf`` avec la configuration Kerberos. + +:: + + [libdefaults] + default_realm = EXAMPLE.LOCAL + default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + + [realms] + EXAMPLE.LOCAL = { + kdc = AD-SERVER.EXAMPLE.LOCAL + default_domain = EXAMPLE.LOCAL + } + + [domain_realm] + example.local = EXAMPLE.LOCAL + .example.local = EXAMPLE.LOCAL + +.. note:: + Remplacez ``EXAMPLE.LOCAL`` par votre nom de domaine AD (en majuscules) et ``AD-SERVER.EXAMPLE.LOCAL`` par le nom d'hôte de votre serveur AD. + +.. warning:: + Un ticket de service chiffré avec un type absent de ``permitted_enctypes`` est rejeté par + l'accepteur Kerberos avec ``encryption type not in permitted_enctypes list``. + Active Directory émet normalement des tickets de service AES256 : AES256 doit donc figurer dans la liste. + +.. note:: + RC4 (``rc4-hmac``), 3DES et DES sont désactivés par défaut à partir de Java 17 ; les mentionner n'a + donc aucun effet et l'exemple ci-dessus ne spécifie que AES. + ``aes256-cts-hmac-sha384-192`` et ``aes128-cts-hmac-sha256-128`` sont les types AES-SHA2 (RFC 8009) + pris en charge par Windows Server 2025. + Un compte de service ne disposant que d'une clé RC4 ne peut pas servir à l'authentification Kerberos : + réinitialisez son mot de passe afin que des clés AES soient générées. + +Fichier de configuration de connexion +------------------------------------- + +Créez ``app/WEB-INF/classes/auth_login.conf`` avec la configuration de connexion JAAS. + +:: + + spnego-client { + com.sun.security.auth.module.Krb5LoginModule required; + }; + + spnego-server { + com.sun.security.auth.module.Krb5LoginModule required + storeKey=true + isInitiator=false; + }; + +.. note:: + Les noms de fichier par défaut de ``krb5.conf`` et ``auth_login.conf`` sont définis respectivement par ``spnego.krb5.conf`` et ``spnego.login.conf``, mais ces fichiers doivent impérativement être créés. + SPNEGO est initialisé lors de la première connexion : |Fess| démarre donc même si ces fichiers sont absents, mais la connexion SSO échoue. + +Paramètres requis +----------------- + +Ajoutez les paramètres suivants à ``app/WEB-INF/conf/system.properties``. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propriété + - Description + - Valeur par défaut + * - ``spnego.preauth.username`` + - Nom d'utilisateur de connexion AD + - (Requis sauf si un keytab est utilisé) + * - ``spnego.preauth.password`` + - Mot de passe de connexion AD + - (Requis sauf si un keytab est utilisé) + * - ``spnego.krb5.conf`` + - Chemin du fichier de configuration Kerberos + - ``krb5.conf`` + * - ``spnego.login.conf`` + - Chemin du fichier de configuration de connexion + - ``auth_login.conf`` + +.. note:: + Si ``spnego.preauth.username`` et ``spnego.preauth.password`` sont tous deux vides, le module de + connexion serveur utilise un keytab. + Si vous ne souhaitez pas stocker le mot de passe du compte de service AD dans un fichier de + configuration |Fess|, créez un keytab et configurez ``spnego-server`` dans ``auth_login.conf`` + comme suit. + + :: + + spnego-server { + com.sun.security.auth.module.Krb5LoginModule required + useKeyTab=true + keyTab="/var/lib/fess/fess.keytab" + principal="HTTP/fess-server.example.local@EXAMPLE.LOCAL" + storeKey=true + isInitiator=false; + }; + +Paramètres optionnels +--------------------- + +Les paramètres suivants peuvent être ajoutés si nécessaire. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - Propriété + - Description + - Valeur par défaut + * - ``spnego.login.client.module`` + - Nom du module client + - ``spnego-client`` + * - ``spnego.login.server.module`` + - Nom du module serveur + - ``spnego-server`` + * - ``spnego.allow.basic`` + - Autoriser l'authentification Basic + - ``true`` + * - ``spnego.allow.unsecure.basic`` + - Autoriser l'authentification Basic non sécurisée + - ``false`` + * - ``spnego.prompt.ntlm`` + - Revenir à l'authentification Basic lors de la réception d'un jeton NTLM + - ``true`` + * - ``spnego.allow.localhost`` + - Autoriser l'accès depuis localhost + - ``false`` + * - ``spnego.allow.delegation`` + - Autoriser la délégation + - ``false`` + * - ``spnego.allowed.realms`` + - Domaines Kerberos acceptés en plus du domaine du serveur (séparés par des virgules) + - (Aucun) + * - ``spnego.logger.level`` + - Niveau de log interne de la bibliothèque SPNEGO (``1`` =FINEST, ``2`` =FINER, ``3`` =FINE, ``4`` =CONFIG, ``6`` =WARNING, ``7`` =SEVERE ; toute autre valeur, y compris ``0`` et ``5``, est traitée comme INFO) + - (Automatique) + +.. warning:: + ``spnego.allow.unsecure.basic=true`` peut envoyer des identifiants encodés en Base64 sur des connexions non chiffrées. + Pour les environnements de production, il est fortement recommandé de définir cette valeur sur ``false`` et d'utiliser HTTPS. + +.. note:: + Avec ``spnego.allow.unsecure.basic=false`` (valeur par défaut), l'authentification Basic n'est + proposée que pour les requêtes dont ``HttpServletRequest#isSecure()`` renvoie ``true``. + Lorsque TLS est terminé par un proxy inverse et que la requête est transmise à |Fess| en HTTP, + cette valeur est ``false`` : un client qui ne peut pas obtenir de ticket Kerberos et bascule + vers NTLM ne peut donc pas se connecter. Définissez ``tomcat.secure=true`` dans + ``tomcat_config.properties`` pour indiquer à |Fess| que la requête est arrivée en HTTPS. + Ce fichier se trouve dans ``lib/classes/`` pour la distribution ZIP et dans ``/etc/fess/`` pour + les paquets DEB/RPM ; |Fess| doit être redémarré après sa modification. + +.. warning:: + Dans |Fess| 15.10, une connexion est refusée par défaut lorsque le domaine Kerberos du principal + client diffère de celui du serveur. Si des utilisateurs se connectent depuis un domaine enfant + d'une arborescence de domaines AD ou depuis une forêt approuvée, indiquez ces domaines dans + ``spnego.allowed.realms``, séparés par des virgules. Sinon, les utilisateurs qui pouvaient se + connecter jusqu'à la version 15.7 sont refusés avec ``Kerberos realm is not allowed``. + +.. warning:: + |Fess| identifie un utilisateur par la partie du principal située avant ``@`` ; le domaine + Kerberos ne fait donc pas partie du nom d'utilisateur. Lorsque vous indiquez des domaines + supplémentaires dans ``spnego.allowed.realms``, les utilisateurs qui partagent un nom de compte + entre domaines — par exemple ``alice@CORP.EXAMPLE.COM`` et ``alice@PARTNER.EXAMPLE.COM`` — + deviennent le même utilisateur |Fess| et partagent ses groupes, ses rôles et ses autorisations + sur les documents. N'ajoutez un domaine que si le nom de compte identifie exactement une + personne dans tous les domaines que vous indiquez. + +.. note:: + La liste d'autorisation s'applique également au repli sur l'authentification Basic. Si un + utilisateur saisit un nom de la forme ``user@REALM``, ce domaine est comparé à + ``spnego.allowed.realms`` et la connexion est refusée lorsqu'il n'est pas autorisé. Un simple + nom de compte, ou la forme ``DOMAIN\user``, n'indique aucun domaine et est authentifié dans le + domaine par défaut de ``krb5.conf``. Comme une connexion Basic est authentifiée directement + auprès du domaine saisi par l'utilisateur, gardez la liste d'autorisation aussi réduite que + possible et envisagez de définir ``spnego.allow.basic`` à ``false`` si vous vous en servez comme + limite de sécurité. + +.. note:: + Lorsque ``spnego.prompt.ntlm=true`` (valeur par défaut), ``spnego.allow.basic`` doit également être ``true``. + Si vous définissez ``spnego.allow.basic=false``, vous devez également définir ``spnego.prompt.ntlm=false``. + Si cette condition n'est pas respectée, une erreur se produit lors de l'initialisation de SPNEGO. + +.. note:: + ``spnego.logger.level`` contrôle le niveau de log du logger interne de la bibliothèque SPNEGO (le logger ``java.util.logging`` nommé ``Spnego``). + Si ce paramètre n'est pas défini, le niveau est déterminé automatiquement en fonction du niveau de log de |Fess|. + +Configuration LDAP +================== + +La configuration LDAP est requise pour récupérer les informations de groupe des utilisateurs authentifiés via l'authentification intégrée Windows. +Configurez les paramètres LDAP dans le panneau d'administration de |Fess| sous "Système" -> "Général". + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Élément + - Exemple + * - URL LDAP + - ``ldap://AD-SERVER.example.local:389`` + * - Base DN + - ``dc=example,dc=local`` + * - Bind DN + - ``svc_fess@example.local`` + * - Mot de passe + - Mot de passe de l'utilisateur d'accès AD + * - User DN + - ``%s@example.local`` + * - Filtre de compte + - ``(&(objectClass=user)(sAMAccountName=%s))`` + * - Attribut memberOf + - ``memberOf`` + +.. note:: + |Fess| ne lit l'attribut ``memberOf`` de l'utilisateur que sur un seul niveau : les groupes + imbriqués (un groupe membre d'un autre groupe) ne sont donc pas développés par défaut. Pour + prendre en compte les groupes imbriqués d'AD, définissez le filtre de groupe + (``ldap.group.filter``) sur ``(member:1.2.840.113556.1.4.1941:=%s)`` dans « Système » → + « Général » de l'interface d'administration. Ce développement s'exécute de façon asynchrone + après la connexion : l'entrée de connexion du journal d'audit ne contient donc que les groupes + résolus avant son achèvement. + +Paramètres du navigateur +======================== + +Les paramètres du navigateur client sont nécessaires pour utiliser l'authentification intégrée Windows. + +Internet Explorer / Microsoft Edge +---------------------------------- + +1. Ouvrir les Options Internet +2. Sélectionner l'onglet "Sécurité" +3. Cliquer sur "Sites" pour la zone "Intranet local" +4. Cliquer sur "Avancé" et ajouter l'URL de Fess +5. Cliquer sur "Personnaliser le niveau" pour la zone "Intranet local" +6. Sous "Authentification utilisateur" -> "Connexion", sélectionner "Connexion automatique uniquement dans la zone Intranet" +7. Dans l'onglet "Avancé", cocher "Activer l'authentification Windows intégrée" + +Google Chrome +------------- + +Chrome utilise généralement les paramètres des Options Internet de Windows. +Si une configuration supplémentaire est nécessaire, définissez ``AuthServerAllowlist`` via la stratégie de groupe ou le registre. + +Mozilla Firefox +--------------- + +1. Entrer ``about:config`` dans la barre d'adresse +2. Rechercher ``network.negotiate-auth.trusted-uris`` +3. Définir l'URL ou le domaine du serveur Fess (ex : ``https://fess-server.example.local``) + +Exemples de configuration +========================= + +Configuration minimale (pour les tests) +--------------------------------------- + +Voici un exemple de configuration minimale pour un environnement de test. + +``app/WEB-INF/conf/system.properties`` : + +:: + + # Activer SSO + sso.type=spnego + + # Paramètres SPNEGO + spnego.preauth.username=svc_fess + spnego.preauth.password=your-password + +``app/WEB-INF/classes/krb5.conf`` : + +:: + + [libdefaults] + default_realm = EXAMPLE.LOCAL + default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + + [realms] + EXAMPLE.LOCAL = { + kdc = AD-SERVER.EXAMPLE.LOCAL + default_domain = EXAMPLE.LOCAL + } + + [domain_realm] + example.local = EXAMPLE.LOCAL + .example.local = EXAMPLE.LOCAL + +``app/WEB-INF/classes/auth_login.conf`` : + +:: + + spnego-client { + com.sun.security.auth.module.Krb5LoginModule required; + }; + + spnego-server { + com.sun.security.auth.module.Krb5LoginModule required + storeKey=true + isInitiator=false; + }; + +Configuration recommandée (pour la production) +---------------------------------------------- + +Voici un exemple de configuration recommandée pour les environnements de production. + +``app/WEB-INF/conf/system.properties`` : + +:: + + # Activer SSO + sso.type=spnego + + # Paramètres SPNEGO + spnego.preauth.username=svc_fess + spnego.preauth.password=your-secure-password + spnego.krb5.conf=krb5.conf + spnego.login.conf=auth_login.conf + + # Paramètres de sécurité (production) + spnego.allow.basic=false + spnego.allow.unsecure.basic=false + spnego.prompt.ntlm=false + spnego.allow.localhost=false + +.. note:: + Si vous définissez ``spnego.allow.basic=false``, vous devez également définir ``spnego.prompt.ntlm=false``. + La valeur par défaut de ``spnego.prompt.ntlm`` est ``true`` ; omettre ce paramètre provoque une erreur lors de l'initialisation. + +Dépannage +========= + +Problèmes courants et solutions +------------------------------- + +La boîte de dialogue d'authentification apparaît +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Vérifiez que le serveur Fess est ajouté à la zone Intranet local dans les paramètres du navigateur +- Vérifiez que "Activer l'authentification Windows intégrée" est activé +- Vérifiez que le SPN est correctement enregistré (``setspn -L ``) + +Des erreurs d'authentification se produisent +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Vérifiez que le nom de domaine (majuscules) et le nom du serveur AD dans ``krb5.conf`` sont corrects +- Vérifiez que ``spnego.preauth.username`` et ``spnego.preauth.password`` sont corrects +- Vérifiez la connectivité réseau vers le serveur AD + +Impossible de récupérer les informations de groupe +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Vérifiez que les paramètres LDAP sont corrects +- Vérifiez que le Bind DN et le mot de passe sont corrects +- Vérifiez que l'utilisateur appartient à des groupes dans AD + +La connexion renvoie HTTP 400 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Pour un utilisateur appartenant à de nombreux groupes, le ticket Kerberos (PAC) devient volumineux et +l'en-tête ``Authorization`` peut dépasser la limite par défaut de Tomcat (8 Ko), ce qui donne un 400. +La requête n'atteint jamais |Fess| : rien n'est écrit dans le journal. +Augmentez la limite dans ``tomcat_config.properties``. + +:: + + tomcat.maxHttpHeaderSize=65536 + +L'authentification échoue après le changement du mot de passe du compte de service +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Les informations d'identification du serveur sont obtenues une seule fois lors de la première +connexion, puis mises en cache pour toute la durée de vie du processus. +Redémarrez |Fess| après avoir changé le mot de passe du compte de service dans AD ou remplacé le +keytab. Un redémarrage est également requis après toute modification d'un paramètre ``spnego.*``. + +Paramètres de débogage +---------------------- + +Pour investiguer les problèmes, vous pouvez afficher des logs détaillés liés à SPNEGO. + +Pour afficher les logs détaillés internes de la bibliothèque SPNEGO, ajoutez ce qui suit à ``app/WEB-INF/conf/system.properties``. +``spnego.logger.level=1`` produit les logs les plus détaillés (FINEST). + +:: + + spnego.logger.level=1 + +Pour afficher les logs détaillés du traitement SPNEGO côté |Fess| (package ``org.codelibs.fess.sso.spnego``), ajoutez le logger suivant à ``app/WEB-INF/classes/log4j2.xml`` : + +:: + + + +.. note:: + Les logs de la bibliothèque SPNEGO elle-même sont émis via ``java.util.logging`` et se contrôlent avec ``spnego.logger.level``, non via ``log4j2.xml``. + Les logs du traitement d'intégration côté |Fess| se contrôlent via le logger ``log4j2.xml``. + +Référence +========= + +- :doc:`security-role` - Configuration de la recherche basée sur les rôles +- :doc:`sso-saml` - Configuration SSO avec authentification SAML +- :doc:`sso-oidc` - Configuration SSO avec authentification OpenID Connect +- :doc:`sso-entraid` - Configuration SSO avec Microsoft Entra ID diff --git a/fr/15.10/dev/datastore-plugin.rst b/fr/15.10/dev/datastore-plugin.rst new file mode 100644 index 000000000..2ab633fb9 --- /dev/null +++ b/fr/15.10/dev/datastore-plugin.rst @@ -0,0 +1,549 @@ +================================== +Développement de plugins DataStore +================================== + +Aperçu +====== + +En développant un plugin DataStore, vous pouvez ajouter à |Fess| la capacité +de récupérer du contenu depuis de nouvelles sources de données. Un DataStore +récupère des enregistrements depuis un système externe (base de données, API, +fichiers, etc.), les convertit en champs d'index selon le script de mapping +défini dans l'écran d'administration, puis les enregistre dans l'index de +|Fess|. + +Les connecteurs publics tels que CSV, JSON, base de données, Git et divers +services cloud (``fess-ds-*``) sont tous implémentés selon ce mécanisme. +`fess-ds-example `__ est publié +comme modèle d'implémentation ; pour créer un nouveau connecteur, il est donc +plus simple de partir en copiant ce projet. + +Structure de base +================= + +Un plugin DataStore se compose des trois éléments suivants. + +- créer une classe héritant de ``AbstractDataStore`` +- implémenter les deux méthodes ``getName()`` et ``storeData()`` +- l'enregistrer comme composant dans ``fess_ds++.xml`` + +Implémentation minimale +------------------------ + +.. code-block:: java + + package org.codelibs.fess.ds.example; + + import java.util.Map; + + import org.codelibs.fess.ds.AbstractDataStore; + import org.codelibs.fess.ds.callback.IndexUpdateCallback; + import org.codelibs.fess.entity.DataStoreParams; + import org.codelibs.fess.opensearch.config.exentity.DataConfig; + + public class ExampleDataStore extends AbstractDataStore { + + @Override + protected String getName() { + // Utilisé comme nom de handler. Il est d'usage de retourner le nom simple de la classe + return this.getClass().getSimpleName(); + } + + @Override + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { + + // Implémenter ici la récupération et le traitement des données + } + } + +.. note:: + + ``getName()`` et ``storeData()`` sont tous deux des méthodes abstraites + ``protected``. Notez que le package de ``DataConfig`` dans |Fess| 15.x est + ``org.codelibs.fess.opensearch.config.exentity`` (l'ancien + ``org.codelibs.fess.es.config.exentity`` a été supprimé). + +Enregistrement du composant +---------------------------- + +Pour que |Fess| reconnaisse le DataStore créé, enregistrez le composant dans +``src/main/resources/fess_ds++.xml``. + +.. code-block:: xml + + + + + + + + + +Grâce à ````, la méthode ``register()`` fournie +par ``AbstractDataStore`` est appelée automatiquement après la création du +composant, ce qui enregistre celui-ci auprès de ``DataStoreFactory``. Le nom +enregistré à ce moment est la valeur de retour de ``getName()`` (``ExampleDataStore`` +dans l'exemple ci-dessus), qui devient le « nom de handler » sélectionnable dans +la configuration du DataStore de l'écran d'administration. + +AbstractDataStore +================= + +Méthodes principales +--------------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 20 45 + + * - Méthode + - Catégorie + - Description + * - ``getName()`` + - Implémentation (obligatoire) + - Méthode abstraite retournant le nom de handler du DataStore. Il est d'usage de retourner ``getClass().getSimpleName()`` + * - ``storeData()`` + - Implémentation (obligatoire) + - Méthode abstraite effectuant la récupération, la conversion et l'enregistrement des données dans l'index + * - ``register()`` + - Héritée (généralement inchangée) + - Appelée automatiquement depuis le ``postConstruct`` de ``fess_ds++.xml`` ; enregistre le composant auprès de ``DataStoreFactory`` + * - ``store()`` + - Héritée (appelée par le framework) + - Point d'entrée appelé par le framework. Prépare notamment ``defaultDataMap`` puis appelle ``storeData()`` + * - ``convertValue()`` + - Héritée (méthode d'aide) + - Évalue la valeur (le gabarit) de ``scriptMap`` à l'aide du moteur de script + * - ``getScriptType()`` + - Héritée (méthode d'aide) + - Récupère le paramètre ``script_type`` (Groovy par défaut) + * - ``getReadInterval()`` + - Héritée (méthode d'aide) + - Récupère le paramètre ``readInterval`` (en millisecondes) + * - ``sleep()`` + - Héritée (méthode d'aide) + - Met en pause l'exécution pendant le nombre de millisecondes indiqué (utilisé pour patienter entre les enregistrements) + +Paramètres de storeData +------------------------- + +Paramètres passés à la méthode ``storeData()`` : + +.. list-table:: + :header-rows: 1 + :widths: 25 35 40 + + * - Paramètre + - Type + - Description + * - ``dataConfig`` + - ``DataConfig`` + - Configuration du DataStore (ID, nom de handler, paramètres, scripts, etc.) + * - ``callback`` + - ``IndexUpdateCallback`` + - Callback permettant d'enregistrer le document généré dans l'index + * - ``paramMap`` + - ``DataStoreParams`` + - Valeurs configurées dans le champ « Paramètres » de l'écran d'administration. Accessible via ``getAsString(key)`` / ``getAsString(key, default)`` / ``get(key)`` / ``asMap()`` / ``containsKey(key)`` + * - ``scriptMap`` + - ``Map`` + - Configuration du champ « Script » de l'écran d'administration. La clé est le nom du champ d'index, la valeur est le gabarit de script à évaluer + * - ``defaultDataMap`` + - ``Map`` + - Valeurs de champs par défaut de chaque document (ID de configuration, boost, rôle, mimetype, hôte virtuel, etc.). Préparé par le framework + +.. warning:: + + Le type de ``paramMap`` n'est pas ``Map`` mais + ``DataStoreParams``. ``DataStoreParams`` n'implémentant pas ``Map``, + utilisez ``getAsString()``, qui retourne une chaîne, plutôt que ``get()`` + pour récupérer les valeurs. + +Flux de traitement des données +-------------------------------- + +L'implémentation de ``storeData()`` traite les données selon le flux suivant. + +#. Récupérer les enregistrements source depuis le système externe. +#. Construire ``resultMap`` en fusionnant les champs de l'enregistrement source + dans ``paramMap.asMap()`` (le script est évalué sur ce ``resultMap``). +#. Évaluer chaque entrée de ``scriptMap`` avec ``convertValue(scriptType, template, resultMap)`` + et stocker le résultat dans ``dataMap``. Il est important que le mapping ne + soit pas codé en dur dans le code, mais défini par l'administrateur dans le + champ « Script ». +#. Appeler ``callback.store(paramMap, dataMap)`` pour enregistrer le document dans l'index. + +Exemple d'implémentation +======================== + +DataStore simple +----------------- + +Exemple récupérant des enregistrements depuis une API externe et les +enregistrant dans l'index. + +.. code-block:: java + + @Override + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { + + // Récupération des paramètres (utiliser getAsString avec DataStoreParams) + final String apiUrl = paramMap.getAsString("api.url"); + final String apiKey = paramMap.getAsString("api.key"); + + // Type d'évaluation du script (Groovy par défaut) + final String scriptType = getScriptType(paramMap); + // Délai d'attente entre les enregistrements (en millisecondes) + final long readInterval = getReadInterval(paramMap); + + try { + // Récupération des données depuis le système externe + final List> records = fetchRecords(apiUrl, apiKey); + + for (final Map record : records) { + // Initialise dataMap en copiant les champs par défaut + final Map dataMap = new HashMap<>(defaultDataMap); + + // Construit resultMap en fusionnant les paramètres et l'enregistrement source + // (le script est évalué sur ce resultMap) + final Map resultMap = new LinkedHashMap<>(paramMap.asMap()); + resultMap.putAll(record); + + // Évalue chaque entrée de scriptMap pour générer les champs d'index + for (final Map.Entry entry : scriptMap.entrySet()) { + final Object value = convertValue(scriptType, entry.getValue(), resultMap); + if (value != null) { + dataMap.put(entry.getKey(), value); + } + } + + // Enregistrement dans l'index + callback.store(paramMap, dataMap); + + if (readInterval > 0) { + sleep(readInterval); + } + } + } catch (final Exception e) { + throw new DataStoreException("Failed to crawl data from " + apiUrl, e); + } + } + +``fetchRecords()`` est une méthode propre au connecteur qui récupère la liste +des enregistrements depuis le système externe. Les noms de champs de chaque +enregistrement récupéré (``Map``) sont les noms auxquels les +scripts de ``scriptMap`` peuvent faire référence. ``DataStoreException`` est +une classe du package ``org.codelibs.fess.exception``. + +Prise en charge de la pagination +----------------------------------- + +Pour traiter de grands volumes de données, il convient de récupérer les +enregistrements page par page. Il est recommandé d'extraire le traitement par +enregistrement (construction de ``resultMap``, évaluation de ``scriptMap``, +appel de ``callback.store()``) dans une méthode telle que ``processRecord()``, +ce qui permet de séparer cette logique de celle de récupération. + +.. code-block:: java + + int offset = 0; + final int pageSize = 100; + + while (true) { + final List> records = fetchRecords(apiUrl, apiKey, offset, pageSize); + + if (records.isEmpty()) { + break; + } + + for (final Map record : records) { + processRecord(record, callback, paramMap, scriptMap, defaultDataMap); + } + + offset += pageSize; + } + +Implémentation de l'authentification +===================================== + +L'authentification auprès du système externe est implémentée côté connecteur. +Voici un exemple d'implémentation utilisant une bibliothèque cliente HTTP +courante ; il ne s'agit pas d'une API fournie par |Fess|. La bibliothèque +utilisée doit être incluse comme dépendance du plugin. + +OAuth 2.0 +--------- + +.. code-block:: java + + protected String getAccessToken(final String clientId, final String clientSecret, final String refreshToken) { + // Exemple de récupération d'un jeton d'accès à l'aide d'un jeton de rafraîchissement + final OkHttpClient client = new OkHttpClient(); + + final RequestBody body = new FormBody.Builder() + .add("grant_type", "refresh_token") + .add("client_id", clientId) + .add("client_secret", clientSecret) + .add("refresh_token", refreshToken) + .build(); + + final Request request = new Request.Builder() + .url("https://oauth.example.com/token") + .post(body) + .build(); + + try (Response response = client.newCall(request).execute()) { + final JsonNode json = objectMapper.readTree(response.body().string()); + return json.get("access_token").asText(); + } + } + +Authentification par clé API +------------------------------ + +.. code-block:: java + + protected Response callApi(final String url, final String apiKey) { + final Request request = new Request.Builder() + .url(url) + .addHeader("Authorization", "Bearer " + apiKey) + .build(); + + return httpClient.newCall(request).execute(); + } + +Gestion des erreurs +==================== + +Pour les erreurs fatales devant interrompre le traitement, levez une exception +``DataStoreException``. + +.. code-block:: java + + @Override + protected void storeData(...) { + try { + // Traitement + } catch (final AuthenticationException e) { + logger.error("Authentication failed. Check your credentials.", e); + throw new DataStoreException("Authentication failed", e); + } catch (final RateLimitException e) { + logger.warn("Rate limit exceeded. Waiting..."); + sleep(60000L); + // Logique de nouvelle tentative + } catch (final Exception e) { + logger.error("Unexpected error occurred", e); + throw new DataStoreException("Failed to crawl data", e); + } + } + +.. note:: + + Dans les connecteurs réels tels que ``fess-ds-example``, afin qu'une erreur + sur un seul enregistrement n'interrompe pas l'ensemble de l'exploration, une + ``CrawlingAccessException`` est capturée au niveau de chaque enregistrement + et l'URL en erreur est enregistrée dans ``FailureUrlService``. Le drapeau + d'interruption de ``DataStoreCrawlingException`` est également utilisé pour + contrôler si l'ensemble de l'exploration doit être interrompu. Pour + implémenter un connecteur robuste, référez-vous à l'implémentation de + ``ExampleDataStore``. + +Tests +===== + +Tests unitaires +----------------- + +Les plugins |Fess| sont testés à l'aide de la classe ``LastaDiTestCase`` d'UTFlute. +Les tests sont écrits avec JUnit 5 (Jupiter). En remplaçant ``IndexUpdateCallback`` +par une implémentation qui collecte les ``dataMap`` enregistrés, il est possible +de vérifier le résultat du mapping sans recourir à une bibliothèque de mocks. + +.. code-block:: java + + public class ExampleDataStoreTest extends LastaDiTestCase { + + public ExampleDataStore dataStore; + + @Override + protected String prepareConfigFile() { + return "test_app.xml"; + } + + @Override + public void setUp(final TestInfo testInfo) throws Exception { + super.setUp(testInfo); + dataStore = new ExampleDataStore(); + } + + @Test + public void test_getName() { + assertEquals("ExampleDataStore", dataStore.getName()); + } + + @Test + public void test_storeData() { + final TestIndexUpdateCallback callback = new TestIndexUpdateCallback(); + final DataStoreParams paramMap = new DataStoreParams(); + + final Map scriptMap = new HashMap<>(); + scriptMap.put("title", "title"); + + dataStore.storeData(new DataConfig(), callback, paramMap, scriptMap, new HashMap<>()); + + assertFalse(callback.getDataMapList().isEmpty()); + } + + // Callback de test collectant les dataMap enregistrés + private static class TestIndexUpdateCallback implements IndexUpdateCallback { + private final List> dataMapList = new ArrayList<>(); + + @Override + public void store(final DataStoreParams paramMap, final Map dataMap) { + dataMapList.add(new HashMap<>(dataMap)); + } + + @Override + public long getExecuteTime() { + return 0; + } + + @Override + public long getDocumentSize() { + return dataMapList.size(); + } + + @Override + public void commit() { + // Ne rien faire + } + + public List> getDataMapList() { + return dataMapList; + } + } + } + +.. note:: + + Comme la classe de base annote déjà ``setUp`` avec ``@BeforeEach``, il n'est + pas nécessaire de réajouter d'annotation de cycle de vie sur la méthode + surchargée. Chaque méthode de test doit être annotée avec ``@Test`` + (``org.junit.jupiter.api.Test``). + +Build et installation +======================== + +pom.xml +------- + +Le plugin est construit comme un jar ayant ``fess-parent`` pour POM parent. +Les dépendances vers ``fess`` et ``opensearch`` étant fournies au moment de +l'exécution par |Fess| lui-même, elles doivent être déclarées en ``provided``. + +.. code-block:: xml + + + 4.0.0 + org.codelibs.fess + fess-ds-example + 15.10.0 + jar + + + org.codelibs.fess + fess-parent + 15.10.0 + + + + + + org.codelibs.fess + fess + provided + + + org.opensearch + opensearch + provided + + + + +Les tests utilisent JUnit 5 et ``org.dbflute.utflute:utflute-lastaflute``. + +Build +----- + +.. code-block:: bash + + mvn clean package + +Le fichier ``fess-ds-example-15.10.0.jar`` est généré dans le répertoire ``target/``. + +Installation +------------ + +Installez le fichier JAR généré dans |Fess| puis redémarrez |Fess|. Pour les +détails de la procédure d'installation, référez-vous à :doc:`../admin/plugin-guide`. +Après l'installation, créez une nouvelle configuration depuis « Crawler > +DataStore » dans l'écran d'administration, et indiquez dans « Nom de handler » +le nom retourné par ``getName()`` (``ExampleDataStore`` dans cet exemple). + +Exemple de configuration +========================== + +Exemple de configuration dans l'écran d'administration : + +Paramètres +---------- + +Le champ « Paramètres » contient les clés et valeurs que le connecteur lit +depuis ``paramMap``. + +:: + + api.url=https://api.example.com/v1 + api.key=your_api_key + +Script +------ + +Le champ « Script » contient le mapping sous la forme ``membre gauche=membre droit``. +Le membre gauche est le nom du champ d'index, le membre droit est un script +(JavaScript pour une configuration nouvellement créée ; une configuration sans +type de script enregistré est traitée comme du Groovy) référençant un champ de +l'enregistrement source. Voici un +exemple pour un enregistrement source comportant les champs ``url`` / ``title`` +/ ``content`` / ``updated_at`` / ``content_type``. + +:: + + url=url + title=title + content=content + last_modified=updated_at + mimetype=content_type + +.. note:: + + Les noms de champs référençables dans le membre droit dépendent des valeurs + que le connecteur stocke dans ``resultMap`` (les valeurs de ``paramMap`` et + les champs de l'enregistrement source). Dans les connecteurs existants tels + que CSV ou JSON, un préfixe propre tel que ``data.*`` peut être utilisé ; + référez-vous à la documentation de chaque connecteur. + +Informations complémentaires +============================== + +- :doc:`plugin-architecture` - Architecture des plugins +- :doc:`../admin/plugin-guide` - Installation des plugins +- :doc:`../config/datastore/ds-overview` - Vue d'ensemble des connecteurs DataStore +- `fess-ds-example `__ - Modèle d'implémentation de plugin DataStore +- `GitHub: fess-ds-* `__ - Exemples de connecteurs publiés diff --git a/fr/15.10/dev/index.rst b/fr/15.10/dev/index.rst new file mode 100644 index 000000000..a6fe5b8a2 --- /dev/null +++ b/fr/15.10/dev/index.rst @@ -0,0 +1,27 @@ +================================== +Documentation developpeur |Fess| +================================== + +Documentation concernant le developpement d'extensions pour |Fess|. + +.. toctree:: + :maxdepth: 2 + :caption: Vue d'ensemble + + overview + +.. toctree:: + :maxdepth: 2 + :caption: Developpement de plugins + + plugin-architecture + datastore-plugin + script-engine-plugin + webapp-plugin + ingest-plugin + +.. toctree:: + :maxdepth: 2 + :caption: Personnalisation + + theme-development diff --git a/fr/15.10/dev/ingest-plugin.rst b/fr/15.10/dev/ingest-plugin.rst new file mode 100644 index 000000000..12dfb7f75 --- /dev/null +++ b/fr/15.10/dev/ingest-plugin.rst @@ -0,0 +1,182 @@ +================================== +Plugin Ingest +================================== + +Vue d'ensemble +============== + +Les plugins Ingest fournissent une fonctionnalité de traitement et de +transformation des données juste avant que les documents ne soient +enregistrés dans l'index. Chaque document récupéré lors du crawl passe +par les Ingester enregistrés avant d'être envoyé à l'index. + +Cas d'utilisation +================= + +- Normalisation du texte (conversion pleine largeur/demi-largeur, + mise en forme des espaces, etc.) +- Ajout de métadonnées ou de champs personnalisés +- Masquage d'informations sensibles +- Conversion de valeurs (par exemple : décodage d'embeddings vectoriels + encodés) + +Classe Ingester +=============== + +La fonctionnalité Ingest s'implémente en héritant de la classe abstraite +``org.codelibs.fess.ingest.Ingester``. ``Ingester`` fournit des méthodes +``process`` appelées selon le type de crawl et l'étape de traitement. +Les implémentations par défaut renvoient toutes le ``target`` reçu tel +quel (elles ne font rien), il suffit donc de ne surcharger que les +méthodes nécessaires. + +- ``protected Map process(Map target)`` + + Point de délégation commun aux deux méthodes basées sur ``Map``. En la + surchargeant, elle s'applique aux documents du crawl de datastore ainsi + qu'à ceux du crawl Web/fichier (lors de l'enregistrement dans l'index). + Pour de nombreux cas d'usage, surcharger uniquement cette méthode + suffit. + +- ``public Map process(Map target, DataStoreParams params)`` + + Appelée lors du crawl de datastore. Par défaut, elle délègue à + ``process(target)``. + +- ``public Map process(Map target, AccessResult accessResult)`` + + Appelée lors de l'enregistrement dans l'index pour le crawl Web/fichier. + Par défaut, elle délègue à ``process(target)``. + +- ``public ResultData process(ResultData target, ResponseData responseData)`` + + Appelée lors du traitement de la réponse pour le crawl Web/fichier + (avant l'enregistrement du résultat d'accès). Par défaut, elle renvoie + ``target`` tel quel. + +Ordre d'exécution (priority) +---------------------------- + +Lorsque plusieurs Ingester sont enregistrés, ils s'exécutent par ordre +croissant du champ ``priority`` (les valeurs les plus petites en +premier). La valeur par défaut est ``99``. Elle peut être définie +directement dans le constructeur ou modifiée via ``setPriority(int)``. + +.. code-block:: java + + public int getPriority() + public void setPriority(final int priority) + +Exemple d'implémentation +======================== + +Exemple de surcharge de ``process(Map)`` qui normalise +le contenu et ajoute un champ personnalisé : + +.. code-block:: java + + package org.codelibs.fess.ingest.example; + + import java.util.Map; + + import org.codelibs.fess.ingest.Ingester; + + public class ExampleIngester extends Ingester { + + public ExampleIngester() { + // Définit l'ordre d'exécution (plus la valeur est petite, plus tôt l'exécution a lieu ; la valeur par défaut est 99) + setPriority(50); + } + + @Override + protected Map process(final Map target) { + // Normalisation du contenu + final Object content = target.get("content"); + if (content instanceof String) { + target.put("content", ((String) content).trim().replaceAll("\\s+", " ")); + } + + // Ajout d'un champ personnalisé + target.put("ingested_by", ExampleIngester.class.getSimpleName()); + + // Renvoie le document traité + return target; + } + } + +.. note:: + + Si la méthode ``process`` renvoie ``null``, l'enregistrement dans + l'index échoue. Comme il n'existe aucun mécanisme pour ignorer un + document, veillez à toujours renvoyer ``target``. + +Enregistrement +============== + +Les Ingester s'enregistrent via le conteneur DI. Le plugin doit inclure +``fess_ingest++.xml``. Le suffixe ``++`` à la fin du nom de fichier +correspond à la convention de fusion qui ajoute la configuration au +fichier ``fess_ingest.xml`` du cœur de |Fess| (qui définit +``ingestFactory``, chargé de gérer les Ingester). + +.. code-block:: xml + + + + + + + + + +Grâce à ````, ``Ingester#register()`` +est appelée après la création du composant, ce qui l'enregistre +lui-même dans ``ingestFactory``. + +Il n'existe aucun paramètre de configuration dans +``fess_config.properties`` pour la fonctionnalité Ingest. L'activation +ou la désactivation dépend de l'installation ou non du plugin, et +l'ordre d'exécution est contrôlé par ``priority``. + +Flux d'exécution +================ + +Les Ingester sont appelés par ordre croissant de ``priority``, juste +avant que le document traité ne soit envoyé à l'index, aux emplacements +suivants : + +- **Crawl de datastore** : ``process(Map, DataStoreParams)`` est + appelée juste avant l'envoi du document. +- **Crawl Web/fichier (traitement de la réponse)** : + ``process(ResultData, ResponseData)`` est appelée avant + l'enregistrement du résultat du crawl. +- **Crawl Web/fichier (enregistrement dans l'index)** : + ``process(Map, AccessResult)`` est appelée juste avant l'envoi du + document. + +Dans tous les cas, si un Ingester lève une exception, un message +d'avertissement est journalisé et le traitement se poursuit +(l'enregistrement du document dans l'index n'est pas interrompu). + +.. note:: + + Comme les Ingester sont enregistrés dans l'environnement + d'exécution du crawler (``ingestFactory``), ils fonctionnent dans + le cadre du traitement de crawl. + +Implémentations de référence +============================= + +À titre de référence pour l'implémentation, les plugins suivants sont +publiés sur GitHub par `CodeLibs `__ : + +- ``fess-ingest-example`` - exemple d'implémentation minimale +- ``fess-webapp-multimodal`` - plugin contenant ``EmbeddingIngester``, + qui décode les embeddings vectoriels + +Informations complémentaires +============================= + +- :doc:`plugin-architecture` - Architecture des plugins diff --git a/fr/15.10/dev/overview.rst b/fr/15.10/dev/overview.rst new file mode 100644 index 000000000..97cc5b6b5 --- /dev/null +++ b/fr/15.10/dev/overview.rst @@ -0,0 +1,249 @@ +==================================================== +Aperçu de la documentation pour les développeurs +==================================================== + +Vue d'ensemble +============== + +Cette section décrit le développement d'extensions pour |Fess|. +Elle fournit des informations pour étendre |Fess|, telles que le développement +de plugins, la création de connecteurs personnalisés et la personnalisation +de thèmes. + +Public cible +============ + +- Développeurs souhaitant développer des fonctionnalités personnalisées pour |Fess| +- Développeurs souhaitant créer des plugins +- Développeurs souhaitant comprendre le code source de |Fess| + +Connaissances préalables +------------------------- + +- Connaissances de base de Java 21 +- Bases de Maven (système de build) +- Expérience en développement d'applications web +- Connaissances de base d'OpenSearch (|Fess| utilise OpenSearch comme moteur de recherche) + +Environnement de développement +=============================== + +Environnement recommandé +-------------------------- + +- **JDK** : OpenJDK 21 ou supérieur +- **IDE** : IntelliJ IDEA / Eclipse / VS Code +- **Outil de build** : Maven (le build n'impose pas de version minimale, mais une version 3.x récente prenant en charge Java 21 est recommandée) +- **Git** : gestion de versions +- **OpenSearch** : moteur de recherche backend (si vous démarrez depuis l'IDE, les modules et plugins nécessaires sont téléchargés lors du build) + +Installation +------------- + +|Fess| se construit comme un projet Maven. Lors du développement, il est plus +simple de le démarrer depuis l'IDE. + +1. Récupération du code source : + + :: + + git clone https://github.com/codelibs/fess.git + +2. Importation dans l'IDE : + + Importez le répertoire récupéré dans l'IDE en tant que projet Maven. + +3. Téléchargement des modules et plugins pour OpenSearch : + + Uniquement lors de la première exécution, récupérez les modules et plugins + du moteur de recherche dans le répertoire ``plugins`` avec la commande + suivante : + + :: + + mvn antrun:run + +4. Démarrage du serveur de développement (depuis l'IDE) : + + Exécutez ou déboguez ``org.codelibs.fess.FessBoot`` dans l'IDE, puis ouvrez + http://localhost:8080/ dans votre navigateur. + L'écran d'administration se trouve à l'adresse http://localhost:8080/admin/ + (compte initial : ``admin`` / ``admin``). + +5. Construction du package (création de la distribution) : + + Si vous avez besoin d'un package de distribution, exécutez le goal + ``package``. Le résultat est généré dans ``target/releases`` (ajoutez + ``-DskipTests`` pour ignorer les tests unitaires). + + :: + + mvn package + + Une fois la distribution générée décompressée, le script de démarrage + ``bin/fess`` est disponible. + + :: + + unzip target/releases/fess-*.zip + ./fess-*/bin/fess + +.. note:: + + Le script de démarrage ``bin/fess`` est inclus dans le package de + distribution (zip/rpm/deb). + Le simple fait d'exécuter ``mvn package`` dans l'arborescence source ne + génère pas ``bin/fess`` à la racine du dépôt. + Pour développer à partir des sources, exécutez ``FessBoot`` dans l'IDE + comme indiqué ci-dessus, ou utilisez le ``bin/fess`` de la distribution + décompressée. + +Aperçu de l'architecture +========================= + +|Fess| est composé des composants principaux suivants : + +Structure des composants +-------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Composant + - Description + * - Couche Web + - Implémentation MVC avec le framework LastaFlute + * - Couche Service + - Logique métier + * - Couche d'accès aux données + - Accès type-safe à OpenSearch via DBFlute (ESFlute/FreeGen) + * - Crawler + - Collecte de contenu via la bibliothèque fess-crawler + * - Moteur de recherche + - Recherche plein texte avec OpenSearch + +Frameworks principaux +----------------------- + +- **LastaFlute** : framework web (actions, formulaires, validation) +- **DBFlute** : framework d'accès aux données. Les classes d'accès type-safe + pour OpenSearch (``Bhv`` / ``ConditionBean``) sont générées par la + fonctionnalité FreeGen de DBFlute et les templates ESFlute (régénération + via ``mvn dbflute:freegen``) +- **Lasta Di** : conteneur d'injection de dépendances + +Structure des répertoires +=========================== + +:: + + fess/ + ├── src/main/java/org/codelibs/fess/ + │ ├── app/ + │ │ ├── web/ # Contrôleurs (Action) + │ │ ├── service/ # Services + │ │ ├── logic/ # Logique + │ │ └── pager/ # Pagination + │ ├── api/ # API REST (api/v2, etc.) + │ ├── helper/ # Classes utilitaires + │ ├── crawler/ # Fonctionnalités liées au crawler + │ ├── indexer/ # Traitement d'indexation + │ ├── opensearch/ # Accès OpenSearch (généré par ESFlute/FreeGen) + │ ├── llm/ # Intégration LLM + │ ├── ds/ # Connecteurs de datastore + │ ├── ingest/ # Ingest (traitement des données lors de l'indexation) + │ ├── script/ # Moteur de script + │ ├── entity/ # Entités + │ └── mylasta/ # Configuration LastaFlute (DI, messages, configuration type-safe) + ├── src/main/resources/ + │ ├── fess_config.properties # Configuration + │ └── fess_*.xml # Configuration DI (app.xml, fess_ds.xml, etc.) + └── src/main/webapp/ + └── WEB-INF/view/ # JSP de l'administration et de la connexion + +Points d'extension +==================== + +|Fess| fournit les points d'extension suivants : + +Plugins +-------- + +Vous pouvez ajouter des fonctionnalités à l'aide de plugins. + +- **Plugin DataStore** : exploration depuis de nouvelles sources de données (hérite de ``AbstractDataStore``) +- **Plugin de moteur de script** : prise en charge de nouveaux langages de script (implémente ``ScriptEngine``) +- **Plugin d'application Web** : extension de l'interface web (surcharge de composants Lasta Di et fusion de ressources) +- **Plugin Ingest** : traitement des données lors de l'indexation (hérite de ``Ingester``) + +Détails : :doc:`plugin-architecture` + +.. note:: + + |Fess| lui-même est empaqueté sous forme de ``war``. Si vous ne parvenez + pas à résoudre |Fess| comme dépendance lors de la construction locale + d'un plugin, modifiez temporairement ```` dans ``pom.xml`` en + ``jar``, exécutez ``mvn clean install -DskipTests``, puis revenez à + ``war``. + +Thèmes +------- + +Vous pouvez personnaliser le design de l'écran de recherche. + +Détails : :doc:`theme-development` + +Configuration +--------------- + +``fess_config.properties`` permet de personnaliser de nombreux comportements. + +Détails : :doc:`../config/intro` + +Développement de plugins +========================== + +Pour plus de détails sur le développement de plugins, consultez : + +- :doc:`plugin-architecture` - Architecture des plugins +- :doc:`datastore-plugin` - Développement de plugins DataStore +- :doc:`script-engine-plugin` - Plugin de moteur de script +- :doc:`webapp-plugin` - Plugin d'application Web +- :doc:`ingest-plugin` - Plugin Ingest + +Développement de thèmes +========================= + +- :doc:`theme-development` - Personnalisation des thèmes + +Bonnes pratiques +================== + +Conventions de codage +----------------------- + +- Suivre le style de code existant de |Fess| +- Formater le code avec ``mvn formatter:format`` +- Ajouter les en-têtes de licence avec ``mvn license:format`` + +Tests +------ + +- Tests unitaires (``*Test.java``) : exécutés via ``mvn test`` dans le profil ``build`` par défaut +- Tests d'intégration (``*Tests.java``) : exécutés via ``mvn test -P integrationTests``. + L'exécution des tests d'intégration nécessite un serveur |Fess| et une instance OpenSearch en cours de fonctionnement + +Journalisation +--------------- + +- Utilise Log4j2 +- ``logger.debug()`` / ``logger.info()`` / ``logger.warn()`` / ``logger.error()`` +- Ne pas journaliser d'informations sensibles + +Ressources +=========== + +- `GitHub Repository `__ +- `Issue Tracker `__ +- `Discussions `__ diff --git a/fr/15.10/dev/plugin-architecture.rst b/fr/15.10/dev/plugin-architecture.rst new file mode 100644 index 000000000..97818124e --- /dev/null +++ b/fr/15.10/dev/plugin-architecture.rst @@ -0,0 +1,388 @@ +========================= +Architecture des plugins +========================= + +Aperçu +====== + +Le système de plugins de |Fess| permet d'étendre les fonctionnalités du cœur. +Les plugins sont distribués sous forme de fichiers JAR ; lorsqu'ils sont +ajoutés au classpath, leurs composants sont chargés par le conteneur DI +(Lasta Di) puis enregistrés auprès de la fabrique ou du gestionnaire +correspondant. + +Types de plugins +================= + +|Fess| détermine le type d'un plugin à partir du préfixe du nom de +l'artefact (``PluginHelper.ArtifactType``). Les principaux types sont les +suivants : + +.. list-table:: + :header-rows: 1 + :widths: 20 25 55 + + * - Type + - Préfixe + - Description + * - DataStore + - ``fess-ds-*`` + - Récupération de contenu depuis de nouvelles sources de données (Box, Slack, Git, etc.) + * - Application Web + - ``fess-webapp-*`` + - Extension de l'interface Web ou des fonctionnalités de recherche + * - Moteur de script + - ``fess-script-*`` + - Prise en charge de nouveaux langages de script + * - Ingest + - ``fess-ingest-*`` + - Traitement des documents lors de leur enregistrement dans l'index + * - Miniature + - ``fess-thumbnail-*`` + - Ajout de méthodes de génération de miniatures + * - LLM + - ``fess-llm-*`` + - Ajout de fournisseurs LLM utilisés pour le RAG/chat + * - Crawler + - ``fess-crawler-*`` + - Extension des clients du crawler + * - Stockage + - ``fess-storage-*`` + - Ajout d'un backend de stockage d'objets utilisé pour le crawl et la fonction de stockage + * - SSO + - ``fess-sso-*`` + - Ajout d'une méthode d'authentification Single Sign-On sélectionnée par ``sso.type`` + +.. note:: + + Le type ``fess-theme-*`` (thème JAR), qui fournissait des JSP, a été supprimé en 15.10. + L'apparence de l'écran de recherche se modifie avec un thème statique, et non avec un + plugin (voir :doc:`theme-development`). + +Structure d'un plugin +====================== + +Structure de base +----------------- + +En prenant comme exemple `fess-ds-example `__, +le modèle d'implémentation d'un plugin DataStore, un plugin se compose d'une +« classe d'implémentation » et d'un « fichier d'enregistrement DI » : + +:: + + fess-ds-example/ + ├── pom.xml + └── src/main/ + ├── java/org/codelibs/fess/ds/example/ + │ └── ExampleDataStore.java # Implémentation du DataStore + └── resources/ + └── fess_ds++.xml # Enregistrement du composant DI + +Exemple de pom.xml +------------------ + +Le plugin est construit comme un jar ayant ``fess-parent`` pour POM parent. +Les bibliothèques telles que ``fess`` ou ``opensearch``, fournies à +l'exécution par |Fess| lui-même, doivent être déclarées avec la portée +``provided``. Le numéro de version et les paramètres de build (formateur, +en-têtes de licence, etc.) sont hérités du POM parent. + +.. code-block:: xml + + + + 4.0.0 + + org.codelibs.fess + fess-ds-example + 15.10.0 + jar + + + org.codelibs.fess + fess-parent + 15.10.0 + + + + + + org.codelibs.fess + fess + provided + + + org.opensearch + opensearch + provided + + + + +.. note:: + + Sur les branches en cours de développement, la version comporte le + suffixe ``-SNAPSHOT``, par exemple ``15.10.0-SNAPSHOT``. Les bibliothèques + dépendantes propres au plugin sont déclarées comme des dépendances Maven + classiques. Comme elles ne sont pas incluses dans |Fess| lui-même, elles + doivent être distribuées avec le plugin. + +Enregistrement du plugin +========================= + +Enregistrement dans le conteneur DI +------------------------------------ + +Un plugin enregistre ses composants dans un fichier de configuration DI dont +le nom se termine par ``++``, comme ``fess_ds++.xml``. Lasta Di fusionne +automatiquement tout fichier suffixé par ``++`` trouvé sur le classpath avec +le fichier de configuration correspondant de |Fess| lui-même (``fess_ds.xml`` +dans cet exemple). Ce mécanisme permet à un plugin d'ajouter ses propres +composants sans modifier les fichiers de |Fess| lui-même. + +.. code-block:: xml + + + + + + + + + +Le fichier cible de la fusion diffère selon le type de plugin. Par exemple, +un moteur de script utilise ``fess_se++.xml``, un plugin Ingest utilise +``fess_ingest++.xml``, un fournisseur LLM utilise ``fess_llm++.xml``, et une +application Web utilise ``app++.xml``. + +Initialisation du composant +---------------------------- + +```` est un paramètre de cycle de vie de +Lasta Di indiquant la méthode à appeler après la création du composant. Dans +le cas d'un DataStore, la méthode ``register()`` fournie par +``AbstractDataStore`` est appelée et enregistre celui-ci auprès de +``DataStoreFactory`` : + +.. code-block:: java + + // Implémentation fournie par AbstractDataStore (il n'est généralement pas nécessaire de la surcharger) + public void register() { + ComponentUtil.getDataStoreFactory().add(getName(), this); + } + +.. note:: + + Il ne s'agit pas de l'annotation Java ``@PostConstruct``, mais d'une + initialisation réalisée via l'élément ```` du fichier de + configuration DI. Le nom enregistré correspond à la valeur de retour de + ``getName()`` ; c'est ce nom qui sera utilisé pour sélectionner le plugin + dans l'écran d'administration. + +Cycle de vie du plugin +======================= + +Initialisation +-------------- + +1. Le fichier JAR du plugin est ajouté au classpath. +2. Le conteneur DI fusionne les fichiers ``fess_*++.xml`` et génère les composants. +3. La méthode indiquée dans ```` (par exemple ``register``) est appelée. +4. Le plugin est enregistré auprès de la fabrique ou du gestionnaire correspondant. + +Arrêt +----- + +1. À l'arrêt du conteneur DI, la méthode indiquée dans ```` est + appelée (si elle est définie). +2. Nettoyage des ressources. + +.. note:: + + Dans le cas d'un DataStore, ``AbstractDataStore.stop()`` positionne un + indicateur d'arrêt sur l'exploration en cours, ce qui permet à la boucle + de traitement des enregistrements de se terminer de manière sûre. + +Dépendances +============ + +Dépendance envers le cœur de Fess +----------------------------------- + +Les classes du cœur de |Fess| étant présentes sur le classpath du serveur au +moment de l'exécution, elles sont déclarées comme dépendance avec la portée +``provided`` (elles ne doivent pas être incluses dans le JAR du plugin). + +.. code-block:: xml + + + org.codelibs.fess + fess + provided + + +Bibliothèques externes +----------------------- + +Un plugin peut inclure ses propres bibliothèques dépendantes : + +.. code-block:: xml + + + com.example + example-sdk + 1.0.0 + + +Comme elles ne sont pas incluses dans |Fess| lui-même, elles doivent être +distribuées avec le plugin. + +Récupération de la configuration +================================== + +Récupération des paramètres et de FessConfig +---------------------------------------------- + +Dans la méthode ``storeData()`` d'un DataStore, les paramètres configurés +dans l'écran d'administration sont récupérés depuis ``DataStoreParams``. +Utilisez ``getAsString()`` pour récupérer les valeurs (``DataStoreParams`` +n'implémentant pas ``Map``, ``get()`` ne retourne pas de chaîne de +caractères). Les valeurs de configuration de |Fess| peuvent également être +récupérées via ``ComponentUtil.getFessConfig()`` : + +.. code-block:: java + + public class ExampleDataStore extends AbstractDataStore { + + @Override + protected String getName() { + // Utilisé comme nom de handler. Il est d'usage de retourner le nom simple de la classe + return this.getClass().getSimpleName(); + } + + @Override + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { + + // Récupération des paramètres + final String apiKey = paramMap.getAsString("api.key"); + final String baseUrl = paramMap.getAsString("base.url"); + + // Récupération de FessConfig + final FessConfig fessConfig = ComponentUtil.getFessConfig(); + } + } + +Pour plus de détails sur l'implémentation de ``storeData()`` (récupération +des données, évaluation du script, enregistrement dans l'index), reportez-vous +à :doc:`datastore-plugin`. + +Build et installation +====================== + +Build +----- + +:: + + mvn clean package + +Le fichier JAR (par exemple ``fess-ds-example-15.10.0.jar``) est généré dans +le répertoire ``target/``. + +Installation +------------ + +1. **Depuis l'écran d'administration** : + + - Ouvrez « Système » → « Plugin » → « Installer ». + - Sélectionnez un plugin dans la liste du dépôt de plugins, ou téléversez + le fichier JAR construit pour l'installer. + +2. **Manuellement** : + + - Copiez le fichier JAR dans le répertoire ``app/WEB-INF/plugin/``. + - Redémarrez |Fess|. + +Pour plus de détails sur la procédure d'installation, reportez-vous à +:doc:`../admin/plugin-guide`. + +Débogage +======== + +Journalisation +--------------- + +|Fess| utilise Log4j2. Le logger s'obtient avec ``LogManager.getLogger()`` : + +.. code-block:: java + + private static final Logger logger = LogManager.getLogger(ExampleDataStore.class); + + public void someMethod() { + logger.debug("Debug message"); + logger.info("Info message"); + } + +.. note:: + + N'écrivez pas d'informations sensibles telles que mots de passe ou + jetons dans les journaux. + +Mode de développement +----------------------- + +Lors du développement, vous pouvez démarrer |Fess| depuis un IDE pour le +déboguer : + +1. Exécutez la classe ``org.codelibs.fess.FessBoot`` en mode débogage. +2. Incluez les sources du plugin dans le projet. +3. Définissez des points d'arrêt. + +Liste des plugins publiés +========================== + +De nombreux plugins sont publiés par le projet |Fess|. Voici quelques +exemples représentatifs (cette liste n'est pas exhaustive) : + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Plugin + - Description + * - ``fess-ds-box`` + - Connecteur Box + * - ``fess-ds-dropbox`` + - Connecteur Dropbox + * - ``fess-ds-slack`` + - Connecteur Slack + * - ``fess-ds-atlassian`` + - Connecteur JIRA / Confluence + * - ``fess-ds-git`` + - Connecteur de dépôt Git + * - ``fess-llm-openai`` + - Fournisseur LLM OpenAI + +D'autres connecteurs DataStore tels que ``fess-ds-csv`` / ``fess-ds-db`` / +``fess-ds-json`` / ``fess-ds-microsoft365`` / ``fess-ds-sharepoint``, ainsi +que des fournisseurs LLM tels que ``fess-llm-ollama`` / ``fess-llm-gemini`` / ``fess-llm-bedrock``, +sont également publiés. Ces plugins sont disponibles sur +`GitHub `__ comme référence pour le +développement. + +Informations complémentaires +============================= + +- :doc:`datastore-plugin` - Développement de plugins DataStore +- :doc:`script-engine-plugin` - Plugin de moteur de script +- :doc:`webapp-plugin` - Plugin d'application Web +- :doc:`ingest-plugin` - Plugin Ingest +- :doc:`theme-development` - Personnalisation des thèmes +- :doc:`../admin/plugin-guide` - Installation des plugins diff --git a/fr/15.10/dev/script-engine-plugin.rst b/fr/15.10/dev/script-engine-plugin.rst new file mode 100644 index 000000000..2e640acbf --- /dev/null +++ b/fr/15.10/dev/script-engine-plugin.rst @@ -0,0 +1,61 @@ +================================== +Plugin Script Engine +================================== + +Vue d'ensemble +============== + +En développant un plugin Script Engine, vous pouvez ajouter le support de nouveaux +langages de script à |Fess|. + +Implémentation de base +====================== + +Implémentez l'interface ``ScriptEngine``: + +.. code-block:: java + + package org.codelibs.fess.script.example; + + import org.codelibs.fess.script.ScriptEngine; + import java.util.Map; + + public class ExampleScriptEngine implements ScriptEngine { + + @Override + public String getName() { + return "example"; + } + + @Override + public Object evaluate(String script, Map params) { + // Logique d'evaluation du script + return executeScript(script, params); + } + } + +Enregistrement +============== + +.. code-block:: java + + @PostConstruct + public void register() { + ComponentUtil.getScriptEngineManager().add(this); + } + +Exemple d'utilisation +===================== + +Sélection du type de script dans l'interface d'administration: + +:: + + scriptType=example + scriptData=your script here + +Informations complémentaires +============================ + +- :doc:`plugin-architecture` - Architecture des plugins +- :doc:`../config/scripting-overview` - Vue d'ensemble du scripting diff --git a/fr/15.10/dev/theme-development.rst b/fr/15.10/dev/theme-development.rst new file mode 100644 index 000000000..ce92b92b2 --- /dev/null +++ b/fr/15.10/dev/theme-development.rst @@ -0,0 +1,360 @@ +================================== +Guide de développement des thèmes +================================== + +Aperçu +====== + +Dans |Fess| 15.10, l'écran de recherche est toujours un thème statique. Un +thème statique est une SPA (Single Page Application, application monopage) +indépendante qui utilise l'API ``/api/v2/*``. Les thèmes sont distribués sous +forme de fichiers ZIP, téléversés puis activés depuis l'écran +d'administration. Lorsqu'aucun thème n'est sélectionné, |Fess| utilise +``bootstrap``, le thème statique fourni avec lui. + +Pour modifier l'apparence de l'écran de recherche, installez un autre thème +(voir :doc:`../admin/theme-guide`) ou créez le vôtre : le plus rapide est de +copier le thème fourni et de modifier la copie, comme décrit dans +`Personnalisation du thème fourni`_. + +.. note:: + + Les thèmes statiques sont disponibles à partir de |Fess| 15.7 et sont + devenus l'écran de recherche par défaut en 15.10. Les plugins de thème JAR, + qui remplaçaient les JSP de l'écran de recherche, ont été supprimés en + 15.10 ; voir `Plugin de thème JAR (supprimé en 15.10)`_. + +Thème statique +============== + +Un thème statique est un ensemble de ressources statiques comprenant le +manifeste ``theme.yml`` et ``index.html``. Le thème lui-même est implémenté +comme une application front-end qui appelle l'API ``/api/v2/*`` de |Fess|. + +Structure +--------- + +Un thème statique adopte la structure de répertoires suivante. + +:: + + example/ + ├── theme.yml # Manifeste (obligatoire) + ├── index.html # HTML d'entrée de la SPA + ├── assets/ # Ressources statiques telles que JavaScript, CSS + │ └── styles.css + ├── i18n/ # Messages multilingues (messages..json) + │ └── messages.en.json + ├── help/ # Définitions d'aide (.json) + │ └── en.json + └── thumbnail.png # Image d'aperçu (facultatif) + +Manifeste (theme.yml) +---------------------- + +``theme.yml`` est le manifeste obligatoire à placer à la racine du ZIP. Voici +un exemple de configuration minimale. + +.. code-block:: yaml + + apiVersion: fess.codelibs.org/v1 + kind: StaticTheme + name: example + displayName: "Example Theme" + version: "15.10.0" + minFessVersion: "15.10" + entry: index.html + spaFallback: true + +Les champs pouvant être spécifiés sont les suivants. + +.. list-table:: + :header-rows: 1 + :widths: 22 12 66 + + * - Champ + - Obligatoire + - Description + * - ``apiVersion`` + - Obligatoire + - Valeur fixe ``fess.codelibs.org/v1``. + * - ``kind`` + - Obligatoire + - Valeur fixe ``StaticTheme``. + * - ``name`` + - Obligatoire + - Nom du thème. Doit correspondre à ``^[a-z0-9][a-z0-9_-]{0,63}$``. Il + est utilisé comme nom du répertoire du thème déployé sous ``themes/`` + (déterminé automatiquement à partir de ce ``name`` lors du + téléversement), ainsi que pour l'URL de diffusion (``/themes//``). + * - ``displayName`` + - Obligatoire + - Nom affiché dans l'écran d'administration. + * - ``version`` + - Obligatoire + - Format de gestion sémantique des versions (exemple : ``15.10.0``, + ``15.10.1-beta.1``). Par convention, ``major.minor`` est la ligne |Fess| que + le thème vise, de sorte que la version seule indique pour quel |Fess| un + thème est prévu. + * - ``author`` + - Facultatif + - Nom de l'auteur. + * - ``description`` + - Facultatif + - Description du thème. + * - ``license`` + - Facultatif + - Licence. + * - ``homepage`` + - Facultatif + - URL de la page d'accueil. + * - ``minFessVersion`` + - Facultatif + - Version minimale de |Fess| prise en charge par le thème. Gardez-la égale au + ``major.minor`` de ``version``. Il n'existe pas de ``maxFessVersion`` : + voir `Publication`_. + * - ``supportedLocales`` + - Facultatif + - Liste des locales prises en charge (exemple : ``[en, ja, de]``). + * - ``entry`` + - Facultatif + - HTML d'entrée de la SPA. Valeur par défaut : ``index.html``. + * - ``spaFallback`` + - Facultatif + - Obsolète. Accepté pour des raisons de compatibilité mais n'est plus + lu : depuis la version 15.10, le HTML d'entrée est toujours servi pour + les chemins de l'écran de recherche. + +.. note:: + + Lors d'un téléversement depuis un ZIP, le nom du répertoire de destination + est déterminé automatiquement à partir de ``name``. Si vous placez + manuellement un thème dans le répertoire ``themes/``, veillez à faire + correspondre le nom du répertoire avec ``name``. Les thèmes dont le nom ne + correspond pas sont ignorés lors de la nouvelle analyse. + +.. note:: + + La miniature d'aperçu doit être placée à la racine du thème sous le nom + fixe ``thumbnail.png`` (elle est affichée dans la liste des thèmes de + l'écran d'administration). Cette image n'est pas un champ du manifeste ; + elle est reconnue par son nom de fichier. Une taille inférieure à 512 Ko + et à 512 × 512 pixels est recommandée. + +Diffusion et API +----------------- + +- Un thème statique est diffusé sous ``/themes//`` (```` + correspond au ``name`` défini dans ``theme.yml``). +- Le HTML d'entrée (par défaut ``index.html``) est renvoyé pour chacun des + chemins ``/``, ``/search``, ``/advance``, ``/help``, ``/error``, + ``/profile``, ``/cache`` et ``/chat``, et le routage ultérieur est assuré + par la SPA. Depuis la version 15.10, c'est le cas quelle que soit la valeur + de ``spaFallback`` ; ce champ n'est plus lu. +- Les erreurs sont également rendues par le thème : lorsqu'une requête + échoue, le navigateur reçoit le HTML d'entrée du thème à l'URL demandée, + avec le véritable statut HTTP. +- L'écran d'administration (``/admin/*``), ``/api/*``, l'écran de connexion, + etc. ne sont pas concernés par le thème statique et sont traités par le + cœur de |Fess|. +- ``{{themePath}}`` dans le HTML d'entrée est remplacé par + ``themes/`` lorsque la page est servie. Faites référence aux + fichiers du thème depuis ``index.html`` sous la forme + ``{{themePath}}/assets/styles.css``, etc. Le nom du thème n'apparaît + alors pas dans la page, et le thème charge ses propres fichiers quel que + soit le nom sous lequel il est installé. +- Le HTML d'entrée est servi avec un en-tête ``Content-Security-Policy`` qui + n'autorise les scripts, les styles, les images et les connexions que depuis + |Fess| lui-même (les styles en ligne sont autorisés ; les scripts en ligne + ne le sont pas). Les polices ou scripts provenant d'un CDN externe ne sont + donc pas chargés ; incluez-les dans le thème. +- La ``Content-Security-Policy`` du HTML d'entrée contient + ``frame-ancestors 'none'`` et la réponse porte aussi + ``X-Frame-Options: DENY`` ; la page n'est donc pas affichée dans un cadre + d'une autre page. La valeur de ``frame-ancestors`` se modifie avec + ``theme.index.frame.ancestors`` dans ``fess_config.properties`` + (par défaut : ``'none'``). Une valeur vide retire ``frame-ancestors`` + (``X-Frame-Options: DENY`` est toujours envoyé). Avec + ``frame-ancestors 'none'``, les navigateurs basés sur WebKit, comme Safari, + laissent vides les cadres qu'un thème affiche depuis une URL ``blob:`` + (aperçu d'un PDF ou copie en cache). Videz la valeur pour les afficher. +- La SPA du thème récupère les données telles que les résultats de recherche + ou le chat depuis l'API ``/api/v2/*``. + +Empaquetage +----------- + +Le script ``scripts/package.sh`` du dépôt `fess-themes +`__ permet d'empaqueter le thème +dans un fichier ZIP destiné à la distribution. + +:: + + ./scripts/package.sh example + +``dist/example-.zip`` est généré (```` correspond au +``version`` défini dans ``theme.yml``). + +.. note:: + + ``theme.yml`` doit être placé à la racine du ZIP. S'il se trouve dans un + sous-répertoire, il ne sera pas reconnu lors du téléversement. + +Publication +----------- + +Les thèmes développés par le projet |Fess| sont publiés sous +https://maven.codelibs.org/release/org/codelibs/fess/themes/ , en +``//-.zip`` avec un ``.sha1`` à côté, et un +``maven-metadata.xml`` par thème qui liste les versions publiées. +``bin/fess-setup install theme `` lit ces métadonnées pour choisir la version construite +pour le |Fess| en cours d'exécution. + +Versionnez un thème sur la ligne |Fess| qu'il vise et augmentez la version dès que ce que livre +l'archive change. Une version publiée n'est jamais écrasée : une modification qui conserve sa +version n'est donc tout simplement jamais distribuée. + +C'est aussi pourquoi le manifeste n'a pas de champ de borne supérieure. Une archive publiée ne +changeant jamais, une borne ne pourrait pas être ajoutée plus tard pour un thème qui cesse de +fonctionner sur un |Fess| plus récent. Ne pas publier ce thème pour la nouvelle ligne dit la même +chose, au moment où on le sait. + +.. note:: + + Énumérez les versions publiées à partir de ``maven-metadata.xml`` plutôt que d'un listage de + répertoire. L'index de répertoire est généré périodiquement : un thème fraîchement publié est + lisible via ses métadonnées avant d'apparaître dans un listage. + +Installation et activation +--------------------------- + +1. Ouvrez « Système » → « Thème » (``/admin/theme/``) dans l'écran + d'administration. +2. Téléversez le fichier ZIP créé. Un thème publié peut aussi être installé depuis + la ligne de commande avec ``bin/fess-setup install theme `` ; voir + :doc:`../install/fess-setup`. +3. Sur la page de liste, sélectionnez le thème souhaité dans le menu + déroulant « Thème par défaut », puis cliquez sur le bouton « Définir » + pour l'activer. + +Le mécanisme d'activation est le suivant. + +- Lorsque vous cliquez sur le bouton « Définir », le nom du thème sélectionné + est enregistré dans la propriété système ``theme.default`` et devient le + thème par défaut pour l'ensemble du système. +- Si le nom du thème correspond à la clé d'un hôte virtuel, le thème n'est + appliqué que lors de l'accès à cet hôte virtuel. Cela permet de changer de + thème pour chaque hôte virtuel. +- Si vous mettez à jour directement le répertoire ``themes/`` sur le disque, + vous pouvez relancer une analyse avec « Recharger ». + +.. note:: + + Le téléversement du ZIP est soumis à des limites telles que la taille du + fichier, la taille totale après décompression et le nombre d'entrées ; ces + limites peuvent être ajustées via les propriétés ``theme.*`` de + ``fess_config.properties`` (par exemple, ``theme.upload.max.size`` vaut + 50 Mo par défaut et ``theme.directory.path`` vaut ``themes`` par défaut). + Lors de la décompression, des vérifications sont effectuées pour empêcher + les attaques de type ZIP Slip et zip bomb. + +.. _theme-customize-bundled: + +Personnalisation du thème fourni +-------------------------------- + +Le thème fourni ``bootstrap`` se trouve dans ``app/themes/bootstrap/`` de +l'installation de |Fess| (``/usr/share/fess/app/themes/bootstrap/`` pour les +paquets RPM/DEB). Ne le modifiez pas sur place : une mise à niveau le +remplace, et le nom ``bootstrap`` lui est réservé, de sorte qu'il ne peut être +ni supprimé ni remplacé par un téléversement. Copiez-le plutôt sous un nouveau +nom. + +1. Copiez le répertoire, par exemple vers ``mytheme`` : + + :: + + $ cp -r app/themes/bootstrap /tmp/mytheme + +2. Dans ``theme.yml``, remplacez ``name`` par ``mytheme`` et modifiez + ``displayName``. ``name`` doit correspondre au nom du répertoire. + +3. Laissez ``index.html`` tel quel. Le ``index.html`` fourni fait + référence à ses propres fichiers, comme la feuille de style, les logos + et le script, sous la forme ``{{themePath}}/assets/...``, et |Fess| + remplace ``{{themePath}}`` par ``themes/`` (le ``name`` de + ``theme.yml``) lorsqu'il sert la page. Il suffit donc de renommer la + copie pour qu'elle charge ses propres fichiers. Si vous ajoutez un + fichier auquel ``index.html`` fait référence, écrivez aussi son URL sous + la forme ``{{themePath}}/assets/...``. + +4. Apportez vos modifications : + + - Couleurs et mise en page : ``assets/styles.css``. + - Logos : ``assets/logo-head.png`` (en-tête) et ``assets/logo.png`` + (page d'accueil de la recherche). + - Textes, comme le pied de page (``footer.copyright_org``) : les fichiers + ``i18n/messages..json``, un par langue. + - Structure de la page : ``index.html``. + +5. Empaquetez le répertoire dans un ZIP avec ``theme.yml`` à sa racine, puis + téléversez-le depuis « Système » → « Thème » dans l'écran + d'administration : + + :: + + $ cd /tmp/mytheme && zip -r ../mytheme.zip . + + Vous pouvez aussi placer le répertoire dans ``app/themes/`` et cliquer sur + « Recharger » sur la même page. + +6. Sélectionnez ``mytheme`` comme thème par défaut sur cette page. + +.. note:: + + Après chaque mise à niveau de |Fess|, remplacez la copie par une nouvelle + copie du thème fourni et réappliquez vos modifications, car le thème + fourni suit l'API ``/api/v2/*`` de sa version de |Fess|. + +Plugin de thème JAR (supprimé en 15.10) +====================================== + +Le type de plugin de thème JAR, qui regroupait des JSP, du CSS et des +images dans un JAR ``fess-theme-*`` et les appliquait comme le thème +portant le même nom que la clé de l'hôte virtuel, a été supprimé dans +|Fess| 15.10. 15.10 ne déploie plus les thèmes JAR et ne les utilise pour +aucun écran. + +- Si vous en installez un depuis « Système » → « Plugin » dans l'écran + d'administration, il est seulement placé dans ``app/WEB-INF/plugin/`` + comme un JAR générique de type ``jar`` et ne modifie aucun écran. Un + ``fess-theme-*.jar`` laissé par une version antérieure s'affiche de la + même manière et peut être supprimé depuis cet écran ou avec + ``bin/fess-setup remove plugin ``. +- ``bin/fess-setup`` n'affiche pas ``fess-theme-*`` dans ses listes et ne + l'installe pas. + +Reportez dans un thème statique les modifications que vous faisiez avec +un thème JAR. + +- Pour les couleurs, la mise en page et le logo de l'écran de recherche, + copiez le thème fourni et modifiez-le (voir + `Personnalisation du thème fourni`_). +- Si vous changiez l'apparence par hôte virtuel, installez un thème + statique portant le même nom que l'hôte virtuel (voir + :doc:`../config/security-virtual-host`). +- L'écran de connexion (``/login/``) est le même pour tous les hôtes + virtuels et ne peut pas être modifié par un thème. + +Exemples de thèmes existants +============================= + +- `fess-themes `__ - Collection de + thèmes statiques (regroupe plusieurs thèmes statiques tels que + ``codesearch`` et ``docsearch``) + +Informations complémentaires +============================= + +- :doc:`plugin-architecture` - Architecture des plugins +- :doc:`../admin/plugin-guide` - Installation des plugins diff --git a/fr/15.10/dev/webapp-plugin.rst b/fr/15.10/dev/webapp-plugin.rst new file mode 100644 index 000000000..6bacd84a0 --- /dev/null +++ b/fr/15.10/dev/webapp-plugin.rst @@ -0,0 +1,337 @@ +======================== +Plugin d'application Web +======================== + +Aperçu +====== + +Les plugins d'application Web (``fess-webapp-*``) sont des plugins qui +étendent l'application Web de |Fess|. Contrairement aux autres types de +plugins, ils n'ajoutent pas directement de classes Action ou de JSP, mais +étendent les fonctionnalités en **ajoutant ou remplaçant des composants** +dans le conteneur DI (Lasta Di). Les cas d'usage représentatifs sont les +suivants : + +- Ajout de nouveaux composants (helpers, services, etc.) +- Remplacement de composants du cœur de |Fess| (par sous-classement) +- Ajout de points de terminaison d'API REST (``WebApiManager``) +- Extension du comportement de recherche (commandes de requête, fusion de + classements, etc.) + +.. note:: + + Les plugins d'application Web sont distribués sous forme de fichier JAR ; + les classes internes et les fichiers de configuration DI qu'ils + contiennent sont chargés dans le classpath de l'application Web de + |Fess|. Ils n'ajoutent pas de vues JSP. Pour personnaliser le design de + l'écran de recherche, reportez-vous à :doc:`theme-development`. + +Structure de base +================= + +En prenant comme exemple +`fess-webapp-example `__, +le modèle d'implémentation d'un plugin d'application Web, un plugin se +compose d'une « classe d'implémentation » et d'un « fichier d'enregistrement +DI » : + +:: + + fess-webapp-example/ + ├── pom.xml + └── src/main/ + ├── java/org/codelibs/fess/webapp/example/helper/ + │ ├── ExampleHelper.java # Composant ajouté + │ └── CustomSystemHelper.java # Remplacement d'un composant du cœur + └── resources/ + ├── app++.xml # Ajout de composant (fusion) + └── fess+systemHelper.xml # Remplacement de composant + +.. note:: + + Le package des classes d'implémentation utilise + ``org.codelibs.fess.webapp.``. Les fichiers de + configuration DI sont placés dans ``src/main/resources/``. Contrairement + aux plugins DataStore, ils n'incluent pas de ``src/main/webapp/`` ni de + JSP. + +pom.xml et manifeste +==================== + +Les plugins d'application Web sont construits comme un jar ayant +``fess-parent`` pour POM parent. Les bibliothèques telles que ``fess`` ou +``opensearch``, fournies à l'exécution par |Fess| lui-même, doivent être +déclarées avec la portée ``provided``, tandis que les bibliothèques +nécessaires à l'exécution telles que ``lastaflute``, ``dbflute-runtime`` ou +``corelib`` sont déclarées avec la portée habituelle. + +Le point le plus important pour un plugin d'application Web est d'ajouter +``Fess-WebAppJar: true`` au manifeste du JAR. Cette déclaration permet à +|Fess| de monter les classes du plugin et ses fichiers de configuration DI +dans le chargeur de classes de l'application Web. Cette configuration se +fait via ``maven-jar-plugin`` : + +.. code-block:: xml + + + + + maven-jar-plugin + + + + true + + + + + + + +.. warning:: + + Si ``Fess-WebAppJar: true`` n'est pas ajouté, les classes du plugin et + les fichiers de configuration DI ne seront pas chargés dans le classpath + de l'application Web, et l'ajout ou le remplacement de composants ne + sera pas effectif. + +Pour la structure complète du pom.xml (POM parent, déclaration des +dépendances, etc.), reportez-vous à :doc:`plugin-architecture`. + +Modèles d'extension +==================== + +Ajout d'un composant (app++.xml) +--------------------------------- + +La méthode d'extension la plus élémentaire consiste à ajouter vos propres +composants. Lasta Di **fusionne** le fichier ``app++.xml`` présent sur le +classpath dans l'espace de noms ``app`` construit à partir du fichier +``app.xml`` de |Fess| lui-même (le suffixe ``++`` est la convention +indiquant une fusion additive). Comme les composants ajoutés utilisent des +noms qui n'existent pas dans |Fess| lui-même, rien n'est écrasé. + +.. code-block:: xml + + + + + + + + +Dans l'implémentation du composant, utilisez ``@PostConstruct`` pour +l'initialisation, et récupérez les composants de |Fess| lui-même via +``ComponentUtil`` pour les réutiliser (sans les copier ni les écraser) : + +.. code-block:: java + + package org.codelibs.fess.webapp.example.helper; + + import org.codelibs.fess.helper.SystemHelper; + import org.codelibs.fess.util.ComponentUtil; + + import jakarta.annotation.PostConstruct; + + public class ExampleHelper { + + protected String pluginName = "fess-webapp-example"; + + @PostConstruct + public void init() { + // Traitement d'initialisation appelé une seule fois après la création par le conteneur DI + } + + public String getPluginLabel() { + // Réutilise le SystemHelper du cœur pour récupérer la version de Fess en cours d'exécution + final SystemHelper systemHelper = ComponentUtil.getSystemHelper(); + final String version = systemHelper != null ? systemHelper.getProductVersion() : "unknown"; + return pluginName + " (Fess " + version + ")"; + } + } + +.. tip:: + + Envisagez d'abord cet « ajout de composant ». À moins qu'il ne soit + nécessaire de modifier une fonctionnalité du cœur, cette approche est + plus sûre et plus facile à maintenir que le remplacement. + +Remplacement d'un composant du cœur (fess+componentName.xml) +-------------------------------------------------------------- + +Si vous souhaitez modifier le comportement d'un composant du cœur de +|Fess|, sous-classez la classe cible et **réenregistrez-la sous le même nom +de composant** dans un fichier de configuration DI nommé +``+.xml``. Par exemple, ``systemHelper`` étant +déclaré dans le fichier ``fess.xml`` de |Fess| lui-même, le fichier de +remplacement sera ``fess+systemHelper.xml`` (et non +``app+systemHelper.xml``). + +.. code-block:: java + + package org.codelibs.fess.webapp.example.helper; + + import java.nio.file.Path; + + import org.codelibs.fess.helper.SystemHelper; + + public class CustomSystemHelper extends SystemHelper { + + @Override + protected void parseProjectProperties(final Path propPath) { + try { + super.parseProjectProperties(propPath); + } catch (final Exception e) { + // Traitement personnalisé + } + System.setProperty("fess.webapp.plugin", "true"); + } + } + +.. warning:: + + Le remplacement (un seul ``+``) remplace **entièrement** la définition + du composant. Pour cette raison, le fichier de remplacement doit + contenir tous les éléments ```` définis par la définition + du cœur (par exemple ``queryHelper`` dans ``app.xml``). Ces éléments + doivent être synchronisés à chaque nouvelle version de |Fess|. Si le + fichier continue d'appeler une méthode supprimée du cœur, + l'initialisation de cette définition de composant échoue avec + ``BeanMethodNotFoundException``. Par exemple, ``addDesignJspFileName`` + de ``systemHelper`` a été supprimé en 15.10, si bien qu'un fichier de + remplacement qui l'appelle échoue. Ce coût de maintenance explique + pourquoi l'ajout est recommandé plutôt que le remplacement. + +Ajout d'une API REST (fess_api++.xml) +--------------------------------------- + +Pour ajouter un nouveau point de terminaison d'API REST, implémentez +``WebApiManager``. Héritez de ``BaseApiManager`` et enregistrez-vous auprès +de ``WebApiManagerFactory`` via ``@PostConstruct``. Le gestionnaire d'API +enregistré est invoqué par ``WebApiFilter`` à chaque requête. Enregistrez +le composant dans ``fess_api++.xml`` : + +.. code-block:: xml + + + + + + + + +.. code-block:: java + + package org.codelibs.fess.webapp.example.api; + + import java.io.IOException; + + import org.codelibs.fess.api.BaseApiManager; + import org.codelibs.fess.util.ComponentUtil; + + import jakarta.annotation.PostConstruct; + import jakarta.servlet.FilterChain; + import jakarta.servlet.ServletException; + import jakarta.servlet.http.HttpServletRequest; + import jakarta.servlet.http.HttpServletResponse; + + public class ExampleApiManager extends BaseApiManager { + + public ExampleApiManager() { + // Préfixe du chemin traité par ce gestionnaire + setPathPrefix("/api/example"); + } + + @PostConstruct + public void register() { + ComponentUtil.getWebApiManagerFactory().add(this); + } + + @Override + public boolean matches(final HttpServletRequest request) { + // Détermine si ce gestionnaire doit traiter la requête + return request.getServletPath().startsWith(pathPrefix); + } + + @Override + public void process(final HttpServletRequest request, final HttpServletResponse response, + final FilterChain chain) throws IOException, ServletException { + // Traitement de la requête et écriture de la réponse + } + + @Override + protected void writeHeaders(final HttpServletResponse response) { + // Configuration des en-têtes de réponse (si nécessaire) + } + } + +Comme exemples d'implémentation, vous pouvez vous référer à +`fess-webapp-v1-api `__, +qui fournit ``/api/v1``, ou à +`fess-webapp-classic-api `__, +qui fournit ``/json`` / ``/suggest``. + +Personnalisation de l'écran de recherche +========================================= + +Les plugins d'application Web ne peuvent pas ajouter de vues JSP. En effet, +les vues JSP sont placées dans ``WEB-INF/view/`` du WAR de |Fess| +lui-même, alors que le JAR du plugin est monté dans le classpath +(``WEB-INF/classes``). Pour modifier le design de l'écran de recherche, +utilisez un thème statique. Le thème statique personnalise le design +(HTML/CSS/JavaScript) de l'écran de recherche. Reportez-vous à +:doc:`theme-development`. + +Build et installation +====================== + +:: + + mvn clean package + +Le fichier JAR (par exemple ``fess-webapp-example-15.10.0.jar``) est généré +dans le répertoire ``target/``. Vous pouvez installer le JAR généré depuis +l'écran d'administration, ou le placer dans le répertoire +``app/WEB-INF/plugin/`` puis redémarrer |Fess|. Pour plus de détails sur la +procédure d'installation, reportez-vous à :doc:`../admin/plugin-guide`. + +Exemples de plugins publiés +============================ + +Le projet |Fess| publie les plugins d'application Web suivants. Ils sont +publiés sur `GitHub `__ comme référence pour +le développement : + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Plugin + - Description + * - ``fess-webapp-example`` + - Modèle d'implémentation de plugin + * - ``fess-webapp-v1-api`` + - API REST ``/api/v1`` + * - ``fess-webapp-classic-api`` + - API REST historique ``/json`` / ``/suggest`` + * - ``fess-webapp-mcp`` + - Serveur MCP (Model Context Protocol) + * - ``fess-webapp-bangs`` + - Bangs de type DuckDuckGo (``!g``) qui envoient une recherche vers un autre site + * - ``fess-webapp-semantic-search`` + - Recherche neuronale / recherche vectorielle (obsolète ; remplacée par l'intégration au + cœur en 15.10) + * - ``fess-webapp-multimodal`` + - Recherche multimodale (image et texte) + +Informations complémentaires +============================= + +- :doc:`plugin-architecture` - Architecture des plugins +- :doc:`theme-development` - Personnalisation des thèmes +- :doc:`../admin/plugin-guide` - Installation des plugins +- :doc:`overview` - Aperçu de la documentation développeur diff --git a/fr/15.10/install/fess-setup.rst b/fr/15.10/install/fess-setup.rst new file mode 100644 index 000000000..f1b9f91ff --- /dev/null +++ b/fr/15.10/install/fess-setup.rst @@ -0,0 +1,348 @@ +==================== +Commande fess-setup +==================== + +``bin/fess-setup`` (``bin\fess-setup.bat`` sous Windows) est fourni avec le package ZIP de |Fess|. +Il installe ce dont |Fess| a besoin sans l'intégrer : OpenSearch avec les plugins requis par +|Fess|, Node.js pour les plugins Playwright, les plugins |Fess| et les thèmes statiques. Il établit également un diagnostic +d'une installation. + +Exécutez-le depuis le répertoire de |Fess|. Sans argument, il affiche la liste des commandes. + +:: + + $ cd /path/to/fess-15.10.0 + $ bin/fess-setup [options] + +Codes de sortie +=============== + +.. list-table:: + :header-rows: 1 + :widths: 15 85 + + * - Code + - Signification + * - ``0`` + - La commande a réussi. + * - ``1`` + - La commande a échoué : par exemple, un téléchargement a échoué, la version demandée n'existe + pas, OpenSearch ne publie pas de version pour cette plateforme, ou ``check`` a détecté un + problème. + * - ``2`` + - La ligne de commande est incorrecte : commande inconnue, ou argument manquant, tel qu'un nom + de plugin. + +Installation d'OpenSearch et de Node.js +========================================= + +install opensearch +------------------ + +:: + + $ bin/fess-setup install opensearch [--dest ] [--version ] [--keep-bundled-plugins] + +Télécharge la version d'OpenSearch prise en charge par ce |Fess| dans ``opensearch/`` du répertoire +de |Fess|, y installe les quatre plugins requis par |Fess| (``opensearch-analysis-fess``, +``opensearch-analysis-extension``, ``opensearch-minhash`` et ``opensearch-configsync``), puis ajoute +les paramètres suivants à son ``config/opensearch.yml`` : + +- ``configsync.config_path``, défini sur le répertoire ``config/dictionary`` de cet OpenSearch +- ``plugins.security.disabled: true`` + +La commande supprime également les plugins fournis ``opensearch-security-analytics`` et +``opensearch-performance-analyzer``, que |Fess| n'utilise pas ; l'OpenSearch de l'image Docker ne +les contient pas non plus. Un plugin absent du téléchargement est ignoré. + +Un paramètre déjà présent dans ``opensearch.yml`` n'est pas ajouté une seconde fois, et +``plugins.security.disabled: true`` n'est pas ajouté lorsque le fichier contient un paramètre +``plugins.security.*``, quel qu'il soit. Lorsque le répertoire d'OpenSearch existe déjà, le +téléchargement est ignoré : exécuter à nouveau la commande sur une installation existante n'ajoute +donc que les paramètres manquants. + +La commande affiche chaque paramètre ajouté, puis indique si ``bin/fess.in.sh`` trouve cet +OpenSearch par lui-même. C'est le cas lorsqu'il s'agit du seul OpenSearch possédant un répertoire +``config/dictionary`` sous ``opensearch/`` dans le répertoire de |Fess| : ``bin/fess.in.sh`` +(``bin\fess.in.bat`` sous Windows) définit alors ``FESS_DICTIONARY_PATH`` sur ce répertoire, et rien +d'autre n'est à configurer pour un OpenSearch situé sur le même hôte. Dans le cas contraire, la +commande affiche les valeurs de ``SEARCH_ENGINE_HTTP_URL`` et de ``FESS_DICTIONARY_PATH`` à définir, +comme décrit dans :doc:`install-linux` ou :doc:`install-windows`. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Option + - Description + * - ``--dest `` + - Répertoire dans lequel extraire OpenSearch, au lieu de ``opensearch/`` dans le répertoire de + |Fess|. ``bin/fess.in.sh`` ne recherche pas OpenSearch en dehors de ce répertoire. + * - ``--version `` + - Version d'OpenSearch à installer. Les plugins sont installés dans la même version. + * - ``--keep-bundled-plugins`` + - Conserve les plugins fournis (``opensearch-security-analytics`` et ``opensearch-performance-analyzer``) au lieu de les supprimer, et laisse le téléchargement tel quel. + +OpenSearch ne publie de versions officielles que pour Linux et Windows. Sur les autres plateformes, +comme macOS, la commande se termine avec le code ``1`` avant tout téléchargement et suggère +d'installer OpenSearch avec Homebrew puis d'ajouter les plugins avec ``install opensearch-plugins``, +ou d'utiliser Docker. + +.. warning:: + + Avec ``plugins.security.disabled: true``, OpenSearch accepte les requêtes sans authentification. + OpenSearch n'écoute que sur l'adresse de bouclage tant que ``network.host`` n'est pas défini. + Avant qu'il n'écoute sur une autre adresse, configurez plutôt le plugin de sécurité ; consultez + :doc:`security`. + +install opensearch-plugins +-------------------------- + +:: + + $ bin/fess-setup install opensearch-plugins --opensearch-home [--version ] + +Installe les quatre plugins requis par |Fess| dans un OpenSearch existant, au lieu d'exécuter quatre +fois son ``bin/opensearch-plugin install``. ``--opensearch-home`` est le répertoire d'installation +d'OpenSearch et est obligatoire. ``--version`` définit la version des plugins, qui doit correspondre +à la version d'OpenSearch. + +Cette commande ne modifie pas ``opensearch.yml``. Ajoutez vous-même ``configsync.config_path`` et +les autres paramètres, comme décrit dans :doc:`install-linux` ou :doc:`install-windows`. + +install nodejs +-------------- + +:: + + $ bin/fess-setup install nodejs [--dest ] [--version ] + +Télécharge Node.js, nécessaire aux plugins Playwright (``fess-crawler-playwright`` pour le robot +Playwright et ``fess-thumbnail-playwright`` pour les vignettes), dans ``nodejs/`` du répertoire de |Fess|. +``bin/fess.in.sh`` (``bin\fess.in.bat`` sous Windows) l'y trouve et définit +``PLAYWRIGHT_NODEJS_PATH``. Avec ``--dest`` en dehors du répertoire de |Fess|, la commande affiche à +la place la ligne ``PLAYWRIGHT_NODEJS_PATH`` à ajouter à ``bin/fess.in.sh``. ``--version`` permet de +choisir une autre version de Node.js. Consultez :doc:`../config/crawler-advanced` pour le robot +Playwright. + +Gestion des plugins +=================== + +Ces commandes agissent sur le répertoire des plugins ``app/WEB-INF/plugin`` de l'installation de +|Fess|. Redémarrez |Fess| après avoir installé, mis à niveau ou supprimé des plugins. Les plugins +peuvent aussi être gérés depuis la page **Système > Plugin** de l'écran d'administration ; consultez +:doc:`../admin/plugin-guide`. + +``install plugin``, ``list plugins``, ``list installed``, ``upgrade plugins``, ``remove plugin`` et ``check`` acceptent ``--dest ``. Il désigne le répertoire de plugins à utiliser à la place de ``app/WEB-INF/plugin`` : le répertoire qui contient lui-même les jars des plugins, et non son parent. Un chemin relatif est résolu à partir du répertoire courant, et non du répertoire de |Fess|. Pour ``install opensearch`` et ``install nodejs``, en revanche, ``--dest`` est le répertoire dans lequel l'archive est extraite. + +``install plugin``, ``list plugins`` et ``upgrade plugins`` acceptent ``--repository ``. Cette +option prend la liste des versions, les jars et leurs sommes de contrôle dans ce seul dépôt Maven, +par exemple un miroir interne, au lieu des dépôts release et snapshot par défaut et de GitHub. + +``--repository`` accepte aussi une URL qui commence par ``file:///``. Sur un serveur sans accès à +Internet, placez une copie du dépôt Maven sur le serveur et indiquez ce répertoire. Indiquez le +répertoire qui contient le répertoire de chaque plugin (``/maven-metadata.xml``, etc.), c'est-à-dire +l'emplacement qui correspond à ``https://maven.codelibs.org/release/org/codelibs/fess/`` du dépôt par +défaut. Les versions sont résolues et les sommes de contrôle vérifiées de la même façon qu'avec un dépôt +HTTP. + +:: + + $ bin/fess-setup install plugin fess-ds-csv --repository file:///opt/maven-repo/org/codelibs/fess/ + +Un schéma autre que ``http``, ``https`` et ``file``, ou une URL sans schéma, est refusé avec une erreur +d'une ligne. + +install plugin +-------------- + +:: + + $ bin/fess-setup install plugin [:]... [--version ] [--repository ] [--dest ] + +Installe un ou plusieurs plugins |Fess|, par exemple ``fess-script-groovy`` ou ``fess-ds-git``. Un +nom sans version installe la version la plus récente compilée pour ce |Fess|. +``:`` fige la version de ce plugin, et ``--version`` est la version de chaque nom qui +n'en indique pas. La version précédemment installée d'un plugin est supprimée une fois la nouvelle +installée. + +Un jar provient de la release GitHub du plugin, ou du dépôt Maven lorsque la release ne contient pas +ce fichier, et est vérifié avec la somme de contrôle SHA-1 publiée par le dépôt Maven. Une version +de développement de |Fess| installe aussi les builds snapshot de sa propre ligne, et les privilégie. + +Consultez :doc:`../admin/plugin-guide` pour des exemples. + +Seuls les types de plugins que |Fess| charge peuvent être installés : les noms qui commencent par +``fess-ds-``, ``fess-ingest-``, ``fess-script-``, ``fess-webapp-``, ``fess-thumbnail-``, +``fess-crawler-``, ``fess-llm-``, ``fess-storage-`` ou ``fess-sso-``, c'est-à-dire ceux qu'affiche +``list plugins``. Tout autre nom (``fess-theme-*``, ou une bibliothèque comme ``fess`` ou +``fess-crawler``) est refusé avec une erreur d'une ligne et le code de sortie 2, avant tout +téléchargement. Si l'un de plusieurs noms est refusé, aucun n'est installé. Installez un thème +statique avec ``install theme``. + +list plugins +------------ + +:: + + $ bin/fess-setup list plugins [--repository ] [--dest ] + +Liste les plugins publiés pour ce |Fess| et signale ceux qui sont installés par +``(installed: )``. Les plugins installés mais non publiés dans le dépôt, comme un jar +compilé localement, sont listés à part. Une version de développement de |Fess| consulte aussi le +dépôt snapshot. + +list installed +-------------- + +:: + + $ bin/fess-setup list installed [--dest ] + +Liste les plugins installés et leurs versions, sans contacter le dépôt. + +upgrade plugins +--------------- + +:: + + $ bin/fess-setup upgrade plugins [--repository ] [--dest ] + +Réinstalle chaque plugin installé dans la version adaptée à ce |Fess|. Un plugin qui est déjà dans +cette version est laissé tel quel. Les plugins de ``app/WEB-INF/plugin`` sont compilés pour une +version précise de |Fess| : exécutez donc cette commande après une mise à niveau de |Fess|. + +remove plugin +------------- + +:: + + $ bin/fess-setup remove plugin ... [--dest ] + +Supprime les jars installés des plugins indiqués. Un nom qui n'est pas installé est signalé, sans +modifier le code de sortie. + +.. _fess-setup-offline: + +Environnements sans accès à Internet +------------------------------------ + +``install plugin``, ``list plugins`` et ``upgrade plugins`` récupèrent les plugins depuis des dépôts +sur Internet. L'écran d'installation de la page Système > Plugin de l'écran d'administration obtient +lui aussi la liste des plugins installables depuis les dépôts (``plugin.repositories``) ; il ne peut +donc pas afficher cette liste dans un environnement sans accès à l'extérieur. + +Dans un tel environnement, apportez les jars des plugins et installez-les ainsi : + +1. Dans un environnement ayant accès à Internet, téléchargez le paquet ZIP de |Fess| et les jars des + plugins nécessaires. Les jars sont disponibles à l'adresse + ``https://maven.codelibs.org/release/org/codelibs/fess///-.jar``. + Choisissez la version correspondant à ce |Fess| (15.10.x pour |Fess| 15.10). +2. Dans l'environnement cible, décompressez le ZIP et placez les jars dans ``app/WEB-INF/plugin/``. + Vous pouvez aussi les téléverser, une fois |Fess| démarré, depuis l'onglet « Local » de l'écran + d'installation des plugins de l'écran d'administration (voir :doc:`../admin/plugin-guide`). +3. Démarrez |Fess|. Si vous avez placé les jars pendant que |Fess| était en cours d'exécution, + redémarrez-le. + +Au lieu d'apporter chaque jar, vous pouvez aussi copier la partie nécessaire du dépôt Maven (les +répertoires ``org/codelibs/fess//``) sur le serveur et installer avec ``install plugin`` et +``--repository file:///...``. Les sommes de contrôle sont vérifiées dans ce cas aussi. + +Gestion des thèmes +================== + +Ces commandes agissent sur le répertoire de thèmes ``app/themes`` de l'installation |Fess|. +Redémarrez |Fess| après avoir installé ou supprimé un thème, ou cliquez sur [Recharger] dans la +page Système > Thème. Les thèmes peuvent aussi être téléversés depuis cette page ; voir +:doc:`../admin/theme-guide`. + +``install theme``, ``list themes`` et ``remove theme`` acceptent ``--dest `` de la même manière et désignent le répertoire de thèmes à utiliser à la place de ``app/themes``. + +La version d'un thème indique la ligne |Fess| qu'il vise : ``15.10.0`` est un thème pour +|Fess| 15.10. Un nom sans version est donc résolu vers le thème construit pour ce |Fess|, comme +pour un plugin. + +install theme +------------- + +:: + + $ bin/fess-setup install theme [:]... [--version ] [--repository ] [--dest ] + +Installe un ou plusieurs thèmes statiques, par exemple ``docuforge`` ou ``voicebox``. Un nom sans +version installe la plus récente construite pour ce |Fess|. ``:`` fige la version +de ce thème, et ``--version`` s'applique à tous les noms qui n'en portent pas. + +L'archive est vérifiée contre la somme SHA-1 publiée par le dépôt Maven, puis extraite dans +``app/themes/``. Un thème déjà installé sous ce nom est conservé en sauvegarde pendant la +même durée qu'un thème remplacé depuis l'écran d'administration (7 jours par défaut, +``theme.upload.attic.retention.days``). + +Le téléchargement, l'extraction et la vérification du manifeste ont tous lieu avant que quoi que +ce soit d'installé ne soit touché : un thème déjà présent survit à une installation qui échoue. +Une archive dont le ``theme.yml`` nomme un autre thème est refusée. + +list themes +----------- + +:: + + $ bin/fess-setup list themes [--repository ] [--dest ] + +Liste les thèmes publiés pour ce |Fess| et marque ceux qui sont installés avec +``(installed: )``. Les thèmes installés que le dépôt ne liste pas apparaissent à part. + +Cette liste provient de l'index de répertoire du dépôt, qui est généré périodiquement. Lorsqu'il +ne peut pas être lu, la commande indique l'URL essayée et liste tout de même les thèmes installés : +un thème s'installe en le nommant, que l'index le référence ou non. + +remove theme +------------ + +:: + + $ bin/fess-setup remove theme ... [--dest ] + +Supprime de ``app/themes`` les thèmes indiqués, en conservant chacun en sauvegarde pendant la +durée de rétention. Un nom qui n'est pas installé est signalé et ne change pas le code de sortie. + +Si un thème supprimé était le thème par défaut, |Fess| revient au thème ``bootstrap`` fourni +jusqu'à ce qu'un autre soit choisi. + +Vérification d'une installation +================================= + +list +---- + +:: + + $ bin/fess-setup list + +Affiche les composants que ``install`` télécharge, ``opensearch`` et ``nodejs``, avec la version de +chacun. + +check +----- + +:: + + $ bin/fess-setup check [--url ] [--playwright] [--dest ] + +Établit un diagnostic de l'installation, une ligne par vérification, chacune marquée ``OK``, +``WARN`` ou ``FAIL`` : + +- Le moteur de recherche : s'il est joignable, sa version (un avertissement lorsque les nœuds + indiquent des versions différentes), si les quatre plugins requis par |Fess| y sont installés, et + si ``configsync`` répond. +- |Fess| : si le répertoire des plugins existe et est accessible en écriture, chaque plugin installé + (un échec pour un plugin compilé pour une autre version de |Fess| et pour un plugin installé en + deux versions), et si Node.js est installé dans ``nodejs/`` du répertoire de |Fess|. + +L'URL du moteur est ``--url``, sinon la variable d'environnement ``SEARCH_ENGINE_HTTP_URL``, sinon +``http://localhost:9200``. ``bin/fess-setup`` ne lit pas ``bin/fess.in.sh`` : indiquez donc +``--url`` lorsqu'OpenSearch se trouve ailleurs. L'absence de Node.js est seulement signalée, sauf si +``--playwright`` est indiqué, auquel cas elle constitue un échec. + +La commande se termine avec le code ``0`` lorsqu'aucune vérification n'a échoué, même si certaines +ont produit des avertissements, et avec le code ``1`` sinon. diff --git a/fr/15.10/install/index.rst b/fr/15.10/install/index.rst new file mode 100644 index 000000000..de7741229 --- /dev/null +++ b/fr/15.10/install/index.rst @@ -0,0 +1,25 @@ +Guide d'Installation de |Fess| +=============================== + +Comment installer et démarrer |Fess| sous Linux, Windows ou Docker, +avec les prérequis, les réglages de sécurité, la mise à niveau et le +dépannage. + +.. toctree:: + :maxdepth: 2 + :caption: Table des matières + + intro + prerequisites + install + install-linux + install-windows + install-docker + fess-setup + run + security + upgrade + uninstall + troubleshooting + + diff --git a/fr/15.10/install/install-docker.rst b/fr/15.10/install/install-docker.rst new file mode 100644 index 000000000..2bc8e6274 --- /dev/null +++ b/fr/15.10/install/install-docker.rst @@ -0,0 +1,609 @@ +================================== +Installation avec Docker (Détails) +================================== + +Cette page décrit la procédure d'installation de |Fess| à l'aide de Docker et Docker Compose. +L'utilisation de Docker vous permet de construire un environnement |Fess| facilement et rapidement. + +Prérequis +========= + +- La configuration requise décrite dans :doc:`prerequisites` doit être satisfaite +- Docker 20.10 ou ultérieur doit être installé +- Docker Compose 2.0 ou ultérieur doit être installé + +Vérification de l'installation de Docker +========================================= + +Vérifiez les versions de Docker et Docker Compose avec les commandes suivantes. + +:: + + $ docker --version + $ docker compose version + +.. note:: + + Si vous utilisez une ancienne version de Docker Compose, utilisez la commande ``docker-compose``. + Ce document utilise le nouveau format de commande ``docker compose``. + +À propos des images Docker +=========================== + +Lorsque vous démarrez |Fess| avec Docker Compose, les deux conteneurs suivants fonctionnent : + +- **Fess** (``fess01``) : système de recherche plein texte principal +- **OpenSearch** (``search01``) : moteur de recherche + +Les images Docker officielles sont publiées sur `GitHub Container Registry `__. +Les fichiers Compose et la procédure de démarrage sont gérés dans le dépôt `docker-fess `__. + +Étape 1 : Obtention des fichiers Docker Compose +================================================ + +Pour le démarrage avec Docker Compose, les fichiers suivants sont nécessaires. + +Méthode 1 : Téléchargement individuel des fichiers +--------------------------------------------------- + +Téléchargez les fichiers suivants : + +:: + + $ mkdir fess-docker + $ cd fess-docker + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose.yaml + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose-opensearch3.yaml + +Méthode 2 : Clonage du dépôt avec Git +-------------------------------------- + +Si Git est installé, vous pouvez également cloner l'ensemble du dépôt : + +:: + + $ git clone --depth 1 --branch v15.10.0 https://github.com/codelibs/docker-fess.git + $ cd docker-fess/compose + +Étape 2 : Vérification des fichiers Docker Compose +=================================================== + +Contenu de ``compose.yaml`` +---------------------------- + +``compose.yaml`` contient la configuration de Fess lui-même (service ``fess01``). + +Principaux paramètres : + +- **Numéro de port** : port de l'interface Web de Fess (par défaut : 8080) +- **Variables d'environnement** : destination de connexion à OpenSearch (``SEARCH_ENGINE_HTTP_URL``), chemin du fichier de dictionnaire (``FESS_DICTIONARY_PATH``), etc. +- **Ordre de démarrage** : ``depends_on`` est configuré pour que le démarrage n'ait lieu qu'une fois qu'OpenSearch (``search01``) est dans un état sain + +Contenu de ``compose-opensearch3.yaml`` +---------------------------------------- + +``compose-opensearch3.yaml`` contient la configuration du moteur de recherche (service ``search01``, OpenSearch). + +Principaux paramètres : + +- **Image OpenSearch** : image OpenSearch utilisée (``ghcr.io/codelibs/fess-opensearch``) +- **Configuration mémoire** : taille du tas JVM +- **Volumes** : volumes de persistance des données (``search01_data`` : données d'index, ``search01_dictionary`` : fichiers de dictionnaire) + +Personnalisation de la configuration (optionnel) +------------------------------------------------- + +Pour modifier la configuration par défaut, éditez ``compose.yaml``. + +Exemple : pour modifier le numéro de port :: + + services: + fess01: + ports: + - "9080:8080" # Mappage sur le port 9080 de l'hôte + +Exemple : pour modifier la configuration mémoire :: + + services: + fess01: + environment: + - "FESS_HEAP_SIZE=2g" # Définir la taille du tas de Fess à 2 Go + +Types d'images et vignettes +--------------------------- + +Les images Docker de |Fess| existent en plusieurs types, qui se distinguent par un suffixe de tag (``-noble``, ``-al2023``, etc.). L'image par défaut sans suffixe (basée sur Alpine) ne contient pas les outils externes qui créent les vignettes des images, des fichiers PDF et des documents Office (ImageMagick, poppler-utils, unoconv et LibreOffice). Avec cette image, seules les pages HTML ont une vignette ; aucune vignette n'est générée pour les images, les fichiers PDF ni les documents Office. + +Si vous avez besoin de ces vignettes, indiquez dans ``image`` de ``compose.yaml`` un tag avec le suffixe ``-noble``, qui inclut les outils. + +:: + + services: + fess01: + image: ghcr.io/codelibs/fess:15.10.0-noble + +Le tableau suivant indique ce que prend en charge chaque image. + +.. list-table:: + :header-rows: 1 + :widths: 40 30 30 + + * - Tag + - Images et PDF + - Documents Office + * - ``15.10.0-noble`` + - Générée + - Générée + * - ``15.10.0-al2023`` + - Générée + - Non générée + * - ``15.10.0``, ``15.10.0-slim``, ``15.10.0-slim-noble``, ``15.10.0-slim-al2023`` + - Non générée + - Non générée + +Quelle que soit l'image, la vignette d'une page HTML est créée à partir d'une image de la page. Pour afficher les vignettes, activez aussi l'affichage des vignettes dans les paramètres généraux de l'interface d'administration. Voir :doc:`../config/crawler-thumbnail` pour plus de détails. + +Étape 3 : Démarrage des conteneurs Docker +========================================== + +Démarrage de base +------------------ + +Démarrez Fess et OpenSearch avec la commande suivante : + +:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +.. note:: + + - L'option ``-f`` permet de spécifier plusieurs fichiers Compose + - L'option ``-d`` permet d'exécuter en arrière-plan + +Vérification des logs de démarrage :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f + +Vous pouvez terminer l'affichage des logs avec ``Ctrl+C``. + +Vérification du démarrage +--------------------------- + +Vérifiez l'état des conteneurs :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps + +Vérifiez que les conteneurs suivants sont en cours d'exécution : + +- ``fess01`` +- ``search01`` + +.. tip:: + + Le démarrage peut prendre quelques minutes. OpenSearch (``search01``) doit d'abord atteindre un état sain avant que Fess (``fess01``) ne démarre. + Vérifiez l'état de chaque conteneur avec ``docker compose ... ps`` ; une fois que ``fess01`` a démarré, vous pouvez accéder à http://localhost:8080/ dans votre navigateur. + +Étape 4 : Accès via un navigateur +================================== + +Une fois le démarrage terminé, accédez aux URL suivantes : + +- **Écran de recherche** : http://localhost:8080/ +- **Écran d'administration** : http://localhost:8080/admin + +L'écran de recherche est ``bootstrap``, le thème statique fourni avec |Fess|. Pour modifier son apparence, +consultez :doc:`../admin/theme-guide`. + +Compte administrateur par défaut : + +- Nom d'utilisateur : ``admin`` +- Mot de passe : ``admin`` + +.. warning:: + + **Note importante sur la sécurité** + + En environnement de production, veuillez obligatoirement changer le mot de passe administrateur. + Pour plus de détails, consultez :doc:`security`. + +Activation du mode de recherche IA (plugins LLM) +================================================= + +Depuis |Fess| 15.10, la fonctionnalité de mode de recherche IA (RAG Chat) a été séparée sous forme de plugins ``fess-llm-*``. +Le dépôt officiel `docker-fess `__ inclut des fichiers overlay pour les principaux fournisseurs de LLM. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Overlay + - Usage + * - ``compose-ollama.yaml`` + - Ollama (LLM local, démarre un service ``ollama01`` supplémentaire) + * - ``compose-gemini.yaml`` + - Google Gemini (API cloud) + * - ``compose-openai.yaml`` + - OpenAI (API cloud) + +Chaque overlay récupère automatiquement le plugin correspondant via ``FESS_PLUGINS`` et active RAG Chat en définissant +``-Dfess.config.rag.chat.enabled=true`` dans ``FESS_JAVA_OPTS``. +Pour Gemini et OpenAI, qui font appel à une API cloud, le fournisseur à utiliser est en outre spécifié via ``-Dfess.system.rag.llm.name``, +et la clé API (``rag.llm..api.key``) ainsi que le modèle (``rag.llm..model``) sont configurés. +Pour Ollama, la valeur par défaut de ``rag.llm.name`` (``ollama``) est utilisée telle quelle, sans spécification explicite, +et la destination de connexion (``rag.llm.ollama.api.url``) est configurée. + +Exemple d'utilisation de Gemini :: + + $ export GEMINI_API_KEY="AIzaSy..." + $ docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-gemini.yaml up -d + +Exemple d'utilisation d'OpenAI :: + + $ export OPENAI_API_KEY="sk-..." + $ docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-openai.yaml up -d + +.. note:: + + Le modèle utilisé peut être modifié via les variables d'environnement ``GEMINI_MODEL`` et ``OPENAI_MODEL`` + (les valeurs par défaut sont respectivement ``gemini-2.5-flash`` et ``gpt-5-mini``). + +Exemple d'utilisation d'Ollama :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-ollama.yaml up -d + $ docker exec -it ollama01 ollama pull gpt-oss:20b + +.. warning:: + + Le service ``ollama01`` de ``compose-ollama.yaml`` est configuré par défaut pour utiliser un GPU NVIDIA + (le `NVIDIA Container Toolkit `__ est requis). + Si vous exécutez ce service dans un environnement sans GPU, supprimez ou commentez le bloc ``deploy:`` de ``compose-ollama.yaml`` (la spécification du GPU sous ``reservations``). + +.. tip:: + + Après le démarrage, l'écran de configuration « Système > Général » de l'écran d'administration permet de modifier + le fournisseur LLM utilisé (``rag.llm.name``) ainsi que les paramètres spécifiques à chaque fournisseur. Cependant, ces + modifications sont enregistrées dans le fichier de configuration à l'intérieur du conteneur et seront perdues si le + conteneur est recréé (``docker compose down`` suivi de ``up``). + Pour rendre la configuration persistante, spécifiez-la via ``FESS_JAVA_OPTS`` dans le fichier Compose, comme dans les exemples ci-dessus. + +Persistance des données +======================== + +Toutes les données de |Fess| (index, documents explorés, informations utilisateur, configuration, etc.) sont stockées dans OpenSearch. +Ces données sont persistées dans les volumes d'OpenSearch, de sorte qu'elles sont conservées même après la suppression des conteneurs. +Le conteneur de Fess lui-même (``fess01``) est sans état et ne dispose d'aucun volume dédié. + +Vérification des volumes :: + + $ docker volume ls + +Principaux volumes définis dans ``compose-opensearch3.yaml`` : + +- ``search01_data`` : données d'index d'OpenSearch (contenant l'ensemble des données de Fess) +- ``search01_dictionary`` : fichiers de dictionnaire + +.. note:: + + Les noms de volumes de Docker Compose sont préfixés par le nom du projet (par défaut, le nom du répertoire contenant le fichier Compose). + Par exemple, si le démarrage a été effectué dans le répertoire ``compose``, le nom réel du volume sera de la forme ``compose_search01_data``. + +.. important:: + + Les volumes ne sont pas supprimés même si les conteneurs sont supprimés. + Pour supprimer les volumes, vous devez exécuter explicitement la commande ``docker volume rm``. + +Arrêt des conteneurs Docker +============================ + +Arrêt des conteneurs :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop + +Arrêt et suppression des conteneurs :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +.. warning:: + + La commande ``down`` supprime les conteneurs, mais pas les volumes. + Si vous souhaitez également supprimer les volumes (tels que ``search01_data``), ajoutez l'option ``-v`` :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down -v + + **Attention** : l'exécution de cette commande supprime toutes les données stockées dans OpenSearch. + +Configuration avancée +====================== + +Personnalisation des variables d'environnement +------------------------------------------------- + +En ajoutant ou en modifiant des variables d'environnement dans ``compose.yaml``, vous pouvez effectuer une configuration détaillée. + +Principales variables d'environnement : + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Variable d'environnement + - Description + * - ``FESS_HEAP_SIZE`` + - Taille du tas JVM de Fess (valeur par défaut de l'image Docker : 512m) + * - ``FESS_JAVA_OPTS`` + - Spécification d'options JVM supplémentaires (par exemple pour remplacer des paramètres via ``-Dfess.config.*``) + * - ``FESS_PLUGINS`` + - Plugins installés automatiquement au démarrage (format ``name:version`` séparés par des espaces. Exemple : ``fess-ds-wikipedia:15.10.0``) + * - ``SEARCH_ENGINE_HTTP_URL`` + - Point de terminaison HTTP d'OpenSearch (valeur par défaut dans ``compose.yaml`` : ``http://search01:9200``) + * - ``SEARCH_ENGINE_TYPE`` + - Le type de moteur de recherche (``default``, ``vanilla`` ou ``aws``). ``vanilla`` nécessite une image de Fess 15.10 ou ultérieure ; avec des images plus anciennes, utilisez ``cloud`` (voir :doc:`../config/search-engine-type`). Avec les images 15.8, seule la variante ``-noble`` transmet la valeur à Fess. + * - ``SEARCH_ENGINE_USERNAME`` / ``SEARCH_ENGINE_PASSWORD`` + - Informations d'identification pour se connecter à un OpenSearch avec authentification activée + * - ``FESS_DICTIONARY_PATH`` + - Chemin du fichier de dictionnaire (répertoire partagé avec OpenSearch) + * - ``FESS_PORT`` + - Port sur lequel Fess écoute à l'intérieur du conteneur (valeur par défaut : 8080) + +Exemple :: + + services: + fess01: + environment: + - "FESS_HEAP_SIZE=4g" + +.. note:: + + Pour changer le fuseau horaire, spécifiez-le dans ``FESS_JAVA_OPTS``, par exemple ``-Duser.timezone=Asia/Tokyo``. + +Comment appliquer les fichiers de configuration +------------------------------------------------- + +Les paramètres détaillés de |Fess| sont décrits dans le fichier ``fess_config.properties``. +Dans l'image Docker, ``fess_config.properties`` se trouve dans ``/etc/fess`` à l'intérieur du conteneur. +Voici les méthodes disponibles pour appliquer la configuration dans un environnement Docker. + +Méthode 1 : Monter le fichier de configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``/etc/fess`` contient également d'autres fichiers de configuration nécessaires au fonctionnement de Fess ; remplacer directement ce répertoire par un montage entraîne un échec du démarrage. +Utilisez à la place le répertoire de substitution ``/opt/fess``, qui est ajouté en tête du classpath (il est vide au départ). + +1. Créez, côté hôte, un répertoire destiné à contenir le fichier de configuration :: + + $ mkdir -p /path/to/fess-config + +2. Récupérez le modèle du fichier de configuration (uniquement la première fois) :: + + $ curl -o /path/to/fess-config/fess_config.properties https://raw.githubusercontent.com/codelibs/fess/refs/tags/fess-15.10.0/src/main/resources/fess_config.properties + +3. Modifiez ``/path/to/fess-config/fess_config.properties`` pour y décrire les paramètres nécessaires :: + + # Exemple + crawler.document.cache.enabled=false + adaptive.load.control=20 + query.facet.fields=label,host + +4. Ajoutez un montage de volume au service ``fess01`` dans ``compose.yaml`` :: + + services: + fess01: + volumes: + - /path/to/fess-config/fess_config.properties:/opt/fess/fess_config.properties + +5. Démarrez le conteneur :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +.. note:: + + ``/opt/fess`` étant ajouté en tête du classpath, le fichier ``fess_config.properties`` placé ici est prioritaire + par rapport à celui fourni avec l'image, ``/etc/fess/fess_config.properties``. + Les fichiers de propriétés sont chargés fichier par fichier et ne sont pas fusionnés élément par élément. + Un élément absent de votre fichier n'empêche pas |Fess| de démarrer : la valeur par défaut fournie avec sa version est utilisée et un avertissement par élément est consigné dans les logs. + Un fichier ne contenant que les éléments à modifier fonctionne donc aussi. Pour éviter ces avertissements, partez du fichier complet, comme à l'étape 2. + Si vous souhaitez ne modifier que certains éléments, utilisez la « Méthode 2 » ci-dessous. + Si un élément est défini à la fois dans ce fichier et avec ``-Dfess.config.`` (Méthode 2), la valeur définie avec ``-D`` est utilisée. + +Méthode 2 : Configuration via propriétés système +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Vous pouvez remplacer les paramètres de ``fess_config.properties`` sous forme de propriétés système, via des variables d'environnement. + +Les paramètres décrits dans ``fess_config.properties`` (par exemple ``crawler.document.cache.enabled=false``) sont spécifiés +au format ``-Dfess.config.nom_du_paramètre=valeur``. + +Ajoutez ``FESS_JAVA_OPTS`` aux variables d'environnement du service ``fess01`` dans ``compose.yaml`` :: + + services: + fess01: + environment: + - "FESS_JAVA_OPTS=-Dfess.config.crawler.document.cache.enabled=false -Dfess.config.adaptive.load.control=20 -Dfess.config.query.facet.fields=label,host" + +.. note:: + + La partie qui suit ``-Dfess.config.`` correspond au nom du paramètre dans ``fess_config.properties``. + Cette méthode est plus simple si vous souhaitez ne remplacer que certains éléments. + +Connexion à un OpenSearch externe +------------------------------------ + +Si vous souhaitez utiliser un cluster OpenSearch existant, démarrez uniquement avec ``compose.yaml`` sans utiliser ``compose-opensearch3.yaml``, et modifiez la destination de connexion. + +1. Démarrez sans spécifier ``compose-opensearch3.yaml`` :: + + $ docker compose -f compose.yaml up -d + +2. Configurez la destination de connexion dans le service ``fess01`` de ``compose.yaml`` :: + + environment: + - "SEARCH_ENGINE_HTTP_URL=http://your-opensearch-host:9200" + +.. note:: + + Si vous vous connectez à un OpenSearch avec authentification activée, spécifiez également ``SEARCH_ENGINE_USERNAME`` et ``SEARCH_ENGINE_PASSWORD``. + +Autres overlays et configurations +------------------------------------ + +Le dépôt ``docker-fess`` contient également, en plus de ceux mentionnés ci-dessus, d'autres fichiers Compose et répertoires spécifiques à certains usages. + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Fichier / Répertoire + - Usage + * - ``compose-dashboards3.yaml`` + - Ajoute OpenSearch Dashboards (port 5601, pour la visualisation des données) + * - ``compose-minio.yaml`` + - Ajoute MinIO (stockage objet) et l'utilise comme destination de stockage pour la fonctionnalité de stockage de Fess + * - ``vanilla/`` + - Configuration combinée avec un OpenSearch standard sans les plugins CodeLibs (``SEARCH_ENGINE_TYPE=vanilla`` ; nécessite une image de Fess 15.10 ou ultérieure, avec des images plus anciennes utilisez ``cloud``). Certaines fonctionnalités, comme la gestion du dictionnaire, ne sont pas disponibles (voir :doc:`../config/search-engine-type`) + * - ``snapshot/`` + - Configuration utilisant des images de développement (snapshot) (inclut une configuration en cluster et une combinaison avec Elasticsearch 8) + * - ``multi-instance/`` + - Configuration démarrant plusieurs instances de Fess partageant un seul OpenSearch + +Configuration du réseau Docker +--------------------------------- + +Si vous devez intégrer plusieurs services, vous pouvez utiliser un réseau personnalisé. + +Exemple :: + + networks: + fess-network: + driver: bridge + + services: + fess01: + networks: + - fess-network + +Exploitation en production avec Docker Compose +=============================================== + +Configuration recommandée pour l'utilisation de Docker Compose en environnement de production : + +1. **Configuration des limitations de ressources** :: + + deploy: + resources: + limits: + cpus: '2.0' + memory: 4G + reservations: + cpus: '1.0' + memory: 2G + +2. **Configuration de la politique de redémarrage** :: + + restart: unless-stopped + +3. **Configuration des logs** :: + + logging: + driver: "json-file" + options: + max-size: "10m" + max-file: "3" + +4. **Activation de la configuration de sécurité** + + Activez le plugin de sécurité d'OpenSearch et configurez une authentification appropriée. + Pour plus de détails, consultez :doc:`security`. + +Dépannage +========= + +Le conteneur ne démarre pas +---------------------------- + +1. Vérification des logs :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs + +2. Vérification des conflits de ports :: + + $ sudo ss -tuln | grep 8080 + $ sudo ss -tuln | grep 9200 + +3. Vérification de l'espace disque :: + + $ df -h + +Erreur de mémoire insuffisante +------------------------------- + +Si OpenSearch ne démarre pas en raison d'une mémoire insuffisante, vous devez augmenter ``vm.max_map_count``. + +Pour Linux :: + + $ sudo sysctl -w vm.max_map_count=262144 + +Pour une configuration permanente :: + + $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf + $ sudo sysctl -p + +Initialisation des données +--------------------------- + +Pour supprimer toutes les données et revenir à l'état initial :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down -v + $ docker volume prune + +.. warning:: + + L'exécution de cette commande supprimera complètement toutes les données. + +Étapes suivantes +================ + +Une fois l'installation terminée, consultez les documents suivants : + +- :doc:`run` - Démarrage de |Fess| et configuration initiale +- :doc:`security` - Configuration de la sécurité pour les environnements de production +- :doc:`troubleshooting` - Dépannage + +Questions fréquemment posées +============================= + +Q : Quel espace disque est nécessaire pour le téléchargement des images ? +--------------------------------------------------------------------------- + +R : Les images de Fess et d'OpenSearch sont téléchargées lors du premier démarrage et nécessitent au total quelques Go d'espace disque. +Le téléchargement peut prendre du temps selon l'environnement réseau. + +Q : Est-il possible d'exploiter Fess sur Kubernetes ? +-------------------------------------------------------- + +R : Oui, c'est possible. Vous pouvez convertir les fichiers Docker Compose en manifestes Kubernetes à l'aide d'un outil tel que ``kompose``, +ou créer vos propres manifestes pour l'exploitation (aucun chart Helm officiel n'est fourni). + +Q : Comment effectuer les mises à jour des conteneurs ? +----------------------------------------------------------- + +R : Suivez la procédure suivante pour les mises à jour : + +1. Obtenir les derniers fichiers Compose +2. Arrêter les conteneurs :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +3. Obtenir les nouvelles images :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull + +4. Démarrer les conteneurs :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +Q : Une configuration multi-nœuds est-elle possible ? +-------------------------------------------------------- + +R : Oui, c'est possible. Vous pouvez vous appuyer sur ``snapshot/compose-cluster.yaml`` du dépôt ``docker-fess`` pour configurer OpenSearch avec plusieurs nœuds, +ou sur ``multi-instance/`` pour configurer plusieurs instances de Fess partageant un seul OpenSearch. +Cependant, pour les environnements de production, nous recommandons l'utilisation d'outils d'orchestration tels que Kubernetes. diff --git a/fr/15.10/install/install-linux.rst b/fr/15.10/install/install-linux.rst new file mode 100644 index 000000000..933be3ec2 --- /dev/null +++ b/fr/15.10/install/install-linux.rst @@ -0,0 +1,563 @@ +================================================ +Installation sur Linux (Procédure détaillée) +================================================ + +Cette page décrit la procédure d'installation de |Fess| sur un environnement Linux. +Elle prend en charge les formats de packages ZIP, RPM et DEB. + +.. note:: + + |Fess| n'intègre pas de moteur de recherche. Un serveur OpenSearch est nécessaire ; + les étapes ci-dessous le mettent en place. + +Prérequis +========= + +- La configuration requise décrite dans :doc:`prerequisites` doit être satisfaite +- Java 21 doit être installé +- OpenSearch 3.9.0 doit être disponible (ou nouvelle installation) + +Choix de la méthode d'installation +=================================== + +Pour les environnements Linux, vous pouvez choisir parmi les méthodes d'installation suivantes : + +.. list-table:: + :header-rows: 1 + :widths: 20 40 40 + + * - Méthode + - Environnement recommandé + - Caractéristiques + * - ZIP + - Environnement de développement, environnement nécessitant une personnalisation + - Peut être déployé dans un répertoire arbitraire + * - RPM + - Systèmes RHEL, CentOS, Fedora + - Gestion des services possible avec systemd + * - DEB + - Systèmes Debian, Ubuntu + - Gestion des services possible avec systemd + +Configuration système pour l'exécution d'OpenSearch +===================================================== + +Pour qu'OpenSearch fonctionne de manière stable sous Linux, configurez les paramètres du noyau et les limites de ressources suivants. +Ces réglages sont principalement nécessaires pour la version TAR.GZ (lorsque OpenSearch est installé manuellement). +Avec les versions RPM / DEB, les packages OpenSearch et |Fess| configurent notamment le nombre de descripteurs de fichiers via systemd, mais comme ``vm.max_map_count`` est un paramètre du noyau côté hôte, vérifiez-le quelle que soit la méthode utilisée. + +Nombre maximal de mappages de mémoire virtuelle +------------------------------------------------ + +OpenSearch utilise un grand nombre de mappages mémoire ; définissez donc ``vm.max_map_count`` à ``262144`` ou plus. + +Pour une configuration temporaire :: + + $ sudo sysctl -w vm.max_map_count=262144 + +Pour une configuration permanente :: + + $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf + $ sudo sysctl -p + +Nombre de descripteurs de fichiers +------------------------------------ + +Lorsque vous exécutez OpenSearch manuellement (version TAR.GZ), définissez la limite du nombre de descripteurs de fichiers de l'utilisateur exécutant OpenSearch à ``65535`` ou plus. + +Ajoutez ce qui suit dans ``/etc/security/limits.conf`` (remplacez ``opensearch`` par le nom de l'utilisateur exécutant OpenSearch) :: + + opensearch - nofile 65535 + +.. note:: + + Avec les versions RPM / DEB, cette configuration n'est pas nécessaire, car la limite du nombre de descripteurs de fichiers est définie dans la définition du service systemd. + +Installation avec la version ZIP +===================================== + +Étape 1 : Installation d'OpenSearch +-------------------------------------- + +.. important:: + + Installez et exécutez OpenSearch avec un utilisateur ordinaire, et non en tant que ``root`` : + OpenSearch refuse de démarrer en tant que ``root``. Exécutez également ``bin/fess-setup`` + ci-dessous avec cet utilisateur, afin que les fichiers qu'il extrait lui appartiennent. + Consultez :doc:`run` si un démarrage en tant que ``root`` a déjà été refusé. + +.. tip:: + + ``bin/fess-setup``, fourni avec |Fess|, exécute les étapes 1 à 3 ci-dessous en une seule + commande : il télécharge et extrait OpenSearch dans ``opensearch/`` du répertoire de |Fess|, + installe les plugins requis, puis ajoute ``configsync.config_path`` et + ``plugins.security.disabled: true`` à son ``config/opensearch.yml``. Décompressez d'abord le + ZIP de |Fess|, comme décrit à l'Étape 2. + + :: + + $ cd /path/to/fess-15.10.0 + $ bin/fess-setup install opensearch + + ``bin/fess.in.sh`` trouve un OpenSearch installé de cette façon et définit + ``FESS_DICTIONARY_PATH`` par lui-même : « Configuration de Fess » à l'Étape 2 ne nécessite donc + aucune modification tant qu'OpenSearch s'exécute sur le même hôte. La commande affiche les + paramètres ajoutés et indique si ``bin/fess.in.sh`` trouve l'installation. Lisez + l'avertissement de l'étape 3 avant qu'OpenSearch n'écoute sur une autre adresse que + ``localhost``. + + Suivez les étapes ci-dessous pour les dérouler une à une, ou lorsque vous utilisez un + OpenSearch existant. Pour n'installer que les plugins dans un OpenSearch existant, utilisez + ``bin/fess-setup install opensearch-plugins --opensearch-home /path/to/opensearch``. + Consultez :doc:`fess-setup` pour toutes les commandes. + +.. note:: + + OpenSearch ne publie pas de version macOS : sous macOS, ``bin/fess-setup install opensearch`` + se termine donc par une erreur. Installez OpenSearch avec Homebrew et ajoutez les plugins avec + ``bin/fess-setup install opensearch-plugins``, ou utilisez plutôt :doc:`install-docker` :: + + $ brew install opensearch + $ bin/fess-setup install opensearch-plugins --opensearch-home $(brew --prefix opensearch) + + Configurez ensuite cet OpenSearch comme à l'étape 3, et définissez ``FESS_DICTIONARY_PATH`` + comme décrit dans « Configuration de Fess » à l'Étape 2. + +1. Téléchargement d'OpenSearch + + Téléchargez la version TAR.GZ depuis `Download OpenSearch `__. + + :: + + $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.9.0/opensearch-3.9.0-linux-x64.tar.gz + $ tar -xzf opensearch-3.9.0-linux-x64.tar.gz + $ cd opensearch-3.9.0 + + Sur une machine arm64 (aarch64), remplacez ``linux-x64`` par ``linux-arm64`` dans les noms de fichier ci-dessus (par exemple, ``opensearch-3.9.0-linux-arm64.tar.gz``). + + .. note:: + + Cet exemple utilise OpenSearch 3.9.0. + |Fess| 15.10 est compatible avec OpenSearch 3.9.0. + +2. Installation des plugins OpenSearch + + Installez les plugins requis par |Fess|. + + :: + + $ cd /path/to/opensearch-3.9.0 + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + + .. important:: + + Les versions des plugins doivent correspondre à la version d'OpenSearch. + Dans l'exemple ci-dessus, toutes sont spécifiées en 3.9.0. + + Les quatre plugins de |Fess| sont publiés sur maven.codelibs.org ; ils s'installent donc par + leur URL. La forme ``groupId:artifactId:version`` de ``opensearch-plugin install`` ne cherche + que dans Maven Central. + +3. Configuration d'OpenSearch + + Ajoutez les paramètres suivants dans ``config/opensearch.yml``. + + :: + + # Chemin pour la synchronisation de configuration (spécifier en chemin absolu) + configsync.config_path: /path/to/opensearch-3.9.0/config/dictionary/ + + # Désactivation du plugin de sécurité (environnement de développement uniquement) + plugins.security.disabled: true + + .. important:: + + Indiquez pour ``configsync.config_path`` un répertoire situé sous le répertoire de configuration d'OpenSearch (``/path/to/opensearch-3.9.0/config/`` dans cet exemple). + À partir d'OpenSearch 3.8.0, la création d'un index est refusée si les fichiers de dictionnaire se trouvent en dehors du répertoire de configuration. + Si vous indiquez un emplacement situé en dehors du répertoire de configuration, comme ``/path/to/opensearch-3.9.0/data/config/``, |Fess| ne peut pas créer ses index et ne démarre pas. + + .. warning:: + + **Remarque importante concernant la sécurité** + + ``plugins.security.disabled: true`` ne doit être utilisé que dans les environnements de développement ou de test. + Pour les environnements de production, activez le plugin de sécurité d'OpenSearch et configurez une authentification et une autorisation appropriées. + Si vous activez le plugin de sécurité avec OpenSearch 2.12 ou une version ultérieure, vous devez définir un mot de passe administrateur (variable d'environnement ``OPENSEARCH_INITIAL_ADMIN_PASSWORD``) lors du premier démarrage. + Pour plus de détails, consultez :doc:`security`. + + .. tip:: + + Vous pouvez ajuster d'autres paramètres tels que le nom du cluster et la configuration réseau en fonction de votre environnement. + Exemple de configuration :: + + cluster.name: fess-cluster + node.name: fess-node-1 + network.host: 0.0.0.0 + discovery.type: single-node + + .. tip:: + + La taille du tas (heap) d'OpenSearch se configure via ``-Xms`` / ``-Xmx`` dans ``config/jvm.options``. + Il est recommandé d'utiliser une valeur inférieure ou égale à la moitié de la mémoire physique disponible, et inférieure à 32 Go, en indiquant la même valeur pour ``-Xms`` et ``-Xmx``. + +Étape 2 : Installation de Fess +--------------------------------- + +1. Téléchargement et décompression de Fess + + Téléchargez la version ZIP depuis le `site de téléchargement `__. + + :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.zip + $ unzip fess-15.10.0.zip + $ cd fess-15.10.0 + + .. note:: + + Choisissez un répertoire dont le chemin ne contient pas d'espaces (sous macOS également). Si le chemin contient un espace, ``bin/fess`` ne démarre pas et affiche ``Could not find or load main class``. + +2. Configuration de Fess + + Les informations de connexion à OpenSearch se trouvent dans ``bin/fess.in.sh``. Avec un OpenSearch que ``bin/fess-setup install opensearch`` a installé dans ``opensearch/`` du répertoire de |Fess| et qui s'exécute sur le même hôte, ce fichier ne nécessite aucune modification : ``SEARCH_ENGINE_HTTP_URL`` vaut ``http://localhost:9200`` par défaut, et ``FESS_DICTIONARY_PATH`` est défini sur le répertoire ``config/dictionary`` de cet OpenSearch. + + Modifiez ``bin/fess.in.sh`` dans l'un des cas suivants : + + - OpenSearch a été installé d'une autre manière, par exemple avec les étapes 1 à 3 ci-dessus ou avec Homebrew, ou avec ``--dest`` en dehors du répertoire de |Fess|. + - ``opensearch/`` dans le répertoire de |Fess| contient plus d'un OpenSearch installé par ``bin/fess-setup``, par exemple deux versions. ``bin/fess.in.sh`` ne peut pas déterminer lequel est utilisé : il affiche donc un avertissement et laisse ``FESS_DICTIONARY_PATH`` non défini. + - OpenSearch s'exécute sur un autre hôte ou un autre port. + + :: + + $ vi bin/fess.in.sh + + Près du début du fichier, supprimez le ``#`` en début de la ligne ``FESS_DICTIONARY_PATH`` et indiquez le chemin, puis modifiez si nécessaire l'URL de la ligne ``SEARCH_ENGINE_HTTP_URL``. + + Avant modification (état par défaut, lignes de commentaire omises) :: + + SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://localhost:9200} + #FESS_DICTIONARY_PATH=/var/lib/opensearch/config/ + + Après modification :: + + SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://localhost:9200} + FESS_DICTIONARY_PATH=/path/to/opensearch-3.9.0/config/dictionary/ + + .. note:: + + - Définissez pour ``FESS_DICTIONARY_PATH`` le même chemin que celui indiqué dans ``configsync.config_path`` du fichier ``opensearch.yml`` d'OpenSearch. Sans ce paramètre, |Fess| ne peut pas créer ses index et ne démarre pas. + - Si OpenSearch s'exécute sur un autre hôte, remplacez l'URL de la ligne ``SEARCH_ENGINE_HTTP_URL`` par celle de cet hôte. Exemple : ``SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://192.168.1.100:9200}``. ``FESS_DICTIONARY_PATH`` est alors le ``configsync.config_path`` de ce serveur. + - Au lieu de modifier le fichier, les deux variables peuvent être exportées dans l'environnement à partir duquel |Fess| est démarré. Un ``SEARCH_ENGINE_HTTP_URL`` exporté est prioritaire sur l'URL du fichier, et un ``FESS_DICTIONARY_PATH`` exporté est utilisé tant que sa ligne dans le fichier reste commentée. + - N'ajoutez pas une nouvelle ligne ``SEARCH_ENGINE_HTTP_URL=...`` ; modifiez plutôt la ligne existante. + + .. tip:: + + Pour modifier la taille du tas (heap) de |Fess|, modifiez ``FESS_MIN_MEM`` (par défaut : ``256m``) et ``FESS_MAX_MEM`` (par défaut : ``2g``) dans ``bin/fess.in.sh``, ou définissez la variable d'environnement ``FESS_HEAP_SIZE``. + +3. Vérification de l'installation + + Vérifiez que le fichier de configuration a été correctement modifié :: + + $ grep "SEARCH_ENGINE_HTTP_URL" bin/fess.in.sh + $ grep "FESS_DICTIONARY_PATH" bin/fess.in.sh + + Une fois OpenSearch démarré, ``bin/fess-setup check`` indique s'il est joignable, s'il dispose des plugins requis par |Fess| et si ``configsync`` répond. La commande se termine avec le code ``0`` lorsqu'aucune vérification n'a échoué. Indiquez ``--url`` lorsqu'OpenSearch ne se trouve pas à ``http://localhost:9200``. + +Étape 3 : Démarrage +---------------------- + +Pour la procédure de démarrage, consultez :doc:`run`. + +Installation avec la version RPM +=================================== + +La version RPM est utilisée sur les distributions Linux basées sur RPM telles que Red Hat Enterprise Linux, CentOS, Fedora, etc. + +Étape 1 : Installation d'OpenSearch +-------------------------------------- + +1. Téléchargement et installation du RPM OpenSearch + + Téléchargez et installez le package RPM depuis `Download OpenSearch `__. + + :: + + $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.9.0/opensearch-3.9.0-linux-x64.rpm + $ sudo rpm -ivh opensearch-3.9.0-linux-x64.rpm + + Sur une machine arm64 (aarch64), remplacez ``linux-x64`` par ``linux-arm64`` dans les noms de fichier ci-dessus (par exemple, ``opensearch-3.9.0-linux-arm64.rpm``). + + Vous pouvez également ajouter un dépôt pour l'installation. + Pour plus de détails, consultez `Installing OpenSearch `__. + +2. Installation des plugins OpenSearch + + :: + + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + +3. Configuration d'OpenSearch + + Ajoutez les paramètres suivants dans ``/etc/opensearch/opensearch.yml``. + + :: + + $ sudo vi /etc/opensearch/opensearch.yml + + Paramètres à ajouter :: + + configsync.config_path: /etc/opensearch/dictionary/ + plugins.security.disabled: true + + Créez le répertoire des fichiers de dictionnaire :: + + $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary + + .. important:: + + Indiquez pour ``configsync.config_path`` un répertoire situé sous le répertoire de configuration d'OpenSearch ``/etc/opensearch/``. + À partir d'OpenSearch 3.8.0, la création d'un index est refusée si les fichiers de dictionnaire se trouvent en dehors du répertoire de configuration. + Si vous indiquez un emplacement situé en dehors du répertoire de configuration, comme ``/var/lib/opensearch/data/config/``, |Fess| ne peut pas créer ses index et ne démarre pas. + + .. warning:: + + N'utilisez pas ``plugins.security.disabled: true`` en environnement de production. + Consultez :doc:`security` pour configurer une sécurité appropriée. + +Étape 2 : Installation de Fess +--------------------------------- + +1. Installation du RPM Fess + + Téléchargez et installez le package RPM depuis le `site de téléchargement `__. + + :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.rpm + $ sudo rpm -ivh fess-15.10.0.rpm + +2. Configuration de Fess + + Pour la version RPM, modifiez le fichier de configuration des variables d'environnement ``/etc/sysconfig/fess``. + Ce fichier est conservé lors des mises à niveau du package (ne modifiez pas directement ``/usr/share/fess/bin/fess.in.sh``, car il est écrasé lors des mises à niveau). + + :: + + $ sudo vi /etc/sysconfig/fess + + Configurez les informations de connexion à OpenSearch. La valeur par défaut de ``FESS_DICTIONARY_PATH``, ``/var/lib/opensearch/config/``, diffère de ``configsync.config_path`` défini à l'étape 3 : modifiez-la comme suit. Modifiez ``SEARCH_ENGINE_HTTP_URL`` si nécessaire :: + + SEARCH_ENGINE_HTTP_URL=http://localhost:9200 + FESS_DICTIONARY_PATH=/etc/opensearch/dictionary/ + + .. note:: + + Indiquez pour ``FESS_DICTIONARY_PATH`` le même chemin que celui défini dans ``configsync.config_path`` du fichier ``opensearch.yml``. + +3. Enregistrement et activation du service + + Activez les services à l'aide de systemd (systemd est standard à partir de RHEL 8 et CentOS 8) :: + + $ sudo systemctl daemon-reload + $ sudo systemctl enable opensearch.service + $ sudo systemctl enable fess.service + + .. note:: + + Le service |Fess| dépend du service OpenSearch ; OpenSearch doit donc être démarré en premier. + + .. note:: + + Dans les environnements traditionnels n'utilisant pas systemd, vous pouvez enregistrer |Fess| avec ``chkconfig`` :: + + $ sudo /sbin/chkconfig --add fess + +Étape 3 : Démarrage +---------------------- + +Pour la procédure de démarrage, consultez :doc:`run`. + +Installation avec la version DEB +=================================== + +La version DEB est utilisée sur les distributions Linux basées sur DEB telles que Debian, Ubuntu, etc. + +Étape 1 : Installation d'OpenSearch +-------------------------------------- + +1. Téléchargement et installation du DEB OpenSearch + + Téléchargez et installez le package DEB depuis `Download OpenSearch `__. + + :: + + $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.9.0/opensearch-3.9.0-linux-x64.deb + $ sudo dpkg -i opensearch-3.9.0-linux-x64.deb + + Sur une machine arm64 (aarch64), remplacez ``linux-x64`` par ``linux-arm64`` dans les noms de fichier ci-dessus (par exemple, ``opensearch-3.9.0-linux-arm64.deb``). + + Vous pouvez également ajouter un dépôt pour l'installation. + Pour plus de détails, consultez `Installing OpenSearch `__. + +2. Installation des plugins OpenSearch + + :: + + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + +3. Configuration d'OpenSearch + + Ajoutez les paramètres suivants dans ``/etc/opensearch/opensearch.yml``. + + :: + + $ sudo vi /etc/opensearch/opensearch.yml + + Paramètres à ajouter :: + + configsync.config_path: /etc/opensearch/dictionary/ + plugins.security.disabled: true + + Créez le répertoire des fichiers de dictionnaire :: + + $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary + + .. important:: + + Indiquez pour ``configsync.config_path`` un répertoire situé sous le répertoire de configuration d'OpenSearch ``/etc/opensearch/``. + À partir d'OpenSearch 3.8.0, la création d'un index est refusée si les fichiers de dictionnaire se trouvent en dehors du répertoire de configuration. + Si vous indiquez un emplacement situé en dehors du répertoire de configuration, comme ``/var/lib/opensearch/data/config/``, |Fess| ne peut pas créer ses index et ne démarre pas. + + .. warning:: + + N'utilisez pas ``plugins.security.disabled: true`` en environnement de production. + Consultez :doc:`security` pour configurer une sécurité appropriée. + +Étape 2 : Installation de Fess +--------------------------------- + +1. Installation du DEB Fess + + Téléchargez et installez le package DEB depuis le `site de téléchargement `__. + + :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.deb + $ sudo dpkg -i fess-15.10.0.deb + +2. Configuration de Fess + + Pour la version DEB, modifiez le fichier de configuration des variables d'environnement ``/etc/default/fess``. + Ce fichier est conservé lors des mises à niveau du package (ne modifiez pas directement ``/usr/share/fess/bin/fess.in.sh``, car il est écrasé lors des mises à niveau). + + :: + + $ sudo vi /etc/default/fess + + Configurez les informations de connexion à OpenSearch. La valeur par défaut de ``FESS_DICTIONARY_PATH``, ``/var/lib/opensearch/config/``, diffère de ``configsync.config_path`` défini à l'étape 3 : modifiez-la comme suit. Modifiez ``SEARCH_ENGINE_HTTP_URL`` si nécessaire :: + + SEARCH_ENGINE_HTTP_URL=http://localhost:9200 + FESS_DICTIONARY_PATH=/etc/opensearch/dictionary/ + + .. note:: + + Indiquez pour ``FESS_DICTIONARY_PATH`` le même chemin que celui défini dans ``configsync.config_path`` du fichier ``opensearch.yml``. + +3. Enregistrement et activation du service + + Activez le service à l'aide de systemd :: + + $ sudo systemctl daemon-reload + $ sudo systemctl enable opensearch.service + $ sudo systemctl enable fess.service + + .. note:: + + Le service |Fess| dépend du service OpenSearch ; OpenSearch doit donc être démarré en premier. + +Étape 3 : Démarrage +---------------------- + +Pour la procédure de démarrage, consultez :doc:`run`. + +Vérification après l'installation +==================================== + +Une fois l'installation terminée, veuillez vérifier les éléments suivants : + +1. **Vérification des fichiers de configuration** + + - Fichier de configuration d'OpenSearch (opensearch.yml) + - Fichier de configuration de |Fess| + + - Version ZIP : ``bin/fess.in.sh`` + - Version RPM : ``/etc/sysconfig/fess`` + - Version DEB : ``/etc/default/fess`` + +2. **Permissions des répertoires** + + Vérifiez que le répertoire spécifié dans la configuration (``configsync.config_path`` / ``FESS_DICTIONARY_PATH``) existe et dispose des permissions appropriées. + + Pour la version ZIP :: + + $ ls -ld /path/to/opensearch-3.9.0/config/dictionary/ + + Pour les versions RPM/DEB :: + + $ sudo ls -ld /etc/opensearch/dictionary/ + +3. **Vérification des paramètres du noyau** + + :: + + $ sysctl vm.max_map_count + + Vérifiez que la valeur est ``262144`` ou plus. + +4. **Vérification de la version de Java** + + :: + + $ java -version + + Vérifiez que Java 21 ou une version ultérieure est installé. + +Étapes suivantes +================ + +Une fois l'installation terminée, consultez les documents suivants : + +- :doc:`run` - Démarrage de |Fess| et configuration initiale +- :doc:`security` - Configuration de la sécurité pour les environnements de production +- :doc:`troubleshooting` - Dépannage + +Questions fréquemment posées +============================= + +Q : D'autres versions d'OpenSearch fonctionnent-elles ? +------------------------------------------------------------------ + +R : |Fess| dépend d'une version spécifique d'OpenSearch. +Pour garantir la compatibilité des plugins, il est fortement recommandé d'utiliser la version recommandée (3.9.0). +Si vous utilisez une autre version, vous devrez également ajuster les versions des plugins de manière appropriée. + +Q : Peut-on partager le même OpenSearch avec plusieurs instances Fess ? +------------------------------------------------------------------------ + +R : C'est possible, mais ce n'est pas recommandé. Nous recommandons de prévoir un cluster OpenSearch dédié pour chaque instance Fess. +Si vous partagez OpenSearch avec plusieurs instances Fess, faites attention aux collisions de noms d'index. + +Q : Comment configurer OpenSearch en cluster ? +----------------------------------------------- + +R : Consultez la documentation officielle d'OpenSearch `Cluster formation `__. +Pour une configuration en cluster, vous devez supprimer le paramètre ``discovery.type: single-node`` et ajouter une configuration de cluster appropriée. diff --git a/fr/15.10/install/install-windows.rst b/fr/15.10/install/install-windows.rst new file mode 100644 index 000000000..12f2e22a7 --- /dev/null +++ b/fr/15.10/install/install-windows.rst @@ -0,0 +1,363 @@ +============================================== +Installation sur Windows (Procédure détaillée) +============================================== + +Cette page décrit la procédure d'installation de |Fess| sur un environnement Windows. +Elle documente la méthode d'installation à l'aide du package ZIP. + +.. note:: + + |Fess| n'intègre pas de moteur de recherche. Un serveur OpenSearch est nécessaire ; + les étapes ci-dessous le mettent en place. + +Prérequis +========= + +- La configuration requise décrite dans :doc:`prerequisites` doit être satisfaite +- Java 21 doit être installé +- OpenSearch 3.9.0 doit être disponible (ou nouvelle installation) +- La variable d'environnement Windows ``JAVA_HOME`` doit être configurée de manière appropriée + +Vérification de l'installation de Java +======================================= + +Ouvrez l'invite de commandes ou PowerShell et vérifiez la version de Java avec la commande suivante. + +Invite de commandes :: + + C:\> java -version + +PowerShell :: + + PS C:\> java -version + +Vérifiez que Java 21 ou ultérieur est affiché. + +Configuration des variables d'environnement +============================================ + +1. Configuration de la variable d'environnement ``JAVA_HOME`` + + Configurez le répertoire d'installation de Java comme ``JAVA_HOME``. + + Exemple :: + + JAVA_HOME=C:\Program Files\Eclipse Adoptium\jdk-21.0.1.12-hotspot + +2. Ajout à la variable d'environnement ``PATH`` + + Ajoutez ``%JAVA_HOME%\bin`` à la variable d'environnement ``PATH``. + +.. tip:: + + Méthode de configuration des variables d'environnement : + + 1. Ouvrir les « Paramètres » depuis le menu « Démarrer » + 2. Cliquer sur « Système » → « Informations système » → « Paramètres système avancés » + 3. Cliquer sur le bouton « Variables d'environnement » + 4. Configurer dans « Variables système » ou « Variables utilisateur » + +Étape 1 : Installation d'OpenSearch +==================================== + +.. tip:: + + ``bin\fess-setup``, fourni avec |Fess|, exécute les étapes ci-dessous en une seule commande : + il télécharge et extrait OpenSearch dans ``opensearch\`` du répertoire de |Fess|, installe les + plugins requis, puis ajoute ``configsync.config_path`` et ``plugins.security.disabled: true`` + à son ``config\opensearch.yml``. Décompressez d'abord le ZIP de |Fess|, comme décrit à + l'Étape 2. + + :: + + > cd C:\fess-15.10.0 + > bin\fess-setup install opensearch + + ``bin\fess.in.bat`` trouve un OpenSearch installé de cette façon et transmet son répertoire + ``config\dictionary`` à |Fess| : « Configuration de Fess » à l'Étape 2 ne nécessite donc aucune + modification tant qu'OpenSearch s'exécute sur le même hôte. La commande affiche les paramètres + ajoutés et indique si ``bin\fess.in.bat`` trouve l'installation. Lisez l'avertissement de + « Configuration d'OpenSearch » avant qu'OpenSearch n'écoute sur une autre adresse que + ``localhost``. + + Suivez les étapes ci-dessous pour les dérouler une à une, ou lorsque vous utilisez un + OpenSearch existant. Pour n'installer que les plugins dans un OpenSearch existant, utilisez + ``bin\fess-setup install opensearch-plugins --opensearch-home C:\opensearch-3.9.0``. + Consultez :doc:`fess-setup` pour toutes les commandes. + +Téléchargement d'OpenSearch +---------------------------- + +1. Téléchargez le package ZIP pour Windows depuis `Download OpenSearch `__. + +2. Décompressez le fichier ZIP téléchargé dans un répertoire arbitraire. + + Exemple :: + + C:\opensearch-3.9.0 + + .. note:: + + Nous recommandons de choisir un répertoire dont le chemin ne contient pas de caractères japonais ou d'espaces. + +Installation des plugins OpenSearch +------------------------------------ + +Ouvrez l'invite de commandes **avec des privilèges d'administrateur** et exécutez les commandes suivantes. + +:: + + C:\> cd C:\opensearch-3.9.0 + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + +.. important:: + + Les versions des plugins doivent correspondre à la version d'OpenSearch. + Dans l'exemple ci-dessus, toutes sont spécifiées en 3.9.0. + + Les quatre plugins de |Fess| sont publiés sur maven.codelibs.org ; ils s'installent donc par leur + URL. La forme ``groupId:artifactId:version`` de ``opensearch-plugin install`` ne cherche que dans + Maven Central. + +Configuration d'OpenSearch +--------------------------- + +Ouvrez ``config\opensearch.yml`` avec un éditeur de texte et ajoutez les paramètres suivants. + +:: + + # Chemin pour la synchronisation de configuration (spécifier en chemin absolu) + configsync.config_path: C:/opensearch-3.9.0/config/dictionary/ + + # Désactivation du plugin de sécurité (environnement de développement uniquement) + plugins.security.disabled: true + +.. warning:: + + **Note importante sur la sécurité** + + ``plugins.security.disabled: true`` ne doit être utilisé que dans les environnements de développement ou de test. + Pour les environnements de production, veuillez activer le plugin de sécurité d'OpenSearch et configurer une authentification et une autorisation appropriées. + Pour plus de détails, consultez :doc:`security`. + +.. note:: + + Sous Windows, utilisez ``/`` plutôt que ``\`` comme séparateur de chemin. + Écrivez ``C:/opensearch-3.9.0/config/dictionary/`` plutôt que ``C:\opensearch-3.9.0\config\dictionary\``. + +.. important:: + + Indiquez pour ``configsync.config_path`` un répertoire situé sous le répertoire de configuration d'OpenSearch (``C:/opensearch-3.9.0/config/`` dans cet exemple). + À partir d'OpenSearch 3.8.0, la création d'un index est refusée si les fichiers de dictionnaire se trouvent en dehors du répertoire de configuration. + Si vous indiquez un emplacement situé en dehors du répertoire de configuration, comme ``C:/opensearch-3.9.0/data/config/``, |Fess| ne peut pas créer ses index et ne démarre pas. + +.. tip:: + + Autres paramètres recommandés :: + + cluster.name: fess-cluster + node.name: fess-node-1 + network.host: 0.0.0.0 + discovery.type: single-node + +.. tip:: + + La taille du tas mémoire d'OpenSearch se configure via ``-Xms`` / ``-Xmx`` dans ``config\jvm.options``. + Il est recommandé de spécifier la même valeur pour ``-Xms`` et ``-Xmx``, inférieure à la moitié de la mémoire physique disponible et inférieure à 32 Go. + +Étape 2 : Installation de Fess +=============================== + +Téléchargement de Fess +----------------------- + +1. Téléchargez le package ZIP pour Windows depuis le `site de téléchargement `__. + +2. Décompressez le fichier ZIP téléchargé dans un répertoire arbitraire. + + Exemple :: + + C:\fess-15.10.0 + + .. note:: + + Nous recommandons de choisir un répertoire dont le chemin ne contient pas de caractères japonais ou d'espaces. + +Configuration de Fess +---------------------- + +Avec un OpenSearch que ``bin\fess-setup install opensearch`` a installé dans ``opensearch\`` du +répertoire de |Fess| et qui s'exécute sur le même hôte, aucune configuration n'est nécessaire ici. +Dans les autres cas, par exemple lorsqu'OpenSearch a été installé avec les étapes ci-dessus, +s'exécute sur un autre hôte, ou lorsque ``opensearch\`` contient plus d'un OpenSearch installé par +``bin\fess-setup``, configurez la connexion comme suit. + +Ouvrez ``bin\fess.in.bat`` avec un éditeur de texte. +Vers la fin de ce fichier, les paramètres de connexion à un cluster OpenSearch externe sont préparés à l'avance sous forme de lignes commentées. + +Avant modification (état par défaut) :: + + REM External opensearch cluster + REM set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200 + REM set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=C:/opensearch/config/dictionary + +Supprimez le préfixe ``REM `` en début des 2 dernières lignes pour décommenter, puis modifiez la valeur de ``fess.dictionary.path`` avec le chemin de synchronisation de configuration d'OpenSearch. + +Après modification :: + + REM External opensearch cluster + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200 + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=C:/opensearch-3.9.0/config/dictionary/ + +.. note:: + + - Pour ``fess.dictionary.path``, spécifiez le même chemin que ``configsync.config_path`` défini dans le fichier ``opensearch.yml`` d'OpenSearch. + - Si vous exécutez OpenSearch sur un autre hôte, modifiez le nom d'hôte ou l'adresse IP de ``fess.search_engine.http_address`` avec la valeur appropriée. + - Utilisez ``/`` comme séparateur de chemin. |Fess| insère le chemin dans les paramètres de l'index, où un ``\`` est perdu : un chemin écrit avec ``\`` n'est donc pas trouvé. + - Ne pas ajouter de nouvelles lignes ``set FESS_JAVA_OPTS=...`` ; décommentez et éditez les lignes existantes. La spécification dupliquée d'une même option peut provoquer un comportement inattendu. + +.. tip:: + + Pour modifier la taille du tas mémoire de |Fess|, éditez ``FESS_MIN_MEM`` (valeur par défaut : ``256m``) et ``FESS_MAX_MEM`` (valeur par défaut : ``1g``) dans ``bin\fess.in.bat``, ou définissez la variable d'environnement ``FESS_HEAP_SIZE``. + +Vérification de l'installation +------------------------------- + +Vérifiez que les fichiers de configuration ont été correctement modifiés. + +Invite de commandes :: + + C:\> findstr "fess.search_engine.http_address" C:\fess-15.10.0\bin\fess.in.bat + C:\> findstr "fess.dictionary.path" C:\fess-15.10.0\bin\fess.in.bat + +Étape 3 : Démarrage +==================== + +Pour la procédure de démarrage, consultez :doc:`run`. + +Enregistrement en tant que service Windows (optionnel) +======================================================= + +En enregistrant |Fess| en tant que service Windows, vous pouvez le configurer pour qu'il démarre automatiquement au démarrage du système. + +|Fess| est livré avec ``bin\service.bat`` pour l'enregistrement en tant que service Windows. +Ce script utilise Apache Commons Daemon (procrun), il n'est donc pas nécessaire de prévoir séparément un outil tiers tel que NSSM. + +.. note:: + + Avant d'exécuter ``service.bat``, vérifiez que la variable d'environnement ``JAVA_HOME`` est correctement configurée. + +Enregistrement du service |Fess| +--------------------------------- + +Ouvrez l'invite de commandes **avec des privilèges d'administrateur** et exécutez les commandes suivantes. + +1. Enregistrement du service :: + + C:\> cd C:\fess-15.10.0 + C:\fess-15.10.0> bin\service.bat install + + Par défaut, le service est enregistré avec l'identifiant ``fess-service-x64`` pour les environnements 64 bits et ``fess-service-x86`` pour les environnements 32 bits. + Pour spécifier explicitement l'identifiant du service, passez-le en argument : ``bin\service.bat install ``. + +2. Démarrage et arrêt du service :: + + C:\fess-15.10.0> bin\service.bat start + C:\fess-15.10.0> bin\service.bat stop + +3. Consultation et modification de la configuration du service (GUI) :: + + C:\fess-15.10.0> bin\service.bat manager + +4. Suppression du service :: + + C:\fess-15.10.0> bin\service.bat remove + +.. note:: + + - ``service.bat`` charge ``bin\fess.in.bat`` en interne, de sorte que les paramètres de connexion à OpenSearch externe définis dans la section « Configuration de Fess » sont également appliqués au service. + - Le type de démarrage par défaut est « Manuel ». Pour que le service démarre automatiquement au lancement du système, définissez la variable d'environnement ``FESS_START_TYPE`` à ``auto`` avant l'enregistrement du service, ou modifiez le type de démarrage en « Automatique » via l'outil de gestion des services (``services.msc``) après l'enregistrement. + - ``service.bat`` ne permet d'enregistrer que le service |Fess|. Pour enregistrer OpenSearch en tant que service, consultez la procédure fournie par OpenSearch. + +Configuration du pare-feu +========================== + +Ouvrez les ports nécessaires dans le Pare-feu Windows Defender. + +1. Ouvrez « Panneau de configuration » → « Pare-feu Windows Defender » → « Paramètres avancés » + +2. Créez une nouvelle règle dans « Règles de trafic entrant » + + - Type de règle : Port + - Protocole et port : TCP, 8080 + - Action : Autoriser la connexion + - Nom : Fess Web Interface + +Ou exécutez dans PowerShell :: + + PS C:\> New-NetFirewallRule -DisplayName "Fess Web Interface" -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow + +Dépannage +========= + +Conflit de numéros de port +--------------------------- + +Si les ports 8080 ou 9200 sont déjà utilisés, vous pouvez le vérifier avec la commande suivante :: + + C:\> netstat -ano | findstr :8080 + C:\> netstat -ano | findstr :9200 + +Modifiez le numéro de port utilisé ou arrêtez le processus en conflit. + +Limitation de la longueur des chemins +-------------------------------------- + +Sous Windows, il existe une limitation de la longueur des chemins. Nous recommandons d'installer dans un chemin aussi court que possible. + +Exemple :: + + C:\opensearch (recommandé) + C:\Program Files\opensearch-3.9.0 (non recommandé - chemin trop long) + +Java n'est pas reconnu +----------------------- + +Si une erreur s'affiche avec la commande ``java -version`` : + +1. Vérifiez que la variable d'environnement ``JAVA_HOME`` est correctement configurée +2. Vérifiez que ``%JAVA_HOME%\bin`` est inclus dans la variable d'environnement ``PATH`` +3. Redémarrez l'invite de commandes pour appliquer les paramètres + +Étapes suivantes +================ + +Une fois l'installation terminée, consultez les documents suivants : + +- :doc:`run` - Démarrage de |Fess| et configuration initiale +- :doc:`security` - Configuration de la sécurité pour les environnements de production +- :doc:`troubleshooting` - Dépannage + +Questions fréquemment posées +============================= + +Q : L'exploitation sur Windows Server est-elle recommandée ? +------------------------------------------------------------- + +R : Oui, l'exploitation sur Windows Server est possible. +Lors de l'exploitation sur Windows Server, enregistrez-le en tant que service Windows et configurez une surveillance appropriée. + +Q : Quelle est la différence entre les versions 64 bits et 32 bits ? +--------------------------------------------------------------------- + +R : |Fess| et OpenSearch ne prennent en charge que la version 64 bits. +Ils ne fonctionnent pas sur Windows 32 bits. + +Q : Comment gérer les chemins contenant des caractères japonais ? +------------------------------------------------------------------ + +R : Dans la mesure du possible, veuillez installer dans un chemin ne contenant pas de caractères japonais ou d'espaces. +Si vous devez absolument utiliser un chemin japonais, vous devez échapper correctement le chemin dans les fichiers de configuration. diff --git a/fr/15.10/install/install.rst b/fr/15.10/install/install.rst new file mode 100644 index 000000000..6fac6d9b8 --- /dev/null +++ b/fr/15.10/install/install.rst @@ -0,0 +1,247 @@ +================================== +Choix de la méthode d'installation +================================== + +Cette page décrit une vue d'ensemble des méthodes d'installation de |Fess|. +Veuillez sélectionner la méthode d'installation appropriée en fonction de votre environnement. + +.. note:: + + |Fess| n'intègre pas de moteur de recherche. Chacune des méthodes d'installation + ci-dessous nécessite un serveur OpenSearch distinct. + +Vérification des prérequis +=========================== + +Avant de commencer l'installation, veuillez vérifier la configuration requise. + +Pour plus de détails, consultez :doc:`prerequisites`. + +Comparaison des méthodes d'installation +======================================== + +|Fess| peut être installé selon les méthodes suivantes. Veuillez sélectionner en fonction de votre environnement et de votre utilisation. + +.. list-table:: + :header-rows: 1 + :widths: 15 25 30 30 + + * - Méthode + - Système d'exploitation + - Usage recommandé + - Documentation détaillée + * - Docker + - Linux, Windows, macOS + - Environnement de développement/évaluation, configuration rapide + - :doc:`install-docker` + * - ZIP + - Linux, macOS + - Environnement nécessitant une personnalisation + - :doc:`install-linux` + * - RPM + - RHEL, CentOS, Fedora + - Environnement de production (basé sur RPM) + - :doc:`install-linux` + * - DEB + - Debian, Ubuntu + - Environnement de production (basé sur DEB) + - :doc:`install-linux` + * - ZIP + - Windows + - Développement/production sur environnement Windows + - :doc:`install-windows` + +Caractéristiques de chaque méthode d'installation +================================================== + +Version Docker +-------------- + +**Avantages :** + +- Configuration la plus rapide possible +- Gestion des dépendances non nécessaire +- Idéal pour la création d'environnements de développement +- Démarrage et arrêt faciles des conteneurs + +**Inconvénients :** + +- Connaissance de Docker requise + +**Environnement recommandé :** Environnements de développement, d'évaluation, POC et de production + +Détails : :doc:`install-docker` + +Packages Linux (ZIP/RPM/DEB) +------------------------------- + +**Avantages :** + +- Hautes performances en environnement natif +- Gestion possible en tant que service système (RPM/DEB) +- Personnalisation fine possible + +**Inconvénients :** + +- Installation manuelle de Java et OpenSearch requise +- Configuration nécessitant un effort + +**Environnement recommandé :** Environnement de production (RPM/DEB recommandé car gérable en tant que service système), environnement nécessitant une personnalisation + +Détails : :doc:`install-linux` + +Version Windows (ZIP) +--------------------- + +**Avantages :** + +- Fonctionne en environnement Windows natif +- Aucun installateur nécessaire + +**Inconvénients :** + +- Installation manuelle de Java et OpenSearch requise +- Configuration nécessitant un effort + +**Environnement recommandé :** Développement/évaluation sur environnement Windows, exploitation en production sur Windows Server + +Détails : :doc:`install-windows` + +Flux d'installation de base +=========================== + +Pour toutes les méthodes d'installation, le flux de base est le même. + +1. **Vérification de la configuration requise** + + Consultez :doc:`prerequisites` pour confirmer que la configuration requise est satisfaite. + +2. **Téléchargement du logiciel** + + Téléchargez |Fess| depuis le `site de téléchargement `__. + + Pour la version Docker, obtenez le fichier Docker Compose. + +3. **Configuration d'OpenSearch** + + Pour les versions autres que Docker, vous devez configurer OpenSearch séparément. + + - Installation d'OpenSearch 3.9.0 + - Installation des plugins requis + - Modification des fichiers de configuration + +4. **Configuration de Fess** + + - Installation de Fess + - Modification des fichiers de configuration (informations de connexion à OpenSearch, etc.) + +5. **Démarrage et vérification** + + - Démarrage du service + - Vérification du fonctionnement en accédant via un navigateur + + Pour plus de détails, consultez :doc:`run`. + +Composants requis +================= + +Pour exécuter |Fess|, les composants suivants sont nécessaires. + +Application Fess +---------------- + +Il s'agit du système de recherche plein texte principal. Il fournit des fonctionnalités telles que l'interface Web, le crawler et l'indexeur. + +OpenSearch +---------- + +OpenSearch est utilisé comme moteur de recherche. + +- **Version compatible** : OpenSearch 3.9.0 +- **Plugins requis** : + + - opensearch-analysis-fess + - opensearch-analysis-extension + - opensearch-minhash + - opensearch-configsync + +.. important:: + + Les versions d'OpenSearch et des plugins doivent correspondre. + Une incompatibilité de version peut causer des erreurs de démarrage ou des comportements inattendus. + +``bin/fess-setup install opensearch`` met en place OpenSearch avec ces plugins sous Linux et Windows. Voir :doc:`install-linux` pour les détails, y compris pour macOS, où OpenSearch doit être installé d'une autre manière, et :doc:`fess-setup` pour toutes les commandes. + +.. note:: + + Si vous utilisez un OpenSearch sur lequel ces plugins ne peuvent pas être installés, comme un service géré, définissez ``search_engine.type`` sur ``vanilla`` (|Fess| 15.10 et ultérieur). Certaines fonctionnalités, comme la gestion du dictionnaire, ne sont alors pas disponibles. Voir :doc:`../config/search-engine-type`. + +Java (sauf version Docker) +-------------------------- + +Pour les versions ZIP/RPM/DEB, Java 21 ou ultérieur est requis. + +- Recommandé : `Eclipse Temurin `__ +- OpenJDK 21 ou ultérieur peut également être utilisé + +.. note:: + + Pour la version Docker, Java est inclus dans l'image Docker, donc aucune installation séparée n'est nécessaire. + +Étapes suivantes +================ + +Après avoir vérifié la configuration requise, veuillez sélectionner la méthode d'installation appropriée. + +1. :doc:`prerequisites` - Vérification de la configuration requise +2. Sélection de la méthode d'installation : + + - :doc:`install-docker` - Installation avec Docker + - :doc:`install-linux` - Installation sur Linux + - :doc:`install-windows` - Installation sur Windows + +3. :doc:`run` - Démarrage de |Fess| et configuration initiale +4. :doc:`security` - Configuration de la sécurité (pour les environnements de production) + +Questions fréquemment posées +============================= + +Q : OpenSearch est-il obligatoire ? +------------------------------------ + +R : Oui, il est obligatoire. |Fess| utilise OpenSearch comme moteur de recherche. +Pour la version Docker, il est configuré automatiquement, mais pour les autres méthodes, vous devez l'installer manuellement. + +Q : Peut-on effectuer une mise à niveau depuis une version antérieure ? +----------------------------------------------------------------------- + +R : Oui, c'est possible. Pour plus de détails, consultez :doc:`upgrade`. + +Q : Peut-on configurer avec plusieurs serveurs ? +------------------------------------------------- + +R : Oui, c'est possible. Fess et OpenSearch peuvent être exécutés sur des serveurs séparés. +De plus, en configurant OpenSearch en cluster, vous pouvez améliorer la haute disponibilité et les performances. + +Téléchargements +=============== + +|Fess| et les composants associés peuvent être téléchargés depuis : + +- **Fess** : `Site de téléchargement `__ +- **OpenSearch** : `Download OpenSearch `__ +- **Java (Adoptium)** : `Adoptium `__ +- **Docker** : `Get Docker `__ + +Informations de version +======================== + +Cette documentation concerne les versions suivantes : + +- **Fess** : 15.10.0 +- **OpenSearch** : 3.9.0 +- **Java** : 21 ou ultérieur +- **Docker** : 20.10 ou ultérieur +- **Docker Compose** : 2.0 ou ultérieur + +Pour la documentation des versions précédentes, veuillez consulter la documentation de chaque version. diff --git a/fr/15.10/install/intro.rst b/fr/15.10/install/intro.rst new file mode 100644 index 000000000..8065408c1 --- /dev/null +++ b/fr/15.10/install/intro.rst @@ -0,0 +1,70 @@ +============================= +Introduction à l'installation +============================= + +À propos de ce document +======================= + +Ce guide d'installation décrit les procédures d'installation, de démarrage, de mise à niveau et de désinstallation de |Fess|. +Veuillez sélectionner la méthode d'installation appropriée en fonction de votre environnement. + +Public cible +============ + +Ce document s'adresse aux utilisateurs chargés de l'installation et de la désinstallation de |Fess|. + +Avant de commencer +================== + +Ce document présente les méthodes d'installation de |Fess|. Les connaissances suivantes sont requises : + +- Connaissances de base de l'administration de serveurs +- Utilisation de la ligne de commande sous Linux ou Windows +- Configuration de base des réseaux et pare-feu +- Connaissances de base de Docker (si vous utilisez la version Docker) + +Organisation du document +======================== + +Ce guide d'installation est organisé selon les sections suivantes : + +- **Configuration requise** : Configuration matérielle et logicielle nécessaire pour exécuter |Fess| +- **Installation** : Procédures d'installation par plateforme + + - Choix d'une méthode d'installation (aperçu et comparaison) + - Installation pour Linux (ZIP/RPM/DEB) + - Installation pour Windows (ZIP) + - Installation pour Docker + +- **Démarrage, arrêt et configuration initiale** : Démarrage, arrêt et configuration initiale du serveur |Fess| +- **Configuration de la sécurité** : Configuration de sécurité recommandée pour les environnements de production +- **Mise à niveau** : Procédure de mise à niveau d'une version antérieure vers la dernière version +- **Désinstallation** : Procédure de désinstallation complète de |Fess| +- **Dépannage** : Problèmes courants et solutions + +Accès en ligne +============== + +Pour les téléchargements, les services professionnels, l'assistance et autres informations pour les développeurs, veuillez consulter : + +- Site du projet : `https://fess.codelibs.org/ `__ + +Contact pour l'assistance technique +==================================== + +Pour toute question ou problème technique concernant ce produit, veuillez consulter : + +- Issues : `https://github.com/codelibs/fess/issues `__ + +Assistance commerciale +----------------------- + +Si vous avez besoin d'une assistance commerciale pour le support technique ou la maintenance de ce produit, veuillez contacter `N2SM, Inc. `__ + +Comment envoyer des commentaires et suggestions +================================================ + +Si vous avez des problèmes ou des améliorations à suggérer, veuillez les soumettre ici : + +- Problèmes avec le produit : `https://github.com/codelibs/fess/issues `__ +- Problèmes avec la documentation : `https://github.com/codelibs/fess-docs/issues `__ diff --git a/fr/15.10/install/prerequisites.rst b/fr/15.10/install/prerequisites.rst new file mode 100644 index 000000000..3a1713e0d --- /dev/null +++ b/fr/15.10/install/prerequisites.rst @@ -0,0 +1,185 @@ +==================== +Configuration requise +==================== + +Cette page décrit la configuration matérielle et logicielle requise pour exécuter |Fess|. + +Configuration matérielle +======================== + +Configuration minimale +---------------------- + +Voici la configuration minimale pour les environnements d'évaluation et de développement : + +- Processeur : 2 cœurs ou plus +- Mémoire : 4 Go ou plus +- Espace disque : 10 Go d'espace libre ou plus + +Configuration recommandée +------------------------- + +Pour les environnements de production, nous recommandons les spécifications suivantes : + +- Processeur : 4 cœurs ou plus +- Mémoire : 8 Go ou plus (à augmenter en fonction de la taille de l'index) +- Espace disque : + + - Zone système : 20 Go ou plus + - Zone de données : 3 fois la taille de l'index ou plus (réplicas inclus) + +- Réseau : 1 Gbit/s ou plus + +.. note:: + + Si la taille de l'index devient importante ou si vous effectuez des explorations à haute fréquence, + veuillez augmenter la mémoire et l'espace disque de manière appropriée. + +Configuration logicielle +======================== + +Système d'exploitation +---------------------- + +|Fess| fonctionne sur les systèmes d'exploitation suivants : + +**Linux** + +- Red Hat Enterprise Linux 8 ou ultérieur +- CentOS 8 ou ultérieur +- Ubuntu 20.04 LTS ou ultérieur +- Debian 11 ou ultérieur +- Autres distributions Linux (environnement capable d'exécuter Java 21) + +**Windows** + +- Windows Server 2019 ou ultérieur +- Windows 10 ou ultérieur + +**Autres** + +- macOS 11 (Big Sur) ou ultérieur (recommandé pour les environnements de développement uniquement ; OpenSearch ne publie pas de version macOS, installez-le avec Homebrew ou Docker) +- Environnement capable d'exécuter Docker + +Logiciels requis +---------------- + +Selon la méthode d'installation, les logiciels suivants sont nécessaires : + +Version ZIP/RPM/DEB +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- **Java 21** : `Eclipse Temurin `__ recommandé + + - OpenJDK 21 ou ultérieur + - Eclipse Temurin 21 ou ultérieur + +- **OpenSearch 3.9.0** : Obligatoire. |Fess| ne démarre pas avec un moteur antérieur à OpenSearch 3 + + - Version compatible : OpenSearch 3.9.0 + - Attention à la compatibilité des plugins avec les autres versions + +Version Docker +~~~~~~~~~~~~~~ + +- **Docker** : 20.10 ou ultérieur +- **Docker Compose** : 2.0 ou ultérieur + +Configuration réseau +==================== + +Ports requis +------------ + +Les ports principaux utilisés par |Fess| sont les suivants : + +.. list-table:: + :header-rows: 1 + :widths: 15 15 50 + + * - Port + - Protocole + - Utilisation + * - 8080 + - HTTP + - Interface Web |Fess| (écran de recherche/écran d'administration) + * - 9200 + - HTTP + - API HTTP OpenSearch (communication de |Fess| vers OpenSearch) + * - 9300 + - TCP + - Communication de transport OpenSearch (lors de la configuration en cluster) + +.. warning:: + + En environnement de production, il est fortement recommandé de restreindre l'accès direct depuis l'extérieur aux ports 9200 et 9300. + Ces ports ne doivent être utilisés que pour la communication interne entre |Fess| et OpenSearch. + +Configuration du pare-feu +------------------------- + +Si vous souhaitez rendre |Fess| accessible depuis l'extérieur, vous devez ouvrir le port 8080. + +**Linux (avec firewalld)** + +:: + + $ sudo firewall-cmd --permanent --add-port=8080/tcp + $ sudo firewall-cmd --reload + +**Linux (avec iptables)** + +:: + + $ sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT + $ sudo iptables-save + +Navigateurs Web compatibles +============================ + +Nous recommandons les navigateurs suivants pour l'écran d'administration et l'écran de recherche de |Fess| : + +- Google Chrome (dernière version) +- Mozilla Firefox (dernière version) +- Microsoft Edge (dernière version) +- Safari (dernière version) + +.. note:: + + Internet Explorer n'est pas pris en charge. + +Liste de vérification des prérequis +==================================== + +Avant l'installation, veuillez vérifier les éléments suivants : + +.. list-table:: + :header-rows: 1 + :widths: 50 50 + + * - Élément de vérification + - État + * - La configuration matérielle est-elle satisfaite ? + - □ + * - Java 21 est-il installé ? (sauf version Docker) + - □ + * - Docker est-il installé ? (version Docker) + - □ + * - Les ports nécessaires sont-ils disponibles ? + - □ + * - La configuration du pare-feu est-elle appropriée ? + - □ + * - Y a-t-il suffisamment d'espace disque disponible ? + - □ + * - La connexion réseau est-elle normale ? (si vous effectuez une exploration de sites externes) + - □ + +Étapes suivantes +================ + +Après avoir vérifié la configuration requise, passez à la procédure d'installation adaptée à votre environnement : + +- :doc:`install-linux` - Installation pour Linux (ZIP/RPM/DEB) +- :doc:`install-windows` - Installation pour Windows (ZIP) +- :doc:`install-docker` - Installation pour Docker +- :doc:`install` - Vue d'ensemble des méthodes d'installation diff --git a/fr/15.10/install/run.rst b/fr/15.10/install/run.rst new file mode 100644 index 000000000..489ef0e0e --- /dev/null +++ b/fr/15.10/install/run.rst @@ -0,0 +1,517 @@ +========================================== +Démarrage, arrêt et configuration initiale +========================================== + +Cette page décrit les procédures de démarrage, d'arrêt et de configuration initiale du serveur |Fess|. + +.. important:: + + Avant de démarrer |Fess|, veuillez obligatoirement démarrer OpenSearch. + Si OpenSearch n'est pas démarré, |Fess| ne fonctionnera pas correctement. + +Méthodes de démarrage +===================== + +Les procédures de démarrage diffèrent selon la méthode d'installation. + +Version ZIP +-------------- + +Démarrage d'OpenSearch +~~~~~~~~~~~~~~~~~~~~~~ + +:: + + $ cd /path/to/opensearch-3.9.0 + $ ./bin/opensearch + +Pour un démarrage en arrière-plan :: + + $ ./bin/opensearch -d + +.. note:: + + ``bin/fess-setup install opensearch`` place OpenSearch dans ``opensearch/opensearch-3.9.0`` du + répertoire de |Fess|. + +.. important:: + + Démarrez OpenSearch avec un utilisateur ordinaire. Il refuse de s'exécuter en tant que ``root`` + et se termine avec ``can not run opensearch as root``. Ce démarrage refusé laisse néanmoins des + fichiers tels que ``config/opensearch.keystore`` appartenant à ``root``, et le démarrage suivant + avec un utilisateur ordinaire échoue alors avec ``AccessDeniedException``. Rendez le répertoire + d'OpenSearch à cet utilisateur avant de le démarrer à nouveau, par exemple :: + + $ sudo chown -R /path/to/opensearch-3.9.0 + +Démarrage de Fess +~~~~~~~~~~~~~~~~~ + +:: + + $ cd /path/to/fess-15.10.0 + $ ./bin/fess + +Pour un démarrage en arrière-plan :: + + $ ./bin/fess -d + +.. note:: + + Le démarrage peut prendre quelques minutes. + Vous pouvez vérifier l'état du démarrage dans les fichiers de log du répertoire ``logs/`` : ``fess.log`` + contient les messages de |Fess| lui-même et ``server_0.log`` ceux du Tomcat intégré (y compris le + message de fin de démarrage). + +Version ZIP (Windows) +--------------------- + +Démarrage d'OpenSearch +~~~~~~~~~~~~~~~~~~~~~~ + +1. Ouvrez le répertoire d'installation d'OpenSearch +2. Double-cliquez sur ``opensearch.bat`` dans le dossier ``bin`` + +Ou depuis l'invite de commandes :: + + C:\> cd C:\opensearch-3.9.0 + C:\opensearch-3.9.0> bin\opensearch.bat + +Démarrage de Fess +~~~~~~~~~~~~~~~~~ + +1. Ouvrez le répertoire d'installation de Fess +2. Double-cliquez sur ``fess.bat`` dans le dossier ``bin`` + +Ou depuis l'invite de commandes :: + + C:\> cd C:\fess-15.10.0 + C:\fess-15.10.0> bin\fess.bat + +Version RPM/DEB (chkconfig) +--------------------------- + +Démarrage d'OpenSearch :: + + $ sudo service opensearch start + +Démarrage de Fess :: + + $ sudo service fess start + +Vérification de l'état de démarrage :: + + $ sudo service fess status + +Version RPM/DEB (systemd) +------------------------- + +Démarrage d'OpenSearch :: + + $ sudo systemctl start opensearch.service + +Démarrage de Fess :: + + $ sudo systemctl start fess.service + +Vérification de l'état de démarrage :: + + $ sudo systemctl status fess.service + +Activation du démarrage automatique du service :: + + $ sudo systemctl enable opensearch.service + $ sudo systemctl enable fess.service + +Version Docker +-------------- + +.. note:: + + ``compose.yaml`` et ``compose-opensearch3.yaml`` ne sont pas inclus dans |Fess| lui-même. Ils sont fournis par le projet docker-fess (https://github.com/codelibs/docker-fess) ; récupérez le dépôt et exécutez les commandes suivantes dans le répertoire ``compose``. + +Démarrage avec Docker Compose :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +Vérification de l'état de démarrage :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps + +Vérification des logs :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01 + +Vérification du démarrage +========================== + +Vérifiez que |Fess| a démarré normalement. + +Vérification de l'état de santé +-------------------------------- + +Accédez à l'URL suivante via un navigateur ou la commande curl :: + + http://localhost:8080/ + +Si le démarrage est normal, l'écran de recherche de Fess s'affiche. + +Vérification en ligne de commande :: + + $ curl -I http://localhost:8080/ + +Si ``HTTP/1.1 200 OK`` est retourné, le démarrage est normal. + +Vérification des logs +---------------------- + +Vérifiez les logs de démarrage pour confirmer qu'il n'y a pas d'erreurs. + +Version ZIP :: + + $ tail -f /path/to/fess-15.10.0/logs/fess.log + +Version RPM/DEB :: + + $ sudo tail -f /var/log/fess/fess.log + +Ou en utilisant journalctl :: + + $ sudo journalctl -u fess.service -f + +Version Docker :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01 + +.. tip:: + + Lorsque le démarrage se termine avec succès, un message de fin de démarrage comme celui-ci est écrit dans ``server_0.log``, dans le répertoire des logs (``logs/`` pour la version ZIP, ``/var/log/fess/`` pour la version RPM/DEB). Il n'apparaît ni sur la console ni dans ``fess.log`` : + + :: + + ...Booting the Tomcat: port=8080 contextPath= + ... + Boot successful: url -> http://localhost:8080 + +Accès via un navigateur +======================== + +Accédez aux URL suivantes pour vérifier l'interface Web. + +Écran de recherche +------------------ + +**URL** : http://localhost:8080/ + +L'écran de recherche de Fess s'affiche. Dans l'état initial, aucun résultat de recherche ne s'affiche car aucune configuration d'exploration n'a été effectuée. + +L'écran de recherche est ``bootstrap``, le thème statique fourni avec |Fess|. Pour modifier son apparence, +installez un autre thème depuis « Système » → « Thème » dans l'écran d'administration ou avec +``bin/fess-setup install theme `` (voir :doc:`fess-setup`), ou copiez le thème fourni et +modifiez la copie (voir :ref:`theme-customize-bundled`). + +Écran d'administration +----------------------- + +**URL** : http://localhost:8080/admin + +Compte administrateur par défaut : + +- **Nom d'utilisateur** : ``admin`` +- **Mot de passe** : ``admin`` + +.. warning:: + + **Note importante sur la sécurité** + + Veuillez obligatoirement changer le mot de passe par défaut. + En particulier dans les environnements de production, il est fortement recommandé de changer le mot de passe immédiatement après la première connexion. + +Configuration initiale +====================== + +Après vous être connecté à l'écran d'administration, effectuez les configurations initiales suivantes. + +Étape 1 : Modification du mot de passe administrateur +------------------------------------------------------ + +1. Connexion à l'écran d'administration (http://localhost:8080/admin) +2. Cliquez sur « Utilisateur » → « Utilisateur » dans le menu de gauche +3. Cliquez sur l'utilisateur ``admin`` +4. Saisissez un nouveau mot de passe dans le champ [Mot de passe] +5. Saisissez à nouveau le même mot de passe dans le champ [Mot de passe (confirmer)] +6. Cliquez sur le bouton [Mettre à jour] + +.. important:: + + Nous recommandons que le mot de passe satisfasse les conditions suivantes : + + - 8 caractères ou plus (longueur minimale requise définie par ``password.min.length``) + - Combinaison de majuscules, minuscules, chiffres et symboles + - Difficile à deviner + + Par défaut, seule la longueur minimale (8 caractères) est requise ; aucune combinaison de types de caractères n'est imposée. Les exigences relatives aux types de caractères peuvent être activées avec des paramètres tels que ``password.require.uppercase``. + +Étape 2 : Création de la configuration d'exploration +----------------------------------------------------- + +Créez une configuration pour explorer les sites ou systèmes de fichiers à rechercher. + +1. Cliquez sur « Explorateur » → « Web » dans le menu de gauche +2. Cliquez sur le bouton « Nouveau » +3. Saisissez les informations nécessaires : + + - **Nom** : Nom de la configuration d'exploration (exemple : Site Web de l'entreprise) + - **URL** : URL cible de l'exploration (exemple : https://www.example.com/). Pour spécifier plusieurs URL, saisissez une URL par ligne + - **Nombre d'accès maximum** : Nombre maximum de documents à explorer (facultatif) + - **Intervalle** : Temps d'attente entre les accès (en millisecondes ; valeur par défaut : ``10000``) + + .. note:: + + Les autres éléments (tels que l'agent utilisateur, le nombre de threads et la profondeur) utilisent leurs valeurs par défaut lorsqu'ils sont laissés vides. + +4. Cliquez sur le bouton « Créer » + +Étape 3 : Exécution de l'exploration +------------------------------------- + +1. Cliquez sur [Système] → [Planificateur] dans le menu de gauche +2. Ouvrez le job [Default Crawler] et cliquez sur le bouton « Démarrer maintenant » +3. Attendez la fin de l'exploration (la progression peut être vérifiée sur le tableau de bord) + +Étape 4 : Vérification de la recherche +--------------------------------------- + +1. Accédez à l'écran de recherche (http://localhost:8080/) +2. Saisissez un mot-clé de recherche +3. Vérifiez que les résultats de recherche s'affichent + +.. note:: + + L'exploration peut prendre du temps. + Pour les sites de grande envergure, cela peut prendre de plusieurs heures à plusieurs jours. + +Autres configurations recommandées +=================================== + +Pour une exploitation en environnement de production, veuillez également envisager les configurations suivantes. + +Principaux paramètres via les variables d'environnement +-------------------------------------------------------- + +Les paramètres tels que le numéro de port, la taille du tas JVM et l'URL de connexion à OpenSearch peuvent être modifiés via des variables d'environnement. Modifiez ``bin/fess.in.sh`` pour l'édition ZIP, ``/etc/sysconfig/fess`` pour l'édition RPM, et ``/etc/default/fess`` pour l'édition DEB. Un redémarrage de |Fess| est requis après toute modification. + +.. list-table:: + :header-rows: 1 + :widths: 30 25 45 + + * - Variable d'environnement + - Valeur par défaut + - Description + * - ``FESS_PORT`` + - ``8080`` + - Port HTTP sur lequel |Fess| écoute. + * - ``FESS_HEAP_SIZE`` + - (non défini) + - Taille du tas JVM. Définit la même valeur pour le minimum et le maximum. Lorsqu'elle n'est pas définie, un minimum de ``256m`` et un maximum de ``2g`` sont utilisés (l'édition ZIP Windows utilise un maximum de ``1g``) ; l'édition RPM/DEB utilise ``512m``. + * - ``SEARCH_ENGINE_HTTP_URL`` + - ``http://localhost:9200`` + - URL de l'OpenSearch auquel se connecter. Pour la version ZIP, ``bin/fess.in.sh`` définit cette valeur par défaut. Exportez la variable, ou modifiez ``bin/fess.in.sh``, lorsqu'OpenSearch s'exécute sur un port ou un hôte différent. L'édition RPM/DEB la définit dans le fichier d'environnement du paquet. + * - ``FESS_LOG_LEVEL`` + - ``warn`` + - Niveau de log de |Fess|. + * - ``FESS_HEAP_NEWSIZE`` + - (non défini) + - Taille de la jeune génération du tas JVM (``-Xmn``), par exemple ``256m``. Lorsqu'elle n'est pas définie, la JVM décide. + * - ``FESS_TEMP_PATH`` + - ``temp`` dans le répertoire de |Fess| (édition RPM/DEB : ``/var/tmp/fess``) + - Répertoire des fichiers temporaires, y compris le répertoire de travail du Tomcat intégré. L'utilisateur qui exécute |Fess| doit pouvoir y écrire. + * - ``FESS_CONF_PATH`` + - (non défini) (édition RPM/DEB : ``/etc/fess``) + - Répertoire contenant les fichiers de configuration. ``bin/fess`` le place au début du classpath et le transmet à |Fess| sous la forme ``-Dfess.conf.path``. Pour les fichiers tels que ``tomcat_config.properties`` de ``lib/classes``, celui de ce répertoire est prioritaire. Toutefois, dans l'édition ZIP, l'application Web lit d'abord les fichiers de ``app/WEB-INF/classes`` ; un ``fess_config.properties`` placé dans ce répertoire ne remplace donc pas les valeurs du ``fess_config.properties`` de ``app/WEB-INF/classes`` (les processus enfants, comme le crawler, lisent ce répertoire avant ``WEB-INF/classes``). Dans l'édition ZIP, modifiez le fichier de ``app/WEB-INF/classes`` pour changer ``fess_config.properties``. L'édition RPM/DEB ne place pas de ``fess_config.properties`` dans ``app/WEB-INF/classes`` et utilise uniquement celui de ``/etc/fess``. + * - ``FESS_USE_IPV4`` + - (non défini) + - Avec n'importe quelle valeur non vide, la JVM n'utilise que la pile IPv4 (``-Djava.net.preferIPv4Stack=true``). + * - ``FESS_USE_GC_LOGGING`` + - (non défini) + - Avec n'importe quelle valeur non vide, la JVM écrit son log du ramasse-miettes dans ``gc-fess.log``, dans le répertoire des logs (jusqu'à 5 fichiers de 64 Mo). + +.. note:: + + Parmi ces variables d'environnement, l'édition ZIP Windows (``bin\fess.in.bat``) lit ``FESS_HEAP_SIZE``, ``FESS_HEAP_NEWSIZE``, ``FESS_USE_IPV4`` et ``FESS_USE_GC_LOGGING``, + ainsi que les variables d'environnement suivantes, absentes du tableau : + + - ``FESS_MIN_MEM``, ``FESS_MAX_MEM`` : définissent séparément la taille minimale et maximale du tas (ignorées si ``FESS_HEAP_SIZE`` est défini). + - ``FESS_DIRECT_SIZE`` : limite de la mémoire directe (``-XX:MaxDirectMemorySize``). + - ``FESS_DICTIONARY_PATH`` : répertoire ``config\dictionary`` d'OpenSearch. + - ``FESS_PROXY_HOST``, ``FESS_PROXY_PORT``, ``FESS_NON_PROXY_HOSTS`` : paramètres du proxy. + - ``FESS_JAVA_OPTS`` : ``fess.in.bat`` ajoute ces options JVM après les valeurs déjà configurées. + - ``PLAYWRIGHT_NODEJS_PATH`` : exécutable Node.js utilisé par le plugin Playwright. + - ``JAVA_HOME`` : obligatoire. + + ``FESS_PORT``, ``FESS_LOG_LEVEL``, ``FESS_TEMP_PATH``, ``FESS_CONF_PATH`` et ``SEARCH_ENGINE_HTTP_URL`` + ne sont pas lues. Ces valeurs sont écrites directement dans le fichier ; modifiez ``bin\fess.in.bat`` directement pour les changer. + +Configuration du serveur de messagerie +--------------------------------------- + +Pour recevoir des notifications d'échec et autres messages par e-mail, configurez le serveur SMTP et l'adresse du destinataire des notifications. + +1. Dans ``fess_env_web.properties`` et ``fess_env_crawler.properties``, spécifiez l'hôte et le port du serveur SMTP dans ``mail.smtp.server.main.host.and.port`` (valeur par défaut : ``localhost:25``). Les fichiers se trouvent dans ``app/WEB-INF/classes/`` pour le paquet ZIP et dans ``/etc/fess/`` pour les paquets RPM/DEB. Le processus web de |Fess| lit le premier, et le crawler, qui envoie l'e-mail de fin d'exploration, lit le second ; ``fess_env.properties`` n'est pas utilisé. Un redémarrage de |Fess| est requis après la modification. +2. Dans l'interface d'administration, cliquez sur [Système] → [Général] dans le menu de gauche. +3. Saisissez l'adresse e-mail du destinataire dans le champ [E-mail de notification]. +4. Cliquez sur le bouton [Mettre à jour]. +5. Vous pouvez vérifier que l'envoi d'e-mail fonctionne correctement avec le bouton [Envoyer un e-mail de test]. + +Configuration du fuseau horaire +-------------------------------- + +|Fess| utilise le fuseau horaire du serveur (OS / JVM). Il n'existe pas de paramètre permettant de modifier le fuseau horaire dans l'interface d'administration. Pour le modifier, changez le paramètre de fuseau horaire de l'OS, ou ajoutez l'option JVM ``-Duser.timezone=Asia/Tokyo`` à ``FESS_JAVA_OPTS`` dans ``bin/fess.in.sh`` (sous Windows, ``bin\fess.in.bat``). + +Ajustement du niveau de log +---------------------------- + +En production, vous pouvez ajuster le niveau de log pour réduire l'utilisation du disque. + +Le niveau de log global de |Fess| peut être modifié avec la variable d'environnement ``FESS_LOG_LEVEL`` (valeur par défaut : ``warn``). Pour contrôler les journaliseurs individuels en détail, modifiez le fichier de configuration ``app/WEB-INF/classes/log4j2.xml``. L'exploration, les suggestions et la génération de miniatures s'exécutent comme des processus séparés ; configurez donc leurs niveaux de log individuellement dans ``app/WEB-INF/env/{crawler,suggest,thumbnail}/resources/log4j2.xml``. + +Pour plus de détails, consultez :doc:`../admin/index`. + +Méthodes d'arrêt +================ + +Version ZIP +------------------ + +Arrêt de Fess +~~~~~~~~~~~~~ + +Tuez le processus :: + + $ ps aux | grep fess + $ kill + +Ou arrêtez depuis la console avec ``Ctrl+C`` (si vous l'exécutez au premier plan). + +Arrêt d'OpenSearch :: + + $ ps aux | grep opensearch + $ kill + +Version RPM/DEB (chkconfig) +--------------------------- + +Arrêt de Fess :: + + $ sudo service fess stop + +Arrêt d'OpenSearch :: + + $ sudo service opensearch stop + +Version RPM/DEB (systemd) +------------------------- + +Arrêt de Fess :: + + $ sudo systemctl stop fess.service + +Arrêt d'OpenSearch :: + + $ sudo systemctl stop opensearch.service + +Version Docker +-------------- + +Arrêt des conteneurs :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop + +Arrêt et suppression des conteneurs :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +.. warning:: + + Pour supprimer également les volumes avec la commande ``down``, ajoutez l'option ``-v``. + Dans ce cas, toutes les données seront supprimées, soyez vigilant. + +Méthodes de redémarrage +======================== + +Version ZIP +------------------ + +Arrêtez puis démarrez. + +Version RPM/DEB +--------------- + +chkconfig :: + + $ sudo service fess restart + +systemd :: + + $ sudo systemctl restart fess.service + +Version Docker +-------------- + +:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml restart + +Dépannage +========= + +En cas de non-démarrage +----------------------- + +1. **Vérifiez qu'OpenSearch est démarré** + + :: + + $ curl http://localhost:9200/ + + Si OpenSearch n'est pas démarré, démarrez d'abord OpenSearch. + +2. **Vérifiez les conflits de ports** + + :: + + $ sudo ss -tuln | grep 8080 + + Si net-tools est installé, ``sudo netstat -tuln | grep 8080`` affiche les mêmes informations. + + Si le port 8080 est déjà utilisé, modifiez le numéro de port. + + - Édition ZIP : modifiez ``FESS_PORT`` dans ``bin/fess.in.sh`` + - Édition ZIP (Windows) : modifiez ``-Dfess.port=8080`` directement dans ``bin\fess.in.bat`` + - Édition RPM : modifiez ``FESS_PORT`` dans ``/etc/sysconfig/fess`` + - Édition DEB : modifiez ``FESS_PORT`` dans ``/etc/default/fess`` + +3. **Vérifiez les logs** + + Vérifiez les messages d'erreur pour identifier le problème. + +4. **Vérifiez la version de Java** + + :: + + $ java -version + + Vérifiez que Java 21 ou ultérieur est installé. + +Pour un dépannage détaillé, consultez :doc:`troubleshooting`. + +Étapes suivantes +================ + +Une fois |Fess| démarré normalement, consultez les documents suivants pour commencer l'exploitation : + +- :doc:`../admin/index` - Détails sur la configuration de l'exploration, la configuration de la recherche et la configuration du système +- :doc:`security` - Configuration de la sécurité pour les environnements de production +- :doc:`troubleshooting` - Problèmes courants et solutions +- :doc:`upgrade` - Procédure de mise à niveau de version +- :doc:`uninstall` - Procédure de désinstallation diff --git a/fr/15.10/install/security.rst b/fr/15.10/install/security.rst new file mode 100644 index 000000000..3d4de589d --- /dev/null +++ b/fr/15.10/install/security.rst @@ -0,0 +1,355 @@ +============================ +Configuration de la sécurité +============================ + +Cette page décrit les configurations de sécurité recommandées pour exploiter |Fess| en toute sécurité dans un environnement de production. + +.. danger:: + + **La sécurité est extrêmement importante** + + Dans les environnements de production, il est fortement recommandé de mettre en œuvre toutes les configurations de sécurité décrites sur cette page. + Le non-respect des configurations de sécurité augmente les risques d'accès non autorisé, de fuite de données et de compromission du système. + +Configurations de sécurité obligatoires +======================================== + +Modification du mot de passe administrateur +-------------------------------------------- + +Veuillez obligatoirement modifier le mot de passe administrateur par défaut (``admin`` / ``admin``). + +**Procédure :** + +1. Connexion à l'écran d'administration : http://localhost:8080/admin +2. Cliquez sur « Utilisateur » → « Utilisateur » +3. Sélectionnez l'utilisateur ``admin`` +4. Définissez un mot de passe fort +5. Cliquez sur le bouton « Mettre à jour » + +.. note:: + + Une fois le mot de passe modifié à partir de ``admin``, il n'est plus possible de le redéfinir avec une valeur aussi simple que ``admin`` (une liste noire de mots de passe administrateur est configurée via ``password.invalid.admin.passwords``). Vous pouvez également modifier le mot de passe initial de l'utilisateur ``admin`` avant le premier démarrage en définissant ``index.user.initial_password`` dans ``fess_config.properties``. + +**Politique de mot de passe recommandée :** + +|Fess| dispose d'une fonctionnalité intégrée qui impose des exigences de longueur minimale/maximale et de types de caractères pour le mot de passe. Configurez les propriétés suivantes dans ``fess_config.properties`` (les valeurs par défaut sont indiquées entre parenthèses) : + +- ``password.min.length`` (par défaut : ``8``) : Longueur minimale. Une valeur de 12 caractères ou plus est recommandée. +- ``password.max.length`` (par défaut : ``100``) : Longueur maximale. +- ``password.require.uppercase`` (par défaut : ``false``) : Exiger des lettres majuscules. +- ``password.require.lowercase`` (par défaut : ``false``) : Exiger des lettres minuscules. +- ``password.require.digit`` (par défaut : ``false``) : Exiger des chiffres. +- ``password.require.special.char`` (par défaut : ``false``) : Exiger des symboles. + +.. note:: + + Par défaut, la longueur minimale est de ``8`` caractères et toutes les exigences de type de caractères sont désactivées. Pour renforcer la sécurité des mots de passe, définissez explicitement les propriétés ci-dessus. Notez que |Fess| ne dispose pas de fonctionnalité d'expiration des mots de passe (changement périodique forcé) ; si vous souhaitez imposer un changement périodique du mot de passe comme règle opérationnelle, faites-le manuellement. + +Activation du plugin de sécurité OpenSearch +-------------------------------------------- + +**Procédure :** + +1. Supprimez ou commentez la ligne suivante dans ``opensearch.yml`` :: + + # plugins.security.disabled: true + +2. Configuration du plugin de sécurité :: + + plugins.security.allow_default_init_securityindex: true + plugins.security.authcz.admin_dn: + - CN=admin,OU=SSL,O=Test,L=Test,C=DE + +3. Configuration des certificats TLS/SSL + +4. Redémarrage d'OpenSearch + +5. Configurez la connexion à OpenSearch du côté |Fess|. + + Spécifiez l'URL de connexion via la variable d'environnement ``SEARCH_ENGINE_HTTP_URL`` (modifiez ``bin/fess.in.sh`` ou le fichier d'environnement du service ; la valeur par défaut provient de ``search_engine.http.url`` dans ``fess_config.properties``) :: + + SEARCH_ENGINE_HTTP_URL=https://opensearch:9200 + + Spécifiez les informations d'authentification via les propriétés suivantes dans ``fess_config.properties`` (il n'existe pas de variables d'environnement ``SEARCH_ENGINE_USERNAME`` / ``SEARCH_ENGINE_PASSWORD``) :: + + search_engine.username=admin + search_engine.password= + +Pour plus de détails, consultez `OpenSearch Security Plugin `__. + +Activation de HTTPS +------------------- + +La communication HTTP n'est pas chiffrée, ce qui présente des risques d'écoute et de falsification. Utilisez obligatoirement HTTPS dans les environnements de production. + +**Méthode 1 : Utilisation d'un proxy inverse (recommandé)** + +Placez Nginx ou Apache devant |Fess| pour terminer HTTPS. + +Exemple de configuration Nginx :: + + server { + listen 443 ssl http2; + server_name your-fess-domain.com; + + ssl_certificate /path/to/cert.pem; + ssl_certificate_key /path/to/key.pem; + + ssl_protocols TLSv1.2 TLSv1.3; + ssl_ciphers HIGH:!aNULL:!MD5; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + } + +**Méthode 2 : Configuration HTTPS directement dans Fess** + +Ajoutez ce qui suit à ``tomcat_config.properties`` :: + + tomcat.secure=true + tomcat.scheme=https + tomcat.SSLEnabled=true + tomcat.certificateKeystoreFile=[chemin vers le fichier keystore] + tomcat.certificateKeystorePassword=[mot de passe spécifié lors de la création du fichier keystore] + tomcat.certificateKeyAlias=[alias du certificat] + tomcat.sslProtocol=[protocole SSL (ex. TLS)] + tomcat.enabledProtocols=liste des protocoles activés (séparés par des virgules) (ex. TLSv1.2,TLSv1.1,TLSv1) + +Configurations de sécurité recommandées +======================================== + +Configuration du pare-feu +------------------------- + +Ouvrez uniquement les ports nécessaires et fermez les ports inutiles. + +**Ports à ouvrir :** + +- **8080** (ou 443 pour HTTPS) : Interface Web |Fess| (si un accès externe est nécessaire) +- **22** : SSH (pour l'administration, uniquement depuis des adresses IP de confiance) + +**Ports à fermer :** + +- **9200, 9300** : OpenSearch (communication interne uniquement, bloquer l'accès externe) + +Exemple de configuration Linux (firewalld) :: + + $ sudo firewall-cmd --permanent --add-service=http + $ sudo firewall-cmd --permanent --add-service=https + $ sudo firewall-cmd --permanent --remove-service=opensearch # En cas de service personnalisé + $ sudo firewall-cmd --reload + +Restriction d'adresse IP :: + + $ sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="192.168.1.0/24" port port="8080" protocol="tcp" accept' + +Configuration du contrôle d'accès +---------------------------------- + +Envisagez de restreindre l'accès à l'écran d'administration à des adresses IP spécifiques. + +Exemple de restriction d'accès avec Nginx :: + + location /admin { + allow 192.168.1.0/24; + deny all; + + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + } + +Rôles et contrôle d'accès +-------------------------- + +|Fess| fournit deux rôles intégrés : + +- ``admin`` : Rôle administrateur pouvant effectuer toutes les opérations, y compris sur l'écran d'administration. +- ``guest`` : Rôle attribué aux utilisateurs non authentifiés (anonymes). + +Tous les autres rôles peuvent être librement créés depuis l'écran d'administration. Dans |Fess|, un rôle est une étiquette ne comportant qu'un nom, principalement utilisée pour le contrôle d'accès aux résultats de recherche (quels documents un utilisateur peut consulter). L'exception est un rôle nommé ``admin-`` suivi du nom d'un écran d'administration, tel que ``admin-user`` ou ``admin-scheduler`` : il permet à un utilisateur d'ouvrir cet écran, et la forme ``-view``, telle que ``admin-user-view``, donne un accès en lecture seule. + +.. warning:: + + Les rôles ``admin-*`` permettent de répartir les écrans d'administration courants entre plusieurs opérateurs, mais ils ne constituent pas une frontière de privilèges. Un utilisateur disposant de ``admin-user`` peut attribuer n'importe quel rôle existant, y compris le rôle administrateur, à n'importe quel utilisateur ; ``admin-accesstoken`` peut émettre un jeton d'accès avec la permission ``Radmin-api``, qui donne accès à l'ensemble de l'API Admin ; ``admin-scheduler`` peut exécuter des tâches de script sur le serveur, et ``admin-plugin`` peut installer des plugins. Traitez chaque rôle ``admin-*`` comme équivalent au rôle administrateur (``authentication.admin.roles``, valeur par défaut ``admin``) et accordez-le uniquement à des opérateurs de confiance. + +Conformément au principe du moindre privilège, accordez le rôle administrateur (``admin``) uniquement aux utilisateurs effectuant des tâches d'administration, et ne l'accordez pas aux utilisateurs de recherche généraux. + +**Procédure :** + +1. Cliquez sur « Utilisateur » → « Rôle » dans l'écran d'administration +2. Créez les rôles nécessaires +3. Attribuez des rôles aux utilisateurs dans « Utilisateur » → « Utilisateur » + +Journalisation d'audit +------------------------ + +L'historique des opérations du système, telles que l'authentification et les opérations d'administration, est enregistré par défaut sous forme de journal d'audit. Le journal d'audit est généré par le logger ``fess.log.audit`` défini dans ``log4j2.xml``, et sa destination de sortie par défaut est ``audit.log``. + +Étant activé par défaut, aucune configuration supplémentaire n'est nécessaire. Pour personnaliser la destination de sortie ou le niveau de journalisation, modifiez la définition suivante dans ``log4j2.xml`` :: + + + + + +Mises à jour de sécurité régulières +------------------------------------ + +Veuillez appliquer régulièrement les mises à jour de sécurité de |Fess| et OpenSearch. + +**Procédure recommandée :** + +1. Vérifier régulièrement les informations de sécurité + + - `Informations sur les versions de Fess `__ + - `Avis de sécurité OpenSearch `__ + +2. Valider les mises à jour dans un environnement de test +3. Appliquer les mises à jour dans l'environnement de production + +Protection des données +======================= + +Chiffrement des sauvegardes +---------------------------- + +Les données de sauvegarde peuvent contenir des informations confidentielles. Veuillez chiffrer et stocker les fichiers de sauvegarde. + +Exemple de sauvegarde chiffrée :: + + $ tar czf fess-backup.tar.gz /var/lib/opensearch /etc/fess + $ gpg --symmetric --cipher-algo AES256 fess-backup.tar.gz + +Meilleures pratiques de sécurité +================================= + +Principe du moindre privilège +------------------------------ + +- Ne pas exécuter Fess et OpenSearch en tant qu'utilisateur root +- Exécuter avec un compte utilisateur dédié +- Accorder les permissions minimales nécessaires sur le système de fichiers + +Isolation réseau +---------------- + +- Placer OpenSearch sur un réseau privé +- Utiliser un VPN ou un réseau privé pour les communications internes +- Placer uniquement l'interface Web |Fess| dans la DMZ + +Audit de sécurité régulier +--------------------------- + +- Vérifier régulièrement les journaux d'accès +- Détecter les modèles d'accès anormaux +- Effectuer régulièrement des analyses de vulnérabilité + +Configuration des en-têtes de sécurité +--------------------------------------- + +Si nécessaire, configurez les en-têtes de sécurité dans Nginx ou Apache :: + + add_header X-Frame-Options "SAMEORIGIN" always; + add_header X-Content-Type-Options "nosniff" always; + add_header X-XSS-Protection "1; mode=block" always; + add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; + add_header Content-Security-Policy "default-src 'self'" always; + +Liste de vérification de sécurité +================================== + +Avant de déployer en environnement de production, veuillez vérifier la liste de contrôle suivante : + +Configuration de base +--------------------- + +- [ ] Mot de passe administrateur modifié +- [ ] HTTPS activé +- [ ] Numéro de port par défaut modifié (optionnel) + +Sécurité réseau +--------------- + +- [ ] Ports inutiles fermés par le pare-feu +- [ ] Accès à l'écran d'administration restreint par IP (si possible) +- [ ] Accès à OpenSearch restreint au réseau interne uniquement + +Contrôle d'accès +---------------- + +- [ ] Rôles et permissions d'accès configurés de manière appropriée (rôle administrateur accordé uniquement aux utilisateurs nécessaires) +- [ ] Comptes utilisateurs inutiles supprimés +- [ ] Politique de mot de passe configurée + +Surveillance et journalisation +------------------------------- + +- [ ] Vérifié que les journaux d'audit sont activés +- [ ] Période de conservation des journaux configurée +- [ ] Mécanisme de surveillance des journaux établi (si possible) + +Sauvegarde et récupération +--------------------------- + +- [ ] Planification de sauvegarde régulière configurée +- [ ] Données de sauvegarde chiffrées +- [ ] Procédure de restauration validée + +Gestion des mises à jour et des correctifs +------------------------------------------- + +- [ ] Mécanisme de réception des notifications de mises à jour de sécurité établi +- [ ] Procédure de mise à jour documentée +- [ ] Système de validation des mises à jour en environnement de test établi + +Réponse aux incidents de sécurité +================================== + +Procédure de réponse en cas d'incident de sécurité : + +1. **Détection de l'incident** + + - Vérification des journaux + - Détection de modèles d'accès anormaux + - Vérification du comportement anormal du système + +2. **Réponse initiale** + + - Identification de l'étendue de l'impact + - Prévention de l'expansion des dommages (arrêt du service concerné, etc.) + - Préservation des preuves + +3. **Enquête et analyse** + + - Analyse détaillée des journaux + - Identification du chemin d'intrusion + - Identification des données potentiellement divulguées + +4. **Récupération** + + - Correction des vulnérabilités + - Restauration du système + - Renforcement de la surveillance + +5. **Suivi** + + - Création d'un rapport d'incident + - Mise en œuvre de mesures préventives + - Rapport aux parties prenantes + +Informations de référence +========================== + +- `OpenSearch Security Plugin `__ +- `OWASP Top 10 `__ +- `CIS Benchmarks `__ + +Pour toute question ou problème de sécurité, veuillez nous contacter : + +- Issues : https://github.com/codelibs/fess/issues +- Assistance commerciale : https://www.n2sm.net/ diff --git a/fr/15.10/install/troubleshooting.rst b/fr/15.10/install/troubleshooting.rst new file mode 100644 index 000000000..994cde4f1 --- /dev/null +++ b/fr/15.10/install/troubleshooting.rst @@ -0,0 +1,596 @@ +============== +Dépannage +============== + +Cette page décrit les problèmes courants lors de l'installation, du démarrage et de l'exploitation de |Fess|, ainsi que leurs solutions. + +Problèmes lors de l'installation +================================= + +Java n'est pas reconnu +----------------------- + +**Symptôme :** + +:: + + -bash: java: command not found + +Ou :: + + 'java' is not recognized as an internal or external command + +**Cause :** + +Java n'est pas installé, ou la variable d'environnement PATH n'est pas correctement configurée. + +**Solution :** + +1. Vérifiez si Java est installé :: + + $ which java + $ java -version + +2. Si non installé, installez Java 21 :: + + # Ubuntu/Debian + $ sudo apt-get update + $ sudo apt-get install openjdk-21-jdk + + # RHEL/CentOS + $ sudo yum install java-21-openjdk + + Les dépôts standard de Debian 12 ne proposent pas de paquet ``openjdk-21-jdk``. Sous Debian 12, installez plutôt Eclipse Temurin 21 en suivant les instructions pour Debian du `guide d'installation d'Adoptium pour Linux `__. + +3. Configurez la variable d'environnement JAVA_HOME :: + + $ export JAVA_HOME=/path/to/java + $ export PATH=$JAVA_HOME/bin:$PATH + + Pour une configuration permanente, ajoutez à ``~/.bashrc`` ou ``/etc/profile``. + +Échec de l'installation des plugins +------------------------------------ + +**Symptôme :** + +:: + + ERROR: Plugin installation failed + +**Cause :** + +- Problème de connexion réseau +- La version du plugin ne correspond pas à la version d'OpenSearch +- Problème de permissions + +**Solution :** + +1. Vérifiez la version d'OpenSearch :: + + $ /path/to/opensearch/bin/opensearch --version + +2. Adaptez la version du plugin à celle d'OpenSearch :: + + $ /path/to/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + +3. Vérifiez les permissions :: + + $ sudo /path/to/opensearch/bin/opensearch-plugin install ... + +4. Pour une installation via proxy :: + + $ export ES_JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080" + $ /path/to/opensearch/bin/opensearch-plugin install ... + +Problèmes lors du démarrage +============================ + +Fess ne démarre pas +------------------- + +**Symptôme :** + +Une erreur se produit lors de l'exécution de la commande de démarrage de Fess, ou le processus se termine immédiatement. + +**Points de vérification :** + +1. **Vérifiez qu'OpenSearch est démarré** :: + + $ curl http://localhost:9200/ + + Si le démarrage est normal, une réponse JSON est retournée. + + Lorsqu'aucun OpenSearch ne répond, |Fess| réessaie pendant environ une minute, puis interrompt + son démarrage avec le message suivant sur la console et dans ``logs/fess.log`` :: + + The search engine at http://localhost:9200 did not become available within 60221ms. Check that OpenSearch is running and reachable. If there is none yet, run bin/fess-setup install opensearch to set one up. + + Démarrez OpenSearch, ou vérifiez ``SEARCH_ENGINE_HTTP_URL``. Une nouvelle installation ZIP ne + dispose d'aucun OpenSearch tant qu'il n'a pas été mis en place avec + ``bin/fess-setup install opensearch`` ; consultez :doc:`install-linux`. + +2. **Vérifiez les conflits de ports** :: + + $ sudo ss -tuln | grep 8080 + + Si le port 8080 est déjà utilisé, modifiez le numéro de port dans le fichier de configuration. + +3. **Vérifiez les fichiers journaux** :: + + $ tail -f /path/to/fess/logs/fess.log + + Identifiez la cause à partir des messages d'erreur. + +4. **Vérifiez la version de Java** :: + + $ java -version + + Vérifiez que Java 21 ou ultérieur est installé. + +5. **Vérifiez la mémoire insuffisante** :: + + $ free -h + + Si la mémoire est insuffisante, ajustez la taille du tas ou augmentez la mémoire système. + +OpenSearch ne démarre pas +-------------------------- + +**Symptôme :** + +:: + + ERROR: bootstrap checks failed + +**Cause :** + +La configuration du système ne satisfait pas aux exigences d'OpenSearch. + +**Solution :** + +1. **Configuration de vm.max_map_count** :: + + $ sudo sysctl -w vm.max_map_count=262144 + + Pour une configuration permanente :: + + $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf + $ sudo sysctl -p + +2. **Augmentation de la limite des descripteurs de fichiers** :: + + $ sudo vi /etc/security/limits.conf + + Ajoutez :: + + opensearch - nofile 65535 + opensearch - nproc 4096 + +3. **Configuration du verrouillage mémoire** :: + + $ sudo vi /etc/security/limits.conf + + Ajoutez :: + + opensearch - memlock unlimited + +4. Redémarrez OpenSearch :: + + $ sudo systemctl restart opensearch + +Impossible de créer l'index (chemin des fichiers de dictionnaire) +----------------------------------------------------------------- + +**Symptôme :** + +L'accès à |Fess| renvoie une erreur HTTP 404 et l'erreur suivante est enregistrée dans ``fess.log`` :: + + Failed to create index: index=fess, path=fess_indices/fess.json + ... reason=Resource path must be inside config directory: /var/lib/opensearch/data/config/ja/mapping.txt + +**Cause :** + +À partir d'OpenSearch 3.8.0, la création d'un index est refusée si les fichiers de dictionnaire se trouvent en dehors du répertoire de configuration d'OpenSearch. +``configsync.config_path`` et ``FESS_DICTIONARY_PATH`` pointent vers un emplacement situé en dehors du répertoire de configuration (par exemple ``data/config/``). + +**Solution :** + +1. Modifiez ``configsync.config_path`` et ``FESS_DICTIONARY_PATH`` pour qu'ils pointent vers un répertoire situé sous le répertoire de configuration d'OpenSearch. + + - Version RPM/DEB : ``/etc/opensearch/dictionary/`` + - Version ZIP : ``/path/to/opensearch-3.9.0/config/dictionary/`` + +2. Si des fichiers de dictionnaire existent déjà, copiez-les dans le nouveau répertoire. +3. Redémarrez OpenSearch, puis |Fess|. + +Pour plus de détails, consultez :doc:`install-linux`. + +Conflit de numéros de port +--------------------------- + +**Symptôme :** + +:: + + Address already in use + +**Solution :** + +1. Vérifiez les ports utilisés :: + + $ sudo ss -tuln | grep 8080 + $ sudo lsof -i :8080 + +2. Arrêtez le processus utilisé, ou modifiez le numéro de port de Fess + + Pour modifier le numéro de port, consultez :doc:`Configuration du port et du réseau <../config/setup-port-network>`. + +Problèmes de connexion +======================= + +Fess ne peut pas se connecter à OpenSearch +------------------------------------------- + +**Symptôme :** + +Les journaux affichent des erreurs telles que :: + + Connection refused + ou + No route to host + +**Solution :** + +1. **Vérifiez qu'OpenSearch est démarré** :: + + $ curl http://localhost:9200/ + +2. **Vérifiez l'URL de connexion** + + Vérifiez que l'URL configurée dans ``fess.in.sh`` ou ``fess.in.bat`` est correcte :: + + SEARCH_ENGINE_HTTP_URL=http://localhost:9200 + +3. **Vérifiez le pare-feu** :: + + $ sudo firewall-cmd --list-all + + Vérifiez que le port 9200 est ouvert. + +4. **Vérifiez la connexion réseau** + + Si vous exécutez OpenSearch sur un autre hôte :: + + $ ping opensearch-host + $ telnet opensearch-host 9200 + +Impossible d'accéder à Fess depuis le navigateur +------------------------------------------------- + +**Symptôme :** + +Impossible d'accéder à http://localhost:8080/ via le navigateur. + +**Solution :** + +1. **Vérifiez que Fess est démarré** :: + + $ ps aux | grep fess + +2. **Essayez d'accéder depuis localhost** :: + + $ curl http://localhost:8080/ + +3. **Vérifiez le pare-feu** :: + + $ sudo firewall-cmd --list-all + + Vérifiez que le port 8080 est ouvert. + +4. **Si vous accédez depuis un autre hôte** + + Vérifiez que Fess écoute sur autre chose que localhost :: + + $ ss -tuln | grep 8080 + + Si c'est ``127.0.0.1:8080``, modifiez la configuration pour écouter sur ``0.0.0.0:8080`` ou une adresse IP spécifique. + +Problèmes de performances +========================== + +La recherche est lente +----------------------- + +**Cause :** + +- Taille de l'index importante +- Mémoire insuffisante +- E/S disque lentes +- Requête complexe + +**Solution :** + +1. **Augmentez la taille du tas** + + Démarrez |Fess| en transmettant ``FESS_HEAP_SIZE`` comme variable d'environnement :: + + $ FESS_HEAP_SIZE=4g bin/fess + + Si vous le définissez dans ``bin/fess.in.sh``, écrivez ``FESS_HEAP_SIZE=4g`` **avant** la ligne qui détermine la taille du tas (celle qui définit la valeur par défaut de ``FESS_MIN_MEM``). Si vous l'ajoutez à la fin du fichier, la taille du tas est déjà décidée à ce stade et la valeur n'est pas prise en compte. Pour les versions RPM/DEB, définissez-le dans ``/etc/sysconfig/fess`` (``/etc/default/fess`` pour la version DEB). + + Ajustez également la taille du tas d'OpenSearch :: + + export OPENSEARCH_JAVA_OPTS="-Xms4g -Xmx4g" + +2. **Utilisez un SSD** + + Si les E/S disque sont le goulot d'étranglement, migrez vers un SSD. + +3. **Activez le cache** + + Activez le cache de requêtes dans le fichier de configuration. + +L'exploration est lente +------------------------ + +**Cause :** + +- Intervalle d'exploration long +- Réponse lente du site cible +- Nombre de threads faible + +**Solution :** + +1. **Ajustez l'intervalle d'exploration** + + Raccourcissez l'« Intervalle » de la configuration d'exploration dans l'écran d'administration (en millisecondes). + + .. warning:: + + Un intervalle trop court peut surcharger le site cible. Configurez une valeur appropriée. + +2. **Augmentez le nombre de threads** + + Augmentez le « Nombre de threads » de la configuration d'exploration dans l'écran d'administration. La valeur par défaut est 1 pour l'exploration Web et 5 pour l'exploration du système de fichiers. + +3. **Ajustez la valeur de timeout** + + Pour les sites à réponse lente, augmentez la valeur de timeout. + +Problèmes de données +===================== + +Les résultats de recherche ne s'affichent pas +---------------------------------------------- + +**Cause :** + +- L'index n'a pas été créé +- L'exploration a échoué +- La requête de recherche est incorrecte + +**Solution :** + +1. **Vérifiez l'index** :: + + $ curl http://localhost:9200/_cat/indices?v + + Vérifiez que l'index de |Fess| existe. + +2. **Vérifiez les journaux d'exploration** + + Téléchargez le journal d'exploration (``fess-crawler.log``) depuis « Informations système » → « Fichier journal » dans l'écran d'administration et recherchez-y les erreurs. + +3. **Réexécutez l'exploration** + + Exécutez « Default Crawler » depuis « Système » → « Planificateur » dans l'écran d'administration. + +4. **Simplifiez la requête de recherche** + + Effectuez d'abord une recherche avec un mot-clé simple pour vérifier que des résultats sont retournés. + +L'index est corrompu +-------------------- + +**Symptôme :** + +Des erreurs se produisent lors de la recherche, ou des résultats inattendus sont retournés. + +**Solution :** + +1. **Supprimez et recréez l'index** + + .. warning:: + + La suppression de l'index entraînera la perte de toutes les données de recherche. Veuillez obligatoirement effectuer une sauvegarde. + + :: + + $ curl -X DELETE http://localhost:9200/fess* + +2. **Redémarrez Fess** + + Les index sont créés au démarrage de |Fess|. Juste après la suppression, l'index des informations utilisateur a également disparu : vous ne pouvez donc pas vous connecter à l'écran d'administration (``/api/v2/health`` continue de renvoyer ``200``). Au redémarrage de |Fess|, les index, les travaux par défaut et l'utilisateur initial (``admin``) sont recréés. + +3. **Réexécutez l'exploration** + + Exécutez « Default Crawler » depuis l'écran d'administration pour enregistrer à nouveau les documents à rechercher. + +Problèmes spécifiques à Docker +=============================== + +Le conteneur ne démarre pas +---------------------------- + +**Symptôme :** + +Le conteneur ne démarre pas avec ``docker compose up``. + +**Solution :** + +1. **Vérifiez les journaux** :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs + +2. **Vérifiez la mémoire insuffisante** + + Augmentez la mémoire allouée à Docker (depuis les paramètres de Docker Desktop). + +3. **Vérifiez les conflits de ports** :: + + $ docker ps + + Vérifiez qu'aucun autre conteneur n'utilise les ports 8080 ou 9200. + +4. **Vérifiez le fichier Docker Compose** + + Vérifiez qu'il n'y a pas d'erreur de syntaxe dans le fichier YAML :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml config + +Le conteneur démarre mais impossible d'accéder à Fess +------------------------------------------------------ + +**Solution :** + +1. **Vérifiez l'état du conteneur** :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps + +2. **Vérifiez les journaux** :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs fess + +3. **Vérifiez la configuration réseau** :: + + $ docker network ls + $ docker network inspect + +Problèmes spécifiques à Windows +================================ + +Problème de chemin +------------------ + +**Symptôme :** + +Des erreurs se produisent si le chemin contient des espaces ou des caractères japonais. + +**Solution :** + +Veuillez installer dans un répertoire dont le chemin ne contient pas d'espaces ou de caractères japonais. + +Exemple :: + + C:\opensearch (recommandé) + C:\Program Files\opensearch (non recommandé) + +Impossible d'enregistrer en tant que service +--------------------------------------------- + +**Solution :** + +Utilisez un outil tiers (tel que NSSM) pour l'enregistrer en tant que service Windows. + +Pour les procédures détaillées, consultez :doc:`install-windows`. + +Autres problèmes +================ + +Modification du niveau de journal +---------------------------------- + +Pour vérifier des journaux détaillés, modifiez le niveau de journal en DEBUG. + +Modifiez ``log4j2.xml`` :: + + + +Réinitialisation de la base de données +--------------------------------------- + +Pour réinitialiser la configuration, supprimez l'index d'OpenSearch :: + + $ curl -X DELETE 'http://localhost:9200/fess_config.*' + +.. warning:: + + L'exécution de cette commande supprimera toutes les données de configuration. + +Mot de passe administrateur oublié +---------------------------------- + +Si vous avez oublié le mot de passe de l'administrateur, vous pouvez le réinitialiser en mettant à jour directement le document de l'utilisateur dans l'index ``fess_user.user`` d'OpenSearch. Le mot de passe est stocké dans le champ ``password`` sous la forme d'un hash ``{bcrypt}$2a$...``. La modification prend effet sans redémarrer |Fess|. + +1. Créez le hash du nouveau mot de passe. |Fess| n'accepte que les hashes bcrypt commençant par ``$2a$`` ; remplacez donc le ``$2y$`` produit par ``htpasswd`` (fourni par le paquet ``apache2-utils`` ou ``httpd-tools``) par ``$2a$``. Remplacez ``NewPassword`` par le nouveau mot de passe :: + + $ HASH=$(htpasswd -bnBC 10 "" 'NewPassword' | tr -d ':\n' | sed 's/^\$2y/$2a/') + +2. Mettez à jour le mot de passe dans le document de l'utilisateur administrateur. L'ID du document de l'utilisateur administrateur à l'état initial est ``YWRtaW4=`` :: + + $ curl -X POST 'http://localhost:9200/fess_user.user/_update/YWRtaW4=?refresh=true' \ + -H 'Content-Type: application/json' \ + -d "{\"doc\":{\"password\":\"{bcrypt}${HASH}\"}}" + + Pour réinitialiser le mot de passe d'un autre utilisateur, recherchez l'``_id`` avec ``curl 'http://localhost:9200/fess_user.user/_search?q=name:UTILISATEUR'`` et utilisez cet ID. Si l'authentification est activée sur OpenSearch, ajoutez les identifiants à curl. + +3. Vérifiez que vous pouvez vous connecter à l'écran d'administration avec le nouveau mot de passe. Si le mot de passe reste dans l'historique des commandes, redéfinissez-le après la connexion dans [Utilisateur > Utilisateur]. + +Informations de support +======================== + +Si le problème n'est pas résolu, veuillez utiliser les ressources de support suivantes : + +Support communautaire +--------------------- + +- **Issues** : https://github.com/codelibs/fess/issues + + Lors du signalement d'un problème, veuillez inclure les informations suivantes : + + - Version de Fess + - Version d'OpenSearch + - Système d'exploitation et version + - Messages d'erreur (extraits des journaux) + - Procédure de reproduction + +- **Forum** : https://discuss.codelibs.org/ + +Support commercial +------------------ + +Si vous avez besoin d'un support commercial, veuillez contacter N2SM, Inc. : + +- **Web** : https://www.n2sm.net/ + +Collecte d'informations de débogage +==================================== + +Lors du signalement d'un problème, il est utile de collecter les informations suivantes : + +1. **Informations de version** (``bin/fess -v`` est disponible à partir de la 15.10) :: + + $ /path/to/fess/bin/fess -v + $ /path/to/opensearch/bin/opensearch --version + $ java -version + +2. **Informations système** :: + + $ uname -a + $ cat /etc/os-release + $ free -h + $ df -h + +3. **Fichiers journaux** :: + + $ tar czf fess-logs.tar.gz /path/to/fess/logs/ + +4. **Fichiers de configuration** (après suppression des informations confidentielles) :: + + $ tar czf fess-config.tar.gz /path/to/fess/app/WEB-INF/conf/ + +5. **État d'OpenSearch** :: + + $ curl http://localhost:9200/_cluster/health?pretty + $ curl http://localhost:9200/_cat/indices?v diff --git a/fr/15.10/install/uninstall.rst b/fr/15.10/install/uninstall.rst new file mode 100644 index 000000000..e72c60075 --- /dev/null +++ b/fr/15.10/install/uninstall.rst @@ -0,0 +1,482 @@ +============================ +Procédure de désinstallation +============================ + +Cette page décrit la procédure de désinstallation complète de |Fess|. + +.. warning:: + + **Notes importantes avant la désinstallation** + + - La désinstallation supprimera toutes les données + - Si vous avez des données importantes, veuillez obligatoirement effectuer une sauvegarde + - Pour les procédures de sauvegarde, consultez :doc:`upgrade` + +Préparation avant la désinstallation +==================================== + +Récupération de la sauvegarde +----------------------------- + +Veuillez sauvegarder les données nécessaires : + +1. **Données de configuration** + + Téléchargez depuis « Système » → « Sauvegarde » dans l'écran d'administration. + Cette opération permet d'exporter en bloc les différents paramètres (y compris la configuration d'exploration), les journaux de recherche, etc. + +2. **Fichiers de configuration personnalisés** + + Version ZIP :: + + $ cp -r /path/to/fess/app/WEB-INF/conf /backup/ + $ cp -r /path/to/fess/app/WEB-INF/classes /backup/ + + Version RPM/DEB :: + + $ sudo cp -r /etc/fess /backup/ + +.. note:: + + La majeure partie des index et de la configuration de |Fess| est stockée dans OpenSearch. + Pour sauvegarder les données d'index, utilisez la fonction de snapshot d'OpenSearch. + Pour la procédure détaillée, consultez :doc:`upgrade`. + +Arrêt des services +------------------ + +Avant la désinstallation, arrêtez tous les services. + +Version ZIP :: + + $ ps aux | grep -E 'fess|opensearch' + $ kill + $ kill + +Version RPM/DEB :: + + $ sudo systemctl stop fess.service + $ sudo systemctl stop opensearch.service + +Version Docker :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +Désinstallation de la version ZIP +======================================== + +Étape 1 : Suppression de Fess +----------------------------- + +Supprimez le répertoire d'installation :: + + $ rm -rf /path/to/fess-15.10.0 + +Étape 2 : Suppression d'OpenSearch +---------------------------------- + +Supprimez le répertoire d'installation d'OpenSearch :: + + $ rm -rf /path/to/opensearch-3.9.0 + +Étape 3 : Suppression du répertoire de données (optionnel) +---------------------------------------------------------- + +Les données d'index de |Fess| sont stockées dans OpenSearch. +Par défaut, elles sont stockées dans le répertoire d'installation d'OpenSearch (``opensearch-3.9.0/data``, etc.), +mais si vous avez spécifié un autre emplacement avec ``path.data``, supprimez également ce répertoire :: + + $ rm -rf /path/to/data + +Étape 4 : Suppression du répertoire de journaux (optionnel) +----------------------------------------------------------- + +Supprimez les fichiers journaux :: + + $ rm -rf /path/to/fess-15.10.0/logs + $ rm -rf /path/to/opensearch-3.9.0/logs + +Désinstallation de la version RPM +================================= + +Étape 1 : Désinstallation de Fess +--------------------------------- + +Désinstallez le package RPM :: + + $ sudo rpm -e fess + +.. note:: + + Lors de la désinstallation du package |Fess|, le script de suppression du package exécute + automatiquement l'arrêt et la désactivation du service ``fess``, ainsi que la suppression de + l'utilisateur et du groupe ``fess``. + Les étapes suivantes servent à vérifier que ces éléments ont bien été supprimés, ou à + supprimer manuellement les données et les fichiers de configuration. + +Étape 2 : Désinstallation d'OpenSearch +-------------------------------------- + +:: + + $ sudo rpm -e opensearch + +Étape 3 : Vérification de la désactivation des services +------------------------------------------------------- + +Normalement, le service est désactivé lors de la suppression du package, mais pour vérifier ou désactiver par précaution, exécutez ce qui suit. + +Avec systemd :: + + $ sudo systemctl disable fess.service + $ sudo systemctl disable opensearch.service + $ sudo systemctl daemon-reload + +Dans un ancien environnement SysV init (chkconfig) :: + + $ sudo /sbin/chkconfig --del fess + $ sudo /sbin/chkconfig --del opensearch + +Étape 4 : Suppression du répertoire de données +---------------------------------------------- + +.. warning:: + + L'exécution de cette opération supprimera complètement toutes les données d'index. + +Le répertoire de données n'étant pas supprimé lors de la désinstallation du package, supprimez-le manuellement :: + + $ sudo rm -rf /var/lib/fess + $ sudo rm -rf /var/lib/opensearch + +Étape 5 : Suppression des fichiers de configuration +--------------------------------------------------- + +Supprimez les fichiers de configuration et les fichiers de configuration d'environnement :: + + $ sudo rm -rf /etc/fess + $ sudo rm -rf /etc/sysconfig/fess + $ sudo rm -rf /etc/opensearch + +.. note:: + + Avec RPM, les fichiers de configuration dans ``/etc/fess`` peuvent subsister sous le nom ``.rpmsave``. + Pour les supprimer complètement, supprimez-les manuellement comme indiqué ci-dessus. + +Étape 6 : Suppression des fichiers journaux +------------------------------------------- + +:: + + $ sudo rm -rf /var/log/fess + $ sudo rm -rf /var/log/opensearch + +Étape 7 : Suppression du répertoire temporaire (optionnel) +---------------------------------------------------------- + +:: + + $ sudo rm -rf /var/tmp/fess + +Étape 8 : Suppression des utilisateurs et groupes (optionnel) +------------------------------------------------------------- + +Normalement, l'utilisateur et le groupe ``fess`` sont supprimés lors de la suppression du package. +S'ils subsistent, ou pour supprimer l'utilisateur et le groupe d'OpenSearch, exécutez ce qui suit :: + + $ sudo userdel fess + $ sudo groupdel fess + $ sudo userdel opensearch + $ sudo groupdel opensearch + +Désinstallation de la version DEB +================================= + +Étape 1 : Désinstallation de Fess +--------------------------------- + +Désinstallez le package DEB :: + + $ sudo dpkg -r fess + +Pour supprimer complètement, y compris les fichiers de configuration et les fichiers de configuration d'environnement, utilisez purge :: + + $ sudo dpkg -P fess + +.. note:: + + Avec ``dpkg -r`` (remove), les fichiers de configuration (conffile) tels que ``/etc/default/fess`` subsistent. + Avec ``dpkg -P`` (purge), ces fichiers de configuration ainsi que l'utilisateur et le groupe ``fess`` sont également supprimés. + +Étape 2 : Désinstallation d'OpenSearch +-------------------------------------- + +:: + + $ sudo dpkg -r opensearch + +Ou, pour supprimer y compris les fichiers de configuration :: + + $ sudo dpkg -P opensearch + +Étape 3 : Vérification de la désactivation des services +------------------------------------------------------- + +Normalement, le service est désactivé lors de la suppression du package. Pour vérifier ou désactiver par précaution, exécutez ce qui suit :: + + $ sudo systemctl disable fess.service + $ sudo systemctl disable opensearch.service + $ sudo systemctl daemon-reload + +Étape 4 : Suppression du répertoire de données +---------------------------------------------- + +.. warning:: + + L'exécution de cette opération supprimera complètement toutes les données d'index. + +:: + + $ sudo rm -rf /var/lib/fess + $ sudo rm -rf /var/lib/opensearch + +Étape 5 : Suppression des fichiers de configuration (si dpkg -P n'a pas été utilisé) +------------------------------------------------------------------------------------ + +:: + + $ sudo rm -rf /etc/fess + $ sudo rm -rf /etc/default/fess + $ sudo rm -rf /etc/opensearch + +Étape 6 : Suppression des fichiers journaux +------------------------------------------- + +:: + + $ sudo rm -rf /var/log/fess + $ sudo rm -rf /var/log/opensearch + +Étape 7 : Suppression des utilisateurs et groupes (optionnel) +------------------------------------------------------------- + +Si vous n'avez pas utilisé ``dpkg -P``, l'utilisateur et le groupe ``fess`` subsistent. +Pour les supprimer, exécutez ce qui suit :: + + $ sudo userdel fess + $ sudo groupdel fess + $ sudo userdel opensearch + $ sudo groupdel opensearch + +Désinstallation de la version Docker +==================================== + +Étape 1 : Suppression des conteneurs et réseaux +----------------------------------------------- + +Supprimez les conteneurs ainsi que le réseau créé par Docker Compose (``search_net``) :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +Étape 2 : Suppression des volumes +--------------------------------- + +.. warning:: + + L'exécution de cette opération supprimera complètement toutes les données. + +Les données de |Fess| (index, dictionnaires, etc.) sont stockées dans les volumes d'OpenSearch. +Vérifiez d'abord la liste des volumes :: + + $ docker volume ls + +Supprimez les volumes liés à OpenSearch :: + + $ docker volume rm _search01_data + $ docker volume rm _search01_dictionary + +.. note:: + + Les noms de volumes sont préfixés par le nom du projet Docker Compose (généralement le nom du + répertoire dans lequel se trouve le fichier Compose). Vérifiez les noms réels avec ``docker volume ls``. + +Pour supprimer en bloc les conteneurs et les volumes, ajoutez l'option ``-v`` à ``down`` :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down -v + +Étape 3 : Suppression des images (optionnel) +-------------------------------------------- + +Pour supprimer les images Docker et libérer de l'espace disque :: + + $ docker images | grep fess + $ docker rmi ghcr.io/codelibs/fess:15.10.0 + $ docker rmi ghcr.io/codelibs/fess-opensearch:3.9.0 + +Étape 4 : Suppression des fichiers Compose +------------------------------------------ + +:: + + $ rm compose.yaml compose-opensearch3.yaml + +Vérification de la désinstallation +================================== + +Vérifiez que tous les composants ont été supprimés. + +Vérification des processus +-------------------------- + +:: + + $ ps aux | grep fess + $ ps aux | grep opensearch + +Si rien ne s'affiche, les processus sont arrêtés. + +Vérification des ports +---------------------- + +:: + + $ sudo ss -tuln | grep 8080 + $ sudo ss -tuln | grep 9200 + +Vérifiez que les ports ne sont pas utilisés. + +Vérification des fichiers +------------------------- + +Version ZIP :: + + $ ls /path/to/fess-15.10.0 # Vérifiez que le répertoire n'existe pas + +Version RPM/DEB :: + + $ ls /var/lib/fess # Vérifiez que le répertoire n'existe pas + $ ls /etc/fess # Vérifiez que le répertoire n'existe pas + +Version Docker :: + + $ docker ps -a | grep -E 'fess01|search01' # Vérifiez que le conteneur n'existe pas + $ docker volume ls | grep search01 # Vérifiez que le volume n'existe pas + +Vérification des packages +------------------------- + +Version RPM :: + + $ rpm -qa | grep fess + $ rpm -qa | grep opensearch + +Version DEB :: + + $ dpkg -l | grep fess + $ dpkg -l | grep opensearch + +Si rien ne s'affiche, les packages ont été supprimés. + +Désinstallation partielle +========================= + +Supprimer uniquement Fess en conservant OpenSearch +-------------------------------------------------- + +Si vous utilisez également OpenSearch pour d'autres applications, vous pouvez supprimer uniquement Fess. + +1. Arrêter Fess +2. Supprimer le package ou le répertoire de Fess +3. Supprimer le répertoire de données de Fess (``/var/lib/fess``, etc.) +4. Supprimer les index de |Fess| créés dans OpenSearch + + Les noms des index de |Fess| commencent par ``fess`` (``fess.*``, ``fess_config.*``, ``fess_user.*``, ``fess_log.*``, ``fess_crawler.*``, ``fess_suggest*``, etc.). La commande suivante permet de tous les supprimer en une fois. + + :: + + $ curl -X DELETE 'http://localhost:9200/fess*' + + Avant la suppression, vérifiez avec ``curl 'http://localhost:9200/_cat/indices?v'`` qu'aucun index d'une autre application ne porte un nom commençant par ``fess``. L'index ``configsync``, qui synchronise les dictionnaires, peut lui aussi être supprimé s'il n'est utilisé par aucune autre application. + +5. Ne pas supprimer OpenSearch + +Supprimer uniquement OpenSearch en conservant Fess +-------------------------------------------------- + +.. warning:: + + Si vous supprimez OpenSearch, Fess ne fonctionnera plus. + Veuillez modifier la configuration pour vous connecter à un autre cluster OpenSearch. + +1. Arrêter OpenSearch +2. Supprimer le package ou le répertoire d'OpenSearch +3. Supprimer le répertoire de données d'OpenSearch (``/var/lib/opensearch``, etc.) +4. Mettre à jour la configuration de Fess pour spécifier un autre cluster OpenSearch + +Dépannage +========= + +Impossible de supprimer le package +---------------------------------- + +**Symptôme :** + +Erreur avec ``rpm -e`` ou ``dpkg -r``. + +**Solution :** + +1. Vérifiez que le service est arrêté :: + + $ sudo systemctl stop fess.service + +2. Vérifiez les dépendances :: + + $ rpm -qa | grep fess + $ dpkg -l | grep fess + +3. Suppression forcée (dernier recours) :: + + $ sudo rpm -e --nodeps fess + $ sudo dpkg -r --force-all fess + +Impossible de supprimer le répertoire +------------------------------------- + +**Symptôme :** + +Impossible de supprimer le répertoire avec ``rm -rf``. + +**Solution :** + +1. Vérifiez les permissions :: + + $ ls -ld /path/to/directory + +2. Suppression avec sudo :: + + $ sudo rm -rf /path/to/directory + +3. Vérifiez qu'aucun processus n'utilise le fichier :: + + $ sudo lsof | grep /path/to/directory + +Préparation pour la réinstallation +================================== + +Si vous réinstallez après la désinstallation, vérifiez les points suivants : + +1. Tous les processus sont arrêtés +2. Tous les fichiers et répertoires ont été supprimés +3. Les ports 8080 et 9200 ne sont pas utilisés +4. Il ne reste aucun fichier de configuration antérieur + +Pour les procédures de réinstallation, consultez :doc:`install`. + +Étapes suivantes +================ + +Une fois la désinstallation terminée : + +- Pour installer une nouvelle version, consultez :doc:`install` +- Pour migrer des données, consultez :doc:`upgrade` +- Pour envisager une solution de recherche alternative, consultez le site officiel de Fess diff --git a/fr/15.10/install/upgrade.rst b/fr/15.10/install/upgrade.rst new file mode 100644 index 000000000..4d1856fb8 --- /dev/null +++ b/fr/15.10/install/upgrade.rst @@ -0,0 +1,1724 @@ +========================== +Procédure de mise à niveau +========================== + +Cette page décrit la procédure de mise à niveau de |Fess| d'une version antérieure vers la dernière version. + +.. warning:: + + **Notes importantes avant la mise à niveau** + + - Veuillez obligatoirement effectuer une sauvegarde avant la mise à niveau + - Il est fortement recommandé de valider la mise à niveau dans un environnement de test au préalable + - Le service s'arrêtera pendant la mise à niveau, veuillez donc définir une fenêtre de maintenance appropriée + - Selon les versions, le format des fichiers de configuration peut avoir changé + +Versions compatibles +==================== + +Cette procédure de mise à niveau est compatible avec les mises à niveau entre les versions suivantes : + +- Fess 14.x → Fess 15.10 +- Fess 15.x → Fess 15.10 + +.. important:: + + |Fess| 14.x est compatible avec la série OpenSearch 2.x, tandis que |Fess| 15.10 est compatible + avec OpenSearch 3.9.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. + Veuillez consulter les notes de version pour plus de détails. + +Préparation avant la mise à niveau +==================================== + +Vérification de la compatibilité des versions +---------------------------------------------- + +Vérifiez la compatibilité entre la version de destination et la version actuelle. + +- `Notes de version `__ +- :doc:`prerequisites` - Configuration requise pour |Fess| 15.10 (versions de Java et d'OpenSearch) + +Planification du temps d'arrêt +------------------------------- + +La mise à niveau nécessite l'arrêt du système. Planifiez le temps d'arrêt en tenant compte des éléments suivants : + +- Temps de sauvegarde : 10 minutes à plusieurs heures (selon la quantité de données) +- Temps de mise à niveau : 10 à 30 minutes +- Temps de vérification du fonctionnement : 30 minutes à 1 heure +- Temps de réserve : 30 minutes + +**Fenêtre de maintenance recommandée** : Total de 2 à 4 heures + +Étape 1 : Sauvegarde des données +================================== + +Avant la mise à niveau, sauvegardez toutes les données. + +Sauvegarde des données de configuration +---------------------------------------- + +1. **Sauvegarde depuis l'écran d'administration** + + 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 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 jusqu'à la 15.8 ; la 15.10 ajoute l'index ``tag_type`` qui contient + les tags des utilisateurs, soit 26) + - ``fess_user.bulk`` - Utilisateurs, rôles, groupes + - ``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. Toutefois, si la source est en 15.10 ou ultérieure et que vous utilisez des tags utilisateur, téléchargez aussi ``fess_config.bulk`` : l'index ``tag_type``, qui contient les tags utilisateur, n'est pas inclus dans ``fess_basic_config.bulk`` (voir :doc:`../admin/tagtype-guide`). + + .. 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`` ; la 15.10 propose aussi ``chat_log.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. 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** + + Version ZIP :: + + $ 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 :: + + $ 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 ZIP, les réglages équivalents se trouvent dans ``bin/fess.in.sh``. + +3. **Fichiers de configuration personnalisés** + + Si vous avez des fichiers de configuration personnalisés, sauvegardez-les également :: + + $ cp /path/to/fess/app/WEB-INF/classes/log4j2.xml /backup/ + $ cp /path/to/fess/lib/classes/tomcat_config.properties /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 +------------------------------- + +Sauvegardez les données d'index d'OpenSearch. + +Méthode 1 : Utilisation de la fonction de snapshot (recommandé) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sauvegardez l'index en utilisant la fonction de snapshot d'OpenSearch. + +.. note:: + + Pour enregistrer un dépôt de système de fichiers (``fs``), vous devez au préalable spécifier le répertoire de destination de sauvegarde dans + ``path.repo`` du fichier ``opensearch.yml`` d'OpenSearch, puis redémarrer OpenSearch. + +1. Configuration du dépôt :: + + $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup" -H 'Content-Type: application/json' -d' + { + "type": "fs", + "settings": { + "location": "/backup/opensearch/snapshots" + } + }' + +2. Création du snapshot :: + + $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup/snapshot_1?wait_for_completion=true" + +3. Vérification du snapshot :: + + $ curl -X GET "http://localhost:9200/_snapshot/fess_backup/snapshot_1" + +Méthode 2 : Sauvegarde du répertoire entier +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Après avoir arrêté OpenSearch, sauvegardez le répertoire de données. + +:: + + $ sudo systemctl stop opensearch + $ sudo tar czf /backup/opensearch-data-$(date +%Y%m%d).tar.gz /var/lib/opensearch/data + $ sudo systemctl start opensearch + +Sauvegarde de la version Docker +-------------------------------- + +Les données d'OpenSearch sont stockées dans des volumes Docker. Dans ``compose-opensearch3.yaml``, +deux volumes sont définis : ``search01_data`` pour les données d'index, et ``search01_dictionary`` +pour les fichiers de dictionnaire. + +.. note:: + + Le nom réel du volume est préfixé par le nom de projet Compose (par défaut, le nom du répertoire + où le fichier Compose est placé). Vérifiez le nom exact avec la commande suivante :: + + $ docker volume ls + +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 + $ 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. + +La version 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 $(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 + $ sudo systemctl stop opensearch.service + +Version Docker :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +.. warning:: + + Assurez-vous que |Fess| est arrêté avant de commencer l'étape 3, et ne remplacez ni le paquet ni + les fichiers d'un |Fess| encore en cours d'exécution. Après le remplacement du paquet DEB d'un + |Fess| 15.8 en cours d'exécution par celui de la 15.10, l'écran de recherche a répondu ``404`` + jusqu'au redémarrage de |Fess|. Pour les versions des paquets, vérifiez avec + ``systemctl status fess.service``. + +Étape 3 : Installation de la nouvelle version +================================================ + +Les procédures diffèrent selon la méthode d'installation. + +Version ZIP +------------------ + +1. Téléchargez et décompressez la nouvelle version :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.zip + $ unzip fess-15.10.0.zip + + .. note:: + + La version archive de |Fess| n'est distribuée qu'au format ZIP (``fess-15.10.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.10.0/app/WEB-INF/conf/ + $ cp /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.10.0/app/WEB-INF/classes/ + $ cp /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.10.0/bin/ + + .. warning:: + + Copiés tels quels, ``fess_config.properties`` et ``fess.in.sh`` conservent leurs anciennes + valeurs, y compris celles dont la valeur par défaut a changé en 15.10 : par exemple, les + tâches créées ensuite utilisent Groovy par défaut. Avant d'exécuter les deux dernières + commandes, comparez chaque fichier avec celui de ``fess-15.10.0`` et ne reportez que les + valeurs que vous avez modifiées vous-même. Voir :ref:`upgrade-159-carried-over-config` pour + les éléments à vérifier. + +3. Si vous avez des personnalisations, copiez également ce qui suit :: + + # Paramètres de Tomcat (le paramètre SAML tomcat.sameSiteCookies=none se trouve ici) + $ cp /path/to/old-fess/lib/classes/tomcat_config.properties /path/to/fess-15.10.0/lib/classes/ + # Plugins installés + $ cp -r /path/to/old-fess/app/WEB-INF/plugin/. /path/to/fess-15.10.0/app/WEB-INF/plugin/ + # Thèmes statiques que vous avez téléversés vous-même (un répertoire par thème ; jamais bootstrap) + $ cp -r /path/to/old-fess/app/themes/ /path/to/fess-15.10.0/app/themes/ + + .. warning:: + + Sans le ``tomcat_config.properties`` de l'ancienne installation, ``tomcat.sameSiteCookies`` + revient silencieusement à la valeur par défaut ``lax`` et la connexion SAML cesse de + fonctionner (voir :ref:`upgrade-159-saml`). Le fichier fourni est identique en 15.8.0 et en + 15.10 ; il peut donc être copié tel quel. + + .. warning:: + + Ne copiez pas ``log4j2.xml`` par-dessus le fichier de la 15.10. Le fichier de la 15.10 maintient + le logger ``RequestLoggingFilter`` au niveau ``warn``, et un fichier copié depuis la 15.8 + supprime ce réglage : avec le niveau de journalisation DEBUG, les en-têtes de requête (y + compris ``Authorization``) et les paramètres de requête (y compris le mot de passe saisi dans + le formulaire de connexion) sont alors écrits dans le journal. Comparez les deux fichiers avec + ``diff`` et ne réappliquez au fichier de la 15.10 que les modifications que vous avez faites + vous-même. + + .. warning:: + + Ne copiez pas l'intégralité du répertoire ``app/themes/``. Il contient aussi ``bootstrap``, + le thème fourni avec |Fess|, et le copier par-dessus celui de la 15.10 remplace l'écran de + recherche de la 15.10 par la version 15.8 du thème. Copiez uniquement les répertoires des + thèmes que vous avez créés vous-même. Pour un thème publié par le projet |Fess|, installez + plutôt la version construite pour la 15.10, avec ``bin/fess-setup install theme `` + (voir :doc:`fess-setup`). + + .. warning:: + + Ne copiez pas les JSP (``app/WEB-INF/view/``) modifiés depuis l'écran d'administration + « Design ». L'écran de recherche de la 15.10 est un thème statique et n'utilise plus ces JSP ; + voir :ref:`upgrade-159-static-theme` pour savoir où ces modifications doivent désormais être + faites. + + .. note:: + + Les plugins copiés depuis ``app/WEB-INF/plugin/`` ont été construits pour l'ancienne version. + Après les avoir copiés, exécutez ``bin/fess-setup upgrade plugins`` dans ``fess-15.10.0`` pour + remplacer chacun d'eux par la version construite pour la 15.10 ; voir + :ref:`upgrade-plugin-versions`. + +4. Vérifiez les différences de configuration et ajustez si nécessaire + +Version RPM/DEB +--------------- + +Installez le package de la nouvelle version :: + + # RPM + $ sudo rpm -Uvh fess-15.10.0.rpm + + # DEB + $ sudo dpkg -i fess-15.10.0.deb + +.. note:: + + 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. Un fichier + ``/etc/fess/fess_config.properties`` que vous avez modifié conserve ses anciennes valeurs en + 15.10, comme un fichier copié dans la procédure ZIP ; voir :ref:`upgrade-159-carried-over-config`. + +.. warning:: + + Dans la version DEB, les fichiers situés sous ``/etc/fess`` (tels que ``fess_config.properties`` + et ``tomcat_config.properties``) sont enregistrés en tant que conffiles, comme + ``/etc/default/fess``, ``/etc/init.d/fess`` et ``/usr/lib/systemd/system/fess.service``. Lors de + la première mise à niveau depuis la 15.8, ``dpkg`` les traite comme suit : + + - Un fichier que vous n'avez jamais modifié est remplacé par celui de la 15.10 sans question. + - Pour un fichier que vous avez modifié, ``dpkg`` pose la question. Si vous conservez votre + fichier (réponse par défaut, ou ``--force-confold``), le fichier de la 15.10 est placé à côté + sous le nom ``.dpkg-dist``. Si vous installez le nouveau fichier (``Y`` ou + ``--force-confnew``), votre fichier est enregistré sous le nom ``.dpkg-old``. + - ``dpkg -i`` et ``apt-get install -y`` s'arrêtent à la première question lorsque personne ne + peut y répondre. Pour une mise à niveau sans surveillance, passez ``--force-confold`` + (``--force-confdef`` évite aussi les questions), par exemple + ``sudo dpkg --force-confold -i fess-15.10.0.deb`` ou + ``sudo apt-get install -y -o Dpkg::Options::=--force-confold ./fess-15.10.0.deb``. + + Sauvegardez dans tous les cas ``/etc/fess`` au préalable (étape 1). Un fichier que vous + conservez a toujours ses valeurs de la 15.8 : comparez-le avec le fichier ``.dpkg-dist`` au lieu + de l'utiliser tel quel (voir :ref:`upgrade-159-carried-over-config`). 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 +-------------- + +1. Obtenez les fichiers Compose de la nouvelle version :: + + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose.yaml + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose-opensearch3.yaml + +2. Récupérez la nouvelle image :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull + +.. _upgrade-opensearch: + +Étape 4 : Mise à niveau d'OpenSearch +==================================== + +|Fess| 15.10 est compatible avec OpenSearch 3.9.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:: + + Cette procédure s'applique aux cas où OpenSearch est géré manuellement avec les versions ZIP et RPM/DEB. + 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.10 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. + + Un snapshot pris avec OpenSearch 3.9.0 ne peut pas être restauré dans OpenSearch 3.8.0 ou + antérieur. Conservez le snapshot pris avant la mise à niveau au cas où vous devriez revenir en + arrière. + +1. Installez la nouvelle version d'OpenSearch + +2. Réinstallez les plugins :: + + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + + .. note:: + + La version de ces plugins doit correspondre à la version d'OpenSearch utilisée. + |Fess| 15.10 est compatible avec OpenSearch 3.9.0. Si les versions ne correspondent pas, + l'installation du plugin échouera. + + Les quatre plugins de |Fess| sont publiés sur maven.codelibs.org ; ils s'installent donc par + leur URL. La forme ``groupId:artifactId:version`` de ``opensearch-plugin install`` ne cherche + que dans Maven Central. + +3. Déplacez le répertoire des dictionnaires sous le répertoire de configuration d'OpenSearch + + À partir d'OpenSearch 3.8.0, la création d'un index est refusée si les fichiers de dictionnaire se trouvent en dehors du répertoire de configuration d'OpenSearch. + Si, conformément à l'ancienne procédure, ``configsync.config_path`` pointe vers un emplacement situé en dehors du répertoire de configuration, comme ``/var/lib/opensearch/data/config/`` (``/path/to/opensearch/data/config/`` pour la version ZIP), + |Fess| ne peut pas créer ses index et ne démarre pas. + Pour les versions RPM/DEB, copiez les fichiers de dictionnaire vers ``/etc/opensearch/dictionary/`` comme suit :: + + $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary + $ sudo cp -a /var/lib/opensearch/data/config/. /etc/opensearch/dictionary/ + $ sudo chown -R opensearch:opensearch /etc/opensearch/dictionary + + Modifiez ensuite ``configsync.config_path`` dans ``/etc/opensearch/opensearch.yml`` et ``FESS_DICTIONARY_PATH`` de |Fess| (``/etc/sysconfig/fess`` pour la version RPM, ``/etc/default/fess`` pour la version DEB) pour qu'ils pointent tous deux vers ``/etc/opensearch/dictionary/``. + Pour la version ZIP, utilisez le répertoire ``config/dictionary/`` d'OpenSearch. Pour plus de détails, consultez :doc:`install-linux`. + +4. Démarrez OpenSearch :: + + $ sudo systemctl start opensearch.service + +Étape 5 : Démarrage de la nouvelle version +============================================ + +Version ZIP :: + + $ cd /path/to/fess-15.10.0 + $ ./bin/fess -d -p /path/to/fess-15.10.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.10.0/fess.pid)``. + +Version RPM/DEB :: + + $ sudo systemctl start opensearch.service + $ sudo systemctl start fess.service + +Version Docker :: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +Étape 6 : Vérification du fonctionnement +========================================== + +1. **Vérification des journaux** + + Vérifiez qu'il n'y a pas d'erreurs. + + Version 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. + +3. **Connexion à l'écran d'administration** + + Accédez à http://localhost:8080/admin et connectez-vous avec le compte administrateur. + +4. **Vérification de la version** + + Dans l'écran d'administration, cliquez sur « Informations système » → « Informations de configuration » et vérifiez que + ``fess.version`` affiché dans « Propriétés système » correspond bien à la nouvelle version. + +5. **Vérification du fonctionnement de la recherche** + + Effectuez une recherche sur l'écran de recherche et vérifiez que les résultats sont retournés normalement. + +Étape 7 : Recréation de l'index (recommandé) +============================================== + +En cas de mise à niveau majeure, il est recommandé de recréer l'index. + +.. note:: + + Les étapes ci-dessous relancent le crawl ; elles ne mettent pas à jour le mapping de l'index + (définitions des champs). Si vous avez besoin d'une réindexation qui met à jour le mapping — + par exemple pour activer nouvellement la recherche par vecteurs de chunks (recherche + sémantique) —, exécutez séparément la « Réindexation » sous « Informations système » → + « Maintenance » dans l'interface d'administration. Voir :ref:`semantic-search-migration` + (:doc:`../config/search-semantic`) pour plus de détails. + + Si vous conservez un index de documents créé avec la 15.8 ou antérieure, consultez aussi + :ref:`upgrade-reindex-new-fields`. + +.. warning:: + + OpenSearch 3.9.0 refuse des entrées de dictionnaire que la 15.8 acceptait, comme la même entrée + ``mapping`` enregistrée deux fois ou un token ``kuromoji`` qui contient une espace. Avec une telle + entrée, la « Réindexation » ne crée pas le nouvel index de documents : ``fess.log`` indique + seulement ``Failed to create index`` et l'ancien index continue de servir les recherches. + Téléchargez le dictionnaire sous « Système » → « Dictionnaire », supprimez les lignes en double + ou invalides, téléversez-le de nouveau, puis relancez la « Réindexation ». Voir + :ref:`upgrade-159-api-requests` pour les entrées que la 15.10 n'enregistre plus. + +1. Vérifiez la planification d'exploration existante +2. Exécutez « Default Crawler » depuis « Système » → « Planificateur » +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. + +Mise à niveau de 15.8 vers 15.10 +=============================== + +Si vous effectuez une mise à niveau depuis la 15.8, les changements suivants ne sont pas +rétrocompatibles. Si vous effectuez une mise à niveau depuis la 15.7 ou antérieure, ils s'appliquent +aussi à vous : lisez toutes les sections de « Suppression de l'OpenSearch intégré » à « Appliquer +les nouveaux champs et la normalisation des kana à un index de documents existant » (l'OpenSearch +intégré, le moteur de script, les plugins S3 et SSO, la tâche Index Exporter, etc.), puis +« Migrations spécifiques à la 15.10 » à la fin de cette page. + +Suppression de l'OpenSearch intégré +----------------------------------- + +Jusqu'à la 15.8, démarrer ``bin/fess`` sans définir ``SEARCH_ENGINE_HTTP_URL`` amenait |Fess| à +exécuter un nœud OpenSearch dans sa propre JVM. Cette configuration disparaît en 15.10 : le moteur +de recherche est toujours un serveur distinct. + +``bin/fess.in.sh`` définit désormais ``SEARCH_ENGINE_HTTP_URL=http://localhost:9200`` par défaut. +|Fess| refuse de démarrer si aucun OpenSearch n'est joignable. ``bin/fess-setup install +opensearch`` en installe un (Linux et Windows uniquement ; OpenSearch ne publie pas de version +macOS, utilisez donc Homebrew ou Docker). + +|Fess| a également besoin que ``FESS_DICTIONARY_PATH`` corresponde à ``configsync.config_path`` +dans le fichier ``opensearch.yml`` de cet OpenSearch ; sans cela, |Fess| ne peut pas créer ses +index. Le ``bin/fess.in.sh`` de la 15.10 (``bin\fess.in.bat`` sous Windows) le définit par lui-même +lorsque ``opensearch/`` dans le répertoire de |Fess| contient exactement un OpenSearch installé par +``bin/fess-setup install opensearch``. Pour tout autre OpenSearch, définissez-le comme décrit dans +:doc:`install-linux` ou :doc:`install-windows`. + +Sont également supprimés : + +- le répertoire ``es/`` (``es/modules``, ``es/plugins`` et ``es/data``) +- ``-Dfess.es.dir`` et ``SEARCH_ENGINE_HOME`` +- ``bin/module.xml`` et ``bin/plugin.xml`` +- les valeurs de repli des anciennes clés de configuration ``elasticsearch.*`` + +Un moteur antérieur à OpenSearch 3 interrompt désormais le démarrage, alors que la 15.8 se +contentait de journaliser une erreur et de poursuivre. Ces versions n'implémentent pas le tri +``_shard_doc`` dont dépendent toutes les opérations parcourant l'ensemble des résultats, et via +HTTP une telle requête reste bloquée au lieu d'échouer. + +.. warning:: + + Les données d'index d'une installation intégrée ne peuvent pas être reprises. Mettez en place + un nouveau serveur OpenSearch externe, transférez les paramètres via la page Sauvegarde de + l'administration, puis relancez une exploration. La sauvegarde couvre les paramètres + d'exploration, les utilisateurs et les journaux ; elle ne contient **pas** les documents + explorés. + +.. note:: + + Deux points à connaître lorsque vous restaurez une sauvegarde de la 15.8 sur le nouveau serveur + 15.10 : + + - Les tâches ne sont restaurées que si elles sont plus récentes que celles du serveur. Les tâches + fournies que vous n'avez jamais modifiées sous 15.8 gardent donc leur version JavaScript de la + 15.10. Une tâche que vous avez modifiée ou créée sous 15.8 revient avec le moteur de script avec + lequel elle a été enregistrée, soit ``groovy`` pour une tâche fournie, et sans le plugin + ``fess-script-groovy`` elle échoue avec ``groovy is not found``. Installez le plugin ou faites + passer ces tâches à JavaScript ; les deux sont décrits dans :ref:`upgrade-159-script-engine`. + - Les mots de passe et secrets enregistrés dans les paramètres de l'authentification Web, des + configurations d'exploration et des configurations DataStore sont chiffrés avec + ``app.cipher.key``. Définissez la valeur de l'ancienne installation dans le + ``fess_config.properties`` du nouveau serveur, comme décrit dans + :ref:`upgrade-159-carried-over-config` ; sinon ils ne peuvent pas être déchiffrés. + +Le robot Playwright passe dans un plugin +---------------------------------------- + +Le robot Playwright, ainsi que les exécutables Node.js qu'il utilise, ne font plus partie de la +distribution. Dans ``fess-15.8.0.zip`` (457,1 Mio), le paquet de pilotes Playwright qui contenait +les exécutables Node.js occupait 204,3 Mio. + +Si une configuration d'exploration désigne le client Playwright, par exemple avec +``client.crawlerClients=playwright:http://.*`` dans ses paramètres, installez à la fois le +plugin et Node.js. Le plugin s'installe également depuis la page **Système > Plugin** de l'écran +d'administration. ``bin/fess.in.sh`` détecte Node.js et définit ``PLAYWRIGHT_NODEJS_PATH``. + +:: + + $ bin/fess-setup install plugin fess-crawler-playwright + $ bin/fess-setup install nodejs + +Sans le plugin, une telle configuration est toujours explorée, mais avec le client HTTP ordinaire : +le texte produit uniquement par JavaScript n'est donc pas indexé. La tâche d'exploration se termine +malgré tout avec succès et aucune URL en échec n'est enregistrée. À chaque exploration, +``fess-crawler.log`` consigne un avertissement par configuration d'exploration, qui nomme le plugin +et les deux commandes ci-dessus. + +Le plugin ``fess-thumbnail-playwright``, qui génère avec Playwright les vignettes des pages HTML, +s'exécute lui aussi sur Node.js. Si vous l'utilisez, installez Node.js avec +``bin/fess-setup install nodejs`` ; la même installation sert aux deux plugins. + +Rien à faire si vous n'utilisez ni le robot Playwright ni le plugin ``fess-thumbnail-playwright``. + +Google Cloud Storage passe dans un plugin +----------------------------------------- + +Le SDK Google Cloud Storage ne fait plus partie de la distribution : l'exploration ``gcs://`` +et le type de stockage ``gcs`` proviennent désormais du plugin ``fess-storage-gcs``. +Installez-le depuis la page **Système > Plugin** de l'écran d'administration ou avec la +commande ci-dessous. + +:: + + $ bin/fess-setup install plugin fess-storage-gcs + +``gcs`` a également quitté la valeur fournie de ``crawler.file.protocols``, qui est +maintenant ``file,smb,smb1,ftp`` ; le plugin la rétablit lors de son installation. +Jusque-là, une configuration d'exploration de fichiers dont le chemin commence par ``gcs:`` +est signalée par un avertissement et ne récupère rien. Une installation mise à niveau conserve +son propre ``crawler.file.protocols``, le chemin est donc toujours accepté mais aucun client +d'exploration ne le prend en charge ; dans une nouvelle installation, ``gcs:`` n'est pas un +protocole configuré, l'écran d'administration refuse donc d'enregistrer le chemin et un chemin +enregistré auparavant est lu comme un chemin de fichier local. La page de stockage journalise +elle aussi un avertissement et affiche l'échec comme une erreur nommant le plugin à installer, +là où elle n'affichait auparavant qu'une liste de fichiers vide. + +Rien à faire si vous n'utilisez pas Google Cloud Storage. Amazon S3 et les stockages +compatibles S3 tels que MinIO sont passés dans un plugin de la même manière ; voir la section +suivante. + +Amazon S3 passe dans un plugin +------------------------------ + +Le SDK AWS ne fait plus partie de la distribution : l'exploration ``s3://`` et les types de +stockage ``s3`` et ``s3_compat`` proviennent désormais du plugin ``fess-storage-s3``. +Installez-le depuis la page **Système > Plugin** de l'écran d'administration ou avec la +commande ci-dessous. + +:: + + $ bin/fess-setup install plugin fess-storage-s3 + +``s3`` a également quitté la valeur fournie de ``crawler.file.protocols``, qui est maintenant +``file,smb,smb1,ftp`` ; le plugin la rétablit lors de son installation. ``storage.type`` vaut +toujours ``auto`` par défaut, ce qui se résout en S3 lorsque aucun point de terminaison n'est +défini : la page de stockage de l'écran d'administration ne fonctionne donc qu'après +l'installation du plugin, même si vous n'avez jamais indiqué ``s3`` vous-même. Vos valeurs +``storage.*`` sont conservées, car elles se trouvent dans ``WEB-INF/conf/system.properties``, +et un ``crawler.file.protocols`` existant n'est pas non plus remplacé par la mise à niveau. + +Rien à faire si vous n'utilisez pas Amazon S3 ni un stockage compatible S3 tel que MinIO. + +L'authentification SSO passe dans des plugins +--------------------------------------------- + +Aucun des quatre authentificateurs SSO ne fait plus partie de la distribution : chaque valeur +de ``sso.type`` provient désormais de son propre plugin, qui embarque la bibliothèque +d'identité dont il a besoin : ``saml`` de ``fess-sso-saml``, ``spnego`` de +``fess-sso-spnego``, ``entraid`` (et l'ancien ``aad``) de ``fess-sso-entraid`` et ``oic`` de +``fess-sso-oidc``. Notez la dernière paire : le plugin s'appelle ``fess-sso-oidc`` alors que la +valeur de ``sso.type`` reste ``oic`` ; c'est le seul endroit où les deux diffèrent. Installez +celui que vous utilisez depuis la page **Système > Plugin** de l'écran d'administration ou avec +la commande ci-dessous. + +:: + + $ bin/fess-setup install plugin fess-sso-saml + +Vos paramètres sont conservés, car ``sso.type`` et les clés ``saml.*``, ``spnego.*``, +``entraid.*``, ``aad.*`` et ``oic.*`` se trouvent dans ``WEB-INF/conf/system.properties``. De +plus, « Système » → « Général » de l'écran d'administration propose toujours les quatre types +et affiche toujours leurs paramètres, car un plugin ne peut pas fournir de JSP : rien sur cet +écran ne signale donc un plugin manquant. + +Jusqu'à l'installation du plugin, une requête vers ``/sso/`` est redirigée vers la page de +connexion, qui signale l'échec de la connexion SSO, et personne ne peut se connecter via le +SSO. La 15.10 journalise dans ``fess.log`` un avertissement nommant le composant recherché et le +plugin qui le fournit, là où jusqu'à la 15.8 rien n'était journalisé à aucun niveau. + +Le plugin ``oic`` est plus strict que l'authentificateur de la 15.8. ``oic.token.server.url`` doit +être en HTTPS (``http`` uniquement pour ``localhost``, ``127.x.x.x`` et ``::1``), les claims +``aud`` et ``exp`` de l'ID Token sont vérifiés, et ``iss`` est vérifié lorsque la nouvelle clé +``oic.issuer`` est définie. Pour plus de détails, consultez :doc:`../config/sso-oidc`. + +En 15.8, ``oic.token.server.url`` pouvait être une URL ``http`` vers n'importe quel hôte. En 15.10, ``http`` vers un nom de service Docker Compose (par exemple ``http://keycloak:8080/...``) ou un nom d'hôte interne est refusé, même s'il désigne la même machine. La connexion échoue alors et ``fess.log`` contient un avertissement commençant par ``Failed to process the OpenID Connect callback: oic.token.server.url must be https``. Passez le endpoint de token en URL HTTPS avant la mise à jour. + +Définissez aussi ``oic.issuer`` avec la valeur ``issuer`` du document Discovery de l'OP. Sans cette valeur, ``iss`` n'est pas vérifié et un avertissement est journalisé lors de la première connexion après le démarrage. Définir ``oic.issuer`` n'assouplit pas la règle HTTPS. + +Rien à faire si vous n'utilisez pas le SSO, c'est-à-dire si ``sso.type`` vaut ``none`` ou n'est +pas défini. + +.. _upgrade-159-script-engine: + +Le moteur de script intégré passe de Groovy à JavaScript +-------------------------------------------------------- + +Jusqu'à la 15.8, le moteur de script intégré était Groovy et ``job.default.script`` avait pour +valeur par défaut ``groovy``. En 15.10, le moteur intégré est JavaScript et la valeur par défaut +est ``javascript``. Groovy n'est plus intégré : il est fourni par le plugin +``fess-script-groovy``, qui doit être installé pour qu'un ``scriptType`` valant ``groovy`` puisse +être résolu. + +Une mise à niveau ne modifie pas le moteur enregistré avec un paramètre, et un paramètre enregistré +avant la 15.10 sans moteur compte comme ``groovy``. Sans le plugin, les éléments suivants cessent de +fonctionner : + +- Les tâches planifiées enregistrées en ``groovy``. **Cela concerne aussi les tâches que la 15.8 a + créées elle-même :** Default Crawler, Suggest Indexer, Config Reloader, Log Aggregator, Doc + Purger et les autres tâches fournies sont toutes enregistrées en ``groovy``, et au démarrage la + 15.10 n'ajoute que les tâches fournies qui n'existent pas encore : elle ne les modifie donc pas. + Chacune d'elles échoue à chaque déclenchement planifié, si bien que Default Crawler n'explore + plus rien. La plupart des tâches fournies ont « Journalisation » désactivée : leurs échecs + n'apparaissent pas dans le journal des tâches, seulement sous la forme d'avertissements + ``Failed to execute job`` dans ``fess.log``. +- Les configurations d'exploration Web et de fichiers dont les « Paramètres de configuration » + contiennent des scripts de champ (``field.script.``). Chaque document d'une telle + configuration échoue avec une ``ScriptEngineException`` et est enregistré comme URL en échec, + alors que la tâche d'exploration elle-même se termine avec succès. +- Les configurations DataStore dotées d'un « Script ». Les valeurs qui ne sont pas un simple nom de + paramètre ne peuvent pas être évaluées ; voir :doc:`../config/datastore/ds-overview`. +- Les règles de boost de document. Une telle règle ne booste rien. +- Les mappages de chemin dont le « Remplacement » commence par ``groovy:``. Un tel mappage n'est + pas appliqué et les URL restent inchangées. + +Après le premier démarrage, recherchez dans ``fess.log`` un avertissement commençant par +``Settings use the script engine groovy, which is not registered``. |Fess| vérifie une fois au +démarrage les paramètres ci-dessus et indique, pour chaque type, combien utilisent un moteur +qu'aucun plugin ne fournit. Il mentionne aussi ``job.default.script`` lorsqu'un +``fess_config.properties`` repris de la 15.8 indique encore ``groovy`` ; dans ce cas, les tâches +créées après la mise à niveau utilisent elles aussi Groovy (voir +:ref:`upgrade-159-carried-over-config`). Deux solutions sont possibles : + +- Installez le plugin et redémarrez |Fess|. Les scripts Groovy enregistrés s'exécutent alors sans + modification et l'avertissement n'est plus journalisé. Le plugin peut aussi être installé depuis + « Système » → « Plugins » dans l'écran d'administration. + + :: + + $ bin/fess-setup install plugin fess-script-groovy + +- Passez chaque paramètre à JavaScript. Réécrivez d'abord toute syntaxe que seul Groovy accepte, + puis sélectionnez JavaScript : + + - Tâches planifiées : sous « Système » → « Planificateur », réglez « Méthode d'exécution » sur + ``javascript``. Les scripts des tâches fournies sont du JavaScript valide tels quels, à deux + exceptions près : Thumbnail Purger utilise le littéral ``long`` Groovy ``1000L``, que + JavaScript refuse (écrivez ``1000``), et Index Exporter nécessite la modification décrite dans + :ref:`upgrade-159-index-exporter`. Un littéral de tableau JavaScript est converti + automatiquement en ``String[]`` Java, ce qui rend inutiles les conversions ``as String[]`` de + la forme Groovy : + + :: + + return container.getComponent("crawlJob").logLevel("info").webConfigIds(["1", "2"]).fileConfigIds(["1"]).dataConfigIds([]).execute(executor); + + - Configurations d'exploration Web et de fichiers : ajoutez ``config.script.type=javascript`` + aux « Paramètres de configuration ». + - Configurations DataStore : ajoutez ``script_type=javascript`` aux « Paramètres ». + - Règles de boost de document : réglez « Type de Script » sur ``javascript``. + - Mappages de chemin : commencez le « Remplacement » par ``javascript:`` au lieu de + ``groovy:``. + - ``job.default.script`` : définissez-le sur ``javascript`` dans un ``fess_config.properties`` + repris de la 15.8. + +``crawler.default.script`` a été supprimé +----------------------------------------- + +``crawler.default.script`` n'existe plus dans ``fess_config.properties``. Supprimez-le de votre +configuration ; une valeur laissée sous ce nom n'a aucun effet. + +Le protocole de crawl ``storage`` a été supprimé +------------------------------------------------ + +``storage`` n'est plus accepté dans ``crawler.file.protocols`` ; la valeur fournie est +``file,smb,smb1,ftp``. Utilisez ``s3`` à la place et remplacez par un chemin ``s3:`` toute +configuration de crawl de fichiers dont le chemin commence par ``storage:``. ``s3`` nécessite +le plugin ``fess-storage-s3``. + +.. _upgrade-159-index-exporter: + +La tâche Index Exporter désigne un paquet supprimé +-------------------------------------------------- + +La 15.10 ne contient plus les classes ``org.opensearch`` ; les constructeurs de requêtes utilisés +par les scripts de tâche se trouvent désormais sous ``org.codelibs.fesen.opensearch``. Le script +que la 15.8 a enregistré pour la tâche Index Exporter désigne +``org.opensearch.index.query.QueryBuilders`` et la mise à niveau ne le remplace pas : la tâche +échoue donc même avec ``fess-script-groovy`` installé. Elle est fournie désactivée et sans +planification, cela ne vous concerne donc que si vous l'exécutez. Ouvrez-la sous « Système » → +« Planificateur » et remplacez le paquet dans son script par celui de la 15.10 : + +:: + + return new org.codelibs.fess.job.IndexExportJob().query(org.codelibs.fesen.opensearch.index.query.QueryBuilders.matchAllQuery()).execute() + +Modifiez de la même manière tout script de votre cru qui désigne ``org.opensearch.index.query``. +Voir :doc:`../config/admin-index-export` pour d'autres exemples de requêtes. + +.. _upgrade-159-carried-over-config: + +Fichiers de configuration repris de la 15.8 +------------------------------------------- + +La procédure ZIP de l'étape 3 copie ``fess_config.properties`` et ``bin/fess.in.sh`` depuis +l'ancienne installation, et une mise à niveau RPM conserve un ``/etc/fess/fess_config.properties`` +que vous avez modifié (le fichier de la 15.10 est placé à côté sous le nom +``fess_config.properties.rpmnew``). Une mise à niveau DEB fait de même lorsque vous conservez votre +version à la question (le fichier de la 15.10 est placé à côté sous le nom +``fess_config.properties.dpkg-dist``). Dans tous les cas, la 15.10 fonctionne ensuite avec les +valeurs de la 15.8, y compris celles dont la valeur fournie a changé en 15.10. Vérifiez au moins les +clés suivantes. + +.. list-table:: + :header-rows: 1 + + * - Clé + - 15.8.0 + - 15.10 + - Effet si la valeur de la 15.8 est conservée + * - ``job.default.script`` + - ``groovy`` + - ``javascript`` + - Les tâches créées sous « Système » → « Planificateur » utilisent ``groovy`` par défaut et + échouent sans le plugin ``fess-script-groovy``. + * - ``job.template.script`` + - Forme Groovy avec ``as String[]`` + - Forme JavaScript + - Une tâche créée depuis une configuration d'exploration reçoit un script Groovy. + * - ``crawler.file.protocols`` + - ``file,smb,smb1,ftp,storage,s3,gcs`` + - ``file,smb,smb1,ftp`` + - Un chemin commençant par ``s3:`` ou ``gcs:`` est toujours accepté sans son plugin, puis + ignoré avec un avertissement lors de l'exploration. ``storage`` n'est plus pris en charge. + * - ``search_engine.http.url`` + - ``http://localhost:9201`` + - ``http://localhost:9200`` + - Utilisée lorsque ``SEARCH_ENGINE_HTTP_URL`` n'est pas défini, comme dans un + ``bin/fess.in.sh`` copié de la 15.8 où vous ne l'avez pas défini. |Fess| cherche alors + OpenSearch sur le port 9201, celui de l'OpenSearch intégré supprimé en 15.10. + * - ``jvm.crawler.options``, ``jvm.thumbnail.options`` + - ``-Djcifs.smb.client.*``, ``-Djcifs.smb1.smb.client.*`` + - ``-Djcifs.client.*`` + - Les délais d'attente SMB restent aux valeurs par défaut de jcifs ; voir + :ref:`upgrade-159-jcifs`. + * - ``response.headers`` + - Contient la ligne ``text/html=Content-Security-Policy: reflected-xss block`` + - Ligne supprimée + - La page de connexion, l'interface d'administration et les autres pages que |Fess| génère + lui-même sont envoyées avec un en-tête ``Content-Security-Policy: reflected-xss block`` + qu'aucun navigateur ne reconnaît, et la console du navigateur consigne + ``Unrecognized Content-Security-Policy directive 'reflected-xss'``. L'en-tête ne restreint + rien. Supprimez la ligne, comme décrit ci-dessous. + * - ``app.encrypt.property.pattern`` + - ``.*password|.*key|.*token|.*secret`` + - ``.*password|.*passphrase|.*key|.*token|.*secret`` + - Un paramètre dont le nom se termine par ``passphrase`` (par exemple ``ssh.passphrase`` d'une + configuration DataStore) est enregistré en clair. Une valeur enregistrée auparavant reste en + clair jusqu'à ce que le paramètre soit de nouveau enregistré avec le motif de la 15.10. + * - ``index.backup.log.targets`` + - ``click_log.ndjson,favorite_log.ndjson,search_log.ndjson,user_info.ndjson`` + - ``chat_log.ndjson,click_log.ndjson,favorite_log.ndjson,search_log.ndjson,user_info.ndjson`` + - La page « Informations système » → « Sauvegarde » ne propose pas ``chat_log.ndjson``. + * - ``index.export.exclude.fields`` + - ``cache`` + - ``cache,tag`` + - Le champ ``tag``, qui contient les tags des utilisateurs, n'est plus exclu des fichiers + qu'écrit la tâche Index Export. + * - ``crawler.default.script``, ``theme.allowed.archive.extensions``, + ``theme.assets.cache.max.age``, ``theme.assets.precompressed``, + ``rag.chat.message.max.length``, ``supported.uploaded.js.extentions``, + ``supported.uploaded.css.extentions``, ``supported.uploaded.media.extentions``, + ``supported.uploaded.files``, ``online.help.name.design`` + - Présentes + - Supprimées + - Aucun effet ; supprimez-les. + +La valeur fournie de ``response.headers`` contient, de la 15.0 à la 15.8, la ligne +``text/html=Content-Security-Policy: reflected-xss block``. ``reflected-xss`` était une directive d'un +des premiers brouillons de Content-Security-Policy que les navigateurs ne reconnaissent plus ; +l'en-tête ne restreint donc rien et n'ajoute qu'une erreur dans la console. La 15.10 ne fournit plus +cette ligne (les lignes ``X-XSS-Protection`` et ``X-Frame-Options`` ne changent pas), mais un +``response.headers`` repris de la 15.8 la conserve. Supprimez uniquement cette ligne de +``response.headers`` dans ``fess_config.properties``. Le ``\n\`` à la fin de chaque ligne poursuit la +valeur sur la ligne suivante ; si vous supprimez la ligne entière, les autres restent intactes :: + + text/html=Content-Security-Policy: reflected-xss block\n\ + +Si vous définissez ``response.headers`` avec ``-Dfess.config.response.headers``, supprimez la même +entrée de cette valeur. + +Un ``bin/fess.in.sh`` copié de la 15.8 ne contient pas non plus deux éléments présents dans le +fichier de la 15.10. Il laisse ``SEARCH_ENGINE_HTTP_URL`` non défini, sauf si vous l'avez défini +vous-même, alors que la 15.10 définit ``http://localhost:9200``, et il ne recherche pas le Node.js +installé par ``bin/fess-setup install nodejs`` : les plugins Playwright ne trouvent donc Node.js que si +vous définissez ``PLAYWRIGHT_NODEJS_PATH``. + +Plutôt que de copier l'un ou l'autre fichier en entier, partez du fichier fourni avec la 15.10 et +réappliquez les valeurs que vous avez modifiées. ``diff`` les affiche :: + + $ diff /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.10.0/app/WEB-INF/classes/fess_config.properties + $ diff /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.10.0/bin/fess.in.sh + +Pour une mise à niveau RPM, comparez de la même manière ``/etc/fess/fess_config.properties`` avec +``/etc/fess/fess_config.properties.rpmnew``, et pour une mise à niveau DEB avec +``/etc/fess/fess_config.properties.dpkg-dist``. Un ``fess_config.properties`` que vous n'avez jamais +modifié est remplacé par le fichier de la 15.10 lors d'une mise à niveau DEB (voir l'étape 3) : il +part donc des valeurs de la 15.10. + +``app.cipher.key`` est la seule valeur à reprendre même si la 15.10 ne l'a pas modifiée. C'est la +clé qui chiffre les mots de passe et secrets enregistrés dans les paramètres de l'authentification +Web, des configurations d'exploration et des configurations DataStore. Si la nouvelle installation +fonctionne avec une clé différente de celle qui les a enregistrés, parce que vous avez pris le +``fess_config.properties`` fourni ou restauré une sauvegarde sur un nouveau serveur, ils ne peuvent +pas être déchiffrés : ``fess-crawler.log`` consigne une ``CipherFailureException`` et une +exploration qui inclut une telle configuration peut n'indexer rien. + +.. note:: + + |Fess| 15.10 enregistre aussi le ``password`` de l'authentification Web et fichier chiffré avec ``app.cipher.key`` ; + ``fess_basic_config.bulk`` et ``fess_config.bulk`` d'une sauvegarde contiennent donc les valeurs chiffrées. Lorsque + vous restaurez sur une autre installation, reprenez la même ``app.cipher.key`` ; avec une clé différente, les + explorations qui utilisent ces identifiants échouent avec une erreur. Une sauvegarde créée avant la 15.10 les contient + en clair et continue de fonctionner (voir :doc:`../admin/backup-guide`). + +.. _upgrade-159-jcifs: + +Les délais d'attente SMB utilisent les noms de propriétés de jcifs 3 +-------------------------------------------------------------------- + +jcifs, la bibliothèque qu'utilise |Fess| pour explorer les serveurs de fichiers SMB, a renommé ses +propriétés dans sa version 3 : ``jcifs.smb.client.*`` est devenu ``jcifs.client.*``, et les noms +distincts ``jcifs.smb1.smb.client.*`` pour SMB1 ont été regroupés dans ces mêmes propriétés. +Jusqu'à la 15.8, ``jvm.crawler.options`` et ``jvm.thumbnail.options`` transmettaient encore les +anciens noms, que jcifs ignore : les explorations SMB fonctionnaient donc avec les valeurs par +défaut de jcifs. La 15.10 transmet les nouveaux noms : + +:: + + -Djcifs.client.responseTimeout=30000 + -Djcifs.client.soTimeout=35000 + -Djcifs.client.connTimeout=60000 + -Djcifs.client.sessionTimeout=60000 + +Les délais de connexion et de session prennent donc effet pour la première fois et passent de la +valeur par défaut de jcifs, 35 secondes, à 60 secondes : une exploration attend désormais jusqu'à +60 secondes un serveur SMB qui ne répond pas. Les délais de réponse et de socket sont égaux aux +valeurs par défaut de jcifs et ne changent donc pas. + +Si vous avez modifié ces délais, renommez-les dans les deux options. Sous les anciens noms, ils +n'avaient pas non plus d'effet en 15.8. Un ``fess_config.properties`` repris de la 15.8 conserve +les anciens noms, et avec eux les valeurs par défaut de jcifs. + +Quatre propriétés sans effet ont été supprimées +----------------------------------------------- + +Les clés suivantes n'existent plus dans ``fess_config.properties``. |Fess| ne les a jamais lues +dans ce fichier : une valeur laissée sous ces noms reste donc sans effet, comme auparavant. + +- ``theme.allowed.archive.extensions`` +- ``theme.assets.cache.max.age`` +- ``theme.assets.precompressed`` +- ``rag.chat.message.max.length`` + +La limite définie par ``rag.chat.message.max.length`` fonctionne toujours, mais elle est lue comme +propriété système : définissez-la dans ``app/WEB-INF/conf/system.properties`` ou avec +``-Dfess.system.rag.chat.message.max.length``, comme décrit dans :doc:`../config/rag-chat`. + +.. _upgrade-159-static-theme: + +L'écran de recherche est désormais un thème statique +---------------------------------------------------- + +L'écran de recherche est servi par le thème statique ``bootstrap``, fourni avec |Fess|, sauf si un +autre thème est sélectionné. Cela s'applique à ``/``, ``/search``, ``/advance``, ``/help``, +``/profile``, ``/cache``, ``/chat`` et aux pages d'erreur. Jusqu'à la 15.8, ces pages étaient des +JSP, sauf si un thème par défaut était défini. + +Le basculement a également lieu lors de la mise à niveau. Une installation 15.8 qui n'a jamais +défini de thème par défaut n'a pas de ``theme.default`` dans ``system.properties`` : après la mise +à niveau, elle affiche donc le thème statique ; rien n'est écrit dans la configuration et rien +n'est journalisé. Aucun paramètre ne permet de revenir à l'écran de recherche JSP. Si vous aviez +défini un thème par défaut en 15.8, ce paramètre est conservé ; installez la version 15.10 du thème +(``bin/fess-setup install theme ``), car un thème par défaut qui désigne un thème non +installé se rabat sur ``bootstrap``, avec un avertissement dans ``fess.log``. + +Si vous avez modifié les JSP, le CSS ou les images de l'écran de recherche, via « Conception de la +page » dans l'écran d'administration ou dans un plugin de thème JAR, ces modifications ne +s'affichent plus. Reportez-les dans un thème statique : copiez le thème fourni et modifiez la +copie, comme décrit dans :ref:`theme-customize-bundled`, ou installez un thème publié depuis +« Système » → « Thème » dans l'écran d'administration ou avec +``bin/fess-setup install theme ``. Une apparence propre à un hôte virtuel est désormais un thème statique portant le nom de +cet hôte virtuel ; voir :doc:`../config/security-virtual-host`. + +Ces deux fonctionnalités ont également disparu : + +- L'écran de connexion par hôte virtuel. Jusqu'en 15.8, l'enregistrement de « Système » → « Général » + copiait les JSP, y compris l'écran de connexion, dans ``WEB-INF/view//``, et + on pouvait les modifier par hôte virtuel. 15.10 ne crée plus ces copies. L'écran de connexion + (``/login/``) reste une JSP, mais tous les hôtes virtuels affichent la même, celle de + ``WEB-INF/view/admin/login/``. Les JSP copiées auparavant ne sont pas utilisées. +- Les plugins de thème JAR (``fess-theme-*``). S'il est installé, un tel plugin est seulement placé + comme un JAR générique de type ``jar`` et ne modifie aucun écran. Les JAR restants peuvent être + supprimés depuis la page « Système » → « Plugin » ou avec ``bin/fess-setup remove plugin `` + (voir :doc:`../dev/theme-development`). + +Si, en 15.8, vous affichiez vos propres champs dans les résultats de recherche JSP, ajoutez les mêmes +champs à ``query.additional.api.response.fields`` en plus de ``query.additional.response.fields``. +Le thème statique obtient les résultats de recherche depuis ``/api/v2/search``. +``query.additional.response.fields`` ajoute seulement les champs récupérés depuis le moteur de +recherche, et cette API n'inclut dans sa réponse que les champs listés dans +``query.additional.api.response.fields`` (voir :doc:`../config/search-advanced`). Modifiez aussi le +thème pour qu'il affiche ces champs. + +Ce que voient les clients +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Les erreurs sont désormais rendues sur place, à l'URL demandée et avec le véritable statut HTTP. +Un navigateur (une requête dont l'en-tête ``Accept`` contient ``text/html``) reçoit la page +d'erreur du thème ; tout autre client reçoit un corps ``text/plain`` d'une ligne (par exemple +``Not Found.`` pour ``404``). Jusqu'à la 15.8, la plupart des erreurs répondaient par une +redirection ``302`` vers une page ``/error/...`` qui renvoyait elle-même ``200``. Vérifiez la +supervision, les contrôles de santé et les clients qui suivent les en-têtes ``Location`` ou +attendent des URL ``/error/``. + +.. list-table:: + :header-rows: 1 + + * - Requête + - Jusqu'à la 15.8 + - 15.10 + * - ``/go/`` avec un paramètre manquant, ou pour un document qui n'existe pas + - ``200``, ou ``302`` vers ``/error/`` + - ``400`` ou ``404`` + * - ``/thumbnail/`` avec un paramètre manquant, pour un document inconnu, ou sans vignette + - ``200`` ou ``302`` + - ``400`` ou ``404`` + * - ``/sso/metadata`` et ``/sso/logout`` lorsque le type SSO configuré ne les prend pas en charge + - ``302`` vers ``/error/badrequest/`` + - ``400`` + * - ``/api/v1/*``, ``/json`` et toute URL inconnue + - ``302`` vers ``/error/notfound/`` + - ``404`` + * - Une exception non interceptée, y compris dans l'API d'administration + - ``302`` vers ``/error/systemerror/`` + - ``500`` avec le corps ``System Error.`` (pas du JSON) + * - ``/error/notfound/``, ``/error/badrequest/``, ``/error/systemerror/`` eux-mêmes + - ``200`` + - ``404``, ``400``, ``500`` + +Avec ``login.required=true``, les pages de recherche ne redirigent plus un utilisateur anonyme. +Elles renvoient ``200`` avec le thème, qui demande à l'utilisateur de se connecter, et ce sont les +données sous-jacentes qui sont refusées : tous les points de terminaison ``/api/v2/`` autres que +``/health``, ``/auth/*`` et ``/ui/config``, y compris ``/api/v2/search``, répondent ``401`` tant +que l'utilisateur ne s'est pas connecté. ``/go/``, ``/thumbnail/`` et ``/osdd`` redirigent toujours +vers la connexion. Un contrôle qui attend une redirection pour une requête anonyme vers ``/`` doit +plutôt vérifier que ``/api/v2/search`` renvoie ``401``. + +L'écran de recherche effectue aussi ses recherches via ``/api/v2/search`` : une recherche est donc +journalisée lorsque cette API est appelée, et non lorsque ``/search`` est demandé. Un client qui +n'exécute pas JavaScript reçoit la page sans résultats. + +Le HTML de l'écran de recherche porte ``X-Frame-Options: DENY`` et un ``Content-Security-Policy`` avec +``frame-ancestors 'none'`` : aucune autre page ne peut l'afficher dans un cadre. L'écran de recherche JSP de +la 15.8 envoyait ``X-Frame-Options: SAMEORIGIN`` (valeur par défaut de ``response.headers``) et pouvait +s'afficher dans un ``iframe`` d'une page de la même origine. Si vous intégriez l'écran de recherche dans un +``iframe`` de la même origine, réglez ``theme.index.frame.ancestors`` dans ``fess_config.properties`` (par +défaut ``'none'``) sur ``'self'``. Pour l'intégrer depuis une autre origine, indiquez cette origine (voir +:doc:`../dev/theme-development`). + +L'éditeur de conception de page a été supprimé +---------------------------------------------- + +[Système > Conception de la page] ne fait plus partie de l'écran d'administration : les fichiers +JSP, CSS et images de l'écran de recherche ne peuvent plus y être modifiés. Pour changer +l'apparence de l'écran de recherche, utilisez un thème statique (voir :ref:`theme-customize-bundled`). + +Les clés suivantes ont également été supprimées de ``fess_config.properties``. Une valeur laissée +sous ces noms n'est pas utilisée. + +- ``supported.uploaded.js.extentions`` +- ``supported.uploaded.css.extentions`` +- ``supported.uploaded.media.extentions`` +- ``supported.uploaded.files`` +- ``online.help.name.design`` + +Les rôles ``admin-design`` et ``admin-design-view`` n'accordent plus aucun droit. Un utilisateur qui +n'a que ces rôles arrive sur l'écran de recherche, et non sur l'écran d'administration, après +s'être connecté. + +``api.access.token.required`` a été supprimé +-------------------------------------------- + +``api.access.token.required`` n'existe plus dans ``fess_config.properties``. Une valeur laissée sous +ce nom n'a aucun effet, y compris dans un ``fess_config.properties`` repris de la 15.8. Avec +``true``, ce paramètre refusait toute requête API d'un utilisateur non connecté. Comme l'écran de +recherche effectue désormais ses recherches via ``/api/v2/search``, il aurait en outre présenté aux +utilisateurs anonymes un écran de recherche sans résultats. + +Une installation qui l'avait réglé sur ``true`` répond désormais aux requêtes API des utilisateurs +anonymes avec les rôles invités, comme pour l'écran de recherche. Pour empêcher les utilisateurs +anonymes de rechercher, définissez ``login.required=true``. Les jetons d'accès fonctionnent comme +avant : une requête munie d'un jeton d'accès enregistré reçoit les permissions de ce jeton, et une +requête munie d'un jeton non enregistré ou expiré est refusée. + +.. _upgrade-159-api-requests: + +Requêtes que l'API refuse désormais +----------------------------------- + +La 15.10 refuse les requêtes suivantes, que la 15.8 acceptait. Vérifiez les clients et les scripts que vous +avez écrits pour la 15.8. L'API d'administration répond à un refus par HTTP ``400`` et ``status`` ``1`` dans +le corps. + +.. list-table:: + :header-rows: 1 + + * - Requête + - Jusqu'à la 15.8 + - 15.10 + * - ``/api/v2/search`` avec ``facet.field`` ou ``facet.query`` et un ``facet.size`` inférieur ou égal à ``0``, ou un ``facet.size`` ou ``facet.minDocCount`` qui n'est pas un entier + - ``200``, mais un résultat vide : ``record_count`` vaut ``0`` et ``partial`` vaut ``true`` + - ``400`` (``invalid_request``). ``facet.size`` doit valoir ``1`` ou plus + * - ``track_total_hits=false``. Si ``query.track.total.hits`` vaut ``false``, toutes les recherches sont concernées + - ``200``, mais sans résultat + - La recherche est refusée (``/api/v2/search`` répond ``400`` avec ``invalid_request``). ``true`` et les entiers positifs fonctionnent comme avant + * - Une entrée des dictionnaires ``mapping`` ou ``kuromoji`` qui répète une entrée existante, créée ou modifiée via l'API d'administration + - Enregistrée. Le chargement du dictionnaire échoue ensuite, ce qui peut rendre la recherche indisponible + - ``400`` + * - Une entrée du dictionnaire ``kuromoji`` dont le ``token`` contient une espace, ou dont ``segmentation`` et ``reading`` n'ont pas le même nombre d'éléments séparés par des espaces, créée ou modifiée via l'API d'administration + - Enregistrée. Le chargement du dictionnaire échoue de la même façon + - ``400`` + * - ``DELETE /api/admin/searchlist/doc/{doc_id}`` qui ne supprime rien : un ``doc_id`` qui n'existe pas, ou une valeur qui n'est pas un ``doc_id``, comme le ``_id`` de la liste des documents + - ``200`` (``status`` ``0``) ; le document n'est pas supprimé + - ``400`` + * - Un nom de rôle ou de groupe dans ``roles`` ou ``groups`` d'un utilisateur de l'API d'administration + - Enregistré, mais le nom n'agit pas comme un rôle. Pour certains noms, la lecture de l'utilisateur échoue + - ``400``. Indiquez l'ID du rôle ou du groupe (le ``id`` renvoyé par ``GET /api/admin/role/settings`` et ``GET /api/admin/group/settings``) + * - Un utilisateur de l'API d'administration dont le mot de passe enfreint la politique de mot de passe (par exemple ``password.min.length``, ``8`` par défaut) ; une création sans mot de passe ; un ``confirm_password`` différent de ``password`` + - Enregistré ; l'utilisateur peut se connecter avec ce mot de passe + - ``400`` + +Les lignes de ``/api/v2/documents/all`` ne portent plus ``score``. Jusqu'à la 15.8, chaque document avait +son score de recherche ; la 15.10 parcourt tout le résultat avec un point in time et ``search_after``, ce qui +ne produit pas de score. ``/json?type=scroll`` et ``/api/v1/documents/all`` des plugins des anciennes API se +comportent de la même façon. Un script qui lit ``score`` doit tolérer son absence. + +Les envois de fichiers de l'API d'administration (les six dictionnaires, ``badword``, ``elevateword`` et +``storage``) sont acceptés par ``POST``. La documentation de la 15.8 indiquait ``PUT``, mais un ``PUT`` en +``multipart/form-data`` ne transmet jamais le fichier : en 15.8 comme en 15.10, il échoue avec l'erreur de +validation indiquant que le fichier est obligatoire. Les points de terminaison ``PUT`` subsistent ; utilisez +``POST`` pour les envois. + +``search_engine.type=cloud`` est obsolète +----------------------------------------- + +La version 15.10 ajoute la valeur ``vanilla`` à ``search_engine.type`` pour un OpenSearch standard sans les plugins CodeLibs (voir :doc:`../config/search-engine-type`). ``cloud`` devient un alias obsolète de ``vanilla`` : il continue de fonctionner, mais |Fess| consigne un avertissement au démarrage. Remplacez-le par ``vanilla`` dès que l'installation fonctionne en 15.10. ``aws`` continue de fonctionner comme avant. + +* ``vanilla`` nécessite la 15.10. |Fess| 15.8 et les versions antérieures ne connaissent pas cette valeur ; conservez donc ``cloud`` tant que vous pouvez encore revenir à la 15.8. +* Les définitions d'index de ``aws`` et de ``cloud`` sont désormais lues dans ``fess_indices/_vanilla/``. Les répertoires ``fess_indices/_aws/`` et ``fess_indices/_cloud/`` fournis n'existent plus, et un répertoire ``fess_indices/_aws/`` ou ``fess_indices/_cloud/`` que vous avez ajouté n'est plus lu. Reportez vos modifications dans ``fess_indices/_vanilla/``. Les index déjà existants ne sont pas modifiés. +* Les paramètres de suggestion que la 15.8 a enregistrés dans le moteur de recherche sont migrés automatiquement ; vous n'avez rien à faire. + +Le DataStore CSV analyse les champs entre guillemets +---------------------------------------------------- + +Le plugin ``fess-ds-csv`` de la 15.10 interprète les guillemets par défaut. Un champ tel que +``"Yamada, Taro"`` forme une seule colonne, alors que le plugin de la 15.8.0 le coupait à la +virgule. Après ``bin/fess-setup upgrade plugins``, vérifiez les configurations DataStore qui lisent +des fichiers CSV contenant des champs entre guillemets. Pour conserver le comportement de la 15.8, +ajoutez ``quote_disabled=true`` aux « Paramètres » ; voir :doc:`../config/datastore/ds-csv`, qui +décrit aussi ce que fait un guillemet sans correspondance. + +.. _upgrade-reindex-new-fields: + +Appliquer les nouveaux champs et la normalisation des kana à un index de documents existant +------------------------------------------------------------------------------------------- + +Au démarrage, la 15.10 ajoute de nouveaux champs aux index de configuration, de journaux et +d'utilisateurs. Dans l'index de documents, elle n'ajoute que le champ ``tag`` (``keyword``), qui +contient les tags des utilisateurs ; le reste du mapping et les paramètres d'analyse ne sont pas +modifiés. Si vous conservez un index de documents créé avec la 15.8 ou antérieure, les changements +suivants de la 15.10 ne prennent pas effet. + +- **Propriétaire et dernier modificateur d'un fichier** (``owner``, ``last_modifier``) : nouveaux + champs indexés par les crawls du système de fichiers, SMB et FTP. L'index de documents existant ne + les définit pas ; la première valeur crawlée les mappe donc dynamiquement en ``text``, et les + recherches comme ``owner:alice`` ou ``facet.field=owner`` ne fonctionnent pas comme prévu. +- **ETag** (``etag``) : le champ dans lequel le crawler stocke l'ETag d'une page crawlée, que la + 15.10 renvoie sous la forme ``If-None-Match`` afin qu'une page inchangée ne soit pas récupérée de + nouveau. L'index de documents existant ne le définit pas non plus ; il est donc mappé + dynamiquement en ``text`` au lieu du ``keyword`` non indexé fourni. Les requêtes conditionnelles + fonctionnent quand même avec ce mapping. +- **Normalisation des variantes de kana et des tirets écrits à la place de la marque de voyelle + longue** (par exemple, ``サ―バ－`` est traité comme le même mot que ``サーバー``) : les règles se + trouvent dans les paramètres d'analyse de l'index de documents et dans le dictionnaire + ``mapping.txt`` ; un index existant ne les reçoit donc pas. + +Pour appliquer les deux, activez « Remplacer les alias » et « Réinitialiser les dictionnaires » sous +« Informations système » → « Maintenance » dans l'interface d'administration, puis lancez la +« Réindexation ». La réindexation copie les documents existants dans un nouvel index ; il n'est pas +nécessaire de recrawler. + +.. warning:: + + « Réinitialiser les dictionnaires » écrase les dictionnaires côté OpenSearch avec les fichiers de + dictionnaire fournis. Si vous avez modifié des synonymes ou d'autres dictionnaires sous + « Dictionnaire » dans l'interface d'administration, téléchargez-les d'abord et réappliquez-les + après la réindexation : supprimez les entrées en double ou invalides des fichiers téléchargés + (voir l'étape 7), téléversez-les, puis cliquez sur « Recharger » sous « Recharger l'index des + documents » dans « Informations système » → « Maintenance ». Tant que vous ne le faites pas, les + analyseurs de l'index de documents continuent d'utiliser les dictionnaires fournis et un synonyme + restauré ne correspond pas, quelle que soit la durée de l'attente. Un dictionnaire qui s'applique + à l'indexation exige aussi que les documents soient crawlés de nouveau ; voir + :ref:`dict-apply-changes`. + +.. note:: + + Les fichiers indexés avec la 15.8 ou antérieure n'ont pas de valeur de propriétaire ni de dernier + modificateur. Le crawl incrémental ne récupère pas à nouveau les fichiers inchangés ; pour ajouter + les valeurs, désactivez temporairement « Vérifier la dernière modification » sous « Système » → + « Général » et lancez un crawl. + + +Migrations spécifiques à la 15.10 +================================ + +Si vous effectuez une mise à niveau depuis la version 15.7 ou antérieure vers la 15.10, 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.10. 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.10, 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. La 15.10 ajoute également ``fess-llm-bedrock`` pour Amazon Bedrock. + +Si vous utilisiez SPNEGO (authentification intégrée Windows) +------------------------------------------------------------ + +À partir de la 15.10, une connexion SPNEGO est refusée lorsque le domaine Kerberos du principal +client diffère de celui du serveur. Si vos utilisateurs se connectent depuis un domaine enfant +d'une arborescence de domaines AD ou depuis une forêt approuvée, indiquez ces domaines, séparés +par des virgules, dans ``spnego.allowed.realms`` depuis « Système » → « Général » dans +l'écran d'administration ou dans ``app/WEB-INF/conf/system.properties``. Sinon, les utilisateurs +qui pouvaient se connecter jusqu'à la version 15.7 sont refusés avec +``Kerberos realm is not allowed``. Pour plus de détails, consultez +:doc:`../config/sso-spnego`. + +Par ailleurs, en 15.10, les valeurs par défaut codées de ``spnego.allow.unsecure.basic`` et +``spnego.allow.localhost`` sont passées de ``true`` à ``false``. Une installation dans laquelle +ces clés sont absentes de ``app/WEB-INF/conf/system.properties`` adopte le comportement plus +strict lors de la mise à niveau. En particulier, avec ``spnego.allow.unsecure.basic=false``, la +bibliothèque SPNEGO ne propose l'authentification Basic que pour les requêtes dont +``HttpServletRequest#isSecure()`` renvoie ``true`` : derrière un proxy inverse qui termine TLS et +transmet la requête en HTTP, les clients qui basculaient jusqu'ici vers l'authentification Basic +ne peuvent plus se connecter. Dans ce cas, définissez ``tomcat.secure=true`` dans +``tomcat_config.properties`` ; pour plus de détails, consultez :doc:`../config/sso-spnego`. + +.. warning:: + + Une valeur par défaut codée ne s'applique que tant que la clé est absente, et + « Système » → « Général » de l'écran d'administration écrit toutes les clés ``spnego.*`` à + chaque enregistrement. Une installation sur laquelle « Mettre à jour » a été cliqué au moins + une fois depuis cet écran en 15.7 conserve donc ``spnego.allow.unsecure.basic=true`` et + ``spnego.allow.localhost=true``, et la mise à niveau vers la 15.10 ne la durcit pas : elle + conserve silencieusement le comportement permissif, et la 15.10 se contente de consigner un + avertissement dans ``fess.log`` lors de l'initialisation de SPNEGO. Ouvrez + « Système » → « Général » (ou modifiez ``system.properties``) et désactivez délibérément les + deux options. ``spnego.allow.localhost=true`` est la plus dangereuse des deux : la bibliothèque + SPNEGO authentifie alors les requêtes provenant du même hôte en tant qu'utilisateur du système + d'exploitation du serveur, sans aucune vérification Kerberos, ce qui n'est pas sûr derrière un + proxy inverse situé sur le même hôte. + +.. _upgrade-159-saml: + +Si vous utilisiez l'authentification SAML (SSO) +----------------------------------------------- + +À partir de la 15.10, |Fess| associe chaque réponse SAML à l'identifiant de l'AuthnRequest qu'il +a émise, si bien que le SSO initié par l'IdP (non sollicité) ne fonctionne plus. Une connexion +démarrée depuis une vignette |Fess| dans un portail IdP, tel que le tableau de bord Okta ou le +portail « Mes applications » de Microsoft Entra ID, n'a aucune AuthnRequest correspondante et est +rejetée. Cela fonctionnait jusqu'à la 15.7 parce que |Fess| renvoyait à l'IdP la réponse qu'il ne +pouvait pas associer et que l'IdP retournait immédiatement une assertion sollicitée. Si vous +placez une vignette côté IdP, faites-la pointer vers le point d'accès ``/sso/`` de |Fess| afin que +la connexion soit initiée par le SP. + +Par ailleurs, l'IdP renvoie l'assertion via un POST intersites : ``tomcat.sameSiteCookies`` doit +donc être défini sur ``none`` dans ``tomcat_config.properties``. Avec la valeur par défaut livrée +``lax``, le cookie de session n'est pas envoyé sur cette requête et la connexion SAML ne peut pas +aboutir. Ce fichier se trouve dans ``lib/classes/`` pour le paquet ZIP et dans ``/etc/fess/`` pour +les paquets DEB/RPM, et |Fess| doit être redémarré après la modification. Les navigateurs +n'acceptent ``none`` que sur un cookie portant également l'attribut ``Secure`` : |Fess| doit donc +être servi en HTTPS. Jusqu'à la 15.7, la même erreur de configuration ne provoquait pas d'échec +net mais une boucle de redirections sans fin vers l'IdP ; vérifiez donc le paramètre même sur un +site qui semblait fonctionner. En 15.10, la connexion échoue une seule fois au lieu de boucler. +Pour plus de détails, consultez :doc:`../config/sso-saml`. + +Si vous utilisiez Microsoft Entra ID (Azure AD) +----------------------------------------------- + +À partir de la 15.10, le mode de réponse demandé au point de terminaison d'autorisation vaut +``query`` par défaut au lieu de ``form_post``. Jusqu'à la 15.7, le callback était renvoyé par un +POST intersite, et la valeur par défaut de |Fess| ``tomcat.sameSiteCookies = lax`` n'envoie pas +le cookie de session avec une telle requête ; ``tomcat.sameSiteCookies = none`` était donc +nécessaire. Si vous aviez défini ``none`` uniquement pour cette raison, vous pouvez revenir à la +valeur par défaut. Pour conserver le comportement précédent, définissez +``entraid.response.mode=form_post`` et laissez ``tomcat.sameSiteCookies = none`` en place. Les +navigateurs n'acceptent ``none`` que sur un cookie portant également l'attribut ``Secure`` : cette +voie impose donc elle aussi de servir |Fess| en HTTPS. + +À partir de la 15.10, |Fess| résout également l'appartenance aux groupes et rôles de l'utilisateur +en arrière-plan une fois la connexion terminée, au lieu de bloquer la connexion en attendant +Microsoft Graph. Tant que la résolution n'est pas terminée — ou si elle n'aboutit pas +entièrement —, l'utilisateur ne dispose que de sa propre autorisation au niveau utilisateur et de +ce qu'apportent ``entraid.default.groups`` et ``entraid.default.roles``. Si aucun des deux n'est +défini — la valeur livrée par défaut —, une recherche effectuée pendant cette fenêtre ne renvoie +aucun document, car une configuration d'exploration créée avec les valeurs livrées par défaut +accorde ``{role}guest``, rôle que ne possède pas un utilisateur connecté. Pendant que la +résolution est en cours, l'écran de recherche l'indique, et il affiche un autre message si elle +n'a pas entièrement abouti : la résolution n'est considérée comme réussie que si la requête des +appartenances directes et le parcours des groupes imbriqués ont tous deux abouti. La résolution +est relancée à chaque renouvellement du jeton d'accès, et une réussite ultérieure fait disparaître +le message : un échec n'est donc pas définitif pour une session qui dure plus longtemps que le +jeton. Pour réessayer immédiatement, déconnectez-vous puis reconnectez-vous. Pour plus de détails, +consultez :doc:`../config/sso-entraid`. + +Conséquence de cette résolution en arrière-plan : tant qu'elle n'a pas abouti, les rôles résolus +de l'utilisateur ne sont pas encore connus. Un administrateur est donc redirigé vers l'écran de +recherche au lieu du tableau de bord de l'administration, et l'ouverture d'une page de l'écran +d'administration pendant cette fenêtre le ramène à l'écran de recherche. La fenêtre dure jusqu'à +environ une seconde de délai de planification, plus les appels à Microsoft Graph eux-mêmes — un +pour les appartenances directes, puis un de plus pour chacun de ces groupes afin de parcourir les +groupes imbriqués, émis les uns après les autres avec un cache froid — : elle croît donc avec le +nombre de groupes auxquels appartient l'utilisateur. Dans cette fenêtre, l'accès n'est jamais +accordé, seulement refusé, et aucun paramétrage n'est nécessaire pour la franchir : l'autorisation +est réévaluée à chaque requête de la même session, si bien qu'une fois la résolution terminée les +écrans d'administration s'ouvrent normalement, sans avoir à se reconnecter. + +.. warning:: + + Ne raccourcissez pas cette fenêtre en plaçant le rôle d'administrateur |Fess| dans + ``entraid.default.roles``. Cette propriété est une valeur globale unique que |Fess| applique à + tous les utilisateurs Entra ID lors de la connexion et réapplique à chaque résolution + ultérieure : elle donnerait à tous les utilisateurs du locataire des droits d'administrateur + |Fess| permanents. + +Si Vous Utilisez LDAP / Active Directory +----------------------------------------- + +À partir de 15.10, le nom de permission d'un groupe ou d'un rôle correspond à la valeur du RDN de +l'entrée et non plus à une portion du texte du DN. Un groupe dont le CN contient un caractère +échappé dans le DN -- la virgule est le cas courant -- obtient donc un nom de permission différent +de celui de 15.7. + +.. list-table:: + :header-rows: 1 + + * - DN de l'entrée du groupe + - Nom de permission jusqu'à 15.7 + - Nom de permission en 15.10 + * - ``CN=Sales\, EMEA,CN=Users,...`` + - ``2Sales`` + - ``2Sales, EMEA`` + * - ``CN=Sales\, APAC,CN=Users,...`` + - ``2Sales`` + - ``2Sales, APAC`` + +Jusqu'à 15.7, plusieurs groupes identiques jusqu'à la virgule se réduisaient à un même nom de +permission : les membres de ``Sales, EMEA`` et de ``Sales, APAC`` pouvaient donc lire les documents +de l'autre groupe ainsi que ceux du groupe ``Sales``. En 15.10, chacun obtient son propre nom de +permission et cet accès inter-groupes ne se produit plus. + +En contrepartie, **les documents indexés sous l'ancien nom de permission ne sont plus visibles par +les membres de ce groupe**. Si le paramètre de permission d'une configuration d'exploration contient +un ancien nom de permission, remplacez-le par le nouveau puis relancez l'exploration (ou la +réindexation). Si vous n'utilisez aucun groupe dont le CN contient une virgule ou un autre caractère +échappé, aucun nom de permission ne change. + +Modification de ``ldap.role.search.user.enabled`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Jusqu'à 15.7, la permission dérivée du nom d'utilisateur (``role.search.user.prefix`` suivi du nom +d'utilisateur) était accordée même avec ``ldap.role.search.user.enabled=false``. À partir de 15.10, +le paramètre prend effet et la permission n'est plus accordée lorsqu'il est désactivé. + +Dans une installation où il vaut ``false``, les utilisateurs perdent après la mise à niveau la +permission portant leur propre nom : les documents attribués à un utilisateur donné ne remontent +plus pour cet utilisateur. Pour conserver le comportement précédent, rétablissez la valeur par +défaut ``true``. + +Si vous aviez modifié les clés de configuration /api/v2 +------------------------------------------------------- + +En 15.8.0, quatre clés de configuration ont perdu leur préfixe ``api.v2.``. Leurs valeurs, leurs +valeurs par défaut et leur comportement sont inchangés, mais **aucun alias rétrocompatible n'est +conservé** : un paramètre laissé sous son ancien nom est ignoré sans avertissement et la valeur +par défaut fournie s'applique. + +.. list-table:: + :header-rows: 1 + + * - Jusqu'à 15.7 + - 15.8.0 et versions ultérieures + - Valeur par défaut + * - ``api.v2.chat.stream.keepalive.interval.ms`` + - ``api.chat.stream.keepalive.interval.ms`` + - ``15000`` + * - ``api.v2.param.max.length`` + - ``api.param.max.length`` + - ``1000`` + * - ``api.v2.param.max.array.size`` + - ``api.param.max.array.size`` + - ``100`` + * - ``api.v2.click.max.rt`` + - ``api.click.max.timestamp`` + - ``9999999999999`` + +Si vous avez défini l'une de ces clés dans ``fess_config.properties`` ou via l'argument JVM +``-Dfess.config.``, renommez-la. Seuls les paramètres explicites sont concernés ; une +installation qui ne les a jamais modifiés n'a rien à faire. + +La première clé détermine la fréquence d'envoi d'une trame keep-alive pendant que +``POST /api/v2/chat/stream`` attend le modèle : c'est donc dans le mode de recherche IA qu'un +paramètre perdu se remarque. La dernière clé a également été renommée par souci d'exactitude : +elle borne la valeur ``rt`` que peut porter un journal de clic, qui est un horodatage et non un +temps de réponse. + + +.. _upgrade-plugin-versions: + +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|. ``bin/fess-setup upgrade plugins`` le fait pour tous les plugins +installés : il installe la version construite pour ce |Fess| et supprime l'ancienne. Redémarrez +ensuite |Fess|. ``bin/fess-setup check`` indique alors l'état d'OpenSearch, de ses plugins et des +plugins |Fess| installés, et se termine avec le code 1 en cas de problème. Il ne lit pas +``bin/fess.in.sh``, ``/etc/sysconfig/fess`` ni ``/etc/default/fess`` : lorsque OpenSearch ne se +trouve pas à ``http://localhost:9200``, passez ``--url`` ou définissez ``SEARCH_ENGINE_HTTP_URL`` +dans le shell qui l'exécute ; sinon il signale le moteur comme injoignable. + +:: + + $ bin/fess-setup upgrade plugins + $ bin/fess-setup check + +``upgrade plugins`` ne traite que les plugins déjà installés. Installez avec +``bin/fess-setup install plugin``, comme indiqué dans les sections précédentes, les plugins qui +remplacent des éléments retirés de la distribution en 15.10, comme ``fess-script-groovy``. + +Si vous spécifiez ``FESS_PLUGINS`` pour la version Docker, mettez à jour la partie version, par +exemple ``fess-ds-wikipedia:15.10.0``. + +Procédure de retour arrière +============================ + +En cas d'échec de la mise à niveau, vous pouvez revenir en arrière avec les procédures suivantes. + +Étape 1 : Arrêt de la nouvelle version +--------------------------------------- + +:: + + $ sudo systemctl stop fess.service + $ sudo systemctl stop opensearch.service + +Étape 2 : Restauration de l'ancienne version +--------------------------------------------- + +Restaurez les fichiers de configuration et les données depuis la sauvegarde. + +Version RPM/DEB :: + + $ sudo rpm -Uvh --oldpackage --nodeps fess-.rpm + +Ou :: + + $ sudo dpkg -i fess-.deb + +.. note:: + + ``--nodeps`` est nécessaire pour le RPM. Le paquet 15.8.0 exige les utilisateurs et groupes + ``fess`` et ``opensearch`` ; sans cette option, ``rpm`` refuse le retour à la version antérieure + avec ``Failed dependencies: group(fess) is needed by fess-15.8.0``. + +.. warning:: + + Le paquet DEB 15.8.0 n'enregistre pas ``/etc/fess/*`` en tant que conffiles ; ``dpkg -i`` écrase + donc les fichiers que vous avez modifiés, tels que ``/etc/fess/fess_config.properties``, sans en + conserver de copie. Restaurez-les depuis la sauvegarde effectuée à l'étape 1. + +Étape 3 : Restauration des données +------------------------------------ + +Restauration depuis le snapshot. OpenSearch doit être en cours d'exécution et |Fess| arrêté : + +1. Démarrez OpenSearch :: + + $ sudo systemctl start opensearch.service + +2. Un snapshot ne peut pas être restauré par-dessus un index existant ; supprimez donc d'abord tous + les index Fess, y compris ceux créés après la mise à niveau (par exemple par une + réindexation), ainsi que l'index ``configsync`` que crée le plugin OpenSearch. Si vous ne + supprimez que les index présents dans le snapshot, un index créé par la réindexation subsiste, + ``fess.search`` pointe sur deux index et la 15.8.0 ne démarre pas :: + + $ curl "http://localhost:9200/_cat/indices/fess*,configsync?h=index" + $ curl -X DELETE "http://localhost:9200/" + + Exécutez la seconde commande pour chaque index que la première liste. + +3. Restaurez le snapshot :: + + $ curl -X POST "http://localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true" + +.. note:: + + Le répertoire des dictionnaires doit exister comme auparavant (``configsync.config_path``, avec + les fichiers de dictionnaire). Sur une machine qui l'a perdu, la restauration se termine mais les + index qui utilisent les dictionnaires restent en rouge. + +Ou restauration du répertoire depuis la sauvegarde (utilisez le nom de l'archive que vous avez +créée à l'étape 1) :: + + $ sudo systemctl stop opensearch + $ sudo rm -rf /var/lib/opensearch/data/* + $ sudo tar xzf /backup/opensearch-data-.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 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 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 +----------------------------------------------- + +:: + + $ sudo systemctl start opensearch.service + $ sudo systemctl start fess.service + +Vérifiez le fonctionnement et confirmez le retour à la normale. + +Questions fréquemment posées +============================== + +Q : Peut-on effectuer une mise à niveau sans temps d'arrêt ? +-------------------------------------------------------------- + +R : La mise à niveau de Fess nécessite l'arrêt du service. Pour minimiser le temps d'arrêt, envisagez ce qui suit : + +- Vérifier les procédures dans un environnement de test au préalable +- Effectuer la sauvegarde à l'avance +- Assurer suffisamment de temps pour la fenêtre de maintenance + +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.10 est compatible avec OpenSearch 3.9.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.9.0). + +Notez par ailleurs que |Fess| 15.10 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 de |Fess| (15.x → 15.10) 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. +- **Recherche par propriétaire ou normalisation des kana avec un index de documents créé avec la 15.8 + ou antérieure** : une réindexation est nécessaire. Voir :ref:`upgrade-reindex-new-fields`. + +.. 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 +-------------------------------------------------------------------------- + +R : Vérifiez les points suivants : + +1. Vérifiez qu'OpenSearch est démarré +2. Vérifiez que l'index existe (``curl http://localhost:9200/_cat/indices``) +3. Réexécutez l'exploration + +Étapes suivantes +================ + +Une fois la mise à niveau terminée : + +- :doc:`run` - Vérification du démarrage et de la configuration initiale +- :doc:`security` - Révision de la configuration de sécurité +- :doc:`../config/search-semantic` - Configuration et étapes de migration de la recherche par + vecteurs de chunks (recherche sémantique) +- Vérifiez les nouvelles fonctionnalités dans les notes de version diff --git a/fr/15.10/user/advanced-search.rst b/fr/15.10/user/advanced-search.rst new file mode 100644 index 000000000..43a48e25f --- /dev/null +++ b/fr/15.10/user/advanced-search.rst @@ -0,0 +1,79 @@ +================== +Recherche avancée +================== + +L'écran de recherche avancée permet d'effectuer des recherches plus complexes en combinant plusieurs conditions. + +Utilisation +----------- + +L'écran de recherche avancée est accessible depuis le lien « Recherche avancée » dans les options de recherche de l'écran de recherche. Lorsqu'il est ouvert depuis l'écran des résultats de recherche, les mots-clés déjà saisis sont reportés dans le champ « Tous les mots ». + +|image0| + +Saisissez les conditions dans chaque champ, puis cliquez sur le bouton Rechercher en bas de la page. Les différents champs saisis sont combinés en une seule condition de recherche. + +Liste des champs +---------------- + +Tous les mots +::::::::::::: + +Recherche les documents contenant tous les mots saisis (recherche ET). Vous pouvez spécifier plusieurs mots séparés par des espaces. + +Correspondance exacte incluant l'ordre des mots +::::::::::::::::::::::::::::::::::::::::::::::::: + +Recherche les documents contenant exactement la chaîne de caractères saisie, ordre des mots compris (recherche par expression). Comme l'ensemble de la chaîne, espaces compris, est traité comme une seule expression, il n'est pas possible de la scinder en mots distincts pour la recherche. + +N'importe quel mot +:::::::::::::::::: + +Recherche les documents contenant l'un quelconque des mots saisis (recherche OU). Vous pouvez spécifier plusieurs mots séparés par des espaces. + +Mots à exclure +:::::::::::::: + +Recherche les documents ne contenant aucun des mots saisis. Vous pouvez spécifier plusieurs mots séparés par des espaces ; tous les mots spécifiés sont exclus des résultats de recherche. + +Nombre de résultats +::::::::::::::::::: + +Permet de spécifier le nombre de résultats de recherche affichés par page. Vous pouvez choisir parmi 10, 20, 30, 40, 50 ou 100. Si aucune valeur n'est spécifiée, le nombre d'affichage par défaut est utilisé (valeur initiale : 10). + +Tri +::: + +Permet de spécifier le critère de tri des résultats de recherche. Vous pouvez choisir parmi « par score », « par nom de fichier », « par date », « par taille » et « par dernière modification », chacun dans l'ordre croissant ou décroissant. Le tri « par nombre de clics » ou « par nombre de favoris » est disponible lorsque la fonctionnalité correspondante est activée. + +Langue préférée +::::::::::::::: + +Permet de spécifier la langue préférée des résultats de recherche. Vous pouvez sélectionner plusieurs langues. Si « Toutes les langues » est sélectionné, aucune langue particulière n'est privilégiée. + +Étiquette +::::::::: + +Permet de filtrer la recherche par étiquette. Vous pouvez sélectionner plusieurs étiquettes. Ce champ n'apparaît pas si aucune étiquette n'est enregistrée ou si aucune étiquette n'est consultable par l'utilisateur actuel. + +Date de mise à jour +::::::::::::::::::: + +Permet de filtrer la recherche par date et heure de mise à jour du document. Vous pouvez choisir parmi « N'importe quand », « Dernières 24 heures », « Semaine dernière », « Mois dernier » et « Année dernière ». + +Format de fichier +::::::::::::::::: + +Permet de filtrer la recherche par format de fichier du document. Vous pouvez choisir parmi « Tout format », « HTML », « PDF », « MS Word », « MS Excel » et « MS PowerPoint ». + +Cible de recherche +:::::::::::::::::: + +Permet de spécifier l'emplacement de la recherche. Vous pouvez choisir parmi « N'importe où dans la page », « dans le titre de la page » et « dans l'URL de la page ». Si l'option titre ou URL est sélectionnée, les mots saisis sont recherchés uniquement dans le titre ou dans l'URL, respectivement. + +Site ou domaine +::::::::::::::: + +Permet de filtrer la recherche par le site ou le domaine saisi. Spécifiez-le lorsque vous souhaitez rechercher uniquement les documents contenus dans un site ou un domaine particulier. + +.. |image0| image:: ../../../resources/images/en/15.10/user/advanced-search-1.png diff --git a/fr/15.10/user/chat-search.rst b/fr/15.10/user/chat-search.rst new file mode 100644 index 000000000..5fc4f627d --- /dev/null +++ b/fr/15.10/user/chat-search.rst @@ -0,0 +1,279 @@ +==================== +Mode de recherche IA +==================== + +Aperçu +====== + +Le mode de recherche IA (chat RAG) de |Fess| vous permet de rechercher des informations sous une +forme conversationnelle naturelle, en complément de la recherche classique par mots-clés. Lorsque +vous saisissez une question, l'assistant IA recherche les documents pertinents et génère, à partir +de leur contenu, une réponse facile à comprendre. + +.. note:: + Le mode de recherche IA est désactivé par défaut. Pour l'utiliser, un administrateur système doit + activer la fonctionnalité et configurer un fournisseur de LLM (grand modèle de langage). + Pour la configuration, consultez :doc:`../config/rag-chat` et :doc:`../config/llm-overview`. + +Caractéristiques du mode de recherche IA +========================================= + +Recherche sous forme de dialogue +--------------------------------- + +Plutôt que de chercher les bons mots-clés, vous pouvez poser vos questions comme dans une +conversation ordinaire. + +Exemples : + +- « Comment installer Fess ? » +- « Comment crawler des fichiers ? » +- « Que faire si les résultats de recherche ne s'affichent pas ? » + +Réponses tenant compte du contexte +------------------------------------ + +L'assistant IA analyse l'intention de la question, recherche les documents pertinents, puis en +extrait les informations nécessaires à partir de plusieurs résultats de recherche afin de fournir +une réponse organisée. + +Indication explicite des sources +----------------------------------- + +Les documents à l'origine de la réponse sont affichés en bas de celle-ci sous la forme d'une liste +de « sources ». Chaque source est un lien numéroté ; cliquer dessus permet de consulter directement +le document original. Le corps de la réponse peut également comporter des citations sous forme de +numéros tels que ``[1]`` ou ``[2]``, qui correspondent aux numéros de la liste des sources. + +Poursuite de la conversation +------------------------------- + +Vous n'êtes pas limité à une seule question : vous pouvez poursuivre la conversation. L'assistant +IA répond aux questions supplémentaires en tenant compte du contexte des questions et réponses +précédentes. + +Utilisation de la recherche par chat +====================================== + +Ouvrir le mode de recherche IA +--------------------------------- + +1. Ouvrez l'écran de recherche de |Fess| +2. Cliquez sur le lien « Recherche IA » (icône de robot) dans la barre de navigation en haut de + l'écran +3. L'écran du mode de recherche IA s'affiche + +.. note:: + Le lien « Recherche IA » ne s'affiche que si le mode de recherche IA est activé et qu'un + fournisseur de LLM est disponible. Si le lien ne s'affiche pas, consultez la section + `Foire aux questions`_. + +Saisir une question +----------------------- + +1. Saisissez votre question dans la zone de texte en bas de l'écran (4000 caractères maximum par + question) +2. Cliquez sur le bouton d'envoi (icône d'avion en papier) ou appuyez sur la touche Entrée +3. L'assistant IA commence à générer une réponse + +.. note:: + Pour saisir un retour à la ligne, appuyez sur Shift+Entrée au lieu de la touche Entrée. + +.. note:: + La génération de la réponse peut prendre de quelques secondes à une dizaine de secondes. Pendant + le traitement, l'étape en cours s'affiche sous forme de barre de progression (Analyse → + Recherche → Évaluation → Récupération → Réponse), accompagnée de messages tels que + « Réflexion en cours... », « Recherche de mots-clés... », « Vérification des résultats... », + « Récupération des documents... » ou « Génération de la réponse... ». Une fois la recherche + terminée, le nombre de documents trouvés s'affiche également. + +Consulter la réponse +------------------------ + +La réponse de l'assistant IA s'affiche. Elle comprend les informations suivantes : + +- **Corps de la réponse** : la réponse à la question, mise en forme au format Markdown +- **Sources** : la liste des liens vers les documents à l'origine de la réponse (liens numérotés ; + un clic ouvre le document original dans un nouvel onglet) + +Le corps de la réponse peut contenir des numéros de citation tels que ``[1]`` ou ``[2]``, qui +correspondent aux numéros de la liste des sources. Chaque réponse dispose d'un bouton de copie +permettant de copier son contenu dans le presse-papiers. + +.. note:: + L'IA n'utilise, comme base de sa réponse, que les documents parmi les résultats de recherche + jugés les plus pertinents. Le nombre de sources peut donc être inférieur au nombre de documents + trouvés par la recherche. + +Restreindre le périmètre de recherche +----------------------------------------- + +Selon le thème utilisé, le bouton « Filtre » situé en haut de l'écran permet de restreindre le +périmètre de recherche selon des critères tels que le label, le type de fichier, la date de mise à +jour ou la taille. Cela est utile lorsque vous souhaitez interroger l'IA sur un sous-ensemble précis +de documents. + +Poursuivre la conversation +------------------------------ + +Si vous avez des questions supplémentaires, vous pouvez continuer à poser des questions : + +- « Pouvez-vous m'en dire plus ? » +- « Existe-t-il d'autres méthodes ? » +- « Plus de détails sur XXX » + +L'assistant IA répond en tenant compte du contexte de la conversation précédente. + +Démarrer une nouvelle conversation +-------------------------------------- + +Pour poser une question sur un autre sujet, cliquez sur le bouton « Nouvelle conversation » +(icône +). Cela efface l'historique de la conversation en cours et permet de démarrer une nouvelle +conversation. + +Conseils pour poser des questions efficaces +============================================= + +Poser des questions précises +-------------------------------- + +Une question précise permet d'obtenir une réponse plus appropriée qu'une question vague. + +.. list-table:: + :header-rows: 1 + :widths: 50 50 + + * - Question vague + - Question précise + * - Comment faire pour configurer ? + - Comment modifier les paramètres de mémoire de Fess ? + * - J'ai une erreur + - J'obtiens l'erreur « index introuvable » lors d'une recherche + * - À propos du crawl + - Comment configurer les exclusions lors du crawl d'un site web ? + +Fournir du contexte +------------------------ + +Indiquer la situation ou l'objectif permet d'obtenir des réponses plus adaptées. + +Bons exemples : + +- « J'utilise Fess dans un environnement Docker. Comment changer l'emplacement de stockage des + logs ? » +- « C'est la première fois que j'utilise Fess. Que dois-je faire en premier ? » + +Poser des questions par étapes +----------------------------------- + +Les problèmes complexes deviennent plus faciles à traiter lorsqu'on les aborde par étapes. + +1. « Fess peut-il crawler des partages de fichiers ? » +2. « Comment se connecter via le protocole SMB ? » +3. « Que faire pour un dossier partagé nécessitant une authentification ? » + +Foire aux questions +====================== + +Q : Le mode de recherche IA ne s'affiche pas +------------------------------------------------ + +R : Il est possible que le mode de recherche IA ne soit pas activé. Le lien « Recherche IA » ne +s'affiche que si la fonctionnalité est activée (``rag.chat.enabled=true``) et qu'un fournisseur de +LLM (OpenAI, Gemini, Ollama, etc.) est configuré et disponible. Demandez à votre administrateur +système de vérifier que le mode de recherche IA est activé et que le fournisseur de LLM est +correctement configuré (pour plus de détails, consultez :doc:`../config/rag-chat`). + +Q : La réponse met du temps à s'afficher +-------------------------------------------- + +R : L'IA analyse la question, recherche puis évalue les documents avant de générer une réponse, ce +qui peut prendre de quelques secondes à une dizaine de secondes. Pendant le traitement, l'étape en +cours s'affiche (« Réflexion en cours... », « Recherche de mots-clés... », +« Vérification des résultats... », « Récupération des documents... », +« Génération de la réponse... »). + +Q : Les sources semblent incorrectes +----------------------------------------- + +R : Cliquez sur les liens des sources pour vérifier le document original. L'IA génère sa réponse à +partir des résultats de recherche, mais son interprétation peut parfois être erronée. Pour toute +information importante, il est recommandé de toujours la vérifier dans le document original. + +Q : La conversation précédente semble avoir été oubliée +------------------------------------------------------------ + +R : Il est possible que la session de conversation ait expiré. Après une certaine durée +d'inactivité (30 minutes par défaut), l'historique de la conversation est effacé. De plus, +l'historique de conversation est conservé temporairement en mémoire sur le serveur : il est donc +également perdu en cas de redémarrage du serveur. Dans ce cas, démarrez une nouvelle conversation. + +.. note:: + La « session » évoquée ici est la session de conversation du mode de recherche IA ; elle est + distincte de la session de connexion à |Fess|. + +Q : Je n'obtiens pas de réponse à une question précise +------------------------------------------------------------ + +R : Plusieurs causes sont possibles : + +- les documents recherchés ne contiennent pas d'information pertinente +- la question est trop vague pour permettre une recherche appropriée +- la limite de débit a été atteinte (dépassement du nombre maximal de requêtes par minute ou du + nombre maximal d'exécutions simultanées) + +Reformulez votre question ou patientez un moment avant de réessayer. + +Q : Y a-t-il une limite au nombre de caractères que je peux saisir ? +-------------------------------------------------------------------------- + +R : Oui, 4000 caractères maximum par question. Un compteur de caractères s'affiche sous la zone de +texte et passe en alerte lorsque la limite approche. Pour une question longue, concentrez-vous sur +l'essentiel afin de la raccourcir. + +Q : Puis-je poser des questions dans une langue autre que le japonais ? +-------------------------------------------------------------------------- + +R : Oui, dans la plupart des cas, vous pouvez poser vos questions en anglais ou dans d'autres +langues. L'IA tente de répondre dans la même langue que celle du navigateur ou de l'affichage de +l'écran, dans la mesure du possible. Il s'agit toutefois d'un traitement au mieux (best effort) : +selon les cas, la réponse peut ne pas être dans la langue attendue. + +Remarques importantes +========================= + +À propos des réponses de l'IA +---------------------------------- + +- les réponses de l'IA sont générées à partir des résultats de recherche +- l'exactitude des réponses n'est pas garantie +- pour toute décision importante, vérifiez toujours le document original (la source) +- pour les informations les plus récentes, consultez la documentation officielle + +À propos de la confidentialité +------------------------------------ + +- les questions saisies sont utilisées pour la recherche et pour le traitement par l'IA du + fournisseur de LLM configuré +- si un service LLM externe est configuré (OpenAI, Gemini, etc.), le contenu des questions et des + résultats de recherche est transmis à ce service ; si vous souhaitez un traitement strictement + interne, demandez à votre administrateur d'utiliser un fournisseur fonctionnant localement + (Ollama, par exemple) +- l'historique de conversation est conservé temporairement en mémoire sur le serveur ; il est + supprimé lors de l'expiration de la session, de l'exécution de « Nouvelle conversation » ou d'un + redémarrage du serveur +- comme pour la recherche classique, le contrôle d'accès par rôle (permission) et par label + s'applique : les documents non consultables par l'utilisateur ne peuvent pas servir de base à la + réponse +- selon la configuration du système, des journaux peuvent être enregistrés + +Informations de référence +=============================== + +- :doc:`../config/rag-chat` - Configuration du mode de recherche IA (pour les administrateurs) +- :doc:`../config/llm-overview` - Configuration des fournisseurs de LLM +- :doc:`../api/api-chat` - Chat API (utilisation programmatique) +- :doc:`search-and` - Utilisation de la recherche AND +- :doc:`search-not` - Utilisation de la recherche NOT +- :doc:`search-field` - Utilisation de la recherche par champ +- :doc:`advanced-search` - Fonctionnalités de recherche avancée diff --git a/fr/15.10/user/index.rst b/fr/15.10/user/index.rst new file mode 100644 index 000000000..25176bbbe --- /dev/null +++ b/fr/15.10/user/index.rst @@ -0,0 +1,29 @@ +Guide utilisateur |Fess| +======================== + +Comment écrire des requêtes dans |Fess| : AND, OR et NOT, recherche +par champ et par étiquette, tri, jokers, plages, boost, recherche +floue, recherche de proximité et recherche géographique. + +.. toctree:: + :maxdepth: 2 + + intro + search-and + search-or + search-not + search-bangs + search-label + search-field + search-sort + search-wildcard + search-range + search-boost + search-fuzzy + search-proximity + search-geo + search-additional + role-search + special-char + advanced-search + chat-search diff --git a/fr/15.10/user/intro.rst b/fr/15.10/user/intro.rst new file mode 100644 index 000000000..00b775b2d --- /dev/null +++ b/fr/15.10/user/intro.rst @@ -0,0 +1,49 @@ +=========================== +Introduction à la recherche +=========================== + +Public visé +=========== + +|Fess| est un serveur de recherche d'entreprise permettant d'effectuer une recherche en texte intégral sur des documents provenant de sites Web, de fichiers, de bases de données, etc. + +Ce document est destiné aux utilisateurs de |Fess|. + +Avant de commencer +================== + +Ce document explique comment effectuer une recherche avec |Fess|. En plus de la recherche par mots-clés de base, il explique aussi comment affiner votre recherche grâce à l'écran de recherche avancée et au mode de recherche IA, qui permet de rechercher des informations sous forme de conversation naturelle. Des connaissances de base en informatique sont requises. + +Accès en ligne +============== + +Pour les téléchargements, les services professionnels, le support et autres informations destinées aux développeurs, veuillez consulter : + +- Site du projet : https://fess.codelibs.org/ + +Coordonnées du support technique +================================= + +Si vous avez des questions techniques concernant ce produit et que vous ne trouvez pas de solution dans la documentation, veuillez consulter : + +- Issues : + `https://github.com/codelibs/fess/issues `__ + +Support commercial +------------------ + +Si vous avez besoin d'un support commercial pour ce produit, y compris l'assistance technique et la maintenance, veuillez contacter `N2SM, Inc. `__. + +Référence aux sites Web tiers +============================== + +Le projet |Fess| n'est pas responsable de la validité des sites Web tiers mentionnés dans ce document. Le projet |Fess| n'assume aucune garantie, responsabilité ou obligation concernant le contenu, les publicités, les produits, les services ou autres documents disponibles sur ou via ces sites ou ressources. Le projet |Fess| ne sera pas responsable des dommages ou préjudices causés par, ou prétendument causés par, l'utilisation ou la confiance accordée à tout contenu, publicité, produit, service ou autre document disponible sur ou via ces sites ou ressources. + +Comment envoyer des commentaires et suggestions +================================================ + +Le projet |Fess| s'efforce d'améliorer ce document et accueille avec plaisir les commentaires et suggestions des lecteurs. + +- Issues : + `https://github.com/codelibs/fess-docs/issues `__ + diff --git a/fr/15.10/user/role-search.rst b/fr/15.10/user/role-search.rst new file mode 100644 index 000000000..b48031f56 --- /dev/null +++ b/fr/15.10/user/role-search.rst @@ -0,0 +1,58 @@ +================== +Recherche par rôle +================== + +|Fess| propose une fonctionnalité de gestion des utilisateurs : les utilisateurs connectés peuvent effectuer des recherches en fonction des rôles auxquels ils appartiennent. Les utilisateurs gérés par |Fess| peuvent, après connexion, utiliser la recherche par rôle et modifier leur mot de passe. + +La recherche par rôle compare les permissions définies sur le contenu (rôle, groupe, utilisateur) avec les permissions détenues par l'utilisateur qui effectue la recherche, et n'affiche dans les résultats que le contenu dont l'accès est autorisé. Pour la configuration de la recherche basée sur les rôles, notamment la création de rôles et d'utilisateurs, ainsi que l'attribution de permissions au contenu, reportez-vous à :doc:`../config/security-role`. + + +Méthode de recherche +-------------------- + +Si des rôles sont configurés et que le contenu a été exploré et indexé dans cet état, les résultats de recherche peuvent être affichés uniquement aux utilisateurs possédant ce rôle. +Si l'utilisateur est connecté, la recherche est effectuée en fonction des rôles et des groupes auxquels il appartient. +S'il n'est pas connecté, la recherche est effectuée en tant qu'utilisateur guest, et seul le contenu publié pour guest est affiché. + +.. note:: + La recherche d'un utilisateur connecté est effectuée uniquement avec les permissions de cet utilisateur et des rôles et groupes auxquels il appartient ; le contenu publié pour guest (``{role}guest``) n'est pas inclus. Ainsi, un contenu publié uniquement pour guest est affiché aux visiteurs non connectés, mais pas aux utilisateurs connectés (y compris ceux qui n'ont ni rôle ni groupe). Pour qu'un contenu soit également visible des utilisateurs connectés, définissez dans les permissions de la configuration d'exploration, en plus de ``{role}guest``, le rôle que possèdent ces utilisateurs (pour l'afficher à tous, un rôle attribué à tous les utilisateurs). + +Connexion +--------- + +En cliquant sur le lien Connexion affiché en haut de l'écran de recherche, l'écran de connexion s'affiche. Après avoir saisi le nom d'utilisateur et le mot de passe puis vous être connecté, vous revenez à l'écran de recherche, et les recherches suivantes sont effectuées en fonction des rôles auxquels appartient cet utilisateur. + +.. note:: + En cas d'intégration avec l'authentification unique ou LDAP, la connexion s'effectue selon la méthode d'authentification correspondante. De plus, l'affichage ou non du lien de connexion peut être modifié via la configuration. + +Modification du mot de passe +----------------------------- + +Après la connexion, cliquez sur le nom d'utilisateur affiché en haut de l'écran de recherche pour afficher le menu. + +|image0| + +En cliquant sur « Changer le mot de passe » dans le menu, l'écran de modification du mot de passe s'affiche. + +|image1| + +Saisissez le mot de passe actuel dans le champ « Mot de passe actuel », le nouveau mot de passe dans le champ « Nouveau mot de passe », confirmez-le dans le champ « Confirmer le nouveau mot de passe », puis cliquez sur le bouton « Mettre à jour » pour mettre à jour le mot de passe. +La modification du mot de passe ferme la session : reconnectez-vous avec le nouveau mot de passe. +Cet écran est la page ``/profile`` du thème de l'écran de recherche, et le mot de passe est modifié via ``POST /api/v2/auth/password`` (voir :doc:`../api/api-auth`). + +.. note:: + Le menu « Changer le mot de passe » ne s'affiche que pour les utilisateurs gérés par |Fess| (ainsi que pour les utilisateurs LDAP autorisés à modifier leur mot de passe). Il ne s'affiche pas pour les utilisateurs authentifiés via l'authentification unique. + Une politique de mot de passe (longueur, types de caractères autorisés, etc.) peut s'appliquer au nouveau mot de passe. + +Déconnexion +----------- + +Lorsque vous êtes connecté, cliquez sur le nom d'utilisateur affiché en haut de l'écran de recherche, puis sélectionnez « Déconnexion » dans le menu pour vous déconnecter. +Pour les utilisateurs disposant des droits d'administrateur, il est également possible de sélectionner « Administration » dans le même menu pour accéder à l'écran d'administration. + + + +.. |image0| image:: ../../../resources/images/en/15.10/user/role-search-1.png +.. pdf :width: 200 px +.. |image1| image:: ../../../resources/images/en/15.10/user/role-search-2.png +.. pdf :width: 300 px diff --git a/fr/15.10/user/search-additional.rst b/fr/15.10/user/search-additional.rst new file mode 100644 index 000000000..eaf3bf11f --- /dev/null +++ b/fr/15.10/user/search-additional.rst @@ -0,0 +1,30 @@ +============================= +Critères de recherche masqués +============================= + +Le paramètre ``ex_q`` permet de transmettre un critère de recherche spécifique sans afficher son texte à l'écran. Les critères spécifiés dans ``ex_q`` ne s'affichent pas dans le champ de recherche et sont conservés même lorsque l'écran est actualisé lors de la pagination ou du filtrage par facettes. + +Dans ``ex_q``, vous pouvez utiliser la même syntaxe de requête que pour le terme de recherche standard (``q``) : le format ``field:value``, les phrases, les plages, des opérateurs tels que ``OR``, etc. Le critère spécifié est combiné par défaut avec le critère de ``q`` au moyen de AND lors de l'exécution de la recherche. Autrement dit, les documents ne correspondant pas au critère de ``ex_q`` sont exclus des résultats de recherche. + +Utilisation +----------- + +Lors de l'exécution d'une recherche (par exemple, depuis un formulaire de recherche), ajoutez la valeur de ``ex_q`` sous forme de champ de formulaire masqué ou de paramètre de requête dans l'URL, puis exécutez la recherche. Vous pouvez ainsi effectuer la recherche sans afficher le critère à l'écran. + +Vous pouvez spécifier ``ex_q`` plusieurs fois. Comme dans l'exemple ci-dessous, transmettre plusieurs valeurs ``ex_q`` ajoute chacune d'elles comme critère de recherche (les valeurs vides ou en double sont ignorées). + +.. code-block:: none + + /search?q=keyword&ex_q=label:manual&ex_q=filetype:pdf + +Conservation lors de la pagination +----------------------------------- + +Fess ajoute automatiquement la valeur de ``ex_q`` aux liens de pagination (page suivante, page précédente, etc.) et aux liens de filtrage par facettes. Le critère ``ex_q`` est donc conservé même lorsque l'écran est actualisé par ces opérations. + +En revanche, si vous saisissez un terme dans le champ de recherche standard (la zone de recherche) et relancez la recherche, ``ex_q`` n'est pas conservé. Si vous souhaitez que le critère soit également conservé via la zone de recherche, prévoyez un champ masqué ``ex_q`` dans votre propre formulaire de recherche et envoyez ``ex_q`` à chaque recherche. + +.. note:: + + * Si la longueur d'une valeur ``ex_q`` dépasse ``query.max.length`` (valeur par défaut : 1000 caractères), cette valeur est ignorée sans provoquer d'erreur. + * ``ex_q`` peut être utilisé non seulement pour la recherche depuis l'écran web, mais aussi avec l'API de recherche (``/api/v2``). Dans l'API, le nombre maximal d'éléments ``ex_q`` par requête (``api.v2.param.max.array.size``, valeur par défaut : 100) et la longueur maximale de chaque élément (``api.v2.param.max.length``, valeur par défaut : 1000 caractères) s'appliquent. diff --git a/fr/15.10/user/search-and.rst b/fr/15.10/user/search-and.rst new file mode 100644 index 000000000..f7b12b3a5 --- /dev/null +++ b/fr/15.10/user/search-and.rst @@ -0,0 +1,46 @@ +============== +Recherche AND +============== + +La recherche AND est utilisée pour rechercher des documents contenant tous les termes de recherche spécifiés. Si vous saisissez plusieurs mots séparés par des espaces dans le champ de recherche, la recherche sera par défaut de type AND ; vous pouvez donc omettre AND tout en obtenant le même résultat. + +Utilisation +----------- + +Pour utiliser la recherche AND, saisissez AND entre les termes de recherche. AND +doit être écrit en majuscules et nécessite des espaces avant et après. AND +peut également être omis. + +Par exemple, pour rechercher des documents contenant à la fois « terme1 » et « terme2 », saisissez ce qui suit dans le formulaire de recherche : + +:: + + terme1 AND terme2 + +Il est également possible d'omettre AND et d'obtenir le même résultat en saisissant simplement : + +:: + + terme1 terme2 + +Il est également possible de connecter trois termes de recherche ou plus avec AND. + +:: + + terme1 AND terme2 AND terme3 + +.. note:: + + AND doit être écrit en majuscules. S'il est écrit en minuscules, comme ``and``, il n'est pas traité comme un opérateur, mais comme un terme de recherche ordinaire « and ». ``&&`` peut également être utilisé avec la même signification que AND. + +En utilisant les parenthèses ``( )``, vous pouvez combiner la recherche AND avec d'autres conditions de recherche. Par exemple, pour rechercher des documents contenant « terme1 », et contenant également soit « terme2 » soit « terme3 », saisissez ce qui suit : + +:: + + terme1 AND (terme2 OR terme3) + +Il est également possible d'effectuer une recherche AND en spécifiant un champ. Dans l'exemple suivant, la recherche porte sur les documents contenant « terme1 » dans le champ title, et « terme2 » dans le champ content. + +:: + + title:terme1 AND content:terme2 diff --git a/fr/15.10/user/search-bangs.rst b/fr/15.10/user/search-bangs.rst new file mode 100644 index 000000000..a414fabe4 --- /dev/null +++ b/fr/15.10/user/search-bangs.rst @@ -0,0 +1,80 @@ +================================================= +Recherche par bang (rechercher sur un autre site) +================================================= + +Un bang envoie une recherche vers un autre site au lieu de rechercher dans |Fess|. Il fonctionne comme les bangs de DuckDuckGo : ajoutez ``!`` et un court mot déclencheur à la requête, et |Fess| envoie le reste de la requête au site que représente ce mot déclencheur. + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Requête + - Destination + * - ``airplane !g`` + - Google, recherche de ``airplane`` + * - ``!w Ohm's law`` + - Wikipedia, recherche de ``Ohm's law`` + * - ``!g`` + - La page d'accueil de Google + * - ``airplane !unknown`` + - |Fess|, comme une recherche normale (``!`` signifie NOT, voir :doc:`search-not`) + +Les bangs sont fournis par le plugin ``fess-webapp-bangs``, qui nécessite |Fess| 15.10 ou une version ultérieure. Installez-le depuis [Système > Plugin] dans la console d'administration ou avec ``bin/fess-setup install plugin fess-webapp-bangs`` (voir :doc:`../admin/plugin-guide`), puis redémarrez |Fess|. + +Comment un bang est reconnu +=========================== + +- Un bang est ``!`` suivi d'un mot déclencheur, écrit comme un mot distinct. Le mot déclencheur ne distingue pas les majuscules des minuscules. +- Le bang est retiré de la requête, et le reste de la requête est envoyé à l'URL du bang. +- Lorsqu'une requête contient plusieurs bangs définis, seul le premier compte. +- Un mot déclencheur qui n'est pas défini n'est pas un bang. ``!unknown`` est recherché comme d'habitude et exclut le mot ``unknown``. +- ``-g`` et ``NOT g`` continuent d'exclure le mot ``g``. Seul ``!g`` est un bang. + +La page de recherche et ``/api/v2/search`` suivent la redirection : l'API renvoie ``redirect_url`` (voir :doc:`../api/api-search`), et le thème ``bootstrap`` fourni avec |Fess| navigue vers cette URL. Les autres thèmes doivent gérer ce cas de la même manière. + +Les appelants qui ne peuvent pas rediriger, comme le chat, MCP, les API JSON v1 et classique et la recherche de la console d'administration, n'envoient pas la recherche vers un autre site. Ils retirent le bang et recherchent le reste de la requête. + +Définir des bangs +================= + +Les bangs sont définis par la propriété système ``bangs.definitions``. Définissez-la dans ``app/WEB-INF/conf/system.properties`` ou transmettez-la sous la forme ``-Dfess.system.bangs.definitions=...``. Une modification de ``system.properties`` est prise en compte sans redémarrer |Fess|. + +La valeur est une liste d'entrées ``mot_déclencheur=URL`` séparées par des espaces. Dans l'URL, ``{query}`` est remplacé par le reste de la requête encodé en URL : + +:: + + bangs.definitions=g=https://www.google.com/search?q={query} w=https://en.wikipedia.org/wiki/Special:Search?search={query} + +- Un mot déclencheur ne peut contenir ni espace, ni ``(``, ``)``, ``!``, ``"``, ``=`` ou ``:``. +- Seules les URL absolues ``http`` ou ``https`` sont acceptées. +- Une entrée qui ne respecte pas ces règles n'est pas utilisée. Un avertissement est écrit dans le journal de |Fess|, et les autres entrées restent en vigueur. +- Si le même mot déclencheur est défini deux fois, la première définition est utilisée. +- Une valeur vide désactive tous les bangs. + +Lorsque ``bangs.definitions`` n'est pas définie, les cinq bangs suivants sont disponibles : + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Mot déclencheur + - Site + * - ``g`` + - Google + * - ``b`` + - Bing + * - ``ddg`` + - DuckDuckGo + * - ``w`` + - Wikipedia (anglais) + * - ``gh`` + - GitHub + +Définir ``bangs.definitions`` remplace cette liste. Pour conserver les bangs par défaut et en ajouter un, écrivez toutes les entrées dont vous avez besoin. + +Voir aussi +========== + +- :doc:`search-not` - Recherche NOT +- :doc:`special-char` - Caractères spéciaux et échappement +- :doc:`../api/api-search` - API de recherche diff --git a/fr/15.10/user/search-boost.rst b/fr/15.10/user/search-boost.rst new file mode 100644 index 000000000..ee0750236 --- /dev/null +++ b/fr/15.10/user/search-boost.rst @@ -0,0 +1,46 @@ +======================= +Recherche avec boost +======================= + +Recherche avec boost (recherche pondérée) +========================================== + +La recherche avec boost est utilisée lorsque vous souhaitez donner la priorité à un terme de recherche spécifique parmi les termes de recherche. L'utilisation de la recherche avec boost permet d'effectuer des recherches en fonction de l'importance des termes de recherche. + +Utilisation +----------- + +Pour utiliser la recherche avec boost, spécifiez une valeur de boost (valeur de pondération) au format « ^valeur_boost » juste après le terme de recherche. N'insérez pas d'espace entre le terme de recherche et la valeur de boost. + +Par exemple, lors de la recherche de « pomme orange », si vous souhaitez donner la priorité à « pomme », saisissez ce qui suit dans le formulaire de recherche : + +:: + + pomme^100 orange + +Dans cet exemple, la valeur de boost s'applique uniquement à « pomme », et non à « orange ». + +Valeur de boost +----------------- + +La valeur de boost est un nombre. Vous pouvez spécifier non seulement des entiers, mais aussi des valeurs décimales telles que ``2.5``. + +- Si vous spécifiez une valeur supérieure à 1, le poids de ce terme de recherche augmente. +- Si vous spécifiez une valeur supérieure à 0 et inférieure à 1 (par exemple, ``0.5``), le poids de ce terme de recherche diminue. + +La valeur de boost ne détermine pas de manière absolue le score des résultats de recherche ; elle ajuste la pondération relative par rapport aux autres termes de recherche. + +Combinaison avec d'autres syntaxes de recherche +--------------------------------------------------- + +La recherche avec boost peut être combinée avec d'autres syntaxes de recherche. Par exemple, il est également possible d'ajouter une valeur de boost à un terme de recherche associé à un champ spécifique. + +:: + + title:pomme^100 orange + +Dans cet exemple, l'opérateur par défaut (AND) s'applique lorsque plusieurs termes de recherche sont placés l'un après l'autre : seuls les documents dont le champ ``title`` contient « pomme » et qui contiennent également « orange » sont donc retournés. Pour donner la priorité aux documents contenant « pomme » tout en conservant dans les résultats ceux qui n'en contiennent pas, reliez les termes par OR. + +:: + + title:pomme^100 OR orange diff --git a/fr/15.10/user/search-field.rst b/fr/15.10/user/search-field.rst new file mode 100644 index 000000000..cd5ad2275 --- /dev/null +++ b/fr/15.10/user/search-field.rst @@ -0,0 +1,137 @@ +===================================================== +Recherche par champ (limiter au titre, à l'URL, etc.) +===================================================== + +Recherche par champ spécifique +=============================== + +La recherche par champ (recherche avec champ spécifié) permet de limiter la recherche à un champ particulier, par exemple uniquement le titre ou uniquement l'URL. + +Les résultats de l'exploration par |Fess| sont enregistrés pour chaque champ tel que le titre ou le contenu. Vous pouvez effectuer une recherche en spécifiant ces champs. En spécifiant un champ, vous pouvez définir des critères de recherche détaillés tels que le type de document ou la taille. + +Champs disponibles +------------------ + +Par défaut, vous pouvez effectuer une recherche en spécifiant les champs suivants. + +.. list-table:: + :header-rows: 1 + + * - Nom du champ + - Description + - Type de données + * - url + - URL explorée + - Mot-clé + * - host + - Nom d'hôte contenu dans l'URL explorée + - Mot-clé + * - site + - Chaîne obtenue en retirant de l'URL le schéma et la chaîne de requête (nom d'hôte et chemin). La recherche s'effectue par correspondance de préfixe + - Mot-clé + * - title + - Titre + - Texte + * - content + - Contenu + - Texte + * - content_length + - Taille du document (en octets) + - Numérique + * - last_modified + - Date de dernière modification du document + - Date + * - timestamp + - Date et heure d'indexation du document (heure d'exécution du crawl si la date de dernière modification n'est pas disponible) + - Date + * - mimetype + - Type MIME du document (exemple : ``text/html``) + - Mot-clé + * - filetype + - Type de fichier déterminé à partir du type MIME (exemple : ``html``, ``word``, ``pdf``. ``others`` si aucun ne correspond) + - Mot-clé + * - filename + - Nom de fichier situé à la fin du chemin de l'URL + - Mot-clé + * - label + - Valeur de l'étiquette attribuée au document + - Mot-clé + * - lang + - Code de langue du document (exemple : ``ja``, ``en``) + - Mot-clé + * - anchor + - URL de destination des liens extraits d'une page HTML (crawl Web uniquement) + - Mot-clé + * - click_count + - Nombre de clics sur le document + - Numérique + * - favorite_count + - Nombre de fois où le document a été ajouté aux favoris + - Numérique + * - owner + - Nom de compte du propriétaire du fichier + - Mot-clé + * - last_modifier + - Dernier modificateur du fichier + - Mot-clé + +Table : Liste des champs disponibles + +« Type de données » indique la différence de mode de recherche propre à chaque champ. + +* Mot-clé : recherche par correspondance exacte sur la valeur entière. Peut être combinée avec une recherche par caractères génériques ou par préfixe. +* Texte : recherche en texte intégral sur les termes obtenus par découpage (notamment par analyse morphologique). C'est le cas des champs title et content. +* Numérique / Date : vous pouvez utiliser la :doc:`Recherche par plage `. + +Si aucun champ n'est spécifié, la recherche porte sur les champs title et content. Selon la configuration, il est également possible d'ajouter des champs supplémentaires à cibler pour la recherche. + +.. note:: + Selon la cible du crawl, certains champs peuvent ne pas être renseignés. Par exemple, anchor n'est enregistré que lors d'un crawl Web. lang provient de l'attribut de langue du document HTML ou de la langue détectée dans le texte du document ; il n'est pas enregistré si aucune langue ne peut être détectée ou si la langue détectée ne figure pas dans ``supported.languages``. Par ailleurs, des champs tels que segment (identifiant de session représentant une exécution de crawl) ou doc_id (identifiant interne attribué par le système) peuvent également être spécifiés, mais ils ne sont pas utilisés dans le cadre d'une recherche normale. + +owner et last_modifier sont enregistrés lors du crawl de serveurs de fichiers et autres. owner +contient le nom de compte du propriétaire du fichier obtenu par les crawls SMB, système de fichiers +et FTP (une valeur comme ``DOMAIN\alice`` devient ``alice``). last_modifier contient le dernier +auteur extrait d'un document Office ou similaire, à défaut le propriétaire. Aucun owner n'est +enregistré pour le HTML issu d'un crawl Web. Recherchez par exemple avec ``owner:alice`` ou +``last_modifier:"Taro Yamada"``. Dans le thème fourni, la recherche avancée permet d'indiquer le +propriétaire et le dernier modificateur. Les administrateurs peuvent activer ou désactiver ces +champs avec ``crawler.document.file.owner.enabled`` et +``crawler.document.file.last.modifier.enabled`` (``true`` par défaut tous les deux). + +Lorsque des fichiers HTML sont ciblés par la recherche, le contenu de la balise title est enregistré dans le champ title, et le texte situé sous la balise body est enregistré dans le champ content. + +Utilisation +----------- + +Pour effectuer une recherche par champ spécifique, saisissez dans le formulaire de recherche au format « nom_champ:terme_recherche », en séparant le nom du champ et le terme de recherche par deux-points (:). + +Pour effectuer une recherche avec fess comme terme de recherche dans le champ title, saisissez ce qui suit : + +:: + + title:fess + +Cette recherche affichera les documents dont le champ title contient fess dans les résultats de recherche. + +Pour effectuer une recherche sur le champ url, saisissez ce qui suit : + +:: + + url:https\:\/\/fess.codelibs.org\/ja\/15.10\/* + url:"https://fess.codelibs.org/ja/15.10/*" + +La première méthode permet d'utiliser des requêtes avec caractères génériques, vous pouvez donc également écrire par exemple ``url:*\/\/fess.codelibs.org\/*``. Les caractères « : » et « / » contenus dans l'URL sont des caractères spéciaux de la syntaxe de requête ; veuillez les échapper avec ``\`` (voir :doc:`special-char`). La seconde méthode ne permet pas d'utiliser des requêtes avec caractères génériques, mais un terme se terminant par ``*`` est traité comme une recherche par préfixe (correspondance en début de chaîne). + +.. tip:: + Si vous souhaitez rechercher une partie de l'URL, vous pouvez utiliser ``inurl:`` pour effectuer une recherche par correspondance partielle sur l'URL. Par exemple, ``inurl:15.10`` recherche les documents dont l'URL contient ``15.10``. + +Pour les champs dont la valeur contient « / », comme mimetype, filetype ou site, entourez la valeur de guillemets comme dans ``mimetype:"text/html"``, ou échappez-la comme dans ``mimetype:text\/html``. + +Pour la syntaxe de recherche associée, consultez également :doc:`Recherche avec caractères génériques `, :doc:`Recherche par plage `, :doc:`Recherche avec tri ` et :doc:`Caractères spéciaux `. + +Voir aussi +========== + +- :doc:`search-range` +- :doc:`search-wildcard` +- :doc:`special-char` diff --git a/fr/15.10/user/search-fuzzy.rst b/fr/15.10/user/search-fuzzy.rst new file mode 100644 index 000000000..ecb4269bf --- /dev/null +++ b/fr/15.10/user/search-fuzzy.rst @@ -0,0 +1,66 @@ +================ +Recherche floue +================ + +Recherche floue (recherche approximative) +========================================== + +Lorsque vous souhaitez également rechercher des mots qui ne correspondent pas exactement au terme de recherche, vous pouvez utiliser la recherche floue (recherche approximative). La recherche floue est une méthode qui consiste à considérer un mot comme correspondant dès lors que la différence (distance d'édition) entre le terme de recherche et le mot enregistré dans l'index reste dans une plage donnée. La distance d'édition désigne le nombre minimal d'opérations d'insertion, de suppression ou de substitution de caractères nécessaires pour transformer un mot en un autre. Par défaut, |Fess| utilise la distance de Damerau-Levenshtein (optimal string alignment), qui, en plus de ces opérations, compte également l'interversion de deux caractères adjacents comme une seule différence. + +Utilisation +----------- + +Ajoutez « ~ » après le terme de recherche auquel vous souhaitez appliquer la recherche floue. + +Par exemple, pour effectuer une recherche floue sur le mot « fess », saisissez ce qui suit dans le formulaire de recherche pour rechercher des documents contenant des mots proches de « fess » (tels que « fes ») : + +:: + + fess~ + +En ajoutant un chiffre après « ~ », vous pouvez indiquer la distance d'édition tolérée (le nombre de différences de caractères autorisées). Les valeurs possibles sont les entiers 0, 1 ou 2. + +:: + + fess~1 + +Dans l'exemple ci-dessus, la recherche porte sur les mots dont la distance d'édition avec « fess » est inférieure ou égale à 1. + +Si vous omettez le chiffre et n'indiquez que « ~ », la distance d'édition est considérée comme égale à 2. La valeur maximale de la distance d'édition est 2 ; si vous indiquez une valeur de 3 ou plus, elle est également ramenée à 2. + +Il est également possible d'effectuer une recherche floue en spécifiant un champ. Dans l'exemple suivant, la recherche porte sur les documents dont le champ title contient un mot proche de « fess ». + +:: + + title:fess~ + +Si aucun champ n'est spécifié, la recherche floue s'applique aux champs title et content. + +Conditions d'utilisation +------------------------ + +Lors de l'utilisation de la recherche floue, tenez compte des points suivants : + +* La recherche floue s'applique au niveau du mot. Elle ne peut pas être appliquée à une phrase entourée de guillemets. Notez que le chiffre placé après une phrase (par exemple ``"Fess Search"~2``) ne correspond pas à une recherche floue, mais à une :doc:`recherche de proximité ` indiquant la distance entre les mots. +* La recherche floue porte sur les mots enregistrés dans l'index, et le terme de recherche n'est pas réanalysé. Par conséquent, elle peut ne pas fonctionner comme prévu pour des textes tels que le japonais, qui sont tokenisés par bi-gramme ou par analyse morphologique. La recherche floue est principalement efficace pour les mots alphanumériques. +* Le terme d'une recherche floue est comparé tel quel pour le calcul de la distance d'édition, majuscules et minuscules comprises. Les mots alphabétiques enregistrés dans l'index sont généralement convertis en minuscules ; utilisez donc des minuscules dans le terme de recherche. Par exemple, ``Fess~1`` épuise déjà la distance d'édition 1 avec la seule majuscule initiale ``F`` et ne donne donc pas le même résultat que ``fess~1``. De même, ``Fess~0`` ne correspond à rien, car l'index ne contient aucun mot correspondant au mot en majuscule ``Fess`` (le ``fess~0`` en minuscules est une correspondance exacte). +* Si vous ajoutez « ~ » (distance d'édition 2) à un mot très court, comme ceux de 1 à 2 caractères, il correspond aussi à des mots dont seul un nombre de caractères proche de la longueur du mot a été remplacé. Par exemple, ``ab~`` correspond à ``ab`` et ``ac``, mais aussi à ``xy``, dont les deux caractères sont différents. Cela multiplie les résultats non voulus ; pour les mots courts, indiquez donc une petite distance d'édition, comme ``ab~1``. + +.. note:: + + Le comportement de la recherche floue peut être ajusté dans ``fess_config.properties``. + + * ``query.fuzzy.prefix_length`` (valeur par défaut : ``0``) : nombre de caractères à faire correspondre exactement depuis le début du mot. Plus cette valeur est élevée, plus la marge d'erreur tolérée est réduite. + * ``query.fuzzy.expansions`` (valeur par défaut : ``50``) : nombre maximal de mots développés comme candidats de correspondance. + * ``query.fuzzy.transpositions`` (valeur par défaut : ``true``) : indique si l'interversion de deux caractères adjacents doit être comptée comme une seule modification. Si ``true``, il s'agit de la distance de Damerau-Levenshtein ; si ``false``, il s'agit de la distance de Levenshtein classique. + +.. note:: + + Même dans une recherche normale sans « ~ », |Fess| ajoute automatiquement, à titre d'appoint, une légère correspondance floue pondérée (``query.boost.fuzzy.*``) pour les termes de recherche d'une longueur supérieure ou égale à un certain seuil (4 caractères par défaut), afin d'améliorer la pertinence. Il s'agit d'une fonctionnalité destinée principalement à ajuster le classement des résultats de recherche, distincte du mécanisme de recherche floue via « ~ ». Toutefois, cette correspondance d'appoint est elle aussi incluse dans les résultats : des documents ne contenant pas le terme de recherche lui-même, mais uniquement un mot qui en diffère d'un caractère, peuvent donc s'ajouter aux résultats (les documents contenant le terme lui-même sont mieux classés). Pour supprimer ce comportement, indiquez une valeur négative (par exemple ``-1``) pour ``query.boost.fuzzy.min.length``. + +Voir aussi +========== + +- :doc:`search-wildcard` +- :doc:`search-proximity` +- :doc:`special-char` diff --git a/fr/15.10/user/search-geo.rst b/fr/15.10/user/search-geo.rst new file mode 100644 index 000000000..57a169e1c --- /dev/null +++ b/fr/15.10/user/search-geo.rst @@ -0,0 +1,56 @@ +========================== +Recherche géolocalisée +========================== + +En ajoutant des informations de géolocalisation (latitude et longitude) à chaque document lors de la génération de l'index, il devient possible de filtrer les résultats de recherche en fonction de la distance par rapport à un point spécifié au moment de la recherche. + +Aperçu +---------- + +La recherche géolocalisée n'inclut dans les résultats de recherche que les documents situés dans un rayon autour d'un point spécifié (latitude et longitude). Ce filtrage est appliqué sous forme de filtre utilisant la requête geo_distance d'OpenSearch, et n'a donc aucun impact sur le score (pertinence). Par ailleurs, le tri par distance n'est pas pris en charge. + +Le champ dans lequel sont stockées les informations de géolocalisation doit être défini comme étant de type ``geo_point`` dans le mapping d'OpenSearch. Par défaut, le champ ``location`` est fourni en tant que type ``geo_point``. Cependant, comme aucun traitement n'est fourni par défaut pour stocker une valeur dans le champ ``location``, l'utilisateur doit lui-même y stocker les informations de géolocalisation, par exemple via le mapping de champs du crawl de source de données, un script, ou une API d'enregistrement de documents dans le moteur de recherche. + +Utilisation +-------------- + +La recherche géolocalisée se spécifie en ajoutant les paramètres suivants à la requête de recherche. Par défaut, elle est disponible pour le champ ``location``. + +.. list-table:: + :header-rows: 1 + + * - Paramètre + - Description + * - ``geo..point`` + - Spécifie la latitude et la longitude du point central au format ``latitude,longitude``. La valeur est exprimée en degrés décimaux (type ``Double``), sous forme de deux nombres séparés par une virgule. Exemple : ``35.681236,139.767125`` + * - ``geo..distance`` + - Spécifie la distance (rayon) à partir du point central. Exemple : ``10km`` + +Table : Paramètres de requête + +```` désigne le nom du champ dans lequel sont stockées les informations de géolocalisation. Seuls les champs enregistrés dans ``query.geo.fields`` peuvent être spécifiés ; par défaut, il s'agit de ``location``. Pour utiliser un autre champ, mappez-le en tant que type ``geo_point``, puis ajoutez-le à ``query.geo.fields`` dans ``fess_config.properties``, en séparant les valeurs par des virgules. + +Par exemple, pour rechercher les documents situés dans un rayon de 10 km autour du point de latitude 35.681236 et de longitude 139.767125 (à proximité de la gare de Tokyo), ajoutez les paramètres suivants à la requête de recherche. + +:: + + geo.location.point=35.681236,139.767125&geo.location.distance=10km + +Unités de distance +---------------------- + +La valeur de ``geo..distance`` est interprétée comme une unité de distance d'OpenSearch. Outre ``km`` (kilomètres), les unités ``mm``, ``cm``, ``m``, ``in``, ``ft``, ``yd``, ``mi`` (miles) et ``nmi`` (milles nautiques), entre autres, peuvent être utilisées. Si l'unité est omise et que seule une valeur numérique est indiquée, elle est traitée comme des mètres (exemple : ``500`` correspond à 500 mètres). + +Spécification multiple +--------------------------- + +* Si plusieurs valeurs de ``geo..point`` sont spécifiées pour le même champ, les documents situés dans le rayon de l'un des points sont recherchés (condition OR). +* Si des informations de géolocalisation sont spécifiées pour des champs différents, seuls les documents satisfaisant à toutes les conditions sont recherchés (condition AND). + +.. note:: + + ``geo..point`` et ``geo..distance`` doivent tous deux être spécifiés. Si ``distance`` n'est pas spécifié, la condition du ``point`` correspondant est ignorée. Par ailleurs, une erreur se produit si la valeur de ``point`` n'est pas au format ``latitude,longitude`` (deux nombres séparés par une virgule) ou si elle ne peut pas être interprétée comme des nombres. + +.. note:: + + La recherche par géolocalisation étant un filtre appliqué au terme de recherche, si celui-ci est vide, la recherche n'est pas exécutée et le résultat est de 0 document. Indiquez donc un terme de recherche dans les requêtes de recherche par géolocalisation. diff --git a/fr/15.10/user/search-label.rst b/fr/15.10/user/search-label.rst new file mode 100644 index 000000000..36ba88526 --- /dev/null +++ b/fr/15.10/user/search-label.rst @@ -0,0 +1,29 @@ +=========================== +Recherche par étiquette +=========================== + +Recherche par étiquette (recherche par catégorie) +=================================================== + +En ajoutant aux documents ciblés par la recherche des informations d'étiquette permettant de les catégoriser, il devient possible d'effectuer une recherche filtrée en spécifiant une étiquette. L'utilisation des étiquettes permet par exemple de limiter le périmètre de recherche par service, par site ou par type de document. + +En enregistrant au préalable les étiquettes dans l'écran d'administration, le filtrage par étiquette devient disponible sur l'écran de recherche. Les étiquettes disponibles peuvent être sélectionnées de manière multiple dans un menu déroulant lors de la recherche ; si plusieurs étiquettes sont sélectionnées, les documents auxquels au moins l'une de ces étiquettes est associée sont inclus dans la recherche. Si aucune étiquette n'est enregistrée, le menu déroulant des étiquettes ne s'affiche pas. + +.. note:: + Comme des permissions peuvent être définies pour chaque étiquette, seules les étiquettes auxquelles l'utilisateur effectuant la recherche a accès s'affichent dans le menu déroulant. Par ailleurs, les étiquettes affichées peuvent également varier selon l'hôte virtuel ou la locale (langue). Ainsi, même si une étiquette est enregistrée, elle peut ne pas apparaître dans le menu déroulant selon l'utilisateur. + +Une étiquette se définit en spécifiant, au moyen d'une expression régulière portant sur le chemin de l'URL, les documents auxquels elle doit être appliquée. Pour la procédure d'enregistrement des étiquettes et les éléments de configuration, consultez le :doc:`guide de gestion des étiquettes <../admin/labeltype-guide>`. + +Utilisation +----------- + +Il est possible de sélectionner une étiquette lors de la recherche. Les informations d'étiquette peuvent être sélectionnées dans les options de recherche affichées en cliquant sur le bouton « Options ». + +|image0| + +En créant un index avec des étiquettes configurées, il est possible d'effectuer une recherche pour chaque document auquel une étiquette a été attribuée. Une recherche sans spécifier d'étiquette correspond à une recherche complète classique, comme d'habitude. + +L'attribution des étiquettes aux documents s'effectue, lors du crawl et de la création de l'index, en comparant l'URL du document avec le chemin défini pour l'étiquette. Par conséquent, si vous ajoutez ou modifiez la définition d'une étiquette (chemins cibles ou chemins exclus), ce changement ne sera pas automatiquement répercuté sur les documents déjà indexés. Pour appliquer les modifications, recrawlez les documents concernés ou exécutez la tâche « Label Updater » enregistrée dans le planificateur afin de mettre à jour l'index. + +.. |image0| image:: ../../../resources/images/en/15.10/user/search-label-1.png +.. pdf :width: 300 px diff --git a/fr/15.10/user/search-not.rst b/fr/15.10/user/search-not.rst new file mode 100644 index 000000000..12a17d508 --- /dev/null +++ b/fr/15.10/user/search-not.rst @@ -0,0 +1,50 @@ +======================================= +Recherche NOT (recherche par exclusion) +======================================= + +La recherche NOT (recherche par exclusion) peut être utilisée pour rechercher des documents ne contenant pas un mot spécifique. + +Utilisation +----------- + +Pour effectuer une recherche NOT, placez NOT avant le mot à exclure. NOT +doit être écrit en majuscules et nécessite des espaces avant et après. + +Par exemple, pour rechercher des documents contenant « terme1 » mais ne contenant pas « terme2 », saisissez ce qui suit : + +:: + + terme1 NOT terme2 + +.. note:: + + NOT doit être écrit en majuscules. S'il est écrit en minuscules, comme ``not``, il n'est pas traité comme un opérateur, mais comme un terme de recherche ordinaire « not ». Le signe ``-`` placé directement avant le mot à exclure, comme dans ``terme1 -terme2``, a également la même signification que NOT. + +Par exemple, l'exemple suivant a la même signification que ``terme1 NOT terme2`` : + +:: + + terme1 -terme2 + +En utilisant les parenthèses ``( )``, vous pouvez combiner la recherche NOT avec d'autres conditions de recherche. Par exemple, pour rechercher des documents contenant soit « terme1 » soit « terme2 », mais ne contenant pas « terme3 », saisissez ce qui suit : + +:: + + (terme1 OR terme2) NOT terme3 + +Il est également possible d'effectuer une recherche NOT en spécifiant un champ. Dans l'exemple suivant, la recherche porte sur les documents contenant « terme1 » dans le champ title, mais ne contenant pas « terme2 » dans le champ title. + +:: + + title:terme1 NOT title:terme2 + +.. note:: + + Lorsque le plugin ``fess-webapp-bangs`` est installé, un bang défini comme ``!g`` n'est plus une exclusion : il envoie la recherche vers un autre site. Voir :doc:`search-bangs`. + +Voir aussi +---------- + +- :doc:`search-and` +- :doc:`search-or` +- :doc:`special-char` diff --git a/fr/15.10/user/search-or.rst b/fr/15.10/user/search-or.rst new file mode 100644 index 000000000..b857c88b3 --- /dev/null +++ b/fr/15.10/user/search-or.rst @@ -0,0 +1,39 @@ +======================================== +Recherche OR (contenant l'un des termes) +======================================== + +La recherche OR est utilisée pour rechercher des documents contenant n'importe lequel des termes de recherche. Si vous saisissez plusieurs mots dans le champ de recherche, la recherche sera par défaut de type AND. + +Utilisation +----------- + +Pour utiliser la recherche OR, saisissez OR entre les termes de recherche. OR +doit être écrit en majuscules et nécessite des espaces avant et après. + +Par exemple, pour rechercher des documents contenant soit « terme1 » soit « terme2 », saisissez ce qui suit dans le formulaire de recherche : + +:: + + terme1 OR terme2 + +Il est également possible de connecter trois termes de recherche ou plus avec OR. + +:: + + terme1 OR terme2 OR terme3 + +.. note:: + + OR doit être écrit en majuscules. S'il est écrit en minuscules, comme ``or``, il n'est pas traité comme un opérateur, mais comme un terme de recherche ordinaire « or ». ``||`` peut également être utilisé avec la même signification que OR. + +En utilisant les parenthèses ``( )``, vous pouvez combiner la recherche OR avec d'autres conditions de recherche. Par exemple, pour rechercher des documents contenant soit « terme1 » soit « terme2 », et contenant également « terme3 », saisissez ce qui suit : + +:: + + (terme1 OR terme2) terme3 + +Il est également possible d'effectuer une recherche OR en spécifiant un champ. Dans l'exemple suivant, la recherche porte sur les documents contenant « terme1 » dans le champ title, ou « terme2 » dans le champ content. + +:: + + title:terme1 OR content:terme2 diff --git a/fr/15.10/user/search-proximity.rst b/fr/15.10/user/search-proximity.rst new file mode 100644 index 000000000..c59cf7cba --- /dev/null +++ b/fr/15.10/user/search-proximity.rst @@ -0,0 +1,70 @@ +======================== +Recherche de proximité +======================== +Recherche de proximité (distance entre les mots) +================================================== + +La recherche de proximité permet de trouver les documents dans lesquels les mots d'une phrase apparaissent proches les uns des autres, même s'ils ne sont pas directement adjacents. Elle est utile lorsque d'autres mots peuvent s'intercaler entre les mots recherchés. + +Utilisation +------------- + +Entourez les mots de guillemets doubles, puis ajoutez « ~ » et un chiffre après le guillemet fermant. + +Par exemple, la recherche suivante trouve les documents dans lesquels « Fess » et « recherche » apparaissent à une distance de 3 au plus : + +:: + + "Fess recherche"~3 + +Le nombre correspond au nombre maximal de déplacements de position autorisés entre les mots (voir « Comment la distance est comptée » ci-dessous). Plus le nombre est grand, plus les mots peuvent être éloignés. + +Vous pouvez également effectuer une recherche de proximité sur un champ précis. Dans l'exemple suivant, la recherche porte sur le champ title. + +:: + + title:"Fess recherche"~3 + +Si vous omettez le nombre et n'indiquez que « ~ » (par exemple ``"Fess recherche"~``), la phrase est recherchée comme une phrase normale dont les mots doivent être adjacents. Un nombre décimal est tronqué à sa partie entière (``~2.5`` est traité comme ``~2``). + +La recherche de proximité peut être combinée avec un boost. Dans l'exemple suivant, la recherche de proximité est pondérée par 2 (voir :doc:`search-boost`). + +:: + + "Fess recherche"~5^2 + +Comment la distance est comptée +--------------------------------- + +* Le nombre correspond au nombre maximal de déplacements de position autorisés entre les mots. Il est compté en tokens produits par l'analyseur du champ cible, et non en caractères ni en mots séparés par des espaces. Pour un texte en anglais, il correspond approximativement au nombre de mots situés entre les termes. Les mots supprimés comme mots vides (stop words) lors de l'analyse sont également comptés. +* Les mots peuvent apparaître dans un ordre différent, mais l'ordre inversé nécessite un nombre plus grand. Par exemple, un document contenant « quick brown fox » correspond à ``"quick fox"~1``, mais ne correspond à ``"fox quick"`` qu'à partir de ``~3``. + +:: + + "quick fox"~1 + "fox quick"~3 + +Texte japonais, chinois et coréen (CJK) +----------------------------------------- + +Pour le japonais et les autres textes CJK, l'unité dans laquelle la distance est comptée dépend du champ. + +* Dans les champs généraux title et content, la distance est proche du nombre de caractères situés entre les mots. +* Dans les champs propres à chaque langue, la distance est comptée en tokens morphologiques, et les particules supprimées sont également comptées. + +Séparez donc les mots par des espaces et indiquez un nombre généreux. + +:: + + "全文 検索"~5 + "大阪 おいしい"~10 + +Une chaîne sans espaces (par exemple ``"大阪おいしい"~10``) peut ne pas fonctionner comme prévu en tant que recherche de proximité entre les mots, car dans les champs généraux elle est comparée comme une seule chaîne continue. Séparez les mots par des espaces. La distance ne peut pas être convertie exactement en nombre de caractères ; commencez donc par un nombre généreux, puis affinez-le en vérifiant les résultats. + +Voir aussi +============ + +- :doc:`search-fuzzy` +- :doc:`search-boost` +- :doc:`search-field` +- :doc:`special-char` diff --git a/fr/15.10/user/search-range.rst b/fr/15.10/user/search-range.rst new file mode 100644 index 000000000..1c3a46cc5 --- /dev/null +++ b/fr/15.10/user/search-range.rst @@ -0,0 +1,71 @@ +=================== +Recherche par plage +=================== + +Lorsqu'un champ contient des données pour lesquelles une plage peut être spécifiée, telles que des valeurs numériques ou des dates/heures, il est possible d'effectuer une recherche par plage sur ce champ. + +Utilisation +----------- + +Pour effectuer une recherche par plage, saisissez « nom_champ:[valeur TO valeur] » dans le formulaire de recherche. Le séparateur de plage est ``TO``, à saisir en majuscules (caractères alphanumériques standard). + +Par exemple, pour rechercher des documents dont le champ content_length est compris entre 1 Ko et 10 Ko, saisissez ce qui suit dans le formulaire de recherche : + +:: + + content_length:[1000 TO 10000] + +Les crochets ``[ ]`` incluent les bornes de la plage (supérieur ou égal / inférieur ou égal), tandis que les accolades ``{ }`` les excluent (strictement supérieur / strictement inférieur). Il est également possible de combiner les deux. Par exemple, ``content_length:{1000 TO 10000]`` représente les documents dont la valeur est strictement supérieure à 1000 et inférieure ou égale à 10000. + +En utilisant ``*`` d'un seul côté, vous obtenez une plage ouverte ne spécifiant que la borne supérieure ou la borne inférieure. ``content_length:[1000 TO *]`` représente les valeurs supérieures ou égales à 1000, et ``content_length:[* TO 10000]`` représente les valeurs inférieures ou égales à 10000. + +La recherche par plage n'est valable que pour les champs enregistrés comme cibles de recherche. Par défaut, les champs content_length, last_modified, timestamp, click_count et favorite_count peuvent être utilisés pour une recherche par plage. + +Recherche par plage de temps +----------------------------- + +Pour effectuer une recherche par plage de temps (date/heure), saisissez « last_modified:[datetime1 TO datetime2] » (datetime1 < datetime2) dans le formulaire de recherche. Notez que si datetime1 est postérieur à datetime2, cela ne provoque pas d'erreur : le résultat de la recherche sera simplement de 0 document. + +Les dates/heures doivent être indiquées au format ISO 8601. Le format est ``YYYY-MM-DDThh:mm:ss.SSSZ``, et la partie relative à l'heure peut être omise. + +.. list-table:: + :header-rows: 1 + + * - Contenu spécifié + - Exemple + * - Année, mois, jour uniquement + - 2012-12-02 + * - Année, mois, jour, heures, minutes, secondes + - 2012-12-02T10:45:23Z + * - Année, mois, jour, heures, minutes, secondes (jusqu'aux millisecondes) + - 2012-12-02T10:45:23.235Z + +Pour spécifier une date/heure, vous pouvez utiliser des calculs de date/heure basés sur la date/heure actuelle. Les symboles utilisables sont les suivants : + +.. list-table:: + :header-rows: 1 + + * - Symbole + - Signification + * - ``now`` + - Date/heure actuelle + * - ``y`` / ``M`` / ``w`` / ``d`` / ``h`` / ``m`` / ``s`` + - Année / mois / semaine / jour / heure / minute / seconde + * - ``+`` / ``-`` + - Addition / soustraction + * - ``/`` + - Arrondi (arrondi à l'unité qui suit ``/``) + +Lorsque vous utilisez ``now`` ou une date/heure comme référence, vous pouvez ajouter des symboles tels que ``+``, ``-`` (addition, soustraction) ou ``/`` (arrondi). Cependant, si la référence est une date/heure précise plutôt que ``now``, il est nécessaire d'insérer ``||`` entre la date/heure et le symbole (exemple : ``2016-01-01||+1M/d``). + +``/`` est le symbole qui permet d'arrondir à l'unité indiquée après ``/``. ``now-1d/d`` représente 00:00 de la veille, c'est-à-dire 00:00 du jour actuel moins 1 jour, quelle que soit l'heure d'exécution de la requête aujourd'hui. + +Notez que ces calculs de date/heure sont évalués côté moteur de recherche (OpenSearch) et ne sont valables que pour les champs de type date/heure. + +Par exemple, pour rechercher, dans le champ last_modified, les documents mis à jour entre 30 jours avant la date/heure actuelle (supposée être le 21 février 2016 à 20h) et la date/heure actuelle, saisissez ce qui suit dans le formulaire de recherche : + +:: + + last_modified:[now-30d TO now] + +Si la date/heure actuelle est le 21 février 2016 à 20h (UTC), cela correspond approximativement à la plage ``[2016-01-22T20:00:00Z TO 2016-02-21T20:00:00Z]``. diff --git a/fr/15.10/user/search-sort.rst b/fr/15.10/user/search-sort.rst new file mode 100644 index 000000000..3ae2add29 --- /dev/null +++ b/fr/15.10/user/search-sort.rst @@ -0,0 +1,76 @@ +==================== +Recherche avec tri +==================== + +Il est possible de trier les résultats de recherche en spécifiant un champ tel que la date de recherche. + +Champs de tri +------------- + +Par défaut, vous pouvez trier en spécifiant les champs suivants. + +.. list-table:: + :header-rows: 1 + + * - Nom du champ + - Description + * - created + - Date d'exploration + * - content_length + - Taille du document exploré + * - last_modified + - Date de dernière modification du document exploré + * - filename + - Nom du fichier + * - score + - Score de pertinence + * - timestamp + - Date d'indexation du document + * - click_count + - Nombre de clics sur le document + * - favorite_count + - Nombre de fois où le document a été ajouté aux favoris + +Table : Liste des champs de tri + + +Vous pouvez également ajouter vos propres champs personnalisés comme cibles de tri. Pour cela, indiquez dans ``query.additional.sort.fields`` du fichier ``fess_config.properties`` les noms des champs que vous souhaitez utiliser comme cibles de tri, séparés par des virgules (la valeur par défaut est vide). Les champs indiqués ici sont ajoutés aux champs standards ci-dessus et deviennent disponibles pour le tri. Notez que le champ à trier doit être préalablement enregistré (indexé) dans l'index. + +Utilisation +----------- + +Vous pouvez sélectionner les critères de tri lors de la recherche. Les critères de tri peuvent être sélectionnés dans la boîte de dialogue des options de recherche affichée en cliquant sur le bouton Options. + +|image0| + +De plus, pour trier dans le champ de recherche, saisissez « sort:nom_champ » dans le formulaire de recherche en séparant sort et le nom du champ par deux-points (:). + +Voici un exemple de recherche de fess avec un tri croissant par taille de document. + +:: + + fess sort:content_length + +Pour trier par ordre décroissant, ajoutez ``.desc`` après le nom du champ. + +:: + + fess sort:content_length.desc + +Le suffixe pouvant être ajouté après le nom du champ est ``.asc`` (ordre croissant) ou ``.desc`` (ordre décroissant) ; si vous l'omettez, l'ordre croissant est utilisé. + +Pour trier sur plusieurs champs, spécifiez-les séparés par des virgules (,) comme suit. Le champ indiqué en premier est prioritaire, et les documents ayant la même valeur pour ce champ sont ensuite triés selon le champ suivant. + +:: + + fess sort:content_length.desc,last_modified + +.. note:: + Indiquer dans ``sort:`` au sein des termes de recherche un nom de champ absent de la liste des champs de tri disponibles, ou un ordre de tri autre que ``asc`` ou ``desc``, ne provoque pas d'erreur. + ``sort:`` n'est alors pas traité comme une condition de tri, et la recherche est relancée en traitant les symboles de l'ensemble du terme de recherche (comme ``:``) comme des caractères ordinaires. + Les résultats ne sont pas triés et, dans la plupart des cas, aucun document n'est trouvé. + + Indiquer la même valeur dans le paramètre ``sort`` de l'API de recherche provoque une erreur (400 Bad Request). + +.. |image0| image:: ../../../resources/images/en/15.10/user/search-sort-1.png +.. pdf :width: 300 px diff --git a/fr/15.10/user/search-wildcard.rst b/fr/15.10/user/search-wildcard.rst new file mode 100644 index 000000000..80db363aa --- /dev/null +++ b/fr/15.10/user/search-wildcard.rst @@ -0,0 +1,53 @@ +==================================== +Recherche avec caractères génériques +==================================== + +Vous pouvez utiliser des caractères génériques pour un ou plusieurs caractères dans les termes de recherche. ? peut être spécifié comme caractère générique pour un seul caractère, et \* peut être spécifié comme caractère générique pour plusieurs caractères. Les caractères génériques peuvent être utilisés sur des mots. La recherche avec caractères génériques sur des phrases n'est pas possible. + +Utilisation +----------- + +Pour utiliser un caractère générique pour un seul caractère, utilisez ? comme suit. + +:: + + te?t + +Dans ce cas, cela correspond à un caractère quelconque à la position de ?, comme dans text ou test. + +Pour utiliser un caractère générique pour plusieurs caractères, utilisez \* comme suit. + +:: + + test* + +Dans ce cas, cela correspond à une chaîne de caractères quelconque de longueur nulle ou plus à la position de \*, comme dans test, tests ou tester. De plus, + +:: + + te*t + +peut également être utilisé au milieu d'un terme de recherche, comme ci-dessus. Par ailleurs, + +:: + + *test + +peut également être utilisé en début de terme de recherche, comme ci-dessus. + +Il est également possible d'effectuer une recherche avec caractères génériques en spécifiant un champ. Dans l'exemple suivant, la recherche porte sur les documents dont le champ title contient un mot commençant par te et se terminant par t. + +:: + + title:te*t + +Si aucun champ n'est spécifié, la recherche porte sur les champs title et content. + +Conditions d'utilisation +------------------------ + +Lors de l'utilisation de la recherche avec caractères génériques, tenez compte des points suivants : + +* Les caractères génériques correspondent aux chaînes de caractères (tokens) enregistrées dans l'index. Le terme de recherche n'étant pas réanalysé, si l'index est créé avec bi-gram par exemple, le japonais est traité comme une chaîne de caractères de longueur fixe sans signification, et les caractères génériques en japonais ne fonctionneront pas comme prévu. Pour utiliser des caractères génériques en japonais, utilisez-les dans des champs utilisant l'analyse morphologique. +* Les motifs contenant un caractère générique (``*``, ``?``) au début ou au milieu du terme de recherche sont sensibles à la casse. Les mots enregistrés dans l'index étant généralement convertis en minuscules, utilisez des minuscules dans le motif. Par exemple, ``Te*t``, ``Te?t`` et ``*Test`` ne correspondent pas à ``test``, qui a été enregistré après conversion en minuscules. En revanche, pour un motif dont seule la fin est ``*`` (comme ``Test*``), il s'agit d'une recherche par préfixe et le terme de recherche est analysé après conversion en minuscules : ``Test*`` correspond donc aussi à ``test``. +* Une recherche avec un caractère générique en début de terme (par exemple ``*test``) parcourt tous les mots de l'index et peut donc prendre du temps. diff --git a/fr/15.10/user/special-char.rst b/fr/15.10/user/special-char.rst new file mode 100644 index 000000000..edfc077a7 --- /dev/null +++ b/fr/15.10/user/special-char.rst @@ -0,0 +1,88 @@ +==================== +Caractères spéciaux +==================== + +Les caractères suivants ont une signification particulière dans la syntaxe des requêtes de recherche et sont donc traités comme des caractères spéciaux dans les termes de recherche. Pour utiliser ces caractères comme caractères de recherche littéraux, vous devez les échapper. + +:: + + + - && || ! ( ) { } [ ] ^ " ~ * ? : \ / + +Ces caractères permettent d'invoquer des fonctionnalités de recherche telles que les termes obligatoires/interdits (``+`` ``-``), les opérateurs booléens (``&&`` ``||`` ``!``), le regroupement (``( )``), la recherche par plage (``[ ]`` ``{ }``), la recherche avec pondération (``^``), la recherche de phrase (``"``), la recherche floue et la recherche de proximité (``~``), la recherche par caractère générique (``*`` ``?``) et la recherche par champ (``:``). + +Par exemple, si vous recherchez tels quels des caractères comme ``/`` ou ``:`` présents dans une URL ou un chemin de fichier, ou encore ``+`` ou ``-`` utilisés dans du code, vous risquez d'obtenir des résultats de recherche inattendus. Reportez-vous à la section ci-dessous pour la méthode d'échappement à utiliser. + +Liste des caractères spéciaux et leur signification +----------------------------------------------------- + +.. list-table:: + :header-rows: 1 + + * - Caractère spécial + - Signification / Rôle + - Page associée + * - ``+`` ``-`` + - Indique un terme obligatoire ou un terme à exclure (recherche AND / recherche NOT) + - :doc:`search-and` / :doc:`search-not` + * - ``&&`` ``||`` + - Recherche AND / recherche OR + - :doc:`search-and` / :doc:`search-or` + * - ``!`` + - Recherche NOT (recherche par exclusion) + - :doc:`search-not` + * - ``( )`` + - Regroupement des conditions de recherche + - :doc:`advanced-search` + * - ``[ ]`` ``{ }`` + - Recherche par plage (``[ ]`` inclut les bornes, ``{ }`` les exclut) + - :doc:`search-range` + * - ``^`` + - Recherche avec boost (pondération) + - :doc:`search-boost` + * - ``"`` + - Recherche de phrase (le texte entouré de guillemets est traité comme une seule expression ; peut aussi servir à échapper des caractères spéciaux) + - :doc:`advanced-search` + * - ``~`` + - Recherche floue (après un mot) / recherche de proximité (après une phrase) + - :doc:`search-fuzzy` / :doc:`search-proximity` + * - ``*`` ``?`` + - Recherche avec caractères génériques + - :doc:`search-wildcard` + * - ``:`` + - Indique le champ de recherche + - :doc:`search-field` + * - ``\`` + - Caractère d'échappement + - (cette page) + * - ``/`` + - Barre oblique (doit être échappée lorsqu'elle apparaît, par exemple, dans une URL) + - :doc:`search-field` + +Utilisation +----------- + +Pour traiter un caractère spécial comme un caractère de recherche littéral, utilisez l'une des méthodes suivantes. + +* Placez ``\`` immédiatement avant le caractère pour l'échapper. Le caractère unique qui suit est alors traité comme un caractère normal plutôt que comme un élément de la syntaxe de requête. +* Entourez le terme de recherche de ``"``. La chaîne ainsi entourée est traitée comme une recherche de phrase, et les caractères spéciaux qu'elle contient ne sont pas interprétés comme faisant partie de la syntaxe de requête. Notez cependant que, s'agissant d'une recherche de phrase, des fonctionnalités telles que la recherche par caractère générique (``*`` ``?``) ne sont pas disponibles. + +:: + + aaa\/bbb + "aaa/bbb" + +Par exemple, si vous souhaitez rechercher le terme « C++ » tel quel, échappez-le comme suit : + +:: + + C\+\+ + "C++" + +Voir aussi +----------- + +- :doc:`search-field` +- :doc:`search-wildcard` +- :doc:`search-fuzzy` +- :doc:`search-proximity` +- :doc:`advanced-search` diff --git a/ja/15.10/admin/accesstoken-guide.rst b/ja/15.10/admin/accesstoken-guide.rst new file mode 100644 index 000000000..1ca1497e5 --- /dev/null +++ b/ja/15.10/admin/accesstoken-guide.rst @@ -0,0 +1,80 @@ +============ +アクセストークン +============ + +概要 +==== + +アクセストークン設定ページではアクセストークンを管理します。 + +管理方法 +====== + +表示方法 +------ + +下図のアクセストークンの設定一覧ページを開くには、左メニューの[システム>アクセストークン] をクリックします。 + +|image0| + +編集するには設定名をクリックします。 + +設定の作成 +-------- + +アクセストークンの設定ページを開くには新規作成ボタンをクリックします。 + +|image1| + +設定項目 +------ + +名前 +:::: + +このアクセストークンを説明するための名前を指定します。 + +パーミッション +::::::::::: + +アクセストークンのパーミッションを設定します。 +「{user\ |group|\ role}name」形式で記述します。 +たとえば、developerグループに属するユーザーが検索結果を表示するためには、パーミッションは「{group}developer」を設定します。 + +.. warning:: + + パーミッションに ``{role}admin-api`` を指定したアクセストークン（内部的には ``Radmin-api`` として保存されます）は、Admin API のすべてのエンドポイントを利用できます。詳しくは :doc:`../api/admin/api-admin-overview` を参照してください。``admin-accesstoken`` ロールを持つユーザーはこのトークンを発行でき、``admin-accesstoken-view`` ロールを持つユーザーはトークンの値を表示できるため、この 2 つのロールは管理者ロールと同等として扱い、信頼できる運用担当者にのみ付与してください。 + +パラメーター名 +::::::::::: + +検索クエリーとしてパーミッションを指定する場合のリクエストパラメーター名を指定します。 + +.. warning:: + + パラメーター名機能は、信頼された内部環境でのみ使用することを想定した機能です。 + この機能を有効にすると、URLパラメーターを通じて追加のパーミッションを指定できるようになりますが、 + 外部からアクセス可能な環境やパブリックAPIとして公開されている環境では、 + 悪意のあるユーザーによってURLパラメーターが操作され、本来持たない権限に昇格される可能性があります。 + + 以下の点に注意してください: + + * この機能は、Fessが他のアプリケーションやサービスに組み込まれ、そのアプリケーションがリクエストを完全に制御する場合にのみ使用してください。 + * Fessが信頼できないネットワークに公開されている場合は、パラメーター名を設定しないでください。 + * アクセストークンを使用する際は、外部ユーザーによってURLパラメーターが操作できないことを確認してください。 + +有効期限 +:::::: + +アクセストークンの有効期限を指定します。 + +設定の削除 +-------- + +一覧ページの設定名をクリックし、削除ボタンをクリックすると確認画面が表示されます。 +削除ボタンを押すと設定が削除されます。 + + + +.. |image0| image:: ../../../resources/images/ja/15.10/admin/accesstoken-1.png +.. |image1| image:: ../../../resources/images/ja/15.10/admin/accesstoken-2.png diff --git a/ja/15.10/admin/backup-guide.rst b/ja/15.10/admin/backup-guide.rst new file mode 100644 index 000000000..671352613 --- /dev/null +++ b/ja/15.10/admin/backup-guide.rst @@ -0,0 +1,111 @@ +========= +バックアップ +========= + +概要 +==== + +バックアップページでは |Fess| の設定情報のダウンロードとアップロードができます。 + +ダウンロード +--------- + +|Fess| は設定情報をインデックスとして保持しています。 +ダウンロードするにはインデックス名をクリックしてください。 + +|image0| + +.. note:: + + 辞書（シノニム、ストップワードなど）のファイルはバックアップの対象に含まれません。 + 辞書ファイルは検索エンジンの辞書ディレクトリ（ ``FESS_DICTIONARY_PATH`` ）に保存されているため、必要に応じて別途コピーしてください。 + +fess_config.bulk +:::::::::::::::: + +fess_config.bulk は |Fess| の設定情報を含んでいます。 + +fess_basic_config.bulk +:::::::::::::::::::::: + +fess_basic_config.bulk は、クロール情報、障害URL、ジョブログ、サムネイルキュー、ユーザータグなどを除いた |Fess| の設定情報を含んでいます。 + +fess_user.bulk +:::::::::::::: + +fess_user.bulk はユーザー、ロールおよびグループの情報を含みます。 + +system.properties +::::::::::::::::: + +system.propertiesは全般設定の情報を含みます。 + +fess.json +::::::::: + +fess.jsonはfessインデックスの設定情報を含みます。 + +doc.json +:::::::: + +doc.jsonはfessインデックスのマッピング情報を含みます。 + +chat_log.ndjson +::::::::::::::: + +chat_log.ndjsonはAIチャットの利用ログの情報を含みます。 + +click_log.ndjson +:::::::::::::::: + +click_log.ndjsonはクリックログの情報を含みます。 + +favorite_log.ndjson +::::::::::::::::::: + +favorite_log.ndjsonはお気に入りログの情報を含みます。 + +search_log.ndjson +::::::::::::::::: + +search_log.ndjsonは検索ログの情報を含みます。 + +user_info.ndjson +:::::::::::::::: + +user_info.ndjsonは検索ユーザの情報を含みます。 + +アップロード +--------- + +設定情報をアップロードして取り込むことができます。 +リストアが可能なファイルは次のとおりです。 + +- ``*.bulk`` +- ``system.properties`` +- ``fess.json`` 、 ``doc.json`` ： |Fess| が使用するインデックスの定義ファイルを置き換えます。既存のインデックスの設定やマッピングはその場では変更されません。 +- ``gsa*.xml`` ：Google Search Appliance の設定ファイルです。ウェブクロール設定、ファイルクロール設定、ラベルとして取り込まれます。 + +``*.ndjson`` （検索ログなどのログ）はアップロードして復元することはできません。 + +\*.bulk 内のドキュメントのうち ``updatedTime`` を持つものは、保存済みのドキュメントが存在しない、 +``updatedTime`` を持たない、またはそれより古い場合にだけ書き込まれます。新しくないドキュメントは +スキップされ、 ``fess.log`` に INFO レベルで記録されます。そのため、バックアップ取得後の変更が +巻き戻されることはなく、インストール済みの版が同梱するスケジュールジョブ（ ``updatedTime`` は 0）も +そのまま残ります。 ``updatedTime`` を持たないドキュメントは常に書き込まれます。 + +.. note:: + + スキップの記録は INFO レベルなので、既定のログレベル（ ``warn`` ）では ``fess.log`` に出力されません。記録を確認するときは、復元の前にログレベルを ``info`` にしてください。管理画面の [システム > 全般] の「ログレベル」で変更でき（ |Fess| を再起動すると元に戻ります）、Linux では ``FESS_LOG_LEVEL=info`` でも指定できます。詳しくは :doc:`../config/admin-logging` を参照してください。 + +.. note:: + + 15.10 の |Fess| は、Web 認証とファイル認証の ``password`` をアプリケーションの暗号鍵（ ``fess_config.properties`` の + ``app.cipher.key`` ）で暗号化して保存します。そのため、 ``fess_basic_config.bulk`` と ``fess_config.bulk`` にも + 暗号化された値が含まれます。バックアップを別のインストールに復元するときは、同じ ``app.cipher.key`` を引き継いでください。 + 鍵が異なると、これらの認証情報を使うクロールはエラーで失敗します。15.10 より前のバックアップには平文で含まれており、 + そのまま使えます。 + + なお、 ``*.bulk`` にはこれら以外の値が暗号化されずに含まれます。 ``*.bulk`` は機密ファイルとして保管してください。 + + .. |image0| image:: ../../../resources/images/ja/15.10/admin/backup-1.png diff --git a/ja/15.10/admin/badword-guide.rst b/ja/15.10/admin/badword-guide.rst new file mode 100644 index 000000000..446fb4b54 --- /dev/null +++ b/ja/15.10/admin/badword-guide.rst @@ -0,0 +1,85 @@ +======== +除外ワード +======== + +概要 +==== + +ここでは、サジェストの除外ワードの設定について説明します。 +サジェストは検索語に応じて表示されますが、そのワードをサジェストに表示しないように設定できます。 + + +管理方法 +====== + +表示方法 +------ + +下図のサジェスト除外ワードの設定一覧ページを開くには、左メニューの [サジェスト > 除外ワード] をクリックします。 + +|image0| + +編集するには設定名をクリックします。 + +設定の作成 +-------- + +サジェスト除外ワードの作成ページを開くには、新規作成ボタンをクリックします。 + +|image1| + +設定項目 +------ + +サジェスト候補 +::::::::::: + +NGワードを登録します。 +ここで登録したワードはサジェストに表示されなくなります。 + +設定の削除 +-------- + +一覧ページの設定名をクリックし、削除ボタンをクリックすると確認画面が表示されます。 +削除ボタンを押すと設定が削除されます。 + +ダウンロード +========= + +登録したワードをCSV形式でダウンロードします。 + +|image2| + +CSVの内容 +-------- + +1行目はヘッダーです。 +2行目以降に除外ワードが記載されます。 + +:: + +"BadWord" +"検索エンジン" + +アップロード +========= + +CSV形式でワードを登録します。 + +|image3| + +CSVの内容 +-------- + +1行目はヘッダーです。 +2行目以降に除外ワードを記述します。 + +:: + +"BadWord" +"検索エンジン" + +.. |image0| image:: ../../../resources/images/ja/15.10/admin/badword-1.png +.. |image1| image:: ../../../resources/images/ja/15.10/admin/badword-2.png +.. |image2| image:: ../../../resources/images/ja/15.10/admin/badword-3.png +.. |image3| image:: ../../../resources/images/ja/15.10/admin/badword-4.png diff --git a/ja/15.10/admin/boostdoc-guide.rst b/ja/15.10/admin/boostdoc-guide.rst new file mode 100644 index 000000000..b37e4a890 --- /dev/null +++ b/ja/15.10/admin/boostdoc-guide.rst @@ -0,0 +1,83 @@ +=============== +ドキュメントブースト +=============== + +概要 +==== + +ここでは、ドキュメントブーストに関する設定について説明します。 +ドキュメントブーストの設定を行うことで、検索語に関わらず検索結果の上位にドキュメントを位置づけることができます。 + +管理方法 +====== + +表示方法 +------ + +下図のドキュメントブーストの設定一覧ページを開くには、左メニューの [クローラー > ドキュメントブースト] をクリックします。 + +|image0| + +編集するには設定名をクリックします。 + +設定の作成 +-------- + +ドキュメントブーストの設定ページを開くには新規作成ボタンをクリックします。 + +|image1| + +設定項目 +------ + +条件 +:::: + +上位に位置づけたいドキュメントの条件を指定します。 +たとえば、https://www.n2sm.net/を含むURLを上位に表示したい場合は、url.matches("https://www.n2sm.net/.\*")を記述します。 +条件は、下記の「スクリプト種別」で指定したスクリプトエンジンの構文で記述します。 + +ブースト値式 +::::::::: + +ドキュメントの重み付けの値を指定します。 +式は、下記の「スクリプト種別」で指定したスクリプトエンジンの構文で記述します。 + +スクリプト種別 +:::::::::::::: + +条件およびブースト値式を評価するスクリプトエンジンを指定します。 +新規作成時は ``javascript`` があらかじめ入力されています。 ``groovy`` を指定する場合は +``fess-script-groovy`` プラグインが必要です。未入力の場合はGroovyとして評価されます。 + +.. warning:: + + JavaScriptでは、条件およびブースト値式を末尾のセミコロンを付けない式として記述してください。 + 文のブロックとしてしか解析できない文字列は、明示的な ``return`` を含まない限り ``null`` と + 評価されます。 :ref:`javascript-statement-null` （ :doc:`../config/scripting-javascript` ） + を参照してください。 + +ソート順 +:::::: + +ドキュメントブーストのソート順を設定します。 + +ルールが適用されるタイミング +---------------------------- + +ドキュメントブーストのルールは、Webクロールまたはファイルクロールでドキュメントをインデックスに登録するときに評価されます。データストアクロールには適用されません。 +ルールを追加・変更・削除しても、すでにインデックスにあるドキュメントのブースト値は変わりません。 + +[システム > 全般] の「最終更新日時の確認」が有効な場合（既定）、内容が変わっていないドキュメントは再クロールしてもインデックスに登録し直されないため、ブーストは再評価されません。 +追加・変更したルールを既存のドキュメントに反映するには、対象のドキュメントをインデックスから削除（ :doc:`searchlist-guide` ）してから、クロールし直してください。 +内容が更新されたドキュメントなど、インデックスに登録し直されるドキュメントは、そのときにルールが評価されます。 +「最終更新日時の確認」を無効にすると、クロールのたびにすべてのドキュメントが登録し直されるため、ルールも毎回評価されます。 + +設定の削除 +-------- + +一覧ページの設定名をクリックし、削除ボタンをクリックすると確認画面が表示されます。削除ボタンを押すと設定が削除されます。 + + +.. |image0| image:: ../../../resources/images/ja/15.10/admin/boostdoc-1.png +.. |image1| image:: ../../../resources/images/ja/15.10/admin/boostdoc-2.png diff --git a/ja/15.10/admin/crawlinginfo-guide.rst b/ja/15.10/admin/crawlinginfo-guide.rst new file mode 100644 index 000000000..e2aea5561 --- /dev/null +++ b/ja/15.10/admin/crawlinginfo-guide.rst @@ -0,0 +1,93 @@ +========= +クロール情報 +========= + +概要 +==== + +クロールの実行結果は記録され、クロール情報はこの管理画面で確認することができます。 + +管理方法 +====== + +一覧 +==== + +クロールが実行されるごとにクロール情報として記録されます。 +一覧では実行したクロールのセッション名と実行した時間を確認することができます。 +クロール情報の詳細を確認したい場合は対象のクロール情報をクリックします。 + +|image0| + +詳細 +==== + +一覧のクロール情報のセッションIDをクリックすることで、対象のクロール情報詳細が表示されます。 + +|image1| + +項目一覧 +------ + +セッションID +:::::::::: + +クロール実行時のセッションID。 + +クローラーの開始時間 +::::::::::::::: + +クロール全体が開始した時刻。 + +クロールの開始時間 (ウェブ/ファイル) +:::::::::::::::::::::::::::: + +ウェブおよびファイルシステムクロールが開始された時刻。 + +クロールの開始時間 (データストア) +:::::::::::::::::::::::::: + +データストアクロールが開始した時刻。 + +クロールの終了時間 (ウェブ/ファイル) +:::::::::::::::::::::::::::: + +ウェブおよびファイルシステムクロールが終了した時刻。 + +クロールの実行時間 (データストア) +:::::::::::::::::::::::::: + +データストアクロールの実行時間(ミリ秒)。 + +インデクシングの実行時間 (データストア) +:::::::::::::::::::::::::::::: + +ウェブおよびファイルシステムクロールの結果をインデクシングするためにかかった時間(ミリ秒)。 + +インデックスのサイズ (データストア) +::::::::::::::::::::::::::: + +インデクシングされたドキュメントの数。 + +クロールの終了時間 (データストア) +:::::::::::::::::::::::::: + +データストアクロールが終了した時刻。 + +クローラーの状態 +:::::::::::: + +クロールが成功したかどうか。 + +クローラーの終了時間 +::::::::::::::: + +クロール全体が終了した時刻。 + +クローラーの実行時間 +::::::::::::::: + +クロール全体の実行時間(ミリ秒)。 + +.. |image0| image:: ../../../resources/images/ja/15.10/admin/crawlinginfo-1.png +.. |image1| image:: ../../../resources/images/ja/15.10/admin/crawlinginfo-2.png diff --git a/ja/15.10/admin/dashboard-guide.rst b/ja/15.10/admin/dashboard-guide.rst new file mode 100644 index 000000000..0e88696b3 --- /dev/null +++ b/ja/15.10/admin/dashboard-guide.rst @@ -0,0 +1,58 @@ +=========== +ダッシュボード +=========== + +概要 +==== + +ダッシュボードでは、 |Fess| がアクセスしている OpenSearch のクラスターとインデックスを管理するウェブ管理ツールを提供します。 + +|image0| + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: |Fess| が管理するインデックス + :header-rows: 1 + + * - インデックス名 + - 説明 + * - fess.yyyyMMddHHmmssSSS + - インデックスされたドキュメント + * - fess_log + - アクセスログ + * - fess.suggest.yyyyMMddHHmmssSSS + - サジェストワード + * - fess_config + - |Fess| の設定 + * - fess_user + - ユーザー/ロール/グループのデータ + * - configsync + - 辞書の設定 + * - fess_suggest + - サジェストのメタデータ + * - fess_suggest_array + - サジェストのメタデータ + * - fess_suggest_badword + - サジェストのNGワードリスト + * - fess_suggest_analyzer + - サジェストのメタデータ + * - fess_crawler + - クロール情報 + +インデックス名の ``fess.`` および ``fess.suggest.`` に続く部分は、インデックスを作成した日時（ ``yyyyMMddHHmmssSSS`` の17桁）です。 + +ドット(.)で始まるインデックス名はシステム用のインデックスであるため、表示されていません。 +システム用のインデックスも表示するためには、Specialのチェックボックスを有効にしてください。 + +インデックスされているドキュメント数の確認 +================================ + +インデックスされているドキュメントの数は、下図のように fessインデックス に表示されています。 + +|image1| + +各インデックスの右上のアイコンをクリックすると、インデックスに対する操作メニューが表示されます。 +インデックスされたドキュメントを削除する場合は管理用の検索画面で削除します。「インデックスを削除」で削除しないように注意してください。 + +.. |image0| image:: ../../../resources/images/ja/15.10/admin/dashboard-1.png +.. |image1| image:: ../../../resources/images/ja/15.10/admin/dashboard-2.png +.. pdf :width: 400 px diff --git a/ja/15.10/admin/dataconfig-guide.rst b/ja/15.10/admin/dataconfig-guide.rst new file mode 100644 index 000000000..07ff4bb43 --- /dev/null +++ b/ja/15.10/admin/dataconfig-guide.rst @@ -0,0 +1,409 @@ +==================== +データストアクロール +==================== + +概要 +==== + +データストアクロールは、リレーショナルデータベース（MySQL・PostgreSQL・Oracle など）や CSV ファイルをはじめ、Web サイトやファイル以外のさまざまなデータソースを |Fess| のインデックスに登録し、全文検索できるようにする機能です。対応するデータソースはデータストアコネクタプラグインによって拡張できます。 + +|Fess| ではデータベースやCSVなどのデータソースをクロール対象とすることができます。 +ここでは、そのために必要なデータストアの設定について説明します。 + +.. note:: + + ``DatabaseDataStore`` はデータベースコネクタプラグイン（ ``fess-ds-db`` ）、``CsvDataStore`` / ``CsvListDataStore`` は CSV コネクタプラグイン（ ``fess-ds-csv`` ）により提供されます。利用可能なコネクタの一覧は :doc:`../config/datastore/ds-overview` を参照してください。 + +管理方法 +====== + +表示方法 +------ + +下図のデータストアの設定を行うための一覧ページを開くには、左メニューの [クローラー > データストア] をクリックします。 + +|image0| + +編集するには設定名をクリックします。 + +設定の作成 +-------- + +データストアの設定ページを開くには新規作成ボタンをクリックします。 + +|image1| + +設定項目 +------ + +名前 +:::: + +クロール設定の名前を指定します。 + +ハンドラー名 +::::::::: + +データストアを処理するハンドラー名です。 + +* DatabaseDataStore: データベースをクロールする +* CsvDataStore: CSV/TSVファイルを対象としてクロールする +* CsvListDataStore: インデクシング対象のファイルパスを記述したCSVファイルをクロールする + +ハンドラー名のプルダウンに表示されるのは、インストールされているデータストアコネクタプラグイン（ ``fess-ds-*`` ）が提供するハンドラーだけです。 +プラグインをインストールしていない場合、選択できるハンドラーはありません。 +上記以外のハンドラーについては、 :doc:`../config/datastore/ds-overview` に掲載している各コネクタのページを参照してください。 +なお、以前のバージョンの文書にある ``EsDataStore`` （ ``fess-ds-elasticsearch`` プラグイン）は、15.6.0 を最後に公開されておらず、15.10 では利用できません。 + +パラメーター +::::::::: + +データストアに関するパラメーターを指定します。 + +``script_type`` パラメーターで、次項のスクリプトを評価するスクリプトエンジンを指定します。 +新規作成時は ``script_type=javascript`` があらかじめ入力されています。 +``script_type`` を指定しない場合、スクリプトはGroovyとして評価されます。 + +スクリプト +:::::::: + +データストアから取得した値をどのフィールドに設定するかなどを指定します。 +式は、上記の ``script_type`` パラメーターで指定したスクリプトエンジンの構文で記述します +（既定はJavaScriptです）。 + +.. warning:: + + JavaScriptでは、各行を末尾のセミコロンを付けない式として記述してください。文のブロックと + してしか解析できない行（末尾にセミコロンがあるもの、 ``let`` / ``const`` による宣言など） + は、明示的な ``return`` を含まない限り ``null`` と評価され、 ``null`` と評価された + マッピングはそのフィールドを設定しません。エラーもログも出力されず、フィールドが黙って + 空になること以外に症状はありません。 + :ref:`javascript-statement-null` （ :doc:`../config/scripting-javascript` ）を参照して + ください。 + +ブースト値 +:::::::: + +この設定でクロールしたときのドキュメントのブースト値を指定します。 + +パーミッション +::::::::::: + +この設定のパーミッションを指定します。 +パーミッションの指定方法は、たとえば、developerグループに属するユーザーに検索結果を表示させるためには{group}developerと指定します。 +ユーザー単位の指定は{user}ユーザー名、ロール単位の指定は{role}ロール名、グループ単位の指定は{group}グループ名で指定します。 + +仮想ホスト +:::::::: + +仮想ホストのホスト名を指定します。 +詳しくは :doc:`設定ガイドの仮想ホスト <../config/security-virtual-host>` を参照してください。 + +状態 +:::: + +このクロール設定を利用するかどうかを指定します。 + +説明 +:::: + +説明を入力できます。 + +設定の削除 +-------- + +一覧ページの設定名をクリックし、削除ボタンをクリックすると確認画面が表示されます。 +削除ボタンを押すと設定が削除されます。 + +例 +== + +DatabaseDataStore +----------------- + +データベースクロールについて説明します。 + +例として、以下のようなテーブルが MySQL の testdb +というデータベースにあり、ユーザ名 hoge 、パスワード fuga +で接続することができるとして、説明を行います。 + +:: + + CREATE TABLE doc ( + id BIGINT NOT NULL AUTO_INCREMENT, + title VARCHAR(100) NOT NULL, + content VARCHAR(255) NOT NULL, + latitude VARCHAR(20), + longitude VARCHAR(20), + versionNo INTEGER NOT NULL, + PRIMARY KEY (id) + ); + +ここでは、データは以下のようなものを入れておきます． + +:: + + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 1', 'コンテンツ 1 です．', '37.77493', ' -122.419416', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 2', 'コンテンツ 2 です．', '34.701909', '135.494977', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 3', 'コンテンツ 3 です．', '-33.868901', '151.207091', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 4', 'コンテンツ 4 です．', '51.500152', '-0.113736', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 5', 'コンテンツ 5 です．', '35.681137', '139.766084', 1); + +パラメーター +:::::::::::: + +パラメーターの設定例は以下のようになります。 + +:: + + driver=com.mysql.jdbc.Driver + url=jdbc:mysql://localhost:3306/testdb?useUnicode=true&characterEncoding=UTF-8 + username=hoge + password=fuga + sql=select * from doc + +パラメーターは「キー=値」形式となっています。キーの説明は以下です。 + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - driver + - ドライバークラス名 + * - url + - URL + * - username + - DBに接続する際のユーザ名 + * - password + - DBに接続する際のパスワード + * - sql + - クロール対象を得るための SQL 文 + +表: DB用設定パラメーター例 + + +スクリプト +:::::::: + +スクリプトの設定例は以下のようになります。 + +:: + + url="http://SERVERNAME/" + id + host="SERVERNAME" + site="SERVERNAME" + title=title + content=content + cache=content + digest=content + anchor= + content_length=content.length() + last_modified=new java.util.Date() + location=latitude + "," + longitude + latitude=latitude + longitude=longitude + +パラメーターは「キー=値」形式になっています。キーの説明は以下です。 + +値の側は、 ``script_type`` パラメーターで指定したスクリプトエンジンの構文で記述します。 +文字列はダブルクォーテーションで閉じてください。データベースのカラム名でアクセスすれば、その値になります。 + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - url + - URL(ご利用の環境に合わせて、データにアクセス可能なURLを設定してください) + * - host + - ホスト名 + * - site + - サイトパス + * - title + - タイトル + * - content + - ドキュメントのコンテンツ(インデックス対象文字列) + * - cache + - ドキュメントのキャッシュ(インデックス対象ではない) + * - digest + - 検索結果に表示されるダイジェスト部分 + * - anchor + - ドキュメントに含まれるリンク(普通は指定する必要はありません) + * - content_length + - ドキュメントの長さ + * - last_modified + - ドキュメントの最終更新日 + +表: スクリプトの設定内容 + + +ドライバー +:::::::: + +データベースに接続する際にはドライバーが必要となります。app/WEB-INF/lib に jar ファイルを置いてください。 + +CsvDataStore +------------ + +CSVファイルを対象としたクロールについて説明します。 + +たとえば、/home/taro/csv ディレクトリに test.csv ファイルを以下のような内容で生成しておきます。 +ファイルのエンコーディングは Shift_JIS にしておきます。 + +:: + + 1,タイトル 1,テスト1です。 + 2,タイトル 2,テスト2です。 + 3,タイトル 3,テスト3です。 + 4,タイトル 4,テスト4です。 + 5,タイトル 5,テスト5です。 + 6,タイトル 6,テスト6です。 + 7,タイトル 7,テスト7です。 + 8,タイトル 8,テスト8です。 + 9,タイトル 9,テスト9です。 + + +パラメーター +::::::::: + +パラメーターの設定例は以下のようになります。 + +:: + + directories=/home/taro/csv + fileEncoding=Shift_JIS + +パラメーターは「キー=値」形式となっています。キーの説明は以下です。 + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - directories + - CSVファイルが含まれるディレクトリ (.csvまたは.tsv) + * - files + - CSVファイル (直接指定する場合) + * - fileEncoding + - CSVファイルのエンコーディング + * - separatorCharacter + - 区切り文字 + + +表: CSVファイル用設定パラメーター例 + + +スクリプト +:::::::: + +スクリプトの設定例は以下のようになります。 + +:: + + url="http://SERVERNAME/" + cell1 + host="SERVERNAME" + site="SERVERNAME" + title=cell2 + content=cell3 + cache=cell3 + digest=cell3 + anchor= + content_length=cell3.length() + last_modified=new java.util.Date() + +パラメーターは「キー=値」形式になります。 +キーはデータベースクロールの場合と同様です。 +CSVファイル内のデータは、cell[数字]で保持しています(数字は 1 から始まります)。 +CSVファイルのセルにデータが存在しない場合はnullになる場合があります。 + +CsvListDataStore +---------------- + +大量のファイルをクロールする場合に利用します。 +更新があったファイルのパスを書き込んだCSVファイルを配置し、指定されたパスだけをクロールさせることで、クロールの実行時間を短縮できます。 + +パスを記述する際のフォーマットは以下になります。 + +:: + + [アクション]<区切り文字>[パス] + +アクションには、以下のいずれかを指定します。 + +* create：ファイルが作成された +* modify：ファイルが更新された +* delete：ファイルが削除された + +たとえば、/home/taro/csv ディレクトリに test.csv ファイルを以下のような内容で生成しておきます。 +ファイルのエンコーディングは Shift_JIS にしておきます。 + +パスはファイルクロールでクロール対象のパスを指定するときと同じ表記でパスを記述します。 +以下のように、「file:/[パス]」、または「smb://[パス]」のように指定します。 + +:: + + modify,smb://servername/data/testfile1.txt + modify,smb://servername/data/testfile2.txt + modify,smb://servername/data/testfile3.txt + modify,smb://servername/data/testfile4.txt + modify,smb://servername/data/testfile5.txt + modify,smb://servername/data/testfile6.txt + modify,smb://servername/data/testfile7.txt + modify,smb://servername/data/testfile8.txt + modify,smb://servername/data/testfile9.txt + modify,smb://servername/data/testfile10.txt + + +パラメーター +::::::::: + +パラメーターの設定例は以下のようになります。 + +:: + + directories=/home/taro/csv + fileEncoding=Shift_JIS + +パラメーターは「キー=値」形式となっています。キーの説明は以下です。 + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - directories + - CSVファイルが含まれるディレクトリ (.csvまたは.tsv) + * - fileEncoding + - CSVファイルのエンコーディング + * - separatorCharacter + - 区切り文字 + + +表: CSVファイル用設定パラメーター例 + + +スクリプト +:::::::: + +スクリプトの設定例は以下のようになります。 + +:: + + event_type=cell1 + url=cell2 + +パラメーターは「キー=値」形式になります。 +キーはデータベースクロールの場合と同様です。 + +クロール先で認証が必要な場合は以下も設定する必要があります。 + +:: + + crawler.file.auth=example + crawler.file.auth.example.scheme=SAMBA + crawler.file.auth.example.username=username + crawler.file.auth.example.password=password + +関連ページ +========== + +- :doc:`../config/datastore/index` +- :doc:`../config/datastore/ds-database` +- :doc:`../config/datastore/ds-overview` +- :doc:`../config/crawler-basic` + +.. |image0| image:: ../../../resources/images/ja/15.10/admin/dataconfig-1.png +.. |image1| image:: ../../../resources/images/ja/15.10/admin/dataconfig-2.png diff --git a/ja/15.10/admin/dict-guide.rst b/ja/15.10/admin/dict-guide.rst new file mode 100644 index 000000000..d8c2fd292 --- /dev/null +++ b/ja/15.10/admin/dict-guide.rst @@ -0,0 +1,163 @@ +==== +辞書 +==== + +概要 +==== + +ここでは、辞書に関する設定について説明します。 + +辞書の変更は各辞書に関する仕様を理解した上で実施してください。 +辞書の変更に失敗するとインデックスにアクセスできなくなる場合があります。 + +.. note:: + + ``search_engine.type`` が ``vanilla`` または ``aws`` の場合（OpenSearch に CodeLibs のプラグインがない場合）、辞書の管理は使えません。詳しくは :doc:`../config/search-engine-type` を参照してください。 + +一覧 +==== + +下図の管理可能な辞書一覧ページを開くには、左メニューの [システム > 辞書] をクリックします。 + + +|image0| + + +辞書が効く範囲と反映のタイミング +================================ + +辞書ごとに、効くフィールドと反映されるタイミングが異なります。 +辞書を編集したのに検索結果が変わらない場合は、まずこの表を確認してください。 + +.. list-table:: + :header-rows: 1 + :widths: 22 26 28 24 + + * - 辞書 + - ファイル + - 効くフィールド + - 反映のタイミング + * - Kuromoji + - ``ja/kuromoji.txt`` + - ``content_ja`` などの ``_ja`` フィールドのみ + - インデックス時（再クロールが必要） + * - 同義語 + - ``synonym.txt`` + - ``content`` ・ ``title`` + - 検索時（再クロール不要） + * - マッピング（言語共通） + - ``mapping.txt`` + - ``content`` ・ ``title`` + - インデックス時（再クロールが必要） + * - マッピング（言語別） + - ``ja/mapping.txt`` + - ``content_ja`` などの ``_ja`` フィールドのみ + - インデックス時（再クロールが必要） + * - Protwords + - ``en/protwords.txt`` + - ``content`` ・ ``title`` + - インデックス時と検索時 + * - ストップワード + - ``en/stopwords.txt`` + - ``content`` ・ ``title`` + - インデックス時と検索時 + * - Stemmer上書き + - ``en/stemmer_override.txt`` + - ``content`` ・ ``title`` + - インデックス時と検索時 + +.. note:: + + アナライザーはインデックスを開くときに構築されるため、辞書ファイルを更新しても + **インデックスを close / open するまで反映されません**\ 。 + さらに「インデックス時」に効く辞書は、すでにインデックス済みの文書には遡及しないので、 + 対象を再クロールする必要があります。 + 反映の手順は :ref:`dict-apply-changes` を参照してください。 + +.. warning:: + + 全文検索の中心となる ``content`` フィールドに効く文字置換辞書は\ **ルートの** + ``mapping.txt`` であり、 ``ja/mapping.txt`` ではありません。 + 同じ「マッピング」という名前ですが、別のファイルです。 + +.. _dict-apply-changes: + +辞書の変更を反映する +-------------------- + +辞書を保存しただけでは、時間をおいても検索結果は変わりません。保存した内容は OpenSearch の +configsync プラグインがおよそ 1 分ごとに辞書ファイルへ書き出しますが、アナライザーが辞書を +読み込むのはインデックスを開いたときだけなので、開いているインデックスは古い辞書のまま動きます。 +辞書を編集したら、ドキュメントインデックスをリロードしてください。 + +1. 左メニューの [システム情報 > メンテナンス] を開きます。 +2. 「ドキュメントインデックスのリロード」の [リロード] ボタンをクリックします。 + +このボタンは、保存済みの辞書をファイルへ書き出してから、 ``fess.update`` エイリアスが指す +インデックスを close して open します。定期的な書き出しを待つ必要はありません。同義語のように +検索時に効く辞書は、インデックスが開いた時点で反映されます。インデックス時に効く辞書は、 +さらに対象の文書を再クロールしてください。 + +.. warning:: + + インデックスを close している間と、open したあとシャードが割り当てられるまでの間は、 + そのインデックスを検索できません。検索がエラーになったり 0 件になったりします。インデックスが + 大きいほどこの時間は長くなるので、アクセスの少ない時間帯に実行してください。 + +管理画面を使わずにスクリプトなどから行う場合は、OpenSearch に同じ操作を送ります:: + + curl -X POST "localhost:9200/_configsync/flush" + curl -X POST "localhost:9200/fess.update/_close" + curl -X POST "localhost:9200/fess.update/_open" + +``_configsync/flush`` は保存済みの辞書をすぐにファイルへ書き出します。省略する場合は、辞書を +保存してから 1 分以上待ってからインデックスを close してください。 + +Kuromoji ユーザー辞書と検索結果 +------------------------------- + +``content`` フィールドは standard トークナイザーと ``cjk_bigram`` で解析されるため、 +Kuromoji の形態素解析の分割結果には影響されません。日本語の複合語を Kuromoji ユーザー辞書に +登録して再クロールしても、 ``content`` に対する検索の結果は変わりません。 +登録の効果が現れるのは ``content_ja`` で、このフィールドはリクエストの言語に応じて +検索条件に加わります。 + +Kuromoji +======== + +日本語形態素解析用の辞書を管理します。 +ja/kuromoji.txt は日本語の形態素解析用辞書になります。 + +同義語 +===== + +同義語辞書の管理をします。 +synonym.txtは言語共通で利用される同義語辞書ファイルになります。 + +マッピング +======== + +文字置換辞書の管理をします。 +mapping.txtは言語共通または各言語用の単語置換辞書ファイルになります。 + +Protwords +========= + +保護単語辞書の管理をします。 +protwords.txtは各言語用に配置して、ステミングの対象外などにするための単語一覧ファイルになります。 + +ストップワード +=========== + +ストップワード辞書の管理をします。 +stopwords.txtは各言語用に配置して、インデックス作成時に除外するための単語一覧ファイルになります。 + +Stemmer上書き +============ + +Stemmer上書き辞書の管理をします。 +stemmer_override.txtは各言語用に配置して、ステミング処理を上書きするための単語置換辞書ファイルになります。 + + +.. |image0| image:: ../../../resources/images/ja/15.10/admin/dict-1.png + :height: 940px diff --git a/ja/15.10/admin/docreport-guide.rst b/ja/15.10/admin/docreport-guide.rst new file mode 100644 index 000000000..09c5ddd62 --- /dev/null +++ b/ja/15.10/admin/docreport-guide.rst @@ -0,0 +1,55 @@ +==================== +ドキュメントレポート +==================== + +概要 +==== + +ドキュメントレポートは、クロールしたファイルサーバーなどの整理に役立つ管理画面です。内容が同じ文書と、長い間更新されていない文書を一覧表示し、それぞれ CSV でダウンロードできます。 + +画面を開くには、左メニューの [システム情報 > ドキュメントレポート] をクリックします。閲覧には ``admin-docreport`` または ``admin-docreport-view`` のロールが必要です。この画面は表示とダウンロードだけを行い、文書を変更しません。 + +どちらのタブも「URL の前方一致」（例: ``smb://server/share/`` ）で対象を絞り込めます。 + +重複文書 +======== + +内容が同一またはほぼ同一の文書をグループにまとめ、文書数の多い順に表示します。グループ分けには、索引時に計算される内容の署名（ ``content_minhash_bits`` 、検索結果の重複表示の折りたたみと同じもの）を使うため、再インデクシングは不要です。内容に語がない文書（空のファイルなど）は対象外です。 + +画面には最大 ``docreport.duplicate.group.size`` （デフォルト: 100）グループを表示し、各グループの文書は ``docreport.duplicate.docs.size`` （デフォルト: 10）件まで表示します。すべてのグループは [CSVをダウンロード] で取得できます。CSV は大きなインデックスでもすべてのグループを読み取り、 ``group, groupSize, url, title, filename, contentLength, lastModified, owner, lastModifier, clickCount, docId`` の列を出力します。 + +.. note:: + + 重複文書レポートには内容の署名が必要ですが、CodeLibs のプラグインを含まない OpenSearch 用のインデックス定義（ ``search_engine.type`` が ``vanilla`` 、 ``aws`` 、非推奨の ``cloud`` ）では署名が計算されません。これらの種別では「重複文書」タブは表示されず、「休眠文書」だけを利用できます。詳しくは :doc:`../config/search-engine-type` を参照してください。 + +休眠文書 +======== + +最終更新日時が指定した日数（「未更新の日数」、デフォルトは ``docreport.dormant.days`` の 365）より前の文書を、古い順に表示します。最終更新日時を持たない文書は表示しません。「検索結果から一度も開かれていない」を有効にすると、検索結果からクリックされたことのある文書を除きます。 + +画面には該当する文書の件数と合計サイズ、文書の一覧を表示します。一覧のページ送りには上限（ ``indexer.max.result.window.size`` ）があり、それを超える文書は [CSVをダウンロード] で取得します。 + +設定 +==== + +``fess_config.properties`` の次の設定で動作を調整できます。 + +.. list-table:: + :header-rows: 1 + :widths: 40 45 15 + + * - プロパティ + - 説明 + - デフォルト + * - ``docreport.duplicate.group.size`` + - 画面に表示する重複グループの最大数 + - ``100`` + * - ``docreport.duplicate.docs.size`` + - 画面で 1 つのグループに表示する文書の最大数 + - ``10`` + * - ``docreport.duplicate.export.page.size`` + - CSV のダウンロード時に 1 回に読み取る署名の数 + - ``10000`` + * - ``docreport.dormant.days`` + - 休眠文書とみなす、最終更新からの日数のデフォルト + - ``365`` diff --git a/ja/15.10/admin/duplicatehost-guide.rst b/ja/15.10/admin/duplicatehost-guide.rst new file mode 100644 index 000000000..0da64dc5e --- /dev/null +++ b/ja/15.10/admin/duplicatehost-guide.rst @@ -0,0 +1,59 @@ +======== +重複ホスト +======== + +概要 +==== + +ここでは、重複ホストに関する設定について説明します。 +重複ホストはクロール時に異なるホスト名を同一のものとして扱いたいときに利用します。 +たとえば、www.example.com と example.com を同じサイトとして扱いたい場合などで利用できます。 + +管理方法 +====== + +表示方法 +------ + +下図の重複ホストの設定を行うための一覧ページを開くには、左メニューの [クローラー > 重複ホスト] をクリックします。 + +|image0| + +編集するには設定名をクリックします。 + +設定の作成 +-------- + +重複ホストの設定ページを開くには新規作成ボタンをクリックします。 + +|image1| + +設定項目 +------ + +正規名 +::::: + +正規ホスト名を指定します。重複ホスト名は正規ホスト名に置き換えます。 + +重複名 +::::: + +重複しているホスト名を指定します。置き換えたいホスト名を指定します。 + +.. note:: + + 重複名に一致するホスト名のURLは、クロール設定の「URL」（開始URL）に書いたものも、クロール中に見つかったリンクのURLも、クロールの前に正規名のURLへ置き換えられます。 + このため、クロール設定の「クロール対象とするURL」「クロール対象から除外するURL」は、置き換えた後のURLに対して評価されます。これらは正規名のホスト名で記述してください。 + + たとえば、正規名を ``example.com`` 、重複名を ``www.example.com`` としたとき、 ``https://www.example.com/.*`` だけを「クロール対象とするURL」に書くと、置き換え後の開始URL（ ``https://example.com/`` ）が対象外になります。 + この場合、エラーもログも出力されないまま、ドキュメントは1件もインデックスに登録されません。 + +設定の削除 +-------- + +一覧ページの設定名をクリックし、削除ボタンをクリックすると確認画面が表示されます。 +削除ボタンを押すと設定が削除されます。 + +.. |image0| image:: ../../../resources/images/ja/15.10/admin/duplicatehost-1.png +.. |image1| image:: ../../../resources/images/ja/15.10/admin/duplicatehost-2.png diff --git a/ja/15.10/admin/elevateword-guide.rst b/ja/15.10/admin/elevateword-guide.rst new file mode 100644 index 000000000..afc36c2dc --- /dev/null +++ b/ja/15.10/admin/elevateword-guide.rst @@ -0,0 +1,106 @@ +======== +追加ワード +======== + +概要 +==== + +ここでは、サジェストのワードの追加候補の設定について説明します。 サジェストは検索語に応じて表示されますが、そのワードを追加したりすることができます。 + +管理方法 +====== + +表示方法 +------ + +下図の追加ワードの設定を行うための一覧ページを開くには、左メニューの [サジェスト > 追加ワード] をクリックします。 + +|image0| + +編集するには設定名をクリックします。 + +設定の作成 +-------- + +追加ワードの設定ページを開くには新規作成ボタンをクリックします。 + +|image1| + +設定項目 +------ + +単語 +:::: + +サジェスト候補として表示されるワードを指定します。 + +読み +:::: + +サジェスト候補のワードのよみがなを指定します。 + +パーミッション +::::::::::: + +ワードにロール情報を設定します。 +設定したロールを持っているユーザーしかサジェストに表示されません。 + +ラベル +::::: + +ワードにラベルを設定します。 +設定したラベル以外を選択している場合はサジェストに表示されません。 + +ブースト値 +:::::::: + +ワードにブースト値を設定します。 + +設定の削除 +-------- + +一覧ページの設定名をクリックし、削除ボタンをクリックすると確認画面が表示されます。 +削除ボタンを押すと設定が削除されます。 + + +ダウンロード +========= + +登録したワードをCSV形式でダウンロードします。 + +|image2| + +CSVの内容 +-------- + +1行目はヘッダーです。 +2行目以降に追加ワードが記載されます。 + +:: + +"SuggestWord","Reading","Role","Label","Boost" +"fess","ふぇす","role1","label1","100" + +アップロード +========= + +CSV形式でワードを登録します。 + +|image3| + +CSVの内容 +-------- + +1行目はヘッダーです。 +2行目以降に追加ワードを記述します。 + +:: + +"SuggestWord","Reading","Role","Label","Boost" +"fess","ふぇす","role1","label1","100" + + +.. |image0| image:: ../../../resources/images/ja/15.10/admin/elevateword-1.png +.. |image1| image:: ../../../resources/images/ja/15.10/admin/elevateword-2.png +.. |image2| image:: ../../../resources/images/ja/15.10/admin/elevateword-3.png +.. |image3| image:: ../../../resources/images/ja/15.10/admin/elevateword-4.png diff --git a/ja/15.10/admin/esreq-guide.rst b/ja/15.10/admin/esreq-guide.rst new file mode 100644 index 000000000..7e8aef6df --- /dev/null +++ b/ja/15.10/admin/esreq-guide.rst @@ -0,0 +1,52 @@ +========================== +OpenSearchへのリクエスト +========================== + +概要 +==== + +このページでは、JSONファイルに記述したリクエストをOpenSearchに送信します。 + +|image0| + +この画面は左メニューにありません。表示するには、管理者としてログインした後、 ``/admin/sereq/`` をURLのパスとして入力してください。 +送信するには、管理者（ ``admin`` ロール）または ``admin-sereq`` ロールが必要です。 + +操作方法 +======== + +リクエストの送信 +---------------- + +OpenSearchに送信したいリクエストをJSONファイルとして作成し、「リクエストファイル」としてそのファイルを選択して「送信」ボタンをクリックすると、OpenSearchにリクエストが送信されます。 +レスポンスはファイルとしてダウンロードされます。 + +設定項目 +-------- + +リクエストファイル +:::::::::::::::::: + +リクエストを記述したファイルを指定します。 + +1行目に ``<メソッド> <パス>`` を半角スペース1つで区切って記述し、2行目以降にリクエストボディ（クエリーDSLなど）を記述します。 +メソッドには GET、POST、PUT、DELETE を指定できます。パスはOpenSearchに対するパスで、先頭の ``/`` は省略できます。 +たとえば、ファイルの内容は以下のようになります。 + +:: + + POST /_search + { + "query": { + "match_all": {} + } + } + +ボディの改行は取り除かれ、各行が連結されて送信されます。このため、1行に1つのJSONを並べる形式（ ``_bulk`` など）のリクエストは送信できません。 + +.. warning:: + + メソッドが PUT や DELETE の場合も、リクエストはそのままOpenSearchに送信されます。 + ファイルの内容によっては、 |Fess| が使用するインデックスの変更や削除など、データを失う操作になります。送信する前に内容を十分に確認してください。 + +.. |image0| image:: ../../../resources/images/ja/15.10/admin/esreq-1.png diff --git a/ja/15.10/admin/failureurl-guide.rst b/ja/15.10/admin/failureurl-guide.rst new file mode 100644 index 000000000..3d9cc3485 --- /dev/null +++ b/ja/15.10/admin/failureurl-guide.rst @@ -0,0 +1,66 @@ +====== +障害URL +====== + +概要 +==== + +ここでは、障害 URL について説明します。 +クロール時に取得できなかった URL が記録され、障害 URL として確認することができます。 + +管理方法 +====== + +表示方法 +------ + +障害 URL を確認するための一覧ページを開くには、左メニューの [システム情報 > 障害URL] をクリックします。 + +|image0| + +障害 URL の確認リンクをクリックすると、詳細が表示されます。 + +障害URLの詳細 +=========== + +障害URLの詳細ではクロール時に発生した例外が記録されます。 + +|image1| + +詳細の内容 +-------- + +URL +:::: + +例外が発生したURL。 + +スレッド名 +:::::::: + +クロールを実行していたスレッド名。 +ログファイルを確認するときに利用できます。 + +種別 +:::: + +例外の種別。 + +ログ +:::: + +例外の内容。 + +エラー回数 +:::::::: + +この例外が発生した回数。 + +最終アクセス日時 +:::::::::::: + +この例外が発生した時刻。 + + +.. |image0| image:: ../../../resources/images/ja/15.10/admin/failureurl-1.png +.. |image1| image:: ../../../resources/images/ja/15.10/admin/failureurl-2.png diff --git a/ja/15.10/admin/fileauth-guide.rst b/ja/15.10/admin/fileauth-guide.rst new file mode 100644 index 000000000..019426231 --- /dev/null +++ b/ja/15.10/admin/fileauth-guide.rst @@ -0,0 +1,85 @@ +========= +ファイル認証 +========= + +概要 +==== + +ここでは、ファイルを対象としたクロールに対してファイル認証が必要な場合の設定方法について説明します。 +|Fess| は FTP または Windows の共有フォルダーに対する認証に対応しています。 + +管理方法 +====== + +表示方法 +------ + +下図のファイル認証の設定を行うための一覧ページを開くには、左メニューの [クローラー > ファイル認証] をクリックします。 + +|image0| + +編集するには設定名をクリックします。 + +設定の作成 +-------- + +ファイル認証の設定ページを開くには新規作成ボタンをクリックします。 + +|image1| + +設定項目 +------ + +ホスト名 +:::::: + +認証が必要なサイトのホスト名を指定します。 +クロールするURLに書いたホスト名と同じ名前で指定してください。別の名前（たとえばIPアドレスと別名）で書いたURLには、この認証は使われません。 + +ポート +:::: + +認証が必要なサイトのポートを指定します。 +空欄にすると、一覧には「任意」と表示されます。空欄の意味はスキームによって異なります。 + +* FTP: 任意のポートのURLに使われます（URLにポートがない場合は21番として扱われます）。 +* SAMBA: ポートを書いていないURL（ ``smb://サーバー名/共有名/`` ）にだけ使われます。 ``smb://サーバー名:445/共有名/`` のようにポートを明示したURLには使われません。ポートを明示したURLをクロールする場合は、同じポートをここにも指定してください。 + +スキーム +:::::: + +認証方法を選択します。 +FTP または SAMBA (Windows共有フォルダー認証) を利用することができます。 + +ユーザー名 +:::::::: + +認証サイトにログインするためのユーザー名を指定します。 + +パスワード +:::::::: + +認証サイトにログインするためのパスワードを指定します。 + +パラメーター +::::::::: + +認証サイトにログインするために必要な設定値がある場合に設定します。SAMBA の場合、domainの値を設定することができます。設定する場合には以下のように記述します。 + +:: + + domain=FUGA + +ファイルクロール設定 +::::::::::::::: + +この認証設定を利用するクロール設定を指定します。 + +設定の削除 +-------- + +一覧ページの設定名をクリックし、削除ボタンをクリックすると確認画面が表示されます。 +削除ボタンを押すと設定が削除されます。 + +.. |image0| image:: ../../../resources/images/ja/15.10/admin/fileauth-1.png +.. |image1| image:: ../../../resources/images/ja/15.10/admin/fileauth-2.png diff --git a/ja/15.10/admin/fileconfig-guide.rst b/ja/15.10/admin/fileconfig-guide.rst new file mode 100644 index 000000000..b98cf4531 --- /dev/null +++ b/ja/15.10/admin/fileconfig-guide.rst @@ -0,0 +1,260 @@ +======================================== +ファイルクロール（ファイルサーバー検索） +======================================== + +概要 +==== + +ファイルクロールは、社内のファイルサーバーや Windows 共有フォルダー、クラウドストレージ上のドキュメントを |Fess| のインデックスに登録し、全文検索（ファイルサーバー検索）できるようにする機能です。Word・Excel・PowerPoint・PDF など多数のファイル形式に対応しています。 + +ファイルクロールの設定ページでは、ファイルシステム上や共有されているネットワーク上のフォルダーのファイルをクロールする設定を管理することができます。クロール対象は「パス」で指定するプロトコルによって決まります。 + +- ``file:/`` … ローカルまたはマウント済みのファイルシステム +- ``smb://`` … Windows ファイルサーバー／共有フォルダー（SMB/CIFS） +- ``smb1://`` … 旧来の SMB1 プロトコルを使用する Windows ファイルサーバー／共有フォルダー +- ``ftp://`` … FTP サーバー +- ``s3://`` … Amazon S3 バケット（ ``fess-storage-s3`` プラグインが必要） +- ``gcs://`` … Google Cloud Storage バケット（ ``fess-storage-gcs`` プラグインが必要） + +管理方法 +====== + +表示方法 +------ + +下図のファイルクロール設定を行うための一覧ページを開くには、左メニューの [クローラー > ファイルシステム] をクリックします。 + +|image0| + +編集するには設定名をクリックします。 + +設定の作成 +------- + +ファイルクロールの設定ページを開くには新規作成ボタンをクリックします。 + +|image1| + +設定項目 +------ + +名前 +:::: + +設定の名前です。 + +パス +:::: + +このパスでは、クロールを開始する場所を指定します（例: file:/, smb://, s3://, gcs://）。 + +クロール対象とするパス +::::::::::::::::: + +この項目で指定した正規表現(Javaフォーマット)にマッチするパスは |Fess| クローラーの対象となります。 + +クロール対象から除外するパス +::::::::::::::::::::: + +この項目で指定した正規表現(Javaフォーマット)にマッチするパスは |Fess| クローラーの対象となりません。 + +検索対象とするパス +:::::::::::::: + +この項目で指定した正規表現(Javaフォーマット)にマッチするパスは検索の対象となります。 + +検索対象から除外するパス +:::::::::::::::::: + +この項目で指定した正規表現(Javaフォーマット)にマッチするパスは検索の対象となりません。 + +設定パラメーター +:::::::::::: + +クロール設定情報を指定することができます。 + +``file:`` で始まるパス（ローカルまたはマウント済みのファイルシステム）のクロールでは、シンボリックリンクをたどるかどうかを ``client.followSymlink`` で指定できます。デフォルトは ``true`` （たどる）です。 ``false`` を指定すると、シンボリックリンクは対象から外れ、リンク先のファイルはリンク経由ではクロールされません（スキップしたリンクは ``fess-crawler.log`` に INFO レベルで記録されます）。リンクをたどると、リンク先のファイルがリンクを含む設定のパーミッションでもう一度登録されるため、リンク先よりも多くのユーザーが読める共有をクロールする場合は ``false`` を検討してください。 + +:: + + client.followSymlink=false + +深さ +:::: + +クロールするファイルシステム構造の深さを指定します。 + +最大アクセス数 +::::::::::: + +インデックスするパスの数を指定します。 + +スレッド数 +:::::::: + +この設定のために使用するスレッドの数を指定します。 + +間隔 +:::: + +スレッドがパスをクロールするごとに待機する時間を指定します。 + +ブースト値 +:::::::: + +ブースト値とは、この設定によってインデックスされたドキュメントの優先度です。 + +パーミッション +::::::::::: + +この設定のパーミッションを指定します。 +パーミッションの指定方法は、たとえば、developerグループに属するユーザーに検索結果を表示させるためには{group}developerと指定します。 +ユーザー単位の指定は{user}ユーザー名、ロール単位の指定は{role}ロール名、グループ単位の指定は{group}グループ名で指定します。 + +仮想ホスト +:::::::: + +仮想ホストのホスト名を指定します。 +詳しくは :doc:`設定ガイドの仮想ホスト <../config/security-virtual-host>` を参照してください。 + +状態 +:::: + +この設定が有効であるとき、デフォルトクローラーのジョブはこの設定を含んでクロールを行います。 + +説明 +:::: + +説明を入力できます。 + +設定の削除 +-------- + +一覧ページの設定名をクリックし、削除ボタンをクリックすると確認画面が表示されます。削除ボタンを押すと設定が削除されます。 + +例 +== + +ローカルファイルをクロール +-------------------- + +/home/share 下のファイルをクロールするならば、設定は以下のようになります。 + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - 名前 + - 値 + * - 名前 + - Share ディレクトリ + * - パス + - file:/home/share + +他のパラメーターはデフォルトの設定で構いません。 + +Windowsの共有フォルダーをクロール +--------------------------- + +\\SERVER\SharedFolder 下のファイルをクロールするならば、設定は以下のようになります。 + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - 名前 + - 値 + * - 名前 + - 共有フォルダー + * - パス + - smb://SERVER/SharedFolder/ + +共有フォルダーのアクセスに ユーザー名/パスワード が必要ならば、左メニューの [クローラー > ファイル認証] からファイル認証の設定を作成する必要があります。 +その際の設定は以下のようになります。 + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - 名前 + - 値 + * - ホスト名 + - SERVER + * - スキーム + - SAMBA + * - ユーザー名 + - (入力してください) + * - パスワード + - (入力してください) + +Amazon S3バケットをクロール +------------------------ + +my-bucket バケット下のファイルをクロールするならば、設定は以下のようになります。 + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - 名前 + - 値 + * - 名前 + - S3 バケット + * - パス + - s3://my-bucket/ + +S3へのアクセスには認証情報が必要です。「設定パラメーター」に以下を設定します。 + +:: + + client.endpoint=https://s3.ap-northeast-1.amazonaws.com + client.accessKey=YOUR_ACCESS_KEY + client.secretKey=YOUR_SECRET_KEY + client.region=ap-northeast-1 + +.. note:: + Amazon S3 と S3 互換ストレージへの対応は ``fess-storage-s3`` プラグインから提供されます。 + 配布物には同梱されていないため、管理画面の「システム > プラグイン」ページ、または + ``bin/fess-setup install plugin fess-storage-s3`` で導入してください。 + +Google Cloud Storageバケットをクロール +----------------------------------- + +my-gcs-bucket バケット下のファイルをクロールするならば、設定は以下のようになります。 + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - 名前 + - 値 + * - 名前 + - GCS バケット + * - パス + - gcs://my-gcs-bucket/ + +GCSへのアクセスには認証情報が必要です。「設定パラメーター」に以下を設定します。 + +:: + + client.projectId=your-project-id + client.credentialsFile=/path/to/service-account.json + +.. note:: + Google Cloud Storage への対応は ``fess-storage-gcs`` プラグインから提供されます。配布物には + 同梱されていないため、管理画面の「システム > プラグイン」ページ、または + ``bin/fess-setup install plugin fess-storage-gcs`` で導入してください。 + +関連ページ +========== + +- :doc:`../config/crawler-basic` +- :doc:`fileauth-guide` +- :doc:`../config/datastore/ds-overview` +- :doc:`../config/search-basic` +- :doc:`../user/index` + + +.. |image0| image:: ../../../resources/images/ja/15.10/admin/fileconfig-1.png +.. |image1| image:: ../../../resources/images/ja/15.10/admin/fileconfig-2.png +.. pdf :height: 940 px diff --git a/ja/15.10/admin/general-guide.rst b/ja/15.10/admin/general-guide.rst new file mode 100644 index 000000000..bd2d5bb82 --- /dev/null +++ b/ja/15.10/admin/general-guide.rst @@ -0,0 +1,679 @@ +==== +全般 +==== + +概要 +==== + +この管理ページでは、 |Fess| の設定を管理することができます。 +|Fess| を再起動せずに |Fess| の様々な設定を変更できます。 + +設定内容 +====== + +システム +------ + +|image0| + +JSONレスポンス +:::::::::::: + +JSON APIを有効にするかを指定します。 + +ログインが必要 +::::::::::: + +検索機能をログインを必須にするかを指定します。 + +ログインリンク表示 +:::::::::::::: + +検索画面でログインページヘのリンクを表示するかどうかを設定します。 + +重複結果の折り畳み +:::::::::::::: + +重複結果を折り畳みを有効にするかを設定します。 + +``search_engine.type`` が ``vanilla`` または ``aws`` の場合、この項目は表示されず、折り畳みは常に無効になります（ :doc:`../config/search-engine-type` を参照）。 + +サムネイル表示 +::::::::::: + +サムネイル表示を有効にするかを設定します。 + +システムプロパティ +:::::::::::::: + +|Fess| のシステムプロパティを設定します。 +``key=value`` の形式で1行ずつ指定します。 + +デフォルトのラベル値 +::::::::::::::: + +デフォルトで検索条件に追加するラベル値を記述します。 +ロールやグループ単位で指定する場合は、「role:admin=label1」のように role: または group: を付加して指定します。 + +デフォルトのソート値 +::::::::::::::: + +デフォルトで検索条件に追加するソート値を記述します。 +ロールやグループ単位で指定する場合は、「role:admin=content_length.desc」のように role: または group: を付加して指定します。 + +仮想ホスト +:::::::: + +仮想ホストを設定します。 +詳しくは :doc:`設定ガイドの仮想ホスト <../config/security-virtual-host>` を参照してください。 + +人気ワードのレスポンス +::::::::::::::::: + +人気ワード APIを有効にするかを指定します。 + +CSVファイルのエンコード +:::::::::::::::::: + +ダウンロードするCSVファイルのエンコーディングを指定します。 + +検索パラメーターの追加 +::::::::::::::::: + +検索結果表示にパラメーターを渡す場合に有効にします。 + +検索ファイルプロキシ +::::::::::::::: + +検索結果のファイルプロキシを有効にするかを指定します。 + +ブラウザロケールを使用 +::::::::::::::::: + +検索時にブラウザのロケールを使用するかを指定します。 + +SSOタイプ +:::::::: + +シングルサインオンのタイプを指定します。 + +- **None**: SSOを使用しない +- **OpenID Connect**: OpenID Connectを使用（ ``fess-sso-oidc`` プラグインが必要） +- **SAML**: SAMLを使用（ ``fess-sso-saml`` プラグインが必要） +- **SPNEGO**: SPNEGOを使用（ ``fess-sso-spnego`` プラグインが必要） +- **Entra ID**: Microsoft Entra IDを使用（ ``fess-sso-entraid`` プラグインが必要） + +クローラー +-------- + +|image1| + +最終更新日時の確認 +:::::::::::::: + +差分クロールを行う場合に有効にします。 + +HTTP/HTTPS の URL では、HEAD の ``Last-Modified`` で判断できない場合（索引に最終更新日時がない、HEAD の応答に ``Last-Modified`` がない、HEAD が 200/404 以外を返した）に、GET に ``If-None-Match`` （索引に保存した ``ETag`` ）や ``If-Modified-Since`` を付ける条件付き GET を行います。サーバーが ``304 Not Modified`` を返したページは、更新されていないページと同じく取得し直されません。設定を変えた後などにすべてを取得し直すには、この設定を無効にしてクロールします。 + +同時クローラー設定 +:::::::::::::: + +同時に実行するクロール設定数を指定します。 + +ユーザーエージェント +::::::::::::::: + +クローラーが使用するユーザーエージェント名を指定します。 + +以前のドキュメントを削除 +:::::::::::::::::: + +ドキュメントの有効期限を日数で指定します。クロールで登録・更新されたドキュメントには、クロールを開始した時刻からこの日数後が有効期限として設定され、次のクロールで再び見つかったドキュメントは有効期限が延長されます。有効期限を過ぎたドキュメントは、スケジューラーの Doc Purger ジョブ（デフォルトでは毎分実行）がインデックスから削除します。 + +デフォルトは ``3`` 、指定できる値は ``-1`` から ``1000`` です。 ``-1`` を指定すると、以後のクロールで登録・更新されるドキュメントには有効期限を設定しません（すでに設定された有効期限は延長されません）。 + +除外するエラーの種別 +::::::::::::::: + +しきい値を超える障害URLはクロール対象から除外されますが、ここで指定された例外名などはしきい値を超える障害URLでもクロール対象になります。 + +障害数のしきい値 +:::::::::::: + +クロール対象のドキュメントがここで指定された回数以上に障害URLに記録された場合は次回のクロールで対象外になります。 + +ロギング +------ + +検索ログ +:::::: + +検索ログの記録を有効にするかを指定します。 + +ユーザログ +:::::::: + +ユーザーログの記録を有効にするかを指定します。 + +お気に入りログ +::::::::::: + +お気に入りログの記録を有効にするかを指定します。 + +以前の検索ログを削除 +::::::::::::::: + +指定された日数以前の検索ログを削除します。デフォルトは ``-1`` で、 ``-1`` の場合はログを削除せず、いつまでも保持します。 +クリックログ、お気に入りログ、チャットログも、この日数で削除されます。 + +以前のジョブログを削除 +::::::::::::::::: + +指定された日数以前のジョブログを削除します。デフォルトは ``-1`` で、 ``-1`` の場合は削除しません。 + +以前のユーザーログを削除 +:::::::::::::::::: + +指定された日数以前のユーザーログを削除します。デフォルトは ``-1`` で、 ``-1`` の場合は削除しません。 + +ログを削除するボット名 +::::::::::::::::: + +検索ログから除外するボット名を指定します。 + +ログレベル +:::::::: + +fess.logのログレベルを指定します。 + +サジェスト +-------- + +検索語でサジェスト +:::::::::::::: + +検索ログからサジェスト候補を生成するかを指定します。 + +ドキュメントでサジェスト +:::::::::::::::::: + +インデックスしたドキュメントからサジェスト候補を生成するかを指定します。 + +以前のサジェスト情報を削除 +:::::::::::::::::::: + +指定された日数以前のサジェストデータを削除します。 + +LDAP +---- + +|image2| + +LDAP URL +:::::::: + +LDAPサーバのURLを指定します。 + +Base DN +::::::: + +検索画面にログインするベースの識別名を指定します。 + +Bind DN +::::::: + +管理者のBind DNを指定します。 + +パスワード +:::::::: + +Bind DNのパスワードを指定します。 + +User DN +::::::: + +ユーザーの識別名を指定します。 + +アカウントフィルター +::::::::::::::: + +ユーザーのCommon Nameやuidなど指定します。 + +グループフィルター +:::::::::::::: + +取得したいグループのフィルター条件を指定します。 + +memberOf属性 +::::::::::: + +LDAPサーバで利用できるmemberOf属性名を指定します。 +Active Directoryの場合、memberOfです。 +その他のLDAPサーバではisMemberOfの場合もあります。 + +セキュリティ認証 +:::::::::::: + +LDAPのセキュリティ認証方式を指定します（例: simple）。 + +初期コンテキストファクトリ +:::::::::::::::::::::: + +LDAPの初期コンテキストファクトリクラスを指定します（例: com.sun.jndi.ldap.LdapCtxFactory）。 + +OpenID Connect +-------------- + +|image3| + +クライアントID +::::::::::: + +OpenID ConnectプロバイダーのクライアントIDを指定します。 + +クライアントシークレット +:::::::::::::::::: + +OpenID Connectプロバイダーのクライアントシークレットを指定します。 + +認証サーバーURL +:::::::::::: + +OpenID Connectの認証サーバーURLを指定します。 + +トークンサーバーURL +:::::::::::::: + +OpenID ConnectのトークンサーバーURLを指定します。 + +リダイレクトURL +:::::::::::: + +OpenID ConnectのリダイレクトURLを指定します。 + +スコープ +:::::: + +OpenID Connectのスコープを指定します。 + +ベースURL +:::::::: + +OpenID ConnectのベースURLを指定します。 + +デフォルトグループ +:::::::::::::: + +OpenID Connect認証時にユーザーに割り当てるデフォルトグループを指定します。 + +デフォルトロール +:::::::::::: + +OpenID Connect認証時にユーザーに割り当てるデフォルトロールを指定します。 + +SAML +---- + +|image4| + +IdPエンティティID +::::::::::::: + +IdP（Identity Provider）のエンティティIDを指定します。 + +IdP SSO URL +::::::::::: + +IdPのシングルサインオンサービスURLを指定します。 + +IdP SLO URL +::::::::::: + +IdPのシングルログアウトサービスURLを指定します。 + +IdP X.509証明書 +::::::::::::: + +IdPのSAMLアサーション署名検証に使用するX.509公開鍵証明書を指定します。 +``-----BEGIN CERTIFICATE-----`` および ``-----END CERTIFICATE-----`` の行を含まず、Base64エンコードされた内容のみを指定します。 + +SPベースURL +:::::::::: + +SAML Service ProviderのベースURLを指定します。 + +SPエンティティID +::::::::::::: + +SP（Service Provider）のエンティティIDを指定します。 +``SPベースURL`` を設定している場合は自動的に設定されます。 + +SP ACS URL +:::::::::: + +SAMLアサーションを受信するAssertion Consumer Service（ACS）のURLを指定します。 +``SPベースURL`` を設定している場合は自動的に設定されます。 + +SP SLO URL +:::::::::: + +SPのシングルログアウトサービスURLを指定します。 +``SPベースURL`` を設定している場合は自動的に設定されます。 + +SP NameIDフォーマット +::::::::::::::::::: + +SAMLアサーションで使用するNameIDのフォーマットを指定します。 + +グループ属性名 +::::::::::: + +SAMLレスポンスからグループを取得するための属性名を指定します。 + +ロール属性名 +::::::::: + +SAMLレスポンスからロールを取得するための属性名を指定します。 + +デフォルトグループ +:::::::::::::: + +SAML認証時にユーザーに割り当てるデフォルトグループを指定します。 + +デフォルトロール +:::::::::::: + +SAML認証時にユーザーに割り当てるデフォルトロールを指定します。 + +SPNEGO +------ + +|image5| + +.. note:: + SPNEGO関連の設定は基盤ライブラリ内でプロセス全体に共有されるため、変更を反映するには |Fess| の再起動が必要です。 + +Krb5設定 +::::::: + +Kerberos 5設定ファイルのパスを指定します。 + +ログイン設定 +::::::::: + +JAAS（Java Authentication and Authorization Service）ログイン設定ファイルのパスを指定します。 + +ログインクライアントモジュール +:::::::::::::::::::::::: + +JAASのクライアントログインモジュール名を指定します。 + +ログインサーバーモジュール +:::::::::::::::::::::: + +JAASのサーバーログインモジュール名を指定します。 + +事前認証ユーザー名 +:::::::::::::: + +SPNEGO事前認証に使用するユーザー名を指定します。 +ユーザー名とパスワードを空欄にすると、keytabベースのサーバーログインが使用されます。 + +事前認証パスワード +:::::::::::::: + +SPNEGO事前認証に使用するパスワードを指定します。 + +Basic認証許可 +:::::::::: + +Basic認証によるフォールバックを許可するかを指定します。 + +非セキュアBasic認証許可 +::::::::::::::::: + +非セキュア（HTTP）接続でのBasic認証を許可するかを指定します。 +資格情報が平文で送信されるのを防ぐため、デフォルトでは無効です（HTTPS接続ではBasic認証が提供されます）。 + +NTLMプロンプト +::::::::::: + +NTLMプロンプトを有効にするかを指定します。 + +ローカルホスト許可 +:::::::::::::: + +ローカルホストからのアクセスを許可するかを指定します。 +有効にすると同一ホストからのリクエストがKerberos検証なしでサーバーOSのユーザーとして認証されるため、セキュリティ上の理由からデフォルトでは無効です。 + +委任許可 +:::::: + +Kerberos委任を許可するかを指定します。 + +ロガーレベル +::::::::: + +SPNEGO認証に関するログの出力レベルを0〜7の数値で指定します。 +空欄または数値以外の値を指定した場合は、自動的にログレベルが判定されます。 + +Entra ID +-------- + +|image6| + +テナント (IDまたはドメイン) +:::::::::::::::::::::::: + +Microsoft Entra IDのテナントIDまたはドメインを指定します。 + +認証局 +::::: + +Microsoft Entra IDの認証局URLを指定します。 + +クライアントID +::::::::::: + +Microsoft Entra IDのアプリケーション（クライアント）IDを指定します。 + +クライアントシークレット +:::::::::::::::::: + +Microsoft Entra IDのクライアントシークレットを指定します。 + +応答URL +:::::: + +Microsoft Entra IDの応答（リダイレクト）URLを指定します。 + +ステートTTL +::::::::: + +認証ステートの有効期間（TTL）を指定します。 + +パーミッションフィールド +:::::::::::::::::: + +Entra IDからパーミッション情報を取得するフィールドを指定します。 + +デフォルトグループ +:::::::::::::: + +Entra ID認証時にユーザーに割り当てるデフォルトグループを指定します。 + +デフォルトロール +:::::::::::: + +Entra ID認証時にユーザーに割り当てるデフォルトロールを指定します。 + +ドメインサービス使用 +::::::::::::::: + +Entra IDドメインサービスを使用するかを指定します。 + +お知らせ表示 +--------- + +|image7| + +.. note:: + + お知らせにはHTMLを記述できます。検索テーマがお知らせを表示するときは、許可リストにあるタグと属性だけが残り、`` + + + +既にサイトでjQueryを利用している場合はjQueryのscript要素は追加する必要はありません。 + +サジェストは |Fess| のサジェストAPI（ ``/api/v2/suggest-words`` ）を利用します。 +``url`` は構築した |Fess| サーバのURLに合わせて変更してください。 + +``suggestor`` に指定できる主なオプションは以下のとおりです。 + +.. list-table:: suggestor の主なオプション + :header-rows: 1 + :widths: 25 75 + + * - オプション + - 説明 + * - ``ajaxinfo.url`` + - サジェストAPIのURL。 |Fess| サーバの ``/api/v2/suggest-words`` を指定します。 + * - ``ajaxinfo.fn`` + - サジェスト対象とするフィールド名の配列。初期値の ``["_default", "content", "title"]`` のまま利用できます。 + * - ``ajaxinfo.num`` + - 表示する候補の最大件数。 + * - ``ajaxinfo.lang`` + - サジェスト候補を絞り込む言語（省略可能）。 + * - ``minterm`` + - サジェストを開始する最小の入力文字数。 + * - ``adjustWidthVal`` + - サジェスト表示領域の幅を入力欄の幅に加算して調整する値（ピクセル）。 + * - ``searchForm`` + - 候補を選択したときに送信する検索フォームの要素。 + * - ``boxCssInfo`` + - サジェスト表示領域に適用するCSS。 + * - ``listSelectedCssInfo`` + - 選択中の候補に適用するCSS（省略可能）。 + * - ``listDeselectedCssInfo`` + - 非選択の候補に適用するCSS（省略可能）。 + +"z-index"で指定する値は、他の要素と重ならない値を指定してください。 + +.. note:: + 検索フォームを |Fess| サーバとは異なるドメインのページに配置する場合、サジェストAPIへのリクエストはクロスオリジン通信になります。 + |Fess| は初期設定で ``api.cors.allow.origin=*`` を許可しているため、そのまま利用できます。 + アクセスを制限したい場合は ``fess_config.properties`` の ``api.cors.allow.origin`` を変更してください。 + +.. note:: + ``/api/v2/suggest-words`` は |Fess| 本体が提供するAPIです。 + 以前のバージョンで利用していた ``/api/v1/suggest-words`` は |Fess| 本体からは提供されなくなり、利用するには ``fess-webapp-v1-api`` プラグインのインストールが必要です。 + 新規に構築する場合は ``/api/v2/suggest-words`` を利用してください。 diff --git a/ja/15.10/config/search-geosearch.rst b/ja/15.10/config/search-geosearch.rst new file mode 100644 index 000000000..03f1b79ca --- /dev/null +++ b/ja/15.10/config/search-geosearch.rst @@ -0,0 +1,353 @@ +============ +位置情報検索 +============ + +概要 +==== + +|Fess| は、緯度経度の位置情報を持つドキュメントに対して、地理的な範囲を指定した検索を実行できます。 +この機能を使用することで、特定の地点から一定の距離内にあるドキュメントを検索したり、 +Googleマップなどの地図サービスと連携した検索システムを構築できます。 + +内部的には、OpenSearch の geo-distance クエリを使用して、指定した中心点から指定した距離以内に +存在するドキュメントを絞り込みます。 + +ユースケース +============ + +位置情報検索は、以下のような用途に活用できます。 + +- 店舗検索: ユーザーの現在地から近い店舗を検索 +- 不動産検索: 特定の駅や施設から一定距離内の物件を検索 +- イベント検索: 指定した場所周辺のイベント情報を検索 +- 施設検索: 観光スポットや公共施設の近隣検索 + +設定方法 +======== + +インデックス生成時の設定 +------------------------ + +位置情報フィールドの定義 +~~~~~~~~~~~~~~~~~~~~~~~~ + +|Fess| では、位置情報を格納するフィールドとして ``location`` が標準で定義されています。 +このフィールドは OpenSearch の ``geo_point`` 型として設定されています。 + +位置情報の登録形式 +~~~~~~~~~~~~~~~~~~ + +インデックス生成時に、緯度と経度をカンマ区切りで ``location`` フィールドに設定します。 + +**形式:** + +:: + + 緯度,経度 + +**例:** + +:: + + 45.17614,-93.87341 + +.. note:: + 緯度は -90 から 90 の範囲、経度は -180 から 180 の範囲で指定します。 + +データストアクロールでの設定例 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +データストアクロールを使用する場合、位置情報を持つデータソースから ``location`` フィールドに +緯度経度を設定します。 + +**例: データベースからの取得** + +緯度・経度を別々のカラムで保持している場合は、SQL でカンマ区切りの文字列に結合します。 +データストアのパラメーターは 1 行が 1 項目なので、 ``sql=`` に続けて SQL を 1 行で記述します +（改行して複数行に分けると、1 行目の ``SELECT`` だけが SQL として扱われ、構文エラーになります）。 + +:: + + sql=SELECT id, name, address, CONCAT(latitude, ',', longitude) AS location FROM stores + +データストアの設定スクリプトで、取得した値を ``location`` フィールドにマッピングします。 +データベースのデータストアでは、SQL の列名（``AS`` で付けた別名を含む）が、そのままスクリプトの変数名になります。 +``data.`` のような接頭辞は付きません。 + +:: + + location=location + +スクリプトでの位置情報追加 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +クロール設定のスクリプト機能を使用して、ドキュメントに位置情報を動的に追加することもできます（既定はJavaScript。Groovyを選択することもできます）。 +フィールド名に直接値を代入します。 + +:: + + // 緯度経度を location フィールドに設定 + location="35.681236,139.767125" + +スクリプトの詳細については :doc:`scripting-overview` を参照してください。 + +検索時の設定 +------------ + +位置情報検索を実行するには、リクエストパラメーターで検索の中心点と範囲を指定します。 + +リクエストパラメーター +~~~~~~~~~~~~~~~~~~~~~~ + +位置情報検索のパラメーター名は ``geo.<フィールド名>.point`` および ``geo.<フィールド名>.distance`` +の形式です。 ``<フィールド名>`` には ``query.geo.fields`` で設定されたフィールド名が入ります +（既定は ``location`` ）。 + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - パラメーター名 + - 説明 + * - ``geo.location.point`` + - 検索の中心となる地点の緯度・経度（カンマ区切り。例: ``35.681236,139.767125`` ） + * - ``geo.location.distance`` + - 中心点からの検索半径（単位付き。例: ``10km`` ） + +.. note:: + ``point`` と ``distance`` は対で指定します。 ``distance`` を指定しない ``point`` は無視されます。 + また、 ``point`` の値は「緯度,経度」の2つの数値で構成されている必要があり、形式が不正な場合は + エラーになります。 + +.. note:: + 位置情報検索は検索語 ``q`` に対する絞り込みとして動作します。 ``q`` が空の場合は検索自体が実行されず、 + 結果は 0 件になります。位置情報検索のリクエストには、検索語を指定してください。 + +.. note:: + 同じフィールドに対して複数の ``point`` を指定した場合は OR 条件（いずれかの範囲内）、 + 複数のフィールドに対して指定した場合は AND 条件（すべての範囲内）として扱われます。 + +距離の単位 +~~~~~~~~~~ + +距離には以下の単位を使用できます。 + +- ``km``: キロメートル +- ``m``: メートル +- ``mi``: マイル +- ``yd``: ヤード + +.. note:: + 距離の値は OpenSearch にそのまま渡されるため、上記以外にも OpenSearch がサポートする単位 + （ ``cm`` 、 ``mm`` 、 ``ft`` 、 ``in`` 、 ``nmi`` など）を使用できます。 + +検索結果の並び順 +~~~~~~~~~~~~~~~~ + +位置情報検索は、指定した範囲内のドキュメントに結果を絞り込む **フィルター** として動作します。 +検索スコア（関連度）には影響せず、中心点からの距離が近い順に並べ替えるわけではありません。 +結果は通常どおり関連度順（または ``sort`` パラメーターで指定した順序）で返ります。 + +.. note:: + |Fess| は距離によるソート（近い順の並べ替え）には対応していません。 + 距離順に表示したい場合は、レスポンスに含めた緯度経度をもとに、クライアント側で並べ替えてください。 + +検索例 +====== + +基本的な検索 +------------ + +東京駅（35.681236, 139.767125）から半径10km以内のドキュメントを検索する場合: + +:: + + http://localhost:8080/search?q=検索キーワード&geo.location.point=35.681236,139.767125&geo.location.distance=10km + +現在地周辺の検索 +---------------- + +ユーザーの現在地から1km以内を検索する場合: + +:: + + http://localhost:8080/search?q=ラーメン&geo.location.point=35.681236,139.767125&geo.location.distance=1km + +APIでの使用 +----------- + +v2 の JSON 検索 API（ ``/api/v2/search`` ）でも位置情報検索を使用できます。 +``geo.location.point`` と ``geo.location.distance`` をリクエストパラメーターとして指定します。 + +:: + + curl "http://localhost:8080/api/v2/search?q=ホテル&geo.location.point=35.681236,139.767125&geo.location.distance=5km" + +検索結果は共通エンベロープの ``response.data`` 配列で返ります。API の詳細は :doc:`../api/api-search` +および :doc:`../api/api-overview` を参照してください。 + +.. note:: + ``location`` フィールドは、既定では API レスポンスに含まれません。検索結果に緯度経度を含めたい場合は、 + ``fess_config.properties`` に次の 2 つの設定を追加して、 |Fess| を再起動してください。 + ``query.additional.response.fields`` は検索エンジンから取得するフィールドを追加し、 + ``query.additional.api.response.fields`` は API レスポンスに出力するフィールドを許可します。 + どちらか一方だけでは ``location`` はレスポンスに含まれません。 + + :: + + query.additional.response.fields=location + query.additional.api.response.fields=location + +フィールド名のカスタマイズ +========================== + +デフォルトのフィールド名変更 +---------------------------- + +位置情報検索で使用するフィールド名を変更する場合は、 +``fess_config.properties`` で以下の設定を変更します。 + +:: + + query.geo.fields=location + +複数のフィールド名を指定する場合は、カンマ区切りで指定します。 + +:: + + query.geo.fields=location,geo_point,coordinates + +.. note:: + - リクエストパラメーター名は設定したフィールド名に連動します。たとえば + ``query.geo.fields=coordinates`` と設定した場合は、 ``geo.coordinates.point`` および + ``geo.coordinates.distance`` を指定します。 + - ここで指定する各フィールドは、インデックスのマッピングで ``geo_point`` 型として + 定義されている必要があります。 + +実装例 +====== + +Webアプリケーションでの実装 +--------------------------- + +JavaScriptで現在地を取得して検索する例: + +.. code-block:: javascript + + // ブラウザのGeolocation APIで現在地を取得 + navigator.geolocation.getCurrentPosition(function(position) { + const latitude = position.coords.latitude; + const longitude = position.coords.longitude; + const distance = "5km"; + + // 検索URLの構築（検索語 q は省略できません） + const searchUrl = `/search?q=${encodeURIComponent('店舗')}&geo.location.point=${latitude},${longitude}&geo.location.distance=${distance}`; + + // 検索実行 + window.location.href = searchUrl; + }); + +Googleマップとの連携 +-------------------- + +検索結果をGoogleマップ上にマーカーで表示する例: + +.. note:: + この例では検索結果から ``location`` フィールドを参照します。事前に + ``query.additional.response.fields=location`` と ``query.additional.api.response.fields=location`` を + 設定して、レスポンスに緯度経度を含めておく必要があります。 + +.. code-block:: javascript + + // 地図の初期化 + const map = new google.maps.Map(document.getElementById('map'), { + center: {lat: 35.681236, lng: 139.767125}, + zoom: 13 + }); + + // Fess の v2 検索 API で位置情報検索を実行 + fetch('/api/v2/search?q=店舗&geo.location.point=35.681236,139.767125&geo.location.distance=5km') + .then(response => response.json()) + .then(json => { + // 検索結果（response.data 配列）をマーカーとして表示 + json.response.data.forEach(doc => { + if (doc.location) { + const [lat, lng] = doc.location.split(',').map(Number); + new google.maps.Marker({ + position: {lat: lat, lng: lng}, + map: map, + title: doc.title + }); + } + }); + }); + +パフォーマンス最適化 +==================== + +インデックス設定の確認 +---------------------- + +位置情報フィールドは、インストール先の +``app/WEB-INF/classes/fess_indices/fess/doc.json`` で ``geo_point`` 型として定義されています。 + +:: + + "location": { + "type": "geo_point" + } + +``geo_point`` 型のフィールドは BKD ツリーでインデックスされるため、geo-distance クエリは +効率的に実行されます。 + +検索範囲とレスポンスの最適化 +---------------------------- + +検索半径を大きくすると、範囲内に該当するドキュメント数が増え、結果の取得・描画に時間が +かかる場合があります。 + +- 用途に応じて適切な検索半径を設定してください。 +- 地図表示などで多くの結果を扱う場合は、ページサイズ（ ``num`` パラメーター）を調整して + 取得件数を制限してください。 + +トラブルシューティング +====================== + +位置情報検索が動作しない +------------------------ + +1. ``location`` フィールドにデータが正しく格納されているか確認してください。 +2. 緯度経度の形式が正しいか確認してください（ ``緯度,経度`` のカンマ区切り。値が2つでない場合はエラーになります）。 +3. OpenSearch のインデックスマッピングで ``location`` が ``geo_point`` 型として定義されているか確認してください。 +4. ``point`` と ``distance`` の両方を指定しているか確認してください（ ``distance`` のない ``point`` は無視されます）。 + +検索結果が返ってこない +---------------------- + +1. 指定した距離の範囲内にドキュメントが存在するか確認してください。 +2. 緯度経度の値が正しい範囲内（緯度: -90〜90, 経度: -180〜180）か確認してください。 +3. 距離の単位が正しく指定されているか確認してください。 + +APIレスポンスに位置情報が含まれない +---------------------------------- + +``location`` フィールドは既定では API レスポンスに含まれません。 +検索結果に緯度経度を含めるには、 ``fess_config.properties`` に +``query.additional.response.fields=location`` と ``query.additional.api.response.fields=location`` +の両方を設定して、 |Fess| を再起動してください。 + +位置情報が正しく登録されない +---------------------------- + +1. クロール時に ``location`` フィールドが正しく設定されているか確認してください。 +2. データソースの緯度経度が正しく取得できているか確認してください。 +3. スクリプトで位置情報を設定する場合、 ``緯度,経度`` の文字列形式になっているか確認してください。 + +参考情報 +======== + +位置情報検索の詳細については、以下のリソースを参照してください。 + +- `OpenSearch Geo Queries `_ +- `OpenSearch Geo Point `_ +- `Geolocation API (MDN) `_ diff --git a/ja/15.10/config/search-scroll.rst b/ja/15.10/config/search-scroll.rst new file mode 100644 index 000000000..2a60d84f7 --- /dev/null +++ b/ja/15.10/config/search-scroll.rst @@ -0,0 +1,455 @@ +================== +検索結果の一括取得 +================== + +概要 +==== + +|Fess| の通常の検索では、ページング機能により一定数の検索結果のみが表示されます。 +すべての検索結果を一括で取得したい場合は、スクロール検索(Scroll Search)機能を利用します。 + +この機能は、データの一括エクスポートやバックアップ、大量データの分析など、 +すべての検索結果を処理する必要がある場合に有用です。 + +ユースケース +============ + +スクロール検索は、以下のような用途に適しています。 + +- 検索結果の全件エクスポート +- データ分析用の大量データ取得 +- バッチ処理でのデータ取得 +- 外部システムへのデータ同期 +- レポート生成用のデータ収集 + +.. warning:: + スクロール検索は大量のデータを返すため、通常の検索と比較して + サーバーリソースを多く消費します。必要な場合のみ有効化してください。 + +設定方法 +======== + +スクロール検索の有効化 +---------------------- + +デフォルトでは、セキュリティとパフォーマンスの観点からスクロール検索は無効になっています。 +有効にするには、 ``app/WEB-INF/classes/fess_config.properties`` (RPM/DEB パッケージの場合は +``/etc/fess/fess_config.properties`` )で以下の設定を変更します。 + +:: + + api.search.scroll=true + +.. note:: + 設定変更後は、|Fess| を再起動する必要があります。 + +スクロールコンテキストの有効期間 +-------------------------------- + +スクロール検索のスクロールコンテキストの有効期間は、|Fess| 内部で ``1m`` (1分)に固定されています。 +この値は ``fess_config.properties`` から変更することはできません。 + +.. note:: + ``index.scroll.search.timeout`` という設定がありますが、これはインデックスの更新・削除を + 伴う内部処理(update by query / delete by query)で使用されるものであり、本機能(検索の + スクロール)のタイムアウトには影響しません。 + +レスポンスフィールドの設定 +-------------------------- + +検索結果のレスポンスに含めるフィールドをカスタマイズできます。 +デフォルトで多数のフィールドが返されますが、追加のフィールドを指定することもできます。 + +:: + + query.additional.scroll.response.fields=content + query.additional.api.response.fields=content + +複数のフィールドを指定する場合は、カンマ区切りで列挙します。 + +.. note:: + ``content`` フィールドはデフォルトのレスポンスには含まれません。全文を取得するには、 + 上記の2つの設定が両方とも必要です。\ ``query.additional.scroll.response.fields`` はインデックスから取得する + フィールドを追加し、\ ``query.additional.api.response.fields`` はAPIレスポンスへの出力を許可するフィールドを + 追加します。どちらか一方だけでは ``content`` は出力されません。 + +使用方法 +======== + +基本的な使用方法 +---------------- + +スクロール検索へのアクセスは、以下のURLで実行します。 + +:: + + http://localhost:8080/api/v2/documents/all?q=検索キーワード + +検索結果は NDJSON(Newline Delimited JSON)形式で返却されます。 +1行ごとに1つのドキュメントがJSON形式で出力されます。 + +**例:** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=Fess" + +リクエストパラメータ +-------------------- + +スクロール検索では、以下のパラメータを使用できます。 + +.. note:: + スクロール検索は GET メソッドのみ対応しています。 ``POST`` などの状態を変更するメソッドでは + CSRF トークンの検証が先に行われるため、有効な ``X-Fess-CSRF-Token`` ヘッダーが無いリクエストには + ``403 Forbidden`` （ ``forbidden`` ）が返されます（ :doc:`../api/api-overview` を参照）。 + 有効なトークンを付けた場合は ``405 Method Not Allowed`` （ ``method_not_allowed`` ）が返されます。 + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - パラメータ名 + - 説明 + * - ``q`` + - 検索クエリ(必須) + * - ``num`` + - 1回のスクロールで取得する件数(デフォルト: 10、最大: 100) + * - ``fields.label`` + - ラベルによるフィルタリング + +.. note:: + ``num`` の最大値は ``paging.search.page.max.size`` (デフォルト: 100)で制御されます。 + 最大値を超える値を指定した場合、自動的に最大値に切り詰められます。 + デフォルト値は ``paging.search.page.size`` (デフォルト: 10)が使用されます。 + ``num`` に 0 以下の値を指定した場合は、エラー(``INVALID_REQUEST``)が返されます。 + +検索クエリの指定 +---------------- + +通常の検索と同じように、検索クエリを指定できます。 + +**例: キーワード検索** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=検索エンジン" + +**例: フィールド指定検索** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=title:Fess" + +**例: 全件取得(検索条件なし)** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=*:*" + +取得件数の指定 +-------------- + +1回のスクロールで取得する件数を変更できます。 + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=Fess&num=100" + +.. note:: + ``num`` パラメータを大きくしすぎると、メモリ使用量が増加します。 + デフォルトの最大値は100です。より大きな値が必要な場合は + ``paging.search.page.max.size`` の設定を変更してください。 + +ラベルによるフィルタリング +-------------------------- + +特定のラベルに属するドキュメントのみを取得できます。 + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=*:*&fields.label=public" + +アクセス制御について +-------------------- + +.. note:: + スクロール検索でも、通常の検索と同様にロールベースのアクセス制御(RBAC)が適用されます。 + リクエストのロール情報に基づいてアクセス可能なドキュメントのみが返されるため、 + 閲覧権限のないドキュメントは結果に含まれません。 + +.. warning:: + スクロール検索のエンドポイントは、デフォルトでは認証を要求しません(誰でもアクセスできます)。 + ただし、返されるドキュメントは上記のロールベースのアクセス制御によってフィルタリングされます。 + エンドポイント自体へのアクセスを制限したい場合は、リバースプロキシ等でIPアドレス制限や + 認証を設定してください。 + +レスポンス形式 +============== + +NDJSON形式 +---------- + +スクロール検索のレスポンスは、NDJSON(Newline Delimited JSON)形式で返されます。 +Content-Type は ``application/x-ndjson; charset=UTF-8`` です。 +各行は ``{"data": {...}}`` の形式でラップされた1つのドキュメントを表します。 + +**例:** + +:: + + {"data":{"url":"http://example.com/page1","title":"Page 1","digest":"..."}} + {"data":{"url":"http://example.com/page2","title":"Page 2","digest":"..."}} + {"data":{"url":"http://example.com/page3","title":"Page 3","digest":"..."}} + +.. note:: + 各ドキュメントは ``data`` キーの下に格納されます。クライアント側では各行をパースした後、 + ``data`` キーの値を参照してください。 + +エラー時の動作 +-------------- + +ストリームの送信開始後にサーバー側でエラーが発生した場合、レスポンスの最終行に +以下のようなエラー終端行が出力されます。 + +:: + + {"error":{"code":"internal_error","message":"stream error"}} + +.. note:: + クライアント側では、最終行に ``error`` キーが含まれているかを確認することで、 + 「ストリームが正常に完了した」のか「サーバー側で途中エラーが発生した」のかを + 判別できます。なお、エラー終端行の書き込み自体に失敗した場合は終端行が出力されず + ストリームが途中で終了するため、予期しない切断もエラーとして扱ってください。 + +レスポンスフィールド +-------------------- + +デフォルトで含まれるフィールド: + +- ``score``: 検索スコア +- ``_id``: ドキュメントID(OpenSearch のドキュメントID) +- ``doc_id``: ドキュメントID(|Fess| 内部) +- ``boost``: ブースト値 +- ``content_length``: コンテンツ長 +- ``host``: ホスト名 +- ``site``: サイト +- ``last_modified``: 最終更新日時 +- ``timestamp``: タイムスタンプ +- ``mimetype``: MIMEタイプ +- ``filetype``: ファイルタイプ +- ``filename``: ファイル名 +- ``created``: 作成日時 +- ``title``: タイトル +- ``digest``: 本文抜粋 +- ``url``: ドキュメントのURL +- ``thumbnail``: サムネイル +- ``click_count``: クリック数 +- ``favorite_count``: お気に入り数 +- ``has_cache``: キャッシュ有無 +- ``content_title``: 表示用タイトル +- ``content_description``: 表示用の本文抜粋 +- ``url_link``: 表示用リンクURL +- ``site_path``: サイトパス + +.. note:: + 実際に出力されるフィールドは、API レスポンスとして許可されたフィールドに限定されます。 + 値が存在しないフィールドは出力されません。 + +.. note:: + ``content`` (全文)はデフォルトでは含まれません。 + ``query.additional.scroll.response.fields`` と ``query.additional.api.response.fields`` の + 両方に追加すると出力されます（「レスポンスフィールドの設定」を参照）。 + +データ処理例 +============ + +Pythonでの処理例 +---------------- + +.. code-block:: python + + import requests + import json + + # スクロール検索の実行 + url = "http://localhost:8080/api/v2/documents/all" + params = { + "q": "Fess", + "num": 100 + } + + response = requests.get(url, params=params, stream=True) + + # NDJSON形式のレスポンスを1行ずつ処理 + for line in response.iter_lines(): + if line: + record = json.loads(line) + if "error" in record: + # ストリーム途中でエラーが発生 + print("stream error:", record["error"]) + break + doc = record["data"] + print(f"Title: {doc.get('title')}") + print(f"URL: {doc.get('url')}") + print("---") + +ファイルへの保存 +---------------- + +検索結果をファイルに保存する例: + +.. code-block:: bash + + curl "http://localhost:8080/api/v2/documents/all?q=*:*" > all_documents.ndjson + +CSVへの変換 +----------- + +jqコマンドを使用してCSVに変換する例: + +.. code-block:: bash + + curl "http://localhost:8080/api/v2/documents/all?q=Fess" | \ + jq -r '.data | [.url, .title, .score] | @csv' > results.csv + +データ分析 +---------- + +取得したデータを分析する例: + +.. code-block:: python + + import json + import pandas as pd + + # NDJSONファイルの読み込み(各行の data キーを取り出す) + documents = [] + with open('all_documents.ndjson', 'r') as f: + for line in f: + record = json.loads(line) + if "data" in record: + documents.append(record["data"]) + + # DataFrameに変換 + df = pd.DataFrame(documents) + + # 基本統計 + print(f"Total documents: {len(df)}") + print(f"Average score: {df['score'].mean()}") + + # URLのドメイン分析 + df['domain'] = df['url'].apply(lambda x: x.split('/')[2]) + print(df['domain'].value_counts()) + +パフォーマンスとベストプラクティス +================================== + +効率的な使用方法 +---------------- + +1. **適切なnumパラメータの設定** + + - 小さすぎると通信オーバーヘッドが増加 + - 大きすぎるとメモリ使用量が増加 + - デフォルトの最大値: 100 + +2. **検索条件の最適化** + + - 必要なドキュメントのみを取得するよう検索条件を指定 + - 全件取得は本当に必要な場合のみ実行 + +3. **オフピーク時間の利用** + + - 大量データの取得は、システムの負荷が低い時間帯に実行 + +4. **バッチ処理での利用** + + - 定期的なデータ同期などはバッチジョブとして実行 + +メモリ使用量の最適化 +-------------------- + +大量のデータを処理する場合、ストリーミング処理を使用してメモリ使用量を抑制します。 + +.. code-block:: python + + import requests + import json + + url = "http://localhost:8080/api/v2/documents/all" + params = {"q": "*:*", "num": 100} + + # ストリーミングで処理 + with requests.get(url, params=params, stream=True) as response: + for line in response.iter_lines(decode_unicode=True): + if line: + record = json.loads(line) + if "error" in record: + break + # ドキュメントの処理 + process_document(record["data"]) + +セキュリティ考慮事項 +==================== + +アクセス制限 +------------ + +スクロール検索は大量のデータを返すため、適切なアクセス制限を設定してください。 +エンドポイント自体はデフォルトで認証を要求しないため、必要に応じて以下のような対策を +検討してください。 + +1. **IPアドレス制限** + + 特定のIPアドレスからのみアクセスを許可 + +2. **API認証** + + リバースプロキシ等でAPIトークンやBasic認証を使用 + +3. **ロールベースのアクセス制御** + + 返されるドキュメントは |Fess| のロールベースのアクセス制御によりフィルタリングされます + +レート制限 +---------- + +過度なアクセスを防ぐため、リバースプロキシでレート制限を設定することを推奨します。 + +トラブルシューティング +====================== + +スクロール検索が利用できない +---------------------------- + +1. ``api.search.scroll`` が ``true`` に設定されているか確認してください。 +2. |Fess| を再起動したか確認してください。 +3. エラーログを確認してください。 + +タイムアウトエラーが発生する +---------------------------- + +1. ``num`` パラメータを小さくして、処理を分散してください。 +2. 検索条件を絞り込んで、取得するデータ量を減らしてください。 + +メモリ不足エラー +---------------- + +1. ``num`` パラメータを小さくしてください。 +2. |Fess| のヒープメモリサイズを増やしてください。 +3. OpenSearch のヒープメモリサイズを確認してください。 + +レスポンスが空になる +-------------------- + +1. 検索クエリが正しいか確認してください。 +2. 指定したラベルやフィルタ条件が正しいか確認してください。 +3. ロールベースのアクセス制御により、閲覧権限のないドキュメントは結果に含まれません。リクエストのロール設定を確認してください。 + +参考情報 +======== + +- :doc:`search-basic` - 検索機能の詳細 +- :doc:`search-advanced` - 検索関連の設定 +- `OpenSearch Scroll API `_ diff --git a/ja/15.10/config/search-semantic.rst b/ja/15.10/config/search-semantic.rst new file mode 100644 index 000000000..5a7ffe476 --- /dev/null +++ b/ja/15.10/config/search-semantic.rst @@ -0,0 +1,885 @@ +======================================================== +セマンティック検索（コンテンツチャンク＋ベクトル検索） +======================================================== + +概要 +==== + +|Fess| 15.10 では、ドキュメント本文をチャンク（断片）に分割し、各チャンクの埋め込みベクトルを +生成・格納する **コンテンツチャンク機能** がコアに統合されました。生成したベクトルは以下の2つの +用途で利用されます。 + +- **セマンティック検索**: キーワード（BM25）検索とベクトル検索を Rank Fusion で統合した + ハイブリッド検索。キーワードが一致しなくても意味的に近いドキュメントがヒットします。 +- **AI検索モード（RAG）**: 回答生成時に、質問と意味的に近いチャンクだけをLLMのコンテキストとして + 選択し、回答品質とトークン効率を向上させます。 + +本機能はすべてデフォルトで無効です。有効にしない場合、|Fess| は従来どおりキーワード検索のみで +動作します。15.7 以前から |Fess| をアップグレードする場合や、``fess-webapp-semantic-search`` +プラグインを利用していた場合は、:ref:`semantic-search-migration` を参照してください。 + +処理の流れ +---------- + +1. クローラーが通常どおりドキュメントをインデックスに登録します（この時点ではチャンクなし）。 +2. スケジューラジョブ **Content Chunk Vector Indexer** が未処理ドキュメントを検出し、 + 本文（``content`` フィールド）をチャンクに分割して埋め込みベクトルを生成し、 + ``content_chunk_vector`` フィールドに格納します。このとき ``content`` フィールド自体も + チャンクの配列に書き換えられます（``content_length`` は元の値のままです）。 +3. 処理結果は ``content_chunk_status`` フィールドに記録されます（後述）。 +4. ``content_chunker.search.enabled=true`` の場合、検索時にセマンティックサーチャーが + Rank Fusion に参加します。 + +前提条件 +======== + +- **OpenSearch（k-NN プラグイン入り）**: |Fess| 15.10 では、コンテンツチャンク機能を有効にしているか + どうかにかかわらず、検索インデックス（``fess.search``）のマッピングに ``content_chunk_vector`` + フィールド（``nested`` 型。その ``vector`` サブフィールドが ANN 用の ``knn_vector`` 型）が + 常に含まれ、インデックス設定にも ``index.knn: true`` が常に含まれます。そのため OpenSearch に + k-NN プラグインが入っていないと、インデックスの新規作成自体が失敗し、|Fess| は起動できません。 + + .. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - 構成 + - k-NN プラグインの対応状況 + * - Docker（``ghcr.io/codelibs/fess-opensearch``）、RPM/DEB 版（常に別途インストールした外部 + OpenSearch に接続します）、または外部 OpenSearch（標準配布） + - ``faiss`` を含めてフルサポートされます。 + * - 外部 OpenSearch の **minimal 配布** + - **非対応です**。k-NN プラグインを含まないため、インデックスの新規作成に失敗します。 + + ``content_chunker.search.knn.engine`` は、上記いずれの構成でも ``nmslib`` を値として受け付けま + せん。``content_chunk_vector`` は ``nested`` フィールドであり、k-NN プラグインが nested + フィールドに対応するエンジンは ``lucene`` / ``faiss`` のみだからです（``nmslib`` は + OpenSearch 3.0 以降で非推奨・利用制限もされています）。設定すると警告ログとともに ``lucene`` + にフォールバックします。ANN 関連の他の設定値については後述の「設定リファレンス」を参照して + ください。 + +- **外部クラスタの OpenSearch バージョン**: 同梱の ``fess.search`` インデックス設定は、 + ``fess_indices/fess.json``\ （および ``vanilla`` 、 ``aws`` 、非推奨の ``cloud`` が使う ``fess_indices/_vanilla/fess.json`` ）で ``index.knn`` と + ``knn.derived_source.enabled`` を常に送信します。後者は k-NN プラグインの比較的新しい設定で、 + これを認識できない古い OpenSearch では、k-NN プラグインの有無にかかわらずインデックスの作成に + 失敗します。|Fess| 15.10 が対応する OpenSearch のバージョンについては + :doc:`../install/prerequisites` を参照してください。 + +- **埋め込みプロバイダ**: 以下のいずれかを使用します。 + +.. list-table:: + :header-rows: 1 + :widths: 20 25 55 + + * - 設定値 + - 提供元 + - 説明 + * - ``opensearch`` + - |Fess| 本体（内蔵） + - OpenSearch ML Commons にデプロイした埋め込みモデルを使用します。追加プラグイン不要。デフォルト設定値。 + * - ``ollama`` + - ``fess-llm-ollama`` プラグイン + - Ollama の埋め込みモデル（``nomic-embed-text`` 等）を使用します。 + * - ``openai`` + - ``fess-llm-openai`` プラグイン + - OpenAI の埋め込みAPIを使用します。 + * - ``gemini`` + - ``fess-llm-gemini`` プラグイン + - Google Gemini の埋め込みAPIを使用します。 + * - ``bedrock`` + - ``fess-llm-bedrock`` プラグイン + - Amazon Bedrock 経由で Amazon Titan Text Embeddings V2 または Cohere Embed を使用します。 + * - ``none`` + - |Fess| 本体（内蔵） + - チャンク分割のみ実行し、ベクトルは生成しません（chunk-onlyモード）。 + +設定リファレンス +================ + +``content_chunker.*`` の設定はすべて「システムプロパティ（``system.properties``）」に統一されて +います。``app/WEB-INF/conf/system.properties``\ （RPM/DEB 版は ``/etc/fess/system.properties``、 +Docker 版は ``/opt/fess/system.properties``）に設定するか、起動オプション +``-Dfess.system.<キー名>`` で初期値を指定します。値は実行時に再読み込みされるため、ほとんどの +設定は変更後すぐに反映されます。ただし ``content_chunker.search.enabled`` の有効化 +（``false`` → ``true``）だけは、セマンティックサーチャーの登録が起動時にしか行われないため、 +**反映には再起動が必要** です。 + +.. note:: + + ``content_chunker.*`` の設定は ``system.properties`` チャネルからのみ読み込まれます。 + ``fess_config.properties`` や ``-Dfess.config.<キー名>`` に記述しても無視されるため、必ず + ``system.properties`` に設定してください。なお 管理画面 > システム情報 > 設定情報 は現在値の + **閲覧専用** の画面で、この画面から ``content_chunker.*`` を設定することはできません。 + +system.properties の設定 +------------------------ + +.. list-table:: + :header-rows: 1 + :widths: 40 15 45 + + * - プロパティ + - デフォルト + - 説明 + * - ``content_chunker.enabled`` + - ``false`` + - コンテンツチャンク機能全体のマスタースイッチ + * - ``content_chunker.chunker.name`` + - ``length`` + - チャンク分割方式 + * - ``content_chunker.length.chunk_size`` + - ``800`` + - 1チャンクの目標文字数。境界考慮分割が有効（既定）の場合、これは上限ではなく目標値です。 + チャンクは ``boundary.lookback_percent`` の分だけ短くなることがあり、 + ``max(lookahead, 32)`` 文字だけ長くなることがあります（既定では640〜840文字）。 + 埋め込みモデルのトークン上限に対してこのマージンを見込んでください + * - ``content_chunker.length.overlap`` + - ``0`` + - チャンク間で重複させる文字数。再開位置も境界にスナップされ、スナップは位置を前方向にしか + 動かさないため、実効的な重複はこの値以上・この値の2倍以下になります + * - ``content_chunker.length.boundary.enabled`` + - ``true`` + - ``chunk_size`` 文字ちょうどで切るのではなく、各切れ目を適切なテキスト境界へ移動します。 + 候補はティア分けされ、存在する最上位ティアの中で最も近いものが選ばれます。改行・文末が + 最優先、次に節区切り・空白、最後に書字系の変化です。``false`` にすると従来の固定長分割に + 戻ります + * - ``content_chunker.length.boundary.lookback_percent`` + - ``20`` + - 切れ目の理想位置より前方を境界探索する範囲（``chunk_size`` に対する百分率、0〜50） + * - ``content_chunker.length.boundary.lookahead_percent`` + - ``5`` + - 切れ目の理想位置より後方を文末・改行について探索する範囲（``chunk_size`` に対する + 百分率、0〜25）。前方に候補が見つからなかった場合にのみ使われます + * - ``content_chunker.max_chunks_per_document`` + - ``1000`` + - 1ドキュメントあたりの最大チャンク数。超過したドキュメントは ``skipped`` になり、 + 埋め込みも作成されません。境界考慮分割はチャンクを短くするため、固定長分割より + およそ3〜25%多くのチャンクが生成されます。非常に大きなドキュメントを扱う場合は + この値を大きくしてください + * - ``content_chunker.embedding.name`` + - ``opensearch`` + - 埋め込みプロバイダ（``opensearch`` / ``ollama`` / ``openai`` / ``gemini`` / ``bedrock`` / ``none``） + * - ``content_chunker.embedding.dimension`` + - ``768`` + - 埋め込みベクトルの次元数。マッピング作成時にこの値が使われるため、使用する埋め込みモデルの + 次元数に **必ず** 合わせて設定してください。この値には読み取り経路が2つあり、挙動が + 異なります。インデックスのマッピング作成時は、未設定の場合は **警告なしで** ``768`` が + 使われ、空・非数値・0 以下・``16000``\ （k-NN プラグイン自体の上限）超の場合は警告とともに + ``768`` が使われます。一方、埋め込み処理の実行時にはフォールバックがなく、未設定・非数値・ + 0 以下はいずれもエラーになります。``16000`` を超える値は実行時には拒否されないため、 + マッピングだけが ``768`` で作成されて次元不一致になります。マッピングの次元数はインデックスの + 作成後に変更できません。未設定のまま作成してしまった場合の復旧は、後述の + 「次元数を設定せずにインデックスを作成した場合」を参照してください + * - ``content_chunker.job.concurrency`` + - ``2`` + - インデクサジョブの並列数 + * - ``content_chunker.job.bulk_size`` + - ``20`` + - 1回の取得・書き込み単位 + * - ``content_chunker.job.max_documents_per_run`` + - ``-1``\ （無制限） + - 1回のジョブ実行で処理する最大ドキュメント数。``0`` 以下の値はすべて無制限として扱われます + * - ``content_chunker.job.retry_failed`` + - ``false`` + - ``true`` にすると、前回の実行で ``content_chunk_status=fail`` になったドキュメントも次回 + 実行時の処理対象に含めます。自動リトライや試行回数の記録はなく、原因を修正した後に + 一時的に有効化して再試行する運用を想定しています + * - ``content_chunker.chat.top_k`` + - ``3`` + - AI検索モードの回答生成時に選択するチャンク数 + * - ``content_chunker.search.enabled`` + - ``false`` + - セマンティック検索の Rank Fusion 統合（**有効化には再起動が必要**） + * - ``content_chunker.search.min_score`` + - （未設定） + - 検索結果に含める最小コサイン類似度（0〜1）。未設定の場合は足切りなし。``ann`` モードでは + ``search.knn.space_type`` が ``cosinesimil`` 以外の場合、コサイン基準の足切りを定義できない + ため、警告とともにスキップされます + * - ``content_chunker.search.knn.method`` + - ``hnsw`` + - ANNインデックスのメソッド。現時点で受け付けられる値は ``hnsw`` のみで、それ以外の値は + 警告とともに ``hnsw`` にフォールバックします（マッピングに反映。変更にはインデックスの + 再作成が必要） + * - ``content_chunker.search.knn.engine`` + - ``lucene`` + - ANNエンジン。受け付けられる値は ``lucene`` または ``faiss`` のみです（前提条件を参照）。 + それ以外の値は警告とともに ``lucene`` にフォールバックします（マッピングに反映。変更には + インデックスの再作成が必要） + * - ``content_chunker.search.knn.space_type`` + - ``cosinesimil`` + - 距離空間。受け付けられる値は ``cosinesimil``、``innerproduct``、``l2`` のみで、それ以外の + 値は警告とともに ``cosinesimil`` にフォールバックします（マッピングに反映。変更には + インデックスの再作成が必要） + * - ``content_chunker.search.knn.k`` + - ``100`` + - ANNクエリでシャードごとに取得する近傍数。|Fess| 側で融合する場合は + ``rank.fusion.window_size`` ÷ サーチャー数（既定では 200 ÷ 2 = 100）が下限になるため、 + それより小さい値には効果がありません。検索エンジン側で融合する場合は、この値がそのまま + 使われます + * - ``content_chunker.search.knn.param.ef_search`` + - （未設定） + - ANNクエリの ``ef_search`` パラメーター + +.. note:: + + ``content_chunker.length.boundary.enabled=true``\ （デフォルト）の場合、 + ``content_chunker.length.chunk_size`` は上限ではなく目標値になります。各分割位置は、 + 探索ウィンドウ内に存在する最上位ティアの候補のうち最も近いものへ移動します。改行・文末は、 + どれだけ手前にあっても節区切りや空白より優先され、それらは書字系の変わり目より優先されます。 + 移動するのは分割位置だけで文字が失われることはないため、ドキュメントのチャンクを連結すれば + 元の内容と完全に一致します。前方探索によって、``chunk_size`` を最大 + ``content_chunker.length.boundary.lookahead_percent`` 分だけ超える場合があります。これとは + 別に、書記素クラスター（結合文字、異体字セレクター、ゼロ幅接合子で連結された絵文字 + シーケンスなど）の途中で分割されそうになった場合には、最大32文字の超過が発生することが + あります。こちらは ``lookahead_percent`` の影響を受けず、``0`` に設定していても発生します。 + 2種類の超過が同じ分割位置で同時に発生することはないため、標準設定でのチャンク長は + 640〜840文字の範囲に収まります。平均的にチャンクが短くなる分、ドキュメントから生成される + チャンク数は固定長分割よりおよそ3〜25%増えます + （``content_chunker.max_chunks_per_document`` を参照）。 + ``content_chunker.length.boundary.enabled`` を ``false`` にするか、2つの百分率をどちらも + ``0`` にすると、従来の固定長分割とまったく同じ結果になります。これらの設定変更が影響するのは + 以降にチャンク化されるドキュメントだけです。すでにチャンク配列として保存されている + ドキュメントは、再クロールされるまで元の境界を保持します。 + +.. note:: + + ``content_chunker.length.chunk_size`` は文字数で指定しますが、埋め込みモデルが一度に受け取れる + のはトークン数の上限までです。|Fess| は埋め込み対象のテキストを切り詰めないため、上限を超えた + 部分はベクトルに反映されないことがあります。``chunk_size`` は、使用するモデルの入力上限から + 選んでください。例えば ``paraphrase-multilingual-MiniLM-L12-v2``\ （最大128トークン）で実測した + ところ、ベクトルに反映された範囲は英語でおよそ440文字、日本語でおよそ210文字でした + （テキストによって変わります）。このモデルでは、既定の ``chunk_size=800`` のチャンクの + 後ろの部分はベクトルに反映されません。 + +.. note:: + + HNSW の ``m`` と ``ef_construction`` パラメーターは ``doc.json`` に固定値 + （``m=16`` / ``ef_construction=100``）として組み込まれており、設定では変更できません。 + +opensearch プロバイダの接続設定 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +内蔵の ``opensearch`` プロバイダ（OpenSearch ML Commons）を使う場合の接続設定です。 +上記と同じ ``system.properties`` に設定します。 + +.. list-table:: + :header-rows: 1 + :widths: 50 20 30 + + * - プロパティ + - デフォルト + - 説明 + * - ``content_chunker.embedding.opensearch.model.id`` + - （必須） + - ML Commons にデプロイ済みのモデルID + * - ``content_chunker.embedding.opensearch.api.url`` + - 検索エンジンのアドレス + - ML Commons API の接続先。未設定時は |Fess| が使用している検索エンジン（``http://localhost:9200`` 等） + * - ``content_chunker.embedding.opensearch.username`` / ``password`` + - 検索エンジンの認証情報 + - 未設定時は検索エンジン接続用の認証情報にフォールバックします。ただしこれは ``api.url`` + が未設定の間（＝接続先が |Fess| 自身が使用している検索エンジンと同じ場合）に限られ、 + ``api.url`` を設定するとフォールバックされません + * - ``content_chunker.embedding.opensearch.timeout`` + - ``60000`` + - リクエストタイムアウト（ミリ秒） + * - ``content_chunker.embedding.opensearch.connect.timeout`` + - ``5000`` + - 接続タイムアウト（ミリ秒） + * - ``content_chunker.embedding.opensearch.retry.max`` + - ``3`` + - 一時的エラー（429/5xx等）に対する最大試行回数（初回を含む）。リトライ回数ではありません。 + ``3`` なら最大3回リクエストし、その間の待機は2回です。``1`` 以下は再試行しません + * - ``content_chunker.embedding.opensearch.retry.base.delay.ms`` + - ``2000`` + - リトライの基準待機時間（ミリ秒） + * - ``content_chunker.embedding.opensearch.availability.check.interval`` + - ``60`` + - プロバイダ可用性チェックの間隔（秒） + * - ``content_chunker.embedding.opensearch.document.prefix`` / ``query.prefix`` + - （空） + - 埋め込み前にドキュメント/クエリテキストへ付与するプレフィックス + +.. warning:: + + ``system.properties`` の内容は 管理画面 > システム情報 > 設定情報 の「アプリのプロパティ」で + 閲覧できます。``content_chunker.embedding.opensearch.password`` はこの画面では ``XXXXXXXX`` + にマスクされますが、``username`` はそのまま表示されます。また、``-Dfess.system.<キー名>`` で + 指定した値は同じ画面の「システムのプロパティ」に **マスクされずに** 表示されるため、認証情報は + 起動オプションではなく ``system.properties`` に記述してください。 + +その他のプロバイダ（ollama / openai / gemini / bedrock） +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``ollama`` プロバイダ（``fess-llm-ollama`` プラグイン）は、 +``content_chunker.embedding.ollama.`` プレフィックスで同様の設定を行います +（``api.url`` デフォルト ``http://localhost:11434``、``model`` デフォルト ``embeddinggemma``、 +``document.prefix`` / ``query.prefix`` デフォルトはそれぞれ ``title: none | text:`` / +``task: search result | query:``）。``nomic-embed-text`` 系のモデルを使用する場合は、 +``document.prefix`` / ``query.prefix`` に ``search_document:`` / ``search_query:`` を明示的に +設定してください。これらのプレフィックスは埋め込み対象のテキストへそのまま連結される +（前後の空白はトリムされない）ため、上記のデフォルト値も ``search_document:`` / +``search_query:`` も、いずれも **末尾に半角スペースを1つ含みます**。自分で設定する場合は、 +区切りの半角スペースを忘れないでください。 +``openai`` / ``gemini`` プロバイダも同様に、それぞれ ``content_chunker.embedding.openai.`` / +``content_chunker.embedding.gemini.`` プレフィックスで設定します。設定キーの詳細は各プラグインの +ドキュメントを参照してください。 ``bedrock`` プロバイダは ``content_chunker.embedding.bedrock.`` +プレフィックスで設定し、 ``content_chunker.embedding.dimension`` にはモデルが出力できる次元数を +指定します。詳細は :doc:`llm-bedrock` を参照してください。 + +セットアップ手順（opensearch プロバイダの例） +============================================= + +ここでは、内蔵の ``opensearch`` プロバイダ（ML Commons）を使用した設定例を示します。 + +1. 埋め込みモデルのデプロイ +--------------------------- + +OpenSearch の ML Commons に埋め込みモデルを登録・デプロイします。 +単一ノード構成では、事前に以下の設定が必要です。 + +.. code-block:: bash + + curl -XPUT "http://localhost:9200/_cluster/settings" \ + -H "Content-Type: application/json" -d ' + {"persistent": {"plugins.ml_commons.only_run_on_ml_node": false}}' + +モデルの登録とデプロイ（例: 384次元の文埋め込みモデル）: + +.. code-block:: bash + + # モデルの登録（レスポンスのtask_idからmodel_idを取得） + curl -XPOST "http://localhost:9200/_plugins/_ml/models/_register" \ + -H "Content-Type: application/json" -d ' + { + "name": "huggingface/sentence-transformers/all-MiniLM-L6-v2", + "version": "1.0.2", + "model_format": "TORCH_SCRIPT" + }' + + # タスクの完了確認と model_id の取得（state が COMPLETED になると model_id が返ります） + curl "http://localhost:9200/_plugins/_ml/tasks/" + + # デプロイ + curl -XPOST "http://localhost:9200/_plugins/_ml/models//_deploy" + + # 状態確認: model_state が DEPLOYED であること + curl "http://localhost:9200/_plugins/_ml/models/" + +.. note:: + + モデルは ``REGISTERED`` のままでは使用できません。必ずデプロイして + ``model_state`` が ``DEPLOYED`` になったことを確認してください。 + +2. |Fess| の設定 +---------------- + +``app/WEB-INF/conf/system.properties``\ （RPM/DEB 版は ``/etc/fess/system.properties``、 +Docker 版は ``/opt/fess/system.properties``。以下はすべて同じファイルに記述します）:: + + content_chunker.enabled=true + content_chunker.embedding.name=opensearch + content_chunker.embedding.dimension=384 + content_chunker.embedding.opensearch.model.id= + +セマンティック検索も利用する場合は、続けて以下も追加します:: + + content_chunker.search.enabled=true + +設定後、|Fess| を再起動します。 + +3. インデックスの再作成（既存の環境で有効化する場合） +----------------------------------------------------- + +``content_chunk_vector`` フィールドのマッピング（設定した次元数・ANNメソッド設定を含む）は、 +``fess.search`` インデックスが **新規作成される時点で** 適用されます。 + +- **新規インストールの場合**: |Fess| を初めて起動する前に、上記の設定を + ``system.properties`` に反映しておけば、最初のインデックス作成時に正しいマッピングが + 自動的に適用されるため、このステップは不要です。 +- **既にインデックスが存在する場合**\ （一度でも |Fess| を起動したことがある場合）: 稼働中の + インデックスへは反映されません。既存のマッピングへの後付けもできないため、以下の手順で + インデックスを再作成してください。 + + 管理画面 > システム情報 > メンテナンス を開き、「再インデクシング」の「エイリアスの更新」を + 有効にした状態で実行してください。 + + 再作成されたインデックスに、インデックス設定の ``index.knn: true`` と、設定した次元数・ANN + メソッド設定を持つ ``content_chunk_vector`` マッピングが含まれていることを確認できます + （``index.knn`` はインデックス設定、ANN メソッド設定はマッピングと、適用先が異なります）。 + +.. warning:: + + 「再インデクシング」はバックグラウンドの非同期処理として実行され、管理画面には完了を示す + 通知は表示されません。``_cat/indices`` はインデックスが存在すること（health・件数など）を + 示すだけで、エイリアスがどちらのインデックスを指しているかは分かりません。以下の + インデクサジョブの手順に進む前に、``_cat/aliases`` で ``fess.search`` と ``fess.update`` + の両方が新しいインデックスを指していることを確認してください。|Fess| のログは失敗時にのみ + 警告を出力するため、ログが静かであることは成功の証拠にはならず、既知の失敗が起きていない + ことを示すに過ぎません。旧インデックス（それまで ``fess.search`` エイリアスが指していた + 実体インデックスで、``fess.`` という名前を持ちます）は自動削除されないため、 + 不要になった時点で手動で削除してください。新旧両方のインデックスが存在する間は、 + インデックス用のディスク使用量がおおむね通常の2倍になります。 + +4. インデクサジョブの有効化 +--------------------------- + +チャンク分割と埋め込み生成は、スケジューラジョブ **Content Chunk Vector Indexer** +（ID: ``content-chunk-vector-indexer``、デフォルト無効、スケジュール ``0 13 * * *``）が行います。 + +管理画面 > システム > スケジューラ で本ジョブを有効化し、「今すぐ開始」で実行します。 +以後は、クロールの完了とは無関係に、設定したスケジュール（既定は毎日 13:00）で未処理ドキュメントが +処理されます。本ジョブはクロールジョブと連鎖していないため、クロール直後に処理したい場合は、 +スケジュールをクロールジョブの想定完了時刻より後に設定してください。 + +.. note:: + + 複数ノード構成では、本ジョブの実行対象をいずれか1ノードに固定することを推奨します。 + 全ノードで同時実行しても整合性は保たれますが、同じドキュメントを各ノードが重複して + 埋め込み処理するため、プロバイダへの負荷・コストがノード数分増加します。 + + 固定するには、以下の2つの設定が両方とも必要です（片方だけでは固定されません）。 + + 1. **実行させたいノード側**\ の ``app/WEB-INF/classes/fess_config.properties`` + （RPM/DEB 版は ``/etc/fess/fess_config.properties``。または + ``-Dfess.config.scheduler.target.name=<任意の識別名>``）に + ``scheduler.target.name=<任意の識別名>`` を設定し、そのノードを再起動します + （既定は空で、他のノードは既定のままにしておきます）。 + 2. 管理画面 > システム > スケジューラ で Content Chunk Vector Indexer ジョブを開き、 + 「対象」フィールドを ``all`` から、手順1で設定した識別名に変更して保存します。 + + 「対象」フィールドの意味は :doc:`../admin/scheduler-guide` を参照してください。 + ``scheduler.target.name`` を設定しても、「対象」フィールドを ``all`` のままにしておくと + **固定されません**。``all`` は常に一致する特別な値として扱われるため、手順1だけ・ + 手順2だけでは固定できず、必ず両方を行ってください。 + +.. warning:: + + ピン留めした後は、「今すぐ開始」も **手順1で識別名を設定したノードの管理画面から** 実行して + ください。対象外のノードで「今すぐ開始」を押すと、画面には「ジョブ … を開始しました。」と + 表示されるにもかかわらず、「対象」の不一致によりジョブは実行されません（そのノードのログに + ``Ignoring job`` が INFO で出力されるだけです）。 + +5. 処理状態の確認 +----------------- + +処理結果は各ドキュメントの ``content_chunk_status`` フィールドで確認できます。 + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - 値 + - 意味 + * - （フィールドなし） + - 未処理（次回のジョブ実行で処理対象）。再クロールされたドキュメントもこの状態に戻ります + * - ``done`` + - チャンク分割とベクトル生成が完了 + * - ``chunked`` + - チャンク分割のみ完了（chunk-onlyモード）。``embedding.name=none`` の場合のほか、 + ``embedding.name`` に指定したプロバイダのプラグインが導入されていない場合もこの状態に + なります + * - ``skipped`` + - 処理をスキップ。本文が空（空白のみを含む）のドキュメント、チャンクが1つも生成されなかった + ドキュメント、``max_chunks_per_document`` を超えたドキュメントが該当します。 + ``content_chunker.chunker.name`` に存在しない名前を指定した場合も、チャンカーが見つからず + チャンクが生成されないため、すべてのドキュメントがこの状態になります。終端状態で、 + ジョブを再実行しても再処理されません + * - ``fail`` + - 処理に失敗（ログを確認してください）。終端状態で、既定ではジョブを再実行しても再処理 + されません。再処理するには ``content_chunker.job.retry_failed`` を ``true`` にします + +状態の分布は検索エンジンに直接問い合わせて確認できます:: + + curl -XPOST "http://localhost:9200/fess.search/_search" \ + -H "Content-Type: application/json" -d ' + {"size": 0, "aggs": {"status": {"terms": {"field": "content_chunk_status", "missing": "pending"}}}}' + +``missing`` オプションにより、``content_chunk_status`` を持たない（＝未処理の）ドキュメントは +``pending`` というキーのバケットに集計されます。 + +チャンクジョブの状況は、この ``content_chunk_status`` の件数分布で判断してください。ジョブを実行する +たびに ``pending`` が減って ``done``\ （chunk-only モードでは ``chunked``）が増えていれば順調です。 +``fail`` が現れた場合は、|Fess| のログで原因を確認してください。``skipped`` は本文が空のドキュメント +などでは正常ですが、ほぼ全件が ``skipped`` になっている場合は ``content_chunker.chunker.name`` の +誤りを疑ってください（チャンカーが見つからない場合は ``Chunker not found`` というWARNログが出力 +されます）。 + +.. warning:: + + ``skipped`` と ``fail`` は、設定を直しただけでは元に戻りません。``skipped`` はジョブの再実行では + 選ばれず（再クロールされたドキュメントは未処理に戻ります）、``fail`` は + ``content_chunker.job.retry_failed`` を ``true`` にした場合にだけ再び処理対象になります。 + たとえば ``content_chunker.chunker.name`` を誤ったままジョブを実行して全件が ``skipped`` に + なった場合は、名前を直したうえで ``content_chunk_status`` を削除してから、ジョブを再実行して + ください（``skipped`` のドキュメントは ``content`` が書き換えられていないため、そのまま + 再処理できます）:: + + curl -XPOST "http://localhost:9200/fess.search/_update_by_query" \ + -H "Content-Type: application/json" -d ' + { + "query": {"term": {"content_chunk_status": "skipped"}}, + "script": {"source": "ctx._source.remove(\"content_chunk_status\")"} + }' + +セマンティック検索の動作 +======================== + +``content_chunker.search.enabled=true`` を設定すると、セマンティックサーチャーが +Rank Fusion に登録され、キーワード検索結果とベクトル検索結果が統合されます +（Rank Fusion の仕組みは :doc:`rank-fusion` を参照）。融合は既定では |Fess| が行いますが、 +``rank.fusion.engine.enabled=true`` を設定すると OpenSearch 側で行うこともできます +（:ref:`rank-fusion-engine` を参照）。 +なお、検索時には ``content_chunker.enabled`` も参照されます。``content_chunker.enabled=false`` +または ``content_chunker.embedding.name=none`` の場合、サーチャーが登録済みでもセマンティック +検索は実行されません（この判定はリクエストごとに行われるため、再起動は不要です）。 + +.. warning:: + + セマンティックサーチャーの登録は起動時に行われるため、**有効化には再起動が必要** です。 + 無効化（``false`` への変更）はリクエストごとに判定されるため即時反映されます。 + +exact モードと ann モード +------------------------- + +検索方式はインデックスの状態から自動選択されます。 + +.. list-table:: + :header-rows: 1 + :widths: 12 44 44 + + * - モード + - 条件 + - 特徴 + * - ``ann`` + - ``index.knn`` と ANN メソッド設定を持つインデックス + - HNSW による近似近傍検索。大規模インデックス向け + * - ``exact`` + - 上記以外（``index.knn`` または ANN メソッド設定のいずれかを欠くインデックス。インデックス + 状態の判定に失敗した場合を含む） + - 全ベクトルとの厳密なコサイン類似度計算。小〜中規模向け + +|Fess| 15.10 で新規作成される ``fess.search`` インデックスは、``content_chunker.search.enabled`` の +値にかかわらず常に ``index.knn`` と ANN メソッド設定を持つため、通常は常に ``ann`` モードが +使われます。``exact`` モードは、この仕組みが導入される前に作成された古いインデックスに対する +フォールバックです。既存インデックスに後から k-NN 設定を追加することはできないため、 +``exact`` モードのインデックスを ``ann`` モードへ切り替えるには、インデックスの再作成が必要です +（:ref:`semantic-search-migration` を参照）。なお、この判定結果は 60 秒間キャッシュされるため、 +インデックスを再作成した直後は反映まで最大 60 秒かかります。 + +スコアの足切り +-------------- + +``content_chunker.search.min_score`` にコサイン類似度（0〜1）を設定すると、最も類似度の高い +チャンクでもその値に達しないドキュメントが、セマンティック検索結果から除外されます +（ドキュメントのスコアは最良チャンクのスコアになるため、足切りはドキュメント単位で働きます）。 +語彙が一致しないクエリでヒット件数が増えすぎる場合の調整に使用します:: + + content_chunker.search.min_score=0.4 + +設定値は ``exact`` / ``ann`` のどちらのモードでもコサイン類似度として解釈されます +（内部でモードごとのスコアスケールへ変換されます）。 + +.. note:: + + この足切りが適用されるのは、``content_chunker.search.knn.space_type`` が + ``cosinesimil``\ （デフォルト）の場合のみです。``innerproduct`` / ``l2`` を指定した ``ann`` + モードのインデックスでは、コサイン類似度を定義できないため、足切りはスキップされ、 + 該当する検索ごとに警告ログが出力されます。 + +制限事項 +-------- + +- クエリに含まれるフィールド指定の条件（``label:``\ 、``site:``\ 、``filetype:``\ 、 + ``timestamp`` / ``last_modified`` の範囲指定など）は、埋め込みの対象から切り離され、ベクトル + 検索にフィルタとして適用されます。判定はクエリの組み立て **後** の文字列に対して行われるため、 + ラベルの指定、ファセットによる絞り込み、詳細検索のファイル種別・サイト・日時の指定など、内部的 + にこうした条件が付加される操作（``ex_q`` や ``fields.*`` パラメーターによるものを含む）でも + セマンティック検索は実行され、キーワード検索と同じ条件で絞り込まれます。 +- 次のクエリでは **セマンティック検索はスキップ** され、キーワード検索のみが実行されます。 + + - ソート条件の指定（``sort:`` 疑似フィールド、または ``sort`` パラメーター。後者も内部的に + ``sort:...`` として付加されます） + - フィールドを指定しない語に対するフレーズ（``"..."``）、ワイルドカード（``*`` ``?``）、 + あいまい検索（``~``）、範囲指定。詳細検索のフレーズ指定も含みます。半角の ``?`` はワイルド + カードとして解釈されるため、「〜とは?」のように半角疑問符で終わる自然文もスキップされます + （全角の ``？`` は対象外です）。 + - 語の除外（``-語``\ 、``NOT 語``\ 。詳細検索の除外語を含む）や語のブースト（``語^2``） + - 語と条件を ``OR`` で結んだクエリなど、条件をフィルタとして切り離せないクエリ + - ``allintitle:`` / ``allinurl:`` + - 条件だけで、埋め込みの対象となる語を含まないクエリ + - 構文解析できないクエリ + +- 位置情報検索（ジオフィルタ）や類似ドキュメント検索と併用した場合もスキップされます。 +- 深いページの扱いは、融合を行う場所によって異なります。 + + - |Fess| 側で融合する場合（既定）は、境界は ``rank.fusion.window_size``\ （デフォルト + ``200``）で決まり、既定では検索結果の 101 件目以降がキーワード検索のみの結果になります。 + - 検索エンジン側で融合する場合（``rank.fusion.engine.enabled=true``）は、すべてのページが + 融合されますが、ページングは ``rank.fusion.pagination_depth``\ （デフォルト ``1000``）件で + 打ち切られ、それより後のページは要求できません。 + + 詳細は :doc:`rank-fusion` を参照してください。 +- 埋め込みプロバイダに接続できない場合や検索エラーが発生した場合は、自動的にキーワード検索のみの + 結果になります（検索自体がエラーになることはありません）。 +- ロール・仮想ホストによるアクセス制御は、セマンティック検索結果にも適用されます。 + +AI検索モードとの連携 +==================== + +AI検索モード（:doc:`rag-chat`、``rag.chat.enabled=true``）が有効な場合、 +``content_chunk_status`` が ``done`` のドキュメントについては、回答生成時に各チャンクとの +類似度を計算し、最も関連する上位 ``content_chunker.chat.top_k`` 件（デフォルト: ``3``）の +チャンクのみをLLMのコンテキストとして使用します。 + +このとき埋め込みの対象になるのは、利用者の発話そのものではなく、**意図判定フェーズでLLMが生成 +した検索クエリ** です（再検索が発生した場合は再生成後のクエリになります）。ドキュメントの要約を +求めた場合のように検索クエリが生成されない場合は、チャンク選択は行われません。 + +これにより、長いドキュメントでも関連部分だけがLLMに渡され、回答精度の向上とトークン使用量の +削減が期待できます。``content_chunk_status`` が ``chunked``\ （チャンクはあるがベクトルがない +状態）のドキュメントでは、類似度計算の代わりにキーワード（ハイライト）一致によるチャンク選択が +行われます。``skipped`` / ``fail`` および未処理のドキュメントは、従来どおり本文（または +ハイライト抜粋）が使用されます。 + +この動作は ``content_chunker.search.enabled`` とは独立していますが、``content_chunker.enabled`` +が有効である必要があります。なお、選択されたチャンクを連結したテキストも +``rag.chat.content.fulltext.max.length``\ （デフォルト ``3000``）で切り詰められるため、 +``content_chunker.chat.top_k`` や ``content_chunker.length.chunk_size`` を大きくしても、 +LLMに渡る文字数はこの上限を超えません。 + +.. _semantic-search-migration: + +15.7 以前からアップグレードする場合の移行 +========================================= + +15.7 以前から |Fess| をアップグレードする場合、現在の利用状況に応じて以下の +4 パターンのいずれかに該当します。該当するパターンの手順に従ってください。 + +新規インストールの場合 +---------------------- + +追加の作業は不要です。ベクトル検索を使う場合は、|Fess| を初めて起動する前に、本ページの +「設定リファレンス」に従って ``system.properties`` を設定しておくだけで、最初の +インデックス作成時に正しいマッピングが自動的に適用されます（具体的な手順は +「セットアップ手順」を参照してください）。 + +.. note:: + + 既に一度でも |Fess| を起動したことがある（インデックスが作成済みの）場合は、 + このパターンではなく次の「既存ユーザー」のいずれかに従ってください。 + +既存ユーザーで、ベクトル検索を利用しない場合 +-------------------------------------------- + +作業は不要です。``content_chunker.enabled`` と ``content_chunker.search.enabled`` は +いずれもデフォルトで ``false`` のため、アップグレード後も検索結果や既存インデックスの +挙動は変わりません。新設のスケジューラジョブ **Content Chunk Vector Indexer** は起動時に +自動登録されますが、デフォルトで無効なため実行されず、セマンティックサーチャーも +Rank Fusion に登録されません（このジョブは起動のたびに登録されるため、管理画面から削除しても +次回起動時に無効状態で再作成されます）。 + +.. note:: + + ベクトル検索を利用しない場合でも、|Fess| 15.10 以降でインデックスを **新規作成**\ （再インデ + クシングを含む）すると、``content_chunk_vector``\ （``knn_vector`` 型）を含むマッピングと + ``index.knn: true`` が適用されます。OpenSearch に k-NN プラグインが入っていない構成では、 + その時点でインデックスの作成に失敗します。詳細は本ページの「前提条件」を参照してください。 + +既存ユーザーで、ベクトル検索を利用したい場合 +-------------------------------------------- + +稼働中のインデックスには新しいマッピングが自動的には反映されないため、以下の手順が +必要です。 + +1. 本ページの「設定リファレンス」に従い、``system.properties`` に設定を投入します + （opensearch プロバイダを使う場合の具体的な手順は「セットアップ手順」を参照）。 +2. |Fess| を再起動します。 +3. 管理画面 > システム情報 > メンテナンス の「再インデクシング」を、「エイリアスの更新」を + 有効にした状態で実行します。処理はバックグラウンドで非同期に進み、完了通知は表示されません。 + ``_cat/indices`` はインデックスの存在を示すだけでエイリアスの向き先は分からないため、次の + 手順に進む前に ``_cat/aliases`` で ``fess.search``/``fess.update`` が新しいインデックスを + 指していることを確認してください（|Fess| のログは失敗時のみ警告を出すため、静かなことは + 成功の証拠にはなりません）。旧インデックスは自動削除されないため、不要になったら手動で + 削除してください（新旧両方のインデックスが存在する間、ディスク使用量はおおむね通常の + 2倍になります）。 +4. 上記のエイリアス切り替えの完了を確認した後、管理画面 > システム > スケジューラ で + Content Chunk Vector Indexer ジョブを有効化し、実行します（クロールのやり直しは不要です。 + ジョブは既存インデックスの ``_source`` から ``content`` を読み出してチャンク化・埋め込みを + 行います）。 + +.. note:: + + 手順1で ``content_chunker.search.enabled=true`` まで投入すると、手順2の再起動から手順4の完了 + までの間、検索のたびにクエリの埋め込みだけが実行され、結果には反映されない状態になります。 + ``openai`` / ``gemini`` / ``bedrock`` など従量課金のプロバイダを使用する場合は、 + ``content_chunker.search.enabled=true`` の投入と再起動を手順4の完了後に行ってください。 + +fess-webapp-semantic-search プラグインを利用していた場合 +-------------------------------------------------------- + +|Fess| 15.7 以前でセマンティック検索を提供していた ``fess-webapp-semantic-search`` +プラグインは、15.10 でコアに統合されたため **不要になりました（非推奨）**。上記 +「既存ユーザーで、ベクトル検索を利用したい場合」の手順に加えて、以下の対応も +必要です。 + +1. **プラグインの削除**: ``app/WEB-INF/plugin/`` から ``fess-webapp-semantic-search-*.jar`` を + 削除します（Docker の場合は ``FESS_PLUGINS`` から除外します）。 + +2. **旧設定の削除**: 起動オプションから ``-Dfess.semantic_search.*`` の設定をすべて削除します。 + また、旧プラグイン用に ``-Drank.fusion.searchers=default,semantic`` を指定していた場合は + 削除します。指定したままだと、新しいセマンティックサーチャー（``semantic_chunk``）が + Rank Fusion から除外され、起動時に警告ログが出力されます。 + +3. **旧 ingest pipeline のデタッチ**: 旧プラグインは、``-Dfess.semantic_search.pipeline`` を + 設定していた場合、インデックスの作成時に ``default_pipeline``\ （ニューラル検索用の ingest + pipeline）をインデックス設定へ埋め込みます。**プラグインを削除しても pipeline はインデックス + 側に残り、動作し続ける** ため、「既存ユーザーで、ベクトル検索を利用したい場合」の再インデク + シングを行う **前に** 解除してください。再インデクシング後の新しいインデックスにはこの設定が + 付かないため、後から実行しても意味がありません。``_cat/aliases`` で ``fess.search`` が指す + ``fess.`` を確認し、エイリアスではなく実体のインデックス名を指定します:: + + curl -XPUT "http://localhost:9200/fess./_settings" \ + -H "Content-Type: application/json" -d ' + {"index": {"default_pipeline": "_none"}}' + + インデックス設定を解除しても、ingest pipeline 自体は検索エンジン側に残ります。今後使用しない + 場合は削除してください:: + + curl -XDELETE "http://localhost:9200/_ingest/pipeline/" + +4. **新設定の追加**: 本ページの設定リファレンスに従い、``content_chunker.*`` の設定を + ``system.properties`` に行います。ML Commons のモデルを引き続き使用する場合は + ``content_chunker.embedding.name=opensearch`` を指定し、既存の ``model_id`` を + ``content_chunker.embedding.opensearch.model.id`` に設定します。 + +5. **インデックスの再作成とジョブ実行**: 旧プラグインが格納していたベクトルフィールド + （既定の構成では ``content_vector``）と、新しいコア機能が使う ``content_chunk_vector`` + フィールドは別物のため、旧ベクトルを新機能で利用することはできません。一方で、再インデク + シングは ``_source`` をそのままコピーするため、旧ベクトルは新しいインデックスにも複製され、 + 動的マッピングでディスクを消費し続けます。再インデクシングの **前に** 除去しておくことを + 推奨します（フィールド名を変更していた場合は読み替えてください）:: + + curl -XPOST "http://localhost:9200/fess.search/_update_by_query" \ + -H "Content-Type: application/json" -d ' + { + "query": {"exists": {"field": "content_vector"}}, + "script": {"source": "ctx._source.remove(\"content_vector\")"} + }' + + その後、管理画面 > システム情報 > メンテナンス で「再インデクシング」を実行し、 + Content Chunk Vector Indexer ジョブを有効化・実行してベクトルを生成し直してください。 + +注意事項 +======== + +埋め込みモデル（次元数）の変更 +------------------------------ + +埋め込みモデルを次元数の異なるモデルへ変更する場合は、以下の順序で行います。 + +1. 既存の古いベクトルを削除します。次元数の異なる古いベクトルが残ったまま再インデクシングすると、 + 新しいマッピングがそれらを受け付けられず、該当ドキュメントが新インデックスにコピーされない + まま処理が進みます。|Fess| は再インデクシングの HTTP ステータスしか確認しないため、管理画面 + にはエラーが表示されないままドキュメントが欠落します:: + + curl -XPOST "http://localhost:9200/fess.search/_update_by_query" \ + -H "Content-Type: application/json" -d ' + { + "query": {"exists": {"field": "content_chunk_status"}}, + "script": {"source": "ctx._source.remove(\"content_chunk_vector\"); ctx._source.remove(\"content_chunk_status\")"} + }' + + .. note:: + + 対象には ``fess.update``\ （再インデクシングの読み出し元となる更新用エイリアス）を指定して + も構いません。また、この操作では ``content`` フィールドはチャンクの配列のまま残ります。 + 次回のジョブ実行時に連結し直して再分割されるため、``content_chunker.length.overlap`` に + 0 以外を設定している場合は、重複部分が二重に含まれた状態で再分割されます。気になる場合は + 該当ドキュメントを再クロールしてください。 + +2. ``content_chunker.embedding.dimension`` と各プロバイダのモデル設定を変更します。 +3. 「セットアップ手順」の「3. インデックスの再作成（既存の環境で有効化する場合）」に従って + インデックスを再作成し、インデクサジョブを再実行します。 + +同じ次元数の別モデルへの変更 +---------------------------- + +``content_chunker.embedding.opensearch.model.id`` など埋め込みモデルの設定を、次元数が同じ別の +モデルに変更しても、|Fess| はエラーも警告も出さずに受け付けます。検査されるのは次元数だけで、 +ベクトルを作成したモデルはインデックスに記録されないためです。この状態では、保存済みのベクトルは +旧モデル、検索時のクエリベクトルは新モデルで作られ、両者は別のベクトル空間にあるため、検索結果の +関連性が崩れます。また、コサイン類似度の値の分布はモデルごとに異なるため、旧モデルに合わせて調整した +``content_chunker.search.min_score`` が新モデルでは厳しすぎて、ほとんどの結果が足切りされることが +あります。 + +モデルを切り替えるときは、新しいモデルを設定したうえで、上記「埋め込みモデル（次元数）の変更」の +手順1と同じ ``_update_by_query`` で ``content_chunk_vector`` と ``content_chunk_status`` を削除し、 +インデクサジョブを再実行してすべてのドキュメントのベクトルを作り直してください（次元数が同じなので +インデックスの再作成は不要です）。``content_chunker.search.min_score`` を設定している場合は、 +新しいモデルで見直してください。 + +次元数を設定せずにインデックスを作成した場合 +-------------------------------------------- + +``content_chunker.embedding.dimension`` が未設定のまま ``fess.search`` インデックスを作成すると、 +``content_chunk_vector`` のマッピングは警告なしで ``768`` 次元になり、作成後は変更できません。 +この状態でインデクサジョブを実行すると、埋め込み処理の実行時には次元数を読み取れずエラーに +なるため、ドキュメントは ``fail`` になります。 + +- 使用するモデルの次元数が ``768`` の場合は、``content_chunker.embedding.dimension=768`` を設定 + します。マッピングと一致するため、インデックスの再作成は不要です。 +- ``768`` 以外の場合は、正しい次元数を設定します。マッピング（``768``）と設定値が食い違っている + 間、インデクサジョブは ERROR ログを出力して実行をスキップします。上記「埋め込みモデル + （次元数）の変更」の手順3と同じ方法でインデックスを再作成してください。 + +どちらの場合も、すでに ``fail`` になったドキュメントは自動では再処理されません。インデックスを +再作成する場合は、「埋め込みモデル（次元数）の変更」の手順1の ``_update_by_query`` が +``content_chunk_status`` も削除します。再作成しない場合は、``content_chunker.job.retry_failed`` を +一時的に ``true`` にしてジョブを再実行してください。 + +ディスク使用量 +-------------- + +チャンクベクトルは検索用のインデックス構造に加えて ``_source`` にも保持されるため、 +ドキュメントあたり「チャンク数 × 次元数」に比例したディスク容量を追加で消費します。 +容量が問題になる場合は ``content_chunker.length.chunk_size`` や +``content_chunker.max_chunks_per_document`` で調整してください。 + +chunk-only モード +----------------- + +``content_chunker.embedding.name=none`` を設定すると、埋め込みベクトルを生成せずに +チャンク分割のみを行います（``content_chunk_status`` は ``chunked``）。 +埋め込みプロバイダの準備前にチャンク分割だけを先行して実行しておき、後からプロバイダを設定して +ジョブを再実行すると、格納済みのチャンクに対してベクトルだけが追加生成されます +（再分割は行われません）。 + +大規模コーパスでのメモリ設定 +---------------------------- + +インデクサジョブの子JVMは、``fess_config.properties`` の ``jvm.chunk.options`` +（デフォルトは ``-Xms128m -Xmx1g`` を含む JVM オプション）で起動されます。 +``content_chunker.job.max_documents_per_run`` の既定値が無制限のため、1回の実行で保留中の +全ドキュメントIDをメモリ上に保持します。ドキュメントIDは SHA-512 ダイジェスト（128文字）で、 +1件あたりおおむね 200 バイトをヒープに保持します。チャンク処理自体にも 200〜250MB 程度を使う +ため、**100〜200万件を超えるコーパス** では ``jvm.chunk.options`` の ``-Xmx`` を引き上げるか、 +``content_chunker.job.max_documents_per_run`` に有限値を設定して分割実行してください。 +``jvm.chunk.options`` は ``app/WEB-INF/classes/fess_config.properties``\ （RPM/DEB 版は +``/etc/fess/fess_config.properties``）で上書きします（JVMオプションの考え方は +:doc:`setup-memory` を参照してください）。 + +同じく既定値が無制限になったことで、``openai`` 、 ``gemini`` 、 ``bedrock`` など従量課金制の埋め込みプロバイダを +使用している場合はコスト面の影響もあります。初回のインデクサジョブ実行で既存コーパス全体の +埋め込みが一度に生成され、その分の利用料金も一度に発生します。費用を複数回の実行に分散させたい +場合は、``content_chunker.job.max_documents_per_run`` に有限の値を設定してください。 + +参考情報 +======== + +- :doc:`rank-fusion` - Rank Fusion（ハイブリッド検索）の設定 +- :doc:`rag-chat` - AI検索モード機能の設定 +- :doc:`llm-overview` - LLM統合の概要 +- :doc:`llm-ollama` - Ollamaの設定 +- :doc:`setup-memory` - JVMメモリ設定 +- :doc:`../install/upgrade` - アップグレード手順 diff --git a/ja/15.10/config/security-role.rst b/ja/15.10/config/security-role.rst new file mode 100644 index 000000000..1c34134a6 --- /dev/null +++ b/ja/15.10/config/security-role.rst @@ -0,0 +1,72 @@ +================= +ロールベース検索の設定 +================= + +ロールベース検索について +================== + +|Fess| では任意の認証システムで認証されたユーザーの認証情報を元に検索結果を出し分けることができます。 +たとえば、ロールaを持つユーザーAは検索結果にロールaの情報が表示されるが、ロールaを持たないユーザーBは検索してもそれが表示されません。 +この機能を利用することで、ポータルやシングルサインオン環境でログインしているユーザーの所属する部門別や役職別などに検索を実現することができます。 + +|Fess| のロールベース検索ではロール情報を以下より取得できます。 + +- リクエストパラメーター + +- リクエストヘッダー + +- クッキー + +- |Fess| の認証情報 + +ポータルやエージェント型シングルサインオンシステムでは認証時に |Fess| の稼働しているドメインとパスに対してクッキーで認証情報を保存することで、ロール情報を取得することができます。 +また、リバースプロキシ型シングルサインオンシステムでは |Fess| へのアクセス時にリクエストパラメーターやリクエストヘッダーに認証情報を付加することでロール情報を取得することができます。 + +.. note:: + リクエストパラメーター・リクエストヘッダー・クッキーからのロール取得は、初期状態では無効になっています。 + これらを利用する場合は、 ``app/WEB-INF/classes/fess.xml`` の ``roleQueryHelper`` コンポーネントで、参照するキー名（ ``parameterKey`` 、 ``headerKey`` 、 ``cookieKey`` ）や値の暗号化（ ``encryptedParameterValue`` など）、区切り文字（ ``valueSeparator`` 、 ``roleSeparator`` ）を設定する必要があります。 + 初期状態で有効なのは、 |Fess| の認証情報を利用したロールベース検索のみです。 + +ロールベース検索の設定 +================= + +ここでは |Fess| の認証情報を利用したロールベース検索の設定方法を説明します。 + +|Fess| の管理画面での設定 +--------------------- + +|Fess| を起動して管理者としてログインします。 +ロールおよびユーザーを作成します。 +たとえば、ロール管理画面で Role1 を作成し、ユーザー管理画面で Role1 に属するユーザーを作成します。 +グループ単位で割り当てたい場合は、グループ管理画面でグループを作成し、ユーザーに割り当てます。 + +次にクロール設定において、パーミッション欄に ``{role}Role1`` を記述して保存します。 +ユーザー単位で指定する場合は ``{user}ユーザー名`` 、グループ単位で指定する場合は ``{group}グループ名`` で記述することができます。 +複数のパーミッションを指定する場合は、改行で区切って記述します。 + +あとはこのクロール設定でクロールすることで、指定したロール・ユーザー・グループに属するユーザーだけで検索可能なインデックスが作成されます。 +ログインしたユーザーには、自分自身を表す ``{user}ユーザー名`` 、所属するロールの ``{role}`` 、所属するグループの ``{group}`` のパーミッションが自動的に付与され、ドキュメントに設定されたパーミッションと照合されます。 + +.. note:: + 特定のロール・ユーザー・グループからのアクセスを明示的に拒否したい場合は、 ``(deny){role}Role1`` のように ``(deny)`` を付けて記述します（ ``(allow)`` を付けた場合は許可となり、無指定時と同じ扱いです）。 + +.. note:: + LDAP やシングルサインオンと連携している場合、ユーザーのロール・グループ情報は認証元から取得され、同様にパーミッションとして扱われます。 + LDAP 連携時の動作は ``fess_config.properties`` の ``ldap.role.search.user.enabled`` 、 ``ldap.role.search.group.enabled`` 、 ``ldap.role.search.role.enabled`` （いずれも初期値は ``true`` ）で制御できます。 + +ログイン +------ + +管理画面からログアウトします。 +Role1 に属するユーザーでログインします。 +ログインに成功すると検索画面のトップにリダイレクトされます。 + +通常通り検索すると、クロール設定で Role1 のロールが設定されたものだけが表示されます。 + +また、ログインしていない状態での検索は、guest ユーザーによる検索となります。 +ログインしていないユーザーに対して表示したいドキュメントには、クロール設定のパーミッション欄に ``{role}guest`` を設定してください（初期値は ``role.search.guest.permissions`` で定義されています）。 + +ログアウト +-------- + +管理者以外のユーザーでログインした状態で検索画面でログアウトを選択することでログアウトされます。 diff --git a/ja/15.10/config/security-virtual-host.rst b/ja/15.10/config/security-virtual-host.rst new file mode 100644 index 000000000..5fd030fa9 --- /dev/null +++ b/ja/15.10/config/security-virtual-host.rst @@ -0,0 +1,91 @@ +======== +仮想ホスト +======== + +仮想ホストについて +============== + +|Fess| にアクセスされた時のホスト名（HTTPの ``Host`` ヘッダーの値）によって、検索結果を出し分けることができます。 +1台の |Fess| サーバーを複数のホスト名で公開し、ホスト名ごとに異なる検索対象（クロール設定）やページデザインを提供できます。 +仮想ホスト名と同じ名前の静的テーマを用意すると、ホストごとに検索画面の見た目を変えることもできます。 + +仮想ホスト機能はデフォルトでは無効（未設定）です。以下の手順で設定します。 + +システム設定 +---------- + +:doc:`管理者ガイド > 全般の設定 <../admin/general-guide>` の「仮想ホスト」で、アクセス元のホスト名と仮想ホスト名の対応を設定します。ここで設定した仮想ホスト名をクロール設定で指定します。 + +**書式** + +1行につき1つの仮想ホストを次の形式で記述します。 + +:: + + ヘッダー名:ヘッダー値=仮想ホスト名 + +.. list-table:: + + * - *ヘッダー名* + - 判定に使用するHTTPリクエストヘッダーの名前。通常は ``Host`` を指定します。リバースプロキシ経由でアクセスする場合などは ``X-Forwarded-Host`` を指定することもできます。 + * - *ヘッダー値* + - 上記ヘッダーに含まれるホスト名（必要に応じて ``ホスト名:ポート番号`` の形式）。アクセス時にクライアントが送信するヘッダーの値と完全一致（大文字・小文字は区別しない）した場合に、この仮想ホストが適用されます。 + * - *仮想ホスト名* + - クロール設定で指定する仮想ホスト名 + +**例** + +:: + + Host:abc.example.com=host1 + Host:192.168.1.123:8080=host2 + +.. note:: + + 判定はホスト名の名前解決（DNS）ではなく、リクエストヘッダーの値との文字列一致で行われます。 + ブラウザーが送信する ``Host`` ヘッダーには、標準ポート（HTTPは80、HTTPSは443）でアクセスした場合はポート番号が含まれず、それ以外のポートでアクセスした場合は ``ホスト名:ポート番号`` の形式でポート番号が含まれます。 + そのため、標準ポート以外で公開する場合は ``Host:abc.example.com:8080=host1`` のようにポート番号まで含めて指定してください。 + +.. note:: + + 仮想ホスト名に使用できる文字は英数字とアンダースコア（ ``a-z`` 、 ``A-Z`` 、 ``0-9`` 、 ``_`` ）のみです。 + それ以外の文字は自動的に除去されます。 + + また、以下の名前は予約されているため仮想ホスト名として使用できません： + ``admin`` 、 ``common`` 、 ``error`` 、 ``login`` 、 ``profile`` + +仮想ホストごとのページデザイン +------------------------------ + +仮想ホストに専用の検索画面を用意するには、 ``theme.yml`` の ``name`` が仮想ホスト名を小文字にしたもの（例: ``host1`` ）である静的テーマをインストールします。 +その仮想ホストに一致するリクエストにはそのテーマが、それ以外のリクエストにはデフォルトのテーマが使われます。 +このテーマをデフォルトテーマに設定する必要はありません。同梱のテーマからテーマを作る方法は :ref:`theme-customize-bundled` を、インストール方法は :doc:`../admin/theme-guide` を参照してください。 + +.. note:: + + |Fess| 15.10 からは、設定を保存しても ``WEB-INF/view/仮想ホスト名`` にJSPは生成されません。 + ログイン画面（ ``/login/`` ）はすべての仮想ホストで共通の画面（ ``WEB-INF/view/admin/login/`` ）で表示され、仮想ホストごとに変えることはできません。 + 仮想ホストごとの見た目は、上記のとおり仮想ホスト名と同じ名前の静的テーマで変えます。 + + +クロール設定 +--------- + +ウェブクロール設定、ファイルクロール設定、データストアクロール設定のいずれかにおいて「仮想ホスト」を指定します。 +「仮想ホスト」はシステム設定で設定した仮想ホスト名のいずれかを指定します。1つのクロール設定に複数の仮想ホストを指定することもできます（1行に1つ）。 + +仮想ホストでアクセスされた検索では、その仮想ホストが指定されたクロール設定のドキュメントだけが検索結果に表示されます。 +どの仮想ホストにも一致しないアクセス（仮想ホストが未設定の通常アクセス）では、この絞り込みは行われず、通常どおりすべての検索結果が表示されます。 + +**例** + +.. list-table:: + + * - *仮想ホスト* + - ``host1`` + + +ユーザータグ +------------ + +ログインしたユーザーが検索結果のドキュメントに付けるタグ（マイタグ）も、仮想ホストに従います（タグ機能を有効にした場合）。仮想ホストでアクセスして作成したタグは、その仮想ホストでだけ一覧に表示され、使えます。どの仮想ホストにも一致しないアクセスでは、すべてのタグが見えます。仮想ホストを持つタグは、その仮想ホストを持つクロール設定のドキュメントにだけ付きます。詳しくは :doc:`../admin/tagtype-guide` と :doc:`../api/api-tag` を参照してください。 diff --git a/ja/15.10/config/setup-memory.rst b/ja/15.10/config/setup-memory.rst new file mode 100644 index 000000000..673d304d7 --- /dev/null +++ b/ja/15.10/config/setup-memory.rst @@ -0,0 +1,439 @@ +============ +メモリ設定 +============ + +概要 +==== + +Java アプリケーションでは、プロセスごとに使用する最大ヒープメモリを設定する必要があります。 +|Fess| では、以下の3つのコンポーネントでそれぞれメモリ設定を行います。 + +- Fess ウェブアプリケーション +- クローラープロセス +- OpenSearch + +適切なメモリ設定を行うことで、パフォーマンスの向上と安定した動作を実現できます。 + +Fess ウェブアプリケーションのメモリ設定 +====================================== + +設定が必要な場合 +---------------- + +以下のような場合にメモリサイズの調整を検討してください。 + +- ``fess.log`` に OutOfMemory エラーが記録される +- 大量の同時アクセスを処理する必要がある +- 管理画面の操作が遅い、またはタイムアウトする + +デフォルトのメモリサイズは、一般的な利用では十分ですが、負荷が高い環境では増量が必要です。 + +環境変数による設定 +------------------ + +環境変数 ``FESS_HEAP_SIZE`` を設定します。 + +:: + + export FESS_HEAP_SIZE=2g + +単位: + +- ``m``: メガバイト +- ``g``: ギガバイト + +詳細なメモリ制御 +~~~~~~~~~~~~~~~~ + +``FESS_HEAP_SIZE`` は ``-Xms`` と ``-Xmx`` を同じ値に設定しますが、初期ヒープサイズと最大ヒープサイズを個別に制御したい場合は、``FESS_MIN_MEM`` と ``FESS_MAX_MEM`` 環境変数を使用します。 + +:: + + export FESS_MIN_MEM=256m + export FESS_MAX_MEM=2g + +.. list-table:: プラットフォーム別デフォルトメモリ設定 + :header-rows: 1 + :widths: 30 35 35 + + * - プラットフォーム + - FESS_MIN_MEM (デフォルト) + - FESS_MAX_MEM (デフォルト) + * - Linux + - 256m + - 2g + * - Windows + - 256m + - 1g + +.. note:: + ``FESS_HEAP_SIZE`` を設定した場合、``FESS_MIN_MEM`` と ``FESS_MAX_MEM`` は無視されます。 + +.. note:: + RPM/DEB パッケージでは、環境設定ファイル（ ``/etc/sysconfig/fess`` 、DEB は ``/etc/default/fess`` ）に ``FESS_HEAP_SIZE=512m`` が設定されています。そのため、ヒープは上の表の既定値ではなく 512m に固定されます。ヒープサイズを変更するときは、この ``FESS_HEAP_SIZE`` の値を書き換えてください。 + +RPM/DEBパッケージの場合 +------------------------ + +RPMパッケージでインストールした場合は、``/etc/sysconfig/fess`` を編集します。 + +:: + + FESS_HEAP_SIZE=2g + +DEBパッケージの場合は、``/etc/default/fess`` を編集します。 + +:: + + FESS_HEAP_SIZE=2g + +.. warning:: + メモリサイズを変更した後は、|Fess| サービスを再起動する必要があります。 + +推奨メモリサイズ +---------------- + +.. list-table:: + :header-rows: 1 + :widths: 30 30 40 + + * - 環境 + - 推奨ヒープサイズ + - 備考 + * - 開発・テスト環境 + - 512m〜1g + - 小規模なインデックス + * - 小規模本番環境 + - 1g〜2g + - 数万〜数十万ドキュメント + * - 中規模本番環境 + - 2g〜4g + - 数十万〜数百万ドキュメント + * - 大規模本番環境 + - 4g〜8g + - 数百万以上のドキュメント + +クローラーのメモリ設定 +====================== + +設定が必要な場合 +---------------- + +以下のような場合にクローラーのメモリサイズを増やす必要があります。 + +- 並列クロール数を増やす場合 +- 大きなファイルをクロールする場合 +- クロール実行中に OutOfMemory エラーが発生する場合 + +設定方法 +-------- + +``app/WEB-INF/classes/fess_config.properties`` または ``/etc/fess/fess_config.properties`` を編集します。 + +``jvm.crawler.options`` は、クローラープロセスの JVM オプションを改行（ ``\n`` ）で区切って並べた 1 つの設定値です。値を書き換えると既定のオプションがすべて置き換わるため、 ``-Xmx512m`` だけを書くと、 ``-Dfile.encoding=UTF-8`` や G1GC の指定などの既定のオプションもなくなります。 ``fess_config.properties`` に記載された既定値を残したまま、ヒープサイズの行だけを書き換えてください。 + +例えば、最大ヒープを 1GB に変更する場合は、既定値の ``-Xmx512m`` の行を次のように書き換えます。 + +:: + + -Xms128m\n\ + -Xmx1g\n\ + +.. note:: + この設定は、クローラープロセス単位(スケジューラーのジョブ単位)で適用されます。 + 複数のクロールジョブを同時に実行する場合は、それぞれのジョブで指定したメモリが使用されます。 + +推奨設定 +-------- + +- **通常のWebクロール**: 512m〜1g +- **大量並列クロール**: 1g〜2g +- **大きなファイルのクロール**: 2g〜4g + +詳細なJVMオプション +------------------ + +クローラーの詳細なJVMオプションは、``jvm.crawler.options`` で設定できます。 +デフォルトの設定には、以下のような最適化が含まれています。 + +**主要なオプション:** + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - オプション + - 説明 + * - ``-Xms128m -Xmx512m`` + - 初期ヒープサイズと最大ヒープサイズ + * - ``-XX:MaxMetaspaceSize=128m`` + - Metaspaceの最大サイズ + * - ``-XX:+UseG1GC`` + - G1ガベージコレクタの使用 + * - ``-XX:MaxGCPauseMillis=60000`` + - GC一時停止の最大目標時間(60秒)。クローラーではGCを積極的に制限しない設定(通常のアプリケーションでは200ms程度が一般的) + * - ``-XX:-HeapDumpOnOutOfMemoryError`` + - OutOfMemory時のヒープダンプを無効化 + +OpenSearch のメモリ設定 +======================= + +重要な考慮事項 +-------------- + +OpenSearch では、以下の2点を考慮してメモリを設定する必要があります。 + +1. **Javaヒープメモリ**: OpenSearch のプロセスで使用 +2. **OSファイルシステムキャッシュ**: 検索パフォーマンスに重要 + +.. warning:: + Javaヒープメモリを大きくしすぎると、OSファイルシステムキャッシュに + 使用できるメモリが減少し、検索パフォーマンスが低下します。 + +設定方法 +-------- + +Linux環境 +~~~~~~~~~ + +OpenSearch のヒープメモリは、``config/jvm.options`` で設定することを推奨します。 + +``config/jvm.options`` を編集: + +:: + + -Xms2g + -Xmx2g + +.. note:: + 最小ヒープサイズ(``-Xms``)と最大ヒープサイズ(``-Xmx``)は同じ値に設定することを推奨します。 + +.. note:: + ``OPENSEARCH_HEAP_SIZE`` 環境変数は OpenSearch 3.x 以降では非推奨です。代わりに ``config/jvm.options`` または ``OPENSEARCH_JAVA_OPTS`` 環境変数を使用してください。 + + :: + + export OPENSEARCH_JAVA_OPTS="-Xms2g -Xmx2g" + +Windows環境 +~~~~~~~~~~~ + +``config\jvm.options`` ファイルを編集します。 + +:: + + -Xms2g + -Xmx2g + +推奨メモリサイズ +---------------- + +.. list-table:: + :header-rows: 1 + :widths: 30 30 40 + + * - インデックスサイズ + - 推奨ヒープサイズ + - 推奨合計メモリ + * - 〜10GB + - 2g + - 4GB以上 + * - 10GB〜50GB + - 4g + - 8GB以上 + * - 50GB〜100GB + - 8g + - 16GB以上 + * - 100GB以上 + - 16g〜31g + - 32GB以上 + +.. warning:: + OpenSearch のヒープメモリは 32GB を超えないように設定してください。 + 32GB を超えると、Compressed OOP が無効になりメモリ効率が低下します。 + +ベストプラクティス +------------------ + +1. **物理メモリの50%をヒープに割り当て** + + サーバーの物理メモリの約50%を OpenSearch のヒープに割り当てます。 + 残りはOSとファイルシステムキャッシュに使用されます。 + +2. **最大31GBまで** + + ヒープサイズは最大31GBまでとし、それ以上必要な場合はノードを増やします。 + +3. **本番環境での確認** + + OpenSearch の公式ドキュメントを参照し、環境に応じた最適な設定を行ってください。 + +サジェスト・サムネイル処理のメモリ設定 +====================================== + +サジェスト生成プロセス +---------------------- + +サジェスト生成処理のメモリ設定は、``jvm.suggest.options`` で設定します。 + +既定のオプションをすべて含む設定値なので、クローラーと同様に ``-Xmx256m`` の行だけを書き換えてください。 + +デフォルトでは以下の設定が使用されます: + +- 初期ヒープ: 128MB +- 最大ヒープ: 256MB +- Metaspace最大: 128MB + +サムネイル生成プロセス +---------------------- + +サムネイル生成処理のメモリ設定は、``jvm.thumbnail.options`` で設定します。 + +既定のオプションをすべて含む設定値なので、クローラーと同様に ``-Xmx256m`` の行だけを書き換えてください。 + +デフォルトでは以下の設定が使用されます: + +- 初期ヒープ: 128MB +- 最大ヒープ: 256MB +- Metaspace最大: 128MB + +.. note:: + サムネイル生成で大きな画像を処理する場合は、メモリを増やす必要があります。 + +メモリ監視とチューニング +======================== + +メモリ使用状況の確認 +-------------------- + +Fess のメモリ使用状況 +~~~~~~~~~~~~~~~~~~~~~ + +管理画面の「システム情報」で確認できます。 + +または、JVMの監視ツールを使用: + +:: + + jps -l # Fessプロセスを確認 + jstat -gcutil 1000 # GC統計を1秒ごとに表示 + +OpenSearchのメモリ使用状況 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + curl -X GET "localhost:9200/_nodes/stats/jvm?pretty" + curl -X GET "localhost:9200/_cat/nodes?v&h=heap.percent,ram.percent" + +メモリ不足の兆候 +---------------- + +以下のような症状が現れた場合、メモリ不足の可能性があります。 + +**Fess ウェブアプリケーション:** + +- レスポンスが遅い +- ``OutOfMemoryError`` がログに記録される +- プロセスが予期せず終了する + +**クローラー:** + +- クロールが途中で停止する +- ``OutOfMemoryError`` が ``fess-crawler.log`` に記録される +- 大きなファイルのクロールに失敗する + +**OpenSearch:** + +- 検索が遅い +- インデックス作成が遅い +- ``circuit_breaker_exception`` エラーが発生する + +チューニング手順 +---------------- + +1. **現在のメモリ使用状況を確認** + + 各コンポーネントのメモリ使用状況を監視します。 + +2. **ボトルネックを特定** + + どのコンポーネントがメモリ不足かを特定します。 + +3. **段階的に増加** + + 一度に大きく増やすのではなく、25-50%ずつ増やして効果を確認します。 + +4. **システム全体のバランスを考慮** + + 各コンポーネントの合計メモリが物理メモリを超えないようにします。 + +5. **継続的な監視** + + メモリ使用状況を継続的に監視し、必要に応じて調整します。 + +メモリリーク対策 +---------------- + +メモリリークが疑われる場合: + +1. **ヒープダンプの取得** + +:: + + jmap -dump:format=b,file=heap.bin + +2. **ヒープダンプの分析** + + Eclipse Memory Analyzer (MAT) などのツールで分析します。 + +3. **問題の報告** + + メモリリークを発見した場合は、GitHub Issuesで報告してください。 + +トラブルシューティング +====================== + +OutOfMemoryError が発生する +--------------------------- + +**Fess ウェブアプリケーション:** + +1. ``FESS_HEAP_SIZE`` を増やします。 +2. 同時アクセス数を制限します。 +3. ログレベルを下げて、ログ出力によるメモリ使用を減らします。 + +**クローラー:** + +1. ``jvm.crawler.options`` の ``-Xmx`` を増やします。 +2. 並列クロール数を減らします。 +3. 大きなファイルを除外するようクロール設定を調整します。 + +**OpenSearch:** + +1. ヒープサイズを増やします(最大31GBまで)。 +2. インデックスのシャード数を見直します。 +3. クエリの複雑さを確認します。 + +GCによる停止時間が長い +---------------------- + +1. G1GCの設定を調整します。 +2. ヒープサイズを適切に設定します(大きすぎても小さすぎてもGCが頻発)。 +3. より新しいJavaバージョンへの更新を検討します。 + +メモリ設定後も性能が改善しない +------------------------------ + +1. CPU、ディスクI/O、ネットワークなど他のリソースを確認します。 +2. インデックスの最適化を行います。 +3. クエリやクロール設定を見直します。 + +参考情報 +======== + +- :doc:`setup-port-network` - ポートとネットワーク設定 +- :doc:`crawler-advanced` - クローラー詳細設定 +- :doc:`admin-logging` - ログ設定 +- `OpenSearch Memory Settings `_ +- `Java GC Tuning `_ diff --git a/ja/15.10/config/setup-port-network.rst b/ja/15.10/config/setup-port-network.rst new file mode 100644 index 000000000..3bbbfa7c1 --- /dev/null +++ b/ja/15.10/config/setup-port-network.rst @@ -0,0 +1,465 @@ +====================== +ポートとネットワーク設定 +====================== + +概要 +==== + +本セクションでは、|Fess| のネットワーク関連の設定について説明します。 +ポート番号の変更、プロキシ設定、HTTP通信の設定など、ネットワーク接続に関する設定を取り扱います。 + +使用ポートの設定 +================ + +デフォルトポート +---------------- + +|Fess| はデフォルトで以下のポートを使用します。 + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - サービス + - ポート番号 + * - Fess ウェブアプリケーション + - 8080 + * - OpenSearch (HTTP) + - 9200 + * - OpenSearch (Transport) + - 9300 + +Fess ウェブアプリケーションのポート変更 +-------------------------------------- + +Linux環境での設定 +~~~~~~~~~~~~~~~~~ + +Linux 環境でポート番号を変更する場合は、``bin/fess.in.sh`` を編集します。 + +:: + + FESS_JAVA_OPTS="$FESS_JAVA_OPTS -Dfess.port=8080" + +例えば、ポート 80 を使用する場合: + +:: + + FESS_JAVA_OPTS="$FESS_JAVA_OPTS -Dfess.port=80" + +.. note:: + 1024 以下のポート番号を使用する場合は、root 権限または適切な権限設定(CAP_NET_BIND_SERVICE)が必要です。 + +環境変数による設定 +~~~~~~~~~~~~~~~~~~ + +環境変数でポート番号を指定することもできます。 + +:: + + export FESS_PORT=8080 + +.. warning:: + ``FESS_PORT`` 環境変数は Linux 環境でのみ有効です。Windows 環境では ``bin\fess.in.bat`` の ``-Dfess.port`` を直接編集してください。 + +RPM/DEBパッケージの場合 +~~~~~~~~~~~~~~~~~~~~~~~~ + +RPMパッケージでは ``/etc/sysconfig/fess``、DEBパッケージでは ``/etc/default/fess`` を編集します。 + +:: + + FESS_PORT=8080 + +Windows環境での設定 +~~~~~~~~~~~~~~~~~~~ + +Windows 環境では、``bin\fess.in.bat`` を編集します。 + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.port=8080 + +Windowsサービスとして登録する場合 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Windows 環境でサービス登録して使用する場合は、``bin\service.bat`` のポート設定も変更してください。 +詳細は :doc:`setup-windows-service` を参照してください。 + +コンテキストパスの設定 +---------------------- + +|Fess| をサブディレクトリで公開する場合、コンテキストパスを設定できます。 + +Linux環境: + +:: + + export FESS_CONTEXT_PATH=/search + +Windows環境では、``bin\fess.in.bat`` の ``-Dfess.context.path`` を直接編集してください。 + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.context.path=/search + +この設定により、``http://localhost:8080/search/`` でアクセスできるようになります。 + +.. warning:: + ``FESS_CONTEXT_PATH`` 環境変数は Linux 環境でのみ有効です。Windows 環境では ``bin\fess.in.bat`` を直接編集してください。 + +.. warning:: + コンテキストパスを変更した場合、静的ファイルのパスも適切に設定する必要があります。 + +プロキシ設定 +============ + +概要 +---- + +イントラネット内から外部サイトをクロールする場合や、外部APIにアクセスする場合、 +ファイアウォールによって通信がブロックされることがあります。 +そのような環境では、プロキシサーバー経由で通信を行う設定が必要です。 + +クローラー用プロキシの設定 +-------------------------- + +基本設定 +~~~~~~~~ + +管理画面のクロール設定で、設定パラメーターに以下のように指定します。 + +:: + + client.proxyHost=proxy.example.com + client.proxyPort=8080 + +認証が必要なプロキシの設定 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +プロキシサーバーで認証が必要な場合は、以下のように追加します。 + +:: + + client.proxyHost=proxy.example.com + client.proxyPort=8080 + client.proxyUsername=proxyuser + client.proxyPassword=proxypass + +特定のホストをプロキシから除外 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +クローラーのプロキシ設定では、特定ホストの除外（nonProxyHosts）はサポートされていません。 +特定のホストをプロキシから除外する場合は、環境変数 ``FESS_NON_PROXY_HOSTS`` を使用してください。 +この設定はJavaシステムプロパティ ``http.nonProxyHosts`` に変換され、Fess全体のHTTP通信に適用されます。 + +:: + + FESS_NON_PROXY_HOSTS=localhost|*.local|192.168.* + +クローラーのデフォルトプロキシ設定 +---------------------------------- + +クロール設定で個別に ``client.proxyHost`` を指定していない場合のデフォルトプロキシを ``fess_config.properties`` で設定できます。 +この設定は、クローラーのデフォルトプロキシに加えて、LLM連携のHTTP通信やプラグインのダウンロードにも適用されます。 +一方で、SSO認証など一部のJavaライブラリによる通信には適用されません。 +Fessアプリケーション全体(SSO認証を含む)でプロキシを適用する場合は、後述の環境変数(``FESS_PROXY_HOST`` 等)を使用してください。 + +:: + + http.proxy.host=proxy.example.com + http.proxy.port=8080 + http.proxy.username=proxyuser + http.proxy.password=proxypass + +.. warning:: + パスワードは暗号化されずに保存されます。適切なファイルパーミッションを設定してください。 + +.. note:: + ``http.proxy.*`` 設定はSSO認証などには適用されません。SSO認証を含むFessアプリケーション全体（JVM全体のHTTP通信）でプロキシを使用する場合は、環境変数 ``FESS_PROXY_HOST``、``FESS_PROXY_PORT`` を設定してください。詳細は後述の「環境変数によるプロキシ設定」を参照してください。 + +環境変数によるプロキシ設定 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +SSO認証などのJavaライブラリがプロキシを使用する場合は、環境変数で設定する必要があります。 +これらの環境変数はJavaシステムプロパティ（``http.proxyHost``、``https.proxyHost`` 等）に変換されます。 + +:: + + FESS_PROXY_HOST=proxy.example.com + FESS_PROXY_PORT=8080 + FESS_NON_PROXY_HOSTS=localhost|*.local|192.168.* + +RPMパッケージでは ``/etc/sysconfig/fess``、DEBパッケージでは ``/etc/default/fess`` に設定します。 + +.. note:: + ``fess_config.properties`` の ``http.proxy.*`` 設定は、クローラーのデフォルトプロキシのほか、LLM連携やプラグインのダウンロードに使用されます。 + SSO認証を含むFessアプリケーション全体（JVM全体のHTTP通信）でプロキシを使用する場合は、上記の環境変数を設定してください。 + +HTTP通信設定 +============ + +ファイルアップロードの制限 +-------------------------- + +管理画面からのファイルアップロードサイズを制限できます。 + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - 設定項目 + - 説明 + * - ``http.fileupload.max.size`` + - 最大ファイルアップロードサイズ(デフォルト: 262144000バイト = 250MB) + * - ``http.fileupload.threshold.size`` + - メモリ上に保持する閾値サイズ(デフォルト: 262144バイト = 256KB) + * - ``http.fileupload.max.file.count`` + - 一度にアップロードできるファイル数(デフォルト: 10) + +``fess_config.properties`` での設定例: + +:: + + http.fileupload.max.size=524288000 + http.fileupload.threshold.size=524288 + http.fileupload.max.file.count=20 + +OpenSearch接続設定 +------------------ + +OpenSearchへの接続先URLとヘルスチェック間隔を設定できます。 + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - 設定項目 + - 説明 + * - ``search_engine.http.url`` + - OpenSearchのURL(デフォルト: http://localhost:9200)。環境変数 ``SEARCH_ENGINE_HTTP_URL`` が優先されます(下記参照)。 + * - ``search_engine.heartbeat_interval`` + - ヘルスチェック間隔(ミリ秒、デフォルト: 10000) + +OpenSearchの接続先変更 +---------------------- + +接続先の URL は環境変数 ``SEARCH_ENGINE_HTTP_URL`` で指定します。この環境変数は +``fess_config.properties`` の ``search_engine.http.url`` より優先されます。ZIP 版の +``bin/fess.in.sh`` と RPM/DEB 版の環境設定ファイルはこの環境変数に既定で +``http://localhost:9200`` を設定するため、 ``search_engine.http.url`` を変更しても接続先は +変わりません。 + +設定する場所は、インストール方法によって異なります。 + +- ZIP 版: ``bin/fess.in.sh`` の ``SEARCH_ENGINE_HTTP_URL`` の行を編集するか、 |Fess| を + 起動する環境で ``SEARCH_ENGINE_HTTP_URL`` を export します(:doc:`../install/install-linux` + を参照)。 +- RPM/DEB 版: ``/etc/sysconfig/fess`` (RPM)または ``/etc/default/fess`` (DEB)の + ``SEARCH_ENGINE_HTTP_URL`` +- Docker: コンテナの環境変数 ``SEARCH_ENGINE_HTTP_URL`` (:doc:`../install/install-docker` + を参照) +- Windows の ZIP 版: ``bin\fess.in.bat`` の ``-Dfess.search_engine.http_address`` の行 + (:doc:`../install/install-windows` を参照) + +:: + + SEARCH_ENGINE_HTTP_URL=http://opensearch-cluster.example.com:9200 + +複数ノードへの接続 +~~~~~~~~~~~~~~~~~~ + +複数の OpenSearch ノードに接続する場合は、URL をカンマ区切りで指定します。一部のノードが +停止していても、 |Fess| は残りのノードに接続します。 + +:: + + SEARCH_ENGINE_HTTP_URL=http://node1:9200,http://node2:9200,http://node3:9200 + +SSL/TLS接続の設定 +----------------- + +OpenSearch へ HTTPS で接続する場合は、上記と同じ方法で ``https://`` の URL を指定します。 + +:: + + SEARCH_ENGINE_HTTP_URL=https://opensearch.example.com:9200 + +CA 証明書と認証情報は ``fess_config.properties`` に設定します。 + +:: + + search_engine.http.ssl.certificate_authorities=/path/to/ca.crt + search_engine.username=admin + search_engine.password=admin_password + +.. note:: + 証明書の検証を行う場合は、``certificate_authorities`` に CA証明書のパスを指定します。 + +仮想ホスト設定 +============== + +概要 +---- + +|Fess| にアクセスされたホスト名によって、検索結果を出し分けることができます。 +詳細は :doc:`security-virtual-host` を参照してください。 + +基本設定 +-------- + +仮想ホストは、管理画面の「システム > 全般」(``virtual.host.headers``)で設定します。 +1行につき1つの仮想ホストを ``Host:ホスト名[:ポート番号]=仮想ホスト名`` の形式で指定します。 +デフォルトは空(未設定)で、仮想ホスト機能は無効です。 + +:: + + Host:search1.example.com=site1 + Host:search2.example.com=site2 + +.. note:: + ``virtual.host.headers`` の値は、``X-Forwarded-Host,Host`` のようなヘッダー名のリストではありません。 + ``ヘッダー名:ヘッダー値=仮想ホスト名`` という対応を1行ごとに記述します。 + 詳細な書式や制約は :doc:`security-virtual-host` を参照してください。 + +リバースプロキシとの連携 +======================== + +Nginx の設定例 +-------------- + +:: + + server { + listen 80; + server_name search.example.com; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Host $host; + } + } + +Apache の設定例 +--------------- + +:: + + + ServerName search.example.com + + ProxyPreserveHost On + ProxyPass / http://localhost:8080/ + ProxyPassReverse / http://localhost:8080/ + + RequestHeader set X-Forwarded-Proto "http" + RequestHeader set X-Forwarded-Host "search.example.com" + + +SSL/TLS終端 +----------- + +リバースプロキシでSSL/TLS終端を行う場合の設定例(Nginx): + +:: + + server { + listen 443 ssl http2; + server_name search.example.com; + + ssl_certificate /path/to/cert.pem; + ssl_certificate_key /path/to/key.pem; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto https; + proxy_set_header X-Forwarded-Host $host; + } + } + +ファイアウォール設定 +==================== + +必要なポートの開放 +------------------ + +|Fess| を外部からアクセス可能にする場合、以下のポートを開放します。 + +**iptables の設定例:** + +:: + + # Fess ウェブアプリケーション + iptables -A INPUT -p tcp --dport 8080 -j ACCEPT + + # HTTPSでアクセスする場合(リバースプロキシ経由) + iptables -A INPUT -p tcp --dport 443 -j ACCEPT + +**firewalld の設定例:** + +:: + + # Fess ウェブアプリケーション + firewall-cmd --permanent --add-port=8080/tcp + firewall-cmd --reload + +セキュリティグループの設定(クラウド環境) +------------------------------------------ + +AWS、GCP、Azureなどのクラウド環境では、セキュリティグループやネットワークACLで +適切なポートを開放してください。 + +推奨設定: +- インバウンド: 80/443ポート(HTTPリバースプロキシ経由) +- 8080ポートは内部からのみアクセス可能に制限 +- OpenSearchの9200/9300ポートは内部からのみアクセス可能に制限 + +トラブルシューティング +====================== + +ポート変更後にアクセスできない +------------------------------ + +1. |Fess| を再起動したか確認してください。 +2. ファイアウォールで該当ポートが開放されているか確認してください。 +3. ログファイル(``fess.log``)でエラーを確認してください。 + +プロキシ経由でクロールできない +------------------------------ + +1. プロキシサーバーのホスト名とポートが正しいか確認してください。 +2. プロキシサーバーで認証が必要な場合、ユーザー名とパスワードを設定してください。 +3. プロキシサーバーのログで接続試行が記録されているか確認してください。 +4. ``nonProxyHosts`` の設定が適切か確認してください。 + +OpenSearchに接続できない +------------------------- + +1. OpenSearchが起動しているか確認してください。 +2. ``search_engine.http.url`` の設定が正しいか確認してください。 +3. ネットワーク接続を確認してください: ``curl http://localhost:9200`` +4. OpenSearchのログでエラーを確認してください。 + +リバースプロキシ経由でアクセスすると正常に動作しない +---------------------------------------------------- + +1. ``X-Forwarded-Host`` ヘッダーが正しく設定されているか確認してください。 +2. ``X-Forwarded-Proto`` ヘッダーが正しく設定されているか確認してください。 +3. コンテキストパスが正しく設定されているか確認してください。 +4. リバースプロキシのログでエラーを確認してください。 + +参考情報 +======== + +- :doc:`setup-memory` - メモリ設定 +- :doc:`setup-windows-service` - Windowsサービス設定 +- :doc:`security-virtual-host` - 仮想ホスト設定 +- :doc:`crawler-advanced` - クローラー詳細設定 +- `OpenSearch Configuration `_ diff --git a/ja/15.10/config/setup-windows-service.rst b/ja/15.10/config/setup-windows-service.rst new file mode 100644 index 000000000..a6330c227 --- /dev/null +++ b/ja/15.10/config/setup-windows-service.rst @@ -0,0 +1,134 @@ +========================== +Windowsサービスへの登録 +========================== + +Windowsサービスとしての登録 +============================ + +|Fess| を Windows のサービスとして登録することができます。サービスとして登録すると、システム起動時に |Fess| を自動的に起動できます。 +|Fess| を動かすには、OpenSearch を起動しておく必要があります。 +ここでは |Fess| を ``c:\opt\fess`` に、OpenSearch を ``c:\opt\opensearch`` にインストールしてあるものとします（パスは環境に合わせて読み替えてください）。 + +.. note:: + |Fess| および OpenSearch は 64 ビット版のみをサポートしています。 + +事前準備 +-------- + +システムの環境変数として ``JAVA_HOME`` を設定してください。\ ``service.bat`` は ``JAVA_HOME`` が設定されていない場合、エラーで終了します。 + +OpenSearchをサービスとして登録 +------------------------------ + +コマンドプロンプトを管理者権限で起動し、``c:\opt\opensearch\bin\opensearch-service.bat`` を実行します。 + +:: + + > cd c:\opt\opensearch\bin + > opensearch-service.bat install + ... + The service 'opensearch-service-x64' has been installed. + +詳細は `OpenSearch のドキュメント `_ を参照してください。 + +|Fess| の設定 +------------- + +サービスは ``c:\opt\fess\bin\service.bat`` から登録します。\ ``service.bat`` は登録時に ``bin\fess.in.bat`` を読み込み、その内容を |Fess| の起動オプションに反映します。 +OpenSearch へ接続するための設定を ``c:\opt\fess\bin\fess.in.bat`` に追加してください。 + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200 + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=c:/opt/opensearch/config/dictionary/ + +.. note:: + - ``fess.search_engine.http_address`` には、登録した OpenSearch サービスの接続先を指定します。この設定を行わない場合、|Fess| は接続先を見つけられず、検索エンジンのアドレスが設定されていないことを報告して起動しません。 + - OpenSearch を別のホストで実行している場合は、ホスト名または IP アドレスを適切に変更してください。 + - パスの区切り文字には ``/`` を使用してください。 + +|Fess| の検索画面・管理画面のデフォルトのポート番号は ``8080`` です。別のポートに変更する場合は ``c:\opt\fess\bin\fess.in.bat`` の ``-Dfess.port`` を編集します。 + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.port=80 + +.. note:: + サービスとして登録する場合、``bin\service.bat`` 内の ``FESS_PARAMS`` にも ``-Dfess.port=8080`` がハードコードされています。この値は ``fess.in.bat`` の設定よりも優先されるため、ポートを変更する際は ``service.bat`` の ``FESS_PARAMS`` も同様に編集してください。 + +サービスのカスタマイズ（任意） +------------------------------ + +``service.bat install`` を実行する前に環境変数を設定することで、サービスの構成を変更できます。主な環境変数は次のとおりです。 + +.. list-table:: + :header-rows: 1 + + * - 環境変数 + - 説明 + * - ``FESS_START_TYPE`` + - スタートアップの種類（``auto`` または ``manual``）。デフォルトは ``manual`` です。 + * - ``FESS_HEAP_SIZE`` + - ヒープサイズ（例: ``1g``）。最小・最大ヒープサイズを個別に指定する場合は ``FESS_MIN_MEM``\ （デフォルト ``256m``）と ``FESS_MAX_MEM``\ （デフォルト ``1g``）を使用します。 + * - ``SERVICE_USERNAME`` / ``SERVICE_PASSWORD`` + - サービスを実行する Windows アカウント。 + * - ``SERVICE_DISPLAY_NAME`` + - サービスの表示名。 + * - ``SERVICE_DESCRIPTION`` + - サービスの説明。 + +登録方法 +-------- + +管理者権限のコマンドプロンプトから ``c:\opt\fess\bin\service.bat`` を実行します。 + +:: + + > cd c:\opt\fess\bin + > service.bat install + ... + The service 'fess-service-x64' has been installed. + +サービスの設定 +-------------- + +サービスを手動で起動する場合は、OpenSearch サービスを先に起動し、その後 |Fess| サービスを起動します。 +システム起動時に自動的に起動する場合は、スタートアップの種類と依存関係を設定します。 + +1. サービスの全般設定でスタートアップの種類を「自動（遅延開始）」とします。 +2. サービスの依存関係はレジストリで設定します。 + +レジストリエディター(regedit)で下記のキーと値を追加します。 + +.. list-table:: + + * - *キー* + - ``コンピューター\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\fess-service-x64\DependOnService`` + * - *値* + - ``opensearch-service-x64`` + +追加すると、 |Fess| サービスのプロパティの依存関係に opensearch-service-x64 が表示されます。 + +.. note:: + ``service.bat install`` の前に環境変数 ``FESS_START_TYPE=auto`` を設定しておくと、スタートアップの種類を「自動」で登録できます。ただし「自動（遅延開始）」や依存関係の設定は ``service.bat`` では行えないため、上記の手順で設定してください。 + +サービスの管理 +-------------- + +``service.bat`` では、以下のコマンドでサービスを操作できます。 + +.. list-table:: + :header-rows: 1 + + * - コマンド + - 説明 + * - ``service.bat install`` + - サービスを登録します。 + * - ``service.bat remove`` + - サービスを削除します。 + * - ``service.bat start`` + - サービスを起動します。 + * - ``service.bat stop`` + - サービスを停止します。 + * - ``service.bat manager`` + - サービス管理用の GUI を起動します。 diff --git a/ja/15.10/config/sso-entraid.rst b/ja/15.10/config/sso-entraid.rst new file mode 100644 index 000000000..e28bb8638 --- /dev/null +++ b/ja/15.10/config/sso-entraid.rst @@ -0,0 +1,395 @@ +=============================== +Microsoft Entra IDによるSSO設定 +=============================== + +概要 +==== + +|Fess| では、Microsoft Entra ID（旧Azure AD）を使用したシングルサインオン（SSO）認証をサポートしています。 +Entra ID認証を使用することで、Microsoft 365環境のユーザー情報やグループ情報を |Fess| のロールベース検索と連携できます。 + +.. note:: + Entra ID認証への対応は ``fess-sso-entraid`` プラグインから提供されます。配布物には + 同梱されていないため、管理画面の「システム > プラグイン」ページ、または + ``bin/fess-setup install plugin fess-sso-entraid`` で導入してください。 + 導入するまで、 ``sso.type=entraid`` （旧名の ``aad`` も同じ）を設定しても ``/sso/`` への + リクエストはログインページへリダイレクトされるだけです。 + +Entra ID認証の仕組み +-------------------- + +Entra ID認証では、|Fess| がOAuth 2.0/OpenID Connectのクライアントとして動作し、Microsoft Entra IDと連携して認証を行います。 + +1. ユーザーが |Fess| のSSOエンドポイント（``/sso/``）にアクセス +2. |Fess| がEntra IDの認可エンドポイントにリダイレクト +3. ユーザーがEntra IDで認証（Microsoftサインイン） +4. Entra IDが認可コードを |Fess| にリダイレクト +5. |Fess| が認可コードを使用してアクセストークンを取得 +6. ユーザーがログイン +7. バックグラウンドで |Fess| がMicrosoft Graph APIを使用してユーザーのグループ・ロール情報を取得し、完了後にロールベース検索に適用 + +.. note:: + |Fess| 15.10 以降は認可エンドポイントに ``response_mode=query`` を要求するため、手順4の認可レスポンスはGETで返されます。 + 15.7 以前はクロスサイトのPOSTで返されており、|Fess| の既定値である ``tomcat.sameSiteCookies = lax`` + ではセッションクッキーが送信されないため、``tomcat.sameSiteCookies = none`` への変更が回避策として必要でした。 + この回避策のためだけに ``none`` を設定していた場合は、既定値に戻せます。 + +ロールベース検索との連携については、:doc:`security-role` を参照してください。 + +前提条件 +======== + +Entra ID認証を設定する前に、以下の前提条件を確認してください。 + +- |Fess| 15.10 以降がインストールされていること +- Microsoft Entra ID（Azure AD）テナントが利用可能であること +- |Fess| がHTTPSでアクセス可能であること（本番環境では必須） +- Entra ID側でアプリケーションを登録できる権限があること + +基本設定 +======== + +SSO機能の有効化 +--------------- + +Entra ID認証を有効にするには、``app/WEB-INF/conf/system.properties`` に以下の設定を追加します。 + +:: + + sso.type=entraid + +必須設定 +-------- + +Entra IDから取得した情報を設定します。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - プロパティ + - 説明 + - デフォルト + * - ``entraid.tenant`` + - テナントID（例: ``xxx.onmicrosoft.com``） + - （必須） + * - ``entraid.client.id`` + - アプリケーション（クライアント）ID + - （必須） + * - ``entraid.client.secret`` + - クライアントシークレットの値 + - （必須） + * - ``entraid.reply.url`` + - リダイレクトURI（コールバックURL） + - リクエストURLを使用 + +.. note:: + ``entraid.*`` プレフィックスの代わりに、レガシーの ``aad.*`` プレフィックスも使用できます（後方互換性）。 + +オプション設定 +-------------- + +必要に応じて以下の設定を追加できます。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - プロパティ + - 説明 + - デフォルト + * - ``entraid.authority`` + - 認証サーバーURL + - ``https://login.microsoftonline.com/`` + * - ``entraid.state.ttl`` + - State有効期限（秒） + - ``3600`` + * - ``entraid.response.mode`` + - 認可レスポンスの受け取り方法。\ ``query`` または ``form_post`` を指定します。 + - ``query`` + * - ``entraid.default.groups`` + - デフォルトグループ（カンマ区切り）。すべてのEntra IDユーザーに適用されます。 + - （なし） + * - ``entraid.default.roles`` + - デフォルトロール（カンマ区切り）。すべてのEntra IDユーザーに適用されます。 + - （なし） + * - ``entraid.permission.fields`` + - 権限値として追加で使用するグループ/ロールのフィールド（カンマ区切り）。グループ/ロールのID（GUID）は常に権限として使用され、ここで指定したフィールド（例: ``mail``）の値が追加されます。指定できるのは、値が文字列であるフィールドだけです。``securityEnabled`` は真偽値、``groupTypes`` は配列としてMicrosoft Graphから返るため権限値にはできず、これらを指定した場合は無視され、該当のフィールド名を示す警告がログに出力されます。 + - ``mail`` + * - ``entraid.use.ds`` + - ドメインサービス連携。\ ``true`` の場合、``name@domain`` 形式の権限値から、ドメイン部を除いたローカル部（``name``）も権限として追加します。これはグループ・ロールだけでなく、サインインしたユーザー自身にも適用され、UPNのローカル部がユーザーレベルの権限として追加されます。そのため ``false`` にすると、グループの権限だけでなくこのユーザーレベルの権限も追加されなくなります。 + - ``true`` + +.. note:: + + グループ/ロールのID（GUID）は常に権限になりますが、\ ``mail`` を持つのはメールが有効なグループだけです。 + Microsoft 365グループはメールが有効なため、グループ名も権限として登録されます。 + 一方、\ **セキュリティグループはメールが有効ではないため、既定値のままではGUIDしか権限になりません**\ 。 + ファイルシステムのアクセス権をセキュリティグループ名で指定している場合、権限が一致せず検索結果に出ません。 + + この場合は、すべてのグループが持つ ``displayName`` を追加してください。 + + .. code-block:: properties + + entraid.permission.fields=mail,displayName + + ``displayName`` はドメインで修飾されず一意でもないため、既定値には含めていません。 + たとえばEntra ID側に ``Administrators`` という名前のグループがあると、 + Windowsの組み込みグループ ``Administrators`` を指定した文書にも一致します。 + 追加する際は、既存のアクセス権で使われている名前と衝突しないことを確認してください。 + +.. note:: + 既定の ``query`` では、認可コードがコールバックURLのクエリ文字列に含まれます。 + ``form_post`` を指定すると認可コードはURLに現れないため、ブラウザの履歴や、 + フロントエンドのプロキシ・WAFのアクセスログにも残りません。 + ただし ``form_post`` はクロスサイトのPOSTになるため、``tomcat.sameSiteCookies = none`` が必要です。 + 設定していない場合はセッションクッキーが送信されず、ログインに失敗します。 + さらに ``none`` はブラウザが ``Secure`` 属性付きCookieに対してのみ受け入れるため、 + ``form_post`` を使うには |Fess| をHTTPSで提供する必要があります。 + HTTPのままでは、``none`` を設定してもブラウザがセッションCookie自体を保存しないため、やはりログインできません。 + 通常は既定値のまま使用してください。 + ``query`` と ``form_post`` 以外を指定した場合は、警告を出力して ``query`` として扱います。 + +.. warning:: + + ``entraid.default.groups`` と ``entraid.default.roles`` は、ユーザーごとに切り替えられない + 単一のグローバル設定です。\ |Fess| はログイン時にすべてのEntra IDユーザーへこれらを適用し、 + その後の解決のたびに再適用するため、Microsoft Graphの結果によって取り消されることはありません。 + 特に、\ |Fess| の管理者ロール（同梱の ``authentication.admin.roles`` では ``admin``\ ）を + ``entraid.default.roles`` に設定してはいけません。テナント内のすべてのユーザーに、 + 管理画面への永続的なアクセス権を与えてしまいます。 + +Entra ID側での設定 +================== + +Azure Portalでのアプリ登録 +-------------------------- + +1. `Azure Portal `_ にサインイン + +2. **Microsoft Entra ID** を選択 + +3. 左メニューの **管理** → **アプリの登録** → **新規登録** をクリック + +4. アプリケーションを登録: + + .. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 設定項目 + - 設定値 + * - 名前 + - 任意の名前（例: Fess SSO） + * - サポートされているアカウントの種類 + - 「この組織ディレクトリのみに含まれるアカウント」 + * - プラットフォームの選択 + - Web + * - リダイレクトURI + - ``https:///sso/`` + +5. **登録** をクリック + +クライアントシークレットの作成 +------------------------------ + +1. アプリの詳細ページで **証明書とシークレット** をクリック + +2. **新しいクライアントシークレット** をクリック + +3. 説明と有効期限を設定して **追加** をクリック + +4. 生成された **値** をコピーして保存（この値は再表示されません） + +.. warning:: + クライアントシークレットの値は、作成直後のみ表示されます。 + 別の画面に遷移する前に必ず記録してください。 + +APIアクセス許可の設定 +--------------------- + +1. 左メニューの **APIのアクセス許可** をクリック + +2. **アクセス許可の追加** をクリック + +3. **Microsoft Graph** を選択 + +4. **委任されたアクセス許可** を選択 + +5. 以下のアクセス許可を追加: + + - ``User.Read`` - サインインしたユーザーの所属グループ（``/me/memberOf``）の取得に必要。アプリ登録の作成時に既定で付与されます + - ``GroupMember.Read.All`` - グループ名などのグループ属性の取得、およびネストされたグループの解決に必要 + +6. **アクセス許可の追加** をクリック + +7. **「<テナント名>に管理者の同意を与えます」** をクリック + +.. note:: + 管理者の同意は、テナント管理者権限が必要です。 + +.. note:: + ``GroupMember.Read.All`` の代わりに ``Group.Read.All`` や ``Directory.Read.All`` を付与しても、 + グループ属性の取得とネストされたグループの解決は動作します。 + 一方、\ ``/me/memberOf`` は ``Group.Read.All`` では認可されないため、 + いずれの場合も ``User.Read`` は必要です。 + +.. note:: + 上記のアクセス許可では、ディレクトリロールの ``displayName`` はMicrosoft Graphから返されません。 + そのため、\ ``entraid.permission.fields`` に ``displayName`` を指定しても、 + ディレクトリロールから権限になるのはロールのID（GUID）だけです。 + ロール名を権限値として使用する場合は、\ ``RoleManagement.Read.Directory`` + （または ``Directory.Read.All``\ ）も付与してください。 + +.. note:: + |Fess| はトークン取得時に ``https://graph.microsoft.com/.default`` スコープを要求します。 + 15.10 以降は、認可エンドポイントにも ``openid profile offline_access https://graph.microsoft.com/.default`` + を要求し、同じ範囲の同意を求めます。 + これは、アプリ登録で構成・同意済みのすべてのアクセス許可が使用されることを意味します。 + そのため、グループ情報を取得するには、上記のアクセス許可をアプリ登録に追加し、 + 管理者の同意を与えておく必要があります。 + +取得する情報 +------------ + +以下の情報をFessの設定に使用します。 + +- **アプリケーション（クライアント）ID**: 概要ページの「アプリケーション (クライアント) ID」 +- **テナントID**: 概要ページの「ディレクトリ (テナント) ID」または ``xxx.onmicrosoft.com`` 形式 +- **クライアントシークレットの値**: 証明書とシークレットで作成した値 + +グループ・ロールマッピング +========================== + +Entra ID認証では、Microsoft Graph APIを使用してユーザーが所属するグループおよびロールを自動的に取得します。 +取得したグループIDおよびグループ名は、|Fess| のロールベース検索に使用できます。 + +ネストされたグループ +-------------------- + +|Fess| は、ユーザーが直接所属するグループだけでなく、そのグループが所属する親グループ（ネストされたグループ）も取得します。 +直接所属するグループの取得と親グループの探索は、いずれもログイン後の同一のバックグラウンド処理として実行されるため、ログイン自体がMicrosoft Graphによって遅延することはありません。 +親グループの取得にはMicrosoft Graphの ``getMemberGroups`` を使用します。これは推移的に解決されるため、直接所属するグループ1件につき1回の呼び出しで、その上位にあるすべての親グループが階層の深さに関わらず返ります。取得結果は一定時間キャッシュされます。 +このバックグラウンド処理が完了すると、ユーザーの権限が再計算されます。 + +デフォルトグループの設定 +------------------------ + +すべてのEntra IDユーザーに共通のグループを付与する場合: + +:: + + entraid.default.groups=authenticated_users,entra_users + +設定例 +====== + +最小構成（検証環境向け） +------------------------ + +以下は、検証環境で動作確認を行うための最小限の設定例です。 + +:: + + # SSO有効化 + sso.type=entraid + + # Entra ID設定 + entraid.tenant=yourcompany.onmicrosoft.com + entraid.client.id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + entraid.client.secret=your-client-secret-value + entraid.reply.url=http://localhost:8080/sso/ + +推奨構成（本番環境向け） +------------------------ + +以下は、本番環境で使用する際の推奨設定例です。 + +:: + + # SSO有効化 + sso.type=entraid + + # Entra ID設定 + entraid.tenant=yourcompany.onmicrosoft.com + entraid.client.id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + entraid.client.secret=your-client-secret-value + entraid.reply.url=https://fess.example.com/sso/ + + # デフォルトグループ（オプション） + entraid.default.groups=authenticated_users + +レガシー設定（後方互換性） +-------------------------- + +以前のバージョンとの互換性のため、``aad.*`` プレフィックスも使用できます。 +各 ``entraid.*`` プロパティが未設定の場合に、対応する ``aad.*`` プロパティの値が使用されます。 +また、``sso.type=aad`` も ``sso.type=entraid`` と同等に扱われます。 + +:: + + # SSO有効化（sso.type=aad も使用可能） + sso.type=entraid + + # レガシー設定キー + aad.tenant=yourcompany.onmicrosoft.com + aad.client.id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + aad.client.secret=your-client-secret-value + aad.reply.url=https://fess.example.com/sso/ + +トラブルシューティング +====================== + +よくある問題と解決方法 +---------------------- + +認証後にFessに戻れない +~~~~~~~~~~~~~~~~~~~~~~ + +- Azure Portalのアプリ登録でリダイレクトURIが正しく設定されているか確認してください +- ``entraid.reply.url`` の値がAzure Portalの設定と完全に一致しているか確認してください +- プロトコル（HTTP/HTTPS）が一致しているか確認してください +- リダイレクトURIの末尾に ``/`` が含まれているか確認してください +- ``entraid.response.mode`` に ``form_post`` を指定している場合は、``tomcat.sameSiteCookies = none`` + が設定されているか、かつ |Fess| をHTTPSで提供しているかを確認してください。既定値の ``lax`` のままでは、 + コールバックのクロスサイトPOSTにブラウザがセッションCookieを送信しません。``none`` を設定しても + HTTPのままでは、``none`` が ``Secure`` 属性を要求するためブラウザがそのCookie自体を保存しません。 + いずれの場合もその場で1回だけログインに失敗し、ブラウザはログイン画面に戻って + 「SSOログイン処理に失敗しました。」を表示します。ログには + ``Failed to process SSO login: could not validate state`` という警告が出力されます + +認証エラーが発生する +~~~~~~~~~~~~~~~~~~~~ + +- テナントID、クライアントID、クライアントシークレットが正しく設定されているか確認してください +- クライアントシークレットの有効期限が切れていないか確認してください +- APIアクセス許可に管理者の同意が与えられているか確認してください + +グループ情報が取得できない +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``User.Read`` と ``GroupMember.Read.All`` のアクセス許可が付与されているか確認してください + （``GroupMember.Read.All`` は ``Group.Read.All`` や ``Directory.Read.All`` でも代用できますが、\ ``/me/memberOf`` には ``User.Read`` が必要です） +- 管理者の同意が与えられているか確認してください +- ユーザーがEntra ID上でグループに所属しているか確認してください +- ネストされた親グループを解決できない場合は、\ ``Not allowed to read the parent groups of ...`` という警告がログに出力されます。この場合は ``GroupMember.Read.All`` を付与してください +- |Fess| はグループ・ロールの権限解決をログイン完了後にバックグラウンドで実行するため、ログイン自体がMicrosoft Graphの応答を待つことはありません。解決が完了するまでの間、ユーザーが保持するのは、ユーザー自身のユーザーレベルの権限と、\ ``entraid.default.groups``\ ・\ ``entraid.default.roles``\ に設定したグループ・ロールだけです。どちらも未設定（同梱の既定値）の場合、この間の検索は1件もヒットしません。\ ``role.search.default.permissions`` は既定で空であり、同梱の ``role.search.default.display.permissions`` のまま作成したクロール設定でクロールした文書には ``{role}guest`` が付与されますが、ログイン済みユーザーはこのロールを持たないためです。この時間は、最大で約1秒のスケジューリング遅延に加えて、Microsoft Graphの呼び出しそのもの（直接所属の取得で1回、さらにネストしたグループをたどるために直接所属グループごとに1回ずつを順番に実行。キャッシュが未作成の場合）だけかかるため、ユーザーが所属するグループ数に応じて長くなります。この間、検索画面には、グループ・ロール権限を読み込み中である旨と、しばらくしてから再検索するよう促すメッセージが表示されます +- 解決が完全には成功しなかった場合は、検索画面に、グループ・ロール権限をすべて取得できなかった旨と、いったんログアウトしてからログインし直すよう、また繰り返し発生する場合は管理者に問い合わせるよう促すメッセージが表示されます。「すべて」は意図的な表現です。直接所属の取得とネストしたグループの探索の両方が成功しない限り解決は失敗として扱われるため、直接所属のグループは取得できていても親グループを取得できなかったユーザーにも、このメッセージが表示されます。ただし1つだけ例外があり、それは前項で説明した状況です。``GroupMember.Read.All`` が付与されておらず、Microsoft Graphがネストされたグループの取得を ``Authorization_RequestDenied`` で拒否した場合、\ |Fess| はこれを失敗ではなく「そのグループに親グループは無い」という回答として扱います。この場合、親グループの権限が欠けているにもかかわらず解決は成功として扱われ、\ **このメッセージは表示されません**\ 。手がかりはログに出力される ``Not allowed to read the parent groups of ...`` の警告だけですので、ネストされたグループを使用している場合は、この警告が出ていないかを確認してください。部分的にしか解決できない主な原因はスロットリングです。Microsoft Graphが1回でもHTTP 429または503を返すと、\ |Fess| は ``Retry-After`` ヘッダーが要求する時間（解釈できる値がない場合は60秒、最大60分）待機し、その間は直接所属の取得が成功していても、\ |Fess| 全体でネストしたグループの取得がスキップされます。ただし、失敗が最終的なものになるとは限りません。アクセストークンが更新されるたびに解決が再実行され、その後成功すればメッセージは消え、欠けていた権限も回復します。すぐに再試行したい場合は、いったんログアウトしてからログインし直してください（ログインしたままSSOのログインURLを開いても、検索画面にリダイレクトされるだけです） + +デバッグ設定 +------------ + +問題を調査する際は、|Fess| のログレベルを調整することで、Entra ID関連の詳細なログを出力できます。 + +``app/WEB-INF/classes/log4j2.xml`` で、以下のロガーを追加してログレベルを変更できます。 + +:: + + + +参考情報 +======== + +- :doc:`security-role` - ロールベース検索の設定について +- :doc:`sso-saml` - SAML認証によるSSO設定について +- :doc:`sso-oidc` - OpenID Connect認証によるSSO設定について diff --git a/ja/15.10/config/sso-oidc.rst b/ja/15.10/config/sso-oidc.rst new file mode 100644 index 000000000..27d3595b8 --- /dev/null +++ b/ja/15.10/config/sso-oidc.rst @@ -0,0 +1,326 @@ +============================== +OpenID ConnectによるSSO設定 +============================== + +概要 +==== + +|Fess| では、OpenID Connect（OIDC）を使用したシングルサインオン（SSO）認証をサポートしています。 +OpenID ConnectはOAuth 2.0を基盤とした認証プロトコルで、ID Token（JWT）を使用してユーザー認証を行います。 +OpenID Connect認証を使用することで、OIDCプロバイダー（OP）で認証されたユーザー情報を |Fess| に連携できます。 + +.. note:: + OpenID Connect認証への対応は ``fess-sso-oidc`` プラグインから提供されます。配布物には + 同梱されていないため、管理画面の「システム > プラグイン」ページ、または + ``bin/fess-setup install plugin fess-sso-oidc`` で導入してください。プラグイン名は + ``fess-sso-oidc`` ですが、 ``sso.type`` の値は ``oic`` のままです。 + 導入するまで、 ``sso.type=oic`` を設定しても ``/sso/`` へのリクエストはログインページへ + リダイレクトされるだけです。 + +OpenID Connect認証の仕組み +-------------------------- + +OpenID Connect認証では、|Fess| がRelying Party（RP）として動作し、外部のOpenIDプロバイダー（OP）と連携して認証を行います。 + +1. ユーザーが |Fess| のSSOエンドポイント（``/sso/``）にアクセス +2. |Fess| がOPの認可エンドポイントにリダイレクト +3. ユーザーがOPで認証を実行 +4. OPが認可コードを |Fess| にリダイレクト +5. |Fess| が認可コードを使用してトークンエンドポイントからID Tokenを取得 +6. |Fess| がID Token（JWT）のクレームを検証したうえでユーザー情報を取得し、ユーザーをログイン + +.. note:: + |Fess| は認可コードフロー（Authorization Code Flow）を使用します。ID Tokenは、ブラウザを経由せず、|Fess| とOPの間のバックチャネル（サーバー間通信）でトークンエンドポイントから直接取得されます。 + |Fess| はID Tokenをデコードしてクレーム（``email`` や ``groups`` など）を取り出してユーザー情報を構成しますが、JWT署名の暗号的な検証は行いません。トークンはトークンエンドポイントからTLS経由で直接受け取るため、OpenID Connect Coreはこれを認めています。そのため、トークンエンドポイントのURL（``oic.token.server.url``）はHTTPSである必要があります（``http`` が使えるのは ``localhost``、``127.x.x.x``、``::1`` のみです）。 + クレームは次のように検証します。``aud`` に ``oic.client.id`` が含まれていること（``azp`` がある場合は ``oic.client.id`` と一致すること）、``exp`` があり期限切れでないこと（300秒までの時刻のずれは許容します）、``oic.issuer`` を設定した場合は ``iss`` がそれと一致すること。``oic.issuer`` を設定しない場合は ``iss`` を検証せず、起動後の最初のログインで警告をログに出力します。``nonce`` とPKCEは使用しません。 + +ロールベース検索との連携については、:doc:`security-role` を参照してください。 + +前提条件 +======== + +OpenID Connect認証を設定する前に、以下の前提条件を確認してください。 + +- |Fess| 15.10 以降がインストールされていること +- OpenID Connect対応のプロバイダー（OP）が利用可能であること +- |Fess| がHTTPSでアクセス可能であること（本番環境では必須） +- OP側で |Fess| をクライアント（RP）として登録できる権限があること + +対応するプロバイダーの例: + +- Microsoft Entra ID（Azure AD） +- Google Workspace / Google Cloud Identity +- Okta +- Keycloak +- Auth0 +- その他のOpenID Connect対応プロバイダー + +基本設定 +======== + +SSO機能の有効化 +--------------- + +OpenID Connect認証を有効にするには、``app/WEB-INF/conf/system.properties`` に以下の設定を追加します。 + +:: + + sso.type=oic + +.. note:: + ``sso.type`` および以降で説明する ``oic.*`` の各設定（``oic.issuer`` を除く）は、管理画面の「システム > 全般」ページからも設定・変更できます。 + 管理画面で変更した設定は ``system.properties`` に保存され、再起動後も保持されます。 + ``oic.issuer`` は ``system.properties`` でのみ設定できます。 + +プロバイダー設定 +---------------- + +OPから取得した情報を設定します。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - プロパティ + - 説明 + - デフォルト + * - ``oic.auth.server.url`` + - 認可エンドポイントURL + - ``https://accounts.google.com/o/oauth2/auth`` + * - ``oic.token.server.url`` + - トークンエンドポイントURL + - ``https://accounts.google.com/o/oauth2/token`` + * - ``oic.issuer`` + - 発行者（issuer）の識別子（省略可）。設定すると、ID Tokenの ``iss`` クレームがこの値と完全に一致する必要があります（末尾のスラッシュも区別されます） + - （空文字：``iss`` を検証しない） + +.. note:: + これらのURLと発行者は、OPのDiscoveryエンドポイント（``/.well-known/openid-configuration``）から取得できます。発行者は、その ``issuer`` の値です。 + トークンエンドポイントのURL（``oic.token.server.url``）はHTTPSである必要があります。 ``http`` が使えるのは、ホストが ``localhost`` （大文字小文字は区別しません）、``127.x.x.x`` の形式のIPv4アドレス、``::1`` のいずれかである場合のみです。ホスト名は書かれたとおりに文字列として比較し、名前解決は行いません。そのため、Docker Composeのサービス名（``http://keycloak:8080/...`` など）や社内のホスト名は、同じマシンを指していても ``http`` では拒否されます。 + + この確認の対象はトークンエンドポイントだけで、認可エンドポイント（``oic.auth.server.url``）には行いません。確認はログイン時に行われ、起動時には行われません。 ``oic.issuer`` を設定してもこの規則は緩和されず、``iss`` クレームの検証が有効になるだけです。 + +クライアント設定 +---------------- + +OP側で登録したクライアント情報を設定します。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - プロパティ + - 説明 + - デフォルト + * - ``oic.client.id`` + - クライアントID + - （空文字） + * - ``oic.client.secret`` + - クライアントシークレット + - （空文字） + * - ``oic.scope`` + - 要求するスコープ + - （空文字） + +.. note:: + スコープには少なくとも ``openid`` を含める必要があります。 + ユーザーのメールアドレスを取得する場合は ``openid email`` を指定します。 + +リダイレクトURL設定 +------------------- + +認証後のコールバックURLを設定します。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - プロパティ + - 説明 + - デフォルト + * - ``oic.redirect.url`` + - リダイレクトURL（コールバックURL） + - ``{oic.base.url}/sso/`` + * - ``oic.base.url`` + - |Fess| のベースURL + - ``http://localhost:8080`` + +.. note:: + ``oic.redirect.url`` を省略した場合、``oic.base.url`` から自動的に構成されます。 + 本番環境では、``oic.base.url`` にHTTPSのURLを設定してください。 + +ユーザー属性設定 +---------------- + +OIDCで認証されたユーザーに割り当てるデフォルトのグループ・ロールを設定します。 +ユーザーID・グループ・ロールは、それぞれ以下のように決定されます。 + +- **ユーザーID**: ID Token（JWT）の ``email`` クレームから取得されます。このため、スコープには実質的に ``email`` を含める必要があります（``email`` クレームが取得できない場合、ログインは正しく行われません）。 +- **グループ**: ID Tokenの ``groups`` クレームから取得されます。\ ``groups`` クレームが存在しない場合は ``oic.default.groups`` の値が使用されます。\ ``groups`` クレームが空の配列で送られてきた場合は「存在する」とみなされるため、\ ``oic.default.groups`` は使用されず、グループなしとして扱われます。 +- **ロール**: 常に ``oic.default.roles`` の値が使用されます（ID Tokenのクレームからロールを取得する仕組みはありません）。 + +.. note:: + |Fess| は ``groups`` クレームの値をそのまま使用し、ディレクトリへの問い合わせや + ネストされたグループ（親グループ）の展開は行いません。 + 親グループが含まれるかどうかは、OP側のクレーム設定だけで決まります。 + Microsoft Graph APIで親グループを解決する :doc:`sso-entraid` とは動作が異なります。 + クレームの値はそのまま検索権限になります。OP側でグループのフルパスを出力する設定にしている場合は + ``/親グループ/子グループ`` のような値がそのまま権限名になり、グループ名だけを付与した文書とは一致しません。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - プロパティ + - 説明 + - デフォルト + * - ``oic.default.groups`` + - デフォルトグループ（カンマ区切り） + - （空文字） + * - ``oic.default.roles`` + - デフォルトロール（カンマ区切り） + - （空文字） + +.. note:: + ロールベース検索を使用する場合は、ユーザーに適切なグループまたはロールを割り当てる必要があります。 + 詳細は :doc:`security-role` を参照してください。 + +OP側での設定 +============ + +OP側で |Fess| をクライアント（RP）として登録する際に、以下の情報を設定します。 + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 設定項目 + - 設定値 + * - アプリケーションの種類 + - Webアプリケーション + * - リダイレクトURI / コールバックURL + - ``https:///sso/`` + * - 許可するスコープ + - ``openid`` および必要なスコープ（``email``, ``profile`` など） + +OPから取得する情報 +------------------ + +OPの設定画面またはDiscoveryエンドポイントから以下の情報を取得し、|Fess| の設定に使用します。 + +- **認可エンドポイント（Authorization Endpoint）**: ユーザー認証を開始するURL +- **トークンエンドポイント（Token Endpoint）**: トークンを取得するURL +- **発行者（Issuer）**: 省略可。Discoveryドキュメントの ``issuer`` の値で、``oic.issuer`` に使用します +- **クライアントID**: OPで発行されたクライアント識別子 +- **クライアントシークレット**: クライアント認証に使用する秘密鍵 + +.. note:: + 多くのOPでは、Discoveryエンドポイント（``https:///.well-known/openid-configuration``）から + 認可エンドポイントとトークンエンドポイントのURLを確認できます。 + +設定例 +====== + +最小構成（検証環境向け） +------------------------ + +以下は、検証環境で動作確認を行うための最小限の設定例です。 + +:: + + # SSO有効化 + sso.type=oic + + # プロバイダー設定（OPから取得した値を設定） + oic.auth.server.url=https://op.example.com/authorize + oic.token.server.url=https://op.example.com/token + + # クライアント設定 + oic.client.id=your-client-id + oic.client.secret=your-client-secret + oic.scope=openid email + + # リダイレクトURL（検証環境） + oic.redirect.url=http://localhost:8080/sso/ + +推奨構成（本番環境向け） +------------------------ + +以下は、本番環境で使用する際の推奨設定例です。 + +:: + + # SSO有効化 + sso.type=oic + + # プロバイダー設定 + oic.auth.server.url=https://op.example.com/authorize + oic.token.server.url=https://op.example.com/token + + # 発行者（Discoveryドキュメントの "issuer" の値） + oic.issuer=https://op.example.com + + # クライアント設定 + oic.client.id=your-client-id + oic.client.secret=your-client-secret + oic.scope=openid email profile + + # ベースURL（本番環境ではHTTPSを使用） + oic.base.url=https://fess.example.com + +トラブルシューティング +====================== + +よくある問題と解決方法 +---------------------- + +認証後に |Fess| に戻れない +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- OP側のリダイレクトURIが正しく設定されているか確認してください +- ``oic.redirect.url`` または ``oic.base.url`` の値がOP側の設定と一致しているか確認してください +- プロトコル（HTTP/HTTPS）が一致しているか確認してください + +認証エラーが発生する +~~~~~~~~~~~~~~~~~~~~ + +- クライアントIDとクライアントシークレットが正しく設定されているか確認してください +- スコープに ``openid`` が含まれているか確認してください +- 認可エンドポイントURLとトークンエンドポイントURLが正しいか確認してください +- ログインに失敗すると、``fess.log`` に ``Failed to process the OpenID Connect callback:`` で始まる警告が、続けて理由とともに出力されます +- ``The ID token was not issued for this client``: ID Tokenの ``aud`` が ``oic.client.id`` ではありません。クライアントIDを確認してください +- ``The ID token has expired``: |Fess| のホストとOPの時計が300秒を超えてずれています。時刻を同期（NTP）してください +- ``The ID token was not issued by the configured issuer``: ``oic.issuer`` がメッセージに表示された ``iss`` と異なります。Discoveryドキュメントの ``issuer`` の値を正確にコピーしてください +- ``oic.token.server.url must be https``: HTTPSのトークンエンドポイントURLを指定してください（``http`` が使えるのは ``localhost``、``127.x.x.x``、``::1`` のみです。Docker Composeのサービス名や社内のホスト名への ``http`` も拒否されます） + +ユーザー情報が取得できない +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- スコープに必要な権限（``email``, ``profile`` など）が含まれているか確認してください +- OP側でクライアントに必要なスコープが許可されているか確認してください +- Microsoft Entra IDでは、ソース属性を変更しない限り ``groups`` クレームの値はグループの ``ObjectId`` （GUID）になるため、 + グループ名とは一致しません +- ユーザーが200を超えるグループに所属している場合、Microsoft Entra IDは ``groups`` クレーム自体を送信しません + （ネストされたグループもこの上限に数えられます）。このとき |Fess| は ``oic.default.groups`` にフォールバックします + +デバッグ設定 +------------ + +問題を調査する際は、|Fess| のログレベルを調整することで、OpenID Connect関連の詳細なログを出力できます。 + +``app/WEB-INF/classes/log4j2.xml`` で、以下のロガーを追加してログレベルを変更できます。 + +:: + + + +.. warning:: + このロガーをDEBUGにすると、ID Tokenのクレーム（\ ``email`` や ``groups`` など）がログファイルに出力されます。 + 調査が終わったらログレベルを元に戻し、出力されたログの取り扱いに注意してください。 + +参考情報 +======== + +- :doc:`security-role` - ロールベース検索の設定について +- :doc:`sso-saml` - SAML認証によるSSO設定について +- :doc:`sso-entraid` - Microsoft Entra ID専用のSSO設定について（Entra IDを利用する場合は、汎用のOpenID Connect設定の代わりに専用の設定を利用することもできます） diff --git a/ja/15.10/config/sso-saml.rst b/ja/15.10/config/sso-saml.rst new file mode 100644 index 000000000..760d3cfe0 --- /dev/null +++ b/ja/15.10/config/sso-saml.rst @@ -0,0 +1,649 @@ +====================== +SAML認証によるSSO設定 +====================== + +概要 +==== + +|Fess| では、SAML（Security Assertion Markup Language）2.0 を使用したシングルサインオン（SSO）認証をサポートしています。 +SAML認証を使用することで、IdP（Identity Provider）で認証されたユーザー情報を |Fess| に連携し、ロールベース検索と組み合わせることで、ユーザーの権限に応じた検索結果の出し分けが可能になります。 + +.. note:: + SAML認証への対応は ``fess-sso-saml`` プラグインから提供されます。配布物には同梱されて + いないため、管理画面の「システム > プラグイン」ページ、または + ``bin/fess-setup install plugin fess-sso-saml`` で導入してください。 + 導入するまで、 ``sso.type=saml`` を設定しても ``/sso/`` へのリクエストはログインページへ + リダイレクトされるだけです。 + +SAML認証の仕組み +---------------- + +SAML認証では、|Fess| がSP（Service Provider）として動作し、外部のIdPと連携して認証を行います。 + +1. ユーザーが |Fess| のSSOエンドポイント（``/sso/``）にアクセス +2. |Fess| がIdPに認証リクエストをリダイレクト +3. ユーザーがIdPで認証を実行 +4. IdPがSAMLアサーションを |Fess| に送信 +5. |Fess| がアサーションを検証し、ユーザーをログイン + +.. note:: + サポートされるのは、上記のように |Fess| 側（``/sso/``）から開始するSP-Initiatedログインのみです。 + |Fess| は送信したAuthnRequestのIDとSAMLレスポンスを対応付けて検証するため、 + IdPのポータル（Oktaのダッシュボードや Microsoft Entra ID の「マイアプリ」など）に置いたタイルから + 開始するIdP-Initiated（未承諾・unsolicited）SSOは、対応付けるAuthnRequestが存在せず拒否されます。 + IdP側にタイルを配置する場合は、リンク先を |Fess| の ``/sso/`` にしてください。 + + なお 15.7 では、``tomcat.sameSiteCookies=none`` を設定していると、IdP-Initiatedのログインが + 結果的に動作していました。|Fess| が対応付けできないレスポンスをIdPへ差し戻し、IdPが即座に + SP-Initiatedのアサーションを返していたためです。15.10 ではこの差し戻しを行わなくなったため、 + IdP-Initiatedのログインは動作しません。 + +ロールベース検索との連携については、:doc:`security-role` を参照してください。 + +前提条件 +======== + +SAML認証を設定する前に、以下の前提条件を確認してください。 + +- |Fess| 15.10 以降がインストールされていること +- SAML 2.0 対応のIdP（Identity Provider）が利用可能であること +- |Fess| がHTTPSでアクセス可能であること（本番環境では必須） +- IdP側で |Fess| をSPとして登録できる権限があること + +対応するIdPの例: + +- Microsoft Entra ID（Azure AD） +- Okta +- Google Workspace +- Keycloak +- OneLogin +- その他のSAML 2.0対応IdP + +基本設定 +======== + +SSO機能の有効化 +--------------- + +SAML認証を有効にするには、``app/WEB-INF/conf/system.properties`` に以下の設定を追加します。 + +:: + + sso.type=saml + +.. note:: + ``sso.type`` および基本的なSAML設定（IdP情報、SP情報、ユーザー属性マッピング）は、管理画面の「システム > 全般」ページからも設定・変更できます。 + 管理画面で変更した設定は ``system.properties`` に保存され、再起動後も保持されます。 + ただし、署名・暗号化などのセキュリティ設定やSP証明書・秘密鍵は管理画面では設定できないため、``system.properties`` に直接記述してください。 + +.. note:: + ``saml.`` で始まる設定は ``system.properties`` からのみ読み込まれます。 + JVMのシステムプロパティ（``-Dsaml.security....`` や ``-Dfess.saml.security....``）で指定しても参照されません。 + 特に ``saml.security.*`` 、 ``saml.strict`` 、 ``saml.debug`` は管理画面にも項目がないため、 + ``system.properties`` に直接記述する以外に設定する方法はありません。 + +セッションCookieの設定 +---------------------- + +IdPはアサーションを |Fess| へ **クロスサイトのPOST** で返します。``SameSite=Lax`` のCookieはこのリクエストに送信されないため、|Fess| が同梱する既定値のままではSAMLログインが完了しません。 + +``tomcat_config.properties`` の ``tomcat.sameSiteCookies`` を ``none`` に変更してください。このファイルはZIP版では ``lib/classes/`` 、DEB/RPM版では ``/etc/fess/`` に配置されています。 + +:: + + tomcat.sameSiteCookies = none + +.. warning:: + ``none`` はブラウザが ``Secure`` 属性付きCookieに対してのみ受け入れます。したがって |Fess| をHTTPSで提供する必要があります。HTTPのままでは |Fess| にログインできなくなります。 + +.. note:: + 既定値の ``lax`` はリダイレクト（GET）で戻るSSO方式のために設定されています。SAMLのHTTP-POSTバインディングはこれに該当しないため、SAMLを利用する場合のみ変更が必要です。設定変更後は |Fess| の再起動が必要です。 + +SP（Service Provider）設定 +-------------------------- + +|Fess| をSPとして設定するには、SP Base URLを指定します。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - プロパティ + - 説明 + - デフォルト + * - ``saml.sp.base.url`` + - SPのベースURL + - ``http://localhost:8080`` + +.. note:: + ``saml.sp.base.url`` のデフォルトは ``http://localhost:8080`` です。 + 検証環境以外では、必ず |Fess| に外部からアクセスする際のURL（本番環境ではHTTPS）を設定してください。 + +この設定により、以下のエンドポイントが自動的に構成されます。 + +- **Entity ID**: ``{saml.sp.base.url}/sso/metadata`` +- **ACS URL**: ``{saml.sp.base.url}/sso/`` +- **SLO URL**: ``{saml.sp.base.url}/sso/logout`` + +設定例:: + + saml.sp.base.url=https://fess.example.com + +個別URL設定 +~~~~~~~~~~~ + +通常は ``saml.sp.base.url`` を設定すれば各エンドポイントURLは自動的に構成されますが、 +必要に応じて以下のプロパティで個別のURLを明示的に指定し、上書きすることもできます。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - プロパティ + - 説明 + - デフォルト + * - ``saml.sp.entityid`` + - SPのEntity ID + - ``{saml.sp.base.url}/sso/metadata`` + * - ``saml.sp.assertion_consumer_service.url`` + - Assertion Consumer Service URL + - ``{saml.sp.base.url}/sso/`` + * - ``saml.sp.single_logout_service.url`` + - Single Logout Service URL + - ``{saml.sp.base.url}/sso/logout`` + +IdP（Identity Provider）設定 +---------------------------- + +IdPから取得した情報を設定します。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - プロパティ + - 説明 + - デフォルト + * - ``saml.idp.entityid`` + - IdPのEntity ID + - （必須） + * - ``saml.idp.single_sign_on_service.url`` + - IdPのSSOサービスURL + - （必須） + * - ``saml.idp.x509cert`` + - IdPの署名用X.509証明書（Base64エンコード、改行なし） + - （必須） + * - ``saml.idp.single_logout_service.url`` + - IdPのSLOサービスURL + - （オプション） + +.. note:: + ``saml.idp.x509cert`` には、証明書のBase64エンコードされた内容を改行なしの1行で指定します。 + ``-----BEGIN CERTIFICATE-----`` と ``-----END CERTIFICATE-----`` の行は含めないでください。 + +SPメタデータの取得 +------------------ + +|Fess| を起動すると、``/sso/metadata`` エンドポイントでSPメタデータをXML形式で取得できます。 + +:: + + https://fess.example.com/sso/metadata + +このメタデータをIdPにインポートするか、メタデータの内容を参考にIdP側でSPを手動登録してください。 + +.. note:: + メタデータを取得するには、先に基本的なSAML設定（``sso.type=saml`` と ``saml.sp.base.url``）を完了し、|Fess| を起動しておく必要があります。 + +IdP側での設定 +============= + +IdP側で |Fess| をSPとして登録する際に、以下の情報を設定します。 + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 設定項目 + - 設定値 + * - ACS URL / Reply URL + - ``https:///sso/`` + * - Entity ID / Audience URI + - ``https:///sso/metadata`` + * - Name ID Format + - ``urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`` （推奨） + +IdPから取得する情報 +------------------- + +IdPの設定画面またはメタデータから以下の情報を取得し、|Fess| の設定に使用します。 + +- **IdP Entity ID**: IdPを識別するためのURI +- **SSO URL（HTTP-Redirect）**: シングルサインオンのエンドポイントURL +- **X.509証明書**: SAMLアサーションの署名検証に使用する公開鍵証明書 + +ユーザー属性マッピング +====================== + +SAMLアサーションから取得したユーザー属性を、|Fess| のグループやロールにマッピングできます。 + +グループ属性の設定 +------------------ + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - プロパティ + - 説明 + - デフォルト + * - ``saml.attribute.group.name`` + - グループ情報を含む属性名 + - ``memberOf`` + * - ``saml.default.groups`` + - デフォルトグループ（カンマ区切り） + - （なし） + +設定例:: + + saml.attribute.group.name=groups + saml.default.groups=user + +.. note:: + |Fess| はアサーションのグループ値をそのまま使用し、ディレクトリへの問い合わせや + ネストされたグループ（親グループ）の展開は行いません。 + 親グループが含まれるかどうかは、IdP側のクレーム設定だけで決まります。 + Microsoft Graph APIで親グループを解決する :doc:`sso-entraid` とは動作が異なります。 + +ロール属性の設定 +---------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - プロパティ + - 説明 + - デフォルト + * - ``saml.attribute.role.name`` + - ロール情報を含む属性名 + - （なし） + * - ``saml.default.roles`` + - デフォルトロール（カンマ区切り） + - （なし） + +設定例:: + + saml.attribute.role.name=roles + saml.default.roles=viewer + +.. note:: + IdPから属性が取得できない場合は、デフォルト値が使用されます。 + ロールベース検索を使用する場合は、適切なグループまたはロールを設定してください。 + +.. warning:: + ``saml.attribute.role.name`` を設定すると、IdPから送信された属性値がそのまま |Fess| のロールになります。 + ``fess_config.properties`` の ``authentication.admin.roles`` は既定で ``admin`` であるため、 + IdPがロール属性に ``admin`` を含めて送信したユーザーは |Fess| の管理者権限を得ます。 + IdP側でロール属性の値を管理できる範囲を確認し、必要に応じて ``authentication.admin.roles`` を + 別の名前に変更してください。 + +属性名が重複するIdP +------------------- + +IdPが同じ属性名を複数の ```` 要素に分けて送信した場合、|Fess| はそのアサーションを +受け付けず、ログイン自体が失敗します。 + +Keycloakは既定でこの形式のアサーションを送信します。ロールマッパーとグループマッパーは +``single`` オプションを有効にしない限り値ごとに別々の ```` 要素を出力し、 +Keycloakのアカウントは既定で複数のレルムロールを持つためです。 + +対処方法は次のいずれかです。 + +- IdP側で属性を1つの要素にまとめる（Keycloakではマッパーの ``single`` オプションを有効にします） +- |Fess| 側で重複を許可し、値をマージする + +.. list-table:: + :header-rows: 1 + :widths: 45 40 15 + + * - プロパティ + - 説明 + - デフォルト + * - ``saml.security.allow_duplicated_attribute_name`` + - 同じ属性名が複数の要素に現れることを許可し、値をマージします + - ``false`` + +設定例:: + + saml.security.allow_duplicated_attribute_name=true + +セキュリティ設定 +================ + +本番環境では、以下のセキュリティ設定を有効にすることを推奨します。 + +.. note:: + 推奨されない設定が残っている場合、SAMLの設定を読み込んだ時点で + ``Insecure SAML settings: ...`` という警告がログに出力されます。 + +署名の設定 +---------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - プロパティ + - 説明 + - デフォルト + * - ``saml.security.authnrequest_signed`` + - 認証リクエストに署名する + - ``false`` + * - ``saml.security.want_messages_signed`` + - メッセージの署名を要求する + - ``false`` + * - ``saml.security.want_assertions_signed`` + - アサーションの署名を要求する + - ``false`` + * - ``saml.security.logoutrequest_signed`` + - ログアウトリクエストに署名する + - ``false`` + * - ``saml.security.logoutresponse_signed`` + - ログアウトレスポンスに署名する + - ``false`` + * - ``saml.security.reject_deprecated_alg`` + - SHA-1などの非推奨署名アルゴリズムを拒否する + - ``false`` + +.. warning:: + デフォルトではセキュリティ機能が無効になっています。 + 本番環境では、少なくとも ``saml.security.want_assertions_signed=true`` を設定することを強く推奨します。 + +.. note:: + ``saml.security.reject_deprecated_alg`` が ``false`` の間は、SHA-1（``rsa-sha1`` および ``dsa-sha1``）で + 署名されたアサーションやメッセージも受け入れられます。既定で有効になっていないのは、 + 有効にするとSHA-1で署名を行うIdPを拒否してしまうためです。 + IdPがSHA-256以上で署名していることを確認したうえで、``saml.security.reject_deprecated_alg=true`` を設定してください。 + +.. warning:: + シングルログアウト（``saml.idp.single_logout_service.url``）を設定する場合は、 + ``saml.security.want_messages_signed=true`` を必ず併せて設定してください。 + ``false`` のままでは署名のないLogoutRequestが受理されるため、 + 細工されたURLを踏ませることで認証済みセッションを終了させられます。 + 影響は強制ログアウト（サービス妨害）であり、アカウントの乗っ取りではありません。 + +暗号化の設定 +------------ + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - プロパティ + - 説明 + - デフォルト + * - ``saml.security.want_assertions_encrypted`` + - アサーションの暗号化を要求する + - ``false`` + * - ``saml.security.want_nameid_encrypted`` + - NameIDの暗号化を要求する + - ``false`` + * - ``saml.security.allowed_key_transport_algorithms`` + - アサーションの復号時に受け付ける鍵輸送アルゴリズム（カンマ区切りのURI） + - （空文字：すべて受け付ける） + +.. note:: + |Fess| はXML Encryption 1.1で暗号化された応答を検証できます。たとえば現行のKeycloakは + ``http://www.w3.org/2009/xmlenc11#rsa-oaep`` を使い応答に ```` 要素を含めますが、 + スキーマ検証を有効にしたまま受け付けられます。以前のバージョンでは + ``Invalid SAML Response. Not match the saml-schema-protocol-2.0.xsd`` で拒否されていました。 + その回避策として ``saml.security.want_xml_validation=false`` を設定していた場合は、削除してください。 + +.. note:: + SPの秘密鍵を設定する場合は、``saml.security.allowed_key_transport_algorithms`` も設定してください。 + 未設定の間は、古い ``http://www.w3.org/2001/04/xmlenc#rsa-1_5`` を含むすべての鍵輸送アルゴリズムを + 受け付けます。アサーションコンシューマのエンドポイントは認証不要であり、復号は応答の検証より前に + 実行されるため、未認証の相手が任意の暗号文をSPの秘密鍵で復号させることができます。この状態では + 起動時の ``Insecure SAML settings`` の行に ``key_transport_algorithms_not_restricted`` が出力されます。 + IdPが実際に使うアルゴリズムだけに限定してください:: + + saml.security.allowed_key_transport_algorithms=http://www.w3.org/2009/xmlenc11#rsa-oaep + +SP証明書・秘密鍵の設定 +---------------------- + +SP側で認証リクエストやログアウトメッセージに署名する場合（``saml.security.authnrequest_signed`` など）、 +またはアサーションやNameIDの暗号化を要求する場合（``saml.security.want_assertions_encrypted`` など）は、 +SPの秘密鍵とX.509証明書を設定する必要があります。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - プロパティ + - 説明 + - デフォルト + * - ``saml.sp.x509cert`` + - SPのX.509証明書（Base64エンコード、改行なし） + - （空文字） + * - ``saml.sp.privatekey`` + - SPの秘密鍵（Base64エンコード、改行なし） + - （空文字） + +.. note:: + ``saml.sp.x509cert`` と ``saml.sp.privatekey`` には、``saml.idp.x509cert`` と同様に、 + Base64エンコードされた内容を改行なしの1行で指定します（``-----BEGIN ...-----`` と ``-----END ...-----`` の行は含めません）。 + 署名・暗号化を有効にする場合は、SP証明書をIdP側にも登録してください。SP証明書は ``/sso/metadata`` のSPメタデータに含まれて公開されます。 + +その他のセキュリティ設定 +------------------------ + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - プロパティ + - 説明 + - デフォルト + * - ``saml.strict`` + - 厳密モード（検証を厳密に行う） + - ``true`` + * - ``saml.security.want_xml_validation`` + - メッセージのXMLスキーマ検証を行う + - ``true`` + * - ``saml.security.signature_algorithm`` + - 署名アルゴリズム + - ``http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`` + * - ``saml.security.requested_authncontext`` + - 要求する認証コンテキスト + - ``urn:oasis:names:tc:SAML:2.0:ac:classes:Password`` + * - ``saml.sp.nameidformat`` + - NameIDフォーマット + - ``urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`` + +.. note:: + |Fess| は内部的にSAMLライブラリ（java-saml）を使用しており、``saml.`` で始まるプロパティは + ライブラリの対応する設定（``onelogin.saml2.`` プレフィックス）にマッピングされます。 + このため、ここで挙げた以外にも、バインディング（``saml.sp.assertion_consumer_service.binding`` など）、 + 組織情報（``saml.organization.*``）、連絡先情報（``saml.contacts.*``）といった詳細な設定を + ``system.properties`` で指定できます。 + +AuthnRequestの有効期限 +====================== + +|Fess| は ``/sso/`` へのアクセスごとにAuthnRequestを1件IdPへ送信し、そのIDをセッションに記録します。 +IdPから返されたSAMLレスポンスは、記録されたIDと対応付けて検証されます。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - プロパティ + - 説明 + - デフォルト + * - ``saml.request.id.ttl`` + - 応答のないAuthnRequestのIDを保持する期間（秒） + - ``3600`` + +記録されたIDは、この期間を過ぎると破棄されます。IdPのログイン画面を開いたまま放置するなどして +有効期限を過ぎた場合、戻ってきたアサーションは対応付けられず、その場で1回だけログインに失敗します。 + +設定例 +====== + +最小構成（検証環境向け） +------------------------ + +以下は、検証環境で動作確認を行うための最小限の設定例です。 + +:: + + # SSO有効化 + sso.type=saml + + # SP設定 + saml.sp.base.url=https://fess.example.com + + # IdP設定（IdPの管理画面から取得した値を設定） + saml.idp.entityid=https://idp.example.com/saml/metadata + saml.idp.single_sign_on_service.url=https://idp.example.com/saml/sso + saml.idp.x509cert=MIIDpDCCAoygAwIBAgI...（Base64エンコードされた証明書） + + # デフォルトグループ + saml.default.groups=user + +推奨構成（本番環境向け） +------------------------ + +以下は、本番環境で使用する際の推奨設定例です。 + +:: + + # SSO有効化 + sso.type=saml + + # SP設定 + saml.sp.base.url=https://fess.example.com + + # IdP設定 + saml.idp.entityid=https://idp.example.com/saml/metadata + saml.idp.single_sign_on_service.url=https://idp.example.com/saml/sso + saml.idp.single_logout_service.url=https://idp.example.com/saml/logout + saml.idp.x509cert=MIIDpDCCAoygAwIBAgI...（Base64エンコードされた証明書） + + # ユーザー属性マッピング + saml.attribute.group.name=groups + saml.attribute.role.name=roles + saml.default.groups=user + + # セキュリティ設定（本番環境では有効化を推奨） + saml.security.want_assertions_signed=true + saml.security.want_messages_signed=true + + # IdPがSHA-256以上で署名していることを確認してから有効化する + saml.security.reject_deprecated_alg=true + +トラブルシューティング +====================== + +よくある問題と解決方法 +---------------------- + +認証後に |Fess| に戻れない +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- IdP側のACS URLが正しく設定されているか確認してください +- ``saml.sp.base.url`` の値がIdP側の設定と一致しているか確認してください +- IdPからのSAMLアサーションはクロスサイトのPOSTで送信されます。``tomcat_config.properties`` の + ``tomcat.sameSiteCookies`` が ``lax``（既定値）の場合、ブラウザはセッションCookieを送信しないため、 + その場で1回だけログインに失敗します。この場合は ``tomcat.sameSiteCookies = none`` を設定してください + （``SameSite=None`` はHTTPSが必須です） +- IdPでのログインに時間がかかった場合、アサーションが戻ってきた時点でAuthnRequestのIDは残っていないため、 + その場で1回だけログインに失敗します。この場合はログインをやり直してください +- |Fess| は ``app/WEB-INF/web.xml`` で ``session-timeout`` を指定していないため、 + サーブレットコンテナの既定値である30分が適用されます。これは ``saml.request.id.ttl`` の3600秒より短く、 + セッションが先に破棄されます。このため ``saml.request.id.ttl`` だけを大きくしても猶予は延びません。 + 猶予を延ばしたい場合は、セッションタイムアウトも合わせて延長してください + +リバースプロキシ経由でDestinationの検証に失敗する +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +TLSを終端するリバースプロキシやロードバランサーの背後に |Fess| を配置すると、 +``saml.sp.base.url`` を正しく設定していてもアサーションの検証に失敗することがあります。 + +アサーションの ``Destination`` 属性は、|Fess| に届いた時点のリクエストURLと比較されます。 +TLSを終端するプロキシの背後では、これはIdPがアサーションを送った外部URLではなく内部の ``http://`` のURLです。 +``saml.sp.base.url`` はこの比較には使われないため、この設定だけでは解決しません。 + +``saml.debug=true`` を設定すると、ログに以下のような理由が出力されます。 + +:: + + The response was received at http://... instead of https://fess.example.com/sso/ + +この場合は ``tomcat_config.properties`` のコネクタ設定を、外部から見えるスキームとポートに合わせてください。 +以下の設定は既定ではコメントアウトされています。 + +:: + + tomcat.secure=true + tomcat.scheme=https + tomcat.proxyPort=443 + +あわせて、リバースプロキシが元の ``Host`` ヘッダーをそのまま |Fess| へ渡すように設定してください。 +リクエストURLのホスト名部分は ``Host`` ヘッダーから組み立てられます。 +``tomcat_config.properties`` を変更した後は |Fess| の再起動が必要です。 + +同じ検証はシングルログアウトのメッセージにも適用されるため、SLOを利用する場合も同様に設定してください。 + +署名検証エラー +~~~~~~~~~~~~~~ + +- IdPの証明書が正しく設定されているか確認してください +- 証明書の有効期限が切れていないか確認してください +- 証明書はBase64エンコードされた内容のみを改行なしで設定してください + +属性名の重複でログインできない +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ログに ``The IdP repeated an attribute name in the SAML assertion`` で始まる警告が出力されている場合、 + IdPが同じ属性名を複数の ```` 要素に分けて送信しています +- アサーションの検証自体は成功しているため、証明書や時刻のずれは原因ではありません +- IdP側で属性を1つの要素にまとめるか、``saml.security.allow_duplicated_attribute_name=true`` を + 設定してください + +ユーザーのグループ・ロールが反映されない +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- IdP側で属性（Attribute）が正しく設定されているか確認してください +- ``saml.attribute.group.name`` の値がIdPから送信される属性名と一致しているか確認してください +- Microsoft Entra IDでは、ソース属性を変更しない限りグループクレームの値はグループの ``ObjectId`` （GUID）になるため、 + グループ名とは一致しません +- ユーザーが150を超えるグループに所属している場合、Microsoft Entra IDはグループクレーム自体を送信しません + （ネストされたグループもこの上限に数えられます）。このとき |Fess| は ``saml.default.groups`` にフォールバックします +- SAMLアサーションの内容を確認するには、デバッグモードを有効にしてください + +デバッグ設定 +------------ + +問題を調査する際は、以下の設定でデバッグモードを有効にできます。 + +:: + + saml.debug=true + +``saml.debug=true`` を設定すると、SAML認証に失敗した際の詳細な理由がログに出力されます。 + +また、``app/WEB-INF/classes/log4j2.xml`` に以下のロガーを追加することで、SAML関連の詳細なログを出力できます。 + +:: + + + +参考情報 +======== + +- :doc:`security-role` - ロールベース検索の設定について +- :doc:`sso-oidc` - OpenID ConnectによるSSO設定について +- :doc:`sso-entraid` - Microsoft Entra ID専用のSSO設定について diff --git a/ja/15.10/config/sso-spnego.rst b/ja/15.10/config/sso-spnego.rst new file mode 100644 index 000000000..27251e0e9 --- /dev/null +++ b/ja/15.10/config/sso-spnego.rst @@ -0,0 +1,489 @@ +================================= +Windows統合認証によるSSO設定 +================================= + +概要 +==== + +|Fess| はWindows統合認証（SPNEGO/Kerberos）を使用したシングルサインオン（SSO）認証をサポートしています。 +Windows統合認証を使用することで、Active Directoryドメインに参加しているWindowsにログインしたユーザーは、追加のログイン操作なしで |Fess| にアクセスできます。 + +.. note:: + Windows統合認証への対応は ``fess-sso-spnego`` プラグインから提供されます。配布物には + 同梱されていないため、管理画面の「システム > プラグイン」ページ、または + ``bin/fess-setup install plugin fess-sso-spnego`` で導入してください。 + 導入するまで、 ``sso.type=spnego`` を設定しても ``/sso/`` へのリクエストはログイン + ページへリダイレクトされるだけです。 + +Windows統合認証の仕組み +----------------------- + +Windows統合認証では、 |Fess| はSPNEGO（Simple and Protected GSSAPI Negotiation Mechanism）プロトコルを使用してKerberos認証を行います。 + +1. ユーザーがWindowsドメインにログイン +2. ユーザーが |Fess| にアクセス +3. |Fess| がSPNEGOチャレンジを送信 +4. ブラウザがKerberosチケットを取得してサーバーに送信 +5. |Fess| がチケットを検証し、ユーザー名を取得 +6. LDAPを使用してユーザーのグループ情報を取得 +7. ユーザーがログイン状態になり、グループ情報がロールベース検索に適用される + +ロールベース検索との連携については、 :doc:`security-role` を参照してください。 + +前提条件 +======== + +Windows統合認証を設定する前に、以下の前提条件を確認してください： + +- |Fess| 15.10以降がインストールされている +- Active Directory（AD）サーバーが利用可能 +- |Fess| サーバーがADドメインからアクセス可能 +- ADでサービスプリンシパル名（SPN）を設定する権限がある +- LDAPでユーザー情報を取得するためのアカウントがある + +Active Directory側の設定 +======================== + +サービスプリンシパル名（SPN）の登録 +----------------------------------- + +|Fess| 用のSPNをActive Directoryに登録する必要があります。 +ADドメインに参加しているWindowsでコマンドプロンプトを開き、 ``setspn`` コマンドを実行します。 + +:: + + setspn -S HTTP/ + +例： + +:: + + setspn -S HTTP/fess-server.example.local svc_fess + +登録を確認するには： + +:: + + setspn -L + +.. note:: + SPNの登録後、Fessサーバーで実行した場合は一度Windowsからログアウトし、再ログインしてください。 + +基本設定 +======== + +SSOの有効化 +----------- + +Windows統合認証を有効にするには、 ``app/WEB-INF/conf/system.properties`` に以下の設定を追加します： + +:: + + sso.type=spnego + +Kerberos設定ファイル +-------------------- + +``app/WEB-INF/classes/krb5.conf`` を作成し、Kerberos設定を記述します。 + +:: + + [libdefaults] + default_realm = EXAMPLE.LOCAL + default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + + [realms] + EXAMPLE.LOCAL = { + kdc = AD-SERVER.EXAMPLE.LOCAL + default_domain = EXAMPLE.LOCAL + } + + [domain_realm] + example.local = EXAMPLE.LOCAL + .example.local = EXAMPLE.LOCAL + +.. note:: + ``EXAMPLE.LOCAL`` はお使いのADドメイン名（大文字）に、 ``AD-SERVER.EXAMPLE.LOCAL`` はADサーバーのホスト名に置き換えてください。 + +.. warning:: + ``permitted_enctypes`` に含まれていない暗号化方式のサービスチケットは、Kerberos の受け入れ側で + ``encryption type not in permitted_enctypes list`` として拒否されます。 + Active Directory は通常 AES256 のサービスチケットを発行するため、AES256 を必ず含めてください。 + +.. note:: + Java 17 以降では RC4（ ``rc4-hmac`` ）、3DES、DES が既定で無効化されているため、 + これらを列挙しても使用されません。上記の例では AES のみを指定しています。 + ``aes256-cts-hmac-sha384-192`` と ``aes128-cts-hmac-sha256-128`` は、Windows Server 2025 が対応する + AES-SHA2（RFC 8009）の暗号化方式です。 + RC4 の鍵しか持たないサービスアカウントでは Kerberos 認証に失敗するため、 + パスワードを再設定して AES の鍵を生成してください。 + +ログイン設定ファイル +-------------------- + +``app/WEB-INF/classes/auth_login.conf`` を作成し、JAASログイン設定を記述します。 + +:: + + spnego-client { + com.sun.security.auth.module.Krb5LoginModule required; + }; + + spnego-server { + com.sun.security.auth.module.Krb5LoginModule required + storeKey=true + isInitiator=false; + }; + +.. note:: + ``krb5.conf`` と ``auth_login.conf`` は、 ``spnego.krb5.conf`` / ``spnego.login.conf`` でデフォルトのファイル名が設定されますが、ファイル自体は必ず作成しておく必要があります。 + SPNEGO の初期化は最初のログイン時に行われるため、これらのファイルが存在しなくても |Fess| 自体は起動しますが、SSO ログインが失敗します。 + +必須設定 +-------- + +``app/WEB-INF/conf/system.properties`` に以下の設定を追加します。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - プロパティ + - 説明 + - デフォルト値 + * - ``spnego.preauth.username`` + - AD接続用ユーザー名 + - （keytabを使用しない場合は必須） + * - ``spnego.preauth.password`` + - AD接続用パスワード + - （keytabを使用しない場合は必須） + * - ``spnego.krb5.conf`` + - Kerberos設定ファイルパス + - ``krb5.conf`` + * - ``spnego.login.conf`` + - ログイン設定ファイルパス + - ``auth_login.conf`` + +.. note:: + ``spnego.preauth.username`` と ``spnego.preauth.password`` を両方とも空にすると、 + サーバー側のログインモジュールが keytab を使用します。 + AD のサービスアカウントのパスワードを |Fess| の設定ファイルに保存したくない場合は、 + keytab を作成して ``auth_login.conf`` の ``spnego-server`` を次のように設定してください。 + + :: + + spnego-server { + com.sun.security.auth.module.Krb5LoginModule required + useKeyTab=true + keyTab="/var/lib/fess/fess.keytab" + principal="HTTP/fess-server.example.local@EXAMPLE.LOCAL" + storeKey=true + isInitiator=false; + }; + +オプション設定 +-------------- + +必要に応じて以下の設定を追加できます。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - プロパティ + - 説明 + - デフォルト値 + * - ``spnego.login.client.module`` + - クライアントモジュール名 + - ``spnego-client`` + * - ``spnego.login.server.module`` + - サーバーモジュール名 + - ``spnego-server`` + * - ``spnego.allow.basic`` + - Basic認証を許可 + - ``true`` + * - ``spnego.allow.unsecure.basic`` + - 非セキュアなBasic認証を許可 + - ``false`` + * - ``spnego.prompt.ntlm`` + - NTLMトークン受信時にBasic認証へフォールバックする + - ``true`` + * - ``spnego.allow.localhost`` + - localhostからのアクセスを許可 + - ``false`` + * - ``spnego.allow.delegation`` + - 委任を許可 + - ``false`` + * - ``spnego.allowed.realms`` + - サーバーのレルムに加えて許可する Kerberos レルム（カンマ区切り） + - （なし） + * - ``spnego.logger.level`` + - SPNEGOライブラリ内部のログレベル（``1`` =FINEST、 ``2`` =FINER、 ``3`` =FINE、 ``4`` =CONFIG、 ``6`` =WARNING、 ``7`` =SEVERE。これら以外の値（ ``0`` 、 ``5`` を含む）はINFO扱い） + - （自動） + +.. warning:: + ``spnego.allow.unsecure.basic=true`` は、Base64エンコードされた認証情報を暗号化されていない接続で送信する可能性があります。 + 本番環境では ``false`` に設定し、HTTPSを使用することを強く推奨します。 + +.. note:: + ``spnego.allow.unsecure.basic=false`` （デフォルト）の場合、Basic認証は + ``HttpServletRequest#isSecure()`` が ``true`` を返すリクエストにのみ提示されます。 + TLSをリバースプロキシで終端して |Fess| へHTTPで転送している構成ではこの値が ``false`` になるため、 + Kerberosチケットを取得できずNTLMにフォールバックしたクライアントはログインできません。 + ``tomcat_config.properties`` で ``tomcat.secure=true`` を設定し、リクエストがHTTPS由来であることを + |Fess| に伝えてください。このファイルはZIP版では ``lib/classes/`` 、DEB/RPM版では ``/etc/fess/`` に + 配置されています。変更後は |Fess| の再起動が必要です。 + +.. warning:: + |Fess| 15.10 では、クライアントのプリンシパルのレルムがサーバーのレルムと異なる場合、 + そのログインは既定で拒否されます。ADのドメインツリーの子ドメインや、信頼関係を結んだフォレストの + ユーザーがログインする構成では、 ``spnego.allowed.realms`` に該当するレルムをカンマ区切りで + 列挙してください。列挙しない場合、15.7 まではログインできていたユーザーが + ``Kerberos realm is not allowed`` として拒否されます。 + +.. warning:: + |Fess| はプリンシパルの ``@`` より前の部分をユーザー名として扱うため、ユーザー名にレルムは + 含まれません。 ``spnego.allowed.realms`` にレルムを追加すると、複数のレルムに同じアカウント名 + を持つユーザー（例: ``alice@CORP.EXAMPLE.COM`` と ``alice@PARTNER.EXAMPLE.COM`` ）は同一の + |Fess| ユーザーとして扱われ、そのユーザーのグループ・ロール・文書の権限を共有します。 + 列挙するすべてのレルムを通じてアカウント名が一意に個人を特定できる場合にのみ追加してください。 + +.. note:: + 許可リストは Basic 認証のフォールバックにも適用されます。ユーザーが ``user@REALM`` の形式で + 入力した場合、そのレルムが ``spnego.allowed.realms`` と照合され、許可されていなければログインは + 拒否されます。単純なアカウント名や ``DOMAIN\user`` の形式はレルムを指定しないため、 + ``krb5.conf`` の既定レルムで認証されます。Basic 認証はユーザーが入力したレルムに対して直接 + 認証を行うため、許可リストは必要最小限にとどめ、これをセキュリティ境界として利用する場合は + ``spnego.allow.basic`` を ``false`` に設定することを検討してください。 + +.. note:: + ``spnego.prompt.ntlm=true`` （デフォルト）の場合、 ``spnego.allow.basic`` も ``true`` である必要があります。 + ``spnego.allow.basic=false`` に設定する場合は、 ``spnego.prompt.ntlm=false`` も併せて設定してください。 + この条件を満たさない場合、SPNEGOの初期化時にエラーが発生します。 + +.. note:: + ``spnego.logger.level`` は、SPNEGOライブラリ内部のロガー（ ``java.util.logging`` の ``Spnego`` という名前のロガー）のログレベルを制御します。 + 未設定の場合は、 |Fess| のログレベルに応じて自動的に決定されます。 + +LDAP設定 +======== + +Windows統合認証でログインしたユーザーのグループ情報を取得するために、LDAP設定が必要です。 +|Fess| 管理画面の「システム」→「全般」でLDAP設定を行います。 + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 項目 + - 設定例 + * - LDAP URL + - ``ldap://AD-SERVER.example.local:389`` + * - Base DN + - ``dc=example,dc=local`` + * - Bind DN + - ``svc_fess@example.local`` + * - パスワード + - AD接続用ユーザーのパスワード + * - User DN + - ``%s@example.local`` + * - アカウントフィルタ + - ``(&(objectClass=user)(sAMAccountName=%s))`` + * - memberOf属性 + - ``memberOf`` + +.. note:: + |Fess| はユーザーの ``memberOf`` 属性を1段だけ読むため、既定では入れ子になったグループ + （グループのメンバーであるグループ）は展開されません。ADの入れ子グループを反映するには、 + 管理画面「システム」→「全般」の「グループフィルター」（ ``ldap.group.filter`` ）に + ``(member:1.2.840.113556.1.4.1941:=%s)`` を設定してください。この展開はログイン後に + 非同期で実行されるため、監査ログのログイン行には展開前のグループだけが記録されます。 + +ブラウザ設定 +============ + +Windows統合認証を使用するには、クライアント側のブラウザ設定が必要です。 + +Internet Explorer / Microsoft Edge +---------------------------------- + +1. インターネットオプションを開く +2. 「セキュリティ」タブを選択 +3. 「ローカル イントラネット」ゾーンの「サイト」をクリック +4. 「詳細設定」をクリックし、FessのURLを追加 +5. 「ローカル イントラネット」ゾーンの「レベルのカスタマイズ」をクリック +6. 「ユーザー認証」→「ログオン」→「イントラネット ゾーンでのみ自動的にログオンする」を選択 +7. 「詳細設定」タブで「統合Windows認証を使用する」にチェック + +Google Chrome +------------- + +Chromeは通常、Windowsのインターネットオプション設定を使用します。 +追加設定が必要な場合は、グループポリシーまたはレジストリで ``AuthServerAllowlist`` を設定します。 + +Mozilla Firefox +--------------- + +1. アドレスバーに ``about:config`` と入力 +2. ``network.negotiate-auth.trusted-uris`` を検索 +3. FessサーバーのURLまたはドメインを設定（例：``https://fess-server.example.local``） + +設定例 +====== + +最小構成（検証用） +------------------ + +以下は検証環境での最小構成例です。 + +``app/WEB-INF/conf/system.properties``: + +:: + + # SSO有効化 + sso.type=spnego + + # SPNEGO設定 + spnego.preauth.username=svc_fess + spnego.preauth.password=your-password + +``app/WEB-INF/classes/krb5.conf``: + +:: + + [libdefaults] + default_realm = EXAMPLE.LOCAL + default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + + [realms] + EXAMPLE.LOCAL = { + kdc = AD-SERVER.EXAMPLE.LOCAL + default_domain = EXAMPLE.LOCAL + } + + [domain_realm] + example.local = EXAMPLE.LOCAL + .example.local = EXAMPLE.LOCAL + +``app/WEB-INF/classes/auth_login.conf``: + +:: + + spnego-client { + com.sun.security.auth.module.Krb5LoginModule required; + }; + + spnego-server { + com.sun.security.auth.module.Krb5LoginModule required + storeKey=true + isInitiator=false; + }; + +推奨構成（本番用） +------------------ + +以下は本番環境での推奨構成例です。 + +``app/WEB-INF/conf/system.properties``: + +:: + + # SSO有効化 + sso.type=spnego + + # SPNEGO設定 + spnego.preauth.username=svc_fess + spnego.preauth.password=your-secure-password + spnego.krb5.conf=krb5.conf + spnego.login.conf=auth_login.conf + + # セキュリティ設定（本番環境） + spnego.allow.basic=false + spnego.allow.unsecure.basic=false + spnego.prompt.ntlm=false + spnego.allow.localhost=false + +.. note:: + ``spnego.allow.basic=false`` を設定する場合は、 ``spnego.prompt.ntlm=false`` も必ず設定してください。 + ``spnego.prompt.ntlm`` はデフォルトで ``true`` のため、この設定を省略すると初期化時にエラーが発生します。 + +トラブルシューティング +====================== + +よくある問題と解決方法 +---------------------- + +認証ダイアログが表示される +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ブラウザの設定でFessサーバーがイントラネットゾーンに追加されているか確認 +- 「統合Windows認証を使用する」が有効になっているか確認 +- SPNが正しく登録されているか確認（ ``setspn -L <ユーザー名>`` ） + +認証エラーが発生する +~~~~~~~~~~~~~~~~~~~~ + +- ``krb5.conf`` のドメイン名（大文字）とADサーバー名が正しいか確認 +- ``spnego.preauth.username`` と ``spnego.preauth.password`` が正しいか確認 +- ADサーバーへのネットワーク接続を確認 + +グループ情報が取得できない +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- LDAP設定が正しいか確認 +- Bind DNとパスワードが正しいか確認 +- ユーザーがADでグループに所属しているか確認 + +ログインがHTTP 400になる +~~~~~~~~~~~~~~~~~~~~~~~~ + +所属グループが多いユーザーはKerberosチケット（PAC）が大きくなり、 ``Authorization`` ヘッダーが +Tomcatの既定の上限（8KB）を超えて400が返されることがあります。 +このときリクエストは |Fess| に届かないため、ログには何も記録されません。 +``tomcat_config.properties`` で上限を引き上げてください。 + +:: + + tomcat.maxHttpHeaderSize=65536 + +サービスアカウントのパスワード変更後に認証できない +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +サーバーの資格情報は最初のログイン時に一度だけ取得され、以後プロセスが終了するまでキャッシュされます。 +AD側でサービスアカウントのパスワードを変更した場合やkeytabを差し替えた場合は、 |Fess| を再起動してください。 +``spnego.*`` の設定を変更した場合も同様に再起動が必要です。 + +デバッグ設定 +------------ + +問題を調査するために、SPNEGO関連の詳細ログを出力できます。 + +SPNEGOライブラリ内部の詳細ログを出力するには、 ``app/WEB-INF/conf/system.properties`` に以下を追加します。 +``spnego.logger.level=1`` は最も詳細なログ（FINEST）を出力します。 + +:: + + spnego.logger.level=1 + +|Fess| 側のSPNEGO連携処理（``org.codelibs.fess.sso.spnego`` パッケージ）の詳細ログを出力するには、 ``app/WEB-INF/classes/log4j2.xml`` に以下のロガーを追加します。 + +:: + + + +.. note:: + SPNEGOライブラリ自体のログは ``java.util.logging`` で出力されるため、 ``log4j2.xml`` ではなく ``spnego.logger.level`` で制御します。 + |Fess| 側の連携処理のログは ``log4j2.xml`` のロガーで制御します。 + +参考情報 +======== + +- :doc:`security-role` - ロールベース検索の設定 +- :doc:`sso-saml` - SAML認証によるSSO設定 +- :doc:`sso-oidc` - OpenID Connect認証によるSSO設定 +- :doc:`sso-entraid` - Microsoft Entra IDによるSSO設定 + diff --git a/ja/15.10/dev/datastore-plugin.rst b/ja/15.10/dev/datastore-plugin.rst new file mode 100644 index 000000000..e3a1a5d72 --- /dev/null +++ b/ja/15.10/dev/datastore-plugin.rst @@ -0,0 +1,524 @@ +================================== +データストアプラグイン開発 +================================== + +概要 +==== + +データストアプラグインを開発することで、|Fess| に新しいデータソースからの +コンテンツ取得機能を追加できます。データストアは、データベース・API・ファイルなどの +外部システムからレコードを取得し、管理画面で設定したマッピングスクリプトに従って +インデックスフィールドへ変換したうえで、|Fess| のインデックスへ登録します。 + +CSV・JSON・データベース・Git・各種クラウドサービスなど、公開されている +コネクター(``fess-ds-*``)はすべてこの仕組みで実装されています。実装の雛形として +`fess-ds-example `__ が公開されているため、 +新しいコネクターを作成する場合はこれをコピーして始めるのが簡単です。 + +基本構造 +======== + +データストアプラグインは、次の3点で構成されます。 + +- ``AbstractDataStore`` を継承したクラスを作成する +- ``getName()`` と ``storeData()`` の2つのメソッドを実装する +- ``fess_ds++.xml`` でコンポーネントとして登録する + +最小実装 +-------- + +.. code-block:: java + + package org.codelibs.fess.ds.example; + + import java.util.Map; + + import org.codelibs.fess.ds.AbstractDataStore; + import org.codelibs.fess.ds.callback.IndexUpdateCallback; + import org.codelibs.fess.entity.DataStoreParams; + import org.codelibs.fess.opensearch.config.exentity.DataConfig; + + public class ExampleDataStore extends AbstractDataStore { + + @Override + protected String getName() { + // ハンドラー名として使用される。クラスの単純名を返すのが慣例 + return this.getClass().getSimpleName(); + } + + @Override + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { + + // データの取得と処理をここに実装 + } + } + +.. note:: + + ``getName()`` と ``storeData()`` はいずれも ``protected`` の抽象メソッドです。 + ``DataConfig`` のパッケージは |Fess| 15.x では ``org.codelibs.fess.opensearch.config.exentity`` + である点に注意してください(以前の ``org.codelibs.fess.es.config.exentity`` は廃止されています)。 + +コンポーネントの登録 +-------------------- + +作成したデータストアを |Fess| に認識させるため、``src/main/resources/fess_ds++.xml`` に +コンポーネントを登録します。 + +.. code-block:: xml + + + + + + + + + +```` により、コンポーネント生成後に ``AbstractDataStore`` +が持つ ``register()`` メソッドが自動的に呼び出され、``DataStoreFactory`` へ自身が登録されます。 +このとき登録される名前が ``getName()`` の戻り値(上記の例では ``ExampleDataStore``)であり、 +管理画面のデータストア設定で選択する「ハンドラー名」になります。 + +AbstractDataStore +================= + +主要メソッド +------------ + +.. list-table:: + :header-rows: 1 + :widths: 35 20 45 + + * - メソッド + - 区分 + - 説明 + * - ``getName()`` + - 実装(必須) + - データストアのハンドラー名を返す抽象メソッド。\ ``getClass().getSimpleName()`` を返すのが慣例 + * - ``storeData()`` + - 実装(必須) + - データの取得・変換・インデックス登録を行う抽象メソッド + * - ``register()`` + - 継承(通常は変更不要) + - ``fess_ds++.xml`` の ``postConstruct`` から自動呼び出しされ、``DataStoreFactory`` へ登録する + * - ``store()`` + - 継承(フレームワーク呼び出し) + - フレームワークが呼び出す入口。\ ``defaultDataMap`` などを準備して ``storeData()`` を呼ぶ + * - ``convertValue()`` + - 継承(ヘルパー) + - ``scriptMap`` の値(テンプレート)をスクリプトエンジンで評価する + * - ``getScriptType()`` + - 継承(ヘルパー) + - ``script_type`` パラメーターを取得する(既定は Groovy) + * - ``getReadInterval()`` + - 継承(ヘルパー) + - ``readInterval`` パラメーター(ミリ秒)を取得する + * - ``sleep()`` + - 継承(ヘルパー) + - 指定ミリ秒スリープする(レコード間の待機に使用) + +storeData のパラメーター +------------------------ + +``storeData()`` メソッドに渡されるパラメーター: + +.. list-table:: + :header-rows: 1 + :widths: 25 35 40 + + * - パラメーター + - 型 + - 説明 + * - ``dataConfig`` + - ``DataConfig`` + - データストア設定(ID・ハンドラー名・パラメーター・スクリプトなど) + * - ``callback`` + - ``IndexUpdateCallback`` + - 生成したドキュメントをインデックスへ登録するコールバック + * - ``paramMap`` + - ``DataStoreParams`` + - 管理画面「パラメーター」欄の設定値。\ ``getAsString(key)`` / ``getAsString(key, default)`` / ``get(key)`` / ``asMap()`` / ``containsKey(key)`` でアクセスする + * - ``scriptMap`` + - ``Map`` + - 管理画面「スクリプト」欄の設定。キーがインデックスフィールド名、値が評価対象のスクリプトテンプレート + * - ``defaultDataMap`` + - ``Map`` + - 各ドキュメントの既定フィールド値(設定ID・boost・role・mimetype・仮想ホストなど)。フレームワークが用意する + +.. warning:: + + ``paramMap`` の型は ``Map`` ではなく ``DataStoreParams`` です。 + ``DataStoreParams`` は ``Map`` を実装していないため、値の取得には ``get()`` ではなく + 文字列を返す ``getAsString()`` を使用してください。 + +データ処理の流れ +---------------- + +``storeData()`` の実装は、次の流れでデータを処理します。 + +#. 外部システムからソースレコードを取得する。 +#. ``paramMap.asMap()`` にソースレコードのフィールドをマージして ``resultMap`` を構築する + (スクリプトはこの ``resultMap`` に対して評価される)。 +#. ``scriptMap`` の各エントリを ``convertValue(scriptType, template, resultMap)`` で評価し、 + 結果を ``dataMap`` に格納する。マッピングはコード内にハードコードするのではなく、 + 管理者が「スクリプト」欄で定義する点が重要です。 +#. ``callback.store(paramMap, dataMap)`` を呼び出してドキュメントとしてインデックス登録する。 + +実装例 +====== + +シンプルなデータストア +---------------------- + +外部 API からレコードを取得してインデックス登録する例です。 + +.. code-block:: java + + @Override + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { + + // パラメーターの取得(DataStoreParams では getAsString を使用する) + final String apiUrl = paramMap.getAsString("api.url"); + final String apiKey = paramMap.getAsString("api.key"); + + // スクリプトの評価タイプ(既定は Groovy) + final String scriptType = getScriptType(paramMap); + // レコード間の待機時間(ミリ秒) + final long readInterval = getReadInterval(paramMap); + + try { + // 外部システムからデータを取得 + final List> records = fetchRecords(apiUrl, apiKey); + + for (final Map record : records) { + // 既定フィールドをコピーして dataMap を初期化 + final Map dataMap = new HashMap<>(defaultDataMap); + + // パラメーターとソースレコードをマージした resultMap を構築 + // (スクリプトはこの resultMap に対して評価される) + final Map resultMap = new LinkedHashMap<>(paramMap.asMap()); + resultMap.putAll(record); + + // scriptMap の各エントリを評価してインデックスフィールドを生成 + for (final Map.Entry entry : scriptMap.entrySet()) { + final Object value = convertValue(scriptType, entry.getValue(), resultMap); + if (value != null) { + dataMap.put(entry.getKey(), value); + } + } + + // インデックスに登録 + callback.store(paramMap, dataMap); + + if (readInterval > 0) { + sleep(readInterval); + } + } + } catch (final Exception e) { + throw new DataStoreException("Failed to crawl data from " + apiUrl, e); + } + } + +``fetchRecords()`` は外部システムからレコード一覧を取得する独自メソッドです。取得した +各レコード(``Map``)のフィールド名が、``scriptMap`` のスクリプトから +参照できる名前になります。\ ``DataStoreException`` は ``org.codelibs.fess.exception`` +パッケージのクラスです。 + +ページネーション対応 +-------------------- + +大量のデータを扱う場合は、ページ単位で取得しながら処理します。1レコードあたりの処理 +(``resultMap`` の構築・``scriptMap`` の評価・``callback.store()`` の呼び出し)を +``processRecord()`` のようなメソッドに切り出しておくと、取得ロジックと分離できます。 + +.. code-block:: java + + int offset = 0; + final int pageSize = 100; + + while (true) { + final List> records = fetchRecords(apiUrl, apiKey, offset, pageSize); + + if (records.isEmpty()) { + break; + } + + for (final Map record : records) { + processRecord(record, callback, paramMap, scriptMap, defaultDataMap); + } + + offset += pageSize; + } + +認証の実装 +========== + +外部システムの認証は、コネクター側で実装します。以下は一般的な HTTP クライアント +ライブラリを用いた実装例で、|Fess| が提供する API ではありません。利用するライブラリは +プラグインの依存関係として同梱してください。 + +OAuth 2.0 +--------- + +.. code-block:: java + + protected String getAccessToken(final String clientId, final String clientSecret, final String refreshToken) { + // リフレッシュトークンを用いてアクセストークンを取得する例 + final OkHttpClient client = new OkHttpClient(); + + final RequestBody body = new FormBody.Builder() + .add("grant_type", "refresh_token") + .add("client_id", clientId) + .add("client_secret", clientSecret) + .add("refresh_token", refreshToken) + .build(); + + final Request request = new Request.Builder() + .url("https://oauth.example.com/token") + .post(body) + .build(); + + try (Response response = client.newCall(request).execute()) { + final JsonNode json = objectMapper.readTree(response.body().string()); + return json.get("access_token").asText(); + } + } + +APIキー認証 +----------- + +.. code-block:: java + + protected Response callApi(final String url, final String apiKey) { + final Request request = new Request.Builder() + .url(url) + .addHeader("Authorization", "Bearer " + apiKey) + .build(); + + return httpClient.newCall(request).execute(); + } + +エラーハンドリング +================== + +処理を中断すべき致命的なエラーでは ``DataStoreException`` をスローします。 + +.. code-block:: java + + @Override + protected void storeData(...) { + try { + // 処理 + } catch (final AuthenticationException e) { + logger.error("Authentication failed. Check your credentials.", e); + throw new DataStoreException("Authentication failed", e); + } catch (final RateLimitException e) { + logger.warn("Rate limit exceeded. Waiting..."); + sleep(60000L); + // リトライロジック + } catch (final Exception e) { + logger.error("Unexpected error occurred", e); + throw new DataStoreException("Failed to crawl data", e); + } + } + +.. note:: + + ``fess-ds-example`` をはじめとする実際のコネクターでは、1レコードのエラーで + クロール全体を止めないよう、レコード単位で ``CrawlingAccessException`` を捕捉し、 + ``FailureUrlService`` にエラー URL を記録しています。また + ``DataStoreCrawlingException`` の中断フラグを用いて、クロール全体を中断するかどうかを + 制御しています。堅牢なコネクターを実装する場合は ``ExampleDataStore`` の実装を参照してください。 + +テスト +====== + +ユニットテスト +-------------- + +|Fess| のプラグインは UTFlute の ``LastaDiTestCase`` を用いてテストします。テストは +JUnit 5(Jupiter)で記述します。\ ``IndexUpdateCallback`` を、登録された ``dataMap`` を +収集する実装に差し替えることで、モックライブラリを使わずにマッピング結果を検証できます。 + +.. code-block:: java + + public class ExampleDataStoreTest extends LastaDiTestCase { + + public ExampleDataStore dataStore; + + @Override + protected String prepareConfigFile() { + return "test_app.xml"; + } + + @Override + public void setUp(final TestInfo testInfo) throws Exception { + super.setUp(testInfo); + dataStore = new ExampleDataStore(); + } + + @Test + public void test_getName() { + assertEquals("ExampleDataStore", dataStore.getName()); + } + + @Test + public void test_storeData() { + final TestIndexUpdateCallback callback = new TestIndexUpdateCallback(); + final DataStoreParams paramMap = new DataStoreParams(); + + final Map scriptMap = new HashMap<>(); + scriptMap.put("title", "title"); + + dataStore.storeData(new DataConfig(), callback, paramMap, scriptMap, new HashMap<>()); + + assertFalse(callback.getDataMapList().isEmpty()); + } + + // 登録された dataMap を収集するテスト用コールバック + private static class TestIndexUpdateCallback implements IndexUpdateCallback { + private final List> dataMapList = new ArrayList<>(); + + @Override + public void store(final DataStoreParams paramMap, final Map dataMap) { + dataMapList.add(new HashMap<>(dataMap)); + } + + @Override + public long getExecuteTime() { + return 0; + } + + @Override + public long getDocumentSize() { + return dataMapList.size(); + } + + @Override + public void commit() { + // 何もしない + } + + public List> getDataMapList() { + return dataMapList; + } + } + } + +.. note:: + + ``setUp`` は基底クラスで ``@BeforeEach`` が付与されているため、オーバーライド側に + ライフサイクルアノテーションを付け直す必要はありません。各テストメソッドには + ``@Test``\ (``org.junit.jupiter.api.Test``)を付与します。 + +ビルドとインストール +==================== + +pom.xml +------- + +プラグインは ``fess-parent`` を親 POM とする jar としてビルドします。\ ``fess`` および +``opensearch`` への依存は、実行時に |Fess| 本体から提供されるため ``provided`` にします。 + +.. code-block:: xml + + + 4.0.0 + org.codelibs.fess + fess-ds-example + 15.10.0 + jar + + + org.codelibs.fess + fess-parent + 15.10.0 + + + + + + org.codelibs.fess + fess + provided + + + org.opensearch + opensearch + provided + + + + +テストには JUnit 5 と ``org.dbflute.utflute:utflute-lastaflute`` を利用します。 + +ビルド +------ + +.. code-block:: bash + + mvn clean package + +``target/`` ディレクトリに ``fess-ds-example-15.10.0.jar`` が生成されます。 + +インストール +------------ + +生成した JAR を |Fess| にインストールし、|Fess| を再起動します。インストール手順の詳細は +:doc:`../admin/plugin-guide` を参照してください。インストール後、管理画面の +「クローラー > データストア」から新規設定を作成し、「ハンドラー名」に ``getName()`` が返す名前 +(この例では ``ExampleDataStore``)を指定します。 + +設定例 +====== + +管理画面での設定例: + +パラメーター +------------ + +「パラメーター」欄には、コネクターが ``paramMap`` から読み取るキーと値を記述します。 + +:: + + api.url=https://api.example.com/v1 + api.key=your_api_key + +スクリプト +---------- + +「スクリプト」欄には、``左辺=右辺`` の形式でマッピングを記述します。左辺がインデックス +フィールド名、右辺がソースレコードのフィールドを参照するスクリプト(新規作成される設定では +JavaScript。スクリプトタイプが記録されていない設定は Groovy として扱われます)です。 +以下は、ソースレコードが ``url`` / ``title`` / ``content`` / ``updated_at`` / +``content_type`` フィールドを持つ場合の例です。 + +:: + + url=url + title=title + content=content + last_modified=updated_at + mimetype=content_type + +.. note:: + + 右辺で参照できるフィールド名は、コネクターが ``resultMap`` に格納する値 + (``paramMap`` の値とソースレコードのフィールド)によって決まります。CSV や JSON など + 既存コネクターでは ``data.*`` のような独自のプレフィックスが付く場合があるため、 + 各コネクターのドキュメントを参照してください。 + +参考情報 +======== + +- :doc:`plugin-architecture` - プラグインアーキテクチャ +- :doc:`../admin/plugin-guide` - プラグインのインストール +- :doc:`../config/datastore/ds-overview` - データストアコネクター概要 +- `fess-ds-example `__ - データストアプラグインの実装テンプレート +- `GitHub: fess-ds-* `__ - 公開コネクターの例 diff --git a/ja/15.10/dev/index.rst b/ja/15.10/dev/index.rst new file mode 100644 index 000000000..00744850c --- /dev/null +++ b/ja/15.10/dev/index.rst @@ -0,0 +1,27 @@ +================================== +|Fess| 開発者ドキュメント +================================== + +|Fess| の拡張開発に関するドキュメントです。 + +.. toctree:: + :maxdepth: 2 + :caption: 概要 + + overview + +.. toctree:: + :maxdepth: 2 + :caption: プラグイン開発 + + plugin-architecture + datastore-plugin + script-engine-plugin + webapp-plugin + ingest-plugin + +.. toctree:: + :maxdepth: 2 + :caption: カスタマイズ + + theme-development diff --git a/ja/15.10/dev/ingest-plugin.rst b/ja/15.10/dev/ingest-plugin.rst new file mode 100644 index 000000000..2424fe4f1 --- /dev/null +++ b/ja/15.10/dev/ingest-plugin.rst @@ -0,0 +1,163 @@ +================================== +Ingestプラグイン +================================== + +概要 +==== + +Ingestプラグインは、ドキュメントがインデックスに登録される直前に +データを加工・変換する機能を提供します。クロールで取得した各ドキュメントは、 +インデックスへ送信される前に登録済みの Ingester を通過します。 + +用途 +==== + +- テキストの正規化（全角/半角変換、空白の整形など） +- メタデータやカスタムフィールドの追加 +- センシティブ情報のマスキング +- 値の変換（例: エンコードされたベクトル埋め込みのデコード） + +Ingester クラス +=============== + +Ingest機能は ``org.codelibs.fess.ingest.Ingester`` 抽象クラスを継承して +実装します。\ ``Ingester`` には、クロールの種類や処理ステージに応じて +呼び出される ``process`` メソッドが用意されています。デフォルト実装は +いずれも受け取った ``target`` をそのまま返す（何もしない）ため、 +必要なメソッドだけをオーバーライドします。 + +- ``protected Map process(Map target)`` + + 2つの ``Map`` 版メソッドの共通の委譲先です。これをオーバーライドすると、 + データストアクロールとWeb/ファイルクロール（インデックス登録時）の + 両方のドキュメントに適用されます。多くの用途では、このメソッドだけを + オーバーライドすれば十分です。 + +- ``public Map process(Map target, DataStoreParams params)`` + + データストアクロール時に呼び出されます。デフォルトでは + ``process(target)`` に委譲します。 + +- ``public Map process(Map target, AccessResult accessResult)`` + + Web/ファイルクロールのインデックス登録時に呼び出されます。 + デフォルトでは ``process(target)`` に委譲します。 + +- ``public ResultData process(ResultData target, ResponseData responseData)`` + + Web/ファイルクロールのレスポンス処理時（アクセス結果を保存する前）に + 呼び出されます。デフォルトでは ``target`` をそのまま返します。 + +実行順序（priority） +-------------------- + +複数の Ingester が登録されている場合は、``priority`` フィールドの昇順 +（値が小さいものが先）に実行されます。デフォルト値は ``99`` です。 +コンストラクタで直接設定するか、``setPriority(int)`` で変更できます。 + +.. code-block:: java + + public int getPriority() + public void setPriority(final int priority) + +実装例 +====== + +``process(Map)`` をオーバーライドし、コンテンツを正規化して +カスタムフィールドを追加する例です: + +.. code-block:: java + + package org.codelibs.fess.ingest.example; + + import java.util.Map; + + import org.codelibs.fess.ingest.Ingester; + + public class ExampleIngester extends Ingester { + + public ExampleIngester() { + // 実行順序を設定（値が小さいほど先に実行。デフォルトは 99） + setPriority(50); + } + + @Override + protected Map process(final Map target) { + // コンテンツの正規化 + final Object content = target.get("content"); + if (content instanceof String) { + target.put("content", ((String) content).trim().replaceAll("\\s+", " ")); + } + + // カスタムフィールドの追加 + target.put("ingested_by", ExampleIngester.class.getSimpleName()); + + // 加工したドキュメントを返す + return target; + } + } + +.. note:: + + ``process`` メソッドで ``null`` を返すとインデックス登録に失敗します。 + ドキュメントをスキップする仕組みはないため、必ず ``target`` を返してください。 + +登録 +==== + +Ingester は DIコンテナ経由で登録します。プラグインには ``fess_ingest++.xml`` +を含めます。ファイル名末尾の ``++`` は、|Fess| 本体の ``fess_ingest.xml`` +（Ingester を管理する ``ingestFactory`` を定義）へ設定を追記するマージ規約です。 + +.. code-block:: xml + + + + + + + + + +```` により、コンポーネント生成後に +``Ingester#register()`` が呼び出され、``ingestFactory`` に自身が登録されます。 + +Ingest機能に関する ``fess_config.properties`` の設定項目はありません。 +有効・無効はプラグインの導入有無で、実行順序は ``priority`` で制御します。 + +実行フロー +========== + +Ingester は、加工されたドキュメントがインデックスへ送信される直前に、 +以下の箇所で ``priority`` の昇順に呼び出されます: + +- **データストアクロール**: ドキュメントを送信する直前に + ``process(Map, DataStoreParams)`` が呼び出されます。 +- **Web/ファイルクロール（レスポンス処理時）**: クロール結果を保存する前に + ``process(ResultData, ResponseData)`` が呼び出されます。 +- **Web/ファイルクロール（インデックス登録時）**: ドキュメントを送信する直前に + ``process(Map, AccessResult)`` が呼び出されます。 + +いずれの箇所でも、ある Ingester が例外をスローした場合は警告ログを出力して +処理を継続します（そのドキュメントのインデックス登録は中断されません）。 + +.. note:: + + Ingester はクローラの実行環境（``ingestFactory``）に登録されるため、 + クロール処理の一部として動作します。 + +参考実装 +======== + +実装の参考として、以下のプラグインが GitHub の +`CodeLibs `__ で公開されています: + +- ``fess-ingest-example`` - 最小構成のサンプル実装 +- ``fess-webapp-multimodal`` - ベクトル埋め込みをデコードする ``EmbeddingIngester`` を含むプラグイン + +参考情報 +======== + +- :doc:`plugin-architecture` - プラグインアーキテクチャ diff --git a/ja/15.10/dev/overview.rst b/ja/15.10/dev/overview.rst new file mode 100644 index 000000000..093dfe0d1 --- /dev/null +++ b/ja/15.10/dev/overview.rst @@ -0,0 +1,236 @@ +================================== +開発者ドキュメント概要 +================================== + +概要 +==== + +このセクションでは、|Fess| の拡張開発について説明します。 +プラグイン開発、カスタムコネクタの作成、テーマのカスタマイズなど、 +|Fess| を拡張するための情報を提供します。 + +対象読者 +======== + +- |Fess| のカスタム機能を開発したい開発者 +- プラグインを作成したい開発者 +- |Fess| のソースコードを理解したい開発者 + +前提知識 +-------- + +- Java 21の基本的な知識 +- Maven（ビルドシステム）の基本 +- Webアプリケーション開発の経験 +- OpenSearchの基本的な知識（|Fess| は検索エンジンとして OpenSearch を使用します） + +開発環境 +======== + +推奨環境 +-------- + +- **JDK**: OpenJDK 21以上 +- **IDE**: IntelliJ IDEA / Eclipse / VS Code +- **ビルドツール**: Maven（ビルドで最小バージョンは強制されていませんが、Java 21 に対応する新しめの 3.x を推奨） +- **Git**: バージョン管理 +- **OpenSearch**: 検索エンジンのバックエンド（IDEから起動する場合、必要なモジュールとプラグインはビルド時にダウンロードされます） + +セットアップ +------------ + +|Fess| は Maven プロジェクトとしてビルドします。開発時は IDE から起動するのが最も簡単です。 + +1. ソースコードの取得: + + :: + + git clone https://github.com/codelibs/fess.git + +2. IDEへのインポート: + + 取得したディレクトリを Maven プロジェクトとして IDE にインポートします。 + +3. OpenSearch用モジュール・プラグインのダウンロード: + + 初回のみ、以下のコマンドで検索エンジンのモジュールとプラグインを ``plugins`` ディレクトリに取得します。 + + :: + + mvn antrun:run + +4. 開発サーバーの起動（IDEから）: + + IDE上で ``org.codelibs.fess.FessBoot`` を実行またはデバッグ実行し、 + ブラウザで http://localhost:8080/ を開きます。 + 管理画面は http://localhost:8080/admin/ （初期アカウント: ``admin`` / ``admin``）です。 + +5. パッケージのビルド（配布物の作成）: + + 配布パッケージが必要な場合は ``package`` ゴールを実行します。 + 成果物は ``target/releases`` に生成されます（ユニットテストを省略するには ``-DskipTests`` を付与）。 + + :: + + mvn package + + 生成された配布物を展開すると ``bin/fess`` 起動スクリプトが利用できます。 + + :: + + unzip target/releases/fess-*.zip + ./fess-*/bin/fess + +.. note:: + + ``bin/fess`` 起動スクリプトは配布パッケージ（zip/rpm/deb）に含まれるものです。 + ソースツリーで ``mvn package`` を実行しただけでは、リポジトリ直下に ``bin/fess`` は生成されません。 + ソースからの開発では、上記のように IDE で ``FessBoot`` を実行するか、 + 展開した配布物の ``bin/fess`` を使用してください。 + +アーキテクチャ概要 +================== + +|Fess| は以下の主要コンポーネントで構成されています: + +コンポーネント構成 +------------------ + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - コンポーネント + - 説明 + * - Web層 + - LastaFluteフレームワークによるMVC実装 + * - サービス層 + - ビジネスロジック + * - データアクセス層 + - DBFlute（ESFlute/FreeGen）による型安全なOpenSearchアクセス + * - クローラー + - fess-crawlerライブラリによるコンテンツ収集 + * - 検索エンジン + - OpenSearchによる全文検索 + +主要フレームワーク +------------------ + +- **LastaFlute**: Webフレームワーク（アクション、フォーム、バリデーション） +- **DBFlute**: データアクセスフレームワーク。OpenSearch向けの型安全なアクセスクラス（``Bhv`` / ``ConditionBean``）は、 + DBFlute の FreeGen 機能と ESFlute テンプレートによって生成されます + （再生成は ``mvn dbflute:freegen``） +- **Lasta Di**: 依存性注入コンテナ + +ディレクトリ構造 +================ + +:: + + fess/ + ├── src/main/java/org/codelibs/fess/ + │ ├── app/ + │ │ ├── web/ # コントローラー（Action） + │ │ ├── service/ # サービス + │ │ ├── logic/ # ロジック + │ │ └── pager/ # ページネーション + │ ├── api/ # REST API（api/v2 など） + │ ├── helper/ # ヘルパークラス + │ ├── crawler/ # クローラー関連 + │ ├── indexer/ # インデックス処理 + │ ├── opensearch/ # OpenSearchアクセス（ESFlute/FreeGen生成） + │ ├── llm/ # LLM統合 + │ ├── ds/ # データストアコネクタ + │ ├── ingest/ # Ingest（インデックス時のデータ加工） + │ ├── script/ # スクリプトエンジン + │ ├── entity/ # エンティティ + │ └── mylasta/ # LastaFlute設定（DI・メッセージ・型安全設定） + ├── src/main/resources/ + │ ├── fess_config.properties # 設定 + │ └── fess_*.xml # DI設定（app.xml, fess_ds.xml など） + └── src/main/webapp/ + └── WEB-INF/view/ # 管理画面とログイン画面のJSP + +拡張ポイント +============ + +|Fess| は以下の拡張ポイントを提供しています: + +プラグイン +---------- + +プラグインを使用して機能を追加できます。 + +- **データストアプラグイン**: 新しいデータソースからのクロール（``AbstractDataStore`` を継承） +- **スクリプトエンジンプラグイン**: 新しいスクリプト言語のサポート（``ScriptEngine`` を実装） +- **Webアプリプラグイン**: Webインターフェースの拡張（Lasta Di のコンポーネント上書きとリソースのマージ） +- **Ingestプラグイン**: インデックス時のデータ加工（``Ingester`` を継承） + +詳細: :doc:`plugin-architecture` + +.. note:: + + |Fess| 本体は ``war`` としてパッケージングされます。プラグインをローカルでビルドする際に、 + |Fess| を依存関係として解決できない場合は、``pom.xml`` の ```` を一時的に ``jar`` に変更して + ``mvn clean install -DskipTests`` を実行し、その後 ``war`` に戻してください。 + +テーマ +------ + +検索画面のデザインをカスタマイズできます。 + +詳細: :doc:`theme-development` + +設定 +---- + +``fess_config.properties`` で多くの動作をカスタマイズできます。 + +詳細: :doc:`../config/intro` + +プラグイン開発 +============== + +プラグイン開発の詳細については、以下を参照してください: + +- :doc:`plugin-architecture` - プラグインアーキテクチャ +- :doc:`datastore-plugin` - データストアプラグイン開発 +- :doc:`script-engine-plugin` - スクリプトエンジンプラグイン +- :doc:`webapp-plugin` - Webアプリプラグイン +- :doc:`ingest-plugin` - Ingestプラグイン + +テーマ開発 +========== + +- :doc:`theme-development` - テーマのカスタマイズ + +ベストプラクティス +================== + +コーディング規約 +---------------- + +- |Fess| の既存コードスタイルに従う +- ``mvn formatter:format`` でコードフォーマット +- ``mvn license:format`` でライセンスヘッダー追加 + +テスト +------ + +- ユニットテスト（``*Test.java``）: デフォルトの ``build`` プロファイルで ``mvn test`` として実行されます +- 統合テスト（``*Tests.java``）: ``mvn test -P integrationTests`` で実行されます。 + 統合テストの実行には、稼働中の |Fess| サーバーと OpenSearch が必要です + +ロギング +-------- + +- Log4j2を使用 +- ``logger.debug()`` / ``logger.info()`` / ``logger.warn()`` / ``logger.error()`` +- センシティブな情報はログに出力しない + +リソース +======== + +- `GitHub Repository `__ +- `Issue Tracker `__ +- `Discussions `__ diff --git a/ja/15.10/dev/plugin-architecture.rst b/ja/15.10/dev/plugin-architecture.rst new file mode 100644 index 000000000..3aa64ae6d --- /dev/null +++ b/ja/15.10/dev/plugin-architecture.rst @@ -0,0 +1,367 @@ +================================== +プラグインアーキテクチャ +================================== + +概要 +==== + +|Fess| のプラグインシステムにより、コア機能を拡張できます。 +プラグインは JAR ファイルとして配布され、クラスパスに追加されると +DI コンテナ(Lasta Di)によってコンポーネントが読み込まれ、対応する +ファクトリーやマネージャーへ登録されます。 + +プラグインの種類 +================ + +|Fess| は、アーティファクト名のプレフィックスによってプラグインの種類を +判別します(``PluginHelper.ArtifactType``)。主な種類は以下のとおりです: + +.. list-table:: + :header-rows: 1 + :widths: 20 25 55 + + * - 種類 + - プレフィックス + - 説明 + * - データストア + - ``fess-ds-*`` + - 新しいデータソースからのコンテンツ取得(Box、Slack、Git 等) + * - Webアプリ + - ``fess-webapp-*`` + - Web インターフェースや検索機能の拡張 + * - スクリプトエンジン + - ``fess-script-*`` + - 新しいスクリプト言語のサポート + * - Ingest + - ``fess-ingest-*`` + - インデックス登録時のドキュメント加工 + * - サムネイル + - ``fess-thumbnail-*`` + - サムネイル生成方式の追加 + * - LLM + - ``fess-llm-*`` + - RAG/チャットで使用する LLM プロバイダーの追加 + * - クローラー + - ``fess-crawler-*`` + - クローラークライアントの拡張 + * - ストレージ + - ``fess-storage-*`` + - クロールとストレージ機能で使用するオブジェクトストレージバックエンドの追加 + * - SSO + - ``fess-sso-*`` + - ``sso.type`` で選択されるシングルサインオン認証方式の追加 + +.. note:: + + JSP を提供する ``fess-theme-*`` (JAR テーマ)の種類は 15.10 で削除されました。 + 検索画面の見た目は、プラグインではなく静的テーマで変えます(:doc:`theme-development` を参照)。 + +プラグイン構造 +============== + +基本構造 +-------- + +データストアプラグインの実装テンプレートである +`fess-ds-example `__ を例にすると、 +プラグインは「実装クラス」と「DI 登録ファイル」で構成されます: + +:: + + fess-ds-example/ + ├── pom.xml + └── src/main/ + ├── java/org/codelibs/fess/ds/example/ + │ └── ExampleDataStore.java # データストア実装 + └── resources/ + └── fess_ds++.xml # DIコンポーネント登録 + +pom.xmlの例 +----------- + +プラグインは ``fess-parent`` を親 POM とする jar としてビルドします。 +``fess`` や ``opensearch`` など、実行時に |Fess| 本体から提供されるライブラリは +``provided`` スコープで宣言します。バージョン番号やビルド設定(フォーマッター・ +ライセンスヘッダーなど)は親 POM から継承されます。 + +.. code-block:: xml + + + + 4.0.0 + + org.codelibs.fess + fess-ds-example + 15.10.0 + jar + + + org.codelibs.fess + fess-parent + 15.10.0 + + + + + + org.codelibs.fess + fess + provided + + + org.opensearch + opensearch + provided + + + + +.. note:: + + 開発中のブランチでは、バージョンは ``15.10.0-SNAPSHOT`` のように ``-SNAPSHOT`` 付きに + なります。プラグイン固有の依存ライブラリは通常の Maven 依存関係として宣言します。 + これらは |Fess| 本体には含まれないため、プラグインと一緒に配布する必要があります。 + +プラグインの登録 +================ + +DIコンテナへの登録 +------------------ + +プラグインは、``fess_ds++.xml`` のように末尾が ``++`` の DI 設定ファイルで +コンポーネントを登録します。Lasta Di は、クラスパス上に見つかった ``++`` 付きの +ファイルを、|Fess| 本体の対応する設定ファイル(この例では ``fess_ds.xml``)へ +自動的にマージします。この仕組みにより、プラグインは |Fess| 本体のファイルを +編集することなく、自身のコンポーネントを追加できます。 + +.. code-block:: xml + + + + + + + + + +プラグインの種類ごとにマージ先のファイルが異なります。例えばスクリプトエンジンは +``fess_se++.xml``、Ingest は ``fess_ingest++.xml``、LLM プロバイダーは +``fess_llm++.xml``、Web アプリは ``app++.xml`` を使用します。 + +コンポーネントの初期化 +---------------------- + +```` は、コンポーネント生成後に呼び出す +メソッドを指定する Lasta Di のライフサイクル設定です。データストアの場合、 +``AbstractDataStore`` が持つ ``register()`` メソッドが呼び出され、 +自身が ``DataStoreFactory`` に登録されます: + +.. code-block:: java + + // AbstractDataStore の実装(通常はオーバーライド不要) + public void register() { + ComponentUtil.getDataStoreFactory().add(getName(), this); + } + +.. note:: + + これは Java の ``@PostConstruct`` アノテーションではなく、DI 設定ファイルの + ```` 要素による初期化です。登録される名前は ``getName()`` の + 戻り値であり、管理画面でプラグインを選択する際の名前になります。 + +プラグインのライフサイクル +========================== + +初期化 +------ + +1. プラグイン JAR がクラスパスに追加される +2. DI コンテナが ``fess_*++.xml`` をマージし、コンポーネントを生成する +3. ```` で指定したメソッド(例: ``register``)が呼び出される +4. プラグインが対応するファクトリー/マネージャーに登録される + +終了 +---- + +1. DI コンテナの終了時に、```` で指定したメソッドが呼び出される + (定義されている場合) +2. リソースのクリーンアップ + +.. note:: + + データストアの場合、実行中のクロールは ``AbstractDataStore.stop()`` によって + 停止フラグが立てられ、レコード処理ループが安全に終了します。 + +依存関係 +======== + +Fess本体との依存 +---------------- + +|Fess| 本体のクラスは実行時にサーバーのクラスパス上に存在するため、 +``provided`` スコープで依存します(プラグイン JAR には含めません)。 + +.. code-block:: xml + + + org.codelibs.fess + fess + provided + + +外部ライブラリ +-------------- + +プラグインは独自の依存ライブラリを含めることができます: + +.. code-block:: xml + + + com.example + example-sdk + 1.0.0 + + +これらは |Fess| 本体に含まれないため、プラグインと一緒に配布する必要があります。 + +設定の取得 +========== + +パラメーターとFessConfigの取得 +------------------------------ + +データストアの ``storeData()`` では、管理画面で設定したパラメーターを +``DataStoreParams`` から取得します。値の取得には ``getAsString()`` を使用します +(``DataStoreParams`` は ``Map`` を実装していないため ``get()`` は文字列を返しません)。 +また、|Fess| の設定値は ``ComponentUtil.getFessConfig()`` から取得できます: + +.. code-block:: java + + public class ExampleDataStore extends AbstractDataStore { + + @Override + protected String getName() { + // ハンドラー名として使用される。クラスの単純名を返すのが慣例 + return this.getClass().getSimpleName(); + } + + @Override + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { + + // パラメーターの取得 + final String apiKey = paramMap.getAsString("api.key"); + final String baseUrl = paramMap.getAsString("base.url"); + + // FessConfig の取得 + final FessConfig fessConfig = ComponentUtil.getFessConfig(); + } + } + +``storeData()`` の詳しい実装方法(データ取得・スクリプト評価・インデックス登録の +流れ)は :doc:`datastore-plugin` を参照してください。 + +ビルドとインストール +==================== + +ビルド +------ + +:: + + mvn clean package + +``target/`` ディレクトリに JAR ファイル(例: ``fess-ds-example-15.10.0.jar``)が +生成されます。 + +インストール +------------ + +1. **管理画面から**: + + - 「システム」→「プラグイン」→「インストール」を開く + - プラグインリポジトリの一覧から選択するか、ビルドした JAR ファイルを + アップロードしてインストール + +2. **手動**: + + - JAR ファイルを ``app/WEB-INF/plugin/`` ディレクトリにコピー + - |Fess| を再起動 + +インストール手順の詳細は :doc:`../admin/plugin-guide` を参照してください。 + +デバッグ +======== + +ログ出力 +-------- + +|Fess| は Log4j2 を使用します。ロガーは ``LogManager.getLogger()`` で取得します: + +.. code-block:: java + + private static final Logger logger = LogManager.getLogger(ExampleDataStore.class); + + public void someMethod() { + logger.debug("Debug message"); + logger.info("Info message"); + } + +.. note:: + + パスワードやトークンなどの機微な情報はログに出力しないでください。 + +開発モード +---------- + +開発時は |Fess| を IDE から起動してデバッグできます: + +1. ``org.codelibs.fess.FessBoot`` クラスをデバッグ実行する +2. プラグインのソースをプロジェクトに含める +3. ブレークポイントを設定する + +公開プラグイン一覧 +================== + +|Fess| プロジェクトでは、多数のプラグインが公開されています。以下は代表例です +(すべてを網羅したものではありません): + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - プラグイン + - 説明 + * - ``fess-ds-box`` + - Box コネクター + * - ``fess-ds-dropbox`` + - Dropbox コネクター + * - ``fess-ds-slack`` + - Slack コネクター + * - ``fess-ds-atlassian`` + - JIRA / Confluence コネクター + * - ``fess-ds-git`` + - Git リポジトリコネクター + * - ``fess-llm-openai`` + - OpenAI LLM プロバイダー + +このほかにも、``fess-ds-csv`` / ``fess-ds-db`` / ``fess-ds-json`` / +``fess-ds-microsoft365`` / ``fess-ds-sharepoint`` などのデータストアコネクターや、 +``fess-llm-ollama`` / ``fess-llm-gemini`` / ``fess-llm-bedrock`` などの LLM プロバイダーが公開されています。 +これらのプラグインは、開発の参考として +`GitHub `__ で公開されています。 + +参考情報 +======== + +- :doc:`datastore-plugin` - データストアプラグイン開発 +- :doc:`script-engine-plugin` - スクリプトエンジンプラグイン +- :doc:`webapp-plugin` - Webアプリプラグイン +- :doc:`ingest-plugin` - Ingestプラグイン +- :doc:`theme-development` - テーマのカスタマイズ +- :doc:`../admin/plugin-guide` - プラグインのインストール diff --git a/ja/15.10/dev/script-engine-plugin.rst b/ja/15.10/dev/script-engine-plugin.rst new file mode 100644 index 000000000..ac16b8cf1 --- /dev/null +++ b/ja/15.10/dev/script-engine-plugin.rst @@ -0,0 +1,61 @@ +================================== +スクリプトエンジンプラグイン +================================== + +概要 +==== + +スクリプトエンジンプラグインを開発することで、|Fess| に新しいスクリプト言語の +サポートを追加できます。 + +基本実装 +======== + +``ScriptEngine`` インターフェースを実装します: + +.. code-block:: java + + package org.codelibs.fess.script.example; + + import org.codelibs.fess.script.ScriptEngine; + import java.util.Map; + + public class ExampleScriptEngine implements ScriptEngine { + + @Override + public String getName() { + return "example"; + } + + @Override + public Object evaluate(String script, Map params) { + // スクリプトの評価ロジック + return executeScript(script, params); + } + } + +登録 +==== + +.. code-block:: java + + @PostConstruct + public void register() { + ComponentUtil.getScriptEngineManager().add(this); + } + +使用例 +====== + +管理画面でスクリプトタイプとして選択: + +:: + + scriptType=example + scriptData=your script here + +参考情報 +======== + +- :doc:`plugin-architecture` - プラグインアーキテクチャ +- :doc:`../config/scripting-overview` - スクリプティング概要 diff --git a/ja/15.10/dev/theme-development.rst b/ja/15.10/dev/theme-development.rst new file mode 100644 index 000000000..f61b9f875 --- /dev/null +++ b/ja/15.10/dev/theme-development.rst @@ -0,0 +1,301 @@ +================================== +テーマ開発ガイド +================================== + +概要 +==== + +|Fess| 15.10 の検索画面は、常に静的テーマで表示されます。静的テーマは ``/api/v2/*`` API を +利用する独立した SPA(シングルページアプリケーション)です。テーマは ZIP ファイルとして +配布し、管理画面からアップロードして有効化します。テーマを選んでいない場合は、|Fess| に +同梱の静的テーマ ``bootstrap`` が使われます。 + +検索画面の見た目を変えるには、別のテーマをインストールするか(:doc:`../admin/theme-guide` +を参照)、独自のテーマを作ります。独自のテーマは、同梱のテーマを複製して変更するのが +最も簡単です(`同梱テーマのカスタマイズ`_ を参照)。 + +.. note:: + + 静的テーマは |Fess| 15.7 以降で利用でき、15.10 で既定の検索画面になりました。検索画面の + JSP を差し替える JAR テーマプラグインは、15.10 で削除されました。 + `JAR テーマプラグイン(15.10 で削除)`_ を参照してください。 + +静的テーマ +========== + +静的テーマは、``theme.yml`` マニフェストと ``index.html`` を含む静的リソースの +集合です。テーマ本体は |Fess| の ``/api/v2/*`` API を呼び出すフロントエンド +アプリケーションとして実装します。 + +構造 +---- + +静的テーマは、次のようなディレクトリ構成になります。 + +:: + + example/ + ├── theme.yml # マニフェスト(必須) + ├── index.html # SPA のエントリー HTML + ├── assets/ # JavaScript・CSS などの静的リソース + │ └── styles.css + ├── i18n/ # 多言語メッセージ(messages..json) + │ └── messages.en.json + ├── help/ # ヘルプ定義(.json) + │ └── en.json + └── thumbnail.png # プレビュー画像(任意) + +マニフェスト (theme.yml) +------------------------ + +``theme.yml`` は ZIP のルートに配置する必須のマニフェストです。以下は最小構成の +例です。 + +.. code-block:: yaml + + apiVersion: fess.codelibs.org/v1 + kind: StaticTheme + name: example + displayName: "Example Theme" + version: "15.10.0" + minFessVersion: "15.10" + entry: index.html + spaFallback: true + +指定できるフィールドは以下のとおりです。 + +.. list-table:: + :header-rows: 1 + :widths: 22 12 66 + + * - フィールド + - 必須 + - 説明 + * - ``apiVersion`` + - 必須 + - 固定値 ``fess.codelibs.org/v1``\ 。 + * - ``kind`` + - 必須 + - 固定値 ``StaticTheme``\ 。 + * - ``name`` + - 必須 + - テーマ名。\ ``^[a-z0-9][a-z0-9_-]{0,63}$`` に一致する必要があります。 + ``themes/`` 配下に展開されるテーマのディレクトリ名(アップロード時は + この ``name`` から自動的に決まります)、および配信 URL + (``/themes//``)に使用されます。 + * - ``displayName`` + - 必須 + - 管理画面に表示される名前。 + * - ``version`` + - 必須 + - セマンティックバージョニング形式(例: ``15.10.0``、``15.10.1-beta.1``)。慣例として + ``major.minor`` はテーマが対象とする |Fess| の系列に合わせます。こうすると + バージョンだけでどの |Fess| 用のテーマか分かります。 + * - ``author`` + - 任意 + - 作者名。 + * - ``description`` + - 任意 + - テーマの説明。 + * - ``license`` + - 任意 + - ライセンス。 + * - ``homepage`` + - 任意 + - ホームページ URL。 + * - ``minFessVersion`` + - 任意 + - テーマが対応する |Fess| の最小バージョン。 ``version`` の ``major.minor`` と + 同じ値にします。 ``maxFessVersion`` はありません。 `公開`_ を参照してください。 + * - ``supportedLocales`` + - 任意 + - 対応ロケールの一覧(例: ``[en, ja, de]``)。 + * - ``entry`` + - 任意 + - SPA のエントリー HTML。既定値は ``index.html``\ 。 + * - ``spaFallback`` + - 任意 + - 非推奨。互換性のために受け付けますが、読まれません。15.10 からは検索画面の + 各パスで常にエントリー HTML が返ります。 + +.. note:: + + ZIP からアップロードする場合、展開先のディレクトリ名は ``name`` から自動的に + 決まります。\ ``themes/`` ディレクトリに手動でテーマを配置する場合は、ディレクトリ名を + ``name`` と一致させてください。一致しないテーマは再スキャン時に無視されます。 + +.. note:: + + プレビュー用のサムネイルは、テーマのルートに ``thumbnail.png`` という固定名で + 配置します(管理画面のテーマ一覧で表示されます)。この画像はマニフェストの + フィールドではなく、ファイル名で認識されます。サイズは 512KB 以内・512×512 + ピクセル以内を推奨します。 + +配信と API +---------- + +- 静的テーマは ``/themes//`` 配下で配信されます(```` は + ``theme.yml`` の ``name``)。 +- ``/``、``/search``、``/advance``、``/help``、``/error``、``/profile``、 + ``/cache``、``/chat`` の各パスでエントリー HTML(既定は ``index.html``)が返され、 + 以降のルーティングは SPA が行います。15.10 からは ``spaFallback`` の値に関係なく + こう動作し、このフィールドは読まれません。 +- エラーもテーマが表示します。リクエストが失敗すると、ブラウザには要求された URL のまま、 + 実際の HTTP ステータスでテーマのエントリー HTML が返ります。 +- 管理画面(``/admin/*``)、``/api/*``、ログイン画面などは静的テーマの対象外で、 + |Fess| 本体が処理します。 +- テーマの SPA は、検索結果やチャットなどのデータを ``/api/v2/*`` API から取得 + します。 +- エントリー HTML の ``{{themePath}}`` は、配信時に ``themes/`` に置き換えられます。 + テーマのファイルを ``index.html`` から参照するときは ``{{themePath}}/assets/styles.css`` + のように書きます。テーマ名を直接書かないので、別の名前でインストールしても自分の + ファイルを読み込めます。 +- エントリー HTML には、スクリプト・スタイル・画像・通信の取得元を |Fess| 自身に限る + ``Content-Security-Policy`` ヘッダーが付きます(インラインのスタイルは許可され、 + インラインのスクリプトは許可されません)。そのため外部の CDN のフォントやスクリプトは + 読み込まれません。テーマに同梱してください。 +- エントリー HTML の ``Content-Security-Policy`` には ``frame-ancestors 'none'`` が含まれ、 + ``X-Frame-Options: DENY`` ヘッダーも付くため、ページは他のページのフレームに表示されません。 + ``frame-ancestors`` の値は ``fess_config.properties`` の ``theme.index.frame.ancestors`` + （デフォルト: ``'none'`` ）で変更できます。空にすると ``frame-ancestors`` を付けません + （ ``X-Frame-Options: DENY`` は付いたままです）。WebKit 系のブラウザー（Safari など）は、 + ``frame-ancestors 'none'`` のもとではテーマが ``blob:`` URL で表示するフレーム + （PDF のプレビューやキャッシュの表示）を空にします。これらを表示するには値を空にします。 + +パッケージング +-------------- + +`fess-themes `__ リポジトリの +``scripts/package.sh`` を使用すると、テーマを配布用の ZIP にまとめられます。 + +:: + + ./scripts/package.sh example + +``dist/example-.zip`` が生成されます(```` は ``theme.yml`` の +``version``)。 + +.. note:: + + ``theme.yml`` は ZIP のルートに配置する必要があります。サブディレクトリに + 入れると、アップロード時に認識されません。 + +公開 +---- + +|Fess| プロジェクトが開発しているテーマは https://maven.codelibs.org/release/org/codelibs/fess/themes/ 以下に公開されています。配置は ``//-.zip`` で、隣に ``.sha1`` が、テーマごとに公開済みバージョンを並べた ``maven-metadata.xml`` が置かれます。 ``bin/fess-setup install theme `` はこのメタデータを読み、動作中の |Fess| 用に作られたバージョンを選びます。 + +テーマのバージョンは対象とする |Fess| の系列に合わせ、アーカイブの中身を変えたときは必ずバージョンを上げてください。公開済みのバージョンが上書きされることはないため、バージョンを据え置いた変更は配布されません。 + +マニフェストに上限を表すフィールドが無いのも同じ理由です。公開されたアーカイブは変更されないため、新しい |Fess| で動作しなくなったテーマにあとから上限を追加することはできません。その系列向けに公開しないことで、分かった時点で同じことを表せます。 + +.. note:: + + 公開済みのバージョンを調べるときは、ディレクトリ一覧ではなく ``maven-metadata.xml`` を使ってください。ディレクトリ索引は定期的に生成されるため、新しく公開したテーマは一覧に現れるより先にメタデータから読み取れます。 + +インストールと有効化 +-------------------- + +1. 管理画面で「システム」→「テーマ」(``/admin/theme/``)を開きます。 +2. 作成した ZIP ファイルをアップロードします。公開済みのテーマは、コマンドラインから + ``bin/fess-setup install theme `` でインストールすることもできます。 + :doc:`../install/fess-setup` を参照してください。 +3. 一覧ページの「デフォルトテーマ」プルダウンから対象テーマを選び、「設定」ボタンを + 押して有効化します。 + +有効化の仕組みは以下のとおりです。 + +- 「設定」ボタンを押すと、選択したテーマ名がシステムプロパティ ``theme.default`` + に保存され、システム全体の既定テーマになります。 +- テーマ名を仮想ホストのキーと一致させると、その仮想ホストにアクセスしたときだけ + テーマが適用されます。これにより、仮想ホストごとにテーマを切り替えられます。 +- ディスク上の ``themes/`` ディレクトリを直接更新した場合は、「再読み込み」で + 再スキャンできます。 + +.. note:: + + ZIP のアップロードには、ファイルサイズ・展開後の合計サイズ・エントリー数などの + 上限があり、``fess_config.properties`` の ``theme.*`` プロパティで調整できます + (例: ``theme.upload.max.size`` は既定 50MB、``theme.directory.path`` は既定 + ``themes``)。展開時には ZIP Slip や zip bomb を防ぐための検証が行われます。 + +.. _theme-customize-bundled: + +同梱テーマのカスタマイズ +------------------------ + +同梱のテーマ ``bootstrap`` は、|Fess| のインストール先の ``app/themes/bootstrap/`` +(RPM/DEB パッケージでは ``/usr/share/fess/app/themes/bootstrap/``)にあります。 +直接編集しないでください。アップグレードで置き換わるうえ、``bootstrap`` という名前は +同梱のテーマ専用で、削除もアップロードによる置き換えもできません。別の名前で複製して +使います。 + +1. ディレクトリを複製します。例えば ``mytheme`` とします:: + + $ cp -r app/themes/bootstrap /tmp/mytheme + +2. ``theme.yml`` の ``name`` を ``mytheme`` に変え、``displayName`` も変えます。 + ``name`` はディレクトリ名と一致させます。 + +3. ``index.html`` は変更しません。同梱の ``index.html`` は、スタイルシート・ロゴ・ + スクリプトなど自分のファイルを ``{{themePath}}/assets/...`` で参照しており、|Fess| は + 配信時に ``{{themePath}}`` を ``themes/`` (``theme.yml`` の ``name``)に + 置き換えます。そのため、名前を変えるだけで複製したテーマは自分のファイルを読み込みます。 + ``index.html`` から参照するファイルを追加するときも、``{{themePath}}/assets/...`` の + 形で書いてください。 + +4. 変更を加えます。 + + - 配色・レイアウト: ``assets/styles.css`` + - ロゴ: ``assets/logo-head.png`` (ヘッダー)と ``assets/logo.png`` (検索トップ) + - フッター(``footer.copyright_org``)などの文言: 言語ごとの + ``i18n/messages..json`` + - ページの構造: ``index.html`` + +5. ``theme.yml`` がルートに来るようにディレクトリを ZIP にまとめ、管理画面の + 「システム」>「テーマ」でアップロードします:: + + $ cd /tmp/mytheme && zip -r ../mytheme.zip . + + ディレクトリを ``app/themes/`` に置き、同じページの「再読み込み」を押してもかまいません。 + +6. 同じページで ``mytheme`` を既定のテーマに設定します。 + +.. note:: + + 同梱のテーマは、その |Fess| のバージョンの ``/api/v2/*`` API に合わせてあります。 + |Fess| をアップグレードしたら、新しい同梱テーマから複製し直して変更を再適用してください。 + +JAR テーマプラグイン(15.10 で削除) +================================== + +JSP・CSS・画像を ``fess-theme-*`` の JAR に入れ、仮想ホストのキーと同じ名前のテーマとして +適用する JAR テーマプラグインの種類は、|Fess| 15.10 で削除されました。15.10 は JAR テーマを +展開せず、どの画面にも使いません。 + +- 管理画面の「システム」→「プラグイン」からインストールしても、種類 ``jar`` の汎用 JAR として + ``app/WEB-INF/plugin/`` に置かれるだけで、画面は何も変わりません。以前のバージョンから + 残った ``fess-theme-*.jar`` も同じように表示され、この画面または + ``bin/fess-setup remove plugin `` で削除できます。 +- ``bin/fess-setup`` は ``fess-theme-*`` を一覧に表示せず、インストールもしません。 + +JAR テーマで行っていた変更は、静的テーマに移してください。 + +- 検索画面の配色・レイアウト・ロゴは、同梱のテーマを複製して変更します + (`同梱テーマのカスタマイズ`_ を参照)。 +- 仮想ホストごとに見た目を変えていた場合は、仮想ホスト名と同じ名前の静的テーマを + インストールします(:doc:`../config/security-virtual-host` を参照)。 +- ログイン画面(``/login/``)は、すべての仮想ホストで共通の画面です。テーマで変えることは + できません。 + +既存テーマの例 +============== + +- `fess-themes `__ - 静的テーマ集 + (``codesearch``、``docsearch`` など複数の静的テーマを収録) + +参考情報 +======== + +- :doc:`plugin-architecture` - プラグインアーキテクチャ +- :doc:`../admin/plugin-guide` - プラグインのインストール diff --git a/ja/15.10/dev/webapp-plugin.rst b/ja/15.10/dev/webapp-plugin.rst new file mode 100644 index 000000000..ed8c59995 --- /dev/null +++ b/ja/15.10/dev/webapp-plugin.rst @@ -0,0 +1,311 @@ +================================== +Webアプリプラグイン +================================== + +概要 +==== + +Web アプリプラグイン(``fess-webapp-*``)は、|Fess| の Web アプリケーションを +拡張するプラグインです。他の種類のプラグインと異なり、Action クラスや JSP を +直接追加するのではなく、DI コンテナ(Lasta Di)に対して **コンポーネントを追加 +または置き換える** ことで機能を拡張します。代表的な用途は次のとおりです: + +- 新しいコンポーネント(ヘルパー・サービスなど)の追加 +- |Fess| 本体のコンポーネントの置き換え(サブクラス化) +- REST API エンドポイントの追加(``WebApiManager``) +- 検索動作の拡張(クエリコマンド、ランクフュージョンなど) + +.. note:: + + Web アプリプラグインは JAR として配布され、内部のクラスと DI 設定ファイルが + |Fess| の Web アプリケーションのクラスパスに読み込まれます。JSP ビューを + 追加するものではありません。検索画面のデザインをカスタマイズする場合は + :doc:`theme-development` を参照してください。 + +基本構造 +======== + +Web アプリプラグインの実装テンプレートである +`fess-webapp-example `__ を +例にすると、プラグインは「実装クラス」と「DI 登録ファイル」で構成されます: + +:: + + fess-webapp-example/ + ├── pom.xml + └── src/main/ + ├── java/org/codelibs/fess/webapp/example/helper/ + │ ├── ExampleHelper.java # 追加するコンポーネント + │ └── CustomSystemHelper.java # コアコンポーネントの置き換え + └── resources/ + ├── app++.xml # コンポーネントの追加(マージ) + └── fess+systemHelper.xml # コンポーネントの置き換え + +.. note:: + + 実装クラスのパッケージは ``org.codelibs.fess.webapp.<プラグイン名>`` を使用します。 + DI 設定ファイルは ``src/main/resources/`` に配置します。データストアプラグインと + 異なり ``src/main/webapp/`` や JSP は含めません。 + +pom.xmlとマニフェスト +===================== + +Web アプリプラグインは ``fess-parent`` を親 POM とする jar としてビルドします。 +|Fess| 本体から実行時に提供される ``fess`` や ``opensearch`` は ``provided`` +スコープで宣言し、``lastaflute``・``dbflute-runtime``・``corelib`` など実行時に +必要なライブラリは通常のスコープで宣言します。 + +Web アプリプラグインで最も重要なのは、JAR マニフェストに ``Fess-WebAppJar: true`` +を付与することです。この宣言により、|Fess| はプラグインのクラスと DI 設定ファイルを +Web アプリケーションのクラスローダーへマウントします。この設定は +``maven-jar-plugin`` で行います: + +.. code-block:: xml + + + + + maven-jar-plugin + + + + true + + + + + + + +.. warning:: + + ``Fess-WebAppJar: true`` を付与しないと、プラグインのクラスや DI 設定ファイルは + Web アプリケーションのクラスパスに読み込まれず、コンポーネントの追加・置き換えが + 有効になりません。 + +pom.xml 全体の構成(親 POM・依存関係の宣言方法など)は +:doc:`plugin-architecture` を参照してください。 + +拡張パターン +============ + +コンポーネントの追加(app++.xml) +-------------------------------- + +最も基本的な拡張方法は、独自のコンポーネントを追加することです。 +Lasta Di は、クラスパス上の ``app++.xml`` を |Fess| 本体の ``app.xml`` から +構築される ``app`` 名前空間へ **マージ** します(末尾の ``++`` は追加マージの +規約です)。追加するコンポーネントは |Fess| 本体に存在しない名前を使用するため、 +何も上書きされません。 + +.. code-block:: xml + + + + + + + + +コンポーネントの実装では、初期化に ``@PostConstruct`` を使用し、|Fess| 本体の +コンポーネントは ``ComponentUtil`` から取得して再利用します(コピーや上書きは +しません): + +.. code-block:: java + + package org.codelibs.fess.webapp.example.helper; + + import org.codelibs.fess.helper.SystemHelper; + import org.codelibs.fess.util.ComponentUtil; + + import jakarta.annotation.PostConstruct; + + public class ExampleHelper { + + protected String pluginName = "fess-webapp-example"; + + @PostConstruct + public void init() { + // DI による生成後に一度だけ呼び出される初期化処理 + } + + public String getPluginLabel() { + // コアの SystemHelper を再利用して稼働中の Fess バージョンを取得 + final SystemHelper systemHelper = ComponentUtil.getSystemHelper(); + final String version = systemHelper != null ? systemHelper.getProductVersion() : "unknown"; + return pluginName + " (Fess " + version + ")"; + } + } + +.. tip:: + + まずはこの「コンポーネントの追加」を検討してください。コア機能を変更する必要が + ない限り、置き換えよりも安全でメンテナンス性に優れます。 + +コアコンポーネントの置き換え(fess+componentName.xml) +----------------------------------------------------- + +|Fess| 本体のコンポーネントの挙動を変更したい場合は、対象クラスをサブクラス化し、 +``+.xml`` という名前の DI 設定ファイルで **同じ +コンポーネント名で再登録** します。例えば ``systemHelper`` は |Fess| 本体の +``fess.xml`` で宣言されているため、置き換えファイルは ``fess+systemHelper.xml`` +になります(``app+systemHelper.xml`` ではありません)。 + +.. code-block:: java + + package org.codelibs.fess.webapp.example.helper; + + import java.nio.file.Path; + + import org.codelibs.fess.helper.SystemHelper; + + public class CustomSystemHelper extends SystemHelper { + + @Override + protected void parseProjectProperties(final Path propPath) { + try { + super.parseProjectProperties(propPath); + } catch (final Exception e) { + // 独自の処理 + } + System.setProperty("fess.webapp.plugin", "true"); + } + } + +.. warning:: + + 置き換え(単一の ``+``)は、コンポーネント定義を **丸ごと** 置き換えます。 + このため、置き換えファイルにはコア定義が行っている ```` を + すべて記述する必要があります(例えば ``app.xml`` の ``queryHelper``)。これらは + |Fess| のリリースごとに同期する必要があります。コアから削除されたメソッドを呼び続けると、 + そのコンポーネント定義は ``BeanMethodNotFoundException`` で初期化に失敗します。例えば + 15.10 では ``systemHelper`` の ``addDesignJspFileName`` が削除されたため、これを呼ぶ + 置き換えファイルは失敗します。この保守コストが、置き換えよりも追加が推奨される理由です。 + +REST APIの追加(fess_api++.xml) +------------------------------- + +新しい REST API エンドポイントを追加するには、``WebApiManager`` を実装します。 +``BaseApiManager`` を継承し、``@PostConstruct`` で ``WebApiManagerFactory`` に +自身を登録します。登録された API マネージャーは、リクエストごとに ``WebApiFilter`` +から呼び出されます。\ ``fess_api++.xml`` でコンポーネントを登録します: + +.. code-block:: xml + + + + + + + + +.. code-block:: java + + package org.codelibs.fess.webapp.example.api; + + import java.io.IOException; + + import org.codelibs.fess.api.BaseApiManager; + import org.codelibs.fess.util.ComponentUtil; + + import jakarta.annotation.PostConstruct; + import jakarta.servlet.FilterChain; + import jakarta.servlet.ServletException; + import jakarta.servlet.http.HttpServletRequest; + import jakarta.servlet.http.HttpServletResponse; + + public class ExampleApiManager extends BaseApiManager { + + public ExampleApiManager() { + // このマネージャーが処理するパスのプレフィックス + setPathPrefix("/api/example"); + } + + @PostConstruct + public void register() { + ComponentUtil.getWebApiManagerFactory().add(this); + } + + @Override + public boolean matches(final HttpServletRequest request) { + // このマネージャーがリクエストを処理するかどうかを判定 + return request.getServletPath().startsWith(pathPrefix); + } + + @Override + public void process(final HttpServletRequest request, final HttpServletResponse response, + final FilterChain chain) throws IOException, ServletException { + // リクエストの処理とレスポンスの書き込み + } + + @Override + protected void writeHeaders(final HttpServletResponse response) { + // レスポンスヘッダーの設定(必要に応じて) + } + } + +実装例としては、``/api/v1`` を提供する +`fess-webapp-v1-api `__ や、 +``/json`` / ``/suggest`` を提供する +`fess-webapp-classic-api `__ が +参考になります。 + +検索画面のカスタマイズ +====================== + +Web アプリプラグインは JSP ビューを追加できません。JSP ビューは |Fess| 本体の WAR の +``WEB-INF/view/`` に配置されており、プラグイン JAR はクラスパス +(``WEB-INF/classes``)にマウントされるためです。検索画面のデザインを変更する場合は、 +静的テーマを使用します。静的テーマは検索画面のデザイン(HTML/CSS/JavaScript)を +カスタマイズします。:doc:`theme-development` を参照してください。 + +ビルドとインストール +==================== + +:: + + mvn clean package + +``target/`` ディレクトリに JAR ファイル(例: ``fess-webapp-example-15.10.0.jar``)が +生成されます。生成した JAR は管理画面からインストールするか、 +``app/WEB-INF/plugin/`` ディレクトリに配置して |Fess| を再起動します。 +インストール手順の詳細は :doc:`../admin/plugin-guide` を参照してください。 + +公開プラグインの例 +================== + +|Fess| プロジェクトでは、以下の Web アプリプラグインが公開されています。 +開発の参考として `GitHub `__ で公開されています: + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - プラグイン + - 説明 + * - ``fess-webapp-example`` + - プラグイン実装のテンプレート + * - ``fess-webapp-v1-api`` + - ``/api/v1`` REST API + * - ``fess-webapp-classic-api`` + - ``/json`` / ``/suggest`` レガシー REST API + * - ``fess-webapp-mcp`` + - MCP(Model Context Protocol)サーバー + * - ``fess-webapp-bangs`` + - DuckDuckGo 形式のバング(``!g``)。別のサイトへ検索を送る + * - ``fess-webapp-semantic-search`` + - ニューラル検索/ベクトル検索(15.10でコアに統合されたため非推奨) + * - ``fess-webapp-multimodal`` + - マルチモーダル(画像・テキスト)検索 + +参考情報 +======== + +- :doc:`plugin-architecture` - プラグインアーキテクチャ +- :doc:`theme-development` - テーマのカスタマイズ +- :doc:`../admin/plugin-guide` - プラグインのインストール +- :doc:`overview` - 開発者ドキュメント概要 diff --git a/ja/15.10/install/fess-setup.rst b/ja/15.10/install/fess-setup.rst new file mode 100644 index 000000000..2b261850c --- /dev/null +++ b/ja/15.10/install/fess-setup.rst @@ -0,0 +1,243 @@ +==================== +fess-setup コマンド +==================== + +``bin/fess-setup`` （Windows では ``bin\fess-setup.bat`` ）は、 |Fess| の ZIP パッケージに同梱されているコマンドです。 |Fess| に必要でありながら配布物に含まれていないもの、つまり |Fess| が必要とするプラグインを入れた OpenSearch、Playwright 系プラグインが使う Node.js、 |Fess| のプラグイン、静的テーマを導入します。インストール状態の診断もできます。 + +|Fess| のディレクトリで実行します。引数を付けずに実行すると、コマンドの一覧を表示します。 + +:: + + $ cd /path/to/fess-15.10.0 + $ bin/fess-setup [options] + +終了コード +========== + +.. list-table:: + :header-rows: 1 + :widths: 15 85 + + * - コード + - 意味 + * - ``0`` + - コマンドが成功しました。 + * - ``1`` + - コマンドが失敗しました。ダウンロードに失敗した、指定したバージョンが存在しない、このプラットフォーム向けの OpenSearch が配布されていない、 ``check`` が問題を検出した、などの場合です。 + * - ``2`` + - コマンドラインの誤りです。未知のコマンドを指定した、プラグイン名などの引数が不足している、などの場合です。 + +OpenSearch と Node.js の導入 +============================ + +install opensearch +------------------ + +:: + + $ bin/fess-setup install opensearch [--dest ] [--version ] [--keep-bundled-plugins] + +この |Fess| が対応するバージョンの OpenSearch を |Fess| のディレクトリの ``opensearch/`` にダウンロードし、 |Fess| が必要とする 4 つのプラグイン（ ``opensearch-analysis-fess`` 、 ``opensearch-analysis-extension`` 、 ``opensearch-minhash`` 、 ``opensearch-configsync`` ）を導入したうえで、その ``config/opensearch.yml`` に次の設定を追記します。 + +- ``configsync.config_path`` （値はその OpenSearch の ``config/dictionary`` ディレクトリ） +- ``plugins.security.disabled: true`` + +また、 |Fess| が使用しない同梱プラグイン ``opensearch-security-analytics`` と ``opensearch-performance-analyzer`` を削除します。Docker イメージの OpenSearch と同じ構成です。配布物に含まれないプラグインは何もせずに進みます。 + +``opensearch.yml`` にすでにある設定は追記しません。また、 ``plugins.security.*`` の設定が 1 つでもある場合は ``plugins.security.disabled: true`` を追記しません。OpenSearch のディレクトリがすでにある場合はダウンロードを省略するため、既存のインストールに対して再実行すると、足りない設定だけが追記されます。 + +コマンドは追記した設定を表示し、続けて ``bin/fess.in.sh`` がこの OpenSearch を自動で見つけられるかどうかを表示します。 |Fess| のディレクトリの ``opensearch/`` の下で ``config/dictionary`` ディレクトリを持つ OpenSearch がこれ 1 つだけであれば見つけられます。このとき ``bin/fess.in.sh`` （Windows では ``bin\fess.in.bat`` ）が ``FESS_DICTIONARY_PATH`` をそのディレクトリに設定するため、同じホストで動かす OpenSearch であれば、ほかに設定は必要ありません。見つけられない場合は、設定すべき ``SEARCH_ENGINE_HTTP_URL`` と ``FESS_DICTIONARY_PATH`` の値を表示します。設定方法は :doc:`install-linux` または :doc:`install-windows` を参照してください。 + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - オプション + - 説明 + * - ``--dest `` + - OpenSearch の展開先を、 |Fess| のディレクトリの ``opensearch/`` の代わりに指定します。 ``bin/fess.in.sh`` は、このディレクトリの外にある OpenSearch を探しません。 + * - ``--version `` + - 導入する OpenSearch のバージョンです。プラグインも同じバージョンで導入されます。 + * - ``--keep-bundled-plugins`` + - 同梱プラグイン（ ``opensearch-security-analytics`` 、 ``opensearch-performance-analyzer`` ）を削除せず、配布物のまま残します。 + +OpenSearch の公式配布は Linux 向けと Windows 向けだけです。macOS などほかのプラットフォームでは、何もダウンロードせずに終了コード ``1`` で終了し、Homebrew で OpenSearch を導入して ``install opensearch-plugins`` でプラグインを入れる方法か、Docker を使う方法を案内します。 + +.. warning:: + + ``plugins.security.disabled: true`` を設定した OpenSearch は、認証なしでリクエストを受け付けます。OpenSearch は ``network.host`` を設定しない限りループバックアドレスでのみ待ち受けます。それ以外のアドレスで待ち受ける前に、代わりにセキュリティプラグインを設定してください。詳細は :doc:`security` を参照してください。 + +install opensearch-plugins +-------------------------- + +:: + + $ bin/fess-setup install opensearch-plugins --opensearch-home [--version ] + +すでにある OpenSearch に、 |Fess| が必要とする 4 つのプラグインを導入します。その OpenSearch の ``bin/opensearch-plugin install`` を 4 回実行する代わりに使えます。 ``--opensearch-home`` には OpenSearch のインストールディレクトリを指定します（必須）。 ``--version`` はプラグインのバージョンで、OpenSearch のバージョンと一致させる必要があります。 + +このコマンドは ``opensearch.yml`` を変更しません。 ``configsync.config_path`` などの設定は、 :doc:`install-linux` または :doc:`install-windows` に従って追加してください。 + +install nodejs +-------------- + +:: + + $ bin/fess-setup install nodejs [--dest ] [--version ] + +Playwright 系のプラグイン（Playwright クローラの ``fess-crawler-playwright`` とサムネイル生成の ``fess-thumbnail-playwright`` ）が必要とする Node.js を、 |Fess| のディレクトリの ``nodejs/`` にダウンロードします。 ``bin/fess.in.sh`` （Windows では ``bin\fess.in.bat`` ）がこれを見つけて ``PLAYWRIGHT_NODEJS_PATH`` を設定します。 ``--dest`` で |Fess| のディレクトリの外に展開した場合は、代わりに ``bin/fess.in.sh`` に追加する ``PLAYWRIGHT_NODEJS_PATH`` の行を表示します。 ``--version`` で別のバージョンの Node.js を指定できます。Playwright クローラについては :doc:`../config/crawler-advanced` を参照してください。 + +プラグインの管理 +================ + +以下のコマンドは、 |Fess| のプラグインディレクトリ ``app/WEB-INF/plugin`` を操作します。プラグインを導入、更新、削除した後は |Fess| を再起動してください。プラグインは管理画面の「システム > プラグイン」ページからも管理できます。 :doc:`../admin/plugin-guide` を参照してください。 + +``install plugin`` 、 ``list plugins`` 、 ``list installed`` 、 ``upgrade plugins`` 、 ``remove plugin`` 、 ``check`` には ``--dest `` を指定できます。 ``app/WEB-INF/plugin`` の代わりに使うプラグインディレクトリを指定します。指定するのはプラグインの jar が置かれるディレクトリそのもので、その親ディレクトリではありません。相対パスは |Fess| のディレクトリではなく、コマンドを実行したカレントディレクトリからの相対パスです。 ``install opensearch`` と ``install nodejs`` の ``--dest`` は、アーカイブを展開するディレクトリを指します。 + +``install plugin`` 、 ``list plugins`` 、 ``upgrade plugins`` には ``--repository `` を指定できます。指定すると、バージョンの一覧、jar、チェックサムをすべてその 1 つの Maven リポジトリ（社内のミラーなど）から取得し、既定のリリースリポジトリ、スナップショットリポジトリ、GitHub は使用しません。 + +``--repository`` には ``file:///`` で始まる URL も指定できます。インターネットに接続できないサーバーでは、Maven リポジトリのコピーをサーバー上に置き、そのディレクトリを指定します。指定するのは、各プラグインのディレクトリ（ ``/maven-metadata.xml`` など）を含むディレクトリで、既定のリポジトリの ``https://maven.codelibs.org/release/org/codelibs/fess/`` に当たる場所です。バージョンの解決とチェックサムの検証は、HTTP のリポジトリと同じように行われます。 + +:: + + $ bin/fess-setup install plugin fess-ds-csv --repository file:///opt/maven-repo/org/codelibs/fess/ + +``http`` 、 ``https`` 、 ``file`` 以外のスキームや、スキームのない URL は 1 行のエラーで拒否されます。 + +install plugin +-------------- + +:: + + $ bin/fess-setup install plugin [:]... [--version ] [--repository ] [--dest ] + +``fess-script-groovy`` や ``fess-ds-git`` などの |Fess| プラグインを 1 つ以上導入します。バージョンを付けない名前には、この |Fess| 向けにビルドされた最新のバージョンが導入されます。 ``:`` でそのプラグインのバージョンを固定でき、 ``--version`` はバージョンを付けなかった名前すべてに使われます。新しいバージョンの導入が完了した後に、同じプラグインの以前のバージョンが削除されます。 + +jar はプラグインの GitHub リリースから取得し、リリースに該当するファイルがない場合は Maven リポジトリから取得します。いずれも Maven リポジトリが公開している SHA-1 チェックサムで検証します。 |Fess| の開発版では、同じ系列のスナップショットビルドも導入対象になり、そちらが優先されます。 + +使用例は :doc:`../admin/plugin-guide` を参照してください。 + +導入できるのは、 |Fess| が読み込む種類のプラグイン（名前が ``fess-ds-`` 、 ``fess-ingest-`` 、 ``fess-script-`` 、 ``fess-webapp-`` 、 ``fess-thumbnail-`` 、 ``fess-crawler-`` 、 ``fess-llm-`` 、 ``fess-storage-`` 、 ``fess-sso-`` で始まるもの）だけです。 ``list plugins`` に表示されるものと同じです。それ以外の名前（ ``fess-theme-*`` 、 ``fess`` 、 ``fess-crawler`` などのライブラリ）を指定すると、何もダウンロードせずに 1 行のエラーを表示し、終了コード 2 で終了します。複数の名前のうち 1 つでも該当すると、どれも導入しません。静的テーマは ``install theme`` で導入してください。 + +list plugins +------------ + +:: + + $ bin/fess-setup list plugins [--repository ] [--dest ] + +この |Fess| 向けに公開されているプラグインを一覧表示し、導入済みのものには ``(installed: )`` を付けます。導入済みでもリポジトリに公開されていないプラグイン（ローカルでビルドした jar など）は、別に一覧表示します。 |Fess| の開発版では、スナップショットリポジトリも参照します。 + +list installed +-------------- + +:: + + $ bin/fess-setup list installed [--dest ] + +導入済みのプラグインとそのバージョンを、リポジトリに問い合わせずに一覧表示します。 + +upgrade plugins +--------------- + +:: + + $ bin/fess-setup upgrade plugins [--repository ] [--dest ] + +導入済みのすべてのプラグインを、この |Fess| に合うバージョンで導入し直します。すでにそのバージョンになっているプラグインはそのままです。 ``app/WEB-INF/plugin`` のプラグインは特定の |Fess| のリリース向けにビルドされているため、 |Fess| をアップグレードした後に実行してください。 + +remove plugin +------------- + +:: + + $ bin/fess-setup remove plugin ... [--dest ] + +指定したプラグインの jar を削除します。導入されていない名前はその旨を表示するだけで、終了コードには影響しません。 + +.. _fess-setup-offline: + +インターネットに接続できない環境 +-------------------------------- + +``install plugin`` 、 ``list plugins`` 、 ``upgrade plugins`` は、プラグインをインターネット上のリポジトリから取得します。管理画面の「システム > プラグイン」のインストール画面も、インストールできるプラグインの一覧をリポジトリ（ ``plugin.repositories`` ）から取得するため、外部に接続できない環境では一覧を表示できません。 + +このような環境では、プラグインの jar を持ち込んで導入します。 + +1. インターネットに接続できる環境で、 |Fess| の ZIP パッケージと、必要なプラグインの jar をダウンロードします。jar は ``https://maven.codelibs.org/release/org/codelibs/fess///-.jar`` から取得できます。この |Fess| に対応するバージョン（ |Fess| 15.10 なら 15.10.x）を選んでください。 +2. 対象の環境で ZIP を展開し、jar を ``app/WEB-INF/plugin/`` に置きます。 |Fess| の起動後に、管理画面のプラグインのインストール画面の「ローカル」タブからアップロードすることもできます（ :doc:`../admin/plugin-guide` を参照）。 +3. |Fess| を起動します。起動中に jar を置いた場合は再起動してください。 + +プラグインの jar を個別に持ち込む代わりに、Maven リポジトリの必要な部分（ ``org/codelibs/fess//`` のディレクトリ）をコピーして持ち込み、 ``--repository file:///...`` を指定して ``install plugin`` で導入することもできます。この場合も、チェックサムが検証されます。 + +テーマの管理 +============ + +これらのコマンドは |Fess| のインストールディレクトリの ``app/themes`` を対象とします。テーマをインストールまたは削除したあとは |Fess| を再起動するか、[システム > テーマ] ページの [再読み込み] をクリックしてください。テーマは同じページからアップロードすることもできます。 :doc:`../admin/theme-guide` を参照してください。 + +``install theme`` 、 ``list themes`` 、 ``remove theme`` にも同様に ``--dest `` を指定でき、 ``app/themes`` の代わりに使うテーマディレクトリを指定します。 + +テーマのバージョンは、そのテーマが対象とする |Fess| の系列を表します。つまり ``15.10.0`` は |Fess| 15.10 用のテーマです。そのためバージョンを付けずに名前だけを指定すると、プラグインの場合と同じように、この |Fess| 用に作られたテーマが選ばれます。 + +install theme +------------- + +:: + + $ bin/fess-setup install theme [:]... [--version ] [--repository ] [--dest ] + +``docuforge`` や ``voicebox`` などの静的テーマをインストールします。バージョンを付けない名前は、この |Fess| 用に作られた最新のものをインストールします。 ``:`` はそのテーマのバージョンを固定し、 ``--version`` は自分のバージョンを持たないすべての名前に適用されます。 + +アーカイブは Maven リポジトリが公開している SHA-1 チェックサムと照合され、 ``app/themes/`` に展開されます。同じ名前ですでにインストールされているテーマは、管理画面から置き換えた場合と同じ期間バックアップとして保持されます（既定 7 日、 ``theme.upload.attic.retention.days`` ）。 + +ダウンロード・展開・マニフェストの検査は、インストール済みのものに手を触れる前にすべて行われます。そのため、インストールに失敗してもすでにあるテーマはそのまま残ります。 ``theme.yml`` が別のテーマを名乗っているアーカイブは拒否されます。 + +list themes +----------- + +:: + + $ bin/fess-setup list themes [--repository ] [--dest ] + +この |Fess| 向けに公開されているテーマを一覧表示し、インストール済みのものには ``(installed: )`` を付けます。インストールされているがリポジトリの一覧に無いテーマは、別に表示されます。 + +この一覧はリポジトリのディレクトリ索引から読み取ります。索引は定期的に生成されるため、読み取れないことがあります。その場合は試みた URL を報告したうえで、インストール済みのテーマは引き続き表示します。索引に載っているかどうかにかかわらず、名前を指定すればテーマはインストールできます。 + +remove theme +------------ + +:: + + $ bin/fess-setup remove theme ... [--dest ] + +指定したテーマを ``app/themes`` から削除します。それぞれ保持期間のあいだバックアップとして残ります。インストールされていない名前は報告されますが、終了コードは変わりません。 + +削除したテーマがデフォルトテーマだった場合、別のテーマを選ぶまで |Fess| は同梱の ``bootstrap`` テーマにフォールバックします。 + +インストール状態の確認 +====================== + +list +---- + +:: + + $ bin/fess-setup list + +``install`` でダウンロードするコンポーネント（ ``opensearch`` と ``nodejs`` ）を、それぞれのバージョンとともに表示します。 + +check +----- + +:: + + $ bin/fess-setup check [--url ] [--playwright] [--dest ] + +インストール状態を診断し、確認項目ごとに ``OK`` 、 ``WARN`` 、 ``FAIL`` のいずれかを付けて 1 行ずつ表示します。 + +- 検索エンジン: 接続できるか、バージョン（ノード間でバージョンが異なる場合は警告）、 |Fess| が必要とする 4 つのプラグインが導入されているか、 ``configsync`` が応答するか +- |Fess| : プラグインディレクトリが存在して書き込めるか、導入済みの各プラグイン（別の |Fess| のリリース向けのものと、2 つのバージョンが導入されているものは失敗）、 |Fess| のディレクトリの ``nodejs/`` に Node.js が導入されているか + +検索エンジンの URL は ``--url`` 、指定がなければ環境変数 ``SEARCH_ENGINE_HTTP_URL`` 、それもなければ ``http://localhost:9200`` です。 ``bin/fess-setup`` は ``bin/fess.in.sh`` を読まないため、OpenSearch がほかの場所にある場合は ``--url`` を指定してください。Node.js がないことは報告されるだけですが、 ``--playwright`` を指定すると失敗として扱われます。 + +失敗した項目がなければ、警告があっても終了コード ``0`` で終了します。失敗した項目があれば終了コード ``1`` で終了します。 diff --git a/ja/15.10/install/index.rst b/ja/15.10/install/index.rst new file mode 100644 index 000000000..7ef32777c --- /dev/null +++ b/ja/15.10/install/index.rst @@ -0,0 +1,25 @@ +|Fess| インストールガイド +===================== + +Linux、Windows、Docker への |Fess| のインストールと起動の方法を、\ +動作要件、セキュリティ設定、アップグレード、トラブルシューティングと\ +あわせて説明します。 + +.. toctree:: + :maxdepth: 2 + :caption: 目次 + + intro + prerequisites + install + install-linux + install-windows + install-docker + fess-setup + run + security + upgrade + uninstall + troubleshooting + + diff --git a/ja/15.10/install/install-docker.rst b/ja/15.10/install/install-docker.rst new file mode 100644 index 000000000..d793610bb --- /dev/null +++ b/ja/15.10/install/install-docker.rst @@ -0,0 +1,608 @@ +============================== +Docker でのインストール (詳細) +============================== + +このページでは、Docker および Docker Compose を使用した |Fess| のインストール手順を説明します。 +Docker を使用することで、簡単かつ迅速に |Fess| 環境を構築できます。 + +前提条件 +======== + +- :doc:`prerequisites` に記載されているシステム要件を満たしていること +- Docker 20.10 以降がインストールされていること +- Docker Compose 2.0 以降がインストールされていること + +Docker のインストール確認 +========================= + +以下のコマンドで Docker および Docker Compose のバージョンを確認します。 + +:: + + $ docker --version + $ docker compose version + +.. note:: + + 古いバージョンの Docker Compose を使用している場合は、``docker-compose`` コマンドを使用します。 + 本ドキュメントでは、新しい ``docker compose`` コマンド形式を使用しています。 + +Docker イメージについて +======================= + +|Fess| を Docker Compose で起動すると、以下の 2 つのコンテナが動作します。 + +- **Fess** (``fess01``): 全文検索システム本体 +- **OpenSearch** (``search01``): 検索エンジン + +公式 Docker イメージは `GitHub Container Registry `__ で公開されています。 +Compose ファイルおよび起動手順は `docker-fess `__ リポジトリで管理されています。 + +ステップ 1: Docker Compose ファイルの取得 +========================================= + +Docker Compose を使用した起動には、以下のファイルが必要です。 + +方法 1: ファイルを個別にダウンロード +------------------------------------ + +以下のファイルをダウンロードします： + +:: + + $ mkdir fess-docker + $ cd fess-docker + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose.yaml + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose-opensearch3.yaml + +方法 2: Git でリポジトリをクローン +---------------------------------- + +Git がインストールされている場合は、リポジトリ全体をクローンすることもできます： + +:: + + $ git clone --depth 1 --branch v15.10.0 https://github.com/codelibs/docker-fess.git + $ cd docker-fess/compose + +ステップ 2: Docker Compose ファイルの確認 +========================================= + +``compose.yaml`` の内容 +----------------------- + +``compose.yaml`` には、Fess 本体（``fess01`` サービス）の設定が含まれています。 + +主な設定項目： + +- **ポート番号**: Fess の Web インターフェースのポート（デフォルト: 8080） +- **環境変数**: OpenSearch の接続先 (``SEARCH_ENGINE_HTTP_URL``) や辞書ファイルのパス (``FESS_DICTIONARY_PATH``) など +- **起動順序**: OpenSearch (``search01``) が正常な状態になってから起動するよう ``depends_on`` が設定されています + +``compose-opensearch3.yaml`` の内容 +----------------------------------- + +``compose-opensearch3.yaml`` には、検索エンジン（``search01`` サービス、OpenSearch）の設定が含まれています。 + +主な設定項目： + +- **OpenSearch イメージ**: 使用する OpenSearch イメージ（``ghcr.io/codelibs/fess-opensearch``） +- **メモリ設定**: JVM ヒープサイズ +- **ボリューム**: データ永続化用のボリューム（``search01_data``: インデックスデータ、``search01_dictionary``: 辞書ファイル） + +設定のカスタマイズ（オプション） +-------------------------------- + +デフォルトの設定を変更する場合は、``compose.yaml`` を編集します。 + +例：ポート番号を変更する場合:: + + services: + fess01: + ports: + - "9080:8080" # ホストの 9080 番ポートにマッピング + +例：メモリ設定を変更する場合:: + + services: + fess01: + environment: + - "FESS_HEAP_SIZE=2g" # Fess のヒープサイズを 2GB に設定 + +イメージの種類とサムネイル +-------------------------- + +|Fess| の Docker イメージには、タグの接尾辞（ ``-noble`` 、 ``-al2023`` など）が異なる複数の種類があります。接尾辞のない既定のイメージ（Alpine ベース）には、画像・PDF・Office 文書のサムネイルを作る外部ツール（ImageMagick、poppler-utils、unoconv と LibreOffice）が入っていません。このイメージでサムネイルを生成できるのは HTML ページだけで、画像・PDF・Office 文書のサムネイルは生成されません。 + +これらのサムネイルが必要な場合は、 ``compose.yaml`` の ``image`` に、ツールを含む ``-noble`` 付きのタグを指定します。 + +:: + + services: + fess01: + image: ghcr.io/codelibs/fess:15.10.0-noble + +イメージごとの対応は次のとおりです。 + +.. list-table:: + :header-rows: 1 + :widths: 40 30 30 + + * - タグ + - 画像・PDF + - Office 文書 + * - ``15.10.0-noble`` + - 生成される + - 生成される + * - ``15.10.0-al2023`` + - 生成される + - 生成されない + * - ``15.10.0`` 、 ``15.10.0-slim`` 、 ``15.10.0-slim-noble`` 、 ``15.10.0-slim-al2023`` + - 生成されない + - 生成されない + +HTML ページのサムネイルは、どのイメージでもページ内の画像から生成されます。サムネイルを表示するには、管理画面の全般設定でサムネイル表示も有効にしてください。詳しくは :doc:`../config/crawler-thumbnail` を参照してください。 + +ステップ 3: Docker コンテナの起動 +================================= + +基本的な起動 +------------ + +以下のコマンドで、Fess と OpenSearch を起動します： + +:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +.. note:: + + - ``-f`` オプションで複数の Compose ファイルを指定します + - ``-d`` オプションでバックグラウンドで実行します + +起動ログの確認:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f + +``Ctrl+C`` でログ表示を終了できます。 + +起動の確認 +---------- + +コンテナの状態を確認します:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps + +以下のようなコンテナが起動していることを確認してください： + +- ``fess01`` +- ``search01`` + +.. tip:: + + 起動には数分かかる場合があります。まず OpenSearch (``search01``) が正常な状態になってから Fess (``fess01``) が起動します。 + ``docker compose ... ps`` で各コンテナの状態を確認し、``fess01`` が起動したらブラウザーで http://localhost:8080/ にアクセスできます。 + +ステップ 4: ブラウザーでアクセス +================================ + +起動が完了したら、以下の URL にアクセスします： + +- **検索画面**: http://localhost:8080/ +- **管理画面**: http://localhost:8080/admin + +検索画面は |Fess| に同梱の静的テーマ ``bootstrap`` です。見た目の変え方は :doc:`../admin/theme-guide` を +参照してください。 + +デフォルトの管理者アカウント： + +- ユーザー名: ``admin`` +- パスワード: ``admin`` + +.. warning:: + + **セキュリティに関する重要な注意** + + 本番環境では、管理者パスワードを必ず変更してください。 + 詳細は :doc:`security` を参照してください。 + +AI検索モード（LLMプラグイン）の有効化 +===================================== + +|Fess| 15.10 から、AI検索モード（RAG Chat）機能は ``fess-llm-*`` プラグインとして分離されました。 +公式の `docker-fess `__ リポジトリには、主要な LLM プロバイダー向けのオーバーレイファイルが同梱されています。 + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - オーバーレイ + - 用途 + * - ``compose-ollama.yaml`` + - Ollama（ローカル LLM、追加の ``ollama01`` サービスを起動） + * - ``compose-gemini.yaml`` + - Google Gemini（クラウド API） + * - ``compose-openai.yaml`` + - OpenAI（クラウド API） + +各オーバーレイは ``FESS_PLUGINS`` で対応するプラグインを自動取得し、``FESS_JAVA_OPTS`` に +``-Dfess.config.rag.chat.enabled=true`` を設定して RAG Chat を有効化します。 +クラウド API を利用する Gemini と OpenAI では、さらに ``-Dfess.system.rag.llm.name`` で使用するプロバイダーを指定し、 +API キー (``rag.llm..api.key``) とモデル (``rag.llm..model``) を設定します。 +Ollama では ``rag.llm.name`` の既定値 (``ollama``) がそのまま使われるため明示的な指定はなく、 +接続先 (``rag.llm.ollama.api.url``) が設定されます。 + +Gemini を使う例:: + + $ export GEMINI_API_KEY="AIzaSy..." + $ docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-gemini.yaml up -d + +OpenAI を使う例:: + + $ export OPENAI_API_KEY="sk-..." + $ docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-openai.yaml up -d + +.. note:: + + 使用するモデルは、``GEMINI_MODEL`` および ``OPENAI_MODEL`` 環境変数で変更できます + （既定値はそれぞれ ``gemini-2.5-flash`` と ``gpt-5-mini`` です）。 + +Ollama を使う例:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-ollama.yaml up -d + $ docker exec -it ollama01 ollama pull gpt-oss:20b + +.. warning:: + + ``compose-ollama.yaml`` の ``ollama01`` サービスは、既定で NVIDIA GPU を使用するように定義されています + （`NVIDIA Container Toolkit `__ が必要です）。 + GPU が搭載されていない環境で実行する場合は、``compose-ollama.yaml`` の ``deploy:`` ブロック（``reservations`` 配下の GPU 指定）を削除またはコメントアウトしてください。 + +.. tip:: + + 起動後、管理画面「システム > 全般」の設定画面で、使用する LLM プロバイダー (``rag.llm.name``) や + 各プロバイダー固有の設定を変更できます。ただし、これらの変更はコンテナ内の設定ファイルに保存されるため、 + コンテナを再作成（``docker compose down`` 後に ``up``）すると失われます。 + 設定を永続化するには、上記の例のように Compose ファイルの ``FESS_JAVA_OPTS`` で指定してください。 + +データの永続化 +============== + +|Fess| のデータ（インデックス、クロールしたドキュメント、ユーザー情報、設定など）は、すべて OpenSearch に保存されます。 +これらのデータは OpenSearch のボリュームに永続化されるため、コンテナを削除してもデータは保持されます。 +Fess 本体（``fess01``）のコンテナ自体は状態を持たず、専用のボリュームはありません。 + +ボリュームの確認:: + + $ docker volume ls + +``compose-opensearch3.yaml`` で定義される主なボリューム： + +- ``search01_data``: OpenSearch のインデックスデータ（Fess の全データを含む） +- ``search01_dictionary``: 辞書ファイル + +.. note:: + + Docker Compose のボリューム名には、プロジェクト名（既定では Compose ファイルのあるディレクトリ名）が接頭辞として付きます。 + たとえば ``compose`` ディレクトリで起動した場合、実際のボリューム名は ``compose_search01_data`` のようになります。 + +.. important:: + + コンテナを削除してもボリュームは削除されません。 + ボリュームを削除するには、明示的に ``docker volume rm`` コマンドを実行する必要があります。 + +Docker コンテナの停止 +===================== + +コンテナを停止する:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop + +コンテナを停止して削除する:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +.. warning:: + + ``down`` コマンドはコンテナを削除しますが、ボリュームは削除しません。 + ボリューム（``search01_data`` など）も削除する場合は ``-v`` オプションを追加します:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down -v + + **注意**: このコマンドを実行すると、OpenSearch に保存されたすべてのデータが削除されます。 + +高度な設定 +========== + +環境変数のカスタマイズ +---------------------- + +``compose.yaml`` で環境変数を追加・変更することで、詳細な設定が可能です。 + +主な環境変数： + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - 環境変数 + - 説明 + * - ``FESS_HEAP_SIZE`` + - Fess の JVM ヒープサイズ（Docker イメージの既定値: 512m） + * - ``FESS_JAVA_OPTS`` + - 追加の JVM オプションの指定（``-Dfess.config.*`` による設定の上書きなど） + * - ``FESS_PLUGINS`` + - 起動時に自動インストールするプラグイン（スペース区切りの ``name:version`` 形式。例: ``fess-ds-wikipedia:15.10.0``） + * - ``SEARCH_ENGINE_HTTP_URL`` + - OpenSearch の HTTP エンドポイント（``compose.yaml`` の既定値: ``http://search01:9200``） + * - ``SEARCH_ENGINE_TYPE`` + - 検索エンジンの種別（ ``default`` 、 ``vanilla`` 、 ``aws`` ）。 ``vanilla`` は Fess 15.10 以降のイメージで指定できます。それより前のイメージでは ``cloud`` を指定します（ :doc:`../config/search-engine-type` を参照）。15.8 のイメージでは、 ``-noble`` 版だけがこの値を Fess に渡します。 + * - ``SEARCH_ENGINE_USERNAME`` / ``SEARCH_ENGINE_PASSWORD`` + - 認証が有効な OpenSearch に接続する際の資格情報 + * - ``FESS_DICTIONARY_PATH`` + - 辞書ファイルのパス（OpenSearch と共有するディレクトリ） + * - ``FESS_PORT`` + - Fess がコンテナ内で待ち受けるポート（既定値: 8080） + +例:: + + services: + fess01: + environment: + - "FESS_HEAP_SIZE=4g" + +.. note:: + + タイムゾーンを変更する場合は、``FESS_JAVA_OPTS`` に ``-Duser.timezone=Asia/Tokyo`` のように指定します。 + +設定ファイルの反映方法 +---------------------- + +|Fess| の詳細な設定は ``fess_config.properties`` ファイルに記述します。 +Docker イメージでは、``fess_config.properties`` はコンテナ内の ``/etc/fess`` に配置されています。 +Docker 環境で設定を反映させるには、以下の方法があります。 + +方法 1: 設定ファイルのマウント +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``/etc/fess`` には Fess の動作に必要な他の設定ファイルも含まれるため、このディレクトリをそのままマウントで置き換えると起動に失敗します。 +代わりに、クラスパスの先頭に追加されるオーバーライド用ディレクトリ ``/opt/fess`` を使用します（初期状態は空です）。 + +1. ホスト側に設定ファイルを用意するためのディレクトリを作成:: + + $ mkdir -p /path/to/fess-config + +2. 設定ファイルのテンプレートを取得（初回のみ）:: + + $ curl -o /path/to/fess-config/fess_config.properties https://raw.githubusercontent.com/codelibs/fess/refs/tags/fess-15.10.0/src/main/resources/fess_config.properties + +3. ``/path/to/fess-config/fess_config.properties`` を編集して必要な設定を記述:: + + # 例 + crawler.document.cache.enabled=false + adaptive.load.control=20 + query.facet.fields=label,host + +4. ``compose.yaml`` の ``fess01`` サービスにボリュームマウントを追加:: + + services: + fess01: + volumes: + - /path/to/fess-config/fess_config.properties:/opt/fess/fess_config.properties + +5. コンテナを起動:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +.. note:: + + ``/opt/fess`` はクラスパスの先頭に追加されるため、ここに置いた ``fess_config.properties`` が + イメージ同梱の ``/etc/fess/fess_config.properties`` よりも優先されます。 + プロパティファイルはファイル単位で読み込まれ、項目ごとにマージされません。 + ファイルに書かれていない項目はエラーにならず、その版の |Fess| に同梱された既定値が使われ、項目ごとに警告が 1 件ログに出力されます。 + そのため、変更したい項目だけを書いたファイルでも動作します。警告を避けるには、手順 2 のように完全なファイルから始めてください。 + 一部の項目のみを変更したい場合は、次の「方法 2」を利用してください。 + 同じ項目をこのファイルと「方法 2」の ``-Dfess.config.`` の両方で指定した場合は、``-D`` で指定した値が使われます。 + +方法 2: システムプロパティによる設定 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``fess_config.properties`` の設定項目を、環境変数経由でシステムプロパティとして上書きできます。 + +``fess_config.properties`` に記載される設定項目（例: ``crawler.document.cache.enabled=false``）を、 +``-Dfess.config.設定項目名=値`` の形式で指定します。 + +``compose.yaml`` の ``fess01`` サービスの環境変数に ``FESS_JAVA_OPTS`` を追加:: + + services: + fess01: + environment: + - "FESS_JAVA_OPTS=-Dfess.config.crawler.document.cache.enabled=false -Dfess.config.adaptive.load.control=20 -Dfess.config.query.facet.fields=label,host" + +.. note:: + + ``-Dfess.config.`` の後に続く部分が ``fess_config.properties`` の設定項目名に対応します。 + 一部の項目のみを上書きする場合は、こちらの方法が簡単です。 + +外部の OpenSearch への接続 +-------------------------- + +既存の OpenSearch クラスターを使用する場合は、``compose-opensearch3.yaml`` を使わずに ``compose.yaml`` のみで起動し、接続先を変更します。 + +1. ``compose-opensearch3.yaml`` を指定せずに起動:: + + $ docker compose -f compose.yaml up -d + +2. ``compose.yaml`` の ``fess01`` サービスで接続先を設定:: + + environment: + - "SEARCH_ENGINE_HTTP_URL=http://your-opensearch-host:9200" + +.. note:: + + 認証が有効な OpenSearch に接続する場合は、``SEARCH_ENGINE_USERNAME`` と ``SEARCH_ENGINE_PASSWORD`` も指定します。 + +その他のオーバーレイと構成 +-------------------------- + +``docker-fess`` リポジトリには、上記以外にも用途別の Compose ファイルやディレクトリが含まれています。 + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - ファイル / ディレクトリ + - 用途 + * - ``compose-dashboards3.yaml`` + - OpenSearch Dashboards を追加（ポート 5601、データ可視化用） + * - ``compose-minio.yaml`` + - MinIO（オブジェクトストレージ）を追加し、Fess のストレージ機能の保存先として利用 + * - ``vanilla/`` + - CodeLibs のプラグインを含まない素の OpenSearch と組み合わせる構成（ ``SEARCH_ENGINE_TYPE=vanilla`` 。Fess 15.10 以降のイメージで指定でき、それより前のイメージでは ``cloud`` を指定します）。辞書管理などの一部機能は利用できません（ :doc:`../config/search-engine-type` を参照） + * - ``snapshot/`` + - 開発版（snapshot）イメージを使用する構成（クラスター構成や Elasticsearch 8 との組み合わせを含む） + * - ``multi-instance/`` + - 1 つの OpenSearch を共有する複数の Fess インスタンスを起動する構成 + +Docker ネットワークの設定 +------------------------- + +複数のサービスと連携する場合、カスタムネットワークを使用できます。 + +例:: + + networks: + fess-network: + driver: bridge + + services: + fess01: + networks: + - fess-network + +Docker Compose での本番運用 +=========================== + +本番環境で Docker Compose を使用する場合の推奨設定： + +1. **リソース制限の設定**:: + + deploy: + resources: + limits: + cpus: '2.0' + memory: 4G + reservations: + cpus: '1.0' + memory: 2G + +2. **再起動ポリシーの設定**:: + + restart: unless-stopped + +3. **ログの設定**:: + + logging: + driver: "json-file" + options: + max-size: "10m" + max-file: "3" + +4. **セキュリティ設定の有効化** + + OpenSearch のセキュリティプラグインを有効にし、適切な認証を設定します。 + 詳細は :doc:`security` を参照してください。 + +トラブルシューティング +====================== + +コンテナが起動しない +-------------------- + +1. ログを確認:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs + +2. ポート番号の競合を確認:: + + $ sudo ss -tuln | grep 8080 + $ sudo ss -tuln | grep 9200 + +3. ディスク容量を確認:: + + $ df -h + +メモリ不足エラー +---------------- + +OpenSearch がメモリ不足で起動しない場合、``vm.max_map_count`` を増やす必要があります。 + +Linux の場合:: + + $ sudo sysctl -w vm.max_map_count=262144 + +永続的に設定する場合:: + + $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf + $ sudo sysctl -p + +データの初期化 +-------------- + +すべてのデータを削除して初期状態に戻す:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down -v + $ docker volume prune + +.. warning:: + + このコマンドを実行すると、すべてのデータが完全に削除されます。 + +次のステップ +============ + +インストールが完了したら、以下のドキュメントを参照してください： + +- :doc:`run` - |Fess| の起動と初回セットアップ +- :doc:`security` - 本番環境でのセキュリティ設定 +- :doc:`troubleshooting` - トラブルシューティング + +よくある質問 +============ + +Q: イメージのダウンロードにはどのくらいのディスク容量が必要ですか？ +-------------------------------------------------------------------- + +A: Fess と OpenSearch のイメージは初回起動時にダウンロードされ、あわせて数 GB 程度のディスク容量が必要です。 +ネットワーク環境によってはダウンロードに時間がかかる場合があります。 + +Q: Kubernetes での運用は可能ですか？ +------------------------------------ + +A: 可能です。Docker Compose ファイルを ``kompose`` などのツールで Kubernetes マニフェストに変換するか、 +独自のマニフェストを作成して運用できます（公式の Helm チャートは提供されていません）。 + +Q: コンテナのアップデートはどのように行いますか？ +-------------------------------------------------- + +A: 以下の手順でアップデートします： + +1. 最新の Compose ファイルを取得 +2. コンテナを停止:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +3. 新しいイメージを取得:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull + +4. コンテナを起動:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +Q: マルチノード構成は可能ですか？ +---------------------------------- + +A: 可能です。\ ``docker-fess`` リポジトリの ``snapshot/compose-cluster.yaml`` を参考に OpenSearch を複数ノードで構成したり、 +``multi-instance/`` を参考に 1 つの OpenSearch を共有する複数の Fess インスタンスを構成したりできます。 +ただし、本番環境では Kubernetes などのオーケストレーションツールの使用を推奨します。 diff --git a/ja/15.10/install/install-linux.rst b/ja/15.10/install/install-linux.rst new file mode 100644 index 000000000..4411ca913 --- /dev/null +++ b/ja/15.10/install/install-linux.rst @@ -0,0 +1,546 @@ +================================== +Linux へのインストール (詳細手順) +================================== + +このページでは、Linux 環境への |Fess| のインストール手順を説明します。 +ZIP、RPM、DEB の各パッケージ形式に対応しています。 + +.. note:: + + |Fess| は検索エンジンを同梱していません。OpenSearch サーバーを別途用意する必要があり、 + 以下の手順で構築します。 + +前提条件 +======== + +- :doc:`prerequisites` に記載されているシステム要件を満たしていること +- Java 21 がインストールされていること +- OpenSearch 3.9.0 を利用可能な状態にすること（または新規インストール） + +インストール方法の選択 +====================== + +Linux 環境では、以下のインストール方法から選択できます： + +.. list-table:: + :header-rows: 1 + :widths: 20 40 40 + + * - 方式 + - 推奨環境 + - 特徴 + * - ZIP + - 開発環境、カスタマイズが必要な環境 + - 任意のディレクトリに展開可能 + * - RPM + - RHEL、CentOS、Fedora 系 + - systemd によるサービス管理が可能 + * - DEB + - Debian、Ubuntu 系 + - systemd によるサービス管理が可能 + +OpenSearch 実行のためのシステム設定 +=================================== + +OpenSearch を Linux 上で安定して動作させるには、以下のカーネルパラメーターおよびリソース制限を設定します。 +これらは主に TAR.GZ 版（OpenSearch を手動でインストールする場合）で必要です。 +RPM / DEB 版では OpenSearch および |Fess| のパッケージが systemd 経由でファイルディスクリプター数などを設定しますが、``vm.max_map_count`` はホスト側のカーネル設定のため、いずれの方式でも確認してください。 + +仮想メモリーの最大マップ数 +-------------------------- + +OpenSearch は多数のメモリーマップを使用するため、``vm.max_map_count`` を ``262144`` 以上に設定します。 + +一時的に設定する場合:: + + $ sudo sysctl -w vm.max_map_count=262144 + +永続的に設定する場合:: + + $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf + $ sudo sysctl -p + +ファイルディスクリプター数 +-------------------------- + +OpenSearch を手動で実行する場合（TAR.GZ 版）は、OpenSearch を実行するユーザーのファイルディスクリプター数の上限を ``65535`` 以上に設定します。 + +``/etc/security/limits.conf`` に以下を追加します（``opensearch`` は OpenSearch を実行するユーザー名に置き換えてください）:: + + opensearch - nofile 65535 + +.. note:: + + RPM / DEB 版では、systemd のサービス定義でファイルディスクリプター数の上限が設定されるため、この設定は不要です。 + +ZIP 版でのインストール +========================= + +ステップ 1: OpenSearch のインストール +------------------------------------- + +.. important:: + + OpenSearch は ``root`` では起動できないため、一般ユーザーで導入して実行してください。以下の ``bin/fess-setup`` も同じユーザーで実行し、展開されるファイルの所有者をそのユーザーにしてください。 ``root`` での起動がすでに拒否された場合は、 :doc:`run` を参照してください。 + +.. tip:: + + |Fess| に同梱の ``bin/fess-setup`` で、以下の手順 1〜3 をまとめて実行できます。OpenSearch を |Fess| のディレクトリの ``opensearch/`` に取得・展開し、必要なプラグインを導入したうえで、その ``config/opensearch.yml`` に ``configsync.config_path`` と ``plugins.security.disabled: true`` を追加します。先にステップ 2 のとおり |Fess| の ZIP を展開しておいてください。 + + :: + + $ cd /path/to/fess-15.10.0 + $ bin/fess-setup install opensearch + + この方法で導入した OpenSearch は ``bin/fess.in.sh`` が見つけて ``FESS_DICTIONARY_PATH`` を自動で設定するため、OpenSearch を同じホストで動かす限り、ステップ 2 の「Fess の設定」で変更は必要ありません。コマンドは、追加した設定と、 ``bin/fess.in.sh`` がこのインストールを見つけられるかどうかを表示します。OpenSearch を ``localhost`` 以外のアドレスで待ち受けさせる前に、手順 3 の警告を確認してください。 + + 手順を個別に確認したい場合や、既存の OpenSearch を使う場合は、以下に従ってください。 + 既存の OpenSearch にプラグインだけを入れる場合は + ``bin/fess-setup install opensearch-plugins --opensearch-home /path/to/opensearch`` を使用します。 + すべてのコマンドについては :doc:`fess-setup` を参照してください。 + +.. note:: + + OpenSearch には macOS 向けの公式配布がないため、macOS では ``bin/fess-setup install opensearch`` はエラーで終了します。Homebrew で OpenSearch を導入して ``bin/fess-setup install opensearch-plugins`` でプラグインを入れるか、代わりに :doc:`install-docker` を使用してください:: + + $ brew install opensearch + $ bin/fess-setup install opensearch-plugins --opensearch-home $(brew --prefix opensearch) + + そのうえで、手順 3 のとおりに OpenSearch を設定し、ステップ 2 の「Fess の設定」のとおりに ``FESS_DICTIONARY_PATH`` を設定してください。 + +1. OpenSearch のダウンロード + + `Download OpenSearch `__ から TAR.GZ 版をダウンロードします。 + + :: + + $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.9.0/opensearch-3.9.0-linux-x64.tar.gz + $ tar -xzf opensearch-3.9.0-linux-x64.tar.gz + $ cd opensearch-3.9.0 + + arm64（aarch64）のマシンでは、上のファイル名の ``linux-x64`` を ``linux-arm64`` に置き換えてください（例: ``opensearch-3.9.0-linux-arm64.tar.gz``）。 + + .. note:: + + この例では OpenSearch 3.9.0 を使用しています。 + |Fess| 15.10 は OpenSearch 3.9.0 に対応しています。 + +2. OpenSearch プラグインのインストール + + |Fess| が必要とするプラグインをインストールします。 + + :: + + $ cd /path/to/opensearch-3.9.0 + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + + .. important:: + + プラグインのバージョンは OpenSearch のバージョンと一致させる必要があります。 + 上記の例では、すべて 3.9.0 を指定しています。 + + |Fess| 用の 4 つのプラグインは maven.codelibs.org で公開しているため、URL で指定します。 ``opensearch-plugin install`` の ``groupId:artifactId:version`` 形式は Maven Central だけを参照します。 + +3. OpenSearch の設定 + + ``config/opensearch.yml`` に以下の設定を追加します。 + + :: + + # 設定同期用のパス（絶対パスで指定） + configsync.config_path: /path/to/opensearch-3.9.0/config/dictionary/ + + # セキュリティプラグインの無効化（開発環境のみ） + plugins.security.disabled: true + + .. important:: + + ``configsync.config_path`` には、OpenSearch の設定ディレクトリ（この例では ``/path/to/opensearch-3.9.0/config/``）の下のディレクトリを指定してください。 + OpenSearch 3.8.0 以降は、辞書ファイルが設定ディレクトリの外にあるとインデックスの作成を拒否します。 + ``/path/to/opensearch-3.9.0/data/config/`` など設定ディレクトリの外を指定すると、 |Fess| はインデックスを作成できず、起動しません。 + + .. warning:: + + **セキュリティに関する重要な注意** + + ``plugins.security.disabled: true`` は、開発環境やテスト環境でのみ使用してください。 + 本番環境では、OpenSearch のセキュリティプラグインを有効にし、適切な認証・認可設定を行ってください。 + OpenSearch 2.12 以降でセキュリティプラグインを有効にする場合は、初回起動時に管理者パスワード（環境変数 ``OPENSEARCH_INITIAL_ADMIN_PASSWORD``）の設定が必要です。 + 詳細は :doc:`security` を参照してください。 + + .. tip:: + + クラスター名やネットワーク設定など、その他の設定は環境に応じて調整してください。 + 設定例:: + + cluster.name: fess-cluster + node.name: fess-node-1 + network.host: 0.0.0.0 + discovery.type: single-node + + .. tip:: + + OpenSearch のヒープサイズは ``config/jvm.options`` の ``-Xms`` / ``-Xmx`` で設定します。 + 利用可能な物理メモリの半分以下、かつ 32GB 未満を目安に、``-Xms`` と ``-Xmx`` には同じ値を指定することを推奨します。 + +ステップ 2: Fess のインストール +------------------------------- + +1. Fess のダウンロードと展開 + + `ダウンロードサイト `__ から ZIP 版をダウンロードします。 + + :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.zip + $ unzip fess-15.10.0.zip + $ cd fess-15.10.0 + + .. note:: + + パスに空白文字が含まれないディレクトリを選択してください（macOS でも同様です）。パスに空白文字が含まれると、``bin/fess`` は起動せず ``Could not find or load main class`` と表示されます。 + +2. Fess の設定 + + OpenSearch への接続情報は ``bin/fess.in.sh`` にあります。 ``bin/fess-setup install opensearch`` で |Fess| のディレクトリの ``opensearch/`` に導入し、同じホストで動かしている OpenSearch であれば、このファイルを変更する必要はありません。 ``SEARCH_ENGINE_HTTP_URL`` の既定値は ``http://localhost:9200`` で、 ``FESS_DICTIONARY_PATH`` にはその OpenSearch の ``config/dictionary`` ディレクトリが設定されます。 + + 次のいずれかに当てはまる場合は、 ``bin/fess.in.sh`` を編集します。 + + - OpenSearch を上記の手順 1〜3 や Homebrew など別の方法で導入した場合、または ``--dest`` で |Fess| のディレクトリの外に導入した場合 + - |Fess| のディレクトリの ``opensearch/`` に、 ``bin/fess-setup`` で導入した OpenSearch が 2 つ以上ある場合（2 つのバージョンなど）。 ``bin/fess.in.sh`` はどれを使うか判断できないため、警告を表示して ``FESS_DICTIONARY_PATH`` を設定しません + - OpenSearch を別のホストやポートで実行している場合 + + :: + + $ vi bin/fess.in.sh + + ファイルの先頭付近にある ``FESS_DICTIONARY_PATH`` の行のコメント（先頭の ``#``）を解除してパスを設定し、必要に応じて ``SEARCH_ENGINE_HTTP_URL`` の行の URL を変更します。 + + 変更前（既定の状態、コメント行は省略）:: + + SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://localhost:9200} + #FESS_DICTIONARY_PATH=/var/lib/opensearch/config/ + + 変更後:: + + SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://localhost:9200} + FESS_DICTIONARY_PATH=/path/to/opensearch-3.9.0/config/dictionary/ + + .. note:: + + - ``FESS_DICTIONARY_PATH`` には、OpenSearch の ``opensearch.yml`` で指定した ``configsync.config_path`` と同じパスを設定してください。設定しないと、 |Fess| はインデックスを作成できず、起動しません。 + - OpenSearch を別のホストで実行している場合は、 ``SEARCH_ENGINE_HTTP_URL`` の行の URL をそのホストに変更してください。例: ``SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://192.168.1.100:9200}`` 。このとき ``FESS_DICTIONARY_PATH`` には、そのサーバーの ``configsync.config_path`` を設定します。 + - ファイルを編集する代わりに、 |Fess| を起動する環境で両方の変数を export することもできます。export した ``SEARCH_ENGINE_HTTP_URL`` はファイルの URL より優先され、export した ``FESS_DICTIONARY_PATH`` はファイルの行がコメントのままであれば使用されます。 + - 新たに ``SEARCH_ENGINE_HTTP_URL=...`` の行を追加するのではなく、既存の行を編集してください。 + + .. tip:: + + |Fess| のヒープサイズを変更するには、``bin/fess.in.sh`` の ``FESS_MIN_MEM`` (既定: ``256m``) と ``FESS_MAX_MEM`` (既定: ``2g``) を編集するか、環境変数 ``FESS_HEAP_SIZE`` を設定します。 + +3. インストールの確認 + + 設定ファイルが正しく編集されたことを確認します:: + + $ grep "SEARCH_ENGINE_HTTP_URL" bin/fess.in.sh + $ grep "FESS_DICTIONARY_PATH" bin/fess.in.sh + + OpenSearch の起動後は、 ``bin/fess-setup check`` で、OpenSearch に接続できるか、 |Fess| が必要とするプラグインが導入されているか、 ``configsync`` が応答するかを確認できます。失敗した項目がなければ終了コード ``0`` で終了します。OpenSearch が ``http://localhost:9200`` にない場合は ``--url`` を指定してください。 + +ステップ 3: 起動 +---------------- + +起動手順については、:doc:`run` を参照してください。 + +RPM 版でのインストール +====================== + +RPM 版は、Red Hat Enterprise Linux、CentOS、Fedora などの RPM ベースの Linux ディストリビューションで使用します。 + +ステップ 1: OpenSearch のインストール +------------------------------------- + +1. OpenSearch RPM のダウンロードとインストール + + `Download OpenSearch `__ から RPM パッケージをダウンロードしてインストールします。 + + :: + + $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.9.0/opensearch-3.9.0-linux-x64.rpm + $ sudo rpm -ivh opensearch-3.9.0-linux-x64.rpm + + arm64（aarch64）のマシンでは、上のファイル名の ``linux-x64`` を ``linux-arm64`` に置き換えてください（例: ``opensearch-3.9.0-linux-arm64.rpm``）。 + + または、リポジトリを追加してインストールすることもできます。 + 詳細は `Installing OpenSearch `__ を参照してください。 + +2. OpenSearch プラグインのインストール + + :: + + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + +3. OpenSearch の設定 + + ``/etc/opensearch/opensearch.yml`` に以下の設定を追加します。 + + :: + + $ sudo vi /etc/opensearch/opensearch.yml + + 追加する設定:: + + configsync.config_path: /etc/opensearch/dictionary/ + plugins.security.disabled: true + + 辞書ファイル用のディレクトリを作成します:: + + $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary + + .. important:: + + ``configsync.config_path`` には、OpenSearch の設定ディレクトリ ``/etc/opensearch/`` の下のディレクトリを指定してください。 + OpenSearch 3.8.0 以降は、辞書ファイルが設定ディレクトリの外にあるとインデックスの作成を拒否します。 + ``/var/lib/opensearch/data/config/`` など設定ディレクトリの外を指定すると、 |Fess| はインデックスを作成できず、起動しません。 + + .. warning:: + + 本番環境では ``plugins.security.disabled: true`` を使用しないでください。 + :doc:`security` を参照して、適切なセキュリティ設定を行ってください。 + +ステップ 2: Fess のインストール +------------------------------- + +1. Fess RPM のインストール + + `ダウンロードサイト `__ から RPM パッケージをダウンロードしてインストールします。 + + :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.rpm + $ sudo rpm -ivh fess-15.10.0.rpm + +2. Fess の設定 + + RPM 版では、環境変数の設定ファイル ``/etc/sysconfig/fess`` を編集します。 + このファイルはパッケージのアップグレード時も保持されます（``/usr/share/fess/bin/fess.in.sh`` はアップグレード時に上書きされるため、直接編集しないでください）。 + + :: + + $ sudo vi /etc/sysconfig/fess + + OpenSearch への接続情報を設定します。 ``FESS_DICTIONARY_PATH`` の既定値 ``/var/lib/opensearch/config/`` は手順 3 の ``configsync.config_path`` と異なるため、次のように変更します。 ``SEARCH_ENGINE_HTTP_URL`` は必要に応じて変更してください:: + + SEARCH_ENGINE_HTTP_URL=http://localhost:9200 + FESS_DICTIONARY_PATH=/etc/opensearch/dictionary/ + + .. note:: + + ``FESS_DICTIONARY_PATH`` は、``opensearch.yml`` の ``configsync.config_path`` と同じパスを指定してください。 + +3. サービスの登録と有効化 + + systemd を使用してサービスを有効化します（RHEL 8 以降、CentOS 8 以降では systemd が標準です）:: + + $ sudo systemctl daemon-reload + $ sudo systemctl enable opensearch.service + $ sudo systemctl enable fess.service + + .. note:: + + |Fess| のサービスは OpenSearch のサービスに依存しているため、OpenSearch を先に起動する必要があります。 + + .. note:: + + systemd を使用しない従来の環境では、``chkconfig`` で |Fess| を登録できます:: + + $ sudo /sbin/chkconfig --add fess + +ステップ 3: 起動 +---------------- + +起動手順については、:doc:`run` を参照してください。 + +DEB 版でのインストール +====================== + +DEB 版は、Debian、Ubuntu などの DEB ベースの Linux ディストリビューションで使用します。 + +ステップ 1: OpenSearch のインストール +------------------------------------- + +1. OpenSearch DEB のダウンロードとインストール + + `Download OpenSearch `__ から DEB パッケージをダウンロードしてインストールします。 + + :: + + $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.9.0/opensearch-3.9.0-linux-x64.deb + $ sudo dpkg -i opensearch-3.9.0-linux-x64.deb + + arm64（aarch64）のマシンでは、上のファイル名の ``linux-x64`` を ``linux-arm64`` に置き換えてください（例: ``opensearch-3.9.0-linux-arm64.deb``）。 + + または、リポジトリを追加してインストールすることもできます。 + 詳細は `Installing OpenSearch `__ を参照してください。 + +2. OpenSearch プラグインのインストール + + :: + + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + +3. OpenSearch の設定 + + ``/etc/opensearch/opensearch.yml`` に以下の設定を追加します。 + + :: + + $ sudo vi /etc/opensearch/opensearch.yml + + 追加する設定:: + + configsync.config_path: /etc/opensearch/dictionary/ + plugins.security.disabled: true + + 辞書ファイル用のディレクトリを作成します:: + + $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary + + .. important:: + + ``configsync.config_path`` には、OpenSearch の設定ディレクトリ ``/etc/opensearch/`` の下のディレクトリを指定してください。 + OpenSearch 3.8.0 以降は、辞書ファイルが設定ディレクトリの外にあるとインデックスの作成を拒否します。 + ``/var/lib/opensearch/data/config/`` など設定ディレクトリの外を指定すると、 |Fess| はインデックスを作成できず、起動しません。 + + .. warning:: + + 本番環境では ``plugins.security.disabled: true`` を使用しないでください。 + :doc:`security` を参照して、適切なセキュリティ設定を行ってください。 + +ステップ 2: Fess のインストール +------------------------------- + +1. Fess DEB のインストール + + `ダウンロードサイト `__ から DEB パッケージをダウンロードしてインストールします。 + + :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.deb + $ sudo dpkg -i fess-15.10.0.deb + +2. Fess の設定 + + DEB 版では、環境変数の設定ファイル ``/etc/default/fess`` を編集します。 + このファイルはパッケージのアップグレード時も保持されます（``/usr/share/fess/bin/fess.in.sh`` はアップグレード時に上書きされるため、直接編集しないでください）。 + + :: + + $ sudo vi /etc/default/fess + + OpenSearch への接続情報を設定します。 ``FESS_DICTIONARY_PATH`` の既定値 ``/var/lib/opensearch/config/`` は手順 3 の ``configsync.config_path`` と異なるため、次のように変更します。 ``SEARCH_ENGINE_HTTP_URL`` は必要に応じて変更してください:: + + SEARCH_ENGINE_HTTP_URL=http://localhost:9200 + FESS_DICTIONARY_PATH=/etc/opensearch/dictionary/ + + .. note:: + + ``FESS_DICTIONARY_PATH`` は、``opensearch.yml`` の ``configsync.config_path`` と同じパスを指定してください。 + +3. サービスの登録と有効化 + + systemd を使用してサービスを有効化します:: + + $ sudo systemctl daemon-reload + $ sudo systemctl enable opensearch.service + $ sudo systemctl enable fess.service + + .. note:: + + |Fess| のサービスは OpenSearch のサービスに依存しているため、OpenSearch を先に起動する必要があります。 + +ステップ 3: 起動 +---------------- + +起動手順については、:doc:`run` を参照してください。 + +インストール後の確認 +==================== + +インストールが完了したら、以下を確認してください： + +1. **設定ファイルの確認** + + - OpenSearch の設定ファイル（opensearch.yml） + - |Fess| の設定ファイル + + - ZIP 版: ``bin/fess.in.sh`` + - RPM 版: ``/etc/sysconfig/fess`` + - DEB 版: ``/etc/default/fess`` + +2. **ディレクトリのパーミッション** + + 設定で指定したディレクトリ（``configsync.config_path`` / ``FESS_DICTIONARY_PATH``）が存在し、適切な権限が設定されていることを確認します。 + + ZIP 版の場合:: + + $ ls -ld /path/to/opensearch-3.9.0/config/dictionary/ + + RPM/DEB 版の場合:: + + $ sudo ls -ld /etc/opensearch/dictionary/ + +3. **カーネルパラメーターの確認** + + :: + + $ sysctl vm.max_map_count + + 値が ``262144`` 以上であることを確認します。 + +4. **Java のバージョン確認** + + :: + + $ java -version + + Java 21 以降がインストールされていることを確認します。 + +次のステップ +============ + +インストールが完了したら、以下のドキュメントを参照してください： + +- :doc:`run` - |Fess| の起動と初回セットアップ +- :doc:`security` - 本番環境でのセキュリティ設定 +- :doc:`troubleshooting` - トラブルシューティング + +よくある質問 +============ + +Q: OpenSearch のバージョンは他のバージョンでも動作しますか？ +------------------------------------------------------------------ + +A: |Fess| は特定のバージョンの OpenSearch に依存しています。 +プラグインの互換性を確保するため、推奨されるバージョン（3.9.0）を使用することを強く推奨します。 +他のバージョンを使用する場合は、プラグインのバージョンも適切に調整する必要があります。 + +Q: 複数の Fess インスタンスで同じ OpenSearch を共有できますか？ +------------------------------------------------------------------ + +A: 可能ですが、推奨されません。各 Fess インスタンスには専用の OpenSearch クラスターを用意することを推奨します。 +複数の Fess インスタンスで OpenSearch を共有する場合は、インデックス名の衝突に注意してください。 + +Q: OpenSearch をクラスター構成にする方法は？ +------------------------------------------------------------------ + +A: OpenSearch の公式ドキュメント `Cluster formation `__ を参照してください。 +クラスター構成にする場合は、``discovery.type: single-node`` の設定を削除し、適切なクラスター設定を追加する必要があります。 diff --git a/ja/15.10/install/install-windows.rst b/ja/15.10/install/install-windows.rst new file mode 100644 index 000000000..b30b07d29 --- /dev/null +++ b/ja/15.10/install/install-windows.rst @@ -0,0 +1,348 @@ +==================================== +Windows へのインストール (詳細手順) +==================================== + +このページでは、Windows 環境への |Fess| のインストール手順を説明します。 +ZIP パッケージを使用したインストール方法について記載しています。 + +.. note:: + + |Fess| は検索エンジンを同梱していません。OpenSearch サーバーを別途用意する必要があり、 + 以下の手順で構築します。 + +前提条件 +======== + +- :doc:`prerequisites` に記載されているシステム要件を満たしていること +- Java 21 がインストールされていること +- OpenSearch 3.9.0 を利用可能な状態にすること（または新規インストール） +- Windows の環境変数 ``JAVA_HOME`` が適切に設定されていること + +Java のインストール確認 +==================== + +コマンドプロンプトまたは PowerShell を開き、以下のコマンドで Java のバージョンを確認します。 + +コマンドプロンプトの場合:: + + C:\> java -version + +PowerShell の場合:: + + PS C:\> java -version + +Java 21 以降が表示されることを確認してください。 + +環境変数の設定 +============ + +1. ``JAVA_HOME`` 環境変数の設定 + + Java がインストールされているディレクトリを ``JAVA_HOME`` として設定します。 + + 例:: + + JAVA_HOME=C:\Program Files\Eclipse Adoptium\jdk-21.0.1.12-hotspot + +2. ``PATH`` 環境変数への追加 + + ``%JAVA_HOME%\bin`` を ``PATH`` 環境変数に追加します。 + +.. tip:: + + 環境変数の設定方法： + + 1. 「スタート」メニューから「設定」を開く + 2. 「システム」→「バージョン情報」→「システムの詳細設定」をクリック + 3. 「環境変数」ボタンをクリック + 4. 「システム環境変数」または「ユーザー環境変数」で設定 + +ステップ 1: OpenSearch のインストール +=================================== + +.. tip:: + + |Fess| に同梱の ``bin\fess-setup`` で、以下の手順をまとめて実行できます。OpenSearch を |Fess| のディレクトリの ``opensearch\`` に取得・展開し、必要なプラグインを導入したうえで、その ``config\opensearch.yml`` に ``configsync.config_path`` と ``plugins.security.disabled: true`` を追加します。先にステップ 2 のとおり |Fess| の ZIP を展開しておいてください。 + + :: + + > cd C:\fess-15.10.0 + > bin\fess-setup install opensearch + + この方法で導入した OpenSearch は ``bin\fess.in.bat`` が見つけ、その ``config\dictionary`` ディレクトリを |Fess| に渡すため、OpenSearch を同じホストで動かす限り、ステップ 2 の「Fess の設定」で変更は必要ありません。コマンドは、追加した設定と、 ``bin\fess.in.bat`` がこのインストールを見つけられるかどうかを表示します。OpenSearch を ``localhost`` 以外のアドレスで待ち受けさせる前に、「OpenSearch の設定」の警告を確認してください。 + + 手順を個別に確認したい場合や、既存の OpenSearch を使う場合は、以下に従ってください。 + 既存の OpenSearch にプラグインだけを入れる場合は + ``bin\fess-setup install opensearch-plugins --opensearch-home C:\opensearch-3.9.0`` を使用します。 + すべてのコマンドについては :doc:`fess-setup` を参照してください。 + +OpenSearch のダウンロード +----------------------- + +1. `Download OpenSearch `__ から Windows 用の ZIP パッケージをダウンロードします。 + +2. ダウンロードした ZIP ファイルを任意のディレクトリに展開します。 + + 例:: + + C:\opensearch-3.9.0 + + .. note:: + + パスに日本語や空白文字が含まれないディレクトリを選択することを推奨します。 + +OpenSearch プラグインのインストール +--------------------------------- + +コマンドプロンプトを\ **管理者権限で**\ 開き、以下のコマンドを実行します。 + +:: + + C:\> cd C:\opensearch-3.9.0 + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + +.. important:: + + プラグインのバージョンは OpenSearch のバージョンと一致させる必要があります。 + 上記の例では、すべて 3.9.0 を指定しています。 + + |Fess| 用の 4 つのプラグインは maven.codelibs.org で公開しているため、URL で指定します。 ``opensearch-plugin install`` の ``groupId:artifactId:version`` 形式は Maven Central だけを参照します。 + +OpenSearch の設定 +--------------- + +``config\opensearch.yml`` をテキストエディタで開き、以下の設定を追加します。 + +:: + + # 設定同期用のパス（絶対パスで指定） + configsync.config_path: C:/opensearch-3.9.0/config/dictionary/ + + # セキュリティプラグインの無効化（開発環境のみ） + plugins.security.disabled: true + +.. warning:: + + **セキュリティに関する重要な注意** + + ``plugins.security.disabled: true`` は、開発環境やテスト環境でのみ使用してください。 + 本番環境では、OpenSearch のセキュリティプラグインを有効にし、適切な認証・認可設定を行ってください。 + 詳細は :doc:`security` を参照してください。 + +.. note:: + + Windows の場合、パスの区切り文字は ``\`` ではなく ``/`` を使用してください。 + ``C:\opensearch-3.9.0\config\dictionary\`` ではなく ``C:/opensearch-3.9.0/config/dictionary/`` と記述します。 + +.. important:: + + ``configsync.config_path`` には、OpenSearch の設定ディレクトリ（この例では ``C:/opensearch-3.9.0/config/``）の下のディレクトリを指定してください。 + OpenSearch 3.8.0 以降は、辞書ファイルが設定ディレクトリの外にあるとインデックスの作成を拒否します。 + ``C:/opensearch-3.9.0/data/config/`` など設定ディレクトリの外を指定すると、 |Fess| はインデックスを作成できず、起動しません。 + +.. tip:: + + その他の推奨設定:: + + cluster.name: fess-cluster + node.name: fess-node-1 + network.host: 0.0.0.0 + discovery.type: single-node + +.. tip:: + + OpenSearch のヒープサイズは、``config\jvm.options`` の ``-Xms`` / ``-Xmx`` で設定します。 + 利用可能な物理メモリの半分以下、かつ 32GB 未満を目安に、``-Xms`` と ``-Xmx`` には同じ値を指定することを推奨します。 + +ステップ 2: Fess のインストール +============================= + +Fess のダウンロード +----------------- + +1. `ダウンロードサイト `__ から Windows 用の ZIP パッケージをダウンロードします。 + +2. ダウンロードした ZIP ファイルを任意のディレクトリに展開します。 + + 例:: + + C:\fess-15.10.0 + + .. note:: + + パスに日本語や空白文字が含まれないディレクトリを選択することを推奨します。 + +Fess の設定 +---------- + +``bin\fess-setup install opensearch`` で |Fess| のディレクトリの ``opensearch\`` に導入し、同じホストで動かしている OpenSearch であれば、ここでの設定は必要ありません。上記の手順で OpenSearch を導入した場合、OpenSearch を別のホストで実行している場合、 ``opensearch\`` に ``bin\fess-setup`` で導入した OpenSearch が 2 つ以上ある場合などは、以下のとおり接続先を設定します。 + +``bin\fess.in.bat`` をテキストエディタで開きます。 +このファイルの末尾付近には、外部 OpenSearch クラスターへ接続するための設定が、あらかじめコメントアウトされた状態で用意されています。 + +変更前（既定の状態）:: + + REM External opensearch cluster + REM set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200 + REM set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=C:/opensearch/config/dictionary + +下 2 行の先頭にある ``REM `` を削除してコメントを解除し、``fess.dictionary.path`` の値を OpenSearch の設定同期用パスに変更します。 + +変更後:: + + REM External opensearch cluster + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200 + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=C:/opensearch-3.9.0/config/dictionary/ + +.. note:: + + - ``fess.dictionary.path`` には、OpenSearch の ``opensearch.yml`` で指定した ``configsync.config_path`` と同じパスを設定してください。 + - OpenSearch を別のホストで実行している場合は、``fess.search_engine.http_address`` のホスト名または IP アドレスを適切な値に変更してください。 + - パスの区切り文字は ``/`` を使用してください。 |Fess| はこのパスをインデックスの設定に埋め込み、その際に ``\`` が失われるため、 ``\`` で書いたパスは見つかりません。 + - 新たに ``set FESS_JAVA_OPTS=...`` の行を追加するのではなく、既存のコメント行を解除して編集してください。同じオプションを重複して指定すると、意図しない動作の原因となる場合があります。 + +.. tip:: + + |Fess| のヒープサイズを変更するには、``bin\fess.in.bat`` の ``FESS_MIN_MEM`` (既定: ``256m``) と ``FESS_MAX_MEM`` (既定: ``1g``) を編集するか、環境変数 ``FESS_HEAP_SIZE`` を設定します。 + +インストールの確認 +---------------- + +設定ファイルが正しく編集されたことを確認します。 + +コマンドプロンプトで:: + + C:\> findstr "fess.search_engine.http_address" C:\fess-15.10.0\bin\fess.in.bat + C:\> findstr "fess.dictionary.path" C:\fess-15.10.0\bin\fess.in.bat + +ステップ 3: 起動 +============== + +起動手順については、:doc:`run` を参照してください。 + +Windows サービスとしての登録（オプション） +======================================= + +|Fess| を Windows サービスとして登録することで、システム起動時に自動的に起動するように設定できます。 + +|Fess| には、Windows サービスを登録するための ``bin\service.bat`` が同梱されています。 +このスクリプトは Apache Commons Daemon (procrun) を利用しているため、NSSM などのサードパーティ製ツールを別途用意する必要はありません。 + +.. note:: + + ``service.bat`` を実行する前に、環境変数 ``JAVA_HOME`` が正しく設定されていることを確認してください。 + +|Fess| サービスの登録 +-------------------- + +コマンドプロンプトを\ **管理者権限で**\ 開き、以下のコマンドを実行します。 + +1. サービスの登録:: + + C:\> cd C:\fess-15.10.0 + C:\fess-15.10.0> bin\service.bat install + + 既定では、64 ビット環境では ``fess-service-x64``、32 ビット環境では ``fess-service-x86`` というサービス ID で登録されます。 + サービス ID を明示的に指定する場合は、``bin\service.bat install <サービスID>`` のように引数で指定します。 + +2. サービスの開始・停止:: + + C:\fess-15.10.0> bin\service.bat start + C:\fess-15.10.0> bin\service.bat stop + +3. サービス設定の確認・変更 (GUI):: + + C:\fess-15.10.0> bin\service.bat manager + +4. サービスの削除:: + + C:\fess-15.10.0> bin\service.bat remove + +.. note:: + + - ``service.bat`` は内部で ``bin\fess.in.bat`` を読み込むため、「Fess の設定」で行った外部 OpenSearch への接続設定はサービスにも反映されます。 + - 既定のスタートアップの種類は「手動」です。システム起動時に自動的に開始するには、サービス登録前に環境変数 ``FESS_START_TYPE`` を ``auto`` に設定するか、登録後に「サービス」管理ツール (``services.msc``) でスタートアップの種類を「自動」に変更してください。 + - ``service.bat`` で登録できるのは |Fess| サービスのみです。OpenSearch をサービスとして登録する場合は、OpenSearch が提供する手順を参照してください。 + +ファイアウォール設定 +================== + +Windows Defender ファイアウォールで、必要なポートを開放します。 + +1. 「コントロールパネル」→「Windows Defender ファイアウォール」→「詳細設定」を開く + +2. 「受信の規則」で新しい規則を作成 + + - 規則の種類: ポート + - プロトコルおよびポート: TCP、8080 + - 操作: 接続を許可する + - 名前: Fess Web Interface + +または、PowerShell で実行:: + + PS C:\> New-NetFirewallRule -DisplayName "Fess Web Interface" -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow + +トラブルシューティング +==================== + +ポート番号の競合 +-------------- + +ポート 8080 または 9200 が既に使用されている場合、以下のコマンドで確認できます:: + + C:\> netstat -ano | findstr :8080 + C:\> netstat -ano | findstr :9200 + +使用中のポート番号を変更するか、競合しているプロセスを停止してください。 + +パスの長さ制限 +------------ + +Windows では、パスの長さに制限があります。可能な限り短いパスにインストールすることを推奨します。 + +例:: + + C:\opensearch (推奨) + C:\Program Files\opensearch-3.9.0 (非推奨 - パスが長い) + +Java が認識されない +----------------- + +``java -version`` コマンドでエラーが表示される場合： + +1. ``JAVA_HOME`` 環境変数が正しく設定されているか確認 +2. ``PATH`` 環境変数に ``%JAVA_HOME%\bin`` が含まれているか確認 +3. コマンドプロンプトを再起動して設定を反映 + +次のステップ +========== + +インストールが完了したら、以下のドキュメントを参照してください： + +- :doc:`run` - |Fess| の起動と初回セットアップ +- :doc:`security` - 本番環境でのセキュリティ設定 +- :doc:`troubleshooting` - トラブルシューティング + +よくある質問 +========== + +Q: Windows Server での運用は推奨されますか？ +------------------------------------------ + +A: はい、Windows Server での運用は可能です。 +Windows Server で運用する場合は、Windows サービスとして登録し、適切な監視を設定してください。 + +Q: 64 ビット版と 32 ビット版の違いは？ +------------------------------------ + +A: |Fess| および OpenSearch は 64 ビット版のみをサポートしています。 +32 ビット版の Windows では動作しません。 + +Q: パスに日本語が含まれる場合の対処法は？ +-------------------------------------- + +A: 可能な限り、日本語や空白文字が含まれないパスにインストールしてください。 +どうしても日本語パスを使用する必要がある場合は、設定ファイルでパスを適切にエスケープする必要があります。 diff --git a/ja/15.10/install/install.rst b/ja/15.10/install/install.rst new file mode 100644 index 000000000..d64e6f1c8 --- /dev/null +++ b/ja/15.10/install/install.rst @@ -0,0 +1,247 @@ +==================== +インストール方法の選択 +==================== + +このページでは、 |Fess| のインストール方法の概要について説明します。 +ご利用の環境に応じて、適切なインストール方法を選択してください。 + +.. note:: + + |Fess| は検索エンジンを同梱していません。以下のいずれのインストール方法でも、 + OpenSearch サーバーが別途必要です。 + +前提条件の確認 +============ + +インストールを開始する前に、システム要件を確認してください。 + +詳細は :doc:`prerequisites` を参照してください。 + +インストール方法の比較 +==================== + +|Fess| は、以下の方法でインストールできます。ご利用の環境と用途に応じて選択してください。 + +.. list-table:: + :header-rows: 1 + :widths: 15 25 30 30 + + * - 方法 + - 対象 OS + - 推奨用途 + - 詳細ドキュメント + * - Docker + - Linux, Windows, macOS + - 開発・評価環境、迅速なセットアップ + - :doc:`install-docker` + * - ZIP + - Linux, macOS + - カスタマイズが必要な環境 + - :doc:`install-linux` + * - RPM + - RHEL, CentOS, Fedora + - 本番環境（RPM ベース） + - :doc:`install-linux` + * - DEB + - Debian, Ubuntu + - 本番環境（DEB ベース） + - :doc:`install-linux` + * - ZIP + - Windows + - Windows 環境での開発・本番 + - :doc:`install-windows` + +各インストール方法の特徴 +====================== + +Docker 版 +-------- + +**メリット:** + +- 最も迅速にセットアップ可能 +- 依存関係の管理が不要 +- 開発環境の構築に最適 +- コンテナの起動・停止が容易 + +**デメリット:** + +- Docker の知識が必要 + +**推奨環境:** 開発環境、評価環境、POC、本番環境 + +詳細: :doc:`install-docker` + +Linux パッケージ版 (ZIP/RPM/DEB) +--------------------------------- + +**メリット:** + +- ネイティブ環境での高いパフォーマンス +- システムサービスとして管理可能（RPM/DEB） +- 細かいカスタマイズが可能 + +**デメリット:** + +- Java と OpenSearch の手動インストールが必要 +- 設定の手間がかかる + +**推奨環境:** 本番環境（システムサービスとして管理できる RPM/DEB を推奨）、カスタマイズが必要な環境 + +詳細: :doc:`install-linux` + +Windows 版 (ZIP) +--------------- + +**メリット:** + +- Windows ネイティブ環境で動作 +- インストーラー不要 + +**デメリット:** + +- Java と OpenSearch の手動インストールが必要 +- 設定の手間がかかる + +**推奨環境:** Windows 環境での開発・評価、Windows Server での本番運用 + +詳細: :doc:`install-windows` + +インストールの基本的な流れ +======================== + +すべてのインストール方法で、基本的な流れは同じです。 + +1. **システム要件の確認** + + :doc:`prerequisites` を参照して、システム要件を満たしていることを確認します。 + +2. **ソフトウェアのダウンロード** + + `ダウンロードサイト `__ から |Fess| をダウンロードします。 + + Docker 版の場合は、Docker Compose ファイルを取得します。 + +3. **OpenSearch のセットアップ** + + Docker 版以外の場合、OpenSearch を個別にセットアップする必要があります。 + + - OpenSearch 3.9.0 のインストール + - 必須プラグインのインストール + - 設定ファイルの編集 + +4. **Fess のセットアップ** + + - Fess のインストール + - 設定ファイルの編集（OpenSearch への接続情報など） + +5. **起動と確認** + + - サービスの起動 + - ブラウザーでアクセスして動作確認 + + 詳細は :doc:`run` を参照してください。 + +必要なコンポーネント +================== + +|Fess| を実行するには、以下のコンポーネントが必要です。 + +Fess 本体 +-------- + +全文検索システムの本体です。Web インターフェース、クローラー、インデクサーなどの機能を提供します。 + +OpenSearch +---------- + +検索エンジンとして OpenSearch を使用します。 + +- **対応バージョン**: OpenSearch 3.9.0 +- **必須プラグイン**: + + - opensearch-analysis-fess + - opensearch-analysis-extension + - opensearch-minhash + - opensearch-configsync + +.. important:: + + OpenSearch のバージョンとプラグインのバージョンは一致させる必要があります。 + バージョンの不一致は、起動エラーや予期しない動作の原因となります。 + +``bin/fess-setup install opensearch`` は、Linux と Windows で、これらのプラグインを含めて OpenSearch を用意します。詳細は、OpenSearch を別の方法で導入する必要がある macOS の場合も含めて :doc:`install-linux` を、すべてのコマンドについては :doc:`fess-setup` を参照してください。 + +.. note:: + + マネージドサービスなど、これらのプラグインを導入できない OpenSearch を使う場合は、 ``search_engine.type`` に ``vanilla`` を指定します（ |Fess| 15.10 以降）。辞書管理などの一部の機能は使えなくなります。詳しくは :doc:`../config/search-engine-type` を参照してください。 + +Java (Docker 版以外) +------------------- + +ZIP/RPM/DEB 版の場合、Java 21 以降が必要です。 + +- 推奨: `Eclipse Temurin `__ +- OpenJDK 21 以降も使用可能 + +.. note:: + + Docker 版の場合、Java は Docker イメージに含まれているため、別途インストールする必要はありません。 + +次のステップ +========== + +システム要件を確認し、適切なインストール方法を選択してください。 + +1. :doc:`prerequisites` - システム要件の確認 +2. インストール方法の選択: + + - :doc:`install-docker` - Docker でのインストール + - :doc:`install-linux` - Linux へのインストール + - :doc:`install-windows` - Windows へのインストール + +3. :doc:`run` - |Fess| の起動と初回セットアップ +4. :doc:`security` - セキュリティ設定（本番環境の場合） + +よくある質問 +========== + +Q: OpenSearch は必須ですか？ +-------------------------- + +A: はい、必須です。\ |Fess| は検索エンジンとして OpenSearch を使用します。 +Docker 版の場合は自動的にセットアップされますが、その他の方法では手動でインストールする必要があります。 + +Q: 以前のバージョンからアップグレードできますか？ +---------------------------------------------- + +A: はい、可能です。詳細は :doc:`upgrade` を参照してください。 + +Q: 複数のサーバーで構成できますか？ +--------------------------------- + +A: はい、可能です。Fess と OpenSearch を別々のサーバーで実行することができます。 +また、OpenSearch をクラスター構成にすることで、高可用性とパフォーマンスの向上が可能です。 + +ダウンロード +========== + +|Fess| および関連コンポーネントは、以下からダウンロードできます： + +- **Fess**: `ダウンロードサイト `__ +- **OpenSearch**: `Download OpenSearch `__ +- **Java (Adoptium)**: `Adoptium `__ +- **Docker**: `Get Docker `__ + +バージョン情報 +============ + +このドキュメントは、以下のバージョンを対象としています： + +- **Fess**: 15.10.0 +- **OpenSearch**: 3.9.0 +- **Java**: 21 以降 +- **Docker**: 20.10 以降 +- **Docker Compose**: 2.0 以降 + +以前のバージョンのドキュメントについては、各バージョンのドキュメントを参照してください。 diff --git a/ja/15.10/install/intro.rst b/ja/15.10/install/intro.rst new file mode 100644 index 000000000..1921e2a43 --- /dev/null +++ b/ja/15.10/install/intro.rst @@ -0,0 +1,70 @@ +====================== +インストールのはじめに +====================== + +本ドキュメントについて +================== + +このインストールガイドは、 |Fess| のインストール、起動、アップグレード、およびアンインストールの手順を説明します。 +ご利用の環境に応じて、適切なインストール方法を選択してください。 + +対象読者 +======== + +このドキュメントは、 |Fess| のインストール作業およびアンインストール作業を担当するユーザーを対象にしています。 + +お読みになる前に +============== + +このドキュメントでは、 |Fess| のインストール方法を示しています。以下の知識が必要になります： + +- サーバー管理の基礎知識 +- Linux または Windows のコマンドライン操作 +- ネットワークおよびファイアウォールの基本設定 +- Docker の基礎知識 (Docker版をご利用の場合) + +ドキュメント構成 +============== + +このインストールガイドは、以下のセクションで構成されています： + +- **システム要件**: |Fess| を実行するために必要なハードウェアおよびソフトウェア要件 +- **インストール**: プラットフォーム別のインストール手順 + + - インストール方法の選択 (各方式の概要と比較) + - Linux (ZIP/RPM/DEB) 向けインストール + - Windows (ZIP) 向けインストール + - Docker 向けインストール + +- **起動、停止、初期設定**: |Fess| サーバーの起動、停止、および初回セットアップ +- **セキュリティ設定**: 本番環境で推奨されるセキュリティ設定 +- **アップグレード**: 以前のバージョンから最新版へのアップグレード手順 +- **アンインストール**: |Fess| の完全なアンインストール手順 +- **トラブルシューティング**: よくある問題と解決方法 + +オンラインでのアクセス +================= + +ダウンロード、専門的サービス、サポート、その他の開発者情報については、次にアクセスしてください。 + +- プロジェクトサイト: `https://fess.codelibs.org/ `__ + +技術的なサポートの連絡先 +================== + +本製品に関する技術的な質問や問題については、次にアクセスしてください。 + +- Issues: `https://github.com/codelibs/fess/issues `__ + +商用サポート +--------- + +本製品に関する技術的対応や保守などの商用サポートが必要な場合は、 `N2SM, Inc. `__ にご相談ください。 + +コメントおよび提案の送付方法 +===================== + +問題や改善点がございましたら、こちらからお送りください。 + +- 製品の問題: `https://github.com/codelibs/fess/issues `__ +- ドキュメントの問題: `https://github.com/codelibs/fess-docs/issues `__ diff --git a/ja/15.10/install/prerequisites.rst b/ja/15.10/install/prerequisites.rst new file mode 100644 index 000000000..ebd1a9252 --- /dev/null +++ b/ja/15.10/install/prerequisites.rst @@ -0,0 +1,185 @@ +============ +システム要件 +============ + +このページでは、 |Fess| を実行するために必要なハードウェアおよびソフトウェア要件について説明します。 + +ハードウェア要件 +============== + +最小要件 +-------- + +以下は、評価および開発環境での最小要件です： + +- CPU: 2コア以上 +- メモリ: 4GB以上 +- ディスク容量: 10GB以上の空き容量 + +推奨要件 +-------- + +本番環境では、以下のスペックを推奨します： + +- CPU: 4コア以上 +- メモリ: 8GB以上（インデックスサイズに応じて増設） +- ディスク容量: + + - システム領域: 20GB以上 + - データ領域: インデックスサイズの3倍以上（レプリカを含む） + +- ネットワーク: 1Gbps以上 + +.. note:: + + インデックスサイズが大きくなる場合や、高頻度のクロールを実行する場合は、 + メモリとディスク容量を適切に増設してください。 + +ソフトウェア要件 +============== + +オペレーティングシステム +-------------------- + +|Fess| は以下のオペレーティングシステムで動作します： + +**Linux** + +- Red Hat Enterprise Linux 8 以降 +- CentOS 8 以降 +- Ubuntu 20.04 LTS 以降 +- Debian 11 以降 +- その他の Linux ディストリビューション（Java 21 が実行可能な環境） + +**Windows** + +- Windows Server 2019 以降 +- Windows 10 以降 + +**その他** + +- macOS 11 (Big Sur) 以降（開発環境のみ推奨。OpenSearch には macOS 向けの公式配布がないため、Homebrew か Docker で用意します） +- Docker が実行可能な環境 + +必須ソフトウェア +-------------- + +インストール方法により、以下のソフトウェアが必要です： + +ZIP/RPM/DEB 版 +~~~~~~~~~~~~~~~~~~~~ + +- **Java 21**: `Eclipse Temurin `__ を推奨 + + - OpenJDK 21 以降 + - Eclipse Temurin 21 以降 + +- **OpenSearch 3.9.0**: 必須。OpenSearch 3 より前のバージョンでは |Fess| は起動しません + + - 対応バージョン: OpenSearch 3.9.0 + - その他のバージョンではプラグインの互換性に注意が必要 + +Docker 版 +~~~~~~~~~ + +- **Docker**: 20.10 以降 +- **Docker Compose**: 2.0 以降 + +ネットワーク要件 +============== + +必要なポート +---------- + +|Fess| が使用する主なポートは以下の通りです： + +.. list-table:: + :header-rows: 1 + :widths: 15 15 50 + + * - ポート + - プロトコル + - 用途 + * - 8080 + - HTTP + - |Fess| Web インターフェース（検索画面・管理画面） + * - 9200 + - HTTP + - OpenSearch HTTP API（|Fess| から OpenSearch への通信） + * - 9300 + - TCP + - OpenSearch トランスポート通信（クラスター構成時） + +.. warning:: + + 本番環境では、外部からポート 9200 および 9300 への直接アクセスを制限することを強く推奨します。 + これらのポートは |Fess| と OpenSearch 間の内部通信にのみ使用されるべきです。 + +ファイアウォール設定 +------------------ + +|Fess| を外部からアクセス可能にする場合、ポート 8080 を開放する必要があります。 + +**Linux (firewalld の場合)** + +:: + + $ sudo firewall-cmd --permanent --add-port=8080/tcp + $ sudo firewall-cmd --reload + +**Linux (iptables の場合)** + +:: + + $ sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT + $ sudo iptables-save + +ブラウザー要件 +============ + +|Fess| の管理画面および検索画面には、以下のブラウザーを推奨します： + +- Google Chrome（最新版） +- Mozilla Firefox（最新版） +- Microsoft Edge（最新版） +- Safari（最新版） + +.. note:: + + Internet Explorer はサポートされていません。 + +前提条件チェックリスト +==================== + +インストール前に、以下の項目を確認してください： + +.. list-table:: + :header-rows: 1 + :widths: 50 50 + + * - 確認項目 + - 状態 + * - ハードウェア要件を満たしているか + - □ + * - Java 21 がインストールされているか（Docker 版以外） + - □ + * - Docker がインストールされているか（Docker 版） + - □ + * - 必要なポートが利用可能か + - □ + * - ファイアウォール設定が適切か + - □ + * - ディスク容量に十分な空きがあるか + - □ + * - ネットワーク接続が正常か（外部サイトのクロールを行う場合） + - □ + +次のステップ +========== + +システム要件を確認したら、ご利用の環境に応じたインストール手順に進んでください： + +- :doc:`install-linux` - Linux (ZIP/RPM/DEB) 向けインストール +- :doc:`install-windows` - Windows (ZIP) 向けインストール +- :doc:`install-docker` - Docker 向けインストール +- :doc:`install` - インストール方法の概要 diff --git a/ja/15.10/install/run.rst b/ja/15.10/install/run.rst new file mode 100644 index 000000000..bee8cc65b --- /dev/null +++ b/ja/15.10/install/run.rst @@ -0,0 +1,533 @@ +==================== +起動、停止、初期設定 +==================== + +このページでは、 |Fess| サーバーの起動、停止、および初回セットアップの手順について説明します。 + +.. important:: + + |Fess| を起動する前に、必ず OpenSearch を起動してください。 + OpenSearch が起動していない場合、 |Fess| は正しく動作しません。 + +起動方法 +======== + +インストール方法により、起動手順が異なります。 + +ZIP 版の場合 +------------- + +OpenSearch の起動 +~~~~~~~~~~~~~~~~ + +:: + + $ cd /path/to/opensearch-3.9.0 + $ ./bin/opensearch + +バックグラウンドで起動する場合:: + + $ ./bin/opensearch -d + +.. note:: + + ``bin/fess-setup install opensearch`` で導入した OpenSearch は、 |Fess| のディレクトリの ``opensearch/opensearch-3.9.0`` にあります。 + +.. important:: + + OpenSearch は一般ユーザーで起動してください。 ``root`` で起動すると ``can not run opensearch as root`` と表示して終了します。拒否された起動でも ``config/opensearch.keystore`` などのファイルが ``root`` の所有で残り、次に一般ユーザーで起動すると ``AccessDeniedException`` で失敗します。再度起動する前に、OpenSearch のディレクトリの所有者をそのユーザーに戻してください。例:: + + $ sudo chown -R /path/to/opensearch-3.9.0 + +Fess の起動 +~~~~~~~~~~ + +:: + + $ cd /path/to/fess-15.10.0 + $ ./bin/fess + +バックグラウンドで起動する場合:: + + $ ./bin/fess -d + +.. note:: + + 起動には数分かかる場合があります。 + ``logs/`` ディレクトリのログファイルで起動状況を確認できます。|Fess| 本体のメッセージは + ``fess.log``、組み込み Tomcat のメッセージ（起動完了メッセージを含む）は ``server_0.log`` に出力されます。 + +ZIP 版の場合（Windows） +--------------------- + +OpenSearch の起動 +~~~~~~~~~~~~~~~~ + +1. OpenSearch のインストールディレクトリを開きます +2. ``bin`` フォルダー内の ``opensearch.bat`` をダブルクリックします + +または、コマンドプロンプトから:: + + C:\> cd C:\opensearch-3.9.0 + C:\opensearch-3.9.0> bin\opensearch.bat + +Fess の起動 +~~~~~~~~~~ + +1. Fess のインストールディレクトリを開きます +2. ``bin`` フォルダー内の ``fess.bat`` をダブルクリックします + +または、コマンドプロンプトから:: + + C:\> cd C:\fess-15.10.0 + C:\fess-15.10.0> bin\fess.bat + +RPM/DEB 版の場合 (chkconfig) +-------------------------- + +OpenSearch の起動:: + + $ sudo service opensearch start + +Fess の起動:: + + $ sudo service fess start + +起動状態の確認:: + + $ sudo service fess status + +RPM/DEB 版の場合 (systemd) +------------------------ + +OpenSearch の起動:: + + $ sudo systemctl start opensearch.service + +Fess の起動:: + + $ sudo systemctl start fess.service + +起動状態の確認:: + + $ sudo systemctl status fess.service + +サービスの自動起動を有効化:: + + $ sudo systemctl enable opensearch.service + $ sudo systemctl enable fess.service + +Docker 版の場合 +------------- + +.. note:: + + ``compose.yaml`` および ``compose-opensearch3.yaml`` は、|Fess| 本体には + 含まれていません。これらは docker-fess プロジェクト + （https://github.com/codelibs/docker-fess）で提供されており、リポジトリを + 取得した上で ``compose`` ディレクトリ内で以下のコマンドを実行します。 + +Docker Compose を使用して起動:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +起動状態の確認:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps + +ログの確認:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01 + +起動の確認 +========== + +|Fess| が正常に起動したことを確認します。 + +ヘルスチェック +------------ + +ブラウザーまたは curl コマンドで以下の URL にアクセスします:: + + http://localhost:8080/ + +正常に起動している場合、Fess の検索画面が表示されます。 + +コマンドラインでの確認:: + + $ curl -I http://localhost:8080/ + +``HTTP/1.1 200 OK`` が返ってくれば、正常に起動しています。 + +ログの確認 +-------- + +起動ログを確認して、エラーがないことを確認します。 + +ZIP 版:: + + $ tail -f /path/to/fess-15.10.0/logs/fess.log + +RPM/DEB 版:: + + $ sudo tail -f /var/log/fess/fess.log + +または journalctl を使用:: + + $ sudo journalctl -u fess.service -f + +Docker 版:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01 + +.. tip:: + + 正常に起動した場合、以下のような起動完了メッセージがログディレクトリ（ZIP 版は ``logs/``、 + RPM/DEB 版は ``/var/log/fess/``）の ``server_0.log`` に出力されます。コンソールにも ``fess.log`` にも + 出力されません:: + + ...Booting the Tomcat: port=8080 contextPath= + ... + Boot successful: url -> http://localhost:8080 + +ブラウザーでのアクセス +==================== + +以下の URL にアクセスして、Web インターフェースを確認します。 + +検索画面 +-------- + +**URL**: http://localhost:8080/ + +Fess の検索画面が表示されます。初期状態では、クロール設定が行われていないため、検索結果は表示されません。 + +検索画面は |Fess| に同梱の静的テーマ ``bootstrap`` です。見た目を変えるには、管理画面の +「システム」>「テーマ」または ``bin/fess-setup install theme `` で別のテーマをインストールするか +（ :doc:`fess-setup` を参照）、同梱のテーマを複製して変更します（ :ref:`theme-customize-bundled` を参照）。 + +管理画面 +-------- + +**URL**: http://localhost:8080/admin + +デフォルトの管理者アカウント： + +- **ユーザー名**: ``admin`` +- **パスワード**: ``admin`` + +.. warning:: + + **セキュリティに関する重要な注意** + + デフォルトのパスワードは必ず変更してください。 + 特に本番環境では、初回ログイン後すぐにパスワードを変更することを強く推奨します。 + +初回セットアップ +============== + +管理画面にログインしたら、以下の初期設定を行います。 + +ステップ 1: 管理者パスワードの変更 +------------------------------- + +1. 管理画面にログイン（http://localhost:8080/admin） +2. 左メニューから「ユーザー」→「ユーザー」をクリック +3. ``admin`` ユーザーをクリック +4. 「パスワード」フィールドに新しいパスワードを入力 +5. 「パスワード(確認)」フィールドに同じパスワードを再入力 +6. 「更新」ボタンをクリック + +.. important:: + + パスワードは以下の条件を満たすことを推奨します： + + - 8文字以上（``password.min.length`` で設定される必須の最小文字数） + - 英大文字、英小文字、数字、記号を組み合わせる + - 推測されにくいもの + + デフォルトで必須となるのは最小文字数（8文字）のみで、文字種の組み合わせは + 強制されません。文字種の要件は ``password.require.uppercase`` などの設定で + 有効化できます。 + +ステップ 2: クロール設定の作成 +--------------------------- + +検索対象のサイトや ファイルシステムをクロールする設定を作成します。 + +1. 左メニューから「クローラー」→「ウェブ」をクリック +2. 「新規作成」ボタンをクリック +3. 必要な情報を入力： + + - **名前**: クロール設定の名前（例：会社のWebサイト） + - **URL**: クロール対象の URL（例：https://www.example.com/）。複数指定する場合は 1 行に 1 URL を記述します + - **最大アクセス数**: クロールするドキュメント数の上限（省略可能） + - **間隔**: 各アクセス間の待機時間（ミリ秒。デフォルト：``10000``） + + .. note:: + + 上記以外の項目（ユーザーエージェント、スレッド数、深さなど）は、 + 未入力の場合はデフォルト値が使用されます。 + +4. 「作成」ボタンをクリック + +ステップ 3: クロールの実行 +----------------------- + +1. 左メニューから「システム」→「スケジューラ」をクリック +2. 「Default Crawler」ジョブを開き、「今すぐ開始」ボタンをクリック +3. クロールが完了するまで待ちます（進行状況はダッシュボードで確認可能） + +ステップ 4: 検索の確認 +------------------- + +1. 検索画面（http://localhost:8080/）にアクセス +2. 検索キーワードを入力 +3. 検索結果が表示されることを確認 + +.. note:: + + クロールには時間がかかる場合があります。 + 大規模なサイトの場合、数時間から数日かかることもあります。 + +その他の推奨設定 +============== + +本番環境で運用する場合、以下の設定も検討してください。 + +主な環境変数による設定 +-------------------- + +ポート番号、JVM ヒープサイズ、接続先の OpenSearch などは、環境変数で変更できます。 +ZIP 版は ``bin/fess.in.sh``、RPM 版は ``/etc/sysconfig/fess``、DEB 版は +``/etc/default/fess`` を編集します。変更後は |Fess| の再起動が必要です。 + +.. list-table:: + :header-rows: 1 + :widths: 30 25 45 + + * - 環境変数 + - デフォルト + - 説明 + * - ``FESS_PORT`` + - ``8080`` + - |Fess| が待ち受けする HTTP ポート番号。 + * - ``FESS_HEAP_SIZE`` + - （未設定） + - JVM ヒープサイズ。最小・最大に同じ値を設定します。未設定時は最小 ``256m``・最大 ``2g``\ （ZIP 版（Windows）は最大 ``1g``）、RPM/DEB 版では ``512m`` が使用されます。 + * - ``SEARCH_ENGINE_HTTP_URL`` + - ``http://localhost:9200`` + - 接続先 OpenSearch の URL。ZIP 版では ``bin/fess.in.sh`` が既定でこの値を設定します。OpenSearch を別ポートや別ホストで稼働させる場合は、環境変数として設定するか ``bin/fess.in.sh`` を編集します。RPM/DEB 版ではパッケージの環境設定ファイルで設定されます。 + * - ``FESS_LOG_LEVEL`` + - ``warn`` + - |Fess| のログレベル。 + * - ``FESS_HEAP_NEWSIZE`` + - （未設定） + - JVM ヒープの新世代領域のサイズ（``-Xmn``）。``256m`` のように指定します。未設定時は JVM が決定します。 + * - ``FESS_TEMP_PATH`` + - |Fess| ディレクトリ内の ``temp``\ （RPM/DEB 版は ``/var/tmp/fess``） + - 一時ファイルを保存するディレクトリ（組み込み Tomcat の作業ディレクトリを含む）。|Fess| を実行するユーザーが書き込める必要があります。 + * - ``FESS_CONF_PATH`` + - （未設定）\ （RPM/DEB 版は ``/etc/fess``） + - 設定ファイルを置くディレクトリ。 ``bin/fess`` がこのディレクトリをクラスパスの先頭に追加し、 ``-Dfess.conf.path`` として |Fess| に渡します。 ``lib/classes`` にある ``tomcat_config.properties`` などは、このディレクトリのものが優先されます。ただし、ZIP 版の Web アプリケーションは ``app/WEB-INF/classes`` のファイルを先に参照するため、このディレクトリに置いた ``fess_config.properties`` では ``app/WEB-INF/classes`` の ``fess_config.properties`` の値を上書きできません（クローラーなどの子プロセスは、このディレクトリを ``WEB-INF/classes`` より先に参照します）。ZIP 版で ``fess_config.properties`` を変更するときは ``app/WEB-INF/classes`` のファイルを編集してください。RPM/DEB 版は ``app/WEB-INF/classes`` に ``fess_config.properties`` を含めず、 ``/etc/fess`` のファイルだけを使用します。 + * - ``FESS_USE_IPV4`` + - （未設定） + - 空でない値を設定すると、JVM は IPv4 スタックだけを使用します（``-Djava.net.preferIPv4Stack=true``）。 + * - ``FESS_USE_GC_LOGGING`` + - （未設定） + - 空でない値を設定すると、JVM は GC ログをログディレクトリの ``gc-fess.log`` に出力します（64 MB のファイルを最大 5 つ）。 + +.. note:: + + ZIP 版（Windows）の ``bin\fess.in.bat`` が参照する環境変数は、これらのうち + ``FESS_HEAP_SIZE``、``FESS_HEAP_NEWSIZE``、``FESS_USE_IPV4``、``FESS_USE_GC_LOGGING`` + と、表にない次の環境変数です。 + + - ``FESS_MIN_MEM``、``FESS_MAX_MEM``: 最小・最大ヒープサイズを個別に指定します（``FESS_HEAP_SIZE`` を設定した場合は無視されます）。 + - ``FESS_DIRECT_SIZE``: ダイレクトメモリの上限（``-XX:MaxDirectMemorySize``）です。 + - ``FESS_DICTIONARY_PATH``: OpenSearch の ``config\dictionary`` ディレクトリです。 + - ``FESS_PROXY_HOST``、``FESS_PROXY_PORT``、``FESS_NON_PROXY_HOSTS``: プロキシの設定です。 + - ``FESS_JAVA_OPTS``: 設定済みの値の後ろに、``fess.in.bat`` が JVM オプションを追加します。 + - ``PLAYWRIGHT_NODEJS_PATH``: Playwright プラグインが使用する Node.js の実行ファイルです。 + - ``JAVA_HOME``: 必須です。 + + ``FESS_PORT``、``FESS_LOG_LEVEL``、``FESS_TEMP_PATH``、``FESS_CONF_PATH``、``SEARCH_ENGINE_HTTP_URL`` + は参照されません。これらの値はファイル内に直接記述されているため、変更する場合は ``bin\fess.in.bat`` を直接編集してください。 + +メールサーバーの設定 +------------------ + +障害通知などをメールで受信するには、SMTP サーバーと通知先メールアドレスを設定します。 + +1. ``fess_env_web.properties`` と ``fess_env_crawler.properties`` の + ``mail.smtp.server.main.host.and.port`` に SMTP サーバーのホストとポートを + 指定します（デフォルト：``localhost:25``）。これらのファイルは、ZIP 版では + ``app/WEB-INF/classes/`` に、RPM/DEB 版では ``/etc/fess/`` にあります。 + |Fess| の Web プロセスが前者を、クロール完了のメールを送信するクローラーが後者を読み、 + ``fess_env.properties`` は使われません。変更後は |Fess| の再起動が必要です。 +2. 管理画面の左メニューから「システム」→「全般」をクリックします。 +3. 「通知メール」フィールドに通知先のメールアドレスを入力します。 +4. 「更新」ボタンをクリックします。 +5. 「テストメールの送信」ボタンで、メールが正しく送信されるか確認できます。 + +タイムゾーンの設定 +---------------- + +|Fess| のタイムゾーンには、サーバー（OS / JVM）のタイムゾーンが使用されます。 +管理画面にタイムゾーンを変更する設定項目はありません。変更する場合は、OS の +タイムゾーン設定を変更するか、``bin/fess.in.sh``\ （Windows は ``bin\fess.in.bat``）の +``FESS_JAVA_OPTS`` に JVM オプション ``-Duser.timezone=Asia/Tokyo`` を追加します。 + +ログレベルの調整 +-------------- + +本番環境では、ログレベルを調整してディスク使用量を抑えることができます。 + +|Fess| 全体のログレベルは、環境変数 ``FESS_LOG_LEVEL``\ （デフォルト：``warn``）で +変更できます。個別のロガーを細かく制御する場合は、設定ファイル +``app/WEB-INF/classes/log4j2.xml`` を編集します。クロール、サジェスト、サムネイル +生成は別プロセスで動作するため、これらのログレベルは +``app/WEB-INF/env/{crawler,suggest,thumbnail}/resources/log4j2.xml`` で個別に +設定します。 + +詳細は :doc:`../admin/index` を参照してください。 + +停止方法 +======== + +ZIP 版の場合 +----------------- + +Fess の停止 +~~~~~~~~~~ + +プロセスを kill します:: + + $ ps aux | grep fess + $ kill + +または、``Ctrl+C`` でコンソールから停止できます（フォアグラウンドで実行している場合）。 + +OpenSearch の停止:: + + $ ps aux | grep opensearch + $ kill + +RPM/DEB 版の場合 (chkconfig) +-------------------------- + +Fess の停止:: + + $ sudo service fess stop + +OpenSearch の停止:: + + $ sudo service opensearch stop + +RPM/DEB 版の場合 (systemd) +------------------------ + +Fess の停止:: + + $ sudo systemctl stop fess.service + +OpenSearch の停止:: + + $ sudo systemctl stop opensearch.service + +Docker 版の場合 +------------- + +コンテナの停止:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop + +コンテナの停止と削除:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +.. warning:: + + ``down`` コマンドでボリュームも削除する場合は ``-v`` オプションを追加します。 + この場合、すべてのデータが削除されるため注意してください。 + +再起動方法 +========== + +ZIP 版の場合 +----------------- + +停止してから起動します。 + +RPM/DEB 版の場合 +-------------- + +chkconfig:: + + $ sudo service fess restart + +systemd:: + + $ sudo systemctl restart fess.service + +Docker 版の場合 +------------- + +:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml restart + +トラブルシューティング +==================== + +起動しない場合 +------------ + +1. **OpenSearch が起動しているか確認** + + :: + + $ curl http://localhost:9200/ + + OpenSearch が起動していない場合、まず OpenSearch を起動してください。 + +2. **ポート番号の競合を確認** + + :: + + $ sudo ss -tuln | grep 8080 + + net-tools が導入されている環境では、``sudo netstat -tuln | grep 8080`` でも同じ内容を確認できます。 + + ポート 8080 が既に使用されている場合、ポート番号を変更します。 + + - ZIP 版：``bin/fess.in.sh`` の ``FESS_PORT`` を変更 + - ZIP 版（Windows）：``bin\fess.in.bat`` の ``-Dfess.port=8080`` を直接編集 + - RPM 版：``/etc/sysconfig/fess`` の ``FESS_PORT`` を変更 + - DEB 版：``/etc/default/fess`` の ``FESS_PORT`` を変更 + +3. **ログを確認** + + エラーメッセージを確認して、問題を特定します。 + +4. **Java のバージョンを確認** + + :: + + $ java -version + + Java 21 以降がインストールされていることを確認してください。 + +詳細なトラブルシューティングについては、:doc:`troubleshooting` を参照してください。 + +次のステップ +========== + +|Fess| が正常に起動したら、以下のドキュメントを参照して運用を開始してください： + +- :doc:`../admin/index` - クロール設定、検索設定、システム設定の詳細 +- :doc:`security` - 本番環境でのセキュリティ設定 +- :doc:`troubleshooting` - よくある問題と解決方法 +- :doc:`upgrade` - バージョンアップ手順 +- :doc:`uninstall` - アンインストール手順 + diff --git a/ja/15.10/install/security.rst b/ja/15.10/install/security.rst new file mode 100644 index 000000000..abf1ac56f --- /dev/null +++ b/ja/15.10/install/security.rst @@ -0,0 +1,355 @@ +================== +セキュリティ設定 +================== + +このページでは、本番環境で |Fess| を安全に運用するために推奨されるセキュリティ設定について説明します。 + +.. danger:: + + **セキュリティは非常に重要です** + + 本番環境では、このページに記載されている全てのセキュリティ設定を実施することを強く推奨します。 + セキュリティ設定を怠ると、不正アクセス、データ漏洩、システムの侵害などのリスクが高まります。 + +必須のセキュリティ設定 +==================== + +管理者パスワードの変更 +-------------------- + +デフォルトの管理者パスワード（``admin`` / ``admin``）は必ず変更してください。 + +**手順:** + +1. 管理画面にログイン: http://localhost:8080/admin +2. 「ユーザー」→「ユーザー」をクリック +3. ``admin`` ユーザーを選択 +4. 強力なパスワードを設定 +5. 「更新」ボタンをクリック + +.. note:: + + 一度 ``admin`` から変更したパスワードは、``admin`` のような単純な文字列には戻せません（``password.invalid.admin.passwords`` により管理者パスワードのブラックリストが設定されています）。また、初回起動前であれば ``fess_config.properties`` の ``index.user.initial_password`` で ``admin`` ユーザーの初期パスワードを変更できます。 + +**推奨パスワードポリシー:** + +|Fess| はパスワードの最小・最大文字数と文字種の要件を強制する機能を備えています。\ ``fess_config.properties`` で以下のプロパティを設定してください（括弧内は既定値）。 + +- ``password.min.length`` （既定値: ``8``）: 最小文字数。12 以上を推奨します。 +- ``password.max.length`` （既定値: ``100``）: 最大文字数。 +- ``password.require.uppercase`` （既定値: ``false``）: 英大文字を必須にする。 +- ``password.require.lowercase`` （既定値: ``false``）: 英小文字を必須にする。 +- ``password.require.digit`` （既定値: ``false``）: 数字を必須にする。 +- ``password.require.special.char`` （既定値: ``false``）: 記号を必須にする。 + +.. note:: + + 既定では最小文字数は ``8`` で、文字種の要件はすべて無効です。パスワード強度を高めるには、上記のプロパティを明示的に設定してください。なお、|Fess| にはパスワードの有効期限（定期変更の強制）機能はありません。定期的なパスワード変更を運用ルールとする場合は、手動で対応してください。 + +OpenSearch のセキュリティプラグイン有効化 +-------------------------------------- + +**手順:** + +1. ``opensearch.yml`` から以下の行を削除またはコメントアウト:: + + # plugins.security.disabled: true + +2. セキュリティプラグインの設定:: + + plugins.security.allow_default_init_securityindex: true + plugins.security.authcz.admin_dn: + - CN=admin,OU=SSL,O=Test,L=Test,C=DE + +3. TLS/SSL証明書の設定 + +4. OpenSearch を再起動 + +5. |Fess| 側で OpenSearch への接続情報を設定します。 + + 接続先 URL は環境変数 ``SEARCH_ENGINE_HTTP_URL`` で指定します（``bin/fess.in.sh`` またはサービスの環境設定ファイルを編集します。既定値は ``fess_config.properties`` の ``search_engine.http.url``）:: + + SEARCH_ENGINE_HTTP_URL=https://opensearch:9200 + + 認証情報は ``fess_config.properties`` の以下のプロパティで指定します（``SEARCH_ENGINE_USERNAME`` / ``SEARCH_ENGINE_PASSWORD`` という環境変数は存在しません）:: + + search_engine.username=admin + search_engine.password= + +詳細は `OpenSearch Security Plugin `__ を参照してください。 + +HTTPS の有効化 +------------ + +HTTP 通信は暗号化されていないため、盗聴や改ざんのリスクがあります。本番環境では必ず HTTPS を使用してください。 + +**方法 1: リバースプロキシの使用（推奨）** + +Nginx または Apache を |Fess| の前段に配置し、HTTPS 終端を行います。 + +Nginx の設定例:: + + server { + listen 443 ssl http2; + server_name your-fess-domain.com; + + ssl_certificate /path/to/cert.pem; + ssl_certificate_key /path/to/key.pem; + + ssl_protocols TLSv1.2 TLSv1.3; + ssl_ciphers HIGH:!aNULL:!MD5; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + } + +**方法 2: Fess 自体で HTTPS を設定** + +``tomcat_config.properties`` に以下を追加:: + + tomcat.secure=true + tomcat.scheme=https + tomcat.SSLEnabled=true + tomcat.certificateKeystoreFile=[キーストアファイルのパス] + tomcat.certificateKeystorePassword=[キーストアファイル作成時に指定したパスワード] + tomcat.certificateKeyAlias=[証明書のエイリアス] + tomcat.sslProtocol=[SSL プロトコル（例: TLS）] + tomcat.enabledProtocols=有効なプロトコル一覧（カンマ区切り）（例: TLSv1.2,TLSv1.1,TLSv1） + +推奨のセキュリティ設定 +==================== + +ファイアウォール設定 +------------------ + +必要なポートのみを開放し、不要なポートは閉じてください。 + +**開放すべきポート:** + +- **8080** (または HTTPS の 443): |Fess| Web インターフェース（外部からのアクセスが必要な場合） +- **22**: SSH（管理用、信頼できる IP アドレスからのみ） + +**閉じるべきポート:** + +- **9200, 9300**: OpenSearch（内部通信のみ、外部からのアクセスを遮断） + +Linux (firewalld) の設定例:: + + $ sudo firewall-cmd --permanent --add-service=http + $ sudo firewall-cmd --permanent --add-service=https + $ sudo firewall-cmd --permanent --remove-service=opensearch # カスタムサービスの場合 + $ sudo firewall-cmd --reload + +IP アドレス制限:: + + $ sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="192.168.1.0/24" port port="8080" protocol="tcp" accept' + +アクセス制御の設定 +---------------- + +管理画面へのアクセスを特定の IP アドレスに制限することを検討してください。 + +Nginx でのアクセス制限例:: + + location /admin { + allow 192.168.1.0/24; + deny all; + + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + } + +ロールとアクセス制御 +------------------ + +|Fess| には、あらかじめ 2 つのロールが用意されています。 + +- ``admin``: 管理画面を含むすべての操作が可能な管理者ロール +- ``guest``: 未ログイン（匿名）ユーザーに割り当てられるロール + +これら以外のロールは、管理画面から自由に作成できます。\ |Fess| のロールは名前のみを持つタグであり、主に検索結果へのアクセス制御（どのドキュメントを表示できるか）に使用されます。ただし、``admin-user`` や ``admin-scheduler`` のように ``admin-`` に管理画面名を続けた名前のロールは、その管理画面を開くための権限になります（``admin-user-view`` のように ``-view`` を付けたロールは参照のみです）。 + +.. warning:: + + ``admin-*`` ロールは、日常的な管理画面を運用担当者に分担させるためのものであり、権限の境界ではありません。たとえば ``admin-user`` を持つユーザーは、管理者ロールを含む既存の任意のロールを任意のユーザーに付与できます。``admin-accesstoken`` では Admin API のすべての機能を使える ``Radmin-api`` パーミッションのアクセストークンを発行でき、``admin-scheduler`` ではサーバー上でスクリプトジョブを実行でき、``admin-plugin`` ではプラグインをインストールできます。すべての ``admin-*`` ロールを管理者ロール（``authentication.admin.roles``、既定値は ``admin``）と同等として扱い、信頼できる運用担当者にのみ付与してください。 + +最小権限の原則に従い、管理者ロール（``admin``）は管理業務を行うユーザーにのみ付与し、一般の検索ユーザーには付与しないでください。 + +**手順:** + +1. 管理画面で「ユーザー」→「ロール」をクリック +2. 必要なロールを作成 +3. 「ユーザー」→「ユーザー」でユーザーにロールを割り当て + +監査ログ +------ + +認証や管理操作などのシステムの操作履歴は、監査ログとしてデフォルトで記録されます。監査ログは ``log4j2.xml`` に定義された ``fess.log.audit`` ロガーによって出力され、既定の出力先は ``audit.log`` です。 + +デフォルトで有効になっているため、追加の設定は不要です。出力先やログレベルをカスタマイズする場合は、``log4j2.xml`` の以下の定義を編集してください:: + + + + + +定期的なセキュリティアップデート +------------------------------ + +|Fess| および OpenSearch のセキュリティアップデートを定期的に適用してください。 + +**推奨手順:** + +1. セキュリティ情報を定期的に確認 + + - `Fess リリース情報 `__ + - `OpenSearch セキュリティアドバイザリ `__ + +2. テスト環境でアップデートを検証 +3. 本番環境にアップデートを適用 + +データ保護 +======== + +バックアップの暗号化 +------------------ + +バックアップデータには機密情報が含まれる可能性があります。バックアップファイルを暗号化して保存してください。 + +暗号化バックアップの例:: + + $ tar czf fess-backup.tar.gz /var/lib/opensearch /etc/fess + $ gpg --symmetric --cipher-algo AES256 fess-backup.tar.gz + +セキュリティベストプラクティス +============================ + +最小権限の原則 +------------ + +- Fess および OpenSearch を root ユーザーで実行しない +- 専用のユーザーアカウントで実行 +- 必要最小限のファイルシステム権限を付与 + +ネットワーク分離 +-------------- + +- OpenSearch をプライベートネットワークに配置 +- 内部通信には VPN またはプライベートネットワークを使用 +- DMZ に |Fess| の Web インターフェースのみを配置 + +定期的なセキュリティ監査 +---------------------- + +- アクセスログを定期的に確認 +- 異常なアクセスパターンを検出 +- 定期的に脆弱性スキャンを実施 + +セキュリティヘッダーの設定 +------------------------ + +必要に応じて、Nginx または Apache でセキュリティヘッダーを設定してください:: + + add_header X-Frame-Options "SAMEORIGIN" always; + add_header X-Content-Type-Options "nosniff" always; + add_header X-XSS-Protection "1; mode=block" always; + add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; + add_header Content-Security-Policy "default-src 'self'" always; + +セキュリティチェックリスト +======================== + +本番環境にデプロイする前に、以下のチェックリストを確認してください： + +基本設定 +-------- + +- [ ] 管理者パスワードを変更済み +- [ ] HTTPS を有効化済み +- [ ] デフォルトのポート番号を変更（オプション） + +ネットワークセキュリティ +---------------------- + +- [ ] ファイアウォールで不要なポートを閉鎖済み +- [ ] 管理画面へのアクセスを IP 制限済み（可能な場合） +- [ ] OpenSearch へのアクセスを内部ネットワークのみに制限済み + +アクセス制御 +---------- + +- [ ] ロールとアクセス権限を適切に設定済み（管理者ロールを必要なユーザーのみに付与） +- [ ] 不要なユーザーアカウントを削除済み +- [ ] パスワードポリシーを設定済み + +監視とログ +-------- + +- [ ] 監査ログが有効になっていることを確認済み +- [ ] ログの保存期間を設定済み +- [ ] ログ監視の仕組みを構築済み（可能な場合） + +バックアップとリカバリ +-------------------- + +- [ ] 定期的なバックアップスケジュールを設定済み +- [ ] バックアップデータを暗号化済み +- [ ] リストア手順を検証済み + +アップデートとパッチ管理 +---------------------- + +- [ ] セキュリティアップデートの通知を受信する仕組みを構築済み +- [ ] アップデート手順を文書化済み +- [ ] テスト環境でアップデートを検証する体制を構築済み + +セキュリティインシデント対応 +========================== + +セキュリティインシデントが発生した場合の対応手順： + +1. **インシデントの検知** + + - ログの確認 + - 異常なアクセスパターンの検出 + - システムの挙動異常の確認 + +2. **初期対応** + + - 影響範囲の特定 + - 被害の拡大防止（該当サービスの停止など） + - 証拠の保全 + +3. **調査と分析** + + - ログの詳細分析 + - 侵入経路の特定 + - 漏洩した可能性のあるデータの特定 + +4. **復旧** + + - 脆弱性の修正 + - システムの復旧 + - 監視の強化 + +5. **事後対応** + + - インシデントレポートの作成 + - 再発防止策の実施 + - 関係者への報告 + +参考情報 +====== + +- `OpenSearch Security Plugin `__ +- `OWASP Top 10 `__ +- `CIS Benchmarks `__ + +セキュリティに関する質問や問題がある場合は、以下にお問い合わせください： + +- Issues: https://github.com/codelibs/fess/issues +- 商用サポート: https://www.n2sm.net/ diff --git a/ja/15.10/install/troubleshooting.rst b/ja/15.10/install/troubleshooting.rst new file mode 100644 index 000000000..5d78203ab --- /dev/null +++ b/ja/15.10/install/troubleshooting.rst @@ -0,0 +1,593 @@ +================== +トラブルシューティング +================== + +このページでは、 |Fess| のインストール、起動、運用時によくある問題とその解決方法について説明します。 + +インストール時の問題 +================== + +Java が認識されない +----------------- + +**症状:** + +:: + + -bash: java: command not found + +または:: + + 'java' is not recognized as an internal or external command + +**原因:** + +Java がインストールされていない、またはPATH環境変数が正しく設定されていない。 + +**解決方法:** + +1. Java がインストールされているか確認:: + + $ which java + $ java -version + +2. インストールされていない場合、Java 21 をインストール:: + + # Ubuntu/Debian + $ sudo apt-get update + $ sudo apt-get install openjdk-21-jdk + + # RHEL/CentOS + $ sudo yum install java-21-openjdk + + Debian 12 の標準リポジトリには ``openjdk-21-jdk`` パッケージがありません。Debian 12 では、代わりに Eclipse Temurin 21 を、`Adoptium の Linux 向けインストール手順 `__ の Debian 向けの手順に従ってインストールしてください。 + +3. JAVA_HOME 環境変数を設定:: + + $ export JAVA_HOME=/path/to/java + $ export PATH=$JAVA_HOME/bin:$PATH + + 永続的に設定する場合は ``~/.bashrc`` または ``/etc/profile`` に追加します。 + +プラグインのインストールに失敗する +------------------------------- + +**症状:** + +:: + + ERROR: Plugin installation failed + +**原因:** + +- ネットワーク接続の問題 +- プラグインのバージョンが OpenSearch のバージョンと一致していない +- 権限の問題 + +**解決方法:** + +1. OpenSearch のバージョンを確認:: + + $ /path/to/opensearch/bin/opensearch --version + +2. プラグインのバージョンを OpenSearch のバージョンに合わせる:: + + $ /path/to/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + +3. 権限を確認:: + + $ sudo /path/to/opensearch/bin/opensearch-plugin install ... + +4. プロキシ経由でインストールする場合:: + + $ export ES_JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080" + $ /path/to/opensearch/bin/opensearch-plugin install ... + +起動時の問題 +========== + +Fess が起動しない +--------------- + +**症状:** + +Fess の起動コマンドを実行してもエラーが発生する、またはすぐに終了する。 + +**確認項目:** + +1. **OpenSearch が起動しているか確認**:: + + $ curl http://localhost:9200/ + + 正常な場合、JSON レスポンスが返されます。 + + OpenSearch が応答しない場合、 |Fess| は 1 分ほど再試行した後に起動を中止し、コンソールと ``logs/fess.log`` に次のメッセージを出力します:: + + The search engine at http://localhost:9200 did not become available within 60221ms. Check that OpenSearch is running and reachable. If there is none yet, run bin/fess-setup install opensearch to set one up. + + OpenSearch を起動するか、 ``SEARCH_ENGINE_HTTP_URL`` を確認してください。新しく導入した ZIP 版には、 ``bin/fess-setup install opensearch`` で導入するまで OpenSearch がありません。 :doc:`install-linux` を参照してください。 + +2. **ポート番号の競合を確認**:: + + $ sudo ss -tuln | grep 8080 + + ポート 8080 が既に使用されている場合は、設定ファイルでポート番号を変更してください。 + +3. **ログファイルを確認**:: + + $ tail -f /path/to/fess/logs/fess.log + + エラーメッセージから原因を特定します。 + +4. **Java のバージョンを確認**:: + + $ java -version + + Java 21 以降がインストールされていることを確認してください。 + +5. **メモリ不足を確認**:: + + $ free -h + + メモリが不足している場合、ヒープサイズを調整するか、システムメモリを増設してください。 + +OpenSearch が起動しない +--------------------- + +**症状:** + +:: + + ERROR: bootstrap checks failed + +**原因:** + +システムの設定が OpenSearch の要件を満たしていない。 + +**解決方法:** + +1. **vm.max_map_count の設定**:: + + $ sudo sysctl -w vm.max_map_count=262144 + + 永続的に設定:: + + $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf + $ sudo sysctl -p + +2. **ファイル記述子の上限を増やす**:: + + $ sudo vi /etc/security/limits.conf + + 以下を追加:: + + opensearch - nofile 65535 + opensearch - nproc 4096 + +3. **メモリロックの設定**:: + + $ sudo vi /etc/security/limits.conf + + 以下を追加:: + + opensearch - memlock unlimited + +4. OpenSearch を再起動:: + + $ sudo systemctl restart opensearch + +インデックスを作成できない（辞書ファイルのパス） +------------------------------------------------ + +**症状:** + +|Fess| にアクセスすると HTTP 404 が返り、 ``fess.log`` に次のエラーが出力される:: + + Failed to create index: index=fess, path=fess_indices/fess.json + ... reason=Resource path must be inside config directory: /var/lib/opensearch/data/config/ja/mapping.txt + +**原因:** + +OpenSearch 3.8.0 以降は、辞書ファイルが OpenSearch の設定ディレクトリの外にあるとインデックスの作成を拒否します。 +``configsync.config_path`` と ``FESS_DICTIONARY_PATH`` が、設定ディレクトリの外（ ``data/config/`` など）を指しています。 + +**解決方法:** + +1. ``configsync.config_path`` と ``FESS_DICTIONARY_PATH`` を、OpenSearch の設定ディレクトリの下のディレクトリに変更します。 + + - RPM/DEB 版: ``/etc/opensearch/dictionary/`` + - ZIP 版: ``/path/to/opensearch-3.9.0/config/dictionary/`` + +2. 既存の辞書ファイルがある場合は、新しいディレクトリへコピーします。 +3. OpenSearch、 |Fess| の順に再起動します。 + +詳細は :doc:`install-linux` を参照してください。 + +ポート番号の競合 +-------------- + +**症状:** + +:: + + Address already in use + +**解決方法:** + +1. 使用中のポートを確認:: + + $ sudo ss -tuln | grep 8080 + $ sudo lsof -i :8080 + +2. 使用中のプロセスを停止、または Fess のポート番号を変更 + + ポート番号の変更は :doc:`ポートとネットワーク設定 <../config/setup-port-network>` を参照してください。 + +接続の問題 +======== + +Fess が OpenSearch に接続できない +------------------------------- + +**症状:** + +ログに以下のようなエラーが表示される:: + + Connection refused + または + No route to host + +**解決方法:** + +1. **OpenSearch が起動しているか確認**:: + + $ curl http://localhost:9200/ + +2. **接続URL を確認** + + ``fess.in.sh`` または ``fess.in.bat`` で設定されている URL が正しいか確認:: + + SEARCH_ENGINE_HTTP_URL=http://localhost:9200 + +3. **ファイアウォールを確認**:: + + $ sudo firewall-cmd --list-all + + ポート 9200 が開放されているか確認します。 + +4. **ネットワーク接続を確認** + + 別のホストで OpenSearch を実行している場合:: + + $ ping opensearch-host + $ telnet opensearch-host 9200 + +ブラウザーから Fess にアクセスできない +---------------------------------- + +**症状:** + +ブラウザーで http://localhost:8080/ にアクセスできない。 + +**解決方法:** + +1. **Fess が起動しているか確認**:: + + $ ps aux | grep fess + +2. **ローカルホストでアクセスを試行**:: + + $ curl http://localhost:8080/ + +3. **ファイアウォールを確認**:: + + $ sudo firewall-cmd --list-all + + ポート 8080 が開放されているか確認します。 + +4. **別のホストからアクセスする場合** + + Fess がローカルホスト以外でリッスンしているか確認:: + + $ ss -tuln | grep 8080 + + ``127.0.0.1:8080`` の場合は、``0.0.0.0:8080`` または特定の IP アドレスでリッスンするように設定を変更します。 + +パフォーマンスの問題 +================== + +検索が遅い +-------- + +**原因:** + +- インデックスサイズが大きい +- メモリ不足 +- ディスク I/O が遅い +- クエリが複雑 + +**解決方法:** + +1. **ヒープサイズを増やす** + + ``FESS_HEAP_SIZE`` を環境変数として渡して |Fess| を起動します:: + + $ FESS_HEAP_SIZE=4g bin/fess + + ``bin/fess.in.sh`` で設定する場合は、ヒープサイズを決めている行（``FESS_MIN_MEM`` の既定値を設定している行）\ **より前**\ に ``FESS_HEAP_SIZE=4g`` を書きます。ファイルの末尾に追記しても、その時点でヒープサイズは決まっているため反映されません。RPM/DEB 版は ``/etc/sysconfig/fess``\ （DEB 版は ``/etc/default/fess``）に設定します。 + + OpenSearch のヒープサイズも調整:: + + export OPENSEARCH_JAVA_OPTS="-Xms4g -Xmx4g" + +2. **SSD を使用する** + + ディスク I/O がボトルネックの場合、SSD に移行します。 + +3. **キャッシュを有効化** + + 設定ファイルでクエリキャッシュを有効化します。 + +クロールが遅い +----------- + +**原因:** + +- クロール間隔が長い +- 対象サイトの応答が遅い +- スレッド数が少ない + +**解決方法:** + +1. **クロール間隔を調整** + + 管理画面でクロール設定の「間隔」を短くします（ミリ秒単位）。 + + .. warning:: + + 間隔を短くしすぎると、対象サイトに負荷がかかります。適切な値を設定してください。 + +2. **スレッド数を増やす** + + 管理画面でクロール設定の「スレッド数」を増やします。デフォルトは、ウェブクロールが 1、ファイルシステムのクロールが 5 です。 + +3. **タイムアウト値を調整** + + 応答の遅いサイトの場合、タイムアウト値を増やします。 + +データの問題 +========== + +検索結果が表示されない +-------------------- + +**原因:** + +- インデックスが作成されていない +- クロールが失敗している +- 検索クエリが間違っている + +**解決方法:** + +1. **インデックスを確認**:: + + $ curl http://localhost:9200/_cat/indices?v + + |Fess| のインデックスが存在するか確認します。 + +2. **クロールログを確認** + + 管理画面で「システム情報 > ログファイル」から ``fess-crawler.log`` などのログをダウンロードし、エラーがないか調べます。 + +3. **クロールを再実行** + + 管理画面で「システム > スケジューラ」から「Default Crawler」を実行します。 + +4. **検索クエリをシンプルにする** + + まず簡単なキーワードで検索して、結果が返されるか確認します。 + +インデックスが破損している +------------------------ + +**症状:** + +検索時にエラーが発生する、または予期しない結果が返される。 + +**解決方法:** + +1. **インデックスを削除して再作成** + + .. warning:: + + インデックスを削除すると、すべての検索データが失われます。必ずバックアップを取得してください。 + + :: + + $ curl -X DELETE http://localhost:9200/fess* + +2. **Fess を再起動** + + インデックスは |Fess| の起動時に作成されます。削除した直後は、ユーザー情報のインデックスも失われているため管理画面にログインできません（``/api/v2/health`` は ``200`` を返したままです）。|Fess| を再起動すると、インデックスと既定のジョブ、初期ユーザー（``admin``）が作り直されます。 + +3. **クロールを再実行** + + 管理画面から「Default Crawler」を実行して、検索対象のドキュメントを再度登録します。 + +Docker 固有の問題 +=============== + +コンテナが起動しない +------------------ + +**症状:** + +``docker compose up`` でコンテナが起動しない。 + +**解決方法:** + +1. **ログを確認**:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs + +2. **メモリ不足を確認** + + Docker に割り当てられているメモリを増やします（Docker Desktop の設定から）。 + +3. **ポート競合を確認**:: + + $ docker ps + + 他のコンテナがポート 8080 または 9200 を使用していないか確認します。 + +4. **Docker Compose ファイルを確認** + + YAML ファイルの構文エラーがないか確認します:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml config + +コンテナは起動するが Fess にアクセスできない +---------------------------------------- + +**解決方法:** + +1. **コンテナの状態を確認**:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps + +2. **ログを確認**:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs fess + +3. **ネットワーク設定を確認**:: + + $ docker network ls + $ docker network inspect + +Windows 固有の問題 +================ + +パスの問題 +-------- + +**症状:** + +パスに空白や日本語が含まれる場合、エラーが発生する。 + +**解決方法:** + +パスに空白や日本語を含まないディレクトリにインストールしてください。 + +例:: + + C:\opensearch (推奨) + C:\Program Files\opensearch (非推奨) + +サービスとして登録できない +------------------------ + +**解決方法:** + +NSSM などのサードパーティツールを使用して、Windows サービスとして登録します。 + +詳細は :doc:`install-windows` を参照してください。 + +その他の問題 +========== + +ログレベルの変更 +-------------- + +詳細なログを確認する場合、ログレベルを DEBUG に変更します。 + +``log4j2.xml`` を編集:: + + + +データベースのリセット +-------------------- + +設定をリセットする場合、OpenSearch のインデックスを削除します:: + + $ curl -X DELETE 'http://localhost:9200/fess_config.*' + +.. warning:: + + このコマンドを実行すると、すべての設定データが削除されます。 + +管理者パスワードを忘れた場合 +---------------------------- + +管理者のパスワードを忘れた場合は、OpenSearch の ``fess_user.user`` インデックスにあるユーザーのドキュメントを直接更新して、パスワードを再設定できます。パスワードは ``password`` フィールドに ``{bcrypt}$2a$...`` の形式のハッシュで保存されています。更新は |Fess| を再起動しなくても有効になります。 + +1. 新しいパスワードのハッシュを作成します。|Fess| が受け付けるのは ``$2a$`` で始まる bcrypt のハッシュだけなので、 ``htpasswd`` （ ``apache2-utils`` や ``httpd-tools`` パッケージに含まれます）が出力する ``$2y$`` を ``$2a$`` に置き換えます。 ``NewPassword`` は新しいパスワードに置き換えてください:: + + $ HASH=$(htpasswd -bnBC 10 "" 'NewPassword' | tr -d ':\n' | sed 's/^\$2y/$2a/') + +2. admin ユーザーのドキュメントのパスワードを更新します。初期状態の admin ユーザーのドキュメント ID は ``YWRtaW4=`` です:: + + $ curl -X POST 'http://localhost:9200/fess_user.user/_update/YWRtaW4=?refresh=true' \ + -H 'Content-Type: application/json' \ + -d "{\"doc\":{\"password\":\"{bcrypt}${HASH}\"}}" + + 別のユーザーのパスワードを再設定する場合は、 ``curl 'http://localhost:9200/fess_user.user/_search?q=name:ユーザー名'`` で ``_id`` を調べて、その ID を指定します。OpenSearch に認証を設定している場合は、curl に認証情報を指定してください。 + +3. 新しいパスワードで管理画面にログインできることを確認します。コマンドの履歴にパスワードが残る場合は、ログイン後に [ユーザー > ユーザー] でパスワードを設定し直してください。 + +サポート情報 +========== + +問題が解決しない場合は、以下のサポートリソースを利用してください： + +コミュニティサポート +------------------ + +- **Issues**: https://github.com/codelibs/fess/issues + + 問題を報告する際は、以下の情報を含めてください： + + - Fess のバージョン + - OpenSearch のバージョン + - OS とバージョン + - エラーメッセージ（ログから抜粋） + - 再現手順 + +- **フォーラム**: https://discuss.codelibs.org/ + +商用サポート +---------- + +商用サポートが必要な場合は、N2SM, Inc. にご相談ください： + +- **Web**: https://www.n2sm.net/ + +デバッグ情報の収集 +================ + +問題を報告する際に、以下の情報を収集しておくと役立ちます： + +1. **バージョン情報**\ （ ``bin/fess -v`` は 15.10 以降で使用できます）:: + + $ /path/to/fess/bin/fess -v + $ /path/to/opensearch/bin/opensearch --version + $ java -version + +2. **システム情報**:: + + $ uname -a + $ cat /etc/os-release + $ free -h + $ df -h + +3. **ログファイル**:: + + $ tar czf fess-logs.tar.gz /path/to/fess/logs/ + +4. **設定ファイル**\ （機密情報を削除してから）:: + + $ tar czf fess-config.tar.gz /path/to/fess/app/WEB-INF/conf/ + +5. **OpenSearch の状態**:: + + $ curl http://localhost:9200/_cluster/health?pretty + $ curl http://localhost:9200/_cat/indices?v diff --git a/ja/15.10/install/uninstall.rst b/ja/15.10/install/uninstall.rst new file mode 100644 index 000000000..a167cd838 --- /dev/null +++ b/ja/15.10/install/uninstall.rst @@ -0,0 +1,481 @@ +================== +アンインストール手順 +================== + +このページでは、 |Fess| を完全にアンインストールする手順について説明します。 + +.. warning:: + + **アンインストール前の重要な注意事項** + + - アンインストールすると、すべてのデータが削除されます + - 重要なデータがある場合は、必ずバックアップを取得してください + - バックアップ手順については :doc:`upgrade` を参照してください + +アンインストール前の準備 +====================== + +バックアップの取得 +---------------- + +必要なデータをバックアップしてください： + +1. **設定データ** + + 管理画面の「システム」→「バックアップ」からダウンロードします。 + この操作で、各種設定（クロール設定を含む）や検索ログなどをまとめてエクスポートできます。 + +2. **カスタマイズした設定ファイル** + + ZIP 版:: + + $ cp -r /path/to/fess/app/WEB-INF/conf /backup/ + $ cp -r /path/to/fess/app/WEB-INF/classes /backup/ + + RPM/DEB 版:: + + $ sudo cp -r /etc/fess /backup/ + +.. note:: + + |Fess| のインデックスや設定の大部分は OpenSearch に保存されます。 + インデックスデータをバックアップする場合は、OpenSearch のスナップショット機能を使用します。 + 詳細な手順は :doc:`upgrade` を参照してください。 + +サービスの停止 +------------ + +アンインストール前に、すべてのサービスを停止します。 + +ZIP 版:: + + $ ps aux | grep -E 'fess|opensearch' + $ kill + $ kill + +RPM/DEB 版:: + + $ sudo systemctl stop fess.service + $ sudo systemctl stop opensearch.service + +Docker 版:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +ZIP 版のアンインストール +============================= + +ステップ 1: Fess の削除 +--------------------- + +インストールディレクトリを削除します:: + + $ rm -rf /path/to/fess-15.10.0 + +ステップ 2: OpenSearch の削除 +-------------------------- + +OpenSearch のインストールディレクトリを削除します:: + + $ rm -rf /path/to/opensearch-3.9.0 + +ステップ 3: データディレクトリの削除（オプション） +------------------------------------------- + +|Fess| のインデックスデータは OpenSearch に保存されます。 +デフォルトでは OpenSearch のインストールディレクトリ内（``opensearch-3.9.0/data`` など）に保存されますが、 +``path.data`` で別の場所を指定している場合は、そのディレクトリも削除してください:: + + $ rm -rf /path/to/data + +ステップ 4: ログディレクトリの削除（オプション） +----------------------------------------- + +ログファイルを削除します:: + + $ rm -rf /path/to/fess-15.10.0/logs + $ rm -rf /path/to/opensearch-3.9.0/logs + +RPM 版のアンインストール +====================== + +ステップ 1: Fess のアンインストール +--------------------------------- + +RPM パッケージをアンインストールします:: + + $ sudo rpm -e fess + +.. note:: + + |Fess| パッケージのアンインストール時には、パッケージの削除スクリプトによって + ``fess`` サービスの停止・無効化と、``fess`` ユーザーおよびグループの削除が自動的に実行されます。 + 以降のステップは、これらが確実に削除されたことを確認するため、または + データや設定ファイルを手動で削除するために実施します。 + +ステップ 2: OpenSearch のアンインストール +-------------------------------------- + +:: + + $ sudo rpm -e opensearch + +ステップ 3: サービスの無効化の確認 +------------------------------- + +通常はパッケージ削除時にサービスが無効化されますが、念のため確認・無効化する場合は以下を実行します。 + +systemd の場合:: + + $ sudo systemctl disable fess.service + $ sudo systemctl disable opensearch.service + $ sudo systemctl daemon-reload + +古い SysV init（chkconfig）環境の場合:: + + $ sudo /sbin/chkconfig --del fess + $ sudo /sbin/chkconfig --del opensearch + +ステップ 4: データディレクトリの削除 +---------------------------------- + +.. warning:: + + この操作を実行すると、すべてのインデックスデータが完全に削除されます。 + +データディレクトリはパッケージのアンインストールでは削除されないため、手動で削除します:: + + $ sudo rm -rf /var/lib/fess + $ sudo rm -rf /var/lib/opensearch + +ステップ 5: 設定ファイルの削除 +---------------------------- + +設定ファイルと環境設定ファイルを削除します:: + + $ sudo rm -rf /etc/fess + $ sudo rm -rf /etc/sysconfig/fess + $ sudo rm -rf /etc/opensearch + +.. note:: + + RPM では ``/etc/fess`` 内の設定ファイルが ``.rpmsave`` という名前で残る場合があります。 + 完全に削除するには、上記のように手動で削除してください。 + +ステップ 6: ログファイルの削除 +---------------------------- + +:: + + $ sudo rm -rf /var/log/fess + $ sudo rm -rf /var/log/opensearch + +ステップ 7: 一時ディレクトリの削除（オプション） +----------------------------------------- + +:: + + $ sudo rm -rf /var/tmp/fess + +ステップ 8: ユーザーとグループの削除（オプション） +------------------------------------------- + +通常はパッケージ削除時に ``fess`` ユーザー・グループは削除されます。 +残っている場合や、OpenSearch 用のユーザー・グループを削除する場合は、以下を実行します:: + + $ sudo userdel fess + $ sudo groupdel fess + $ sudo userdel opensearch + $ sudo groupdel opensearch + +DEB 版のアンインストール +====================== + +ステップ 1: Fess のアンインストール +--------------------------------- + +DEB パッケージをアンインストールします:: + + $ sudo dpkg -r fess + +設定ファイルや環境設定ファイルも含めて完全に削除する場合は、purge を使用します:: + + $ sudo dpkg -P fess + +.. note:: + + ``dpkg -r``\ （remove）では、設定ファイル（conffile）である ``/etc/default/fess`` などは残ります。 + ``dpkg -P``\ （purge）を使用すると、これらの設定ファイルと ``fess`` ユーザー・グループも削除されます。 + +ステップ 2: OpenSearch のアンインストール +-------------------------------------- + +:: + + $ sudo dpkg -r opensearch + +または、設定ファイルも含めて削除:: + + $ sudo dpkg -P opensearch + +ステップ 3: サービスの無効化の確認 +------------------------------- + +通常はパッケージ削除時にサービスが無効化されます。念のため確認・無効化する場合は以下を実行します:: + + $ sudo systemctl disable fess.service + $ sudo systemctl disable opensearch.service + $ sudo systemctl daemon-reload + +ステップ 4: データディレクトリの削除 +---------------------------------- + +.. warning:: + + この操作を実行すると、すべてのインデックスデータが完全に削除されます。 + +:: + + $ sudo rm -rf /var/lib/fess + $ sudo rm -rf /var/lib/opensearch + +ステップ 5: 設定ファイルの削除（dpkg -P を使用しなかった場合） +--------------------------------------------------------- + +:: + + $ sudo rm -rf /etc/fess + $ sudo rm -rf /etc/default/fess + $ sudo rm -rf /etc/opensearch + +ステップ 6: ログファイルの削除 +---------------------------- + +:: + + $ sudo rm -rf /var/log/fess + $ sudo rm -rf /var/log/opensearch + +ステップ 7: ユーザーとグループの削除（オプション） +------------------------------------------- + +``dpkg -P`` を使用しなかった場合、``fess`` ユーザー・グループが残ります。 +削除する場合は以下を実行します:: + + $ sudo userdel fess + $ sudo groupdel fess + $ sudo userdel opensearch + $ sudo groupdel opensearch + +Docker 版のアンインストール +========================= + +ステップ 1: コンテナとネットワークの削除 +------------------------------------ + +コンテナ、および Docker Compose が作成したネットワーク（``search_net``）を削除します:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +ステップ 2: ボリュームの削除 +-------------------------- + +.. warning:: + + この操作を実行すると、すべてのデータが完全に削除されます。 + +|Fess| のデータ（インデックスや辞書など）は OpenSearch のボリュームに保存されます。 +まず、ボリューム一覧を確認します:: + + $ docker volume ls + +OpenSearch 関連のボリュームを削除します:: + + $ docker volume rm _search01_data + $ docker volume rm _search01_dictionary + +.. note:: + + ボリューム名には、Docker Compose のプロジェクト名（通常は Compose ファイルを配置した + ディレクトリ名）が接頭辞として付きます。\ ``docker volume ls`` で実際の名前を確認してください。 + +コンテナとボリュームを一括で削除する場合は、``down`` に ``-v`` オプションを付けます:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down -v + +ステップ 3: イメージの削除（オプション） +------------------------------------ + +Docker イメージを削除してディスクスペースを解放する場合:: + + $ docker images | grep fess + $ docker rmi ghcr.io/codelibs/fess:15.10.0 + $ docker rmi ghcr.io/codelibs/fess-opensearch:3.9.0 + +ステップ 4: Compose ファイルの削除 +-------------------------------- + +:: + + $ rm compose.yaml compose-opensearch3.yaml + +アンインストールの確認 +==================== + +すべてのコンポーネントが削除されたことを確認します。 + +プロセスの確認 +------------ + +:: + + $ ps aux | grep fess + $ ps aux | grep opensearch + +何も表示されなければ、プロセスは停止しています。 + +ポートの確認 +---------- + +:: + + $ sudo ss -tuln | grep 8080 + $ sudo ss -tuln | grep 9200 + +ポートが使用されていないことを確認します。 + +ファイルの確認 +------------ + +ZIP 版:: + + $ ls /path/to/fess-15.10.0 # ディレクトリが存在しないことを確認 + +RPM/DEB 版:: + + $ ls /var/lib/fess # ディレクトリが存在しないことを確認 + $ ls /etc/fess # ディレクトリが存在しないことを確認 + +Docker 版:: + + $ docker ps -a | grep -E 'fess01|search01' # コンテナが存在しないことを確認 + $ docker volume ls | grep search01 # ボリュームが存在しないことを確認 + +パッケージの確認 +-------------- + +RPM 版:: + + $ rpm -qa | grep fess + $ rpm -qa | grep opensearch + +DEB 版:: + + $ dpkg -l | grep fess + $ dpkg -l | grep opensearch + +何も表示されなければ、パッケージは削除されています。 + +部分的なアンインストール +====================== + +Fess のみを削除して OpenSearch を残す +----------------------------------- + +OpenSearch を他のアプリケーションでも使用している場合、Fess のみを削除できます。 + +1. Fess を停止 +2. Fess のパッケージまたはディレクトリを削除 +3. Fess のデータディレクトリを削除（``/var/lib/fess`` など） +4. OpenSearch 内に作成された |Fess| のインデックスを削除 + + |Fess| のインデックスの名前は ``fess`` で始まります（``fess.*``、``fess_config.*``、``fess_user.*``、``fess_log.*``、``fess_crawler.*``、``fess_suggest*`` など）。次のコマンドでまとめて削除できます。 + + :: + + $ curl -X DELETE 'http://localhost:9200/fess*' + + 削除する前に ``curl 'http://localhost:9200/_cat/indices?v'`` で、``fess`` で始まる名前のほかのアプリケーションのインデックスがないことを確認してください。辞書を同期する ``configsync`` インデックスも、ほかのアプリケーションで使っていなければ削除できます。 + +5. OpenSearch は削除しない + +OpenSearch のみを削除して Fess を残す +----------------------------------- + +.. warning:: + + OpenSearch を削除すると、Fess は動作しなくなります。 + 別の OpenSearch クラスターに接続するように設定を変更してください。 + +1. OpenSearch を停止 +2. OpenSearch のパッケージまたはディレクトリを削除 +3. OpenSearch のデータディレクトリを削除（``/var/lib/opensearch`` など） +4. Fess の設定を更新して、別の OpenSearch クラスターを指定 + +トラブルシューティング +==================== + +パッケージが削除できない +---------------------- + +**症状:** + +``rpm -e`` または ``dpkg -r`` でエラーが発生する。 + +**解決方法:** + +1. サービスが停止していることを確認:: + + $ sudo systemctl stop fess.service + +2. 依存関係を確認:: + + $ rpm -qa | grep fess + $ dpkg -l | grep fess + +3. 強制削除（最終手段）:: + + $ sudo rpm -e --nodeps fess + $ sudo dpkg -r --force-all fess + +ディレクトリが削除できない +------------------------ + +**症状:** + +``rm -rf`` でディレクトリが削除できない。 + +**解決方法:** + +1. 権限を確認:: + + $ ls -ld /path/to/directory + +2. sudo で削除:: + + $ sudo rm -rf /path/to/directory + +3. プロセスがファイルを使用していないか確認:: + + $ sudo lsof | grep /path/to/directory + +再インストールの準備 +================== + +アンインストール後に再インストールする場合は、以下を確認してください： + +1. すべてのプロセスが停止していること +2. すべてのファイルとディレクトリが削除されていること +3. ポート 8080 および 9200 が使用されていないこと +4. 以前の設定ファイルが残っていないこと + +再インストール手順については、:doc:`install` を参照してください。 + +次のステップ +========== + +アンインストールが完了したら： + +- 新しいバージョンをインストールする場合は :doc:`install` を参照 +- データを移行する場合は :doc:`upgrade` を参照 +- 代替の検索ソリューションを検討する場合は、Fess の公式サイトを参照 diff --git a/ja/15.10/install/upgrade.rst b/ja/15.10/install/upgrade.rst new file mode 100644 index 000000000..b974c9d1b --- /dev/null +++ b/ja/15.10/install/upgrade.rst @@ -0,0 +1,1622 @@ +==================== +アップグレード手順 +==================== + +このページでは、 |Fess| を以前のバージョンから最新版にアップグレードする手順について説明します。 + +.. warning:: + + **アップグレード前の重要な注意事項** + + - アップグレード前に必ずバックアップを取得してください + - テスト環境で事前にアップグレードを検証することを強く推奨します + - アップグレード中はサービスが停止するため、適切なメンテナンス時間を設定してください + - バージョンによっては、設定ファイルの形式が変更されている場合があります + +対応バージョン +============== + +このアップグレード手順は、以下のバージョン間のアップグレードに対応しています： + +- Fess 14.x → Fess 15.10 +- Fess 15.x → Fess 15.10 + +.. important:: + + |Fess| 14.x は OpenSearch 2.x 系、\ |Fess| 15.10 は OpenSearch 3.9.0 に対応しています。 + |Fess| 用の OpenSearch プラグインは OpenSearch のバージョンと完全に一致している必要があるため、 + 14.x からアップグレードする場合は OpenSearch のメジャーバージョンアップも必須です。 + :ref:`upgrade-opensearch` を参照してください。 + +.. note:: + + さらに古いバージョン（13.x 以前）からアップグレードする場合は、段階的なアップグレードが必要な場合があります。 + 詳細はリリースノートを確認してください。 + +アップグレード前の準備 +====================== + +バージョン互換性の確認 +---------------------- + +アップグレード先のバージョンと現在のバージョンの互換性を確認してください。 + +- `リリースノート `__ +- :doc:`prerequisites` - |Fess| 15.10 の動作環境（Java、OpenSearch のバージョン） + +ダウンタイムの計画 +------------------ + +アップグレード作業には、システムの停止が必要です。以下を考慮してダウンタイムを計画してください： + +- バックアップ時間: 10分 〜 数時間（データ量による） +- アップグレード時間: 10 〜 30分 +- 動作確認時間: 30分 〜 1時間 +- 予備時間: 30分 + +**推奨メンテナンス時間**: 合計 2 〜 4時間 + +ステップ 1: データのバックアップ +================================ + +アップグレード前に、すべてのデータをバックアップしてください。 + +設定データのバックアップ +------------------------ + +1. **管理画面からのバックアップ** + + 管理画面にログインし、「システム情報」→「バックアップ」をクリックします。 + + バックアップページには、以下の設定データが項目ごとに一覧表示されます。 + 各行をクリックしてダウンロードします（単一の ZIP ファイルではなく、項目ごとの個別ファイルです。 + 一括ダウンロードの機能はないため、必要な項目を 1 つずつダウンロードします）。 + + - ``fess_basic_config.bulk`` - 設定インデックス（クロール設定、スケジューラー、ラベル、 + キーマッチ、ロール、Web/ファイル認証など 19 インデックス） + - ``fess_config.bulk`` - 上記 19 インデックスに加えて、クロール情報、障害 URL、ジョブログ、 + サムネイルキューなどの実行時データを含む 25 インデックス（15.8 まで。15.10 ではユーザータグを + 保持する ``tag_type`` インデックスが加わり 26 インデックス） + - ``fess_user.bulk`` - ユーザー、ロール、グループ + - ``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 つで十分です。ただし、バックアップ元が 15.10 以降でユーザータグを使っている場合は、ユーザータグを保持する ``tag_type`` インデックスが ``fess_basic_config.bulk`` には含まれないため、\ ``fess_config.bulk`` も取得してください（ :doc:`../admin/tagtype-guide` を参照）。 + + .. note:: + + 検索ログやクリックログなどのログデータ（``search_log.ndjson``、``click_log.ndjson``、 + ``favorite_log.ndjson``、``user_info.ndjson``。15.10 では ``chat_log.ndjson`` も表示されます）も + 同じページからダウンロードできます。 + 設定のみをバックアップする場合は不要です。なお、これらの ``*.ndjson`` ファイルは + バックアップページからアップロードして復元することはできません + （「ロールバック手順」を参照）。 + +2. **設定ファイルのバックアップ** + + ZIP 版:: + + $ 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 版:: + + $ 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`` などを指定する環境変数ファイルです。 + ZIP 版でこれらに相当する設定は ``bin/fess.in.sh`` にあります。 + +3. **カスタマイズした設定ファイル** + + カスタマイズした設定ファイルがある場合、それらもバックアップします:: + + $ cp /path/to/fess/app/WEB-INF/classes/log4j2.xml /backup/ + $ cp /path/to/fess/lib/classes/tomcat_config.properties /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 のスナップショット機能を使用して、インデックスをバックアップします。 + +.. note:: + + ファイルシステムリポジトリ（``fs``）を登録するには、事前に OpenSearch の ``opensearch.yml`` の + ``path.repo`` にバックアップ先ディレクトリを指定し、OpenSearch を再起動しておく必要があります。 + +1. リポジトリの設定:: + + $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup" -H 'Content-Type: application/json' -d' + { + "type": "fs", + "settings": { + "location": "/backup/opensearch/snapshots" + } + }' + +2. スナップショットの作成:: + + $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup/snapshot_1?wait_for_completion=true" + +3. スナップショットの確認:: + + $ curl -X GET "http://localhost:9200/_snapshot/fess_backup/snapshot_1" + +方法 2: ディレクトリごとバックアップ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +OpenSearch を停止してから、データディレクトリをバックアップします。 + +:: + + $ sudo systemctl stop opensearch + $ sudo tar czf /backup/opensearch-data-$(date +%Y%m%d).tar.gz /var/lib/opensearch/data + $ sudo systemctl start opensearch + +Docker 版のバックアップ +----------------------- + +OpenSearch のデータは Docker ボリュームに保存されます。\ ``compose-opensearch3.yaml`` では、 +インデックスデータ用の ``search01_data`` と、辞書ファイル用の ``search01_dictionary`` の +2 つのボリュームが定義されています。 + +.. note:: + + 実際のボリューム名には、Compose のプロジェクト名（既定では Compose ファイルを配置した + ディレクトリ名）が接頭辞として付与されます。正確な名前は次のコマンドで確認してください:: + + $ docker volume ls + +コンテナーを停止してから、ボリュームをバックアップします。\ ``docker run`` の ``-v`` には、 +接頭辞を含む実際のボリューム名を指定します:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop + $ 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 を停止します。 + +ZIP 版には停止用のスクリプトは同梱されていません。\ ``bin/fess`` を ``-p`` オプション付きで +起動していた場合は、PID ファイルを使って停止します:: + + $ kill $(cat /path/to/fess/fess.pid) + $ kill + +``-p`` を指定せずに起動していた場合は、プロセス ID を確認して ``kill`` します +（``-d`` だけでは PID ファイルは作成されません）。 + +RPM/DEB 版 (systemd):: + + $ sudo systemctl stop fess.service + $ sudo systemctl stop opensearch.service + +Docker 版:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +.. warning:: + + ステップ 3 を始める前に |Fess| が停止していることを確認してください。起動中の |Fess| のパッケージや + ファイルを入れ替えないでください。起動中の 15.8 の |Fess| で DEB パッケージを 15.10 のものに + 入れ替えたところ、|Fess| を再起動するまで検索画面が ``404`` を返しました。パッケージ版では + ``systemctl status fess.service`` で確認できます。 + +ステップ 3: 新しいバージョンのインストール +========================================== + +インストール方法により、手順が異なります。 + +ZIP 版 +------------- + +1. 新しいバージョンをダウンロードして展開:: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.zip + $ unzip fess-15.10.0.zip + + .. note:: + + |Fess| のアーカイブ版は ZIP 形式でのみ配布されています（``fess-15.10.0.tar.gz`` は + 提供されていません）。 + +2. 古いバージョンの設定をコピー:: + + $ cp /path/to/old-fess/app/WEB-INF/conf/system.properties /path/to/fess-15.10.0/app/WEB-INF/conf/ + $ cp /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.10.0/app/WEB-INF/classes/ + $ cp /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.10.0/bin/ + + .. warning:: + + ``fess_config.properties`` と ``fess.in.sh`` をそのままコピーすると、15.10 で既定値が変わった + 値も含めて、旧バージョンの値が引き継がれます。たとえば、アップグレード後に作成したジョブの + 既定は Groovy になります。後の 2 つのコマンドを実行する前に、各ファイルを ``fess-15.10.0`` + のファイルと比較し、自分で変更した値だけを移してください。確認すべき項目は + :ref:`upgrade-159-carried-over-config` を参照してください。 + +3. カスタマイズしている場合は、以下もコピーします:: + + # Tomcat の設定（SAML で必要な tomcat.sameSiteCookies=none もここにあります） + $ cp /path/to/old-fess/lib/classes/tomcat_config.properties /path/to/fess-15.10.0/lib/classes/ + # インストール済みプラグイン + $ cp -r /path/to/old-fess/app/WEB-INF/plugin/. /path/to/fess-15.10.0/app/WEB-INF/plugin/ + # 自分でアップロードした静的テーマ（テーマごとのディレクトリ。bootstrap は除く） + $ cp -r /path/to/old-fess/app/themes/ /path/to/fess-15.10.0/app/themes/ + + .. warning:: + + 旧バージョンの ``tomcat_config.properties`` をコピーしないと、 ``tomcat.sameSiteCookies`` は + 何も知らせずに既定値の ``lax`` に戻り、SAML ログインが動作しなくなります + （ :ref:`upgrade-159-saml` を参照）。このファイルの同梱の内容は 15.8.0 と 15.10 で同じなので、 + そのままコピーできます。 + + .. warning:: + + ``log4j2.xml`` を 15.10 のファイルに上書きコピーしないでください。15.10 のファイルは + ``RequestLoggingFilter`` のロガーを ``warn`` に固定しており、15.8 のファイルをコピーすると + この設定が失われます。ログレベルを DEBUG にすると、リクエストヘッダー（ ``Authorization`` を含む）と + リクエストパラメーター（ログインフォームに入力したパスワードを含む）がログに書き出されます。 + 2 つのファイルを ``diff`` で比較し、自分で変更した内容だけを 15.10 のファイルに再適用してください。 + + .. warning:: + + ``app/themes/`` ディレクトリ全体はコピーしないでください。このディレクトリには |Fess| に + 同梱のテーマ ``bootstrap`` も入っており、15.10 のものに上書きすると、15.10 の検索画面が + 15.8 版のテーマに置き換わります。コピーするのは自分で作成したテーマのディレクトリだけにして + ください。 |Fess| プロジェクトが公開しているテーマは、 ``bin/fess-setup install theme `` + で 15.10 向けのビルドをインストールしてください（ :doc:`fess-setup` を参照）。 + + .. warning:: + + 管理画面「デザイン」で編集した JSP（``app/WEB-INF/view/``）はコピーしないでください。 + 15.10 の検索画面は静的テーマで、これらの JSP を使いません。変更内容の移し先は + :ref:`upgrade-159-static-theme` を参照してください。 + + .. note:: + + ``app/WEB-INF/plugin/`` からコピーしたプラグインは、旧バージョン向けにビルドされています。 + コピーした後、 ``fess-15.10.0`` で ``bin/fess-setup upgrade plugins`` を実行し、15.10 向けに + ビルドされたバージョンに入れ替えてください（ :ref:`upgrade-plugin-versions` を参照）。 + +4. 設定差分を確認し、必要に応じて調整します + +RPM/DEB 版 +---------- + +新しいバージョンのパッケージをインストール:: + + # RPM + $ sudo rpm -Uvh fess-15.10.0.rpm + + # DEB + $ sudo dpkg -i fess-15.10.0.deb + +.. note:: + + RPM 版では ``/etc/fess/*`` の設定ファイルは ``%config(noreplace)`` として登録されているため、 + アップグレード時も保持されます（新しい既定のファイルは ``.rpmnew`` として併置されます）。 + 新しい設定オプションが追加されている場合は、手動で調整が必要です。変更を加えた + ``/etc/fess/fess_config.properties`` は、ZIP 版の手順でコピーしたファイルと同様に、15.10 でも + 旧バージョンの値のまま使われます。 :ref:`upgrade-159-carried-over-config` を参照してください。 + +.. warning:: + + DEB 版では、 ``/etc/fess`` 以下のファイル（ ``fess_config.properties`` や + ``tomcat_config.properties`` など）は、 ``/etc/default/fess``\ 、\ ``/etc/init.d/fess``\ 、 + ``/usr/lib/systemd/system/fess.service`` と同様に conffile として登録されています。15.8 からの + 最初のアップグレードでは、 ``dpkg`` は次のように扱います。 + + - 編集していないファイルは、確認なしに 15.10 のファイルへ置き換えられます。 + - 編集したファイルについては、 ``dpkg`` が確認を求めます。自分のファイルを残す場合（既定の回答、または + ``--force-confold`` ）は、15.10 のファイルが ``<ファイル名>.dpkg-dist`` として併置されます。新しいファイルを + インストールする場合（ ``Y`` または ``--force-confnew`` ）は、自分のファイルが + ``<ファイル名>.dpkg-old`` として保存されます。 + - 回答する人がいないとき、 ``dpkg -i`` と ``apt-get install -y`` は最初の確認で停止します。 + 無人でアップグレードする場合は ``--force-confold`` を指定してください（ ``--force-confdef`` でも確認は + 出なくなります）。たとえば ``sudo dpkg --force-confold -i fess-15.10.0.deb`` や + ``sudo apt-get install -y -o Dpkg::Options::=--force-confold ./fess-15.10.0.deb`` です。 + + いずれの場合も、事前に ``/etc/fess`` をバックアップしてください（ステップ 1）。残したファイルは 15.8 の値の + ままなので、そのまま使わず ``.dpkg-dist`` のファイルと比較してください（ + :ref:`upgrade-159-carried-over-config` を参照）。なお ``/etc/fess/system.properties`` はパッケージに + 含まれない実行時生成ファイルのため、上書きされません。 + +Docker 版 +--------- + +1. 新しいバージョンの Compose ファイルを取得:: + + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose.yaml + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose-opensearch3.yaml + +2. 新しいイメージを取得:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull + +.. _upgrade-opensearch: + +ステップ 4: OpenSearch のアップグレード +======================================= + +|Fess| 15.10 は OpenSearch 3.9.0 に対応しています。接続先の OpenSearch がこれより古い場合は、 +以下の手順でアップグレードしてください。 + +.. note:: + + この手順は ZIP 版および RPM/DEB 版で OpenSearch を手動運用している場合の手順です。 + Docker 版では、ステップ 3 で新しいイメージを取得すると OpenSearch とプラグインも + まとめて更新されるため、本ステップは不要です。 + +.. important:: + + |Fess| 15.10 は、チャンクベクトル検索（セマンティック検索）の利用有無にかかわらず、 + 検索インデックスの設定に ``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 からのアップグレードでは必ずこのケースに該当します。 + + OpenSearch 3.9.0 で取得したスナップショットは、3.8.0 以前の OpenSearch には復元できません。切り戻しに備えて、アップグレード前に取得したスナップショットを残しておいてください。 + +1. 新しいバージョンの OpenSearch をインストール + +2. プラグインを再インストール:: + + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + + .. note:: + + これらのプラグインのバージョンは、使用する OpenSearch のバージョンと一致させる必要があります。 + |Fess| 15.10 は OpenSearch 3.9.0 に対応しています。バージョンが一致しない場合、 + プラグインのインストールに失敗します。 + + |Fess| 用の 4 つのプラグインは maven.codelibs.org で公開しているため、URL で指定します。 ``opensearch-plugin install`` の ``groupId:artifactId:version`` 形式は Maven Central だけを参照します。 + +3. 辞書ディレクトリを OpenSearch の設定ディレクトリの下へ移動 + + OpenSearch 3.8.0 以降は、辞書ファイルが OpenSearch の設定ディレクトリの外にあるとインデックスの作成を拒否します。 + 以前の手順どおり ``configsync.config_path`` に ``/var/lib/opensearch/data/config/`` （ZIP 版では ``/path/to/opensearch/data/config/``）など設定ディレクトリの外を指定している場合、 + |Fess| はインデックスを作成できず、起動しません。 + RPM/DEB 版では、次のように辞書ファイルを ``/etc/opensearch/dictionary/`` へコピーします:: + + $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary + $ sudo cp -a /var/lib/opensearch/data/config/. /etc/opensearch/dictionary/ + $ sudo chown -R opensearch:opensearch /etc/opensearch/dictionary + + そのうえで、 ``/etc/opensearch/opensearch.yml`` の ``configsync.config_path`` と、 |Fess| の ``FESS_DICTIONARY_PATH`` （RPM 版は ``/etc/sysconfig/fess`` 、DEB 版は ``/etc/default/fess``）を、どちらも ``/etc/opensearch/dictionary/`` に変更します。 + ZIP 版では、OpenSearch の ``config/dictionary/`` を使用します。詳細は :doc:`install-linux` を参照してください。 + +4. OpenSearch を起動:: + + $ sudo systemctl start opensearch.service + +ステップ 5: 新しいバージョンの起動 +================================== + +ZIP 版:: + + $ cd /path/to/fess-15.10.0 + $ ./bin/fess -d -p /path/to/fess-15.10.0/fess.pid + +.. note:: + + ``-p`` を指定すると PID ファイルが作成され、次回の停止時に + ``kill $(cat /path/to/fess-15.10.0/fess.pid)`` で停止できます。 + +RPM/DEB 版:: + + $ sudo systemctl start opensearch.service + $ sudo systemctl start fess.service + +Docker 版:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +ステップ 6: 動作確認 +==================== + +1. **ログの確認** + + エラーがないことを確認します。 + + 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/ にアクセスします。 + +3. **管理画面へのログイン** + + http://localhost:8080/admin にアクセスし、管理者アカウントでログインします。 + +4. **バージョンの確認** + + 管理画面で「システム情報」→「設定情報」をクリックし、「システムのプロパティ」に表示される + ``fess.version`` が新しいバージョンになっていることを確認します。 + +5. **検索の動作確認** + + 検索画面で検索を実行し、正常に結果が返されることを確認します。 + +ステップ 7: インデックスの再作成（推奨） +======================================== + +メジャーバージョンアップの場合、インデックスを再作成することを推奨します。 + +.. note:: + + 以下の手順はクロールの再実行であり、インデックスのマッピング（フィールド定義）自体は + 更新されません。チャンクベクトル検索（セマンティック検索）を新たに有効にする場合など、 + マッピングの更新を伴う再インデックスが必要な場合は、管理画面 > システム情報 > メンテナンス の + 「再インデクシング」を別途実行してください。詳細は + :ref:`semantic-search-migration`\ （:doc:`../config/search-semantic`）を + 参照してください。 + + 15.8 以前で作成した文書インデックスを引き続き使う場合は、 :ref:`upgrade-reindex-new-fields` も参照してください。 + +.. warning:: + + 15.8 が受け付けた辞書のエントリーのうち、OpenSearch 3.9.0 が拒否するものがあります。たとえば + 同じ ``mapping`` のエントリーを 2 回保存している場合や、 ``kuromoji`` のトークンに空白が含まれる + 場合です。そのようなエントリーがあると「再インデクシング」は新しい文書インデックスを作成しません。 + ``fess.log`` には ``Failed to create index`` としか出力されず、古いインデックスが検索を提供し続けます。 + 「システム」→「辞書」で辞書をダウンロードし、重複または不正な行を削除してから再度アップロードし、 + 「再インデクシング」をもう一度実行してください。15.10 が保存しなくなったエントリーは + :ref:`upgrade-159-api-requests` を参照してください。 + +1. 既存のクロールスケジュールを確認 +2. 「システム」→「スケジューラ」から「Default Crawler」を実行 +3. クロールが完了するまで待機 +4. 検索結果を確認 + +.. warning:: + + 再インデクシングでは新しいマッピングでインデックスが作り直されるため、k-NN プラグインの + ない OpenSearch では失敗します。ステップ 4 の注意事項を確認してください。 + +15.8 から 15.10 へのアップグレード +================================= + +15.8 からアップグレードする場合、以下が互換性のない変更です。15.7 以前からアップグレードする場合も +これらがすべて当てはまります。「組み込み OpenSearch の廃止」から「既存の文書インデックスへの新しい +フィールドとかなの正規化の反映」までの各節（組み込み OpenSearch、スクリプトエンジン、S3 と SSO の +プラグイン、Index Exporter ジョブなど）と、このページの最後にある「15.10 固有の移行作業」をすべて +読んでください。 + +組み込み OpenSearch の廃止 +-------------------------- + +15.8 までは ``SEARCH_ENGINE_HTTP_URL`` を設定せずに ``bin/fess`` を起動すると、|Fess| が自身の +JVM 内で OpenSearch ノードを起動していました。15.10 ではこの構成がなくなり、検索エンジンは常に +別のサーバーになります。 + +``bin/fess.in.sh`` は既定で ``SEARCH_ENGINE_HTTP_URL=http://localhost:9200`` を設定します。 +接続先の OpenSearch がない場合、|Fess| は起動に失敗します。 ``bin/fess-setup install opensearch`` +で導入できます（Linux と Windows のみ。macOS には OpenSearch の公式配布がないため、Homebrew か +Docker を使用してください）。 + +また、 ``FESS_DICTIONARY_PATH`` をその OpenSearch の ``opensearch.yml`` にある ``configsync.config_path`` と一致させる必要があります。設定されていないか一致していないと、 |Fess| はインデックスを作成できません。15.10 の ``bin/fess.in.sh`` （Windows では ``bin\fess.in.bat`` ）は、 |Fess| のディレクトリの ``opensearch/`` に ``bin/fess-setup install opensearch`` で導入した OpenSearch が 1 つだけある場合に、これを自動で設定します。それ以外の OpenSearch を使う場合は、 :doc:`install-linux` または :doc:`install-windows` のとおりに設定してください。 + +あわせて次が廃止されました。 + +- ``es/`` ディレクトリ（ ``es/modules`` 、 ``es/plugins`` 、 ``es/data`` ） +- ``-Dfess.es.dir`` と ``SEARCH_ENGINE_HOME`` +- ``bin/module.xml`` と ``bin/plugin.xml`` +- 旧 ``elasticsearch.*`` 設定キーのフォールバック + +また、OpenSearch 3 より前のバージョンに接続した場合、15.8 まではエラーログを出して起動を続行して +いましたが、15.10 では起動に失敗します。これらのバージョンは全文書を走査する処理が使う +``_shard_doc`` ソートを実装しておらず、HTTP 経由では失敗せずに応答が返らなくなるためです。 + +.. warning:: + + 組み込み OpenSearch で運用していた場合、インデックスデータは引き継げません。外部の + OpenSearch サーバーを新しく構築し、管理画面「バックアップ」で設定を移したうえで + 再クロールしてください。バックアップに含まれるのはクロール設定・ユーザー・ログで、 + **クロール済みの文書は含まれません**。 + +.. note:: + + 15.8 のバックアップを新しい 15.10 のサーバーへ復元するときは、次の 2 点に注意してください。 + + - ジョブは、サーバー上のものより新しい場合にだけ復元されます。そのため、15.8 で編集していない同梱ジョブは + 15.10 の JavaScript 版のまま残ります。15.8 で編集または作成したジョブは、保存されたスクリプトエンジン + （同梱ジョブなら ``groovy``）のまま復元され、 ``fess-script-groovy`` プラグインがないと + ``groovy is not found`` で失敗します。プラグインを導入するか、そのジョブを JavaScript に切り替えてください。 + どちらも :ref:`upgrade-159-script-engine` で説明しています。 + - Web 認証、クロール設定、データストア設定のパラメーターに保存されたパスワードやシークレットは + ``app.cipher.key`` で暗号化されています。新しいサーバーの ``fess_config.properties`` に、旧環境の値を + 設定してください（ :ref:`upgrade-159-carried-over-config` を参照）。そうしないと復号できません。 + +Playwright クローラをプラグインへ移動 +------------------------------------- + +Playwright クローラと、それが使用する Node.js の実行ファイルは、配布物に含まれなく +なりました。 ``fess-15.8.0.zip``\ （457.1 MiB）では、Node.js の実行ファイルを収めた +Playwright のドライバーバンドルが 204.3 MiB を占めていました。 + +クロール設定の設定パラメータで ``client.crawlerClients=playwright:http://.*`` のように +Playwright クライアントを指定している場合は、プラグインと Node.js の両方を導入してください。 +プラグインは管理画面の「システム > プラグイン」ページからも導入できます。 ``bin/fess.in.sh`` +が Node.js の導入先を検出し、 ``PLAYWRIGHT_NODEJS_PATH`` を設定します。 + +:: + + $ bin/fess-setup install plugin fess-crawler-playwright + $ bin/fess-setup install nodejs + +プラグインがない場合でも、そのような設定はクロールされますが、通常の HTTP クライアントが +使われるため、JavaScript によって生成されるテキストはインデックスされません。クロールジョブは +正常に終了し、障害 URL も記録されません。クロールのたびに、 ``fess-crawler.log`` にはクロール設定 +ごとに 1 件、プラグイン名と上記の 2 つのコマンドを示す警告が記録されます。 + +Playwright で HTML ページのサムネイルを生成する ``fess-thumbnail-playwright`` プラグインも +Node.js で動作します。このプラグインを使用している場合も、 ``bin/fess-setup install nodejs`` +で Node.js を導入してください。導入した Node.js は 2 つのプラグインで共用されます。 + +Playwright クローラも ``fess-thumbnail-playwright`` プラグインも使用していない場合、対応は不要です。 + +Google Cloud Storage をプラグインへ移動 +--------------------------------------- + +Google Cloud Storage の SDK は配布物に含まれなくなり、 ``gcs://`` のクロールと ``gcs`` +ストレージタイプは ``fess-storage-gcs`` プラグインから提供されます。管理画面の +「システム > プラグイン」ページ、または次のコマンドで導入してください。 + +:: + + $ bin/fess-setup install plugin fess-storage-gcs + +``crawler.file.protocols`` の既定値からも ``gcs`` が外れ、 ``file,smb,smb1,ftp`` に +なりました。プラグインを導入すると再び追加されます。導入前は、パスが ``gcs:`` で始まる +ファイルクロール設定について警告がログに記録されるだけで、何も取得できません。 +アップグレードした既存インストールでは ``crawler.file.protocols`` がそのまま残るため、 +パスは受け付けられますが、対応するクローラクライアントがありません。新規インストールでは +``gcs:`` が設定済みのプロトコルではないため、管理画面はそのパスの保存を拒否し、以前に +保存されたパスはローカルファイルパスとして扱われます。ストレージ画面も警告をログに記録し、 +導入すべきプラグイン名を含むエラーを表示します。以前は空のファイル一覧を表示するだけでした。 + +Google Cloud Storage を使用していない場合、対応は不要です。Amazon S3 と MinIO などの +S3 互換ストレージも同じようにプラグインへ移動しました。次の節を参照してください。 + +Amazon S3 をプラグインへ移動 +---------------------------- + +AWS SDK は配布物に含まれなくなり、 ``s3://`` のクロールと ``s3`` および ``s3_compat`` の +ストレージタイプは ``fess-storage-s3`` プラグインから提供されます。管理画面の +「システム > プラグイン」ページ、または次のコマンドで導入してください。 + +:: + + $ bin/fess-setup install plugin fess-storage-s3 + +``crawler.file.protocols`` の既定値からも ``s3`` が外れ、 ``file,smb,smb1,ftp`` に +なりました。プラグインを導入すると再び追加されます。 ``storage.type`` の既定値は ``auto`` +のままで、エンドポイントが未設定なら S3 に解決されるため、 ``s3`` を明示していなくても +プラグインを導入するまで管理画面のストレージは機能しません。 ``storage.*`` の設定値は +``WEB-INF/conf/system.properties`` にあるため残り、既存の ``crawler.file.protocols`` も +アップグレードで置き換わりません。 + +Amazon S3 と MinIO などの S3 互換ストレージを使用していない場合、対応は不要です。 + +SSO 認証をプラグインへ移動 +-------------------------- + +4 種類の SSO 認証はいずれも配布物に含まれなくなり、 ``sso.type`` の値ごとに専用の +プラグインから提供されます。プラグインには必要な認証ライブラリも含まれます。 ``saml`` は +``fess-sso-saml`` 、 ``spnego`` は ``fess-sso-spnego`` 、 ``entraid`` （旧名の ``aad`` も +同じ）は ``fess-sso-entraid`` 、 ``oic`` は ``fess-sso-oidc`` です。最後の組み合わせに +注意してください。プラグイン名は ``fess-sso-oidc`` ですが ``sso.type`` の値は ``oic`` の +ままで、両者が異なるのはここ 1 か所だけです。使用するものを管理画面の +「システム > プラグイン」ページ、または次のコマンドで導入してください。 + +:: + + $ bin/fess-setup install plugin fess-sso-saml + +``sso.type`` と ``saml.*`` 、 ``spnego.*`` 、 ``entraid.*`` 、 ``aad.*`` 、 ``oic.*`` の各キーは +``WEB-INF/conf/system.properties`` にあるため、設定値はそのまま残ります。管理画面 +「システム」→「全般」も 4 種類すべてを選択肢として表示し、設定欄も残ります。プラグインから +JSP を提供できないためで、この画面はプラグインが未導入であることを知らせません。 + +プラグインを導入するまで、 ``/sso/`` へのリクエストは SSO ログインの失敗を表示する +ログインページへリダイレクトされ、SSO でログインできません。15.10 では探した +コンポーネント名と提供元のプラグイン名を含む警告が ``fess.log`` に記録されます。 +15.8 まではどのログレベルでも何も出力されませんでした。 + +``oic`` プラグインは、15.8 の認証機能より検証が厳しくなっています。 ``oic.token.server.url`` は HTTPS +である必要があり（ ``http`` が使えるのは ``localhost`` 、 ``127.x.x.x`` 、 ``::1`` のみです）、ID Token の ``aud`` と +``exp`` を検証します。新しいキー ``oic.issuer`` を設定した場合は ``iss`` も検証します。詳しくは +:doc:`../config/sso-oidc` を参照してください。 + +15.8 では ``oic.token.server.url`` に ``http`` のURLを指定でき、ホスト名の制限もありませんでした。15.10 では、Docker Composeのサービス名（``http://keycloak:8080/...`` など）や社内のホスト名への ``http`` は、同じマシンを指していても拒否されます。拒否されるとログインに失敗し、 ``fess.log`` に ``Failed to process the OpenID Connect callback: oic.token.server.url must be https`` で始まる警告が出力されます。更新する前に、トークンエンドポイントを HTTPS のURLに変更してください。 + +あわせて ``oic.issuer`` に、OPのDiscoveryドキュメントの ``issuer`` の値を設定することをお勧めします。設定しない場合、 ``iss`` は検証されず、起動後の最初のログインで警告が出力されます。 ``oic.issuer`` を設定しても HTTPS の規則は緩和されません。 + +SSO を使用していない場合、つまり ``sso.type`` が ``none`` または未設定の場合、 +対応は不要です。 + +.. _upgrade-159-script-engine: + +標準のスクリプトエンジンが Groovy から JavaScript に変更 +-------------------------------------------------------- + +15.8 までは標準のスクリプトエンジンが Groovy で、 ``job.default.script`` の既定値も ``groovy`` +でした。15.10 では標準のエンジンが JavaScript になり、既定値は ``javascript`` です。Groovy は +標準では組み込まれなくなり、 ``fess-script-groovy`` プラグインで提供されます。 ``scriptType`` +に ``groovy`` を指定するには、このプラグインをインストールしておく必要があります。 + +アップグレードでは、各設定に保存されたスクリプトエンジンは変更されません。また、15.10 より前に +保存され、エンジンを記録していない設定は ``groovy`` として扱われます。プラグインがない場合、 +次の設定が動作しなくなります。 + +- ``groovy`` として保存されたスケジュールジョブ。 + **15.8 が自動で登録したジョブもこれに該当します。**\ Default Crawler、Suggest Indexer、 + Config Reloader、Log Aggregator、Doc Purger などの同梱ジョブはすべて ``groovy`` として保存されて + おり、15.10 は起動時にまだ存在しない同梱ジョブだけを追加するため、これらは書き換えられません。 + 各ジョブはスケジュールで起動されるたびに失敗し、Default Crawler によるクロールも行われなく + なります。同梱ジョブの多くは「ロギング」が無効なため、失敗はジョブログには残らず、 + ``fess.log`` に ``Failed to execute job`` の警告として出力されるだけです。 +- 「設定パラメーター」にフィールドスクリプト（ ``field.script.<フィールド名>`` ）を書いた Web + クロール設定とファイルクロール設定。その設定のドキュメントはすべて ``ScriptEngineException`` + で失敗して障害 URL に記録されますが、クロールジョブ自体は正常に終了します。 +- 「スクリプト」を設定したデータストア設定。パラメーター名そのもの以外の値は評価できません。 + :doc:`../config/datastore/ds-overview` を参照してください。 +- ドキュメントブーストのルール。そのルールは何もブーストしません。 +- 「置換」が ``groovy:`` で始まるパスマッピング。そのマッピングは適用されず、URL は変更されません。 + +最初の起動後、 ``fess.log`` で +``Settings use the script engine groovy, which is not registered`` で始まる警告を確認して +ください。\ |Fess| は起動時に上記の設定を一度確認し、どのプラグインも提供していないエンジンを +使う設定の数を種類ごとに出力します。15.8 から引き継いだ ``fess_config.properties`` に +``job.default.script=groovy`` が残っている場合はそれも示され、この場合はアップグレード後に作成した +ジョブも Groovy を使います（ :ref:`upgrade-159-carried-over-config` を参照）。次のいずれかで +対応してください。 + +- プラグインをインストールして |Fess| を再起動します。保存済みの Groovy スクリプトはそのまま + 動作し、警告も出力されなくなります。プラグインは管理画面「システム」→「プラグイン」からも + インストールできます。 + + :: + + $ bin/fess-setup install plugin fess-script-groovy + +- 各設定を JavaScript に移行します。Groovy だけが受け付ける構文を先に書き換えてから、 + JavaScript を選択します。 + + - スケジュールジョブ: 管理画面「システム」→「スケジューラ」で「実行方法」を ``javascript`` + にします。同梱ジョブのスクリプトは、次の 2 つを除いてそのまま JavaScript として有効です。 + Thumbnail Purger は Groovy の ``long`` リテラル ``1000L`` を使っており、JavaScript では + 構文エラーになります（ ``1000`` と書きます）。Index Exporter には + :ref:`upgrade-159-index-exporter` の変更が必要です。JavaScript では配列リテラルが Java の + ``String[]`` へ自動的に変換されるため、Groovy 形式の ``as String[]`` は不要です。 + + :: + + return container.getComponent("crawlJob").logLevel("info").webConfigIds(["1", "2"]).fileConfigIds(["1"]).dataConfigIds([]).execute(executor); + + - Web クロール設定とファイルクロール設定: 「設定パラメーター」に + ``config.script.type=javascript`` を追加します。 + - データストア設定: 「パラメーター」に ``script_type=javascript`` を追加します。 + - ドキュメントブーストのルール: 「スクリプト種別」を ``javascript`` にします。 + - パスマッピング: 「置換」の先頭を ``groovy:`` から ``javascript:`` に変えます。 + - ``job.default.script``: 15.8 から引き継いだ ``fess_config.properties`` で ``javascript`` + に設定します。 + +``crawler.default.script`` の削除 +--------------------------------- + +``crawler.default.script`` は ``fess_config.properties`` から削除されました。設定に残していても +効果はないため、削除してください。 + +クロールプロトコル ``storage`` の削除 +------------------------------------- + +``crawler.file.protocols`` で ``storage`` は指定できなくなりました。同梱の値は +``file,smb,smb1,ftp`` です。代わりに ``s3`` を使用し、 ``storage:`` で始まるパスを +指定しているファイルクロール設定は ``s3:`` のパスへ変更してください。 ``s3`` には +``fess-storage-s3`` プラグインが必要です。 + +.. _upgrade-159-index-exporter: + +Index Exporter ジョブが削除されたパッケージを参照 +------------------------------------------------- + +15.10 には ``org.opensearch`` のクラスが含まれなくなり、ジョブのスクリプトで使用するクエリビルダーは +``org.codelibs.fesen.opensearch`` の下に移りました。15.8 が Index Exporter ジョブに保存した +スクリプトは ``org.opensearch.index.query.QueryBuilders`` を参照しており、アップグレードでも +置き換えられないため、 ``fess-script-groovy`` をインストールしてもこのジョブは失敗します。 +このジョブは無効かつスケジュールなしの状態で同梱されているため、影響があるのは実行している +場合だけです。管理画面「システム」→「スケジューラ」でジョブを開き、スクリプトのパッケージを +15.10 のものに変更してください。 + +:: + + return new org.codelibs.fess.job.IndexExportJob().query(org.codelibs.fesen.opensearch.index.query.QueryBuilders.matchAllQuery()).execute() + +独自に作成したスクリプトで ``org.opensearch.index.query`` を参照している場合も、同じように +変更してください。クエリの例は :doc:`../config/admin-index-export` を参照してください。 + +.. _upgrade-159-carried-over-config: + +15.8 から引き継いだ設定ファイル +------------------------------- + +ステップ 3 の ZIP 版の手順では、旧バージョンの ``fess_config.properties`` と ``bin/fess.in.sh`` +をコピーします。RPM 版のアップグレードでは、変更を加えた ``/etc/fess/fess_config.properties`` +がそのまま残ります（15.10 のファイルは ``fess_config.properties.rpmnew`` として併置されます）。 +DEB 版でも、確認で自分のファイルを残した場合は同様です（15.10 のファイルは +``fess_config.properties.dpkg-dist`` として併置されます）。 +いずれの場合も 15.10 は 15.8 の値のまま動作し、15.10 で同梱の値が変わったキーも例外ではありません。 +少なくとも次のキーを確認してください。 + +.. list-table:: + :header-rows: 1 + + * - キー + - 15.8.0 + - 15.10 + - 15.8 の値が残った場合の影響 + * - ``job.default.script`` + - ``groovy`` + - ``javascript`` + - 管理画面「システム」→「スケジューラ」で作成するジョブの既定が ``groovy`` になり、 + ``fess-script-groovy`` プラグインがないと失敗します。 + * - ``job.template.script`` + - ``as String[]`` を含む Groovy 形式 + - JavaScript 形式 + - クロール設定から作成したジョブのスクリプトが Groovy 形式になります。 + * - ``crawler.file.protocols`` + - ``file,smb,smb1,ftp,storage,s3,gcs`` + - ``file,smb,smb1,ftp`` + - ``s3:`` や ``gcs:`` で始まるパスがプラグインなしでも受け付けられ、クロール時に警告を + 出して処理されません。 ``storage`` はサポートされなくなりました。 + * - ``search_engine.http.url`` + - ``http://localhost:9201`` + - ``http://localhost:9200`` + - ``SEARCH_ENGINE_HTTP_URL`` が設定されていない場合に使われます。15.8 からコピーした + ``bin/fess.in.sh`` で設定していなかった場合がこれに当たり、\ |Fess| は 15.10 で廃止された + 組み込み OpenSearch のポートである 9201 で OpenSearch を探します。 + * - ``jvm.crawler.options``\ 、\ ``jvm.thumbnail.options`` + - ``-Djcifs.smb.client.*``\ 、\ ``-Djcifs.smb1.smb.client.*`` + - ``-Djcifs.client.*`` + - SMB のタイムアウトが jcifs の既定値のままになります。 :ref:`upgrade-159-jcifs` を + 参照してください。 + * - ``response.headers`` + - ``text/html=Content-Security-Policy: reflected-xss block`` の行を含む + - その行なし + - ログイン画面や管理画面など、\ |Fess| 自身が描画するページのレスポンスに、ブラウザーが認識しない + ``Content-Security-Policy: reflected-xss block`` ヘッダーが付き、ブラウザーのコンソールに + ``Unrecognized Content-Security-Policy directive 'reflected-xss'`` が出ます。このヘッダーは + 何も制限しません。次の段落のとおり、その行を削除してください。 + * - ``app.encrypt.property.pattern`` + - ``.*password|.*key|.*token|.*secret`` + - ``.*password|.*passphrase|.*key|.*token|.*secret`` + - 名前が ``passphrase`` で終わるパラメーター（たとえばデータストア設定の ``ssh.passphrase``）が + 平文で保存されます。すでに保存されている値は、15.10 のパターンで設定を保存し直すまで平文のままです。 + * - ``index.backup.log.targets`` + - ``click_log.ndjson,favorite_log.ndjson,search_log.ndjson,user_info.ndjson`` + - ``chat_log.ndjson,click_log.ndjson,favorite_log.ndjson,search_log.ndjson,user_info.ndjson`` + - 「システム情報」→「バックアップ」ページに ``chat_log.ndjson`` が表示されません。 + * - ``index.export.exclude.fields`` + - ``cache`` + - ``cache,tag`` + - ユーザータグを保持する ``tag`` フィールドが、Index Export ジョブが書き出すファイルから + 除外されなくなります。 + * - ``crawler.default.script``\ 、\ ``theme.allowed.archive.extensions``\ 、 + ``theme.assets.cache.max.age``\ 、\ ``theme.assets.precompressed``\ 、 + ``rag.chat.message.max.length``\ 、\ ``supported.uploaded.js.extentions``\ 、 + ``supported.uploaded.css.extentions``\ 、\ ``supported.uploaded.media.extentions``\ 、 + ``supported.uploaded.files``\ 、\ ``online.help.name.design`` + - あり + - 削除 + - 効果はありません。削除してください。 + +``response.headers`` の同梱の値には、15.0 から 15.8 まで ``text/html=Content-Security-Policy: reflected-xss block`` +の行があります。 ``reflected-xss`` は Content-Security-Policy の初期の草案にあったディレクティブで、現在の +ブラウザーは認識しないため、このヘッダーは何も制限せず、コンソールにエラーを出すだけです。15.10 は同梱の値から +この行を削除しました。 ``X-XSS-Protection`` と ``X-Frame-Options`` の行は変わりません。15.8 から引き継いだ +``response.headers`` にはこの行が残るため、 ``fess_config.properties`` の ``response.headers`` から、次の行だけを +削除してください。各行の末尾の ``\n\`` は値が次の行に続くことを表すため、行ごと削除すれば、ほかの行はそのまま +使えます:: + + text/html=Content-Security-Policy: reflected-xss block\n\ + +``response.headers`` を ``-Dfess.config.response.headers`` で指定している場合は、その値から同じ項目を削除してください。 + +15.8 からコピーした ``bin/fess.in.sh`` には、15.10 のファイルにある次の 2 点もありません。 +15.10 は ``SEARCH_ENGINE_HTTP_URL`` に ``http://localhost:9200`` を設定しますが、15.8 のファイルは +自分で設定しない限り未設定のままです。また、 ``bin/fess-setup install nodejs`` で導入した +Node.js を検出しないため、 ``PLAYWRIGHT_NODEJS_PATH`` を自分で設定しない限り、Playwright +系のプラグインは Node.js を見つけられません。 + +どちらのファイルも丸ごとコピーするのではなく、15.10 に同梱のファイルを元にして、変更した値を +再適用してください。変更した値は ``diff`` で確認できます:: + + $ diff /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.10.0/app/WEB-INF/classes/fess_config.properties + $ diff /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.10.0/bin/fess.in.sh + +RPM 版では、同じように ``/etc/fess/fess_config.properties`` と +``/etc/fess/fess_config.properties.rpmnew`` を、DEB 版では +``/etc/fess/fess_config.properties.dpkg-dist`` を比較してください。DEB 版のアップグレードでは、 +編集していない ``fess_config.properties`` は 15.10 のファイルに置き換えられるため（ステップ 3 を参照）、 +15.10 の値から始まります。 + +``app.cipher.key`` は、15.10 で変わっていなくても必ず引き継ぐ必要がある値です。Web 認証、クロール設定、 +データストア設定のパラメーターに保存されたパスワードやシークレットを暗号化する鍵だからです。新しい +環境が、それらを保存したときとは別の鍵で動作していると（同梱の ``fess_config.properties`` を使った場合や、 +バックアップを新しいサーバーへ復元した場合など）復号できず、 ``fess-crawler.log`` に +``CipherFailureException`` が記録され、そのような設定を含むクロールは何も索引できないことがあります。 + +.. note:: + + 15.10 の |Fess| は、Web 認証とファイル認証の ``password`` も ``app.cipher.key`` で暗号化して保存するため、 + バックアップの ``fess_basic_config.bulk`` と ``fess_config.bulk`` には暗号化された値が含まれます。 + 別のインストールに復元するときは同じ ``app.cipher.key`` を引き継いでください。鍵が異なると、これらの認証情報を使う + クロールはエラーで失敗します。15.10 より前のバックアップには平文で含まれており、そのまま使えます + （詳細は :doc:`../admin/backup-guide` を参照）。 + +.. _upgrade-159-jcifs: + +SMB のタイムアウトは jcifs 3 のプロパティ名を使用 +------------------------------------------------- + +SMB ファイルサーバーのクロールに |Fess| が使用する jcifs は、バージョン 3 でプロパティ名を +変更しました。 ``jcifs.smb.client.*`` は ``jcifs.client.*`` になり、SMB1 用の +``jcifs.smb1.smb.client.*`` も同じプロパティに統合されました。15.8 までの ``jvm.crawler.options`` +と ``jvm.thumbnail.options`` は旧名を渡しており、jcifs はそれを読まないため、SMB のクロールは +jcifs の既定値で動作していました。15.10 は新しい名前を渡します。 + +:: + + -Djcifs.client.responseTimeout=30000 + -Djcifs.client.soTimeout=35000 + -Djcifs.client.connTimeout=60000 + -Djcifs.client.sessionTimeout=60000 + +そのため、接続タイムアウトとセッションタイムアウトが初めて有効になり、jcifs の既定値の 35 秒から +60 秒に延びます。応答しない SMB サーバーに対して、クロールは最大 60 秒待つようになります。 +応答タイムアウトとソケットタイムアウトは jcifs の既定値と同じ値のため、変わりません。 + +これらのタイムアウトを変更していた場合は、両方のオプションで名前を変更してください。旧名のままでは +15.8 でも効果はありませんでした。15.8 から引き継いだ ``fess_config.properties`` には旧名が残り、 +jcifs の既定値のままになります。 + +効果のなかった 4 つのプロパティの削除 +------------------------------------- + +次のキーは ``fess_config.properties`` から削除されました。\ |Fess| はこれらをこのファイルから +読み込んでいなかったため、これまでと同様、この名前で残した値に効果はありません。 + +- ``theme.allowed.archive.extensions`` +- ``theme.assets.cache.max.age`` +- ``theme.assets.precompressed`` +- ``rag.chat.message.max.length`` + +``rag.chat.message.max.length`` による上限は引き続き有効ですが、システムプロパティとして +読み込まれます。 :doc:`../config/rag-chat` のとおり、 ``app/WEB-INF/conf/system.properties`` +または ``-Dfess.system.rag.chat.message.max.length`` で設定してください。 + +.. _upgrade-159-static-theme: + +検索画面は静的テーマに +---------------------- + +別のテーマを選んでいない限り、検索画面は |Fess| に同梱の静的テーマ ``bootstrap`` で表示されます。 +対象は ``/`` 、 ``/search`` 、 ``/advance`` 、 ``/help`` 、 ``/profile`` 、 ``/cache`` 、 ``/chat`` と +エラーページです。15.8 までは、既定のテーマを設定していなければ、これらのページは JSP でした。 + +この切り替えはアップグレードでも起こります。既定のテーマを設定したことのない 15.8 の環境では +``system.properties`` に ``theme.default`` が無いため、アップグレード後は静的テーマで表示されます。 +設定ファイルには何も書き込まれず、ログにも何も出ません。JSP の検索画面に戻す設定はありません。 +15.8 で既定のテーマを設定していた場合、その設定は引き継がれます。そのテーマは 15.10 向けのビルドを +インストールしてください（ ``bin/fess-setup install theme `` ）。インストールされていないテーマを +既定に指定していると、 ``fess.log`` に警告を出して ``bootstrap`` で表示します。 + +管理画面の「ページのデザイン」や JAR テーマプラグインで検索画面の JSP、CSS、画像を変更していた場合、 +その変更は表示されなくなります。変更は静的テーマで行ってください。同梱のテーマを複製して変更するか +（ :ref:`theme-customize-bundled` を参照）、公開されているテーマを管理画面の「システム」>「テーマ」または +``bin/fess-setup install theme `` でインストールします。仮想ホストごとの見た目は、仮想ホスト名と +同じ名前の静的テーマで変えます（ :doc:`../config/security-virtual-host` を参照）。 + +次の 2 つも無くなりました。 + +- 仮想ホストごとのログイン画面。15.8 までは「システム」>「全般」を保存すると、ログイン画面を含む + JSP が ``WEB-INF/view/<仮想ホスト名>/`` にコピーされ、仮想ホストごとに編集できました。15.10 は + このコピーを作りません。ログイン画面（ ``/login/`` ）は引き続き JSP ですが、すべての仮想ホストで + 共通の ``WEB-INF/view/admin/login/`` のものが表示されます。以前にコピーされた JSP は使われません。 +- JAR テーマプラグイン（ ``fess-theme-*`` ）。インストールしても種類 ``jar`` の汎用 JAR として + 置かれるだけで、画面は変わりません。残っている JAR は「システム」>「プラグイン」ページ、または + ``bin/fess-setup remove plugin `` で削除できます（ :doc:`../dev/theme-development` を参照）。 + +15.8 で JSP の検索結果に独自のフィールドを表示していた場合は、 ``query.additional.response.fields`` +に加えて ``query.additional.api.response.fields`` にも同じフィールドを追加してください。静的テーマは +検索結果を ``/api/v2/search`` から取得します。 ``query.additional.response.fields`` は検索エンジンから +取得するフィールドを追加するだけで、この API が応答に含めるのは ``query.additional.api.response.fields`` +に列挙されたフィールドだけです（ :doc:`../config/search-advanced` を参照）。そのフィールドを表示するように +テーマも変更してください。 + +クライアントから見た変化 +~~~~~~~~~~~~~~~~~~~~~~~~ + +エラーは、要求された URL のまま、実際の HTTP ステータスで返るようになりました。ブラウザ +（ ``Accept`` ヘッダーに ``text/html`` を含むリクエスト）にはテーマのエラーページを、それ以外の +クライアントには ``Not Found.`` のような 1 行の ``text/plain`` を返します。15.8 までは、ほとんどの +エラーが ``/error/...`` のページへの ``302`` リダイレクトになり、そのページが ``200`` を返していました。 +監視、ヘルスチェック、 ``Location`` ヘッダーをたどるクライアントや ``/error/`` の URL を前提とする +クライアントを見直してください。 + +.. list-table:: + :header-rows: 1 + + * - リクエスト + - 15.8 まで + - 15.10 + * - パラメーターが欠けた、または存在しない文書に対する ``/go/`` + - ``200`` 、または ``/error/`` への ``302`` + - ``400`` または ``404`` + * - パラメーターが欠けた、未知の文書に対する、またはサムネイルの無い ``/thumbnail/`` + - ``200`` または ``302`` + - ``400`` または ``404`` + * - 設定した SSO の種類が扱わない ``/sso/metadata`` と ``/sso/logout`` + - ``/error/badrequest/`` への ``302`` + - ``400`` + * - ``/api/v1/*`` 、 ``/json`` 、および存在しない URL + - ``/error/notfound/`` への ``302`` + - ``404`` + * - 捕捉されない例外（管理 API を含む） + - ``/error/systemerror/`` への ``302`` + - ``500`` 。本文は ``System Error.`` （JSON ではありません） + * - ``/error/notfound/`` 、 ``/error/badrequest/`` 、 ``/error/systemerror/`` そのもの + - ``200`` + - ``404`` 、 ``400`` 、 ``500`` + +``login.required=true`` のとき、検索系のページは未ログインのユーザーをリダイレクトしなくなりました。 +ページはテーマとともに ``200`` を返してログインを求め、その裏のデータの方を拒否します。 ``/health`` 、 +``/auth/*`` 、 ``/ui/config`` 以外の ``/api/v2/`` のエンドポイントは、 ``/api/v2/search`` を含め、ログインするまで +``401`` を返します。 ``/go/`` 、 ``/thumbnail/`` 、 ``/osdd`` は従来どおりログインへ +リダイレクトします。未ログインで ``/`` にアクセスしたときのリダイレクトを確認している監視は、 +``/api/v2/search`` が ``401`` を返すことを確認するように変えてください。 + +検索画面は ``/api/v2/search`` を使って検索するため、検索ログは ``/search`` へのリクエストではなく +この API の呼び出しで記録されます。JavaScript を実行しないクライアントには、検索結果の無いページが +返ります。 + +検索画面の HTML には ``X-Frame-Options: DENY`` と、 ``frame-ancestors 'none'`` を含む +``Content-Security-Policy`` が付き、他のページのフレームには表示されません。15.8 の JSP の検索画面は +``response.headers`` の既定値により ``X-Frame-Options: SAMEORIGIN`` で、同じオリジンのページの ``iframe`` に\ +表示できました。検索画面を同じオリジンの ``iframe`` に埋め込んでいる場合は、 ``fess_config.properties`` の +``theme.index.frame.ancestors`` （既定値 ``'none'`` ）に ``'self'`` を設定してください。別のオリジンから\ +埋め込むときは、そのオリジンを指定します（ :doc:`../dev/theme-development` を参照）。 + +管理画面の「ページのデザイン」を削除 +------------------------------------ + +管理画面の [システム > ページのデザイン] を削除しました。検索画面の JSP、CSS、画像を管理画面から +編集することはできません。検索画面の見た目は静的テーマで変更してください（ :ref:`theme-customize-bundled` +を参照）。 + +次のキーも ``fess_config.properties`` から削除しました。この名前で残した値は使われません。 + +- ``supported.uploaded.js.extentions`` +- ``supported.uploaded.css.extentions`` +- ``supported.uploaded.media.extentions`` +- ``supported.uploaded.files`` +- ``online.help.name.design`` + +``admin-design`` と ``admin-design-view`` のロールは、何の権限も与えなくなりました。これらのロールだけを +持つユーザーは、ログインすると管理画面ではなく検索画面に移動します。 + +``api.access.token.required`` の削除 +------------------------------------ + +``api.access.token.required`` は ``fess_config.properties`` から削除されました。15.8 から引き継いだ +``fess_config.properties`` に残っている場合も含め、この名前の値は効果がありません。 ``true`` にすると、 +ログインしていないユーザーからの API リクエストをすべて拒否していました。検索画面は +``/api/v2/search`` を使って検索するようになったため、この設定では匿名ユーザーに結果のない検索画面が +表示されることにもなります。 + +``true`` に設定していた環境では、匿名ユーザーからの API リクエストにも、検索画面と同じくゲストのロールで +応答するようになります。匿名ユーザーに検索させない場合は ``login.required=true`` を設定してください。 +アクセストークンの動作は変わりません。登録済みのアクセストークンを付けたリクエストにはそのトークンの +権限が与えられ、未登録または期限切れのトークンを付けたリクエストは拒否されます。 + +.. _upgrade-159-api-requests: + +API が拒否するようになったリクエスト +------------------------------------ + +15.8 では受け付けられていた次のリクエストを、15.10 は拒否します。15.8 向けに作ったクライアントやスクリプトが\ +送っていないか確認してください。管理 API の拒否は HTTP ``400`` で、本文の ``status`` は ``1`` です。 + +.. list-table:: + :header-rows: 1 + + * - リクエスト + - 15.8 + - 15.10 + * - ``/api/v2/search`` に ``facet.field`` または ``facet.query`` と一緒に、 ``0`` 以下の ``facet.size`` 、\ + または整数でない ``facet.size`` ・ ``facet.minDocCount`` を指定する + - ``200`` 。ただし ``record_count`` が ``0`` で ``partial`` が ``true`` の空の結果 + - ``400`` （ ``invalid_request`` ）。 ``facet.size`` は ``1`` 以上です + * - ``track_total_hits=false`` を指定する。 ``query.track.total.hits`` を ``false`` にしている場合は\ + すべての検索が対象です + - ``200`` 。ただし検索結果が 0 件 + - 検索が拒否されます（ ``/api/v2/search`` は ``400`` で ``invalid_request`` ）。 ``true`` と正の整数は\ + 従来どおりです + * - 管理 API の辞書（ ``mapping`` ・ ``kuromoji`` ）に、既にある項目と重複する項目を登録・更新する + - 保存されます。辞書を読み込むときに失敗し、検索できなくなる原因になります + - ``400`` + * - 管理 API の ``kuromoji`` 辞書に、 ``token`` が空白を含む項目や、 ``segmentation`` と ``reading`` で\ + 空白区切りの語の数が異なる項目を登録・更新する + - 保存されます。上と同じく、辞書を読み込むときに失敗します + - ``400`` + * - ``DELETE /api/admin/searchlist/doc/{doc_id}`` で、何も削除されなかった場合（存在しない ``doc_id`` 、\ + または文書一覧が返す ``_id`` のように ``doc_id`` でない値） + - ``200`` （ ``status`` は ``0`` ）。文書は削除されません + - ``400`` + * - 管理 API のユーザーの ``roles`` ・ ``groups`` に、ロール名・グループ名を指定する + - 保存されますが、指定した名前はロールとして働きません。名前によっては、そのユーザーの読み込みに失敗します + - ``400`` 。ロール・グループの ID（ ``GET /api/admin/role/settings`` ・ ``GET /api/admin/group/settings`` の + ``id`` ）を指定します + * - 管理 API のユーザーに、パスワードポリシー（ ``password.min.length`` の既定値 ``8`` など）に反する\ + パスワードを設定する。作成時にパスワードを省略する。 ``confirm_password`` を送り、 ``password`` と\ + 一致しない + - 保存され、そのパスワードでログインできます + - ``400`` + +``/api/v2/documents/all`` の各行から ``score`` がなくなりました。15.8 では各文書に検索スコアが付いていましたが、 +15.10 は全件の取得を point in time と ``search_after`` で行うため、スコアは付きません。旧 API プラグインの +``/json?type=scroll`` ・ ``/api/v1/documents/all`` も同じです。 ``score`` を読むスクリプトは、値がない場合を\ +扱えるようにしてください。 + +管理 API のファイルのアップロード（辞書 6 種類、 ``badword`` 、 ``elevateword`` 、 ``storage`` ）は、 ``POST`` で\ +受け付けます。15.8 の文書は ``PUT`` を案内していましたが、 ``multipart/form-data`` の ``PUT`` ではファイルが\ +届かず、15.8 でも 15.10 でも「ファイルが必要です」という検証エラーになります。 ``PUT`` のエンドポイントは\ +残っていますが、アップロードには ``POST`` を使ってください。 + +``search_engine.type`` の ``cloud`` は非推奨 +-------------------------------------------- + +15.10 では、CodeLibs のプラグインを含まない素の OpenSearch 用に、 ``search_engine.type`` の値として ``vanilla`` が追加されました（ :doc:`../config/search-engine-type` を参照）。 ``cloud`` は ``vanilla`` の非推奨の別名になりました。引き続き動作しますが、起動時に警告をログに出力します。15.10 で運用するようになったら、 ``vanilla`` に変更してください。 ``aws`` はこれまでどおり動作します。 + +* ``vanilla`` は 15.10 以降で使えます。15.8 以前の |Fess| はこの値を認識しません。15.8 に戻す可能性がある間は ``cloud`` のままにしてください。 +* ``aws`` と ``cloud`` のインデックス定義は ``fess_indices/_vanilla/`` から読み込まれます。同梱されていた ``fess_indices/_aws/`` と ``fess_indices/_cloud/`` はなくなりました。独自に追加した ``fess_indices/_aws/`` または ``fess_indices/_cloud/`` は読み込まれなくなるため、変更内容を ``fess_indices/_vanilla/`` に移してください。作成済みのインデックスは変更されません。 +* 15.8 が検索エンジンに保存したサジェストの設定は、自動的に移行されます。対応は不要です。 + +CSV データストアが引用符で囲まれたフィールドを解釈 +-------------------------------------------------- + +15.10 の ``fess-ds-csv`` プラグインは、既定で引用符を解釈します。 ``"山田, 太郎"`` のようなフィールドは +1 つの列になります。15.8.0 のプラグインはカンマの位置で分割していました。 +``bin/fess-setup upgrade plugins`` の実行後は、引用符で囲まれたフィールドを含む CSV ファイルを読む +データストア設定を確認してください。15.8 の動作を維持するには、「パラメーター」に +``quote_disabled=true`` を追加します。対応する引用符がない場合の動作も含め、 +:doc:`../config/datastore/ds-csv` を参照してください。 + +.. _upgrade-reindex-new-fields: + +既存の文書インデックスへの新しいフィールドとかなの正規化の反映 +-------------------------------------------------------------- + +15.10 は起動時に、設定・ログ・ユーザーのインデックスへ新しいフィールドを追加します。文書の +インデックスに追加するのは、ユーザータグを保持する ``tag`` フィールド（ ``keyword`` ）だけで、 +マッピングのそれ以外の部分と解析の設定は変更しません。15.8 以前で作成した文書インデックスを +そのまま使うと、次の 15.10 の変更が効きません。 + +- **ファイルの所有者と最終更新者**\ （\ ``owner``\ ・\ ``last_modifier``\ ）: ファイルシステム・SMB・FTP の + クロールで新たに索引されるフィールドです。既存の文書インデックスには定義がないため、最初に + クロールした値から ``text`` 型として自動でマッピングされ、\ ``owner:alice`` のような検索や + ``facet.field=owner`` が期待どおりに動きません。 +- **ETag**\ （\ ``etag``\ ）: クロールしたページの ETag を保存するフィールドです。15.10 はこれを + ``If-None-Match`` として送り返し、変更のないページを再取得しません。既存の文書インデックスにはこれも + 定義がないため、同梱の「索引されない ``keyword``」ではなく ``text`` 型として自動でマッピングされます。 + このマッピングでも条件付きリクエストは動作します。 +- **かなの表記ゆれと、長音符の代わりに書かれたダッシュの正規化**\ （例: ``サ―バ－`` を ``サーバー`` と + 同じ語として扱う）: 規則は文書インデックスの解析の設定と辞書 ``mapping.txt`` にあるため、 + 既存のインデックスには反映されません。 + +両方を反映するには、管理画面の「システム情報」→「メンテナンス」で「エイリアスの更新」と +「辞書の初期化」を有効にして「再インデクシング」を実行します。再インデクシングは既存の文書を +新しいインデックスへコピーするため、クロールし直す必要はありません。 + +.. warning:: + + 「辞書の初期化」は、同梱の辞書ファイルで OpenSearch 側の辞書を上書きします。管理画面の「辞書」で + 同義語などを編集している場合は、事前にダウンロードしておき、再インデクシングの後に反映し直して + ください。ダウンロードしたファイルから重複または不正なエントリーを削除し（ステップ 7 を参照）、 + アップロードしたうえで、「システム情報」→「メンテナンス」の「ドキュメントインデックスのリロード」で + [リロード] をクリックしてください。リロードするまで、文書インデックスのアナライザーは同梱の辞書を + 使い続けるため、復元した同義語は、どれだけ待っても一致しません。インデックス時に効く辞書は、さらに + 文書の再クロールが必要です。 :ref:`dict-apply-changes` を参照してください。 + +.. note:: + + 15.8 以前に索引したファイルには、所有者と最終更新者の値がありません。差分クロールでは変更のない + ファイルは取得し直されないため、値を付けるには「システム」→「全般」の「最終更新日時の確認」を + 一時的に無効にしてクロールしてください。 + + +15.10 固有の移行作業 +=================== + +15.7 以前から 15.10 へアップグレードする場合、利用している機能に応じて以下の作業が必要です。 + +セマンティック検索を利用していた場合 +------------------------------------ + +15.7 以前でセマンティック検索を提供していた ``fess-webapp-semantic-search`` プラグインは、 +15.10 でコアに統合されたため不要になりました（非推奨）。プラグインの削除、\ ``-Dfess.semantic_search.*`` +および ``-Drank.fusion.searchers=default,semantic`` の削除、旧 ingest pipeline のデタッチが +必要です。手順は :ref:`semantic-search-migration`\ （:doc:`../config/search-semantic`）を +参照してください。 + +AI 検索モード（RAG チャット）を利用していた場合 +----------------------------------------------- + +15.10 から、AI 検索モード（RAG チャット）の機能は ``fess-llm-ollama``\ 、\ ``fess-llm-openai``\ 、 +``fess-llm-gemini`` などのプラグインとして分離されました。利用しているプロバイダーに対応する +プラグインを管理画面「システム」→「プラグイン」からインストールしてください。 +また、15.10 では Amazon Bedrock 用の ``fess-llm-bedrock`` が追加されています。 + +SPNEGO（Windows 統合認証）を利用していた場合 +-------------------------------------------- + +15.10 から、クライアントのプリンシパルの Kerberos レルムがサーバーのレルムと異なる場合、 +SPNEGO ログインは拒否されます。AD のドメインツリーの子ドメインや信頼関係を結んだフォレストの +ユーザーがログインする構成では、管理画面「システム」→「全般」または +``app/WEB-INF/conf/system.properties`` の ``spnego.allowed.realms`` に該当するレルムを +カンマ区切りで列挙してください。列挙しない場合、15.7 まではログインできていたユーザーが +``Kerberos realm is not allowed`` として拒否されます。 +詳細は :doc:`../config/sso-spnego` を参照してください。 + +また、15.10 では ``spnego.allow.unsecure.basic`` と ``spnego.allow.localhost`` のコード上の +既定値が ``true`` から ``false`` へ変更されました。これらのキーが +``app/WEB-INF/conf/system.properties`` に存在しない環境では、アップグレードによって +より厳格な挙動が適用されます。特に ``spnego.allow.unsecure.basic=false`` では、SPNEGO ライブラリは +``HttpServletRequest#isSecure()`` が ``true`` を返すリクエストにのみ Basic 認証を提示するため、 +TLS をリバースプロキシで終端して HTTP で転送している構成では、これまで Basic 認証へ +フォールバックしていたクライアントがログインできなくなります。その場合は +``tomcat_config.properties`` で ``tomcat.secure=true`` を設定してください。 +詳細は :doc:`../config/sso-spnego` を参照してください。 + +.. warning:: + + コード上の既定値は、キーが存在しない場合にのみ適用されます。管理画面「システム」→「全般」は + 保存のたびにすべての ``spnego.*`` キーを書き込むため、15.7 でこの画面から一度でも更新した環境には + ``spnego.allow.unsecure.basic=true`` と ``spnego.allow.localhost=true`` が保存されたままです。 + この場合、15.10 へアップグレードしても設定は強化されず、緩い挙動が黙って引き継がれます。 + 15.10 は SPNEGO の初期化時に ``fess.log`` へ警告を出力するだけです。管理画面「システム」→「全般」 + または ``system.properties`` で、両方を明示的に無効化してください。特に + ``spnego.allow.localhost=true`` は危険です。SPNEGO ライブラリが同一ホストからのリクエストを + Kerberos の検証なしにサーバーの OS ユーザーとして認証するため、同一ホスト上にリバースプロキシを + 置く構成では安全ではありません。 + +.. _upgrade-159-saml: + +SAML 認証（SSO）を利用していた場合 +---------------------------------- + +15.10 から、\ |Fess| は送信した AuthnRequest の ID と SAML レスポンスを対応付けて検証するため、 +IdP-Initiated（未承諾・unsolicited）SSO は動作しなくなりました。IdP のポータル（Okta の +ダッシュボードや Microsoft Entra ID の「マイアプリ」など）に置いたタイルから開始したログインは、 +対応付ける AuthnRequest が存在せず拒否されます。15.7 では、\ |Fess| が対応付けできないレスポンスを +IdP へ差し戻し、IdP が即座に SP-Initiated のアサーションを返していたため動作していました。 +IdP 側にタイルを配置する場合は、リンク先を |Fess| の ``/sso/`` に変更し、SP-Initiated の +ログインにしてください。 + +また、IdP はアサーションをクロスサイトの POST で返すため、``tomcat_config.properties`` の +``tomcat.sameSiteCookies`` に ``none`` を設定する必要があります。同梱の既定値 ``lax`` のままでは +セッション Cookie がこのリクエストに送信されず、SAML ログインが完了しません。このファイルは +ZIP 版では ``lib/classes/``\ 、DEB/RPM 版では ``/etc/fess/`` に配置されており、変更後は +|Fess| の再起動が必要です。``none`` はブラウザーが ``Secure`` 属性付きの Cookie に対してのみ +受け入れるため、\ |Fess| を HTTPS で提供する必要があります。15.7 までは同じ設定不備が明確な +エラーにならず、IdP への再リダイレクトが繰り返されるループになっていたため、動作しているように +見えていた環境でも設定を確認してください。15.10 ではループせずに 1 回で失敗します。 +詳細は :doc:`../config/sso-saml` を参照してください。 + +Microsoft Entra ID（Azure AD）を利用していた場合 +------------------------------------------------ + +15.10 から、認可エンドポイントに要求するレスポンスモードの既定値が ``form_post`` から ``query`` +に変わりました。15.7 まではコールバックがクロスサイトの POST で返るため、\ |Fess| の既定値である +``tomcat.sameSiteCookies = lax`` ではセッションクッキーが送信されず、\ ``none`` への変更が必要で +した。この回避策のためだけに ``none`` を設定していた場合は、既定値に戻せます。従来どおり +``form_post`` を使う場合は ``entraid.response.mode=form_post`` を指定し、 +``tomcat.sameSiteCookies = none`` を維持してください。``none`` はブラウザーが ``Secure`` 属性付きの +Cookie に対してのみ受け入れるため、この場合も |Fess| を HTTPS で提供する必要があります。 + +また 15.10 からは、ログイン完了後にユーザーのグループ・ロール権限をバックグラウンドで解決するように +なり、ログインがMicrosoft Graphの応答を待って止まることはなくなりました。解決が完了するまでの間、 +または解決が完全には成功しなかった場合、ユーザーが保持するのは、ユーザー自身のユーザーレベルの +権限と、\ ``entraid.default.groups``\ ・\ ``entraid.default.roles``\ に設定したグループ・ロール +だけです。どちらも未設定（同梱の既定値）の場合、この間の検索は1件もヒットしません。同梱の既定値の +まま作成したクロール設定でクロールした文書には ``{role}guest`` が付与されますが、 +ログイン済みユーザーはこのロールを持たないためです。解決中は検索画面にその旨のメッセージが表示され、 +完全には成功しなかった場合は別のメッセージが表示されます（直接所属の取得とネストしたグループの +探索の両方が成功しない限り、解決は失敗として扱われます）。アクセストークンが更新されるたびに解決が +再実行され、その後成功すればメッセージは消えるため、トークンの有効期間を超えて続くセッションでは +失敗が最終的なものになるとは限りません。すぐに再試行したい場合は、いったんログアウトしてから +ログインし直してください。 +詳細は :doc:`../config/sso-entraid` を参照してください。 + +バックグラウンドで解決することの副作用として、解決が完了するまでの間は、解決済みの +ロールがまだ分かりません。そのため、管理者は管理ダッシュボードではなく検索画面にリダイレクトされ、 +その間に管理画面を開いても検索画面に戻されます。この時間は、最大で約1秒のスケジューリング遅延に +加えて、Microsoft Graphの呼び出しそのもの（直接所属の取得で1回、さらにネストしたグループをたどる +ために直接所属グループごとに1回ずつを順番に実行。キャッシュが未作成の場合）だけかかるため、 +ユーザーが所属するグループ数に応じて長くなります。この間にアクセスが許可されてしまうことはなく、 +拒否されるだけです。また、この時間帯をなくすための設定は必要ありません。認可は同じセッションの +リクエストごとに評価し直されるため、解決の完了後に開き直せば、ログインし直さなくても管理画面に +正常にアクセスできます。 + +.. warning:: + + この時間帯を短くするために、\ |Fess| の管理者ロールを + ``entraid.default.roles``\ に設定してはいけません。この設定は単一のグローバル設定で、\ + |Fess| はログイン時にすべてのEntra IDユーザーへ適用し、その後の解決のたびに再適用します。 + テナント内のすべてのユーザーに、永続的な |Fess| の管理者権限を与えてしまいます。 + +LDAP / Active Directory 連携を利用していた場合 +------------------------------------------------ + +15.10 から、グループやロールの権限名はエントリーの DN をテキストとして切り出すのではなく、 +RDN として解析した値になりました。DN の中でエスケープされる文字（一般的にはカンマ）を CN に含む +グループは、15.7 までとは異なる権限名になります。 + +.. list-table:: + :header-rows: 1 + + * - グループのエントリー DN + - 15.7 までの権限名 + - 15.10 の権限名 + * - ``CN=Sales\, EMEA,CN=Users,...`` + - ``2Sales`` + - ``2Sales, EMEA`` + * - ``CN=Sales\, APAC,CN=Users,...`` + - ``2Sales`` + - ``2Sales, APAC`` + +15.7 までは、カンマの手前までが一致する複数のグループが同じ権限名に潰れていたため、\ +``Sales, EMEA`` と ``Sales, APAC`` の所属者は互いの文書と ``Sales`` グループの文書を +読めていました。 +15.10 ではそれぞれ別の権限名になり、この横断的なアクセスは発生しません。 + +その代わり、\ **旧来の権限名でインデックスされた文書は、該当グループの利用者から見えなくなります**\ 。 +クロール設定の「パーミッション」に旧来の権限名を設定していた場合は、新しい権限名に更新して +再クロール（または再インデクシング）してください。CN にカンマなどを含むグループを使っていない場合、 +権限名は変わりません。 + +``ldap.role.search.user.enabled`` の挙動変更 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +15.7 までは、\ ``ldap.role.search.user.enabled=false`` を設定していても、ユーザー名から導出した +権限（``role.search.user.prefix`` ＋ ユーザー名）は付与されていました。15.10 からはこの設定が +実際に反映され、\ ``false`` の場合は付与されません。 + +``false`` を設定している環境では、アップグレード後にユーザーが自分自身の権限を失うため、 +個々のユーザーに対して設定した権限を持つ文書が検索できなくなります。従来の挙動を維持する場合は、 +同梱の既定値である ``true`` に戻してください。 + +/api/v2 の設定キーを変更していた場合 +------------------------------------------------ + +15.8.0 から、4 つの設定キーが ``api.v2.`` の接頭辞を失いました。値・既定値・挙動は変わりませんが、\ +**後方互換のための別名は用意されていません**\ 。古い名前のまま残した設定は警告もなく無視され、\ +同梱の既定値が使われます。 + +.. list-table:: + :header-rows: 1 + + * - 15.7 まで + - 15.8.0 以降 + - 既定値 + * - ``api.v2.chat.stream.keepalive.interval.ms`` + - ``api.chat.stream.keepalive.interval.ms`` + - ``15000`` + * - ``api.v2.param.max.length`` + - ``api.param.max.length`` + - ``1000`` + * - ``api.v2.param.max.array.size`` + - ``api.param.max.array.size`` + - ``100`` + * - ``api.v2.click.max.rt`` + - ``api.click.max.timestamp`` + - ``9999999999999`` + +``fess_config.properties`` または ``-Dfess.config.<キー>`` の JVM 引数でこれらを設定していた場合は、\ +新しい名前に変更してください。影響を受けるのは明示的に設定していた場合だけで、\ +変更していなかった環境で対応は不要です。 + +1 つ目のキーは ``POST /api/v2/chat/stream`` がモデルの応答を待つあいだに送出する keep-alive の\ +間隔を決めるため、設定が失われたことに気づくのは AI 検索モードの利用時になります。\ +最後のキーは名前の正確さのためにも変更されました。これはクリックログが持てる ``rt`` の値の上限で、\ +応答時間ではなくタイムスタンプを指します。 + + +.. _upgrade-plugin-versions: + +プラグインのバージョン更新 +-------------------------- + +``app/WEB-INF/plugin/`` にインストールされているプラグインは、\ |Fess| のバージョンに対応した +ものへ入れ替えが必要です。 ``bin/fess-setup upgrade plugins`` は、インストール済みのすべての +プラグインについて、この |Fess| 向けにビルドされたバージョンをインストールし、古いものを +削除します。その後 |Fess| を再起動してください。 ``bin/fess-setup check`` は、OpenSearch と +そのプラグイン、インストール済みの |Fess| プラグインの状態を報告し、問題がある場合は終了コード 1 +で終了します。 ``bin/fess.in.sh``\ 、\ ``/etc/sysconfig/fess``\ 、\ ``/etc/default/fess`` は読み込まないため、 +OpenSearch が ``http://localhost:9200`` にない場合は、 ``--url`` を指定するか、実行するシェルで +``SEARCH_ENGINE_HTTP_URL`` を設定してください。そうしないと、エンジンに接続できないと報告されます。 + +:: + + $ bin/fess-setup upgrade plugins + $ bin/fess-setup check + +``upgrade plugins`` が対象にするのはインストール済みのプラグインだけです。 ``fess-script-groovy`` +など、15.10 で配布物から外れた部分を補うプラグインは、前述の各節のとおり +``bin/fess-setup install plugin`` でインストールしてください。 + +Docker 版で ``FESS_PLUGINS`` を指定している場合は、 +``fess-ds-wikipedia:15.10.0`` のようにバージョン部分を更新してください。 + +ロールバック手順 +================ + +アップグレードに失敗した場合、以下の手順でロールバックできます。 + +ステップ 1: 新しいバージョンの停止 +---------------------------------- + +:: + + $ sudo systemctl stop fess.service + $ sudo systemctl stop opensearch.service + +ステップ 2: 古いバージョンの復元 +-------------------------------- + +バックアップから設定ファイルとデータを復元します。 + +RPM/DEB 版の場合:: + + $ sudo rpm -Uvh --oldpackage --nodeps fess-.rpm + +または:: + + $ sudo dpkg -i fess-.deb + +.. note:: + + RPM では ``--nodeps`` が必要です。15.8.0 のパッケージは ``fess`` と ``opensearch`` のユーザーとグループを + 必須としているため、指定しないと ``rpm`` は ``Failed dependencies: group(fess) is needed by fess-15.8.0`` + でダウングレードを拒否します。 + +.. warning:: + + 15.8.0 の DEB パッケージは ``/etc/fess/*`` を conffile として登録していないため、 ``dpkg -i`` は、 + 編集した ``/etc/fess/fess_config.properties`` などを、コピーを残さずに上書きします。ステップ 1 で + 取ったバックアップから戻してください。 + +ステップ 3: データの復元 +------------------------ + +スナップショットから復元します。OpenSearch を起動し、 |Fess| は停止したままにしてください。 + +1. OpenSearch を起動します:: + + $ sudo systemctl start opensearch.service + +2. スナップショットは、存在するインデックスの上には復元できません。そのため、アップグレード後に + （再インデクシングなどで）作成されたものと、OpenSearch のプラグインが作成する ``configsync`` + インデックスを含め、Fess のインデックスをすべて先に削除します。スナップショットに含まれる + インデックスだけを削除すると、再インデクシングで作られたインデックスが残り、 ``fess.search`` が + 2 つのインデックスを指して、15.8.0 が起動しません:: + + $ curl "http://localhost:9200/_cat/indices/fess*,configsync?h=index" + $ curl -X DELETE "http://localhost:9200/" + + 2 つ目のコマンドは、1 つ目が表示したインデックスごとに実行します。 + +3. スナップショットを復元します:: + + $ curl -X POST "http://localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true" + +.. note:: + + 辞書ディレクトリ（ ``configsync.config_path`` 。辞書ファイルを含む）は、以前と同じように存在している + 必要があります。失われたマシンでは、復元は完了しても、辞書を使うインデックスは red のままになります。 + +または、バックアップからディレクトリを復元（ステップ 1 で作成したアーカイブの名前を指定します）:: + + $ sudo systemctl stop opensearch + $ sudo rm -rf /var/lib/opensearch/data/* + $ sudo tar xzf /backup/opensearch-data-.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| を再起動すると失われます。 + 確実に復元するには、バックアップしたファイルを所定の場所（ZIP 版は + ``app/WEB-INF/conf/``\ 、RPM/DEB 版は ``/etc/fess/``\ ）へ直接配置してから起動してください。 + +.. note:: + + インポートは非同期で実行され、画面には開始した旨のみが表示されます。 + 実際に成功したかどうかは ``fess.log`` を確認してください。 + +ステップ 4: サービスの起動と確認 +-------------------------------- + +:: + + $ sudo systemctl start opensearch.service + $ sudo systemctl start fess.service + +動作を確認し、正常に戻ったことを確認します。 + +よくある質問 +============ + +Q: ダウンタイムなしでアップグレードできますか？ +----------------------------------------------- + +A: Fess のアップグレードには、サービスの停止が必要です。ダウンタイムを最小限にするには、以下を検討してください： + +- 事前にテスト環境で手順を確認する +- バックアップを事前に取得しておく +- メンテナンス時間を十分に確保する + +Q: OpenSearch もアップグレードする必要がありますか？ +---------------------------------------------------- + +A: |Fess| のバージョンごとに対応する OpenSearch のバージョンが決まっています。 +|Fess| 15.10 は OpenSearch 3.9.0 に対応しています。 +``opensearch-analysis-fess`` などの |Fess| 用 OpenSearch プラグインは OpenSearch のバージョンと +完全に一致している必要があるため、OpenSearch をアップグレードする場合は、 +対応するバージョン（3.9.0）のプラグインに更新してください。 + +なお |Fess| 15.10 は k-NN プラグインを必須とし、インデックス設定に ``knn.derived_source.enabled`` +を常に送信します。古い OpenSearch のままでは新しいインデックスの作成に失敗するため、 +実質的に OpenSearch のアップグレードが必要です。詳細はステップ 4 を参照してください。 + +Q: インデックスを再作成する必要がありますか？ +--------------------------------------------- + +A: |Fess| のマイナーバージョンアップ（15.x → 15.10）で、チャンクベクトル検索を利用しない場合は +通常不要です。既存インデックスはそのまま利用でき、\ ``content_chunker.enabled`` などは既定で +無効のため挙動は変わりません。 + +次の場合は再作成・再インデクシングが必要です。 + +- **新たにチャンクベクトル検索（セマンティック検索）を有効にする場合**: 既存インデックスには + 新しいマッピングが反映されないため、再インデクシングが必須です。詳細は + :ref:`semantic-search-migration`\ （:doc:`../config/search-semantic`）を参照してください。 +- **14.x からアップグレードする場合**: OpenSearch が 2.x から 3.x へメジャーバージョンアップ + するため、インデックスの再作成を推奨します。 +- **15.8 以前で作成した文書インデックスで、所有者での検索やかなの正規化を使う場合**: 再インデクシングが + 必要です。詳細は :ref:`upgrade-reindex-new-fields` を参照してください。 + +.. warning:: + + インデックスを新規に作成する操作（再インデクシングを含む）は、k-NN プラグインのない + OpenSearch では失敗します。ステップ 4 の注意事項を確認してください。 + +Q: アップグレード後、検索結果が表示されません +--------------------------------------------- + +A: 以下を確認してください： + +1. OpenSearch が起動しているか確認 +2. インデックスが存在するか確認（``curl http://localhost:9200/_cat/indices``） +3. クロールを再実行 + +次のステップ +============ + +アップグレードが完了したら： + +- :doc:`run` - 起動と初期設定の確認 +- :doc:`security` - セキュリティ設定の見直し +- :doc:`../config/search-semantic` - チャンクベクトル検索（セマンティック検索）の設定と移行手順 +- リリースノートで新機能を確認 + diff --git a/ja/15.10/user/advanced-search.rst b/ja/15.10/user/advanced-search.rst new file mode 100644 index 000000000..85b2f06b2 --- /dev/null +++ b/ja/15.10/user/advanced-search.rst @@ -0,0 +1,79 @@ +====== +詳細検索 +====== + +詳細検索画面では、複数の条件を組み合わせたより高度な検索ができます。 + +利用方法 +------ + +詳細検索画面は、検索画面の検索オプション内にある「詳細検索」のリンクからアクセスできます。検索結果画面から開いた場合は、入力済みの検索キーワードが「すべての単語を含む」欄に引き継がれます。 + +|image0| + +各項目に条件を入力し、ページ下部の「検索」ボタンを押すことで検索できます。入力した複数の項目は組み合わされて1つの検索条件になります。 + +項目一覧 +------ + +すべての単語を含む +:::::::::::::: + +入力した単語をすべて含むドキュメントを検索します（AND検索）。単語はスペースで区切って複数指定できます。 + +語順も含めた完全一致 +::::::::::::::: + +入力した文字列を語順も含めて完全に含む（フレーズ検索）ドキュメントを検索します。スペースを含む文字列全体が1つのフレーズとして扱われるため、単語ごとに区切って検索することはできません。 + +いずれかの単語を含む +::::::::::::::: + +入力した単語のいずれかを含むドキュメントを検索します（OR検索）。単語はスペースで区切って複数指定できます。 + +含めない単語 +::::::::: + +入力した単語を含まないドキュメントを検索します。単語はスペースで区切って複数指定でき、指定したすべての単語が検索結果から除外されます。 + +表示件数 +:::::: + +1ページに表示する検索結果の件数を指定できます。10、20、30、40、50、100件から選択できます。指定しない場合は、既定の表示件数（初期値は10件）が使用されます。 + +ソート +::::: + +検索結果を並び替える基準を指定できます。スコア順、ファイル名、日付、サイズ、最終更新日時から選択でき、それぞれ昇順・降順を指定できます。クリック数やお気に入り数による並び替えは、対応する機能が有効な場合に選択できます。 + +優先する言語 +::::::::: + +検索結果で優先する言語を指定できます。複数の言語を選択することもできます。「すべての言語」を選択した場合は、特定の言語を優先しません。 + +ラベル +::::: + +ラベルで絞り込み検索ができます。複数のラベルを選択することもできます。ラベルが登録されていない場合や、現在のユーザーが参照できるラベルがない場合は表示されません。 + +更新日時 +:::::: + +ドキュメントの更新日時で絞り込み検索ができます。「指定なし」「24時間以内」「1週間以内」「1ヶ月以内」「1年以内」から選択できます。 + +ファイル形式 +::::::::: + +ドキュメントのファイル形式で絞り込み検索ができます。「すべての形式」「HTML」「PDF」「MS Word」「MS Excel」「MS PowerPoint」から選択できます。 + +検索対象 +:::::: + +検索する対象を指定できます。「ページ全体」「ページ内のタイトル」「ページ内のURL」から選択できます。「ページ内のタイトル」または「ページ内のURL」を指定すると、入力した単語をタイトルまたはURLのみから検索します。 + +サイトまたはドメイン +::::::::::::::: + +入力したサイトまたはドメインで絞り込み検索ができます。特定のサイトやドメインに含まれるドキュメントのみを検索したい場合に指定します。 + +.. |image0| image:: ../../../resources/images/ja/15.10/user/advanced-search-1.png diff --git a/ja/15.10/user/chat-search.rst b/ja/15.10/user/chat-search.rst new file mode 100644 index 000000000..32efc062c --- /dev/null +++ b/ja/15.10/user/chat-search.rst @@ -0,0 +1,250 @@ +================ +AI検索モード +================ + +概要 +==== + +|Fess| のAI検索モード機能（RAGチャット）を使用すると、従来のキーワード検索に加えて、 +自然な会話形式で情報を探すことができます。質問を入力すると、AIアシスタントが +関連する文書を検索し、その内容を基にわかりやすい回答を生成します。 + +.. note:: + AI検索モードは初期状態では無効になっています。利用するには、システム管理者が + 機能を有効化し、LLM（大規模言語モデル）プロバイダーを設定しておく必要があります。 + 設定方法は :doc:`../config/rag-chat` および :doc:`../config/llm-overview` を参照してください。 + +AI検索モードの特徴 +================== + +対話形式での検索 +---------------- + +キーワードを考える代わりに、普段の会話のように質問できます。 + +例: + +- 「Fessのインストール方法を教えてください」 +- 「ファイルをクロールするにはどうすればいいですか？」 +- 「検索結果が表示されない場合の対処法は？」 + +文脈を理解した回答 +------------------ + +AIアシスタントは質問の意図を分析し、関連する文書を検索したうえで、 +複数の検索結果から必要な情報を抽出し、整理された形で回答します。 + +参照元の明示 +------------ + +回答の下部には、回答の基になった文書が「参照元」として一覧表示されます。 +各参照元は番号付きのリンクになっており、クリックすると元のドキュメントを直接確認できます。 +また、回答本文に ``[1]`` 、 ``[2]`` のような番号で引用が示される場合があり、 +これらは参照元一覧の番号に対応します。 + +会話の継続 +---------- + +一度の質問で終わりではなく、会話を続けることができます。 +AIアシスタントは前の質問や回答の文脈を踏まえて、追加の質問に回答します。 + +チャット検索の使い方 +==================== + +AI検索モードを開く +------------------ + +1. |Fess| の検索画面を開きます +2. 画面上部のナビゲーションバーにある「AI検索」リンク（ロボットのアイコン）をクリックします +3. AI検索モードの画面が表示されます + +.. note:: + 「AI検索」リンクは、AI検索モードが有効で、かつLLMプロバイダーが利用可能な場合にのみ表示されます。 + リンクが表示されない場合は、`よくある質問`_ を参照してください。 + +質問を入力する +-------------- + +1. 画面下部のテキストボックスに質問を入力します（1回の質問につき最大4000文字） +2. 送信ボタン（紙飛行機のアイコン）をクリックするか、Enterキーを押します +3. AIアシスタントが回答の生成を開始します + +.. note:: + 改行を入力したい場合は、Enterキーの代わりに Shift+Enter を押します。 + +.. note:: + 回答の生成には数秒〜十数秒かかる場合があります。処理中は、現在の処理段階が + 進捗表示（分析 → 検索 → 評価 → 取得 → 回答）として示され、 + 「考え中...」「検索中...」「検索結果を確認中...」「ドキュメント取得中...」「回答生成中...」 + のようなメッセージが表示されます。検索が完了すると、見つかった文書の件数も表示されます。 + +回答を確認する +-------------- + +AIアシスタントの回答が表示されます。回答には以下の情報が含まれます: + +- **回答本文**: 質問に対する回答（Markdown形式で整形されます） +- **参照元**: 回答の基になった文書へのリンク一覧（番号付きのリンク。クリックすると別タブで元の文書が開きます） + +回答本文中に ``[1]`` 、 ``[2]`` のような引用番号が含まれる場合があり、参照元一覧の番号に対応します。 +各回答にはコピーボタンがあり、回答内容をクリップボードにコピーできます。 + +.. note:: + AIは、検索結果のうち関連性が高いと判断した上位の文書のみを回答の根拠として使用します。 + このため、参照元の件数が検索でヒットした文書の件数より少なくなることがあります。 + +検索対象を絞り込む +------------------ + +テーマによっては、画面上部の「フィルター」ボタンから、ラベルやファイル種別・更新日時・サイズ +などの条件で検索対象を絞り込めます。特定の範囲の文書だけを対象にAIに質問したい場合に便利です。 + +会話を続ける +------------ + +追加の質問がある場合は、そのまま続けて質問できます: + +- 「もう少し詳しく教えてください」 +- 「他の方法はありますか？」 +- 「〇〇について詳しく」 + +AIアシスタントは、前の会話の文脈を考慮して回答します。 + +新しい会話を始める +------------------ + +別のトピックについて質問したい場合は、「新規チャット」ボタン（＋アイコン）をクリックします。 +これにより、それまでの会話の履歴がクリアされ、新しい会話を始められます。 + +効果的な質問のコツ +================== + +具体的に質問する +---------------- + +曖昧な質問よりも、具体的な質問の方が適切な回答が得られます。 + +.. list-table:: + :header-rows: 1 + :widths: 50 50 + + * - 曖昧な質問 + - 具体的な質問 + * - 設定方法は？ + - Fessのメモリ設定を変更する方法は？ + * - エラーが出る + - 検索時に「インデックスが見つからない」というエラーが出ます + * - クロールについて + - Webサイトをクロールする際の除外設定はどうすればいいですか？ + +背景情報を含める +---------------- + +状況や目的を含めると、より適切な回答が得られます。 + +良い例: + +- 「Docker環境でFessを動かしています。ログの保存先を変更したいのですが、どうすればいいですか？」 +- 「初めてFessを使います。まず何をすればいいですか？」 + +段階的に質問する +---------------- + +複雑な問題は、段階的に質問することで理解しやすくなります。 + +1. 「Fessでファイル共有をクロールできますか？」 +2. 「SMBプロトコルでの接続方法を教えてください」 +3. 「認証が必要な共有フォルダの場合はどうすればいいですか？」 + +よくある質問 +============ + +Q: AI検索モードが表示されません +------------------------------- + +A: AI検索モードが有効になっていない可能性があります。 +「AI検索」リンクは、機能が有効（``rag.chat.enabled=true``）で、かつLLMプロバイダー +（OpenAI、Gemini、Ollama など）が設定・利用可能な場合にのみ表示されます。 +システム管理者に、AI検索モードが有効になっているか、LLMプロバイダーが正しく設定されているかを +確認してください（詳細は :doc:`../config/rag-chat` を参照）。 + +Q: 回答が表示されるまで時間がかかります +--------------------------------------- + +A: AIが質問を分析し、文書を検索・評価してから回答を生成しているため、 +数秒〜十数秒かかる場合があります。処理中は、現在の処理段階 +（「考え中...」「検索中...」「検索結果を確認中...」「ドキュメント取得中...」「回答生成中...」）が +表示されます。 + +Q: 参照元が間違っているように見えます +------------------------------------- + +A: 参照元のリンクをクリックして、元のドキュメントを確認してください。 +AIは検索結果を基に回答を生成しますが、解釈に誤りがある場合があります。 +重要な情報は、必ず元のドキュメントで確認することをお勧めします。 + +Q: 前の会話を忘れてしまったようです +----------------------------------- + +A: 会話のセッションがタイムアウトした可能性があります。 +一定時間（既定では30分）操作がない場合、会話の履歴はクリアされます。 +また、会話の履歴はサーバーのメモリ上に一時的に保持されるため、サーバーの再起動によっても失われます。 +その場合は、新しく会話を始めてください。 + +.. note:: + ここでいう「セッション」はAI検索モードの会話セッションであり、|Fess| へのログインセッションとは別のものです。 + +Q: 特定の質問に対して回答が得られません +--------------------------------------- + +A: 以下の可能性があります: + +- 検索対象のドキュメントに関連情報がない +- 質問が曖昧で、適切な検索ができない +- レート制限に達している（1分あたりのリクエスト数の上限、または同時実行数の上限を超えている） + +質問を言い換えるか、しばらく待ってから再度試してください。 + +Q: 入力できる文字数に制限はありますか？ +--------------------------------------- + +A: 1回の質問につき最大4000文字までです。テキストボックスの下に文字数カウンターが表示され、 +上限に近づくと警告表示になります。長い質問は、要点を絞って短くしてください。 + +Q: 日本語以外で質問できますか？ +------------------------------- + +A: はい、多くの場合、英語やその他の言語でも質問できます。 +AIは、ブラウザや画面の表示言語に基づいて、可能な限り同じ言語で回答しようとします。 +ただし、これはベストエフォートであり、状況によっては意図した言語にならない場合があります。 + +注意事項 +======== + +AIの回答について +---------------- + +- AIの回答は、検索結果を基に生成されたものです +- 回答の正確性は保証されません +- 重要な判断には、必ず元のドキュメント（参照元）を確認してください +- 最新の情報は、公式ドキュメントで確認してください + +プライバシーについて +-------------------- + +- 入力した質問は、検索と、設定されたLLMプロバイダーによるAI処理のために使用されます +- 外部のLLMサービス（OpenAI や Gemini など）を利用する設定の場合、質問の内容や検索結果がそのサービスに送信されます。社内のみで処理したい場合は、ローカルで動作するプロバイダー（Ollama など）の利用について管理者に相談してください +- 会話の履歴はサーバーのメモリ上に一時的に保持され、セッションのタイムアウト、「新規チャット」の実行、またはサーバーの再起動によって削除されます +- 検索と同様に、ロール（権限）やラベルによるアクセス制御が適用され、閲覧できない文書は回答の対象になりません +- システムの設定により、ログが記録される場合があります + +参考情報 +======== + +- :doc:`../config/rag-chat` - AI検索モード機能の設定（管理者向け） +- :doc:`../config/llm-overview` - LLMプロバイダーの設定 +- :doc:`../api/api-chat` - Chat API（プログラムからの利用） +- :doc:`search-and` - AND検索の使い方 +- :doc:`search-not` - NOT検索の使い方 +- :doc:`search-field` - フィールド検索の使い方 +- :doc:`advanced-search` - 高度な検索機能 diff --git a/ja/15.10/user/index.rst b/ja/15.10/user/index.rst new file mode 100644 index 000000000..4edf34941 --- /dev/null +++ b/ja/15.10/user/index.rst @@ -0,0 +1,29 @@ +|Fess| ユーザーガイド +================== + +AND・OR・NOT、フィールド検索やラベル検索、並び替え、ワイルドカード、\ +範囲指定、ブースト、あいまい検索、近接検索、位置情報検索など、|Fess| での\ +検索の書き方を説明します。 + +.. toctree:: + :maxdepth: 2 + + intro + search-and + search-or + search-not + search-bangs + search-label + search-field + search-sort + search-wildcard + search-range + search-boost + search-fuzzy + search-proximity + search-geo + search-additional + role-search + special-char + advanced-search + chat-search diff --git a/ja/15.10/user/intro.rst b/ja/15.10/user/intro.rst new file mode 100644 index 000000000..0a3c88a9c --- /dev/null +++ b/ja/15.10/user/intro.rst @@ -0,0 +1,50 @@ +============== +検索のはじめに +============== + +対象読者 +====== + +|Fess| は、Web サイトやファイル、データベースなどに含まれるドキュメントを対象に全文検索を行える、エンタープライズ向けの検索サーバーです。 + +このドキュメントは |Fess| を利用するユーザーを対象にしています。 + +お読みになる前に +============ + +このドキュメントでは、 |Fess| での検索方法を説明します。基本的なキーワード検索に加えて、詳細検索画面を使った絞り込み検索や、自然な会話形式で情報を探せる AI 検索モードについても解説します。コンピューター操作の基礎的な知識が必要になります。 + +オンラインでのアクセス +================= + +ダウンロード、専門的サービス、サポート、その他の開発者情報については、次にアクセスしてください。 + +- プロジェクトサイト: https://fess.codelibs.org/ + +技術的なサポートの連絡先 +================== + +本製品に関する技術的質問で、ドキュメント内に解決策が得られない場合は、次にアクセスしてください。 + +- Issues: + `https://github.com/codelibs/fess/issues `__ + +商用サポート +--------- + +本製品に関する技術的対応や保守などの商用サポートが必要な場合は、`N2SM, Inc. `__ にご相談ください。 + +関連サードパーティー Web サイトの参照 +============================= + +|Fess| プロジェクトでは、このドキュメントに記載されているサードパーティーの Web サイトの有効性については責任を持ちません。\ |Fess| プロジェクトはそのようなサイトやリソースを通じて、利用可能なコンテンツ、広告、製品、サービス、その他のドキュメントなどについて、保証、責任、義務を負いません。\ |Fess| プロジェクトはそのようなサイトやリソースを通じて、利用可能なコンテンツ、広告、製品、サービス、その他のドキュメントなどを、使用または信用したり、それに関連して発生または申し立てられた、一切の損傷や損害に対しては責任または義務を負いません。 + +コメントおよび提案の送付方法 +===================== + +|Fess| +プロジェクトは、このドキュメントの改善に努めており、読者からのコメントおよび提案などを歓迎しています。 + +- Issues: + `https://github.com/codelibs/fess-docs/issues `__ + diff --git a/ja/15.10/user/role-search.rst b/ja/15.10/user/role-search.rst new file mode 100644 index 000000000..81dfb5e77 --- /dev/null +++ b/ja/15.10/user/role-search.rst @@ -0,0 +1,58 @@ +======== +ロール検索 +======== + +|Fess| はユーザー管理機能を提供しており、ログインしたユーザーは自分が所属するロールに基づいて検索できます。\ |Fess| で管理しているユーザーは、ログイン後にロール検索を利用したり、自分のパスワードを変更したりできます。 + +ロール検索では、コンテンツに設定されたパーミッション（ロール・グループ・ユーザー）と、検索するユーザーが持つパーミッションを照合し、アクセスが許可されたコンテンツだけを検索結果に表示します。ロールやユーザーの作成方法、およびコンテンツへのパーミッションの割り当て方法など、ロールベース検索の設定については :doc:`../config/security-role` を参照してください。 + + +検索方法 +------ + +ロールを設定して、クロールおよびインデックスしてある状態であれば、検索結果はそのロールを保持したユーザーだけに表示することができます。 +ユーザーがログインしている場合は、そのユーザーが所属するロールやグループに基づいて検索が行われます。 +ログインしていない場合は guest ユーザーとして検索され、guest 向けに公開されたコンテンツのみが表示されます。 + +.. note:: + ログインしたユーザーの検索は、そのユーザー自身と所属するロール・グループのパーミッションだけで行われ、guest 向け（``{role}guest``）に公開したコンテンツは対象になりません。そのため、guest 向けにだけ公開したコンテンツは、ログインしない訪問者には表示されますが、ログインしたユーザーには（ロールやグループを持たないユーザーも含めて）表示されません。ログインしたユーザーにも見せたいコンテンツには、クロール設定のパーミッションに ``{role}guest`` に加えて、そのユーザーが持つロール（全員に見せる場合は全ユーザーに付与したロール）も設定してください。 + +ログイン +------ + +検索画面の上部に表示されるログインリンクをクリックすると、ログイン画面が表示されます。ユーザー名とパスワードを入力してログインすると検索画面に戻り、以降の検索はそのユーザーが所属するロールに基づいて行われます。 + +.. note:: + シングルサインオンや LDAP と連携している場合は、それぞれの認証方式でログインします。また、ログインリンクの表示有無は設定により変更できます。 + +パスワードの変更 +------------ + +ログイン後、検索画面の上部に表示されるユーザー名をクリックすると、メニューが表示されます。 + +|image0| + +メニューの中から「パスワード変更」をクリックすると、パスワードの変更画面が表示されます。 + +|image1| + +現在のパスワード、新しいパスワード、および確認用の新しいパスワード（再入力）を入力して、更新ボタンをクリックすることでパスワードが更新されます。 +パスワードを変更するとログアウトされるため、新しいパスワードでログインし直してください。 +この画面は検索画面のテーマの ``/profile`` ページで、パスワードは ``POST /api/v2/auth/password`` で変更されます（ :doc:`../api/api-auth` を参照）。 + +.. note:: + 「パスワード変更」メニューは、|Fess| で管理しているユーザー（および編集が許可された LDAP ユーザー）にのみ表示されます。シングルサインオンで認証したユーザーには表示されません。 + 新しいパスワードには、長さや使用できる文字種などのパスワードポリシーが適用される場合があります。 + +ログアウト +-------- + +ログインしている状態で検索画面の上部に表示されるユーザー名をクリックし、メニューの中から「ログアウト」を選択することでログアウトできます。 +管理者権限を持つユーザーの場合は、同じメニューから「管理」を選択して管理画面に移動することもできます。 + + + +.. |image0| image:: ../../../resources/images/ja/15.10/user/role-search-1.png +.. pdf :width: 200 px +.. |image1| image:: ../../../resources/images/ja/15.10/user/role-search-2.png +.. pdf :width: 300 px diff --git a/ja/15.10/user/search-additional.rst b/ja/15.10/user/search-additional.rst new file mode 100644 index 000000000..d44a72e9b --- /dev/null +++ b/ja/15.10/user/search-additional.rst @@ -0,0 +1,30 @@ +=========== +非表示検索条件 +=========== + +画面上に検索条件の文字列を表示せずに、特定の検索条件を引き回したい場合は ``ex_q`` パラメーターを利用できます。\ ``ex_q`` に指定した条件は検索キーワードの入力欄には表示されず、ページングやファセット絞り込みで画面が更新されても保持されます。 + +``ex_q`` には、通常の検索キーワード（``q``）と同じクエリー構文（``field:value`` 形式、フレーズ、範囲指定、``OR`` などの演算子）を記述できます。指定した条件は ``q`` の条件と既定では AND で結合されて検索が実行されます。つまり ``ex_q`` の条件に一致しないドキュメントは検索結果から除外されます。 + +利用方法 +------ + +検索を実行する際（たとえば検索フォームなど）に、hidden フォームフィールドまたは URL のクエリーパラメーターとして ``ex_q`` の値を付加して検索を実行します。これにより、条件を画面に表示することなく検索できます。 + +``ex_q`` は複数指定できます。次の例のように複数の ``ex_q`` を渡すと、それぞれが検索条件として追加されます（空の値や重複した値は無視されます）。 + +.. code-block:: none + + /search?q=keyword&ex_q=label:manual&ex_q=filetype:pdf + +ページング時の保持 +---------- + +ページング（次ページ・前ページなど）やファセット絞り込みのリンクには、Fess が自動的に ``ex_q`` の値を付加します。そのため、これらの操作で画面が更新されても ``ex_q`` の条件は保持されます。 + +一方、標準の検索キーワード入力欄（検索ボックス）からキーワードを入力して再検索した場合、``ex_q`` は引き継がれません。検索ボックス経由でも条件を保持したい場合は、独自の検索フォームに ``ex_q`` の hidden フィールドを用意し、検索のたびに ``ex_q`` を送信してください。 + +.. note:: + + * ``ex_q`` の各値の長さが ``query.max.length`` （既定値: 1000 文字）を超えた場合、その値はエラーにならず無視されます。 + * ``ex_q`` は Web 画面の検索だけでなく、検索 API（``/api/v2``）でも利用できます。API では、1 リクエストあたりの ``ex_q`` の要素数の上限（``api.v2.param.max.array.size`` 、既定値: 100）と、各要素の長さの上限（``api.v2.param.max.length`` 、既定値: 1000 文字）が適用されます。 diff --git a/ja/15.10/user/search-and.rst b/ja/15.10/user/search-and.rst new file mode 100644 index 000000000..c4fa2a7d7 --- /dev/null +++ b/ja/15.10/user/search-and.rst @@ -0,0 +1,46 @@ +======= +AND 検索 +======= + +複数の検索語がすべて含まれるドキュメントを検索したい場合には AND 検索を利用します。検索語入力欄に複数単語をスペース区切りで記述した場合、デフォルトで AND 検索になるため、AND を省略しても同じ結果が得られます。 + +利用方法 +------ + +AND 検索を利用する場合は検索語間に AND を記述します。AND +は半角大文字で記述して、前後にスペースが必要になります。AND +は省略することも可能です。 + +たとえば、「検索語1」と「検索語2」の両方が含まれるドキュメントを検索したい場合は以下のように検索フォームに入力します。 + +:: + + 検索語1 AND 検索語2 + +AND を省略して次のように記述しても同じ結果になります。 + +:: + + 検索語1 検索語2 + +AND で 3 つ以上の検索語をつなぐこともできます。 + +:: + + 検索語1 AND 検索語2 AND 検索語3 + +.. note:: + + AND は半角大文字で記述する必要があります。\ ``and`` のように小文字で記述した場合は演算子として扱われず、「and」という通常の検索語として検索されます。\ ``&&`` も AND と同じ意味で利用できます。 + +丸括弧 ``( )`` を利用すると、AND 検索と他の検索条件を組み合わせることができます。たとえば「検索語1」を含み、かつ「検索語2」または「検索語3」のいずれかを含むドキュメントを検索したい場合は以下のように入力します。 + +:: + + 検索語1 AND (検索語2 OR 検索語3) + +フィールドを指定して AND 検索を行うこともできます。次の例では、title フィールドに「検索語1」を含み、かつ content フィールドに「検索語2」を含むドキュメントを検索します。 + +:: + + title:検索語1 AND content:検索語2 diff --git a/ja/15.10/user/search-bangs.rst b/ja/15.10/user/search-bangs.rst new file mode 100644 index 000000000..7852be114 --- /dev/null +++ b/ja/15.10/user/search-bangs.rst @@ -0,0 +1,80 @@ +============================== +バング検索（別のサイトで検索） +============================== + +バング(bang)は、|Fess| で検索する代わりに、別のサイトへ検索を送る機能です。DuckDuckGo のバングと同じ使い方で、検索語に ``!`` と短いトリガー語を加えると、|Fess| は残りの検索語をそのトリガー語が表すサイトへ送ります。 + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - 検索語 + - 送り先 + * - ``airplane !g`` + - Google で ``airplane`` を検索 + * - ``!w Ohm's law`` + - Wikipedia で ``Ohm's law`` を検索 + * - ``!g`` + - Google のトップページ + * - ``airplane !unknown`` + - |Fess| での通常の検索(``!`` は NOT の意味です。:doc:`search-not` を参照) + +バングは ``fess-webapp-bangs`` プラグインが提供します。|Fess| 15.10 以降が必要です。管理画面の [システム > プラグイン] か ``bin/fess-setup install plugin fess-webapp-bangs`` でインストールし(:doc:`../admin/plugin-guide` を参照)、|Fess| を再起動します。 + +バングとして扱われる条件 +======================== + +- バングは ``!`` にトリガー語を続けたもので、独立した単語として記述します。トリガー語は大文字・小文字を区別しません。 +- バングは検索語から取り除かれ、残りの検索語がバングの URL に送られます。 +- 定義済みのバングが検索語に複数含まれる場合は、最初の 1 つだけが有効です。 +- 定義されていないトリガー語はバングではありません。``!unknown`` は通常どおり検索され、単語 ``unknown`` を除外します。 +- ``-g`` や ``NOT g`` はこれまでどおり単語 ``g`` を除外します。バングになるのは ``!g`` だけです。 + +検索画面と ``/api/v2/search`` はリダイレクトに対応しています。API は ``redirect_url`` を返し(:doc:`../api/api-search` を参照)、|Fess| に同梱の ``bootstrap`` テーマはその URL へ移動します。ほかのテーマでは同様の処理が必要です。 + +チャット、MCP、v1 API・クラシック JSON API、管理画面の検索など、リダイレクトできない呼び出し元では、別サイトへ検索を送りません。バングを取り除き、残りの検索語で検索します。 + +バングの定義 +============ + +バングはシステムプロパティ ``bangs.definitions`` で定義します。``app/WEB-INF/conf/system.properties`` に記述するか、``-Dfess.system.bangs.definitions=...`` として渡します。``system.properties`` の変更は、|Fess| を再起動しなくても反映されます。 + +値は ``トリガー語=URL`` の空白区切りのリストです。URL の中の ``{query}`` は、URL エンコードした残りの検索語に置き換えられます。 + +:: + + bangs.definitions=g=https://www.google.com/search?q={query} w=https://en.wikipedia.org/wiki/Special:Search?search={query} + +- トリガー語には、空白、``(``、``)``、``!``、``"``、``=``、``:`` を含められません。 +- 受け付けるのは、絶対 URL の ``http`` または ``https`` だけです。 +- この規則に合わない項目は使われません。|Fess| のログに警告が出力され、ほかの項目は有効なままです。 +- 同じトリガー語を 2 回定義した場合は、最初の定義が使われます。 +- 値を空にすると、すべてのバングが無効になります。 + +``bangs.definitions`` を設定していない場合は、次の 5 つのバングが使えます。 + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - トリガー語 + - サイト + * - ``g`` + - Google + * - ``b`` + - Bing + * - ``ddg`` + - DuckDuckGo + * - ``w`` + - Wikipedia(英語) + * - ``gh`` + - GitHub + +``bangs.definitions`` を設定すると、この一覧は置き換わります。既定のバングを残したまま 1 つ足したい場合は、必要な項目をすべて記述してください。 + +関連項目 +======== + +- :doc:`search-not` - NOT 検索の書き方 +- :doc:`special-char` - 特殊文字とエスケープ +- :doc:`../api/api-search` - 検索 API diff --git a/ja/15.10/user/search-boost.rst b/ja/15.10/user/search-boost.rst new file mode 100644 index 000000000..976b27c95 --- /dev/null +++ b/ja/15.10/user/search-boost.rst @@ -0,0 +1,46 @@ +========= +ブースト検索 +========= + +ブースト検索(重み付け検索) +==================== + +検索語のうち、特定の検索語を優先したい場合にはブースト検索を利用します。ブースト検索を利用することで、検索語の重要度に応じた検索が可能になります。 + +利用方法 +------ + +ブースト検索を利用するためには、検索語の直後に「^ブースト値」という形式でブースト値 (重み付け値) を指定します。検索語とブースト値の間にはスペースを入れずに記述してください。 + +たとえば、「りんご みかん」を検索する際に「りんご」をより優先したい場合は、以下のように検索フォームに入力します。 + +:: + + りんご^100 みかん + +この例では「りんご」にのみブースト値が適用され、「みかん」には適用されません。 + +ブースト値 +-------- + +ブースト値には数値を指定します。整数だけでなく、``2.5`` のような小数も指定できます。 + +- 1 より大きい値を指定すると、その検索語の重みが増加します。 +- 0 より大きく 1 未満の値 (例: ``0.5``) を指定すると、その検索語の重みが減少します。 + +ブースト値は検索結果のスコアを絶対的に決めるものではなく、他の検索語との相対的な重み付けを調整するものです。 + +他の検索構文との組み合わせ +-------------------- + +ブースト検索は他の検索構文と組み合わせて利用できます。たとえば、フィールドを指定した検索語にブースト値を付加することもできます。 + +:: + + title:りんご^100 みかん + +この例では、複数の検索語を並べた場合の既定の演算子 (AND) が適用されるため、title フィールドに「りんご」を含み、かつ「みかん」を含むドキュメントだけが検索されます。「りんご」を含むドキュメントを優先しつつ、含まないドキュメントも結果に残したい場合は、OR で結合します。 + +:: + + title:りんご^100 OR みかん diff --git a/ja/15.10/user/search-field.rst b/ja/15.10/user/search-field.rst new file mode 100644 index 000000000..ff5e05705 --- /dev/null +++ b/ja/15.10/user/search-field.rst @@ -0,0 +1,122 @@ +================================================== +フィールド指定検索（タイトル・URL などで絞り込む） +================================================== + +フィールド指定検索 +============== + +特定のフィールドだけを対象にした検索(フィールド検索)を行うことで、タイトルだけ・URLだけといった絞り込みができます。 + +|Fess| でクロールした結果は、タイトルや本文などのフィールドごとに保存されています。それらのフィールドを指定して検索することで、ドキュメントの種類別やサイズ別など、細かい検索条件を指定できます。 + +利用可能なフィールド +--------------- + +デフォルトでは、以下のフィールドを指定して検索できます。 + +.. list-table:: + :header-rows: 1 + + * - フィールド名 + - 説明 + - データ型 + * - url + - クロールした URL + - キーワード + * - host + - クロールした URL に含まれるホスト名 + - キーワード + * - site + - URL からスキームとクエリー文字列を除いた文字列（ホスト名とパス）。前方一致で検索されます + - キーワード + * - title + - タイトル + - テキスト + * - content + - 本文 + - テキスト + * - content_length + - ドキュメントのサイズ（バイト） + - 数値 + * - last_modified + - ドキュメントの最終更新日時 + - 日時 + * - timestamp + - ドキュメントの登録日時（最終更新日時を取得できない場合はクロール実行時刻） + - 日時 + * - mimetype + - ドキュメントの MIME タイプ（例: ``text/html``） + - キーワード + * - filetype + - MIME タイプから決まるファイル種別（例: ``html``、``word``、``pdf``\ 。該当しない場合は ``others``） + - キーワード + * - filename + - URL のパス末尾のファイル名 + - キーワード + * - label + - ドキュメントに付与されたラベルの値 + - キーワード + * - lang + - ドキュメントの言語コード（例: ``ja``、``en``） + - キーワード + * - anchor + - HTML ページ内から抽出したリンク先 URL（Web クロールのみ） + - キーワード + * - click_count + - ドキュメントがクリックされた回数 + - 数値 + * - favorite_count + - ドキュメントがお気に入り登録された回数 + - 数値 + * - owner + - ファイルの所有者のアカウント名 + - キーワード + * - last_modifier + - ファイルの最終更新者 + - キーワード + +表: 利用可能なフィールド一覧 + +「データ型」は、フィールドごとの検索方法の違いを表します。 + +* キーワード: 値全体を対象に完全一致で検索します。ワイルドカード検索やプレフィックス検索と組み合わせることもできます。 +* テキスト: 形態素解析などで分割された語を対象に全文検索します。title や content が該当します。 +* 数値・日時: :doc:`範囲指定検索 ` を利用できます。 + +フィールドを指定しない場合は、title および content を対象に検索します。設定によって、検索対象とするフィールドを追加することもできます。 + +.. note:: + クロール対象によっては値が登録されないフィールドもあります。たとえば anchor は Web クロール時のみ登録されます。lang には、HTML の言語属性、または本文から判定した言語が登録されます。言語を判定できない場合や、判定した言語が ``supported.languages`` にない場合は登録されません。また、segment（クロール実行単位を表すセッション ID）や doc_id（システムが採番する内部 ID）などのフィールドも指定できますが、通常の検索では利用しません。 + +owner と last_modifier は、ファイルサーバーなどのクロールで登録されます。owner には SMB、ファイルシステム、FTP のクロールで取得したファイルの所有者のアカウント名が入ります（ ``DOMAIN\alice`` のような値は ``alice`` になります）。last_modifier には Office 文書などから抽出した最終更新者が入り、取得できない場合は所有者が入ります。Web クロールした HTML には owner は登録されません。たとえば ``owner:alice`` や ``last_modifier:"Taro Yamada"`` のように検索します。同梱のテーマでは、詳細検索で所有者と最終更新者を指定できます。登録するかどうかは、管理者が ``crawler.document.file.owner.enabled`` と ``crawler.document.file.last.modifier.enabled`` （どちらもデフォルトは ``true`` ）で切り替えられます。 + +HTML ファイルを検索対象としている場合、title タグが title フィールドに、body タグ以下の文字列が content フィールドに登録されます。 + +利用方法 +------ + +フィールド指定検索をする場合は、「フィールド名:検索語」のように、フィールド名と検索語をコロン(:)で区切って検索フォームに入力します。 + +title フィールドに対して fess を検索語として検索する場合は、以下のように入力します。 + +:: + + title:fess + +上記の検索により、title フィールドに fess が含まれるドキュメントが検索結果として表示されます。 + +url フィールドに対して検索する場合は、以下のように入力します。 + +:: + + url:https\:\/\/fess.codelibs.org\/ja\/15.10\/* + url:"https://fess.codelibs.org/ja/15.10/*" + +前者はワイルドカード検索が使えるので、 ``url:*\/\/fess.codelibs.org\/*`` のような書き方もできます。url に含まれる「:」や「/」は検索クエリーの特殊文字なので、``\`` を付けてエスケープしてください（:doc:`special-char` を参照）。後者はワイルドカード検索は使えませんが、末尾を ``*`` にした語はプレフィックス（前方一致）検索として扱われます。 + +.. tip:: + URL の一部で検索したい場合は、``inurl:`` を使うと URL に対する部分一致検索ができます。たとえば ``inurl:15.10`` は、URL に ``15.10`` を含むドキュメントを検索します。 + +mimetype や filetype、site のように値に「/」を含むフィールドを指定する場合は、``mimetype:"text/html"`` のように引用符で囲むか、``mimetype:text\/html`` のようにエスケープしてください。 + +関連する検索構文については、:doc:`ワイルドカード検索 ` 、 :doc:`範囲指定検索 ` 、 :doc:`ソート検索 ` 、 :doc:`特殊文字 ` も参照してください。 diff --git a/ja/15.10/user/search-fuzzy.rst b/ja/15.10/user/search-fuzzy.rst new file mode 100644 index 000000000..13d883562 --- /dev/null +++ b/ja/15.10/user/search-fuzzy.rst @@ -0,0 +1,67 @@ +====== +曖昧検索 +====== + +曖昧検索(ファジー検索) +================= + +検索語に完全一致しない単語も検索したい場合には曖昧検索(ファジー検索)を利用できます。タイプミスや表記ゆれ、つづり違いなどで完全一致しないドキュメントも拾いたい場合に有効です。曖昧検索は、検索語とインデックスに登録されている単語との違い(編集距離)が一定の範囲内であれば、その単語を一致とみなして検索する方法です。編集距離とは、ある単語を別の単語に変換するために必要な文字の挿入・削除・置換などの最小回数のことです。\ |Fess| では、既定でこれらの操作に加えて隣接する 2 文字の入れ替えも 1 回の違いとして数えるダメラウ・レーベンシュタイン距離(最適文字列アライメント)を使用します。 + +利用方法 +------ + +曖昧検索を適用したい検索語の後に「~」を付加します。 + +たとえば、「fess」という単語を曖昧検索したい場合、以下のように検索フォームに入力することで、「fess」に近い語 (「fes」など) を含むドキュメントを検索できます。 + +:: + + fess~ + +「~」の後ろに数字を付けると、許容する編集距離 (何文字までの違いを許容するか) を指定できます。指定できる値は 0、1、2 のいずれかの整数です。 + +:: + + fess~1 + +上記の場合は、「fess」との編集距離が 1 以内の単語を検索します。 + +数字を省略して「~」のみを指定した場合は、編集距離 2 として扱われます。編集距離の最大値は 2 であり、3 以上の値を指定した場合も 2 として扱われます。 + +フィールドを指定して曖昧検索を行うこともできます。次の例では、title フィールドに「fess」に近い語を含むドキュメントを検索します。 + +:: + + title:fess~ + +フィールドを指定しない場合は、title および content フィールドを対象に曖昧検索を行います。 + +利用条件 +------ + +曖昧検索を利用する際は以下の点に注意してください。 + +* 曖昧検索は単語単位で適用されます。引用符で囲んだフレーズには適用できません。なお、フレーズの後ろに付けた数字 (たとえば ``"Fess Search"~2``) は、曖昧検索ではなく単語間の距離を表す\ :doc:`近接検索 `\ になります。 +* 曖昧検索はインデックスに登録された単語を対象に行われ、検索語は再解析されません。そのため、bi-gram や形態素解析でトークン化される日本語などのテキストでは期待どおりに動作しないことがあります。曖昧検索は主に英数字の単語で有効です。 +* 曖昧検索の検索語は、大文字と小文字の区別を含めてそのまま編集距離を数えます。インデックスに登録される英字の単語は通常小文字に変換されているため、検索語には小文字を使用してください。たとえば ``Fess~1`` は先頭の大文字 ``F`` だけで編集距離 1 を使い切るため、``fess~1`` と同じ結果にはなりません。また、``Fess~0`` は ``Fess`` という大文字の語に一致する語がインデックスに無いため、何も一致しません (小文字の ``fess~0`` は完全一致です)。 +* 1〜2 文字などの非常に短い単語に「~」(編集距離 2) を付けると、語の長さに近い文字数を置き換えただけの語にも一致します。たとえば ``ab~`` は ``ab`` や ``ac`` に加えて、2 文字とも異なる ``xy`` にも一致します。意図しない結果が増えるため、短い単語には ``ab~1`` のように小さい編集距離を指定してください。 + +.. note:: + + 曖昧検索の動作は ``fess_config.properties`` で調整できます。 + + * ``query.fuzzy.prefix_length`` (既定値: ``0``): 先頭から完全に一致させる文字数です。値を大きくすると、誤りを許容する範囲が狭くなります。 + * ``query.fuzzy.expansions`` (既定値: ``50``): 一致候補として展開する単語の最大数です。 + * ``query.fuzzy.transpositions`` (既定値: ``true``): 隣接する 2 文字の入れ替えを 1 回の編集として数えるかどうかを指定します。\ ``true`` の場合はダメラウ・レーベンシュタイン距離、``false`` の場合は古典的なレーベンシュタイン距離になります。 + +.. note:: + + 「~」を付けない通常の検索でも、|Fess| は一定の長さ以上 (既定では 4 文字以上) の検索語に対して、関連度を高める目的でわずかな重み付けの曖昧一致を自動的に補助として加えます (``query.boost.fuzzy.*``)。これは主に検索結果の順位付けを調整するための機能であり、「~」による曖昧検索とは別の仕組みです。ただし、この補助的な一致も検索結果に含まれるため、検索語そのものを含まない、1 文字違いの語だけを含むドキュメントが結果に加わることがあります (検索語そのものを含むドキュメントのほうが上位になります)。この動作を止めたい場合は、``query.boost.fuzzy.min.length`` に負の値 (例: ``-1``) を指定してください。 + + +関連項目 +======== + +- :doc:`search-wildcard` +- :doc:`search-proximity` +- :doc:`special-char` diff --git a/ja/15.10/user/search-geo.rst b/ja/15.10/user/search-geo.rst new file mode 100644 index 000000000..951412b3b --- /dev/null +++ b/ja/15.10/user/search-geo.rst @@ -0,0 +1,56 @@ +============ +位置情報検索 +============ + +インデックス生成時に各ドキュメントへ緯度・経度の位置情報を付加しておくことで、検索時に指定した地点からの距離を条件とした絞り込みが可能になります。 + +概要 +---- + +位置情報検索では、指定した地点（緯度・経度）を中心とする半径内に含まれるドキュメントだけを検索結果に含めます。この絞り込みは OpenSearch の geo_distance クエリを利用したフィルターとして適用されるため、スコア（関連度）には影響しません。また、距離による並べ替えには対応していません。 + +位置情報を格納するフィールドは、OpenSearch のマッピングで ``geo_point`` 型として定義されている必要があります。標準では ``location`` フィールドが ``geo_point`` 型として用意されています。ただし、``location`` フィールドへ値を格納する処理は標準では用意されていないため、データストアクロールのフィールドマッピングやスクリプト、検索エンジンへドキュメントを登録する API などを用いて、利用者側で位置情報を格納する必要があります。 + +利用方法 +-------- + +位置情報検索は、検索リクエストに以下のパラメーターを付加して指定します。標準では ``location`` フィールドに対して利用できます。 + +.. list-table:: + :header-rows: 1 + + * - パラメーター + - 説明 + * - ``geo..point`` + - 中心となる地点の緯度・経度を ``緯度,経度`` の形式で指定します。値は10進数の度（Double 型）で、カンマ区切りで2つの数値を指定します。例: ``35.681236,139.767125`` + * - ``geo..distance`` + - 中心地点からの距離（半径）を指定します。例: ``10km`` + +表: リクエストパラメーター + +```` には位置情報を格納したフィールド名を指定します。指定できるのは ``query.geo.fields`` に登録されているフィールドのみで、標準では ``location`` です。それ以外のフィールドを利用する場合は、``geo_point`` 型としてマッピングした上で、``fess_config.properties`` の ``query.geo.fields`` にカンマ区切りで追加します。 + +たとえば、緯度 35.681236・経度 139.767125（東京駅付近）から半径10km以内のドキュメントを検索する場合は、検索リクエストに以下のパラメーターを付加します。 + +:: + + geo.location.point=35.681236,139.767125&geo.location.distance=10km + +距離の単位 +---------- + +``geo..distance`` の値は OpenSearch の距離単位として解釈されます。\ ``km``\ （キロメートル）のほか、``mm``、``cm``、``m``、``in``、``ft``、``yd``、``mi``\ （マイル）、``nmi``\ （海里）などが利用できます。単位を省略して数値のみを指定した場合はメートルとして扱われます（例: ``500`` は500メートル）。 + +複数指定 +-------- + +* 同一フィールドに対して ``geo..point`` を複数指定した場合、いずれかの地点の半径内に含まれるドキュメントが検索されます（OR 条件）。 +* 異なるフィールドに対してそれぞれ位置情報を指定した場合、すべての条件を満たすドキュメントが検索されます（AND 条件）。 + +.. note:: + + ``geo..point`` と ``geo..distance`` は両方を指定する必要があります。\ ``distance`` が指定されていない場合、その ``point`` の条件は無視されます。また、``point`` の値が ``緯度,経度`` の形式（カンマ区切りの2つの数値）でない場合や、数値として解釈できない場合はエラーになります。 + +.. note:: + + 位置情報検索は検索語に対する絞り込みなので、検索語が空の場合は検索が実行されず、結果は 0 件になります。位置情報検索のリクエストには、検索語を指定してください。 diff --git a/ja/15.10/user/search-label.rst b/ja/15.10/user/search-label.rst new file mode 100644 index 000000000..18a73a019 --- /dev/null +++ b/ja/15.10/user/search-label.rst @@ -0,0 +1,29 @@ +=========== +ラベル指定検索 +=========== + +ラベル指定検索 (カテゴリ検索) +======================= + +検索対象のドキュメントにカテゴリ分けするためのラベル情報を付加することで、検索時にラベルを指定した絞り込み検索が可能です。ラベルを利用すると、たとえば部署やサイト、ドキュメントの種類ごとに検索範囲を限定できます。 + +ラベルは管理画面であらかじめ登録しておくことで、検索画面でラベルによる絞り込みが利用できるようになります。利用可能なラベルは検索時にプルダウンで複数選択でき、複数のラベルを選択した場合は、いずれかのラベルが付与されたドキュメントが検索対象になります。ラベルを登録していない場合は、ラベルのプルダウンボックスは表示されません。 + +.. note:: + ラベルにはパーミッションを設定できるため、検索するユーザーがアクセスを許可されたラベルだけがプルダウンに表示されます。また、仮想ホストやロケール（言語）によって表示されるラベルが切り替わる場合もあります。そのため、ラベルを登録していても、ユーザーによってはプルダウンに表示されないことがあります。 + +ラベルは、ラベルを付加する対象を URL のパスの正規表現で指定して定義します。ラベルの登録方法や設定項目については、:doc:`ラベルの管理ガイド <../admin/labeltype-guide>` を参照してください。 + +利用方法 +------ + +検索時にラベル情報を選択することができます。ラベル情報は「オプション」ボタンを押下することで表示される検索オプション内で選択することができます。 + +|image0| + +ラベルを設定してインデックスを作成することで、ラベルが設定されたドキュメントごとに検索をすることができます。ラベルを指定しない検索は通常と同様の全件検索になります。 + +ドキュメントへのラベルの付与は、クロールしてインデックスを作成するときに、ドキュメントの URL とラベルに設定されたパスを照合して行われます。そのため、ラベルの定義（対象とするパスや除外するパス）を追加・変更した場合、その内容はすでにインデックスされているドキュメントには自動では反映されません。変更を反映するには、対象のドキュメントを再度クロールするか、スケジューラに登録されている「Label Updater」ジョブを実行してインデックスを更新してください。 + +.. |image0| image:: ../../../resources/images/ja/15.10/user/search-label-1.png +.. pdf :width: 300 px diff --git a/ja/15.10/user/search-not.rst b/ja/15.10/user/search-not.rst new file mode 100644 index 000000000..b5f7d6ae2 --- /dev/null +++ b/ja/15.10/user/search-not.rst @@ -0,0 +1,49 @@ +==================== +NOT 検索（除外検索） +==================== + +ある単語を含まないドキュメントを検索する場合に NOT 検索が利用できます。 + +この検索は除外検索とも呼ばれ、特定のキーワードを検索結果から除外してノイズを減らしたい場合に便利です。 + +利用方法 +------ + +NOT 検索は含まない単語の前に NOT を付けて検索します。NOT +は半角大文字で、前後にスペースが必要です。 + +たとえば、「検索語1」が含まれるが「検索語2」を含まないドキュメントを検索したい場合は以下のように入力して検索します。 + +:: + + 検索語1 NOT 検索語2 + +.. note:: + + NOT は半角大文字で記述する必要があります。\ ``not`` のように小文字で記述した場合は演算子として扱われず、「not」という通常の検索語として検索されます。また、除外したい単語の直前に ``-`` を付けて ``検索語1 -検索語2`` のように記述しても、NOT と同じ意味になります。 + +丸括弧 ``( )`` を利用すると、NOT 検索と他の検索条件を組み合わせることができます。たとえば「検索語1」または「検索語2」のいずれかを含み、かつ「検索語3」を含まないドキュメントを検索したい場合は以下のように入力します。 + +:: + + (検索語1 OR 検索語2) NOT 検索語3 + +フィールドを指定して NOT 検索を行うこともできます。次の例では、title フィールドに「検索語1」を含み、かつ title フィールドに「検索語2」を含まないドキュメントを検索します。 + +:: + + title:検索語1 NOT title:検索語2 + +NOT 検索は「除外検索」「ノット検索」とも呼ばれます。 + + +.. note:: + + ``fess-webapp-bangs`` プラグインをインストールすると、``!g`` のように定義されたバングは除外検索ではなくなり、別のサイトへ検索を送ります。:doc:`search-bangs` を参照してください。 + +関連項目 +------ + +- :doc:`search-and` +- :doc:`search-or` +- :doc:`special-char` diff --git a/ja/15.10/user/search-or.rst b/ja/15.10/user/search-or.rst new file mode 100644 index 000000000..a1fe6dd81 --- /dev/null +++ b/ja/15.10/user/search-or.rst @@ -0,0 +1,39 @@ +============================= +OR 検索（いずれかを含む検索） +============================= + +検索語のどれかが含まれるドキュメントを検索したい場合には OR 検索を利用します。検索語入力欄に複数単語を記述した場合、デフォルトでは AND 検索になります。 + +利用方法 +------ + +OR 検索を利用する場合は検索語間に OR を記述します。OR +は半角大文字で記述して、前後にスペースが必要になります。 + +たとえば、「検索語1」と「検索語2」のどちらかが含まれるドキュメントを検索したい場合は以下のように検索フォームに入力します。 + +:: + + 検索語1 OR 検索語2 + +OR で 3 つ以上の検索語をつなぐこともできます。 + +:: + + 検索語1 OR 検索語2 OR 検索語3 + +.. note:: + + OR は半角大文字で記述する必要があります。\ ``or`` のように小文字で記述した場合は演算子として扱われず、「or」という通常の検索語として検索されます。\ ``||`` も OR と同じ意味で利用できます。 + +丸括弧 ``( )`` を利用すると、OR 検索と他の検索条件を組み合わせることができます。たとえば「検索語1」または「検索語2」のいずれかを含み、かつ「検索語3」を含むドキュメントを検索したい場合は以下のように入力します。 + +:: + + (検索語1 OR 検索語2) 検索語3 + +フィールドを指定して OR 検索を行うこともできます。次の例では、title フィールドに「検索語1」を含む、または content フィールドに「検索語2」を含むドキュメントを検索します。 + +:: + + title:検索語1 OR content:検索語2 diff --git a/ja/15.10/user/search-proximity.rst b/ja/15.10/user/search-proximity.rst new file mode 100644 index 000000000..ec3ec6347 --- /dev/null +++ b/ja/15.10/user/search-proximity.rst @@ -0,0 +1,70 @@ +========== +近接検索 +========== +近接検索(プロキシミティ検索) +============================== + +近接検索は、フレーズに含まれる単語が隣り合っていなくても、互いに近い位置にあるドキュメントを検索する方法です。探している単語の間に別の語が入る可能性がある場合に有効です。 + +利用方法 +---------- + +単語を二重引用符で囲み、閉じる引用符の後ろに「~」と数字を付加します。 + +たとえば、以下のように入力すると、「Fess」と「検索」が距離 3 以内にあるドキュメントを検索できます。 + +:: + + "Fess 検索"~3 + +数字は、単語の間で許容される位置の移動回数の最大値です (詳しくは後述の「距離の数え方」を参照してください)。数字が大きいほど、単語が離れていても一致します。 + +フィールドを指定して近接検索を行うこともできます。次の例では、title フィールドを検索します。 + +:: + + title:"Fess 検索"~3 + +数字を省略して「~」のみを指定した場合 (たとえば ``"Fess 検索"~``) は、単語が隣り合っている必要がある通常のフレーズ検索として扱われます。小数を指定した場合は小数点以下が切り捨てられます (``~2.5`` は ``~2`` として扱われます)。 + +ブーストと組み合わせることもできます。次の例では、近接検索に 2 のブーストを適用します (:doc:`search-boost` を参照)。 + +:: + + "Fess 検索"~5^2 + +距離の数え方 +-------------- + +* 数字は、単語の間で許容される位置の移動回数の最大値です。対象フィールドのアナライザーが生成したトークンを単位として数え、文字数や空白で区切られた単語数ではありません。英語のテキストでは、おおむね語の間に挟まる単語数になります。解析時にストップワードとして除去された語も数えられます。 +* 単語の順序が入れ替わっていても一致しますが、逆順の場合はより大きな数字が必要です。たとえば「quick brown fox」を含むドキュメントは ``"quick fox"~1`` に一致しますが、``"fox quick"`` に一致させるには ``~3`` 以上が必要です。 + +:: + + "quick fox"~1 + "fox quick"~3 + +日本語などの CJK テキストの場合 +--------------------------------- + +日本語などの CJK テキストでは、距離を数える単位がフィールドによって異なります。 + +* title や content などの汎用フィールドでは、単語の間にある文字数に近い値になります。 +* 言語別のフィールドでは、形態素を単位として数えられ、除去された助詞なども数えられます。 + +そのため、単語は空白で区切り、数字は余裕を持って指定してください。 + +:: + + "全文 検索"~5 + "大阪 おいしい"~10 + +空白を含まない文字列 (たとえば ``"大阪おいしい"~10``) は、汎用フィールドでは連続した 1 つの文字列として照合されるため、単語間の近接検索として期待どおりに動作しないことがあります。単語は空白で区切ってください。距離を文字数に正確に換算することはできないため、まず大きめの数字を指定し、結果を確認しながら絞り込んでください。 + +関連項目 +========== + +- :doc:`search-fuzzy` +- :doc:`search-boost` +- :doc:`search-field` +- :doc:`special-char` diff --git a/ja/15.10/user/search-range.rst b/ja/15.10/user/search-range.rst new file mode 100644 index 000000000..84cbbd1c5 --- /dev/null +++ b/ja/15.10/user/search-range.rst @@ -0,0 +1,71 @@ +============ +範囲指定検索 +============ + +数値や日時など、範囲を指定できるデータをフィールドに格納している場合、そのフィールドに対して範囲指定検索が可能です。 + +利用方法 +-------- + +範囲指定検索をするためには、「フィールド名:[値 TO 値]」を検索フォームに入力します。範囲の区切りには半角大文字の ``TO`` を使用します。 + +たとえば、content_length フィールドに対して、1kバイトから10kバイトの範囲にあるドキュメントを検索する場合は、以下のように検索フォームに入力します。 + +:: + + content_length:[1000 TO 10000] + +角括弧 ``[ ]`` は範囲の端を含み（以上・以下）、波括弧 ``{ }`` は範囲の端を含みません（より大きい・より小さい）。両者は組み合わせて指定することもできます。たとえば ``content_length:{1000 TO 10000]`` は、1000より大きく10000以下のドキュメントを表します。 + +片側を ``*`` にすると、上限または下限のみを指定した開いた範囲を表します。\ ``content_length:[1000 TO *]`` は1000以上、``content_length:[* TO 10000]`` は10000以下を表します。 + +範囲指定検索は、検索対象として登録されているフィールドに対してのみ有効です。デフォルトでは content_length、last_modified、timestamp、click_count、favorite_count などのフィールドを範囲指定検索できます。 + +時間の範囲指定検索 +------------------ + +時間（日時）の範囲指定検索をするためには、「last_modified:[日時1 TO 日時2]」(日時1＜日時2) を検索フォームに入力します。なお、日時1が日時2より後の場合でもエラーにはならず、検索結果が0件になります。 + +日時は ISO 8601 形式で指定します。フォーマットは ``YYYY-MM-DDThh:mm:ss.SSSZ`` で、時刻以降は省略できます。 + +.. list-table:: + :header-rows: 1 + + * - 指定内容 + - 例 + * - 年月日のみ + - 2012-12-02 + * - 年月日および時分秒 + - 2012-12-02T10:45:23Z + * - 年月日および時分秒（ミリ秒まで） + - 2012-12-02T10:45:23.235Z + +日時の指定には、現在日時を基準にした日時演算を利用できます。利用できる記号は以下のとおりです。 + +.. list-table:: + :header-rows: 1 + + * - 記号 + - 意味 + * - ``now`` + - 現在の日時 + * - ``y`` / ``M`` / ``w`` / ``d`` / ``h`` / ``m`` / ``s`` + - 年 / 月 / 週 / 日 / 時 / 分 / 秒 + * - ``+`` / ``-`` + - 加算 / 減算 + * - ``/`` + - 丸め（``/`` の後ろの単位で丸める） + +now や日時を基準にした場合には、+、-（加算、減算）や /（丸め）といった記号を付けることができます。ただし、now ではなく特定の日時を基準にした場合は、日時と記号の間に ``||`` を入れる必要があります（例：``2016-01-01||+1M/d``）。 + +``/`` は ``/`` の後ろの単位で丸める記号です。\ ``now-1d/d`` は、本日何時に実行したとしても、本日00:00から-1日した前日の00:00を表します。 + +なお、これらの日時演算は検索エンジン（OpenSearch）側で評価され、日時型のフィールドに対してのみ有効です。 + +たとえば、last_modified フィールドに対して、現在日時（2016年2月21日20時とする）から30日前までに更新されたドキュメントを検索する場合は、以下のように検索フォームに入力します。 + +:: + + last_modified:[now-30d TO now] + +上記は、現在日時が2016年2月21日20時（UTC）の場合、おおよそ ``[2016-01-22T20:00:00Z TO 2016-02-21T20:00:00Z]`` の範囲に相当します。 diff --git a/ja/15.10/user/search-sort.rst b/ja/15.10/user/search-sort.rst new file mode 100644 index 000000000..a06abf6bf --- /dev/null +++ b/ja/15.10/user/search-sort.rst @@ -0,0 +1,76 @@ +======== +ソート検索 +======== + +検索日時などのフィールドを指定して検索結果をソートすることができます。 + +ソート対象フィールド +--------------- + +デフォルトでは以下のフィールドを指定してソートすることができます。 + +.. list-table:: + :header-rows: 1 + + * - フィールド名 + - 説明 + * - created + - クロールした日時 + * - content_length + - クロールしたドキュメントサイズ + * - last_modified + - クロールしたドキュメントの最終更新日時 + * - filename + - ファイル名 + * - score + - スコア値 + * - timestamp + - ドキュメントをインデックスした日時 + * - click_count + - ドキュメントをクリックした回数 + * - favorite_count + - ドキュメントをお気に入りした回数 + +表: ソート対象フィールド一覧 + + +独自のフィールドをソート対象として追加することもできます。追加するには ``fess_config.properties`` の ``query.additional.sort.fields`` に、ソート対象としたいフィールド名をカンマ区切りで指定します（初期値は空です）。ここで指定したフィールドは上記の標準フィールドに追加され、ソートに利用できるようになります。なお、ソート対象とするフィールドは、あらかじめインデックスに登録されている必要があります。 + +利用方法 +------ + +検索時にソート条件を選択することができます。ソート条件はオプションボタンを押下することで表示される検索オプションダイアログで選択することができます。 + +|image0| + +また、検索フィールドでソートをする場合は、「sort:フィールド名」のようにsortとフィールド名をコロン(:)で区切って検索フォームに入力して検索します。 + +以下は fess を検索語として、ドキュメントサイズを昇順にソートします。 + +:: + + fess sort:content_length + +降順にソートする場合は、フィールド名の後ろに ``.desc`` を付けます。 + +:: + + fess sort:content_length.desc + +フィールド名の後ろに指定できるのは ``.asc`` （昇順）または ``.desc`` （降順）で、省略した場合は昇順になります。 + +複数のフィールドでソートする場合は、以下のように , 区切りで指定します。先に指定したフィールドが優先され、その値が同じドキュメント同士が次のフィールドで並び替えられます。 + +:: + + fess sort:content_length.desc,last_modified + +.. note:: + 検索語の ``sort:`` に、ソート対象フィールド一覧にないフィールド名や ``asc`` ・ ``desc`` 以外のソート順を指定しても、エラーにはなりません。 + その場合、 ``sort:`` はソート条件として扱われず、検索語全体の記号（ ``:`` など）を通常の文字として扱って検索し直します。 + ソートされないうえに、多くの場合は検索結果が0件になります。 + + 検索APIの ``sort`` パラメーターに同じ値を指定した場合は、エラー（400 Bad Request）になります。 + +.. |image0| image:: ../../../resources/images/ja/15.10/user/search-sort-1.png +.. pdf :width: 300 px diff --git a/ja/15.10/user/search-wildcard.rst b/ja/15.10/user/search-wildcard.rst new file mode 100644 index 000000000..fb63ec06a --- /dev/null +++ b/ja/15.10/user/search-wildcard.rst @@ -0,0 +1,53 @@ +============== +ワイルドカード検索 +============== + +検索語内で 1文字または複数文字のワイルドカードを利用することができます。? は 1文字のワイルドカードとして指定でき、\*は複数文字のワイルドカードとして指定することができます。ワイルドカードを利用できる対象は単語になります。文に対するワイルドカード検索はできません。 + +利用方法 +------ + +1 文字のワイルドカードを利用する場合は以下のように ? を利用します。 + +:: + + te?t + +上記の場合は、text や test など、? の位置の任意の 1 文字に一致します。 + +複数文字のワイルドカードを利用する場合は以下のように \* を利用します。 + +:: + + test* + +上記の場合は、test、tests や tester など、\* の位置の 0 文字以上の任意の文字列に一致します。また、 + +:: + + te*t + +のように検索語の途中で利用することもできます。さらに、 + +:: + + *test + +のように検索語の先頭でワイルドカードを利用することもできます。 + +フィールドを指定してワイルドカード検索を行うこともできます。次の例では、title フィールドに te で始まり t で終わる単語を含むドキュメントを検索します。 + +:: + + title:te*t + +フィールドを指定しない場合は、title および content フィールドを対象に検索します。 + +利用条件 +------ + +ワイルドカード検索を利用する際は以下の点に注意してください。 + +* ワイルドカードはインデックスに登録された文字列 (トークン) を対象に一致します。検索語は再解析されないため、bi-gram などでインデックスを作成した場合、日本語は意味を持たない固定長の文字列として扱われ、日本語でのワイルドカードは期待する動作になりません。日本語でワイルドカードを利用する場合は、形態素解析を利用しているフィールドで利用してください。 +* 検索語の先頭や途中にワイルドカード (``*``・``?``) を含むパターンは、大文字と小文字を区別します。インデックスに登録される単語は通常小文字に変換されるため、パターンには小文字を使用してください。たとえば ``Te*t``、``Te?t``、``*Test`` は、小文字化されて登録された ``test`` には一致しません。一方、末尾だけが ``*`` のパターン (``Test*`` など) は前方一致として検索語が小文字化されて解析されるため、``Test*`` は ``test`` にも一致します。 +* 先頭にワイルドカードを付けた検索 (たとえば ``*test``) は、インデックス内のすべての単語を走査するため、処理に時間がかかることがあります。 diff --git a/ja/15.10/user/special-char.rst b/ja/15.10/user/special-char.rst new file mode 100644 index 000000000..a864348f9 --- /dev/null +++ b/ja/15.10/user/special-char.rst @@ -0,0 +1,91 @@ +====== +特殊文字 +====== + +以下の文字は検索クエリー構文で特別な意味を持つため、検索語では特別な文字として扱われます。これらの文字を検索文字として利用する場合にはエスケープする必要があります。 + +:: + + + - && || ! ( ) { } [ ] ^ " ~ * ? : \ / + +これらの文字は、必須・除外指定(``+`` ``-``)、ブール演算(``&&`` ``||`` ``!``)、グループ化(``( )``)、範囲検索(``[ ]`` ``{ }``)、ブースト検索(``^``)、フレーズ検索(``"``)、あいまい検索・近接検索(``~``)、ワイルドカード検索(``*`` ``?``)、フィールド指定検索(``:``)などの検索機能を呼び出すために使われます。 + +たとえば URL やファイルパスに含まれる「/」「:」、プログラム中の「+」「-」などをそのまま検索すると、意図しない検索結果になることがあります。エスケープの方法は以下を参照してください。 + + +特殊文字の一覧と意味 +-------------- + +.. list-table:: + :header-rows: 1 + + * - 特殊文字 + - 意味・役割 + - 関連ページ + * - ``+`` ``-`` + - 必須語・除外語の指定(AND 検索 / NOT 検索) + - :doc:`search-and` / :doc:`search-not` + * - ``&&`` ``||`` + - AND 検索 / OR 検索 + - :doc:`search-and` / :doc:`search-or` + * - ``!`` + - NOT 検索(除外検索) + - :doc:`search-not` + * - ``( )`` + - 検索条件のグループ化 + - :doc:`advanced-search` + * - ``[ ]`` ``{ }`` + - 範囲指定検索(``[ ]`` は境界を含む、``{ }`` は境界を含まない) + - :doc:`search-range` + * - ``^`` + - ブースト検索(重み付け) + - :doc:`search-boost` + * - ``"`` + - フレーズ検索(囲んだ範囲を1語句として扱う。エスケープの代わりにも使える) + - :doc:`advanced-search` + * - ``~`` + - あいまい検索(単語の後ろ)/ 近接検索(フレーズの後ろ) + - :doc:`search-fuzzy` / :doc:`search-proximity` + * - ``*`` ``?`` + - ワイルドカード検索 + - :doc:`search-wildcard` + * - ``:`` + - 検索フィールドの指定 + - :doc:`search-field` + * - ``\`` + - エスケープ文字 + - (本ページ) + * - ``/`` + - スラッシュ(URL などに含まれる場合はエスケープが必要) + - :doc:`search-field` + + +利用方法 +------ + +特別な文字を検索文字そのものとして扱うには、次のいずれかの方法を利用します。 + +* ``\`` を文字の直前に付けてエスケープします。直後の 1 文字が検索構文ではなく通常の文字として扱われます。 +* ``"`` で検索語を囲みます。囲まれた文字列はフレーズ検索として扱われ、内部の特別な文字は検索構文として解釈されません。ただしフレーズ検索になるため、ワイルドカード検索(``*`` ``?``)などの機能は利用できません。 + +:: + + aaa\/bbb + "aaa/bbb" + +たとえば「C++」を検索語として扱いたい場合は、以下のようにエスケープします。 + +:: + + C\+\+ + "C++" + + +関連項目 +======== + +- :doc:`search-field` +- :doc:`search-wildcard` +- :doc:`search-fuzzy` +- :doc:`search-proximity` +- :doc:`advanced-search` diff --git a/ko/15.10/admin/accesstoken-guide.rst b/ko/15.10/admin/accesstoken-guide.rst new file mode 100644 index 000000000..c975511c2 --- /dev/null +++ b/ko/15.10/admin/accesstoken-guide.rst @@ -0,0 +1,80 @@ +============ +액세스 토큰 +============ + +개요 +==== + +액세스 토큰 설정 페이지에서 액세스 토큰을 관리합니다. + +관리 방법 +====== + +표시 방법 +------ + +아래 그림의 액세스 토큰 설정 목록 페이지를 열려면 왼쪽 메뉴의 [시스템>액세스 토큰]을 클릭합니다. + +|image0| + +편집하려면 설정 이름을 클릭합니다. + +설정 생성 +-------- + +액세스 토큰 설정 페이지를 열려면 신규 생성 버튼을 클릭합니다. + +|image1| + +설정 항목 +------ + +이름 +:::: + +이 액세스 토큰을 설명하기 위한 이름을 지정합니다. + +권한 +::::::::::: + +액세스 토큰의 권한을 설정합니다. +"{user\ |group|\ role}name" 형식으로 기술합니다. +예를 들어 developer 그룹에 속한 사용자가 검색 결과를 표시하려면 권한을 "{group}developer"로 설정합니다. + +.. warning:: + + 권한을 ``{role}admin-api`` 로 지정한 액세스 토큰(내부적으로는 ``Radmin-api`` 로 저장됩니다)은 Admin API의 모든 엔드포인트를 사용할 수 있습니다. 자세한 내용은 :doc:`../api/admin/api-admin-overview` 를 참조하십시오. ``admin-accesstoken`` 역할을 가진 사용자는 이 토큰을 발급할 수 있고, ``admin-accesstoken-view`` 역할을 가진 사용자는 토큰 값을 표시할 수 있으므로, 이 두 역할은 관리자 역할과 동등하게 취급하고 신뢰할 수 있는 운영 담당자에게만 부여하십시오. + +매개변수명 +::::::::::: + +검색 쿼리로 권한을 지정하는 경우 요청 매개변수명을 지정합니다. + +.. warning:: + + 매개변수명 기능은 신뢰할 수 있는 내부 환경에서만 사용하도록 설계된 기능입니다. + 이 기능을 활성화하면 URL 매개변수를 통해 추가 권한을 지정할 수 있지만, + 외부에서 액세스 가능한 환경이나 퍼블릭 API로 공개된 환경에서는 + 악의적인 사용자가 URL 매개변수를 조작하여 본래 가지지 않은 권한으로 승격될 가능성이 있습니다. + + 다음 사항에 유의하십시오: + + * 이 기능은 Fess가 다른 애플리케이션이나 서비스에 통합되어 해당 애플리케이션이 요청을 완전히 제어하는 경우에만 사용하십시오. + * Fess가 신뢰할 수 없는 네트워크에 공개된 경우 매개변수명을 설정하지 마십시오. + * 액세스 토큰 사용 시 외부 사용자가 URL 매개변수를 조작할 수 없는지 확인하십시오. + +유효 기간 +:::::: + +액세스 토큰의 유효 기간을 지정합니다. + +설정 삭제 +-------- + +목록 페이지의 설정 이름을 클릭하고 삭제 버튼을 클릭하면 확인 화면이 표시됩니다. +삭제 버튼을 누르면 설정이 삭제됩니다. + + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/accesstoken-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/accesstoken-2.png diff --git a/ko/15.10/admin/backup-guide.rst b/ko/15.10/admin/backup-guide.rst new file mode 100644 index 000000000..0e9555787 --- /dev/null +++ b/ko/15.10/admin/backup-guide.rst @@ -0,0 +1,110 @@ +========= +백업 +========= + +개요 +==== + +백업 페이지에서는 |Fess| 의 설정 정보를 다운로드하고 업로드할 수 있습니다. + +다운로드 +--------- + +|Fess| 는 설정 정보를 인덱스로 보유하고 있습니다. +다운로드하려면 인덱스 이름을 클릭하십시오. + +|image0| + +.. note:: + + 사전(동의어, 불용어 등) 파일은 백업 대상에 포함되지 않습니다. + 사전 파일은 검색 엔진의 사전 디렉터리(``FESS_DICTIONARY_PATH``)에 저장되어 있으므로, + 필요하면 별도로 복사하십시오. + +fess_config.bulk +:::::::::::::::: + +fess_config.bulk는 |Fess| 의 설정 정보를 포함하고 있습니다. + +fess_basic_config.bulk +:::::::::::::::::::::: + +fess_basic_config.bulk는 크롤링 정보, 장애 URL, 작업 로그, 썸네일 큐, 사용자 태그 등을 제외한 |Fess| 의 설정 정보를 포함하고 있습니다. + +fess_user.bulk +:::::::::::::: + +fess_user.bulk는 사용자, 역할 및 그룹 정보를 포함합니다. + +system.properties +::::::::::::::::: + +system.properties는 전체 설정 정보를 포함합니다. + +fess.json +::::::::: + +fess.json은 fess 인덱스의 설정 정보를 포함합니다. + +doc.json +:::::::: + +doc.json은 fess 인덱스의 매핑 정보를 포함합니다. + +chat_log.ndjson +::::::::::::::: + +chat_log.ndjson은 AI 채팅 이용 로그 정보를 포함합니다. + +click_log.ndjson +:::::::::::::::: + +click_log.ndjson은 클릭 로그 정보를 포함합니다. + +favorite_log.ndjson +::::::::::::::::::: + +favorite_log.ndjson은 즐겨찾기 로그 정보를 포함합니다. + +search_log.ndjson +::::::::::::::::: + +search_log.ndjson은 검색 로그 정보를 포함합니다. + +user_info.ndjson +:::::::::::::::: + +user_info.ndjson은 검색 사용자 정보를 포함합니다. + +업로드 +--------- + +설정 정보를 업로드하여 가져올 수 있습니다. +복원 가능한 파일은 다음과 같습니다. + +- ``*.bulk`` +- ``system.properties`` +- ``fess.json`` , ``doc.json``: |Fess| 가 사용하는 인덱스 정의 파일을 교체합니다. 기존 인덱스의 설정이나 매핑은 그 자리에서 변경되지 않습니다. +- ``gsa*.xml``: Google Search Appliance 의 설정 파일입니다. 웹 크롤링 설정, 파일 크롤링 설정, 레이블로 가져옵니다. + +``*.ndjson`` (검색 로그 등의 로그)은 업로드하여 복원할 수 없습니다. + +\*.bulk 안의 문서 중 ``updatedTime`` 이 있는 문서는 저장된 문서가 없거나, ``updatedTime`` 이 없거나, +더 오래된 경우에만 기록됩니다. 더 새롭지 않은 문서는 건너뛰고 ``fess.log`` 에 INFO 수준으로 +기록하므로, 복원해도 백업 이후의 변경이 되돌려지지 않고 설치된 버전이 포함하는 예약 작업 +(``updatedTime`` 0)도 그대로 유지됩니다. ``updatedTime`` 이 없는 문서는 항상 기록됩니다. + +.. note:: + + 건너뜀은 INFO 수준으로 기록되므로, 기본 로그 레벨(``warn``)에서는 ``fess.log`` 에 출력되지 않습니다. 기록을 확인하려면 복원 전에 로그 레벨을 ``info`` 로 변경하십시오. 관리 화면의 [시스템 > 전반]에 있는 "로그 레벨"에서 변경할 수 있으며(|Fess| 를 재시작하면 원래대로 돌아갑니다), Linux에서는 ``FESS_LOG_LEVEL=info`` 로도 지정할 수 있습니다. 자세한 내용은 :doc:`../config/admin-logging` 을 참조하십시오. + +.. note:: + + |Fess| 15.10 는 웹 인증과 파일 인증의 ``password`` 를 애플리케이션 암호화 키(``fess_config.properties`` 의 + ``app.cipher.key``)로 암호화하여 저장하므로, ``fess_basic_config.bulk`` 와 ``fess_config.bulk`` 에도 암호화된 값이 + 포함됩니다. 백업을 다른 설치에 복원할 때는 동일한 ``app.cipher.key`` 를 이어받으십시오. 키가 다르면 이 인증 정보를 + 사용하는 크롤이 오류로 실패합니다. 15.10 이전에 만든 백업에는 평문으로 들어 있으며 그대로 사용할 수 있습니다. + + 또한 ``*.bulk`` 에는 이 외의 값이 암호화되지 않은 채 포함되므로, 이 파일들은 기밀 파일로 보관하십시오. + + .. |image0| image:: ../../../resources/images/en/15.10/admin/backup-1.png diff --git a/ko/15.10/admin/badword-guide.rst b/ko/15.10/admin/badword-guide.rst new file mode 100644 index 000000000..464f894e1 --- /dev/null +++ b/ko/15.10/admin/badword-guide.rst @@ -0,0 +1,85 @@ +======== +제외 단어 +======== + +개요 +==== + +여기서는 추천의 제외 단어 설정에 대해 설명합니다. +추천은 검색어에 따라 표시되지만, 해당 단어를 추천에 표시하지 않도록 설정할 수 있습니다. + + +관리 방법 +====== + +표시 방법 +------ + +아래 그림의 추천 제외 단어 설정 목록 페이지를 열려면 왼쪽 메뉴의 [추천 > 제외 단어]를 클릭합니다. + +|image0| + +편집하려면 설정 이름을 클릭합니다. + +설정 생성 +-------- + +추천 제외 단어 생성 페이지를 열려면 신규 생성 버튼을 클릭합니다. + +|image1| + +설정 항목 +------ + +추천 후보 +::::::::::: + +금지 단어를 등록합니다. +여기서 등록한 단어는 추천에 표시되지 않습니다. + +설정 삭제 +-------- + +목록 페이지의 설정 이름을 클릭하고 삭제 버튼을 클릭하면 확인 화면이 표시됩니다. +삭제 버튼을 누르면 설정이 삭제됩니다. + +다운로드 +========= + +등록한 단어를 CSV 형식으로 다운로드합니다. + +|image2| + +CSV 내용 +-------- + +1행은 헤더입니다. +2행 이후에 제외 단어가 기재됩니다. + +:: + +"BadWord" +"검색엔진" + +업로드 +========= + +CSV 형식으로 단어를 등록합니다. + +|image3| + +CSV 내용 +-------- + +1행은 헤더입니다. +2행 이후에 제외 단어를 기술합니다. + +:: + +"BadWord" +"검색엔진" + +.. |image0| image:: ../../../resources/images/en/15.10/admin/badword-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/badword-2.png +.. |image2| image:: ../../../resources/images/en/15.10/admin/badword-3.png +.. |image3| image:: ../../../resources/images/en/15.10/admin/badword-4.png diff --git a/ko/15.10/admin/boostdoc-guide.rst b/ko/15.10/admin/boostdoc-guide.rst new file mode 100644 index 000000000..7c5ebb0b5 --- /dev/null +++ b/ko/15.10/admin/boostdoc-guide.rst @@ -0,0 +1,83 @@ +=============== +문서 부스트 +=============== + +개요 +==== + +여기서는 문서 부스트에 관한 설정에 대해 설명합니다. +문서 부스트 설정을 수행하면 검색어와 관계없이 검색 결과의 상위에 문서를 배치할 수 있습니다. + +관리 방법 +====== + +표시 방법 +------ + +아래 그림의 문서 부스트 설정 목록 페이지를 열려면 왼쪽 메뉴의 [크롤러 > 문서 부스트]를 클릭합니다. + +|image0| + +편집하려면 설정 이름을 클릭합니다. + +설정 생성 +-------- + +문서 부스트 설정 페이지를 열려면 신규 생성 버튼을 클릭합니다. + +|image1| + +설정 항목 +------ + +조건 +:::: + +상위에 배치하려는 문서의 조건을 지정합니다. +예를 들어, https://www.n2sm.net/를 포함하는 URL을 상위에 표시하려는 경우 url.matches("https://www.n2sm.net/.\*")를 기술합니다. +조건은 아래의 "스크립트 종류"에서 지정한 스크립트 엔진의 구문으로 작성합니다. + +부스트 값 식 +::::::::: + +문서 가중치 값을 지정합니다. +표현식은 아래의 "스크립트 종류"에서 지정한 스크립트 엔진의 구문으로 작성합니다. + +스크립트 종류 +::::::::::::: + +조건 및 부스트 값 식을 평가하는 스크립트 엔진을 지정합니다. +신규 작성 시에는 ``javascript``\ 가 미리 입력되어 있습니다. ``groovy``\ 를 지정하려면 +``fess-script-groovy`` 플러그인이 필요합니다. 비워두면 Groovy로 평가됩니다. + +.. warning:: + + JavaScript에서는 조건 및 부스트 값 식을 끝에 세미콜론을 붙이지 않은 식으로 작성하십시오. + 문 블록으로만 해석할 수 있는 문자열은 명시적인 ``return`` 을 포함하지 않는 한 ``null`` 로 + 평가됩니다. :ref:`javascript-statement-null` + ( :doc:`../config/scripting-javascript` )을 참조하세요. + +정렬 순서 +:::::: + +문서 부스트의 정렬 순서를 설정합니다. + +규칙이 적용되는 시점 +-------------------- + +문서 부스트 규칙은 웹 크롤링 또는 파일 크롤링이 문서를 인덱스에 등록할 때 평가됩니다. 데이터 스토어 크롤링에는 적용되지 않습니다. +규칙을 추가, 변경, 삭제해도 이미 인덱스에 있는 문서의 부스트 값은 바뀌지 않습니다. + +[시스템 > 일반]의 "최종 갱신 일시 확인"이 활성화되어 있으면(기본값) 내용이 바뀌지 않은 문서는 다시 크롤링해도 인덱스에 다시 등록되지 않으므로 부스트가 다시 평가되지 않습니다. +추가하거나 변경한 규칙을 기존 문서에 반영하려면 대상 문서를 인덱스에서 삭제( :doc:`searchlist-guide` )한 후 다시 크롤링하십시오. +내용이 갱신된 문서처럼 인덱스에 다시 등록되는 문서는 그때 규칙이 평가됩니다. +"최종 갱신 일시 확인"을 비활성화하면 크롤링할 때마다 모든 문서가 다시 등록되므로 규칙도 매번 평가됩니다. + +설정 삭제 +-------- + +목록 페이지의 설정 이름을 클릭하고 삭제 버튼을 클릭하면 확인 화면이 표시됩니다. 삭제 버튼을 누르면 설정이 삭제됩니다. + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/boostdoc-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/boostdoc-2.png diff --git a/ko/15.10/admin/crawlinginfo-guide.rst b/ko/15.10/admin/crawlinginfo-guide.rst new file mode 100644 index 000000000..cf368a6c6 --- /dev/null +++ b/ko/15.10/admin/crawlinginfo-guide.rst @@ -0,0 +1,93 @@ +========= +크롤링 정보 +========= + +개요 +==== + +크롤링의 실행 결과가 기록되며, 크롤링 정보는 이 관리 화면에서 확인할 수 있습니다. + +관리 방법 +====== + +목록 +==== + +크롤링이 실행될 때마다 크롤링 정보로 기록됩니다. +목록에서는 실행한 크롤링의 세션 이름과 실행한 시간을 확인할 수 있습니다. +크롤링 정보의 세부 정보를 확인하려면 대상 크롤링 정보를 클릭합니다. + +|image0| + +세부 정보 +==== + +목록의 크롤링 정보 세션 ID를 클릭하면 대상 크롤링 정보 세부 정보가 표시됩니다. + +|image1| + +항목 목록 +------ + +세션 ID +:::::::::: + +크롤링 실행 시의 세션 ID. + +크롤러 시작 시간 +::::::::::::::: + +크롤링 전체가 시작한 시각. + +크롤링 시작 시간 (웹/파일) +:::::::::::::::::::::::::::: + +웹 및 파일 시스템 크롤링이 시작된 시각. + +크롤링 시작 시간 (데이터 저장소) +:::::::::::::::::::::::::: + +데이터 저장소 크롤링이 시작한 시각. + +크롤링 종료 시간 (웹/파일) +:::::::::::::::::::::::::::: + +웹 및 파일 시스템 크롤링이 종료한 시각. + +크롤링 실행 시간 (데이터 저장소) +:::::::::::::::::::::::::: + +데이터 저장소 크롤링의 실행 시간(밀리초). + +인덱싱 실행 시간 (데이터 저장소) +:::::::::::::::::::::::::::::: + +웹 및 파일 시스템 크롤링의 결과를 인덱싱하는 데 걸린 시간(밀리초). + +인덱스 크기 (데이터 저장소) +::::::::::::::::::::::::::: + +인덱싱된 문서의 수. + +크롤링 종료 시간 (데이터 저장소) +:::::::::::::::::::::::::: + +데이터 저장소 크롤링이 종료한 시각. + +크롤러 상태 +:::::::::::: + +크롤링이 성공했는지 여부. + +크롤러 종료 시간 +::::::::::::::: + +크롤링 전체가 종료한 시각. + +크롤러 실행 시간 +::::::::::::::: + +크롤링 전체의 실행 시간(밀리초). + +.. |image0| image:: ../../../resources/images/en/15.10/admin/crawlinginfo-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/crawlinginfo-2.png diff --git a/ko/15.10/admin/dashboard-guide.rst b/ko/15.10/admin/dashboard-guide.rst new file mode 100644 index 000000000..281db9ff4 --- /dev/null +++ b/ko/15.10/admin/dashboard-guide.rst @@ -0,0 +1,58 @@ +=========== +대시보드 +=========== + +개요 +==== + +대시보드에서는 |Fess| 가 액세스하는 OpenSearch 클러스터와 인덱스를 관리하는 웹 관리 도구를 제공합니다. + +|image0| + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: |Fess| 가 관리하는 인덱스 + :header-rows: 1 + + * - 인덱스명 + - 설명 + * - fess.yyyyMMddHHmmssSSS + - 인덱싱된 문서 + * - fess_log + - 액세스 로그 + * - fess.suggest.yyyyMMddHHmmssSSS + - 제안 키워드 + * - fess_config + - |Fess| 의 설정 + * - fess_user + - 사용자/역할/그룹 데이터 + * - configsync + - 사전 설정 + * - fess_suggest + - 제안 메타데이터 + * - fess_suggest_array + - 제안 메타데이터 + * - fess_suggest_badword + - 제안 금지어 목록 + * - fess_suggest_analyzer + - 제안 메타데이터 + * - fess_crawler + - 크롤 정보 + +``fess.`` 및 ``fess.suggest.`` 뒤에 오는 부분은 인덱스를 생성한 일시(``yyyyMMddHHmmssSSS``, 17자리)입니다. + +점(.)으로 시작하는 인덱스명은 시스템용 인덱스이므로 표시되지 않습니다. +시스템용 인덱스도 표시하려면 Special 체크박스를 활성화하십시오. + +인덱싱된 문서 수 확인 +================================ + +인덱싱된 문서의 수는 아래 그림과 같이 fess인덱스에 표시됩니다. + +|image1| + +각 인덱스의 오른쪽 상단 아이콘을 클릭하면 인덱스에 대한 작업 메뉴가 표시됩니다. +인덱싱된 문서를 삭제하는 경우 관리용 검색 화면에서 삭제합니다. "인덱스 삭제"로 삭제하지 않도록 주의하십시오. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/dashboard-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/dashboard-2.png +.. pdf :width: 400 px diff --git a/ko/15.10/admin/dataconfig-guide.rst b/ko/15.10/admin/dataconfig-guide.rst new file mode 100644 index 000000000..478f00a64 --- /dev/null +++ b/ko/15.10/admin/dataconfig-guide.rst @@ -0,0 +1,408 @@ +==================== +데이터 저장소 크롤링 +==================== + +개요 +==== + +데이터 저장소 크롤링은 웹사이트나 파일이 아닌 관계형 데이터베이스(MySQL・PostgreSQL・Oracle 등)나 CSV 파일을 비롯한 다양한 데이터 소스를 |Fess| 의 인덱스에 등록하여 전문 검색할 수 있도록 하는 기능입니다. 지원하는 데이터 소스는 데이터 저장소 커넥터 플러그인을 통해 확장할 수 있습니다. + +|Fess| 에서는 데이터베이스나 CSV 등의 데이터 소스를 크롤링 대상으로 지정할 수 있습니다. +여기서는 이를 위해 필요한 데이터 저장소 설정에 대해 설명합니다. + +.. note:: + + ``DatabaseDataStore`` 는 데이터베이스 커넥터 플러그인( ``fess-ds-db`` ), ``CsvDataStore`` / ``CsvListDataStore`` 는 CSV 커넥터 플러그인( ``fess-ds-csv`` )을 통해 제공됩니다. 사용 가능한 커넥터 목록은 :doc:`../config/datastore/ds-overview` 를 참조하십시오. + +관리 방법 +====== + +표시 방법 +------ + +아래 그림의 데이터 저장소 설정 목록 페이지를 열려면 왼쪽 메뉴의 [크롤러 > 데이터 저장소]를 클릭합니다. + +|image0| + +편집하려면 설정 이름을 클릭합니다. + +설정 생성 +-------- + +데이터 저장소 설정 페이지를 열려면 신규 생성 버튼을 클릭합니다. + +|image1| + +설정 항목 +------ + +이름 +:::: + +크롤링 설정 이름을 지정합니다. + +핸들러 이름 +::::::::: + +데이터 저장소를 처리하는 핸들러 이름입니다. + +* DatabaseDataStore: 데이터베이스를 크롤링합니다 +* CsvDataStore: CSV/TSV 파일을 대상으로 크롤링합니다 +* CsvListDataStore: 인덱싱 대상 파일 경로를 기술한 CSV 파일을 크롤링합니다 + +핸들러 이름 드롭다운에 표시되는 것은 설치된 데이터 저장소 커넥터 플러그인(``fess-ds-*``)이 제공하는 핸들러뿐입니다. +플러그인을 설치하지 않은 경우 선택할 수 있는 핸들러가 없습니다. +위 이외의 핸들러는 :doc:`../config/datastore/ds-overview` 에 나열된 각 커넥터 페이지를 참조하십시오. +또한 이전 버전의 문서에 있는 ``EsDataStore`` (``fess-ds-elasticsearch`` 플러그인)는 15.6.0 이후 공개되지 않았으며 15.10에서는 사용할 수 없습니다. + +파라미터 +::::::::: + +데이터 저장소에 관한 파라미터를 지정합니다. + +``script_type`` 파라미터로 아래 스크립트를 평가할 스크립트 엔진을 지정합니다. +신규 작성 시에는 ``script_type=javascript`` 가 미리 입력되어 있습니다. +``script_type`` 을 지정하지 않으면 스크립트는 Groovy로 평가됩니다. + +스크립트 +:::::::: + +데이터 저장소에서 가져온 값을 어떤 필드에 설정할지 등을 지정합니다. +식은 위의 ``script_type`` 파라미터로 지정한 스크립트 엔진의 구문으로 작성합니다 +（기본값은 JavaScript입니다）。 + +.. warning:: + + JavaScript에서는 각 행을 끝에 세미콜론을 붙이지 않은 식으로 작성하십시오. 문 블록으로만 + 해석할 수 있는 행(끝에 세미콜론이 있는 것, ``let`` / ``const`` 선언 등)은 명시적인 + ``return`` 을 포함하지 않는 한 ``null`` 로 평가되며, ``null`` 로 평가된 매핑은 해당 필드를 + 설정하지 않습니다. 오류도 로그도 출력되지 않으며, 필드가 조용히 비는 것 외에는 아무런 증상도 + 없습니다. :ref:`javascript-statement-null` ( :doc:`../config/scripting-javascript` )을 + 참조하세요. + +부스트 값 +:::::::: + +이 설정으로 크롤링할 때 문서의 부스트 값을 지정합니다. + +권한 +::::::::::: + +이 설정의 권한을 지정합니다. +권한 지정 방법은 예를 들어, developer 그룹에 속한 사용자에게 검색 결과를 표시하려면 {group}developer로 지정합니다. +사용자 단위 지정은 {user}사용자명, 역할 단위 지정은 {role}역할명, 그룹 단위 지정은 {group}그룹명으로 지정합니다. + +가상 호스트 +:::::::: + +가상 호스트의 호스트명을 지정합니다. +자세한 내용은 :doc:`설정 가이드의 가상 호스트 <../config/security-virtual-host>` 를 참조하십시오. + +상태 +:::: + +이 크롤링 설정을 사용할지 여부를 지정합니다. + +설명 +:::: + +설명을 입력할 수 있습니다. + +설정 삭제 +-------- + +목록 페이지의 설정 이름을 클릭하고 삭제 버튼을 클릭하면 확인 화면이 표시됩니다. +삭제 버튼을 누르면 설정이 삭제됩니다. + +예 +== + +DatabaseDataStore +----------------- + +데이터베이스 크롤링에 대해 설명합니다. + +예를 들어, 다음과 같은 테이블이 MySQL의 testdb +라는 데이터베이스에 있고, 사용자 이름 hoge, 비밀번호 fuga +로 접속할 수 있다고 가정하고 설명합니다. + +:: + + CREATE TABLE doc ( + id BIGINT NOT NULL AUTO_INCREMENT, + title VARCHAR(100) NOT NULL, + content VARCHAR(255) NOT NULL, + latitude VARCHAR(20), + longitude VARCHAR(20), + versionNo INTEGER NOT NULL, + PRIMARY KEY (id) + ); + +여기서는 다음과 같은 데이터를 입력해 둡니다. + +:: + + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('타이틀 1', '콘텐츠 1 입니다.', '37.77493', ' -122.419416', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('타이틀 2', '콘텐츠 2 입니다.', '34.701909', '135.494977', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('타이틀 3', '콘텐츠 3 입니다.', '-33.868901', '151.207091', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('타이틀 4', '콘텐츠 4 입니다.', '51.500152', '-0.113736', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('타이틀 5', '콘텐츠 5 입니다.', '35.681137', '139.766084', 1); + +매개변수 +:::::::::::: + +매개변수 설정 예는 다음과 같습니다. + +:: + + driver=com.mysql.jdbc.Driver + url=jdbc:mysql://localhost:3306/testdb?useUnicode=true&characterEncoding=UTF-8 + username=hoge + password=fuga + sql=select * from doc + +매개변수는 "키=값" 형식입니다. 키에 대한 설명은 다음과 같습니다. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - driver + - 드라이버 클래스 이름 + * - url + - URL + * - username + - DB에 접속할 때의 사용자 이름 + * - password + - DB에 접속할 때의 비밀번호 + * - sql + - 크롤링 대상을 얻기 위한 SQL 문 + +표: DB용 설정 매개변수 예 + + +스크립트 +:::::::: + +스크립트 설정 예는 다음과 같습니다. + +:: + + url="http://SERVERNAME/" + id + host="SERVERNAME" + site="SERVERNAME" + title=title + content=content + cache=content + digest=content + anchor= + content_length=content.length() + last_modified=new java.util.Date() + location=latitude + "," + longitude + latitude=latitude + longitude=longitude + +매개변수는 "키=값" 형식입니다. 키에 대한 설명은 다음과 같습니다. + +값 측은 ``script_type`` 파라미터로 지정한 스크립트 엔진의 구문으로 작성합니다. +문자열은 큰따옴표로 묶으십시오. 데이터베이스의 열 이름으로 액세스하면 그 값이 됩니다. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - url + - URL(사용 중인 환경에 맞춰 데이터에 액세스 가능한 URL을 설정하십시오) + * - host + - 호스트 이름 + * - site + - 사이트 경로 + * - title + - 제목 + * - content + - 문서의 콘텐츠(인덱스 대상 문자열) + * - cache + - 문서의 캐시(인덱스 대상이 아님) + * - digest + - 검색 결과에 표시되는 다이제스트 부분 + * - anchor + - 문서에 포함된 링크(일반적으로 지정할 필요가 없음) + * - content_length + - 문서의 길이 + * - last_modified + - 문서의 최종 수정 날짜 + +표: 스크립트 설정 내용 + + +드라이버 +:::::::: + +데이터베이스에 접속할 때는 드라이버가 필요합니다. app/WEB-INF/lib 에 jar 파일을 배치하십시오. + +CsvDataStore +------------ + +CSV 파일을 대상으로 한 크롤링에 대해 설명합니다. + +예를 들어, /home/taro/csv 디렉터리에 test.csv 파일을 다음과 같은 내용으로 생성해 둡니다. +파일 인코딩은 Shift_JIS로 설정합니다. + +:: + + 1,타이틀 1,테스트1입니다. + 2,타이틀 2,테스트2입니다. + 3,타이틀 3,테스트3입니다. + 4,타이틀 4,테스트4입니다. + 5,타이틀 5,테스트5입니다. + 6,타이틀 6,테스트6입니다. + 7,타이틀 7,테스트7입니다. + 8,타이틀 8,테스트8입니다. + 9,타이틀 9,테스트9입니다. + + +매개변수 +::::::::: + +매개변수 설정 예는 다음과 같습니다. + +:: + + directories=/home/taro/csv + fileEncoding=Shift_JIS + +매개변수는 "키=값" 형식입니다. 키에 대한 설명은 다음과 같습니다. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - directories + - CSV 파일이 포함된 디렉터리 (.csv 또는 .tsv) + * - files + - CSV 파일 (직접 지정하는 경우) + * - fileEncoding + - CSV 파일의 인코딩 + * - separatorCharacter + - 구분 문자 + + +표: CSV 파일용 설정 매개변수 예 + + +스크립트 +:::::::: + +스크립트 설정 예는 다음과 같습니다. + +:: + + url="http://SERVERNAME/" + cell1 + host="SERVERNAME" + site="SERVERNAME" + title=cell2 + content=cell3 + cache=cell3 + digest=cell3 + anchor= + content_length=cell3.length() + last_modified=new java.util.Date() + +매개변수는 "키=값" 형식입니다. +키는 데이터베이스 크롤링의 경우와 동일합니다. +CSV 파일 내의 데이터는 cell[숫자]로 보유하고 있습니다(숫자는 1부터 시작). +CSV 파일의 셀에 데이터가 존재하지 않는 경우 null이 될 수 있습니다. + +CsvListDataStore +---------------- + +대량의 파일을 크롤링할 때 사용합니다. +업데이트된 파일의 경로를 기록한 CSV 파일을 배치하고, 지정된 경로만 크롤링하여 크롤링 실행 시간을 단축할 수 있습니다. + +경로를 기술할 때의 형식은 다음과 같습니다. + +:: + + [액션]<구분 문자>[경로] + +액션에는 다음 중 하나를 지정합니다. + +* create: 파일이 생성됨 +* modify: 파일이 업데이트됨 +* delete: 파일이 삭제됨 + +예를 들어, /home/taro/csv 디렉터리에 test.csv 파일을 다음과 같은 내용으로 생성해 둡니다. +파일 인코딩은 Shift_JIS로 설정합니다. + +경로는 파일 크롤링에서 크롤링 대상 경로를 지정할 때와 동일한 표기법으로 경로를 기술합니다. +다음과 같이 "file:/[경로]" 또는 "smb://[경로]"로 지정합니다. + +:: + + modify,smb://servername/data/testfile1.txt + modify,smb://servername/data/testfile2.txt + modify,smb://servername/data/testfile3.txt + modify,smb://servername/data/testfile4.txt + modify,smb://servername/data/testfile5.txt + modify,smb://servername/data/testfile6.txt + modify,smb://servername/data/testfile7.txt + modify,smb://servername/data/testfile8.txt + modify,smb://servername/data/testfile9.txt + modify,smb://servername/data/testfile10.txt + + +매개변수 +::::::::: + +매개변수 설정 예는 다음과 같습니다. + +:: + + directories=/home/taro/csv + fileEncoding=Shift_JIS + +매개변수는 "키=값" 형식입니다. 키에 대한 설명은 다음과 같습니다. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - directories + - CSV 파일이 포함된 디렉터리 (.csv 또는 .tsv) + * - fileEncoding + - CSV 파일의 인코딩 + * - separatorCharacter + - 구분 문자 + + +표: CSV 파일용 설정 매개변수 예 + + +스크립트 +:::::::: + +스크립트 설정 예는 다음과 같습니다. + +:: + + event_type=cell1 + url=cell2 + +매개변수는 "키=값" 형식입니다. +키는 데이터베이스 크롤링의 경우와 동일합니다. + +크롤링 대상에 인증이 필요한 경우 다음도 설정해야 합니다. + +:: + + crawler.file.auth=example + crawler.file.auth.example.scheme=SAMBA + crawler.file.auth.example.username=username + crawler.file.auth.example.password=password + +관련 항목 +============ + +- :doc:`../config/datastore/index` +- :doc:`../config/datastore/ds-database` +- :doc:`../config/datastore/ds-overview` +- :doc:`../config/crawler-basic` + +.. |image0| image:: ../../../resources/images/en/15.10/admin/dataconfig-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/dataconfig-2.png diff --git a/ko/15.10/admin/dict-guide.rst b/ko/15.10/admin/dict-guide.rst new file mode 100644 index 000000000..9cf8e33dd --- /dev/null +++ b/ko/15.10/admin/dict-guide.rst @@ -0,0 +1,163 @@ +==== +사전 +==== + +개요 +==== + +여기에서는 사전에 관한 설정에 대해 설명합니다. + +사전 변경은 각 사전에 관한 사양을 이해한 후 실시하십시오. +사전 변경에 실패하면 인덱스에 액세스할 수 없게 될 수 있습니다. + +.. note:: + + ``search_engine.type`` 이 ``vanilla`` 또는 ``aws`` 인 경우(OpenSearch 에 CodeLibs 플러그인이 없는 경우) 사전 관리를 사용할 수 없습니다. 자세한 내용은 :doc:`../config/search-engine-type` 을 참조하십시오. + +목록 +==== + +아래 그림의 관리 가능한 사전 목록 페이지를 열려면 왼쪽 메뉴의 [시스템 > 사전]을 클릭합니다. + + +|image0| + + +각 사전이 적용되는 범위와 반영 시점 +==================================== + +사전마다 적용되는 필드와 반영되는 시점이 다릅니다. +사전을 편집했는데 검색 결과가 바뀌지 않는다면 먼저 이 표를 확인하십시오. + +.. list-table:: + :header-rows: 1 + :widths: 22 26 28 24 + + * - 사전 + - 파일 + - 적용되는 필드 + - 반영 시점 + * - Kuromoji + - ``ja/kuromoji.txt`` + - ``content_ja`` 등 ``_ja`` 필드에만 + - 색인 시(재크롤링 필요) + * - 동의어 + - ``synonym.txt`` + - ``content`` 및 ``title`` + - 검색 시(재크롤링 불필요) + * - 매핑(언어 공통) + - ``mapping.txt`` + - ``content`` 및 ``title`` + - 색인 시(재크롤링 필요) + * - 매핑(언어별) + - ``ja/mapping.txt`` + - ``content_ja`` 등 ``_ja`` 필드에만 + - 색인 시(재크롤링 필요) + * - Protwords + - ``en/protwords.txt`` + - ``content`` 및 ``title`` + - 색인 시와 검색 시 + * - 불용어 + - ``en/stopwords.txt`` + - ``content`` 및 ``title`` + - 색인 시와 검색 시 + * - Stemmer 덮어쓰기 + - ``en/stemmer_override.txt`` + - ``content`` 및 ``title`` + - 색인 시와 검색 시 + +.. note:: + + 분석기는 인덱스를 열 때 구성되므로 사전 파일을 갱신해도 + **인덱스를 close / open 하기 전까지는 반영되지 않습니다**. + 또한 색인 시에 적용되는 사전은 이미 색인된 문서에 소급 적용되지 않으므로 + 해당 문서를 다시 크롤링해야 합니다. + 반영하는 절차는 :ref:`dict-apply-changes` 를 참조하십시오. + +.. warning:: + + 대부분의 검색에 응답하는 ``content`` 필드에 적용되는 문자 치환 사전은 + **루트의** ``mapping.txt`` 이며 ``ja/mapping.txt`` 가 아닙니다. + 이름은 같은 매핑이지만 서로 다른 파일입니다. + +.. _dict-apply-changes: + +사전 변경 반영하기 +------------------ + +사전을 저장하기만 해서는 시간이 지나도 검색 결과가 바뀌지 않습니다. 저장한 내용은 OpenSearch 의 +configsync 플러그인이 약 1분마다 사전 파일에 기록하지만, 분석기는 인덱스를 열 때만 사전을 읽으므로 +이미 열려 있는 인덱스는 이전 사전을 계속 사용합니다. 사전을 편집한 후에는 문서 인덱스를 다시 +로드하십시오. + +1. 왼쪽 메뉴의 [시스템 정보 > 유지보수]를 엽니다. +2. "문서 인덱스 다시 로드"의 [다시 로드] 버튼을 클릭합니다. + +이 버튼은 저장된 사전을 먼저 파일에 기록한 다음 ``fess.update`` 별칭이 가리키는 인덱스를 close +하고 open 합니다. 주기적인 기록을 기다릴 필요는 없습니다. 동의어처럼 검색 시에 적용되는 사전은 +인덱스가 다시 열리는 시점에 반영됩니다. 색인 시에 적용되는 사전은 대상 문서를 추가로 다시 +크롤링하십시오. + +.. warning:: + + 인덱스를 close 하는 동안과 open 한 뒤 샤드가 다시 할당될 때까지는 그 인덱스를 검색할 수 + 없습니다. 검색이 오류가 되거나 결과가 0건이 됩니다. 인덱스가 클수록 이 시간이 길어지므로 + 접속이 적은 시간대에 실행하십시오. + +관리 화면을 사용하지 않고 스크립트 등에서 수행하려면 OpenSearch 에 같은 작업을 보냅니다:: + + curl -X POST "localhost:9200/_configsync/flush" + curl -X POST "localhost:9200/fess.update/_close" + curl -X POST "localhost:9200/fess.update/_open" + +``_configsync/flush`` 는 저장된 사전을 즉시 파일에 기록합니다. 생략하는 경우에는 사전을 저장한 뒤 +1분 이상 기다린 다음 인덱스를 close 하십시오. + +Kuromoji 사용자 사전과 검색 결과 +--------------------------------- + +``content`` 필드는 standard 토크나이저와 ``cjk_bigram`` 으로 분석되므로 +Kuromoji의 형태소 분할 결과에 영향을 받지 않습니다. 일본어 복합어를 Kuromoji +사용자 사전에 등록하고 다시 크롤링해도 ``content`` 에 대한 검색 결과는 바뀌지 +않습니다. 등록의 효과는 ``content_ja`` 에 나타나며, 이 필드는 요청 언어에 따라 +검색 조건에 추가됩니다. + +Kuromoji +======== + +일본어 형태소 분석용 사전을 관리합니다. +ja/kuromoji.txt는 일본어 형태소 분석용 사전입니다. + +동의어 +===== + +동의어 사전을 관리합니다. +synonym.txt는 언어 공통으로 사용되는 동의어 사전 파일입니다. + +매핑 +======== + +문자 치환 사전을 관리합니다. +mapping.txt는 언어 공통 또는 각 언어용 단어 치환 사전 파일입니다. + +Protwords +========= + +보호 단어 사전을 관리합니다. +protwords.txt는 각 언어용으로 배치하여 스테밍 대상 제외 등을 위한 단어 목록 파일입니다. + +불용어 +=========== + +불용어 사전을 관리합니다. +stopwords.txt는 각 언어용으로 배치하여 인덱스 생성 시 제외할 단어 목록 파일입니다. + +Stemmer 재정의 +============ + +Stemmer 재정의 사전을 관리합니다. +stemmer_override.txt는 각 언어용으로 배치하여 스테밍 처리를 재정의하기 위한 단어 치환 사전 파일입니다. + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/dict-1.png + :height: 940px diff --git a/ko/15.10/admin/docreport-guide.rst b/ko/15.10/admin/docreport-guide.rst new file mode 100644 index 000000000..7cd144c1b --- /dev/null +++ b/ko/15.10/admin/docreport-guide.rst @@ -0,0 +1,58 @@ +=========== +문서 리포트 +=========== + +개요 +==== + +문서 리포트는 크롤링한 파일 서버 등을 정리하는 데 도움이 되는 관리 화면입니다. 내용이 같은 문서와 오랫동안 갱신되지 않은 문서를 목록으로 표시하며, 각각 CSV 로 다운로드할 수 있습니다. + +화면을 열려면 왼쪽 메뉴의 [시스템 정보 > 문서 리포트] 를 클릭합니다. 열람하려면 ``admin-docreport`` 또는 ``admin-docreport-view`` 역할이 필요합니다. 이 화면은 표시와 다운로드만 하며 문서를 변경하지 않습니다. + +두 탭 모두 「URL 접두사」(예: ``smb://server/share/`` )로 대상을 좁힐 수 있습니다. + +중복 문서 +========= + +내용이 같거나 거의 같은 문서를 그룹으로 묶어 문서 수가 많은 순으로 표시합니다. +그룹화에는 색인 시 계산되는 내용 서명( ``content_minhash_bits`` , 검색 결과의 중복 묶기와 같은 것)을 사용하므로 재인덱싱은 필요하지 않습니다. +내용에 단어가 없는 문서(빈 파일 등)는 대상에서 제외됩니다. + +화면에는 최대 ``docreport.duplicate.group.size`` (기본값: 100)개 그룹을 표시하고, 각 그룹의 문서는 ``docreport.duplicate.docs.size`` (기본값: 10)건까지 표시합니다. 모든 그룹은 [CSV 다운로드] 로 가져올 수 있습니다. CSV 는 큰 인덱스에서도 모든 그룹을 읽어 들이며 ``group, groupSize, url, title, filename, contentLength, lastModified, owner, lastModifier, clickCount, docId`` 열을 출력합니다. + +.. note:: + + 중복 문서 리포트에는 내용 서명이 필요한데, CodeLibs 플러그인이 없는 OpenSearch 용 인덱스 정의(``search_engine.type`` 이 ``vanilla``, ``aws``, 사용 중단 예정인 ``cloud`` 인 경우)에서는 서명이 계산되지 않습니다. 이러한 종류에서는 「중복 문서」 탭이 표시되지 않으며 「휴면 문서」만 사용할 수 있습니다. 자세한 내용은 :doc:`../config/search-engine-type` 을 참조하십시오. + +휴면 문서 +========= + +최종 갱신 일시가 지정한 일수(「미갱신 일수」, 기본값은 ``docreport.dormant.days`` 의 365)보다 이전인 문서를 오래된 순으로 표시합니다. 최종 갱신 일시가 없는 문서는 표시하지 않습니다. +「검색 결과에서 한 번도 열리지 않음」을 활성화하면 검색 결과에서 클릭된 적이 있는 문서를 제외합니다. + +화면에는 해당 문서의 건수와 합계 크기, 문서 목록을 표시합니다. 목록의 페이지 이동에는 상한( ``indexer.max.result.window.size`` )이 있으며, 이를 넘는 문서는 [CSV 다운로드] 로 가져옵니다. + +설정 +==== + +``fess_config.properties`` 의 다음 설정으로 동작을 조정할 수 있습니다. + +.. list-table:: + :header-rows: 1 + :widths: 40 45 15 + + * - 속성 + - 설명 + - 기본값 + * - ``docreport.duplicate.group.size`` + - 화면에 표시하는 중복 그룹의 최대 수 + - ``100`` + * - ``docreport.duplicate.docs.size`` + - 화면에서 그룹 하나에 표시하는 문서의 최대 수 + - ``10`` + * - ``docreport.duplicate.export.page.size`` + - CSV 다운로드 시 한 번에 읽어 들이는 서명의 수 + - ``10000`` + * - ``docreport.dormant.days`` + - 휴면 문서로 간주하는, 최종 갱신 이후 일수의 기본값 + - ``365`` diff --git a/ko/15.10/admin/duplicatehost-guide.rst b/ko/15.10/admin/duplicatehost-guide.rst new file mode 100644 index 000000000..cba892505 --- /dev/null +++ b/ko/15.10/admin/duplicatehost-guide.rst @@ -0,0 +1,59 @@ +======== +중복 호스트 +======== + +개요 +==== + +여기서는 중복 호스트에 관한 설정에 대해 설명합니다. +중복 호스트는 크롤링 시 다른 호스트 이름을 동일한 것으로 처리하고 싶을 때 사용합니다. +예를 들어, www.example.com과 example.com을 같은 사이트로 처리하고 싶은 경우 등에 사용할 수 있습니다. + +관리 방법 +====== + +표시 방법 +------ + +아래 그림의 중복 호스트 설정 목록 페이지를 열려면 왼쪽 메뉴의 [크롤러 > 중복 호스트]를 클릭합니다. + +|image0| + +편집하려면 설정 이름을 클릭합니다. + +설정 생성 +-------- + +중복 호스트 설정 페이지를 열려면 신규 생성 버튼을 클릭합니다. + +|image1| + +설정 항목 +------ + +정규 이름 +::::: + +정규 호스트 이름을 지정합니다. 중복 호스트 이름은 정규 호스트 이름으로 대체됩니다. + +중복 이름 +::::: + +중복되는 호스트 이름을 지정합니다. 대체하려는 호스트 이름을 지정합니다. + +.. note:: + + 중복 이름과 일치하는 호스트 이름의 URL은 크롤링 설정의 "URL"(시작 URL)에 작성한 것도, 크롤링 중에 발견된 링크의 URL도 크롤링 전에 정규 이름의 URL로 대체됩니다. + 따라서 크롤링 설정의 "크롤링할 URL"과 "크롤링에서 제외할 URL"은 대체된 후의 URL에 대해 평가됩니다. 이 항목들은 정규 이름의 호스트 이름으로 작성하십시오. + + 예를 들어 정규 이름이 ``example.com`` 이고 중복 이름이 ``www.example.com`` 일 때, "크롤링할 URL"에 ``https://www.example.com/.*`` 만 작성하면 대체 후의 시작 URL(``https://example.com/``)이 대상에서 제외됩니다. + 이 경우 오류도 로그도 출력되지 않은 채 문서가 하나도 인덱스에 등록되지 않습니다. + +설정 삭제 +-------- + +목록 페이지의 설정 이름을 클릭하고 삭제 버튼을 클릭하면 확인 화면이 표시됩니다. +삭제 버튼을 누르면 설정이 삭제됩니다. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/duplicatehost-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/duplicatehost-2.png diff --git a/ko/15.10/admin/elevateword-guide.rst b/ko/15.10/admin/elevateword-guide.rst new file mode 100644 index 000000000..f88fa7ace --- /dev/null +++ b/ko/15.10/admin/elevateword-guide.rst @@ -0,0 +1,106 @@ +======== +추가 단어 +======== + +개요 +==== + +여기서는 추천 단어의 추가 후보 설정에 대해 설명합니다. 추천은 검색어에 따라 표시되지만, 해당 단어를 추가할 수 있습니다. + +관리 방법 +====== + +표시 방법 +------ + +아래 그림의 추가 단어 설정 목록 페이지를 열려면 왼쪽 메뉴의 [추천 > 추가 단어]를 클릭합니다. + +|image0| + +편집하려면 설정 이름을 클릭합니다. + +설정 생성 +-------- + +추가 단어 설정 페이지를 열려면 신규 생성 버튼을 클릭합니다. + +|image1| + +설정 항목 +------ + +단어 +:::: + +추천 후보로 표시될 단어를 지정합니다. + +읽기 +:::: + +추천 후보 단어의 읽기를 지정합니다. + +권한 +::::::::::: + +단어에 역할 정보를 설정합니다. +설정한 역할을 가진 사용자만 추천에 표시됩니다. + +라벨 +::::: + +단어에 라벨을 설정합니다. +설정한 라벨 이외를 선택한 경우 추천에 표시되지 않습니다. + +부스트 값 +:::::::: + +단어에 부스트 값을 설정합니다. + +설정 삭제 +-------- + +목록 페이지의 설정 이름을 클릭하고 삭제 버튼을 클릭하면 확인 화면이 표시됩니다. +삭제 버튼을 누르면 설정이 삭제됩니다. + + +다운로드 +========= + +등록한 단어를 CSV 형식으로 다운로드합니다. + +|image2| + +CSV 내용 +-------- + +1행은 헤더입니다. +2행 이후에 추가 단어가 기재됩니다. + +:: + +"SuggestWord","Reading","Role","Label","Boost" +"fess","ふぇす","role1","label1","100" + +업로드 +========= + +CSV 형식으로 단어를 등록합니다. + +|image3| + +CSV 내용 +-------- + +1행은 헤더입니다. +2행 이후에 추가 단어를 기술합니다. + +:: + +"SuggestWord","Reading","Role","Label","Boost" +"fess","ふぇす","role1","label1","100" + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/elevateword-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/elevateword-2.png +.. |image2| image:: ../../../resources/images/en/15.10/admin/elevateword-3.png +.. |image3| image:: ../../../resources/images/en/15.10/admin/elevateword-4.png diff --git a/ko/15.10/admin/esreq-guide.rst b/ko/15.10/admin/esreq-guide.rst new file mode 100644 index 000000000..235508080 --- /dev/null +++ b/ko/15.10/admin/esreq-guide.rst @@ -0,0 +1,52 @@ +=================== +OpenSearch에 요청 +=================== + +개요 +==== + +이 페이지에서는 JSON 파일에 작성한 요청을 OpenSearch에 전송합니다. + +|image0| + +이 화면은 왼쪽 메뉴에 없습니다. 표시하려면 관리자로 로그인한 후 ``/admin/sereq/`` 를 URL 경로로 입력하십시오. +요청을 전송하려면 ``admin`` 역할(관리자) 또는 ``admin-sereq`` 역할이 필요합니다. + +작업 방법 +========= + +요청 전송 +--------- + +OpenSearch에 전송하려는 요청을 JSON 파일로 작성하여 "요청 파일"로 해당 파일을 선택하고 "전송" 버튼을 클릭하면 OpenSearch에 요청이 전송됩니다. +응답은 파일로 다운로드됩니다. + +설정 항목 +--------- + +요청 파일 +::::::::: + +요청을 기술한 파일을 지정합니다. + +첫 번째 줄에 ``<메서드> <경로>`` 를 공백 하나로 구분하여 작성하고, 두 번째 줄부터 요청 본문(쿼리 DSL 등)을 작성합니다. +메서드로는 GET, POST, PUT, DELETE를 사용할 수 있습니다. 경로는 OpenSearch에 대한 경로이며 맨 앞의 ``/`` 는 생략할 수 있습니다. +예를 들어, 파일의 내용은 다음과 같습니다. + +:: + + POST /_search + { + "query": { + "match_all": {} + } + } + +본문의 줄바꿈은 제거되고 각 줄이 연결되어 전송됩니다. 따라서 한 줄에 JSON 하나를 나열하는 형식(``_bulk`` 등)의 요청은 전송할 수 없습니다. + +.. warning:: + + 메서드가 PUT이나 DELETE인 요청도 그대로 OpenSearch에 전송됩니다. + 파일의 내용에 따라서는 |Fess| 가 사용하는 인덱스를 변경하거나 삭제하여 데이터를 잃게 될 수 있습니다. 전송하기 전에 내용을 충분히 확인하십시오. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/esreq-1.png diff --git a/ko/15.10/admin/failureurl-guide.rst b/ko/15.10/admin/failureurl-guide.rst new file mode 100644 index 000000000..759805aad --- /dev/null +++ b/ko/15.10/admin/failureurl-guide.rst @@ -0,0 +1,66 @@ +====== +장애 URL +====== + +개요 +==== + +여기서는 장애 URL에 대해 설명합니다. +크롤링 시 가져올 수 없었던 URL이 기록되어 장애 URL로 확인할 수 있습니다. + +관리 방법 +====== + +표시 방법 +------ + +장애 URL을 확인하기 위한 목록 페이지를 열려면 왼쪽 메뉴의 [시스템 정보 > 장애 URL]을 클릭합니다. + +|image0| + +장애 URL 확인 링크를 클릭하면 세부 정보가 표시됩니다. + +장애 URL 세부 정보 +=========== + +장애 URL 세부 정보에서는 크롤링 시 발생한 예외가 기록됩니다. + +|image1| + +세부 정보 내용 +-------- + +URL +:::: + +예외가 발생한 URL. + +스레드 이름 +:::::::: + +크롤링을 실행하던 스레드 이름. +로그 파일을 확인할 때 사용할 수 있습니다. + +종류 +:::: + +예외의 종류. + +로그 +:::: + +예외의 내용. + +오류 횟수 +:::::::: + +이 예외가 발생한 횟수. + +최종 접근 일시 +:::::::::::: + +이 예외가 발생한 시각. + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/failureurl-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/failureurl-2.png diff --git a/ko/15.10/admin/fileauth-guide.rst b/ko/15.10/admin/fileauth-guide.rst new file mode 100644 index 000000000..2cde2b935 --- /dev/null +++ b/ko/15.10/admin/fileauth-guide.rst @@ -0,0 +1,85 @@ +========= +파일 인증 +========= + +개요 +==== + +여기서는 파일을 대상으로 한 크롤링에서 파일 인증이 필요한 경우의 설정 방법에 대해 설명합니다. +|Fess| 는 FTP 또는 Windows의 공유 폴더에 대한 인증을 지원합니다. + +관리 방법 +====== + +표시 방법 +------ + +아래 그림의 파일 인증 설정 목록 페이지를 열려면 왼쪽 메뉴의 [크롤러 > 파일 인증]을 클릭합니다. + +|image0| + +편집하려면 설정 이름을 클릭합니다. + +설정 생성 +-------- + +파일 인증 설정 페이지를 열려면 신규 생성 버튼을 클릭합니다. + +|image1| + +설정 항목 +------ + +호스트명 +:::::: + +인증이 필요한 사이트의 호스트 이름을 지정합니다. +크롤링할 URL에 작성한 호스트 이름과 같은 이름으로 지정하십시오. 다른 이름(예: IP 주소와 별칭)으로 작성한 URL에는 이 인증이 사용되지 않습니다. + +포트 +:::: + +인증이 필요한 사이트의 포트를 지정합니다. +비워 두면 목록에 "임의"로 표시됩니다. 비워 둔 포트의 의미는 스키마에 따라 다릅니다. + +* FTP: 모든 포트의 URL에 사용됩니다(포트가 없는 URL은 21번으로 취급됩니다). +* SAMBA: 포트를 작성하지 않은 URL(``smb://서버명/공유명/``)에만 사용됩니다. ``smb://서버명:445/공유명/`` 과 같이 포트를 명시한 URL에는 사용되지 않습니다. 포트를 명시한 URL을 크롤링하는 경우에는 같은 포트를 여기에도 지정하십시오. + +스키마 +:::::: + +인증 방법을 선택합니다. +FTP 또는 SAMBA (Windows 공유 폴더 인증)를 사용할 수 있습니다. + +사용자명 +:::::::: + +인증 사이트에 로그인하기 위한 사용자 이름을 지정합니다. + +비밀번호 +:::::::: + +인증 사이트에 로그인하기 위한 비밀번호를 지정합니다. + +파라미터 +::::::::: + +인증 사이트에 로그인하는 데 필요한 설정 값이 있는 경우 설정합니다. SAMBA의 경우 domain 값을 설정할 수 있습니다. 설정하는 경우 다음과 같이 기술합니다. + +:: + + domain=FUGA + +파일 크롤링 설정 +::::::::::::::: + +이 인증 설정을 사용할 크롤링 설정을 지정합니다. + +설정 삭제 +-------- + +목록 페이지의 설정 이름을 클릭하고 삭제 버튼을 클릭하면 확인 화면이 표시됩니다. +삭제 버튼을 누르면 설정이 삭제됩니다. + +.. |image0| image:: ../../../resources/images/en/15.10/admin/fileauth-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/fileauth-2.png diff --git a/ko/15.10/admin/fileconfig-guide.rst b/ko/15.10/admin/fileconfig-guide.rst new file mode 100644 index 000000000..241b4eb23 --- /dev/null +++ b/ko/15.10/admin/fileconfig-guide.rst @@ -0,0 +1,209 @@ +============================= +파일 크롤링(파일 서버 검색) +============================= + +개요 +==== + +파일 크롤링은 사내 파일 서버나 Windows 공유 폴더, 클라우드 스토리지에 있는 문서를 |Fess| 의 인덱스에 등록하여 전문 검색(파일 서버 검색)할 수 있도록 하는 기능입니다. Word・Excel・PowerPoint・PDF 등 다양한 파일 형식을 지원합니다. + +파일 크롤링 설정 페이지에서는 파일 시스템이나 공유 네트워크의 폴더에 있는 파일을 크롤링하는 설정을 관리할 수 있습니다. + +크롤링 대상은 "경로"에 지정하는 프로토콜에 따라 결정됩니다. + +- ``file:/`` … 로컬 또는 마운트된 파일 시스템 +- ``smb://`` … Windows 파일 서버/공유 폴더(SMB/CIFS) +- ``smb1://`` … 예전 SMB1 프로토콜을 사용하는 Windows 파일 서버/공유 폴더 +- ``ftp://`` … FTP 서버 +- ``s3://`` … Amazon S3 버킷（ ``fess-storage-s3`` 플러그인 필요） +- ``gcs://`` … Google Cloud Storage 버킷（ ``fess-storage-gcs`` 플러그인 필요） + +.. note:: + ``fess-storage-s3`` 플러그인과 ``fess-storage-gcs`` 플러그인은 배포물에 포함되어 있지 않으므로 + 관리 화면의 「시스템 > 플러그인」 페이지 또는 ``bin/fess-setup install plugin fess-storage-s3`` , + ``bin/fess-setup install plugin fess-storage-gcs`` 로 설치하십시오. + +관리 방법 +====== + +표시 방법 +------ + +아래 그림의 파일 크롤링 설정 목록 페이지를 열려면 왼쪽 메뉴의 [크롤러 > 파일 시스템]을 클릭합니다. + +|image0| + +편집하려면 설정 이름을 클릭합니다. + +설정 생성 +------- + +파일 크롤링 설정 페이지를 열려면 신규 생성 버튼을 클릭합니다. + +|image1| + +설정 항목 +------ + +이름 +:::: + +설정 이름입니다. + +경로 +:::: + +이 경로에서 크롤링을 시작할 위치를 지정합니다(예: file:/ 또는 smb://). + +크롤링 대상 경로 +::::::::::::::::: + +이 항목에 지정한 정규 표현식(Java 형식)과 일치하는 경로는 |Fess| 크롤러의 대상이 됩니다. + +크롤링 대상에서 제외할 경로 +::::::::::::::::::::: + +이 항목에 지정한 정규 표현식(Java 형식)과 일치하는 경로는 |Fess| 크롤러의 대상이 되지 않습니다. + +검색 대상 경로 +:::::::::::::: + +이 항목에 지정한 정규 표현식(Java 형식)과 일치하는 경로는 검색 대상이 됩니다. + +검색 대상에서 제외할 경로 +:::::::::::::::::: + +이 항목에 지정한 정규 표현식(Java 형식)과 일치하는 경로는 검색 대상이 되지 않습니다. + +설정 파라미터 +:::::::::::: + +크롤링 설정 정보를 지정할 수 있습니다. + +``file:`` 로 시작하는 경로(로컬 또는 마운트된 파일 시스템)를 크롤링할 때는 ``client.followSymlink`` 로 심볼릭 링크를 따라갈지 지정할 수 있습니다. 기본값은 ``true`` (따라감)입니다. ``false`` 를 지정하면 심볼릭 링크는 대상에서 제외되고, 링크가 가리키는 파일은 링크를 통해서는 크롤링되지 않습니다(건너뛴 링크는 ``fess-crawler.log`` 에 INFO 레벨로 기록됩니다). 링크를 따라가면 링크가 가리키는 파일이 링크를 포함한 설정의 권한으로 한 번 더 등록되므로, 링크 대상보다 많은 사용자가 읽을 수 있는 공유를 크롤링하는 경우에는 ``false`` 를 고려하십시오. + +:: + + client.followSymlink=false + +깊이 +:::: + +크롤링할 파일 시스템 구조의 깊이를 지정합니다. + +최대 접근 횟수 +::::::::::: + +인덱싱할 경로의 수를 지정합니다. + +스레드 수 +:::::::: + +이 설정에 사용할 스레드 수를 지정합니다. + +간격 +:::: + +스레드가 경로를 크롤링할 때마다 대기할 시간을 지정합니다. + +부스트 값 +:::::::: + +부스트 값은 이 설정으로 인덱싱된 문서의 우선순위입니다. + +권한 +::::::::::: + +이 설정의 권한을 지정합니다. +권한 지정 방법은 예를 들어, developer 그룹에 속한 사용자에게 검색 결과를 표시하려면 {group}developer로 지정합니다. +사용자 단위 지정은 {user}사용자명, 역할 단위 지정은 {role}역할명, 그룹 단위 지정은 {group}그룹명으로 지정합니다. + +가상 호스트 +:::::::: + +가상 호스트의 호스트명을 지정합니다. +자세한 내용은 :doc:`설정 가이드의 가상 호스트 <../config/security-virtual-host>` 를 참조하십시오. + +상태 +:::: + +이 설정이 활성화되어 있으면 기본 크롤러의 작업에 이 설정이 포함되어 크롤링을 수행합니다. + +설명 +:::: + +설명을 입력할 수 있습니다. + +설정 삭제 +-------- + +목록 페이지의 설정 이름을 클릭하고 삭제 버튼을 클릭하면 확인 화면이 표시됩니다. 삭제 버튼을 누르면 설정이 삭제됩니다. + +예 +== + +로컬 파일 크롤링 +-------------------- + +/home/share 아래의 파일을 크롤링하는 경우 설정은 다음과 같습니다. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - 이름 + - 값 + * - 이름 + - Share 디렉터리 + * - 경로 + - file:/home/share + +다른 매개변수는 기본 설정으로 충분합니다. + +Windows 공유 폴더 크롤링 +--------------------------- + +\\SERVER\SharedFolder 아래의 파일을 크롤링하는 경우 설정은 다음과 같습니다. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - 이름 + - 값 + * - 이름 + - 공유 폴더 + * - 경로 + - smb://SERVER/SharedFolder/ + +공유 폴더 액세스에 사용자 이름/비밀번호가 필요한 경우 왼쪽 메뉴의 [크롤러 > 파일 인증]에서 파일 인증 설정을 생성해야 합니다. +이 경우 설정은 다음과 같습니다. + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - 이름 + - 값 + * - 호스트 이름 + - SERVER + * - 스키마 + - SAMBA + * - 사용자 이름 + - (입력하십시오) + * - 비밀번호 + - (입력하십시오) + +관련 항목 +============ + +- :doc:`../config/crawler-basic` +- :doc:`fileauth-guide` +- :doc:`../config/datastore/ds-overview` +- :doc:`../config/search-basic` +- :doc:`../user/index` + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/fileconfig-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/fileconfig-2.png +.. pdf :height: 940 px diff --git a/ko/15.10/admin/general-guide.rst b/ko/15.10/admin/general-guide.rst new file mode 100644 index 000000000..b29a2bff4 --- /dev/null +++ b/ko/15.10/admin/general-guide.rst @@ -0,0 +1,679 @@ +==== +일반 +==== + +개요 +==== + +이 관리 페이지에서는 |Fess| 의 설정을 관리할 수 있습니다. +|Fess| 를 재시작하지 않고 |Fess| 의 다양한 설정을 변경할 수 있습니다. + +설정 내용 +====== + +시스템 +------ + +|image0| + +JSON 응답 +:::::::::::: + +JSON API를 활성화할지 여부를 지정합니다. + +로그인 필요 +::::::::::: + +검색 기능을 로그인 필수로 할지 여부를 지정합니다. + +로그인 링크 표시 +:::::::::::::: + +검색 화면에서 로그인 페이지로의 링크를 표시할지 여부를 설정합니다. + +중복 결과 접기 +:::::::::::::: + +중복 결과 접기를 활성화할지 여부를 설정합니다. + +``search_engine.type`` 이 ``vanilla`` 또는 ``aws`` 이면 이 항목은 표시되지 않으며 접기는 항상 비활성 상태가 됩니다( :doc:`../config/search-engine-type` 참조). + +썸네일 표시 +::::::::::: + +썸네일 표시를 활성화할지 여부를 설정합니다. + +시스템 속성 +::::::::::: + +|Fess| 의 시스템 속성을 설정합니다. +``키=값`` 형식으로 한 줄씩 지정합니다. + +기본 라벨 값 +::::::::::::::: + +기본적으로 검색 조건에 추가할 라벨 값을 기술합니다. +역할이나 그룹 단위로 지정하는 경우 "role:admin=label1"과 같이 role: 또는 group: 을 추가하여 지정합니다. + +기본 정렬 값 +::::::::::::::: + +기본적으로 검색 조건에 추가할 정렬 값을 기술합니다. +역할이나 그룹 단위로 지정하는 경우 "role:admin=content_length.desc"와 같이 role: 또는 group: 을 추가하여 지정합니다. + +가상 호스트 +:::::::: + +가상 호스트를 설정합니다. +자세한 내용은 :doc:`설정 가이드의 가상 호스트 <../config/security-virtual-host>` 를 참조하십시오. + +인기 검색어 응답 +::::::::::::::::: + +인기 키워드 API를 활성화할지 여부를 지정합니다. + +CSV 파일 인코딩 +:::::::::::::::::: + +다운로드하는 CSV 파일의 인코딩을 지정합니다. + +검색 파라미터 추가 +::::::::::::::::: + +검색 결과 표시에 매개변수를 전달하는 경우 활성화합니다. + +검색 파일 프록시 +::::::::::::::: + +검색 결과의 파일 프록시를 활성화할지 여부를 지정합니다. + +브라우저 로케일 사용 +::::::::::::::::: + +검색 시 브라우저의 로케일을 사용할지 여부를 지정합니다. + +SSO 유형 +:::::::: + +싱글 사인온(Single Sign-On) 유형을 지정합니다. + +- **None**: SSO를 사용하지 않음 +- **OpenID Connect**: OpenID Connect 사용（ ``fess-sso-oidc`` 플러그인 필요） +- **SAML**: SAML 사용（ ``fess-sso-saml`` 플러그인 필요） +- **SPNEGO**: SPNEGO 사용（ ``fess-sso-spnego`` 플러그인 필요） +- **Entra ID**: Microsoft Entra ID 사용（ ``fess-sso-entraid`` 플러그인 필요） + +크롤러 +-------- + +|image1| + +최종 갱신 일시 확인 +:::::::::::::: + +차분 크롤을 수행하는 경우 활성화합니다. + +HTTP/HTTPS URL 에서는 HEAD 의 ``Last-Modified`` 로 판단할 수 없는 경우(색인에 최종 갱신 일시가 없거나, HEAD 응답에 ``Last-Modified`` 가 없거나, HEAD 가 200/404 이외를 반환한 경우), GET 에 ``If-None-Match`` (색인에 저장한 ``ETag`` )나 ``If-Modified-Since`` 를 붙인 조건부 GET 을 수행합니다. 서버가 ``304 Not Modified`` 를 반환한 페이지는 갱신되지 않은 페이지와 마찬가지로 다시 가져오지 않습니다. 설정을 변경한 후 등 모든 것을 다시 가져오려면 이 설정을 비활성화하고 크롤링하십시오. + +동시 크롤러 설정 +:::::::::::::: + +동시에 실행할 크롤 설정 수를 지정합니다. + +사용자 에이전트 +::::::::::::: + +크롤러가 사용하는 사용자 에이전트 이름을 지정합니다. + +이전 문서 삭제 +:::::::::::::::::: + +문서의 유효 기간을 일수로 지정합니다. 크롤링으로 등록·갱신된 문서에는 크롤링을 시작한 시각으로부터 이 일수 뒤가 만료 시각으로 설정되며, 다음 크롤링에서 다시 발견된 문서는 만료 시각이 연장됩니다. 만료 시각이 지난 문서는 스케줄러의 Doc Purger 작업(기본값으로 매분 실행)이 인덱스에서 삭제합니다. + +기본값은 ``3`` 이며, 지정할 수 있는 값은 ``-1`` 부터 ``1000`` 까지입니다. ``-1`` 을 지정하면 이후 크롤링에서 등록·갱신되는 문서에는 만료 시각을 설정하지 않습니다(이미 설정된 만료 시각은 연장되지 않습니다). + +제외할 오류 종류 +::::::::::::::: + +임계값을 초과하는 장애 URL은 크롤 대상에서 제외되지만, 여기에서 지정된 예외명 등은 임계값을 초과하는 장애 URL이어도 크롤 대상이 됩니다. + +장애 수 임계값 +:::::::::::: + +크롤 대상 문서가 여기에서 지정된 횟수 이상 장애 URL에 기록된 경우 다음 크롤에서 대상에서 제외됩니다. + +로깅 +------ + +검색 로그 +:::::: + +검색 로그 기록을 활성화할지 여부를 지정합니다. + +사용자 로그 +:::::::: + +사용자 로그 기록을 활성화할지 여부를 지정합니다. + +즐겨찾기 로그 +::::::::::: + +즐겨찾기 로그 기록을 활성화할지 여부를 지정합니다. + +이전 검색 로그 삭제 +::::::::::::::: + +지정된 일수 이전의 검색 로그를 삭제합니다. 기본값은 ``-1`` 이며, ``-1`` 인 경우에는 로그를 삭제하지 않고 계속 보관합니다. +클릭 로그, 즐겨찾기 로그, 채팅 로그도 이 일수로 삭제됩니다. + +이전 작업 로그 삭제 +::::::::::::::::: + +지정된 일수 이전의 작업 로그를 삭제합니다. 기본값은 ``-1`` 이며, ``-1`` 인 경우에는 삭제하지 않습니다. + +이전 사용자 로그 삭제 +:::::::::::::::::: + +지정된 일수 이전의 사용자 로그를 삭제합니다. 기본값은 ``-1`` 이며, ``-1`` 인 경우에는 삭제하지 않습니다. + +로그를 삭제할 봇 이름 +::::::::::::::::: + +검색 로그에서 제외할 봇 이름을 지정합니다. + +로그 레벨 +:::::::: + +fess.log의 로그 레벨을 지정합니다. + +추천 +-------- + +검색어로 추천 +:::::::::::::: + +검색 로그에서 추천 후보를 생성할지 여부를 지정합니다. + +문서로 추천 +:::::::::::::::::: + +인덱싱한 문서에서 추천 후보를 생성할지 여부를 지정합니다. + +이전 추천 정보 삭제 +:::::::::::::::::::: + +지정된 일수 이전의 추천 데이터를 삭제합니다. + +LDAP +---- + +|image2| + +LDAP URL +:::::::: + +LDAP 서버의 URL을 지정합니다. + +베이스 DN +::::::: + +검색 화면에 로그인하는 베이스 식별명을 지정합니다. + +바인드 DN +::::::: + +관리자의 바인드 DN을 지정합니다. + +비밀번호 +:::::::: + +바인드 DN의 비밀번호를 지정합니다. + +사용자 DN +::::::: + +사용자의 식별명을 지정합니다. + +계정 필터 +::::::::::::::: + +사용자의 Common Name이나 uid 등을 지정합니다. + +그룹 필터 +:::::::::::::: + +가져올 그룹의 필터 조건을 지정합니다. + +memberOf 속성 +::::::::::: + +LDAP 서버에서 사용할 수 있는 memberOf 속성명을 지정합니다. +Active Directory의 경우 memberOf입니다. +기타 LDAP 서버에서는 isMemberOf인 경우도 있습니다. + +보안 인증 +:::::::: + +LDAP의 보안 인증 방식을 지정합니다 (예: simple). + +초기 컨텍스트 팩토리 +::::::::::::::::: + +LDAP의 초기 컨텍스트 팩토리 클래스를 지정합니다 (예: com.sun.jndi.ldap.LdapCtxFactory). + +OpenID Connect +-------------- + +|image3| + +클라이언트 ID +::::::::::: + +OpenID Connect 공급자의 클라이언트 ID를 지정합니다. + +클라이언트 시크릿 +:::::::::::::: + +OpenID Connect 공급자의 클라이언트 시크릿을 지정합니다. + +인증 서버 URL +::::::::::: + +OpenID Connect의 인증 서버 URL을 지정합니다. + +토큰 서버 URL +::::::::::: + +OpenID Connect의 토큰 서버 URL을 지정합니다. + +리다이렉트 URL +:::::::::::: + +OpenID Connect의 리다이렉트 URL을 지정합니다. + +스코프 +::::: + +OpenID Connect의 스코프를 지정합니다. + +베이스 URL +:::::::: + +OpenID Connect의 베이스 URL을 지정합니다. + +기본 그룹 +:::::::: + +OpenID Connect 인증 시 사용자에게 할당할 기본 그룹을 지정합니다. + +기본 역할 +:::::::: + +OpenID Connect 인증 시 사용자에게 할당할 기본 역할을 지정합니다. + +SAML +---- + +|image4| + +IdP 엔티티 ID +::::::::::::: + +IdP(Identity Provider)의 엔티티 ID를 지정합니다. + +IdP SSO URL +::::::::::: + +IdP의 싱글 사인온 서비스 URL을 지정합니다. + +IdP SLO URL +::::::::::: + +IdP의 싱글 로그아웃 서비스 URL을 지정합니다. + +IdP X.509 인증서 +:::::::::::::::: + +IdP의 SAML 어설션 서명 검증에 사용하는 X.509 공개 키 인증서를 지정합니다. +``-----BEGIN CERTIFICATE-----`` 및 ``-----END CERTIFICATE-----`` 줄을 포함하지 않고 Base64 인코딩된 내용만 지정합니다. + +SP 베이스 URL +::::::::::: + +SAML Service Provider의 베이스 URL을 지정합니다. + +SP 엔티티 ID +:::::::::::: + +SP(Service Provider)의 엔티티 ID를 지정합니다. +``SP 베이스 URL`` 을 설정한 경우 자동으로 설정됩니다. + +SP ACS URL +:::::::::: + +SAML 어설션을 수신하는 Assertion Consumer Service(ACS) URL을 지정합니다. +``SP 베이스 URL`` 을 설정한 경우 자동으로 설정됩니다. + +SP SLO URL +:::::::::: + +SP의 싱글 로그아웃 서비스 URL을 지정합니다. +``SP 베이스 URL`` 을 설정한 경우 자동으로 설정됩니다. + +SP NameID 형식 +:::::::::::::: + +SAML 어설션에서 사용하는 NameID 형식을 지정합니다. + +그룹 속성명 +::::::::: + +SAML 응답에서 그룹을 가져오기 위한 속성명을 지정합니다. + +역할 속성명 +::::::::: + +SAML 응답에서 역할을 가져오기 위한 속성명을 지정합니다. + +기본 그룹 +:::::::: + +SAML 인증 시 사용자에게 할당할 기본 그룹을 지정합니다. + +기본 역할 +:::::::: + +SAML 인증 시 사용자에게 할당할 기본 역할을 지정합니다. + +SPNEGO +------ + +|image5| + +.. note:: + SPNEGO 관련 설정은 기반 라이브러리 내에서 프로세스 전체에 공유되므로, 변경 사항을 적용하려면 |Fess| 를 재시작해야 합니다. + +Krb5 설정 +:::::::: + +Kerberos 5 설정 파일의 경로를 지정합니다. + +로그인 설정 +::::::::: + +JAAS (Java Authentication and Authorization Service) 로그인 설정 파일의 경로를 지정합니다. + +로그인 클라이언트 모듈 +:::::::::::::::::::: + +JAAS의 클라이언트 로그인 모듈명을 지정합니다. + +로그인 서버 모듈 +:::::::::::::: + +JAAS의 서버 로그인 모듈명을 지정합니다. + +사전 인증 사용자명 +:::::::::::::: + +SPNEGO 사전 인증에 사용하는 사용자명을 지정합니다. +사용자명과 비밀번호를 비워 두면 keytab 기반 서버 로그인이 사용됩니다. + +사전 인증 비밀번호 +:::::::::::::: + +SPNEGO 사전 인증에 사용하는 비밀번호를 지정합니다. + +Basic 인증 허용 +::::::::::::: + +Basic 인증 폴백을 허용할지 여부를 지정합니다. + +비보안 Basic 인증 허용 +:::::::::::::::::: + +비보안(HTTP) 연결에서의 Basic 인증을 허용할지 여부를 지정합니다. +자격 증명이 평문으로 전송되는 것을 방지하기 위해 기본적으로 비활성화되어 있습니다(HTTPS 연결에서는 Basic 인증이 계속 제공됩니다). + +NTLM 프롬프트 +::::::::::: + +NTLM 프롬프트를 활성화할지 여부를 지정합니다. + +로컬호스트 허용 +:::::::::::: + +로컬호스트에서의 접근을 허용할지 여부를 지정합니다. +활성화하면 동일 호스트에서의 요청이 Kerberos 검증 없이 서버 OS 사용자로 인증되므로, 보안상의 이유로 기본적으로 비활성화되어 있습니다. + +위임 허용 +:::::::: + +Kerberos 위임을 허용할지 여부를 지정합니다. + +로거 레벨 +:::::::: + +SPNEGO 인증에 관한 로그 출력 레벨을 0~7 사이의 숫자로 지정합니다. +비워 두거나 숫자가 아닌 값을 지정하면 로그 레벨이 자동으로 판별됩니다. + +Entra ID +-------- + +|image6| + +테넌트 (ID 또는 도메인) +::::::::::::::::::::::: + +Microsoft Entra ID의 테넌트 ID 또는 도메인을 지정합니다. + +인증 기관 +:::::::: + +Microsoft Entra ID의 인증 기관 URL을 지정합니다. + +클라이언트 ID +::::::::::: + +Microsoft Entra ID의 애플리케이션(클라이언트) ID를 지정합니다. + +클라이언트 시크릿 +:::::::::::::: + +Microsoft Entra ID의 클라이언트 시크릿을 지정합니다. + +응답 URL +:::::: + +Microsoft Entra ID의 응답(리다이렉트) URL을 지정합니다. + +상태 TTL +:::::: + +인증 상태의 유효 기간(TTL)을 지정합니다. + +권한 필드 +:::::::: + +Entra ID에서 권한 정보를 가져오는 필드를 지정합니다. + +기본 그룹 +:::::::: + +Entra ID 인증 시 사용자에게 할당할 기본 그룹을 지정합니다. + +기본 역할 +:::::::: + +Entra ID 인증 시 사용자에게 할당할 기본 역할을 지정합니다. + +도메인 서비스 사용 +:::::::::::::: + +Entra ID 도메인 서비스를 사용할지 여부를 지정합니다. + +알림 표시 +--------- + +|image7| + +.. note:: + + 알림에는 HTML을 기술할 수 있습니다. 검색 테마가 알림을 표시할 때는 허용 목록에 있는 태그와 속성만 남고, `` + + + +이미 사이트에서 jQuery를 사용하고 있는 경우 jQuery의 script 요소는 추가할 필요가 없습니다. + +제안 기능은 |Fess| 의 제안 API(``/api/v2/suggest-words``)를 사용합니다. +``url`` 은 구축한 |Fess| 서버의 URL에 맞춰 변경하십시오. + +``suggestor`` 에 지정할 수 있는 주요 옵션은 다음과 같습니다. + +.. list-table:: suggestor 의 주요 옵션 + :header-rows: 1 + :widths: 25 75 + + * - 옵션 + - 설명 + * - ``ajaxinfo.url`` + - 제안 API의 URL. |Fess| 서버의 ``/api/v2/suggest-words`` 를 지정합니다. + * - ``ajaxinfo.fn`` + - 제안 대상으로 하는 필드 이름의 배열. 초기값인 ``["_default", "content", "title"]`` 을 그대로 사용할 수 있습니다. + * - ``ajaxinfo.num`` + - 표시할 후보의 최대 개수. + * - ``ajaxinfo.lang`` + - 제안 후보를 좁히는 언어(생략 가능). + * - ``minterm`` + - 제안을 시작하는 최소 입력 문자 수. + * - ``adjustWidthVal`` + - 제안 표시 영역의 폭을 입력란의 폭에 더하여 조정하는 값(픽셀). + * - ``searchForm`` + - 후보를 선택했을 때 전송하는 검색 폼 요소. + * - ``boxCssInfo`` + - 제안 표시 영역에 적용하는 CSS. + * - ``listSelectedCssInfo`` + - 선택 중인 후보에 적용하는 CSS(생략 가능). + * - ``listDeselectedCssInfo`` + - 비선택 후보에 적용하는 CSS(생략 가능). + +"z-index"로 지정하는 값은 다른 요소와 겹치지 않는 값을 지정하십시오. + +.. note:: + 검색 폼을 |Fess| 서버와 다른 도메인의 페이지에 배치하는 경우, 제안 API에 대한 요청은 교차 출처(cross-origin) 통신이 됩니다. + |Fess| 는 초기 설정에서 모든 출처를 허용(``api.cors.allow.origin=*``)하므로 그대로 사용할 수 있습니다. + 액세스를 제한하려면 ``fess_config.properties`` 의 ``api.cors.allow.origin`` 을 변경하십시오. + +.. note:: + ``/api/v2/suggest-words`` 는 |Fess| 본체가 제공하는 API입니다. + 이전 버전에서 사용하던 ``/api/v1/suggest-words`` 는 |Fess| 본체에서는 더 이상 제공되지 않으며, 사용하려면 ``fess-webapp-v1-api`` 플러그인을 설치해야 합니다. + 새로 구축하는 경우 ``/api/v2/suggest-words`` 를 사용하십시오. diff --git a/ko/15.10/config/search-geosearch.rst b/ko/15.10/config/search-geosearch.rst new file mode 100644 index 000000000..58f663cd6 --- /dev/null +++ b/ko/15.10/config/search-geosearch.rst @@ -0,0 +1,353 @@ +================ +위치 정보 검색 +================ + +개요 +==== + +|Fess| 는 위도와 경도의 위치 정보를 가진 문서에 대해 지리적 범위를 지정한 검색을 실행할 수 있습니다. +이 기능을 사용하면 특정 지점에서 일정 거리 내에 있는 문서를 검색하거나, +Google Maps 등의 지도 서비스와 연계한 검색 시스템을 구축할 수 있습니다. + +내부적으로는 OpenSearch의 geo-distance 쿼리를 사용하여, 지정한 중심점에서 지정한 거리 이내에 +존재하는 문서를 필터링합니다. + +활용 사례 +============ + +위치 정보 검색은 다음과 같은 용도로 활용할 수 있습니다. + +- 매장 검색: 사용자의 현재 위치에서 가까운 매장 검색 +- 부동산 검색: 특정 역이나 시설에서 일정 거리 내의 매물 검색 +- 이벤트 검색: 지정한 장소 주변의 이벤트 정보 검색 +- 시설 검색: 관광 명소나 공공 시설의 인근 검색 + +설정 방법 +========= + +인덱스 생성 시 설정 +------------------- + +위치 정보 필드 정의 +~~~~~~~~~~~~~~~~~~~ + +|Fess| 에서는 위치 정보를 저장하는 필드로 ``location`` 이 표준으로 정의되어 있습니다. +이 필드는 OpenSearch의 ``geo_point`` 타입으로 설정되어 있습니다. + +위치 정보 등록 형식 +~~~~~~~~~~~~~~~~~~~ + +인덱스 생성 시 위도와 경도를 쉼표로 구분하여 ``location`` 필드에 설정합니다. + +**형식:** + +:: + + 위도,경도 + +**예:** + +:: + + 45.17614,-93.87341 + +.. note:: + 위도는 -90에서 90 범위, 경도는 -180에서 180 범위로 지정합니다. + +데이터 스토어 크롤링 설정 예 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +데이터 스토어 크롤링을 사용하는 경우 위치 정보를 가진 데이터 소스에서 ``location`` 필드에 +위도와 경도를 설정합니다. + +**예: 데이터베이스에서 가져오기** + +위도·경도를 별도 컬럼으로 저장하는 경우, SQL에서 쉼표로 구분된 문자열로 결합합니다. +데이터 스토어의 파라미터는 한 줄이 한 항목이므로, ``sql=`` 에 이어서 SQL을 한 줄로 작성합니다 +(줄을 바꿔 여러 줄로 나누면 첫 번째 줄의 ``SELECT`` 만 SQL로 취급되어 구문 오류가 발생합니다). + +:: + + sql=SELECT id, name, address, CONCAT(latitude, ',', longitude) AS location FROM stores + +데이터 스토어 설정 스크립트에서 가져온 값을 ``location`` 필드에 매핑합니다. +데이터베이스 데이터 스토어에서는 SQL의 컬럼 이름(``AS`` 로 붙인 별칭 포함)이 그대로 스크립트의 변수 이름이 됩니다. +``data.`` 와 같은 접두사는 붙지 않습니다. + +:: + + location=location + +스크립트로 위치 정보 추가 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +크롤 설정의 스크립트 기능을 사용하여 문서에 위치 정보를 동적으로 추가할 수도 있습니다(기본값은 JavaScript이며 Groovy도 선택할 수 있습니다). +필드 이름에 직접 값을 대입합니다. + +:: + + // 위도와 경도를 location 필드에 설정 + location="37.566536,126.977966" + +스크립트의 자세한 내용은 :doc:`scripting-overview` 를 참조하십시오. + +검색 시 설정 +------------ + +위치 정보 검색을 실행하려면 요청 파라미터로 검색의 중심점과 범위를 지정합니다. + +요청 파라미터 +~~~~~~~~~~~~~ + +위치 정보 검색의 파라미터 이름은 ``geo.<필드명>.point`` 및 ``geo.<필드명>.distance`` +형식입니다. ``<필드명>`` 에는 ``query.geo.fields`` 에서 설정된 필드 이름이 들어갑니다 +(기본값은 ``location`` ). + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 파라미터 이름 + - 설명 + * - ``geo.location.point`` + - 검색 중심이 되는 지점의 위도·경도(쉼표 구분. 예: ``37.566536,126.977966`` ) + * - ``geo.location.distance`` + - 중심점에서의 검색 반경(단위 포함. 예: ``10km`` ) + +.. note:: + ``point`` 와 ``distance`` 는 쌍으로 지정합니다. ``distance`` 를 지정하지 않은 ``point`` 는 무시됩니다. + 또한 ``point`` 의 값은 "위도,경도" 의 두 숫자로 구성되어야 하며, 형식이 올바르지 않은 경우 + 오류가 발생합니다. + +.. note:: + 위치 정보 검색은 검색어 ``q`` 에 대한 필터로 동작합니다. ``q`` 가 비어 있으면 검색 자체가 실행되지 않으며 + 결과는 0건이 됩니다. 위치 정보 검색 요청에는 검색어를 지정하십시오. + +.. note:: + 같은 필드에 대해 여러 개의 ``point`` 를 지정한 경우 OR 조건(어느 범위 내), 여러 필드에 대해 + 지정한 경우 AND 조건(모든 범위 내)으로 처리됩니다. + +거리 단위 +~~~~~~~~~ + +거리에는 다음 단위를 사용할 수 있습니다. + +- ``km``: 킬로미터 +- ``m``: 미터 +- ``mi``: 마일 +- ``yd``: 야드 + +.. note:: + 거리 값은 OpenSearch에 그대로 전달되므로, 위 외에도 OpenSearch가 지원하는 단위 + ( ``cm`` , ``mm`` , ``ft`` , ``in`` , ``nmi`` 등)를 사용할 수 있습니다. + +검색 결과 정렬 순서 +~~~~~~~~~~~~~~~~~~~ + +위치 정보 검색은 지정한 범위 내의 문서로 결과를 필터링하는 **필터** 로 동작합니다. +검색 스코어(관련도)에는 영향을 미치지 않으며, 중심점에서 가까운 순으로 정렬하지는 않습니다. +결과는 일반적으로 관련도 순(또는 ``sort`` 파라미터로 지정한 순서)으로 반환됩니다. + +.. note:: + |Fess| 는 거리에 의한 정렬(가까운 순 정렬)을 지원하지 않습니다. + 거리 순으로 표시하려면 응답에 포함된 위도·경도를 기반으로 클라이언트 측에서 정렬하십시오. + +검색 예 +======= + +기본 검색 +--------- + +서울역(37.566536, 126.977966)에서 반경 10km 이내의 문서를 검색하는 경우: + +:: + + http://localhost:8080/search?q=검색키워드&geo.location.point=37.566536,126.977966&geo.location.distance=10km + +현재 위치 주변 검색 +-------------------- + +사용자의 현재 위치에서 1km 이내를 검색하는 경우: + +:: + + http://localhost:8080/search?q=카페&geo.location.point=37.566536,126.977966&geo.location.distance=1km + +API 사용 +-------- + +v2 JSON 검색 API( ``/api/v2/search`` )에서도 위치 정보 검색을 사용할 수 있습니다. +``geo.location.point`` 와 ``geo.location.distance`` 를 요청 파라미터로 지정합니다. + +:: + + curl "http://localhost:8080/api/v2/search?q=호텔&geo.location.point=37.566536,126.977966&geo.location.distance=5km" + +검색 결과는 공통 엔벨로프의 ``response.data`` 배열로 반환됩니다. API의 자세한 내용은 :doc:`../api/api-search` +및 :doc:`../api/api-overview` 를 참조하십시오. + +.. note:: + ``location`` 필드는 기본적으로 API 응답에 포함되지 않습니다. 검색 결과에 위도·경도를 포함하려면 + ``fess_config.properties`` 에 다음 2개의 설정을 추가하고 |Fess| 를 재시작하십시오. + ``query.additional.response.fields`` 는 검색 엔진에서 가져올 필드를 추가하고, + ``query.additional.api.response.fields`` 는 API 응답에 출력할 필드를 허용합니다. + 둘 중 하나만으로는 ``location`` 이 응답에 포함되지 않습니다. + + :: + + query.additional.response.fields=location + query.additional.api.response.fields=location + +필드 이름 사용자 정의 +====================== + +기본 필드 이름 변경 +------------------- + +위치 정보 검색에서 사용하는 필드 이름을 변경하는 경우 +``fess_config.properties`` 에서 다음 설정을 변경합니다. + +:: + + query.geo.fields=location + +여러 필드 이름을 지정하는 경우 쉼표로 구분하여 지정합니다. + +:: + + query.geo.fields=location,geo_point,coordinates + +.. note:: + - 요청 파라미터 이름은 설정한 필드 이름과 연동됩니다. 예를 들어 + ``query.geo.fields=coordinates`` 로 설정한 경우, ``geo.coordinates.point`` 및 + ``geo.coordinates.distance`` 를 지정합니다. + - 여기서 지정하는 각 필드는 인덱스 매핑에서 ``geo_point`` 타입으로 + 정의되어 있어야 합니다. + +구현 예 +======= + +웹 애플리케이션에서의 구현 +-------------------------- + +JavaScript로 현재 위치를 가져와 검색하는 예: + +.. code-block:: javascript + + // 브라우저의 Geolocation API로 현재 위치 가져오기 + navigator.geolocation.getCurrentPosition(function(position) { + const latitude = position.coords.latitude; + const longitude = position.coords.longitude; + const distance = "5km"; + + // 검색 URL 구축(검색어 q는 생략할 수 없음) + const searchUrl = `/search?q=${encodeURIComponent('매장')}&geo.location.point=${latitude},${longitude}&geo.location.distance=${distance}`; + + // 검색 실행 + window.location.href = searchUrl; + }); + +Google Maps와의 연계 +-------------------- + +검색 결과를 Google Maps에 마커로 표시하는 예: + +.. note:: + 이 예에서는 검색 결과에서 ``location`` 필드를 참조합니다. 사전에 + ``query.additional.response.fields=location`` 과 ``query.additional.api.response.fields=location`` 을 + 설정하여 응답에 위도·경도를 포함해 두어야 합니다. + +.. code-block:: javascript + + // 지도 초기화 + const map = new google.maps.Map(document.getElementById('map'), { + center: {lat: 37.566536, lng: 126.977966}, + zoom: 13 + }); + + // Fess v2 검색 API로 위치 정보 검색 실행 + fetch('/api/v2/search?q=매장&geo.location.point=37.566536,126.977966&geo.location.distance=5km') + .then(response => response.json()) + .then(json => { + // 검색 결과(response.data 배열)를 마커로 표시 + json.response.data.forEach(doc => { + if (doc.location) { + const [lat, lng] = doc.location.split(',').map(Number); + new google.maps.Marker({ + position: {lat: lat, lng: lng}, + map: map, + title: doc.title + }); + } + }); + }); + +성능 최적화 +=========== + +인덱스 설정 확인 +---------------- + +위치 정보 필드는 설치 경로의 +``app/WEB-INF/classes/fess_indices/fess/doc.json`` 에서 ``geo_point`` 타입으로 정의되어 있습니다. + +:: + + "location": { + "type": "geo_point" + } + +``geo_point`` 타입의 필드는 BKD 트리로 인덱싱되므로, geo-distance 쿼리는 +효율적으로 실행됩니다. + +검색 범위와 응답 최적화 +------------------------ + +검색 반경을 크게 할수록 범위 내에 해당하는 문서 수가 증가하여, 결과를 가져오고 렌더링하는 데 +시간이 걸릴 수 있습니다. + +- 용도에 맞게 적절한 검색 반경을 설정하십시오. +- 지도 표시 등에서 많은 결과를 처리하는 경우, 페이지 크기( ``num`` 파라미터)를 조정하여 + 가져오는 건수를 제한하십시오. + +문제 해결 +========== + +위치 정보 검색이 작동하지 않음 +------------------------------- + +1. ``location`` 필드에 데이터가 올바르게 저장되어 있는지 확인하십시오. +2. 위도·경도의 형식이 올바른지 확인하십시오( ``위도,경도`` 의 쉼표 구분. 값이 두 개가 아닌 경우 오류가 발생합니다). +3. OpenSearch의 인덱스 매핑에서 ``location`` 이 ``geo_point`` 타입으로 정의되어 있는지 확인하십시오. +4. ``point`` 와 ``distance`` 를 모두 지정하고 있는지 확인하십시오( ``distance`` 가 없는 ``point`` 는 무시됩니다). + +검색 결과가 반환되지 않음 +-------------------------- + +1. 지정한 거리 범위 내에 문서가 존재하는지 확인하십시오. +2. 위도·경도 값이 올바른 범위 내(위도: -90~90, 경도: -180~180)인지 확인하십시오. +3. 거리 단위가 올바르게 지정되어 있는지 확인하십시오. + +API 응답에 위치 정보가 포함되지 않음 +-------------------------------------- + +``location`` 필드는 기본적으로 API 응답에 포함되지 않습니다. +검색 결과에 위도·경도를 포함하려면 ``fess_config.properties`` 에 +``query.additional.response.fields=location`` 과 ``query.additional.api.response.fields=location`` +을 모두 설정하고 |Fess| 를 재시작하십시오. + +위치 정보가 올바르게 등록되지 않음 +------------------------------------ + +1. 크롤 시 ``location`` 필드가 올바르게 설정되어 있는지 확인하십시오. +2. 데이터 소스의 위도·경도가 올바르게 가져와지고 있는지 확인하십시오. +3. 스크립트로 위치 정보를 설정하는 경우, ``위도,경도`` 의 문자열 형식인지 확인하십시오. + +참고 정보 +========= + +위치 정보 검색의 자세한 내용은 다음 리소스를 참조하십시오. + +- `OpenSearch Geo Queries `_ +- `OpenSearch Geo Point `_ +- `Geolocation API (MDN) `_ diff --git a/ko/15.10/config/search-scroll.rst b/ko/15.10/config/search-scroll.rst new file mode 100644 index 000000000..fbe4f004e --- /dev/null +++ b/ko/15.10/config/search-scroll.rst @@ -0,0 +1,455 @@ +==================== +검색 결과 일괄 취득 +==================== + +개요 +==== + +|Fess| 의 일반 검색에서는 페이징 기능으로 일정 수의 검색 결과만 표시됩니다. +모든 검색 결과를 일괄로 취득하려면 스크롤 검색(Scroll Search) 기능을 이용합니다. + +이 기능은 데이터의 일괄 내보내기나 백업, 대량 데이터 분석 등 +모든 검색 결과를 처리해야 하는 경우에 유용합니다. + +활용 사례 +========= + +스크롤 검색은 다음과 같은 용도에 적합합니다. + +- 검색 결과 전체 내보내기 +- 데이터 분석용 대량 데이터 취득 +- 배치 처리에서의 데이터 취득 +- 외부 시스템으로의 데이터 동기화 +- 리포트 생성용 데이터 수집 + +.. warning:: + 스크롤 검색은 대량의 데이터를 반환하므로 일반 검색에 비해 + 서버 리소스를 많이 소비합니다. 필요한 경우에만 활성화하십시오. + +설정 방법 +========= + +스크롤 검색 활성화 +------------------ + +기본적으로 보안과 성능 관점에서 스크롤 검색은 비활성화되어 있습니다. +활성화하려면 ``app/WEB-INF/classes/fess_config.properties`` (RPM/DEB 패키지의 경우 +``/etc/fess/fess_config.properties`` )에서 다음 설정을 변경합니다. + +:: + + api.search.scroll=true + +.. note:: + 설정 변경 후 |Fess| 를 재시작해야 합니다. + +스크롤 컨텍스트 유효 기간 +-------------------------- + +스크롤 검색의 스크롤 컨텍스트 유효 기간은 |Fess| 내부에서 ``1m`` (1분)으로 고정되어 있습니다. +이 값은 ``fess_config.properties`` 에서 변경할 수 없습니다. + +.. note:: + ``index.scroll.search.timeout`` 라는 설정이 있지만, 이는 인덱스의 업데이트·삭제를 + 수반하는 내부 처리(update by query / delete by query)에서 사용되는 것으로, + 본 기능(검색 스크롤)의 타임아웃에는 영향을 주지 않습니다. + +응답 필드 설정 +-------------- + +검색 결과 응답에 포함할 필드를 사용자 정의할 수 있습니다. +기본적으로 많은 필드가 반환되지만 추가 필드를 지정할 수도 있습니다. + +:: + + query.additional.scroll.response.fields=content + query.additional.api.response.fields=content + +여러 필드를 지정하는 경우 쉼표로 구분하여 나열합니다. + +.. note:: + ``content`` 필드는 기본 응답에 포함되지 않습니다. 전문을 취득하려면 위의 두 설정이 + 모두 필요합니다. ``query.additional.scroll.response.fields`` 는 인덱스에서 가져올 필드를 추가하고, + ``query.additional.api.response.fields`` 는 API 응답으로 출력이 허용되는 필드를 추가합니다. + 어느 한쪽만으로는 ``content`` 가 출력되지 않습니다. + +사용 방법 +========= + +기본 사용 방법 +-------------- + +스크롤 검색에 접근하려면 다음 URL로 실행합니다. + +:: + + http://localhost:8080/api/v2/documents/all?q=검색키워드 + +검색 결과는 NDJSON(Newline Delimited JSON) 형식으로 반환됩니다. +1행마다 1개의 문서가 JSON 형식으로 출력됩니다. + +**예:** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=Fess" + +요청 파라미터 +------------- + +스크롤 검색에서는 다음 파라미터를 사용할 수 있습니다. + +.. note:: + 스크롤 검색은 GET 메서드만 지원합니다. ``POST`` 등 상태를 변경하는 메서드에서는 + CSRF 토큰 검증이 먼저 수행되므로, 유효한 ``X-Fess-CSRF-Token`` 헤더가 없는 요청에는 + ``403 Forbidden`` ( ``forbidden`` )이 반환됩니다( :doc:`../api/api-overview` 참조). + 유효한 토큰을 붙인 경우에는 ``405 Method Not Allowed`` ( ``method_not_allowed`` )가 반환됩니다. + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - 파라미터 이름 + - 설명 + * - ``q`` + - 검색 쿼리(필수) + * - ``num`` + - 1회 스크롤로 취득할 건수(기본값: 10, 최대: 100) + * - ``fields.label`` + - 레이블에 의한 필터링 + +.. note:: + ``num`` 의 최대값은 ``paging.search.page.max.size`` (기본값: 100)로 제어됩니다. + 최대값을 초과하는 값을 지정하면 자동으로 최대값으로 잘립니다. + 기본값은 ``paging.search.page.size`` (기본값: 10)가 사용됩니다. + ``num`` 에 0 이하의 값을 지정하면 오류( ``INVALID_REQUEST`` )가 반환됩니다. + +검색 쿼리 지정 +-------------- + +일반 검색과 동일하게 검색 쿼리를 지정할 수 있습니다. + +**예: 키워드 검색** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=검색엔진" + +**예: 필드 지정 검색** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=title:Fess" + +**예: 전체 취득(검색 조건 없음)** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=*:*" + +취득 건수 지정 +-------------- + +1회 스크롤로 취득할 건수를 변경할 수 있습니다. + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=Fess&num=100" + +.. note:: + ``num`` 파라미터를 너무 크게 하면 메모리 사용량이 증가합니다. + 기본 최대값은 100입니다. 더 큰 값이 필요한 경우에는 + ``paging.search.page.max.size`` 설정을 변경하십시오. + +레이블에 의한 필터링 +-------------------- + +특정 레이블에 속하는 문서만 취득할 수 있습니다. + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=*:*&fields.label=public" + +접근 제어에 대하여 +------------------ + +.. note:: + 스크롤 검색에서도 일반 검색과 동일하게 역할 기반 접근 제어(RBAC)가 적용됩니다. + 요청의 역할 정보를 기반으로 접근 가능한 문서만 반환되므로 + 열람 권한이 없는 문서는 결과에 포함되지 않습니다. + +.. warning:: + 스크롤 검색 엔드포인트는 기본적으로 인증을 요구하지 않습니다(누구나 접근 가능합니다). + 단, 반환되는 문서는 위의 역할 기반 접근 제어에 의해 필터링됩니다. + 엔드포인트 자체에 대한 접근을 제한하려면 리버스 프록시 등에서 IP 주소 제한이나 + 인증을 설정하십시오. + +응답 형식 +========= + +NDJSON 형식 +----------- + +스크롤 검색의 응답은 NDJSON(Newline Delimited JSON) 형식으로 반환됩니다. +Content-Type 은 ``application/x-ndjson; charset=UTF-8`` 입니다. +각 행은 ``{"data": {...}}`` 형식으로 래핑된 1개의 문서를 나타냅니다. + +**예:** + +:: + + {"data":{"url":"http://example.com/page1","title":"Page 1","digest":"..."}} + {"data":{"url":"http://example.com/page2","title":"Page 2","digest":"..."}} + {"data":{"url":"http://example.com/page3","title":"Page 3","digest":"..."}} + +.. note:: + 각 문서는 ``data`` 키 아래에 저장됩니다. 클라이언트 측에서는 각 행을 파싱한 후 + ``data`` 키의 값을 참조하십시오. + +오류 발생 시의 동작 +------------------- + +스트림 전송 시작 후 서버 측에서 오류가 발생한 경우, 응답의 마지막 행에 +다음과 같은 오류 종단 행이 출력됩니다. + +:: + + {"error":{"code":"internal_error","message":"stream error"}} + +.. note:: + 클라이언트 측에서는 마지막 행에 ``error`` 키가 포함되어 있는지 확인함으로써 + 「스트림이 정상적으로 완료되었는지」아니면 「서버 측에서 중간에 오류가 발생했는지」를 + 판별할 수 있습니다. 또한 오류 종단 행의 기록 자체가 실패한 경우에는 종단 행이 출력되지 않고 + 스트림이 중간에 종료되므로 예기치 않은 연결 끊김도 오류로 처리하십시오. + +응답 필드 +--------- + +기본적으로 포함되는 필드: + +- ``score``: 검색 점수 +- ``_id``: 문서 ID(OpenSearch 의 문서 ID) +- ``doc_id``: 문서 ID( |Fess| 내부) +- ``boost``: 부스트 값 +- ``content_length``: 콘텐츠 길이 +- ``host``: 호스트명 +- ``site``: 사이트 +- ``last_modified``: 최종 수정 날짜 및 시간 +- ``timestamp``: 타임스탬프 +- ``mimetype``: MIME 타입 +- ``filetype``: 파일 유형 +- ``filename``: 파일명 +- ``created``: 생성 날짜 및 시간 +- ``title``: 제목 +- ``digest``: 본문 발췌 +- ``url``: 문서의 URL +- ``thumbnail``: 썸네일 +- ``click_count``: 클릭 수 +- ``favorite_count``: 즐겨찾기 수 +- ``has_cache``: 캐시 유무 +- ``content_title``: 표시용 제목 +- ``content_description``: 표시용 본문 발췌 +- ``url_link``: 표시용 링크 URL +- ``site_path``: 사이트 경로 + +.. note:: + 실제로 출력되는 필드는 API 응답으로 허용된 필드에 한정됩니다. + 값이 존재하지 않는 필드는 출력되지 않습니다. + +.. note:: + ``content`` (전문)은 기본적으로 포함되지 않습니다. + ``query.additional.scroll.response.fields`` 와 ``query.additional.api.response.fields`` 양쪽에 + 추가하면 출력됩니다 (응답 필드 설정 참조). + +데이터 처리 예 +============== + +Python으로 처리하는 예 +---------------------- + +.. code-block:: python + + import requests + import json + + # 스크롤 검색 실행 + url = "http://localhost:8080/api/v2/documents/all" + params = { + "q": "Fess", + "num": 100 + } + + response = requests.get(url, params=params, stream=True) + + # NDJSON 형식의 응답을 1행씩 처리 + for line in response.iter_lines(): + if line: + record = json.loads(line) + if "error" in record: + # 스트림 도중에 오류 발생 + print("stream error:", record["error"]) + break + doc = record["data"] + print(f"Title: {doc.get('title')}") + print(f"URL: {doc.get('url')}") + print("---") + +파일에 저장 +----------- + +검색 결과를 파일에 저장하는 예: + +.. code-block:: bash + + curl "http://localhost:8080/api/v2/documents/all?q=*:*" > all_documents.ndjson + +CSV로 변환 +---------- + +jq 명령을 사용하여 CSV로 변환하는 예: + +.. code-block:: bash + + curl "http://localhost:8080/api/v2/documents/all?q=Fess" | \ + jq -r '.data | [.url, .title, .score] | @csv' > results.csv + +데이터 분석 +----------- + +취득한 데이터를 분석하는 예: + +.. code-block:: python + + import json + import pandas as pd + + # NDJSON 파일 읽기(각 행의 data 키를 꺼냄) + documents = [] + with open('all_documents.ndjson', 'r') as f: + for line in f: + record = json.loads(line) + if "data" in record: + documents.append(record["data"]) + + # DataFrame으로 변환 + df = pd.DataFrame(documents) + + # 기본 통계 + print(f"Total documents: {len(df)}") + print(f"Average score: {df['score'].mean()}") + + # URL의 도메인 분석 + df['domain'] = df['url'].apply(lambda x: x.split('/')[2]) + print(df['domain'].value_counts()) + +성능 및 모범 사례 +================= + +효율적인 사용 방법 +------------------ + +1. **적절한 num 파라미터 설정** + + - 너무 작으면 통신 오버헤드가 증가 + - 너무 크면 메모리 사용량이 증가 + - 기본 최대값: 100 + +2. **검색 조건 최적화** + + - 필요한 문서만 취득하도록 검색 조건 지정 + - 전체 취득은 정말 필요한 경우에만 실행 + +3. **오프피크 시간 활용** + + - 대량 데이터 취득은 시스템 부하가 낮은 시간대에 실행 + +4. **배치 처리에서 활용** + + - 정기적인 데이터 동기화 등은 배치 작업으로 실행 + +메모리 사용량 최적화 +-------------------- + +대량의 데이터를 처리하는 경우 스트리밍 처리를 사용하여 메모리 사용량을 억제합니다. + +.. code-block:: python + + import requests + import json + + url = "http://localhost:8080/api/v2/documents/all" + params = {"q": "*:*", "num": 100} + + # 스트리밍으로 처리 + with requests.get(url, params=params, stream=True) as response: + for line in response.iter_lines(decode_unicode=True): + if line: + record = json.loads(line) + if "error" in record: + break + # 문서 처리 + process_document(record["data"]) + +보안 고려 사항 +============== + +접근 제한 +--------- + +스크롤 검색은 대량의 데이터를 반환하므로 적절한 접근 제한을 설정하십시오. +엔드포인트 자체는 기본적으로 인증을 요구하지 않으므로 필요에 따라 다음과 같은 +대책을 검토하십시오. + +1. **IP 주소 제한** + + 특정 IP 주소에서만 접근 허용 + +2. **API 인증** + + 리버스 프록시 등에서 API 토큰이나 Basic 인증 사용 + +3. **역할 기반 접근 제어** + + 반환되는 문서는 |Fess| 의 역할 기반 접근 제어에 의해 필터링됩니다 + +속도 제한 +--------- + +과도한 접근을 방지하기 위해 리버스 프록시에서 속도 제한을 설정하는 것을 권장합니다. + +문제 해결 +========= + +스크롤 검색을 이용할 수 없음 +---------------------------- + +1. ``api.search.scroll`` 이 ``true`` 로 설정되어 있는지 확인하십시오. +2. |Fess| 를 재시작했는지 확인하십시오. +3. 오류 로그를 확인하십시오. + +타임아웃 오류가 발생함 +---------------------- + +1. ``num`` 파라미터를 작게 하여 처리를 분산하십시오. +2. 검색 조건을 좁혀 취득하는 데이터 양을 줄이십시오. + +메모리 부족 오류 +---------------- + +1. ``num`` 파라미터를 작게 하십시오. +2. |Fess| 의 힙 메모리 크기를 늘리십시오. +3. OpenSearch의 힙 메모리 크기를 확인하십시오. + +응답이 비어 있음 +---------------- + +1. 검색 쿼리가 올바른지 확인하십시오. +2. 지정한 레이블이나 필터 조건이 올바른지 확인하십시오. +3. 역할 기반 접근 제어로 인해 열람 권한이 없는 문서는 결과에 포함되지 않습니다. 요청의 역할 설정을 확인하십시오. + +참고 정보 +========= + +- :doc:`search-basic` - 검색 기능 자세히 보기 +- :doc:`search-advanced` - 검색 관련 설정 +- `OpenSearch Scroll API `_ diff --git a/ko/15.10/config/search-semantic.rst b/ko/15.10/config/search-semantic.rst new file mode 100644 index 000000000..2864c220e --- /dev/null +++ b/ko/15.10/config/search-semantic.rst @@ -0,0 +1,874 @@ +=================================================== +시맨틱 검색(콘텐츠 청킹 + 벡터 검색) +=================================================== + +개요 +==== + +|Fess| 15.10\ 에서는 문서 본문을 청크(조각)로 분할하고 각 청크의 임베딩 벡터를 생성·저장하는 +**콘텐츠 청킹 기능**\ 이 코어에 통합되었습니다. 생성된 벡터는 다음 두 가지 용도로 사용됩니다. + +- **시맨틱 검색**: 키워드(BM25) 검색과 벡터 검색을 Rank Fusion으로 통합한 하이브리드 검색입니다. + 키워드가 정확히 일치하지 않아도 질의와 의미적으로 가까운 문서가 매칭될 수 있습니다. +- **AI 검색 모드(RAG)**: 답변을 생성할 때 질문과 의미적으로 가장 가까운 청크만 LLM의 컨텍스트로 + 선택하여 답변 품질과 토큰 효율을 향상시킵니다. + +이 기능은 모두 기본적으로 비활성화되어 있습니다. 활성화하지 않는 한 |Fess|\ 는 이전과 완전히 +동일하게 키워드 검색만으로 동작합니다. 15.7 이전 버전에서 |Fess|\ 를 업그레이드하는 경우나 +``fess-webapp-semantic-search`` 플러그인을 사용하고 있었던 경우에는 :ref:`semantic-search-migration` +을 참조하세요. + +처리 흐름 +---------- + +1. 크롤러는 평소처럼 문서를 인덱싱합니다(이 시점에는 청크가 존재하지 않습니다). +2. 스케줄러 작업 **Content Chunk Vector Indexer**\ 가 미처리 문서를 찾아 본문(``content`` 필드)을 + 청크로 분할하고 임베딩 벡터를 생성하여 ``content_chunk_vector`` 필드에 저장합니다. 이때 + ``content`` 필드 자체도 청크의 배열로 재작성됩니다(``content_length`` 는 원래 값 그대로 + 유지됩니다). +3. 처리 결과는 ``content_chunk_status`` 필드에 기록됩니다(아래에서 설명). +4. ``content_chunker.search.enabled=true`` 인 경우, 검색 시점에 시맨틱 서처가 Rank Fusion에 + 참여합니다. + +전제 조건 +========= + +- **k-NN 플러그인이 포함된 OpenSearch**: |Fess| 15.10\ 에서는 콘텐츠 청킹 기능의 활성화 여부와 + 관계없이 검색 인덱스(``fess.search``)의 매핑에 ``content_chunk_vector`` 필드(``nested`` + 타입이며, 그 ``vector`` 서브필드가 ANN용 ``knn_vector`` 타입)가 항상 포함되고, 인덱스 설정에도 + ``index.knn: true`` 가 항상 포함됩니다. 이 때문에 OpenSearch에 k-NN 플러그인이 설치되어 있지 + 않으면 인덱스 신규 생성 자체가 실패하며, |Fess|\ 는 시작할 수 없습니다. + + .. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - 구성 + - k-NN 플러그인 지원 여부 + * - Docker(``ghcr.io/codelibs/fess-opensearch``), 별도로 설치한 외부 OpenSearch에 항상 + 연결하는 RPM/DEB 패키지, 또는 그 밖의 외부 OpenSearch(표준 배포판) + - ``faiss`` 를 포함하여 완전히 지원됩니다. + * - 외부 OpenSearch의 **minimal 배포판** + - **지원되지 않습니다.** k-NN 플러그인이 포함되어 있지 않으므로 인덱스 신규 생성이 + 실패합니다. + + ``content_chunker.search.knn.engine`` 은 위의 어떤 구성에서도 ``nmslib`` 를 값으로 허용하지 + 않습니다. ``content_chunk_vector`` 는 ``nested`` 필드이며, k-NN 플러그인이 nested 필드를 + 지원하는 엔진은 ``lucene`` / ``faiss`` 뿐이기 때문입니다(``nmslib`` 는 OpenSearch 3.0 이후 + 지원 중단·제한되기도 했습니다). 설정하면 경고와 함께 ``lucene`` 으로 대체됩니다. 다른 ANN + 설정값은 아래 「설정 레퍼런스」를 참조하세요. + +- **외부 클러스터의 OpenSearch 버전**: 동봉된 ``fess.search`` 인덱스 설정은 + ``fess_indices/fess.json``\ (및 ``vanilla``, ``aws``, 사용 중단 예정인 ``cloud`` 가 사용하는 ``fess_indices/_vanilla/fess.json``)에서 ``index.knn`` 과 + ``knn.derived_source.enabled`` 를 항상 전송합니다. 후자는 k-NN 플러그인의 비교적 새로운 + 설정이며, 이를 인식하지 못하는 오래된 OpenSearch에서는 k-NN 플러그인 유무와 관계없이 인덱스 + 생성에 실패합니다. |Fess| 15.10\ 이 지원하는 OpenSearch 버전은 + :doc:`../install/prerequisites` 를 참조하세요. + +- **임베딩 프로바이더**: 다음 중 하나를 사용합니다. + +.. list-table:: + :header-rows: 1 + :widths: 20 25 55 + + * - 설정값 + - 제공 주체 + - 설명 + * - ``opensearch`` + - |Fess| 코어(내장) + - OpenSearch ML Commons에 배포된 임베딩 모델을 사용합니다. 추가 플러그인이 필요하지 않습니다. + 기본 설정값입니다. + * - ``ollama`` + - ``fess-llm-ollama`` 플러그인 + - Ollama 임베딩 모델(예: ``nomic-embed-text``)을 사용합니다. + * - ``openai`` + - ``fess-llm-openai`` 플러그인 + - OpenAI 임베딩 API를 사용합니다. + * - ``gemini`` + - ``fess-llm-gemini`` 플러그인 + - Google Gemini 임베딩 API를 사용합니다. + * - ``bedrock`` + - ``fess-llm-bedrock`` 플러그인 + - Amazon Bedrock을 통해 Amazon Titan Text Embeddings V2 또는 Cohere Embed를 사용합니다. + * - ``none`` + - |Fess| 코어(내장) + - 문서를 청크로 분할만 하고 벡터는 생성하지 않습니다(chunk-only 모드). + +설정 레퍼런스 +=============== + +모든 ``content_chunker.*`` 설정은 **시스템 프로퍼티**\ (``system.properties``) 하나의 채널로 +통합되어 있습니다. ``app/WEB-INF/conf/system.properties``\ (RPM/DEB 패키지는 +``/etc/fess/system.properties``, Docker 버전은 ``/opt/fess/system.properties``)에 설정하거나, +시작 옵션 ``-Dfess.system.<키>`` 로 초기값을 지정할 수 있습니다. 값은 실행 중에 다시 로드되므로 +대부분의 설정은 변경 직후 바로 반영됩니다. 유일한 예외는 ``content_chunker.search.enabled`` 를 +활성화(``false`` → ``true``)하는 경우입니다. 시맨틱 서처는 시작 시에만 등록되므로, **이 변경을 +반영하려면 재시작이 필요합니다**. + +.. note:: + + ``content_chunker.*`` 설정은 ``system.properties`` 채널에서만 읽힙니다. + ``fess_config.properties`` 나 ``-Dfess.config.<키>`` 에 기술해도 무시되므로 반드시 + ``system.properties`` 에 설정하세요. 또한 관리 화면의 「시스템 정보」→「설정 정보」는 현재 값을 + **확인만 할 수 있는** 화면이며, 이 화면에서 ``content_chunker.*`` 를 설정할 수는 없습니다. + +system.properties 설정 +------------------------ + +.. list-table:: + :header-rows: 1 + :widths: 40 15 45 + + * - 프로퍼티 + - 기본값 + - 설명 + * - ``content_chunker.enabled`` + - ``false`` + - 콘텐츠 청킹 기능 전체의 마스터 스위치 + * - ``content_chunker.chunker.name`` + - ``length`` + - 청크 분할 방식 + * - ``content_chunker.length.chunk_size`` + - ``800`` + - 청크당 목표 문자 수. 경계 인식 분할이 활성화된 경우(기본값) 이 값은 상한이 아니라 + 목표치입니다. 청크는 ``boundary.lookback_percent`` 만큼 짧아질 수 있고 + ``max(lookahead, 32)`` 문자만큼 길어질 수 있습니다(기본값에서 640~840자). 임베딩 모델의 + 토큰 상한에 대해 이 여유를 확보해 두세요 + * - ``content_chunker.length.overlap`` + - ``0`` + - 청크 간에 중복시킬 문자 수. 재시작 지점도 경계에 맞춰지며, 이 보정은 지점을 앞으로만 + 옮기므로 실제 중복은 이 값 이상, 이 값의 2배 이하가 됩니다 + * - ``content_chunker.length.boundary.enabled`` + - ``true`` + - ``chunk_size`` 문자에서 정확히 자르는 대신 각 절단 지점을 적절한 텍스트 경계로 + 옮깁니다. 후보는 계층으로 나뉘며 존재하는 가장 높은 계층에서 가장 가까운 후보가 + 선택됩니다. 줄바꿈·문장 끝이 최우선이고, 다음이 절 구분자·공백, 마지막이 문자 체계 + 변화입니다. ``false`` 로 설정하면 기존의 고정 길이 동작으로 돌아갑니다 + * - ``content_chunker.length.boundary.lookback_percent`` + - ``20`` + - 이상적인 절단 지점보다 앞쪽에서 경계를 탐색하는 범위(``chunk_size`` 에 대한 백분율, + 0~50) + * - ``content_chunker.length.boundary.lookahead_percent`` + - ``5`` + - 이상적인 절단 지점보다 뒤쪽에서 문장 끝이나 줄바꿈을 탐색하는 범위(``chunk_size`` + 에 대한 백분율, 0~25). 앞쪽에서 아무것도 찾지 못한 경우에만 사용됩니다 + * - ``content_chunker.max_chunks_per_document`` + - ``1000`` + - 문서당 최대 청크 수. 이를 초과하는 문서는 ``skipped`` 로 표시되며 임베딩도 생성되지 + 않습니다. 경계 인식 분할은 청크를 짧게 만들기 때문에 고정 길이 분할보다 약 3~25% 더 많은 + 청크가 생성됩니다. 매우 큰 문서를 다루는 경우에는 이 값을 늘리세요 + * - ``content_chunker.embedding.name`` + - ``opensearch`` + - 임베딩 프로바이더(``opensearch`` / ``ollama`` / ``openai`` / ``gemini`` / ``bedrock`` / ``none``) + * - ``content_chunker.embedding.dimension`` + - ``768`` + - 임베딩 벡터의 차원 수. 매핑 생성 시 이 값이 사용되므로 사용하는 임베딩 모델의 차원 수와 + **반드시** 일치해야 합니다. 이 값에는 읽기 경로가 두 가지 있으며 동작이 다릅니다. 인덱스 + 매핑 생성 시에는 미설정이면 **경고 없이** ``768`` 이 사용되고, 빈 값·숫자가 아닌 값·0 + 이하·``16000``\ (k-NN 플러그인 자체의 상한) 초과이면 경고와 함께 ``768`` 이 사용됩니다. + 반면 임베딩 처리 실행 시에는 폴백이 + 없어, 미설정·숫자가 아닌 값·0 이하는 모두 오류가 됩니다. ``16000`` 을 초과하는 값은 실행 + 시에 거부되지 않으므로, 매핑만 ``768`` 로 생성되어 차원 불일치가 발생합니다. 매핑의 차원 + 수는 인덱스를 만든 뒤에는 변경할 수 없습니다. 미설정인 채로 만든 인덱스의 복구 방법은 + *주의 사항* 의 *차원 수를 설정하지 않고 인덱스를 만든 경우* 를 참조하세요 + * - ``content_chunker.job.concurrency`` + - ``2`` + - 인덱서 작업의 병렬 워커 수 + * - ``content_chunker.job.bulk_size`` + - ``20`` + - 한 번의 배치로 가져와서 쓰는 문서 수 + * - ``content_chunker.job.max_documents_per_run`` + - ``-1``\ (무제한) + - 작업 1회 실행당 처리하는 최대 문서 수. ``0`` 이하의 값은 모두 무제한으로 취급됩니다 + * - ``content_chunker.job.retry_failed`` + - ``false`` + - ``true`` 로 설정하면 이전 실행에서 ``content_chunk_status=fail`` 로 끝난 문서도 다음 실행의 + 처리 대상에 포함됩니다. 자동 재시도나 시도 횟수 기록은 없으며, 근본 원인을 수정한 뒤 + 일시적으로 활성화하여 재시도하는 방식을 의도한 것입니다 + * - ``content_chunker.chat.top_k`` + - ``3`` + - AI 검색 모드가 답변을 생성할 때 선택하는 청크 수 + * - ``content_chunker.search.enabled`` + - ``false`` + - 시맨틱 검색을 위한 Rank Fusion 통합(**활성화에는 재시작이 필요**) + * - ``content_chunker.search.min_score`` + - (미설정) + - 결과에 포함되기 위해 필요한 최소 코사인 유사도(0-1). 미설정 시 컷오프 없음. ``ann`` + 모드에서 ``search.knn.space_type`` 이 ``cosinesimil`` 이외인 경우에는 코사인 기준의 + 컷오프를 정의할 수 없으므로, 경고와 함께 스킵됩니다 + * - ``content_chunker.search.knn.method`` + - ``hnsw`` + - ANN 인덱스 방식. 현재 허용되는 값은 ``hnsw`` 뿐이며, 그 외의 값은 경고와 함께 ``hnsw`` 로 + 대체됩니다(매핑에 반영됨. 변경하려면 인덱스 재작성이 필요) + * - ``content_chunker.search.knn.engine`` + - ``lucene`` + - ANN 엔진. 허용되는 값은 ``lucene`` 또는 ``faiss`` 뿐입니다(위의 전제 조건 참조). 그 외의 + 값은 경고와 함께 ``lucene`` 으로 대체됩니다(매핑에 반영됨. 변경하려면 인덱스 재작성이 + 필요) + * - ``content_chunker.search.knn.space_type`` + - ``cosinesimil`` + - 거리 공간. 허용되는 값은 ``cosinesimil``, ``innerproduct``, ``l2`` 뿐이며, 그 외의 값은 + 경고와 함께 ``cosinesimil`` 로 대체됩니다(매핑에 반영됨. 변경하려면 인덱스 재작성이 필요) + * - ``content_chunker.search.knn.k`` + - ``100`` + - ANN 쿼리가 샤드별로 가져오는 이웃 수. |Fess| 측에서 융합하는 경우 실효값은 + ``rank.fusion.window_size`` 를 검색기 수로 나눈 값(기본값에서는 200 ÷ 2 = 100) 아래로 + 내려가지 않으므로, 그보다 작은 값은 효과가 없습니다. 검색 엔진 측에서 융합하는 경우에는 + 이 값이 그대로 사용됩니다 + * - ``content_chunker.search.knn.param.ef_search`` + - (미설정) + - ANN 쿼리의 ``ef_search`` 파라미터 + +.. note:: + + ``content_chunker.length.boundary.enabled=true``\ (기본값)인 경우, + ``content_chunker.length.chunk_size`` 는 상한이 아니라 목표값이 됩니다. 각 절단 위치는 탐색 + 범위 안에 존재하는 가장 높은 계층의 후보 중 가장 가까운 것으로 이동합니다. 줄바꿈·문장 끝은 + 아무리 멀리 앞쪽에 있어도 절 구분자·공백보다 우선하며, 이들은 다시 문자 체계 변화보다 + 우선합니다. 이동하는 것은 절단 위치뿐이며 문자는 손실되지 않으므로, 문서의 청크를 이어 붙이면 + 원본 내용과 정확히 일치합니다. 전방 탐색으로 인해 ``chunk_size`` 를 최대 + ``content_chunker.length.boundary.lookahead_percent`` 만큼 초과할 수 있습니다. 이와는 별도로, + 절단 위치가 자소 클러스터(결합 문자, 이형 선택자, 너비 없는 접합자로 연결된 이모지 시퀀스 등) + 내부에 놓이게 될 경우 최대 32자까지 추가로 초과할 수 있습니다. 이 초과는 + ``lookahead_percent`` 의 영향을 받지 않으며 ``0`` 으로 설정해도 발생할 수 있습니다. 두 종류의 + 초과는 동일한 절단 위치에서 동시에 발생하지 않으므로, 기본값 기준 청크 길이는 640~840자 + 범위에 들어갑니다. 청크가 평균적으로 짧아지는 만큼 문서에서 생성되는 청크 수는 고정 길이 + 분할보다 약 3~25% 늘어납니다(``content_chunker.max_chunks_per_document`` 참고). + ``content_chunker.length.boundary.enabled`` 를 ``false`` 로 설정하거나 두 백분율을 모두 + ``0`` 으로 설정하면 기존의 고정 길이 동작과 완전히 동일한 결과가 됩니다. 이 설정 변경은 이후에 + 청크화되는 문서에만 영향을 줍니다. 이미 청크 배열로 저장된 문서는 다시 크롤링될 때까지 원래 + 경계를 유지합니다. + +.. note:: + + ``content_chunker.length.chunk_size`` 는 문자 수로 지정하지만, 임베딩 모델이 한 번에 받아들일 + 수 있는 것은 토큰 수 상한까지입니다. |Fess| 는 임베딩 대상 텍스트를 잘라내지 않으므로 상한을 + 넘는 부분은 벡터에 반영되지 않을 수 있습니다. ``chunk_size`` 는 사용하는 모델의 입력 상한에 + 맞춰 선택하세요. 예를 들어 ``paraphrase-multilingual-MiniLM-L12-v2`` (최대 128 토큰)로 실측한 + 결과, 벡터에 반영된 범위는 영어로 약 440자, 일본어로 약 210자였습니다(텍스트에 따라 + 달라집니다). 이 모델에서는 기본값 ``chunk_size=800`` 인 청크의 뒷부분이 벡터에 반영되지 + 않습니다. + +.. note:: + + HNSW의 ``m`` 및 ``ef_construction`` 파라미터는 ``doc.json`` 에 하드코딩되어 있으며 + (``m=16`` / ``ef_construction=100``), 설정으로 변경할 수 없습니다. + +opensearch 프로바이더 연결 설정 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +내장 ``opensearch`` 프로바이더(OpenSearch ML Commons)의 연결 설정입니다. 위와 동일한 +``system.properties`` 파일에 설정합니다. + +.. list-table:: + :header-rows: 1 + :widths: 50 20 30 + + * - 프로퍼티 + - 기본값 + - 설명 + * - ``content_chunker.embedding.opensearch.model.id`` + - (필수) + - ML Commons에 이미 배포된 모델의 ID + * - ``content_chunker.embedding.opensearch.api.url`` + - 검색 엔진의 주소 + - ML Commons API 엔드포인트. 미설정 시 |Fess|\ 가 이미 사용 중인 검색 엔진으로 기본 + 설정됩니다(예: ``http://localhost:9200``) + * - ``content_chunker.embedding.opensearch.username`` / ``password`` + - 검색 엔진의 인증 정보 + - 미설정 시 검색 엔진 연결에 사용하는 인증 정보로 대체되지만, 이는 ``api.url``\ 이 설정되지 + 않은 동안(즉 대상이 |Fess|\ 가 이미 사용 중인 클러스터와 동일한 경우)에만 적용됩니다. + ``api.url``\ 을 설정하면 이 대체 동작은 적용되지 않습니다 + * - ``content_chunker.embedding.opensearch.timeout`` + - ``60000`` + - 요청 타임아웃(ms) + * - ``content_chunker.embedding.opensearch.connect.timeout`` + - ``5000`` + - 연결 타임아웃(ms) + * - ``content_chunker.embedding.opensearch.retry.max`` + - ``3`` + - 일시적 오류(429, 5xx 등)에 대한 최대 시도 횟수(첫 번째 시도 포함). 재시도 횟수가 아닙니다. + ``3`` 이면 최대 3번 요청하고 그 사이의 대기는 2번입니다. ``1`` 이하이면 재시도하지 않습니다 + * - ``content_chunker.embedding.opensearch.retry.base.delay.ms`` + - ``2000`` + - 재시도 기본 백오프 지연(ms) + * - ``content_chunker.embedding.opensearch.availability.check.interval`` + - ``60`` + - 프로바이더 가용성 확인 간격(초) + * - ``content_chunker.embedding.opensearch.document.prefix`` / ``query.prefix`` + - (빈 값) + - 임베딩 전에 문서/쿼리 텍스트 앞에 붙이는 접두사 + +.. warning:: + + ``system.properties`` 의 내용은 관리 화면의 「시스템 정보」→「설정 정보」 화면, 「앱 속성」 + 패널에서 확인할 수 있습니다. ``content_chunker.embedding.opensearch.password`` 는 이 화면에서 + ``XXXXXXXX`` 로 마스킹되지만 ``username`` 은 그대로 표시됩니다. 또한 ``-Dfess.system.<키>`` 로 + 지정한 값은 같은 화면의 「시스템 속성」 패널에 **마스킹되지 않은 채** 표시되므로, 인증 정보는 + 시작 옵션이 아니라 ``system.properties`` 에 기술하세요. + +기타 프로바이더(ollama / openai / gemini / bedrock) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``ollama`` 프로바이더(``fess-llm-ollama`` 플러그인)는 ``content_chunker.embedding.ollama.`` +접두사 아래에 동일한 형식의 설정을 사용합니다(``api.url`` 기본값은 ``http://localhost:11434``, +``model`` 기본값은 ``embeddinggemma``, ``document.prefix`` / ``query.prefix`` 기본값은 각각 +``title: none | text:`` / ``task: search result | query:`` 입니다). ``nomic-embed-text`` 계열의 +모델을 사용하는 경우에는 ``document.prefix`` / ``query.prefix`` 에 ``search_document:`` / +``search_query:`` 를 명시적으로 설정하세요. 이 접두사는 임베딩할 텍스트에 그대로 연결되며 +앞뒤 공백이 잘리지 않으므로, 위의 기본값과 ``search_document:`` / ``search_query:`` 는 모두 +**끝에 반각 공백이 하나 포함되어 있습니다**\ . 접두사를 직접 설정할 때는 구분용 공백을 +잊지 마세요. +``openai`` 와 ``gemini`` 프로바이더도 각각 +``content_chunker.embedding.openai.`` 및 ``content_chunker.embedding.gemini.`` 접두사 아래에 +동일한 방식으로 설정합니다. 전체 설정 항목은 각 플러그인의 문서를 참조하세요. +``bedrock`` 프로바이더는 ``content_chunker.embedding.bedrock.`` 접두사를 사용하며, +``content_chunker.embedding.dimension`` 은 설정한 모델이 생성하는 크기여야 합니다. +:doc:`llm-bedrock` 을 참조하세요. + +설정 절차(opensearch 프로바이더 예시) +======================================= + +이 섹션에서는 내장 ``opensearch`` 프로바이더(ML Commons)를 사용하는 설정 예시를 설명합니다. + +1. 임베딩 모델 배포 +--------------------- + +OpenSearch ML Commons에 임베딩 모델을 등록하고 배포합니다. 단일 노드 클러스터에서는 먼저 다음 +설정을 적용해야 합니다. + +.. code-block:: bash + + curl -XPUT "http://localhost:9200/_cluster/settings" \ + -H "Content-Type: application/json" -d ' + {"persistent": {"plugins.ml_commons.only_run_on_ml_node": false}}' + +모델을 등록하고 배포합니다(예: 384차원 문장 임베딩 모델): + +.. code-block:: bash + + # 모델 등록(응답의 task_id로부터 model_id를 얻습니다) + curl -XPOST "http://localhost:9200/_plugins/_ml/models/_register" \ + -H "Content-Type: application/json" -d ' + { + "name": "huggingface/sentence-transformers/all-MiniLM-L6-v2", + "version": "1.0.2", + "model_format": "TORCH_SCRIPT" + }' + + # 작업 완료 확인 및 model_id 취득(state가 COMPLETED가 되면 model_id가 반환됩니다) + curl "http://localhost:9200/_plugins/_ml/tasks/" + + # 배포 + curl -XPOST "http://localhost:9200/_plugins/_ml/models//_deploy" + + # 상태 확인: model_state가 DEPLOYED가 되어야 합니다 + curl "http://localhost:9200/_plugins/_ml/models/" + +.. note:: + + ``REGISTERED`` 상태 그대로인 모델은 사용할 수 없습니다. 반드시 배포한 뒤 ``model_state`` 가 + ``DEPLOYED`` 가 되었는지 확인하세요. + +2. |Fess| 설정 +------------------ + +``app/WEB-INF/conf/system.properties``\ (RPM/DEB 패키지는 ``/etc/fess/system.properties``, +Docker 버전은 ``/opt/fess/system.properties``. 아래 항목은 모두 같은 파일에 기술합니다):: + + content_chunker.enabled=true + content_chunker.embedding.name=opensearch + content_chunker.embedding.dimension=384 + content_chunker.embedding.opensearch.model.id= + +시맨틱 검색도 함께 사용하려면 다음도 추가합니다:: + + content_chunker.search.enabled=true + +변경 후 |Fess|\ 를 재시작합니다. + +3. 인덱스 재작성(기존 환경에서 활성화하는 경우) +------------------------------------------------- + +``content_chunk_vector`` 필드의 매핑(설정한 차원 수와 ANN 방식 설정 포함)은 ``fess.search`` +인덱스가 **새로 생성되는 시점에** 적용됩니다. + +- **신규 설치의 경우**: |Fess|\ 를 처음 시작하기 전에 위 설정을 ``system.properties`` 에 + 적용해 두면, 인덱스가 처음 생성될 때 올바른 매핑이 자동으로 적용되므로 이 단계는 필요하지 + 않습니다. +- **이미 인덱스가 존재하는 경우**\ (즉 이전에 |Fess|\ 를 한 번이라도 시작한 적이 있는 경우): 실행 + 중인 인덱스에는 새 매핑이 자동으로 반영되지 않으며, 기존 매핑을 나중에 수정할 수도 없습니다. + 다음과 같이 인덱스를 재작성하세요. + + 「시스템 정보」→「유지보수」를 열고, 「재인덱싱」에서 「에일리어스 갱신」을 활성화한 상태로 + 실행합니다. + + 재작성된 인덱스에 인덱스 설정의 ``index.knn: true`` 와, 설정한 차원 수 및 ANN 방식 설정을 가진 + ``content_chunk_vector`` 매핑이 포함되어 있는지 확인할 수 있습니다(``index.knn`` 은 인덱스 + 설정, ANN 방식 설정은 매핑으로 적용 대상이 서로 다릅니다). + +.. warning:: + + 「재인덱싱」은 백그라운드에서 비동기로 실행되며, 관리 화면에는 완료를 알리는 알림이 + 표시되지 않습니다. ``_cat/indices`` 는 새 인덱스가 존재한다는 것(상태, 문서 수 등)만 + 보여줄 뿐, 에일리어스가 어느 인덱스를 가리키는지는 보여주지 않습니다. 아래 인덱서 작업 + 절차로 넘어가기 전에 ``_cat/aliases`` 로 ``fess.search`` 와 ``fess.update`` 가 모두 새 + 인덱스를 가리키는지 확인하세요. |Fess|\ 의 로그는 실패 시에만 경고를 남기므로, 로그가 + 조용하다는 것이 성공의 증거가 되지는 않으며 알려진 실패가 없다는 것만 나타냅니다. 이전 + 인덱스(그동안 ``fess.search`` 에일리어스가 가리키고 있던 실체 인덱스로, + ``fess.`` 형태의 이름을 가집니다)는 자동으로 삭제되지 않으므로, 더 이상 + 필요하지 않게 되면 수동으로 삭제하세요. 두 인덱스가 모두 존재하는 동안에는 인덱스용 + 디스크 사용량이 평소의 약 2배가 됩니다. + +4. 인덱서 작업 활성화 +----------------------- + +청크 분할과 임베딩 생성은 스케줄러 작업 **Content Chunk Vector Indexer**\ (ID: +``content-chunk-vector-indexer``; 기본 비활성화; 스케줄 ``0 13 * * *``)가 수행합니다. + +「시스템」→「스케줄러」에서 이 작업을 활성화한 뒤 「지금 시작」으로 한 번 실행합니다. 이후에는 +크롤링 완료 여부와 관계없이 설정된 일정(기본값은 매일 13:00)에 따라 미처리 문서가 처리됩니다. +이 작업은 크롤링 작업과 연쇄되지 않으므로, 크롤링 직후에 처리하고 싶다면 일정을 크롤링 작업의 +예상 완료 시각보다 뒤로 설정하세요. + +.. note:: + + 다중 노드 구성에서는 이 작업을 정확히 하나의 노드에서만 실행하도록 고정하는 것을 권장합니다. + 모든 노드에서 동시에 실행해도 정합성이 깨지지는 않지만, 모든 노드가 동일한 문서를 중복해서 + 처리하고 임베딩하게 되어 임베딩 프로바이더에 대한 부하와 비용이 노드 수만큼 배로 늘어납니다. + + 고정하려면 다음 **두 가지** 설정이 모두 필요합니다. 둘 중 하나만으로는 고정되지 않습니다. + + 1. **작업을 실행하고자 하는 노드에서**: ``app/WEB-INF/classes/fess_config.properties``\ (RPM/DEB + 패키지는 ``/etc/fess/fess_config.properties``)에 ``scheduler.target.name=<임의의 식별자>`` 를 + 설정(또는 ``-Dfess.config.scheduler.target.name=<임의의 식별자>`` 로 지정)한 뒤 해당 노드를 + 재시작합니다. (기본값은 빈 문자열이며, 다른 모든 노드는 기본값 그대로 둡니다.) + 2. 관리 화면의 「시스템」→「스케줄러」에서 Content Chunk Vector Indexer 작업을 열고, 「대상」 + 필드를 ``all`` 에서 1단계에서 설정한 것과 동일한 식별자로 변경한 뒤 저장합니다. + + 「대상」 필드의 의미는 :doc:`../admin/scheduler-guide` 를 참조하세요. 「대상」 필드를 ``all`` + 로 남겨두면 ``scheduler.target.name`` 을 설정하더라도 작업이 고정되지 **않습니다**. ``all`` 은 + 항상 일치하는 특수 값으로 취급되므로, 1단계만 또는 2단계만으로는 충분하지 않으며 반드시 둘 다 + 수행해야 합니다. + +.. warning:: + + 고정한 뒤에는 「지금 시작」도 **1단계에서 식별자를 설정한 노드의 관리 화면에서** 실행하세요. + 대상이 아닌 노드에서 「지금 시작」을 누르면 화면에는 작업을 시작했다는 메시지가 표시되지만, + 「대상」이 일치하지 않으므로 작업은 실행되지 않습니다(해당 노드의 로그에 ``Ignoring job`` 이 + INFO로 출력될 뿐입니다). + +5. 처리 상태 확인 +------------------- + +각 문서의 처리 결과는 ``content_chunk_status`` 필드에서 확인할 수 있습니다. + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - 값 + - 의미 + * - (필드 없음) + - 아직 미처리(다음 작업 실행에서 처리됨). 재크롤링된 문서도 이 상태로 돌아갑니다 + * - ``done`` + - 청크 분할과 벡터 생성이 완료됨 + * - ``chunked`` + - 청크 분할만 완료됨(chunk-only 모드). ``embedding.name=none`` 인 경우 외에, + ``embedding.name`` 에 지정한 프로바이더의 플러그인이 설치되어 있지 않은 경우에도 이 + 상태가 됩니다 + * - ``skipped`` + - 처리가 스킵됨. 본문이 비어 있는(공백만 있는 경우 포함) 문서, 청크가 하나도 생성되지 않은 + 문서, ``max_chunks_per_document`` 를 초과한 문서가 해당됩니다. + ``content_chunker.chunker.name`` 에 존재하지 않는 이름을 지정한 경우에도 청커를 찾지 못해 + 청크가 생성되지 않으므로 모든 문서가 이 상태가 됩니다. 종료 상태이며, 작업을 다시 + 실행해도 재처리되지 않습니다 + * - ``fail`` + - 처리 실패(로그를 확인하세요). 종료 상태이며, 기본적으로 작업을 다시 실행해도 재처리되지 + 않습니다. 재처리하려면 ``content_chunker.job.retry_failed`` 를 ``true`` 로 설정합니다 + +검색 엔진에 직접 질의하여 상태 분포를 확인할 수 있습니다:: + + curl -XPOST "http://localhost:9200/fess.search/_search" \ + -H "Content-Type: application/json" -d ' + {"size": 0, "aggs": {"status": {"terms": {"field": "content_chunk_status", "missing": "pending"}}}}' + +``missing`` 옵션에 의해 ``content_chunk_status`` 를 가지지 않는(즉 미처리) 문서는 ``pending`` +이라는 키의 버킷으로 집계됩니다. + +청크 작업의 상황은 이 ``content_chunk_status`` 의 건수 분포로 판단하세요. 작업을 실행할 때마다 +``pending`` 이 줄고 ``done`` (chunk-only 모드에서는 ``chunked``)이 늘어나면 순조로운 것입니다. +``fail`` 이 나타나면 |Fess| 로그에서 원인을 확인하세요. ``skipped`` 는 본문이 빈 문서 등에서는 +정상이지만, 거의 모든 문서가 ``skipped`` 라면 ``content_chunker.chunker.name`` 의 오류를 +의심하세요(청커를 찾지 못하면 ``Chunker not found`` 라는 WARN 로그가 출력됩니다). + +.. warning:: + + 설정을 고치는 것만으로는 ``skipped`` 와 ``fail`` 이 원래대로 돌아가지 않습니다. ``skipped`` + 문서는 작업을 다시 실행해도 선택되지 않고(재크롤링된 문서는 미처리로 돌아갑니다), ``fail`` + 문서는 ``content_chunker.job.retry_failed`` 를 ``true`` 로 한 경우에만 다시 처리 대상이 + 됩니다. 예를 들어 ``content_chunker.chunker.name`` 을 잘못 지정한 채 작업을 실행해 모든 + 문서가 ``skipped`` 가 되었다면, 이름을 고친 뒤 ``content_chunk_status`` 를 삭제하고 나서 + 작업을 다시 실행하세요(``skipped`` 문서는 ``content`` 가 다시 쓰이지 않았으므로 그대로 + 재처리할 수 있습니다):: + + curl -XPOST "http://localhost:9200/fess.search/_update_by_query" \ + -H "Content-Type: application/json" -d ' + { + "query": {"term": {"content_chunk_status": "skipped"}}, + "script": {"source": "ctx._source.remove(\"content_chunk_status\")"} + }' + +시맨틱 검색의 동작 방식 +========================== + +``content_chunker.search.enabled=true`` 를 설정하면 시맨틱 서처가 Rank Fusion에 등록되며, +그 이후 키워드 검색 결과와 벡터 검색 결과가 병합됩니다(Rank Fusion의 동작 방식은 +:doc:`rank-fusion` 을 참조하세요). 융합은 기본적으로 |Fess|\ 가 수행하지만, +``rank.fusion.engine.enabled=true`` 를 설정하면 OpenSearch 측에서 수행할 수도 있습니다 +(:ref:`rank-fusion-engine` 을 참조하세요). +또한 검색 시에는 ``content_chunker.enabled`` 도 함께 참조됩니다. ``content_chunker.enabled=false`` +이거나 ``content_chunker.embedding.name=none`` 인 경우에는 서처가 등록되어 있더라도 시맨틱 +검색은 실행되지 않습니다(이 판정은 요청마다 이루어지므로 재시작은 필요하지 않습니다). + +.. warning:: + + 시맨틱 서처는 시작 시에 등록되므로 **활성화에는 재시작이 필요합니다**. 비활성화(값을 다시 + ``false`` 로 변경)는 요청 단위로 판정되므로 즉시 반영됩니다. + +exact 모드와 ann 모드 +------------------------ + +검색 방식은 인덱스의 상태에 따라 자동으로 선택됩니다. + +.. list-table:: + :header-rows: 1 + :widths: 12 44 44 + + * - 모드 + - 조건 + - 특징 + * - ``ann`` + - ``index.knn`` 과 ANN 방식 설정을 가진 인덱스 + - HNSW를 이용한 근사 최근접 이웃 검색. 대규모 인덱스에 적합 + * - ``exact`` + - 그 외(``index.knn`` 또는 ANN 방식 설정 중 어느 하나라도 없는 인덱스. 인덱스 상태 판정에 + 실패한 경우를 포함) + - 모든 벡터에 대한 정확한 코사인 유사도 계산. 중소 규모 인덱스에 적합 + +|Fess| 15.10\ 에서 새로 생성되는 ``fess.search`` 인덱스는 ``content_chunker.search.enabled`` 값과 +관계없이 항상 ``index.knn`` 과 ANN 방식 설정을 가지므로, 평소에는 항상 ``ann`` 모드가 +사용됩니다. ``exact`` 모드는 이 메커니즘이 도입되기 전에 만들어진 오래된 인덱스를 위한 +폴백입니다. 기존 인덱스에는 나중에 k-NN 설정을 추가할 수 없으므로, ``exact`` 모드 인덱스를 +``ann`` 모드로 전환하려면 인덱스를 재작성해야 합니다(:ref:`semantic-search-migration` 참조). +또한 이 판정 결과는 60초 동안 캐시되므로, 인덱스를 재작성한 직후에는 반영되기까지 최대 60초가 +걸립니다. + +스코어 컷오프 +---------------- + +``content_chunker.search.min_score`` 에 코사인 유사도(0-1)를 설정하면, 가장 유사도가 높은 +청크마저 그 값에 도달하지 못하는 문서가 시맨틱 검색 결과에서 제외됩니다(문서의 스코어는 가장 +점수가 높은 청크의 스코어가 되므로, 컷오프는 문서 단위로 동작합니다). 어휘가 겹치지 않는 쿼리가 +너무 광범위하게 매칭될 때 히트 수를 줄이는 용도로 사용합니다:: + + content_chunker.search.min_score=0.4 + +설정값은 ``exact`` / ``ann`` 어느 모드에서도 코사인 유사도로 해석됩니다(내부적으로 모드별 스코어 +스케일로 변환됩니다). + +.. note:: + + 이 컷오프가 적용되는 것은 ``content_chunker.search.knn.space_type`` 이 + ``cosinesimil``\ (기본값)인 경우뿐입니다. ``innerproduct`` 나 ``l2`` 를 지정한 ``ann`` 모드 + 인덱스에서는 코사인 유사도를 정의할 수 없으므로, 컷오프는 스킵되며 해당 검색마다 경고 + 로그가 출력됩니다. + +제한 사항 +---------- + +- 쿼리에 포함된 필드 지정 조건(``label:``\ , ``site:``\ , ``filetype:``\ , ``timestamp`` / + ``last_modified`` 의 범위 지정 등)은 임베딩 대상에서 분리되어 벡터 검색에 필터로 적용됩니다. + 판정은 쿼리를 조립한 **뒤**\ 의 문자열에 대해 이루어지므로, 라벨 지정, 패싯을 이용한 좁히기, + 상세 검색의 파일 종류·사이트·일시 지정 등 내부적으로 이러한 조건이 부가되는 조작(``ex_q`` 나 + ``fields.*`` 파라미터에 의한 것을 포함)에서도 시맨틱 검색이 실행되며, 키워드 검색과 동일한 + 조건으로 좁혀집니다. +- 다음 쿼리에서는 **시맨틱 검색이 스킵**\ 되고 키워드 검색만 실행됩니다. + + - 정렬 조건 지정(``sort:`` 의사 필드 또는 ``sort`` 파라미터. 후자도 내부적으로 + ``sort:...`` 로 부가됩니다) + - 필드를 지정하지 않은 단어에 대한 구문(``"..."``), 와일드카드(``*`` ``?``), 퍼지 검색(``~``), + 범위 지정. 상세 검색의 구문 지정도 포함합니다. 반각 ``?`` 는 와일드카드로 해석되므로, + "~란?"처럼 반각 물음표로 끝나는 자연문도 스킵됩니다(전각 ``？`` 는 대상이 아닙니다). + - 단어 제외(``-단어``\ , ``NOT 단어``\ . 상세 검색의 제외어 포함)나 단어 부스트(``단어^2``) + - 단어와 조건을 ``OR`` 로 연결한 쿼리 등, 조건을 필터로 분리할 수 없는 쿼리 + - ``allintitle:`` / ``allinurl:`` + - 조건만 있고 임베딩 대상이 되는 단어를 포함하지 않는 쿼리 + - 구문 분석할 수 없는 쿼리 + +- 위치 정보 검색(지오 필터) 또는 유사 문서 검색과 조합된 경우에도 스킵됩니다. +- 깊은 페이지의 처리는 융합을 수행하는 위치에 따라 다릅니다. + + - |Fess| 측에서 융합하는 경우(기본값)에는 경계가 ``rank.fusion.window_size``\ (기본값 + ``200``)로 결정되며, 기본 설정에서는 검색 결과의 101번째 이후가 키워드 검색만의 결과가 됩니다. + - 검색 엔진 측에서 융합하는 경우(``rank.fusion.engine.enabled=true``)에는 모든 페이지가 + 융합되지만, 페이징은 ``rank.fusion.pagination_depth``\ (기본값 ``1000``)건에서 끝나며 그 + 이후의 페이지는 요청할 수 없습니다. + + 자세한 내용은 :doc:`rank-fusion` 을 참조하세요. +- 임베딩 프로바이더에 연결할 수 없거나 검색 오류가 발생한 경우, |Fess|\ 는 자동으로 키워드 + 검색만의 결과로 폴백합니다(그 결과로 검색 자체가 실패하는 일은 없습니다). +- 역할 및 가상 호스트 기반 접근 제어는 시맨틱 검색 결과에도 적용됩니다. + +AI 검색 모드와의 연계 +======================== + +AI 검색 모드(:doc:`rag-chat`, ``rag.chat.enabled=true``)가 활성화되어 있는 경우, +``content_chunk_status`` 가 ``done`` 인 문서에 대해 답변을 생성할 때 각 청크와의 유사도를 +계산하고, 가장 관련성이 높은 상위 ``content_chunker.chat.top_k`` 개(기본값: ``3``)의 청크만 +LLM의 컨텍스트로 사용합니다. + +이때 임베딩의 대상이 되는 것은 사용자의 발화 그 자체가 아니라 **의도 판정 단계에서 LLM이 생성한 +검색 쿼리**\ 입니다(재검색이 발생한 경우에는 재생성된 쿼리가 됩니다). 문서 요약을 요청한 경우처럼 +검색 쿼리가 생성되지 않는 경우에는 청크 선택이 이루어지지 않습니다. + +그 결과 긴 문서라도 관련된 부분만 LLM에 전달되어 답변 정확도 향상과 토큰 사용량 절감을 기대할 수 +있습니다. ``content_chunk_status`` 가 ``chunked``\ (청크는 있지만 벡터가 없는 상태)인 문서에서는 +유사도 계산 대신 키워드(하이라이트) 일치에 의한 청크 선택이 이루어집니다. ``skipped`` / +``fail`` 및 미처리 문서는 이전과 마찬가지로 전체 본문(또는 하이라이트된 발췌)을 사용합니다. + +이 동작은 ``content_chunker.search.enabled`` 와 무관하지만, ``content_chunker.enabled`` 가 +활성화되어 있어야 합니다. 또한 선택된 청크를 연결한 텍스트도 +``rag.chat.content.fulltext.max.length``\ (기본값 ``3000``)로 잘리므로, +``content_chunker.chat.top_k`` 나 ``content_chunker.length.chunk_size`` 를 크게 설정하더라도 +LLM에 전달되는 문자 수는 이 상한을 넘지 않습니다. + +.. _semantic-search-migration: + +15.7 이전 버전에서 업그레이드하는 경우의 마이그레이션 +======================================================== + +15.7 이전 버전에서 |Fess|\ 를 업그레이드하는 경우, 현재 이 기능들을 어떻게 사용하고 있는지에 따라 +아래 네 가지 패턴 중 하나에 해당합니다. 해당하는 패턴의 안내를 따르세요. + +신규 설치의 경우 +------------------ + +추가 작업은 필요하지 않습니다. 벡터 검색을 사용하고 싶다면 |Fess|\ 를 처음 시작하기 전에 이 +페이지의 *설정 레퍼런스* 섹션에 따라 ``system.properties`` 를 설정해 두기만 하면, 인덱스가 처음 +생성될 때 올바른 매핑이 자동으로 적용됩니다.(구체적인 절차는 위의 *설정 절차* 를 참조하세요.) + +.. note:: + + 이전에 |Fess|\ 를 한 번이라도 시작한 적이 있다면(즉 인덱스가 이미 존재한다면), 이 패턴이 + 아니라 아래의 *기존 사용자* 패턴 중 하나를 따르세요. + +기존 사용자로, 벡터 검색을 이용하지 않는 경우 +------------------------------------------------ + +아무런 작업도 필요하지 않습니다. ``content_chunker.enabled`` 와 ``content_chunker.search.enabled`` +는 모두 기본값이 ``false`` 이므로, 업그레이드 후에도 검색 결과와 기존 인덱스의 동작은 변하지 +않습니다. 새로 추가된 스케줄러 작업 **Content Chunk Vector Indexer**\ 는 시작 시 자동으로 +등록되지만, 기본적으로 비활성화되어 있으므로 실행되지 않으며 시맨틱 서처도 Rank Fusion에 +등록되지 않습니다(이 작업은 시작할 때마다 등록되므로, 관리 화면에서 삭제해도 다음 시작 시 +비활성화 상태로 다시 생성됩니다). + +.. note:: + + 벡터 검색을 사용하지 않더라도 |Fess| 15.10 이후에서 인덱스를 **신규 생성**\ (재인덱싱 포함)하면 + ``content_chunk_vector``\ (``knn_vector`` 타입)를 포함하는 매핑과 ``index.knn: true`` 가 + 적용됩니다. OpenSearch에 k-NN 플러그인이 설치되어 있지 않은 구성에서는 그 시점에 인덱스 + 생성이 실패합니다. 자세한 내용은 이 페이지의 *전제 조건* 을 참조하세요. + +기존 사용자로, 벡터 검색을 이용하려는 경우 +---------------------------------------------- + +실행 중인 인덱스에는 새 매핑이 자동으로 반영되지 않으므로, 다음 단계가 필요합니다. + +1. 이 페이지의 *설정 레퍼런스* 에 설명된 대로 ``system.properties`` 에 설정을 적용합니다 + (opensearch 프로바이더를 사용하는 경우의 구체적인 절차는 위의 *설정 절차* 를 참조하세요). +2. |Fess|\ 를 재시작합니다. +3. 관리 화면에서 「시스템 정보」→「유지보수」의 「재인덱싱」을, 「에일리어스 갱신」을 활성화한 + 상태로 실행합니다. 이 작업은 백그라운드에서 비동기로 진행되며 완료 알림은 표시되지 + 않습니다. ``_cat/indices`` 는 새 인덱스의 존재만 보여줄 뿐 에일리어스가 전환되었는지는 + 보여주지 않으므로, 다음 단계로 넘어가기 전에 ``_cat/aliases`` 로 ``fess.search``/ + ``fess.update`` 가 새 인덱스를 가리키는지 확인하세요(|Fess|\ 의 로그는 실패 시에만 + 경고를 남기므로 조용하다고 해서 성공을 의미하지는 않습니다). 이전 인덱스는 자동으로 + 삭제되지 않으므로 필요 없어지면 수동으로 삭제하세요(두 인덱스가 모두 존재하는 동안 + 디스크 사용량은 평소의 약 2배가 됩니다). +4. 위의 에일리어스 전환이 완료되었음을 확인한 후에, 「시스템」→「스케줄러」에서 Content Chunk + Vector Indexer 작업을 활성화하고 실행합니다(재크롤링은 필요하지 않습니다. 이 작업은 기존 + 인덱스의 ``_source`` 에서 ``content`` 를 읽어 청크로 나누고 임베딩합니다). + +.. note:: + + 1단계에서 ``content_chunker.search.enabled=true`` 까지 함께 적용하면, 2단계의 재시작부터 + 4단계가 완료될 때까지 검색할 때마다 쿼리의 임베딩만 실행되고 그 결과는 반영되지 않는 상태가 + 됩니다. ``openai``, ``gemini``, ``bedrock`` 처럼 종량제 프로바이더를 사용하는 경우에는 + ``content_chunker.search.enabled=true`` 의 적용과 재시작을 4단계 완료 후에 수행하세요. + +fess-webapp-semantic-search 플러그인을 사용하고 있었던 경우 +---------------------------------------------------------------- + +|Fess| 15.7 이전에서 시맨틱 검색을 제공하던 ``fess-webapp-semantic-search`` 플러그인은 15.10에서 +코어로 통합되어 이제 **불필요(사용 중단)**\ 합니다. 위의 *기존 사용자로, 벡터 검색을 이용하려는 +경우* 의 단계에 더해 다음 작업도 필요합니다. + +1. **플러그인 제거**: ``app/WEB-INF/plugin/`` 에서 ``fess-webapp-semantic-search-*.jar`` 를 + 삭제합니다(Docker에서는 ``FESS_PLUGINS`` 에서 제외합니다). + +2. **기존 설정 제거**: ``-Dfess.semantic_search.*`` 시작 옵션을 모두 삭제합니다. 또한 기존 + 플러그인용으로 ``-Drank.fusion.searchers=default,semantic`` 을 지정했다면 이것도 + 제거합니다. 그대로 두면 새 시맨틱 서처(``semantic_chunk``)가 Rank Fusion에서 제외되고 시작 + 시 경고 로그가 남습니다. + +3. **기존 인제스트 파이프라인 분리**: 기존 플러그인은 ``-Dfess.semantic_search.pipeline`` 을 + 설정했던 경우에 한해, 인덱스를 생성할 때 ``default_pipeline``\ (뉴럴 검색용 인제스트 + 파이프라인)을 인덱스 설정에 심어 넣습니다. **플러그인을 제거해도 파이프라인은 인덱스에 그대로 + 남아 계속 동작하므로**, 위의 *기존 사용자로, 벡터 검색을 이용하려는 경우* 에 있는 재인덱싱을 + 수행하기 **전에** 분리하세요. 재인덱싱 후의 새 인덱스에는 이 설정이 붙지 않으므로, 나중에 + 실행해도 의미가 없습니다. ``_cat/aliases`` 로 ``fess.search`` 가 가리키는 + ``fess.`` 를 확인하고, 에일리어스가 아니라 실체 인덱스 이름을 지정합니다:: + + curl -XPUT "http://localhost:9200/fess./_settings" \ + -H "Content-Type: application/json" -d ' + {"index": {"default_pipeline": "_none"}}' + + 인덱스 설정을 해제해도 인제스트 파이프라인 자체는 검색 엔진에 남아 있습니다. 앞으로 사용하지 + 않을 경우에는 삭제하세요:: + + curl -XDELETE "http://localhost:9200/_ingest/pipeline/<파이프라인명>" + +4. **새 설정 추가**: 이 페이지의 *설정 레퍼런스* 에 설명된 대로 ``system.properties`` 에 + ``content_chunker.*`` 를 설정합니다. 기존 ML Commons 모델을 계속 사용하려면 + ``content_chunker.embedding.name=opensearch`` 로 설정하고, 기존 ``model_id`` 를 + ``content_chunker.embedding.opensearch.model.id`` 에 지정합니다. + +5. **인덱스 재작성 및 작업 실행**: 기존 플러그인이 저장하던 벡터 필드(기본 구성에서는 + ``content_vector``)와 새 코어 기능이 사용하는 ``content_chunk_vector`` 필드는 별개의 필드이므로, + 기존 벡터를 새 기능에서 사용할 수는 없습니다. 한편 재인덱싱은 ``_source`` 를 그대로 + 복사하므로, 기존 벡터는 새 인덱스에도 복제되어 동적 매핑으로 디스크를 계속 소비합니다. + 재인덱싱 **전에** 제거해 둘 것을 권장합니다(필드 이름을 변경했다면 그에 맞게 바꿔 읽으세요):: + + curl -XPOST "http://localhost:9200/fess.search/_update_by_query" \ + -H "Content-Type: application/json" -d ' + { + "query": {"exists": {"field": "content_vector"}}, + "script": {"source": "ctx._source.remove(\"content_vector\")"} + }' + + 그 후 「시스템 정보」→「유지보수」에서 「재인덱싱」을 실행한 뒤, Content Chunk Vector Indexer + 작업을 활성화·실행하여 벡터를 다시 생성하세요. + +주의 사항 +========== + +임베딩 모델(차원) 변경 +------------------------ + +차원이 다른 임베딩 모델로 전환하려면 다음 순서로 진행합니다. + +1. 기존의 오래된 벡터를 삭제합니다. 차원 수가 다른 오래된 벡터가 남아 있는 상태로 재인덱싱하면, + 새 매핑이 그 벡터들을 받아들이지 못해 해당 문서가 새 인덱스로 복사되지 않은 채 처리가 + 진행됩니다. |Fess|\ 는 재인덱싱의 HTTP 상태 코드만 확인하므로, 관리 화면에는 오류가 표시되지 + 않은 채 문서가 누락됩니다:: + + curl -XPOST "http://localhost:9200/fess.search/_update_by_query" \ + -H "Content-Type: application/json" -d ' + { + "query": {"exists": {"field": "content_chunk_status"}}, + "script": {"source": "ctx._source.remove(\"content_chunk_vector\"); ctx._source.remove(\"content_chunk_status\")"} + }' + + .. note:: + + 대상으로 ``fess.update``\ (재인덱싱의 읽기 원본이 되는 갱신용 에일리어스)를 지정해도 + 됩니다. 또한 이 작업으로는 ``content`` 필드가 청크의 배열 그대로 남습니다. 다음 작업 실행 + 시에 다시 연결한 뒤 재분할되므로, ``content_chunker.length.overlap`` 에 0 이외의 값을 + 설정한 경우에는 중복 부분이 이중으로 포함된 상태로 재분할됩니다. 이것이 문제가 된다면 + 해당 문서를 다시 크롤링하세요. + +2. ``content_chunker.embedding.dimension`` 과 사용 중인 프로바이더의 모델 설정을 변경합니다. +3. 위의 *설정 절차* 에 있는 *3. 인덱스 재작성(기존 환경에서 활성화하는 경우)* 에 따라 인덱스를 + 재작성하고 인덱서 작업을 다시 실행합니다. + +차원 수가 같은 다른 모델로 변경하는 경우 +------------------------------------------ + +``content_chunker.embedding.opensearch.model.id`` 등 임베딩 모델 설정을 차원 수가 같은 다른 +모델로 변경해도 |Fess| 는 오류도 경고도 없이 받아들입니다. 검사되는 것은 차원 수뿐이며, 벡터를 +만든 모델은 인덱스에 기록되지 않기 때문입니다. 이 상태에서는 저장된 벡터는 이전 모델로, 검색 +시의 쿼리 벡터는 새 모델로 만들어져 서로 다른 벡터 공간에 있게 되므로 검색 결과의 관련성이 +무너집니다. 또한 코사인 유사도 값의 분포는 모델마다 다르므로, 이전 모델에 맞춰 조정한 +``content_chunker.search.min_score`` 가 새 모델에서는 너무 엄격해 대부분의 결과가 잘려 나갈 수 +있습니다. + +모델을 전환할 때는 새 모델을 설정한 뒤, 위의 *임베딩 모델(차원) 변경* 의 순서 1과 같은 +``_update_by_query`` 로 ``content_chunk_vector`` 와 ``content_chunk_status`` 를 삭제하고, +인덱서 작업을 다시 실행하여 모든 문서의 벡터를 다시 생성하세요(차원 수가 같으므로 인덱스를 +다시 만들 필요는 없습니다). ``content_chunker.search.min_score`` 를 설정했다면 새 모델에서 +다시 검토하세요. + +차원 수를 설정하지 않고 인덱스를 만든 경우 +--------------------------------------------- + +``content_chunker.embedding.dimension`` 이 미설정인 채로 ``fess.search`` 인덱스를 만들면 +``content_chunk_vector`` 의 매핑은 경고 없이 ``768`` 차원이 되며, 이후에는 변경할 수 없습니다. +이 상태에서 인덱서 작업을 실행하면 임베딩 처리 시 차원 수를 읽을 수 없어 오류가 되므로 문서가 +``fail`` 이 됩니다. + +- 사용하는 모델의 차원 수가 ``768`` 이라면 ``content_chunker.embedding.dimension=768`` 을 + 설정합니다. 매핑과 일치하므로 인덱스를 다시 만들 필요는 없습니다. +- ``768`` 이 아니라면 올바른 차원 수를 설정합니다. 매핑(``768``)과 설정값이 어긋나 있는 동안 + 인덱서 작업은 ERROR 로그를 출력하고 실행을 건너뜁니다. 위의 *임베딩 모델(차원) 변경* 의 + 순서 3과 같은 방법으로 인덱스를 다시 만드세요. + +어느 경우든 이미 ``fail`` 이 된 문서는 자동으로 재처리되지 않습니다. 인덱스를 다시 만드는 +경우에는 *임베딩 모델(차원) 변경* 의 순서 1의 ``_update_by_query`` 가 +``content_chunk_status`` 도 삭제합니다. 다시 만들지 않는 경우에는 +``content_chunker.job.retry_failed`` 를 일시적으로 ``true`` 로 설정하고 작업을 다시 실행하세요. + +디스크 사용량 +-------------- + +청크 벡터는 검색 인덱스 구조 외에도 ``_source`` 에 보관되므로, 각 문서는 청크 수 × 벡터 차원 +수에 비례하는 추가 디스크 용량을 소비합니다. 디스크 용량이 문제가 되면 +``content_chunker.length.chunk_size`` 나 ``content_chunker.max_chunks_per_document`` 를 +조정하세요. + +chunk-only 모드 +----------------- + +``content_chunker.embedding.name=none`` 을 설정하면 임베딩 벡터를 생성하지 않고 청크 분할만 +수행합니다(``content_chunk_status`` 는 ``chunked`` 가 됩니다). 이를 이용하면 임베딩 +프로바이더가 준비되기 전에 청크 분할을 미리 실행해 둘 수 있으며, 이후 프로바이더를 설정하고 +작업을 다시 실행하면 이미 저장된 청크에 대해 벡터만 생성됩니다(다시 청크로 나누지는 않습니다). + +대규모 코퍼스에서의 메모리 설정 +---------------------------------- + +인덱서 작업의 자식 JVM은 ``fess_config.properties`` 의 ``jvm.chunk.options``\ (기본값은 +``-Xms128m -Xmx1g`` 를 포함하는 JVM 옵션)로 시작됩니다. +``content_chunker.job.max_documents_per_run`` 의 기본값이 무제한이므로, 한 번의 실행에서 대기 +중인 모든 문서 ID를 메모리에 보관합니다. 문서 ID는 SHA-512 다이제스트(128자)이며, 한 건당 대략 +200바이트를 힙에 보관합니다. 청크 처리 자체에도 200~250MB 정도를 사용하므로, **100만~200만 건을 +넘는 코퍼스**\ 에서는 ``jvm.chunk.options`` 의 ``-Xmx`` 값을 높이거나 +``content_chunker.job.max_documents_per_run`` 에 유한한 값을 설정하여 분할 실행하세요. +``jvm.chunk.options`` 는 ``app/WEB-INF/classes/fess_config.properties``\ (RPM/DEB 패키지는 +``/etc/fess/fess_config.properties``)에서 재정의합니다(JVM 옵션의 개념은 :doc:`setup-memory` 를 +참조하세요). + +동일한 무제한 기본값은 ``openai``, ``gemini``, ``bedrock`` 과 같은 종량제 임베딩 프로바이더를 사용할 때 +비용 측면에도 영향을 줍니다. 첫 인덱서 실행에서 기존 코퍼스 전체가 한 번에 임베딩되어 +그만큼의 비용이 한꺼번에 청구됩니다. 비용을 여러 번의 실행에 분산시키려면 +``content_chunker.job.max_documents_per_run`` 에 유한한 값을 설정하세요. + +참고 정보 +========== + +- :doc:`rank-fusion` - Rank Fusion(하이브리드 검색) 설정 +- :doc:`rag-chat` - AI 검색 모드 설정 +- :doc:`llm-overview` - LLM 통합 개요 +- :doc:`llm-ollama` - Ollama 설정 +- :doc:`setup-memory` - JVM 메모리 설정 +- :doc:`../install/upgrade` - 업그레이드 절차 diff --git a/ko/15.10/config/security-role.rst b/ko/15.10/config/security-role.rst new file mode 100644 index 000000000..007e480be --- /dev/null +++ b/ko/15.10/config/security-role.rst @@ -0,0 +1,72 @@ +================= +역할 기반 검색 설정 +================= + +역할 기반 검색에 대하여 +================== + +|Fess| 에서는 임의의 인증 시스템에서 인증된 사용자의 인증 정보를 기반으로 검색 결과를 구분할 수 있습니다. +예를 들어 역할 a를 가진 사용자 A는 검색 결과에 역할 a의 정보가 표시되지만, 역할 a를 가지지 않은 사용자 B는 검색해도 표시되지 않습니다. +이 기능을 이용하여 포털이나 싱글 사인온 환경에서 로그인한 사용자의 소속 부서별이나 직급별로 검색을 실현할 수 있습니다. + +|Fess| 의 역할 기반 검색에서는 역할 정보를 다음에서 취득할 수 있습니다. + +- 요청 파라미터 + +- 요청 헤더 + +- 쿠키 + +- |Fess| 의 인증 정보 + +포털이나 에이전트형 싱글 사인온 시스템에서는 인증 시 |Fess| 가 실행되고 있는 도메인과 경로에 대해 쿠키로 인증 정보를 저장하여 역할 정보를 취득할 수 있습니다. +또한 리버스 프록시형 싱글 사인온 시스템에서는 |Fess| 에 접근 시 요청 파라미터나 요청 헤더에 인증 정보를 추가하여 역할 정보를 취득할 수 있습니다. + +.. note:: + 요청 파라미터·요청 헤더·쿠키에서의 역할 취득은 초기 상태에서 비활성화되어 있습니다. + 이를 이용하는 경우 ``app/WEB-INF/classes/fess.xml`` 의 ``roleQueryHelper`` 컴포넌트에서 참조할 키 이름(``parameterKey``, ``headerKey``, ``cookieKey``)이나 값의 암호화(``encryptedParameterValue`` 등), 구분 문자(``valueSeparator``, ``roleSeparator``)를 설정해야 합니다. + 초기 상태에서 활성화된 것은 |Fess| 의 인증 정보를 이용한 역할 기반 검색뿐입니다. + +역할 기반 검색 설정 +================= + +여기서는 |Fess| 의 인증 정보를 이용한 역할 기반 검색 설정 방법을 설명합니다. + +|Fess| 의 관리 화면에서 설정 +--------------------- + +|Fess| 를 시작하고 관리자로 로그인합니다. +역할 및 사용자를 생성합니다. +예를 들어 역할 관리 화면에서 Role1을 생성하고, 사용자 관리 화면에서 Role1에 속하는 사용자를 생성합니다. +그룹 단위로 할당하려면 그룹 관리 화면에서 그룹을 생성하고 사용자에게 할당합니다. + +다음으로 크롤 설정에서 권한 란에 ``{role}Role1`` 을 기술하고 저장합니다. +사용자 단위로 지정하는 경우는 ``{user}username``, 그룹 단위로 지정하는 경우는 ``{group}groupname`` 으로 기술할 수 있습니다. +여러 권한을 지정하는 경우는 줄바꿈으로 구분하여 기술합니다. + +이후 이 크롤 설정으로 크롤링하면 지정한 역할·사용자·그룹에 속하는 사용자만 검색 가능한 인덱스가 생성됩니다. +로그인한 사용자에게는 자기 자신을 나타내는 ``{user}username``, 소속 역할의 ``{role}``, 소속 그룹의 ``{group}`` 권한이 자동으로 부여되어 문서에 설정된 권한과 대조됩니다. + +.. note:: + 특정 역할·사용자·그룹의 접근을 명시적으로 거부하려면 ``(deny){role}Role1`` 과 같이 ``(deny)`` 를 붙여 기술합니다(``(allow)`` 를 붙인 경우는 허가이며, 미지정 시와 동일하게 처리됩니다). + +.. note:: + LDAP이나 싱글 사인온과 연계하는 경우 사용자의 역할·그룹 정보는 인증 원본에서 취득되어 동일하게 권한으로 처리됩니다. + LDAP 연계 시의 동작은 ``fess_config.properties`` 의 ``ldap.role.search.user.enabled``, ``ldap.role.search.group.enabled``, ``ldap.role.search.role.enabled``\ (초기값은 모두 ``true``)로 제어할 수 있습니다. + +로그인 +------ + +관리 화면에서 로그아웃합니다. +Role1에 속하는 사용자로 로그인합니다. +로그인에 성공하면 검색 화면 상단으로 리다이렉트됩니다. + +일반적으로 검색하면 크롤 설정에서 Role1의 역할이 설정된 것만 표시됩니다. + +또한 로그인하지 않은 상태의 검색은 guest 사용자에 의한 검색이 됩니다. +로그인하지 않은 사용자에게 표시하려는 문서에는 크롤 설정의 권한 란에 ``{role}guest`` 를 설정해 주십시오(초기값은 ``role.search.guest.permissions`` 에서 정의됩니다). + +로그아웃 +-------- + +관리자 이외의 사용자로 로그인한 상태에서 검색 화면에서 로그아웃을 선택하면 로그아웃됩니다. diff --git a/ko/15.10/config/security-virtual-host.rst b/ko/15.10/config/security-virtual-host.rst new file mode 100644 index 000000000..86571b702 --- /dev/null +++ b/ko/15.10/config/security-virtual-host.rst @@ -0,0 +1,91 @@ +======== +가상 호스트 +======== + +가상 호스트에 대하여 +============== + +|Fess| 에 접근했을 때의 호스트명(HTTP의 ``Host`` 헤더 값)에 따라 검색 결과를 구분할 수 있습니다. +한 대의 |Fess| 서버를 여러 호스트명으로 공개하여, 호스트명마다 다른 검색 대상(크롤 설정)이나 페이지 디자인을 제공할 수 있습니다. +검색 화면의 외관도 호스트마다 다르게 할 수 있습니다. 가상 호스트명과 이름이 일치하는 정적 테마가 해당 호스트에 사용됩니다. + +가상 호스트 기능은 기본적으로 비활성화(미설정) 상태입니다. 아래 절차에 따라 설정합니다. + +시스템 설정 +---------- + +:doc:`관리자 가이드 > 전반 설정 <../admin/general-guide>` 의 "가상 호스트"에서 접근 시의 호스트명과 가상 호스트명의 대응을 설정합니다. 여기서 설정한 가상 호스트명을 크롤 설정에서 지정합니다. + +**형식** + +1행에 1개의 가상 호스트를 다음 형식으로 기술합니다. + +:: + + 헤더명:헤더값=가상호스트명 + +.. list-table:: + + * - *헤더명* + - 판정에 사용할 HTTP 요청 헤더의 이름. 일반적으로는 ``Host`` 를 지정합니다. 리버스 프록시를 경유하여 접근하는 경우 등에는 ``X-Forwarded-Host`` 를 지정할 수도 있습니다. + * - *헤더값* + - 위 헤더에 포함되는 호스트명(필요에 따라 ``호스트명:포트번호`` 형식). 접근 시 클라이언트가 전송하는 헤더 값과 완전 일치(대소문자 구분 없음)하는 경우에 이 가상 호스트가 적용됩니다. + * - *가상호스트명* + - 크롤 설정에서 지정하는 가상 호스트명 + +**예** + +:: + + Host:abc.example.com=host1 + Host:192.168.1.123:8080=host2 + +.. note:: + + 판정은 호스트명의 이름 확인(DNS)이 아닌 요청 헤더 값과의 문자열 일치로 수행됩니다. + 브라우저가 전송하는 ``Host`` 헤더에는, 표준 포트(HTTP는 80, HTTPS는 443)로 접근한 경우 포트 번호가 포함되지 않으며, 그 외 포트로 접근한 경우에는 ``호스트명:포트번호`` 형식으로 포트 번호가 포함됩니다. + 따라서 표준 포트 이외로 공개하는 경우에는 ``Host:abc.example.com:8080=host1`` 과 같이 포트 번호까지 포함하여 지정하십시오. + +.. note:: + + 가상 호스트명에는 영숫자와 밑줄( ``a-z`` , ``A-Z`` , ``0-9`` , ``_`` )만 사용할 수 있습니다. + 그 외의 문자는 자동으로 제거됩니다. + + 또한 다음 이름은 예약되어 있어 가상 호스트명으로 사용할 수 없습니다: + ``admin`` , ``common`` , ``error`` , ``login`` , ``profile`` + +가상 호스트별 페이지 디자인 +--------------------------- + +가상 호스트에 전용 검색 화면을 제공하려면, ``theme.yml`` 의 ``name`` 이 가상 호스트명을 소문자로 한 것(예: ``host1`` )인 정적 테마를 설치합니다. +가상 호스트에 일치하는 요청에는 그 테마가 사용되고, 그 외의 요청에는 기본 테마가 사용됩니다. +이 테마를 기본 테마로 설정할 필요는 없습니다. 번들 테마로부터 테마를 만드는 방법은 :ref:`theme-customize-bundled` 를, 설치 방법은 :doc:`../admin/theme-guide` 를 참조하십시오. + +.. note:: + + |Fess| 15.10 부터는 설정을 저장해도 ``WEB-INF/view/가상호스트명`` 에 JSP가 생성되지 않습니다. + 로그인 화면( ``/login/`` )은 모든 가상 호스트에서 공통 화면( ``WEB-INF/view/admin/login/`` )으로 표시되며, 가상 호스트별로 변경할 수 없습니다. + 가상 호스트별 외관은 위와 같이 가상 호스트 이름과 같은 이름의 정적 테마로 변경합니다. + + +크롤 설정 +--------- + +웹 크롤 설정, 파일 크롤 설정, 데이터 스토어 크롤 설정 중 하나에서 "가상 호스트"를 지정합니다. +"가상 호스트"는 시스템 설정에서 설정한 가상 호스트명 중 하나를 지정합니다. 1개의 크롤 설정에 여러 가상 호스트를 지정할 수도 있습니다(1행에 1개). + +가상 호스트로 접근한 검색에서는, 해당 가상 호스트가 지정된 크롤 설정의 문서만 검색 결과에 표시됩니다. +어떤 가상 호스트에도 일치하지 않는 접근(가상 호스트가 미설정인 일반 접근)에서는 이 필터링이 적용되지 않아 평소와 같이 모든 검색 결과가 표시됩니다. + +**예** + +.. list-table:: + + * - *가상 호스트* + - ``host1`` + + +사용자 태그 +----------- + +로그인한 사용자가 검색 결과의 문서에 붙이는 태그(내 태그)도 가상 호스트를 따릅니다(태그 기능을 활성화한 경우). 가상 호스트로 접근해 만든 태그는 그 가상 호스트에서만 목록에 표시되고 사용할 수 있습니다. 어떤 가상 호스트와도 일치하지 않는 접근에서는 모든 태그가 보입니다. 가상 호스트가 있는 태그는 그 가상 호스트가 있는 크롤 설정의 문서에만 붙습니다. 자세한 내용은 :doc:`../admin/tagtype-guide` 와 :doc:`../api/api-tag` 를 참조하십시오. diff --git a/ko/15.10/config/setup-memory.rst b/ko/15.10/config/setup-memory.rst new file mode 100644 index 000000000..9ce0981e4 --- /dev/null +++ b/ko/15.10/config/setup-memory.rst @@ -0,0 +1,433 @@ +============ +메모리 설정 +============ + +개요 +==== + +Java 애플리케이션에서는 프로세스마다 사용할 최대 힙 메모리를 설정해야 합니다. +|Fess| 에서는 다음 3개의 컴포넌트에서 각각 메모리 설정을 수행합니다. + +- Fess 웹 애플리케이션 +- 크롤러 프로세스 +- OpenSearch + +적절한 메모리 설정을 통해 성능 향상과 안정적인 동작을 실현할 수 있습니다. + +Fess 웹 애플리케이션의 메모리 설정 +====================================== + +설정이 필요한 경우 +---------------- + +다음과 같은 경우 메모리 크기 조정을 고려하십시오. + +- ``fess.log`` 에 OutOfMemory 오류가 기록됨 +- 대량의 동시 접속을 처리해야 함 +- 관리 화면의 작업이 느리거나 타임아웃됨 + +기본 메모리 크기는 일반적인 사용에는 충분하지만, 부하가 높은 환경에서는 증량이 필요합니다. + +환경 변수를 통한 설정 +------------------ + +환경 변수 ``FESS_HEAP_SIZE`` 를 설정합니다. + +:: + + export FESS_HEAP_SIZE=2g + +단위: + +- ``m``: 메가바이트 +- ``g``: 기가바이트 + +세부 메모리 제어 +~~~~~~~~~~~~~~~~ + +``FESS_HEAP_SIZE`` 는 ``-Xms`` 와 ``-Xmx`` 를 동일한 값으로 설정합니다. 초기 힙 크기와 최대 힙 크기를 개별적으로 제어하려면 ``FESS_MIN_MEM`` 과 ``FESS_MAX_MEM`` 환경 변수를 사용하세요. + +:: + + export FESS_MIN_MEM=256m + export FESS_MAX_MEM=2g + +.. list-table:: 플랫폼별 기본 메모리 설정 + :header-rows: 1 + :widths: 30 35 35 + + * - 플랫폼 + - FESS_MIN_MEM (기본값) + - FESS_MAX_MEM (기본값) + * - Linux + - 256m + - 2g + * - Windows + - 256m + - 1g + +.. note:: + ``FESS_HEAP_SIZE`` 가 설정된 경우 ``FESS_MIN_MEM`` 과 ``FESS_MAX_MEM`` 은 무시됩니다. + +.. note:: + RPM/DEB 패키지에서는 환경 설정 파일(``/etc/sysconfig/fess`` , DEB는 ``/etc/default/fess`` )에 ``FESS_HEAP_SIZE=512m`` 이 설정되어 있습니다. 따라서 힙은 위 표의 기본값이 아니라 512m로 고정됩니다. 힙 크기를 바꾸려면 이 ``FESS_HEAP_SIZE`` 값을 변경하십시오. + +RPM/DEB 패키지의 경우 +------------------------ + +RPM 패키지로 설치한 경우 ``/etc/sysconfig/fess`` 를 편집합니다. + +:: + + FESS_HEAP_SIZE=2g + +DEB 패키지의 경우 ``/etc/default/fess`` 를 편집합니다. + +:: + + FESS_HEAP_SIZE=2g + +.. warning:: + 메모리 크기를 변경한 후에는 |Fess| 서비스를 재시작해야 합니다. + +권장 메모리 크기 +---------------- + +.. list-table:: + :header-rows: 1 + :widths: 30 30 40 + + * - 환경 + - 권장 힙 크기 + - 비고 + * - 개발/테스트 환경 + - 512m〜1g + - 소규모 인덱스 + * - 소규모 운영 환경 + - 1g〜2g + - 수만〜수십만 문서 + * - 중규모 운영 환경 + - 2g〜4g + - 수십만〜수백만 문서 + * - 대규모 운영 환경 + - 4g〜8g + - 수백만 이상의 문서 + +크롤러의 메모리 설정 +====================== + +설정이 필요한 경우 +---------------- + +다음과 같은 경우 크롤러의 메모리 크기를 늘려야 합니다. + +- 병렬 크롤 수를 늘리는 경우 +- 큰 파일을 크롤링하는 경우 +- 크롤 실행 중 OutOfMemory 오류가 발생하는 경우 + +설정 방법 +-------- + +``app/WEB-INF/classes/fess_config.properties`` 또는 ``/etc/fess/fess_config.properties`` 를 편집합니다. + +``jvm.crawler.options`` 는 크롤러 프로세스의 JVM 옵션을 줄바꿈(``\n``)으로 구분하여 나열한 하나의 설정값입니다. 값을 바꾸면 기본 옵션이 모두 교체되므로, ``-Xmx512m`` 만 쓰면 ``-Dfile.encoding=UTF-8`` 이나 G1GC 지정 등 다른 기본 옵션도 사라집니다. ``fess_config.properties`` 에 기재된 기본값을 그대로 두고 힙 크기 줄만 변경하십시오. + +예를 들어 최대 힙을 1GB로 변경하려면 기본값의 ``-Xmx512m`` 줄을 다음과 같이 바꿉니다. + +:: + + -Xms128m\n\ + -Xmx1g\n\ + +.. note:: + 이 설정은 크롤러 프로세스 단위(스케줄러의 작업 단위)로 적용됩니다. + 여러 크롤 작업을 동시에 실행하는 경우 각 작업에서 지정한 메모리가 사용됩니다. + +권장 설정 +-------- + +- **일반 웹 크롤링**: 512m〜1g +- **대량 병렬 크롤링**: 1g〜2g +- **큰 파일 크롤링**: 2g〜4g + +상세 JVM 옵션 +------------------ + +크롤러의 상세 JVM 옵션은 ``jvm.crawler.options`` 에서 설정할 수 있습니다. +기본 설정에는 다음과 같은 최적화가 포함되어 있습니다. + +**주요 옵션:** + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - 옵션 + - 설명 + * - ``-Xms128m -Xmx512m`` + - 초기 힙 크기와 최대 힙 크기 + * - ``-XX:MaxMetaspaceSize=128m`` + - Metaspace의 최대 크기 + * - ``-XX:+UseG1GC`` + - G1 가비지 컬렉터 사용 + * - ``-XX:MaxGCPauseMillis=60000`` + - 최대 GC 일시 정지 목표 시간(60초). 크롤러 워크로드에 대한 완화된 설정(일반 애플리케이션에서는 약 200ms가 일반적) + * - ``-XX:-HeapDumpOnOutOfMemoryError`` + - OutOfMemory 시 힙 덤프 비활성화 + +OpenSearch의 메모리 설정 +======================= + +중요 고려 사항 +-------------- + +OpenSearch에서는 다음 2가지를 고려하여 메모리를 설정해야 합니다. + +1. **Java 힙 메모리**: OpenSearch 프로세스에서 사용 +2. **OS 파일 시스템 캐시**: 검색 성능에 중요 + +.. warning:: + Java 힙 메모리를 너무 크게 하면 OS 파일 시스템 캐시에 + 사용할 수 있는 메모리가 감소하여 검색 성능이 저하됩니다. + +설정 방법 +-------- + +Linux 환경 +~~~~~~~~~ + +OpenSearch의 힙 메모리는 ``config/jvm.options`` 파일에서 지정하는 것을 권장합니다. + +:: + + -Xms2g + -Xmx2g + +.. note:: + 최소 힙 크기(``-Xms``)와 최대 힙 크기(``-Xmx``)는 동일한 값으로 설정하는 것을 권장합니다. + +.. note:: + ``OPENSEARCH_HEAP_SIZE`` 환경 변수는 더 이상 권장되지 않습니다. 대신 ``config/jvm.options`` 를 사용하십시오. 환경 변수로 설정해야 하는 경우 ``OPENSEARCH_JAVA_OPTS="-Xms2g -Xmx2g"`` 를 사용하십시오. + +Windows 환경 +~~~~~~~~~~~ + +``config\jvm.options`` 파일을 편집합니다. + +:: + + -Xms2g + -Xmx2g + +권장 메모리 크기 +---------------- + +.. list-table:: + :header-rows: 1 + :widths: 30 30 40 + + * - 인덱스 크기 + - 권장 힙 크기 + - 권장 총 메모리 + * - 〜10GB + - 2g + - 4GB 이상 + * - 10GB〜50GB + - 4g + - 8GB 이상 + * - 50GB〜100GB + - 8g + - 16GB 이상 + * - 100GB 이상 + - 16g〜31g + - 32GB 이상 + +.. warning:: + OpenSearch의 힙 메모리는 32GB를 초과하지 않도록 설정하십시오. + 32GB를 초과하면 Compressed OOP가 비활성화되어 메모리 효율성이 저하됩니다. + +모범 사례 +------------------ + +1. **물리 메모리의 50%를 힙에 할당** + + 서버의 물리 메모리 약 50%를 OpenSearch의 힙에 할당합니다. + 나머지는 OS와 파일 시스템 캐시에 사용됩니다. + +2. **최대 31GB까지** + + 힙 크기는 최대 31GB까지로 하고, 그 이상 필요한 경우 노드를 추가합니다. + +3. **운영 환경에서 확인** + + OpenSearch의 공식 문서를 참조하여 환경에 맞는 최적 설정을 수행하십시오. + +제안 및 썸네일 처리의 메모리 설정 +====================================== + +제안 생성 프로세스 +---------------------- + +제안 생성 처리의 메모리 설정은 ``jvm.suggest.options`` 에서 설정합니다. + +크롤러와 마찬가지로 이 설정값에는 모든 기본 옵션이 들어 있으므로, ``-Xmx256m`` 줄만 변경하고 나머지는 그대로 두십시오. + +기본적으로 다음 설정이 사용됩니다: + +- 초기 힙: 128MB +- 최대 힙: 256MB +- Metaspace 최대: 128MB + +썸네일 생성 프로세스 +---------------------- + +썸네일 생성 처리의 메모리 설정은 ``jvm.thumbnail.options`` 에서 설정합니다. + +크롤러와 마찬가지로 이 설정값에는 모든 기본 옵션이 들어 있으므로, ``-Xmx256m`` 줄만 변경하고 나머지는 그대로 두십시오. + +기본적으로 다음 설정이 사용됩니다: + +- 초기 힙: 128MB +- 최대 힙: 256MB +- Metaspace 최대: 128MB + +.. note:: + 썸네일 생성에서 큰 이미지를 처리하는 경우 메모리를 늘려야 합니다. + +메모리 모니터링 및 튜닝 +======================== + +메모리 사용 상황 확인 +-------------------- + +Fess의 메모리 사용 상황 +~~~~~~~~~~~~~~~~~~~~~ + +관리 화면의 "시스템 정보"에서 확인할 수 있습니다. + +또는 JVM 모니터링 도구를 사용: + +:: + + jps -l # Fess 프로세스 확인 + jstat -gcutil 1000 # GC 통계를 1초마다 표시 + +OpenSearch의 메모리 사용 상황 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + curl -X GET "localhost:9200/_nodes/stats/jvm?pretty" + curl -X GET "localhost:9200/_cat/nodes?v&h=heap.percent,ram.percent" + +메모리 부족 징후 +---------------- + +다음과 같은 증상이 나타나면 메모리 부족일 가능성이 있습니다. + +**Fess 웹 애플리케이션:** + +- 응답이 느림 +- ``OutOfMemoryError`` 가 로그에 기록됨 +- 프로세스가 예기치 않게 종료됨 + +**크롤러:** + +- 크롤이 중간에 중지됨 +- ``OutOfMemoryError`` 가 ``fess-crawler.log`` 에 기록됨 +- 큰 파일의 크롤링에 실패함 + +**OpenSearch:** + +- 검색이 느림 +- 인덱스 생성이 느림 +- ``circuit_breaker_exception`` 오류가 발생함 + +튜닝 절차 +---------------- + +1. **현재 메모리 사용 상황 확인** + + 각 컴포넌트의 메모리 사용 상황을 모니터링합니다. + +2. **병목 현상 식별** + + 어떤 컴포넌트에서 메모리가 부족한지 식별합니다. + +3. **단계적으로 증가** + + 한 번에 크게 늘리지 말고 25-50%씩 늘려 효과를 확인합니다. + +4. **시스템 전체의 균형 고려** + + 각 컴포넌트의 총 메모리가 물리 메모리를 초과하지 않도록 합니다. + +5. **지속적인 모니터링** + + 메모리 사용 상황을 지속적으로 모니터링하고 필요에 따라 조정합니다. + +메모리 누수 대책 +---------------- + +메모리 누수가 의심되는 경우: + +1. **힙 덤프 획득** + +:: + + jmap -dump:format=b,file=heap.bin + +2. **힙 덤프 분석** + + Eclipse Memory Analyzer (MAT) 등의 도구로 분석합니다. + +3. **문제 보고** + + 메모리 누수를 발견한 경우 GitHub Issues에 보고해 주십시오. + +문제 해결 +====================== + +OutOfMemoryError 발생 +--------------------------- + +**Fess 웹 애플리케이션:** + +1. ``FESS_HEAP_SIZE`` 를 늘립니다. +2. 동시 접속 수를 제한합니다. +3. 로그 레벨을 낮춰 로그 출력에 의한 메모리 사용을 줄입니다. + +**크롤러:** + +1. ``jvm.crawler.options`` 의 ``-Xmx`` 를 늘립니다. +2. 병렬 크롤 수를 줄입니다. +3. 큰 파일을 제외하도록 크롤 설정을 조정합니다. + +**OpenSearch:** + +1. 힙 크기를 늘립니다(최대 31GB까지). +2. 인덱스의 샤드 수를 검토합니다. +3. 쿼리의 복잡성을 확인합니다. + +GC로 인한 중지 시간이 긴 경우 +---------------------- + +1. G1GC 설정을 조정합니다. +2. 힙 크기를 적절히 설정합니다(너무 크거나 작아도 GC가 빈번함). +3. 더 새로운 Java 버전으로 업데이트를 고려합니다. + +메모리 설정 후에도 성능이 개선되지 않음 +------------------------------ + +1. CPU, 디스크 I/O, 네트워크 등 다른 리소스를 확인합니다. +2. 인덱스 최적화를 수행합니다. +3. 쿼리나 크롤 설정을 검토합니다. + +참고 정보 +======== + +- :doc:`setup-port-network` - 포트 및 네트워크 설정 +- :doc:`crawler-advanced` - 크롤러 고급 설정 +- :doc:`admin-logging` - 로그 설정 +- `OpenSearch Memory Settings `_ +- `Java GC Tuning `_ diff --git a/ko/15.10/config/setup-port-network.rst b/ko/15.10/config/setup-port-network.rst new file mode 100644 index 000000000..3035244d6 --- /dev/null +++ b/ko/15.10/config/setup-port-network.rst @@ -0,0 +1,470 @@ +====================== +포트 및 네트워크 설정 +====================== + +개요 +==== + +본 섹션에서는 |Fess| 의 네트워크 관련 설정에 대해 설명합니다. +포트 번호 변경, 프록시 설정, HTTP 통신 설정 등 네트워크 연결에 관한 설정을 다룹니다. + +사용 포트 설정 +================ + +기본 포트 +---------------- + +|Fess| 는 기본적으로 다음 포트를 사용합니다. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 서비스 + - 포트 번호 + * - Fess 웹 애플리케이션 + - 8080 + * - OpenSearch (HTTP) + - 9200 + * - OpenSearch (Transport) + - 9300 + +Fess 웹 애플리케이션의 포트 변경 +-------------------------------------- + +Linux 환경 설정 +~~~~~~~~~~~~~~~~~ + +Linux 환경에서 포트 번호를 변경하는 경우 ``bin/fess.in.sh`` 를 편집합니다. + +:: + + FESS_JAVA_OPTS="$FESS_JAVA_OPTS -Dfess.port=8080" + +예를 들어 포트 80을 사용하는 경우: + +:: + + FESS_JAVA_OPTS="$FESS_JAVA_OPTS -Dfess.port=80" + +.. note:: + 1024 이하의 포트 번호를 사용하는 경우 root 권한 또는 적절한 권한 설정(CAP_NET_BIND_SERVICE)이 필요합니다. + +환경 변수를 통한 설정 +~~~~~~~~~~~~~~~~~~ + +환경 변수로 포트 번호를 지정할 수도 있습니다. + +:: + + export FESS_PORT=8080 + +.. warning:: + ``FESS_PORT`` 환경 변수는 Linux 환경에서만 사용할 수 있습니다. Windows 환경에서는 ``bin\fess.in.bat`` 의 ``-Dfess.port`` 를 직접 편집하세요. + +RPM/DEB 패키지의 경우 +~~~~~~~~~~~~~~~~~~~~~~~~ + +RPM 패키지에서는 ``/etc/sysconfig/fess``, DEB 패키지에서는 ``/etc/default/fess`` 를 편집합니다. + +:: + + FESS_PORT=8080 + +Windows 환경 설정 +~~~~~~~~~~~~~~~~~~~ + +Windows 환경에서는 ``bin\fess.in.bat`` 를 편집합니다. + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.port=8080 + +Windows 서비스로 등록하는 경우 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Windows 환경에서 서비스 등록하여 사용하는 경우 ``bin\service.bat`` 의 포트 설정도 변경하십시오. +자세한 내용은 :doc:`setup-windows-service` 를 참조하십시오. + +컨텍스트 경로 설정 +---------------------- + +|Fess| 를 서브디렉터리에서 공개하는 경우 컨텍스트 경로를 설정할 수 있습니다. + +Linux 환경: + +:: + + FESS_JAVA_OPTS="$FESS_JAVA_OPTS -Dfess.context.path=/search" + +Windows 환경: + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.context.path=/search + +이 설정으로 ``http://localhost:8080/search/`` 에서 접근할 수 있게 됩니다. + +Linux 환경에서는 환경 변수 ``FESS_CONTEXT_PATH`` 를 사용할 수도 있습니다. + +:: + + export FESS_CONTEXT_PATH=/search + +.. warning:: + ``FESS_CONTEXT_PATH`` 환경 변수는 Linux 환경에서만 사용할 수 있습니다. Windows 환경에서는 ``FESS_JAVA_OPTS`` 에서 ``-Dfess.context.path`` 를 직접 설정하세요. + +.. warning:: + 컨텍스트 경로를 변경한 경우 정적 파일의 경로도 적절히 설정해야 합니다. + +프록시 설정 +============ + +개요 +---- + +인트라넷 내부에서 외부 사이트를 크롤링하거나 외부 API에 접근하는 경우, +방화벽에 의해 통신이 차단될 수 있습니다. +이러한 환경에서는 프록시 서버를 경유하여 통신하도록 설정해야 합니다. + +크롤러용 프록시 설정 +-------------------------- + +기본 설정 +~~~~~~~~ + +관리 화면의 크롤 설정에서 설정 파라미터에 다음과 같이 지정합니다. + +:: + + client.proxyHost=proxy.example.com + client.proxyPort=8080 + +인증이 필요한 프록시 설정 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +프록시 서버에서 인증이 필요한 경우 다음과 같이 추가합니다. + +:: + + client.proxyHost=proxy.example.com + client.proxyPort=8080 + client.proxyUsername=proxyuser + client.proxyPassword=proxypass + +특정 호스트를 프록시에서 제외 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +크롤러의 프록시 설정에서는 특정 호스트의 제외(nonProxyHosts)는 지원되지 않습니다. +특정 호스트를 프록시에서 제외하는 경우 환경 변수 ``FESS_NON_PROXY_HOSTS`` 를 사용하십시오. +이 설정은 Java 시스템 속성 ``http.nonProxyHosts`` 로 변환되어 Fess 전체의 HTTP 통신에 적용됩니다. + +:: + + FESS_NON_PROXY_HOSTS=localhost|*.local|192.168.* + +크롤러의 기본 프록시 설정 +------------------------------ + +크롤 설정에서 개별적으로 ``client.proxyHost`` 를 지정하지 않은 경우의 기본 프록시를 ``fess_config.properties`` 에서 설정할 수 있습니다. +이 설정은 크롤러의 기본 프록시뿐만 아니라 LLM 연동의 HTTP 통신과 플러그인 다운로드에도 적용됩니다. 다만 SSO 인증 등 일부 Java 라이브러리의 통신에는 적용되지 않습니다. +SSO 인증을 포함한 Fess 애플리케이션 전체에 프록시를 적용하려면 아래에서 설명하는 환경 변수(``FESS_PROXY_HOST`` 등)를 사용하십시오. + +:: + + http.proxy.host=proxy.example.com + http.proxy.port=8080 + http.proxy.username=proxyuser + http.proxy.password=proxypass + +.. warning:: + 비밀번호는 암호화되지 않고 저장됩니다. 적절한 파일 권한을 설정하십시오. + +.. note:: + ``http.proxy.*`` 설정은 SSO 인증 등에는 적용되지 않습니다. SSO 인증을 포함한 Fess 애플리케이션 전체(JVM 전체의 HTTP 통신)에 프록시를 사용하려면 환경 변수 ``FESS_PROXY_HOST``, ``FESS_PROXY_PORT`` 를 설정하십시오. 자세한 내용은 아래의 '환경 변수를 통한 프록시 설정'을 참조하십시오. + +환경 변수를 통한 프록시 설정 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +SSO 인증과 같은 Java 라이브러리가 프록시를 사용해야 하는 경우 환경 변수를 통해 구성해야 합니다. +이러한 환경 변수는 Java 시스템 속성(``http.proxyHost``, ``https.proxyHost`` 등)으로 변환됩니다. + +:: + + FESS_PROXY_HOST=proxy.example.com + FESS_PROXY_PORT=8080 + FESS_NON_PROXY_HOSTS=localhost|*.local|192.168.* + +RPM 패키지의 경우 ``/etc/sysconfig/fess`` 에서 구성합니다. DEB 패키지의 경우 ``/etc/default/fess`` 에서 구성합니다. + +.. note:: + ``fess_config.properties`` 의 ``http.proxy.*`` 설정은 크롤러의 기본 프록시뿐만 아니라 LLM 연동과 플러그인 다운로드에도 사용됩니다. + SSO 인증을 포함한 Fess 애플리케이션 전체(JVM 전체의 HTTP 통신)에 프록시를 사용하려면 위의 환경 변수를 설정하십시오. + +HTTP 통신 설정 +============ + +파일 업로드 제한 +-------------------------- + +관리 화면에서의 파일 업로드 크기를 제한할 수 있습니다. + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - 설정 항목 + - 설명 + * - ``http.fileupload.max.size`` + - 최대 파일 업로드 크기(기본값: 262144000바이트 = 250MB) + * - ``http.fileupload.threshold.size`` + - 메모리에 보관할 임계값 크기(기본값: 262144바이트 = 256KB) + * - ``http.fileupload.max.file.count`` + - 한 번에 업로드 가능한 파일 수(기본값: 10) + +``fess_config.properties`` 에서의 설정 예: + +:: + + http.fileupload.max.size=524288000 + http.fileupload.threshold.size=524288 + http.fileupload.max.file.count=20 + +OpenSearch 연결 설정 +---------------------- + +OpenSearch 연결 URL과 상태 확인(하트비트) 간격을 설정할 수 있습니다. + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - 설정 항목 + - 설명 + * - ``search_engine.http.url`` + - OpenSearch의 URL(기본값: http://localhost:9200). 환경 변수 ``SEARCH_ENGINE_HTTP_URL`` 이 우선합니다(아래 참조). + * - ``search_engine.heartbeat_interval`` + - 헬스체크 간격(밀리초, 기본값: 10000) + +OpenSearch 연결 대상 변경 +---------------------- + +연결 대상 URL 은 환경 변수 ``SEARCH_ENGINE_HTTP_URL`` 로 지정합니다. 이 환경 변수는 +``fess_config.properties`` 의 ``search_engine.http.url`` 보다 우선합니다. ZIP 버전의 +``bin/fess.in.sh`` 와 RPM/DEB 버전의 환경 설정 파일은 이 환경 변수를 기본적으로 +``http://localhost:9200`` 으로 설정하므로, ``search_engine.http.url`` 을 변경해도 연결 +대상은 바뀌지 않습니다. + +설정하는 위치는 설치 방법에 따라 다릅니다. + +- ZIP 버전: ``bin/fess.in.sh`` 의 ``SEARCH_ENGINE_HTTP_URL`` 행을 편집하거나, |Fess| 를 + 시작하는 환경에서 ``SEARCH_ENGINE_HTTP_URL`` 을 export 합니다 + (:doc:`../install/install-linux` 참조). +- RPM/DEB 버전: ``/etc/sysconfig/fess`` (RPM) 또는 ``/etc/default/fess`` (DEB)의 + ``SEARCH_ENGINE_HTTP_URL`` +- Docker: 컨테이너의 환경 변수 ``SEARCH_ENGINE_HTTP_URL`` + (:doc:`../install/install-docker` 참조) +- Windows 의 ZIP 버전: ``bin\fess.in.bat`` 의 ``-Dfess.search_engine.http_address`` 행 + (:doc:`../install/install-windows` 참조) + +:: + + SEARCH_ENGINE_HTTP_URL=http://opensearch-cluster.example.com:9200 + +여러 노드에 연결 +~~~~~~~~~~~~~~~~~~ + +여러 OpenSearch 노드에 연결하는 경우 URL 을 쉼표로 구분하여 지정합니다. 일부 노드가 +중지되어 있어도 |Fess| 는 나머지 노드에 연결합니다. + +:: + + SEARCH_ENGINE_HTTP_URL=http://node1:9200,http://node2:9200,http://node3:9200 + +SSL/TLS 연결 설정 +----------------- + +OpenSearch 에 HTTPS 로 연결하는 경우, 위와 같은 방법으로 ``https://`` URL 을 지정합니다. + +:: + + SEARCH_ENGINE_HTTP_URL=https://opensearch.example.com:9200 + +CA 인증서와 인증 정보는 ``fess_config.properties`` 에 설정합니다. + +:: + + search_engine.http.ssl.certificate_authorities=/path/to/ca.crt + search_engine.username=admin + search_engine.password=admin_password + +.. note:: + 인증서 검증을 수행하는 경우 ``certificate_authorities`` 에 CA 인증서 경로를 지정합니다. + +가상 호스트 설정 +============== + +개요 +---- + +|Fess| 에 접근한 호스트명에 따라 검색 결과를 구분할 수 있습니다. +자세한 내용은 :doc:`security-virtual-host` 를 참조하십시오. + +기본 설정 +-------- + +가상 호스트는 관리 화면의 '시스템 > 일반'(``virtual.host.headers``)에서 설정합니다. +한 줄에 하나씩 ``Host:호스트명[:포트번호]=가상호스트명`` 형식으로 지정합니다. +기본값은 비어 있으며(미설정) 가상 호스트 기능은 비활성화되어 있습니다. + +:: + + Host:search1.example.com=site1 + Host:search2.example.com=site2 + +.. note:: + ``virtual.host.headers`` 의 값은 ``X-Forwarded-Host,Host`` 와 같은 헤더 이름 목록이 아닙니다. + 각 줄은 ``헤더명:헤더값=가상호스트명`` 형식의 매핑을 기술합니다. + 자세한 형식과 제약은 :doc:`security-virtual-host` 를 참조하십시오. + +리버스 프록시와의 연계 +======================== + +Nginx 설정 예 +-------------- + +:: + + server { + listen 80; + server_name search.example.com; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Host $host; + } + } + +Apache 설정 예 +--------------- + +:: + + + ServerName search.example.com + + ProxyPreserveHost On + ProxyPass / http://localhost:8080/ + ProxyPassReverse / http://localhost:8080/ + + RequestHeader set X-Forwarded-Proto "http" + RequestHeader set X-Forwarded-Host "search.example.com" + + +SSL/TLS 종단 +----------- + +리버스 프록시에서 SSL/TLS 종단을 수행하는 경우의 설정 예(Nginx): + +:: + + server { + listen 443 ssl http2; + server_name search.example.com; + + ssl_certificate /path/to/cert.pem; + ssl_certificate_key /path/to/key.pem; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto https; + proxy_set_header X-Forwarded-Host $host; + } + } + +방화벽 설정 +==================== + +필요한 포트 개방 +------------------ + +|Fess| 를 외부에서 접근 가능하게 하는 경우 다음 포트를 개방합니다. + +**iptables 설정 예:** + +:: + + # Fess 웹 애플리케이션 + iptables -A INPUT -p tcp --dport 8080 -j ACCEPT + + # HTTPS로 접근하는 경우(리버스 프록시 경유) + iptables -A INPUT -p tcp --dport 443 -j ACCEPT + +**firewalld 설정 예:** + +:: + + # Fess 웹 애플리케이션 + firewall-cmd --permanent --add-port=8080/tcp + firewall-cmd --reload + +보안 그룹 설정(클라우드 환경) +------------------------------------------ + +AWS, GCP, Azure 등의 클라우드 환경에서는 보안 그룹이나 네트워크 ACL에서 +적절한 포트를 개방하십시오. + +권장 설정: +- 인바운드: 80/443 포트(HTTP 리버스 프록시 경유) +- 8080 포트는 내부에서만 접근 가능하도록 제한 +- OpenSearch의 9200/9300 포트는 내부에서만 접근 가능하도록 제한 + +문제 해결 +====================== + +포트 변경 후 접근할 수 없음 +------------------------------ + +1. |Fess| 를 재시작했는지 확인하십시오. +2. 방화벽에서 해당 포트가 개방되어 있는지 확인하십시오. +3. 로그 파일(``fess.log``)에서 오류를 확인하십시오. + +프록시를 경유하여 크롤링할 수 없음 +------------------------------ + +1. 프록시 서버의 호스트명과 포트가 올바른지 확인하십시오. +2. 프록시 서버에서 인증이 필요한 경우 사용자명과 비밀번호를 설정하십시오. +3. 프록시 서버의 로그에서 연결 시도가 기록되어 있는지 확인하십시오. +4. ``nonProxyHosts`` 설정이 적절한지 확인하십시오. + +OpenSearch에 연결할 수 없음 +------------------------- + +1. OpenSearch가 시작되어 있는지 확인하십시오. +2. ``search_engine.http.url`` 설정이 올바른지 확인하십시오. +3. 네트워크 연결을 확인하십시오: ``curl http://localhost:9200`` +4. OpenSearch의 로그에서 오류를 확인하십시오. + +리버스 프록시를 경유하여 접근하면 정상 작동하지 않음 +---------------------------------------------------- + +1. ``X-Forwarded-Host`` 헤더가 올바르게 설정되어 있는지 확인하십시오. +2. ``X-Forwarded-Proto`` 헤더가 올바르게 설정되어 있는지 확인하십시오. +3. 컨텍스트 경로가 올바르게 설정되어 있는지 확인하십시오. +4. 리버스 프록시의 로그에서 오류를 확인하십시오. + +참고 정보 +======== + +- :doc:`setup-memory` - 메모리 설정 +- :doc:`setup-windows-service` - Windows 서비스 설정 +- :doc:`security-virtual-host` - 가상 호스트 설정 +- :doc:`crawler-advanced` - 크롤러 고급 설정 +- `OpenSearch Configuration `_ diff --git a/ko/15.10/config/setup-windows-service.rst b/ko/15.10/config/setup-windows-service.rst new file mode 100644 index 000000000..59f9c993a --- /dev/null +++ b/ko/15.10/config/setup-windows-service.rst @@ -0,0 +1,134 @@ +========================== +Windows 서비스 등록 +========================== + +Windows 서비스로 등록 +====================== + +|Fess| 를 Windows 서비스로 등록할 수 있습니다. 서비스로 등록하면 시스템 시작 시 |Fess| 를 자동으로 시작할 수 있습니다. +|Fess| 를 실행하려면 OpenSearch를 미리 시작해 두어야 합니다. +여기서는 |Fess| 를 ``c:\opt\fess`` 에, OpenSearch를 ``c:\opt\opensearch`` 에 설치했다고 가정합니다（경로는 환경에 맞게 읽어 주십시오）. + +.. note:: + |Fess| 및 OpenSearch는 64비트 버전만 지원합니다. + +사전 준비 +--------- + +시스템 환경 변수로 ``JAVA_HOME`` 을 설정하십시오. ``service.bat`` 는 ``JAVA_HOME`` 이 설정되어 있지 않으면 오류로 종료됩니다. + +OpenSearch를 서비스로 등록 +-------------------------- + +명령 프롬프트를 관리자 권한으로 시작하고 ``c:\opt\opensearch\bin\opensearch-service.bat`` 를 실행합니다. + +:: + + > cd c:\opt\opensearch\bin + > opensearch-service.bat install + ... + The service 'opensearch-service-x64' has been installed. + +자세한 내용은 `OpenSearch 문서 `_ 를 참조하십시오. + +|Fess| 설정 +----------- + +서비스는 ``c:\opt\fess\bin\service.bat`` 에서 등록합니다. ``service.bat`` 는 등록 시 ``bin\fess.in.bat`` 를 읽어 그 내용을 |Fess| 의 시작 옵션에 반영합니다. +OpenSearch에 연결하기 위한 설정을 ``c:\opt\fess\bin\fess.in.bat`` 에 추가하십시오. + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200 + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=c:/opt/opensearch/config/dictionary/ + +.. note:: + - ``fess.search_engine.http_address`` 에는 등록한 OpenSearch 서비스의 연결 대상을 지정합니다. 이 설정을 하지 않으면 |Fess| 는 연결 대상을 찾지 못해 시작되지 않으며, 검색 엔진 주소가 설정되어 있지 않다는 내용을 보고합니다. + - OpenSearch를 다른 호스트에서 실행하는 경우 호스트명 또는 IP 주소를 적절히 변경하십시오. + - 경로 구분 문자는 ``/`` 를 사용하십시오. + +|Fess| 의 검색 화면·관리 화면의 기본 포트 번호는 ``8080`` 입니다. 다른 포트로 변경하는 경우 ``c:\opt\fess\bin\fess.in.bat`` 의 ``-Dfess.port`` 를 편집합니다. + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.port=80 + +.. note:: + 서비스로 등록하는 경우 ``bin\service.bat`` 의 ``FESS_PARAMS`` 에 ``-Dfess.port=8080`` 이 하드코딩되어 있습니다. 이 값은 ``fess.in.bat`` 의 설정보다 우선되므로 포트를 변경할 때는 ``service.bat`` 의 ``FESS_PARAMS`` 도 함께 편집하십시오. + +서비스 커스터마이즈（선택） +---------------------------- + +``service.bat install`` 을 실행하기 전에 환경 변수를 설정하면 서비스 구성을 변경할 수 있습니다. 주요 환경 변수는 다음과 같습니다. + +.. list-table:: + :header-rows: 1 + + * - 환경 변수 + - 설명 + * - ``FESS_START_TYPE`` + - 시작 유형（``auto`` 또는 ``manual``）. 기본값은 ``manual`` 입니다. + * - ``FESS_HEAP_SIZE`` + - 힙 크기（예: ``1g``）. 최소·최대 힙 크기를 개별로 지정하는 경우 ``FESS_MIN_MEM``\ （기본값 ``256m``）과 ``FESS_MAX_MEM``\ （기본값 ``1g``）을 사용합니다. + * - ``SERVICE_USERNAME`` / ``SERVICE_PASSWORD`` + - 서비스를 실행할 Windows 계정. + * - ``SERVICE_DISPLAY_NAME`` + - 서비스 표시 이름. + * - ``SERVICE_DESCRIPTION`` + - 서비스 설명. + +등록 방법 +--------- + +관리자 권한의 명령 프롬프트에서 ``c:\opt\fess\bin\service.bat`` 를 실행합니다. + +:: + + > cd c:\opt\fess\bin + > service.bat install + ... + The service 'fess-service-x64' has been installed. + +서비스 설정 +----------- + +서비스를 수동으로 시작하는 경우 OpenSearch 서비스를 먼저 시작하고, 그 후 |Fess| 서비스를 시작합니다. +시스템 시작 시 자동으로 시작하는 경우 시작 유형과 의존 관계를 설정합니다. + +1. 서비스의 일반 설정에서 시작 유형을 "자동(지연된 시작)"으로 설정합니다. +2. 서비스의 의존 관계는 레지스트리에서 설정합니다. + +레지스트리 편집기(regedit)에서 다음 키와 값을 추가합니다. + +.. list-table:: + + * - *키* + - ``Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\fess-service-x64\DependOnService`` + * - *값* + - ``opensearch-service-x64`` + +추가하면 |Fess| 서비스의 속성 의존 관계에 opensearch-service-x64가 표시됩니다. + +.. note:: + ``service.bat install`` 전에 환경 변수 ``FESS_START_TYPE=auto`` 를 설정해 두면 시작 유형을 "자동"으로 등록할 수 있습니다. 다만 "자동(지연된 시작)"이나 의존 관계 설정은 ``service.bat`` 에서는 수행할 수 없으므로 위의 절차로 설정하십시오. + +서비스 관리 +----------- + +``service.bat`` 에서 다음 명령으로 서비스를 조작할 수 있습니다. + +.. list-table:: + :header-rows: 1 + + * - 명령 + - 설명 + * - ``service.bat install`` + - 서비스를 등록합니다. + * - ``service.bat remove`` + - 서비스를 삭제합니다. + * - ``service.bat start`` + - 서비스를 시작합니다. + * - ``service.bat stop`` + - 서비스를 정지합니다. + * - ``service.bat manager`` + - 서비스 관리용 GUI를 시작합니다. diff --git a/ko/15.10/config/sso-entraid.rst b/ko/15.10/config/sso-entraid.rst new file mode 100644 index 000000000..c64c184a5 --- /dev/null +++ b/ko/15.10/config/sso-entraid.rst @@ -0,0 +1,394 @@ +===================================== +Microsoft Entra ID를 이용한 SSO 설정 +===================================== + +개요 +==== + +|Fess| 에서는 Microsoft Entra ID（구 Azure AD）를 사용한 싱글 사인온（SSO）인증을 지원합니다. +Entra ID 인증을 사용하면 Microsoft 365 환경의 사용자 정보 및 그룹 정보를 |Fess| 의 역할 기반 검색과 연동할 수 있습니다. + +.. note:: + Entra ID 인증 지원은 ``fess-sso-entraid`` 플러그인에서 제공됩니다. 배포물에 포함되어 + 있지 않으므로 관리 화면의 「시스템 > 플러그인」 페이지 또는 + ``bin/fess-setup install plugin fess-sso-entraid`` 로 설치하십시오. + 설치하기 전에는 ``sso.type=entraid`` (이전 이름 ``aad`` 포함) 설정만으로는 ``/sso/`` 요청이 + 로그인 페이지로 리디렉션될 뿐입니다. + +Entra ID 인증의 동작 방식 +-------------------------- + +Entra ID 인증에서는 |Fess| 가 OAuth 2.0/OpenID Connect의 클라이언트로 동작하여 Microsoft Entra ID와 연동하여 인증을 수행합니다. + +1. 사용자가 |Fess| 의 SSO 엔드포인트（``/sso/``）에 접근 +2. |Fess| 가 Entra ID의 인가 엔드포인트로 리다이렉트 +3. 사용자가 Entra ID에서 인증（Microsoft 로그인） +4. Entra ID가 인가 코드를 |Fess| 로 리다이렉트 +5. |Fess| 가 인가 코드를 사용하여 액세스 토큰을 취득 +6. 사용자가 로그인 +7. 백그라운드에서 |Fess| 가 Microsoft Graph API를 사용하여 사용자의 그룹 및 역할 정보를 취득하고, 완료되면 역할 기반 검색에 적용 + +.. note:: + |Fess| 15.10 이상에서는 인가 엔드포인트에 ``response_mode=query`` 를 요청하므로, 4번의 인가 + 응답은 GET으로 반환됩니다. 15.7 이전에는 크로스 사이트 POST로 반환되었고, |Fess| 의 기본값인 + ``tomcat.sameSiteCookies = lax`` 에서는 세션 쿠키가 전송되지 않기 때문에 + ``tomcat.sameSiteCookies = none`` 으로 변경하는 우회 방법이 필요했습니다. + 이 우회 방법을 위해서만 ``none`` 을 설정했다면 기본값으로 되돌릴 수 있습니다. + +역할 기반 검색과의 연동에 대해서는 :doc:`security-role` 을 참조하십시오. + +전제조건 +======== + +Entra ID 인증을 설정하기 전에 다음 전제조건을 확인하십시오. + +- |Fess| 15.10 이상이 설치되어 있을 것 +- Microsoft Entra ID（Azure AD）테넌트를 사용할 수 있을 것 +- |Fess| 가 HTTPS로 접근 가능할 것（운영 환경에서는 필수） +- Entra ID 측에서 애플리케이션을 등록할 수 있는 권한이 있을 것 + +기본 설정 +========= + +SSO 기능 활성화 +--------------- + +Entra ID 인증을 활성화하려면 ``app/WEB-INF/conf/system.properties`` 에 다음 설정을 추가합니다. + +:: + + sso.type=entraid + +필수 설정 +--------- + +Entra ID에서 취득한 정보를 설정합니다. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 프로퍼티 + - 설명 + - 기본값 + * - ``entraid.tenant`` + - 테넌트 ID（예: ``xxx.onmicrosoft.com``） + - （필수） + * - ``entraid.client.id`` + - 애플리케이션（클라이언트）ID + - （필수） + * - ``entraid.client.secret`` + - 클라이언트 시크릿 값 + - （필수） + * - ``entraid.reply.url`` + - 리다이렉트 URI（콜백 URL） + - 요청 URL을 사용 + +.. note:: + ``entraid.*`` 프리픽스 대신 레거시 ``aad.*`` 프리픽스도 사용할 수 있습니다（하위 호환성）. + +옵션 설정 +-------------- + +필요에 따라 다음 설정을 추가할 수 있습니다. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 프로퍼티 + - 설명 + - 기본값 + * - ``entraid.authority`` + - 인증 서버 URL + - ``https://login.microsoftonline.com/`` + * - ``entraid.state.ttl`` + - State 유효 기간（초） + - ``3600`` + * - ``entraid.response.mode`` + - 인가 응답을 받는 방식. ``query`` 또는 ``form_post`` 를 지정합니다. + - ``query`` + * - ``entraid.default.groups`` + - 기본 그룹（쉼표 구분）. 모든 Entra ID 사용자에게 적용됩니다. + - （없음） + * - ``entraid.default.roles`` + - 기본 역할（쉼표 구분）. 모든 Entra ID 사용자에게 적용됩니다. + - （없음） + * - ``entraid.permission.fields`` + - 권한 값으로 추가로 사용할 그룹/역할 필드（쉼표 구분）. 그룹/역할의 ID（GUID）는 항상 권한으로 사용되며, 여기서 지정한 필드（예: ``mail``）의 값이 추가됩니다. 지정할 수 있는 것은 값이 문자열인 필드뿐입니다. ``securityEnabled`` 는 불리언, ``groupTypes`` 는 배열로 Microsoft Graph에서 반환되므로 권한 값으로 사용할 수 없으며, 이러한 필드를 지정한 경우에는 무시되고 해당 필드 이름을 알리는 경고가 로그에 출력됩니다. + - ``mail`` + * - ``entraid.use.ds`` + - 도메인 서비스 연동. ``true`` 인 경우, ``name@domain`` 형식의 권한 값에서 도메인 부분을 제거한 로컬 부분（``name``）도 권한으로 추가합니다. 이는 그룹·역할뿐만 아니라 로그인한 사용자 본인에게도 적용되어, 사용자 주체 이름（UPN）의 로컬 부분이 사용자 수준 권한으로 추가됩니다. 따라서 ``false`` 로 설정하면 그룹의 권한뿐만 아니라 이 사용자 수준 권한도 추가되지 않습니다. + - ``true`` + +.. note:: + + 그룹/역할의 ID（GUID）는 항상 권한으로 사용되지만, ``mail`` 값을 가지는 것은 메일이 활성화된 + 그룹뿐입니다. Microsoft 365 그룹은 메일이 활성화되어 있으므로 그룹 이름도 권한으로 등록됩니다. + 반면 **보안 그룹은 메일이 활성화되어 있지 않아, 기본값 그대로면 GUID만 권한이 됩니다**. + 파일 시스템의 액세스 권한을 보안 그룹 이름으로 지정한 경우 권한이 일치하지 않아 검색 결과에 + 나타나지 않습니다. + + 이 경우 모든 그룹이 가지고 있는 ``displayName`` 을 추가하십시오. + + .. code-block:: properties + + entraid.permission.fields=mail,displayName + + ``displayName`` 은 도메인으로 한정되지 않고 고유하지도 않기 때문에 기본값에 포함되어 있지 + 않습니다. 예를 들어 Entra ID에 ``Administrators`` 라는 이름의 그룹이 있으면, Windows 기본 제공 + 그룹 ``Administrators`` 를 지정한 문서에도 일치합니다. 추가하기 전에 기존 액세스 권한에서 + 사용 중인 이름과 충돌하지 않는지 확인하십시오. + +.. note:: + 기본값인 ``query`` 에서는 인가 코드가 콜백 URL의 쿼리 문자열에 포함됩니다. + ``form_post`` 를 지정하면 인가 코드가 URL에 나타나지 않으므로 브라우저 기록이나 프런트엔드 + 프록시・WAF의 액세스 로그에도 남지 않습니다. 다만 ``form_post`` 는 콜백이 크로스 사이트 + POST가 되므로 ``tomcat.sameSiteCookies = none`` 이 필요합니다. 설정하지 않으면 세션 쿠키가 + 전송되지 않아 로그인에 실패합니다. 또한 브라우저는 ``Secure`` 속성이 함께 있는 쿠키에 대해서만 + ``none`` 을 허용하므로, ``form_post`` 를 사용하려면 |Fess| 를 HTTPS로 제공해야 합니다. + 일반 HTTP에서는 ``none`` 을 설정해도 브라우저가 세션 쿠키 자체를 저장하지 않아 역시 로그인할 수 + 없습니다. 따라서 대부분의 환경에서는 기본값 그대로 사용하십시오. + 그 외의 값을 지정한 경우에는 경고를 출력하고 ``query`` 로 처리합니다. + +.. warning:: + + ``entraid.default.groups`` 와 ``entraid.default.roles`` 는 사용자별로 구분할 수 없는 단일 + 전역 설정입니다. |Fess| 는 로그인 시 모든 Entra ID 사용자에게 이를 적용하고 이후의 해결 + 때마다 다시 적용하므로, Microsoft Graph의 결과로 회수되는 일은 없습니다. 특히 |Fess| 의 + 관리자 역할（기본 제공 ``authentication.admin.roles`` 에서는 ``admin``）을 + ``entraid.default.roles`` 에 설정해서는 안 됩니다. 테넌트의 모든 사용자에게 관리 화면에 대한 + 영구적인 접근 권한을 부여하게 됩니다. + +Entra ID 측 설정 +================== + +Azure Portal에서의 앱 등록 +-------------------------- + +1. `Azure Portal `_ 에 로그인 + +2. **Microsoft Entra ID** 를 선택 + +3. 왼쪽 메뉴의 **관리** → **앱 등록** → **새 등록** 을 클릭 + +4. 애플리케이션을 등록: + + .. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 설정 항목 + - 설정값 + * - 이름 + - 임의의 이름（예: Fess SSO） + * - 지원되는 계정 유형 + - 「이 조직 디렉터리의 계정만」 + * - 플랫폼 선택 + - Web + * - 리다이렉트 URI + - ``https:///sso/`` + +5. **등록** 을 클릭 + +클라이언트 시크릿 생성 +------------------------------ + +1. 앱 세부 정보 페이지에서 **인증서 및 비밀** 을 클릭 + +2. **새 클라이언트 비밀** 을 클릭 + +3. 설명과 만료 기간을 설정하고 **추가** 를 클릭 + +4. 생성된 **값** 을 복사하여 저장（이 값은 다시 표시되지 않습니다） + +.. warning:: + 클라이언트 시크릿 값은 생성 직후에만 표시됩니다. + 다른 화면으로 이동하기 전에 반드시 기록해 두십시오. + +API 접근 권한 설정 +--------------------- + +1. 왼쪽 메뉴의 **API 권한** 을 클릭 + +2. **권한 추가** 를 클릭 + +3. **Microsoft Graph** 를 선택 + +4. **위임된 권한** 을 선택 + +5. 다음 접근 권한을 추가: + + - ``User.Read`` - 로그인한 사용자의 소속 그룹（``/me/memberOf``）을 취득하기 위해 필요. 앱 등록 생성 시 기본으로 부여됩니다 + - ``GroupMember.Read.All`` - 그룹 이름 등 그룹 속성의 취득과 중첩된 그룹의 해결에 필요 + +6. **권한 추가** 를 클릭 + +7. **「<테넌트 이름>에 관리자 동의 부여」** 를 클릭 + +.. note:: + 관리자 동의는 테넌트 관리자 권한이 필요합니다. + +.. note:: + ``GroupMember.Read.All`` 대신 ``Group.Read.All`` 이나 ``Directory.Read.All`` 을 부여해도 + 그룹 속성의 취득과 중첩된 그룹의 해결은 동작합니다. 다만 ``/me/memberOf`` 는 + ``Group.Read.All`` 로는 인가되지 않으므로 어느 경우에도 ``User.Read`` 는 필요합니다. + +.. note:: + 위의 접근 권한으로는 디렉터리 역할의 ``displayName`` 을 Microsoft Graph가 반환하지 않습니다. + 따라서 ``entraid.permission.fields`` 에 ``displayName`` 을 지정해도 디렉터리 역할에서 + 권한이 되는 것은 역할의 ID（GUID）뿐입니다. 역할 이름을 권한 값으로 사용하려면 + ``RoleManagement.Read.Directory``\ （또는 ``Directory.Read.All``\ ）도 부여하십시오. + +.. note:: + |Fess| 는 토큰 취득 시 ``https://graph.microsoft.com/.default`` 스코프를 요청합니다. + 15.10 이상에서는 인가 엔드포인트에도 ``openid profile offline_access https://graph.microsoft.com/.default`` + 를 요청하여 동일한 범위의 동의를 요구합니다. + 이는 앱 등록에서 구성 및 동의된 모든 접근 권한이 사용됨을 의미합니다. + 따라서 그룹 정보를 취득하려면 위의 접근 권한을 앱 등록에 추가하고 + 관리자 동의를 부여해야 합니다. + +취득하는 정보 +------------- + +다음 정보를 Fess 설정에 사용합니다. + +- **애플리케이션（클라이언트）ID**: 개요 페이지의 「애플리케이션 (클라이언트) ID」 +- **테넌트 ID**: 개요 페이지의 「디렉터리 (테넌트) ID」또는 ``xxx.onmicrosoft.com`` 형식 +- **클라이언트 시크릿 값**: 인증서 및 비밀에서 생성한 값 + +그룹 및 역할 매핑 +========================== + +Entra ID 인증에서는 Microsoft Graph API를 사용하여 사용자가 소속된 그룹 및 역할을 자동으로 취득합니다. +취득한 그룹 ID 및 그룹 이름은 |Fess| 의 역할 기반 검색에 사용할 수 있습니다. + +중첩 그룹 +-------------------- + +|Fess| 는 사용자가 직접 소속된 그룹뿐만 아니라 해당 그룹이 소속된 상위 그룹（중첩 그룹）도 취득합니다. +직접 소속된 그룹의 취득과 상위 그룹의 탐색은 모두 로그인 후 동일한 백그라운드 작업으로 실행되므로, 로그인 자체가 Microsoft Graph로 인해 지연되는 일은 없습니다. +상위 그룹의 취득에는 Microsoft Graph의 ``getMemberGroups`` 를 사용합니다. 이는 추이적으로 해결되므로, 직접 소속된 그룹 1건당 1회의 호출로 그 상위에 있는 모든 상위 그룹이 계층의 깊이와 관계없이 반환됩니다. 취득 결과는 일정 시간 동안 캐시됩니다. +이 백그라운드 작업이 완료되면 사용자의 권한이 재계산됩니다. + +기본 그룹 설정 +------------------------ + +모든 Entra ID 사용자에게 공통 그룹을 부여하는 경우: + +:: + + entraid.default.groups=authenticated_users,entra_users + +설정 예 +======= + +최소 구성（검증 환경용） +------------------------ + +다음은 검증 환경에서 동작을 확인하기 위한 최소한의 설정 예입니다. + +:: + + # SSO 활성화 + sso.type=entraid + + # Entra ID 설정 + entraid.tenant=yourcompany.onmicrosoft.com + entraid.client.id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + entraid.client.secret=your-client-secret-value + entraid.reply.url=http://localhost:8080/sso/ + +권장 구성（운영 환경용） +------------------------ + +다음은 운영 환경에서 사용할 때의 권장 설정 예입니다. + +:: + + # SSO 활성화 + sso.type=entraid + + # Entra ID 설정 + entraid.tenant=yourcompany.onmicrosoft.com + entraid.client.id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + entraid.client.secret=your-client-secret-value + entraid.reply.url=https://fess.example.com/sso/ + + # 기본 그룹（옵션） + entraid.default.groups=authenticated_users + +레거시 설정（하위 호환성） +-------------------------- + +이전 버전과의 호환성을 위해 ``aad.*`` 프리픽스도 사용할 수 있습니다. +각 ``entraid.*`` 프로퍼티가 설정되지 않은 경우, 대응하는 ``aad.*`` 프로퍼티의 값이 사용됩니다. +또한 ``sso.type=aad`` 도 ``sso.type=entraid`` 와 동등하게 처리됩니다. + +:: + + # SSO 활성화（sso.type=aad 도 사용 가능） + sso.type=entraid + + # 레거시 설정 키 + aad.tenant=yourcompany.onmicrosoft.com + aad.client.id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + aad.client.secret=your-client-secret-value + aad.reply.url=https://fess.example.com/sso/ + +문제 해결 +====================== + +자주 발생하는 문제와 해결 방법 +------------------------------ + +인증 후 Fess로 돌아올 수 없음 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Azure Portal의 앱 등록에서 리다이렉트 URI가 올바르게 설정되어 있는지 확인하십시오 +- ``entraid.reply.url`` 의 값이 Azure Portal의 설정과 완전히 일치하는지 확인하십시오 +- 프로토콜（HTTP/HTTPS）이 일치하는지 확인하십시오 +- 리다이렉트 URI의 끝에 ``/`` 가 포함되어 있는지 확인하십시오 +- ``entraid.response.mode`` 에 ``form_post`` 를 지정한 경우에는 ``tomcat.sameSiteCookies = none`` + 이 설정되어 있는지, 그리고 |Fess| 를 HTTPS로 제공하고 있는지 확인하십시오. 기본값인 ``lax`` 에서는 + 콜백의 크로스 사이트 POST에 브라우저가 세션 쿠키를 전송하지 않습니다. ``none`` 을 설정하더라도 일반 + HTTP에서는 ``none`` 이 ``Secure`` 속성을 요구하기 때문에 브라우저가 해당 쿠키 자체를 저장하지 + 않습니다. 어느 경우든 그 자리에서 한 번만 로그인에 실패하며, 브라우저는 로그인 화면으로 돌아가 + "SSO 로그인 프로세스에 실패했습니다." 를 표시하고, 로그에는 + ``Failed to process SSO login: could not validate state`` 경고가 출력됩니다 + +인증 오류가 발생함 +~~~~~~~~~~~~~~~~~~~~ + +- 테넌트 ID, 클라이언트 ID, 클라이언트 시크릿이 올바르게 설정되어 있는지 확인하십시오 +- 클라이언트 시크릿의 유효 기간이 만료되지 않았는지 확인하십시오 +- API 접근 권한에 관리자 동의가 부여되어 있는지 확인하십시오 + +그룹 정보를 취득할 수 없음 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``User.Read`` 와 ``GroupMember.Read.All`` 의 접근 권한이 부여되어 있는지 확인하십시오 + （``GroupMember.Read.All`` 은 ``Group.Read.All`` 이나 ``Directory.Read.All`` 로 대체할 수 있지만, ``/me/memberOf`` 에는 ``User.Read`` 가 필요합니다） +- 관리자 동의가 부여되어 있는지 확인하십시오 +- 사용자가 Entra ID에서 그룹에 소속되어 있는지 확인하십시오 +- 중첩된 상위 그룹을 해결할 수 없는 경우에는 ``Not allowed to read the parent groups of ...`` 경고가 로그에 출력됩니다. 이 경우에는 ``GroupMember.Read.All`` 을 부여하십시오 +- |Fess| 는 로그인이 완료된 후 백그라운드에서 사용자의 그룹·역할 소속을 해결하므로, 로그인 자체가 Microsoft Graph의 응답을 기다리는 일은 없습니다. 해결이 완료될 때까지 사용자가 보유하는 것은 사용자 본인의 사용자 수준 권한과 ``entraid.default.groups`` 및 ``entraid.default.roles`` 에 설정한 그룹·역할뿐입니다. 둘 다 설정하지 않은 경우（기본 제공 설정값）, 이 시간대의 검색은 한 건도 결과가 나오지 않습니다. ``role.search.default.permissions`` 는 기본적으로 비어 있고, 기본 제공 ``role.search.default.display.permissions`` 그대로 만든 크롤 설정으로 크롤링한 문서에는 ``{role}guest`` 가 부여되지만 로그인한 사용자는 이 역할을 갖고 있지 않기 때문입니다. 이 시간대는 최대 약 1초의 스케줄링 지연에 더해 Microsoft Graph 호출 자체（직접 소속 조회 1회, 여기에 중첩 그룹을 따라가기 위해 직접 소속 그룹마다 1회씩 순차 실행. 캐시가 없는 경우）가 걸리므로, 사용자가 소속된 그룹 수에 따라 길어집니다. 그동안 검색 화면에는 그룹·역할 권한을 아직 불러오는 중이라는 사실과 잠시 후 다시 검색하라는 안내 메시지가 표시됩니다 +- 해결이 완전히 성공하지 못한 경우에는 검색 화면에 그룹·역할 권한을 모두 불러오지 못했다는 사실과, 로그아웃한 후 다시 로그인하라는 안내, 그리고 반복해서 발생하는 경우 관리자에게 문의하라는 안내 메시지가 표시됩니다. 「모두」는 의도적인 표현입니다. 직접 소속 조회와 중첩 그룹 탐색이 모두 성공하지 않는 한 해결은 실패로 처리되므로, 직접 소속 그룹은 가져왔지만 상위 그룹을 가져오지 못한 사용자에게도 이 메시지가 표시됩니다. 다만 한 가지 예외가 있으며, 그것은 앞 항목에서 설명한 상황입니다. ``GroupMember.Read.All`` 이 부여되지 않아 Microsoft Graph가 중첩 그룹 조회를 ``Authorization_RequestDenied`` 로 거부한 경우, |Fess| 는 이를 실패가 아니라 「해당 그룹에는 상위 그룹이 없다」는 응답으로 처리합니다. 이 경우 상위 그룹의 권한이 누락되었음에도 해결은 성공으로 처리되며, **이 메시지는 표시되지 않습니다**. 단서는 로그에 출력되는 ``Not allowed to read the parent groups of ...`` 경고뿐이므로, 중첩 그룹을 사용하고 있는 경우에는 이 경고가 출력되지 않았는지 확인하십시오. 부분적으로만 해결되는 주된 원인은 스로틀링입니다. Microsoft Graph가 한 번이라도 HTTP 429 또는 503을 반환하면 |Fess| 는 ``Retry-After`` 헤더가 요구하는 시간（해석할 수 있는 값이 없으면 60초, 최대 60분）만큼 대기하며, 그동안에는 직접 소속 조회가 계속 성공하더라도 |Fess| 인스턴스 전체에서 중첩 그룹 조회가 건너뛰어집니다. 다만 실패가 최종적인 것이 되지는 않습니다. 액세스 토큰이 갱신될 때마다 해결이 다시 실행되며, 그 후 성공하면 메시지는 사라지고 없던 권한도 복구됩니다. 바로 다시 시도하려면 일단 로그아웃한 후 다시 로그인하십시오（로그인한 상태로 SSO 로그인 URL을 열어도 검색 화면으로 리다이렉트될 뿐입니다） + +디버그 설정 +------------ + +문제를 조사할 때는 |Fess| 의 로그 레벨을 조정하면 Entra ID 관련 상세 로그를 출력할 수 있습니다. + +``app/WEB-INF/classes/log4j2.xml`` 에서 다음 로거를 추가하여 로그 레벨을 변경할 수 있습니다. + +:: + + + +참고 정보 +========= + +- :doc:`security-role` - 역할 기반 검색 설정에 대하여 +- :doc:`sso-saml` - SAML 인증을 이용한 SSO 설정에 대하여 +- :doc:`sso-oidc` - OpenID Connect 인증을 이용한 SSO 설정에 대하여 diff --git a/ko/15.10/config/sso-oidc.rst b/ko/15.10/config/sso-oidc.rst new file mode 100644 index 000000000..01759706e --- /dev/null +++ b/ko/15.10/config/sso-oidc.rst @@ -0,0 +1,325 @@ +===================================== +OpenID Connect를 통한 SSO 설정 +===================================== + +개요 +==== + +|Fess| 는 OpenID Connect（OIDC）를 이용한 싱글 사인온（SSO）인증을 지원합니다. +OpenID Connect는 OAuth 2.0을 기반으로 한 인증 프로토콜로, ID Token（JWT）을 사용하여 사용자 인증을 수행합니다. +OpenID Connect 인증을 사용하면 OIDC 프로바이더（OP）에서 인증된 사용자 정보를 |Fess| 에 연동할 수 있습니다. + +.. note:: + OpenID Connect 인증 지원은 ``fess-sso-oidc`` 플러그인에서 제공됩니다. 배포물에 포함되어 + 있지 않으므로 관리 화면의 「시스템 > 플러그인」 페이지 또는 + ``bin/fess-setup install plugin fess-sso-oidc`` 로 설치하십시오. 플러그인 이름은 + ``fess-sso-oidc`` 이지만 ``sso.type`` 의 값은 그대로 ``oic`` 입니다. + 설치하기 전에는 ``sso.type=oic`` 설정만으로는 ``/sso/`` 요청이 로그인 페이지로 + 리디렉션될 뿐입니다. + +OpenID Connect 인증 동작 방식 +------------------------------ + +OpenID Connect 인증에서는 |Fess| 가 Relying Party（RP）로 동작하며, 외부 OpenID 프로바이더（OP）와 연계하여 인증을 수행합니다. + +1. 사용자가 |Fess| 의 SSO 엔드포인트（``/sso/``）에 접근 +2. |Fess| 가 OP의 인가 엔드포인트로 리다이렉트 +3. 사용자가 OP에서 인증 수행 +4. OP가 인가 코드를 |Fess| 에 리다이렉트 +5. |Fess| 가 인가 코드를 사용하여 토큰 엔드포인트에서 ID Token 취득 +6. |Fess| 가 ID Token（JWT）의 클레임을 검증한 뒤 사용자 정보를 취득하고 사용자를 로그인 + +.. note:: + |Fess| 는 인가 코드 플로우（Authorization Code Flow）를 사용합니다. ID Token은 브라우저를 경유하지 않고, |Fess| 와 OP 간의 백채널（서버 간 통신）을 통해 토큰 엔드포인트에서 직접 취득됩니다. + |Fess| 는 ID Token을 디코딩하여 클레임（``email`` 이나 ``groups`` 등）을 추출하고 사용자 정보를 구성하지만, JWT 서명의 암호적 검증은 수행하지 않습니다. 토큰은 토큰 엔드포인트에서 TLS를 통해 직접 수신하므로 OpenID Connect Core는 이를 허용하며, 따라서 토큰 엔드포인트 URL（``oic.token.server.url``）은 HTTPS여야 합니다. ``http`` 는 ``localhost``, ``127.x.x.x``, ``::1`` 에서만 허용됩니다. + |Fess| 는 클레임을 다음과 같이 검증합니다. ``aud`` 에 ``oic.client.id`` 가 포함되어 있어야 하고（``azp`` 가 있으면 ``oic.client.id`` 와 일치해야 합니다）, ``exp`` 가 존재하며 만료되지 않았어야 합니다（최대 300초의 시각 차이는 허용합니다）. ``oic.issuer`` 를 설정한 경우에는 ``iss`` 가 이 값과 일치해야 합니다. ``oic.issuer`` 를 설정하지 않으면 ``iss`` 는 검증하지 않으며, 시작 후 첫 로그인 시 경고를 로그에 출력합니다. ``nonce`` 와 PKCE는 사용하지 않습니다. + +역할 기반 검색과의 연동에 대해서는 :doc:`security-role` 을 참조하십시오. + +전제조건 +======== + +OpenID Connect 인증을 설정하기 전에 다음 전제조건을 확인하십시오. + +- |Fess| 15.10 이상이 설치되어 있을 것 +- OpenID Connect 대응 프로바이더（OP）가 사용 가능할 것 +- |Fess| 가 HTTPS로 접근 가능할 것（운영 환경에서는 필수） +- OP 측에서 |Fess| 를 클라이언트（RP）로 등록할 수 있는 권한이 있을 것 + +지원 프로바이더 예: + +- Microsoft Entra ID（Azure AD） +- Google Workspace / Google Cloud Identity +- Okta +- Keycloak +- Auth0 +- 기타 OpenID Connect 대응 프로바이더 + +기본 설정 +========= + +SSO 기능 활성화 +--------------- + +OpenID Connect 인증을 활성화하려면 ``app/WEB-INF/conf/system.properties`` 에 다음 설정을 추가합니다. + +:: + + sso.type=oic + +.. note:: + ``sso.type`` 및 이후에 설명하는 ``oic.*`` 의 각 설정（``oic.issuer`` 제외）은 관리 화면의 「시스템 > 전체」페이지에서도 설정·변경할 수 있습니다. + 관리 화면에서 변경한 설정은 ``system.properties`` 에 저장되며, 재시작 후에도 유지됩니다. + ``oic.issuer`` 는 ``system.properties`` 에서만 설정할 수 있습니다. + +프로바이더 설정 +--------------- + +OP에서 취득한 정보를 설정합니다. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 프로퍼티 + - 설명 + - 기본값 + * - ``oic.auth.server.url`` + - 인가 엔드포인트 URL + - ``https://accounts.google.com/o/oauth2/auth`` + * - ``oic.token.server.url`` + - 토큰 엔드포인트 URL + - ``https://accounts.google.com/o/oauth2/token`` + * - ``oic.issuer`` + - 발행자（issuer）의 식별자（선택 사항）. 설정하면 ID Token의 ``iss`` 클레임이 이 값과 정확히 일치해야 합니다（끝의 슬래시도 구별됩니다） + - (빈 문자열: ``iss`` 는 검증하지 않음) + +.. note:: + 이 URL들과 발행자는 OP의 Discovery 엔드포인트（``/.well-known/openid-configuration``）에서 취득할 수 있으며, 발행자는 그 안의 ``issuer`` 값입니다. + 토큰 엔드포인트 URL（``oic.token.server.url``）은 HTTPS여야 합니다. ``http`` 는 호스트가 ``localhost`` （대소문자 구분 없음）, ``127.x.x.x`` 형식의 IPv4 주소, ``::1`` 중 하나인 경우에만 허용됩니다. 호스트는 적힌 그대로 문자열로 비교하며 이름 해석은 하지 않습니다. 따라서 Docker Compose의 서비스 이름（``http://keycloak:8080/...`` 등）이나 사내 호스트 이름은 같은 머신을 가리키더라도 ``http`` 로는 거부됩니다. + + 이 확인은 토큰 엔드포인트에만 적용되며 인가 엔드포인트（``oic.auth.server.url``）에는 적용되지 않습니다. 확인은 로그인 시에 수행되며 시작 시에는 수행되지 않습니다. ``oic.issuer`` 를 설정해도 이 규칙은 완화되지 않으며, ``iss`` 클레임 검증이 활성화될 뿐입니다. + +클라이언트 설정 +--------------- + +OP 측에서 등록한 클라이언트 정보를 설정합니다. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 프로퍼티 + - 설명 + - 기본값 + * - ``oic.client.id`` + - 클라이언트 ID + - (빈 문자열) + * - ``oic.client.secret`` + - 클라이언트 시크릿 + - (빈 문자열) + * - ``oic.scope`` + - 요청할 스코프 + - (빈 문자열) + +.. note:: + 스코프에는 최소한 ``openid`` 를 포함해야 합니다. + 사용자의 이메일 주소를 취득하는 경우 ``openid email`` 을 지정합니다. + +리다이렉트 URL 설정 +------------------- + +인증 후 콜백 URL을 설정합니다. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 프로퍼티 + - 설명 + - 기본값 + * - ``oic.redirect.url`` + - 리다이렉트 URL（콜백 URL） + - ``{oic.base.url}/sso/`` + * - ``oic.base.url`` + - |Fess| 의 베이스 URL + - ``http://localhost:8080`` + +.. note:: + ``oic.redirect.url`` 을 생략한 경우 ``oic.base.url`` 에서 자동으로 구성됩니다. + 운영 환경에서는 ``oic.base.url`` 에 HTTPS URL을 설정하십시오. + +사용자 속성 설정 +---------------- + +OIDC로 인증된 사용자에게 할당할 기본 그룹·역할을 설정합니다. +사용자 ID·그룹·역할은 각각 다음과 같이 결정됩니다. + +- **사용자 ID**: ID Token（JWT）의 ``email`` 클레임에서 취득됩니다. 이 때문에 스코프에는 실질적으로 ``email`` 을 포함해야 합니다（``email`` 클레임을 취득할 수 없는 경우 로그인이 올바르게 이루어지지 않습니다）. +- **그룹**: ID Token의 ``groups`` 클레임에서 취득됩니다. ``groups`` 클레임이 존재하지 않는 경우 ``oic.default.groups`` 의 값이 사용됩니다. ``groups`` 클레임이 빈 배열로 전달된 경우에는 존재하는 것으로 간주되므로 ``oic.default.groups`` 가 사용되지 않으며, 그룹이 없는 것으로 처리됩니다. +- **역할**: 항상 ``oic.default.roles`` 의 값이 사용됩니다（ID Token의 클레임에서 역할을 취득하는 구조는 없습니다）. + +.. note:: + |Fess| 는 ``groups`` 클레임의 값을 그대로 사용하며, 디렉토리 조회나 중첩 그룹(상위 그룹)의 + 확장은 수행하지 않습니다. 상위 그룹이 포함되는지 여부는 OP 측의 클레임 설정에 따라서만 + 결정됩니다. Microsoft Graph API로 상위 그룹을 해결하는 :doc:`sso-entraid` 의 동작과는 다릅니다. + 클레임의 값은 그대로 검색 권한이 됩니다. OP 측에서 그룹의 전체 경로를 출력하도록 설정한 경우 + ``/상위그룹/하위그룹`` 과 같은 값이 그대로 권한 이름이 되며, 그룹 이름만 부여한 문서와는 일치하지 않습니다. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 프로퍼티 + - 설명 + - 기본값 + * - ``oic.default.groups`` + - 기본 그룹（쉼표로 구분） + - (빈 문자열) + * - ``oic.default.roles`` + - 기본 역할（쉼표로 구분） + - (빈 문자열) + +.. note:: + 역할 기반 검색을 사용하는 경우 사용자에게 적절한 그룹 또는 역할을 할당해야 합니다. + 자세한 내용은 :doc:`security-role` 을 참조하십시오. + +OP 측 설정 +========== + +OP 측에서 |Fess| 를 클라이언트（RP）로 등록할 때 다음 정보를 설정합니다. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 설정 항목 + - 설정값 + * - 애플리케이션 종류 + - 웹 애플리케이션 + * - 리다이렉트 URI / 콜백 URL + - ``https:///sso/`` + * - 허용 스코프 + - ``openid`` 및 필요한 스코프（``email``, ``profile`` 등） + +OP에서 취득하는 정보 +-------------------- + +OP의 설정 화면 또는 Discovery 엔드포인트에서 다음 정보를 취득하여 |Fess| 의 설정에 사용합니다. + +- **인가 엔드포인트（Authorization Endpoint）**: 사용자 인증을 시작하는 URL +- **토큰 엔드포인트（Token Endpoint）**: 토큰을 취득하는 URL +- **발행자（Issuer）**: 선택 사항. Discovery 문서의 ``issuer`` 값이며 ``oic.issuer`` 에 사용합니다 +- **클라이언트 ID**: OP에서 발급된 클라이언트 식별자 +- **클라이언트 시크릿**: 클라이언트 인증에 사용하는 비밀 키 + +.. note:: + 많은 OP에서 Discovery 엔드포인트（``https:///.well-known/openid-configuration``）를 통해 + 인가 엔드포인트와 토큰 엔드포인트 URL을 확인할 수 있습니다. + +설정 예 +======= + +최소 구성（검증 환경용） +------------------------ + +다음은 검증 환경에서 동작을 확인하기 위한 최소한의 설정 예입니다. + +:: + + # SSO 활성화 + sso.type=oic + + # 프로바이더 설정（OP에서 취득한 값을 설정） + oic.auth.server.url=https://op.example.com/authorize + oic.token.server.url=https://op.example.com/token + + # 클라이언트 설정 + oic.client.id=your-client-id + oic.client.secret=your-client-secret + oic.scope=openid email + + # 리다이렉트 URL（검증 환경） + oic.redirect.url=http://localhost:8080/sso/ + +권장 구성（운영 환경용） +------------------------ + +다음은 운영 환경에서 사용할 때의 권장 설정 예입니다. + +:: + + # SSO 활성화 + sso.type=oic + + # 프로바이더 설정 + oic.auth.server.url=https://op.example.com/authorize + oic.token.server.url=https://op.example.com/token + + # 발행자（Discovery 문서의 "issuer" 값） + oic.issuer=https://op.example.com + + # 클라이언트 설정 + oic.client.id=your-client-id + oic.client.secret=your-client-secret + oic.scope=openid email profile + + # 베이스 URL（운영 환경에서는 HTTPS 사용） + oic.base.url=https://fess.example.com + +문제 해결 +========== + +자주 발생하는 문제와 해결 방법 +------------------------------ + +인증 후 |Fess| 로 돌아올 수 없음 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- OP 측의 리다이렉트 URI가 올바르게 설정되어 있는지 확인하십시오 +- ``oic.redirect.url`` 또는 ``oic.base.url`` 의 값이 OP 측 설정과 일치하는지 확인하십시오 +- 프로토콜（HTTP/HTTPS）이 일치하는지 확인하십시오 + +인증 오류가 발생함 +~~~~~~~~~~~~~~~~~~ + +- 클라이언트 ID와 클라이언트 시크릿이 올바르게 설정되어 있는지 확인하십시오 +- 스코프에 ``openid`` 가 포함되어 있는지 확인하십시오 +- 인가 엔드포인트 URL과 토큰 엔드포인트 URL이 올바른지 확인하십시오 +- 로그인에 실패하면 ``fess.log`` 에 ``Failed to process the OpenID Connect callback:`` 로 시작하는 경고가 이유와 함께 출력됩니다 +- ``The ID token was not issued for this client``: ID Token의 ``aud`` 가 ``oic.client.id`` 가 아닙니다. 클라이언트 ID를 확인하십시오 +- ``The ID token has expired``: |Fess| 호스트와 OP의 시계가 300초를 넘게 어긋나 있습니다. 시각을 동기화（NTP）하십시오 +- ``The ID token was not issued by the configured issuer``: ``oic.issuer`` 가 메시지에 표시된 ``iss`` 와 다릅니다. Discovery 문서의 ``issuer`` 값을 정확히 복사하십시오 +- ``oic.token.server.url must be https``: HTTPS 토큰 엔드포인트 URL을 사용하십시오（``http`` 는 ``localhost``, ``127.x.x.x``, ``::1`` 에서만 사용할 수 있으며, Docker Compose의 서비스 이름이나 사내 호스트 이름에 대한 ``http`` 도 거부됩니다） + +사용자 정보를 취득할 수 없음 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- 스코프에 필요한 권한（``email``, ``profile`` 등）이 포함되어 있는지 확인하십시오 +- OP 측에서 클라이언트에 필요한 스코프가 허용되어 있는지 확인하십시오 +- Microsoft Entra ID에서는 소스 속성을 변경하지 않는 한 ``groups`` 클레임의 값이 그룹의 ``ObjectId`` (GUID)이므로 + 그룹 이름과 일치하지 않습니다 +- 사용자가 200개를 초과하는 그룹에 소속된 경우 Microsoft Entra ID는 ``groups`` 클레임 자체를 보내지 않으며 + (중첩 그룹도 이 상한에 포함됩니다), 이때 |Fess| 는 ``oic.default.groups`` 로 폴백합니다 + +디버그 설정 +----------- + +문제를 조사할 때 |Fess| 의 로그 레벨을 조정하면 OpenID Connect 관련 상세 로그를 출력할 수 있습니다. + +``app/WEB-INF/classes/log4j2.xml`` 에서 다음 로거를 추가하여 로그 레벨을 변경할 수 있습니다. + +:: + + + +.. warning:: + 이 로거를 DEBUG로 설정하면 ID Token의 클레임(``email`` 이나 ``groups`` 등)이 로그 파일에 출력됩니다. + 조사가 끝나면 로그 레벨을 원래대로 되돌리고, 출력된 로그의 취급에 주의하십시오. + +참고 정보 +========= + +- :doc:`security-role` - 역할 기반 검색 설정에 대하여 +- :doc:`sso-saml` - SAML 인증을 통한 SSO 설정에 대하여 +- :doc:`sso-entraid` - Microsoft Entra ID 전용 SSO 설정에 대하여（Entra ID를 사용하는 경우, 범용 OpenID Connect 설정 대신 전용 설정을 사용할 수도 있습니다） diff --git a/ko/15.10/config/sso-saml.rst b/ko/15.10/config/sso-saml.rst new file mode 100644 index 000000000..9f83b3c8e --- /dev/null +++ b/ko/15.10/config/sso-saml.rst @@ -0,0 +1,649 @@ +============================ +SAML 인증을 통한 SSO 설정 +============================ + +개요 +==== + +|Fess| 에서는 SAML（Security Assertion Markup Language）2.0을 사용한 싱글 사인온（SSO）인증을 지원합니다. +SAML 인증을 사용하면 IdP（Identity Provider）에서 인증된 사용자 정보를 |Fess| 에 연동하고, 역할 기반 검색과 결합하여 사용자의 권한에 따른 검색 결과 구분이 가능해집니다. + +.. note:: + SAML 인증 지원은 ``fess-sso-saml`` 플러그인에서 제공됩니다. 배포물에 포함되어 있지 + 않으므로 관리 화면의 「시스템 > 플러그인」 페이지 또는 + ``bin/fess-setup install plugin fess-sso-saml`` 로 설치하십시오. + 설치하기 전에는 ``sso.type=saml`` 설정만으로는 ``/sso/`` 요청이 로그인 페이지로 + 리디렉션될 뿐입니다. + +SAML 인증의 구조 +---------------- + +SAML 인증에서는 |Fess| 가 SP（Service Provider）로 동작하여 외부 IdP와 연동하여 인증을 수행합니다. + +1. 사용자가 |Fess| 의 SSO 엔드포인트（``/sso/``）에 접근 +2. |Fess| 가 IdP에 인증 요청을 리다이렉트 +3. 사용자가 IdP에서 인증 실행 +4. IdP가 SAML 어서션을 |Fess| 에 전송 +5. |Fess| 가 어서션을 검증하고 사용자를 로그인 + +.. note:: + 지원되는 것은 위와 같이 |Fess| 측（``/sso/``）에서 시작하는 SP-Initiated 로그인뿐입니다. + |Fess| 는 전송한 AuthnRequest의 ID와 SAML 응답을 대응시켜 검증하므로, + IdP 포털（Okta 대시보드나 Microsoft Entra ID의 「내 앱」 등）에 배치한 타일에서 시작하는 + IdP-Initiated（미요청·unsolicited）SSO는 대응시킬 AuthnRequest가 없어 거부됩니다. + IdP 측에 타일을 배치하는 경우에는 링크 대상을 |Fess| 의 ``/sso/`` 로 지정하십시오. + + 참고로 15.7에서는 ``tomcat.sameSiteCookies=none`` 을 설정하면 IdP-Initiated 로그인이 결과적으로 + 동작했습니다. |Fess| 가 대응시키지 못한 응답을 IdP로 되돌려 보내고, IdP가 즉시 SP-Initiated + 어서션을 반환했기 때문입니다. 15.10에서는 이 되돌려 보내기를 하지 않으므로 IdP-Initiated 로그인은 + 동작하지 않습니다. + +역할 기반 검색과의 연동에 대해서는 :doc:`security-role` 을 참조하십시오. + +전제 조건 +========= + +SAML 인증을 설정하기 전에 다음 전제 조건을 확인하십시오. + +- |Fess| 15.10 이상이 설치되어 있을 것 +- SAML 2.0 대응 IdP（Identity Provider）를 사용할 수 있을 것 +- |Fess| 가 HTTPS로 접근 가능할 것（운영 환경에서는 필수） +- IdP 측에서 |Fess| 를 SP로 등록할 수 있는 권한이 있을 것 + +지원 IdP의 예: + +- Microsoft Entra ID（Azure AD） +- Okta +- Google Workspace +- Keycloak +- OneLogin +- 기타 SAML 2.0 대응 IdP + +기본 설정 +========= + +SSO 기능 활성화 +--------------- + +SAML 인증을 활성화하려면 ``app/WEB-INF/conf/system.properties`` 에 다음 설정을 추가합니다. + +:: + + sso.type=saml + +.. note:: + ``sso.type`` 및 기본적인 SAML 설정（IdP 정보, SP 정보, 사용자 속성 매핑）은 관리 화면의 「시스템 > 전체」 페이지에서도 설정·변경할 수 있습니다. + 관리 화면에서 변경한 설정은 ``system.properties`` 에 저장되며, 재시작 후에도 유지됩니다. + 단, 서명·암호화 등의 보안 설정이나 SP 인증서·비밀 키는 관리 화면에서 설정할 수 없으므로 ``system.properties`` 에 직접 기술하십시오. + +.. note:: + ``saml.`` 로 시작하는 설정은 ``system.properties`` 에서만 읽어 들입니다. + JVM 시스템 프로퍼티（``-Dsaml.security....`` 나 ``-Dfess.saml.security....``）로 지정해도 참조되지 않습니다. + 특히 ``saml.security.*`` , ``saml.strict`` , ``saml.debug`` 는 관리 화면에도 항목이 없으므로 + ``system.properties`` 에 직접 기술하는 것 외에는 설정할 방법이 없습니다. + +세션 쿠키 설정 +-------------- + +IdP는 어설션을 |Fess| 로 **크로스 사이트 POST** 로 반환합니다. ``SameSite=Lax`` 쿠키는 이러한 요청에 전송되지 않으므로, |Fess| 에 포함된 기본값 그대로는 SAML 로그인이 완료되지 않습니다. + +``tomcat_config.properties`` 의 ``tomcat.sameSiteCookies`` 를 ``none`` 으로 변경하십시오. 이 파일은 ZIP 패키지에서는 ``lib/classes/`` , DEB/RPM 패키지에서는 ``/etc/fess/`` 에 있습니다. + +:: + + tomcat.sameSiteCookies = none + +.. warning:: + 브라우저는 ``Secure`` 속성이 함께 있는 쿠키에 대해서만 ``none`` 을 허용하므로 |Fess| 를 HTTPS로 제공해야 합니다. 일반 HTTP에서는 이 설정으로 인해 |Fess| 에 로그인할 수 없게 됩니다. + +.. note:: + 기본값 ``lax`` 는 콜백이 리디렉션(GET)으로 돌아오는 SSO 방식을 위한 것입니다. SAML의 HTTP-POST 바인딩은 여기에 해당하지 않으므로 SAML을 사용할 때만 변경이 필요합니다. 설정 변경 후에는 |Fess| 를 재시작해야 합니다. + +SP（Service Provider）설정 +-------------------------- + +|Fess| 를 SP로 설정하려면 SP Base URL을 지정합니다. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 프로퍼티 + - 설명 + - 기본값 + * - ``saml.sp.base.url`` + - SP의 베이스 URL + - ``http://localhost:8080`` + +.. note:: + ``saml.sp.base.url`` 의 기본값은 ``http://localhost:8080`` 입니다. + 검증 환경 이외에서는 반드시 |Fess| 에 외부에서 접근할 때의 URL（운영 환경에서는 HTTPS）을 설정하십시오. + +이 설정에 의해 다음 엔드포인트가 자동으로 구성됩니다. + +- **Entity ID**: ``{saml.sp.base.url}/sso/metadata`` +- **ACS URL**: ``{saml.sp.base.url}/sso/`` +- **SLO URL**: ``{saml.sp.base.url}/sso/logout`` + +설정 예:: + + saml.sp.base.url=https://fess.example.com + +개별 URL 설정 +~~~~~~~~~~~~~ + +일반적으로 ``saml.sp.base.url`` 을 설정하면 각 엔드포인트 URL이 자동으로 구성되지만, +필요에 따라 다음 프로퍼티로 개별 URL을 명시적으로 지정하여 덮어쓸 수도 있습니다. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 프로퍼티 + - 설명 + - 기본값 + * - ``saml.sp.entityid`` + - SP의 Entity ID + - ``{saml.sp.base.url}/sso/metadata`` + * - ``saml.sp.assertion_consumer_service.url`` + - Assertion Consumer Service URL + - ``{saml.sp.base.url}/sso/`` + * - ``saml.sp.single_logout_service.url`` + - Single Logout Service URL + - ``{saml.sp.base.url}/sso/logout`` + +IdP（Identity Provider）설정 +---------------------------- + +IdP에서 취득한 정보를 설정합니다. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 프로퍼티 + - 설명 + - 기본값 + * - ``saml.idp.entityid`` + - IdP의 Entity ID + - （필수） + * - ``saml.idp.single_sign_on_service.url`` + - IdP의 SSO 서비스 URL + - （필수） + * - ``saml.idp.x509cert`` + - IdP의 서명용 X.509 인증서（Base64 인코딩, 줄 바꿈 없음） + - （필수） + * - ``saml.idp.single_logout_service.url`` + - IdP의 SLO 서비스 URL + - （선택 사항） + +.. note:: + ``saml.idp.x509cert`` 에는 인증서의 Base64 인코딩된 내용을 줄 바꿈 없이 1행으로 지정합니다. + ``-----BEGIN CERTIFICATE-----`` 와 ``-----END CERTIFICATE-----`` 행은 포함하지 마십시오. + +SP 메타데이터 취득 +------------------ + +|Fess| 를 시작하면 ``/sso/metadata`` 엔드포인트에서 SP 메타데이터를 XML 형식으로 취득할 수 있습니다. + +:: + + https://fess.example.com/sso/metadata + +이 메타데이터를 IdP에 임포트하거나, 메타데이터의 내용을 참고하여 IdP 측에서 SP를 수동으로 등록하십시오. + +.. note:: + 메타데이터를 취득하려면 먼저 기본적인 SAML 설정（``sso.type=saml`` 과 ``saml.sp.base.url``）을 완료하고 |Fess| 를 시작해 두어야 합니다. + +IdP 측 설정 +=========== + +IdP 측에서 |Fess| 를 SP로 등록할 때 다음 정보를 설정합니다. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 설정 항목 + - 설정값 + * - ACS URL / Reply URL + - ``https:///sso/`` + * - Entity ID / Audience URI + - ``https:///sso/metadata`` + * - Name ID Format + - ``urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`` （권장） + +IdP에서 취득하는 정보 +--------------------- + +IdP의 설정 화면 또는 메타데이터에서 다음 정보를 취득하여 |Fess| 의 설정에 사용합니다. + +- **IdP Entity ID**: IdP를 식별하기 위한 URI +- **SSO URL（HTTP-Redirect）**: 싱글 사인온의 엔드포인트 URL +- **X.509 인증서**: SAML 어서션의 서명 검증에 사용하는 공개 키 인증서 + +사용자 속성 매핑 +================ + +SAML 어서션에서 취득한 사용자 속성을 |Fess| 의 그룹이나 역할에 매핑할 수 있습니다. + +그룹 속성 설정 +-------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 프로퍼티 + - 설명 + - 기본값 + * - ``saml.attribute.group.name`` + - 그룹 정보를 포함하는 속성명 + - ``memberOf`` + * - ``saml.default.groups`` + - 기본 그룹（쉼표로 구분） + - （없음） + +설정 예:: + + saml.attribute.group.name=groups + saml.default.groups=user + +.. note:: + |Fess| 는 어서션의 그룹 값을 그대로 사용하며, 디렉토리 조회나 중첩 그룹(상위 그룹)의 확장은 + 수행하지 않습니다. 상위 그룹이 포함되는지 여부는 IdP 측의 클레임 설정에 따라서만 결정됩니다. + Microsoft Graph API로 상위 그룹을 해결하는 :doc:`sso-entraid` 의 동작과는 다릅니다. + +역할 속성 설정 +-------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 프로퍼티 + - 설명 + - 기본값 + * - ``saml.attribute.role.name`` + - 역할 정보를 포함하는 속성명 + - （없음） + * - ``saml.default.roles`` + - 기본 역할（쉼표로 구분） + - （없음） + +설정 예:: + + saml.attribute.role.name=roles + saml.default.roles=viewer + +.. note:: + IdP에서 속성을 취득할 수 없는 경우 기본값이 사용됩니다. + 역할 기반 검색을 사용하는 경우 적절한 그룹 또는 역할을 설정하십시오. + +.. warning:: + ``saml.attribute.role.name`` 을 설정하면 IdP가 보낸 속성 값이 그대로 |Fess| 의 역할이 됩니다. + ``fess_config.properties`` 의 ``authentication.admin.roles`` 기본값은 ``admin`` 이므로, + IdP가 역할 속성에 ``admin`` 을 포함해 보낸 사용자는 |Fess| 의 관리자 권한을 갖게 됩니다. + IdP 측에서 역할 속성 값을 제어할 수 있는 범위를 확인하고, 필요하다면 + ``authentication.admin.roles`` 를 다른 이름으로 변경하십시오. + +속성 이름이 중복되는 IdP +------------------------ + +IdP가 동일한 속성 이름을 여러 ```` 요소로 나누어 보내면 |Fess| 는 해당 어서션을 +거부하며 로그인 자체가 실패합니다. + +Keycloak은 기본적으로 이러한 형태의 어서션을 보냅니다. 역할 매퍼와 그룹 매퍼는 ``single`` +옵션을 활성화하지 않는 한 값마다 별도의 ```` 요소를 출력하며, Keycloak 계정은 +기본적으로 여러 개의 렐름 역할을 가지기 때문입니다. + +대처 방법은 다음 중 하나입니다. + +- IdP 측에서 속성을 하나의 요소로 합칩니다(Keycloak에서는 매퍼의 ``single`` 옵션을 활성화합니다) +- |Fess| 측에서 중복을 허용하고 값을 병합합니다 + +.. list-table:: + :header-rows: 1 + :widths: 45 40 15 + + * - 프로퍼티 + - 설명 + - 기본값 + * - ``saml.security.allow_duplicated_attribute_name`` + - 동일한 속성 이름이 여러 요소에 나타나는 것을 허용하고 값을 병합합니다 + - ``false`` + +설정 예:: + + saml.security.allow_duplicated_attribute_name=true + +보안 설정 +========= + +운영 환경에서는 다음 보안 설정을 활성화하는 것을 권장합니다. + +.. note:: + 권장되지 않는 설정이 남아 있으면 SAML 설정을 읽어 들일 때 ``Insecure SAML settings: ...`` + 경고가 로그에 출력됩니다. + +서명 설정 +--------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 프로퍼티 + - 설명 + - 기본값 + * - ``saml.security.authnrequest_signed`` + - 인증 요청에 서명한다 + - ``false`` + * - ``saml.security.want_messages_signed`` + - 메시지의 서명을 요구한다 + - ``false`` + * - ``saml.security.want_assertions_signed`` + - 어서션의 서명을 요구한다 + - ``false`` + * - ``saml.security.logoutrequest_signed`` + - 로그아웃 요청에 서명한다 + - ``false`` + * - ``saml.security.logoutresponse_signed`` + - 로그아웃 응답에 서명한다 + - ``false`` + * - ``saml.security.reject_deprecated_alg`` + - SHA-1 등 사용이 권장되지 않는 서명 알고리즘을 거부한다 + - ``false`` + +.. warning:: + 기본값에서는 보안 기능이 비활성화되어 있습니다. + 운영 환경에서는 최소한 ``saml.security.want_assertions_signed=true`` 를 설정하도록 강력히 권장합니다. + +.. note:: + ``saml.security.reject_deprecated_alg`` 가 ``false`` 인 동안에는 SHA-1（``rsa-sha1`` 및 ``dsa-sha1``）로 + 서명된 어서션이나 메시지도 허용됩니다. 기본적으로 활성화되어 있지 않은 이유는, 활성화하면 아직 SHA-1로 + 서명하는 IdP를 거부하게 되기 때문입니다. + IdP가 SHA-256 이상으로 서명하는지 확인한 후 ``saml.security.reject_deprecated_alg=true`` 를 설정하십시오. + +.. warning:: + 싱글 로그아웃（``saml.idp.single_logout_service.url``）을 설정하는 경우에는 + ``saml.security.want_messages_signed=true`` 도 반드시 함께 설정하십시오. + ``false`` 인 상태에서는 서명이 없는 LogoutRequest가 수락되므로, 조작된 URL로 인증된 사용자의 + 세션을 종료시킬 수 있습니다. + 영향은 강제 로그아웃（서비스 거부）이며, 계정 탈취는 아닙니다. + +암호화 설정 +----------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 프로퍼티 + - 설명 + - 기본값 + * - ``saml.security.want_assertions_encrypted`` + - 어서션의 암호화를 요구한다 + - ``false`` + * - ``saml.security.want_nameid_encrypted`` + - NameID의 암호화를 요구한다 + - ``false`` + * - ``saml.security.allowed_key_transport_algorithms`` + - 어설션을 복호화할 때 허용할 키 전송 알고리즘 (쉼표로 구분된 URI) + - (빈 값: 모든 알고리즘을 허용) + +.. note:: + |Fess| 는 XML Encryption 1.1로 암호화된 응답을 검증합니다. 예를 들어 현재 Keycloak은 + ``http://www.w3.org/2009/xmlenc11#rsa-oaep`` 를 사용하고 응답에 ```` 요소를 + 포함하지만, 스키마 검증을 켠 상태로도 이러한 응답을 받아들입니다. 이전 버전에서는 + ``Invalid SAML Response. Not match the saml-schema-protocol-2.0.xsd`` 로 거부되었습니다. + 그 회피책으로 ``saml.security.want_xml_validation=false`` 를 설정했다면 제거하십시오. + +.. note:: + SP 개인 키를 설정할 때는 ``saml.security.allowed_key_transport_algorithms`` 도 함께 + 설정하십시오. 설정하지 않으면 오래된 ``http://www.w3.org/2001/04/xmlenc#rsa-1_5`` 를 포함한 + 모든 키 전송 알고리즘을 허용합니다. 어설션 컨슈머 엔드포인트는 인증이 필요 없고 복호화는 + 응답 검증보다 먼저 실행되므로, 인증되지 않은 호출자가 임의의 암호문을 SP 개인 키로 복호화하게 + 만들 수 있습니다. 이 상태에서는 시작 시 ``Insecure SAML settings`` 줄에 + ``key_transport_algorithms_not_restricted`` 가 출력됩니다. IdP가 실제로 사용하는 것으로 + 제한하십시오:: + + saml.security.allowed_key_transport_algorithms=http://www.w3.org/2009/xmlenc11#rsa-oaep + +SP 인증서 및 비밀 키 설정 +-------------------------- + +SP 측에서 인증 요청이나 로그아웃 메시지에 서명하는 경우（``saml.security.authnrequest_signed`` 등）, +또는 어서션이나 NameID의 암호화를 요구하는 경우（``saml.security.want_assertions_encrypted`` 등）는, +SP의 비밀 키와 X.509 인증서를 설정해야 합니다. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 프로퍼티 + - 설명 + - 기본값 + * - ``saml.sp.x509cert`` + - SP의 X.509 인증서（Base64 인코딩, 줄 바꿈 없음） + - （빈 문자열） + * - ``saml.sp.privatekey`` + - SP의 비밀 키（Base64 인코딩, 줄 바꿈 없음） + - （빈 문자열） + +.. note:: + ``saml.sp.x509cert`` 와 ``saml.sp.privatekey`` 에는 ``saml.idp.x509cert`` 와 마찬가지로, + Base64 인코딩된 내용을 줄 바꿈 없이 1행으로 지정합니다（``-----BEGIN ...-----`` 와 ``-----END ...-----`` 행은 포함하지 않습니다）. + 서명·암호화를 활성화하는 경우 SP 인증서를 IdP 측에도 등록하십시오. SP 인증서는 ``/sso/metadata`` 의 SP 메타데이터에 포함되어 공개됩니다. + +기타 보안 설정 +-------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 프로퍼티 + - 설명 + - 기본값 + * - ``saml.strict`` + - 엄격 모드（검증을 엄격하게 수행） + - ``true`` + * - ``saml.security.want_xml_validation`` + - 메시지의 XML 스키마 검증을 수행한다 + - ``true`` + * - ``saml.security.signature_algorithm`` + - 서명 알고리즘 + - ``http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`` + * - ``saml.security.requested_authncontext`` + - 요구하는 인증 컨텍스트 + - ``urn:oasis:names:tc:SAML:2.0:ac:classes:Password`` + * - ``saml.sp.nameidformat`` + - NameID 형식 + - ``urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`` + +.. note:: + |Fess| 는 내부적으로 SAML 라이브러리（java-saml）를 사용하며, ``saml.`` 로 시작하는 프로퍼티는 + 라이브러리의 대응하는 설정（``onelogin.saml2.`` 프리픽스）에 매핑됩니다. + 이 때문에 여기서 소개한 것 외에도, 바인딩（``saml.sp.assertion_consumer_service.binding`` 등）, + 조직 정보（``saml.organization.*``）, 연락처 정보（``saml.contacts.*``）와 같은 상세 설정을 + ``system.properties`` 에 지정할 수 있습니다. + +AuthnRequest 유효 기간 +====================== + +|Fess| 는 ``/sso/`` 에 접근할 때마다 AuthnRequest를 1건 IdP로 전송하고, 그 ID를 세션에 기록합니다. +IdP에서 반환된 SAML 응답은 기록된 ID와 대응시켜 검증됩니다. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 프로퍼티 + - 설명 + - 기본값 + * - ``saml.request.id.ttl`` + - 응답이 없는 AuthnRequest의 ID를 보관하는 기간（초） + - ``3600`` + +기록된 ID는 이 기간이 지나면 폐기됩니다. +IdP 로그인 화면을 열어둔 채로 방치하는 등의 이유로 유효 기간이 지나면 반환된 어서션을 대응시킬 수 없어 그 자리에서 한 번만 로그인에 실패합니다. + +설정 예 +======= + +최소 구성（검증 환경용） +------------------------ + +다음은 검증 환경에서 동작을 확인하기 위한 최소한의 설정 예입니다. + +:: + + # SSO 활성화 + sso.type=saml + + # SP 설정 + saml.sp.base.url=https://fess.example.com + + # IdP 설정（IdP의 관리 화면에서 취득한 값을 설정） + saml.idp.entityid=https://idp.example.com/saml/metadata + saml.idp.single_sign_on_service.url=https://idp.example.com/saml/sso + saml.idp.x509cert=MIIDpDCCAoygAwIBAgI...（Base64 인코딩된 인증서） + + # 기본 그룹 + saml.default.groups=user + +권장 구성（운영 환경용） +------------------------ + +다음은 운영 환경에서 사용하기 위한 권장 설정 예입니다. + +:: + + # SSO 활성화 + sso.type=saml + + # SP 설정 + saml.sp.base.url=https://fess.example.com + + # IdP 설정 + saml.idp.entityid=https://idp.example.com/saml/metadata + saml.idp.single_sign_on_service.url=https://idp.example.com/saml/sso + saml.idp.single_logout_service.url=https://idp.example.com/saml/logout + saml.idp.x509cert=MIIDpDCCAoygAwIBAgI...（Base64 인코딩된 인증서） + + # 사용자 속성 매핑 + saml.attribute.group.name=groups + saml.attribute.role.name=roles + saml.default.groups=user + + # 보안 설정（운영 환경에서는 활성화 권장） + saml.security.want_assertions_signed=true + saml.security.want_messages_signed=true + + # IdP가 SHA-256 이상으로 서명하는지 확인한 후 활성화한다 + saml.security.reject_deprecated_alg=true + +문제 해결 +========= + +자주 발생하는 문제와 해결 방법 +------------------------------ + +인증 후 |Fess| 로 돌아올 수 없음 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- IdP 측의 ACS URL이 올바르게 설정되어 있는지 확인하십시오 +- ``saml.sp.base.url`` 의 값이 IdP 측의 설정과 일치하는지 확인하십시오 +- SAML 어설션은 IdP에서 교차 사이트 POST로 전송됩니다. ``tomcat_config.properties`` 의 + ``tomcat.sameSiteCookies`` 가 ``lax`` (기본값)인 경우 브라우저가 세션 쿠키를 함께 보내지 않으므로 + 그 자리에서 한 번만 로그인에 실패합니다. 이 경우 + ``tomcat.sameSiteCookies = none`` 을 설정하십시오 (``SameSite=None`` 은 HTTPS가 필요합니다) +- IdP에서 로그인에 시간이 오래 걸리면 어설션이 돌아온 시점에 AuthnRequest의 ID가 남아 있지 않으므로 + 그 자리에서 한 번만 로그인에 실패합니다. 이 경우에는 로그인을 다시 시작하십시오 +- |Fess| 는 ``app/WEB-INF/web.xml`` 에 ``session-timeout`` 을 지정하지 않으므로 서블릿 컨테이너의 + 기본값인 30분이 적용됩니다. 이는 ``saml.request.id.ttl`` 의 3600초보다 짧아 세션이 먼저 폐기됩니다. + 따라서 ``saml.request.id.ttl`` 만 늘려도 사용자가 IdP에서 로그인을 마칠 수 있는 시간은 늘어나지 + 않으므로, 세션 타임아웃도 함께 늘리십시오 + +리버스 프록시 환경에서 Destination 검증에 실패함 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +TLS를 종단하는 리버스 프록시나 로드 밸런서 뒤에 |Fess| 를 배치하면, +``saml.sp.base.url`` 을 올바르게 설정했더라도 어설션 검증에 실패할 수 있습니다. + +어설션의 ``Destination`` 속성은 |Fess| 에 도달한 시점의 요청 URL과 비교됩니다. +TLS를 종단하는 프록시 뒤에서는 이 값이 IdP가 어설션을 보낸 외부 URL이 아니라 내부 ``http://`` URL입니다. +``saml.sp.base.url`` 은 이 비교에 사용되지 않으므로 이 설정만으로는 해결되지 않습니다. + +``saml.debug=true`` 를 설정하면 로그에 다음과 같은 이유가 출력됩니다. + +:: + + The response was received at http://... instead of https://fess.example.com/sso/ + +이 경우 ``tomcat_config.properties`` 의 커넥터 설정을 외부에서 보이는 스킴과 포트에 맞추십시오. +다음 설정은 기본적으로 주석 처리되어 있습니다. + +:: + + tomcat.secure=true + tomcat.scheme=https + tomcat.proxyPort=443 + +아울러 리버스 프록시가 원래의 ``Host`` 헤더를 그대로 |Fess| 로 전달하도록 설정하십시오. +요청 URL의 호스트명 부분은 ``Host`` 헤더로부터 조립됩니다. +``tomcat_config.properties`` 를 변경한 후에는 |Fess| 의 재시작이 필요합니다. + +같은 검증이 싱글 로그아웃 메시지에도 적용되므로, SLO를 사용하는 경우에도 동일하게 설정하십시오. + +서명 검증 오류 +~~~~~~~~~~~~~~ + +- IdP의 인증서가 올바르게 설정되어 있는지 확인하십시오 +- 인증서의 유효 기간이 만료되지 않았는지 확인하십시오 +- 인증서는 Base64 인코딩된 내용만 줄 바꿈 없이 설정하십시오 + +속성 이름 중복으로 로그인할 수 없음 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- 로그에 ``The IdP repeated an attribute name in the SAML assertion`` 으로 시작하는 경고가 + 출력된다면, IdP가 동일한 속성 이름을 여러 ```` 요소로 나누어 보내고 있습니다 +- 어서션 검증 자체는 성공했으므로 인증서나 시각 오차는 원인이 아닙니다 +- IdP 측에서 속성을 하나로 합치거나 ``saml.security.allow_duplicated_attribute_name=true`` 를 + 설정하세요 + +사용자의 그룹·역할이 반영되지 않음 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- IdP 측에서 속성（Attribute）이 올바르게 설정되어 있는지 확인하십시오 +- ``saml.attribute.group.name`` 의 값이 IdP에서 전송되는 속성명과 일치하는지 확인하십시오 +- Microsoft Entra ID에서는 소스 속성을 변경하지 않는 한 그룹 클레임의 값이 그룹의 ``ObjectId`` (GUID)이므로 + 그룹 이름과 일치하지 않습니다 +- 사용자가 150개를 초과하는 그룹에 소속된 경우 Microsoft Entra ID는 그룹 클레임 자체를 보내지 않으며 + (중첩 그룹도 이 상한에 포함됩니다), 이때 |Fess| 는 ``saml.default.groups`` 로 폴백합니다 +- SAML 어서션의 내용을 확인하려면 디버그 모드를 활성화하십시오 + +디버그 설정 +----------- + +문제를 조사할 때는 다음 설정으로 디버그 모드를 활성화할 수 있습니다. + +:: + + saml.debug=true + +``saml.debug=true`` 를 설정하면 SAML 인증에 실패했을 때의 상세한 이유가 로그에 출력됩니다. + +또한 ``app/WEB-INF/classes/log4j2.xml`` 에 다음 로거를 추가하면 SAML 관련 상세 로그를 출력할 수 있습니다. + +:: + + + +참고 정보 +========= + +- :doc:`security-role` - 역할 기반 검색 설정에 대하여 +- :doc:`sso-oidc` - OpenID Connect에 의한 SSO 설정에 대하여 +- :doc:`sso-entraid` - Microsoft Entra ID 전용 SSO 설정에 대하여 diff --git a/ko/15.10/config/sso-spnego.rst b/ko/15.10/config/sso-spnego.rst new file mode 100644 index 000000000..f06e24362 --- /dev/null +++ b/ko/15.10/config/sso-spnego.rst @@ -0,0 +1,487 @@ +========================================== +Windows 통합 인증을 통한 SSO 설정 +========================================== + +개요 +==== + +|Fess| 는 Windows 통합 인증(SPNEGO/Kerberos)을 사용한 싱글 사인온(SSO) 인증을 지원합니다. +Windows 통합 인증을 사용하면 Active Directory 도메인에 가입한 Windows에 로그인한 사용자는 추가 로그인 조작 없이 |Fess| 에 접근할 수 있습니다. + +.. note:: + Windows 통합 인증 지원은 ``fess-sso-spnego`` 플러그인에서 제공됩니다. 배포물에 포함되어 + 있지 않으므로 관리 화면의 「시스템 > 플러그인」 페이지 또는 + ``bin/fess-setup install plugin fess-sso-spnego`` 로 설치하십시오. + 설치하기 전에는 ``sso.type=spnego`` 설정만으로는 ``/sso/`` 요청이 로그인 페이지로 + 리디렉션될 뿐입니다. + +Windows 통합 인증의 동작 방식 +------------------------------ + +Windows 통합 인증에서는 |Fess| 가 SPNEGO(Simple and Protected GSSAPI Negotiation Mechanism) 프로토콜을 사용하여 Kerberos 인증을 수행합니다. + +1. 사용자가 Windows 도메인에 로그인 +2. 사용자가 |Fess| 에 접근 +3. |Fess| 가 SPNEGO 챌린지를 송신 +4. 브라우저가 Kerberos 티켓을 취득하여 서버에 송신 +5. |Fess| 가 티켓을 검증하고 사용자명을 취득 +6. LDAP를 사용하여 사용자의 그룹 정보를 취득 +7. 사용자가 로그인 상태가 되고 그룹 정보가 역할 기반 검색에 적용됨 + +역할 기반 검색과의 연계에 대해서는 :doc:`security-role` 을 참조하십시오. + +전제조건 +======== + +Windows 통합 인증을 설정하기 전에 다음 전제조건을 확인하십시오: + +- |Fess| 15.10 이상이 설치되어 있을 것 +- Active Directory(AD) 서버가 사용 가능할 것 +- |Fess| 서버가 AD 도메인에서 접근 가능할 것 +- AD에서 서비스 프린시펄 이름(SPN)을 설정할 권한이 있을 것 +- LDAP로 사용자 정보를 취득하기 위한 계정이 있을 것 + +Active Directory 측 설정 +========================= + +서비스 프린시펄 이름(SPN) 등록 +-------------------------------- + +|Fess| 용 SPN을 Active Directory에 등록해야 합니다. +AD 도메인에 가입한 Windows에서 명령 프롬프트를 열고 ``setspn`` 명령을 실행합니다. + +:: + + setspn -S HTTP/ + +예: + +:: + + setspn -S HTTP/fess-server.example.local svc_fess + +등록을 확인하려면: + +:: + + setspn -L + +.. note:: + SPN 등록 후 Fess 서버에서 실행한 경우에는 한 번 Windows에서 로그아웃하고 다시 로그인하십시오. + +기본 설정 +========= + +SSO 활성화 +----------- + +Windows 통합 인증을 활성화하려면 ``app/WEB-INF/conf/system.properties`` 에 다음 설정을 추가합니다: + +:: + + sso.type=spnego + +Kerberos 설정 파일 +------------------- + +``app/WEB-INF/classes/krb5.conf`` 를 생성하고 Kerberos 설정을 작성합니다. + +:: + + [libdefaults] + default_realm = EXAMPLE.LOCAL + default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + + [realms] + EXAMPLE.LOCAL = { + kdc = AD-SERVER.EXAMPLE.LOCAL + default_domain = EXAMPLE.LOCAL + } + + [domain_realm] + example.local = EXAMPLE.LOCAL + .example.local = EXAMPLE.LOCAL + +.. note:: + ``EXAMPLE.LOCAL`` 은 사용 중인 AD 도메인 이름(대문자)으로, ``AD-SERVER.EXAMPLE.LOCAL`` 은 AD 서버의 호스트명으로 교체하십시오. + +.. warning:: + ``permitted_enctypes`` 에 없는 암호화 방식으로 암호화된 서비스 티켓은 Kerberos 수신 측에서 + ``encryption type not in permitted_enctypes list`` 로 거부됩니다. + Active Directory 는 일반적으로 AES256 서비스 티켓을 발급하므로 AES256 을 반드시 포함해야 합니다. + +.. note:: + Java 17 이상에서는 RC4( ``rc4-hmac`` ), 3DES, DES 가 기본적으로 비활성화되어 있어 나열해도 + 사용되지 않습니다. 위 예에서는 AES 만 지정했습니다. + ``aes256-cts-hmac-sha384-192`` 와 ``aes128-cts-hmac-sha256-128`` 은 Windows Server 2025 가 지원하는 + AES-SHA2(RFC 8009) 암호화 방식입니다. + RC4 키만 가진 서비스 계정은 Kerberos 인증에 사용할 수 없으므로, 비밀번호를 재설정하여 + AES 키가 생성되도록 하십시오. + +로그인 설정 파일 +----------------- + +``app/WEB-INF/classes/auth_login.conf`` 를 생성하고 JAAS 로그인 설정을 작성합니다. + +:: + + spnego-client { + com.sun.security.auth.module.Krb5LoginModule required; + }; + + spnego-server { + com.sun.security.auth.module.Krb5LoginModule required + storeKey=true + isInitiator=false; + }; + +.. note:: + ``krb5.conf`` 와 ``auth_login.conf`` 는 ``spnego.krb5.conf`` / ``spnego.login.conf`` 로 기본 파일명이 설정되어 있지만, 파일 자체는 반드시 생성해 두어야 합니다. + SPNEGO 는 첫 로그인 시 초기화되므로 이 파일들이 없어도 |Fess| 자체는 시작되지만 SSO 로그인이 실패합니다. + +필수 설정 +---------- + +``app/WEB-INF/conf/system.properties`` 에 다음 설정을 추가합니다. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 프로퍼티 + - 설명 + - 기본값 + * - ``spnego.preauth.username`` + - AD 접속용 사용자명 + - (keytab을 사용하지 않는 경우 필수) + * - ``spnego.preauth.password`` + - AD 접속용 비밀번호 + - (keytab을 사용하지 않는 경우 필수) + * - ``spnego.krb5.conf`` + - Kerberos 설정 파일 경로 + - ``krb5.conf`` + * - ``spnego.login.conf`` + - 로그인 설정 파일 경로 + - ``auth_login.conf`` + +.. note:: + ``spnego.preauth.username`` 과 ``spnego.preauth.password`` 를 모두 비워 두면 서버 로그인 모듈이 + keytab 을 사용합니다. + AD 서비스 계정의 비밀번호를 |Fess| 설정 파일에 저장하고 싶지 않은 경우, keytab 을 만들고 + ``auth_login.conf`` 의 ``spnego-server`` 를 다음과 같이 설정하십시오. + + :: + + spnego-server { + com.sun.security.auth.module.Krb5LoginModule required + useKeyTab=true + keyTab="/var/lib/fess/fess.keytab" + principal="HTTP/fess-server.example.local@EXAMPLE.LOCAL" + storeKey=true + isInitiator=false; + }; + +옵션 설정 +---------- + +필요에 따라 다음 설정을 추가할 수 있습니다. + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 프로퍼티 + - 설명 + - 기본값 + * - ``spnego.login.client.module`` + - 클라이언트 모듈명 + - ``spnego-client`` + * - ``spnego.login.server.module`` + - 서버 모듈명 + - ``spnego-server`` + * - ``spnego.allow.basic`` + - Basic 인증 허용 + - ``true`` + * - ``spnego.allow.unsecure.basic`` + - 비보안 Basic 인증 허용 + - ``false`` + * - ``spnego.prompt.ntlm`` + - NTLM 토큰 수신 시 Basic 인증으로 폴백 + - ``true`` + * - ``spnego.allow.localhost`` + - localhost에서의 접근 허용 + - ``false`` + * - ``spnego.allow.delegation`` + - 위임 허용 + - ``false`` + * - ``spnego.allowed.realms`` + - 서버 영역에 더해 허용할 Kerberos 영역(쉼표 구분) + - (없음) + * - ``spnego.logger.level`` + - SPNEGO 라이브러리 내부 로그 레벨( ``1`` =FINEST, ``2`` =FINER, ``3`` =FINE, ``4`` =CONFIG, ``6`` =WARNING, ``7`` =SEVERE. 이 외의 값( ``0``, ``5`` 포함)은 INFO로 처리) + - (자동) + +.. warning:: + ``spnego.allow.unsecure.basic=true`` 는 Base64로 인코딩된 인증 정보를 암호화되지 않은 연결로 송신할 가능성이 있습니다. + 프로덕션 환경에서는 ``false`` 로 설정하고 HTTPS를 사용할 것을 강력히 권장합니다. + +.. note:: + ``spnego.allow.unsecure.basic=false`` (기본값)인 경우 Basic 인증은 + ``HttpServletRequest#isSecure()`` 가 ``true`` 를 반환하는 요청에만 제공됩니다. + 리버스 프록시에서 TLS를 종료하고 |Fess| 로 HTTP로 전달하는 구성에서는 이 값이 ``false`` 이므로, + Kerberos 티켓을 받지 못해 NTLM으로 대체된 클라이언트는 로그인할 수 없습니다. + ``tomcat_config.properties`` 에서 ``tomcat.secure=true`` 를 설정하여 요청이 HTTPS로 도착했음을 + |Fess| 에 알려 주십시오. 이 파일은 ZIP 버전에서는 ``lib/classes/`` , DEB/RPM 버전에서는 + ``/etc/fess/`` 에 있으며, 변경 후에는 |Fess| 를 재시작해야 합니다. + +.. warning:: + |Fess| 15.10에서는 클라이언트 주체의 영역이 서버의 영역과 다르면 로그인이 기본적으로 거부됩니다. + AD 도메인 트리의 하위 도메인이나 신뢰 관계를 맺은 포리스트의 사용자가 로그인하는 구성에서는 + ``spnego.allowed.realms`` 에 해당 영역을 쉼표로 구분하여 나열하십시오. + 나열하지 않으면 15.7까지 로그인할 수 있었던 사용자가 ``Kerberos realm is not allowed`` 로 + 거부됩니다. + +.. warning:: + |Fess| 는 주체의 ``@`` 앞부분을 사용자 이름으로 사용하므로 사용자 이름에 영역은 포함되지 + 않습니다. ``spnego.allowed.realms`` 에 영역을 추가하면, 여러 영역에 같은 계정 이름을 가진 + 사용자(예: ``alice@CORP.EXAMPLE.COM`` 과 ``alice@PARTNER.EXAMPLE.COM`` )는 동일한 |Fess| + 사용자로 취급되어 해당 사용자의 그룹, 역할, 문서 권한을 공유합니다. + 나열하는 모든 영역에서 계정 이름이 한 사람만 식별하는 경우에만 영역을 추가하십시오. + +.. note:: + 허용 목록은 Basic 인증 폴백에도 적용됩니다. 사용자가 ``user@REALM`` 형식으로 입력한 경우 + 해당 영역이 ``spnego.allowed.realms`` 와 대조되어, 허용되지 않으면 로그인이 거부됩니다. + 단순한 계정 이름이나 ``DOMAIN\user`` 형식은 영역을 지정하지 않으므로 ``krb5.conf`` 의 + 기본 영역에서 인증됩니다. Basic 인증은 사용자가 입력한 영역에 대해 직접 인증하므로 허용 + 목록은 최소한으로 유지하고, 이를 보안 경계로 사용하는 경우에는 ``spnego.allow.basic`` 을 + ``false`` 로 설정하는 것을 검토하십시오. + +.. note:: + ``spnego.prompt.ntlm=true`` (기본값)인 경우, ``spnego.allow.basic`` 도 ``true`` 이어야 합니다. + ``spnego.allow.basic=false`` 로 설정하는 경우에는 ``spnego.prompt.ntlm=false`` 도 함께 설정하십시오. + 이 조건을 충족하지 않으면 SPNEGO 초기화 시 오류가 발생합니다. + +.. note:: + ``spnego.logger.level`` 은 SPNEGO 라이브러리 내부의 로거( ``java.util.logging`` 의 ``Spnego`` 라는 이름의 로거)의 로그 레벨을 제어합니다. + 미설정 시에는 |Fess| 의 로그 레벨에 따라 자동으로 결정됩니다. + +LDAP 설정 +========= + +Windows 통합 인증으로 로그인한 사용자의 그룹 정보를 취득하기 위해 LDAP 설정이 필요합니다. +|Fess| 관리 화면의 「시스템」→「일반」에서 LDAP 설정을 수행합니다. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 항목 + - 설정 예 + * - LDAP URL + - ``ldap://AD-SERVER.example.local:389`` + * - Base DN + - ``dc=example,dc=local`` + * - Bind DN + - ``svc_fess@example.local`` + * - 비밀번호 + - AD 접속용 사용자의 비밀번호 + * - User DN + - ``%s@example.local`` + * - 계정 필터 + - ``(&(objectClass=user)(sAMAccountName=%s))`` + * - memberOf 속성 + - ``memberOf`` + +.. note:: + |Fess| 는 사용자의 ``memberOf`` 속성을 한 단계만 읽으므로 중첩된 그룹(다른 그룹의 멤버인 그룹)은 + 기본적으로 전개되지 않습니다. AD의 중첩 그룹을 반영하려면 관리 화면 「시스템」 → 「일반」의 + 「그룹 필터」( ``ldap.group.filter`` )에 ``(member:1.2.840.113556.1.4.1941:=%s)`` 를 설정하십시오. + 이 전개는 로그인 후 비동기로 실행되므로 감사 로그의 로그인 항목에는 전개 이전의 그룹만 기록됩니다. + +브라우저 설정 +============= + +Windows 통합 인증을 사용하려면 클라이언트 측의 브라우저 설정이 필요합니다. + +Internet Explorer / Microsoft Edge +------------------------------------ + +1. 인터넷 옵션 열기 +2. 「보안」 탭 선택 +3. 「로컬 인트라넷」 영역의 「사이트」 클릭 +4. 「고급」을 클릭하고 Fess의 URL 추가 +5. 「로컬 인트라넷」 영역의 「사용자 지정 수준」 클릭 +6. 「사용자 인증」→「로그온」→「인트라넷 영역에서만 자동으로 로그온」 선택 +7. 「고급」 탭에서 「Windows 통합 인증 사용」 체크 + +Google Chrome +-------------- + +Chrome은 일반적으로 Windows의 인터넷 옵션 설정을 사용합니다. +추가 설정이 필요한 경우 그룹 정책 또는 레지스트리에서 ``AuthServerAllowlist`` 를 설정합니다. + +Mozilla Firefox +---------------- + +1. 주소창에 ``about:config`` 입력 +2. ``network.negotiate-auth.trusted-uris`` 검색 +3. Fess 서버의 URL 또는 도메인 설정(예: ``https://fess-server.example.local``) + +설정 예 +======= + +최소 구성(검증용) +------------------ + +다음은 검증 환경에서의 최소 구성 예입니다. + +``app/WEB-INF/conf/system.properties``: + +:: + + # SSO 활성화 + sso.type=spnego + + # SPNEGO 설정 + spnego.preauth.username=svc_fess + spnego.preauth.password=your-password + +``app/WEB-INF/classes/krb5.conf``: + +:: + + [libdefaults] + default_realm = EXAMPLE.LOCAL + default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + + [realms] + EXAMPLE.LOCAL = { + kdc = AD-SERVER.EXAMPLE.LOCAL + default_domain = EXAMPLE.LOCAL + } + + [domain_realm] + example.local = EXAMPLE.LOCAL + .example.local = EXAMPLE.LOCAL + +``app/WEB-INF/classes/auth_login.conf``: + +:: + + spnego-client { + com.sun.security.auth.module.Krb5LoginModule required; + }; + + spnego-server { + com.sun.security.auth.module.Krb5LoginModule required + storeKey=true + isInitiator=false; + }; + +권장 구성(프로덕션용) +----------------------- + +다음은 프로덕션 환경에서의 권장 구성 예입니다. + +``app/WEB-INF/conf/system.properties``: + +:: + + # SSO 활성화 + sso.type=spnego + + # SPNEGO 설정 + spnego.preauth.username=svc_fess + spnego.preauth.password=your-secure-password + spnego.krb5.conf=krb5.conf + spnego.login.conf=auth_login.conf + + # 보안 설정(프로덕션 환경) + spnego.allow.basic=false + spnego.allow.unsecure.basic=false + spnego.prompt.ntlm=false + spnego.allow.localhost=false + +.. note:: + ``spnego.allow.basic=false`` 로 설정하는 경우에는 ``spnego.prompt.ntlm=false`` 도 반드시 설정하십시오. + ``spnego.prompt.ntlm`` 은 기본값이 ``true`` 이므로, 이 설정을 생략하면 초기화 시 오류가 발생합니다. + +문제 해결 +========= + +자주 발생하는 문제와 해결 방법 +-------------------------------- + +인증 다이얼로그가 표시되는 경우 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- 브라우저 설정에서 Fess 서버가 인트라넷 영역에 추가되어 있는지 확인 +- 「Windows 통합 인증 사용」이 활성화되어 있는지 확인 +- SPN이 올바르게 등록되어 있는지 확인( ``setspn -L <사용자명>`` ) + +인증 오류가 발생하는 경우 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``krb5.conf`` 의 도메인 이름(대문자)과 AD 서버명이 올바른지 확인 +- ``spnego.preauth.username`` 과 ``spnego.preauth.password`` 가 올바른지 확인 +- AD 서버로의 네트워크 연결 확인 + +그룹 정보를 취득할 수 없는 경우 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- LDAP 설정이 올바른지 확인 +- Bind DN과 비밀번호가 올바른지 확인 +- 사용자가 AD에서 그룹에 속해 있는지 확인 + +로그인이 HTTP 400을 반환한다 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +소속 그룹이 많은 사용자는 Kerberos 티켓(PAC)이 커져 ``Authorization`` 헤더가 Tomcat의 기본 상한 +(8KB)을 초과하여 400이 반환될 수 있습니다. +이때 요청은 |Fess| 에 도달하지 않으므로 로그에 아무것도 기록되지 않습니다. +``tomcat_config.properties`` 에서 상한을 늘리십시오. + +:: + + tomcat.maxHttpHeaderSize=65536 + +서비스 계정 비밀번호 변경 후 인증되지 않는다 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +서버 자격 증명은 첫 로그인 시 한 번만 취득되어 프로세스가 종료될 때까지 캐시됩니다. +AD에서 서비스 계정의 비밀번호를 변경했거나 keytab을 교체한 경우에는 |Fess| 를 재시작하십시오. +``spnego.*`` 설정을 변경한 경우에도 마찬가지로 재시작이 필요합니다. + +디버그 설정 +----------- + +문제를 조사하기 위해 SPNEGO 관련 상세 로그를 출력할 수 있습니다. + +SPNEGO 라이브러리 내부의 상세 로그를 출력하려면 ``app/WEB-INF/conf/system.properties`` 에 다음을 추가합니다. +``spnego.logger.level=1`` 은 가장 상세한 로그(FINEST)를 출력합니다. + +:: + + spnego.logger.level=1 + +|Fess| 측의 SPNEGO 연계 처리( ``org.codelibs.fess.sso.spnego`` 패키지)의 상세 로그를 출력하려면 ``app/WEB-INF/classes/log4j2.xml`` 에 다음 로거를 추가합니다. + +:: + + + +.. note:: + SPNEGO 라이브러리 자체의 로그는 ``java.util.logging`` 으로 출력되므로 ``log4j2.xml`` 이 아닌 ``spnego.logger.level`` 로 제어합니다. + |Fess| 측의 연계 처리 로그는 ``log4j2.xml`` 의 로거로 제어합니다. + +참고 정보 +========= + +- :doc:`security-role` - 역할 기반 검색 설정 +- :doc:`sso-saml` - SAML 인증을 통한 SSO 설정 +- :doc:`sso-oidc` - OpenID Connect 인증을 통한 SSO 설정 +- :doc:`sso-entraid` - Microsoft Entra ID를 통한 SSO 설정 diff --git a/ko/15.10/dev/datastore-plugin.rst b/ko/15.10/dev/datastore-plugin.rst new file mode 100644 index 000000000..fe0af674e --- /dev/null +++ b/ko/15.10/dev/datastore-plugin.rst @@ -0,0 +1,524 @@ +================================== +데이터스토어 플러그인 개발 +================================== + +개요 +==== + +데이터스토어 플러그인을 개발하여 |Fess| 에 새로운 데이터 소스로부터 +콘텐츠 취득 기능을 추가할 수 있습니다. 데이터스토어는 데이터베이스·API·파일 등의 +외부 시스템에서 레코드를 취득하고, 관리 화면에서 설정한 매핑 스크립트에 따라 +인덱스 필드로 변환한 다음, |Fess| 의 인덱스에 등록합니다. + +CSV·JSON·데이터베이스·Git·각종 클라우드 서비스 등, 공개되어 있는 +커넥터(``fess-ds-*``)는 모두 이 구조로 구현되어 있습니다. 구현 템플릿으로 +`fess-ds-example `__ 가 공개되어 있으므로, +새로운 커넥터를 작성할 때는 이를 복사해서 시작하는 것이 간단합니다. + +기본 구조 +======== + +데이터스토어 플러그인은 다음 3가지 요소로 구성됩니다. + +- ``AbstractDataStore`` 를 상속한 클래스를 작성한다 +- ``getName()`` 과 ``storeData()`` 두 개의 메서드를 구현한다 +- ``fess_ds++.xml`` 에 컴포넌트로 등록한다 + +최소 구현 +-------- + +.. code-block:: java + + package org.codelibs.fess.ds.example; + + import java.util.Map; + + import org.codelibs.fess.ds.AbstractDataStore; + import org.codelibs.fess.ds.callback.IndexUpdateCallback; + import org.codelibs.fess.entity.DataStoreParams; + import org.codelibs.fess.opensearch.config.exentity.DataConfig; + + public class ExampleDataStore extends AbstractDataStore { + + @Override + protected String getName() { + // 핸들러 이름으로 사용된다. 클래스의 단순 이름을 반환하는 것이 관례 + return this.getClass().getSimpleName(); + } + + @Override + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { + + // 데이터 취득 및 처리를 여기에 구현 + } + } + +.. note:: + + ``getName()`` 과 ``storeData()`` 는 모두 ``protected`` 추상 메서드입니다. + ``DataConfig`` 의 패키지는 |Fess| 15.x 에서는 ``org.codelibs.fess.opensearch.config.exentity`` + 임에 유의하십시오(이전의 ``org.codelibs.fess.es.config.exentity`` 는 폐지되었습니다). + +컴포넌트 등록 +-------------------- + +작성한 데이터스토어를 |Fess| 가 인식하도록 하기 위해, ``src/main/resources/fess_ds++.xml`` 에 +컴포넌트를 등록합니다. + +.. code-block:: xml + + + + + + + + + +```` 에 의해 컴포넌트 생성 후 ``AbstractDataStore`` +가 가진 ``register()`` 메서드가 자동으로 호출되어 ``DataStoreFactory`` 에 자신이 등록됩니다. +이때 등록되는 이름이 ``getName()`` 의 반환값(위 예에서는 ``ExampleDataStore``)이며, +관리 화면의 데이터스토어 설정에서 선택하는 「핸들러 이름」이 됩니다. + +AbstractDataStore +================= + +주요 메서드 +------------ + +.. list-table:: + :header-rows: 1 + :widths: 35 20 45 + + * - 메서드 + - 구분 + - 설명 + * - ``getName()`` + - 구현(필수) + - 데이터스토어의 핸들러 이름을 반환하는 추상 메서드. ``getClass().getSimpleName()`` 을 반환하는 것이 관례 + * - ``storeData()`` + - 구현(필수) + - 데이터의 취득·변환·인덱스 등록을 수행하는 추상 메서드 + * - ``register()`` + - 상속(통상 변경 불필요) + - ``fess_ds++.xml`` 의 ``postConstruct`` 에서 자동으로 호출되어 ``DataStoreFactory`` 에 등록한다 + * - ``store()`` + - 상속(프레임워크 호출) + - 프레임워크가 호출하는 진입점. ``defaultDataMap`` 등을 준비하여 ``storeData()`` 를 호출한다 + * - ``convertValue()`` + - 상속(헬퍼) + - ``scriptMap`` 의 값(템플릿)을 스크립트 엔진으로 평가한다 + * - ``getScriptType()`` + - 상속(헬퍼) + - ``script_type`` 파라미터를 취득한다(기본값은 Groovy) + * - ``getReadInterval()`` + - 상속(헬퍼) + - ``readInterval`` 파라미터(밀리초)를 취득한다 + * - ``sleep()`` + - 상속(헬퍼) + - 지정한 밀리초만큼 대기한다(레코드 간 대기에 사용) + +storeData의 파라미터 +------------------------ + +``storeData()`` 메서드에 전달되는 파라미터: + +.. list-table:: + :header-rows: 1 + :widths: 25 35 40 + + * - 파라미터 + - 타입 + - 설명 + * - ``dataConfig`` + - ``DataConfig`` + - 데이터스토어 설정(ID·핸들러 이름·파라미터·스크립트 등) + * - ``callback`` + - ``IndexUpdateCallback`` + - 생성한 문서를 인덱스에 등록하는 콜백 + * - ``paramMap`` + - ``DataStoreParams`` + - 관리 화면 「파라미터」란의 설정값. ``getAsString(key)`` / ``getAsString(key, default)`` / ``get(key)`` / ``asMap()`` / ``containsKey(key)`` 로 접근한다 + * - ``scriptMap`` + - ``Map`` + - 관리 화면 「스크립트」란의 설정. 키가 인덱스 필드 이름, 값이 평가 대상 스크립트 템플릿 + * - ``defaultDataMap`` + - ``Map`` + - 각 문서의 기본 필드 값(설정 ID·boost·role·mimetype·가상 호스트 등). 프레임워크가 준비한다 + +.. warning:: + + ``paramMap`` 의 타입은 ``Map`` 이 아니라 ``DataStoreParams`` 입니다. + ``DataStoreParams`` 는 ``Map`` 을 구현하지 않으므로, 값을 가져올 때는 ``get()`` 이 아니라 + 문자열을 반환하는 ``getAsString()`` 을 사용하십시오. + +데이터 처리 흐름 +---------------- + +``storeData()`` 구현은 다음 흐름으로 데이터를 처리합니다. + +#. 외부 시스템에서 소스 레코드를 취득한다. +#. ``paramMap.asMap()`` 에 소스 레코드의 필드를 병합하여 ``resultMap`` 을 구축한다 + (스크립트는 이 ``resultMap`` 에 대해 평가된다). +#. ``scriptMap`` 의 각 엔트리를 ``convertValue(scriptType, template, resultMap)`` 로 평가하여 + 결과를 ``dataMap`` 에 저장한다. 매핑을 코드 안에 하드코딩하는 것이 아니라 + 관리자가 「스크립트」란에서 정의한다는 점이 중요합니다. +#. ``callback.store(paramMap, dataMap)`` 을 호출하여 문서로 인덱스에 등록한다. + +구현 예 +====== + +심플한 데이터스토어 +---------------------- + +외부 API 에서 레코드를 취득하여 인덱스에 등록하는 예입니다. + +.. code-block:: java + + @Override + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { + + // 파라미터 취득(DataStoreParams 에서는 getAsString 을 사용한다) + final String apiUrl = paramMap.getAsString("api.url"); + final String apiKey = paramMap.getAsString("api.key"); + + // 스크립트 평가 타입(기본값은 Groovy) + final String scriptType = getScriptType(paramMap); + // 레코드 간 대기 시간(밀리초) + final long readInterval = getReadInterval(paramMap); + + try { + // 외부 시스템에서 데이터 취득 + final List> records = fetchRecords(apiUrl, apiKey); + + for (final Map record : records) { + // 기본 필드를 복사하여 dataMap 초기화 + final Map dataMap = new HashMap<>(defaultDataMap); + + // 파라미터와 소스 레코드를 병합한 resultMap 구축 + // (스크립트는 이 resultMap 에 대해 평가된다) + final Map resultMap = new LinkedHashMap<>(paramMap.asMap()); + resultMap.putAll(record); + + // scriptMap 의 각 엔트리를 평가하여 인덱스 필드 생성 + for (final Map.Entry entry : scriptMap.entrySet()) { + final Object value = convertValue(scriptType, entry.getValue(), resultMap); + if (value != null) { + dataMap.put(entry.getKey(), value); + } + } + + // 인덱스에 등록 + callback.store(paramMap, dataMap); + + if (readInterval > 0) { + sleep(readInterval); + } + } + } catch (final Exception e) { + throw new DataStoreException("Failed to crawl data from " + apiUrl, e); + } + } + +``fetchRecords()`` 는 외부 시스템에서 레코드 목록을 취득하는 자체 메서드입니다. 취득한 +각 레코드(``Map``)의 필드 이름이, ``scriptMap`` 의 스크립트에서 +참조할 수 있는 이름이 됩니다. ``DataStoreException`` 은 ``org.codelibs.fess.exception`` +패키지의 클래스입니다. + +페이지네이션 대응 +-------------------- + +대량의 데이터를 다루는 경우에는 페이지 단위로 취득하면서 처리합니다. 레코드 1건당 처리 +(``resultMap`` 구축·``scriptMap`` 평가·``callback.store()`` 호출)를 +``processRecord()`` 와 같은 메서드로 분리해두면 취득 로직과 분리할 수 있습니다. + +.. code-block:: java + + int offset = 0; + final int pageSize = 100; + + while (true) { + final List> records = fetchRecords(apiUrl, apiKey, offset, pageSize); + + if (records.isEmpty()) { + break; + } + + for (final Map record : records) { + processRecord(record, callback, paramMap, scriptMap, defaultDataMap); + } + + offset += pageSize; + } + +인증 구현 +========== + +외부 시스템의 인증은 커넥터 측에서 구현합니다. 아래는 일반적인 HTTP 클라이언트 +라이브러리를 사용한 구현 예시로, |Fess| 가 제공하는 API 는 아닙니다. 사용할 라이브러리는 +플러그인의 의존 관계로 함께 포함시켜 주십시오. + +OAuth 2.0 +--------- + +.. code-block:: java + + protected String getAccessToken(final String clientId, final String clientSecret, final String refreshToken) { + // 리프레시 토큰을 이용해 액세스 토큰을 취득하는 예 + final OkHttpClient client = new OkHttpClient(); + + final RequestBody body = new FormBody.Builder() + .add("grant_type", "refresh_token") + .add("client_id", clientId) + .add("client_secret", clientSecret) + .add("refresh_token", refreshToken) + .build(); + + final Request request = new Request.Builder() + .url("https://oauth.example.com/token") + .post(body) + .build(); + + try (Response response = client.newCall(request).execute()) { + final JsonNode json = objectMapper.readTree(response.body().string()); + return json.get("access_token").asText(); + } + } + +API 키 인증 +----------- + +.. code-block:: java + + protected Response callApi(final String url, final String apiKey) { + final Request request = new Request.Builder() + .url(url) + .addHeader("Authorization", "Bearer " + apiKey) + .build(); + + return httpClient.newCall(request).execute(); + } + +오류 처리 +================== + +처리를 중단해야 하는 치명적인 오류에서는 ``DataStoreException`` 을 던집니다. + +.. code-block:: java + + @Override + protected void storeData(...) { + try { + // 처리 + } catch (final AuthenticationException e) { + logger.error("Authentication failed. Check your credentials.", e); + throw new DataStoreException("Authentication failed", e); + } catch (final RateLimitException e) { + logger.warn("Rate limit exceeded. Waiting..."); + sleep(60000L); + // 재시도 로직 + } catch (final Exception e) { + logger.error("Unexpected error occurred", e); + throw new DataStoreException("Failed to crawl data", e); + } + } + +.. note:: + + ``fess-ds-example`` 을 비롯한 실제 커넥터에서는 레코드 1건의 오류로 + 크롤링 전체가 중단되지 않도록, 레코드 단위로 ``CrawlingAccessException`` 을 포착하여 + ``FailureUrlService`` 에 오류 URL 을 기록합니다. 또한 + ``DataStoreCrawlingException`` 의 중단 플래그를 사용하여, 크롤링 전체를 중단할지 여부를 + 제어합니다. 견고한 커넥터를 구현하려는 경우에는 ``ExampleDataStore`` 의 구현을 참조하십시오. + +테스트 +====== + +유닛 테스트 +-------------- + +|Fess| 의 플러그인은 UTFlute 의 ``LastaDiTestCase`` 를 사용하여 테스트합니다. 테스트는 +JUnit 5(Jupiter)로 작성합니다. ``IndexUpdateCallback`` 을, 등록된 ``dataMap`` 을 +수집하는 구현으로 교체함으로써, 목(mock) 라이브러리를 사용하지 않고도 매핑 결과를 검증할 수 있습니다. + +.. code-block:: java + + public class ExampleDataStoreTest extends LastaDiTestCase { + + public ExampleDataStore dataStore; + + @Override + protected String prepareConfigFile() { + return "test_app.xml"; + } + + @Override + public void setUp(final TestInfo testInfo) throws Exception { + super.setUp(testInfo); + dataStore = new ExampleDataStore(); + } + + @Test + public void test_getName() { + assertEquals("ExampleDataStore", dataStore.getName()); + } + + @Test + public void test_storeData() { + final TestIndexUpdateCallback callback = new TestIndexUpdateCallback(); + final DataStoreParams paramMap = new DataStoreParams(); + + final Map scriptMap = new HashMap<>(); + scriptMap.put("title", "title"); + + dataStore.storeData(new DataConfig(), callback, paramMap, scriptMap, new HashMap<>()); + + assertFalse(callback.getDataMapList().isEmpty()); + } + + // 등록된 dataMap 을 수집하는 테스트용 콜백 + private static class TestIndexUpdateCallback implements IndexUpdateCallback { + private final List> dataMapList = new ArrayList<>(); + + @Override + public void store(final DataStoreParams paramMap, final Map dataMap) { + dataMapList.add(new HashMap<>(dataMap)); + } + + @Override + public long getExecuteTime() { + return 0; + } + + @Override + public long getDocumentSize() { + return dataMapList.size(); + } + + @Override + public void commit() { + // 아무것도 하지 않음 + } + + public List> getDataMapList() { + return dataMapList; + } + } + } + +.. note:: + + ``setUp`` 은 기반 클래스에서 ``@BeforeEach`` 가 부여되어 있으므로, 오버라이드하는 쪽에 + 라이프사이클 애너테이션을 다시 붙일 필요가 없습니다. 각 테스트 메서드에는 + ``@Test``\ (``org.junit.jupiter.api.Test``)를 부여합니다. + +빌드와 설치 +==================== + +pom.xml +------- + +플러그인은 ``fess-parent`` 를 부모 POM 으로 하는 jar 로 빌드합니다. ``fess`` 및 +``opensearch`` 에 대한 의존성은 실행 시 |Fess| 본체에서 제공되므로 ``provided`` 로 설정합니다. + +.. code-block:: xml + + + 4.0.0 + org.codelibs.fess + fess-ds-example + 15.10.0 + jar + + + org.codelibs.fess + fess-parent + 15.10.0 + + + + + + org.codelibs.fess + fess + provided + + + org.opensearch + opensearch + provided + + + + +테스트에는 JUnit 5 와 ``org.dbflute.utflute:utflute-lastaflute`` 를 사용합니다. + +빌드 +------ + +.. code-block:: bash + + mvn clean package + +``target/`` 디렉터리에 ``fess-ds-example-15.10.0.jar`` 가 생성됩니다. + +설치 +------------ + +생성한 JAR 를 |Fess| 에 설치하고 |Fess| 를 재시작합니다. 설치 절차의 자세한 내용은 +:doc:`../admin/plugin-guide` 를 참조하십시오. 설치 후 관리 화면의 +「크롤러 > 데이터스토어」에서 신규 설정을 작성하고, 「핸들러 이름」에 ``getName()`` 이 반환하는 이름 +(이 예에서는 ``ExampleDataStore``)을 지정합니다. + +설정 예 +====== + +관리 화면에서의 설정 예: + +파라미터 +------------ + +「파라미터」란에는 커넥터가 ``paramMap`` 에서 읽어들이는 키와 값을 기술합니다. + +:: + + api.url=https://api.example.com/v1 + api.key=your_api_key + +스크립트 +---------- + +「스크립트」란에는 ``좌변=우변`` 형식으로 매핑을 기술합니다. 좌변이 인덱스 +필드 이름, 우변이 소스 레코드의 필드를 참조하는 스크립트(신규 작성되는 설정에서는 +JavaScript. 스크립트 타입이 기록되어 있지 않은 설정은 Groovy로 취급됩니다)입니다. +아래는 소스 레코드가 ``url`` / ``title`` / ``content`` / ``updated_at`` / +``content_type`` 필드를 가지고 있는 경우의 예입니다. + +:: + + url=url + title=title + content=content + last_modified=updated_at + mimetype=content_type + +.. note:: + + 우변에서 참조할 수 있는 필드 이름은 커넥터가 ``resultMap`` 에 저장하는 값 + (``paramMap`` 의 값과 소스 레코드의 필드)에 따라 결정됩니다. CSV 나 JSON 등 + 기존 커넥터에서는 ``data.*`` 와 같은 독자적인 프리픽스가 붙는 경우가 있으므로, + 각 커넥터의 문서를 참조하십시오. + +참고 정보 +======== + +- :doc:`plugin-architecture` - 플러그인 아키텍처 +- :doc:`../admin/plugin-guide` - 플러그인 설치 +- :doc:`../config/datastore/ds-overview` - 데이터스토어 커넥터 개요 +- `fess-ds-example `__ - 데이터스토어 플러그인 구현 템플릿 +- `GitHub: fess-ds-* `__ - 공개 커넥터 예시 diff --git a/ko/15.10/dev/index.rst b/ko/15.10/dev/index.rst new file mode 100644 index 000000000..24f70e798 --- /dev/null +++ b/ko/15.10/dev/index.rst @@ -0,0 +1,27 @@ +================================== +|Fess| 개발자 문서 +================================== + +|Fess| 의 확장 개발에 관한 문서입니다. + +.. toctree:: + :maxdepth: 2 + :caption: 개요 + + overview + +.. toctree:: + :maxdepth: 2 + :caption: 플러그인 개발 + + plugin-architecture + datastore-plugin + script-engine-plugin + webapp-plugin + ingest-plugin + +.. toctree:: + :maxdepth: 2 + :caption: 커스터마이즈 + + theme-development diff --git a/ko/15.10/dev/ingest-plugin.rst b/ko/15.10/dev/ingest-plugin.rst new file mode 100644 index 000000000..3dfda7927 --- /dev/null +++ b/ko/15.10/dev/ingest-plugin.rst @@ -0,0 +1,162 @@ +================================== +Ingest 플러그인 +================================== + +개요 +==== + +Ingest 플러그인은 문서가 인덱스에 등록되기 직전에 +데이터를 가공·변환하는 기능을 제공합니다. 크롤링으로 수집한 각 문서는, +인덱스로 전송되기 전에 등록된 Ingester를 통과합니다. + +용도 +==== + +- 텍스트 정규화(전각/반각 변환, 공백 정리 등) +- 메타데이터나 커스텀 필드 추가 +- 민감한 정보 마스킹 +- 값 변환(예: 인코딩된 벡터 임베딩 디코딩) + +Ingester 클래스 +=============== + +Ingest 기능은 ``org.codelibs.fess.ingest.Ingester`` 추상 클래스를 상속하여 +구현합니다. ``Ingester``\ 에는 크롤링 종류나 처리 단계에 따라 +호출되는 ``process`` 메서드가 준비되어 있습니다. 기본 구현은 +모두 전달받은 ``target``\ 을 그대로 반환(아무 작업도 하지 않음)하므로, +필요한 메서드만 오버라이드합니다. + +- ``protected Map process(Map target)`` + + 두 ``Map`` 버전 메서드가 공통으로 위임하는 대상입니다. 이 메서드를 오버라이드하면 + 데이터 스토어 크롤링과 Web/파일 크롤링(인덱스 등록 시) 양쪽 문서에 모두 적용됩니다. + 대부분의 용도에서는 이 메서드만 오버라이드하면 충분합니다. + +- ``public Map process(Map target, DataStoreParams params)`` + + 데이터 스토어 크롤링 시 호출됩니다. 기본적으로 + ``process(target)``\ 에 위임합니다. + +- ``public Map process(Map target, AccessResult accessResult)`` + + Web/파일 크롤링의 인덱스 등록 시 호출됩니다. + 기본적으로 ``process(target)``\ 에 위임합니다. + +- ``public ResultData process(ResultData target, ResponseData responseData)`` + + Web/파일 크롤링의 응답 처리 시(액세스 결과를 저장하기 전)에 + 호출됩니다. 기본적으로 ``target``\ 을 그대로 반환합니다. + +실행 순서(priority) +-------------------- + +여러 Ingester가 등록되어 있는 경우 ``priority`` 필드의 오름차순 +(값이 작은 것이 먼저)으로 실행됩니다. 기본값은 ``99``\ 입니다. +생성자에서 직접 설정하거나 ``setPriority(int)``\ 로 변경할 수 있습니다. + +.. code-block:: java + + public int getPriority() + public void setPriority(final int priority) + +구현 예시 +====== + +``process(Map)``\ 를 오버라이드하여 콘텐츠를 정규화하고 +커스텀 필드를 추가하는 예시입니다: + +.. code-block:: java + + package org.codelibs.fess.ingest.example; + + import java.util.Map; + + import org.codelibs.fess.ingest.Ingester; + + public class ExampleIngester extends Ingester { + + public ExampleIngester() { + // 실행 순서를 설정(값이 작을수록 먼저 실행됨. 기본값은 99) + setPriority(50); + } + + @Override + protected Map process(final Map target) { + // 콘텐츠 정규화 + final Object content = target.get("content"); + if (content instanceof String) { + target.put("content", ((String) content).trim().replaceAll("\\s+", " ")); + } + + // 커스텀 필드 추가 + target.put("ingested_by", ExampleIngester.class.getSimpleName()); + + // 가공한 문서를 반환 + return target; + } + } + +.. note:: + + ``process`` 메서드에서 ``null``\ 을 반환하면 인덱스 등록이 실패합니다. + 문서를 건너뛰는 방법은 없으므로 반드시 ``target``\ 을 반환해야 합니다. + +등록 +==== + +Ingester는 DI 컨테이너를 통해 등록합니다. 플러그인에는 ``fess_ingest++.xml`` +을 포함합니다. 파일명 끝의 ``++``\ 는 |Fess| 본체의 ``fess_ingest.xml`` +(Ingester를 관리하는 ``ingestFactory``\ 를 정의)에 설정을 추가하는 병합 규칙입니다. + +.. code-block:: xml + + + + + + + + + +````\ 에 의해 컴포넌트 생성 후 +``Ingester#register()``\ 가 호출되어 ``ingestFactory``\ 에 자신이 등록됩니다. + +Ingest 기능과 관련된 ``fess_config.properties`` 설정 항목은 없습니다. +활성화 여부는 플러그인 도입 여부로, 실행 순서는 ``priority``\ 로 제어합니다. + +실행 흐름 +========== + +Ingester는 가공된 문서가 인덱스로 전송되기 직전에, +다음 위치에서 ``priority`` 오름차순으로 호출됩니다: + +- **데이터 스토어 크롤링**: 문서를 전송하기 직전에 + ``process(Map, DataStoreParams)``\ 가 호출됩니다. +- **Web/파일 크롤링(응답 처리 시)**: 크롤링 결과를 저장하기 전에 + ``process(ResultData, ResponseData)``\ 가 호출됩니다. +- **Web/파일 크롤링(인덱스 등록 시)**: 문서를 전송하기 직전에 + ``process(Map, AccessResult)``\ 가 호출됩니다. + +어느 위치에서든 특정 Ingester가 예외를 던지면 경고 로그를 출력하고 +처리를 계속합니다(해당 문서의 인덱스 등록은 중단되지 않습니다). + +.. note:: + + Ingester는 크롤러 실행 환경(``ingestFactory``)에 등록되므로 + 크롤링 처리의 일부로 동작합니다. + +참고 구현 +======== + +구현 참고 자료로 다음 플러그인이 GitHub의 +`CodeLibs `__ 에 공개되어 있습니다: + +- ``fess-ingest-example`` - 최소 구성의 샘플 구현 +- ``fess-webapp-multimodal`` - 벡터 임베딩을 디코딩하는 ``EmbeddingIngester``\ 를 포함하는 플러그인 + +참고 정보 +======== + +- :doc:`plugin-architecture` - 플러그인 아키텍처 diff --git a/ko/15.10/dev/overview.rst b/ko/15.10/dev/overview.rst new file mode 100644 index 000000000..6d2ad6f07 --- /dev/null +++ b/ko/15.10/dev/overview.rst @@ -0,0 +1,236 @@ +================================== +개발자 문서 개요 +================================== + +개요 +==== + +이 섹션에서는 |Fess| 의 확장 개발에 대해 설명합니다. +플러그인 개발, 커스텀 커넥터 작성, 테마 커스터마이즈 등 +|Fess| 를 확장하기 위한 정보를 제공합니다. + +대상 독자 +========== + +- |Fess| 의 커스텀 기능을 개발하고 싶은 개발자 +- 플러그인을 작성하고 싶은 개발자 +- |Fess| 의 소스 코드를 이해하고 싶은 개발자 + +필요 지식 +---------- + +- Java 21의 기본적인 지식 +- Maven(빌드 시스템)의 기본 +- 웹 애플리케이션 개발 경험 +- OpenSearch에 대한 기본적인 지식(|Fess| 는 검색 엔진으로 OpenSearch를 사용합니다) + +개발 환경 +========== + +권장 환경 +---------- + +- **JDK**: OpenJDK 21 이상 +- **IDE**: IntelliJ IDEA / Eclipse / VS Code +- **빌드 도구**: Maven(빌드에서 최소 버전이 강제되지는 않지만, Java 21에 대응하는 최신 3.x를 권장) +- **Git**: 버전 관리 +- **OpenSearch**: 검색 엔진의 백엔드(IDE에서 실행하는 경우, 필요한 모듈과 플러그인은 빌드 시 다운로드됩니다) + +설정 +------------ + +|Fess| 는 Maven 프로젝트로 빌드합니다. 개발 시에는 IDE에서 실행하는 것이 가장 간단합니다. + +1. 소스 코드 취득: + + :: + + git clone https://github.com/codelibs/fess.git + +2. IDE로 임포트: + + 취득한 디렉토리를 Maven 프로젝트로 IDE에 임포트합니다. + +3. OpenSearch용 모듈·플러그인 다운로드: + + 최초 한 번만 다음 명령으로 검색 엔진의 모듈과 플러그인을 ``plugins`` 디렉토리에 취득합니다. + + :: + + mvn antrun:run + +4. 개발 서버 시작(IDE에서): + + IDE에서 ``org.codelibs.fess.FessBoot`` 를 실행 또는 디버그 실행하고, + 브라우저에서 http://localhost:8080/ 을 엽니다. + 관리 화면은 http://localhost:8080/admin/ (초기 계정: ``admin`` / ``admin``)입니다. + +5. 패키지 빌드(배포물 생성): + + 배포 패키지가 필요한 경우 ``package`` 골을 실행합니다. + 결과물은 ``target/releases`` 에 생성됩니다(유닛 테스트를 건너뛰려면 ``-DskipTests`` 를 지정). + + :: + + mvn package + + 생성된 배포물을 압축 해제하면 ``bin/fess`` 실행 스크립트를 사용할 수 있습니다. + + :: + + unzip target/releases/fess-*.zip + ./fess-*/bin/fess + +.. note:: + + ``bin/fess`` 실행 스크립트는 배포 패키지(zip/rpm/deb)에 포함되어 있는 것입니다. + 소스 트리에서 ``mvn package`` 를 실행하는 것만으로는 저장소 바로 아래에 ``bin/fess`` 가 생성되지 않습니다. + 소스에서 개발할 때는 위와 같이 IDE에서 ``FessBoot`` 를 실행하거나, + 압축을 해제한 배포물의 ``bin/fess`` 를 사용하세요. + +아키텍처 개요 +================== + +|Fess| 는 다음의 주요 컴포넌트로 구성되어 있습니다: + +컴포넌트 구성 +------------------ + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - 컴포넌트 + - 설명 + * - Web층 + - LastaFlute 프레임워크에 의한 MVC 구현 + * - 서비스층 + - 비즈니스 로직 + * - 데이터 액세스층 + - DBFlute(ESFlute/FreeGen)에 의한 타입 세이프 OpenSearch 액세스 + * - 크롤러 + - fess-crawler 라이브러리에 의한 콘텐츠 수집 + * - 검색 엔진 + - OpenSearch에 의한 전문 검색 + +주요 프레임워크 +------------------ + +- **LastaFlute**: 웹 프레임워크(액션, 폼, 밸리데이션) +- **DBFlute**: 데이터 액세스 프레임워크. OpenSearch용 타입 세이프 액세스 클래스(``Bhv`` / ``ConditionBean``)는 + DBFlute의 FreeGen 기능과 ESFlute 템플릿에 의해 생성됩니다 + (재생성은 ``mvn dbflute:freegen``) +- **Lasta Di**: 의존성 주입 컨테이너 + +디렉토리 구조 +================ + +:: + + fess/ + ├── src/main/java/org/codelibs/fess/ + │ ├── app/ + │ │ ├── web/ # 컨트롤러(Action) + │ │ ├── service/ # 서비스 + │ │ ├── logic/ # 로직 + │ │ └── pager/ # 페이지네이션 + │ ├── api/ # REST API(api/v2 등) + │ ├── helper/ # 헬퍼 클래스 + │ ├── crawler/ # 크롤러 관련 + │ ├── indexer/ # 인덱스 처리 + │ ├── opensearch/ # OpenSearch 액세스(ESFlute/FreeGen 생성) + │ ├── llm/ # LLM 통합 + │ ├── ds/ # 데이터스토어 커넥터 + │ ├── ingest/ # Ingest(인덱싱 시 데이터 가공) + │ ├── script/ # 스크립트 엔진 + │ ├── entity/ # 엔티티 + │ └── mylasta/ # LastaFlute 설정(DI·메시지·타입 세이프 설정) + ├── src/main/resources/ + │ ├── fess_config.properties # 설정 + │ └── fess_*.xml # DI 설정(app.xml, fess_ds.xml 등) + └── src/main/webapp/ + └── WEB-INF/view/ # 관리 화면과 로그인 화면의 JSP + +확장 포인트 +============ + +|Fess| 는 다음의 확장 포인트를 제공합니다: + +플러그인 +---------- + +플러그인을 사용하여 기능을 추가할 수 있습니다. + +- **데이터스토어 플러그인**: 새로운 데이터 소스로부터의 크롤링(``AbstractDataStore`` 를 상속) +- **스크립트 엔진 플러그인**: 새로운 스크립트 언어 지원(``ScriptEngine`` 을 구현) +- **웹앱 플러그인**: 웹 인터페이스 확장(Lasta Di의 컴포넌트 오버라이드와 리소스 병합) +- **Ingest 플러그인**: 인덱싱 시 데이터 가공(``Ingester`` 를 상속) + +상세: :doc:`plugin-architecture` + +.. note:: + + |Fess| 본체는 ``war`` 로 패키징됩니다. 플러그인을 로컬에서 빌드할 때 + |Fess| 를 의존성으로 해결할 수 없는 경우에는, ``pom.xml`` 의 ```` 을 일시적으로 ``jar`` 로 변경하여 + ``mvn clean install -DskipTests`` 를 실행한 후, ``war`` 로 되돌리세요. + +테마 +------ + +검색 화면의 디자인을 커스터마이즈할 수 있습니다. + +상세: :doc:`theme-development` + +설정 +---- + +``fess_config.properties`` 에서 다양한 동작을 커스터마이즈할 수 있습니다. + +상세: :doc:`../config/intro` + +플러그인 개발 +============== + +플러그인 개발의 상세에 대해서는 다음을 참조하세요: + +- :doc:`plugin-architecture` - 플러그인 아키텍처 +- :doc:`datastore-plugin` - 데이터스토어 플러그인 개발 +- :doc:`script-engine-plugin` - 스크립트 엔진 플러그인 +- :doc:`webapp-plugin` - 웹앱 플러그인 +- :doc:`ingest-plugin` - Ingest 플러그인 + +테마 개발 +========== + +- :doc:`theme-development` - 테마 커스터마이즈 + +베스트 프랙티스 +================== + +코딩 규약 +---------------- + +- |Fess| 의 기존 코드 스타일을 따름 +- ``mvn formatter:format`` 으로 코드 포맷 +- ``mvn license:format`` 으로 라이선스 헤더 추가 + +테스트 +------ + +- 유닛 테스트(``*Test.java``): 기본 ``build`` 프로파일에서 ``mvn test`` 로 실행됩니다 +- 통합 테스트(``*Tests.java``): ``mvn test -P integrationTests`` 로 실행됩니다. + 통합 테스트를 실행하려면 실행 중인 |Fess| 서버와 OpenSearch가 필요합니다 + +로깅 +-------- + +- Log4j2 사용 +- ``logger.debug()`` / ``logger.info()`` / ``logger.warn()`` / ``logger.error()`` +- 민감한 정보는 로그에 출력하지 않음 + +리소스 +======== + +- `GitHub Repository `__ +- `Issue Tracker `__ +- `Discussions `__ diff --git a/ko/15.10/dev/plugin-architecture.rst b/ko/15.10/dev/plugin-architecture.rst new file mode 100644 index 000000000..02f80b062 --- /dev/null +++ b/ko/15.10/dev/plugin-architecture.rst @@ -0,0 +1,367 @@ +================================== +플러그인 아키텍처 +================================== + +개요 +==== + +|Fess| 의 플러그인 시스템을 통해 코어 기능을 확장할 수 있습니다. +플러그인은 JAR 파일로 배포되며, 클래스패스에 추가되면 DI 컨테이너 +(Lasta Di)에 의해 컴포넌트가 로드되어 해당 팩토리나 매니저에 +등록됩니다. + +플러그인 종류 +================ + +|Fess| 는 아티팩트 이름의 프리픽스로 플러그인의 종류를 +판별합니다(``PluginHelper.ArtifactType``). 주요 종류는 다음과 같습니다: + +.. list-table:: + :header-rows: 1 + :widths: 20 25 55 + + * - 종류 + - 프리픽스 + - 설명 + * - 데이터스토어 + - ``fess-ds-*`` + - 새로운 데이터 소스로부터의 콘텐츠 취득(Box, Slack, Git 등) + * - 웹앱 + - ``fess-webapp-*`` + - 웹 인터페이스나 검색 기능의 확장 + * - 스크립트 엔진 + - ``fess-script-*`` + - 새로운 스크립트 언어 지원 + * - Ingest + - ``fess-ingest-*`` + - 인덱스 등록 시 문서 가공 + * - 썸네일 + - ``fess-thumbnail-*`` + - 썸네일 생성 방식 추가 + * - LLM + - ``fess-llm-*`` + - RAG/채팅에서 사용하는 LLM 프로바이더 추가 + * - 크롤러 + - ``fess-crawler-*`` + - 크롤러 클라이언트 확장 + * - 스토리지 + - ``fess-storage-*`` + - 크롤링과 스토리지 기능에서 사용하는 객체 스토리지 백엔드 추가 + * - SSO + - ``fess-sso-*`` + - ``sso.type`` 으로 선택되는 싱글 사인온 인증 방식 추가 + +.. note:: + + JSP 를 제공하는 ``fess-theme-*`` (JAR 테마) 종류는 15.10 에서 삭제되었습니다. + 검색 화면의 외관은 플러그인이 아니라 정적 테마로 변경합니다(:doc:`theme-development` 참조). + +플러그인 구조 +============== + +기본 구조 +--------- + +데이터스토어 플러그인의 구현 템플릿인 +`fess-ds-example `__ 를 예로 들면, +플러그인은 「구현 클래스」와 「DI 등록 파일」로 구성됩니다: + +:: + + fess-ds-example/ + ├── pom.xml + └── src/main/ + ├── java/org/codelibs/fess/ds/example/ + │ └── ExampleDataStore.java # 데이터스토어 구현 + └── resources/ + └── fess_ds++.xml # DI 컴포넌트 등록 + +pom.xml 예제 +------------ + +플러그인은 ``fess-parent`` 를 부모 POM 으로 하는 jar 로 빌드합니다. +``fess`` 나 ``opensearch`` 등, 실행 시 |Fess| 본체에서 제공되는 라이브러리는 +``provided`` 스코프로 선언합니다. 버전 번호나 빌드 설정(포맷터· +라이선스 헤더 등)은 부모 POM 에서 상속됩니다. + +.. code-block:: xml + + + + 4.0.0 + + org.codelibs.fess + fess-ds-example + 15.10.0 + jar + + + org.codelibs.fess + fess-parent + 15.10.0 + + + + + + org.codelibs.fess + fess + provided + + + org.opensearch + opensearch + provided + + + + +.. note:: + + 개발 중인 브랜치에서는 버전이 ``15.10.0-SNAPSHOT`` 처럼 ``-SNAPSHOT`` 이 붙은 + 형태가 됩니다. 플러그인 고유의 의존 라이브러리는 일반적인 Maven 의존 관계로 + 선언합니다. 이들은 |Fess| 본체에는 포함되지 않으므로, 플러그인과 함께 배포해야 합니다. + +플러그인 등록 +================ + +DI 컨테이너 등록 +------------------ + +플러그인은 ``fess_ds++.xml`` 처럼 끝이 ``++`` 로 끝나는 DI 설정 파일로 +컴포넌트를 등록합니다. Lasta Di 는 클래스패스 상에서 발견한 ``++`` 가 붙은 +파일을, |Fess| 본체의 대응하는 설정 파일(이 예에서는 ``fess_ds.xml``)에 +자동으로 병합합니다. 이 구조를 통해 플러그인은 |Fess| 본체의 파일을 +수정하지 않고도 자신의 컴포넌트를 추가할 수 있습니다. + +.. code-block:: xml + + + + + + + + + +플러그인 종류마다 병합 대상 파일이 다릅니다. 예를 들어 스크립트 엔진은 +``fess_se++.xml``, Ingest 는 ``fess_ingest++.xml``, LLM 프로바이더는 +``fess_llm++.xml``, 웹앱은 ``app++.xml`` 을 사용합니다. + +컴포넌트 초기화 +---------------------- + +```` 는 컴포넌트 생성 후에 호출할 +메서드를 지정하는 Lasta Di 의 라이프사이클 설정입니다. 데이터스토어의 경우, +``AbstractDataStore`` 가 가진 ``register()`` 메서드가 호출되어 +자신이 ``DataStoreFactory`` 에 등록됩니다: + +.. code-block:: java + + // AbstractDataStore 의 구현(통상 오버라이드 불필요) + public void register() { + ComponentUtil.getDataStoreFactory().add(getName(), this); + } + +.. note:: + + 이것은 Java 의 ``@PostConstruct`` 애너테이션이 아니라, DI 설정 파일의 + ```` 요소에 의한 초기화입니다. 등록되는 이름은 ``getName()`` 의 + 반환값이며, 관리 화면에서 플러그인을 선택할 때의 이름이 됩니다. + +플러그인 라이프사이클 +========================== + +초기화 +------ + +1. 플러그인 JAR 가 클래스패스에 추가된다 +2. DI 컨테이너가 ``fess_*++.xml`` 을 병합하여 컴포넌트를 생성한다 +3. ```` 에서 지정한 메서드(예: ``register``)가 호출된다 +4. 플러그인이 대응하는 팩토리/매니저에 등록된다 + +종료 +---- + +1. DI 컨테이너 종료 시, ```` 에서 지정한 메서드가 호출된다 + (정의되어 있는 경우) +2. 리소스 정리 + +.. note:: + + 데이터스토어의 경우, 실행 중인 크롤링은 ``AbstractDataStore.stop()`` 에 의해 + 정지 플래그가 설정되어 레코드 처리 루프가 안전하게 종료됩니다. + +의존 관계 +========= + +Fess 본체 의존성 +---------------- + +|Fess| 본체의 클래스는 실행 시 서버의 클래스패스 상에 존재하므로, +``provided`` 스코프로 의존합니다(플러그인 JAR 에는 포함하지 않습니다). + +.. code-block:: xml + + + org.codelibs.fess + fess + provided + + +외부 라이브러리 +--------------- + +플러그인은 자체 의존 라이브러리를 포함할 수 있습니다: + +.. code-block:: xml + + + com.example + example-sdk + 1.0.0 + + +이들은 |Fess| 본체에는 포함되지 않으므로, 플러그인과 함께 배포해야 합니다. + +설정 취득 +========== + +파라미터와 FessConfig 취득 +------------------------------ + +데이터스토어의 ``storeData()`` 에서는 관리 화면에서 설정한 파라미터를 +``DataStoreParams`` 에서 취득합니다. 값을 가져올 때는 ``getAsString()`` 을 사용합니다 +(``DataStoreParams`` 는 ``Map`` 을 구현하지 않으므로 ``get()`` 은 문자열을 반환하지 않습니다). +또한 |Fess| 의 설정값은 ``ComponentUtil.getFessConfig()`` 에서 취득할 수 있습니다: + +.. code-block:: java + + public class ExampleDataStore extends AbstractDataStore { + + @Override + protected String getName() { + // 핸들러 이름으로 사용된다. 클래스의 단순 이름을 반환하는 것이 관례 + return this.getClass().getSimpleName(); + } + + @Override + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { + + // 파라미터 취득 + final String apiKey = paramMap.getAsString("api.key"); + final String baseUrl = paramMap.getAsString("base.url"); + + // FessConfig 취득 + final FessConfig fessConfig = ComponentUtil.getFessConfig(); + } + } + +``storeData()`` 의 자세한 구현 방법(데이터 취득·스크립트 평가·인덱스 등록의 +흐름)은 :doc:`datastore-plugin` 을 참조하십시오. + +빌드와 설치 +==================== + +빌드 +------ + +:: + + mvn clean package + +``target/`` 디렉터리에 JAR 파일(예: ``fess-ds-example-15.10.0.jar``)이 +생성됩니다. + +설치 +------------ + +1. **관리 화면에서**: + + - [시스템 > 플러그인 > 설치]를 연다 + - 플러그인 리포지토리 목록에서 선택하거나, 빌드한 JAR 파일을 + 업로드하여 설치 + +2. **수동**: + + - JAR 파일을 ``app/WEB-INF/plugin/`` 디렉터리에 복사 + - |Fess| 를 재시작 + +설치 절차의 자세한 내용은 :doc:`../admin/plugin-guide` 를 참조하십시오. + +디버깅 +======== + +로그 출력 +--------- + +|Fess| 는 Log4j2 를 사용합니다. 로거는 ``LogManager.getLogger()`` 로 취득합니다: + +.. code-block:: java + + private static final Logger logger = LogManager.getLogger(ExampleDataStore.class); + + public void someMethod() { + logger.debug("Debug message"); + logger.info("Info message"); + } + +.. note:: + + 비밀번호나 토큰 등의 민감한 정보는 로그에 출력하지 마십시오. + +개발 모드 +---------- + +개발 시에는 |Fess| 를 IDE 에서 실행하여 디버깅할 수 있습니다: + +1. ``org.codelibs.fess.FessBoot`` 클래스를 디버그 실행한다 +2. 플러그인의 소스를 프로젝트에 포함시킨다 +3. 브레이크포인트를 설정한다 + +공개 플러그인 목록 +================== + +|Fess| 프로젝트에서는 다수의 플러그인이 공개되어 있습니다. 다음은 대표적인 예입니다 +(전부를 망라한 것은 아닙니다): + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 플러그인 + - 설명 + * - ``fess-ds-box`` + - Box 커넥터 + * - ``fess-ds-dropbox`` + - Dropbox 커넥터 + * - ``fess-ds-slack`` + - Slack 커넥터 + * - ``fess-ds-atlassian`` + - JIRA / Confluence 커넥터 + * - ``fess-ds-git`` + - Git 리포지토리 커넥터 + * - ``fess-llm-openai`` + - OpenAI LLM 프로바이더 + +이 밖에도 ``fess-ds-csv`` / ``fess-ds-db`` / ``fess-ds-json`` / +``fess-ds-microsoft365`` / ``fess-ds-sharepoint`` 등의 데이터스토어 커넥터나, +``fess-llm-ollama`` / ``fess-llm-gemini`` / ``fess-llm-bedrock`` 등의 LLM 프로바이더가 공개되어 있습니다. +이들 플러그인은 개발 참고용으로 +`GitHub `__ 에 공개되어 있습니다. + +참고 정보 +========= + +- :doc:`datastore-plugin` - 데이터스토어 플러그인 개발 +- :doc:`script-engine-plugin` - 스크립트 엔진 플러그인 +- :doc:`webapp-plugin` - 웹앱 플러그인 +- :doc:`ingest-plugin` - Ingest 플러그인 +- :doc:`theme-development` - 테마 커스터마이징 +- :doc:`../admin/plugin-guide` - 플러그인 설치 diff --git a/ko/15.10/dev/script-engine-plugin.rst b/ko/15.10/dev/script-engine-plugin.rst new file mode 100644 index 000000000..bc565bcd5 --- /dev/null +++ b/ko/15.10/dev/script-engine-plugin.rst @@ -0,0 +1,61 @@ +================================== +스크립트 엔진 플러그인 +================================== + +개요 +==== + +스크립트 엔진 플러그인을 개발하면 |Fess|\ 에 새로운 스크립트 언어 +지원을 추가할 수 있습니다. + +기본 구현 +======== + +``ScriptEngine`` 인터페이스를 구현합니다: + +.. code-block:: java + + package org.codelibs.fess.script.example; + + import org.codelibs.fess.script.ScriptEngine; + import java.util.Map; + + public class ExampleScriptEngine implements ScriptEngine { + + @Override + public String getName() { + return "example"; + } + + @Override + public Object evaluate(String script, Map params) { + // 스크립트 평가 로직 + return executeScript(script, params); + } + } + +등록 +==== + +.. code-block:: java + + @PostConstruct + public void register() { + ComponentUtil.getScriptEngineManager().add(this); + } + +사용 예 +====== + +관리 화면에서 스크립트 유형으로 선택: + +:: + + scriptType=example + scriptData=your script here + +참고 정보 +======== + +- :doc:`plugin-architecture` - 플러그인 아키텍처 +- :doc:`../config/scripting-overview` - 스크립팅 개요 diff --git a/ko/15.10/dev/theme-development.rst b/ko/15.10/dev/theme-development.rst new file mode 100644 index 000000000..3565d8f9f --- /dev/null +++ b/ko/15.10/dev/theme-development.rst @@ -0,0 +1,307 @@ +================================== +테마 개발 가이드 +================================== + +개요 +==== + +|Fess| 15.10 에서는 검색 화면이 항상 정적 테마로 표시됩니다. 정적 테마는 +``/api/v2/*`` API 를 이용하는 독립된 SPA(싱글 페이지 애플리케이션)입니다. +테마는 ZIP 파일로 배포하고, 관리 화면에서 업로드하여 활성화합니다. 테마를 +선택하지 않은 경우에는 |Fess| 에 번들된 정적 테마 ``bootstrap`` 이 사용됩니다. + +검색 화면의 외관을 변경하려면 다른 테마를 설치하거나 +(:doc:`../admin/theme-guide` 참조) 직접 만듭니다. 가장 빠른 방법은 번들된 +테마를 복사하여 그 복사본을 변경하는 것입니다. `번들 테마 커스터마이징`_ 을 +참조하십시오. + +.. note:: + + 정적 테마는 |Fess| 15.7 이후 버전에서 사용할 수 있으며, 15.10 에서 기본 + 검색 화면이 되었습니다. 검색 화면의 JSP 를 교체하는 JAR 테마 플러그인은 + 15.10 에서 삭제되었습니다. + `JAR 테마 플러그인(15.10 에서 삭제)`_ 을 참조하십시오. + +정적 테마 +========== + +정적 테마는 ``theme.yml`` 매니페스트와 ``index.html`` 을 포함하는 정적 리소스의 +집합입니다. 테마 본체는 |Fess| 의 ``/api/v2/*`` API 를 호출하는 프런트엔드 +애플리케이션으로 구현합니다. + +구조 +---- + +정적 테마는 다음과 같은 디렉터리 구성을 가집니다. + +:: + + example/ + ├── theme.yml # 매니페스트(필수) + ├── index.html # SPA 엔트리 HTML + ├── assets/ # JavaScript·CSS 등 정적 리소스 + │ └── styles.css + ├── i18n/ # 다국어 메시지(messages..json) + │ └── messages.en.json + ├── help/ # 도움말 정의(.json) + │ └── en.json + └── thumbnail.png # 미리보기 이미지(임의) + +매니페스트 (theme.yml) +------------------------ + +``theme.yml`` 은 ZIP 의 루트에 배치하는 필수 매니페스트입니다. 다음은 최소 구성의 +예입니다. + +.. code-block:: yaml + + apiVersion: fess.codelibs.org/v1 + kind: StaticTheme + name: example + displayName: "Example Theme" + version: "15.10.0" + minFessVersion: "15.10" + entry: index.html + spaFallback: true + +지정할 수 있는 필드는 다음과 같습니다. + +.. list-table:: + :header-rows: 1 + :widths: 22 12 66 + + * - 필드 + - 필수 + - 설명 + * - ``apiVersion`` + - 필수 + - 고정값 ``fess.codelibs.org/v1``. + * - ``kind`` + - 필수 + - 고정값 ``StaticTheme``. + * - ``name`` + - 필수 + - 테마 이름. ``^[a-z0-9][a-z0-9_-]{0,63}$`` 에 일치해야 합니다. + ``themes/`` 아래에 전개되는 테마의 디렉터리 이름(업로드 시에는 + 이 ``name`` 으로 자동으로 결정됩니다), 그리고 배포 URL + (``/themes//``)에 사용됩니다. + * - ``displayName`` + - 필수 + - 관리 화면에 표시되는 이름. + * - ``version`` + - 필수 + - 시맨틱 버저닝 형식(예: ``15.10.0``, ``15.10.1-beta.1``). 관례로 + ``major.minor`` 는 테마가 대상으로 하는 |Fess| 계열에 맞춥니다. 그러면 + 버전만으로 어느 |Fess| 용 테마인지 알 수 있습니다. + * - ``author`` + - 선택 + - 작성자 이름. + * - ``description`` + - 선택 + - 테마 설명. + * - ``license`` + - 선택 + - 라이선스. + * - ``homepage`` + - 선택 + - 홈페이지 URL. + * - ``minFessVersion`` + - 선택 + - 테마가 지원하는 |Fess| 의 최소 버전. ``version`` 의 ``major.minor`` 와 + 같은 값으로 둡니다. ``maxFessVersion`` 은 없습니다. `공개`_ 를 참조하십시오. + * - ``supportedLocales`` + - 선택 + - 지원 로케일 목록(예: ``[en, ja, de]``). + * - ``entry`` + - 선택 + - SPA 엔트리 HTML. 기본값은 ``index.html``. + * - ``spaFallback`` + - 선택 + - 더 이상 사용되지 않음. 호환성을 위해 허용되지만 읽히지 않습니다. + 15.10 부터는 검색 화면의 각 경로에서 항상 엔트리 HTML 이 반환됩니다. + +.. note:: + + ZIP 에서 업로드하는 경우, 전개될 디렉터리 이름은 ``name`` 으로 자동으로 + 결정됩니다. ``themes/`` 디렉터리에 수동으로 테마를 배치하는 경우에는 디렉터리 + 이름을 ``name`` 과 일치시켜 주십시오. 일치하지 않는 테마는 재스캔 시 무시됩니다. + +.. note:: + + 미리보기용 썸네일은 테마의 루트에 ``thumbnail.png`` 라는 고정된 이름으로 + 배치합니다(관리 화면의 테마 목록에 표시됩니다). 이 이미지는 매니페스트의 + 필드가 아니라 파일 이름으로 인식됩니다. 크기는 512KB 이내·512×512 + 픽셀 이내를 권장합니다. + +배포와 API +---------- + +- 정적 테마는 ``/themes//`` 아래에서 배포됩니다(```` 은 + ``theme.yml`` 의 ``name``). +- ``/``, ``/search``, ``/advance``, ``/help``, ``/error``, ``/profile``, + ``/cache``, ``/chat`` 의 각 경로에서 엔트리 HTML(기본값은 + ``index.html``)이 반환되며, 이후의 라우팅은 SPA 가 담당합니다. + 15.10 부터는 ``spaFallback`` 의 값과 관계없이 이렇게 동작하며, 이 필드는 + 더 이상 읽히지 않습니다. +- 오류도 테마가 표시합니다. 요청이 실패하면 브라우저는 요청한 URL 에서 + 실제 HTTP 상태와 함께 테마의 엔트리 HTML 을 받습니다. +- 관리 화면(``/admin/*``), ``/api/*``, 로그인 화면 등은 정적 테마의 대상 외이며, + |Fess| 본체가 처리합니다. +- 엔트리 HTML 의 ``{{themePath}}`` 는 반환될 때 ``themes/`` 으로 치환됩니다. + ``index.html`` 에서 테마 자신의 파일을 참조할 때는 ``{{themePath}}/assets/styles.css`` + 처럼 작성합니다. 테마 이름을 직접 쓰지 않으므로, 어떤 이름으로 설치해도 테마는 자신의 + 파일을 로드합니다. +- 엔트리 HTML 은 스크립트, 스타일, 이미지, 접속을 |Fess| 자신으로부터만 + 허용하는 ``Content-Security-Policy`` 헤더와 함께 반환됩니다(인라인 스타일은 + 허용되지만 인라인 스크립트는 허용되지 않습니다). 따라서 외부 CDN 의 폰트나 + 스크립트는 로드되지 않으므로 테마에 포함하십시오. +- 엔트리 HTML 의 ``Content-Security-Policy`` 에는 ``frame-ancestors 'none'`` 이 + 포함되고 ``X-Frame-Options: DENY`` 헤더도 붙으므로, 페이지는 다른 페이지의 + 프레임에 표시되지 않습니다. ``frame-ancestors`` 의 값은 ``fess_config.properties`` + 의 ``theme.index.frame.ancestors`` (기본값: ``'none'`` )로 변경할 수 있습니다. + 값을 비우면 ``frame-ancestors`` 를 붙이지 않습니다( ``X-Frame-Options: DENY`` 는 + 그대로 붙습니다). WebKit 계열 브라우저(Safari 등)는 ``frame-ancestors 'none'`` + 에서 테마가 ``blob:`` URL 로 표시하는 프레임(PDF 미리보기나 캐시 표시)을 비워 둡니다. + 이를 표시하려면 값을 비우십시오. +- 테마의 SPA 는 검색 결과나 채팅 등의 데이터를 ``/api/v2/*`` API 에서 가져옵니다. + +패키징 +-------------- + +`fess-themes `__ 리포지토리의 +``scripts/package.sh`` 를 사용하면 테마를 배포용 ZIP 으로 묶을 수 있습니다. + +:: + + ./scripts/package.sh example + +``dist/example-.zip`` 이 생성됩니다(```` 은 ``theme.yml`` 의 +``version``). + +.. note:: + + ``theme.yml`` 은 ZIP 의 루트에 배치해야 합니다. 하위 디렉터리에 + 넣으면 업로드 시 인식되지 않습니다. + +공개 +---- + +|Fess| 프로젝트가 개발하는 테마는 https://maven.codelibs.org/release/org/codelibs/fess/themes/ 아래에 공개됩니다. 배치는 ``//-.zip`` 이고 그 옆에 ``.sha1`` 이, 테마마다 공개된 버전을 나열한 ``maven-metadata.xml`` 이 놓입니다. ``bin/fess-setup install theme `` 은 이 메타데이터를 읽어 실행 중인 |Fess| 용으로 만들어진 버전을 고릅니다. + +테마의 버전은 대상으로 하는 |Fess| 계열에 맞추고, 아카이브가 담는 내용을 바꿀 때마다 버전을 올리십시오. 공개된 버전이 덮어써지는 일은 없으므로 버전을 그대로 둔 변경은 배포되지 않습니다. + +매니페스트에 상한 필드가 없는 것도 같은 이유입니다. 공개된 아카이브는 변경되지 않으므로 새로운 |Fess| 에서 동작하지 않게 된 테마에 나중에 상한을 추가할 수 없습니다. 그 계열용으로 공개하지 않음으로써 알게 된 시점에 같은 것을 나타낼 수 있습니다. + +.. note:: + + 공개된 버전을 조사할 때는 디렉터리 목록이 아니라 ``maven-metadata.xml`` 을 사용하십시오. 디렉터리 색인은 주기적으로 생성되므로 새로 공개한 테마는 목록에 나타나기 전에 메타데이터에서 읽을 수 있습니다. + +설치와 활성화 +-------------------- + +1. 관리 화면에서 [시스템 > 테마](``/admin/theme/``)를 엽니다. +2. 작성한 ZIP 파일을 업로드합니다. 공개된 테마는 명령줄에서 + ``bin/fess-setup install theme `` 으로 설치할 수도 있습니다. + :doc:`../install/fess-setup` 를 참조하십시오. +3. 목록 페이지의 「기본 테마」 드롭다운에서 대상 테마를 선택하고, 「설정」 버튼을 + 눌러 활성화합니다. + +활성화의 원리는 다음과 같습니다. + +- 「설정」 버튼을 누르면 선택한 테마 이름이 시스템 프로퍼티 ``theme.default`` + 에 저장되어 시스템 전체의 기본 테마가 됩니다. +- 테마 이름을 가상 호스트의 키와 일치시키면, 해당 가상 호스트에 접속했을 때만 + 테마가 적용됩니다. 이를 통해 가상 호스트별로 테마를 전환할 수 있습니다. +- 디스크상의 ``themes/`` 디렉터리를 직접 갱신한 경우에는 「다시 로드」로 + 재스캔할 수 있습니다. + +.. note:: + + ZIP 업로드에는 파일 크기·전개 후 총 크기·엔트리 수 등의 상한이 있으며, + ``fess_config.properties`` 의 ``theme.*`` 프로퍼티로 조정할 수 있습니다 + (예: ``theme.upload.max.size`` 는 기본값 50MB, ``theme.directory.path`` 는 + 기본값 ``themes``). 전개 시에는 ZIP Slip 이나 zip bomb 을 방지하기 위한 + 검증이 이루어집니다. + +.. _theme-customize-bundled: + +번들 테마 커스터마이징 +---------------------- + +번들 테마 ``bootstrap`` 은 |Fess| 설치 디렉터리의 ``app/themes/bootstrap/`` 에 +있습니다(RPM/DEB 패키지의 경우 ``/usr/share/fess/app/themes/bootstrap/``). +그 자리에서 편집하지 마십시오. 업그레이드 시 교체되며, ``bootstrap`` 이라는 +이름은 번들 테마용으로 예약되어 있어 삭제할 수도, 업로드로 교체할 수도 +없습니다. 대신 다른 이름으로 복사하십시오. + +1. 디렉터리를 복사합니다. 예를 들어 ``mytheme`` 으로 복사합니다:: + + $ cp -r app/themes/bootstrap /tmp/mytheme + +2. ``theme.yml`` 에서 ``name`` 을 ``mytheme`` 으로 변경하고 ``displayName`` 도 + 변경합니다. ``name`` 은 디렉터리 이름과 일치해야 합니다. + +3. ``index.html`` 은 변경하지 않습니다. 번들된 ``index.html`` 은 스타일시트, 로고, + 스크립트 등 자신의 파일을 ``{{themePath}}/assets/...`` 로 참조하며, |Fess| 는 + 반환할 때 ``{{themePath}}`` 를 ``themes/`` (``theme.yml`` 의 ``name``)으로 + 치환합니다. 따라서 이름만 바꾸면 복사본은 자신의 파일을 로드합니다. ``index.html`` 에서 + 참조하는 파일을 추가할 때도 URL 을 ``{{themePath}}/assets/...`` 형식으로 작성하십시오. + +4. 원하는 대로 변경합니다. + + - 배색과 레이아웃: ``assets/styles.css``. + - 로고: ``assets/logo-head.png`` (헤더)와 ``assets/logo.png`` + (검색 첫 페이지). + - 푸터(``footer.copyright_org``) 등의 텍스트: 언어별로 하나씩 있는 + ``i18n/messages..json`` 파일. + - 페이지 구조: ``index.html``. + +5. ``theme.yml`` 이 루트에 오도록 디렉터리를 ZIP 으로 묶어, 관리 화면의 + 「시스템」 > 「테마」에서 업로드합니다:: + + $ cd /tmp/mytheme && zip -r ../mytheme.zip . + + 또는 디렉터리를 ``app/themes/`` 에 배치하고, 같은 페이지에서 + 「다시 로드」를 클릭합니다. + +6. 같은 페이지에서 ``mytheme`` 을 기본 테마로 선택합니다. + +.. note:: + + 번들 테마는 해당 |Fess| 버전의 ``/api/v2/*`` API 에 맞춰져 있으므로, + |Fess| 를 업그레이드할 때마다 번들 테마에서 새로 복사본을 만들어 변경 사항을 + 다시 적용하십시오. + +JAR 테마 플러그인(15.10 에서 삭제) +==================================== + +JSP·CSS·이미지를 ``fess-theme-*`` JAR 에 넣고, 가상 호스트의 키와 같은 이름의 테마로 +적용하는 JAR 테마 플러그인 종류는 |Fess| 15.10 에서 삭제되었습니다. 15.10 는 JAR 테마를 +전개하지 않으며, 어떤 화면에도 사용하지 않습니다. + +- 관리 화면의 「시스템」→「플러그인」에서 설치해도, 종류 ``jar`` 의 범용 JAR 로 + ``app/WEB-INF/plugin/`` 에 놓일 뿐이며 화면은 아무것도 바뀌지 않습니다. 이전 버전에서 + 남은 ``fess-theme-*.jar`` 도 같은 방식으로 표시되며, 이 화면 또는 + ``bin/fess-setup remove plugin `` 으로 삭제할 수 있습니다. +- ``bin/fess-setup`` 은 ``fess-theme-*`` 를 목록에 표시하지 않으며, 설치하지도 않습니다. + +JAR 테마에서 하던 변경은 정적 테마로 옮기십시오. + +- 검색 화면의 배색·레이아웃·로고는 번들 테마를 복사하여 변경합니다 + (`번들 테마 커스터마이징`_ 참조). +- 가상 호스트별로 외관을 바꾸던 경우에는 가상 호스트 이름과 같은 이름의 정적 테마를 + 설치합니다(:doc:`../config/security-virtual-host` 참조). +- 로그인 화면(``/login/``)은 모든 가상 호스트에서 공통인 화면입니다. 테마로 변경할 수 + 없습니다. + +기존 테마 예시 +============== + +- `fess-themes `__ - 정적 테마 모음집 + (``codesearch``, ``docsearch`` 등 여러 정적 테마 수록) + +참고 정보 +========= + +- :doc:`plugin-architecture` - 플러그인 아키텍처 +- :doc:`../admin/plugin-guide` - 플러그인 설치 diff --git a/ko/15.10/dev/webapp-plugin.rst b/ko/15.10/dev/webapp-plugin.rst new file mode 100644 index 000000000..1ff821050 --- /dev/null +++ b/ko/15.10/dev/webapp-plugin.rst @@ -0,0 +1,317 @@ +================================== +웹앱 플러그인 +================================== + +개요 +==== + +웹앱 플러그인(``fess-webapp-*``)은 |Fess| 의 웹 애플리케이션을 확장하는 +플러그인입니다. 다른 종류의 플러그인과 달리 Action 클래스나 JSP 를 직접 +추가하는 것이 아니라, DI 컨테이너(Lasta Di)에 대해 **컴포넌트를 추가하거나 +교체** 함으로써 기능을 확장합니다. 대표적인 용도는 다음과 같습니다: + +- 새로운 컴포넌트(헬퍼·서비스 등)의 추가 +- |Fess| 본체 컴포넌트의 교체(서브클래스화) +- REST API 엔드포인트의 추가(``WebApiManager``) +- 검색 동작의 확장(쿼리 커맨드, 랭크 퓨전 등) + +.. note:: + + 웹앱 플러그인은 JAR 로 배포되며, 내부의 클래스와 DI 설정 파일이 + |Fess| 웹 애플리케이션의 클래스패스에 로드됩니다. JSP 뷰를 추가하는 + 것은 아닙니다. 검색 화면의 디자인을 커스터마이즈하려면 + :doc:`theme-development` 를 참조하십시오. + +기본 구조 +========= + +웹앱 플러그인의 구현 템플릿인 +`fess-webapp-example `__ 를 +예로 들면, 플러그인은 「구현 클래스」와 「DI 등록 파일」로 구성됩니다: + +:: + + fess-webapp-example/ + ├── pom.xml + └── src/main/ + ├── java/org/codelibs/fess/webapp/example/helper/ + │ ├── ExampleHelper.java # 추가할 컴포넌트 + │ └── CustomSystemHelper.java # 코어 컴포넌트의 교체 + └── resources/ + ├── app++.xml # 컴포넌트의 추가(병합) + └── fess+systemHelper.xml # 컴포넌트의 교체 + +.. note:: + + 구현 클래스의 패키지는 ``org.codelibs.fess.webapp.<플러그인 이름>`` 을 + 사용합니다. DI 설정 파일은 ``src/main/resources/`` 에 배치합니다. + 데이터스토어 플러그인과 달리 ``src/main/webapp/`` 나 JSP 는 포함하지 + 않습니다. + +pom.xml과 매니페스트 +==================== + +웹앱 플러그인은 ``fess-parent`` 를 부모 POM 으로 하는 jar 로 빌드합니다. +|Fess| 본체에서 실행 시 제공되는 ``fess`` 나 ``opensearch`` 는 ``provided`` +스코프로 선언하고, ``lastaflute``·``dbflute-runtime``·``corelib`` 등 실행 +시 필요한 라이브러리는 일반 스코프로 선언합니다. + +웹앱 플러그인에서 가장 중요한 것은 JAR 매니페스트에 ``Fess-WebAppJar: true`` +를 부여하는 것입니다. 이 선언에 의해 |Fess| 는 플러그인의 클래스와 DI 설정 +파일을 웹 애플리케이션의 클래스로더에 마운트합니다. 이 설정은 +``maven-jar-plugin`` 으로 수행합니다: + +.. code-block:: xml + + + + + maven-jar-plugin + + + + true + + + + + + + +.. warning:: + + ``Fess-WebAppJar: true`` 를 부여하지 않으면 플러그인의 클래스나 DI + 설정 파일이 웹 애플리케이션의 클래스패스에 로드되지 않아, 컴포넌트의 + 추가·교체가 활성화되지 않습니다. + +pom.xml 전체 구성(부모 POM·의존 관계 선언 방법 등)은 +:doc:`plugin-architecture` 를 참조하십시오. + +확장 패턴 +========= + +컴포넌트 추가(app++.xml) +------------------------- + +가장 기본적인 확장 방법은 자체 컴포넌트를 추가하는 것입니다. Lasta Di 는 +클래스패스 상의 ``app++.xml`` 을 |Fess| 본체의 ``app.xml`` 로부터 구축되는 +``app`` 네임스페이스에 **병합** 합니다(끝의 ``++`` 는 추가 병합 규약입니다). +추가하는 컴포넌트는 |Fess| 본체에 존재하지 않는 이름을 사용하므로, 아무것도 +덮어쓰지 않습니다. + +.. code-block:: xml + + + + + + + + +컴포넌트 구현에서는 초기화에 ``@PostConstruct`` 를 사용하고, |Fess| 본체의 +컴포넌트는 ``ComponentUtil`` 에서 가져와 재사용합니다(복사나 덮어쓰기는 +하지 않습니다): + +.. code-block:: java + + package org.codelibs.fess.webapp.example.helper; + + import org.codelibs.fess.helper.SystemHelper; + import org.codelibs.fess.util.ComponentUtil; + + import jakarta.annotation.PostConstruct; + + public class ExampleHelper { + + protected String pluginName = "fess-webapp-example"; + + @PostConstruct + public void init() { + // DI 에 의한 생성 후 한 번만 호출되는 초기화 처리 + } + + public String getPluginLabel() { + // 코어의 SystemHelper 를 재사용하여 실행 중인 Fess 버전을 취득 + final SystemHelper systemHelper = ComponentUtil.getSystemHelper(); + final String version = systemHelper != null ? systemHelper.getProductVersion() : "unknown"; + return pluginName + " (Fess " + version + ")"; + } + } + +.. tip:: + + 먼저 이 「컴포넌트 추가」를 검토하십시오. 코어 기능을 변경할 필요가 + 없는 한, 교체보다 안전하고 유지보수성이 뛰어납니다. + +코어 컴포넌트 교체(fess+componentName.xml) +------------------------------------------- + +|Fess| 본체 컴포넌트의 동작을 변경하고 싶은 경우, 대상 클래스를 +서브클래스화하고 ``+.xml`` 이라는 이름의 DI +설정 파일로 **동일한 컴포넌트 이름으로 재등록** 합니다. 예를 들어 +``systemHelper`` 는 |Fess| 본체의 ``fess.xml`` 에서 선언되어 있으므로, +교체 파일은 ``fess+systemHelper.xml`` 이 됩니다(``app+systemHelper.xml`` +이 아닙니다). + +.. code-block:: java + + package org.codelibs.fess.webapp.example.helper; + + import java.nio.file.Path; + + import org.codelibs.fess.helper.SystemHelper; + + public class CustomSystemHelper extends SystemHelper { + + @Override + protected void parseProjectProperties(final Path propPath) { + try { + super.parseProjectProperties(propPath); + } catch (final Exception e) { + // 자체 처리 + } + System.setProperty("fess.webapp.plugin", "true"); + } + } + +.. warning:: + + 교체(단일 ``+``)는 컴포넌트 정의를 **통째로** 교체합니다. 이 때문에 + 교체 파일에는 코어 정의가 수행하고 있는 ```` 를 모두 + 기술해야 합니다(예: ``app.xml`` 의 ``queryHelper``). 이는 |Fess| + 릴리스마다 동기화해야 합니다. 코어에서 삭제된 메서드를 계속 호출하면, 그 + 컴포넌트 정의는 ``BeanMethodNotFoundException`` 으로 초기화에 실패합니다. + 예를 들어 15.10 에서는 ``systemHelper`` 의 ``addDesignJspFileName`` 이 + 삭제되었기 때문에, 이를 호출하는 교체 파일은 실패합니다. 이러한 유지보수 + 비용이 교체보다 추가가 권장되는 이유입니다. + +REST API 추가(fess_api++.xml) +------------------------------- + +새로운 REST API 엔드포인트를 추가하려면 ``WebApiManager`` 를 구현합니다. +``BaseApiManager`` 를 상속하고, ``@PostConstruct`` 에서 +``WebApiManagerFactory`` 에 자신을 등록합니다. 등록된 API 매니저는 +요청마다 ``WebApiFilter`` 에서 호출됩니다. ``fess_api++.xml`` 에서 +컴포넌트를 등록합니다: + +.. code-block:: xml + + + + + + + + +.. code-block:: java + + package org.codelibs.fess.webapp.example.api; + + import java.io.IOException; + + import org.codelibs.fess.api.BaseApiManager; + import org.codelibs.fess.util.ComponentUtil; + + import jakarta.annotation.PostConstruct; + import jakarta.servlet.FilterChain; + import jakarta.servlet.ServletException; + import jakarta.servlet.http.HttpServletRequest; + import jakarta.servlet.http.HttpServletResponse; + + public class ExampleApiManager extends BaseApiManager { + + public ExampleApiManager() { + // 이 매니저가 처리하는 경로의 프리픽스 + setPathPrefix("/api/example"); + } + + @PostConstruct + public void register() { + ComponentUtil.getWebApiManagerFactory().add(this); + } + + @Override + public boolean matches(final HttpServletRequest request) { + // 이 매니저가 요청을 처리할지 여부를 판정 + return request.getServletPath().startsWith(pathPrefix); + } + + @Override + public void process(final HttpServletRequest request, final HttpServletResponse response, + final FilterChain chain) throws IOException, ServletException { + // 요청 처리 및 응답 작성 + } + + @Override + protected void writeHeaders(final HttpServletResponse response) { + // 응답 헤더 설정(필요한 경우) + } + } + +구현 예로는 ``/api/v1`` 을 제공하는 +`fess-webapp-v1-api `__ 나, +``/json`` / ``/suggest`` 를 제공하는 +`fess-webapp-classic-api `__ +가 참고가 됩니다. + +검색 화면 커스터마이즈 +====================== + +웹앱 플러그인은 JSP 뷰를 추가할 수 없습니다. JSP 뷰는 |Fess| 본체 WAR 의 +``WEB-INF/view/`` 에 배치되어 있으며, 플러그인 JAR 는 클래스패스 +(``WEB-INF/classes``)에 마운트되기 때문입니다. 검색 화면의 디자인을 +변경하려면 정적 테마를 사용합니다. 정적 테마는 검색 화면의 디자인 +(HTML/CSS/JavaScript)을 커스터마이즈합니다. :doc:`theme-development` 를 +참조하십시오. + +빌드와 설치 +=========== + +:: + + mvn clean package + +``target/`` 디렉터리에 JAR 파일(예: ``fess-webapp-example-15.10.0.jar``)이 +생성됩니다. 생성한 JAR 는 관리 화면에서 설치하거나, ``app/WEB-INF/plugin/`` +디렉터리에 배치하고 |Fess| 를 재시작합니다. 설치 절차의 자세한 내용은 +:doc:`../admin/plugin-guide` 를 참조하십시오. + +공개 플러그인 예 +================ + +|Fess| 프로젝트에서는 다음의 웹앱 플러그인이 공개되어 있습니다. +개발 참고용으로 `GitHub `__ 에 공개되어 +있습니다: + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - 플러그인 + - 설명 + * - ``fess-webapp-example`` + - 플러그인 구현의 템플릿 + * - ``fess-webapp-v1-api`` + - ``/api/v1`` REST API + * - ``fess-webapp-classic-api`` + - ``/json`` / ``/suggest`` 레거시 REST API + * - ``fess-webapp-mcp`` + - MCP(Model Context Protocol) 서버 + * - ``fess-webapp-bangs`` + - DuckDuckGo 방식의 뱅(``!g``). 다른 사이트로 검색을 보냄 + * - ``fess-webapp-semantic-search`` + - 뉴럴 검색/벡터 검색(사용 중단됨; 15.10의 코어 통합 기능으로 대체됨) + * - ``fess-webapp-multimodal`` + - 멀티모달(이미지·텍스트) 검색 + +참고 정보 +========= + +- :doc:`plugin-architecture` - 플러그인 아키텍처 +- :doc:`theme-development` - 테마 커스터마이즈 +- :doc:`../admin/plugin-guide` - 플러그인 설치 +- :doc:`overview` - 개발자 문서 개요 diff --git a/ko/15.10/install/fess-setup.rst b/ko/15.10/install/fess-setup.rst new file mode 100644 index 000000000..87557f590 --- /dev/null +++ b/ko/15.10/install/fess-setup.rst @@ -0,0 +1,243 @@ +==================== +fess-setup 명령 +==================== + +``bin/fess-setup`` (Windows 에서는 ``bin\fess-setup.bat`` )은 |Fess| 의 ZIP 패키지에 포함되어 있습니다. |Fess| 에 필요하지만 배포물에 포함되지 않은 것, 즉 |Fess| 가 필요로 하는 플러그인을 넣은 OpenSearch, Playwright 플러그인이 사용하는 Node.js, |Fess| 플러그인, 정적 테마를 설치합니다. 설치 상태를 진단할 수도 있습니다. + +|Fess| 디렉터리에서 실행합니다. 인수 없이 실행하면 명령 목록을 표시합니다. + +:: + + $ cd /path/to/fess-15.10.0 + $ bin/fess-setup [options] + +종료 코드 +========== + +.. list-table:: + :header-rows: 1 + :widths: 15 85 + + * - 코드 + - 의미 + * - ``0`` + - 명령이 성공했습니다. + * - ``1`` + - 명령이 실패했습니다. 예를 들어 다운로드에 실패한 경우, 지정한 버전이 존재하지 않는 경우, 이 플랫폼용 OpenSearch 배포판이 없는 경우, ``check`` 가 문제를 발견한 경우입니다. + * - ``2`` + - 명령줄이 잘못되었습니다. 알 수 없는 명령을 지정했거나 플러그인 이름 등의 인수가 부족한 경우입니다. + +OpenSearch 와 Node.js 설치 +============================ + +install opensearch +------------------ + +:: + + $ bin/fess-setup install opensearch [--dest ] [--version ] [--keep-bundled-plugins] + +이 |Fess| 가 지원하는 버전의 OpenSearch 를 |Fess| 디렉터리의 ``opensearch/`` 에 다운로드하고, |Fess| 가 필요로 하는 4개의 플러그인( ``opensearch-analysis-fess`` , ``opensearch-analysis-extension`` , ``opensearch-minhash`` , ``opensearch-configsync`` )을 설치한 다음, 해당 OpenSearch 의 ``config/opensearch.yml`` 에 다음 설정을 추가합니다. + +- ``configsync.config_path`` (값은 해당 OpenSearch 의 ``config/dictionary`` 디렉터리) +- ``plugins.security.disabled: true`` + +또한 |Fess| 가 사용하지 않는 번들 플러그인 ``opensearch-security-analytics`` 와 ``opensearch-performance-analyzer`` 를 제거합니다. Docker 이미지의 OpenSearch 와 같은 구성입니다. 배포본에 포함되지 않은 플러그인은 건너뜁니다. + +``opensearch.yml`` 에 이미 있는 설정은 다시 추가하지 않으며, ``plugins.security.*`` 설정이 하나라도 있으면 ``plugins.security.disabled: true`` 를 추가하지 않습니다. OpenSearch 디렉터리가 이미 있으면 다운로드를 건너뛰므로, 기존 설치에 대해 다시 실행하면 부족한 설정만 추가됩니다. + +명령은 추가한 설정을 표시한 다음, ``bin/fess.in.sh`` 가 이 OpenSearch 를 자동으로 찾을 수 있는지 표시합니다. |Fess| 디렉터리의 ``opensearch/`` 아래에서 ``config/dictionary`` 디렉터리를 가진 OpenSearch 가 이것 하나뿐이면 찾을 수 있습니다. 이때 ``bin/fess.in.sh`` (Windows 에서는 ``bin\fess.in.bat`` )가 ``FESS_DICTIONARY_PATH`` 를 그 디렉터리로 설정하므로, 같은 호스트에서 실행하는 OpenSearch 라면 그 밖의 설정은 필요하지 않습니다. 찾을 수 없으면 설정해야 할 ``SEARCH_ENGINE_HTTP_URL`` 과 ``FESS_DICTIONARY_PATH`` 값을 표시합니다. 설정 방법은 :doc:`install-linux` 또는 :doc:`install-windows` 를 참조하십시오. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 옵션 + - 설명 + * - ``--dest `` + - OpenSearch 를 압축 해제할 디렉터리를 |Fess| 디렉터리의 ``opensearch/`` 대신 지정합니다. ``bin/fess.in.sh`` 는 이 디렉터리 밖에 있는 OpenSearch 를 찾지 않습니다. + * - ``--version `` + - 설치할 OpenSearch 버전입니다. 플러그인도 같은 버전으로 설치됩니다. + * - ``--keep-bundled-plugins`` + - 번들 플러그인( ``opensearch-security-analytics`` , ``opensearch-performance-analyzer`` )을 제거하지 않고 배포본 그대로 둡니다. + +OpenSearch 공식 배포판은 Linux 용과 Windows 용뿐입니다. macOS 등 그 밖의 플랫폼에서는 아무것도 다운로드하지 않고 종료 코드 ``1`` 로 종료하며, Homebrew 로 OpenSearch 를 설치하고 ``install opensearch-plugins`` 로 플러그인을 넣는 방법 또는 Docker 를 사용하는 방법을 안내합니다. + +.. warning:: + + ``plugins.security.disabled: true`` 를 설정한 OpenSearch 는 인증 없이 요청을 받아들입니다. OpenSearch 는 ``network.host`` 를 설정하지 않는 한 루프백 주소에서만 수신 대기합니다. 그 밖의 주소에서 수신 대기하기 전에 대신 보안 플러그인을 설정하십시오. 자세한 내용은 :doc:`security` 를 참조하십시오. + +install opensearch-plugins +-------------------------- + +:: + + $ bin/fess-setup install opensearch-plugins --opensearch-home [--version ] + +이미 있는 OpenSearch 에 |Fess| 가 필요로 하는 4개의 플러그인을 설치합니다. 해당 OpenSearch 의 ``bin/opensearch-plugin install`` 을 4번 실행하는 대신 사용할 수 있습니다. ``--opensearch-home`` 에는 OpenSearch 설치 디렉터리를 지정합니다(필수). ``--version`` 은 플러그인 버전이며, OpenSearch 버전과 일치시켜야 합니다. + +이 명령은 ``opensearch.yml`` 을 변경하지 않습니다. ``configsync.config_path`` 등의 설정은 :doc:`install-linux` 또는 :doc:`install-windows` 에 따라 직접 추가하십시오. + +install nodejs +-------------- + +:: + + $ bin/fess-setup install nodejs [--dest ] [--version ] + +Playwright 플러그인(Playwright 크롤러용 ``fess-crawler-playwright`` 와 썸네일용 ``fess-thumbnail-playwright`` )이 필요로 하는 Node.js 를 |Fess| 디렉터리의 ``nodejs/`` 에 다운로드합니다. ``bin/fess.in.sh`` (Windows 에서는 ``bin\fess.in.bat`` )가 이를 찾아 ``PLAYWRIGHT_NODEJS_PATH`` 를 설정합니다. ``--dest`` 로 |Fess| 디렉터리 밖에 압축 해제한 경우에는 대신 ``bin/fess.in.sh`` 에 추가할 ``PLAYWRIGHT_NODEJS_PATH`` 줄을 표시합니다. ``--version`` 으로 다른 버전의 Node.js 를 지정할 수 있습니다. Playwright 크롤러에 대해서는 :doc:`../config/crawler-advanced` 를 참조하십시오. + +플러그인 관리 +================ + +다음 명령은 |Fess| 설치의 플러그인 디렉터리 ``app/WEB-INF/plugin`` 을 대상으로 합니다. 플러그인을 설치, 업그레이드, 삭제한 후에는 |Fess| 를 재시작하십시오. 플러그인은 관리 화면의 「시스템 > 플러그인」 페이지에서도 관리할 수 있습니다. :doc:`../admin/plugin-guide` 를 참조하십시오. + +``install plugin`` , ``list plugins`` , ``list installed`` , ``upgrade plugins`` , ``remove plugin`` , ``check`` 에는 ``--dest `` 을 지정할 수 있습니다. ``app/WEB-INF/plugin`` 대신 사용할 플러그인 디렉터리를 지정하며, 플러그인 jar 가 놓이는 디렉터리 자체를 가리킵니다(그 상위 디렉터리가 아닙니다). 상대 경로는 |Fess| 디렉터리가 아니라 명령을 실행한 현재 디렉터리를 기준으로 합니다. ``install opensearch`` 와 ``install nodejs`` 의 ``--dest`` 는 아카이브를 압축 해제할 디렉터리를 가리킵니다. + +``install plugin`` , ``list plugins`` , ``upgrade plugins`` 에는 ``--repository `` 을 지정할 수 있습니다. 지정하면 버전 목록, jar, 체크섬을 모두 그 하나의 Maven 저장소(사내 미러 등)에서 가져오며, 기본 릴리스 저장소, 스냅숏 저장소, GitHub 은 사용하지 않습니다. + +``--repository`` 에는 ``file:///`` 로 시작하는 URL 도 지정할 수 있습니다. 인터넷에 연결할 수 없는 서버에서는 Maven 저장소의 사본을 서버에 두고 그 디렉터리를 지정합니다. 지정하는 것은 각 플러그인의 디렉터리( ``/maven-metadata.xml`` 등)를 포함하는 디렉터리로, 기본 저장소의 ``https://maven.codelibs.org/release/org/codelibs/fess/`` 에 해당하는 위치입니다. 버전 확인과 체크섬 검증은 HTTP 저장소와 같은 방식으로 이루어집니다. + +:: + + $ bin/fess-setup install plugin fess-ds-csv --repository file:///opt/maven-repo/org/codelibs/fess/ + +``http`` , ``https`` , ``file`` 이외의 스킴이나 스킴이 없는 URL 은 한 줄의 오류로 거부됩니다. + +install plugin +-------------- + +:: + + $ bin/fess-setup install plugin [:]... [--version ] [--repository ] [--dest ] + +``fess-script-groovy`` 나 ``fess-ds-git`` 등 |Fess| 플러그인을 하나 이상 설치합니다. 버전을 붙이지 않은 이름에는 이 |Fess| 용으로 빌드된 최신 버전이 설치됩니다. ``:`` 으로 해당 플러그인의 버전을 고정할 수 있으며, ``--version`` 은 자체 버전이 없는 모든 이름에 사용됩니다. 새 버전의 설치가 완료된 후에 같은 플러그인의 이전 버전이 삭제됩니다. + +jar 는 플러그인의 GitHub 릴리스에서 가져오며, 릴리스에 해당 파일이 없으면 Maven 저장소에서 가져옵니다. 어느 경우든 Maven 저장소가 공개하는 SHA-1 체크섬으로 검증합니다. |Fess| 의 개발 빌드에서는 같은 계열의 스냅숏 빌드도 설치 대상이 되며, 스냅숏이 우선됩니다. + +사용 예는 :doc:`../admin/plugin-guide` 를 참조하십시오. + +설치할 수 있는 것은 |Fess| 가 읽어 들이는 종류의 플러그인(이름이 ``fess-ds-`` , ``fess-ingest-`` , ``fess-script-`` , ``fess-webapp-`` , ``fess-thumbnail-`` , ``fess-crawler-`` , ``fess-llm-`` , ``fess-storage-`` , ``fess-sso-`` 로 시작하는 것)뿐입니다. ``list plugins`` 에 표시되는 것과 같습니다. 그 밖의 이름( ``fess-theme-*`` , ``fess`` , ``fess-crawler`` 등의 라이브러리)을 지정하면 아무것도 다운로드하지 않고 한 줄의 오류를 표시한 후 종료 코드 2로 종료합니다. 여러 이름 중 하나라도 해당하면 아무것도 설치하지 않습니다. 정적 테마는 ``install theme`` 으로 설치하십시오. + +list plugins +------------ + +:: + + $ bin/fess-setup list plugins [--repository ] [--dest ] + +이 |Fess| 용으로 공개된 플러그인 목록을 표시하고, 설치된 플러그인에는 ``(installed: )`` 을 붙입니다. 설치되어 있지만 저장소에 공개되지 않은 플러그인(로컬에서 빌드한 jar 등)은 따로 표시합니다. |Fess| 의 개발 빌드에서는 스냅숏 저장소도 참조합니다. + +list installed +-------------- + +:: + + $ bin/fess-setup list installed [--dest ] + +설치된 플러그인과 그 버전을 저장소에 조회하지 않고 표시합니다. + +upgrade plugins +--------------- + +:: + + $ bin/fess-setup upgrade plugins [--repository ] [--dest ] + +설치된 모든 플러그인을 이 |Fess| 에 맞는 버전으로 다시 설치합니다. 이미 그 버전인 플러그인은 그대로 둡니다. ``app/WEB-INF/plugin`` 의 플러그인은 특정 |Fess| 릴리스용으로 빌드되므로, |Fess| 를 업그레이드한 후에 이 명령을 실행하십시오. + +remove plugin +------------- + +:: + + $ bin/fess-setup remove plugin ... [--dest ] + +지정한 플러그인의 설치된 jar 를 삭제합니다. 설치되지 않은 이름은 그 사실을 표시할 뿐이며, 종료 코드에는 영향을 주지 않습니다. + +.. _fess-setup-offline: + +인터넷에 연결할 수 없는 환경 +---------------------------- + +``install plugin`` , ``list plugins`` , ``upgrade plugins`` 는 플러그인을 인터넷상의 저장소에서 가져옵니다. 관리 화면의 「시스템 > 플러그인」 설치 화면도 설치할 수 있는 플러그인 목록을 저장소( ``plugin.repositories`` )에서 가져오므로, 외부에 연결할 수 없는 환경에서는 목록을 표시할 수 없습니다. + +이러한 환경에서는 플러그인 jar 를 반입하여 설치합니다. + +1. 인터넷에 연결할 수 있는 환경에서 |Fess| ZIP 패키지와 필요한 플러그인 jar 를 다운로드합니다. jar 는 ``https://maven.codelibs.org/release/org/codelibs/fess///-.jar`` 에서 가져올 수 있습니다. 이 |Fess| 에 대응하는 버전( |Fess| 15.10 라면 15.10.x)을 선택하십시오. +2. 대상 환경에서 ZIP 을 압축 해제하고, jar 를 ``app/WEB-INF/plugin/`` 에 둡니다. |Fess| 시작 후에 관리 화면 플러그인 설치 화면의 「로컬」 탭에서 업로드할 수도 있습니다( :doc:`../admin/plugin-guide` 참조). +3. |Fess| 를 시작합니다. 실행 중에 jar 를 둔 경우에는 재시작하십시오. + +플러그인 jar 를 하나씩 가져오는 대신, Maven 저장소의 필요한 부분( ``org/codelibs/fess//`` 디렉터리)을 복사해 가져온 후 ``--repository file:///...`` 를 지정하여 ``install plugin`` 으로 설치할 수도 있습니다. 이 경우에도 체크섬이 검증됩니다. + +테마 관리 +========= + +이 명령들은 |Fess| 설치 디렉터리의 ``app/themes`` 를 대상으로 합니다. 테마를 설치하거나 삭제한 뒤에는 |Fess| 를 재시작하거나 [시스템 > 테마] 페이지에서 [다시 읽기] 를 클릭하십시오. 테마는 같은 페이지에서 업로드할 수도 있습니다. :doc:`../admin/theme-guide` 를 참조하십시오. + +``install theme`` , ``list themes`` , ``remove theme`` 에도 같은 방식으로 ``--dest `` 을 지정할 수 있으며, ``app/themes`` 대신 사용할 테마 디렉터리를 지정합니다. + +테마의 버전은 그 테마가 대상으로 하는 |Fess| 계열을 나타냅니다. 즉 ``15.10.0`` 은 |Fess| 15.10 용 테마입니다. 따라서 버전 없이 이름만 지정하면 플러그인과 마찬가지로 이 |Fess| 용으로 만들어진 테마가 선택됩니다. + +install theme +------------- + +:: + + $ bin/fess-setup install theme [:]... [--version ] [--repository ] [--dest ] + +``docuforge`` 나 ``voicebox`` 같은 정적 테마를 설치합니다. 버전이 없는 이름은 이 |Fess| 용으로 만들어진 최신 버전을 설치합니다. ``:`` 은 그 테마의 버전을 고정하고, ``--version`` 은 자체 버전이 없는 모든 이름에 적용됩니다. + +아카이브는 Maven 저장소가 공개한 SHA-1 체크섬과 대조된 뒤 ``app/themes/`` 에 전개됩니다. 같은 이름으로 이미 설치된 테마는 관리 화면에서 교체한 경우와 같은 기간 동안 백업으로 보관됩니다(기본 7일, ``theme.upload.attic.retention.days`` ). + +다운로드, 전개, 매니페스트 검사는 모두 이미 설치된 것에 손대기 전에 이루어집니다. 따라서 설치에 실패해도 기존 테마는 그대로 남습니다. ``theme.yml`` 이 다른 테마 이름을 가리키는 아카이브는 거부됩니다. + +list themes +----------- + +:: + + $ bin/fess-setup list themes [--repository ] [--dest ] + +이 |Fess| 용으로 공개된 테마를 표시하고, 설치된 것에는 ``(installed: )`` 을 붙입니다. 설치되어 있으나 저장소 목록에 없는 테마는 따로 표시됩니다. + +이 목록은 저장소의 디렉터리 색인에서 읽습니다. 색인은 주기적으로 생성되므로 읽지 못할 때가 있습니다. 그런 경우에는 시도한 URL 을 알린 뒤 설치된 테마는 계속 표시합니다. 색인에 있든 없든 이름을 지정하면 테마를 설치할 수 있습니다. + +remove theme +------------ + +:: + + $ bin/fess-setup remove theme ... [--dest ] + +지정한 테마를 ``app/themes`` 에서 삭제합니다. 각각은 보관 기간 동안 백업으로 남습니다. 설치되어 있지 않은 이름은 보고되지만 종료 코드는 달라지지 않습니다. + +삭제한 테마가 기본 테마였던 경우, 다른 테마를 선택할 때까지 |Fess| 는 내장된 ``bootstrap`` 테마로 대체합니다. + +설치 상태 확인 +================ + +list +---- + +:: + + $ bin/fess-setup list + +``install`` 이 다운로드하는 구성 요소( ``opensearch`` 와 ``nodejs`` )를 각각의 버전과 함께 표시합니다. + +check +----- + +:: + + $ bin/fess-setup check [--url ] [--playwright] [--dest ] + +설치 상태를 진단하고, 확인 항목마다 ``OK`` , ``WARN`` , ``FAIL`` 중 하나를 붙여 한 줄씩 표시합니다. + +- 검색 엔진: 접속할 수 있는지, 버전(노드 간에 버전이 다르면 경고), |Fess| 가 필요로 하는 4개의 플러그인이 설치되어 있는지, ``configsync`` 가 응답하는지 +- |Fess| : 플러그인 디렉터리가 존재하고 쓰기 가능한지, 설치된 각 플러그인(다른 |Fess| 릴리스용이거나 두 버전이 설치되어 있으면 실패), |Fess| 디렉터리의 ``nodejs/`` 에 Node.js 가 설치되어 있는지 + +검색 엔진 URL 은 ``--url`` , 지정하지 않으면 환경 변수 ``SEARCH_ENGINE_HTTP_URL`` , 그것도 없으면 ``http://localhost:9200`` 입니다. ``bin/fess-setup`` 은 ``bin/fess.in.sh`` 를 읽지 않으므로, OpenSearch 가 다른 곳에 있으면 ``--url`` 을 지정하십시오. Node.js 가 없는 것은 보고만 되지만, ``--playwright`` 를 지정하면 실패로 처리됩니다. + +실패한 항목이 없으면 경고가 있더라도 종료 코드 ``0`` 으로 종료하고, 실패한 항목이 있으면 종료 코드 ``1`` 로 종료합니다. diff --git a/ko/15.10/install/index.rst b/ko/15.10/install/index.rst new file mode 100644 index 000000000..e9a6e13f2 --- /dev/null +++ b/ko/15.10/install/index.rst @@ -0,0 +1,24 @@ +|Fess| 설치 가이드 +===================== + +Linux, Windows, Docker에 |Fess|\ 를 설치하고 실행하는 방법을 동작 +요건, 보안 설정, 업그레이드, 문제 해결과 함께 설명합니다. + +.. toctree:: + :maxdepth: 2 + :caption: 목차 + + intro + prerequisites + install + install-linux + install-windows + install-docker + fess-setup + run + security + upgrade + uninstall + troubleshooting + + diff --git a/ko/15.10/install/install-docker.rst b/ko/15.10/install/install-docker.rst new file mode 100644 index 000000000..1d34b2345 --- /dev/null +++ b/ko/15.10/install/install-docker.rst @@ -0,0 +1,608 @@ +============================== +Docker 설치 (상세) +============================== + +이 페이지에서는 Docker 및 Docker Compose를 사용한 |Fess| 의 설치 절차를 설명합니다. +Docker를 사용하면 간단하고 신속하게 |Fess| 환경을 구축할 수 있습니다. + +전제 조건 +============ + +- :doc:`prerequisites` 에 기재된 시스템 요구 사항을 충족할 것 +- Docker 20.10 이상이 설치되어 있을 것 +- Docker Compose 2.0 이상이 설치되어 있을 것 + +Docker 설치 확인 +==================== + +다음 명령으로 Docker 및 Docker Compose의 버전을 확인합니다. + +:: + + $ docker --version + $ docker compose version + +.. note:: + + 이전 버전의 Docker Compose를 사용하는 경우 ``docker-compose`` 명령을 사용합니다. + 이 문서에서는 새로운 ``docker compose`` 명령 형식을 사용합니다. + +Docker 이미지 정보 +====================== + +|Fess| 를 Docker Compose로 시작하면 다음 2개의 컨테이너가 동작합니다. + +- **Fess** (``fess01``): 전문 검색 시스템 본체 +- **OpenSearch** (``search01``): 검색 엔진 + +공식 Docker 이미지는 `GitHub Container Registry `__ 에서 공개되고 있습니다. +Compose 파일 및 시작 절차는 `docker-fess `__ 리포지토리에서 관리됩니다. + +단계 1: Docker Compose 파일 가져오기 +======================================== + +Docker Compose를 사용한 시작에는 다음 파일이 필요합니다. + +방법 1: 파일을 개별적으로 다운로드 +------------------------------------ + +다음 파일을 다운로드합니다: + +:: + + $ mkdir fess-docker + $ cd fess-docker + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose.yaml + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose-opensearch3.yaml + +방법 2: Git으로 리포지토리 복제 +---------------------------------- + +Git이 설치되어 있는 경우 리포지토리 전체를 클론할 수도 있습니다: + +:: + + $ git clone --depth 1 --branch v15.10.0 https://github.com/codelibs/docker-fess.git + $ cd docker-fess/compose + +단계 2: Docker Compose 파일 확인 +==================================== + +``compose.yaml`` 의 내용 +-------------------------- + +``compose.yaml`` 에는 Fess 본체(``fess01`` 서비스)의 설정이 포함되어 있습니다. + +주요 설정 항목: + +- **포트 번호**: Fess 웹 인터페이스의 포트 (기본값: 8080) +- **환경 변수**: OpenSearch 연결 대상 (``SEARCH_ENGINE_HTTP_URL``) 이나 사전 파일 경로 (``FESS_DICTIONARY_PATH``) 등 +- **시작 순서**: OpenSearch (``search01``) 가 정상 상태가 된 후 시작하도록 ``depends_on`` 이 설정되어 있습니다 + +``compose-opensearch3.yaml`` 의 내용 +--------------------------------------- + +``compose-opensearch3.yaml`` 에는 검색 엔진(``search01`` 서비스, OpenSearch)의 설정이 포함되어 있습니다. + +주요 설정 항목: + +- **OpenSearch 이미지**: 사용할 OpenSearch 이미지 (``ghcr.io/codelibs/fess-opensearch``) +- **메모리 설정**: JVM 힙 크기 +- **볼륨**: 데이터 영속화용 볼륨 (``search01_data``: 인덱스 데이터, ``search01_dictionary``: 사전 파일) + +설정 커스터마이징(옵션) +-------------------------- + +기본 설정을 변경하는 경우 ``compose.yaml`` 을 편집합니다. + +예: 포트 번호를 변경하는 경우:: + + services: + fess01: + ports: + - "9080:8080" # 호스트의 9080번 포트에 매핑 + +예: 메모리 설정을 변경하는 경우:: + + services: + fess01: + environment: + - "FESS_HEAP_SIZE=2g" # Fess의 힙 크기를 2GB로 설정 + +이미지 종류와 썸네일 +-------------------- + +|Fess| 의 Docker 이미지에는 태그 접미사(``-noble`` , ``-al2023`` 등)가 다른 여러 종류가 있습니다. 접미사가 없는 기본 이미지(Alpine 기반)에는 이미지, PDF, Office 문서의 썸네일을 만드는 외부 도구(ImageMagick, poppler-utils, unoconv, LibreOffice)가 들어 있지 않습니다. 이 이미지에서 썸네일이 생성되는 것은 HTML 페이지뿐이며, 이미지, PDF, Office 문서의 썸네일은 생성되지 않습니다. + +이러한 썸네일이 필요하면 ``compose.yaml`` 의 ``image`` 에 도구가 포함된 ``-noble`` 접미사가 붙은 태그를 지정하십시오. + +:: + + services: + fess01: + image: ghcr.io/codelibs/fess:15.10.0-noble + +이미지별 지원 여부는 다음과 같습니다. + +.. list-table:: + :header-rows: 1 + :widths: 40 30 30 + + * - 태그 + - 이미지·PDF + - Office 문서 + * - ``15.10.0-noble`` + - 생성됨 + - 생성됨 + * - ``15.10.0-al2023`` + - 생성됨 + - 생성되지 않음 + * - ``15.10.0``, ``15.10.0-slim``, ``15.10.0-slim-noble``, ``15.10.0-slim-al2023`` + - 생성되지 않음 + - 생성되지 않음 + +HTML 페이지의 썸네일은 어느 이미지에서나 페이지 안의 이미지로 생성됩니다. 썸네일을 표시하려면 관리 화면의 전반 설정에서 썸네일 표시도 활성화하십시오. 자세한 내용은 :doc:`../config/crawler-thumbnail` 을 참조하십시오. + +단계 3: Docker 컨테이너 시작 +================================ + +기본 시작 +------------ + +다음 명령으로 Fess와 OpenSearch를 시작합니다: + +:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +.. note:: + + - ``-f`` 옵션으로 여러 개의 Compose 파일을 지정합니다 + - ``-d`` 옵션으로 백그라운드에서 실행합니다 + +시작 로그 확인:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f + +``Ctrl+C`` 로 로그 표시를 종료할 수 있습니다. + +시작 확인 +------------ + +컨테이너 상태를 확인합니다:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps + +다음과 같은 컨테이너가 시작되어 있는지 확인하십시오: + +- ``fess01`` +- ``search01`` + +.. tip:: + + 시작에는 몇 분 정도 걸릴 수 있습니다. 먼저 OpenSearch (``search01``) 가 정상 상태가 된 후 Fess (``fess01``) 가 시작됩니다. + ``docker compose ... ps`` 로 각 컨테이너의 상태를 확인하고, ``fess01`` 이 시작되면 브라우저에서 http://localhost:8080/ 에 접속할 수 있습니다. + +단계 4: 브라우저에서 액세스 +================================ + +시작이 완료되면 다음 URL에 접속합니다: + +- **검색 화면**: http://localhost:8080/ +- **관리 화면**: http://localhost:8080/admin + +검색 화면은 |Fess| 에 번들된 정적 테마 ``bootstrap`` 입니다. 외관을 변경하려면 +:doc:`../admin/theme-guide` 를 참조하십시오. + +기본 관리자 계정: + +- 사용자 이름: ``admin`` +- 비밀번호: ``admin`` + +.. warning:: + + **보안 관련 중요 주의사항** + + 운영 환경에서는 관리자 비밀번호를 반드시 변경하십시오. + 자세한 내용은 :doc:`security` 를 참조하십시오. + +AI 검색 모드(LLM 플러그인) 활성화 +==================================== + +|Fess| 15.10부터 AI 검색 모드(RAG Chat) 기능은 ``fess-llm-*`` 플러그인으로 분리되었습니다. +공식 `docker-fess `__ 리포지토리에는 주요 LLM 프로바이더용 오버레이 파일이 동봉되어 있습니다. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 오버레이 + - 용도 + * - ``compose-ollama.yaml`` + - Ollama (로컬 LLM, 추가 ``ollama01`` 서비스를 시작) + * - ``compose-gemini.yaml`` + - Google Gemini (클라우드 API) + * - ``compose-openai.yaml`` + - OpenAI (클라우드 API) + +각 오버레이는 ``FESS_PLUGINS`` 로 해당 플러그인을 자동으로 가져오고, ``FESS_JAVA_OPTS`` 에 +``-Dfess.config.rag.chat.enabled=true`` 를 설정하여 RAG Chat을 활성화합니다. +클라우드 API를 이용하는 Gemini와 OpenAI에서는 추가로 ``-Dfess.system.rag.llm.name`` 으로 사용할 프로바이더를 지정하고, +API 키 (``rag.llm..api.key``) 와 모델 (``rag.llm..model``) 을 설정합니다. +Ollama에서는 ``rag.llm.name`` 의 기본값 (``ollama``) 이 그대로 사용되므로 명시적인 지정은 없으며, +접속 대상 (``rag.llm.ollama.api.url``) 이 설정됩니다. + +Gemini를 사용하는 예:: + + $ export GEMINI_API_KEY="AIzaSy..." + $ docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-gemini.yaml up -d + +OpenAI를 사용하는 예:: + + $ export OPENAI_API_KEY="sk-..." + $ docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-openai.yaml up -d + +.. note:: + + 사용할 모델은 ``GEMINI_MODEL`` 및 ``OPENAI_MODEL`` 환경 변수로 변경할 수 있습니다 + (기본값은 각각 ``gemini-2.5-flash`` 와 ``gpt-5-mini`` 입니다). + +Ollama를 사용하는 예:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-ollama.yaml up -d + $ docker exec -it ollama01 ollama pull gpt-oss:20b + +.. warning:: + + ``compose-ollama.yaml`` 의 ``ollama01`` 서비스는 기본적으로 NVIDIA GPU를 사용하도록 정의되어 있습니다 + (`NVIDIA Container Toolkit `__ 가 필요합니다). + GPU가 탑재되지 않은 환경에서 실행하는 경우에는 ``compose-ollama.yaml`` 의 ``deploy:`` 블록 (``reservations`` 아래의 GPU 지정)을 삭제하거나 주석 처리하십시오. + +.. tip:: + + 시작 후 관리 화면 "시스템 > 전체" 의 설정 화면에서 사용할 LLM 프로바이더 (``rag.llm.name``) 나 + 각 프로바이더 고유의 설정을 변경할 수 있습니다. 다만 이러한 변경 사항은 컨테이너 내부의 설정 파일에 저장되므로, + 컨테이너를 재생성(``docker compose down`` 후 ``up``)하면 사라집니다. + 설정을 영속화하려면 위 예시와 같이 Compose 파일의 ``FESS_JAVA_OPTS`` 로 지정하십시오. + +데이터 영속화 +================ + +|Fess| 의 데이터(인덱스, 크롤링한 문서, 사용자 정보, 설정 등)는 모두 OpenSearch에 저장됩니다. +이 데이터는 OpenSearch의 볼륨에 영속화되므로, 컨테이너를 삭제해도 데이터는 유지됩니다. +Fess 본체(``fess01``) 컨테이너 자체는 상태를 갖지 않으며, 전용 볼륨은 없습니다. + +볼륨 확인:: + + $ docker volume ls + +``compose-opensearch3.yaml`` 에서 정의되는 주요 볼륨: + +- ``search01_data``: OpenSearch의 인덱스 데이터(Fess의 모든 데이터를 포함) +- ``search01_dictionary``: 사전 파일 + +.. note:: + + Docker Compose의 볼륨 이름에는 프로젝트 이름(기본값은 Compose 파일이 있는 디렉터리 이름)이 접두사로 붙습니다. + 예를 들어 ``compose`` 디렉터리에서 시작한 경우, 실제 볼륨 이름은 ``compose_search01_data`` 와 같이 됩니다. + +.. important:: + + 컨테이너를 삭제해도 볼륨은 삭제되지 않습니다. + 볼륨을 삭제하려면 명시적으로 ``docker volume rm`` 명령을 실행해야 합니다. + +Docker 컨테이너 중지 +======================== + +컨테이너 중지:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop + +컨테이너 중지 및 삭제:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +.. warning:: + + ``down`` 명령은 컨테이너를 삭제하지만 볼륨은 삭제하지 않습니다. + 볼륨(``search01_data`` 등)도 삭제하려면 ``-v`` 옵션을 추가합니다:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down -v + + **주의**: 이 명령을 실행하면 OpenSearch에 저장된 모든 데이터가 삭제됩니다. + +고급 설정 +============ + +환경 변수 커스터마이징 +-------------------------- + +``compose.yaml`` 에서 환경 변수를 추가·변경함으로써 상세한 설정이 가능합니다. + +주요 환경 변수: + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - 환경 변수 + - 설명 + * - ``FESS_HEAP_SIZE`` + - Fess의 JVM 힙 크기(Docker 이미지의 기본값: 512m) + * - ``FESS_JAVA_OPTS`` + - 추가 JVM 옵션 지정(``-Dfess.config.*`` 에 의한 설정 오버라이드 등) + * - ``FESS_PLUGINS`` + - 시작 시 자동으로 설치할 플러그인(공백으로 구분된 ``name:version`` 형식. 예: ``fess-ds-wikipedia:15.10.0``) + * - ``SEARCH_ENGINE_HTTP_URL`` + - OpenSearch의 HTTP 엔드포인트(``compose.yaml`` 의 기본값: ``http://search01:9200``) + * - ``SEARCH_ENGINE_TYPE`` + - 검색 엔진 종류(``default``, ``vanilla``, ``aws``). ``vanilla`` 는 Fess 15.10 이상의 이미지에서 지정할 수 있으며, 그보다 이전 이미지에서는 ``cloud`` 를 지정합니다( :doc:`../config/search-engine-type` 참조). 15.8 이미지에서는 ``-noble`` 변형만 이 값을 Fess 에 전달합니다. + * - ``SEARCH_ENGINE_USERNAME`` / ``SEARCH_ENGINE_PASSWORD`` + - 인증이 활성화된 OpenSearch에 접속할 때의 자격 증명 + * - ``FESS_DICTIONARY_PATH`` + - 사전 파일의 경로(OpenSearch와 공유하는 디렉터리) + * - ``FESS_PORT`` + - Fess가 컨테이너 내부에서 대기하는 포트(기본값: 8080) + +예:: + + services: + fess01: + environment: + - "FESS_HEAP_SIZE=4g" + +.. note:: + + 시간대를 변경하는 경우에는 ``FESS_JAVA_OPTS`` 에 ``-Duser.timezone=Asia/Tokyo`` 와 같이 지정합니다. + +설정 파일 반영 방법 +---------------------- + +|Fess| 의 상세한 설정은 ``fess_config.properties`` 파일에 기술합니다. +Docker 이미지에서는 ``fess_config.properties`` 가 컨테이너 내부의 ``/etc/fess`` 에 배치되어 있습니다. +Docker 환경에서 설정을 반영시키려면 다음 방법이 있습니다. + +방법 1: 설정 파일 마운트 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``/etc/fess`` 에는 Fess 동작에 필요한 다른 설정 파일도 포함되어 있으므로, 이 디렉터리를 그대로 마운트로 교체하면 시작에 실패합니다. +대신 클래스패스 맨 앞에 추가되는 오버라이드용 디렉터리 ``/opt/fess`` 를 사용합니다(초기 상태는 비어 있습니다). + +1. 호스트 측에 설정 파일을 준비하기 위한 디렉터리를 생성:: + + $ mkdir -p /path/to/fess-config + +2. 설정 파일 템플릿을 가져오기(최초 1회만):: + + $ curl -o /path/to/fess-config/fess_config.properties https://raw.githubusercontent.com/codelibs/fess/refs/tags/fess-15.10.0/src/main/resources/fess_config.properties + +3. ``/path/to/fess-config/fess_config.properties`` 를 편집하여 필요한 설정을 기술:: + + # 예 + crawler.document.cache.enabled=false + adaptive.load.control=20 + query.facet.fields=label,host + +4. ``compose.yaml`` 의 ``fess01`` 서비스에 볼륨 마운트를 추가:: + + services: + fess01: + volumes: + - /path/to/fess-config/fess_config.properties:/opt/fess/fess_config.properties + +5. 컨테이너 시작:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +.. note:: + + ``/opt/fess`` 는 클래스패스 맨 앞에 추가되므로, 여기에 배치한 ``fess_config.properties`` 가 + 이미지에 동봉된 ``/etc/fess/fess_config.properties`` 보다 우선됩니다. + 프로퍼티 파일은 파일 단위로 읽어들이며, 항목별로 병합되지 않습니다. + 파일에 없는 항목이 있어도 |Fess| 는 시작되며, 해당 버전에 동봉된 기본값이 사용되고 항목마다 경고가 한 번씩 로그에 출력됩니다. + 따라서 변경하려는 항목만 적은 파일도 동작합니다. 경고를 피하려면 2단계와 같이 완전한 파일에서 시작하십시오. + 일부 항목만 변경하고 싶은 경우에는 다음의 "방법 2"를 이용하십시오. + 같은 항목을 이 파일과 "방법 2"의 ``-Dfess.config.`` 로 모두 지정한 경우에는 ``-D`` 로 지정한 값이 사용됩니다. + +방법 2: 시스템 속성에 의한 설정 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``fess_config.properties`` 의 설정 항목을 환경 변수를 통해 시스템 속성으로 오버라이드할 수 있습니다. + +``fess_config.properties`` 에 기재되는 설정 항목(예: ``crawler.document.cache.enabled=false``)을 +``-Dfess.config.설정항목명=값`` 형식으로 지정합니다. + +``compose.yaml`` 의 ``fess01`` 서비스의 환경 변수에 ``FESS_JAVA_OPTS`` 를 추가:: + + services: + fess01: + environment: + - "FESS_JAVA_OPTS=-Dfess.config.crawler.document.cache.enabled=false -Dfess.config.adaptive.load.control=20 -Dfess.config.query.facet.fields=label,host" + +.. note:: + + ``-Dfess.config.`` 뒤에 이어지는 부분이 ``fess_config.properties`` 의 설정 항목명에 대응합니다. + 일부 항목만 오버라이드하는 경우에는 이 방법이 간단합니다. + +외부 OpenSearch 연결 +------------------------ + +기존 OpenSearch 클러스터를 사용하는 경우에는 ``compose-opensearch3.yaml`` 을 사용하지 않고 ``compose.yaml`` 만으로 시작하여 접속 대상을 변경합니다. + +1. ``compose-opensearch3.yaml`` 을 지정하지 않고 시작:: + + $ docker compose -f compose.yaml up -d + +2. ``compose.yaml`` 의 ``fess01`` 서비스에서 접속 대상을 설정:: + + environment: + - "SEARCH_ENGINE_HTTP_URL=http://your-opensearch-host:9200" + +.. note:: + + 인증이 활성화된 OpenSearch에 접속하는 경우에는 ``SEARCH_ENGINE_USERNAME`` 과 ``SEARCH_ENGINE_PASSWORD`` 도 지정합니다. + +기타 오버레이 및 구성 +------------------------ + +``docker-fess`` 리포지토리에는 위에서 설명한 것 외에도 용도별 Compose 파일 및 디렉터리가 포함되어 있습니다. + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - 파일 / 디렉터리 + - 용도 + * - ``compose-dashboards3.yaml`` + - OpenSearch Dashboards를 추가(포트 5601, 데이터 시각화용) + * - ``compose-minio.yaml`` + - MinIO(오브젝트 스토리지)를 추가하여 Fess의 스토리지 기능의 저장 위치로 이용 + * - ``vanilla/`` + - CodeLibs 플러그인을 포함하지 않는 순정 OpenSearch와 조합하는 구성(``SEARCH_ENGINE_TYPE=vanilla``. Fess 15.10 이상의 이미지에서 지정할 수 있으며, 그보다 이전 이미지에서는 ``cloud`` 를 지정합니다). 사전 관리 등 일부 기능은 이용 불가( :doc:`../config/search-engine-type` 참조) + * - ``snapshot/`` + - 개발판(snapshot) 이미지를 사용하는 구성(클러스터 구성 및 Elasticsearch 8과의 조합을 포함) + * - ``multi-instance/`` + - 하나의 OpenSearch를 공유하는 여러 개의 Fess 인스턴스를 시작하는 구성 + +Docker 네트워크 설정 +------------------------ + +여러 서비스와 연계하는 경우 사용자 정의 네트워크를 사용할 수 있습니다. + +예:: + + networks: + fess-network: + driver: bridge + + services: + fess01: + networks: + - fess-network + +Docker Compose로 운영 환경 운용 +==================================== + +운영 환경에서 Docker Compose를 사용하는 경우의 권장 설정: + +1. **리소스 제한 설정**:: + + deploy: + resources: + limits: + cpus: '2.0' + memory: 4G + reservations: + cpus: '1.0' + memory: 2G + +2. **재시작 정책 설정**:: + + restart: unless-stopped + +3. **로그 설정**:: + + logging: + driver: "json-file" + options: + max-size: "10m" + max-file: "3" + +4. **보안 설정 활성화** + + OpenSearch의 보안 플러그인을 활성화하고 적절한 인증을 설정합니다. + 자세한 내용은 :doc:`security` 를 참조하십시오. + +문제 해결 +============ + +컨테이너가 시작되지 않음 +-------------------------- + +1. 로그 확인:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs + +2. 포트 번호 충돌 확인:: + + $ sudo ss -tuln | grep 8080 + $ sudo ss -tuln | grep 9200 + +3. 디스크 용량 확인:: + + $ df -h + +메모리 부족 오류 +-------------------- + +OpenSearch가 메모리 부족으로 시작되지 않는 경우, ``vm.max_map_count`` 를 늘려야 합니다. + +Linux의 경우:: + + $ sudo sysctl -w vm.max_map_count=262144 + +영구적으로 설정하는 경우:: + + $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf + $ sudo sysctl -p + +데이터 초기화 +---------------- + +모든 데이터를 삭제하고 초기 상태로 되돌리기:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down -v + $ docker volume prune + +.. warning:: + + 이 명령을 실행하면 모든 데이터가 완전히 삭제됩니다. + +다음 단계 +============ + +설치가 완료되면 다음 문서를 참조하십시오: + +- :doc:`run` - |Fess| 시작 및 초기 설정 +- :doc:`security` - 운영 환경에서의 보안 설정 +- :doc:`troubleshooting` - 문제 해결 + +자주 묻는 질문 +================== + +Q: 이미지 다운로드에는 어느 정도의 디스크 용량이 필요합니까? +---------------------------------------------------------------- + +A: Fess와 OpenSearch의 이미지는 처음 시작할 때 다운로드되며, 합쳐서 수 GB 정도의 디스크 용량이 필요합니다. +네트워크 환경에 따라 다운로드에 시간이 걸릴 수 있습니다. + +Q: Kubernetes에서의 운용이 가능합니까? +-------------------------------------------- + +A: 가능합니다. Docker Compose 파일을 ``kompose`` 등의 도구로 Kubernetes 매니페스트로 변환하거나, +직접 매니페스트를 작성하여 운용할 수 있습니다(공식 Helm 차트는 제공되지 않습니다). + +Q: 컨테이너 업데이트는 어떻게 수행합니까? +-------------------------------------------------- + +A: 다음 절차로 업데이트합니다: + +1. 최신 Compose 파일 가져오기 +2. 컨테이너 중지:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +3. 새 이미지 가져오기:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull + +4. 컨테이너 시작:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +Q: 다중 노드 구성이 가능합니까? +-------------------------------------- + +A: 가능합니다. ``docker-fess`` 리포지토리의 ``snapshot/compose-cluster.yaml`` 을 참고하여 OpenSearch를 여러 노드로 구성하거나, +``multi-instance/`` 를 참고하여 하나의 OpenSearch를 공유하는 여러 개의 Fess 인스턴스를 구성할 수 있습니다. +다만 운영 환경에서는 Kubernetes 등의 오케스트레이션 도구 사용을 권장합니다. diff --git a/ko/15.10/install/install-linux.rst b/ko/15.10/install/install-linux.rst new file mode 100644 index 000000000..2adde8162 --- /dev/null +++ b/ko/15.10/install/install-linux.rst @@ -0,0 +1,546 @@ +====================== +Linux 설치 (상세 절차) +====================== + +이 페이지에서는 Linux 환경에 |Fess| 를 설치하는 절차를 설명합니다. +ZIP, RPM, DEB 각 패키지 형식에 대응합니다. + +.. note:: + + |Fess| 는 검색 엔진을 포함하지 않습니다. OpenSearch 서버가 별도로 필요하며, + 아래 절차에서 구축합니다. + +전제 조건 +========= + +- :doc:`prerequisites` 에 기재된 시스템 요구사항을 충족할 것 +- Java 21이 설치되어 있을 것 +- OpenSearch 3.9.0을 사용 가능한 상태로 할 것(또는 신규 설치) + +설치 방법 선택 +============== + +Linux 환경에서는 다음 설치 방법 중에서 선택할 수 있습니다: + +.. list-table:: + :header-rows: 1 + :widths: 20 40 40 + + * - 방식 + - 권장 환경 + - 특징 + * - ZIP + - 개발 환경, 커스터마이징이 필요한 환경 + - 임의의 디렉터리에 압축 해제 가능 + * - RPM + - RHEL, CentOS, Fedora 계열 + - systemd를 통한 서비스 관리 가능 + * - DEB + - Debian, Ubuntu 계열 + - systemd를 통한 서비스 관리 가능 + +OpenSearch 실행을 위한 시스템 설정 +================================== + +OpenSearch를 Linux에서 안정적으로 동작시키려면 다음 커널 매개변수 및 리소스 제한을 설정합니다. +이는 주로 TAR.GZ 버전(OpenSearch를 수동으로 설치하는 경우)에서 필요합니다. +RPM / DEB 버전에서는 OpenSearch 및 |Fess| 패키지가 systemd를 통해 파일 디스크립터 수 등을 설정하지만, ``vm.max_map_count`` 는 호스트 측 커널 설정이므로 어느 방식이든 확인하시기 바랍니다. + +가상 메모리 최대 맵 수 +---------------------- + +OpenSearch는 다수의 메모리 맵을 사용하므로 ``vm.max_map_count`` 를 ``262144`` 이상으로 설정합니다. + +일시적으로 설정하는 경우:: + + $ sudo sysctl -w vm.max_map_count=262144 + +영구적으로 설정하는 경우:: + + $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf + $ sudo sysctl -p + +파일 디스크립터 수 +------------------ + +OpenSearch를 수동으로 실행하는 경우(TAR.GZ 버전)에는 OpenSearch를 실행하는 사용자의 파일 디스크립터 수 상한을 ``65535`` 이상으로 설정합니다. + +``/etc/security/limits.conf`` 에 다음을 추가합니다(``opensearch`` 는 OpenSearch를 실행하는 사용자 이름으로 바꿔주세요):: + + opensearch - nofile 65535 + +.. note:: + + RPM / DEB 버전에서는 systemd 서비스 정의에서 파일 디스크립터 수 상한이 설정되므로 이 설정은 필요하지 않습니다. + +ZIP 버전 설치 +================ + +단계 1: OpenSearch 설치 +----------------------- + +.. important:: + + OpenSearch 는 ``root`` 로는 시작되지 않으므로 일반 사용자로 설치하고 실행하십시오. 아래의 ``bin/fess-setup`` 도 같은 사용자로 실행하여, 압축 해제되는 파일의 소유자가 그 사용자가 되도록 하십시오. ``root`` 로 시작하려다 이미 거부된 경우에는 :doc:`run` 을 참조하십시오. + +.. tip:: + + |Fess| 에 포함된 ``bin/fess-setup`` 으로 아래 절차 1~3을 한 번에 실행할 수 있습니다. OpenSearch 를 |Fess| 디렉터리의 ``opensearch/`` 에 다운로드하여 압축 해제하고, 필요한 플러그인을 설치한 다음, 해당 ``config/opensearch.yml`` 에 ``configsync.config_path`` 와 ``plugins.security.disabled: true`` 를 추가합니다. 먼저 단계 2 에 설명된 대로 |Fess| 의 ZIP 을 압축 해제해 두십시오. + + :: + + $ cd /path/to/fess-15.10.0 + $ bin/fess-setup install opensearch + + 이 방법으로 설치한 OpenSearch 는 ``bin/fess.in.sh`` 가 찾아서 ``FESS_DICTIONARY_PATH`` 를 자동으로 설정하므로, OpenSearch 를 같은 호스트에서 실행하는 한 단계 2 의 「Fess 설정」은 변경할 필요가 없습니다. 명령은 추가한 설정과, ``bin/fess.in.sh`` 가 이 설치를 찾을 수 있는지를 표시합니다. OpenSearch 가 ``localhost`` 이외의 주소에서 수신 대기하기 전에 절차 3의 경고를 확인하십시오. + + 절차를 하나씩 확인하려는 경우나 기존 OpenSearch 를 사용하는 경우에는 아래를 따르십시오. + 기존 OpenSearch 에 플러그인만 설치하려면 + ``bin/fess-setup install opensearch-plugins --opensearch-home /path/to/opensearch`` 를 사용합니다. + 모든 명령에 대해서는 :doc:`fess-setup` 을 참조하십시오. + +.. note:: + + OpenSearch 는 macOS 용 공식 배포판이 없으므로, macOS 에서는 ``bin/fess-setup install opensearch`` 가 오류로 종료됩니다. Homebrew 로 OpenSearch 를 설치하고 ``bin/fess-setup install opensearch-plugins`` 로 플러그인을 넣거나, 대신 :doc:`install-docker` 를 사용하십시오:: + + $ brew install opensearch + $ bin/fess-setup install opensearch-plugins --opensearch-home $(brew --prefix opensearch) + + 그런 다음 절차 3과 같이 OpenSearch 를 설정하고, 단계 2 의 「Fess 설정」에 따라 ``FESS_DICTIONARY_PATH`` 를 설정하십시오. + +1. OpenSearch 다운로드 + + `Download OpenSearch `__ 에서 TAR.GZ 버전을 다운로드합니다. + + :: + + $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.9.0/opensearch-3.9.0-linux-x64.tar.gz + $ tar -xzf opensearch-3.9.0-linux-x64.tar.gz + $ cd opensearch-3.9.0 + + arm64(aarch64) 머신에서는 위 파일명의 ``linux-x64`` 를 ``linux-arm64`` 로 바꾸십시오(예: ``opensearch-3.9.0-linux-arm64.tar.gz``). + + .. note:: + + 이 예제에서는 OpenSearch 3.9.0을 사용하고 있습니다. + |Fess| 15.10은 OpenSearch 3.9.0에 대응합니다. + +2. OpenSearch 플러그인 설치 + + |Fess| 가 필요로 하는 플러그인을 설치합니다. + + :: + + $ cd /path/to/opensearch-3.9.0 + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + + .. important:: + + 플러그인 버전은 OpenSearch 버전과 일치시켜야 합니다. + 위의 예제에서는 모두 3.9.0을 지정하고 있습니다. + + |Fess| 용 플러그인 4개는 maven.codelibs.org 에 공개되어 있으므로 URL로 지정합니다. ``opensearch-plugin install`` 의 ``groupId:artifactId:version`` 형식은 Maven Central만 참조합니다. + +3. OpenSearch 설정 + + ``config/opensearch.yml`` 에 다음 설정을 추가합니다. + + :: + + # 설정 동기화용 경로(절대 경로로 지정) + configsync.config_path: /path/to/opensearch-3.9.0/config/dictionary/ + + # 보안 플러그인 비활성화(개발 환경 전용) + plugins.security.disabled: true + + .. important:: + + ``configsync.config_path`` 에는 OpenSearch 설정 디렉터리(이 예에서는 ``/path/to/opensearch-3.9.0/config/``) 아래의 디렉터리를 지정하십시오. + OpenSearch 3.8.0 이상에서는 사전 파일이 설정 디렉터리 밖에 있으면 인덱스 생성을 거부합니다. + ``/path/to/opensearch-3.9.0/data/config/`` 등 설정 디렉터리 밖을 지정하면 |Fess| 는 인덱스를 생성할 수 없어 시작되지 않습니다. + + .. warning:: + + **보안 관련 중요 주의사항** + + ``plugins.security.disabled: true`` 는 개발 환경이나 테스트 환경에서만 사용하십시오. + 운영 환경에서는 OpenSearch의 보안 플러그인을 활성화하고 적절한 인증·인가 설정을 수행하십시오. + OpenSearch 2.12 이후 버전에서 보안 플러그인을 활성화하는 경우, 최초 시작 시 관리자 비밀번호(환경 변수 ``OPENSEARCH_INITIAL_ADMIN_PASSWORD``)를 설정해야 합니다. + 자세한 내용은 :doc:`security` 를 참조하십시오. + + .. tip:: + + 클러스터 이름 및 네트워크 설정 등 기타 설정은 환경에 맞게 조정하십시오. + 설정 예:: + + cluster.name: fess-cluster + node.name: fess-node-1 + network.host: 0.0.0.0 + discovery.type: single-node + + .. tip:: + + OpenSearch의 힙 크기는 ``config/jvm.options`` 의 ``-Xms`` / ``-Xmx`` 로 설정합니다. + 사용 가능한 물리 메모리의 절반 이하이면서 32GB 미만을 기준으로, ``-Xms`` 와 ``-Xmx`` 에 동일한 값을 지정할 것을 권장합니다. + +단계 2: Fess 설치 +----------------- + +1. Fess 다운로드 및 압축 해제 + + `다운로드 사이트 `__ 에서 ZIP 버전을 다운로드합니다. + + :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.zip + $ unzip fess-15.10.0.zip + $ cd fess-15.10.0 + + .. note:: + + 경로에 공백 문자가 포함되지 않은 디렉터리를 선택하십시오(macOS에서도 마찬가지입니다). 경로에 공백 문자가 포함되어 있으면 ``bin/fess`` 가 시작되지 않고 ``Could not find or load main class`` 가 출력됩니다. + +2. Fess 설정 + + OpenSearch 연결 정보는 ``bin/fess.in.sh`` 에 있습니다. ``bin/fess-setup install opensearch`` 로 |Fess| 디렉터리의 ``opensearch/`` 에 설치하고 같은 호스트에서 실행하는 OpenSearch 라면 이 파일을 변경할 필요가 없습니다. ``SEARCH_ENGINE_HTTP_URL`` 의 기본값은 ``http://localhost:9200`` 이며, ``FESS_DICTIONARY_PATH`` 에는 해당 OpenSearch 의 ``config/dictionary`` 디렉터리가 설정됩니다. + + 다음 중 하나에 해당하는 경우에는 ``bin/fess.in.sh`` 를 편집합니다. + + - OpenSearch 를 위의 절차 1~3이나 Homebrew 등 다른 방법으로 설치한 경우, 또는 ``--dest`` 로 |Fess| 디렉터리 밖에 설치한 경우 + - |Fess| 디렉터리의 ``opensearch/`` 에 ``bin/fess-setup`` 으로 설치한 OpenSearch 가 두 개 이상 있는 경우(예: 두 버전). ``bin/fess.in.sh`` 는 어느 것을 사용하는지 판단할 수 없으므로 경고를 표시하고 ``FESS_DICTIONARY_PATH`` 를 설정하지 않습니다 + - OpenSearch 를 다른 호스트나 포트에서 실행하는 경우 + + :: + + $ vi bin/fess.in.sh + + 파일 앞부분에 있는 ``FESS_DICTIONARY_PATH`` 줄의 주석(``#``)을 해제하여 경로를 설정하고, 필요에 따라 ``SEARCH_ENGINE_HTTP_URL`` 줄의 URL 을 변경합니다. + + 변경 전(기본 상태, 주석 줄은 생략):: + + SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://localhost:9200} + #FESS_DICTIONARY_PATH=/var/lib/opensearch/config/ + + 변경 후:: + + SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://localhost:9200} + FESS_DICTIONARY_PATH=/path/to/opensearch-3.9.0/config/dictionary/ + + .. note:: + + - ``FESS_DICTIONARY_PATH`` 에는 OpenSearch의 ``opensearch.yml`` 에서 지정한 ``configsync.config_path`` 와 동일한 경로를 설정하십시오. 설정하지 않으면 |Fess| 는 인덱스를 생성할 수 없어 시작되지 않습니다. + - OpenSearch를 다른 호스트에서 실행하는 경우 ``SEARCH_ENGINE_HTTP_URL`` 줄의 URL 을 그 호스트로 변경하십시오. 예: ``SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://192.168.1.100:9200}`` . 이때 ``FESS_DICTIONARY_PATH`` 에는 그 서버의 ``configsync.config_path`` 를 설정합니다. + - 파일을 편집하는 대신 |Fess| 를 시작하는 환경에서 두 변수를 export 할 수도 있습니다. export 한 ``SEARCH_ENGINE_HTTP_URL`` 은 파일의 URL 보다 우선하며, export 한 ``FESS_DICTIONARY_PATH`` 는 파일의 해당 줄이 주석 상태로 남아 있으면 사용됩니다. + - 새로 ``SEARCH_ENGINE_HTTP_URL=...`` 줄을 추가하지 말고 기존 줄을 편집하십시오. + + .. tip:: + + |Fess| 의 힙 크기를 변경하려면 ``bin/fess.in.sh`` 의 ``FESS_MIN_MEM`` (기본값: ``256m``) 과 ``FESS_MAX_MEM`` (기본값: ``2g``) 을 편집하거나 환경 변수 ``FESS_HEAP_SIZE`` 를 설정합니다. + +3. 설치 확인 + + 설정 파일이 올바르게 편집되었는지 확인합니다:: + + $ grep "SEARCH_ENGINE_HTTP_URL" bin/fess.in.sh + $ grep "FESS_DICTIONARY_PATH" bin/fess.in.sh + + OpenSearch 를 시작한 후에는 ``bin/fess-setup check`` 로 OpenSearch 에 접속할 수 있는지, |Fess| 가 필요로 하는 플러그인이 설치되어 있는지, ``configsync`` 가 응답하는지 확인할 수 있습니다. 실패한 항목이 없으면 종료 코드 ``0`` 으로 종료합니다. OpenSearch 가 ``http://localhost:9200`` 에 있지 않은 경우에는 ``--url`` 을 지정하십시오. + +단계 3: 시작 +------------ + +시작 절차는 :doc:`run` 을 참조하십시오. + +RPM 버전 설치 +============= + +RPM 버전은 Red Hat Enterprise Linux, CentOS, Fedora 등 RPM 기반 Linux 배포판에서 사용합니다. + +단계 1: OpenSearch 설치 +----------------------- + +1. OpenSearch RPM 다운로드 및 설치 + + `Download OpenSearch `__ 에서 RPM 패키지를 다운로드하여 설치합니다. + + :: + + $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.9.0/opensearch-3.9.0-linux-x64.rpm + $ sudo rpm -ivh opensearch-3.9.0-linux-x64.rpm + + arm64(aarch64) 머신에서는 위 파일명의 ``linux-x64`` 를 ``linux-arm64`` 로 바꾸십시오(예: ``opensearch-3.9.0-linux-arm64.rpm``). + + 또는 리포지토리를 추가하여 설치할 수도 있습니다. + 자세한 내용은 `Installing OpenSearch `__ 를 참조하십시오. + +2. OpenSearch 플러그인 설치 + + :: + + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + +3. OpenSearch 설정 + + ``/etc/opensearch/opensearch.yml`` 에 다음 설정을 추가합니다. + + :: + + $ sudo vi /etc/opensearch/opensearch.yml + + 추가할 설정:: + + configsync.config_path: /etc/opensearch/dictionary/ + plugins.security.disabled: true + + 사전 파일용 디렉터리를 생성합니다:: + + $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary + + .. important:: + + ``configsync.config_path`` 에는 OpenSearch 설정 디렉터리 ``/etc/opensearch/`` 아래의 디렉터리를 지정하십시오. + OpenSearch 3.8.0 이상에서는 사전 파일이 설정 디렉터리 밖에 있으면 인덱스 생성을 거부합니다. + ``/var/lib/opensearch/data/config/`` 등 설정 디렉터리 밖을 지정하면 |Fess| 는 인덱스를 생성할 수 없어 시작되지 않습니다. + + .. warning:: + + 운영 환경에서는 ``plugins.security.disabled: true`` 를 사용하지 마십시오. + :doc:`security` 를 참조하여 적절한 보안 설정을 수행하십시오. + +단계 2: Fess 설치 +----------------- + +1. Fess RPM 설치 + + `다운로드 사이트 `__ 에서 RPM 패키지를 다운로드하여 설치합니다. + + :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.rpm + $ sudo rpm -ivh fess-15.10.0.rpm + +2. Fess 설정 + + RPM 버전에서는 환경 변수 설정 파일 ``/etc/sysconfig/fess`` 를 편집합니다. + 이 파일은 패키지 업그레이드 시에도 유지됩니다(``/usr/share/fess/bin/fess.in.sh`` 는 업그레이드 시 덮어써지므로 직접 편집하지 마십시오). + + :: + + $ sudo vi /etc/sysconfig/fess + + OpenSearch 연결 정보를 설정합니다. ``FESS_DICTIONARY_PATH`` 의 기본값 ``/var/lib/opensearch/config/`` 는 단계 3의 ``configsync.config_path`` 와 다르므로 다음과 같이 변경합니다. ``SEARCH_ENGINE_HTTP_URL`` 은 필요에 따라 변경하십시오:: + + SEARCH_ENGINE_HTTP_URL=http://localhost:9200 + FESS_DICTIONARY_PATH=/etc/opensearch/dictionary/ + + .. note:: + + ``FESS_DICTIONARY_PATH`` 는 ``opensearch.yml`` 의 ``configsync.config_path`` 와 동일한 경로를 지정하십시오. + +3. 서비스 등록 및 활성화 + + systemd를 사용하여 서비스를 활성화합니다(RHEL 8 이상, CentOS 8 이상에서는 systemd가 표준입니다):: + + $ sudo systemctl daemon-reload + $ sudo systemctl enable opensearch.service + $ sudo systemctl enable fess.service + + .. note:: + + |Fess| 서비스는 OpenSearch 서비스에 의존하므로 OpenSearch를 먼저 시작해야 합니다. + + .. note:: + + systemd를 사용하지 않는 기존 환경에서는 ``chkconfig`` 로 |Fess| 를 등록할 수 있습니다:: + + $ sudo /sbin/chkconfig --add fess + +단계 3: 시작 +------------ + +시작 절차는 :doc:`run` 을 참조하십시오. + +DEB 버전 설치 +============= + +DEB 버전은 Debian, Ubuntu 등 DEB 기반 Linux 배포판에서 사용합니다. + +단계 1: OpenSearch 설치 +----------------------- + +1. OpenSearch DEB 다운로드 및 설치 + + `Download OpenSearch `__ 에서 DEB 패키지를 다운로드하여 설치합니다. + + :: + + $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.9.0/opensearch-3.9.0-linux-x64.deb + $ sudo dpkg -i opensearch-3.9.0-linux-x64.deb + + arm64(aarch64) 머신에서는 위 파일명의 ``linux-x64`` 를 ``linux-arm64`` 로 바꾸십시오(예: ``opensearch-3.9.0-linux-arm64.deb``). + + 또는 리포지토리를 추가하여 설치할 수도 있습니다. + 자세한 내용은 `Installing OpenSearch `__ 를 참조하십시오. + +2. OpenSearch 플러그인 설치 + + :: + + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + +3. OpenSearch 설정 + + ``/etc/opensearch/opensearch.yml`` 에 다음 설정을 추가합니다. + + :: + + $ sudo vi /etc/opensearch/opensearch.yml + + 추가할 설정:: + + configsync.config_path: /etc/opensearch/dictionary/ + plugins.security.disabled: true + + 사전 파일용 디렉터리를 생성합니다:: + + $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary + + .. important:: + + ``configsync.config_path`` 에는 OpenSearch 설정 디렉터리 ``/etc/opensearch/`` 아래의 디렉터리를 지정하십시오. + OpenSearch 3.8.0 이상에서는 사전 파일이 설정 디렉터리 밖에 있으면 인덱스 생성을 거부합니다. + ``/var/lib/opensearch/data/config/`` 등 설정 디렉터리 밖을 지정하면 |Fess| 는 인덱스를 생성할 수 없어 시작되지 않습니다. + + .. warning:: + + 운영 환경에서는 ``plugins.security.disabled: true`` 를 사용하지 마십시오. + :doc:`security` 를 참조하여 적절한 보안 설정을 수행하십시오. + +단계 2: Fess 설치 +----------------- + +1. Fess DEB 설치 + + `다운로드 사이트 `__ 에서 DEB 패키지를 다운로드하여 설치합니다. + + :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.deb + $ sudo dpkg -i fess-15.10.0.deb + +2. Fess 설정 + + DEB 버전에서는 환경 변수 설정 파일 ``/etc/default/fess`` 를 편집합니다. + 이 파일은 패키지 업그레이드 시에도 유지됩니다(``/usr/share/fess/bin/fess.in.sh`` 는 업그레이드 시 덮어써지므로 직접 편집하지 마십시오). + + :: + + $ sudo vi /etc/default/fess + + OpenSearch 연결 정보를 설정합니다. ``FESS_DICTIONARY_PATH`` 의 기본값 ``/var/lib/opensearch/config/`` 는 단계 3의 ``configsync.config_path`` 와 다르므로 다음과 같이 변경합니다. ``SEARCH_ENGINE_HTTP_URL`` 은 필요에 따라 변경하십시오:: + + SEARCH_ENGINE_HTTP_URL=http://localhost:9200 + FESS_DICTIONARY_PATH=/etc/opensearch/dictionary/ + + .. note:: + + ``FESS_DICTIONARY_PATH`` 는 ``opensearch.yml`` 의 ``configsync.config_path`` 와 동일한 경로를 지정하십시오. + +3. 서비스 등록 및 활성화 + + systemd를 사용하여 서비스를 활성화합니다:: + + $ sudo systemctl daemon-reload + $ sudo systemctl enable opensearch.service + $ sudo systemctl enable fess.service + + .. note:: + + |Fess| 서비스는 OpenSearch 서비스에 의존하므로 OpenSearch를 먼저 시작해야 합니다. + +단계 3: 시작 +------------ + +시작 절차는 :doc:`run` 을 참조하십시오. + +설치 후 확인 +============ + +설치가 완료되면 다음을 확인하십시오: + +1. **설정 파일 확인** + + - OpenSearch 설정 파일(opensearch.yml) + - |Fess| 설정 파일 + + - ZIP 버전: ``bin/fess.in.sh`` + - RPM 버전: ``/etc/sysconfig/fess`` + - DEB 버전: ``/etc/default/fess`` + +2. **디렉터리 권한** + + 설정에서 지정한 디렉터리(``configsync.config_path`` / ``FESS_DICTIONARY_PATH``)가 존재하며 적절한 권한이 설정되어 있는지 확인합니다. + + ZIP 버전의 경우:: + + $ ls -ld /path/to/opensearch-3.9.0/config/dictionary/ + + RPM/DEB 버전의 경우:: + + $ sudo ls -ld /etc/opensearch/dictionary/ + +3. **커널 매개변수 확인** + + :: + + $ sysctl vm.max_map_count + + 값이 ``262144`` 이상인지 확인합니다. + +4. **Java 버전 확인** + + :: + + $ java -version + + Java 21 이상이 설치되어 있는지 확인합니다. + +다음 단계 +========= + +설치가 완료되면 다음 문서를 참조하십시오: + +- :doc:`run` - |Fess| 시작 및 초기 설정 +- :doc:`security` - 운영 환경의 보안 설정 +- :doc:`troubleshooting` - 문제 해결 + +자주 묻는 질문 +============== + +Q: OpenSearch 버전은 다른 버전에서도 작동합니까? +------------------------------------------------ + +A: |Fess| 는 특정 버전의 OpenSearch에 의존합니다. +플러그인 호환성을 보장하기 위해 권장 버전(3.9.0)을 사용할 것을 강력히 권장합니다. +다른 버전을 사용하는 경우 플러그인 버전도 적절히 조정해야 합니다. + +Q: 여러 Fess 인스턴스에서 동일한 OpenSearch를 공유할 수 있습니까? +----------------------------------------------------------------- + +A: 가능하지만 권장하지 않습니다. 각 Fess 인스턴스에는 전용 OpenSearch 클러스터를 준비할 것을 권장합니다. +여러 Fess 인스턴스에서 OpenSearch를 공유하는 경우 인덱스 이름 충돌에 주의하십시오. + +Q: OpenSearch를 클러스터 구성으로 만드는 방법은? +------------------------------------------------ + +A: OpenSearch 공식 문서 `Cluster formation `__ 을 참조하십시오. +클러스터 구성으로 만드는 경우 ``discovery.type: single-node`` 설정을 제거하고 적절한 클러스터 설정을 추가해야 합니다. diff --git a/ko/15.10/install/install-windows.rst b/ko/15.10/install/install-windows.rst new file mode 100644 index 000000000..643c928c1 --- /dev/null +++ b/ko/15.10/install/install-windows.rst @@ -0,0 +1,348 @@ +==================================== +Windows 설치 (상세 절차) +==================================== + +이 페이지에서는 Windows 환경에 |Fess| 를 설치하는 절차를 설명합니다. +ZIP 패키지를 사용한 설치 방법에 대해 기재하고 있습니다. + +.. note:: + + |Fess| 는 검색 엔진을 포함하지 않습니다. OpenSearch 서버가 별도로 필요하며, + 아래 절차에서 구축합니다. + +전제 조건 +========= + +- :doc:`prerequisites` 에 기재된 시스템 요구사항을 충족할 것 +- Java 21이 설치되어 있을 것 +- OpenSearch 3.9.0을 사용 가능한 상태로 할 것(또는 신규 설치) +- Windows 환경 변수 ``JAVA_HOME`` 이 적절히 설정되어 있을 것 + +Java 설치 확인 +==================== + +명령 프롬프트 또는 PowerShell을 열고 다음 명령으로 Java 버전을 확인합니다. + +명령 프롬프트의 경우:: + + C:\> java -version + +PowerShell의 경우:: + + PS C:\> java -version + +Java 21 이상이 표시되는지 확인하십시오. + +환경 변수 설정 +============== + +1. ``JAVA_HOME`` 환경 변수 설정 + + Java가 설치된 디렉터리를 ``JAVA_HOME`` 으로 설정합니다. + + 예:: + + JAVA_HOME=C:\Program Files\Eclipse Adoptium\jdk-21.0.1.12-hotspot + +2. ``PATH`` 환경 변수에 추가 + + ``%JAVA_HOME%\bin`` 을 ``PATH`` 환경 변수에 추가합니다. + +.. tip:: + + 환경 변수 설정 방법: + + 1. "시작" 메뉴에서 "설정" 열기 + 2. "시스템"→"정보"→"고급 시스템 설정" 클릭 + 3. "환경 변수" 버튼 클릭 + 4. "시스템 환경 변수" 또는 "사용자 환경 변수"에서 설정 + +단계 1: OpenSearch 설치 +=================================== + +.. tip:: + + |Fess| 에 포함된 ``bin\fess-setup`` 으로 아래 절차를 한 번에 실행할 수 있습니다. OpenSearch 를 |Fess| 디렉터리의 ``opensearch\`` 에 다운로드하여 압축 해제하고, 필요한 플러그인을 설치한 다음, 해당 ``config\opensearch.yml`` 에 ``configsync.config_path`` 와 ``plugins.security.disabled: true`` 를 추가합니다. 먼저 단계 2 에 설명된 대로 |Fess| 의 ZIP 을 압축 해제해 두십시오. + + :: + + > cd C:\fess-15.10.0 + > bin\fess-setup install opensearch + + 이 방법으로 설치한 OpenSearch 는 ``bin\fess.in.bat`` 이 찾아서 그 ``config\dictionary`` 디렉터리를 |Fess| 에 전달하므로, OpenSearch 를 같은 호스트에서 실행하는 한 단계 2 의 「Fess 설정」은 변경할 필요가 없습니다. 명령은 추가한 설정과, ``bin\fess.in.bat`` 이 이 설치를 찾을 수 있는지를 표시합니다. OpenSearch 가 ``localhost`` 이외의 주소에서 수신 대기하기 전에 「OpenSearch 설정」의 경고를 확인하십시오. + + 절차를 하나씩 확인하려는 경우나 기존 OpenSearch 를 사용하는 경우에는 아래를 따르십시오. + 기존 OpenSearch 에 플러그인만 설치하려면 + ``bin\fess-setup install opensearch-plugins --opensearch-home C:\opensearch-3.9.0`` 을 사용합니다. + 모든 명령에 대해서는 :doc:`fess-setup` 을 참조하십시오. + +OpenSearch 다운로드 +----------------------- + +1. `Download OpenSearch `__ 에서 Windows용 ZIP 패키지를 다운로드합니다. + +2. 다운로드한 ZIP 파일을 임의의 디렉터리에 압축 해제합니다. + + 예:: + + C:\opensearch-3.9.0 + + .. note:: + + 경로에 한국어나 공백 문자가 포함되지 않은 디렉터리를 선택할 것을 권장합니다. + +OpenSearch 플러그인 설치 +--------------------------------- + +명령 프롬프트를 **관리자 권한으로** 열고 다음 명령을 실행합니다. + +:: + + C:\> cd C:\opensearch-3.9.0 + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + +.. important:: + + 플러그인 버전은 OpenSearch 버전과 일치시켜야 합니다. + 위의 예제에서는 모두 3.9.0을 지정하고 있습니다. + + |Fess| 용 플러그인 4개는 maven.codelibs.org 에 공개되어 있으므로 URL로 지정합니다. ``opensearch-plugin install`` 의 ``groupId:artifactId:version`` 형식은 Maven Central만 참조합니다. + +OpenSearch 설정 +--------------- + +``config\opensearch.yml`` 을 텍스트 편집기로 열고 다음 설정을 추가합니다. + +:: + + # 설정 동기화용 경로(절대 경로로 지정) + configsync.config_path: C:/opensearch-3.9.0/config/dictionary/ + + # 보안 플러그인 비활성화(개발 환경 전용) + plugins.security.disabled: true + +.. warning:: + + **보안 관련 중요 주의사항** + + ``plugins.security.disabled: true`` 는 개발 환경이나 테스트 환경에서만 사용하십시오. + 운영 환경에서는 OpenSearch의 보안 플러그인을 활성화하고 적절한 인증·권한 설정을 수행하십시오. + 자세한 내용은 :doc:`security` 를 참조하십시오. + +.. note:: + + Windows의 경우 경로 구분 문자는 ``\`` 가 아닌 ``/`` 를 사용하십시오. + ``C:\opensearch-3.9.0\config\dictionary\`` 가 아니라 ``C:/opensearch-3.9.0/config/dictionary/`` 로 기술합니다. + +.. important:: + + ``configsync.config_path`` 에는 OpenSearch 설정 디렉터리(이 예에서는 ``C:/opensearch-3.9.0/config/``) 아래의 디렉터리를 지정하십시오. + OpenSearch 3.8.0 이상에서는 사전 파일이 설정 디렉터리 밖에 있으면 인덱스 생성을 거부합니다. + ``C:/opensearch-3.9.0/data/config/`` 등 설정 디렉터리 밖을 지정하면 |Fess| 는 인덱스를 생성할 수 없어 시작되지 않습니다. + +.. tip:: + + 기타 권장 설정:: + + cluster.name: fess-cluster + node.name: fess-node-1 + network.host: 0.0.0.0 + discovery.type: single-node + +.. tip:: + + OpenSearch의 힙 크기는 ``config\jvm.options`` 의 ``-Xms`` / ``-Xmx`` 로 설정합니다. + 사용 가능한 물리 메모리의 절반 이하이며 32GB 미만을 기준으로, ``-Xms`` 와 ``-Xmx`` 에는 동일한 값을 지정할 것을 권장합니다. + +단계 2: Fess 설치 +============================= + +Fess 다운로드 +----------------- + +1. `다운로드 사이트 `__ 에서 Windows용 ZIP 패키지를 다운로드합니다. + +2. 다운로드한 ZIP 파일을 임의의 디렉터리에 압축 해제합니다. + + 예:: + + C:\fess-15.10.0 + + .. note:: + + 경로에 한국어나 공백 문자가 포함되지 않은 디렉터리를 선택할 것을 권장합니다. + +Fess 설정 +---------- + +``bin\fess-setup install opensearch`` 로 |Fess| 디렉터리의 ``opensearch\`` 에 설치하고 같은 호스트에서 실행하는 OpenSearch 라면 여기서 설정할 필요가 없습니다. 위의 절차로 OpenSearch 를 설치한 경우, OpenSearch 를 다른 호스트에서 실행하는 경우, ``opensearch\`` 에 ``bin\fess-setup`` 으로 설치한 OpenSearch 가 두 개 이상 있는 경우 등에는 다음과 같이 연결 대상을 설정합니다. + +``bin\fess.in.bat`` 을 텍스트 편집기로 엽니다. +이 파일의 끝부분 근처에는 외부 OpenSearch 클러스터에 연결하기 위한 설정이 미리 주석 처리된 상태로 준비되어 있습니다. + +변경 전(기본 상태):: + + REM External opensearch cluster + REM set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200 + REM set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=C:/opensearch/config/dictionary + +아래 2행의 행 시작 부분에 있는 ``REM `` 을 삭제하여 주석을 해제하고, ``fess.dictionary.path`` 의 값을 OpenSearch의 설정 동기화용 경로로 변경합니다. + +변경 후:: + + REM External opensearch cluster + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200 + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=C:/opensearch-3.9.0/config/dictionary/ + +.. note:: + + - ``fess.dictionary.path`` 에는 OpenSearch의 ``opensearch.yml`` 에서 지정한 ``configsync.config_path`` 와 동일한 경로를 설정하십시오. + - OpenSearch를 다른 호스트에서 실행하는 경우 ``fess.search_engine.http_address`` 의 호스트 이름 또는 IP 주소를 적절한 값으로 변경하십시오. + - 경로 구분 문자는 ``/`` 를 사용하십시오. |Fess| 는 이 경로를 인덱스 설정에 삽입하며, 그때 ``\`` 가 사라지므로 ``\`` 로 쓴 경로는 찾을 수 없습니다. + - 새로 ``set FESS_JAVA_OPTS=...`` 행을 추가하는 것이 아니라 기존 주석 행을 해제하여 편집하십시오. 동일한 옵션을 중복하여 지정하면 의도하지 않은 동작의 원인이 될 수 있습니다. + +.. tip:: + + |Fess| 의 힙 크기를 변경하려면 ``bin\fess.in.bat`` 의 ``FESS_MIN_MEM`` (기본값: ``256m``) 과 ``FESS_MAX_MEM`` (기본값: ``1g``) 을 편집하거나 환경 변수 ``FESS_HEAP_SIZE`` 를 설정하십시오. + +설치 확인 +---------------- + +설정 파일이 올바르게 편집되었는지 확인합니다. + +명령 프롬프트에서:: + + C:\> findstr "fess.search_engine.http_address" C:\fess-15.10.0\bin\fess.in.bat + C:\> findstr "fess.dictionary.path" C:\fess-15.10.0\bin\fess.in.bat + +단계 3: 시작 +============== + +시작 절차는 :doc:`run` 을 참조하십시오. + +Windows 서비스로 등록(옵션) +======================================= + +|Fess| 를 Windows 서비스로 등록하면 시스템 시작 시 자동으로 시작되도록 설정할 수 있습니다. + +|Fess| 에는 Windows 서비스를 등록하기 위한 ``bin\service.bat`` 가 동봉되어 있습니다. +이 스크립트는 Apache Commons Daemon (procrun)을 이용하고 있으므로 NSSM 등의 서드파티 도구를 별도로 준비할 필요가 없습니다. + +.. note:: + + ``service.bat`` 를 실행하기 전에 환경 변수 ``JAVA_HOME`` 이 올바르게 설정되어 있는지 확인하십시오. + +|Fess| 서비스 등록 +-------------------- + +명령 프롬프트를 **관리자 권한으로** 열고 다음 명령을 실행합니다. + +1. 서비스 등록:: + + C:\> cd C:\fess-15.10.0 + C:\fess-15.10.0> bin\service.bat install + + 기본적으로 64비트 환경에서는 ``fess-service-x64``, 32비트 환경에서는 ``fess-service-x86`` 이라는 서비스 ID로 등록됩니다. + 서비스 ID를 명시적으로 지정하는 경우 ``bin\service.bat install <서비스ID>`` 와 같이 인수로 지정합니다. + +2. 서비스 시작·중지:: + + C:\fess-15.10.0> bin\service.bat start + C:\fess-15.10.0> bin\service.bat stop + +3. 서비스 설정 확인·변경 (GUI):: + + C:\fess-15.10.0> bin\service.bat manager + +4. 서비스 삭제:: + + C:\fess-15.10.0> bin\service.bat remove + +.. note:: + + - ``service.bat`` 는 내부에서 ``bin\fess.in.bat`` 를 읽어 들이므로 "Fess 설정"에서 수행한 외부 OpenSearch 연결 설정이 서비스에도 반영됩니다. + - 기본 시작 유형은 "수동"입니다. 시스템 시작 시 자동으로 시작하려면 서비스 등록 전에 환경 변수 ``FESS_START_TYPE`` 을 ``auto`` 로 설정하거나, 등록 후 "서비스" 관리 도구(``services.msc``)에서 시작 유형을 "자동"으로 변경하십시오. + - ``service.bat`` 로 등록할 수 있는 것은 |Fess| 서비스뿐입니다. OpenSearch를 서비스로 등록하는 경우에는 OpenSearch가 제공하는 절차를 참조하십시오. + +방화벽 설정 +================== + +Windows Defender 방화벽에서 필요한 포트를 개방합니다. + +1. "제어판"→"Windows Defender 방화벽"→"고급 설정" 열기 + +2. "인바운드 규칙"에서 새 규칙 만들기 + + - 규칙 유형: 포트 + - 프로토콜 및 포트: TCP, 8080 + - 작업: 연결 허용 + - 이름: Fess Web Interface + +또는 PowerShell에서 실행:: + + PS C:\> New-NetFirewallRule -DisplayName "Fess Web Interface" -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow + +문제 해결 +==================== + +포트 번호 충돌 +-------------- + +포트 8080 또는 9200이 이미 사용 중인 경우 다음 명령으로 확인할 수 있습니다:: + + C:\> netstat -ano | findstr :8080 + C:\> netstat -ano | findstr :9200 + +사용 중인 포트 번호를 변경하거나 충돌하는 프로세스를 중지하십시오. + +경로 길이 제한 +-------------- + +Windows에서는 경로 길이에 제한이 있습니다. 가능한 한 짧은 경로에 설치할 것을 권장합니다. + +예:: + + C:\opensearch (권장) + C:\Program Files\opensearch-3.9.0 (비권장 - 경로가 김) + +Java가 인식되지 않음 +-------------------- + +``java -version`` 명령에서 오류가 표시되는 경우: + +1. ``JAVA_HOME`` 환경 변수가 올바르게 설정되어 있는지 확인 +2. ``PATH`` 환경 변수에 ``%JAVA_HOME%\bin`` 이 포함되어 있는지 확인 +3. 명령 프롬프트를 재시작하여 설정 반영 + +다음 단계 +========== + +설치가 완료되면 다음 문서를 참조하십시오: + +- :doc:`run` - |Fess| 시작 및 초기 설정 +- :doc:`security` - 운영 환경의 보안 설정 +- :doc:`troubleshooting` - 문제 해결 + +자주 묻는 질문 +============== + +Q: Windows Server에서의 운영이 권장됩니까? +------------------------------------------ + +A: 예, Windows Server에서의 운영이 가능합니다. +Windows Server에서 운영하는 경우 Windows 서비스로 등록하고 적절한 모니터링을 설정하십시오. + +Q: 64비트 버전과 32비트 버전의 차이는? +-------------------------------------- + +A: |Fess| 및 OpenSearch는 64비트 버전만 지원합니다. +32비트 버전의 Windows에서는 작동하지 않습니다. + +Q: 경로에 한국어가 포함된 경우 대처 방법은? +------------------------------------------- + +A: 가능한 한 한국어나 공백 문자가 포함되지 않은 경로에 설치하십시오. +어쩔 수 없이 한국어 경로를 사용해야 하는 경우 설정 파일에서 경로를 적절히 이스케이프해야 합니다. diff --git a/ko/15.10/install/install.rst b/ko/15.10/install/install.rst new file mode 100644 index 000000000..d7ca0ecf9 --- /dev/null +++ b/ko/15.10/install/install.rst @@ -0,0 +1,247 @@ +==================== +설치 방법 선택 +==================== + +이 페이지에서는 |Fess| 의 설치 방법 개요에 대해 설명합니다. +사용자의 환경에 맞는 적절한 설치 방법을 선택하시기 바랍니다. + +.. note:: + + |Fess| 는 검색 엔진을 포함하지 않습니다. 아래의 어떤 설치 방법을 사용하더라도 + OpenSearch 서버가 별도로 필요합니다. + +전제 조건 확인 +============== + +설치를 시작하기 전에 시스템 요구사항을 확인하시기 바랍니다. + +자세한 내용은 :doc:`prerequisites` 를 참조하십시오. + +설치 방법 비교 +==================== + +|Fess| 는 다음과 같은 방법으로 설치할 수 있습니다. 사용 환경 및 용도에 따라 선택하십시오. + +.. list-table:: + :header-rows: 1 + :widths: 15 25 30 30 + + * - 방법 + - 대상 OS + - 권장 용도 + - 상세 문서 + * - Docker + - Linux, Windows, macOS + - 개발·평가 환경, 신속한 설정 + - :doc:`install-docker` + * - ZIP + - Linux, macOS + - 커스터마이징이 필요한 환경 + - :doc:`install-linux` + * - RPM + - RHEL, CentOS, Fedora + - 운영 환경(RPM 기반) + - :doc:`install-linux` + * - DEB + - Debian, Ubuntu + - 운영 환경(DEB 기반) + - :doc:`install-linux` + * - ZIP + - Windows + - Windows 환경의 개발·운영 + - :doc:`install-windows` + +각 설치 방법의 특징 +====================== + +Docker 버전 +----------- + +**장점:** + +- 가장 신속하게 설정 가능 +- 의존성 관리 불필요 +- 개발 환경 구축에 최적 +- 컨테이너 시작·중지가 용이 + +**단점:** + +- Docker 지식 필요 + +**권장 환경:** 개발 환경, 평가 환경, POC, 운영 환경 + +상세: :doc:`install-docker` + +Linux 패키지 버전 (ZIP/RPM/DEB) +---------------------------------- + +**장점:** + +- 네이티브 환경에서의 높은 성능 +- 시스템 서비스로 관리 가능(RPM/DEB) +- 세밀한 커스터마이징 가능 + +**단점:** + +- Java 및 OpenSearch 수동 설치 필요 +- 설정에 시간이 소요됨 + +**권장 환경:** 운영 환경 (시스템 서비스로 관리할 수 있는 RPM/DEB 권장), 커스터마이징이 필요한 환경 + +상세: :doc:`install-linux` + +Windows 버전 (ZIP) +------------------ + +**장점:** + +- Windows 네이티브 환경에서 작동 +- 설치 프로그램 불필요 + +**단점:** + +- Java 및 OpenSearch 수동 설치 필요 +- 설정에 시간이 소요됨 + +**권장 환경:** Windows 환경의 개발·평가, Windows Server 운영 + +상세: :doc:`install-windows` + +설치의 기본 절차 +======================== + +모든 설치 방법에서 기본 절차는 동일합니다. + +1. **시스템 요구사항 확인** + + :doc:`prerequisites` 를 참조하여 시스템 요구사항을 충족하는지 확인합니다. + +2. **소프트웨어 다운로드** + + `다운로드 사이트 `__ 에서 |Fess| 를 다운로드합니다. + + Docker 버전의 경우 Docker Compose 파일을 가져옵니다. + +3. **OpenSearch 설정** + + Docker 버전 이외의 경우 OpenSearch를 별도로 설정해야 합니다. + + - OpenSearch 3.9.0 설치 + - 필수 플러그인 설치 + - 설정 파일 편집 + +4. **Fess 설정** + + - Fess 설치 + - 설정 파일 편집(OpenSearch 연결 정보 등) + +5. **시작 및 확인** + + - 서비스 시작 + - 브라우저에서 액세스하여 동작 확인 + + 자세한 내용은 :doc:`run` 을 참조하십시오. + +필요한 구성요소 +================== + +|Fess| 를 실행하려면 다음 구성요소가 필요합니다. + +Fess 본체 +--------- + +전문 검색 시스템의 본체입니다. 웹 인터페이스, 크롤러, 인덱서 등의 기능을 제공합니다. + +OpenSearch +---------- + +검색 엔진으로 OpenSearch를 사용합니다. + +- **지원 버전**: OpenSearch 3.9.0 +- **필수 플러그인**: + + - opensearch-analysis-fess + - opensearch-analysis-extension + - opensearch-minhash + - opensearch-configsync + +.. important:: + + OpenSearch 버전과 플러그인 버전을 일치시켜야 합니다. + 버전 불일치는 시작 오류 또는 예기치 않은 동작의 원인이 됩니다. + +``bin/fess-setup install opensearch`` 는 Linux 와 Windows 에서 이러한 플러그인을 포함하여 OpenSearch 를 준비합니다. 자세한 내용은 OpenSearch 를 다른 방법으로 설치해야 하는 macOS 의 경우를 포함하여 :doc:`install-linux` 를, 모든 명령에 대해서는 :doc:`fess-setup` 을 참조하십시오. + +.. note:: + + 매니지드 서비스 등 이러한 플러그인을 설치할 수 없는 OpenSearch 를 사용하는 경우에는 ``search_engine.type`` 에 ``vanilla`` 를 지정합니다(|Fess| 15.10 이상). 이 경우 사전 관리 등 일부 기능은 사용할 수 없습니다. 자세한 내용은 :doc:`../config/search-engine-type` 을 참조하십시오. + +Java (Docker 버전 제외) +----------------------- + +ZIP/RPM/DEB 버전의 경우 Java 21 이상이 필요합니다. + +- 권장: `Eclipse Temurin `__ +- OpenJDK 21 이상도 사용 가능 + +.. note:: + + Docker 버전의 경우 Java는 Docker 이미지에 포함되어 있으므로 별도로 설치할 필요가 없습니다. + +다음 단계 +========== + +시스템 요구사항을 확인하고 적절한 설치 방법을 선택하십시오. + +1. :doc:`prerequisites` - 시스템 요구사항 확인 +2. 설치 방법 선택: + + - :doc:`install-docker` - Docker 설치 + - :doc:`install-linux` - Linux 설치 + - :doc:`install-windows` - Windows 설치 + +3. :doc:`run` - |Fess| 시작 및 초기 설정 +4. :doc:`security` - 보안 설정(운영 환경의 경우) + +자주 묻는 질문 +============== + +Q: OpenSearch는 필수입니까? +--------------------------- + +A: 예, 필수입니다. |Fess| 는 검색 엔진으로 OpenSearch를 사용합니다. +Docker 버전의 경우 자동으로 설정되지만, 기타 방법에서는 수동으로 설치해야 합니다. + +Q: 이전 버전에서 업그레이드할 수 있습니까? +---------------------------------------------- + +A: 예, 가능합니다. 자세한 내용은 :doc:`upgrade` 를 참조하십시오. + +Q: 여러 서버로 구성할 수 있습니까? +---------------------------------- + +A: 예, 가능합니다. Fess와 OpenSearch를 별도의 서버에서 실행할 수 있습니다. +또한 OpenSearch를 클러스터 구성으로 만들어 고가용성과 성능 향상을 도모할 수 있습니다. + +다운로드 +========== + +|Fess| 및 관련 구성요소는 다음에서 다운로드할 수 있습니다: + +- **Fess**: `다운로드 사이트 `__ +- **OpenSearch**: `Download OpenSearch `__ +- **Java (Adoptium)**: `Adoptium `__ +- **Docker**: `Get Docker `__ + +버전 정보 +============ + +이 문서는 다음 버전을 대상으로 합니다: + +- **Fess**: 15.10.0 +- **OpenSearch**: 3.9.0 +- **Java**: 21 이상 +- **Docker**: 20.10 이상 +- **Docker Compose**: 2.0 이상 + +이전 버전의 문서에 대해서는 각 버전의 문서를 참조하십시오. diff --git a/ko/15.10/install/intro.rst b/ko/15.10/install/intro.rst new file mode 100644 index 000000000..1453b5652 --- /dev/null +++ b/ko/15.10/install/intro.rst @@ -0,0 +1,70 @@ +========= +설치 소개 +========= + +본 문서에 대하여 +================== + +이 설치 가이드는 |Fess| 의 설치, 시작, 업그레이드 및 제거 절차를 설명합니다. +사용자의 환경에 맞는 적절한 설치 방법을 선택하시기 바랍니다. + +대상 독자 +======== + +이 문서는 |Fess| 의 설치 작업 및 제거 작업을 담당하는 사용자를 대상으로 합니다. + +읽기 전에 +============== + +이 문서에서는 |Fess| 의 설치 방법을 안내합니다. 다음의 지식이 필요합니다: + +- 서버 관리 기본 지식 +- Linux 또는 Windows 명령줄 작업 +- 네트워크 및 방화벽 기본 설정 +- Docker 기본 지식 (Docker 버전 사용 시) + +문서 구성 +============== + +이 설치 가이드는 다음 섹션으로 구성되어 있습니다: + +- **시스템 요구사항**: |Fess| 를 실행하는 데 필요한 하드웨어 및 소프트웨어 요구사항 +- **설치**: 플랫폼별 설치 절차 + + - 설치 방법 선택 (개요 및 비교) + - Linux (ZIP/RPM/DEB) 설치 + - Windows (ZIP) 설치 + - Docker 설치 + +- **시작, 중지, 초기 설정**: |Fess| 서버의 시작, 중지 및 초기 설정 +- **보안 설정**: 운영 환경에서 권장되는 보안 설정 +- **업그레이드**: 이전 버전에서 최신 버전으로 업그레이드하는 절차 +- **제거**: |Fess| 의 완전한 제거 절차 +- **문제 해결**: 일반적인 문제 및 해결 방법 + +온라인 액세스 +================= + +다운로드, 전문 서비스, 지원 및 기타 개발자 정보는 다음을 참조하십시오. + +- 프로젝트 사이트: `https://fess.codelibs.org/ `__ + +기술 지원 연락처 +================== + +본 제품에 대한 기술적인 질문이나 문제는 다음을 참조하십시오. + +- Issues: `https://github.com/codelibs/fess/issues `__ + +상용 지원 +--------- + +본 제품에 대한 기술 지원 및 유지보수 등의 상용 지원이 필요한 경우 `N2SM, Inc. `__ 에 문의하시기 바랍니다. + +의견 및 제안 보내기 +===================== + +문제점이나 개선사항이 있으시면 다음을 통해 보내주시기 바랍니다. + +- 제품 문제: `https://github.com/codelibs/fess/issues `__ +- 문서 문제: `https://github.com/codelibs/fess-docs/issues `__ diff --git a/ko/15.10/install/prerequisites.rst b/ko/15.10/install/prerequisites.rst new file mode 100644 index 000000000..2a47901e4 --- /dev/null +++ b/ko/15.10/install/prerequisites.rst @@ -0,0 +1,185 @@ +============ +시스템 요구사항 +============ + +이 페이지에서는 |Fess| 를 실행하는 데 필요한 하드웨어 및 소프트웨어 요구사항에 대해 설명합니다. + +하드웨어 요구사항 +============== + +최소 요구사항 +-------- + +다음은 평가 및 개발 환경의 최소 요구사항입니다: + +- CPU: 2코어 이상 +- 메모리: 4GB 이상 +- 디스크 용량: 10GB 이상의 여유 공간 + +권장 사양 +-------- + +운영 환경에서는 다음 사양을 권장합니다: + +- CPU: 4코어 이상 +- 메모리: 8GB 이상(인덱스 크기에 따라 증설) +- 디스크 용량: + + - 시스템 영역: 20GB 이상 + - 데이터 영역: 인덱스 크기의 3배 이상(복제본 포함) + +- 네트워크: 1Gbps 이상 + +.. note:: + + 인덱스 크기가 커지거나 고빈도 크롤링을 수행하는 경우 + 메모리 및 디스크 용량을 적절히 증설하시기 바랍니다. + +소프트웨어 요구사항 +============== + +운영 체제 +-------------------- + +|Fess| 는 다음 운영 체제에서 작동합니다: + +**Linux** + +- Red Hat Enterprise Linux 8 이상 +- CentOS 8 이상 +- Ubuntu 20.04 LTS 이상 +- Debian 11 이상 +- 기타 Linux 배포판(Java 21 실행 가능 환경) + +**Windows** + +- Windows Server 2019 이상 +- Windows 10 이상 + +**기타** + +- macOS 11 (Big Sur) 이상(개발 환경에만 권장. macOS 용 OpenSearch 공식 배포판은 없으므로 Homebrew 또는 Docker 로 준비합니다) +- Docker 실행 가능 환경 + +필수 소프트웨어 +-------------- + +설치 방법에 따라 다음 소프트웨어가 필요합니다: + +ZIP/RPM/DEB 버전 +~~~~~~~~~~~~~~~~~~~~ + +- **Java 21**: `Eclipse Temurin `__ 권장 + + - OpenJDK 21 이상 + - Eclipse Temurin 21 이상 + +- **OpenSearch 3.9.0**: 필수입니다. OpenSearch 3 이전 버전에서는 |Fess| 가 시작되지 않습니다 + + - 지원 버전: OpenSearch 3.9.0 + - 기타 버전에서는 플러그인 호환성에 주의 필요 + +Docker 버전 +~~~~~~~~~ + +- **Docker**: 20.10 이상 +- **Docker Compose**: 2.0 이상 + +네트워크 요구사항 +============== + +필요한 포트 +---------- + +|Fess| 가 사용하는 주요 포트는 다음과 같습니다: + +.. list-table:: + :header-rows: 1 + :widths: 15 15 50 + + * - 포트 + - 프로토콜 + - 용도 + * - 8080 + - HTTP + - |Fess| 웹 인터페이스(검색 화면·관리 화면) + * - 9200 + - HTTP + - OpenSearch HTTP API(|Fess| 에서 OpenSearch로의 통신) + * - 9300 + - TCP + - OpenSearch 트랜스포트 통신(클러스터 구성 시) + +.. warning:: + + 운영 환경에서는 외부에서 포트 9200 및 9300에 직접 액세스하는 것을 제한할 것을 강력히 권장합니다. + 이러한 포트는 |Fess| 와 OpenSearch 간의 내부 통신에만 사용되어야 합니다. + +방화벽 설정 +------------------ + +|Fess| 를 외부에서 액세스할 수 있게 하려면 포트 8080을 개방해야 합니다. + +**Linux (firewalld 사용 시)** + +:: + + $ sudo firewall-cmd --permanent --add-port=8080/tcp + $ sudo firewall-cmd --reload + +**Linux (iptables 사용 시)** + +:: + + $ sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT + $ sudo iptables-save + +브라우저 요구사항 +============ + +|Fess| 의 관리 화면 및 검색 화면에는 다음 브라우저를 권장합니다: + +- Google Chrome(최신 버전) +- Mozilla Firefox(최신 버전) +- Microsoft Edge(최신 버전) +- Safari(최신 버전) + +.. note:: + + Internet Explorer는 지원되지 않습니다. + +설치 전 체크리스트 +==================== + +설치 전에 다음 항목을 확인하시기 바랍니다: + +.. list-table:: + :header-rows: 1 + :widths: 50 50 + + * - 확인 항목 + - 상태 + * - 하드웨어 요구사항을 충족하는가 + - □ + * - Java 21이 설치되어 있는가(Docker 버전 제외) + - □ + * - Docker가 설치되어 있는가(Docker 버전) + - □ + * - 필요한 포트를 사용할 수 있는가 + - □ + * - 방화벽 설정이 적절한가 + - □ + * - 디스크 용량에 충분한 여유가 있는가 + - □ + * - 네트워크 연결이 정상인가(외부 사이트 크롤링 수행 시) + - □ + +다음 단계 +========== + +시스템 요구사항을 확인했으면 사용 환경에 맞는 설치 절차로 진행하시기 바랍니다: + +- :doc:`install-linux` - Linux (ZIP/RPM/DEB) 설치 +- :doc:`install-windows` - Windows (ZIP) 설치 +- :doc:`install-docker` - Docker 설치 +- :doc:`install` - 설치 방법 개요 diff --git a/ko/15.10/install/run.rst b/ko/15.10/install/run.rst new file mode 100644 index 000000000..1fcceae3f --- /dev/null +++ b/ko/15.10/install/run.rst @@ -0,0 +1,521 @@ +===================== +시작, 중지, 초기 설정 +===================== + +이 페이지에서는 |Fess| 서버의 시작, 중지 및 초기 설정 절차에 대해 설명합니다. + +.. important:: + + |Fess| 를 시작하기 전에 반드시 OpenSearch를 시작하십시오. + OpenSearch가 시작되어 있지 않은 경우 |Fess| 는 올바르게 작동하지 않습니다. + +시작 방법 +========= + +설치 방법에 따라 시작 절차가 다릅니다. + +ZIP 버전의 경우 +------------------ + +OpenSearch 시작 +~~~~~~~~~~~~~~~~ + +:: + + $ cd /path/to/opensearch-3.9.0 + $ ./bin/opensearch + +백그라운드에서 시작하는 경우:: + + $ ./bin/opensearch -d + +.. note:: + + ``bin/fess-setup install opensearch`` 로 설치한 OpenSearch 는 |Fess| 디렉터리의 ``opensearch/opensearch-3.9.0`` 에 있습니다. + +.. important:: + + OpenSearch 는 일반 사용자로 시작하십시오. ``root`` 로 시작하면 ``can not run opensearch as root`` 를 표시하고 종료합니다. 거부된 시작에서도 ``config/opensearch.keystore`` 등의 파일이 ``root`` 소유로 남으며, 다음에 일반 사용자로 시작하면 ``AccessDeniedException`` 으로 실패합니다. 다시 시작하기 전에 OpenSearch 디렉터리의 소유자를 그 사용자로 되돌리십시오. 예:: + + $ sudo chown -R /path/to/opensearch-3.9.0 + +Fess 시작 +~~~~~~~~~~ + +:: + + $ cd /path/to/fess-15.10.0 + $ ./bin/fess + +백그라운드에서 시작하는 경우:: + + $ ./bin/fess -d + +.. note:: + + 시작에는 몇 분 정도 소요될 수 있습니다. + ``logs/`` 디렉터리의 로그 파일에서 시작 상태를 확인할 수 있습니다. ``fess.log`` 에는 |Fess| 자체의 메시지가, + ``server_0.log`` 에는 내장 Tomcat의 메시지(시작 완료 메시지 포함)가 출력됩니다. + +ZIP 버전의 경우(Windows) +------------------------ + +OpenSearch 시작 +~~~~~~~~~~~~~~~~ + +1. OpenSearch 설치 디렉터리를 엽니다 +2. ``bin`` 폴더 내의 ``opensearch.bat`` 을 더블클릭합니다 + +또는 명령 프롬프트에서:: + + C:\> cd C:\opensearch-3.9.0 + C:\opensearch-3.9.0> bin\opensearch.bat + +Fess 시작 +~~~~~~~~~~ + +1. Fess 설치 디렉터리를 엽니다 +2. ``bin`` 폴더 내의 ``fess.bat`` 을 더블클릭합니다 + +또는 명령 프롬프트에서:: + + C:\> cd C:\fess-15.10.0 + C:\fess-15.10.0> bin\fess.bat + +RPM/DEB 버전의 경우 (chkconfig) +------------------------------- + +OpenSearch 시작:: + + $ sudo service opensearch start + +Fess 시작:: + + $ sudo service fess start + +시작 상태 확인:: + + $ sudo service fess status + +RPM/DEB 버전의 경우 (systemd) +----------------------------- + +OpenSearch 시작:: + + $ sudo systemctl start opensearch.service + +Fess 시작:: + + $ sudo systemctl start fess.service + +시작 상태 확인:: + + $ sudo systemctl status fess.service + +서비스 자동 시작 활성화:: + + $ sudo systemctl enable opensearch.service + $ sudo systemctl enable fess.service + +Docker 버전의 경우 +------------------ + +.. note:: + + ``compose.yaml`` 및 ``compose-opensearch3.yaml`` 은 |Fess| 자체에 포함되어 있지 않습니다. + 이 파일들은 docker-fess 프로젝트(https://github.com/codelibs/docker-fess)에서 제공됩니다. + 해당 리포지터리를 취득하여 ``compose`` 디렉터리 안에서 다음 명령을 실행하십시오. + +Docker Compose를 사용하여 시작:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +시작 상태 확인:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps + +로그 확인:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01 + +시작 확인 +========== + +|Fess| 가 정상적으로 시작되었는지 확인합니다. + +헬스 체크 +------------ + +브라우저 또는 curl 명령으로 다음 URL에 액세스합니다:: + + http://localhost:8080/ + +정상적으로 시작된 경우 Fess의 검색 화면이 표시됩니다. + +명령줄에서 확인:: + + $ curl -I http://localhost:8080/ + +``HTTP/1.1 200 OK`` 가 반환되면 정상적으로 시작된 것입니다. + +로그 확인 +--------- + +시작 로그를 확인하여 오류가 없는지 확인합니다. + +ZIP 버전:: + + $ tail -f /path/to/fess-15.10.0/logs/fess.log + +RPM/DEB 버전:: + + $ sudo tail -f /var/log/fess/fess.log + +또는 journalctl 사용:: + + $ sudo journalctl -u fess.service -f + +Docker 버전:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01 + +.. tip:: + + 시작이 정상적으로 완료되면 다음과 같은 시작 완료 메시지가 로그 디렉터리(ZIP 버전은 ``logs/``, + RPM/DEB 버전은 ``/var/log/fess/``)의 ``server_0.log`` 에 출력됩니다. 콘솔에도 ``fess.log`` 에도 + 출력되지 않습니다:: + + ...Booting the Tomcat: port=8080 contextPath= + ... + Boot successful: url -> http://localhost:8080 + +브라우저에서 액세스 +==================== + +다음 URL에 액세스하여 웹 인터페이스를 확인합니다. + +검색 화면 +--------- + +**URL**: http://localhost:8080/ + +Fess의 검색 화면이 표시됩니다. 초기 상태에서는 크롤 설정이 수행되지 않았기 때문에 검색 결과가 표시되지 않습니다. + +검색 화면은 |Fess| 에 번들된 정적 테마 ``bootstrap`` 입니다. 외관을 변경하려면 +관리 화면의 "시스템" > "테마"에서 또는 ``bin/fess-setup install theme `` 으로 +다른 테마를 설치하거나( :doc:`fess-setup` 참조), 번들 테마를 복사하여 그 복사본을 +변경하십시오( :ref:`theme-customize-bundled` 참조). + +관리 화면 +--------- + +**URL**: http://localhost:8080/admin + +기본 관리자 계정: + +- **사용자 이름**: ``admin`` +- **비밀번호**: ``admin`` + +.. warning:: + + **보안 관련 중요 주의사항** + + 기본 비밀번호는 반드시 변경하십시오. + 특히 운영 환경에서는 최초 로그인 후 즉시 비밀번호를 변경할 것을 강력히 권장합니다. + +초기 설정 +============== + +관리 화면에 로그인한 후 다음 초기 설정을 수행합니다. + +단계 1: 관리자 비밀번호 변경 +------------------------------- + +1. 관리 화면에 로그인(http://localhost:8080/admin) +2. 왼쪽 메뉴에서 "사용자"→"사용자" 클릭 +3. ``admin`` 사용자 클릭 +4. 「비밀번호」 필드에 새 비밀번호를 입력합니다 +5. 「비밀번호(확인)」 필드에 같은 비밀번호를 다시 입력합니다 +6. 「갱신」 버튼을 클릭합니다 + +.. important:: + + 비밀번호는 다음 조건을 충족할 것을 권장합니다: + + - 8자 이상(``password.min.length`` 로 설정된 최소 길이) + - 영문 대문자, 영문 소문자, 숫자, 기호를 조합 + - 추측하기 어려운 것 + + 기본적으로 최소 길이(8자) 조건만 적용되며, 문자 종류의 조합은 강제되지 않습니다. + ``password.require.uppercase`` 등의 설정을 사용하여 문자 종류 조건을 활성화할 수 있습니다. + +단계 2: 크롤 설정 생성 +--------------------------- + +검색 대상 사이트나 파일 시스템을 크롤링하는 설정을 생성합니다. + +1. 왼쪽 메뉴에서 "크롤러"→"웹" 클릭 +2. "새로 만들기" 버튼 클릭 +3. 필요한 정보 입력: + + - **이름**: 크롤 설정 이름(예: 회사 웹사이트) + - **URL**: 크롤 대상 URL(예: https://www.example.com/). 여러 URL을 지정하려면 한 줄에 하나씩 입력하십시오 + - **최대 액세스 수**: 크롤할 문서 수의 상한(선택 사항) + - **간격**: 각 액세스 간의 대기 시간(밀리초. 기본값: ``10000``) + + .. note:: + + 위 항목 이외의 설정(사용자 에이전트, 스레드 수, 깊이 등)은 + 미입력 시 기본값이 사용됩니다. + +4. "생성" 버튼 클릭 + +단계 3: 크롤 실행 +----------------------- + +1. 왼쪽 메뉴에서 [시스템] → [스케줄러] 클릭 +2. [Default Crawler] 작업을 열고 "지금 시작" 버튼을 클릭합니다 +3. 크롤이 완료될 때까지 기다립니다(진행 상황은 대시보드에서 확인 가능) + +단계 4: 검색 확인 +------------------- + +1. 검색 화면(http://localhost:8080/)에 액세스 +2. 검색 키워드 입력 +3. 검색 결과가 표시되는지 확인 + +.. note:: + + 크롤에는 시간이 소요될 수 있습니다. + 대규모 사이트의 경우 수 시간에서 수일이 걸릴 수도 있습니다. + +기타 권장 설정 +============== + +운영 환경에서 운용하는 경우 다음 설정도 검토하십시오. + +환경 변수를 통한 주요 설정 +-------------------------- + +포트 번호, JVM 힙 크기, OpenSearch 연결 URL 등의 설정은 환경 변수를 통해 변경할 수 있습니다. +ZIP 버전은 ``bin/fess.in.sh``, RPM 버전은 ``/etc/sysconfig/fess``, DEB 버전은 ``/etc/default/fess`` 를 편집하십시오. +변경 후 |Fess| 를 재시작할 필요가 있습니다. + +.. list-table:: + :header-rows: 1 + :widths: 30 25 45 + + * - 환경 변수 + - 기본값 + - 설명 + * - ``FESS_PORT`` + - ``8080`` + - |Fess| 가 수신 대기하는 HTTP 포트입니다. + * - ``FESS_HEAP_SIZE`` + - (미설정) + - JVM 힙 크기입니다. 최솟값과 최댓값에 동일한 값을 설정합니다. 미설정 시 최솟값 ``256m``, 최댓값 ``2g`` 가 사용되며(Windows ZIP 버전은 최댓값 ``1g``), RPM/DEB 버전은 ``512m`` 이 사용됩니다. + * - ``SEARCH_ENGINE_HTTP_URL`` + - ``http://localhost:9200`` + - 접속할 OpenSearch의 URL입니다. ZIP 버전에서는 ``bin/fess.in.sh`` 가 기본적으로 이 값을 설정합니다. OpenSearch를 다른 포트나 호스트에서 실행하는 경우 환경 변수로 설정하거나 ``bin/fess.in.sh`` 를 편집하십시오. RPM/DEB 버전은 패키지 환경 설정 파일에서 설정합니다. + * - ``FESS_LOG_LEVEL`` + - ``warn`` + - |Fess| 의 로그 레벨입니다. + * - ``FESS_HEAP_NEWSIZE`` + - (미설정) + - JVM 힙의 Young 영역 크기(``-Xmn``)입니다. ``256m`` 과 같이 지정합니다. 미설정 시 JVM이 결정합니다. + * - ``FESS_TEMP_PATH`` + - |Fess| 디렉터리 안의 ``temp`` (RPM/DEB 버전은 ``/var/tmp/fess``) + - 임시 파일을 저장하는 디렉터리입니다(내장 Tomcat의 작업 디렉터리 포함). |Fess| 를 실행하는 사용자가 쓸 수 있어야 합니다. + * - ``FESS_CONF_PATH`` + - (미설정) (RPM/DEB 버전은 ``/etc/fess``) + - 설정 파일을 두는 디렉터리입니다. ``bin/fess`` 가 이 디렉터리를 클래스패스 맨 앞에 추가하고 ``-Dfess.conf.path`` 로 |Fess| 에 전달합니다. ``lib/classes`` 의 ``tomcat_config.properties`` 등은 이 디렉터리의 파일이 우선합니다. 다만 ZIP 버전의 웹 애플리케이션은 ``app/WEB-INF/classes`` 의 파일을 먼저 참조하므로, 이 디렉터리에 둔 ``fess_config.properties`` 로는 ``app/WEB-INF/classes`` 의 ``fess_config.properties`` 값을 덮어쓸 수 없습니다(크롤러 등 자식 프로세스는 이 디렉터리를 ``WEB-INF/classes`` 보다 먼저 참조합니다). ZIP 버전에서 ``fess_config.properties`` 를 변경할 때는 ``app/WEB-INF/classes`` 의 파일을 편집하십시오. RPM/DEB 버전은 ``app/WEB-INF/classes`` 에 ``fess_config.properties`` 를 포함하지 않고 ``/etc/fess`` 의 파일만 사용합니다. + * - ``FESS_USE_IPV4`` + - (미설정) + - 비어 있지 않은 값을 설정하면 JVM이 IPv4 스택만 사용합니다(``-Djava.net.preferIPv4Stack=true``). + * - ``FESS_USE_GC_LOGGING`` + - (미설정) + - 비어 있지 않은 값을 설정하면 JVM이 GC 로그를 로그 디렉터리의 ``gc-fess.log`` 에 기록합니다(64MB 파일 최대 5개). + +.. note:: + + Windows ZIP 버전의 ``bin\fess.in.bat`` 이 참조하는 환경 변수는 이 표의 항목 중 + ``FESS_HEAP_SIZE``, ``FESS_HEAP_NEWSIZE``, ``FESS_USE_IPV4``, ``FESS_USE_GC_LOGGING`` + 과 표에 없는 다음 환경 변수입니다. + + - ``FESS_MIN_MEM``, ``FESS_MAX_MEM``: 최소·최대 힙 크기를 개별적으로 지정합니다(``FESS_HEAP_SIZE`` 를 설정한 경우 무시됩니다). + - ``FESS_DIRECT_SIZE``: 다이렉트 메모리의 상한(``-XX:MaxDirectMemorySize``)입니다. + - ``FESS_DICTIONARY_PATH``: OpenSearch의 ``config\dictionary`` 디렉터리입니다. + - ``FESS_PROXY_HOST``, ``FESS_PROXY_PORT``, ``FESS_NON_PROXY_HOSTS``: 프록시 설정입니다. + - ``FESS_JAVA_OPTS``: 설정된 값 뒤에 ``fess.in.bat`` 이 JVM 옵션을 추가합니다. + - ``PLAYWRIGHT_NODEJS_PATH``: Playwright 플러그인이 사용하는 Node.js 실행 파일입니다. + - ``JAVA_HOME``: 필수입니다. + + ``FESS_PORT``, ``FESS_LOG_LEVEL``, ``FESS_TEMP_PATH``, ``FESS_CONF_PATH``, ``SEARCH_ENGINE_HTTP_URL`` + 은 참조되지 않습니다. 이 값들은 파일 안에 직접 기술되어 있으므로, 변경하려면 ``bin\fess.in.bat`` 을 직접 편집하십시오. + +메일 서버 설정 +------------------ + +장애 알림 등을 메일로 수신하려면 SMTP 서버와 알림 수신 주소를 설정합니다. + +1. ``fess_env_web.properties`` 와 ``fess_env_crawler.properties`` 의 ``mail.smtp.server.main.host.and.port`` (기본값: ``localhost:25``) 에 SMTP 서버 호스트와 포트를 지정합니다. 파일은 ZIP 패키지의 경우 ``app/WEB-INF/classes/`` 에, RPM/DEB 패키지의 경우 ``/etc/fess/`` 에 있습니다. 앞의 파일은 |Fess| 웹 프로세스가 읽고, 뒤의 파일은 크롤 완료 메일을 전송하는 크롤러가 읽습니다. ``fess_env.properties`` 는 사용되지 않습니다. 변경 후 |Fess| 를 재시작할 필요가 있습니다. +2. 관리 UI에서 왼쪽 메뉴의 [시스템] → [일반] 을 클릭합니다. +3. [알림 메일] 필드에 수신자 메일 주소를 입력합니다. +4. [갱신] 버튼을 클릭합니다. +5. [테스트 메일 보내기] 버튼으로 메일이 올바르게 발송되는지 확인할 수 있습니다. + +시간대 설정 +---------------- + +|Fess| 는 서버(OS / JVM)의 시간대를 사용합니다. 관리 UI에서 시간대를 변경하는 설정은 없습니다. +변경하려면 OS의 시간대 설정을 변경하거나, ``bin/fess.in.sh`` (Windows의 경우 ``bin\fess.in.bat``) 의 ``FESS_JAVA_OPTS`` 에 JVM 옵션 ``-Duser.timezone=Asia/Tokyo`` 를 추가하십시오. + +로그 레벨 조정 +-------------- + +운영 환경에서는 로그 레벨을 조정하여 디스크 사용량을 억제할 수 있습니다. + +|Fess| 전체의 로그 레벨은 ``FESS_LOG_LEVEL`` 환경 변수(기본값: ``warn``)로 변경할 수 있습니다. +개별 로거를 세밀하게 제어하려면 설정 파일 ``app/WEB-INF/classes/log4j2.xml`` 을 편집하십시오. +크롤링, 서제스트, 썸네일 생성은 별도 프로세스로 실행되므로, 각각의 로그 레벨을 ``app/WEB-INF/env/{crawler,suggest,thumbnail}/resources/log4j2.xml`` 에서 개별적으로 설정하십시오. + +자세한 내용은 :doc:`../admin/index` 를 참조하십시오. + +중지 방법 +========= + +ZIP 버전의 경우 +---------------------- + +Fess 중지 +~~~~~~~~~~ + +프로세스를 kill합니다:: + + $ ps aux | grep fess + $ kill + +또는 ``Ctrl+C`` 로 콘솔에서 중지할 수 있습니다(포어그라운드에서 실행 중인 경우). + +OpenSearch 중지:: + + $ ps aux | grep opensearch + $ kill + +RPM/DEB 버전의 경우 (chkconfig) +------------------------------- + +Fess 중지:: + + $ sudo service fess stop + +OpenSearch 중지:: + + $ sudo service opensearch stop + +RPM/DEB 버전의 경우 (systemd) +----------------------------- + +Fess 중지:: + + $ sudo systemctl stop fess.service + +OpenSearch 중지:: + + $ sudo systemctl stop opensearch.service + +Docker 버전의 경우 +------------------ + +컨테이너 중지:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop + +컨테이너 중지 및 삭제:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +.. warning:: + + ``down`` 명령으로 볼륨도 삭제하는 경우 ``-v`` 옵션을 추가합니다. + 이 경우 모든 데이터가 삭제되므로 주의하십시오. + +재시작 방법 +=========== + +ZIP 버전의 경우 +---------------------- + +중지한 후 시작합니다. + +RPM/DEB 버전의 경우 +------------------- + +chkconfig:: + + $ sudo service fess restart + +systemd:: + + $ sudo systemctl restart fess.service + +Docker 버전의 경우 +------------------ + +:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml restart + +문제 해결 +==================== + +시작되지 않는 경우 +------------------ + +1. **OpenSearch가 시작되어 있는지 확인** + + :: + + $ curl http://localhost:9200/ + + OpenSearch가 시작되어 있지 않은 경우 먼저 OpenSearch를 시작하십시오. + +2. **포트 번호 충돌 확인** + + :: + + $ sudo ss -tuln | grep 8080 + + net-tools 가 설치되어 있는 환경에서는 ``sudo netstat -tuln | grep 8080`` 으로도 같은 내용을 확인할 수 있습니다. + + 포트 8080이 이미 사용되고 있는 경우 포트 번호를 변경하십시오. + + - ZIP 버전: ``bin/fess.in.sh`` 의 ``FESS_PORT`` 를 변경합니다 + - ZIP 버전(Windows): ``bin\fess.in.bat`` 에서 ``-Dfess.port=8080`` 을 직접 편집합니다 + - RPM 버전: ``/etc/sysconfig/fess`` 의 ``FESS_PORT`` 를 변경합니다 + - DEB 버전: ``/etc/default/fess`` 의 ``FESS_PORT`` 를 변경합니다 + +3. **로그 확인** + + 오류 메시지를 확인하여 문제를 특정합니다. + +4. **Java 버전 확인** + + :: + + $ java -version + + Java 21 이상이 설치되어 있는지 확인하십시오. + +자세한 문제 해결에 대해서는 :doc:`troubleshooting` 을 참조하십시오. + +다음 단계 +========== + +|Fess| 가 정상적으로 시작되면 다음 문서를 참조하여 운용을 시작하십시오: + +- :doc:`../admin/index` - 크롤 설정, 검색 설정, 시스템 설정의 상세 +- :doc:`security` - 운영 환경의 보안 설정 +- :doc:`troubleshooting` - 일반적인 문제 및 해결 방법 +- :doc:`upgrade` - 버전 업그레이드 절차 +- :doc:`uninstall` - 제거 절차 diff --git a/ko/15.10/install/security.rst b/ko/15.10/install/security.rst new file mode 100644 index 000000000..75136ee8b --- /dev/null +++ b/ko/15.10/install/security.rst @@ -0,0 +1,355 @@ +================== +보안 설정 +================== + +이 페이지에서는 운영 환경에서 |Fess| 를 안전하게 운용하기 위해 권장되는 보안 설정에 대해 설명합니다. + +.. danger:: + + **보안은 매우 중요합니다** + + 운영 환경에서는 이 페이지에 기재된 모든 보안 설정을 실시할 것을 강력히 권장합니다. + 보안 설정을 소홀히 하면 무단 액세스, 데이터 유출, 시스템 침해 등의 위험이 높아집니다. + +필수 보안 설정 +==================== + +관리자 비밀번호 변경 +-------------------- + +기본 관리자 비밀번호(``admin`` / ``admin``)는 반드시 변경하십시오. + +**절차:** + +1. 관리 화면에 로그인: http://localhost:8080/admin +2. "사용자"→"사용자" 클릭 +3. ``admin`` 사용자 선택 +4. 강력한 비밀번호 설정 +5. "업데이트" 버튼 클릭 + +.. note:: + + 한 번 ``admin`` 에서 변경한 비밀번호는 ``admin`` 과 같은 단순한 문자열로는 다시 설정할 수 없습니다(``password.invalid.admin.passwords`` 에 의해 관리자 비밀번호의 블랙리스트가 설정되어 있습니다). 또한 최초 시작 전이라면 ``fess_config.properties`` 의 ``index.user.initial_password`` 로 ``admin`` 사용자의 초기 비밀번호를 변경할 수 있습니다. + +**권장 비밀번호 정책:** + +|Fess| 는 비밀번호의 최소·최대 문자 수와 문자 종류 요건을 강제하는 기능을 제공합니다. ``fess_config.properties`` 에서 다음 속성을 설정하십시오(괄호 안은 기본값입니다). + +- ``password.min.length`` (기본값: ``8``): 최소 문자 수. 12자 이상을 권장합니다. +- ``password.max.length`` (기본값: ``100``): 최대 문자 수. +- ``password.require.uppercase`` (기본값: ``false``): 영문 대문자를 필수로 설정합니다. +- ``password.require.lowercase`` (기본값: ``false``): 영문 소문자를 필수로 설정합니다. +- ``password.require.digit`` (기본값: ``false``): 숫자를 필수로 설정합니다. +- ``password.require.special.char`` (기본값: ``false``): 기호를 필수로 설정합니다. + +.. note:: + + 기본값에서는 최소 문자 수가 ``8`` 이며 문자 종류 요건은 모두 비활성화되어 있습니다. 비밀번호 강도를 높이려면 위의 속성을 명시적으로 설정하십시오. 또한 |Fess| 에는 비밀번호 유효기간(정기 변경 강제) 기능이 없습니다. 정기적인 비밀번호 변경을 운영 규칙으로 정하고자 하는 경우에는 수동으로 대응하십시오. + +OpenSearch 보안 플러그인 활성화 +-------------------------------------- + +**절차:** + +1. ``opensearch.yml`` 에서 다음 행을 삭제하거나 주석 처리:: + + # plugins.security.disabled: true + +2. 보안 플러그인 설정:: + + plugins.security.allow_default_init_securityindex: true + plugins.security.authcz.admin_dn: + - CN=admin,OU=SSL,O=Test,L=Test,C=DE + +3. TLS/SSL 인증서 설정 + +4. OpenSearch 재시작 + +5. |Fess| 측에서 OpenSearch로의 연결 정보를 설정합니다. + + 연결 URL은 환경 변수 ``SEARCH_ENGINE_HTTP_URL`` 로 지정합니다(``bin/fess.in.sh`` 또는 서비스의 환경 설정 파일을 편집합니다. 기본값은 ``fess_config.properties`` 의 ``search_engine.http.url`` 입니다):: + + SEARCH_ENGINE_HTTP_URL=https://opensearch:9200 + + 인증 정보는 ``fess_config.properties`` 의 다음 속성으로 지정합니다(``SEARCH_ENGINE_USERNAME`` / ``SEARCH_ENGINE_PASSWORD`` 라는 환경 변수는 존재하지 않습니다):: + + search_engine.username=admin + search_engine.password= + +자세한 내용은 `OpenSearch Security Plugin `__ 을 참조하십시오. + +HTTPS 활성화 +------------ + +HTTP 통신은 암호화되지 않아 도청 및 변조 위험이 있습니다. 운영 환경에서는 반드시 HTTPS를 사용하십시오. + +**방법 1: 리버스 프록시 사용(권장)** + +Nginx 또는 Apache를 |Fess| 앞단에 배치하여 HTTPS 종단을 수행합니다. + +Nginx 설정 예:: + + server { + listen 443 ssl http2; + server_name your-fess-domain.com; + + ssl_certificate /path/to/cert.pem; + ssl_certificate_key /path/to/key.pem; + + ssl_protocols TLSv1.2 TLSv1.3; + ssl_ciphers HIGH:!aNULL:!MD5; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + } + +**방법 2: Fess 자체에서 HTTPS 설정** + +``tomcat_config.properties`` 에 다음을 추가:: + + tomcat.secure=true + tomcat.scheme=https + tomcat.SSLEnabled=true + tomcat.certificateKeystoreFile=[키스토어 파일 경로] + tomcat.certificateKeystorePassword=[키스토어 파일 생성 시 지정한 비밀번호] + tomcat.certificateKeyAlias=[인증서 별칭] + tomcat.sslProtocol=[SSL 프로토콜 (예: TLS)] + tomcat.enabledProtocols=활성화된 프로토콜 목록 (쉼표 구분) (예: TLSv1.2,TLSv1.1,TLSv1) + +권장 보안 설정 +==================== + +방화벽 설정 +------------------ + +필요한 포트만 개방하고 불필요한 포트는 닫으십시오. + +**개방해야 할 포트:** + +- **8080** (또는 HTTPS의 443): |Fess| 웹 인터페이스(외부에서 액세스가 필요한 경우) +- **22**: SSH(관리용, 신뢰할 수 있는 IP 주소에서만) + +**닫아야 할 포트:** + +- **9200, 9300**: OpenSearch(내부 통신만, 외부 액세스 차단) + +Linux (firewalld) 설정 예:: + + $ sudo firewall-cmd --permanent --add-service=http + $ sudo firewall-cmd --permanent --add-service=https + $ sudo firewall-cmd --permanent --remove-service=opensearch # 사용자 정의 서비스의 경우 + $ sudo firewall-cmd --reload + +IP 주소 제한:: + + $ sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="192.168.1.0/24" port port="8080" protocol="tcp" accept' + +액세스 제어 설정 +---------------- + +관리 화면에 대한 액세스를 특정 IP 주소로 제한하는 것을 고려하십시오. + +Nginx에서 액세스 제한 예:: + + location /admin { + allow 192.168.1.0/24; + deny all; + + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + } + +역할과 액세스 제어 +-------------------- + +|Fess| 에는 미리 2개의 역할이 준비되어 있습니다. + +- ``admin``: 관리 화면을 포함한 모든 작업이 가능한 관리자 역할 +- ``guest``: 로그인하지 않은(익명) 사용자에게 할당되는 역할 + +이 외의 역할은 관리 화면에서 자유롭게 생성할 수 있습니다. |Fess| 의 역할은 이름만을 가진 태그이며, 주로 검색 결과에 대한 액세스 제어(어떤 문서를 표시할 수 있는지)에 사용됩니다. 다만 ``admin-user`` 나 ``admin-scheduler`` 처럼 ``admin-`` 뒤에 관리 화면 이름을 붙인 이름의 역할은 해당 관리 화면을 열기 위한 권한이 됩니다(``admin-user-view`` 처럼 ``-view`` 를 붙인 역할은 참조 전용입니다). + +.. warning:: + + ``admin-*`` 역할은 일상적인 관리 화면을 운영 담당자에게 나누어 맡기기 위한 것이며, 권한의 경계가 아닙니다. 예를 들어 ``admin-user`` 를 가진 사용자는 관리자 역할을 포함한 기존의 모든 역할을 임의의 사용자에게 부여할 수 있습니다. ``admin-accesstoken`` 으로는 Admin API의 모든 기능을 사용할 수 있는 ``Radmin-api`` 권한의 액세스 토큰을 발급할 수 있고, ``admin-scheduler`` 로는 서버에서 스크립트 작업을 실행할 수 있으며, ``admin-plugin`` 으로는 플러그인을 설치할 수 있습니다. 모든 ``admin-*`` 역할을 관리자 역할(``authentication.admin.roles``, 기본값은 ``admin``)과 동등하게 취급하고, 신뢰할 수 있는 운영 담당자에게만 부여하십시오. + +최소 권한 원칙에 따라 관리자 역할(``admin``)은 관리 업무를 수행하는 사용자에게만 부여하고, 일반 검색 사용자에게는 부여하지 마십시오. + +**절차:** + +1. 관리 화면에서 "사용자"→"역할" 클릭 +2. 필요한 역할 생성 +3. "사용자"→"사용자"에서 사용자에게 역할 할당 + +감사 로그 +------------ + +인증이나 관리 작업 등 시스템의 작업 이력은 기본적으로 감사 로그로 기록됩니다. 감사 로그는 ``log4j2.xml`` 에 정의된 ``fess.log.audit`` 로거에 의해 출력되며, 기본 출력 대상은 ``audit.log`` 입니다. + +기본적으로 활성화되어 있으므로 추가 설정은 필요하지 않습니다. 출력 대상이나 로그 레벨을 커스터마이즈하려면 ``log4j2.xml`` 의 다음 정의를 편집하십시오:: + + + + + +정기적인 보안 업데이트 +------------------------------ + +|Fess| 및 OpenSearch의 보안 업데이트를 정기적으로 적용하십시오. + +**권장 절차:** + +1. 보안 정보를 정기적으로 확인 + + - `Fess 릴리스 정보 `__ + - `OpenSearch 보안 권고 `__ + +2. 테스트 환경에서 업데이트 검증 +3. 운영 환경에 업데이트 적용 + +데이터 보호 +=========== + +백업 암호화 +------------------ + +백업 데이터에는 기밀 정보가 포함될 수 있습니다. 백업 파일을 암호화하여 저장하십시오. + +암호화 백업 예:: + + $ tar czf fess-backup.tar.gz /var/lib/opensearch /etc/fess + $ gpg --symmetric --cipher-algo AES256 fess-backup.tar.gz + +보안 모범 사례 +============================ + +최소 권한 원칙 +-------------- + +- Fess 및 OpenSearch를 root 사용자로 실행하지 않음 +- 전용 사용자 계정으로 실행 +- 필요 최소한의 파일 시스템 권한 부여 + +네트워크 분리 +-------------- + +- OpenSearch를 프라이빗 네트워크에 배치 +- 내부 통신에는 VPN 또는 프라이빗 네트워크 사용 +- DMZ에 |Fess| 의 웹 인터페이스만 배치 + +정기적인 보안 감사 +---------------------- + +- 액세스 로그를 정기적으로 확인 +- 비정상적인 액세스 패턴 검출 +- 정기적으로 취약점 스캔 실시 + +보안 헤더 설정 +------------------------ + +필요에 따라 Nginx 또는 Apache에서 보안 헤더를 설정하십시오:: + + add_header X-Frame-Options "SAMEORIGIN" always; + add_header X-Content-Type-Options "nosniff" always; + add_header X-XSS-Protection "1; mode=block" always; + add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; + add_header Content-Security-Policy "default-src 'self'" always; + +보안 체크리스트 +======================== + +운영 환경에 배포하기 전에 다음 체크리스트를 확인하십시오: + +기본 설정 +--------- + +- [ ] 관리자 비밀번호 변경 완료 +- [ ] HTTPS 활성화 완료 +- [ ] 기본 포트 번호 변경(옵션) + +네트워크 보안 +---------------------- + +- [ ] 방화벽으로 불필요한 포트 폐쇄 완료 +- [ ] 관리 화면에 대한 액세스 IP 제한 완료(가능한 경우) +- [ ] OpenSearch에 대한 액세스를 내부 네트워크로만 제한 완료 + +액세스 제어 +----------- + +- [ ] 역할과 액세스 권한을 적절히 설정 완료(관리자 역할을 필요한 사용자에게만 부여) +- [ ] 불필요한 사용자 계정 삭제 완료 +- [ ] 비밀번호 정책 설정 완료 + +모니터링 및 로그 +---------------- + +- [ ] 감사 로그가 활성화되어 있음을 확인 완료 +- [ ] 로그 보존 기간 설정 완료 +- [ ] 로그 모니터링 체계 구축 완료(가능한 경우) + +백업 및 복구 +-------------------- + +- [ ] 정기적인 백업 일정 설정 완료 +- [ ] 백업 데이터 암호화 완료 +- [ ] 복원 절차 검증 완료 + +업데이트 및 패치 관리 +---------------------- + +- [ ] 보안 업데이트 알림 수신 체계 구축 완료 +- [ ] 업데이트 절차 문서화 완료 +- [ ] 테스트 환경에서 업데이트 검증 체제 구축 완료 + +보안 사고 대응 +========================== + +보안 사고가 발생한 경우의 대응 절차: + +1. **사고 감지** + + - 로그 확인 + - 비정상적인 액세스 패턴 검출 + - 시스템 동작 이상 확인 + +2. **초기 대응** + + - 영향 범위 특정 + - 피해 확산 방지(해당 서비스 중지 등) + - 증거 보전 + +3. **조사 및 분석** + + - 로그 상세 분석 + - 침입 경로 특정 + - 유출되었을 가능성이 있는 데이터 특정 + +4. **복구** + + - 취약점 수정 + - 시스템 복구 + - 모니터링 강화 + +5. **사후 대응** + + - 사고 보고서 작성 + - 재발 방지 대책 실시 + - 관계자에게 보고 + +참고 정보 +========= + +- `OpenSearch Security Plugin `__ +- `OWASP Top 10 `__ +- `CIS Benchmarks `__ + +보안에 관한 질문이나 문제가 있는 경우 다음으로 문의하십시오: + +- Issues: https://github.com/codelibs/fess/issues +- 상용 지원: https://www.n2sm.net/ diff --git a/ko/15.10/install/troubleshooting.rst b/ko/15.10/install/troubleshooting.rst new file mode 100644 index 000000000..bf5eef774 --- /dev/null +++ b/ko/15.10/install/troubleshooting.rst @@ -0,0 +1,593 @@ +================== +문제 해결 +================== + +이 페이지에서는 |Fess| 의 설치, 시작, 운용 시 자주 발생하는 문제와 해결 방법에 대해 설명합니다. + +설치 시 문제 +================== + +Java가 인식되지 않음 +----------------- + +**증상:** + +:: + + -bash: java: command not found + +또는:: + + 'java' is not recognized as an internal or external command + +**원인:** + +Java가 설치되어 있지 않거나 PATH 환경 변수가 올바르게 설정되어 있지 않음. + +**해결 방법:** + +1. Java가 설치되어 있는지 확인:: + + $ which java + $ java -version + +2. 설치되어 있지 않은 경우 Java 21 설치:: + + # Ubuntu/Debian + $ sudo apt-get update + $ sudo apt-get install openjdk-21-jdk + + # RHEL/CentOS + $ sudo yum install java-21-openjdk + + Debian 12 의 표준 리포지토리에는 ``openjdk-21-jdk`` 패키지가 없습니다. Debian 12 에서는 대신 `Adoptium의 Linux 설치 안내 `__ 의 Debian 용 절차에 따라 Eclipse Temurin 21 을 설치하십시오. + +3. JAVA_HOME 환경 변수 설정:: + + $ export JAVA_HOME=/path/to/java + $ export PATH=$JAVA_HOME/bin:$PATH + + 영구적으로 설정하는 경우 ``~/.bashrc`` 또는 ``/etc/profile`` 에 추가합니다. + +플러그인 설치 실패 +------------------------------- + +**증상:** + +:: + + ERROR: Plugin installation failed + +**원인:** + +- 네트워크 연결 문제 +- 플러그인 버전이 OpenSearch 버전과 일치하지 않음 +- 권한 문제 + +**해결 방법:** + +1. OpenSearch 버전 확인:: + + $ /path/to/opensearch/bin/opensearch --version + +2. 플러그인 버전을 OpenSearch 버전에 맞춤:: + + $ /path/to/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + +3. 권한 확인:: + + $ sudo /path/to/opensearch/bin/opensearch-plugin install ... + +4. 프록시를 통해 설치하는 경우:: + + $ export ES_JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080" + $ /path/to/opensearch/bin/opensearch-plugin install ... + +시작 시 문제 +========== + +Fess가 시작되지 않음 +--------------- + +**증상:** + +Fess 시작 명령을 실행해도 오류가 발생하거나 즉시 종료됨. + +**확인 항목:** + +1. **OpenSearch가 시작되어 있는지 확인**:: + + $ curl http://localhost:9200/ + + 정상인 경우 JSON 응답이 반환됩니다. + + OpenSearch 가 응답하지 않으면 |Fess| 는 1분 정도 재시도한 후 시작을 중단하고, 콘솔과 ``logs/fess.log`` 에 다음 메시지를 출력합니다:: + + The search engine at http://localhost:9200 did not become available within 60221ms. Check that OpenSearch is running and reachable. If there is none yet, run bin/fess-setup install opensearch to set one up. + + OpenSearch 를 시작하거나 ``SEARCH_ENGINE_HTTP_URL`` 을 확인하십시오. 새로 설치한 ZIP 버전에는 ``bin/fess-setup install opensearch`` 로 설치하기 전까지 OpenSearch 가 없습니다. :doc:`install-linux` 를 참조하십시오. + +2. **포트 번호 충돌 확인**:: + + $ sudo ss -tuln | grep 8080 + + 포트 8080이 이미 사용되고 있는 경우 설정 파일에서 포트 번호를 변경하십시오. + +3. **로그 파일 확인**:: + + $ tail -f /path/to/fess/logs/fess.log + + 오류 메시지에서 원인을 특정합니다. + +4. **Java 버전 확인**:: + + $ java -version + + Java 21 이상이 설치되어 있는지 확인하십시오. + +5. **메모리 부족 확인**:: + + $ free -h + + 메모리가 부족한 경우 힙 크기를 조정하거나 시스템 메모리를 증설하십시오. + +OpenSearch가 시작되지 않음 +--------------------- + +**증상:** + +:: + + ERROR: bootstrap checks failed + +**원인:** + +시스템 설정이 OpenSearch 요구사항을 충족하지 못함. + +**해결 방법:** + +1. **vm.max_map_count 설정**:: + + $ sudo sysctl -w vm.max_map_count=262144 + + 영구적으로 설정:: + + $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf + $ sudo sysctl -p + +2. **파일 디스크립터 상한 증가**:: + + $ sudo vi /etc/security/limits.conf + + 다음을 추가:: + + opensearch - nofile 65535 + opensearch - nproc 4096 + +3. **메모리 잠금 설정**:: + + $ sudo vi /etc/security/limits.conf + + 다음을 추가:: + + opensearch - memlock unlimited + +4. OpenSearch 재시작:: + + $ sudo systemctl restart opensearch + +인덱스를 생성할 수 없음(사전 파일 경로) +--------------------------------------- + +**증상:** + +|Fess| 에 액세스하면 HTTP 404 가 반환되고 ``fess.log`` 에 다음 오류가 출력됩니다:: + + Failed to create index: index=fess, path=fess_indices/fess.json + ... reason=Resource path must be inside config directory: /var/lib/opensearch/data/config/ja/mapping.txt + +**원인:** + +OpenSearch 3.8.0 이상에서는 사전 파일이 OpenSearch 설정 디렉터리 밖에 있으면 인덱스 생성을 거부합니다. +``configsync.config_path`` 와 ``FESS_DICTIONARY_PATH`` 가 설정 디렉터리 밖(``data/config/`` 등)을 가리키고 있습니다. + +**해결 방법:** + +1. ``configsync.config_path`` 와 ``FESS_DICTIONARY_PATH`` 를 OpenSearch 설정 디렉터리 아래의 디렉터리로 변경합니다. + + - RPM/DEB 버전: ``/etc/opensearch/dictionary/`` + - ZIP 버전: ``/path/to/opensearch-3.9.0/config/dictionary/`` + +2. 기존 사전 파일이 있는 경우 새 디렉터리로 복사합니다. +3. OpenSearch, |Fess| 순서로 재시작합니다. + +자세한 내용은 :doc:`install-linux` 를 참조하십시오. + +포트 번호 충돌 +-------------- + +**증상:** + +:: + + Address already in use + +**해결 방법:** + +1. 사용 중인 포트 확인:: + + $ sudo ss -tuln | grep 8080 + $ sudo lsof -i :8080 + +2. 사용 중인 프로세스 중지, 또는 Fess의 포트 번호 변경 + + 포트 번호 변경은 :doc:포트 및 네트워크 설정 <../config/setup-port-network> 을 참조하세요. + +연결 문제 +======== + +Fess가 OpenSearch에 연결할 수 없음 +------------------------------- + +**증상:** + +로그에 다음과 같은 오류 표시:: + + Connection refused + 또는 + No route to host + +**해결 방법:** + +1. **OpenSearch가 시작되어 있는지 확인**:: + + $ curl http://localhost:9200/ + +2. **연결 URL 확인** + + ``fess.in.sh`` 또는 ``fess.in.bat`` 에서 설정된 URL이 올바른지 확인:: + + SEARCH_ENGINE_HTTP_URL=http://localhost:9200 + +3. **방화벽 확인**:: + + $ sudo firewall-cmd --list-all + + 포트 9200이 개방되어 있는지 확인합니다. + +4. **네트워크 연결 확인** + + 다른 호스트에서 OpenSearch를 실행하는 경우:: + + $ ping opensearch-host + $ telnet opensearch-host 9200 + +브라우저에서 Fess에 액세스할 수 없음 +---------------------------------- + +**증상:** + +브라우저에서 http://localhost:8080/ 에 액세스할 수 없음. + +**해결 방법:** + +1. **Fess가 시작되어 있는지 확인**:: + + $ ps aux | grep fess + +2. **로컬호스트에서 액세스 시도**:: + + $ curl http://localhost:8080/ + +3. **방화벽 확인**:: + + $ sudo firewall-cmd --list-all + + 포트 8080이 개방되어 있는지 확인합니다. + +4. **다른 호스트에서 액세스하는 경우** + + Fess가 로컬호스트 이외에서 수신 대기하고 있는지 확인:: + + $ ss -tuln | grep 8080 + + ``127.0.0.1:8080`` 인 경우 ``0.0.0.0:8080`` 또는 특정 IP 주소에서 수신 대기하도록 설정을 변경합니다. + +성능 문제 +================== + +검색이 느림 +-------- + +**원인:** + +- 인덱스 크기가 큼 +- 메모리 부족 +- 디스크 I/O가 느림 +- 쿼리가 복잡함 + +**해결 방법:** + +1. **힙 크기 증가** + + ``FESS_HEAP_SIZE`` 를 환경 변수로 전달하여 |Fess| 를 시작합니다:: + + $ FESS_HEAP_SIZE=4g bin/fess + + ``bin/fess.in.sh`` 에서 설정하는 경우에는 힙 크기를 결정하는 줄(``FESS_MIN_MEM`` 의 기본값을 설정하는 줄)\ **보다 앞**\ 에 ``FESS_HEAP_SIZE=4g`` 를 작성합니다. 파일 끝에 추가해도 그 시점에는 이미 힙 크기가 결정되어 있으므로 반영되지 않습니다. RPM/DEB 버전은 ``/etc/sysconfig/fess``\ (DEB 버전은 ``/etc/default/fess``)에 설정합니다. + + OpenSearch의 힙 크기도 조정:: + + export OPENSEARCH_JAVA_OPTS="-Xms4g -Xmx4g" + +2. **SSD 사용** + + 디스크 I/O가 병목인 경우 SSD로 이전합니다. + +3. **캐시 활성화** + + 설정 파일에서 쿼리 캐시를 활성화합니다. + +크롤링이 느림 +----------- + +**원인:** + +- 크롤 간격이 김 +- 대상 사이트 응답이 느림 +- 스레드 수가 적음 + +**해결 방법:** + +1. **크롤 간격 조정** + + 관리 화면에서 크롤 설정의 "간격"을 짧게 합니다(밀리초 단위). + + .. warning:: + + 간격을 너무 짧게 하면 대상 사이트에 부하가 걸립니다. 적절한 값을 설정하십시오. + +2. **스레드 수 증가** + + 관리 화면에서 크롤링 설정의 "스레드 수"를 늘립니다. 기본값은 웹 크롤이 1, 파일 시스템 크롤이 5입니다. + +3. **타임아웃 값 조정** + + 응답이 느린 사이트의 경우 타임아웃 값을 늘립니다. + +데이터 문제 +========== + +검색 결과가 표시되지 않음 +-------------------- + +**원인:** + +- 인덱스가 작성되지 않음 +- 크롤링이 실패함 +- 검색 쿼리가 잘못됨 + +**해결 방법:** + +1. **인덱스 확인**:: + + $ curl http://localhost:9200/_cat/indices?v + + |Fess| 의 인덱스가 존재하는지 확인합니다. + +2. **크롤 로그 확인** + + 관리 화면의 "시스템 정보"→"로그 파일"에서 크롤 로그(``fess-crawler.log``)를 다운로드하여 오류가 없는지 조사합니다. + +3. **크롤 재실행** + + 관리 화면에서 "시스템"→"스케줄러"에서 "Default Crawler"를 실행합니다. + +4. **검색 쿼리를 간단하게** + + 먼저 간단한 키워드로 검색하여 결과가 반환되는지 확인합니다. + +인덱스가 손상됨 +------------------------ + +**증상:** + +검색 시 오류 발생 또는 예기치 않은 결과 반환. + +**해결 방법:** + +1. **인덱스 삭제 후 재작성** + + .. warning:: + + 인덱스를 삭제하면 모든 검색 데이터가 손실됩니다. 반드시 백업을 취득하십시오. + + :: + + $ curl -X DELETE http://localhost:9200/fess* + +2. **Fess 재시작** + + 인덱스는 |Fess| 시작 시에 생성됩니다. 삭제한 직후에는 사용자 정보 인덱스도 함께 사라졌으므로 관리 화면에 로그인할 수 없습니다(``/api/v2/health`` 는 ``200`` 을 계속 반환합니다). |Fess| 를 재시작하면 인덱스와 기본 작업, 초기 사용자(``admin``)가 다시 생성됩니다. + +3. **크롤 재실행** + + 관리 화면에서 "Default Crawler"를 실행하여 검색 대상 문서를 다시 등록합니다. + +Docker 고유 문제 +=============== + +컨테이너가 시작되지 않음 +------------------ + +**증상:** + +``docker compose up`` 으로 컨테이너가 시작되지 않음. + +**해결 방법:** + +1. **로그 확인**:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs + +2. **메모리 부족 확인** + + Docker에 할당된 메모리를 늘립니다(Docker Desktop 설정에서). + +3. **포트 충돌 확인**:: + + $ docker ps + + 다른 컨테이너가 포트 8080 또는 9200을 사용하고 있지 않은지 확인합니다. + +4. **Docker Compose 파일 확인** + + YAML 파일의 구문 오류가 없는지 확인합니다:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml config + +컨테이너는 시작되지만 Fess에 액세스할 수 없음 +---------------------------------------- + +**해결 방법:** + +1. **컨테이너 상태 확인**:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps + +2. **로그 확인**:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs fess + +3. **네트워크 설정 확인**:: + + $ docker network ls + $ docker network inspect + +Windows 고유 문제 +================ + +경로 문제 +-------- + +**증상:** + +경로에 공백이나 한국어가 포함된 경우 오류 발생. + +**해결 방법:** + +경로에 공백이나 한국어를 포함하지 않은 디렉터리에 설치하십시오. + +예:: + + C:\opensearch (권장) + C:\Program Files\opensearch (비권장) + +서비스로 등록할 수 없음 +------------------------ + +**해결 방법:** + +NSSM 등의 타사 도구를 사용하여 Windows 서비스로 등록합니다. + +자세한 내용은 :doc:`install-windows` 를 참조하십시오. + +기타 문제 +========== + +로그 레벨 변경 +-------------- + +상세한 로그를 확인하는 경우 로그 레벨을 DEBUG로 변경합니다. + +``log4j2.xml`` 편집:: + + + +데이터베이스 재설정 +-------------------- + +설정을 재설정하는 경우 OpenSearch의 인덱스를 삭제합니다:: + + $ curl -X DELETE 'http://localhost:9200/fess_config.*' + +.. warning:: + + 이 명령을 실행하면 모든 설정 데이터가 삭제됩니다. + +관리자 비밀번호를 잊은 경우 +--------------------------- + +관리자 비밀번호를 잊은 경우에는 OpenSearch 의 ``fess_user.user`` 인덱스에 있는 사용자 문서를 직접 갱신하여 비밀번호를 다시 설정할 수 있습니다. 비밀번호는 ``password`` 필드에 ``{bcrypt}$2a$...`` 형식의 해시로 저장되어 있습니다. 갱신은 |Fess| 를 재시작하지 않아도 유효합니다. + +1. 새 비밀번호의 해시를 만듭니다. |Fess| 가 받아들이는 것은 ``$2a$`` 로 시작하는 bcrypt 해시뿐이므로, ``htpasswd`` (``apache2-utils`` 또는 ``httpd-tools`` 패키지에 포함)가 출력하는 ``$2y$`` 를 ``$2a$`` 로 바꿉니다. ``NewPassword`` 는 새 비밀번호로 바꾸십시오:: + + $ HASH=$(htpasswd -bnBC 10 "" 'NewPassword' | tr -d ':\n' | sed 's/^\$2y/$2a/') + +2. admin 사용자 문서의 비밀번호를 갱신합니다. 초기 상태의 admin 사용자의 문서 ID는 ``YWRtaW4=`` 입니다:: + + $ curl -X POST 'http://localhost:9200/fess_user.user/_update/YWRtaW4=?refresh=true' \ + -H 'Content-Type: application/json' \ + -d "{\"doc\":{\"password\":\"{bcrypt}${HASH}\"}}" + + 다른 사용자의 비밀번호를 다시 설정하는 경우에는 ``curl 'http://localhost:9200/fess_user.user/_search?q=name:사용자명'`` 로 ``_id`` 를 조회하여 그 ID를 지정합니다. OpenSearch 에 인증을 설정한 경우에는 curl 에 인증 정보를 지정하십시오. + +3. 새 비밀번호로 관리 화면에 로그인할 수 있는지 확인합니다. 명령 이력에 비밀번호가 남는 경우에는 로그인 후 [사용자 > 사용자] 에서 비밀번호를 다시 설정하십시오. + +지원 정보 +========== + +문제가 해결되지 않는 경우 다음 지원 리소스를 이용하십시오: + +커뮤니티 지원 +------------------ + +- **Issues**: https://github.com/codelibs/fess/issues + + 문제를 보고할 때는 다음 정보를 포함하십시오: + + - Fess 버전 + - OpenSearch 버전 + - OS 및 버전 + - 오류 메시지(로그에서 발췌) + - 재현 절차 + +- **포럼**: https://discuss.codelibs.org/ + +상용 지원 +---------- + +상용 지원이 필요한 경우 N2SM, Inc.에 문의하십시오: + +- **Web**: https://www.n2sm.net/ + +디버그 정보 수집 +================ + +문제를 보고할 때 다음 정보를 수집해 두면 도움이 됩니다: + +1. **버전 정보** (``bin/fess -v`` 는 15.10 이상에서 사용할 수 있습니다):: + + $ /path/to/fess/bin/fess -v + $ /path/to/opensearch/bin/opensearch --version + $ java -version + +2. **시스템 정보**:: + + $ uname -a + $ cat /etc/os-release + $ free -h + $ df -h + +3. **로그 파일**:: + + $ tar czf fess-logs.tar.gz /path/to/fess/logs/ + +4. **설정 파일**\ (기밀 정보를 삭제한 후):: + + $ tar czf fess-config.tar.gz /path/to/fess/app/WEB-INF/conf/ + +5. **OpenSearch 상태**:: + + $ curl http://localhost:9200/_cluster/health?pretty + $ curl http://localhost:9200/_cat/indices?v diff --git a/ko/15.10/install/uninstall.rst b/ko/15.10/install/uninstall.rst new file mode 100644 index 000000000..1315f0992 --- /dev/null +++ b/ko/15.10/install/uninstall.rst @@ -0,0 +1,481 @@ +================== +제거 절차 +================== + +이 페이지에서는 |Fess| 를 완전히 제거하는 절차에 대해 설명합니다. + +.. warning:: + + **제거 전 중요한 주의사항** + + - 제거하면 모든 데이터가 삭제됩니다 + - 중요한 데이터가 있는 경우 반드시 백업을 취득하십시오 + - 백업 절차에 대해서는 :doc:`upgrade` 를 참조하십시오 + +제거 전 준비 +====================== + +백업 취득 +---------------- + +필요한 데이터를 백업하십시오: + +1. **설정 데이터** + + 관리 화면의 "시스템" → "백업" 에서 다운로드합니다. + 이 작업으로 각종 설정(크롤 설정 포함)이나 검색 로그 등을 한꺼번에 내보낼 수 있습니다. + +2. **커스터마이징한 설정 파일** + + ZIP 버전:: + + $ cp -r /path/to/fess/app/WEB-INF/conf /backup/ + $ cp -r /path/to/fess/app/WEB-INF/classes /backup/ + + RPM/DEB 버전:: + + $ sudo cp -r /etc/fess /backup/ + +.. note:: + + |Fess| 의 인덱스나 설정의 대부분은 OpenSearch 에 저장됩니다. + 인덱스 데이터를 백업하는 경우 OpenSearch 의 스냅샷 기능을 사용합니다. + 자세한 절차는 :doc:`upgrade` 를 참조하십시오. + +서비스 중지 +------------ + +제거하기 전에 모든 서비스를 중지합니다. + +ZIP 버전:: + + $ ps aux | grep -E 'fess|opensearch' + $ kill + $ kill + +RPM/DEB 버전:: + + $ sudo systemctl stop fess.service + $ sudo systemctl stop opensearch.service + +Docker 버전:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +ZIP 버전 제거 +============================= + +단계 1: Fess 삭제 +--------------------- + +설치 디렉터리를 삭제합니다:: + + $ rm -rf /path/to/fess-15.10.0 + +단계 2: OpenSearch 삭제 +-------------------------- + +OpenSearch 설치 디렉터리를 삭제합니다:: + + $ rm -rf /path/to/opensearch-3.9.0 + +단계 3: 데이터 디렉터리 삭제(옵션) +------------------------------------------- + +|Fess| 의 인덱스 데이터는 OpenSearch 에 저장됩니다. +기본적으로 OpenSearch 의 설치 디렉터리 내(``opensearch-3.9.0/data`` 등)에 저장되지만, +``path.data`` 로 다른 위치를 지정한 경우 해당 디렉터리도 삭제하십시오:: + + $ rm -rf /path/to/data + +단계 4: 로그 디렉터리 삭제(옵션) +----------------------------------------- + +로그 파일을 삭제합니다:: + + $ rm -rf /path/to/fess-15.10.0/logs + $ rm -rf /path/to/opensearch-3.9.0/logs + +RPM 버전 제거 +====================== + +단계 1: Fess 제거 +--------------------------------- + +RPM 패키지를 제거합니다:: + + $ sudo rpm -e fess + +.. note:: + + |Fess| 패키지를 제거할 때에는 패키지의 삭제 스크립트에 의해 + ``fess`` 서비스의 중지·비활성화와 ``fess`` 사용자 및 그룹의 삭제가 자동으로 실행됩니다. + 이후 단계는 이러한 항목이 확실히 삭제되었는지 확인하기 위해, 또는 + 데이터나 설정 파일을 수동으로 삭제하기 위해 실시합니다. + +단계 2: OpenSearch 제거 +-------------------------------------- + +:: + + $ sudo rpm -e opensearch + +단계 3: 서비스 비활성화 확인 +------------------------------- + +일반적으로 패키지 삭제 시 서비스가 비활성화되지만, 만약을 위해 확인·비활성화하는 경우 다음을 실행합니다. + +systemd 의 경우:: + + $ sudo systemctl disable fess.service + $ sudo systemctl disable opensearch.service + $ sudo systemctl daemon-reload + +오래된 SysV init(chkconfig) 환경의 경우:: + + $ sudo /sbin/chkconfig --del fess + $ sudo /sbin/chkconfig --del opensearch + +단계 4: 데이터 디렉터리 삭제 +---------------------------------- + +.. warning:: + + 이 작업을 실행하면 모든 인덱스 데이터가 완전히 삭제됩니다. + +데이터 디렉터리는 패키지 제거로는 삭제되지 않으므로 수동으로 삭제합니다:: + + $ sudo rm -rf /var/lib/fess + $ sudo rm -rf /var/lib/opensearch + +단계 5: 설정 파일 삭제 +---------------------------- + +설정 파일과 환경 설정 파일을 삭제합니다:: + + $ sudo rm -rf /etc/fess + $ sudo rm -rf /etc/sysconfig/fess + $ sudo rm -rf /etc/opensearch + +.. note:: + + RPM 에서는 ``/etc/fess`` 내의 설정 파일이 ``.rpmsave`` 라는 이름으로 남는 경우가 있습니다. + 완전히 삭제하려면 위와 같이 수동으로 삭제하십시오. + +단계 6: 로그 파일 삭제 +---------------------------- + +:: + + $ sudo rm -rf /var/log/fess + $ sudo rm -rf /var/log/opensearch + +단계 7: 임시 디렉터리 삭제(옵션) +----------------------------------------- + +:: + + $ sudo rm -rf /var/tmp/fess + +단계 8: 사용자 및 그룹 삭제(옵션) +------------------------------------------- + +일반적으로 패키지 삭제 시 ``fess`` 사용자·그룹은 삭제됩니다. +남아 있는 경우나 OpenSearch 용 사용자·그룹을 삭제하는 경우 다음을 실행합니다:: + + $ sudo userdel fess + $ sudo groupdel fess + $ sudo userdel opensearch + $ sudo groupdel opensearch + +DEB 버전 제거 +====================== + +단계 1: Fess 제거 +--------------------------------- + +DEB 패키지를 제거합니다:: + + $ sudo dpkg -r fess + +설정 파일이나 환경 설정 파일도 포함하여 완전히 삭제하는 경우 purge 를 사용합니다:: + + $ sudo dpkg -P fess + +.. note:: + + ``dpkg -r``\ (remove)에서는 설정 파일(conffile)인 ``/etc/default/fess`` 등은 남습니다. + ``dpkg -P``\ (purge)를 사용하면 이러한 설정 파일과 ``fess`` 사용자·그룹도 삭제됩니다. + +단계 2: OpenSearch 제거 +-------------------------------------- + +:: + + $ sudo dpkg -r opensearch + +또는 설정 파일도 포함하여 삭제:: + + $ sudo dpkg -P opensearch + +단계 3: 서비스 비활성화 확인 +------------------------------- + +일반적으로 패키지 삭제 시 서비스가 비활성화됩니다. 만약을 위해 확인·비활성화하는 경우 다음을 실행합니다:: + + $ sudo systemctl disable fess.service + $ sudo systemctl disable opensearch.service + $ sudo systemctl daemon-reload + +단계 4: 데이터 디렉터리 삭제 +---------------------------------- + +.. warning:: + + 이 작업을 실행하면 모든 인덱스 데이터가 완전히 삭제됩니다. + +:: + + $ sudo rm -rf /var/lib/fess + $ sudo rm -rf /var/lib/opensearch + +단계 5: 설정 파일 삭제(dpkg -P 를 사용하지 않은 경우) +--------------------------------------------------------- + +:: + + $ sudo rm -rf /etc/fess + $ sudo rm -rf /etc/default/fess + $ sudo rm -rf /etc/opensearch + +단계 6: 로그 파일 삭제 +---------------------------- + +:: + + $ sudo rm -rf /var/log/fess + $ sudo rm -rf /var/log/opensearch + +단계 7: 사용자 및 그룹 삭제(옵션) +------------------------------------------- + +``dpkg -P`` 를 사용하지 않은 경우 ``fess`` 사용자·그룹이 남습니다. +삭제하는 경우 다음을 실행합니다:: + + $ sudo userdel fess + $ sudo groupdel fess + $ sudo userdel opensearch + $ sudo groupdel opensearch + +Docker 버전 제거 +========================= + +단계 1: 컨테이너 및 네트워크 삭제 +------------------------------------ + +컨테이너 및 Docker Compose 가 생성한 네트워크(``search_net``)를 삭제합니다:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +단계 2: 볼륨 삭제 +-------------------------- + +.. warning:: + + 이 작업을 실행하면 모든 데이터가 완전히 삭제됩니다. + +|Fess| 의 데이터(인덱스나 사전 등)는 OpenSearch 의 볼륨에 저장됩니다. +먼저 볼륨 목록을 확인합니다:: + + $ docker volume ls + +OpenSearch 관련 볼륨을 삭제합니다:: + + $ docker volume rm _search01_data + $ docker volume rm _search01_dictionary + +.. note:: + + 볼륨 이름에는 Docker Compose 의 프로젝트 이름(일반적으로 Compose 파일을 배치한 + 디렉터리 이름)이 접두사로 붙습니다. ``docker volume ls`` 로 실제 이름을 확인하십시오. + +컨테이너와 볼륨을 일괄로 삭제하는 경우 ``down`` 에 ``-v`` 옵션을 붙입니다:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down -v + +단계 3: 이미지 삭제(옵션) +------------------------------------ + +Docker 이미지를 삭제하여 디스크 공간을 확보하는 경우:: + + $ docker images | grep fess + $ docker rmi ghcr.io/codelibs/fess:15.10.0 + $ docker rmi ghcr.io/codelibs/fess-opensearch:3.9.0 + +단계 4: Compose 파일 삭제 +-------------------------------- + +:: + + $ rm compose.yaml compose-opensearch3.yaml + +제거 확인 +==================== + +모든 구성요소가 삭제되었는지 확인합니다. + +프로세스 확인 +------------ + +:: + + $ ps aux | grep fess + $ ps aux | grep opensearch + +아무것도 표시되지 않으면 프로세스가 중지되어 있습니다. + +포트 확인 +---------- + +:: + + $ sudo ss -tuln | grep 8080 + $ sudo ss -tuln | grep 9200 + +포트가 사용되고 있지 않은지 확인합니다. + +파일 확인 +------------ + +ZIP 버전:: + + $ ls /path/to/fess-15.10.0 # 디렉터리가 존재하지 않는지 확인 + +RPM/DEB 버전:: + + $ ls /var/lib/fess # 디렉터리가 존재하지 않는지 확인 + $ ls /etc/fess # 디렉터리가 존재하지 않는지 확인 + +Docker 버전:: + + $ docker ps -a | grep -E 'fess01|search01' # 컨테이너가 존재하지 않는지 확인 + $ docker volume ls | grep search01 # 볼륨이 존재하지 않는지 확인 + +패키지 확인 +-------------- + +RPM 버전:: + + $ rpm -qa | grep fess + $ rpm -qa | grep opensearch + +DEB 버전:: + + $ dpkg -l | grep fess + $ dpkg -l | grep opensearch + +아무것도 표시되지 않으면 패키지가 삭제되어 있습니다. + +부분 제거 +====================== + +Fess만 삭제하고 OpenSearch 유지 +----------------------------------- + +OpenSearch 를 다른 애플리케이션에서도 사용하고 있는 경우 Fess 만 삭제할 수 있습니다. + +1. Fess 중지 +2. Fess 패키지 또는 디렉터리 삭제 +3. Fess 데이터 디렉터리 삭제(``/var/lib/fess`` 등) +4. OpenSearch 내에 생성된 |Fess| 의 인덱스 삭제 + + |Fess| 인덱스의 이름은 ``fess`` 로 시작합니다(``fess.*``, ``fess_config.*``, ``fess_user.*``, ``fess_log.*``, ``fess_crawler.*``, ``fess_suggest*`` 등). 다음 명령으로 한꺼번에 삭제할 수 있습니다. + + :: + + $ curl -X DELETE 'http://localhost:9200/fess*' + + 삭제하기 전에 ``curl 'http://localhost:9200/_cat/indices?v'`` 로 ``fess`` 로 시작하는 이름의 다른 애플리케이션 인덱스가 없는지 확인하십시오. 사전을 동기화하는 ``configsync`` 인덱스도 다른 애플리케이션에서 사용하지 않는다면 삭제할 수 있습니다. + +5. OpenSearch 는 삭제하지 않음 + +OpenSearch만 삭제하고 Fess 유지 +----------------------------------- + +.. warning:: + + OpenSearch 를 삭제하면 Fess 는 작동하지 않게 됩니다. + 다른 OpenSearch 클러스터에 연결하도록 설정을 변경하십시오. + +1. OpenSearch 중지 +2. OpenSearch 패키지 또는 디렉터리 삭제 +3. OpenSearch 데이터 디렉터리 삭제(``/var/lib/opensearch`` 등) +4. Fess 설정을 업데이트하여 다른 OpenSearch 클러스터 지정 + +문제 해결 +==================== + +패키지를 삭제할 수 없음 +---------------------- + +**증상:** + +``rpm -e`` 또는 ``dpkg -r`` 에서 오류 발생. + +**해결 방법:** + +1. 서비스가 중지되어 있는지 확인:: + + $ sudo systemctl stop fess.service + +2. 종속성 확인:: + + $ rpm -qa | grep fess + $ dpkg -l | grep fess + +3. 강제 삭제(최후의 수단):: + + $ sudo rpm -e --nodeps fess + $ sudo dpkg -r --force-all fess + +디렉터리를 삭제할 수 없음 +------------------------ + +**증상:** + +``rm -rf`` 로 디렉터리를 삭제할 수 없음. + +**해결 방법:** + +1. 권한 확인:: + + $ ls -ld /path/to/directory + +2. sudo로 삭제:: + + $ sudo rm -rf /path/to/directory + +3. 프로세스가 파일을 사용하고 있지 않은지 확인:: + + $ sudo lsof | grep /path/to/directory + +재설치 준비 +================== + +제거 후 재설치하는 경우 다음을 확인하십시오: + +1. 모든 프로세스가 중지되어 있는지 +2. 모든 파일과 디렉터리가 삭제되어 있는지 +3. 포트 8080 및 9200이 사용되고 있지 않은지 +4. 이전 설정 파일이 남아 있지 않은지 + +재설치 절차에 대해서는 :doc:`install` 을 참조하십시오. + +다음 단계 +========== + +제거가 완료되면: + +- 새 버전을 설치하는 경우 :doc:`install` 참조 +- 데이터를 이전하는 경우 :doc:`upgrade` 참조 +- 대체 검색 솔루션을 검토하는 경우 Fess 공식 사이트 참조 diff --git a/ko/15.10/install/upgrade.rst b/ko/15.10/install/upgrade.rst new file mode 100644 index 000000000..33e5a4199 --- /dev/null +++ b/ko/15.10/install/upgrade.rst @@ -0,0 +1,1606 @@ +==================== +업그레이드 절차 +==================== + +이 페이지에서는 |Fess| 를 이전 버전에서 최신 버전으로 업그레이드하는 절차에 대해 설명합니다. + +.. warning:: + + **업그레이드 전 중요한 주의사항** + + - 업그레이드 전에 반드시 백업을 취득하십시오 + - 테스트 환경에서 사전에 업그레이드를 검증할 것을 강력히 권장합니다 + - 업그레이드 중에는 서비스가 중지되므로 적절한 유지보수 시간을 설정하십시오 + - 버전에 따라 설정 파일 형식이 변경된 경우가 있습니다 + +대응 버전 +============ + +이 업그레이드 절차는 다음 버전 간의 업그레이드에 대응합니다: + +- Fess 14.x → Fess 15.10 +- Fess 15.x → Fess 15.10 + +.. important:: + + |Fess| 14.x는 OpenSearch 2.x 계열, |Fess| 15.10은 OpenSearch 3.9.0에 대응합니다. + |Fess| 용 OpenSearch 플러그인은 OpenSearch 버전과 완전히 일치해야 하므로, + 14.x에서 업그레이드하는 경우 OpenSearch의 메이저 버전 업그레이드도 필수입니다. + :ref:`upgrade-opensearch` 를 참조하십시오. + +.. note:: + + 더 오래된 버전(13.x 이전)에서 업그레이드하는 경우 단계적 업그레이드가 필요할 수 있습니다. + 자세한 내용은 릴리스 노트를 확인하십시오. + +업그레이드 전 준비 +==================== + +버전 호환성 확인 +-------------------- + +업그레이드 대상 버전과 현재 버전의 호환성을 확인하십시오. + +- `릴리스 노트 `__ +- :doc:`prerequisites` - |Fess| 15.10의 동작 환경(Java, OpenSearch 버전) + +다운타임 계획 +---------------- + +업그레이드 작업에는 시스템 중지가 필요합니다. 다음을 고려하여 다운타임을 계획하십시오: + +- 백업 시간: 10분 ~ 수 시간(데이터 양에 따라) +- 업그레이드 시간: 10 ~ 30분 +- 동작 확인 시간: 30분 ~ 1시간 +- 예비 시간: 30분 + +**권장 유지보수 시간**: 총 2 ~ 4시간 + +단계 1: 데이터 백업 +============================== + +업그레이드 전에 모든 데이터를 백업하십시오. + +설정 데이터 백업 +---------------------- + +1. **관리 화면에서 백업** + + 관리 화면에 로그인하여 「시스템 정보」→「백업」을 클릭합니다. + + 백업 페이지에는 다음 설정 데이터가 항목별로 목록 표시됩니다. + 각 행을 클릭하여 다운로드합니다(단일 ZIP 파일이 아니라 항목별 개별 파일입니다. + 일괄 다운로드 기능은 없으므로 필요한 항목을 하나씩 다운로드합니다). + + - ``fess_basic_config.bulk`` - 설정 인덱스(크롤 설정, 스케줄러, 레이블, + 키 매치, 역할, 웹/파일 인증 등 19개 인덱스) + - ``fess_config.bulk`` - 위 19개 인덱스에 더해 크롤 정보, 장애 URL, 작업 로그, + 썸네일 큐 등 실행 시 데이터를 포함하는 25개 인덱스(15.8 까지. 15.10 에서는 사용자 태그를 + 보관하는 ``tag_type`` 인덱스가 추가되어 26개) + - ``fess_user.bulk`` - 사용자, 역할, 그룹 + - ``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개면 충분합니다. 다만 백업 원본이 15.10 이상이고 사용자 태그를 사용하는 경우에는, 사용자 태그를 보관하는 ``tag_type`` 인덱스가 ``fess_basic_config.bulk`` 에 포함되지 않으므로 ``fess_config.bulk`` 도 다운로드하십시오( :doc:`../admin/tagtype-guide` 참조). + + .. note:: + + 검색 로그나 클릭 로그 등의 로그 데이터(``search_log.ndjson``, ``click_log.ndjson``, + ``favorite_log.ndjson``, ``user_info.ndjson``. 15.10 에서는 ``chat_log.ndjson`` 도 표시됩니다)도 + 같은 페이지에서 다운로드할 수 있습니다. + 설정만 백업하는 경우에는 불필요합니다. 또한 이 ``*.ndjson`` 파일들은 + 백업 페이지에서 업로드하여 복원할 수 없습니다 + (「롤백 절차」 참조). + +2. **설정 파일 백업** + + ZIP 버전:: + + $ 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 버전:: + + $ 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`` 등을 지정하는 환경 변수 파일입니다. + ZIP 버전에서 이에 해당하는 설정은 ``bin/fess.in.sh`` 에 있습니다. + +3. **커스터마이징한 설정 파일** + + 커스터마이징한 설정 파일이 있는 경우 해당 파일도 백업합니다:: + + $ cp /path/to/fess/app/WEB-INF/classes/log4j2.xml /backup/ + $ cp /path/to/fess/lib/classes/tomcat_config.properties /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의 스냅샷 기능을 사용하여 인덱스를 백업합니다. + +.. note:: + + 파일 시스템 리포지토리(``fs``)를 등록하려면 사전에 OpenSearch의 ``opensearch.yml`` 의 + ``path.repo`` 에 백업 대상 디렉터리를 지정하고 OpenSearch를 재시작해 두어야 합니다. + +1. 리포지토리 설정:: + + $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup" -H 'Content-Type: application/json' -d' + { + "type": "fs", + "settings": { + "location": "/backup/opensearch/snapshots" + } + }' + +2. 스냅샷 생성:: + + $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup/snapshot_1?wait_for_completion=true" + +3. 스냅샷 확인:: + + $ curl -X GET "http://localhost:9200/_snapshot/fess_backup/snapshot_1" + +방법 2: 디렉터리별 백업 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +OpenSearch를 중지한 후 데이터 디렉터리를 백업합니다. + +:: + + $ sudo systemctl stop opensearch + $ sudo tar czf /backup/opensearch-data-$(date +%Y%m%d).tar.gz /var/lib/opensearch/data + $ sudo systemctl start opensearch + +Docker 버전 백업 +--------------------- + +OpenSearch의 데이터는 Docker 볼륨에 저장됩니다. ``compose-opensearch3.yaml`` 에는 +인덱스 데이터용 ``search01_data`` 와 사전 파일용 ``search01_dictionary`` 의 +2개 볼륨이 정의되어 있습니다. + +.. note:: + + 실제 볼륨 이름에는 Compose 프로젝트 이름(기본값은 Compose 파일을 배치한 + 디렉터리 이름)이 접두사로 부여됩니다. 정확한 이름은 다음 명령으로 확인하십시오:: + + $ docker volume ls + +컨테이너를 중지한 후 볼륨을 백업합니다. ``docker run`` 의 ``-v`` 에는 +접두사를 포함한 실제 볼륨 이름을 지정합니다:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop + $ 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를 중지합니다. + +ZIP 버전에는 중지용 스크립트가 포함되어 있지 않습니다. ``bin/fess`` 를 ``-p`` 옵션과 함께 +실행한 경우에는 PID 파일을 사용하여 중지합니다:: + + $ kill $(cat /path/to/fess/fess.pid) + $ kill + +``-p`` 를 지정하지 않고 실행한 경우에는 프로세스 ID를 확인하여 ``kill`` 합니다 +(``-d`` 만으로는 PID 파일이 생성되지 않습니다). + +RPM/DEB 버전 (systemd):: + + $ sudo systemctl stop fess.service + $ sudo systemctl stop opensearch.service + +Docker 버전:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +.. warning:: + + 단계 3을 시작하기 전에 |Fess| 가 중지되어 있는지 확인하십시오. 실행 중인 |Fess| 의 패키지나 + 파일을 교체하지 마십시오. 실행 중인 15.8 |Fess| 의 DEB 패키지를 15.10 의 것으로 교체했더니 + |Fess| 를 재시작할 때까지 검색 화면이 ``404`` 를 반환했습니다. 패키지 버전에서는 + ``systemctl status fess.service`` 로 확인할 수 있습니다. + +단계 3: 새 버전 설치 +====================================== + +설치 방법에 따라 절차가 다릅니다. + +ZIP 버전 +--------------- + +1. 새 버전을 다운로드하여 압축을 해제합니다:: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.zip + $ unzip fess-15.10.0.zip + + .. note:: + + |Fess| 의 아카이브 버전은 ZIP 형식으로만 배포됩니다(``fess-15.10.0.tar.gz`` 는 + 제공되지 않습니다). + +2. 이전 버전의 설정을 복사합니다:: + + $ cp /path/to/old-fess/app/WEB-INF/conf/system.properties /path/to/fess-15.10.0/app/WEB-INF/conf/ + $ cp /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.10.0/app/WEB-INF/classes/ + $ cp /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.10.0/bin/ + + .. warning:: + + ``fess_config.properties`` 와 ``fess.in.sh`` 를 그대로 복사하면 15.10 에서 기본값이 바뀐 값을 + 포함해 이전 버전의 값이 그대로 이어집니다. 예를 들어 업그레이드 후에 만든 작업의 기본값이 + Groovy 가 됩니다. 마지막 두 명령을 실행하기 전에 각 파일을 ``fess-15.10.0`` 의 파일과 비교하고, + 직접 변경한 값만 옮기십시오. 확인할 항목은 :ref:`upgrade-159-carried-over-config` 를 + 참조하십시오. + +3. 커스터마이징한 경우에는 다음도 복사합니다:: + + # Tomcat 설정(SAML 에 필요한 tomcat.sameSiteCookies=none 도 여기에 있습니다) + $ cp /path/to/old-fess/lib/classes/tomcat_config.properties /path/to/fess-15.10.0/lib/classes/ + # 설치된 플러그인 + $ cp -r /path/to/old-fess/app/WEB-INF/plugin/. /path/to/fess-15.10.0/app/WEB-INF/plugin/ + # 직접 업로드한 정적 테마(테마마다 하나의 디렉터리. bootstrap 은 제외) + $ cp -r /path/to/old-fess/app/themes/ /path/to/fess-15.10.0/app/themes/ + + .. warning:: + + 이전 설치의 ``tomcat_config.properties`` 를 복사하지 않으면 ``tomcat.sameSiteCookies`` 가 + 아무런 알림 없이 기본값 ``lax`` 로 돌아가 SAML 로그인이 동작하지 않게 됩니다 + ( :ref:`upgrade-159-saml` 참조). 이 파일의 기본 제공 내용은 15.8.0 과 15.10 에서 같으므로 + 그대로 복사할 수 있습니다. + + .. warning:: + + ``log4j2.xml`` 을 15.10 의 파일 위에 복사하지 마십시오. 15.10 의 파일은 ``RequestLoggingFilter`` + 로거를 ``warn`` 으로 고정하고 있으며, 15.8 의 파일을 복사하면 이 설정이 사라집니다. 로그 레벨을 + DEBUG 로 하면 요청 헤더( ``Authorization`` 포함)와 요청 파라미터(로그인 폼에 입력한 비밀번호 + 포함)가 로그에 기록됩니다. 두 파일을 ``diff`` 로 비교하여 직접 변경한 내용만 15.10 의 파일에 + 다시 적용하십시오. + + .. warning:: + + ``app/themes/`` 디렉터리 전체를 복사하지 마십시오. 이 디렉터리에는 |Fess| 에 번들된 테마 + ``bootstrap`` 도 들어 있으며, 이를 15.10 의 것 위에 복사하면 15.10 의 검색 화면이 15.8 버전의 + 테마로 바뀝니다. 직접 만든 테마의 디렉터리만 복사하십시오. |Fess| 프로젝트가 공개하는 테마는 + 대신 ``bin/fess-setup install theme `` 으로 15.10 용 빌드를 설치하십시오 + ( :doc:`fess-setup` 참조). + + .. warning:: + + 관리 화면 「디자인」에서 편집한 JSP(``app/WEB-INF/view/``)는 복사하지 마십시오. 15.10 의 검색 + 화면은 정적 테마이며 더 이상 이 JSP들을 사용하지 않습니다. 이러한 변경을 이제 어디에서 하는지는 + :ref:`upgrade-159-static-theme` 를 참조하십시오. + + .. note:: + + ``app/WEB-INF/plugin/`` 에서 복사한 플러그인은 이전 버전용으로 빌드된 것입니다. 복사한 뒤 + ``fess-15.10.0`` 에서 ``bin/fess-setup upgrade plugins`` 를 실행하여 각 플러그인을 15.10 용으로 + 빌드된 버전으로 교체하십시오( :ref:`upgrade-plugin-versions` 참조). + +4. 설정 차이를 확인하고 필요에 따라 조정합니다 + +RPM/DEB 버전 +------------ + +새 버전 패키지를 설치:: + + # RPM + $ sudo rpm -Uvh fess-15.10.0.rpm + + # DEB + $ sudo dpkg -i fess-15.10.0.deb + +.. note:: + + RPM 버전에서는 ``/etc/fess/*`` 의 설정 파일이 ``%config(noreplace)`` 로 등록되어 있으므로 + 업그레이드 시에도 유지됩니다(새 기본 파일은 ``.rpmnew`` 로 함께 배치됩니다). + 새로운 설정 옵션이 추가된 경우에는 수동으로 조정이 필요합니다. 변경한 + ``/etc/fess/fess_config.properties`` 는 ZIP 버전 절차에서 복사한 파일과 마찬가지로 15.10 에서도 + 이전 값이 그대로 사용됩니다. :ref:`upgrade-159-carried-over-config` 를 참조하십시오. + +.. warning:: + + DEB 버전에서는 ``/etc/fess`` 아래의 파일(``fess_config.properties`` 와 + ``tomcat_config.properties`` 등)이 ``/etc/default/fess``, ``/etc/init.d/fess``, + ``/usr/lib/systemd/system/fess.service`` 와 마찬가지로 conffile로 등록되어 있습니다. + 15.8 에서 처음 업그레이드할 때 ``dpkg`` 는 이를 다음과 같이 처리합니다. + + - 편집하지 않은 파일은 확인 없이 15.10 의 파일로 교체됩니다. + - 편집한 파일에 대해서는 ``dpkg`` 가 확인을 요청합니다. 자신의 파일을 유지하면(기본 응답 또는 + ``--force-confold``) 15.10 의 파일이 ``<파일 이름>.dpkg-dist`` 로 함께 배치됩니다. 새 파일을 + 설치하면(``Y`` 또는 ``--force-confnew``) 자신의 파일이 ``<파일 이름>.dpkg-old`` 로 저장됩니다. + - 응답할 사람이 없으면 ``dpkg -i`` 와 ``apt-get install -y`` 는 첫 번째 확인에서 멈춥니다. + 무인으로 업그레이드하려면 ``--force-confold`` 를 지정하십시오(``--force-confdef`` 로도 확인이 + 나오지 않습니다). 예를 들면 ``sudo dpkg --force-confold -i fess-15.10.0.deb`` 나 + ``sudo apt-get install -y -o Dpkg::Options::=--force-confold ./fess-15.10.0.deb`` 입니다. + + 어느 경우든 먼저 ``/etc/fess`` 를 백업하십시오(단계 1). 유지한 파일은 여전히 15.8 의 값이므로 + 그대로 사용하지 말고 ``.dpkg-dist`` 파일과 비교하십시오( :ref:`upgrade-159-carried-over-config` + 참조). 또한 ``/etc/fess/system.properties`` 는 패키지에 포함되지 않는 실행 시 생성 파일이므로 + 덮어써지지 않습니다. + +Docker 버전 +----------- + +1. 새 버전의 Compose 파일 가져오기:: + + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose.yaml + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose-opensearch3.yaml + +2. 새 이미지 가져오기:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull + +.. _upgrade-opensearch: + +단계 4: OpenSearch 업그레이드 +==================================== + +|Fess| 15.10은 OpenSearch 3.9.0에 대응합니다. 연결 대상 OpenSearch가 이보다 오래된 경우 +다음 절차에 따라 업그레이드하십시오. + +.. note:: + + 이 절차는 ZIP 버전 및 RPM/DEB 버전에서 OpenSearch를 수동으로 운용하는 경우의 절차입니다. + Docker 버전에서는 단계 3에서 새 이미지를 가져오면 OpenSearch와 플러그인도 + 함께 업데이트되므로 이 단계는 불필요합니다. + +.. important:: + + |Fess| 15.10은 청크 벡터 검색(시맨틱 검색) 사용 여부와 관계없이 검색 인덱스 설정에 + ``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에서의 업그레이드는 반드시 이 경우에 해당합니다. + + OpenSearch 3.9.0에서 생성한 스냅샷은 OpenSearch 3.8.0 이하로 복원할 수 없습니다. 롤백에 대비하여 업그레이드 전에 생성한 스냅샷을 보관해 두십시오. + +1. 새 버전의 OpenSearch 설치 + +2. 플러그인 재설치:: + + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + + .. note:: + + 이러한 플러그인의 버전은 사용하는 OpenSearch의 버전과 일치시켜야 합니다. + |Fess| 15.10은 OpenSearch 3.9.0에 대응합니다. 버전이 일치하지 않으면 + 플러그인 설치에 실패합니다. + + |Fess| 용 플러그인 4개는 maven.codelibs.org 에 공개되어 있으므로 URL로 지정합니다. ``opensearch-plugin install`` 의 ``groupId:artifactId:version`` 형식은 Maven Central만 참조합니다. + +3. 사전 디렉터리를 OpenSearch 설정 디렉터리 아래로 이동 + + OpenSearch 3.8.0 이상에서는 사전 파일이 OpenSearch 설정 디렉터리 밖에 있으면 인덱스 생성을 거부합니다. + 이전 절차대로 ``configsync.config_path`` 에 ``/var/lib/opensearch/data/config/`` (ZIP 버전에서는 ``/path/to/opensearch/data/config/``) 등 설정 디렉터리 밖을 지정한 경우, + |Fess| 는 인덱스를 생성할 수 없어 시작되지 않습니다. + RPM/DEB 버전에서는 다음과 같이 사전 파일을 ``/etc/opensearch/dictionary/`` 로 복사합니다:: + + $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary + $ sudo cp -a /var/lib/opensearch/data/config/. /etc/opensearch/dictionary/ + $ sudo chown -R opensearch:opensearch /etc/opensearch/dictionary + + 그런 다음 ``/etc/opensearch/opensearch.yml`` 의 ``configsync.config_path`` 와 |Fess| 의 ``FESS_DICTIONARY_PATH`` (RPM 버전은 ``/etc/sysconfig/fess``, DEB 버전은 ``/etc/default/fess``)를 모두 ``/etc/opensearch/dictionary/`` 로 변경합니다. + ZIP 버전에서는 OpenSearch 의 ``config/dictionary/`` 를 사용합니다. 자세한 내용은 :doc:`install-linux` 를 참조하십시오. + +4. OpenSearch 시작:: + + $ sudo systemctl start opensearch.service + +단계 5: 새 버전 시작 +================================ + +ZIP 버전:: + + $ cd /path/to/fess-15.10.0 + $ ./bin/fess -d -p /path/to/fess-15.10.0/fess.pid + +.. note:: + + ``-p`` 를 지정하면 PID 파일이 생성되며, 다음 중지 시 + ``kill $(cat /path/to/fess-15.10.0/fess.pid)`` 로 중지할 수 있습니다. + +RPM/DEB 버전:: + + $ sudo systemctl start opensearch.service + $ sudo systemctl start fess.service + +Docker 버전:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +단계 6: 동작 확인 +================== + +1. **로그 확인** + + 오류가 없는지 확인합니다. + + 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/ 에 액세스합니다. + +3. **관리 화면 로그인** + + http://localhost:8080/admin 에 액세스하여 관리자 계정으로 로그인합니다. + +4. **버전 확인** + + 관리 화면에서 「시스템 정보」→「설정 정보」를 클릭하여 「시스템 속성」에 표시되는 + ``fess.version`` 이 새 버전으로 되어 있는지 확인합니다. + +5. **검색 동작 확인** + + 검색 화면에서 검색을 실행하여 정상적으로 결과가 반환되는지 확인합니다. + +단계 7: 인덱스 재작성(권장) +==================================== + +메이저 버전 업그레이드의 경우 인덱스를 재작성할 것을 권장합니다. + +.. note:: + + 아래 단계는 크롤을 다시 실행하는 것으로, 인덱스 매핑(필드 정의)은 업데이트되지 않습니다. + 매핑을 업데이트하는 재인덱스가 필요한 경우 — 예를 들어 청크 벡터 검색(시맨틱 검색)을 새로 + 활성화하려는 경우 등 — 는 관리 화면의 「시스템 정보」→「유지보수」에서 「재인덱싱」을 별도로 + 실행하세요. 자세한 내용은 :ref:`semantic-search-migration`\ (:doc:`../config/search-semantic`)\ 을 + 참조하세요. + + 15.8 이전에 생성한 문서 인덱스를 계속 사용하는 경우에는 :ref:`upgrade-reindex-new-fields` 도 참조하십시오. + +.. warning:: + + OpenSearch 3.9.0 은 15.8 이 받아들였던 사전 항목을 거부합니다. 같은 ``mapping`` 항목을 두 번 + 저장한 경우나 공백이 포함된 ``kuromoji`` 토큰이 그 예입니다. 이러한 항목이 있으면 + 「재인덱싱」은 새 문서 인덱스를 생성하지 않으며, ``fess.log`` 에는 ``Failed to create index`` 라고만 + 출력되고 이전 인덱스가 계속 검색을 제공합니다. 「시스템」→「사전」에서 사전을 다운로드하여 + 중복되거나 잘못된 행을 삭제한 뒤 다시 업로드하고 「재인덱싱」을 다시 실행하십시오. 15.10 가 더 이상 + 저장하지 않는 항목은 :ref:`upgrade-159-api-requests` 를 참조하십시오. + +1. 기존 크롤 일정 확인 +2. 「시스템」→「스케줄러」에서 "Default Crawler" 실행 +3. 크롤이 완료될 때까지 대기 +4. 검색 결과 확인 + +.. warning:: + + 재인덱싱에서는 새로운 매핑으로 인덱스가 다시 생성되므로, k-NN 플러그인이 + 없는 OpenSearch에서는 실패합니다. 단계 4의 주의사항을 확인하십시오. + +15.8에서 15.10로 업그레이드 +========================== + +15.8에서 업그레이드하는 경우 다음 변경 사항은 하위 호환되지 않습니다. 15.7 이전에서 업그레이드하는 +경우에도 이 변경 사항이 모두 적용됩니다. 「내장 OpenSearch 폐지」부터 「기존 문서 인덱스에 새 필드와 +가나 정규화 반영」까지의 각 절(내장 OpenSearch, 스크립트 엔진, S3 와 SSO 플러그인, Index Exporter +작업 등)과 이 페이지 끝의 「15.10 전용 마이그레이션 작업」을 모두 읽으십시오. + +내장 OpenSearch 폐지 +-------------------- + +15.8 까지는 ``SEARCH_ENGINE_HTTP_URL`` 을 설정하지 않고 ``bin/fess`` 를 실행하면 |Fess| 가 자체 +JVM 안에서 OpenSearch 노드를 시작했습니다. 15.10 에서는 이 구성이 없어지고 검색 엔진은 항상 별도의 +서버가 됩니다. + +``bin/fess.in.sh`` 는 기본적으로 ``SEARCH_ENGINE_HTTP_URL=http://localhost:9200`` 을 설정합니다. +접속할 OpenSearch 가 없으면 |Fess| 는 시작되지 않습니다. ``bin/fess-setup install opensearch`` +로 설치할 수 있습니다(Linux 와 Windows 만 지원. macOS 용 OpenSearch 공식 배포판은 없으므로 +Homebrew 또는 Docker 를 사용하십시오). + +또한 ``FESS_DICTIONARY_PATH`` 를 해당 OpenSearch 의 ``opensearch.yml`` 에 있는 ``configsync.config_path`` +와 일치시켜야 합니다. 설정되지 않았거나 일치하지 않으면 |Fess| 는 인덱스를 생성할 수 없습니다. 15.10 의 +``bin/fess.in.sh`` (Windows 에서는 ``bin\fess.in.bat`` )는 |Fess| 디렉터리의 ``opensearch/`` 에 +``bin/fess-setup install opensearch`` 로 설치한 OpenSearch 가 하나만 있을 때 이를 자동으로 설정합니다. +그 밖의 OpenSearch 를 사용하는 경우에는 :doc:`install-linux` 또는 :doc:`install-windows` 에 따라 +설정하십시오. + +다음도 함께 폐지되었습니다. + +- ``es/`` 디렉터리( ``es/modules`` , ``es/plugins`` , ``es/data`` ) +- ``-Dfess.es.dir`` 와 ``SEARCH_ENGINE_HOME`` +- ``bin/module.xml`` 과 ``bin/plugin.xml`` +- 이전 ``elasticsearch.*`` 설정 키에 대한 대체 처리 + +또한 OpenSearch 3 이전 버전에 접속한 경우 15.8 까지는 오류 로그를 남기고 계속 실행했지만 15.10 +에서는 시작에 실패합니다. 해당 버전에는 전체 문서를 순회하는 처리가 사용하는 ``_shard_doc`` +정렬이 구현되어 있지 않아, HTTP 를 통해서는 실패하지 않고 응답이 돌아오지 않기 때문입니다. + +.. warning:: + + 내장 OpenSearch 로 운영한 경우 인덱스 데이터는 이어받을 수 없습니다. 외부 OpenSearch 서버를 + 새로 구축하고 관리 화면의 「백업」에서 설정을 옮긴 뒤 다시 크롤링하십시오. 백업에 포함되는 + 것은 크롤링 설정, 사용자, 로그이며 **크롤링한 문서는 포함되지 않습니다**. + +.. note:: + + 15.8 의 백업을 새 15.10 서버에 복원할 때 알아 둘 점이 두 가지 있습니다. + + - 작업은 서버에 있는 것보다 새로운 경우에만 복원됩니다. 따라서 15.8 에서 편집하지 않은 기본 제공 작업은 + 15.10 의 JavaScript 버전을 그대로 유지합니다. 15.8 에서 편집하거나 만든 작업은 저장된 스크립트 엔진 + (기본 제공 작업이면 ``groovy``) 으로 복원되며, ``fess-script-groovy`` 플러그인이 없으면 + ``groovy is not found`` 로 실패합니다. 플러그인을 설치하거나 해당 작업을 JavaScript 로 전환하십시오. + 둘 다 :ref:`upgrade-159-script-engine` 에 설명되어 있습니다. + - 웹 인증, 크롤링 설정, 데이터스토어 설정의 파라미터에 저장된 비밀번호와 시크릿은 + ``app.cipher.key`` 로 암호화되어 있습니다. 새 서버의 ``fess_config.properties`` 에 이전 + 설치의 값을 설정하십시오( :ref:`upgrade-159-carried-over-config` 참조). 그렇지 않으면 + 복호화할 수 없습니다. + +Playwright 크롤러를 플러그인으로 이동 +------------------------------------- + +Playwright 크롤러와 그것이 사용하는 Node.js 실행 파일은 더 이상 배포물에 포함되지 +않습니다. ``fess-15.8.0.zip`` (457.1 MiB)에서는 Node.js 실행 파일을 담은 Playwright 드라이버 +번들이 204.3 MiB 를 차지했습니다. + +크롤링 설정의 설정 파라미터에서 ``client.crawlerClients=playwright:http://.*`` 와 같이 +Playwright 클라이언트를 지정한 경우에는 플러그인과 Node.js 를 모두 설치하십시오. +플러그인은 관리 화면의 「시스템 > 플러그인」 페이지에서도 설치할 수 있습니다. +``bin/fess.in.sh`` 가 Node.js 설치 위치를 찾아 ``PLAYWRIGHT_NODEJS_PATH`` 를 설정합니다. + +:: + + $ bin/fess-setup install plugin fess-crawler-playwright + $ bin/fess-setup install nodejs + +플러그인이 없어도 이러한 설정은 크롤링되지만 일반 HTTP 클라이언트가 사용되므로, JavaScript 로만 +생성되는 텍스트는 인덱싱되지 않습니다. 크롤 작업은 정상적으로 종료되며 장애 URL 도 기록되지 +않습니다. 크롤링할 때마다 ``fess-crawler.log`` 에는 크롤링 설정마다 1건씩, 플러그인 이름과 위의 +두 명령을 알려 주는 경고가 기록됩니다. + +Playwright 로 HTML 페이지의 썸네일을 생성하는 ``fess-thumbnail-playwright`` 플러그인도 Node.js +에서 동작합니다. 이 플러그인을 사용하는 경우에도 ``bin/fess-setup install nodejs`` 로 Node.js 를 +설치하십시오. 설치한 Node.js 는 두 플러그인이 함께 사용합니다. + +Playwright 크롤러도 ``fess-thumbnail-playwright`` 플러그인도 사용하지 않는 경우에는 대응이 필요 +없습니다. + +Google Cloud Storage 를 플러그인으로 이동 +----------------------------------------- + +Google Cloud Storage 의 SDK 는 더 이상 배포물에 포함되지 않으며, ``gcs://`` 크롤링과 +``gcs`` 스토리지 타입은 ``fess-storage-gcs`` 플러그인에서 제공됩니다. 관리 화면의 +「시스템 > 플러그인」 페이지 또는 아래 명령으로 설치하십시오. + +:: + + $ bin/fess-setup install plugin fess-storage-gcs + +``crawler.file.protocols`` 의 기본값에서도 ``gcs`` 가 빠져 ``file,smb,smb1,ftp`` 가 +되었습니다. 플러그인을 설치하면 다시 추가됩니다. 설치 전에는 경로가 ``gcs:`` 로 시작하는 +파일 크롤링 설정에 대해 경고가 기록될 뿐이며 아무것도 가져오지 않습니다. 업그레이드한 +기존 설치는 자체 ``crawler.file.protocols`` 를 그대로 유지하므로 경로는 계속 허용되지만 +처리할 크롤러 클라이언트가 없고, 새로 설치한 경우에는 ``gcs:`` 가 설정된 프로토콜이 +아니므로 관리 화면이 경로 저장을 거부하고 이전에 저장된 경로는 로컬 파일 경로로 +처리됩니다. 스토리지 화면도 경고를 기록하고 설치해야 하는 플러그인 이름이 포함된 오류를 +표시합니다. 이전에는 빈 파일 목록만 표시했습니다. + +Google Cloud Storage 를 사용하지 않는 경우에는 대응이 필요 없습니다. Amazon S3 와 MinIO +등 S3 호환 스토리지도 같은 방식으로 플러그인으로 이동했습니다. 다음 절을 참조하십시오. + +Amazon S3 를 플러그인으로 이동 +------------------------------ + +AWS SDK 는 더 이상 배포물에 포함되지 않으며, ``s3://`` 크롤링과 ``s3`` 및 ``s3_compat`` +스토리지 타입은 ``fess-storage-s3`` 플러그인에서 제공됩니다. 관리 화면의 +「시스템 > 플러그인」 페이지 또는 아래 명령으로 설치하십시오. + +:: + + $ bin/fess-setup install plugin fess-storage-s3 + +``crawler.file.protocols`` 의 기본값에서도 ``s3`` 가 빠져 ``file,smb,smb1,ftp`` 가 +되었습니다. 플러그인을 설치하면 다시 추가됩니다. ``storage.type`` 의 기본값은 여전히 +``auto`` 이며 엔드포인트가 설정되지 않으면 S3 로 해석되므로, ``s3`` 를 직접 지정하지 +않았더라도 플러그인을 설치할 때까지 관리 화면의 스토리지는 동작하지 않습니다. +``storage.*`` 설정값은 ``WEB-INF/conf/system.properties`` 에 있으므로 그대로 남고, 기존 +``crawler.file.protocols`` 도 업그레이드로 교체되지 않습니다. + +Amazon S3 와 MinIO 등 S3 호환 스토리지를 사용하지 않는 경우에는 대응이 필요 없습니다. + +SSO 인증을 플러그인으로 이동 +---------------------------- + +네 가지 SSO 인증은 모두 더 이상 배포물에 포함되지 않으며, ``sso.type`` 의 값별로 전용 +플러그인에서 제공됩니다. 플러그인에는 필요한 인증 라이브러리도 포함됩니다. 대응하는 +플러그인은 ``saml`` 에는 ``fess-sso-saml``, ``spnego`` 에는 ``fess-sso-spnego``, +``entraid`` (이전 이름 ``aad`` 포함)에는 ``fess-sso-entraid``, ``oic`` 에는 +``fess-sso-oidc`` 입니다. 마지막 조합에 유의하십시오. 플러그인 이름은 ``fess-sso-oidc`` +이지만 ``sso.type`` 의 값은 그대로 ``oic`` 이며, 둘이 달라지는 곳은 이 한 곳뿐입니다. +사용하는 것을 관리 화면의 「시스템 > 플러그인」 페이지 또는 아래 명령으로 설치하십시오. + +:: + + $ bin/fess-setup install plugin fess-sso-saml + +``sso.type`` 과 ``saml.*``, ``spnego.*``, ``entraid.*``, ``aad.*``, ``oic.*`` 각 키는 +``WEB-INF/conf/system.properties`` 에 있으므로 설정값은 그대로 남습니다. 관리 화면 +「시스템」→「일반」도 네 가지 모두를 선택 항목으로 표시하고 설정란도 그대로 남습니다. +플러그인에서 JSP 를 제공할 수 없기 때문이며, 이 화면은 플러그인이 없다는 것을 알리지 +않습니다. + +플러그인을 설치하기 전에는 ``/sso/`` 요청이 SSO 로그인 실패를 알리는 로그인 페이지로 +리디렉션되며 SSO 로 로그인할 수 없습니다. 15.10 에서는 찾은 컴포넌트 이름과 제공하는 +플러그인 이름이 포함된 경고가 ``fess.log`` 에 기록됩니다. 15.8 까지는 어느 로그 레벨에서도 +아무것도 출력되지 않았습니다. + +``oic`` 플러그인은 15.8 의 인증 기능보다 검증이 엄격합니다. ``oic.token.server.url`` 은 +HTTPS 여야 하며(``http`` 는 ``localhost``, ``127.x.x.x``, ``::1`` 에서만 사용할 수 있습니다), +ID Token 의 ``aud`` 와 ``exp`` 클레임을 검증합니다. 새 키 ``oic.issuer`` 를 설정한 경우에는 +``iss`` 도 검증합니다. 자세한 내용은 :doc:`../config/sso-oidc` 를 참조하십시오. + +15.8 에서는 ``oic.token.server.url`` 에 호스트 제한 없이 ``http`` URL을 지정할 수 있었습니다. 15.10 에서는 Docker Compose의 서비스 이름（``http://keycloak:8080/...`` 등）이나 사내 호스트 이름에 대한 ``http`` 는 같은 머신을 가리키더라도 거부됩니다. 거부되면 로그인에 실패하고 ``fess.log`` 에 ``Failed to process the OpenID Connect callback: oic.token.server.url must be https`` 로 시작하는 경고가 출력됩니다. 업데이트하기 전에 토큰 엔드포인트를 HTTPS URL로 변경하십시오. + +``oic.issuer`` 에 OP의 Discovery 문서에 있는 ``issuer`` 값을 설정하는 것도 권장합니다. 설정하지 않으면 ``iss`` 는 검증되지 않으며, 시작 후 첫 로그인 때 경고가 출력됩니다. ``oic.issuer`` 를 설정해도 HTTPS 규칙은 완화되지 않습니다. + +SSO 를 사용하지 않는 경우, 즉 ``sso.type`` 이 ``none`` 이거나 설정되지 않은 경우에는 +대응이 필요 없습니다. + +.. _upgrade-159-script-engine: + +내장 스크립트 엔진이 Groovy에서 JavaScript로 변경 +------------------------------------------------- + +15.8까지는 내장 스크립트 엔진이 Groovy였고 ``job.default.script`` 의 기본값도 ``groovy`` 였습니다. +15.10에서는 내장 엔진이 JavaScript이며 기본값은 ``javascript`` 입니다. Groovy는 더 이상 기본으로 +내장되지 않고 ``fess-script-groovy`` 플러그인이 제공합니다. ``scriptType`` 에 ``groovy`` 를 +지정하려면 이 플러그인을 설치해야 합니다. + +업그레이드는 각 설정에 저장된 스크립트 엔진을 바꾸지 않으며, 15.10 이전에 저장되어 엔진이 기록되지 +않은 설정은 ``groovy`` 로 취급됩니다. 플러그인이 없으면 다음이 동작하지 않게 됩니다. + +- ``groovy`` 로 저장된 스케줄 작업. + **15.8 이 직접 등록한 작업도 여기에 해당합니다.** Default Crawler, Suggest Indexer, + Config Reloader, Log Aggregator, Doc Purger 등 기본 제공 작업은 모두 ``groovy`` 로 저장되어 + 있으며, 15.10 는 시작할 때 아직 존재하지 않는 기본 제공 작업만 추가하므로 이 작업들은 바뀌지 + 않습니다. 각 작업은 스케줄에 따라 실행될 때마다 실패하고, Default Crawler 에 의한 크롤링도 + 이루어지지 않습니다. 기본 제공 작업 대부분은 「로깅」이 꺼져 있어 실패가 작업 로그에는 남지 + 않고 ``fess.log`` 에 ``Failed to execute job`` 경고로만 기록됩니다. +- 「설정 파라미터」에 필드 스크립트( ``field.script.<필드 이름>`` )를 작성한 웹 크롤링 설정과 + 파일 크롤링 설정. 해당 설정의 문서는 모두 ``ScriptEngineException`` 으로 실패하여 장애 URL 로 + 기록되지만, 크롤 작업 자체는 정상적으로 종료됩니다. +- 「스크립트」를 설정한 데이터스토어 설정. 파라미터 이름 자체가 아닌 값은 평가할 수 없습니다. + :doc:`../config/datastore/ds-overview` 를 참조하십시오. +- 문서 부스트 규칙. 해당 규칙은 아무것도 부스트하지 않습니다. +- 「치환」이 ``groovy:`` 로 시작하는 경로 매핑. 해당 매핑은 적용되지 않으며 URL 은 바뀌지 + 않습니다. + +처음 시작한 후 ``fess.log`` 에서 +``Settings use the script engine groovy, which is not registered`` 로 시작하는 경고를 +확인하십시오. |Fess| 는 시작할 때 위의 설정을 한 번 확인하고, 어느 플러그인도 제공하지 않는 +엔진을 사용하는 설정의 수를 종류별로 출력합니다. 15.8 에서 이어받은 ``fess_config.properties`` +에 ``job.default.script=groovy`` 가 남아 있으면 그것도 표시되며, 이 경우 업그레이드 후에 만든 +작업도 Groovy 를 사용합니다( :ref:`upgrade-159-carried-over-config` 참조). 다음 중 하나로 +대응하십시오. + +- 플러그인을 설치하고 |Fess| 를 재시작합니다. 저장된 Groovy 스크립트는 그대로 동작하며 경고도 + 더 이상 기록되지 않습니다. 플러그인은 관리 화면 「시스템」→「플러그인」에서도 설치할 수 + 있습니다. + + :: + + $ bin/fess-setup install plugin fess-script-groovy + +- 각 설정을 JavaScript 로 전환합니다. Groovy 만 허용하는 구문을 먼저 다시 작성한 뒤 + JavaScript 를 선택합니다. + + - 스케줄 작업: 관리 화면 「시스템」→「스케줄러」에서 「실행 방법」을 ``javascript`` 로 + 바꿉니다. 기본 제공 작업의 스크립트는 다음 두 가지를 제외하면 그대로 유효한 JavaScript + 입니다. Thumbnail Purger 는 Groovy 의 ``long`` 리터럴 ``1000L`` 을 사용하는데 JavaScript + 에서는 구문 오류가 됩니다( ``1000`` 으로 작성합니다). Index Exporter 에는 + :ref:`upgrade-159-index-exporter` 의 변경이 필요합니다. JavaScript의 배열 리터럴은 Java의 + ``String[]`` 로 자동 변환되므로 Groovy 형식의 ``as String[]`` 은 필요하지 않습니다. + + :: + + return container.getComponent("crawlJob").logLevel("info").webConfigIds(["1", "2"]).fileConfigIds(["1"]).dataConfigIds([]).execute(executor); + + - 웹 크롤링 설정과 파일 크롤링 설정: 「설정 파라미터」에 ``config.script.type=javascript`` + 를 추가합니다. + - 데이터스토어 설정: 「파라미터」에 ``script_type=javascript`` 를 추가합니다. + - 문서 부스트 규칙: 「스크립트 종류」를 ``javascript`` 로 바꿉니다. + - 경로 매핑: 「치환」을 ``groovy:`` 대신 ``javascript:`` 로 시작합니다. + - ``job.default.script``: 15.8 에서 이어받은 ``fess_config.properties`` 에서 ``javascript`` + 로 설정합니다. + +``crawler.default.script`` 삭제 +------------------------------- + +``crawler.default.script`` 는 ``fess_config.properties`` 에서 삭제되었습니다. 설정에 남겨 두어도 +효과가 없으므로 제거하십시오. + +크롤 프로토콜 ``storage`` 삭제 +------------------------------ + +``crawler.file.protocols`` 에서 ``storage`` 는 더 이상 사용할 수 없으며, 기본 제공 값은 +``file,smb,smb1,ftp`` 입니다. 대신 ``s3`` 를 사용하고, 경로가 ``storage:`` 로 시작하는 +파일 크롤 설정은 ``s3:`` 경로로 변경하십시오. ``s3`` 에는 ``fess-storage-s3`` 플러그인이 +필요합니다. + +.. _upgrade-159-index-exporter: + +Index Exporter 작업이 삭제된 패키지를 참조 +------------------------------------------ + +15.10 에는 ``org.opensearch`` 클래스가 더 이상 포함되지 않으며, 작업 스크립트에서 사용하는 쿼리 +빌더는 ``org.codelibs.fesen.opensearch`` 아래로 옮겨졌습니다. 15.8 이 Index Exporter 작업에 +저장한 스크립트는 ``org.opensearch.index.query.QueryBuilders`` 를 참조하며 업그레이드로도 +교체되지 않으므로, ``fess-script-groovy`` 를 설치해도 이 작업은 실패합니다. 이 작업은 +비활성화되고 스케줄이 없는 상태로 제공되므로 실행하는 경우에만 영향이 있습니다. 관리 화면 +「시스템」→「스케줄러」에서 작업을 열고 스크립트의 패키지를 15.10 의 것으로 변경하십시오. + +:: + + return new org.codelibs.fess.job.IndexExportJob().query(org.codelibs.fesen.opensearch.index.query.QueryBuilders.matchAllQuery()).execute() + +직접 작성한 스크립트에서 ``org.opensearch.index.query`` 를 참조하는 경우에도 같은 방식으로 +변경하십시오. 쿼리 예는 :doc:`../config/admin-index-export` 를 참조하십시오. + +.. _upgrade-159-carried-over-config: + +15.8 에서 이어받은 설정 파일 +---------------------------- + +단계 3의 ZIP 버전 절차에서는 이전 설치의 ``fess_config.properties`` 와 ``bin/fess.in.sh`` 를 +복사합니다. RPM 버전 업그레이드에서는 변경한 ``/etc/fess/fess_config.properties`` 가 그대로 +남습니다(15.10 의 파일은 ``fess_config.properties.rpmnew`` 로 함께 배치됩니다). DEB 버전 업그레이드도 +확인에서 자신의 파일을 유지한 경우에는 마찬가지입니다(15.10 의 파일은 +``fess_config.properties.dpkg-dist`` 로 함께 배치됩니다). 어느 경우든 15.10 는 15.8 의 값으로 +동작하며, 15.10 에서 기본 제공 값이 바뀐 키도 예외가 아닙니다. 적어도 다음 키를 확인하십시오. + +.. list-table:: + :header-rows: 1 + + * - 키 + - 15.8.0 + - 15.10 + - 15.8 의 값이 남은 경우의 영향 + * - ``job.default.script`` + - ``groovy`` + - ``javascript`` + - 관리 화면 「시스템」→「스케줄러」에서 만드는 작업의 기본값이 ``groovy`` 가 되며, + ``fess-script-groovy`` 플러그인이 없으면 실패합니다. + * - ``job.template.script`` + - ``as String[]`` 를 포함한 Groovy 형식 + - JavaScript 형식 + - 크롤링 설정에서 만든 작업의 스크립트가 Groovy 형식이 됩니다. + * - ``crawler.file.protocols`` + - ``file,smb,smb1,ftp,storage,s3,gcs`` + - ``file,smb,smb1,ftp`` + - ``s3:`` 나 ``gcs:`` 로 시작하는 경로가 플러그인이 없어도 허용되며, 크롤링할 때 경고를 + 남기고 처리되지 않습니다. ``storage`` 는 더 이상 지원되지 않습니다. + * - ``search_engine.http.url`` + - ``http://localhost:9201`` + - ``http://localhost:9200`` + - ``SEARCH_ENGINE_HTTP_URL`` 이 설정되지 않은 경우에 사용됩니다. 15.8 에서 복사한 + ``bin/fess.in.sh`` 에서 설정하지 않았다면 여기에 해당하며, |Fess| 는 15.10 에서 폐지된 + 내장 OpenSearch 의 포트인 9201 에서 OpenSearch 를 찾습니다. + * - ``jvm.crawler.options``, ``jvm.thumbnail.options`` + - ``-Djcifs.smb.client.*``, ``-Djcifs.smb1.smb.client.*`` + - ``-Djcifs.client.*`` + - SMB 타임아웃이 jcifs 의 기본값 그대로 남습니다. :ref:`upgrade-159-jcifs` 를 참조하십시오. + * - ``response.headers`` + - ``text/html=Content-Security-Policy: reflected-xss block`` 행이 있음 + - 해당 행 삭제됨 + - 로그인 화면, 관리 화면 등 |Fess| 가 직접 렌더링하는 페이지의 응답에 어떤 브라우저도 인식하지 + 못하는 ``Content-Security-Policy: reflected-xss block`` 헤더가 붙고, 브라우저 콘솔에 + ``Unrecognized Content-Security-Policy directive 'reflected-xss'`` 가 출력됩니다. 이 헤더는 + 아무것도 제한하지 않습니다. 아래 설명대로 해당 행을 제거하십시오. + * - ``app.encrypt.property.pattern`` + - ``.*password|.*key|.*token|.*secret`` + - ``.*password|.*passphrase|.*key|.*token|.*secret`` + - 이름이 ``passphrase`` 로 끝나는 파라미터(예: 데이터스토어 설정의 ``ssh.passphrase``)가 + 평문으로 저장됩니다. 이미 저장된 값은 15.10 의 패턴으로 설정을 다시 저장할 때까지 평문 그대로입니다. + * - ``index.backup.log.targets`` + - ``click_log.ndjson,favorite_log.ndjson,search_log.ndjson,user_info.ndjson`` + - ``chat_log.ndjson,click_log.ndjson,favorite_log.ndjson,search_log.ndjson,user_info.ndjson`` + - 「시스템 정보」→「백업」 페이지에 ``chat_log.ndjson`` 이 표시되지 않습니다. + * - ``index.export.exclude.fields`` + - ``cache`` + - ``cache,tag`` + - 사용자 태그를 보관하는 ``tag`` 필드가 Index Export 작업이 기록하는 파일에서 더 이상 + 제외되지 않습니다. + * - ``crawler.default.script``, ``theme.allowed.archive.extensions``, + ``theme.assets.cache.max.age``, ``theme.assets.precompressed``, + ``rag.chat.message.max.length``, ``supported.uploaded.js.extentions``, + ``supported.uploaded.css.extentions``, ``supported.uploaded.media.extentions``, + ``supported.uploaded.files``, ``online.help.name.design`` + - 있음 + - 삭제됨 + - 효과가 없습니다. 제거하십시오. + +15.0 부터 15.8 까지 ``response.headers`` 의 기본 제공 값에는 +``text/html=Content-Security-Policy: reflected-xss block`` 행이 있습니다. ``reflected-xss`` 는 +Content-Security-Policy 초기 초안에 있던 디렉티브로 현재 브라우저는 인식하지 않으므로, 이 헤더는 +아무것도 제한하지 않고 콘솔에 오류만 출력합니다. 15.10 는 기본 제공 값에서 이 행을 삭제했습니다 +(``X-XSS-Protection`` 과 ``X-Frame-Options`` 행은 그대로입니다). 15.8 에서 이어받은 +``response.headers`` 에는 이 행이 남으므로, ``fess_config.properties`` 의 ``response.headers`` 에서 다음 +행만 제거하십시오. 각 행 끝의 ``\n\`` 는 값이 다음 줄로 이어짐을 나타내므로, 행 전체를 삭제하면 +나머지 행은 그대로 사용할 수 있습니다:: + + text/html=Content-Security-Policy: reflected-xss block\n\ + +``response.headers`` 를 ``-Dfess.config.response.headers`` 로 지정하고 있다면, 그 값에서 같은 항목을 +제거하십시오. + +15.8 에서 복사한 ``bin/fess.in.sh`` 에는 15.10 의 파일에 있는 다음 두 가지도 없습니다. 15.10 는 +``SEARCH_ENGINE_HTTP_URL`` 에 ``http://localhost:9200`` 을 설정하지만, 15.8 의 파일은 직접 +설정하지 않는 한 설정되지 않은 상태로 둡니다. 또한 ``bin/fess-setup install nodejs`` 로 설치한 +Node.js 를 찾지 않으므로, ``PLAYWRIGHT_NODEJS_PATH`` 를 직접 설정하지 않는 한 Playwright +플러그인은 Node.js 를 찾을 수 없습니다. + +어느 파일이든 통째로 복사하지 말고, 15.10 에 포함된 파일을 바탕으로 변경한 값을 다시 +적용하십시오. 변경한 값은 ``diff`` 로 확인할 수 있습니다:: + + $ diff /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.10.0/app/WEB-INF/classes/fess_config.properties + $ diff /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.10.0/bin/fess.in.sh + +RPM 버전에서는 같은 방식으로 ``/etc/fess/fess_config.properties`` 와 +``/etc/fess/fess_config.properties.rpmnew`` 를, DEB 버전 업그레이드에서는 +``/etc/fess/fess_config.properties.dpkg-dist`` 를 비교하십시오. 편집하지 않은 +``fess_config.properties`` 는 DEB 버전 업그레이드에서 15.10 의 파일로 교체되므로(단계 3 참조) +15.10 의 값에서 시작합니다. + +``app.cipher.key`` 는 15.10 에서 바뀌지 않았더라도 반드시 이어받아야 하는 값입니다. 웹 인증, +크롤링 설정, 데이터스토어 설정의 파라미터에 저장된 비밀번호와 시크릿을 암호화하는 키이기 +때문입니다. 기본 제공 ``fess_config.properties`` 를 사용했거나 백업을 새 서버에 복원했기 때문에 +새 설치가 그것들을 저장했을 때와 다른 키로 동작하면 복호화할 수 없으며, ``fess-crawler.log`` 에 +``CipherFailureException`` 이 기록되고 그러한 설정을 포함하는 크롤은 아무것도 색인하지 못할 수 +있습니다. + +.. note:: + + |Fess| 15.10 는 웹 인증과 파일 인증의 ``password`` 도 ``app.cipher.key`` 로 암호화하여 저장하므로, 백업의 + ``fess_basic_config.bulk`` 와 ``fess_config.bulk`` 에는 암호화된 값이 포함됩니다. 다른 설치에 복원할 때는 동일한 + ``app.cipher.key`` 를 이어받으십시오. 키가 다르면 이 인증 정보를 사용하는 크롤이 오류로 실패합니다. 15.10 이전에 만든 + 백업에는 평문으로 들어 있으며 그대로 사용할 수 있습니다(:doc:`../admin/backup-guide` 참조). + +.. _upgrade-159-jcifs: + +SMB 타임아웃은 jcifs 3 의 속성 이름을 사용 +------------------------------------------ + +|Fess| 가 SMB 파일 서버를 크롤링할 때 사용하는 jcifs 는 버전 3 에서 속성 이름을 변경했습니다. +``jcifs.smb.client.*`` 는 ``jcifs.client.*`` 가 되었고, SMB1 용의 ``jcifs.smb1.smb.client.*`` +도 같은 속성으로 통합되었습니다. 15.8 까지의 ``jvm.crawler.options`` 와 +``jvm.thumbnail.options`` 는 이전 이름을 전달했고 jcifs 는 이를 읽지 않으므로, SMB 크롤링은 +jcifs 의 기본값으로 동작했습니다. 15.10 는 새 이름을 전달합니다. + +:: + + -Djcifs.client.responseTimeout=30000 + -Djcifs.client.soTimeout=35000 + -Djcifs.client.connTimeout=60000 + -Djcifs.client.sessionTimeout=60000 + +따라서 연결 타임아웃과 세션 타임아웃이 처음으로 적용되어 jcifs 의 기본값인 35초에서 60초로 +늘어납니다. 응답하지 않는 SMB 서버에 대해 크롤링은 최대 60초 동안 기다리게 됩니다. 응답 +타임아웃과 소켓 타임아웃은 jcifs 의 기본값과 같으므로 바뀌지 않습니다. + +이 타임아웃들을 변경했다면 두 옵션 모두에서 이름을 바꾸십시오. 이전 이름으로는 15.8 에서도 +효과가 없었습니다. 15.8 에서 이어받은 ``fess_config.properties`` 에는 이전 이름이 남아 jcifs 의 +기본값이 그대로 사용됩니다. + +효과가 없던 네 가지 속성 삭제 +----------------------------- + +다음 키는 ``fess_config.properties`` 에서 삭제되었습니다. |Fess| 는 이 파일에서 이 키들을 읽지 +않았으므로, 이 이름으로 남겨 둔 값은 이전과 마찬가지로 효과가 없습니다. + +- ``theme.allowed.archive.extensions`` +- ``theme.assets.cache.max.age`` +- ``theme.assets.precompressed`` +- ``rag.chat.message.max.length`` + +``rag.chat.message.max.length`` 가 정하는 상한은 계속 유효하지만 시스템 속성으로 읽힙니다. +:doc:`../config/rag-chat` 에 설명된 대로 ``app/WEB-INF/conf/system.properties`` 또는 +``-Dfess.system.rag.chat.message.max.length`` 로 설정하십시오. + +.. _upgrade-159-static-theme: + +검색 화면이 정적 테마로 변경됨 +------------------------------ + +다른 테마를 선택하지 않는 한, 검색 화면은 |Fess| 에 번들된 정적 테마 ``bootstrap`` 으로 제공됩니다. +이는 ``/``, ``/search``, ``/advance``, ``/help``, ``/profile``, ``/cache``, ``/chat`` 및 오류 +페이지에 적용됩니다. 15.8 까지는 기본 테마를 설정하지 않으면 이 페이지들은 JSP 였습니다. + +이 전환은 업그레이드 시에도 일어납니다. 기본 테마를 한 번도 설정하지 않은 15.8 환경에는 +``system.properties`` 에 ``theme.default`` 가 없으므로, 업그레이드 후에는 정적 테마가 표시됩니다. +설정에 아무것도 기록되지 않으며 로그도 출력되지 않습니다. JSP 검색 화면으로 되돌리는 설정은 +없습니다. 15.8 에서 기본 테마를 설정했다면 그 설정은 유지됩니다. 해당 테마의 15.10 용 빌드를 +설치하십시오( ``bin/fess-setup install theme `` ). 설치되지 않은 테마를 지정한 기본값은 +``fess.log`` 에 경고를 남기고 ``bootstrap`` 으로 대체되기 때문입니다. + +관리 화면의 「페이지 디자인」이나 JAR 테마 플러그인으로 검색 화면의 JSP, CSS, 이미지를 변경했다면 +그 변경은 더 이상 표시되지 않습니다. 정적 테마에서 변경하십시오. :ref:`theme-customize-bundled` 에 +설명된 대로 번들 테마를 복사하여 그 복사본을 변경하거나, 관리 화면의 「시스템」 > 「테마」 또는 +``bin/fess-setup install theme `` 으로 공개된 테마를 설치합니다. 가상 호스트별 외관은 이제 +가상 호스트 이름을 딴 정적 테마로 제공됩니다. :doc:`../config/security-virtual-host` 를 +참조하십시오. + +다음 2가지도 없어졌습니다. + +- 가상 호스트별 로그인 화면. 15.8 까지는 「시스템」 > 「일반」을 저장하면 로그인 화면을 포함한 + JSP 가 ``WEB-INF/view/<가상 호스트 이름>/`` 에 복사되어, 가상 호스트별로 편집할 수 있었습니다. + 15.10 는 이 복사본을 만들지 않습니다. 로그인 화면( ``/login/`` )은 여전히 JSP 이지만, 모든 가상 + 호스트에서 공통인 ``WEB-INF/view/admin/login/`` 의 것이 표시됩니다. 이전에 복사된 JSP 는 + 사용되지 않습니다. +- JAR 테마 플러그인( ``fess-theme-*`` ). 설치해도 종류 ``jar`` 의 범용 JAR 로 놓일 뿐이며, + 화면은 바뀌지 않습니다. 남아 있는 JAR 는 「시스템」 > 「플러그인」 페이지, 또는 + ``bin/fess-setup remove plugin `` 으로 삭제할 수 있습니다( :doc:`../dev/theme-development` 참조). + +15.8 에서 JSP 검색 결과에 독자적인 필드를 표시하고 있었다면, ``query.additional.response.fields`` +에 더해 ``query.additional.api.response.fields`` 에도 같은 필드를 추가하십시오. 정적 테마는 +검색 결과를 ``/api/v2/search`` 에서 가져옵니다. ``query.additional.response.fields`` 는 검색 엔진에서 +가져오는 필드를 추가할 뿐이며, 이 API 가 응답에 포함하는 것은 ``query.additional.api.response.fields`` +에 나열된 필드뿐입니다( :doc:`../config/search-advanced` 참조). 그 필드를 표시하도록 테마도 +변경하십시오. + +클라이언트에서 보이는 변화 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +오류는 이제 요청한 URL 에서 실제 HTTP 상태와 함께 그 자리에서 표시됩니다. 브라우저( ``Accept`` +헤더에 ``text/html`` 을 포함하는 요청)는 테마의 오류 페이지를 받고, 그 외의 클라이언트는 한 줄의 +``text/plain`` 본문(예: ``404`` 의 경우 ``Not Found.`` )을 받습니다. 15.8 까지는 대부분의 오류가 +``/error/...`` 페이지로의 ``302`` 리디렉트로 응답했고, 그 페이지 자체는 ``200`` 을 반환했습니다. +모니터링, 헬스 체크, 그리고 ``Location`` 헤더를 따라가거나 ``/error/`` URL 을 기대하는 +클라이언트를 점검하십시오. + +.. list-table:: + :header-rows: 1 + + * - 요청 + - 15.8 까지 + - 15.10 + * - 파라미터가 없거나 존재하지 않는 문서에 대한 ``/go/`` + - ``200``, 또는 ``/error/`` 로의 ``302`` + - ``400`` 또는 ``404`` + * - 파라미터가 없거나, 알 수 없는 문서이거나, 썸네일이 없는 ``/thumbnail/`` + - ``200`` 또는 ``302`` + - ``400`` 또는 ``404`` + * - 설정된 SSO 유형이 처리하지 않는 경우의 ``/sso/metadata`` 와 ``/sso/logout`` + - ``/error/badrequest/`` 로의 ``302`` + - ``400`` + * - ``/api/v1/*``, ``/json`` 및 알 수 없는 모든 URL + - ``/error/notfound/`` 로의 ``302`` + - ``404`` + * - 관리 API 를 포함하여 포착되지 않은 예외 + - ``/error/systemerror/`` 로의 ``302`` + - 본문이 ``System Error.`` 인 ``500`` (JSON 아님) + * - ``/error/notfound/``, ``/error/badrequest/``, ``/error/systemerror/`` 자체 + - ``200`` + - ``404``, ``400``, ``500`` + +``login.required=true`` 인 경우, 검색 페이지는 더 이상 익명 사용자를 리디렉트하지 않습니다. 테마와 +함께 ``200`` 을 반환하고 테마가 사용자에게 로그인을 요청하며, 대신 그 뒤의 데이터가 거부됩니다. +``/health``, ``/auth/*``, ``/ui/config`` 이외의 모든 ``/api/v2/`` 엔드포인트는 ``/api/v2/search`` +를 포함하여 사용자가 로그인할 때까지 ``401`` 을 반환합니다. ``/go/``, ``/thumbnail/``, ``/osdd`` 는 +여전히 로그인으로 리디렉트합니다. ``/`` 에 대한 익명 요청이 리디렉트될 것을 기대하는 점검은 +대신 ``/api/v2/search`` 가 ``401`` 을 반환하는지 확인해야 합니다. + +검색 화면은 ``/api/v2/search`` 를 통해 검색하므로, 검색은 ``/search`` 가 요청될 때가 아니라 이 +API 가 호출될 때 로그에 기록됩니다. JavaScript 를 실행하지 않는 클라이언트는 결과가 없는 페이지를 +받습니다. + +검색 화면의 HTML 에는 ``X-Frame-Options: DENY`` 와 ``frame-ancestors 'none'`` 을 포함하는 ``Content-Security-Policy`` 가 +붙으므로, 다른 페이지의 프레임에 표시되지 않습니다. 15.8 의 JSP 검색 화면은 ``response.headers`` 의 기본값에 따라 +``X-Frame-Options: SAMEORIGIN`` 을 보냈고, 같은 오리진 페이지의 ``iframe`` 에 표시할 수 있었습니다. 검색 화면을 같은 오리진의 ``iframe`` 에 +포함하고 있었다면 ``fess_config.properties`` 의 ``theme.index.frame.ancestors`` (기본값 ``'none'`` )를 ``'self'`` 로 +설정하십시오. 다른 오리진에서 포함하려면 그 오리진을 지정하십시오 (:doc:`../dev/theme-development` 참조). + +관리 화면의 「페이지 디자인」 삭제 +---------------------------------- + +관리 화면의 [시스템 > 페이지 디자인] 을 삭제했습니다. 검색 화면의 JSP, CSS, 이미지를 관리 화면에서 +편집할 수 없습니다. 검색 화면의 모양은 정적 테마로 변경하십시오 (:ref:`theme-customize-bundled` +참조). + +다음 키도 ``fess_config.properties`` 에서 삭제되었습니다. 이 이름으로 남겨 둔 값은 사용되지 않습니다. + +- ``supported.uploaded.js.extentions`` +- ``supported.uploaded.css.extentions`` +- ``supported.uploaded.media.extentions`` +- ``supported.uploaded.files`` +- ``online.help.name.design`` + +``admin-design`` 과 ``admin-design-view`` 롤은 더 이상 아무 권한도 부여하지 않습니다. 이 롤만 가진 +사용자는 로그인하면 관리 화면이 아니라 검색 화면으로 이동합니다. + +``api.access.token.required`` 삭제 +---------------------------------- + +``api.access.token.required`` 는 ``fess_config.properties`` 에서 삭제되었습니다. 15.8 에서 가져온 +``fess_config.properties`` 에 남아 있는 경우를 포함하여, 이 이름의 값은 효과가 없습니다. ``true`` 로 +설정하면 로그인하지 않은 사용자의 API 요청을 모두 거부했습니다. 이제 검색 화면은 ``/api/v2/search`` 로 +검색하므로, 이 설정은 익명 사용자에게 결과가 없는 검색 화면을 보여 주게 됩니다. + +``true`` 로 설정했던 환경에서는 이제 익명 사용자의 API 요청에도 검색 화면과 마찬가지로 게스트 롤로 +응답합니다. 익명 사용자가 검색하지 못하게 하려면 ``login.required=true`` 를 설정하십시오. 액세스 토큰의 +동작은 변경되지 않았습니다. 등록된 액세스 토큰이 있는 요청에는 해당 토큰의 권한이 부여되고, 등록되지 +않았거나 만료된 토큰이 있는 요청은 거부됩니다. + +.. _upgrade-159-api-requests: + +API 가 거부하게 된 요청 +----------------------- + +15.8 에서는 받아들여졌던 다음 요청을 15.10 는 거부합니다. 15.8 용으로 만든 클라이언트와 스크립트가 이러한 요청을 보내고 있지 않은지 확인하십시오. 관리 API 는 거부를 HTTP +``400`` 으로 응답하며, 본문의 ``status`` 는 ``1`` 입니다. + +.. list-table:: + :header-rows: 1 + + * - 요청 + - 15.8 까지 + - 15.10 + * - ``facet.field`` 또는 ``facet.query`` 와 함께 ``/api/v2/search`` 에 ``0`` 이하의 ``facet.size`` 를 지정하거나, 정수가 아닌 ``facet.size`` 또는 ``facet.minDocCount`` 를 지정 + - ``200``. 다만 ``record_count`` 가 ``0`` 이고 ``partial`` 이 ``true`` 인 빈 결과 + - ``400`` (``invalid_request``). ``facet.size`` 는 ``1`` 이상이어야 합니다 + * - ``track_total_hits=false`` 지정. ``query.track.total.hits`` 를 ``false`` 로 설정한 경우에는 모든 검색이 대상입니다 + - ``200``. 다만 검색 결과가 0건 + - 검색이 거부됩니다 (``/api/v2/search`` 는 ``400`` 과 ``invalid_request``). ``true`` 와 양의 정수는 종전과 같습니다 + * - 관리 API 로 ``mapping`` 또는 ``kuromoji`` 사전에, 이미 있는 항목과 중복되는 항목을 등록하거나 갱신 + - 저장됩니다. 이후 사전을 읽어 들일 때 실패하여 검색을 할 수 없게 될 수 있습니다 + - ``400`` + * - 관리 API 로 ``kuromoji`` 사전에, ``token`` 에 공백이 포함된 항목이나 ``segmentation`` 과 ``reading`` 의 공백으로 구분한 단어 수가 다른 항목을 등록하거나 갱신 + - 저장됩니다. 위와 마찬가지로 사전을 읽어 들일 때 실패합니다 + - ``400`` + * - ``DELETE /api/admin/searchlist/doc/{doc_id}`` 에서 아무것도 삭제되지 않은 경우 (존재하지 않는 ``doc_id`` , 또는 문서 목록이 반환하는 ``_id`` 처럼 ``doc_id`` 가 아닌 값) + - ``200`` (``status`` 는 ``0``). 문서는 삭제되지 않습니다 + - ``400`` + * - 관리 API 사용자의 ``roles`` 또는 ``groups`` 에 롤 이름이나 그룹 이름을 지정 + - 저장되지만 지정한 이름은 롤로 동작하지 않습니다. 이름에 따라서는 그 사용자를 읽지 못합니다 + - ``400``. 롤이나 그룹의 ID (``GET /api/admin/role/settings`` 와 ``GET /api/admin/group/settings`` 의 ``id`` )를 지정하십시오 + * - 관리 API 로 사용자에게 비밀번호 정책(``password.min.length`` 의 기본값 ``8`` 등)에 어긋나는 비밀번호를 설정, 생성 시 비밀번호를 생략, 또는 ``password`` 와 일치하지 않는 ``confirm_password`` 를 전송 + - 저장되며, 그 비밀번호로 로그인할 수 있습니다 + - ``400`` + +``/api/v2/documents/all`` 의 각 행에서 ``score`` 가 없어졌습니다. 15.8 까지는 각 문서에 검색 점수가 붙었지만, 15.10 는 전체 결과를 point in +time 과 ``search_after`` 로 가져오므로 점수가 붙지 않습니다. 구 API 플러그인의 ``/json?type=scroll`` 과 ``/api/v1/documents/all`` 도 +마찬가지입니다. ``score`` 를 읽는 스크립트는 값이 없는 경우를 처리할 수 있어야 합니다. + +관리 API 의 파일 업로드(사전 6종, ``badword``, ``elevateword``, ``storage``)는 ``POST`` 로 받습니다. 15.8 의 문서는 ``PUT`` 을 +안내했지만, ``multipart/form-data`` 의 ``PUT`` 으로는 파일이 전달되지 않아 15.8 에서도 15.10 에서도 파일이 필요하다는 검증 오류가 됩니다. ``PUT`` +엔드포인트는 남아 있지만, 업로드에는 ``POST`` 를 사용하십시오. + +``search_engine.type`` 의 ``cloud`` 는 사용 중단 예정 +----------------------------------------------------- + +15.10 에서는 CodeLibs 플러그인이 없는 순정 OpenSearch 용으로 ``search_engine.type`` 의 값 ``vanilla`` 가 추가되었습니다( :doc:`../config/search-engine-type` 참조). ``cloud`` 는 ``vanilla`` 의 사용 중단 예정 별칭이 되었습니다. 계속 동작하지만 시작할 때 경고를 로그에 출력합니다. 15.10 로 운영하게 되면 ``vanilla`` 로 변경하십시오. ``aws`` 는 이전과 같이 동작합니다. + +* ``vanilla`` 는 15.10 이상에서 사용할 수 있습니다. 15.8 이전의 |Fess| 는 이 값을 인식하지 못합니다. 15.8 로 되돌릴 가능성이 있는 동안에는 ``cloud`` 를 그대로 두십시오. +* ``aws`` 와 ``cloud`` 의 인덱스 정의는 ``fess_indices/_vanilla/`` 에서 읽어 들입니다. 동봉되어 있던 ``fess_indices/_aws/`` 와 ``fess_indices/_cloud/`` 는 없어졌으며, 직접 추가한 ``fess_indices/_aws/`` 또는 ``fess_indices/_cloud/`` 는 더 이상 읽지 않으므로 변경 내용을 ``fess_indices/_vanilla/`` 로 옮기십시오. 이미 만들어진 인덱스는 변경되지 않습니다. +* 15.8 이 검색 엔진에 저장한 추천 단어(Suggest) 설정은 자동으로 마이그레이션됩니다. 별도의 조치는 필요하지 않습니다. + +CSV 데이터스토어가 인용 부호로 감싼 필드를 해석 +----------------------------------------------- + +15.10 의 ``fess-ds-csv`` 플러그인은 기본적으로 인용 부호를 해석합니다. ``"Yamada, Taro"`` 와 같은 +필드는 하나의 열이 되며, 15.8.0 의 플러그인은 이를 쉼표 위치에서 분할했습니다. +``bin/fess-setup upgrade plugins`` 실행 후에는 인용 부호로 감싼 필드가 있는 CSV 파일을 읽는 +데이터스토어 설정을 확인하십시오. 15.8 의 동작을 유지하려면 「파라미터」에 +``quote_disabled=true`` 를 추가하십시오. 짝이 맞지 않는 인용 부호의 동작도 포함하여 +:doc:`../config/datastore/ds-csv` 를 참조하십시오. + +.. _upgrade-reindex-new-fields: + +기존 문서 인덱스에 새 필드와 가나 정규화 반영 +--------------------------------------------- + +15.10는 시작할 때 설정·로그·사용자 인덱스에 새 필드를 추가합니다. 문서 인덱스에 추가하는 것은 +사용자 태그를 보관하는 ``tag`` 필드(``keyword``)뿐이며, 매핑의 나머지 부분과 분석 설정은 변경하지 +않습니다. 15.8 이전에 생성한 문서 인덱스를 그대로 사용하면 다음 15.10 변경 사항이 적용되지 +않습니다. + +- **파일의 소유자와 최종 수정자** (``owner``, ``last_modifier``): 파일 시스템·SMB·FTP 크롤에서 새로 + 색인되는 필드입니다. 기존 문서 인덱스에는 정의가 없으므로 처음 크롤한 값에 따라 ``text`` 형으로 + 자동 매핑되어, ``owner:alice`` 와 같은 검색이나 ``facet.field=owner`` 가 의도대로 동작하지 않습니다. +- **ETag** (``etag``): 크롤러가 크롤한 페이지의 ETag 를 저장하는 필드로, 15.10 는 이를 + ``If-None-Match`` 로 다시 보내 변경되지 않은 페이지를 다시 가져오지 않습니다. 기존 문서 + 인덱스에는 이 필드의 정의도 없으므로, 기본 제공되는 색인하지 않는 ``keyword`` 가 아니라 + ``text`` 형으로 자동 매핑됩니다. 이 매핑으로도 조건부 요청은 동작합니다. +- **가나 표기 차이와 장음 기호 대신 쓰인 대시의 정규화** (예: ``サ―バ－`` 를 ``サーバー`` 와 같은 + 단어로 취급): 규칙이 문서 인덱스의 분석 설정과 사전 ``mapping.txt`` 에 있으므로 기존 인덱스에는 + 반영되지 않습니다. + +두 가지를 모두 반영하려면 관리 화면의 「시스템 정보」→「유지보수」에서 「에일리어스 갱신」과 +「사전 초기화」를 활성화하고 「재인덱싱」을 실행합니다. 재인덱싱은 기존 문서를 새 인덱스로 복사하므로 +다시 크롤할 필요가 없습니다. + +.. warning:: + + 「사전 초기화」는 동봉된 사전 파일로 OpenSearch 측 사전을 덮어씁니다. 관리 화면의 「사전」에서 + 동의어 등을 편집한 경우에는 미리 다운로드해 두고, 재인덱싱 후에 다시 반영하십시오. 다운로드한 + 파일에서 중복되거나 잘못된 항목을 삭제하고(단계 7 참조) 업로드한 다음, 「시스템 정보」→「유지보수」의 + 「문서 인덱스 다시 로드」에서 [다시 로드]를 클릭하십시오. 그렇게 하기 전까지는 문서 인덱스의 + 분석기가 기본 제공 사전을 계속 사용하므로, 복원한 동의어는 아무리 기다려도 일치하지 않습니다. + 색인 시에 적용되는 사전은 문서를 다시 크롤해야 하기도 합니다. :ref:`dict-apply-changes` 를 + 참조하십시오. + +.. note:: + + 15.8 이전에 색인된 파일에는 소유자와 최종 수정자 값이 없습니다. 차분 크롤에서는 변경되지 않은 + 파일을 다시 가져오지 않으므로, 값을 추가하려면 「시스템」→「일반」의 「최종 갱신 일시 확인」을 + 일시적으로 비활성화하고 크롤하십시오. + + +15.10 전용 마이그레이션 작업 +=========================== + +15.7 이전 버전에서 15.10로 업그레이드하는 경우, 사용 중인 기능에 따라 다음 작업이 필요합니다. + +시맨틱 검색을 사용하고 있었던 경우 +---------------------------------- + +15.7 이전에 시맨틱 검색을 제공하던 ``fess-webapp-semantic-search`` 플러그인은 +15.10에서 코어로 통합되어 불필요해졌습니다(사용 중단). 플러그인 제거, ``-Dfess.semantic_search.*`` +및 ``-Drank.fusion.searchers=default,semantic`` 의 제거, 기존 인제스트 파이프라인 분리가 +필요합니다. 절차는 :ref:`semantic-search-migration` (:doc:`../config/search-semantic`)를 +참조하십시오. + +AI 검색 모드(RAG 채팅)를 사용하고 있었던 경우 +--------------------------------------------- + +15.10부터 AI 검색 모드(RAG 채팅) 기능은 ``fess-llm-ollama``, ``fess-llm-openai``, +``fess-llm-gemini`` 등의 플러그인으로 분리되었습니다. 사용 중인 프로바이더에 대응하는 +플러그인을 관리 화면 「시스템」→「플러그인」에서 설치하십시오. 15.10에서는 Amazon Bedrock용 +``fess-llm-bedrock`` 도 추가되었습니다. + +SPNEGO(Windows 통합 인증)를 사용하고 있었던 경우 +------------------------------------------------ + +15.10부터 클라이언트 주체의 Kerberos 영역이 서버의 영역과 다르면 SPNEGO 로그인이 거부됩니다. +AD 도메인 트리의 하위 도메인이나 신뢰 관계를 맺은 포리스트의 사용자가 로그인하는 구성에서는 +관리 화면 「시스템」→「일반」 또는 ``app/WEB-INF/conf/system.properties`` 의 +``spnego.allowed.realms`` 에 해당 영역을 쉼표로 구분하여 나열하십시오. 나열하지 않으면 +15.7까지 로그인할 수 있었던 사용자가 ``Kerberos realm is not allowed`` 로 거부됩니다. +자세한 내용은 :doc:`../config/sso-spnego` 를 참조하십시오. + +또한 15.10에서는 ``spnego.allow.unsecure.basic`` 과 ``spnego.allow.localhost`` 의 코드상 기본값이 +``true`` 에서 ``false`` 로 변경되었습니다. 이 키들이 ``app/WEB-INF/conf/system.properties`` 에 +없는 환경에서는 업그레이드와 함께 더 엄격한 동작이 적용됩니다. 특히 +``spnego.allow.unsecure.basic=false`` 인 경우 SPNEGO 라이브러리는 ``HttpServletRequest#isSecure()`` +가 ``true`` 를 반환하는 요청에만 Basic 인증을 제공하므로, 리버스 프록시에서 TLS를 종료하고 HTTP로 +전달하는 구성에서는 지금까지 Basic 인증으로 대체하던 클라이언트가 로그인할 수 없게 됩니다. +이 경우 ``tomcat_config.properties`` 에서 ``tomcat.secure=true`` 를 설정하십시오. +자세한 내용은 :doc:`../config/sso-spnego` 를 참조하십시오. + +.. warning:: + + 코드상의 기본값은 키가 없는 경우에만 적용되며, 관리 화면 「시스템」→「일반」은 저장할 때마다 + 모든 ``spnego.*`` 키를 기록합니다. 따라서 15.7에서 이 화면으로 한 번이라도 갱신한 환경에는 + ``spnego.allow.unsecure.basic=true`` 와 ``spnego.allow.localhost=true`` 가 저장된 채로 남아 + 있으며, 15.10로 업그레이드해도 설정은 강화되지 않습니다. 느슨한 동작이 조용히 유지되고, 15.10은 + SPNEGO 초기화 시 ``fess.log`` 에 경고를 기록할 뿐입니다. 관리 화면 「시스템」→「일반」 또는 + ``system.properties`` 에서 두 가지를 모두 명시적으로 비활성화하십시오. 특히 + ``spnego.allow.localhost=true`` 는 위험합니다. SPNEGO 라이브러리가 동일 호스트에서 온 요청을 + Kerberos 검증 없이 서버의 OS 사용자로 인증하므로, 동일 호스트에 리버스 프록시를 두는 구성에서는 + 안전하지 않습니다. + +.. _upgrade-159-saml: + +SAML 인증(SSO)을 사용하고 있었던 경우 +------------------------------------- + +15.10부터 |Fess| 는 전송한 AuthnRequest의 ID와 SAML 응답을 대응시켜 검증하므로 +IdP-Initiated(미요청·unsolicited) SSO는 동작하지 않습니다. IdP 포털(Okta 대시보드나 +Microsoft Entra ID의 「내 앱」 등)에 배치한 타일에서 시작한 로그인은 대응시킬 AuthnRequest가 +없어 거부됩니다. 15.7까지는 |Fess| 가 대응시키지 못한 응답을 IdP로 되돌려 보내고, IdP가 즉시 +SP-Initiated 어서션을 반환했기 때문에 동작했습니다. IdP 측에 타일을 배치하는 경우에는 링크 +대상을 |Fess| 의 ``/sso/`` 로 지정하여 SP-Initiated 로그인이 되도록 하십시오. + +또한 IdP는 어서션을 크로스 사이트 POST로 반환하므로 ``tomcat_config.properties`` 의 +``tomcat.sameSiteCookies`` 를 ``none`` 으로 설정해야 합니다. 포함된 기본값 ``lax`` 그대로는 +세션 쿠키가 이 요청에 전송되지 않아 SAML 로그인을 완료할 수 없습니다. 이 파일은 ZIP 패키지에서는 +``lib/classes/`` , DEB/RPM 패키지에서는 ``/etc/fess/`` 에 있으며, 변경 후에는 |Fess| 를 +재시작해야 합니다. 브라우저는 ``Secure`` 속성이 함께 있는 쿠키에 대해서만 ``none`` 을 +허용하므로 |Fess| 를 HTTPS로 제공해야 합니다. 15.7까지는 같은 설정 오류가 명확한 오류가 아니라 +IdP로의 무한 리다이렉트 루프로 나타났으므로, 동작하는 것처럼 보였던 사이트에서도 설정을 +확인하십시오. 15.10에서는 루프에 빠지지 않고 한 번에 실패합니다. +자세한 내용은 :doc:`../config/sso-saml` 을 참조하십시오. + +Microsoft Entra ID(Azure AD)를 사용하고 있었던 경우 +--------------------------------------------------- + +15.10부터 인가 엔드포인트에 요청하는 응답 모드의 기본값이 ``form_post`` 에서 ``query`` 로 +변경되었습니다. 15.7까지는 콜백이 교차 사이트 POST로 반환되므로, |Fess| 의 기본값인 +``tomcat.sameSiteCookies = lax`` 에서는 세션 쿠키가 전송되지 않아 ``none`` 으로 변경해야 +했습니다. 이 회피책만을 위해 ``none`` 을 설정했다면 기본값으로 되돌릴 수 있습니다. 기존과 같이 +``form_post`` 를 사용하려면 ``entraid.response.mode=form_post`` 를 지정하고 +``tomcat.sameSiteCookies = none`` 을 유지하십시오. 브라우저는 ``Secure`` 속성이 함께 있는 쿠키에 +대해서만 ``none`` 을 허용하므로, 이 경우에도 |Fess| 를 HTTPS로 제공해야 합니다. + +또한 15.10부터 |Fess| 는 로그인이 완료된 후 백그라운드에서 사용자의 그룹·역할 소속을 해결하며, +로그인이 Microsoft Graph의 응답을 기다리다 멈추는 일은 없어졌습니다. 해결이 완료될 때까지, 또는 +해결이 완전히 성공하지 못한 경우 사용자가 보유하는 것은 사용자 본인의 사용자 수준 권한과 +``entraid.default.groups`` 및 ``entraid.default.roles`` 에 설정한 그룹·역할뿐입니다. 둘 다 +설정하지 않은 경우（기본 제공 설정값）, 이 시간대의 검색은 한 건도 결과가 나오지 않습니다. +기본 제공 설정값 그대로 만든 크롤 설정으로 크롤링한 문서에는 ``{role}guest`` 가 부여되지만, +로그인한 사용자는 이 역할을 갖고 있지 않기 때문입니다. 해결이 진행되는 동안에는 검색 화면에 +그 사실을 알리는 메시지가 표시되며, 완전히 성공하지 못한 경우에는 별도의 메시지가 표시됩니다 +（직접 소속 조회와 중첩 그룹 탐색이 모두 성공하지 않는 한 해결은 실패로 처리됩니다）. +액세스 토큰이 갱신될 때마다 해결이 다시 실행되고, 그 후 성공하면 메시지는 사라지므로, 토큰 유효 기간을 넘겨 이어지는 세션에서는 실패가 최종적인 +것이 되지는 않습니다. 바로 다시 시도하려면 일단 로그아웃한 후 다시 로그인하십시오. +자세한 내용은 :doc:`../config/sso-entraid` 를 참조하십시오. + +백그라운드에서 해결하기 때문에 생기는 영향으로, 해결이 완료될 때까지는 해결된 +역할을 아직 알 수 없습니다. 그래서 관리자는 관리 대시보드가 아니라 검색 화면으로 리다이렉트되며, +그 사이에 관리 화면을 열어도 검색 화면으로 되돌아옵니다. 이 시간대는 최대 약 1초의 스케줄링 +지연에 더해 Microsoft Graph 호출 자체（직접 소속 조회 1회, 여기에 중첩 그룹을 따라가기 위해 +직접 소속 그룹마다 1회씩 순차 실행. 캐시가 없는 경우）가 걸리므로, 사용자가 소속된 그룹 수에 +따라 길어집니다. 이 시간대에 접근이 허용되는 일은 없고 거부될 뿐이며, +이 시간대를 넘기기 위한 설정은 필요하지 않습니다. 인가는 같은 세션의 요청마다 +다시 평가되므로, 해결이 완료된 후에 다시 열면 다시 로그인하지 않아도 관리 화면에 정상적으로 +접근할 수 있습니다. + +.. warning:: + + 이 시간대를 줄이기 위해 |Fess| 의 관리자 역할을 ``entraid.default.roles`` 에 설정해서는 + 안 됩니다. 이 속성은 단일 전역 설정으로, |Fess| 는 로그인 시 모든 Entra ID 사용자에게 이를 + 적용하고 이후의 해결 때마다 다시 적용하므로, 테넌트의 모든 사용자에게 영구적인 |Fess| + 관리자 권한을 부여하게 됩니다. + +LDAP / Active Directory 연동을 사용하던 경우 +--------------------------------------------- + +15.10부터 그룹과 롤의 권한 이름은 엔트리의 DN을 텍스트로 잘라낸 값이 아니라 RDN으로 해석한 값이 +됩니다. DN 안에서 이스케이프되는 문자(일반적으로 쉼표)를 CN에 포함하는 그룹은 15.7까지와 다른 +권한 이름을 갖게 됩니다. + +.. list-table:: + :header-rows: 1 + + * - 그룹 엔트리의 DN + - 15.7까지의 권한 이름 + - 15.10의 권한 이름 + * - ``CN=Sales\, EMEA,CN=Users,...`` + - ``2Sales`` + - ``2Sales, EMEA`` + * - ``CN=Sales\, APAC,CN=Users,...`` + - ``2Sales`` + - ``2Sales, APAC`` + +15.7까지는 쉼표 앞부분이 일치하는 여러 그룹이 같은 권한 이름으로 합쳐졌기 때문에, +``Sales, EMEA``\ 와 ``Sales, APAC``\ 의 소속자는 서로의 문서와 ``Sales`` 그룹의 문서를 읽을 수 +있었습니다. 15.10에서는 각각 다른 권한 이름이 되어 이러한 그룹 간 접근은 발생하지 않습니다. + +그 대신 **기존 권한 이름으로 색인된 문서는 해당 그룹의 사용자에게 보이지 않게 됩니다**\ . +크롤 설정의 「퍼미션」에 기존 권한 이름을 설정했다면 새로운 권한 이름으로 변경한 뒤 다시 크롤 +(또는 재색인)하십시오. CN에 쉼표 등을 포함하는 그룹을 사용하지 않는다면 권한 이름은 바뀌지 않습니다. + +``ldap.role.search.user.enabled`` 의 동작 변경 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +15.7까지는 ``ldap.role.search.user.enabled=false`` 를 설정해도 사용자 이름에서 유도한 권한 +(``role.search.user.prefix`` + 사용자 이름)이 부여되었습니다. 15.10부터는 이 설정이 실제로 +반영되어 ``false`` 인 경우 부여되지 않습니다. + +``false`` 로 설정한 환경에서는 업그레이드 후 사용자가 자신의 권한을 잃게 되므로, 개별 사용자에게 +설정한 권한을 가진 문서를 검색할 수 없게 됩니다. 기존 동작을 유지하려면 기본값인 ``true`` 로 +되돌리십시오. + +/api/v2 설정 키를 변경했던 경우 +------------------------------------------------ + +15.8.0부터 네 개의 설정 키에서 ``api.v2.`` 접두사가 없어졌습니다. 값과 기본값, 동작은 그대로이지만 +**하위 호환을 위한 별칭은 제공되지 않습니다**. 예전 이름 그대로 남겨 둔 설정은 경고 없이 무시되며, +기본으로 포함된 값이 사용됩니다. + +.. list-table:: + :header-rows: 1 + + * - 15.7까지 + - 15.8.0 이후 + - 기본값 + * - ``api.v2.chat.stream.keepalive.interval.ms`` + - ``api.chat.stream.keepalive.interval.ms`` + - ``15000`` + * - ``api.v2.param.max.length`` + - ``api.param.max.length`` + - ``1000`` + * - ``api.v2.param.max.array.size`` + - ``api.param.max.array.size`` + - ``100`` + * - ``api.v2.click.max.rt`` + - ``api.click.max.timestamp`` + - ``9999999999999`` + +``fess_config.properties`` 또는 ``-Dfess.config.<키>`` JVM 인수로 이 키들을 설정했다면 새 이름으로 +변경하십시오. 영향을 받는 것은 명시적으로 설정한 경우뿐이며, 변경한 적이 없는 환경에서는 대응이 +필요하지 않습니다. + +첫 번째 키는 ``POST /api/v2/chat/stream`` 이 모델의 응답을 기다리는 동안 keep-alive 프레임을 보내는 +간격을 정하므로, 설정이 사라진 것은 AI 검색 모드에서 드러납니다. 마지막 키는 정확성을 위해서도 +이름이 바뀌었습니다. 클릭 로그가 가질 수 있는 ``rt`` 값의 상한이며, 응답 시간이 아니라 +타임스탬프를 가리킵니다. + + +.. _upgrade-plugin-versions: + +플러그인 버전 갱신 +------------------------ + +``app/WEB-INF/plugin/`` 에 설치된 플러그인은 |Fess| 버전에 대응하는 +것으로 교체해야 합니다. ``bin/fess-setup upgrade plugins`` 는 설치된 모든 플러그인에 대해 이 +|Fess| 용으로 빌드된 버전을 설치하고 이전 버전을 삭제합니다. 그 후 |Fess| 를 재시작하십시오. +``bin/fess-setup check`` 는 OpenSearch 와 그 플러그인, 설치된 |Fess| 플러그인의 상태를 보고하며, +문제가 있으면 종료 코드 1 로 종료합니다. ``bin/fess.in.sh``, ``/etc/sysconfig/fess``, +``/etc/default/fess`` 는 읽지 않으므로, OpenSearch 가 ``http://localhost:9200`` 에 없는 경우에는 +``--url`` 을 지정하거나 실행하는 셸에서 ``SEARCH_ENGINE_HTTP_URL`` 을 설정하십시오. 그렇지 않으면 +엔진에 연결할 수 없다고 보고합니다. + +:: + + $ bin/fess-setup upgrade plugins + $ bin/fess-setup check + +``upgrade plugins`` 의 대상은 이미 설치된 플러그인뿐입니다. ``fess-script-groovy`` 등 15.10 에서 +배포물에서 빠진 부분을 보완하는 플러그인은 앞의 각 절에 설명된 대로 +``bin/fess-setup install plugin`` 으로 설치하십시오. + +Docker 버전에서 ``FESS_PLUGINS`` 를 지정하는 경우에는 +``fess-ds-wikipedia:15.10.0`` 처럼 버전 부분을 갱신하십시오. + +롤백 절차 +============== + +업그레이드에 실패한 경우 다음 절차로 롤백할 수 있습니다. + +단계 1: 새 버전 중지 +------------------------------ + +:: + + $ sudo systemctl stop fess.service + $ sudo systemctl stop opensearch.service + +단계 2: 이전 버전 복원 +---------------------------- + +백업에서 설정 파일과 데이터를 복원합니다. + +RPM/DEB 버전의 경우:: + + $ sudo rpm -Uvh --oldpackage --nodeps fess-.rpm + +또는:: + + $ sudo dpkg -i fess-.deb + +.. note:: + + RPM 에서는 ``--nodeps`` 가 필요합니다. 15.8.0 패키지는 ``fess`` 와 ``opensearch`` 사용자 및 + 그룹을 필수로 하므로, 지정하지 않으면 ``rpm`` 은 ``Failed dependencies: group(fess) is needed by fess-15.8.0`` + 으로 다운그레이드를 거부합니다. + +.. warning:: + + 15.8.0 의 DEB 패키지는 ``/etc/fess/*`` 를 conffile 로 등록하지 않으므로, ``dpkg -i`` 는 편집한 + ``/etc/fess/fess_config.properties`` 등을 사본을 남기지 않고 덮어씁니다. 단계 1 에서 취득한 + 백업에서 복원하십시오. + +단계 3: 데이터 복원 +---------------------- + +스냅샷에서 복원합니다. OpenSearch 는 실행 중이어야 하고 |Fess| 는 중지되어 있어야 합니다. + +1. OpenSearch 를 시작합니다:: + + $ sudo systemctl start opensearch.service + +2. 스냅샷은 존재하는 인덱스 위에 복원할 수 없으므로, 업그레이드 후에(예를 들어 재인덱싱으로) + 생성된 것과 OpenSearch 플러그인이 생성하는 ``configsync`` 인덱스를 포함하여 Fess 의 인덱스를 + 모두 먼저 삭제합니다. 스냅샷에 포함된 인덱스만 삭제하면 재인덱싱으로 만들어진 인덱스가 남아 + ``fess.search`` 가 두 개의 인덱스를 가리키게 되어 15.8.0 이 시작되지 않습니다:: + + $ curl "http://localhost:9200/_cat/indices/fess*,configsync?h=index" + $ curl -X DELETE "http://localhost:9200/" + + 두 번째 명령은 첫 번째 명령이 표시한 인덱스마다 실행합니다. + +3. 스냅샷을 복원합니다:: + + $ curl -X POST "http://localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true" + +.. note:: + + 사전 디렉터리(``configsync.config_path``, 사전 파일 포함)는 이전과 같이 존재해야 합니다. + 이를 잃어버린 머신에서는 복원은 완료되지만 사전을 사용하는 인덱스가 red 로 남습니다. + +또는 백업에서 디렉터리 복원(단계 1 에서 생성한 아카이브의 이름을 지정합니다):: + + $ sudo systemctl stop opensearch + $ sudo rm -rf /var/lib/opensearch/data/* + $ sudo tar xzf /backup/opensearch-data-.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개입니다. + 검색 로그 등의 ``*.ndjson`` 파일은 받아들여지지 않으며 오류가 됩니다. + +.. warning:: + + ``fess.json`` 과 ``doc.json`` 의 업로드는 |Fess| 에 동봉된 인덱스 정의 + 파일 자체를 덮어씁니다. 업그레이드 후에 이전 버전의 ``fess.json`` 이나 + ``doc.json`` 을 업로드하면 새 버전의 인덱스 설정·매핑이 유실됩니다. + 롤백 목적 이외에는 업로드하지 마십시오. + +.. note:: + + 업로드된 ``system.properties`` 는 메모리에만 로드되며 파일로는 + 기록되지 않습니다. 따라서 ``system.properties`` 의 내용은 |Fess| 를 재시작하면 유실됩니다. + 확실히 복원하려면 백업한 파일을 정해진 위치(ZIP 버전은 + ``app/WEB-INF/conf/``, RPM/DEB 버전은 ``/etc/fess/``)에 직접 배치한 후 시작하십시오. + +.. note:: + + 임포트는 비동기로 실행되며, 화면에는 시작되었다는 내용만 표시됩니다. + 실제로 성공했는지는 ``fess.log`` 를 확인하십시오. + +단계 4: 서비스 시작 및 확인 +---------------------------- + +:: + + $ sudo systemctl start opensearch.service + $ sudo systemctl start fess.service + +동작을 확인하고 정상적으로 복구되었는지 확인합니다. + +자주 묻는 질문 +============== + +Q: 다운타임 없이 업그레이드할 수 있습니까? +-------------------------------------------- + +A: Fess의 업그레이드에는 서비스 중지가 필요합니다. 다운타임을 최소화하려면 다음을 고려하십시오: + +- 사전에 테스트 환경에서 절차를 확인 +- 백업을 사전에 취득 +- 유지보수 시간을 충분히 확보 + +Q: OpenSearch도 업그레이드해야 합니까? +------------------------------------------------- + +A: |Fess| 버전마다 대응하는 OpenSearch 버전이 정해져 있습니다. +|Fess| 15.10은 OpenSearch 3.9.0에 대응합니다. +``opensearch-analysis-fess`` 등의 |Fess| 용 OpenSearch 플러그인은 OpenSearch 버전과 +완전히 일치해야 하므로, OpenSearch를 업그레이드하는 경우 +대응하는 버전(3.9.0)의 플러그인으로 업데이트하십시오. + +또한 |Fess| 15.10은 k-NN 플러그인을 필수로 하며, 인덱스 설정에 ``knn.derived_source.enabled`` +를 항상 전송합니다. 오래된 OpenSearch를 그대로 사용하면 새 인덱스 생성에 실패하므로 +사실상 OpenSearch의 업그레이드가 필요합니다. 자세한 내용은 단계 4를 참조하십시오. + +Q: 인덱스를 재작성해야 합니까? +------------------------------------------ + +A: |Fess| 의 마이너 버전 업그레이드(15.x → 15.10)에서 청크 벡터 검색을 이용하지 않는 경우는 +일반적으로 불필요합니다. 기존 인덱스를 그대로 이용할 수 있으며, ``content_chunker.enabled`` 등은 +기본값이 비활성화이므로 동작은 변하지 않습니다. + +다음의 경우에는 재작성·재인덱싱이 필요합니다. + +- **새로 청크 벡터 검색(시맨틱 검색)을 활성화하는 경우**: 기존 인덱스에는 + 새 매핑이 반영되지 않으므로 재인덱싱이 필수입니다. 자세한 내용은 + :ref:`semantic-search-migration` (:doc:`../config/search-semantic`)를 참조하십시오. +- **14.x에서 업그레이드하는 경우**: OpenSearch가 2.x에서 3.x로 메이저 버전 업그레이드 + 되므로 인덱스 재작성을 권장합니다. +- **15.8 이전에 생성한 문서 인덱스에서 소유자 검색이나 가나 정규화를 사용하는 경우**: 재인덱싱이 + 필요합니다. 자세한 내용은 :ref:`upgrade-reindex-new-fields` 를 참조하십시오. + +.. warning:: + + 인덱스를 새로 생성하는 작업(재인덱싱 포함)은 k-NN 플러그인이 없는 + OpenSearch에서는 실패합니다. 단계 4의 주의사항을 확인하십시오. + +Q: 업그레이드 후 검색 결과가 표시되지 않습니다 +---------------------------------------------- + +A: 다음을 확인하십시오: + +1. OpenSearch가 시작되어 있는지 확인 +2. 인덱스가 존재하는지 확인(``curl http://localhost:9200/_cat/indices``) +3. 크롤 재실행 + +다음 단계 +========== + +업그레이드가 완료되면: + +- :doc:`run` - 시작 및 초기 설정 확인 +- :doc:`security` - 보안 설정 검토 +- :doc:`../config/search-semantic` - 청크 벡터 검색(시맨틱 검색) 설정 및 마이그레이션 절차 +- 릴리스 노트에서 새 기능 확인 diff --git a/ko/15.10/user/advanced-search.rst b/ko/15.10/user/advanced-search.rst new file mode 100644 index 000000000..3096d0268 --- /dev/null +++ b/ko/15.10/user/advanced-search.rst @@ -0,0 +1,79 @@ +========== +상세 검색 +========== + +상세 검색 화면에서는 여러 조건을 조합하여 더욱 복잡한 검색을 수행할 수 있습니다. + +사용 방법 +---------- + +상세 검색 화면은 검색 화면의 검색 옵션에 있는 「상세 검색」 링크에서 열 수 있습니다. 검색 결과 화면에서 열면 이미 입력한 검색 키워드가 「모든 단어 포함」 필드로 인계됩니다. + +|image0| + +각 필드에 조건을 입력하고 페이지 하단의 검색 버튼을 클릭합니다. 입력한 여러 필드는 하나의 검색 조건으로 조합됩니다. + +항목 목록 +---------- + +모든 단어 포함 +:::::::::::::::: + +입력한 모든 단어를 포함하는 문서를 검색합니다(AND 검색). 여러 단어를 공백으로 구분하여 지정할 수 있습니다. + +어순 포함 완전 일치 +:::::::::::::::: + +입력한 문자열을 어순을 포함하여 그대로 포함하는 문서를 검색합니다(구문 검색). 공백을 포함한 문자열 전체를 하나의 구문으로 취급하므로 개별 단어로 나누어 검색할 수 없습니다. + +단어 중 하나라도 포함 +:::::::::::::::: + +입력한 단어 중 하나라도 포함하는 문서를 검색합니다(OR 검색). 여러 단어를 공백으로 구분하여 지정할 수 있습니다. + +제외할 단어 +:::::::::::::::: + +입력한 단어를 포함하지 않는 문서를 검색합니다. 여러 단어를 공백으로 구분하여 지정할 수 있으며, 지정한 모든 단어가 검색 결과에서 제외됩니다. + +표시 건수 +:::::::::::::::: + +한 페이지에 표시되는 검색 결과 건수를 지정합니다. 10, 20, 30, 40, 50, 100 중에서 선택할 수 있습니다. 지정하지 않으면 기본 표시 건수(초깃값 10)가 사용됩니다. + +정렬 +:::::::::::::::: + +검색 결과를 정렬하는 기준을 지정합니다. 점수 순, 파일 이름, 날짜, 크기, 최종 갱신 일시 중에서 각각 오름차순 또는 내림차순으로 선택할 수 있습니다. 해당 기능이 활성화된 경우에는 클릭 수 또는 즐겨찾기 수로 정렬할 수도 있습니다. + +우선 언어 +:::::::::::::::: + +검색 결과에서 우선할 언어를 지정합니다. 여러 언어를 선택할 수 있습니다. 「모든 언어」를 선택하면 특정 언어를 우선하지 않습니다. + +라벨 +:::::::::::::::: + +라벨로 검색을 필터링합니다. 여러 라벨을 선택할 수 있습니다. 라벨이 등록되어 있지 않거나 현재 사용자가 볼 수 있는 라벨이 없는 경우에는 표시되지 않습니다. + +업데이트 일시 +:::::::::::::::: + +문서의 업데이트 일시로 검색을 필터링합니다. 「지정 없음」, 「24시간 이내」, 「1주일 이내」, 「1개월 이내」, 「1년 이내」 중에서 선택할 수 있습니다. + +파일 형식 +:::::::::::::::: + +문서의 파일 형식으로 검색을 필터링합니다. 「모든 형식」, 「HTML」, 「PDF」, 「MS Word」, 「MS Excel」, 「MS PowerPoint」 중에서 선택할 수 있습니다. + +검색 대상 +:::::::::::::::: + +검색할 대상을 지정합니다. 「페이지 전체」, 「페이지 내 제목」, 「페이지 내 URL」 중에서 선택할 수 있습니다. 제목 또는 URL 옵션을 선택하면 입력한 단어를 각각 제목 또는 URL에서만 검색합니다. + +사이트 또는 도메인 +:::::::::::::::: + +입력한 사이트 또는 도메인으로 검색을 필터링합니다. 특정 사이트나 도메인에 포함된 문서만 검색하고 싶을 때 지정합니다. + +.. |image0| image:: ../../../resources/images/en/15.10/user/advanced-search-1.png diff --git a/ko/15.10/user/chat-search.rst b/ko/15.10/user/chat-search.rst new file mode 100644 index 000000000..4f9f1f713 --- /dev/null +++ b/ko/15.10/user/chat-search.rst @@ -0,0 +1,254 @@ +================ +AI 검색 모드 +================ + +개요 +==== + +|Fess| 의 AI 검색 모드 기능(RAG 채팅)을 사용하면 기존의 키워드 검색에 더해 +자연스러운 대화 형식으로 정보를 찾을 수 있습니다. 질문을 입력하면 AI 어시스턴트가 +관련 문서를 검색하고, 그 내용을 바탕으로 이해하기 쉬운 답변을 생성합니다. + +.. note:: + AI 검색 모드는 초기 상태에서는 비활성화되어 있습니다. 이용하려면 시스템 관리자가 + 기능을 활성화하고 LLM(대규모 언어 모델) 프로바이더를 설정해 두어야 합니다. + 설정 방법은 :doc:`../config/rag-chat` 및 :doc:`../config/llm-overview` 를 참조하세요. + +AI 검색 모드의 특징 +=================== + +대화형 검색 +---------------- + +키워드를 생각하는 대신 평소 대화처럼 질문할 수 있습니다. + +예: + +- "Fess의 설치 방법을 알려주세요" +- "파일을 크롤링하려면 어떻게 하면 되나요?" +- "검색 결과가 표시되지 않을 때 대처 방법은?" + +맥락을 반영한 답변 +------------------ + +AI 어시스턴트는 질문의 의도를 분석하고 관련 문서를 검색한 다음, +여러 검색 결과에서 필요한 정보를 추출하여 정리된 형태로 답변합니다. + +출처 명시 +------------ + +답변 하단에는 답변의 근거가 된 문서가 "출처"로 목록 표시됩니다. +각 출처는 번호가 매겨진 링크로 되어 있으며, 클릭하면 원본 문서를 바로 확인할 수 있습니다. +또한 답변 본문에 ``[1]`` , ``[2]`` 와 같은 번호로 인용이 표시되는 경우가 있으며, +이는 출처 목록의 번호와 대응합니다. + +대화 지속 +---------- + +한 번의 질문으로 끝나지 않고 대화를 계속할 수 있습니다. +AI 어시스턴트는 이전 질문과 답변의 맥락을 바탕으로 추가 질문에 답변합니다. + +채팅 검색 사용법 +==================== + +AI 검색 모드 열기 +------------------ + +1. |Fess| 의 검색 화면을 엽니다 +2. 화면 상단 내비게이션 바에 있는 "AI 검색" 링크(로봇 아이콘)를 클릭합니다 +3. AI 검색 모드 화면이 표시됩니다 + +.. note:: + "AI 검색" 링크는 AI 검색 모드가 활성화되어 있고, 또한 LLM 프로바이더를 사용할 수 있는 + 경우에만 표시됩니다. 링크가 표시되지 않는 경우에는 `자주 묻는 질문`_ 을 참조하세요. + +질문 입력하기 +-------------- + +1. 화면 하단의 텍스트 상자에 질문을 입력합니다(1회당 최대 4000자) +2. 전송 버튼("메시지 보내기", 종이비행기 아이콘)을 클릭하거나 Enter 키를 누릅니다 +3. AI 어시스턴트가 답변 생성을 시작합니다 + +.. note:: + 줄 바꿈을 입력하고 싶은 경우에는 Enter 키 대신 Shift+Enter를 누릅니다. + +.. note:: + 답변 생성에는 몇 초에서 십여 초 정도 걸릴 수 있습니다. 처리 중에는 현재 처리 단계가 + 진행 상황 표시(분석 → 검색 → 평가 → 가져오기 → 답변)로 나타나며, + "생각 중...", "검색 중...", "검색 결과 확인 중...", "문서 가져오는 중...", "답변 생성 중..." + 와 같은 메시지가 표시됩니다. 검색이 완료되면 찾은 문서 건수도 표시됩니다. + +답변 확인하기 +-------------- + +AI 어시스턴트의 답변이 표시됩니다. 답변에는 다음 정보가 포함됩니다: + +- **답변 본문**: 질문에 대한 답변(마크다운 형식으로 정리됩니다) +- **출처**: 답변의 근거가 된 문서로의 링크 목록(번호가 매겨진 링크. 클릭하면 새 탭에서 원본 문서가 열립니다) + +답변 본문 중에 ``[1]`` , ``[2]`` 와 같은 인용 번호가 포함되는 경우가 있으며, 출처 목록의 번호와 대응합니다. +각 답변에는 복사 버튼이 있어 답변 내용을 클립보드에 복사할 수 있습니다. + +.. note:: + AI는 검색 결과 중 관련성이 높다고 판단한 상위 문서만을 답변의 근거로 사용합니다. + 이 때문에 출처 건수가 검색에서 히트한 문서 건수보다 적을 수 있습니다. + +검색 대상 좁히기 +------------------ + +주제에 따라서는 화면 상단의 "필터" 버튼에서 라벨이나 파일 종류·수정일·크기 등의 조건으로 +검색 대상을 좁힐 수 있습니다. 특정 범위의 문서만을 대상으로 AI에게 질문하고 싶을 때 유용합니다. + +대화 계속하기 +------------- + +추가 질문이 있는 경우 그대로 이어서 질문할 수 있습니다: + +- "좀 더 자세히 알려주세요" +- "다른 방법이 있나요?" +- "OO에 대해 자세히" + +AI 어시스턴트는 이전 대화의 맥락을 고려하여 답변합니다. + +새 대화 시작하기 +------------------ + +다른 주제에 대해 질문하고 싶은 경우에는 "새 채팅" 버튼(+ 아이콘)을 클릭합니다. +이렇게 하면 그동안의 대화 이력이 초기화되고 새로운 대화를 시작할 수 있습니다. + +효과적인 질문 요령 +================== + +구체적으로 질문하기 +------------------- + +모호한 질문보다 구체적인 질문이 더 적절한 답변을 얻을 수 있습니다. + +.. list-table:: + :header-rows: 1 + :widths: 50 50 + + * - 모호한 질문 + - 구체적인 질문 + * - 설정 방법은? + - Fess의 메모리 설정을 변경하는 방법은? + * - 오류가 발생합니다 + - 검색 시 "인덱스를 찾을 수 없음"이라는 오류가 발생합니다 + * - 크롤링에 대해 + - 웹사이트를 크롤링할 때 제외 설정은 어떻게 하나요? + +배경 정보 포함하기 +------------------ + +상황이나 목적을 포함하면 더 적절한 답변을 얻을 수 있습니다. + +좋은 예: + +- "Docker 환경에서 Fess를 실행하고 있습니다. 로그 저장 위치를 변경하고 싶은데 어떻게 하면 되나요?" +- "처음 Fess를 사용합니다. 먼저 무엇을 하면 되나요?" + +단계적으로 질문하기 +------------------- + +복잡한 문제는 단계적으로 질문하면 이해하기 쉬워집니다. + +1. "Fess에서 파일 공유를 크롤링할 수 있나요?" +2. "SMB 프로토콜로 연결하는 방법을 알려주세요" +3. "인증이 필요한 공유 폴더인 경우에는 어떻게 하면 되나요?" + +자주 묻는 질문 +============== + +Q: AI 검색 모드가 표시되지 않습니다 +----------------------------------- + +A: AI 검색 모드가 활성화되어 있지 않을 가능성이 있습니다. +"AI 검색" 링크는 기능이 활성화되어 있고(``rag.chat.enabled=true``), 또한 LLM 프로바이더 +(OpenAI, Gemini, Ollama 등)가 설정되어 사용 가능한 경우에만 표시됩니다. +시스템 관리자에게 AI 검색 모드가 활성화되어 있는지, LLM 프로바이더가 올바르게 설정되어 +있는지 확인해 달라고 요청하세요(자세한 내용은 :doc:`../config/rag-chat` 참조). + +Q: 답변이 표시되기까지 시간이 걸립니다 +--------------------------------------- + +A: AI가 질문을 분석하고 문서를 검색·평가한 후 답변을 생성하기 때문에 +몇 초에서 십여 초 정도 걸릴 수 있습니다. 처리 중에는 현재 처리 단계 +("생각 중...", "검색 중...", "검색 결과 확인 중...", "문서 가져오는 중...", "답변 생성 중...")가 +표시됩니다. + +Q: 출처가 잘못된 것처럼 보입니다 +------------------------------------- + +A: 출처 링크를 클릭하여 원본 문서를 확인하세요. +AI는 검색 결과를 바탕으로 답변을 생성하지만, 해석에 오류가 있을 수 있습니다. +중요한 정보는 반드시 원본 문서에서 확인할 것을 권장합니다. + +Q: 이전 대화를 잊어버린 것 같습니다 +----------------------------------- + +A: 대화 세션이 타임아웃되었을 가능성이 있습니다. +일정 시간(기본값 30분) 동안 조작이 없으면 대화 이력이 초기화됩니다. +또한 대화 이력은 서버의 메모리에 일시적으로 유지되므로 서버 재시작으로도 사라집니다. +그런 경우에는 새로 대화를 시작하세요. + +.. note:: + 여기서 말하는 "세션"은 AI 검색 모드의 대화 세션이며, |Fess| 로그인 세션과는 별개입니다. + +Q: 특정 질문에 대해 답변을 얻을 수 없습니다 +------------------------------------------- + +A: 다음과 같은 가능성이 있습니다: + +- 검색 대상 문서에 관련 정보가 없음 +- 질문이 모호하여 적절한 검색이 되지 않음 +- 속도 제한에 도달함(1분당 요청 수 상한 또는 동시 실행 수 상한을 초과함) + +질문을 바꿔서 하거나 잠시 기다린 후 다시 시도하세요. + +Q: 입력할 수 있는 문자 수에 제한이 있나요? +------------------------------------------ + +A: 1회당 최대 4000자까지입니다. 텍스트 상자 아래에 문자 수 카운터가 표시되며, +상한에 가까워지면 경고 표시로 바뀝니다. 긴 질문은 요점을 추려 짧게 작성하세요. + +Q: 한국어 이외의 언어로 질문할 수 있나요? +----------------------------------------- + +A: 네, 대부분의 경우 영어나 그 밖의 언어로도 질문할 수 있습니다. +AI는 브라우저나 화면의 표시 언어를 바탕으로 가능한 한 같은 언어로 답변하려고 합니다. +다만 이는 최선을 다하는 수준(베스트 에포트)이며, 상황에 따라서는 의도한 언어가 아닐 수 있습니다. + +주의사항 +======== + +AI 답변에 대해 +---------------- + +- AI의 답변은 검색 결과를 바탕으로 생성된 것입니다 +- 답변의 정확성은 보장되지 않습니다 +- 중요한 판단에는 반드시 원본 문서(출처)를 확인하세요 +- 최신 정보는 공식 문서에서 확인하세요 + +개인정보에 대해 +-------------------- + +- 입력한 질문은 검색과, 설정된 LLM 프로바이더에 의한 AI 처리를 위해 사용됩니다 +- 외부 LLM 서비스(OpenAI, Gemini 등)를 이용하도록 설정한 경우, 질문 내용과 검색 결과가 + 해당 서비스로 전송됩니다. 사내에서만 처리하고 싶은 경우에는 로컬에서 동작하는 + 프로바이더(Ollama 등)의 이용에 대해 관리자와 상의하세요 +- 대화 이력은 서버의 메모리에 일시적으로 유지되며, 세션 타임아웃, "새 채팅" 실행, + 또는 서버 재시작에 의해 삭제됩니다 +- 검색과 마찬가지로 역할(권한)이나 라벨에 의한 접근 제어가 적용되며, 열람할 수 없는 + 문서는 답변의 대상이 되지 않습니다 +- 시스템 설정에 따라 로그가 기록될 수 있습니다 + +참고 정보 +========= + +- :doc:`../config/rag-chat` - AI 검색 모드 기능 설정(관리자용) +- :doc:`../config/llm-overview` - LLM 프로바이더 설정 +- :doc:`../api/api-chat` - Chat API(프로그램에서의 이용) +- :doc:`search-and` - AND 검색 사용법 +- :doc:`search-not` - NOT 검색 사용법 +- :doc:`search-field` - 필드 검색 사용법 +- :doc:`advanced-search` - 고급 검색 기능 diff --git a/ko/15.10/user/index.rst b/ko/15.10/user/index.rst new file mode 100644 index 000000000..22b743bf5 --- /dev/null +++ b/ko/15.10/user/index.rst @@ -0,0 +1,29 @@ +|Fess| 사용자 가이드 +================== + +AND·OR·NOT, 필드 검색과 라벨 검색, 정렬, 와일드카드, 범위 지정, +부스트, 유사 검색, 근접 검색, 위치 검색 등 |Fess|\ 에서 검색어를 작성하는 방법을 +설명합니다. + +.. toctree:: + :maxdepth: 2 + + intro + search-and + search-or + search-not + search-bangs + search-label + search-field + search-sort + search-wildcard + search-range + search-boost + search-fuzzy + search-proximity + search-geo + search-additional + role-search + special-char + advanced-search + chat-search diff --git a/ko/15.10/user/intro.rst b/ko/15.10/user/intro.rst new file mode 100644 index 000000000..57f80ccbd --- /dev/null +++ b/ko/15.10/user/intro.rst @@ -0,0 +1,50 @@ +========= +검색 소개 +========= + +대상 독자 +========= + +|Fess| 는 웹사이트, 파일, 데이터베이스 등에 포함된 문서를 대상으로 전문 검색을 수행할 수 있는 엔터프라이즈용 검색 서버입니다. + +본 문서는 |Fess| 를 사용하는 사용자를 대상으로 합니다. + +시작하기 전에 +============= + +본 문서는 |Fess| 의 검색 방법을 설명합니다. 기본적인 키워드 검색에 더해, 상세 검색 화면을 사용한 필터링 검색과 자연스러운 대화 형식으로 정보를 찾을 수 있는 AI 검색 모드에 대해서도 설명합니다. 컴퓨터 조작에 대한 기초적인 지식이 필요합니다. + +온라인 접속 +================= + +다운로드, 전문 서비스, 지원 및 기타 개발자 정보는 다음을 참조하십시오. + +- 프로젝트 사이트: https://fess.codelibs.org/ + +기술 지원 문의 +================== + +본 제품과 관련된 기술적 질문에 대해 문서에서 해결책을 찾을 수 없는 경우 다음을 참조하십시오. + +- Issues: + `https://github.com/codelibs/fess/issues `__ + +상용 지원 +--------- + +본 제품과 관련된 기술 지원 또는 유지보수 등의 상용 지원이 필요한 경우 `N2SM, Inc. `__ 에 문의하십시오. + +관련 타사 웹사이트 참조 +============================= + +|Fess| 프로젝트는 본 문서에 언급된 타사 웹사이트의 유효성에 대해 책임을 지지 않습니다. |Fess| 프로젝트는 해당 사이트나 리소스를 통해 이용 가능한 콘텐츠, 광고, 제품, 서비스 및 기타 문서 등에 대해 보증, 책임 또는 의무를 지지 않습니다. |Fess| 프로젝트는 해당 사이트나 리소스를 통해 이용 가능한 콘텐츠, 광고, 제품, 서비스 및 기타 문서 등을 사용하거나 신뢰하거나, 이와 관련하여 발생하거나 주장되는 모든 손상이나 손해에 대해 책임 또는 의무를 지지 않습니다. + +의견 및 제안 보내기 +===================== + +|Fess| +프로젝트는 본 문서의 개선을 위해 노력하고 있으며, 독자 여러분의 의견과 제안을 환영합니다. + +- Issues: + `https://github.com/codelibs/fess-docs/issues `__ + diff --git a/ko/15.10/user/role-search.rst b/ko/15.10/user/role-search.rst new file mode 100644 index 000000000..07a958fe4 --- /dev/null +++ b/ko/15.10/user/role-search.rst @@ -0,0 +1,57 @@ +========= +역할 검색 +========= + +|Fess| 는 사용자 관리 기능을 제공하며, 로그인한 사용자는 자신이 속한 역할을 기준으로 검색할 수 있습니다. |Fess| 에서 관리하는 사용자는 로그인 후 역할 검색을 이용하거나 자신의 비밀번호를 변경할 수 있습니다. + +역할 검색에서는 콘텐츠에 설정된 권한(역할·그룹·사용자)과 검색하는 사용자가 가진 권한을 대조하여, 접근이 허용된 콘텐츠만 검색 결과에 표시합니다. 역할과 사용자를 만드는 방법, 콘텐츠에 권한을 할당하는 방법 등 역할 기반 검색 설정에 대해서는 :doc:`../config/security-role` 를 참조하십시오. + + +검색 방법 +--------- + +역할을 설정하고 크롤링 및 인덱싱한 상태라면 검색 결과는 해당 역할을 보유한 사용자에게만 표시할 수 있습니다. +사용자가 로그인한 경우에는 그 사용자가 속한 역할이나 그룹을 기준으로 검색이 수행됩니다. +로그인하지 않은 경우에는 guest 사용자로 검색되며, guest 대상으로 공개된 콘텐츠만 표시됩니다. + +.. note:: + 로그인한 사용자의 검색은 그 사용자 자신과 소속된 역할·그룹의 권한만으로 수행되며, guest 대상(``{role}guest``)으로 공개한 콘텐츠는 대상이 되지 않습니다. 따라서 guest 대상으로만 공개한 콘텐츠는 로그인하지 않은 방문자에게는 표시되지만, 로그인한 사용자에게는(역할이나 그룹을 가지지 않은 사용자도 포함하여) 표시되지 않습니다. 로그인한 사용자에게도 보여주고 싶은 콘텐츠에는 크롤 설정의 권한에 ``{role}guest`` 와 함께 해당 사용자가 가진 역할(모든 사용자에게 보여주려면 전체 사용자에게 부여한 역할)도 설정하십시오. + +로그인 +------ + +검색 화면 상단에 표시되는 로그인 링크를 클릭하면 로그인 화면이 표시됩니다. 사용자 이름과 비밀번호를 입력하여 로그인하면 검색 화면으로 돌아가고, 이후의 검색은 그 사용자가 속한 역할을 기준으로 수행됩니다. + +.. note:: + 싱글 사인온이나 LDAP 와 연동되어 있는 경우에는 각각의 인증 방식으로 로그인합니다. 또한 로그인 링크의 표시 여부는 설정으로 변경할 수 있습니다. + +비밀번호 변경 +------------- + +로그인 후 검색 화면 상단에 표시되는 사용자 이름을 클릭하면 메뉴가 표시됩니다. + +|image0| + +메뉴에서 "비밀번호 변경"을 클릭하면 비밀번호 변경 화면이 표시됩니다. + +|image1| + +현재 비밀번호, 새 비밀번호, 확인용 새 비밀번호(재입력)를 입력하고 갱신 버튼을 클릭하면 비밀번호가 갱신됩니다. +비밀번호를 변경하면 로그아웃되므로, 새 비밀번호로 다시 로그인하십시오. +이 화면은 검색 화면 테마의 ``/profile`` 페이지이며, 비밀번호는 ``POST /api/v2/auth/password`` 로 변경됩니다( :doc:`../api/api-auth` 참조). + +.. note:: + "비밀번호 변경" 메뉴는 |Fess| 에서 관리하는 사용자(및 편집이 허용된 LDAP 사용자)에게만 표시됩니다. 싱글 사인온으로 인증한 사용자에게는 표시되지 않습니다. + 새 비밀번호에는 길이나 사용할 수 있는 문자 종류 등의 비밀번호 정책이 적용될 수 있습니다. + +로그아웃 +-------- + +로그인한 상태에서 검색 화면 상단에 표시되는 사용자 이름을 클릭하고 메뉴에서 "로그아웃"을 선택하면 로그아웃할 수 있습니다. +관리자 권한을 가진 사용자의 경우, 같은 메뉴에서 "관리"를 선택하여 관리 화면으로 이동할 수도 있습니다. + + +.. |image0| image:: ../../../resources/images/en/15.10/user/role-search-1.png +.. pdf :width: 200 px +.. |image1| image:: ../../../resources/images/en/15.10/user/role-search-2.png +.. pdf :width: 300 px diff --git a/ko/15.10/user/search-additional.rst b/ko/15.10/user/search-additional.rst new file mode 100644 index 000000000..185d0a277 --- /dev/null +++ b/ko/15.10/user/search-additional.rst @@ -0,0 +1,30 @@ +================ +비표시 검색 조건 +================ + +화면에 조건 텍스트를 표시하지 않고 특정 검색 조건을 전달하고 싶은 경우 ``ex_q`` 매개변수를 사용할 수 있습니다. ``ex_q`` 에 지정한 조건은 검색어 입력란에는 표시되지 않으며, 페이징이나 패싯 필터링으로 화면이 갱신되어도 유지됩니다. + +``ex_q`` 에는 일반 검색어(``q``)와 동일한 쿼리 구문(``field:value`` 형식, 구문, 범위 지정, ``OR`` 등의 연산자)을 작성할 수 있습니다. 지정한 조건은 ``q`` 의 조건과 기본적으로 AND 로 결합되어 검색이 실행됩니다. 즉 ``ex_q`` 의 조건에 일치하지 않는 문서는 검색 결과에서 제외됩니다. + +사용 방법 +--------- + +검색을 실행할 때(예: 검색 양식 등) ``ex_q`` 값을 히든 폼 필드 또는 URL 쿼리 파라미터로 추가하여 검색을 실행합니다. 이렇게 하면 조건을 화면에 표시하지 않고 검색할 수 있습니다. + +``ex_q`` 는 여러 번 지정할 수 있습니다. 아래 예시처럼 여러 개의 ``ex_q`` 를 전달하면 각각이 검색 조건으로 추가됩니다(빈 값이나 중복된 값은 무시됩니다). + +.. code-block:: none + + /search?q=keyword&ex_q=label:manual&ex_q=filetype:pdf + +페이징 시 유지 +-------------- + +페이징(다음 페이지·이전 페이지 등)이나 패싯 필터링 링크에는 Fess 가 자동으로 ``ex_q`` 값을 추가합니다. 따라서 이러한 조작으로 화면이 갱신되어도 ``ex_q`` 조건은 유지됩니다. + +반면 표준 검색어 입력란(검색 상자)에서 검색어를 입력하여 다시 검색한 경우 ``ex_q`` 는 유지되지 않습니다. 검색 상자를 통해서도 조건을 유지하고 싶다면, 자체 검색 양식에 ``ex_q`` 의 히든 필드를 마련하고 검색할 때마다 ``ex_q`` 를 전송하십시오. + +.. note:: + + * ``ex_q`` 의 각 값의 길이가 ``query.max.length`` (기본값: 1000자)를 초과하면 해당 값은 오류 없이 무시됩니다. + * ``ex_q`` 는 웹 화면 검색뿐만 아니라 검색 API(``/api/v2``)에서도 사용할 수 있습니다. API 에서는 요청당 ``ex_q`` 요소 수의 상한(``api.v2.param.max.array.size``, 기본값: 100)과 각 요소 길이의 상한(``api.v2.param.max.length``, 기본값: 1000자)이 적용됩니다. diff --git a/ko/15.10/user/search-and.rst b/ko/15.10/user/search-and.rst new file mode 100644 index 000000000..e4dc48da9 --- /dev/null +++ b/ko/15.10/user/search-and.rst @@ -0,0 +1,46 @@ +======== +AND 검색 +======== + +여러 검색어가 모두 포함된 문서를 검색하려는 경우 AND 검색을 사용합니다. 검색어 입력란에 여러 단어를 공백으로 구분하여 입력하면 기본적으로 AND 검색이 되므로, AND를 생략해도 동일한 결과를 얻을 수 있습니다. + +사용 방법 +--------- + +AND 검색을 사용하는 경우 검색어 사이에 AND를 입력합니다. AND는 +반각 대문자로 입력해야 하며, 앞뒤로 공백이 필요합니다. AND는 +생략할 수도 있습니다. + +예를 들어, "검색어1"과 "검색어2"가 포함된 문서를 검색하려는 경우 다음과 같이 검색 양식에 입력합니다. + +:: + + 검색어1 AND 검색어2 + +AND를 생략하고 다음과 같이 입력해도 같은 결과가 됩니다. + +:: + + 검색어1 검색어2 + +AND로 3개 이상의 검색어를 연결할 수도 있습니다. + +:: + + 검색어1 AND 검색어2 AND 검색어3 + +.. note:: + + AND는 반각 대문자로 입력해야 합니다. ``and``\ 처럼 소문자로 입력한 경우에는 연산자로 취급되지 않고, "and"라는 일반 검색어로 검색됩니다. ``&&``\ 도 AND와 같은 의미로 사용할 수 있습니다. + +괄호 ``( )``\ 를 사용하면 AND 검색과 다른 검색 조건을 조합할 수 있습니다. 예를 들어 "검색어1"을 포함하고, 또한 "검색어2" 또는 "검색어3" 중 하나를 포함하는 문서를 검색하려는 경우 다음과 같이 입력합니다. + +:: + + 검색어1 AND (검색어2 OR 검색어3) + +필드를 지정하여 AND 검색을 수행할 수도 있습니다. 다음 예에서는 title 필드에 "검색어1"을 포함하고, 또한 content 필드에 "검색어2"를 포함하는 문서를 검색합니다. + +:: + + title:검색어1 AND content:검색어2 diff --git a/ko/15.10/user/search-bangs.rst b/ko/15.10/user/search-bangs.rst new file mode 100644 index 000000000..4caa9edf4 --- /dev/null +++ b/ko/15.10/user/search-bangs.rst @@ -0,0 +1,80 @@ +============================= +뱅 검색(다른 사이트에서 검색) +============================= + +뱅(bang)은 |Fess| 에서 검색하는 대신 다른 사이트로 검색을 보내는 기능입니다. DuckDuckGo의 뱅과 같은 방식으로, 검색어에 ``!`` 와 짧은 트리거 단어를 넣으면 |Fess| 가 나머지 검색어를 그 트리거 단어가 가리키는 사이트로 보냅니다. + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - 검색어 + - 전송 대상 + * - ``airplane !g`` + - Google에서 ``airplane`` 검색 + * - ``!w Ohm's law`` + - Wikipedia에서 ``Ohm's law`` 검색 + * - ``!g`` + - Google 홈페이지 + * - ``airplane !unknown`` + - |Fess| 에서의 일반 검색 (``!`` 는 NOT을 뜻합니다. :doc:`search-not` 참조) + +뱅은 ``fess-webapp-bangs`` 플러그인이 제공하며, |Fess| 15.10 이상이 필요합니다. 관리 화면의 [시스템 > 플러그인] 또는 ``bin/fess-setup install plugin fess-webapp-bangs`` 로 설치하고(:doc:`../admin/plugin-guide` 참조) |Fess| 를 재시작합니다. + +뱅으로 인식되는 조건 +==================== + +- 뱅은 ``!`` 뒤에 트리거 단어가 붙은 것이며, 독립된 단어로 작성합니다. 트리거 단어는 대소문자를 구분하지 않습니다. +- 뱅은 검색어에서 제거되고, 나머지 검색어가 뱅의 URL로 전송됩니다. +- 정의된 뱅이 검색어에 여러 개 있으면 첫 번째 것만 유효합니다. +- 정의되지 않은 트리거 단어는 뱅이 아닙니다. ``!unknown`` 은 평소처럼 검색되며 단어 ``unknown`` 을 제외합니다. +- ``-g`` 와 ``NOT g`` 는 지금까지처럼 단어 ``g`` 를 제외합니다. 뱅이 되는 것은 ``!g`` 뿐입니다. + +검색 화면과 ``/api/v2/search`` 는 리디렉션을 따릅니다. API는 ``redirect_url`` 을 반환하고(:doc:`../api/api-search` 참조), |Fess| 에 포함된 ``bootstrap`` 테마가 해당 URL로 이동합니다. 다른 테마에서는 같은 처리가 필요합니다. + +채팅, MCP, v1 API와 클래식 JSON API, 관리 화면의 검색처럼 리디렉션할 수 없는 호출자는 다른 사이트로 검색을 보내지 않습니다. 뱅을 제거하고 나머지 검색어로 검색합니다. + +뱅 정의 +======= + +뱅은 시스템 속성 ``bangs.definitions`` 로 정의합니다. ``app/WEB-INF/conf/system.properties`` 에 기술하거나 ``-Dfess.system.bangs.definitions=...`` 로 전달합니다. ``system.properties`` 의 변경은 |Fess| 를 재시작하지 않아도 반영됩니다. + +값은 ``트리거 단어=URL`` 항목을 공백으로 구분한 목록입니다. URL 안의 ``{query}`` 는 URL 인코딩된 나머지 검색어로 바뀝니다. + +:: + + bangs.definitions=g=https://www.google.com/search?q={query} w=https://en.wikipedia.org/wiki/Special:Search?search={query} + +- 트리거 단어에는 공백, ``(``, ``)``, ``!``, ``"``, ``=``, ``:`` 를 포함할 수 없습니다. +- 절대 URL인 ``http`` 또는 ``https`` 만 허용됩니다. +- 이 규칙에 맞지 않는 항목은 사용되지 않습니다. |Fess| 로그에 경고가 출력되며 다른 항목은 그대로 유효합니다. +- 같은 트리거 단어를 두 번 정의하면 첫 번째 정의가 사용됩니다. +- 값을 비우면 모든 뱅이 꺼집니다. + +``bangs.definitions`` 를 설정하지 않으면 다음 5개의 뱅을 사용할 수 있습니다. + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - 트리거 단어 + - 사이트 + * - ``g`` + - Google + * - ``b`` + - Bing + * - ``ddg`` + - DuckDuckGo + * - ``w`` + - Wikipedia (영어) + * - ``gh`` + - GitHub + +``bangs.definitions`` 를 설정하면 이 목록이 대체됩니다. 기본 뱅을 유지한 채 하나를 추가하려면 필요한 항목을 모두 작성하십시오. + +관련 항목 +========= + +- :doc:`search-not` - NOT 검색 +- :doc:`special-char` - 특수 문자와 이스케이프 +- :doc:`../api/api-search` - 검색 API diff --git a/ko/15.10/user/search-boost.rst b/ko/15.10/user/search-boost.rst new file mode 100644 index 000000000..cc75d1174 --- /dev/null +++ b/ko/15.10/user/search-boost.rst @@ -0,0 +1,46 @@ +========= +부스트 검색 +========= + +부스트 검색(가중치 검색) +==================== + +검색어 중 특정 검색어를 우선하고 싶은 경우에는 부스트 검색을 사용합니다. 부스트 검색을 사용하면 검색어의 중요도에 따른 검색이 가능해집니다. + +사용 방법 +---------- + +부스트 검색을 사용하려면 검색어 바로 뒤에 "^부스트값" 형식으로 부스트 값(가중치 값)을 지정합니다. 검색어와 부스트 값 사이에는 공백을 넣지 않고 작성하십시오. + +예를 들어 "사과 귤"을 검색할 때 "사과"를 더 우선하고 싶은 경우에는 다음과 같이 검색 양식에 입력합니다. + +:: + + 사과^100 귤 + +이 예에서는 "사과"에만 부스트 값이 적용되고, "귤"에는 적용되지 않습니다. + +부스트 값 +---------- + +부스트 값에는 숫자를 지정합니다. 정수뿐만 아니라 ``2.5``\ 와 같은 소수도 지정할 수 있습니다. + +- 1보다 큰 값을 지정하면 해당 검색어의 가중치가 증가합니다. +- 0보다 크고 1 미만인 값(예: ``0.5``)을 지정하면 해당 검색어의 가중치가 감소합니다. + +부스트 값은 검색 결과의 점수를 절대적으로 결정하는 것이 아니라, 다른 검색어와의 상대적인 가중치를 조정하는 것입니다. + +다른 검색 구문과의 조합 +-------------------- + +부스트 검색은 다른 검색 구문과 조합하여 사용할 수 있습니다. 예를 들어 필드를 지정한 검색어에 부스트 값을 추가할 수도 있습니다. + +:: + + title:사과^100 귤 + +이 예에서는 여러 검색어를 나열한 경우의 기본 연산자(AND)가 적용되므로, title 필드에 "사과"를 포함하고 "귤"도 포함하는 문서만 검색됩니다. "사과"를 포함하는 문서를 우선하면서 포함하지 않는 문서도 결과에 남기고 싶은 경우에는 OR로 결합합니다. + +:: + + title:사과^100 OR 귤 diff --git a/ko/15.10/user/search-field.rst b/ko/15.10/user/search-field.rst new file mode 100644 index 000000000..86c9c64f4 --- /dev/null +++ b/ko/15.10/user/search-field.rst @@ -0,0 +1,128 @@ +======================================= +필드 지정 검색(제목, URL 등으로 좁히기) +======================================= + +필드 지정 검색 +============== + +특정 필드만을 대상으로 하는 검색(필드 검색)을 하면 제목만, URL만과 같이 범위를 좁힌 검색을 할 수 있습니다. |Fess| 에서 크롤링한 결과는 제목이나 본문 등 필드별로 저장됩니다. 이러한 필드를 지정하여 검색하면 문서 유형별이나 크기별 등 세밀한 검색 조건을 지정할 수 있습니다. + +사용 가능한 필드 +--------------- + +기본적으로 다음 필드를 지정하여 검색할 수 있습니다. + +.. list-table:: + :header-rows: 1 + + * - 필드명 + - 설명 + - 데이터 타입 + * - url + - 크롤링한 URL + - 키워드 + * - host + - 크롤링한 URL에 포함된 호스트명 + - 키워드 + * - site + - URL에서 스킴과 쿼리 문자열을 제외한 문자열(호스트명과 경로). 전방 일치로 검색됩니다 + - 키워드 + * - title + - 제목 + - 텍스트 + * - content + - 본문 + - 텍스트 + * - content_length + - 문서 크기(바이트) + - 숫자 + * - last_modified + - 문서의 최종 수정 일시 + - 일시 + * - timestamp + - 문서의 등록 일시(최종 수정 일시를 가져올 수 없는 경우 크롤링 실행 시각) + - 일시 + * - mimetype + - 문서의 MIME 타입(예: ``text/html``) + - 키워드 + * - filetype + - MIME 타입으로 결정되는 파일 종류(예: ``html``, ``word``, ``pdf``. 해당하지 않는 경우 ``others``) + - 키워드 + * - filename + - URL 경로 끝의 파일명 + - 키워드 + * - label + - 문서에 부여된 레이블 값 + - 키워드 + * - lang + - 문서의 언어 코드(예: ``ja``, ``en``) + - 키워드 + * - anchor + - HTML 페이지 내에서 추출한 링크 대상 URL(웹 크롤링 시에만) + - 키워드 + * - click_count + - 문서가 클릭된 횟수 + - 숫자 + * - favorite_count + - 문서가 즐겨찾기에 등록된 횟수 + - 숫자 + * - owner + - 파일 소유자의 계정 이름 + - 키워드 + * - last_modifier + - 파일의 최종 수정자 + - 키워드 + +표: 사용 가능한 필드 목록 + +"데이터 타입"은 필드별 검색 방법의 차이를 나타냅니다. + +* 키워드: 값 전체를 대상으로 완전 일치로 검색합니다. 와일드카드 검색이나 프리픽스(전방 일치) 검색과 조합할 수도 있습니다. +* 텍스트: 형태소 분석 등으로 분할된 단어를 대상으로 전문 검색을 합니다. title이나 content가 이에 해당합니다. +* 숫자·일시: :doc:`범위 지정 검색 ` 을 이용할 수 있습니다. + +필드를 지정하지 않은 경우는 title 및 content를 대상으로 검색합니다. 설정에 따라 검색 대상 필드를 추가할 수도 있습니다. + +.. note:: + 크롤링 대상에 따라 값이 등록되지 않는 필드도 있습니다. 예를 들어 anchor는 웹 크롤링 시에만 등록됩니다. lang에는 HTML의 언어 속성 또는 문서 본문에서 판별한 언어가 등록되며, 언어를 판별할 수 없거나 판별한 언어가 ``supported.languages`` 에 없으면 등록되지 않습니다. 또한 segment(크롤링 실행 단위를 나타내는 세션 ID)나 doc_id(시스템이 부여하는 내부 ID) 등의 필드도 지정할 수 있지만, 일반적인 검색에서는 사용하지 않습니다. + +owner 와 last_modifier 는 파일 서버 등을 크롤링할 때 등록됩니다. owner 에는 SMB, 파일 시스템, FTP 크롤링에서 가져온 파일 소유자의 계정 이름이 들어갑니다( ``DOMAIN\alice`` 와 같은 값은 ``alice`` 가 됩니다). last_modifier 에는 Office 문서 등에서 추출한 최종 수정자가 들어가며, 가져올 수 없으면 소유자가 들어갑니다. 웹 크롤링한 HTML 에는 owner 가 등록되지 않습니다. 예를 들어 ``owner:alice`` 나 ``last_modifier:"Taro Yamada"`` 와 같이 검색합니다. 기본 제공 테마에서는 고급 검색에서 소유자와 최종 수정자를 지정할 수 있습니다. 등록 여부는 관리자가 ``crawler.document.file.owner.enabled`` 와 ``crawler.document.file.last.modifier.enabled`` (둘 다 기본값은 ``true`` )로 전환할 수 있습니다. + +HTML 파일을 검색 대상으로 하는 경우 title 태그가 title 필드에, body 태그 이하의 문자열이 content 필드에 등록됩니다. + +사용 방법 +------ + +필드 지정 검색을 하는 경우는 "필드명:검색어"와 같이 필드명과 검색어를 콜론(:)으로 구분하여 검색 양식에 입력합니다. + +title 필드에 대해 fess를 검색어로 검색하는 경우는 다음과 같이 입력합니다. + +:: + + title:fess + +위 검색으로 title 필드에 fess가 포함된 문서가 검색 결과로 표시됩니다. + +url 필드에 대해 검색하는 경우는 다음과 같이 입력합니다. + +:: + + url:https\:\/\/fess.codelibs.org\/ja\/15.10\/* + url:"https://fess.codelibs.org/ja/15.10/*" + +전자는 와일드카드 검색을 사용할 수 있으므로 ``url:*\/\/fess.codelibs.org\/*`` 와 같은 작성도 가능합니다. url에 포함된 ":"나 "/"는 검색 쿼리의 특수 문자이므로 ``\`` 를 붙여 이스케이프하십시오(:doc:`special-char` 참조). 후자는 와일드카드 검색을 사용할 수 없지만, 끝을 ``*`` 로 한 단어는 프리픽스(전방 일치) 검색으로 처리됩니다. + +.. tip:: + URL의 일부로 검색하고 싶은 경우는 ``inurl:`` 을 사용하면 URL에 대한 부분 일치 검색을 할 수 있습니다. 예를 들어 ``inurl:15.10`` 은 URL에 ``15.10`` 을 포함하는 문서를 검색합니다. + +mimetype나 filetype, site와 같이 값에 "/"를 포함하는 필드를 지정하는 경우에는 ``mimetype:"text/html"`` 처럼 인용부호로 감싸거나, ``mimetype:text\/html`` 처럼 이스케이프하십시오. + +관련 검색 구문에 대해서는 :doc:`와일드카드 검색 `, :doc:`범위 지정 검색 `, :doc:`정렬 검색 `, :doc:`특수 문자 ` 도 참조하십시오. + + +관련 항목 +============== + +- :doc:`search-range` - 범위 지정 검색 +- :doc:`search-wildcard` - 와일드카드 검색 +- :doc:`special-char` - 특수 문자 diff --git a/ko/15.10/user/search-fuzzy.rst b/ko/15.10/user/search-fuzzy.rst new file mode 100644 index 000000000..aa420d06d --- /dev/null +++ b/ko/15.10/user/search-fuzzy.rst @@ -0,0 +1,67 @@ +====== +유사 검색 +====== + +유사 검색(퍼지 검색) +================= + +검색어와 완전히 일치하지 않는 단어도 검색하고 싶은 경우에는 유사 검색(퍼지 검색)을 사용할 수 있습니다. 철자 오류나 표기 차이 등으로 완전히 일치하지 않는 문서도 찾고 싶은 경우에 유용합니다. 유사 검색은 검색어와 인덱스에 등록되어 있는 단어 사이의 차이(편집 거리)가 일정 범위 이내이면 해당 단어를 일치하는 것으로 간주하여 검색하는 방법입니다. 편집 거리란 어떤 단어를 다른 단어로 변환하는 데 필요한 문자의 삽입・삭제・치환 등의 최소 횟수를 말합니다. |Fess| 에서는 기본적으로 이러한 조작에 더해 인접한 2 문자의 교체도 1 회의 차이로 계산하는 다메라우-레벤슈타인 거리 (optimal string alignment)를 사용합니다. + +사용 방법 +------ + +유사 검색을 적용하려는 검색어 뒤에 "~"를 추가합니다. + +예를 들어, "fess"라는 단어를 유사 검색하려는 경우 다음과 같이 검색 양식에 입력하면 "fess"와 유사한 단어("fes" 등)를 포함하는 문서를 검색할 수 있습니다. + +:: + + fess~ + +"~" 뒤에 숫자를 붙이면 허용할 편집 거리 (몇 문자까지의 차이를 허용할지)를 지정할 수 있습니다. 지정할 수 있는 값은 0, 1, 2 중 하나의 정수입니다. + +:: + + fess~1 + +위 예시의 경우 "fess"와의 편집 거리가 1 이내인 단어를 검색합니다. + +숫자를 생략하고 "~"만 지정한 경우에는 편집 거리 2로 처리됩니다. 편집 거리의 최댓값은 2이며, 3 이상의 값을 지정한 경우에도 2로 처리됩니다. + +필드를 지정하여 유사 검색을 수행할 수도 있습니다. 다음 예에서는 title 필드에서 "fess"와 유사한 단어를 포함하는 문서를 검색합니다. + +:: + + title:fess~ + +필드를 지정하지 않은 경우에는 title 및 content 필드를 대상으로 유사 검색을 수행합니다. + +사용 조건 +------ + +유사 검색을 사용할 때는 다음 사항에 주의하십시오. + +* 유사 검색은 단어 단위로 적용됩니다. 따옴표로 묶은 구문에는 적용할 수 없습니다. 또한 구문 뒤에 붙인 숫자 (예: ``"Fess Search"~2``)는 유사 검색이 아니라 단어 사이의 거리를 나타내는 :doc:`근접 검색 `\ 이 됩니다. +* 유사 검색은 인덱스에 등록된 단어를 대상으로 수행되며, 검색어는 다시 분석되지 않습니다. 따라서 bi-gram이나 형태소 분석으로 토큰화되는 일본어 등의 텍스트에서는 예상대로 동작하지 않을 수 있습니다. 유사 검색은 주로 영숫자 단어에 유효합니다. +* 유사 검색의 검색어는 대문자와 소문자의 구분을 포함하여 그대로 편집 거리를 계산합니다. 인덱스에 등록되는 영문 단어는 일반적으로 소문자로 변환되어 있으므로 검색어에는 소문자를 사용하십시오. 예를 들어 ``Fess~1`` 은 첫 글자의 대문자 ``F`` 만으로 편집 거리 1을 모두 소진하므로 ``fess~1`` 과 같은 결과가 되지 않습니다. 또한 ``Fess~0`` 은 ``Fess`` 라는 대문자 단어와 일치하는 단어가 인덱스에 없으므로 아무것도 일치하지 않습니다(소문자 ``fess~0`` 은 완전 일치입니다). +* 1~2 문자 등 매우 짧은 단어에 "~"(편집 거리 2)를 붙이면, 단어 길이에 가까운 문자 수를 치환한 단어에도 일치합니다. 예를 들어 ``ab~`` 는 ``ab`` 와 ``ac`` 외에 두 문자가 모두 다른 ``xy`` 와도 일치합니다. 의도하지 않은 결과가 늘어나므로 짧은 단어에는 ``ab~1`` 과 같이 작은 편집 거리를 지정하십시오. + +.. note:: + + 유사 검색의 동작은 ``fess_config.properties`` 로 조정할 수 있습니다. + + * ``query.fuzzy.prefix_length`` (기본값: ``0``): 앞에서부터 완전히 일치시킬 문자 수입니다. 값을 크게 하면 오류를 허용하는 범위가 좁아집니다. + * ``query.fuzzy.expansions`` (기본값: ``50``): 일치 후보로 전개할 단어의 최대 수입니다. + * ``query.fuzzy.transpositions`` (기본값: ``true``): 인접한 2 문자의 교체를 1 회의 편집으로 계산할지 여부를 지정합니다. ``true``\ 인 경우에는 다메라우-레벤슈타인 거리 (optimal string alignment), ``false``\ 인 경우에는 고전적인 레벤슈타인 거리가 됩니다. + +.. note:: + + "~"를 붙이지 않는 일반 검색에서도 |Fess| 는 일정 길이 이상 (기본적으로 4 문자 이상)의 검색어에 대해 관련도를 높이기 위한 목적으로 약간의 가중치를 부여한 유사 일치를 자동으로 보조로 추가합니다 (``query.boost.fuzzy.*``). 이는 주로 검색 결과의 순위를 조정하기 위한 기능이며, "~"에 의한 유사 검색과는 다른 방식입니다. 다만 이 보조적인 일치도 검색 결과에 포함되므로, 검색어 자체를 포함하지 않고 한 글자만 다른 단어만 포함하는 문서가 결과에 추가될 수 있습니다(검색어 자체를 포함하는 문서가 더 상위에 표시됩니다). 이 동작을 중지하려면 ``query.boost.fuzzy.min.length`` 에 음수 값(예: ``-1``)을 지정하십시오. + + +관련 항목 +================= + +- :doc:`search-wildcard` - 와일드카드 검색 +- :doc:`search-proximity` - 근접 검색 +- :doc:`special-char` - 특수 문자 diff --git a/ko/15.10/user/search-geo.rst b/ko/15.10/user/search-geo.rst new file mode 100644 index 000000000..d2da7a2e4 --- /dev/null +++ b/ko/15.10/user/search-geo.rst @@ -0,0 +1,56 @@ +================ +위치 정보 검색 +================ + +인덱스를 생성할 때 각 문서에 위도·경도의 위치 정보를 추가해 두면, 검색 시 지정한 지점으로부터의 거리를 조건으로 검색 결과를 좁힐 수 있습니다. + +개요 +---- + +위치 정보 검색에서는 지정한 지점(위도·경도)을 중심으로 하는 반경 내에 포함된 문서만 검색 결과에 포함합니다. 이 필터링은 OpenSearch의 geo_distance 쿼리를 이용한 필터로 적용되기 때문에 점수(관련도)에는 영향을 주지 않습니다. 또한 거리에 의한 정렬은 지원하지 않습니다. + +위치 정보를 저장하는 필드는 OpenSearch의 매핑에서 ``geo_point`` 형으로 정의되어 있어야 합니다. 기본적으로 ``location`` 필드가 ``geo_point`` 형으로 준비되어 있습니다. 다만 ``location`` 필드에 값을 저장하는 처리는 기본적으로 제공되지 않으므로, 데이터 스토어 크롤링의 필드 매핑이나 스크립트, 검색 엔진에 문서를 등록하는 API 등을 이용하여 이용자가 직접 위치 정보를 저장해야 합니다. + +사용 방법 +---------- + +위치 정보 검색은 검색 요청에 다음 매개변수를 추가하여 지정합니다. 기본적으로 ``location`` 필드에 대해 이용할 수 있습니다. + +.. list-table:: + :header-rows: 1 + + * - 매개변수 + - 설명 + * - ``geo..point`` + - 중심이 되는 지점의 위도·경도를 ``위도,경도`` 형식으로 지정합니다. 값은 10진수 도(Double 형)이며, 쉼표로 구분한 두 개의 숫자를 지정합니다. 예: ``35.681236,139.767125`` + * - ``geo..distance`` + - 중심 지점으로부터의 거리(반경)를 지정합니다. 예: ``10km`` + +표: 요청 매개변수 + +````\ 에는 위치 정보를 저장한 필드 이름을 지정합니다. 지정할 수 있는 것은 ``query.geo.fields``\ 에 등록된 필드뿐이며, 기본값은 ``location``\ 입니다. 그 외의 필드를 사용하려면 ``geo_point`` 형으로 매핑한 후, ``fess_config.properties``\ 의 ``query.geo.fields``\ 에 쉼표로 구분하여 추가합니다. + +예를 들어 위도 35.681236, 경도 139.767125(도쿄역 부근)로부터 반경 10km 이내의 문서를 검색하는 경우, 검색 요청에 다음 매개변수를 추가합니다. + +:: + + geo.location.point=35.681236,139.767125&geo.location.distance=10km + +거리 단위 +---------- + +``geo..distance``\ 의 값은 OpenSearch의 거리 단위로 해석됩니다. ``km``\ (킬로미터) 외에도 ``mm``, ``cm``, ``m``, ``in``, ``ft``, ``yd``, ``mi``\ (마일), ``nmi``\ (해리) 등을 사용할 수 있습니다. 단위를 생략하고 숫자만 지정한 경우에는 미터로 처리됩니다(예: ``500``\ 은 500미터). + +복수 지정 +---------- + +* 동일한 필드에 대해 ``geo..point``\ 를 여러 번 지정한 경우, 그중 어느 한 지점의 반경 내에 포함되는 문서가 검색됩니다(OR 조건). +* 서로 다른 필드에 대해 각각 위치 정보를 지정한 경우, 모든 조건을 만족하는 문서가 검색됩니다(AND 조건). + +.. note:: + + ``geo..point``\ 와 ``geo..distance``\ 는 둘 다 지정해야 합니다. ``distance``\ 가 지정되어 있지 않은 경우, 해당 ``point``\ 의 조건은 무시됩니다. 또한 ``point``\ 의 값이 ``위도,경도`` 형식(쉼표로 구분한 두 개의 숫자)이 아니거나 숫자로 해석할 수 없는 경우에는 오류가 발생합니다. + +.. note:: + + 위치 정보 검색은 검색어에 대한 필터이므로, 검색어가 비어 있으면 검색이 실행되지 않으며 결과는 0건이 됩니다. 위치 정보 검색 요청에는 검색어를 지정하십시오. diff --git a/ko/15.10/user/search-label.rst b/ko/15.10/user/search-label.rst new file mode 100644 index 000000000..32b86987c --- /dev/null +++ b/ko/15.10/user/search-label.rst @@ -0,0 +1,29 @@ +=========== +라벨 지정 검색 +=========== + +라벨 지정 검색 (카테고리 검색) +======================= + +검색 대상 문서에 카테고리를 분류하기 위한 라벨 정보를 추가함으로써 검색 시 라벨을 지정한 필터링 검색이 가능합니다. 라벨을 이용하면 예를 들어 부서나 사이트, 문서 종류별로 검색 범위를 제한할 수 있습니다. + +라벨은 관리 화면에서 미리 등록해 두면 검색 화면에서 라벨을 이용한 필터링 검색이 가능해집니다. 이용 가능한 라벨은 검색 시 풀다운 메뉴에서 여러 개를 선택할 수 있으며, 여러 라벨을 선택한 경우 그중 하나라도 부여된 문서가 검색 대상이 됩니다. 라벨을 등록하지 않은 경우 라벨 풀다운 박스는 표시되지 않습니다. + +.. note:: + 라벨에는 권한(퍼미션)을 설정할 수 있으므로, 검색하는 사용자가 접근이 허용된 라벨만 풀다운에 표시됩니다. 또한 가상 호스트나 로케일(언어)에 따라 표시되는 라벨이 달라지는 경우도 있습니다. 따라서 라벨을 등록해 두었더라도 사용자에 따라 풀다운에 표시되지 않을 수 있습니다. + +라벨은 라벨을 부여할 대상을 URL 경로의 정규 표현식으로 지정하여 정의합니다. 라벨 등록 방법과 설정 항목에 대해서는 :doc:`라벨 관리 가이드 <../admin/labeltype-guide>` 를 참조하십시오. + +사용 방법 +------ + +검색 시 라벨 정보를 선택할 수 있습니다. 라벨 정보는 옵션 버튼을 클릭하면 표시되는 검색 옵션에서 선택할 수 있습니다. + +|image0| + +라벨을 설정하고 인덱스를 생성하면 라벨이 설정된 문서별로 검색할 수 있습니다. 라벨을 지정하지 않은 검색은 일반적인 전체 검색과 동일합니다. + +문서에 대한 라벨 부여는 크롤링하여 인덱스를 생성할 때 문서의 URL과 라벨에 설정된 경로를 대조하여 이루어집니다. 따라서 라벨 정의(대상으로 하는 경로나 제외할 경로)를 추가·변경한 경우, 그 내용은 이미 인덱싱된 문서에는 자동으로 반영되지 않습니다. 변경 사항을 반영하려면 대상 문서를 다시 크롤링하거나, 스케줄러에 등록된 "Label Updater" 작업을 실행하여 인덱스를 업데이트하십시오. + +.. |image0| image:: ../../../resources/images/en/15.10/user/search-label-1.png +.. pdf :width: 300 px diff --git a/ko/15.10/user/search-not.rst b/ko/15.10/user/search-not.rst new file mode 100644 index 000000000..ecf743d62 --- /dev/null +++ b/ko/15.10/user/search-not.rst @@ -0,0 +1,45 @@ +=================== +NOT 검색(제외 검색) +=================== + +특정 단어를 포함하지 않는 문서를 검색하는 경우 NOT 검색을 사용할 수 있습니다. 이는 제외 검색이라고도 하며, 특정 키워드를 검색 결과에서 제외하여 불필요한 결과(노이즈)를 줄이고 싶을 때 유용합니다. + +사용 방법 +------ + +NOT 검색은 제외하려는 단어 앞에 NOT을 붙여서 검색합니다. NOT은 +반각 대문자로 입력해야 하며, 앞뒤로 공백이 필요합니다. + +예를 들어, "검색어1"은 포함하지만 "검색어2"는 포함하지 않는 문서를 검색하려는 경우 다음과 같이 입력하여 검색합니다. + +:: + + 검색어1 NOT 검색어2 + +.. note:: + + NOT은 반각 대문자로 입력해야 합니다. ``not``\ 처럼 소문자로 입력한 경우에는 연산자로 취급되지 않고, "not"이라는 일반 검색어로 검색됩니다. 또한, 제외하고 싶은 단어 바로 앞에 ``-``\ 를 붙여 ``검색어1 -검색어2``\ 처럼 작성해도 NOT과 같은 의미가 됩니다. + +괄호 ``( )``\ 를 사용하면 NOT 검색과 다른 검색 조건을 조합할 수 있습니다. 예를 들어 "검색어1" 또는 "검색어2" 중 하나를 포함하고, "검색어3"은 포함하지 않는 문서를 검색하려는 경우 다음과 같이 입력합니다. + +:: + + (검색어1 OR 검색어2) NOT 검색어3 + +필드를 지정하여 NOT 검색을 수행할 수도 있습니다. 다음 예에서는 title 필드에 "검색어1"을 포함하고, title 필드에 "검색어2"는 포함하지 않는 문서를 검색합니다. + +:: + + title:검색어1 NOT title:검색어2 + + +.. note:: + + ``fess-webapp-bangs`` 플러그인을 설치하면 ``!g`` 처럼 정의된 뱅은 더 이상 제외 검색이 아니며, 다른 사이트로 검색을 보냅니다. :doc:`search-bangs` 를 참조하십시오. + +관련 항목 +------------ + +- :doc:`search-and` - AND 검색 +- :doc:`search-or` - OR 검색 +- :doc:`special-char` - 특수 문자 diff --git a/ko/15.10/user/search-or.rst b/ko/15.10/user/search-or.rst new file mode 100644 index 000000000..6dbc68e2c --- /dev/null +++ b/ko/15.10/user/search-or.rst @@ -0,0 +1,39 @@ +================================ +OR 검색(검색어 중 하나라도 포함) +================================ + +검색어 중 하나라도 포함된 문서를 검색하려는 경우 OR 검색을 사용합니다. 검색어 입력란에 여러 단어를 입력한 경우 기본적으로 AND 검색이 수행됩니다. + +사용 방법 +--------- + +OR 검색을 사용하는 경우 검색어 사이에 OR을 입력합니다. OR은 +반각 대문자로 입력해야 하며, 앞뒤로 공백이 필요합니다. + +예를 들어, "검색어1"과 "검색어2" 중 하나라도 포함된 문서를 검색하려는 경우 다음과 같이 검색 양식에 입력합니다. + +:: + + 검색어1 OR 검색어2 + +OR로 3개 이상의 검색어를 연결할 수도 있습니다. + +:: + + 검색어1 OR 검색어2 OR 검색어3 + +.. note:: + + OR는 반각 대문자로 입력해야 합니다. ``or``\ 처럼 소문자로 입력한 경우에는 연산자로 취급되지 않고, "or"라는 일반 검색어로 검색됩니다. ``||``\ 도 OR과 같은 의미로 사용할 수 있습니다. + +괄호 ``( )``\ 를 사용하면 OR 검색과 다른 검색 조건을 조합할 수 있습니다. 예를 들어 "검색어1" 또는 "검색어2" 중 하나를 포함하고, 또한 "검색어3"을 포함하는 문서를 검색하려는 경우 다음과 같이 입력합니다. + +:: + + (검색어1 OR 검색어2) 검색어3 + +필드를 지정하여 OR 검색을 수행할 수도 있습니다. 다음 예에서는 title 필드에 "검색어1"을 포함하거나, 또는 content 필드에 "검색어2"를 포함하는 문서를 검색합니다. + +:: + + title:검색어1 OR content:검색어2 diff --git a/ko/15.10/user/search-proximity.rst b/ko/15.10/user/search-proximity.rst new file mode 100644 index 000000000..e0569707f --- /dev/null +++ b/ko/15.10/user/search-proximity.rst @@ -0,0 +1,70 @@ +=========== +근접 검색 +=========== +근접 검색(단어 간 거리 검색) +============================== + +근접 검색은 구문에 포함된 단어가 서로 붙어 있지 않더라도 가까운 위치에 있는 문서를 검색하는 방법입니다. 찾으려는 단어 사이에 다른 단어가 들어갈 수 있는 경우에 유용합니다. + +사용 방법 +----------- + +단어를 큰따옴표로 묶고, 닫는 따옴표 뒤에 "~"와 숫자를 추가합니다. + +예를 들어 다음과 같이 입력하면 "Fess"와 "검색"이 거리 3 이내에 있는 문서를 검색할 수 있습니다. + +:: + + "Fess 검색"~3 + +숫자는 단어 사이에서 허용되는 위치 이동 횟수의 최댓값입니다 (자세한 내용은 아래의 "거리 계산 방식"을 참조하십시오). 숫자가 클수록 단어가 더 멀리 떨어져 있어도 일치합니다. + +필드를 지정하여 근접 검색을 수행할 수도 있습니다. 다음 예에서는 title 필드를 검색합니다. + +:: + + title:"Fess 검색"~3 + +숫자를 생략하고 "~"만 지정한 경우 (예: ``"Fess 검색"~``)에는 단어가 인접해 있어야 하는 일반 구문 검색으로 처리됩니다. 소수를 지정한 경우 소수점 이하는 버려집니다 (``~2.5``\ 는 ``~2``\ 로 처리됩니다). + +부스트와 함께 사용할 수도 있습니다. 다음 예에서는 근접 검색에 2의 부스트를 적용합니다 (:doc:`search-boost` 참조). + +:: + + "Fess 검색"~5^2 + +거리 계산 방식 +---------------- + +* 숫자는 단어 사이에서 허용되는 위치 이동 횟수의 최댓값입니다. 대상 필드의 애널라이저가 생성한 토큰을 단위로 계산하며, 문자 수나 공백으로 구분된 단어 수가 아닙니다. 영어 텍스트에서는 대략 단어 사이에 끼어 있는 단어 수에 해당합니다. 분석 시 불용어로 제거된 단어도 계산에 포함됩니다. +* 단어의 순서가 바뀌어도 일치하지만, 역순인 경우에는 더 큰 숫자가 필요합니다. 예를 들어 "quick brown fox"를 포함하는 문서는 ``"quick fox"~1``\ 에 일치하지만, ``"fox quick"``\ 에 일치시키려면 ``~3`` 이상이 필요합니다. + +:: + + "quick fox"~1 + "fox quick"~3 + +한국어 등 CJK 텍스트의 경우 +----------------------------- + +일본어, 중국어, 한국어 등 CJK 텍스트에서는 거리를 계산하는 단위가 필드에 따라 다릅니다. + +* title, content 등의 범용 필드에서는 단어 사이에 있는 문자 수에 가까운 값이 됩니다. +* 언어별 필드에서는 형태소를 단위로 계산되며, 제거된 조사 등도 계산에 포함됩니다. + +따라서 단어는 공백으로 구분하고, 숫자는 여유 있게 지정하십시오. + +:: + + "전문 검색"~5 + "오사카 맛있는"~10 + +공백이 없는 문자열 (예: ``"오사카맛있는"~10``)은 범용 필드에서는 연속된 하나의 문자열로 대조되므로, 단어 간 근접 검색으로 기대한 대로 동작하지 않을 수 있습니다. 단어는 공백으로 구분하십시오. 거리를 문자 수로 정확하게 환산할 수는 없으므로, 먼저 큰 숫자를 지정하고 결과를 확인하면서 좁혀 나가십시오. + +관련 항목 +=========== + +- :doc:`search-fuzzy` - 유사 검색(퍼지 검색) +- :doc:`search-boost` - 부스트 검색 +- :doc:`search-field` - 필드 지정 검색 +- :doc:`special-char` - 특수 문자 diff --git a/ko/15.10/user/search-range.rst b/ko/15.10/user/search-range.rst new file mode 100644 index 000000000..9b1df0e38 --- /dev/null +++ b/ko/15.10/user/search-range.rst @@ -0,0 +1,71 @@ +============== +범위 지정 검색 +============== + +숫자나 일시 등 범위를 지정할 수 있는 데이터를 필드에 저장하고 있는 경우, 해당 필드에 대해 범위 지정 검색이 가능합니다. + +사용 방법 +--------- + +범위 지정 검색을 하려면 "필드명:[값 TO 값]"을 검색 양식에 입력합니다. 범위의 구분에는 반각 대문자 ``TO`` 를 사용합니다. + +예를 들어, content_length 필드에 대해 1k바이트에서 10k바이트 범위에 있는 문서를 검색하는 경우에는 다음과 같이 검색 양식에 입력합니다. + +:: + + content_length:[1000 TO 10000] + +대괄호 ``[ ]`` 는 범위의 양 끝을 포함하며(이상·이하), 중괄호 ``{ }`` 는 범위의 양 끝을 포함하지 않습니다(초과·미만). 두 가지를 조합하여 지정할 수도 있습니다. 예를 들어 ``content_length:{1000 TO 10000]`` 는 1000보다 크고 10000 이하인 문서를 나타냅니다. + +한쪽을 ``*`` 로 지정하면 상한 또는 하한만을 지정한 열린 범위를 나타냅니다. ``content_length:[1000 TO *]`` 는 1000 이상, ``content_length:[* TO 10000]`` 는 10000 이하를 나타냅니다. + +범위 지정 검색은 검색 대상으로 등록되어 있는 필드에 대해서만 유효합니다. 기본적으로 content_length, last_modified, timestamp, click_count, favorite_count 등의 필드에서 범위 지정 검색을 할 수 있습니다. + +시간 범위 지정 검색 +------------------- + +시간(일시)의 범위 지정 검색을 하려면 "last_modified:[일시1 TO 일시2]"(일시1＜일시2)를 검색 양식에 입력합니다. 또한 일시1이 일시2보다 나중인 경우에도 오류가 되지 않고 검색 결과가 0건이 됩니다. + +일시는 ISO 8601 형식으로 지정합니다. 형식은 ``YYYY-MM-DDThh:mm:ss.SSSZ`` 이며, 시각 이후는 생략할 수 있습니다. + +.. list-table:: + :header-rows: 1 + + * - 지정 내용 + - 예 + * - 연월일만 + - 2012-12-02 + * - 연월일 및 시분초 + - 2012-12-02T10:45:23Z + * - 연월일 및 시분초(밀리초까지) + - 2012-12-02T10:45:23.235Z + +일시 지정에는 현재 일시를 기준으로 한 일시 연산을 사용할 수 있습니다. 사용할 수 있는 기호는 다음과 같습니다. + +.. list-table:: + :header-rows: 1 + + * - 기호 + - 의미 + * - ``now`` + - 현재 일시 + * - ``y`` / ``M`` / ``w`` / ``d`` / ``h`` / ``m`` / ``s`` + - 년 / 월 / 주 / 일 / 시 / 분 / 초 + * - ``+`` / ``-`` + - 가산 / 감산 + * - ``/`` + - 반올림(``/`` 뒤의 단위로 반올림) + +now나 일시를 기준으로 한 경우에는 +, -(가산, 감산)나 /(반올림)와 같은 기호를 붙일 수 있습니다. 다만, now가 아니라 특정 일시를 기준으로 한 경우에는 일시와 기호 사이에 ``||`` 를 넣어야 합니다(예: ``2016-01-01||+1M/d``). + +``/`` 는 ``/`` 뒤의 단위로 반올림하는 기호입니다. ``now-1d/d`` 는 오늘 몇 시에 실행하더라도 오늘 00:00에서 -1일 한 전날 00:00을 나타냅니다. + +또한 이러한 일시 연산은 검색 엔진(OpenSearch) 측에서 평가되며, 일시형 필드에 대해서만 유효합니다. + +예를 들어, last_modified 필드에 대해 현재 일시(2016년 2월 21일 20시로 가정)로부터 30일 전까지 업데이트된 문서를 검색하는 경우에는 다음과 같이 검색 양식에 입력합니다. + +:: + + last_modified:[now-30d TO now] + +위 예는 현재 일시가 2016년 2월 21일 20시(UTC)인 경우, 대략 ``[2016-01-22T20:00:00Z TO 2016-02-21T20:00:00Z]`` 범위에 해당합니다. diff --git a/ko/15.10/user/search-sort.rst b/ko/15.10/user/search-sort.rst new file mode 100644 index 000000000..43129dde5 --- /dev/null +++ b/ko/15.10/user/search-sort.rst @@ -0,0 +1,76 @@ +======== +정렬 검색 +======== + +검색 일시 등의 필드를 지정하여 검색 결과를 정렬할 수 있습니다. + +정렬 대상 필드 +--------------- + +기본적으로 다음 필드를 지정하여 정렬할 수 있습니다. + +.. list-table:: + :header-rows: 1 + + * - 필드명 + - 설명 + * - created + - 크롤링한 일시 + * - content_length + - 크롤링한 문서 크기 + * - last_modified + - 크롤링한 문서의 최종 수정 일시 + * - filename + - 파일명 + * - score + - 점수 값 + * - timestamp + - 문서를 인덱싱한 일시 + * - click_count + - 문서를 클릭한 횟수 + * - favorite_count + - 문서를 즐겨찾기한 횟수 + +표: 정렬 대상 필드 목록 + + +독자적인 필드를 정렬 대상으로 추가할 수도 있습니다. 추가하려면 ``fess_config.properties`` 의 ``query.additional.sort.fields`` 에 정렬 대상으로 하고 싶은 필드명을 쉼표(,)로 구분하여 지정합니다(초기값은 비어 있습니다). 여기서 지정한 필드는 위의 표준 필드에 추가되어 정렬에 이용할 수 있게 됩니다. 또한 정렬 대상으로 하는 필드는 사전에 인덱스에 등록되어 있어야 합니다. + +사용 방법 +------ + +검색 시 정렬 조건을 선택할 수 있습니다. 정렬 조건은 옵션 버튼을 클릭하여 표시되는 검색 옵션 대화상자에서 선택할 수 있습니다. + +|image0| + +또한 검색 필드에서 정렬하는 경우 "sort:필드명"과 같이 sort와 필드명을 콜론(:)으로 구분하여 검색 양식에 입력하여 검색합니다. + +다음은 fess를 검색어로 하여 문서 크기를 오름차순으로 정렬합니다. + +:: + + fess sort:content_length + +내림차순으로 정렬하는 경우에는 필드명 뒤에 ``.desc`` 를 붙입니다. + +:: + + fess sort:content_length.desc + +필드명 뒤에 지정할 수 있는 것은 ``.asc`` (오름차순) 또는 ``.desc`` (내림차순)이며, 생략한 경우에는 오름차순이 됩니다. + +여러 필드로 정렬하는 경우에는 다음과 같이 쉼표(,)로 구분하여 지정합니다. 먼저 지정한 필드가 우선되며, 그 값이 동일한 문서끼리는 다음 필드로 정렬됩니다. + +:: + + fess sort:content_length.desc,last_modified + +.. note:: + 검색어의 ``sort:`` 에 정렬 대상 필드 목록에 없는 필드명이나 ``asc`` · ``desc`` 이외의 정렬 순서를 지정해도 오류가 되지 않습니다. + 이 경우 ``sort:`` 는 정렬 조건으로 취급되지 않으며, 검색어 전체의 기호( ``:`` 등)를 일반 문자로 취급하여 다시 검색합니다. + 정렬되지 않을 뿐 아니라 대부분의 경우 검색 결과가 0건이 됩니다. + + 검색 API의 ``sort`` 파라미터에 같은 값을 지정한 경우에는 오류(400 Bad Request)가 됩니다. + +.. |image0| image:: ../../../resources/images/en/15.10/user/search-sort-1.png +.. pdf :width: 300 px diff --git a/ko/15.10/user/search-wildcard.rst b/ko/15.10/user/search-wildcard.rst new file mode 100644 index 000000000..15093787e --- /dev/null +++ b/ko/15.10/user/search-wildcard.rst @@ -0,0 +1,53 @@ +============== +와일드카드 검색 +============== + +검색어 내에서 1개 문자 또는 여러 문자의 와일드카드를 사용할 수 있습니다. ?는 1개 문자의 와일드카드로 지정할 수 있으며, \*는 여러 문자의 와일드카드로 지정할 수 있습니다. 와일드카드를 사용할 수 있는 대상은 단어입니다. 문장에 대한 와일드카드 검색은 할 수 없습니다. + +사용 방법 +------ + +1개 문자의 와일드카드를 사용하는 경우 다음과 같이 ?를 사용합니다. + +:: + + te?t + +위의 경우 text나 test 등, ? 위치의 임의의 한 문자에 일치합니다. + +여러 문자의 와일드카드를 사용하는 경우 다음과 같이 \*를 사용합니다. + +:: + + test* + +위의 경우 test, tests나 tester 등, \* 위치의 0자 이상의 임의의 문자열에 일치합니다. 또한, + +:: + + te*t + +와 같이 검색어 중간에서도 사용할 수 있습니다. 더 나아가, + +:: + + *test + +와 같이 검색어 앞부분에서도 와일드카드를 사용할 수 있습니다. + +필드를 지정하여 와일드카드 검색을 수행할 수도 있습니다. 다음 예에서는 title 필드에서 te로 시작하고 t로 끝나는 단어를 포함하는 문서를 검색합니다. + +:: + + title:te*t + +필드를 지정하지 않은 경우에는 title 및 content 필드를 대상으로 검색합니다. + +사용 조건 +------ + +와일드카드 검색을 사용할 때는 다음 사항에 주의하십시오. + +* 와일드카드는 인덱스에 등록된 문자열(토큰)을 대상으로 일치합니다. 검색어는 다시 분석되지 않으므로, bi-gram 등으로 인덱스를 생성한 경우 일본어는 의미를 갖지 않는 고정 길이 문자열로 처리되어 일본어에서의 와일드카드는 예상한 대로 동작하지 않습니다. 일본어로 와일드카드를 사용하는 경우에는 형태소 분석을 사용하는 필드에서 사용하십시오. +* 검색어의 앞부분이나 중간에 와일드카드(``*``·``?``)를 포함하는 패턴은 대문자와 소문자를 구분합니다. 인덱스에 등록되는 단어는 일반적으로 소문자로 변환되므로 패턴에는 소문자를 사용하십시오. 예를 들어 ``Te*t``, ``Te?t``, ``*Test`` 는 소문자로 변환되어 등록된 ``test`` 와 일치하지 않습니다. 한편 끝부분만 ``*`` 인 패턴(``Test*`` 등)은 전방 일치로 검색어가 소문자로 변환되어 분석되므로 ``Test*`` 는 ``test`` 에도 일치합니다. +* 검색어 앞부분에 와일드카드를 붙인 검색(예: ``*test``)은 인덱스 내의 모든 단어를 탐색하므로 처리에 시간이 걸릴 수 있습니다. diff --git a/ko/15.10/user/special-char.rst b/ko/15.10/user/special-char.rst new file mode 100644 index 000000000..752105619 --- /dev/null +++ b/ko/15.10/user/special-char.rst @@ -0,0 +1,91 @@ +====== +특수 문자 +====== + +다음 문자는 검색 쿼리 구문에서 특별한 의미를 가지므로 검색어에서 특수 문자로 취급됩니다. 이러한 문자를 검색 문자로 그대로 사용하려면 이스케이프해야 합니다. + +:: + + + - && || ! ( ) { } [ ] ^ " ~ * ? : \ / + +이러한 문자는 필수/제외 지정(``+`` ``-``), 불리언 연산(``&&`` ``||`` ``!``), 그룹화(``( )``), 범위 검색(``[ ]`` ``{ }``), 부스트 검색(``^``), 프레이즈 검색(``"``), 퍼지 검색·근접 검색(``~``), 와일드카드 검색(``*`` ``?``), 필드 지정 검색(``:``) 등의 검색 기능을 호출하는 데 사용됩니다. + +예를 들어 URL이나 파일 경로에 포함된 "/", ":", 프로그램 코드에 포함된 "+", "-" 등을 그대로 검색하면 의도하지 않은 검색 결과가 나올 수 있습니다. 이스케이프 방법은 아래를 참조하십시오. + + +특수 문자 목록과 의미 +------------------------ + +.. list-table:: + :header-rows: 1 + + * - 특수 문자 + - 의미・역할 + - 관련 페이지 + * - ``+`` ``-`` + - 필수어・제외어 지정(AND 검색 / NOT 검색) + - :doc:`search-and` / :doc:`search-not` + * - ``&&`` ``||`` + - AND 검색 / OR 검색 + - :doc:`search-and` / :doc:`search-or` + * - ``!`` + - NOT 검색(제외 검색) + - :doc:`search-not` + * - ``( )`` + - 검색 조건 그룹화 + - :doc:`advanced-search` + * - ``[ ]`` ``{ }`` + - 범위 지정 검색(``[ ]`` 는 경계를 포함, ``{ }`` 는 경계를 포함하지 않음) + - :doc:`search-range` + * - ``^`` + - 부스트 검색(가중치 부여) + - :doc:`search-boost` + * - ``"`` + - 프레이즈 검색(감싼 범위를 하나의 어구로 취급. 이스케이프 대신 사용 가능) + - :doc:`advanced-search` + * - ``~`` + - 유사 검색(단어 뒤) / 근접 검색(구문 뒤) + - :doc:`search-fuzzy` / :doc:`search-proximity` + * - ``*`` ``?`` + - 와일드카드 검색 + - :doc:`search-wildcard` + * - ``:`` + - 검색 필드 지정 + - :doc:`search-field` + * - ``\`` + - 이스케이프 문자 + - (본 페이지) + * - ``/`` + - 슬래시(URL 등에 포함된 경우 이스케이프 필요) + - :doc:`search-field` + + +사용 방법 +------ + +특수 문자를 검색 문자 그대로 취급하려면 다음 중 하나의 방법을 사용합니다. + +* ``\`` 를 문자 바로 앞에 붙여서 이스케이프합니다. 바로 뒤에 오는 문자 1개는 검색 구문이 아니라 일반 문자로 취급됩니다. +* ``"`` 로 검색어를 묶습니다. 묶인 문자열은 프레이즈 검색으로 취급되며, 내부의 특수 문자는 검색 구문으로 해석되지 않습니다. 단, 프레이즈 검색이 되기 때문에 와일드카드 검색(``*`` ``?``) 등의 기능은 사용할 수 없습니다. + +:: + + aaa\/bbb + "aaa/bbb" + +예를 들어 "C++"를 검색어로 사용하고 싶은 경우에는 다음과 같이 이스케이프합니다. + +:: + + C\+\+ + "C++" + + +관련 항목 +------------ + +- :doc:`search-field` - 필드 지정 검색 +- :doc:`search-wildcard` - 와일드카드 검색 +- :doc:`search-fuzzy` - 유사 검색(퍼지 검색) +- :doc:`search-proximity` - 근접 검색 +- :doc:`advanced-search` - 고급 검색 diff --git a/resources/images/en/15.10/admin/accesstoken-1.png b/resources/images/en/15.10/admin/accesstoken-1.png new file mode 100644 index 000000000..74ae80832 Binary files /dev/null and b/resources/images/en/15.10/admin/accesstoken-1.png differ diff --git a/resources/images/en/15.10/admin/accesstoken-2.png b/resources/images/en/15.10/admin/accesstoken-2.png new file mode 100644 index 000000000..77ca71681 Binary files /dev/null and b/resources/images/en/15.10/admin/accesstoken-2.png differ diff --git a/resources/images/en/15.10/admin/backup-1.png b/resources/images/en/15.10/admin/backup-1.png new file mode 100644 index 000000000..b8ec084f5 Binary files /dev/null and b/resources/images/en/15.10/admin/backup-1.png differ diff --git a/resources/images/en/15.10/admin/badword-1.png b/resources/images/en/15.10/admin/badword-1.png new file mode 100644 index 000000000..2f07d9727 Binary files /dev/null and b/resources/images/en/15.10/admin/badword-1.png differ diff --git a/resources/images/en/15.10/admin/badword-2.png b/resources/images/en/15.10/admin/badword-2.png new file mode 100644 index 000000000..e92cc2663 Binary files /dev/null and b/resources/images/en/15.10/admin/badword-2.png differ diff --git a/resources/images/en/15.10/admin/badword-3.png b/resources/images/en/15.10/admin/badword-3.png new file mode 100644 index 000000000..02a2a792a Binary files /dev/null and b/resources/images/en/15.10/admin/badword-3.png differ diff --git a/resources/images/en/15.10/admin/badword-4.png b/resources/images/en/15.10/admin/badword-4.png new file mode 100644 index 000000000..3023ce8f4 Binary files /dev/null and b/resources/images/en/15.10/admin/badword-4.png differ diff --git a/resources/images/en/15.10/admin/boostdoc-1.png b/resources/images/en/15.10/admin/boostdoc-1.png new file mode 100644 index 000000000..a65592b4b Binary files /dev/null and b/resources/images/en/15.10/admin/boostdoc-1.png differ diff --git a/resources/images/en/15.10/admin/boostdoc-2.png b/resources/images/en/15.10/admin/boostdoc-2.png new file mode 100644 index 000000000..1074f756f Binary files /dev/null and b/resources/images/en/15.10/admin/boostdoc-2.png differ diff --git a/resources/images/en/15.10/admin/crawlinginfo-1.png b/resources/images/en/15.10/admin/crawlinginfo-1.png new file mode 100644 index 000000000..412baa029 Binary files /dev/null and b/resources/images/en/15.10/admin/crawlinginfo-1.png differ diff --git a/resources/images/en/15.10/admin/crawlinginfo-2.png b/resources/images/en/15.10/admin/crawlinginfo-2.png new file mode 100644 index 000000000..8dea0daae Binary files /dev/null and b/resources/images/en/15.10/admin/crawlinginfo-2.png differ diff --git a/resources/images/en/15.10/admin/dashboard-1.png b/resources/images/en/15.10/admin/dashboard-1.png new file mode 100644 index 000000000..fa17d1b26 Binary files /dev/null and b/resources/images/en/15.10/admin/dashboard-1.png differ diff --git a/resources/images/en/15.10/admin/dashboard-2.png b/resources/images/en/15.10/admin/dashboard-2.png new file mode 100644 index 000000000..a053ad980 Binary files /dev/null and b/resources/images/en/15.10/admin/dashboard-2.png differ diff --git a/resources/images/en/15.10/admin/dataconfig-1.png b/resources/images/en/15.10/admin/dataconfig-1.png new file mode 100644 index 000000000..1f01a9c4d Binary files /dev/null and b/resources/images/en/15.10/admin/dataconfig-1.png differ diff --git a/resources/images/en/15.10/admin/dataconfig-2.png b/resources/images/en/15.10/admin/dataconfig-2.png new file mode 100644 index 000000000..478d34afd Binary files /dev/null and b/resources/images/en/15.10/admin/dataconfig-2.png differ diff --git a/resources/images/en/15.10/admin/dict-1.png b/resources/images/en/15.10/admin/dict-1.png new file mode 100644 index 000000000..7e02a9baf Binary files /dev/null and b/resources/images/en/15.10/admin/dict-1.png differ diff --git a/resources/images/en/15.10/admin/duplicatehost-1.png b/resources/images/en/15.10/admin/duplicatehost-1.png new file mode 100644 index 000000000..4604a16f3 Binary files /dev/null and b/resources/images/en/15.10/admin/duplicatehost-1.png differ diff --git a/resources/images/en/15.10/admin/duplicatehost-2.png b/resources/images/en/15.10/admin/duplicatehost-2.png new file mode 100644 index 000000000..6efb37581 Binary files /dev/null and b/resources/images/en/15.10/admin/duplicatehost-2.png differ diff --git a/resources/images/en/15.10/admin/elevateword-1.png b/resources/images/en/15.10/admin/elevateword-1.png new file mode 100644 index 000000000..b9720d918 Binary files /dev/null and b/resources/images/en/15.10/admin/elevateword-1.png differ diff --git a/resources/images/en/15.10/admin/elevateword-2.png b/resources/images/en/15.10/admin/elevateword-2.png new file mode 100644 index 000000000..46ef8fa74 Binary files /dev/null and b/resources/images/en/15.10/admin/elevateword-2.png differ diff --git a/resources/images/en/15.10/admin/elevateword-3.png b/resources/images/en/15.10/admin/elevateword-3.png new file mode 100644 index 000000000..f41bc3239 Binary files /dev/null and b/resources/images/en/15.10/admin/elevateword-3.png differ diff --git a/resources/images/en/15.10/admin/elevateword-4.png b/resources/images/en/15.10/admin/elevateword-4.png new file mode 100644 index 000000000..56a316b79 Binary files /dev/null and b/resources/images/en/15.10/admin/elevateword-4.png differ diff --git a/resources/images/en/15.10/admin/esreq-1.png b/resources/images/en/15.10/admin/esreq-1.png new file mode 100644 index 000000000..e490b3b58 Binary files /dev/null and b/resources/images/en/15.10/admin/esreq-1.png differ diff --git a/resources/images/en/15.10/admin/failureurl-1.png b/resources/images/en/15.10/admin/failureurl-1.png new file mode 100644 index 000000000..fecdbb475 Binary files /dev/null and b/resources/images/en/15.10/admin/failureurl-1.png differ diff --git a/resources/images/en/15.10/admin/failureurl-2.png b/resources/images/en/15.10/admin/failureurl-2.png new file mode 100644 index 000000000..17a4cb002 Binary files /dev/null and b/resources/images/en/15.10/admin/failureurl-2.png differ diff --git a/resources/images/en/15.10/admin/fileauth-1.png b/resources/images/en/15.10/admin/fileauth-1.png new file mode 100644 index 000000000..44bd7c93a Binary files /dev/null and b/resources/images/en/15.10/admin/fileauth-1.png differ diff --git a/resources/images/en/15.10/admin/fileauth-2.png b/resources/images/en/15.10/admin/fileauth-2.png new file mode 100644 index 000000000..8d27a14ec Binary files /dev/null and b/resources/images/en/15.10/admin/fileauth-2.png differ diff --git a/resources/images/en/15.10/admin/fileconfig-1.png b/resources/images/en/15.10/admin/fileconfig-1.png new file mode 100644 index 000000000..70c31863b Binary files /dev/null and b/resources/images/en/15.10/admin/fileconfig-1.png differ diff --git a/resources/images/en/15.10/admin/fileconfig-2.png b/resources/images/en/15.10/admin/fileconfig-2.png new file mode 100644 index 000000000..807064ac6 Binary files /dev/null and b/resources/images/en/15.10/admin/fileconfig-2.png differ diff --git a/resources/images/en/15.10/admin/general-1.png b/resources/images/en/15.10/admin/general-1.png new file mode 100644 index 000000000..0dfc80c61 Binary files /dev/null and b/resources/images/en/15.10/admin/general-1.png differ diff --git a/resources/images/en/15.10/admin/general-2.png b/resources/images/en/15.10/admin/general-2.png new file mode 100644 index 000000000..dc7300708 Binary files /dev/null and b/resources/images/en/15.10/admin/general-2.png differ diff --git a/resources/images/en/15.10/admin/general-3.png b/resources/images/en/15.10/admin/general-3.png new file mode 100644 index 000000000..cbb65de84 Binary files /dev/null and b/resources/images/en/15.10/admin/general-3.png differ diff --git a/resources/images/en/15.10/admin/general-4.png b/resources/images/en/15.10/admin/general-4.png new file mode 100644 index 000000000..ff3e28e96 Binary files /dev/null and b/resources/images/en/15.10/admin/general-4.png differ diff --git a/resources/images/en/15.10/admin/general-5.png b/resources/images/en/15.10/admin/general-5.png new file mode 100644 index 000000000..1c8a7e742 Binary files /dev/null and b/resources/images/en/15.10/admin/general-5.png differ diff --git a/resources/images/en/15.10/admin/general-6.png b/resources/images/en/15.10/admin/general-6.png new file mode 100644 index 000000000..7f148af8b Binary files /dev/null and b/resources/images/en/15.10/admin/general-6.png differ diff --git a/resources/images/en/15.10/admin/general-7.png b/resources/images/en/15.10/admin/general-7.png new file mode 100644 index 000000000..03389852c Binary files /dev/null and b/resources/images/en/15.10/admin/general-7.png differ diff --git a/resources/images/en/15.10/admin/general-8.png b/resources/images/en/15.10/admin/general-8.png new file mode 100644 index 000000000..181729164 Binary files /dev/null and b/resources/images/en/15.10/admin/general-8.png differ diff --git a/resources/images/en/15.10/admin/group-1.png b/resources/images/en/15.10/admin/group-1.png new file mode 100644 index 000000000..c3ae7fcee Binary files /dev/null and b/resources/images/en/15.10/admin/group-1.png differ diff --git a/resources/images/en/15.10/admin/group-2.png b/resources/images/en/15.10/admin/group-2.png new file mode 100644 index 000000000..7b3f3b61e Binary files /dev/null and b/resources/images/en/15.10/admin/group-2.png differ diff --git a/resources/images/en/15.10/admin/joblog-1.png b/resources/images/en/15.10/admin/joblog-1.png new file mode 100644 index 000000000..7350d5629 Binary files /dev/null and b/resources/images/en/15.10/admin/joblog-1.png differ diff --git a/resources/images/en/15.10/admin/joblog-2.png b/resources/images/en/15.10/admin/joblog-2.png new file mode 100644 index 000000000..9570803f9 Binary files /dev/null and b/resources/images/en/15.10/admin/joblog-2.png differ diff --git a/resources/images/en/15.10/admin/keymatch-1.png b/resources/images/en/15.10/admin/keymatch-1.png new file mode 100644 index 000000000..688e9e685 Binary files /dev/null and b/resources/images/en/15.10/admin/keymatch-1.png differ diff --git a/resources/images/en/15.10/admin/keymatch-2.png b/resources/images/en/15.10/admin/keymatch-2.png new file mode 100644 index 000000000..783fb5f77 Binary files /dev/null and b/resources/images/en/15.10/admin/keymatch-2.png differ diff --git a/resources/images/en/15.10/admin/kuromoji-1.png b/resources/images/en/15.10/admin/kuromoji-1.png new file mode 100644 index 000000000..8072f27d1 Binary files /dev/null and b/resources/images/en/15.10/admin/kuromoji-1.png differ diff --git a/resources/images/en/15.10/admin/kuromoji-2.png b/resources/images/en/15.10/admin/kuromoji-2.png new file mode 100644 index 000000000..d566b8134 Binary files /dev/null and b/resources/images/en/15.10/admin/kuromoji-2.png differ diff --git a/resources/images/en/15.10/admin/labeltype-1.png b/resources/images/en/15.10/admin/labeltype-1.png new file mode 100644 index 000000000..062be5996 Binary files /dev/null and b/resources/images/en/15.10/admin/labeltype-1.png differ diff --git a/resources/images/en/15.10/admin/labeltype-2.png b/resources/images/en/15.10/admin/labeltype-2.png new file mode 100644 index 000000000..bd23b3be2 Binary files /dev/null and b/resources/images/en/15.10/admin/labeltype-2.png differ diff --git a/resources/images/en/15.10/admin/log-1.png b/resources/images/en/15.10/admin/log-1.png new file mode 100644 index 000000000..979825149 Binary files /dev/null and b/resources/images/en/15.10/admin/log-1.png differ diff --git a/resources/images/en/15.10/admin/maintenance-1.png b/resources/images/en/15.10/admin/maintenance-1.png new file mode 100644 index 000000000..f4ad492af Binary files /dev/null and b/resources/images/en/15.10/admin/maintenance-1.png differ diff --git a/resources/images/en/15.10/admin/mapping-1.png b/resources/images/en/15.10/admin/mapping-1.png new file mode 100644 index 000000000..f6b758c4c Binary files /dev/null and b/resources/images/en/15.10/admin/mapping-1.png differ diff --git a/resources/images/en/15.10/admin/mapping-2.png b/resources/images/en/15.10/admin/mapping-2.png new file mode 100644 index 000000000..bddb9cd55 Binary files /dev/null and b/resources/images/en/15.10/admin/mapping-2.png differ diff --git a/resources/images/en/15.10/admin/pathmap-1.png b/resources/images/en/15.10/admin/pathmap-1.png new file mode 100644 index 000000000..4bb1b1dc5 Binary files /dev/null and b/resources/images/en/15.10/admin/pathmap-1.png differ diff --git a/resources/images/en/15.10/admin/pathmap-2.png b/resources/images/en/15.10/admin/pathmap-2.png new file mode 100644 index 000000000..08e0701dd Binary files /dev/null and b/resources/images/en/15.10/admin/pathmap-2.png differ diff --git a/resources/images/en/15.10/admin/plugin-1.png b/resources/images/en/15.10/admin/plugin-1.png new file mode 100644 index 000000000..db67f4449 Binary files /dev/null and b/resources/images/en/15.10/admin/plugin-1.png differ diff --git a/resources/images/en/15.10/admin/plugin-2.png b/resources/images/en/15.10/admin/plugin-2.png new file mode 100644 index 000000000..f316d15a4 Binary files /dev/null and b/resources/images/en/15.10/admin/plugin-2.png differ diff --git a/resources/images/en/15.10/admin/protwords-1.png b/resources/images/en/15.10/admin/protwords-1.png new file mode 100644 index 000000000..22998f09c Binary files /dev/null and b/resources/images/en/15.10/admin/protwords-1.png differ diff --git a/resources/images/en/15.10/admin/protwords-2.png b/resources/images/en/15.10/admin/protwords-2.png new file mode 100644 index 000000000..a15a2a381 Binary files /dev/null and b/resources/images/en/15.10/admin/protwords-2.png differ diff --git a/resources/images/en/15.10/admin/relatedcontent-1.png b/resources/images/en/15.10/admin/relatedcontent-1.png new file mode 100644 index 000000000..9f73036f1 Binary files /dev/null and b/resources/images/en/15.10/admin/relatedcontent-1.png differ diff --git a/resources/images/en/15.10/admin/relatedcontent-2.png b/resources/images/en/15.10/admin/relatedcontent-2.png new file mode 100644 index 000000000..fe6ea59b8 Binary files /dev/null and b/resources/images/en/15.10/admin/relatedcontent-2.png differ diff --git a/resources/images/en/15.10/admin/relatedquery-1.png b/resources/images/en/15.10/admin/relatedquery-1.png new file mode 100644 index 000000000..c7b9356e4 Binary files /dev/null and b/resources/images/en/15.10/admin/relatedquery-1.png differ diff --git a/resources/images/en/15.10/admin/relatedquery-2.png b/resources/images/en/15.10/admin/relatedquery-2.png new file mode 100644 index 000000000..3e25beded Binary files /dev/null and b/resources/images/en/15.10/admin/relatedquery-2.png differ diff --git a/resources/images/en/15.10/admin/reqheader-1.png b/resources/images/en/15.10/admin/reqheader-1.png new file mode 100644 index 000000000..f1de6c16a Binary files /dev/null and b/resources/images/en/15.10/admin/reqheader-1.png differ diff --git a/resources/images/en/15.10/admin/reqheader-2.png b/resources/images/en/15.10/admin/reqheader-2.png new file mode 100644 index 000000000..53e81df9e Binary files /dev/null and b/resources/images/en/15.10/admin/reqheader-2.png differ diff --git a/resources/images/en/15.10/admin/role-1.png b/resources/images/en/15.10/admin/role-1.png new file mode 100644 index 000000000..1ad94bc3a Binary files /dev/null and b/resources/images/en/15.10/admin/role-1.png differ diff --git a/resources/images/en/15.10/admin/role-2.png b/resources/images/en/15.10/admin/role-2.png new file mode 100644 index 000000000..221956d48 Binary files /dev/null and b/resources/images/en/15.10/admin/role-2.png differ diff --git a/resources/images/en/15.10/admin/scheduler-1.png b/resources/images/en/15.10/admin/scheduler-1.png new file mode 100644 index 000000000..f091a05ab Binary files /dev/null and b/resources/images/en/15.10/admin/scheduler-1.png differ diff --git a/resources/images/en/15.10/admin/scheduler-2.png b/resources/images/en/15.10/admin/scheduler-2.png new file mode 100644 index 000000000..bb0146af4 Binary files /dev/null and b/resources/images/en/15.10/admin/scheduler-2.png differ diff --git a/resources/images/en/15.10/admin/searchlist-1.png b/resources/images/en/15.10/admin/searchlist-1.png new file mode 100644 index 000000000..41e6606b9 Binary files /dev/null and b/resources/images/en/15.10/admin/searchlist-1.png differ diff --git a/resources/images/en/15.10/admin/searchlog-1.png b/resources/images/en/15.10/admin/searchlog-1.png new file mode 100644 index 000000000..f3221f429 Binary files /dev/null and b/resources/images/en/15.10/admin/searchlog-1.png differ diff --git a/resources/images/en/15.10/admin/searchlog-2.png b/resources/images/en/15.10/admin/searchlog-2.png new file mode 100644 index 000000000..dd02fb5e4 Binary files /dev/null and b/resources/images/en/15.10/admin/searchlog-2.png differ diff --git a/resources/images/en/15.10/admin/stemmeroverride-1.png b/resources/images/en/15.10/admin/stemmeroverride-1.png new file mode 100644 index 000000000..b19c3f51b Binary files /dev/null and b/resources/images/en/15.10/admin/stemmeroverride-1.png differ diff --git a/resources/images/en/15.10/admin/stemmeroverride-2.png b/resources/images/en/15.10/admin/stemmeroverride-2.png new file mode 100644 index 000000000..fb811e73a Binary files /dev/null and b/resources/images/en/15.10/admin/stemmeroverride-2.png differ diff --git a/resources/images/en/15.10/admin/stopwords-1.png b/resources/images/en/15.10/admin/stopwords-1.png new file mode 100644 index 000000000..b7ae37a9c Binary files /dev/null and b/resources/images/en/15.10/admin/stopwords-1.png differ diff --git a/resources/images/en/15.10/admin/stopwords-2.png b/resources/images/en/15.10/admin/stopwords-2.png new file mode 100644 index 000000000..c6426a419 Binary files /dev/null and b/resources/images/en/15.10/admin/stopwords-2.png differ diff --git a/resources/images/en/15.10/admin/storage-1.png b/resources/images/en/15.10/admin/storage-1.png new file mode 100644 index 000000000..771e7eaf6 Binary files /dev/null and b/resources/images/en/15.10/admin/storage-1.png differ diff --git a/resources/images/en/15.10/admin/suggest-1.png b/resources/images/en/15.10/admin/suggest-1.png new file mode 100644 index 000000000..0afde0e8b Binary files /dev/null and b/resources/images/en/15.10/admin/suggest-1.png differ diff --git a/resources/images/en/15.10/admin/synonym-1.png b/resources/images/en/15.10/admin/synonym-1.png new file mode 100644 index 000000000..71ce14dbc Binary files /dev/null and b/resources/images/en/15.10/admin/synonym-1.png differ diff --git a/resources/images/en/15.10/admin/synonym-2.png b/resources/images/en/15.10/admin/synonym-2.png new file mode 100644 index 000000000..355086be5 Binary files /dev/null and b/resources/images/en/15.10/admin/synonym-2.png differ diff --git a/resources/images/en/15.10/admin/systeminfo-1.png b/resources/images/en/15.10/admin/systeminfo-1.png new file mode 100644 index 000000000..ea0b654b7 Binary files /dev/null and b/resources/images/en/15.10/admin/systeminfo-1.png differ diff --git a/resources/images/en/15.10/admin/upgrade-1.png b/resources/images/en/15.10/admin/upgrade-1.png new file mode 100644 index 000000000..b44ec3ae3 Binary files /dev/null and b/resources/images/en/15.10/admin/upgrade-1.png differ diff --git a/resources/images/en/15.10/admin/user-1.png b/resources/images/en/15.10/admin/user-1.png new file mode 100644 index 000000000..e73c69ca9 Binary files /dev/null and b/resources/images/en/15.10/admin/user-1.png differ diff --git a/resources/images/en/15.10/admin/user-2.png b/resources/images/en/15.10/admin/user-2.png new file mode 100644 index 000000000..2a25b5e36 Binary files /dev/null and b/resources/images/en/15.10/admin/user-2.png differ diff --git a/resources/images/en/15.10/admin/webauth-1.png b/resources/images/en/15.10/admin/webauth-1.png new file mode 100644 index 000000000..2172cc13c Binary files /dev/null and b/resources/images/en/15.10/admin/webauth-1.png differ diff --git a/resources/images/en/15.10/admin/webauth-2.png b/resources/images/en/15.10/admin/webauth-2.png new file mode 100644 index 000000000..ade3f6791 Binary files /dev/null and b/resources/images/en/15.10/admin/webauth-2.png differ diff --git a/resources/images/en/15.10/admin/webconfig-1.png b/resources/images/en/15.10/admin/webconfig-1.png new file mode 100644 index 000000000..6b9b143db Binary files /dev/null and b/resources/images/en/15.10/admin/webconfig-1.png differ diff --git a/resources/images/en/15.10/admin/webconfig-2.png b/resources/images/en/15.10/admin/webconfig-2.png new file mode 100644 index 000000000..e5e68c192 Binary files /dev/null and b/resources/images/en/15.10/admin/webconfig-2.png differ diff --git a/resources/images/en/15.10/admin/wizard-1.png b/resources/images/en/15.10/admin/wizard-1.png new file mode 100644 index 000000000..4e61f1caf Binary files /dev/null and b/resources/images/en/15.10/admin/wizard-1.png differ diff --git a/resources/images/en/15.10/admin/wizard-2.png b/resources/images/en/15.10/admin/wizard-2.png new file mode 100644 index 000000000..439934123 Binary files /dev/null and b/resources/images/en/15.10/admin/wizard-2.png differ diff --git a/resources/images/en/15.10/admin/wizard-3.png b/resources/images/en/15.10/admin/wizard-3.png new file mode 100644 index 000000000..d30637277 Binary files /dev/null and b/resources/images/en/15.10/admin/wizard-3.png differ diff --git a/resources/images/en/15.10/user/advanced-search-1.png b/resources/images/en/15.10/user/advanced-search-1.png new file mode 100644 index 000000000..a41ba964c Binary files /dev/null and b/resources/images/en/15.10/user/advanced-search-1.png differ diff --git a/resources/images/en/15.10/user/fess-ss-1.png b/resources/images/en/15.10/user/fess-ss-1.png new file mode 100644 index 000000000..c71cee357 Binary files /dev/null and b/resources/images/en/15.10/user/fess-ss-1.png differ diff --git a/resources/images/en/15.10/user/search-label-1.png b/resources/images/en/15.10/user/search-label-1.png new file mode 100644 index 000000000..19c705984 Binary files /dev/null and b/resources/images/en/15.10/user/search-label-1.png differ diff --git a/resources/images/en/15.10/user/search-sort-1.png b/resources/images/en/15.10/user/search-sort-1.png new file mode 100644 index 000000000..b11c81a74 Binary files /dev/null and b/resources/images/en/15.10/user/search-sort-1.png differ diff --git a/resources/images/ja/15.10/admin/accesstoken-1.png b/resources/images/ja/15.10/admin/accesstoken-1.png new file mode 100644 index 000000000..0a1fbd670 Binary files /dev/null and b/resources/images/ja/15.10/admin/accesstoken-1.png differ diff --git a/resources/images/ja/15.10/admin/accesstoken-2.png b/resources/images/ja/15.10/admin/accesstoken-2.png new file mode 100644 index 000000000..2dd32b292 Binary files /dev/null and b/resources/images/ja/15.10/admin/accesstoken-2.png differ diff --git a/resources/images/ja/15.10/admin/backup-1.png b/resources/images/ja/15.10/admin/backup-1.png new file mode 100644 index 000000000..78435bf29 Binary files /dev/null and b/resources/images/ja/15.10/admin/backup-1.png differ diff --git a/resources/images/ja/15.10/admin/badword-1.png b/resources/images/ja/15.10/admin/badword-1.png new file mode 100644 index 000000000..42fe8365a Binary files /dev/null and b/resources/images/ja/15.10/admin/badword-1.png differ diff --git a/resources/images/ja/15.10/admin/badword-2.png b/resources/images/ja/15.10/admin/badword-2.png new file mode 100644 index 000000000..930335d5d Binary files /dev/null and b/resources/images/ja/15.10/admin/badword-2.png differ diff --git a/resources/images/ja/15.10/admin/badword-3.png b/resources/images/ja/15.10/admin/badword-3.png new file mode 100644 index 000000000..d78a79110 Binary files /dev/null and b/resources/images/ja/15.10/admin/badword-3.png differ diff --git a/resources/images/ja/15.10/admin/badword-4.png b/resources/images/ja/15.10/admin/badword-4.png new file mode 100644 index 000000000..26d245bde Binary files /dev/null and b/resources/images/ja/15.10/admin/badword-4.png differ diff --git a/resources/images/ja/15.10/admin/boostdoc-1.png b/resources/images/ja/15.10/admin/boostdoc-1.png new file mode 100644 index 000000000..f7af02b28 Binary files /dev/null and b/resources/images/ja/15.10/admin/boostdoc-1.png differ diff --git a/resources/images/ja/15.10/admin/boostdoc-2.png b/resources/images/ja/15.10/admin/boostdoc-2.png new file mode 100644 index 000000000..44c8c7d2f Binary files /dev/null and b/resources/images/ja/15.10/admin/boostdoc-2.png differ diff --git a/resources/images/ja/15.10/admin/crawlinginfo-1.png b/resources/images/ja/15.10/admin/crawlinginfo-1.png new file mode 100644 index 000000000..aa69642df Binary files /dev/null and b/resources/images/ja/15.10/admin/crawlinginfo-1.png differ diff --git a/resources/images/ja/15.10/admin/crawlinginfo-2.png b/resources/images/ja/15.10/admin/crawlinginfo-2.png new file mode 100644 index 000000000..2266c69e8 Binary files /dev/null and b/resources/images/ja/15.10/admin/crawlinginfo-2.png differ diff --git a/resources/images/ja/15.10/admin/dashboard-1.png b/resources/images/ja/15.10/admin/dashboard-1.png new file mode 100644 index 000000000..80d7cdbaa Binary files /dev/null and b/resources/images/ja/15.10/admin/dashboard-1.png differ diff --git a/resources/images/ja/15.10/admin/dashboard-2.png b/resources/images/ja/15.10/admin/dashboard-2.png new file mode 100644 index 000000000..a6a159809 Binary files /dev/null and b/resources/images/ja/15.10/admin/dashboard-2.png differ diff --git a/resources/images/ja/15.10/admin/dataconfig-1.png b/resources/images/ja/15.10/admin/dataconfig-1.png new file mode 100644 index 000000000..2f11eb7f7 Binary files /dev/null and b/resources/images/ja/15.10/admin/dataconfig-1.png differ diff --git a/resources/images/ja/15.10/admin/dataconfig-2.png b/resources/images/ja/15.10/admin/dataconfig-2.png new file mode 100644 index 000000000..a4d7d916b Binary files /dev/null and b/resources/images/ja/15.10/admin/dataconfig-2.png differ diff --git a/resources/images/ja/15.10/admin/dict-1.png b/resources/images/ja/15.10/admin/dict-1.png new file mode 100644 index 000000000..1e25326c2 Binary files /dev/null and b/resources/images/ja/15.10/admin/dict-1.png differ diff --git a/resources/images/ja/15.10/admin/duplicatehost-1.png b/resources/images/ja/15.10/admin/duplicatehost-1.png new file mode 100644 index 000000000..18a54de1b Binary files /dev/null and b/resources/images/ja/15.10/admin/duplicatehost-1.png differ diff --git a/resources/images/ja/15.10/admin/duplicatehost-2.png b/resources/images/ja/15.10/admin/duplicatehost-2.png new file mode 100644 index 000000000..cfe2f17ea Binary files /dev/null and b/resources/images/ja/15.10/admin/duplicatehost-2.png differ diff --git a/resources/images/ja/15.10/admin/elevateword-1.png b/resources/images/ja/15.10/admin/elevateword-1.png new file mode 100644 index 000000000..319c0265d Binary files /dev/null and b/resources/images/ja/15.10/admin/elevateword-1.png differ diff --git a/resources/images/ja/15.10/admin/elevateword-2.png b/resources/images/ja/15.10/admin/elevateword-2.png new file mode 100644 index 000000000..5bb6cfc1e Binary files /dev/null and b/resources/images/ja/15.10/admin/elevateword-2.png differ diff --git a/resources/images/ja/15.10/admin/elevateword-3.png b/resources/images/ja/15.10/admin/elevateword-3.png new file mode 100644 index 000000000..f6ec97582 Binary files /dev/null and b/resources/images/ja/15.10/admin/elevateword-3.png differ diff --git a/resources/images/ja/15.10/admin/elevateword-4.png b/resources/images/ja/15.10/admin/elevateword-4.png new file mode 100644 index 000000000..8a4d8debe Binary files /dev/null and b/resources/images/ja/15.10/admin/elevateword-4.png differ diff --git a/resources/images/ja/15.10/admin/esreq-1.png b/resources/images/ja/15.10/admin/esreq-1.png new file mode 100644 index 000000000..78c41cc3a Binary files /dev/null and b/resources/images/ja/15.10/admin/esreq-1.png differ diff --git a/resources/images/ja/15.10/admin/failureurl-1.png b/resources/images/ja/15.10/admin/failureurl-1.png new file mode 100644 index 000000000..656a40515 Binary files /dev/null and b/resources/images/ja/15.10/admin/failureurl-1.png differ diff --git a/resources/images/ja/15.10/admin/failureurl-2.png b/resources/images/ja/15.10/admin/failureurl-2.png new file mode 100644 index 000000000..468135eed Binary files /dev/null and b/resources/images/ja/15.10/admin/failureurl-2.png differ diff --git a/resources/images/ja/15.10/admin/fileauth-1.png b/resources/images/ja/15.10/admin/fileauth-1.png new file mode 100644 index 000000000..f67ef8240 Binary files /dev/null and b/resources/images/ja/15.10/admin/fileauth-1.png differ diff --git a/resources/images/ja/15.10/admin/fileauth-2.png b/resources/images/ja/15.10/admin/fileauth-2.png new file mode 100644 index 000000000..b447f8eeb Binary files /dev/null and b/resources/images/ja/15.10/admin/fileauth-2.png differ diff --git a/resources/images/ja/15.10/admin/fileconfig-1.png b/resources/images/ja/15.10/admin/fileconfig-1.png new file mode 100644 index 000000000..209b5e4bb Binary files /dev/null and b/resources/images/ja/15.10/admin/fileconfig-1.png differ diff --git a/resources/images/ja/15.10/admin/fileconfig-2.png b/resources/images/ja/15.10/admin/fileconfig-2.png new file mode 100644 index 000000000..ddd4ff67f Binary files /dev/null and b/resources/images/ja/15.10/admin/fileconfig-2.png differ diff --git a/resources/images/ja/15.10/admin/general-1.png b/resources/images/ja/15.10/admin/general-1.png new file mode 100644 index 000000000..b028a8e9e Binary files /dev/null and b/resources/images/ja/15.10/admin/general-1.png differ diff --git a/resources/images/ja/15.10/admin/general-2.png b/resources/images/ja/15.10/admin/general-2.png new file mode 100644 index 000000000..251ec119f Binary files /dev/null and b/resources/images/ja/15.10/admin/general-2.png differ diff --git a/resources/images/ja/15.10/admin/general-3.png b/resources/images/ja/15.10/admin/general-3.png new file mode 100644 index 000000000..5ab35caec Binary files /dev/null and b/resources/images/ja/15.10/admin/general-3.png differ diff --git a/resources/images/ja/15.10/admin/general-4.png b/resources/images/ja/15.10/admin/general-4.png new file mode 100644 index 000000000..a0c33f23e Binary files /dev/null and b/resources/images/ja/15.10/admin/general-4.png differ diff --git a/resources/images/ja/15.10/admin/general-5.png b/resources/images/ja/15.10/admin/general-5.png new file mode 100644 index 000000000..67041a739 Binary files /dev/null and b/resources/images/ja/15.10/admin/general-5.png differ diff --git a/resources/images/ja/15.10/admin/general-6.png b/resources/images/ja/15.10/admin/general-6.png new file mode 100644 index 000000000..80c94c9cf Binary files /dev/null and b/resources/images/ja/15.10/admin/general-6.png differ diff --git a/resources/images/ja/15.10/admin/general-7.png b/resources/images/ja/15.10/admin/general-7.png new file mode 100644 index 000000000..05d92ed50 Binary files /dev/null and b/resources/images/ja/15.10/admin/general-7.png differ diff --git a/resources/images/ja/15.10/admin/general-8.png b/resources/images/ja/15.10/admin/general-8.png new file mode 100644 index 000000000..b64fd8ccf Binary files /dev/null and b/resources/images/ja/15.10/admin/general-8.png differ diff --git a/resources/images/ja/15.10/admin/group-1.png b/resources/images/ja/15.10/admin/group-1.png new file mode 100644 index 000000000..ebc54257e Binary files /dev/null and b/resources/images/ja/15.10/admin/group-1.png differ diff --git a/resources/images/ja/15.10/admin/group-2.png b/resources/images/ja/15.10/admin/group-2.png new file mode 100644 index 000000000..f9defb7e6 Binary files /dev/null and b/resources/images/ja/15.10/admin/group-2.png differ diff --git a/resources/images/ja/15.10/admin/joblog-1.png b/resources/images/ja/15.10/admin/joblog-1.png new file mode 100644 index 000000000..03b99f2c3 Binary files /dev/null and b/resources/images/ja/15.10/admin/joblog-1.png differ diff --git a/resources/images/ja/15.10/admin/joblog-2.png b/resources/images/ja/15.10/admin/joblog-2.png new file mode 100644 index 000000000..7c0f16491 Binary files /dev/null and b/resources/images/ja/15.10/admin/joblog-2.png differ diff --git a/resources/images/ja/15.10/admin/keymatch-1.png b/resources/images/ja/15.10/admin/keymatch-1.png new file mode 100644 index 000000000..d5faf9c75 Binary files /dev/null and b/resources/images/ja/15.10/admin/keymatch-1.png differ diff --git a/resources/images/ja/15.10/admin/keymatch-2.png b/resources/images/ja/15.10/admin/keymatch-2.png new file mode 100644 index 000000000..0989b251a Binary files /dev/null and b/resources/images/ja/15.10/admin/keymatch-2.png differ diff --git a/resources/images/ja/15.10/admin/kuromoji-1.png b/resources/images/ja/15.10/admin/kuromoji-1.png new file mode 100644 index 000000000..fe664120d Binary files /dev/null and b/resources/images/ja/15.10/admin/kuromoji-1.png differ diff --git a/resources/images/ja/15.10/admin/kuromoji-2.png b/resources/images/ja/15.10/admin/kuromoji-2.png new file mode 100644 index 000000000..488000c06 Binary files /dev/null and b/resources/images/ja/15.10/admin/kuromoji-2.png differ diff --git a/resources/images/ja/15.10/admin/labeltype-1.png b/resources/images/ja/15.10/admin/labeltype-1.png new file mode 100644 index 000000000..f53815247 Binary files /dev/null and b/resources/images/ja/15.10/admin/labeltype-1.png differ diff --git a/resources/images/ja/15.10/admin/labeltype-2.png b/resources/images/ja/15.10/admin/labeltype-2.png new file mode 100644 index 000000000..26d714e58 Binary files /dev/null and b/resources/images/ja/15.10/admin/labeltype-2.png differ diff --git a/resources/images/ja/15.10/admin/log-1.png b/resources/images/ja/15.10/admin/log-1.png new file mode 100644 index 000000000..cb2460be0 Binary files /dev/null and b/resources/images/ja/15.10/admin/log-1.png differ diff --git a/resources/images/ja/15.10/admin/maintenance-1.png b/resources/images/ja/15.10/admin/maintenance-1.png new file mode 100644 index 000000000..5e8cd8327 Binary files /dev/null and b/resources/images/ja/15.10/admin/maintenance-1.png differ diff --git a/resources/images/ja/15.10/admin/mapping-1.png b/resources/images/ja/15.10/admin/mapping-1.png new file mode 100644 index 000000000..aba4beb65 Binary files /dev/null and b/resources/images/ja/15.10/admin/mapping-1.png differ diff --git a/resources/images/ja/15.10/admin/mapping-2.png b/resources/images/ja/15.10/admin/mapping-2.png new file mode 100644 index 000000000..19d087749 Binary files /dev/null and b/resources/images/ja/15.10/admin/mapping-2.png differ diff --git a/resources/images/ja/15.10/admin/pathmap-1.png b/resources/images/ja/15.10/admin/pathmap-1.png new file mode 100644 index 000000000..012fad19a Binary files /dev/null and b/resources/images/ja/15.10/admin/pathmap-1.png differ diff --git a/resources/images/ja/15.10/admin/pathmap-2.png b/resources/images/ja/15.10/admin/pathmap-2.png new file mode 100644 index 000000000..2ac12e57b Binary files /dev/null and b/resources/images/ja/15.10/admin/pathmap-2.png differ diff --git a/resources/images/ja/15.10/admin/plugin-1.png b/resources/images/ja/15.10/admin/plugin-1.png new file mode 100644 index 000000000..da1394b6f Binary files /dev/null and b/resources/images/ja/15.10/admin/plugin-1.png differ diff --git a/resources/images/ja/15.10/admin/plugin-2.png b/resources/images/ja/15.10/admin/plugin-2.png new file mode 100644 index 000000000..a72a0ebda Binary files /dev/null and b/resources/images/ja/15.10/admin/plugin-2.png differ diff --git a/resources/images/ja/15.10/admin/protwords-1.png b/resources/images/ja/15.10/admin/protwords-1.png new file mode 100644 index 000000000..de4a7ca55 Binary files /dev/null and b/resources/images/ja/15.10/admin/protwords-1.png differ diff --git a/resources/images/ja/15.10/admin/protwords-2.png b/resources/images/ja/15.10/admin/protwords-2.png new file mode 100644 index 000000000..029e37a3f Binary files /dev/null and b/resources/images/ja/15.10/admin/protwords-2.png differ diff --git a/resources/images/ja/15.10/admin/relatedcontent-1.png b/resources/images/ja/15.10/admin/relatedcontent-1.png new file mode 100644 index 000000000..dac67e913 Binary files /dev/null and b/resources/images/ja/15.10/admin/relatedcontent-1.png differ diff --git a/resources/images/ja/15.10/admin/relatedcontent-2.png b/resources/images/ja/15.10/admin/relatedcontent-2.png new file mode 100644 index 000000000..ea7b51d7a Binary files /dev/null and b/resources/images/ja/15.10/admin/relatedcontent-2.png differ diff --git a/resources/images/ja/15.10/admin/relatedquery-1.png b/resources/images/ja/15.10/admin/relatedquery-1.png new file mode 100644 index 000000000..cc6b1380c Binary files /dev/null and b/resources/images/ja/15.10/admin/relatedquery-1.png differ diff --git a/resources/images/ja/15.10/admin/relatedquery-2.png b/resources/images/ja/15.10/admin/relatedquery-2.png new file mode 100644 index 000000000..23659d58a Binary files /dev/null and b/resources/images/ja/15.10/admin/relatedquery-2.png differ diff --git a/resources/images/ja/15.10/admin/reqheader-1.png b/resources/images/ja/15.10/admin/reqheader-1.png new file mode 100644 index 000000000..e91a1bd70 Binary files /dev/null and b/resources/images/ja/15.10/admin/reqheader-1.png differ diff --git a/resources/images/ja/15.10/admin/reqheader-2.png b/resources/images/ja/15.10/admin/reqheader-2.png new file mode 100644 index 000000000..bb9452cfa Binary files /dev/null and b/resources/images/ja/15.10/admin/reqheader-2.png differ diff --git a/resources/images/ja/15.10/admin/role-1.png b/resources/images/ja/15.10/admin/role-1.png new file mode 100644 index 000000000..cf12fbd3a Binary files /dev/null and b/resources/images/ja/15.10/admin/role-1.png differ diff --git a/resources/images/ja/15.10/admin/role-2.png b/resources/images/ja/15.10/admin/role-2.png new file mode 100644 index 000000000..c025b2b16 Binary files /dev/null and b/resources/images/ja/15.10/admin/role-2.png differ diff --git a/resources/images/ja/15.10/admin/scheduler-1.png b/resources/images/ja/15.10/admin/scheduler-1.png new file mode 100644 index 000000000..36c91251a Binary files /dev/null and b/resources/images/ja/15.10/admin/scheduler-1.png differ diff --git a/resources/images/ja/15.10/admin/scheduler-2.png b/resources/images/ja/15.10/admin/scheduler-2.png new file mode 100644 index 000000000..d780c5fab Binary files /dev/null and b/resources/images/ja/15.10/admin/scheduler-2.png differ diff --git a/resources/images/ja/15.10/admin/searchlist-1.png b/resources/images/ja/15.10/admin/searchlist-1.png new file mode 100644 index 000000000..0efc01db9 Binary files /dev/null and b/resources/images/ja/15.10/admin/searchlist-1.png differ diff --git a/resources/images/ja/15.10/admin/searchlog-1.png b/resources/images/ja/15.10/admin/searchlog-1.png new file mode 100644 index 000000000..3d3a7b818 Binary files /dev/null and b/resources/images/ja/15.10/admin/searchlog-1.png differ diff --git a/resources/images/ja/15.10/admin/searchlog-2.png b/resources/images/ja/15.10/admin/searchlog-2.png new file mode 100644 index 000000000..707aa1931 Binary files /dev/null and b/resources/images/ja/15.10/admin/searchlog-2.png differ diff --git a/resources/images/ja/15.10/admin/stemmeroverride-1.png b/resources/images/ja/15.10/admin/stemmeroverride-1.png new file mode 100644 index 000000000..448f816cc Binary files /dev/null and b/resources/images/ja/15.10/admin/stemmeroverride-1.png differ diff --git a/resources/images/ja/15.10/admin/stemmeroverride-2.png b/resources/images/ja/15.10/admin/stemmeroverride-2.png new file mode 100644 index 000000000..8bfbac072 Binary files /dev/null and b/resources/images/ja/15.10/admin/stemmeroverride-2.png differ diff --git a/resources/images/ja/15.10/admin/stopwords-1.png b/resources/images/ja/15.10/admin/stopwords-1.png new file mode 100644 index 000000000..75f8266a4 Binary files /dev/null and b/resources/images/ja/15.10/admin/stopwords-1.png differ diff --git a/resources/images/ja/15.10/admin/stopwords-2.png b/resources/images/ja/15.10/admin/stopwords-2.png new file mode 100644 index 000000000..dd4f034a8 Binary files /dev/null and b/resources/images/ja/15.10/admin/stopwords-2.png differ diff --git a/resources/images/ja/15.10/admin/storage-1.png b/resources/images/ja/15.10/admin/storage-1.png new file mode 100644 index 000000000..ca2c602d8 Binary files /dev/null and b/resources/images/ja/15.10/admin/storage-1.png differ diff --git a/resources/images/ja/15.10/admin/suggest-1.png b/resources/images/ja/15.10/admin/suggest-1.png new file mode 100644 index 000000000..819fd8c8c Binary files /dev/null and b/resources/images/ja/15.10/admin/suggest-1.png differ diff --git a/resources/images/ja/15.10/admin/synonym-1.png b/resources/images/ja/15.10/admin/synonym-1.png new file mode 100644 index 000000000..33396eb10 Binary files /dev/null and b/resources/images/ja/15.10/admin/synonym-1.png differ diff --git a/resources/images/ja/15.10/admin/synonym-2.png b/resources/images/ja/15.10/admin/synonym-2.png new file mode 100644 index 000000000..310d18f7d Binary files /dev/null and b/resources/images/ja/15.10/admin/synonym-2.png differ diff --git a/resources/images/ja/15.10/admin/systeminfo-1.png b/resources/images/ja/15.10/admin/systeminfo-1.png new file mode 100644 index 000000000..03ba225a4 Binary files /dev/null and b/resources/images/ja/15.10/admin/systeminfo-1.png differ diff --git a/resources/images/ja/15.10/admin/upgrade-1.png b/resources/images/ja/15.10/admin/upgrade-1.png new file mode 100644 index 000000000..37e912f7e Binary files /dev/null and b/resources/images/ja/15.10/admin/upgrade-1.png differ diff --git a/resources/images/ja/15.10/admin/user-1.png b/resources/images/ja/15.10/admin/user-1.png new file mode 100644 index 000000000..607484cae Binary files /dev/null and b/resources/images/ja/15.10/admin/user-1.png differ diff --git a/resources/images/ja/15.10/admin/user-2.png b/resources/images/ja/15.10/admin/user-2.png new file mode 100644 index 000000000..b4e43b67d Binary files /dev/null and b/resources/images/ja/15.10/admin/user-2.png differ diff --git a/resources/images/ja/15.10/admin/webauth-1.png b/resources/images/ja/15.10/admin/webauth-1.png new file mode 100644 index 000000000..79de12d99 Binary files /dev/null and b/resources/images/ja/15.10/admin/webauth-1.png differ diff --git a/resources/images/ja/15.10/admin/webauth-2.png b/resources/images/ja/15.10/admin/webauth-2.png new file mode 100644 index 000000000..dd5a26e4f Binary files /dev/null and b/resources/images/ja/15.10/admin/webauth-2.png differ diff --git a/resources/images/ja/15.10/admin/webconfig-1.png b/resources/images/ja/15.10/admin/webconfig-1.png new file mode 100644 index 000000000..107bd01dd Binary files /dev/null and b/resources/images/ja/15.10/admin/webconfig-1.png differ diff --git a/resources/images/ja/15.10/admin/webconfig-2.png b/resources/images/ja/15.10/admin/webconfig-2.png new file mode 100644 index 000000000..fef997412 Binary files /dev/null and b/resources/images/ja/15.10/admin/webconfig-2.png differ diff --git a/resources/images/ja/15.10/admin/wizard-1.png b/resources/images/ja/15.10/admin/wizard-1.png new file mode 100644 index 000000000..cc8ef2cfc Binary files /dev/null and b/resources/images/ja/15.10/admin/wizard-1.png differ diff --git a/resources/images/ja/15.10/admin/wizard-2.png b/resources/images/ja/15.10/admin/wizard-2.png new file mode 100644 index 000000000..04caed609 Binary files /dev/null and b/resources/images/ja/15.10/admin/wizard-2.png differ diff --git a/resources/images/ja/15.10/admin/wizard-3.png b/resources/images/ja/15.10/admin/wizard-3.png new file mode 100644 index 000000000..23de7f952 Binary files /dev/null and b/resources/images/ja/15.10/admin/wizard-3.png differ diff --git a/resources/images/ja/15.10/config/search-result.png b/resources/images/ja/15.10/config/search-result.png new file mode 100644 index 000000000..1e2a91c5a Binary files /dev/null and b/resources/images/ja/15.10/config/search-result.png differ diff --git a/resources/images/ja/15.10/user/advanced-search-1.png b/resources/images/ja/15.10/user/advanced-search-1.png new file mode 100644 index 000000000..c95a264d8 Binary files /dev/null and b/resources/images/ja/15.10/user/advanced-search-1.png differ diff --git a/resources/images/ja/15.10/user/role-search-1.png b/resources/images/ja/15.10/user/role-search-1.png new file mode 100644 index 000000000..024caa3cb Binary files /dev/null and b/resources/images/ja/15.10/user/role-search-1.png differ diff --git a/resources/images/ja/15.10/user/role-search-2.png b/resources/images/ja/15.10/user/role-search-2.png new file mode 100644 index 000000000..c6c6e58de Binary files /dev/null and b/resources/images/ja/15.10/user/role-search-2.png differ diff --git a/resources/images/ja/15.10/user/search-label-1.png b/resources/images/ja/15.10/user/search-label-1.png new file mode 100644 index 000000000..dedafa004 Binary files /dev/null and b/resources/images/ja/15.10/user/search-label-1.png differ diff --git a/resources/images/ja/15.10/user/search-sort-1.png b/resources/images/ja/15.10/user/search-sort-1.png new file mode 100644 index 000000000..7bbd42a1a Binary files /dev/null and b/resources/images/ja/15.10/user/search-sort-1.png differ diff --git a/versions.json b/versions.json index a0d84dc30..919461cac 100644 --- a/versions.json +++ b/versions.json @@ -1,7 +1,7 @@ { "_comment": "Which Fess documentation versions are current, and when each one reaches end of life. The maintenance tables in /eol.rst are generated from this file by tools/update_eol.py -- edit here, not there.", "release": "15.9", - "development": "15.9", + "development": "15.10", "supported": [ "15.0", "15.1", diff --git a/zh-cn/15.10/admin/accesstoken-guide.rst b/zh-cn/15.10/admin/accesstoken-guide.rst new file mode 100644 index 000000000..35d194242 --- /dev/null +++ b/zh-cn/15.10/admin/accesstoken-guide.rst @@ -0,0 +1,80 @@ +============ +访问令牌 +============ + +概述 +==== + +访问令牌配置页面用于管理访问令牌。 + +管理方法 +====== + +显示方法 +------ + +要打开下图所示的访问令牌配置列表页面,请单击左侧菜单中的[系统 > 访问令牌]。 + +|image0| + +单击配置名称进行编辑。 + +创建配置 +-------- + +要打开访问令牌配置页面,请单击"新建"按钮。 + +|image1| + +配置项 +------ + +名称 +:::: + +指定用于描述此访问令牌的名称。 + +权限 +::::::::::: + +设置访问令牌的权限。 +以 ``{user|group|role}name`` 格式描述。 +例如,要让属于 developer 组的用户显示搜索结果,请将权限设置为"{group}developer"。 + +.. warning:: + + 将权限指定为 ``{role}admin-api`` 的访问令牌(内部以 ``Radmin-api`` 保存)可以使用 Admin API 的所有端点。详情请参见 :doc:`../api/admin/api-admin-overview`。拥有 ``admin-accesstoken`` 角色的用户可以颁发此类令牌,拥有 ``admin-accesstoken-view`` 角色的用户可以显示令牌的值,因此请将这两个角色视同管理员角色,仅授予受信任的运维人员。 + +参数名称 +::::::::::: + +指定作为搜索查询指定权限时的请求参数名称。 + +.. warning:: + + 参数名称功能仅适用于受信任的内部环境。 + 启用此功能后,可以通过URL参数指定额外的权限。 + 但是,在外部可访问的环境中或作为公共API公开时, + 恶意用户可能会操纵URL参数以提升到他们本不应拥有的权限。 + + 请注意以下几点: + + * 仅当Fess嵌入在完全控制入站请求的其他应用程序或服务中时才使用此功能。 + * 当Fess暴露于不受信任的网络时,请勿配置参数名称。 + * 使用访问令牌时,请确保外部用户无法操纵URL参数。 + +有效期 +:::::: + +指定访问令牌的有效期。 + +删除配置 +-------- + +在列表页面单击配置名称,然后单击"删除"按钮,将显示确认界面。 +单击"删除"按钮后,配置将被删除。 + + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/accesstoken-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/accesstoken-2.png diff --git a/zh-cn/15.10/admin/backup-guide.rst b/zh-cn/15.10/admin/backup-guide.rst new file mode 100644 index 000000000..2ff6e97ab --- /dev/null +++ b/zh-cn/15.10/admin/backup-guide.rst @@ -0,0 +1,108 @@ +========= +备份 +========= + +概述 +==== + +在备份页面可以下载和上传 |Fess| 的配置信息。 + +下载 +--------- + +|Fess| 将配置信息保存为索引。 +要下载，请点击索引名称。 + +|image0| + +.. note:: + + 词典（同义词、停用词等）文件不包含在备份中。 + 词典文件保存在搜索引擎的词典目录（ ``FESS_DICTIONARY_PATH`` ）中，如有需要，请另行复制。 + +fess_config.bulk +:::::::::::::::: + +fess_config.bulk 包含 |Fess| 的配置信息。 + +fess_basic_config.bulk +:::::::::::::::::::::: + +fess_basic_config.bulk 包含除爬取信息、失败URL、作业日志、缩略图队列、用户标签等以外的 |Fess| 配置信息。 + +fess_user.bulk +:::::::::::::: + +fess_user.bulk 包含用户、角色和组的信息。 + +system.properties +::::::::::::::::: + +system.properties包含常规配置信息。 + +fess.json +::::::::: + +fess.json包含fess索引的配置信息。 + +doc.json +:::::::: + +doc.json包含fess索引的映射信息。 + +chat_log.ndjson +::::::::::::::: + +chat_log.ndjson包含AI聊天使用日志信息。 + +click_log.ndjson +:::::::::::::::: + +click_log.ndjson包含点击日志信息。 + +favorite_log.ndjson +::::::::::::::::::: + +favorite_log.ndjson包含收藏日志信息。 + +search_log.ndjson +::::::::::::::::: + +search_log.ndjson包含搜索日志信息。 + +user_info.ndjson +:::::::::::::::: + +user_info.ndjson包含搜索用户的信息。 + +上传 +--------- + +可以上传和导入配置信息。 +可以恢复的文件如下。 + +- ``*.bulk`` +- ``system.properties`` +- ``fess.json`` 、 ``doc.json`` ：替换 |Fess| 使用的索引定义文件。已有索引的设置和映射不会被立即更改。 +- ``gsa*.xml`` ：Google Search Appliance 的配置文件。将作为 Web 爬取配置、文件爬取配置和标签导入。 + +``*.ndjson`` （搜索日志等日志）无法通过上传来恢复。 + +\*.bulk 中带有 ``updatedTime`` 的文档，仅在已存储的文档不存在、没有 ``updatedTime`` 或更旧时才会写入。 +不比已存储文档更新的文档会被跳过，并以 INFO 级别记录在 ``fess.log`` 中。因此恢复不会撤销备份之后所做的更改， +已安装版本自带的计划作业（``updatedTime`` 为 0）也会原样保留。没有 ``updatedTime`` 的文档总是会被写入。 + +.. note:: + + 跳过的记录以 INFO 级别输出，因此在默认的日志级别（ ``warn`` ）下不会写入 ``fess.log`` 。要查看这些记录，请在恢复之前将日志级别改为 ``info`` 。可以在管理页面的 [系统 > 常规] 的“日志级别”中更改（重启 |Fess| 后会恢复原值），在 Linux 上也可以通过 ``FESS_LOG_LEVEL=info`` 指定。详情请参阅 :doc:`../config/admin-logging` 。 + +.. note:: + + |Fess| 15.10 会使用应用程序加密密钥（ ``fess_config.properties`` 中的 ``app.cipher.key`` ）加密保存 Web 认证和文件认证的 + ``password`` ，因此 ``fess_basic_config.bulk`` 和 ``fess_config.bulk`` 中也包含加密后的值。将备份恢复到其他安装环境时， + 请沿用相同的 ``app.cipher.key`` 。密钥不同时，使用这些认证信息的爬取会因错误而失败。15.10 之前创建的备份以明文包含这些值， + 可以继续正常使用。 + + 另外， ``*.bulk`` 中包含的其他值并未加密，请将这些文件作为机密文件妥善保管。 + + .. |image0| image:: ../../../resources/images/en/15.10/admin/backup-1.png diff --git a/zh-cn/15.10/admin/badword-guide.rst b/zh-cn/15.10/admin/badword-guide.rst new file mode 100644 index 000000000..685a18296 --- /dev/null +++ b/zh-cn/15.10/admin/badword-guide.rst @@ -0,0 +1,85 @@ +======== +排除词汇 +======== + +概述 +==== + +本节介绍如何配置建议的排除词汇。 +建议会根据搜索词显示，但您可以将某些词汇设置为不显示在建议中。 + + +管理方法 +====== + +显示方法 +------ + +要打开下图所示的建议排除词汇配置列表页面，请点击左侧菜单中的 [建议 > 不良词]。 + +|image0| + +要编辑配置，请点击配置名称。 + +创建配置 +-------- + +要打开建议排除词汇创建页面，请点击新建按钮。 + +|image1| + +配置项目 +------ + +建议候选词 +::::::::::: + +注册禁用词汇。 +在此注册的词汇将不会显示在建议中。 + +删除配置 +-------- + +点击列表页面中的配置名称，然后点击删除按钮将显示确认屏幕。 +点击删除按钮后，配置将被删除。 + +下载 +========= + +以CSV格式下载已注册的词汇。 + +|image2| + +CSV内容 +-------- + +第1行是标题行。 +第2行及以后记录排除词汇。 + +:: + +"BadWord" +"检索エンジン" + +上传 +========= + +以CSV格式注册词汇。 + +|image3| + +CSV内容 +-------- + +第1行是标题行。 +第2行及以后描述排除词汇。 + +:: + +"BadWord" +"检索エンジン" + +.. |image0| image:: ../../../resources/images/en/15.10/admin/badword-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/badword-2.png +.. |image2| image:: ../../../resources/images/en/15.10/admin/badword-3.png +.. |image3| image:: ../../../resources/images/en/15.10/admin/badword-4.png diff --git a/zh-cn/15.10/admin/boostdoc-guide.rst b/zh-cn/15.10/admin/boostdoc-guide.rst new file mode 100644 index 000000000..bb348cba8 --- /dev/null +++ b/zh-cn/15.10/admin/boostdoc-guide.rst @@ -0,0 +1,82 @@ +=============== +文档提升 +=============== + +概述 +==== + +本节介绍文档提升的相关配置。 +通过配置文档提升,可以将文档置于搜索结果的上方,而不受搜索词的影响。 + +管理方法 +====== + +显示方法 +------ + +要打开下图所示的文档提升配置列表页面,请点击左侧菜单中的 [爬虫 > 文档提升]。 + +|image0| + +点击配置名称进行编辑。 + +创建配置 +-------- + +要打开文档提升配置页面,请点击新建按钮。 + +|image1| + +配置项 +------ + +条件 +:::: + +指定要置于上方的文档的条件。 +例如,如果要将包含 https://www.n2sm.net/ 的 URL 显示在上方,请写入 url.matches("https://www.n2sm.net/.\*")。 +条件使用下方"脚本类型"中指定的脚本引擎语法编写。 + +提升值表达式 +::::::::: + +指定文档权重的值。 +表达式使用下方"脚本类型"中指定的脚本引擎语法编写。 + +脚本类型 +:::::::: + +指定用于对条件和提升值表达式求值的脚本引擎。 +新建配置时会预填 ``javascript`` 。选择 ``groovy`` 需要 ``fess-script-groovy`` 插件。 +留空时将按 Groovy 求值。 + +.. warning:: + + 在 JavaScript 中，请将条件和提升值表达式写成不带末尾分号的纯表达式。只能解析为语句块的 + 文本，除非包含显式的 ``return`` ，否则其求值结果为 ``null`` 。请参阅 + :ref:`javascript-statement-null` （ :doc:`../config/scripting-javascript` ）。 + +排序顺序 +:::::: + +设置文档提升的排序顺序。 + +规则的应用时机 +-------------- + +文档提升规则在 Web 爬网或文件爬网将文档登记到索引时进行求值，不适用于数据存储爬网。 +添加、修改或删除规则不会改变索引中已有文档的提升值。 + +当 [系统 > 通用] 中的“检查上次修改时间”处于启用状态（默认）时，内容未发生变化的文档在重新爬网时不会再次登记到索引，因此不会重新计算其提升值。 +要将新增或修改的规则应用于已有文档，请先将这些文档从索引中删除（ :doc:`searchlist-guide` ），然后重新爬网。 +重新登记到索引的文档（例如内容已更新的文档）会在此时进行求值。 +如果禁用“检查上次修改时间”，每次爬网都会重新登记所有文档，因此规则每次都会被求值。 + +删除配置 +-------- + +点击列表页面中的配置名称,然后点击删除按钮,将显示确认画面。点击删除按钮将删除配置。 + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/boostdoc-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/boostdoc-2.png diff --git a/zh-cn/15.10/admin/crawlinginfo-guide.rst b/zh-cn/15.10/admin/crawlinginfo-guide.rst new file mode 100644 index 000000000..6a10274f8 --- /dev/null +++ b/zh-cn/15.10/admin/crawlinginfo-guide.rst @@ -0,0 +1,93 @@ +========= +爬网信息 +========= + +概述 +==== + +爬虫的执行结果会被记录，爬网信息可以在此管理界面中查看。 + +管理方法 +====== + +列表 +==== + +每次执行爬虫时都会记录为爬网信息。 +在列表中可以查看已执行爬虫的会话名称和执行时间。 +如果要查看爬网信息的详细内容，请点击目标爬网信息。 + +|image0| + +详情 +==== + +从列表中点击爬网信息的会话ID后，将显示目标爬网信息的详细内容。 + +|image1| + +项目列表 +------ + +会话ID +:::::::::: + +爬虫执行时的会话ID。 + +爬虫开始时间 +::::::::::::::: + +爬虫整体开始的时间。 + +爬虫开始时间（Web/文件） +:::::::::::::::::::::::::::: + +Web和文件系统爬虫开始的时间。 + +爬虫开始时间（数据存储） +:::::::::::::::::::::::::: + +数据存储爬虫开始的时间。 + +爬虫结束时间（Web/文件） +:::::::::::::::::::::::::::: + +Web和文件系统爬虫结束的时间。 + +爬虫执行时间（数据存储） +:::::::::::::::::::::::::: + +数据存储爬虫的执行时间（毫秒）。 + +索引执行时间（数据存储） +:::::::::::::::::::::::::::::: + +索引Web和文件系统爬虫结果所需的时间（毫秒）。 + +索引大小（数据存储） +::::::::::::::::::::::::::: + +已索引文档的数量。 + +爬虫结束时间（数据存储） +:::::::::::::::::::::::::: + +数据存储爬虫结束的时间。 + +爬虫状态 +:::::::::::: + +爬虫是否成功。 + +爬虫结束时间 +::::::::::::::: + +爬虫整体结束的时间。 + +爬虫执行时间 +::::::::::::::: + +爬虫整体的执行时间（毫秒）。 + +.. |image0| image:: ../../../resources/images/en/15.10/admin/crawlinginfo-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/crawlinginfo-2.png diff --git a/zh-cn/15.10/admin/dashboard-guide.rst b/zh-cn/15.10/admin/dashboard-guide.rst new file mode 100644 index 000000000..89a0cbf43 --- /dev/null +++ b/zh-cn/15.10/admin/dashboard-guide.rst @@ -0,0 +1,58 @@ +=========== +仪表板 +=========== + +概述 +==== + +仪表板提供了一个 Web 管理工具,用于管理 |Fess| 访问的 OpenSearch 集群和索引。 + +|image0| + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: |Fess| 管理的索引 + :header-rows: 1 + + * - 索引名称 + - 说明 + * - fess.yyyyMMddHHmmssSSS + - 已索引的文档 + * - fess_log + - 访问日志 + * - fess.suggest.yyyyMMddHHmmssSSS + - 建议词 + * - fess_config + - |Fess| 的配置 + * - fess_user + - 用户/角色/组数据 + * - configsync + - 词典配置 + * - fess_suggest + - 建议元数据 + * - fess_suggest_array + - 建议元数据 + * - fess_suggest_badword + - 建议的禁用词列表 + * - fess_suggest_analyzer + - 建议元数据 + * - fess_crawler + - 爬取信息 + +``fess.`` 和 ``fess.suggest.`` 后面的部分是创建索引的日期和时间（``yyyyMMddHHmmssSSS``，共 17 位）。 + +以点(.)开头的索引名称是系统索引,因此不会显示。 +要显示系统索引,请启用 Special 复选框。 + +确认已索引的文档数 +================================ + +已索引的文档数显示在 fess 索引中,如下图所示。 + +|image1| + +单击每个索引右上角的图标,将显示索引操作菜单。 +要删除已索引的文档,请在管理搜索界面中删除。请注意不要使用"删除索引"删除。 + +.. |image0| image:: ../../../resources/images/en/15.10/admin/dashboard-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/dashboard-2.png +.. pdf :width: 400 px diff --git a/zh-cn/15.10/admin/dataconfig-guide.rst b/zh-cn/15.10/admin/dataconfig-guide.rst new file mode 100644 index 000000000..d902a5cbf --- /dev/null +++ b/zh-cn/15.10/admin/dataconfig-guide.rst @@ -0,0 +1,405 @@ +============ +数据存储爬取 +============ + +概述 +==== + +数据存储爬取是将关系型数据库(MySQL、PostgreSQL、Oracle等)、CSV 文件等网站和文件以外的各种数据源注册到 |Fess| 索引,实现全文搜索的功能。支持的数据源可以通过数据存储连接器插件进行扩展。 + +|Fess| 可以将数据库和CSV等数据源作为爬取对象。 +本文档将说明配置数据存储所需的设置。 + +.. note:: + + ``DatabaseDataStore`` 由数据库连接器插件( ``fess-ds-db`` )提供,``CsvDataStore`` / ``CsvListDataStore`` 由CSV连接器插件( ``fess-ds-csv`` )提供。可用连接器列表请参考 :doc:`../config/datastore/ds-overview`。 + +管理方法 +====== + +显示方法 +------ + +要打开下图所示的数据存储配置列表页面,请点击左侧菜单中的 [爬虫 > 数据存储]。 + +|image0| + +点击配置名称即可进行编辑。 + +创建配置 +-------- + +点击新建按钮打开数据存储配置页面。 + +|image1| + +配置项 +------ + +名称 +:::: + +指定爬取配置的名称。 + +处理器名称 +::::::::: + +处理数据存储的处理器名称。 + +* DatabaseDataStore: 爬取数据库 +* CsvDataStore: 以CSV/TSV文件为对象进行爬取 +* CsvListDataStore: 爬取包含索引目标文件路径的CSV文件 + +处理器名称下拉列表中只显示已安装的数据存储连接器插件（``fess-ds-*``）所提供的处理器。 +如果没有安装插件，则没有可选择的处理器。 +其他处理器请参阅 :doc:`../config/datastore/ds-overview` 中列出的各连接器页面。 +另外，早期版本文档中的 ``EsDataStore`` （``fess-ds-elasticsearch`` 插件）自 15.6.0 起未再发布，在 15.10 中无法使用。 + +参数 +::::::::: + +指定与数据存储相关的参数。 + +``script_type`` 参数用于指定对下方脚本求值所使用的脚本引擎。 +新建配置时会预填 ``script_type=javascript`` 。 +如果未指定 ``script_type`` ,脚本将按 Groovy 求值。 + +脚本 +:::::::: + +指定如何将从数据存储获取的值设置到哪些字段。 +表达式使用上方 ``script_type`` 参数所指定脚本引擎的语法编写 +（默认使用 JavaScript）。 + +.. warning:: + + 在 JavaScript 中，请将每一行写成不带末尾分号的纯表达式。只能解析为语句块的行（带末尾分号 + 的内容，或 ``let`` / ``const`` 声明等），除非包含显式的 ``return`` ，否则其求值结果为 + ``null`` ；而求值为 ``null`` 的映射只是不设置该字段而已。既不会报错也不会输出日志行， + 除了字段悄然变空之外没有任何症状。请参阅 :ref:`javascript-statement-null` + （ :doc:`../config/scripting-javascript` ）。 + +权重值 +:::::::: + +指定使用此配置爬取的文档的权重值。 + +权限 +::::::::::: + +指定此配置的权限。 +权限的指定方法,例如,要向属于developer组的用户显示搜索结果,需要指定{group}developer。 +用户级别的指定为{user}用户名,角色级别的指定为{role}角色名,组级别的指定为{group}组名。 + +虚拟主机 +:::::::: + +指定虚拟主机的主机名。 +详情请参考 :doc:`配置指南的虚拟主机 <../config/security-virtual-host>`。 + +状态 +:::: + +指定是否使用此爬取配置。 + +说明 +:::: + +可以输入说明。 + +删除配置 +-------- + +在列表页面点击配置名称,然后点击删除按钮将显示确认界面。 +按下删除按钮后配置将被删除。 + +示例 +== + +DatabaseDataStore +----------------- + +说明数据库爬取。 + +例如,假设MySQL的testdb数据库中有以下表,可以使用用户名hoge、密码fuga进行连接。 + +:: + + CREATE TABLE doc ( + id BIGINT NOT NULL AUTO_INCREMENT, + title VARCHAR(100) NOT NULL, + content VARCHAR(255) NOT NULL, + latitude VARCHAR(20), + longitude VARCHAR(20), + versionNo INTEGER NOT NULL, + PRIMARY KEY (id) + ); + +这里预先插入以下数据。 + +:: + + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 1', 'コンテンツ 1 です．', '37.77493', ' -122.419416', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 2', 'コンテンツ 2 です．', '34.701909', '135.494977', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 3', 'コンテンツ 3 です．', '-33.868901', '151.207091', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 4', 'コンテンツ 4 です．', '51.500152', '-0.113736', 1); + INSERT INTO doc (title, content, latitude, longitude, versionNo) VALUES ('タイトル 5', 'コンテンツ 5 です．', '35.681137', '139.766084', 1); + +参数 +:::::::::::: + +参数配置示例如下。 + +:: + + driver=com.mysql.jdbc.Driver + url=jdbc:mysql://localhost:3306/testdb?useUnicode=true&characterEncoding=UTF-8 + username=hoge + password=fuga + sql=select * from doc + +参数采用"键=值"格式。键的说明如下。 + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - driver + - 驱动程序类名 + * - url + - URL + * - username + - 连接数据库时的用户名 + * - password + - 连接数据库时的密码 + * - sql + - 用于获取爬取对象的SQL语句 + +表: 数据库配置参数示例 + + +脚本 +:::::::: + +脚本配置示例如下。 + +:: + + url="http://SERVERNAME/" + id + host="SERVERNAME" + site="SERVERNAME" + title=title + content=content + cache=content + digest=content + anchor= + content_length=content.length() + last_modified=new java.util.Date() + location=latitude + "," + longitude + latitude=latitude + longitude=longitude + +参数采用"键=值"格式。键的说明如下。 + +值的部分使用 ``script_type`` 参数所指定脚本引擎的语法编写。 +字符串请用双引号括起来。通过数据库列名访问即可获取其值。 + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - url + - URL(请根据您的环境设置可访问数据的URL) + * - host + - 主机名 + * - site + - 站点路径 + * - title + - 标题 + * - content + - 文档内容(索引目标字符串) + * - cache + - 文档缓存(不作为索引目标) + * - digest + - 搜索结果中显示的摘要部分 + * - anchor + - 文档中包含的链接(通常不需要指定) + * - content_length + - 文档长度 + * - last_modified + - 文档最后修改日期 + +表: 脚本配置内容 + + +驱动程序 +:::::::: + +连接数据库时需要驱动程序。请将jar文件放置在app/WEB-INF/lib目录下。 + +CsvDataStore +------------ + +说明以CSV文件为对象的爬取。 + +例如,在/home/taro/csv目录中创建test.csv文件,内容如下。 +文件编码设置为Shift_JIS。 + +:: + + 1,タイトル 1,テスト1です。 + 2,タイトル 2,テスト2です。 + 3,タイトル 3,テスト3です。 + 4,タイトル 4,テスト4です。 + 5,タイトル 5,テスト5です。 + 6,タイトル 6,テスト6です。 + 7,タイトル 7,テスト7です。 + 8,タイトル 8,テスト8です。 + 9,タイトル 9,テスト9です。 + + +参数 +::::::::: + +参数配置示例如下。 + +:: + + directories=/home/taro/csv + fileEncoding=Shift_JIS + +参数采用"键=值"格式。键的说明如下。 + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - directories + - 包含CSV文件的目录(.csv或.tsv) + * - files + - CSV文件(直接指定时) + * - fileEncoding + - CSV文件编码 + * - separatorCharacter + - 分隔符 + + +表: CSV文件配置参数示例 + + +脚本 +:::::::: + +脚本配置示例如下。 + +:: + + url="http://SERVERNAME/" + cell1 + host="SERVERNAME" + site="SERVERNAME" + title=cell2 + content=cell3 + cache=cell3 + digest=cell3 + anchor= + content_length=cell3.length() + last_modified=new java.util.Date() + +参数采用"键=值"格式。 +键与数据库爬取的情况相同。 +CSV文件中的数据保存在cell[数字]中(数字从1开始)。 +如果CSV文件的单元格中不存在数据,可能会为null。 + +CsvListDataStore +---------------- + +用于爬取大量文件。 +将已更新文件的路径写入CSV文件并放置,通过仅爬取指定的路径,可以缩短爬取的执行时间。 + +描述路径时的格式如下。 + +:: + + [操作]<分隔符>[路径] + +操作指定以下之一: + +* create: 文件已创建 +* modify: 文件已更新 +* delete: 文件已删除 + +例如,在/home/taro/csv目录中创建test.csv文件,内容如下。 +文件编码设置为Shift_JIS。 + +路径的描述方式与在文件爬取中指定爬取目标路径时相同。 +如下所示,指定为"file:/[路径]"或"smb://[路径]"的形式。 + +:: + + modify,smb://servername/data/testfile1.txt + modify,smb://servername/data/testfile2.txt + modify,smb://servername/data/testfile3.txt + modify,smb://servername/data/testfile4.txt + modify,smb://servername/data/testfile5.txt + modify,smb://servername/data/testfile6.txt + modify,smb://servername/data/testfile7.txt + modify,smb://servername/data/testfile8.txt + modify,smb://servername/data/testfile9.txt + modify,smb://servername/data/testfile10.txt + + +参数 +::::::::: + +参数配置示例如下。 + +:: + + directories=/home/taro/csv + fileEncoding=Shift_JIS + +参数采用"键=值"格式。键的说明如下。 + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + + * - directories + - 包含CSV文件的目录(.csv或.tsv) + * - fileEncoding + - CSV文件编码 + * - separatorCharacter + - 分隔符 + + +表: CSV文件配置参数示例 + + +脚本 +:::::::: + +脚本配置示例如下。 + +:: + + event_type=cell1 + url=cell2 + +参数采用"键=值"格式。 +键与数据库爬取的情况相同。 + +如果爬取目标需要身份验证,还需要设置以下内容。 + +:: + + crawler.file.auth=example + crawler.file.auth.example.scheme=SAMBA + crawler.file.auth.example.username=username + crawler.file.auth.example.password=password + +相关页面 +======== + +- :doc:`../config/datastore/index` +- :doc:`../config/datastore/ds-database` +- :doc:`../config/datastore/ds-overview` +- :doc:`../config/crawler-basic` + +.. |image0| image:: ../../../resources/images/en/15.10/admin/dataconfig-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/dataconfig-2.png diff --git a/zh-cn/15.10/admin/dict-guide.rst b/zh-cn/15.10/admin/dict-guide.rst new file mode 100644 index 000000000..c53bb1b40 --- /dev/null +++ b/zh-cn/15.10/admin/dict-guide.rst @@ -0,0 +1,157 @@ +==== +字典 +==== + +概述 +==== + +本节介绍字典的相关配置。 + +请在理解各字典相关规范后再进行字典更改。 +如果字典更改失败,可能无法访问索引。 + +.. note:: + + 当 ``search_engine.type`` 为 ``vanilla`` 或 ``aws`` 时（即 OpenSearch 中没有 CodeLibs 插件时），无法使用字典管理。详情请参阅 :doc:`../config/search-engine-type` 。 + +列表 +==== + +要打开下图所示的可管理字典列表页面,请单击左侧菜单中的[系统 > 字典]。 + + +|image0| + + +各词典的作用范围与生效时机 +========================== + +每个词典作用的字段和生效的时机都不同。 +如果编辑了词典但搜索结果没有变化，请先查看下表。 + +.. list-table:: + :header-rows: 1 + :widths: 22 26 28 24 + + * - 词典 + - 文件 + - 作用的字段 + - 生效时机 + * - Kuromoji + - ``ja/kuromoji.txt`` + - 仅 ``content_ja`` 等 ``_ja`` 字段 + - 索引时（需要重新爬取） + * - 同义词 + - ``synonym.txt`` + - ``content`` 和 ``title`` + - 搜索时（无需重新爬取） + * - 映射（各语言通用） + - ``mapping.txt`` + - ``content`` 和 ``title`` + - 索引时（需要重新爬取） + * - 映射（按语言） + - ``ja/mapping.txt`` + - 仅 ``content_ja`` 等 ``_ja`` 字段 + - 索引时（需要重新爬取） + * - Protwords + - ``en/protwords.txt`` + - ``content`` 和 ``title`` + - 索引时与搜索时 + * - 停用词 + - ``en/stopwords.txt`` + - ``content`` 和 ``title`` + - 索引时与搜索时 + * - Stemmer 覆盖 + - ``en/stemmer_override.txt`` + - ``content`` 和 ``title`` + - 索引时与搜索时 + +.. note:: + + 分析器是在打开索引时构建的，因此更新词典文件后 + **在索引 close / open 之前不会生效**\ 。 + 而且在索引时生效的词典不会追溯应用到已经索引的文档，这些文档需要重新爬取。 + 使更改生效的步骤请参见 :ref:`dict-apply-changes`\ 。 + +.. warning:: + + 对 ``content`` 字段（大多数搜索由该字段作答）生效的字符替换词典是\ **根目录的** + ``mapping.txt`` ，而不是 ``ja/mapping.txt`` 。二者同名为映射，但是不同的文件。 + +.. _dict-apply-changes: + +使词典的更改生效 +---------------- + +仅保存词典，无论等待多久，搜索结果都不会改变。OpenSearch 的 configsync 插件大约每分钟将已保存的 +词典写入词典文件，但分析器只在打开索引时读取词典，因此已经打开的索引会继续使用旧的词典。 +编辑词典后，请重新加载文档索引： + +1. 打开左侧菜单中的 [系统信息 > 维护]。 +2. 在“重新加载文档索引”中单击 [重新加载] 按钮。 + +该按钮会先将已保存的词典写入文件，然后关闭（close）并重新打开（open） ``fess.update`` 别名所指向的 +索引，因此无需等待定期写入。同义词这类在搜索时生效的词典，会在索引重新打开时生效。对于在索引时 +生效的词典，还需要重新爬取相关文档。 + +.. warning:: + + 在索引关闭期间，以及打开后分片重新分配完成之前，无法搜索该索引：搜索会出错或返回 0 条结果。 + 索引越大，所需时间越长，请在访问较少的时段执行。 + +如果不使用管理界面、而要从脚本等执行，请向 OpenSearch 发送相同的操作:: + + curl -X POST "localhost:9200/_configsync/flush" + curl -X POST "localhost:9200/fess.update/_close" + curl -X POST "localhost:9200/fess.update/_open" + +``_configsync/flush`` 会立即将已保存的词典写入文件。如果省略此步骤，请在保存词典后至少等待 1 分钟， +再关闭索引。 + +Kuromoji 用户词典与搜索结果 +---------------------------- + +``content`` 字段使用 standard 分词器和 ``cjk_bigram`` 进行分析，因此不受 Kuromoji +形态素切分结果的影响。将日语复合词注册到 Kuromoji 用户词典后重新爬取，对 ``content`` +的搜索结果仍然不会改变。注册的效果体现在 ``content_ja`` 上，该字段会根据请求的语言 +加入到查询条件中。 + +Kuromoji +======== + +管理日语形态素分析用的词典。 +ja/kuromoji.txt 是日语形态素分析用词典。 + +同义词 +===== + +管理同义词词典。 +synonym.txt 是通用于所有语言的同义词词典文件。 + +映射 +======== + +管理字符替换词典。 +mapping.txt 是通用于所有语言或各语言的单词替换词典文件。 + +Protwords +========= + +管理保护单词词典。 +protwords.txt 按各语言配置,是用于排除词干提取等的单词列表文件。 + +停用词 +=========== + +管理停用词词典。 +stopwords.txt 按各语言配置,是在创建索引时排除的单词列表文件。 + +Stemmer覆盖 +============ + +管理 Stemmer 覆盖词典。 +stemmer_override.txt 按各语言配置,是用于覆盖词干提取处理的单词替换词典文件。 + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/dict-1.png + :height: 940px diff --git a/zh-cn/15.10/admin/docreport-guide.rst b/zh-cn/15.10/admin/docreport-guide.rst new file mode 100644 index 000000000..2aa7e7f71 --- /dev/null +++ b/zh-cn/15.10/admin/docreport-guide.rst @@ -0,0 +1,55 @@ +======== +文档报告 +======== + +概述 +==== + +文档报告是有助于整理已爬取的文件服务器等的管理页面。它会列出内容相同的文档和长期未更新的文档，并且各列表都可以下载为 CSV。 + +要打开该页面，请点击左侧菜单中的 [系统信息 > 文档报告]。查看需要 ``admin-docreport`` 或 ``admin-docreport-view`` 角色。该页面只进行显示和下载，不会修改任何文档。 + +两个选项卡都可以通过“URL 前缀”（例如 ``smb://server/share/`` ）缩小范围。 + +重复文档 +======== + +将内容相同或几乎相同的文档分组，按文档数量从多到少显示。分组使用在编入索引时计算的内容签名（ ``content_minhash_bits``\ ，与折叠重复搜索结果所用的相同），因此无需重新索引。内容中没有词语的文档（如空文件）不在对象范围内。 + +页面最多显示 ``docreport.duplicate.group.size`` （默认值：100）个组，每个组最多显示 ``docreport.duplicate.docs.size`` （默认值：10）个文档。可以通过 [下载 CSV] 获取所有组。即使索引很大，CSV 也会读取所有组，并输出 ``group, groupSize, url, title, filename, contentLength, lastModified, owner, lastModifier, clickCount, docId`` 列。 + +.. note:: + + 重复文档报告需要内容签名，而面向不含 CodeLibs 插件的 OpenSearch 的索引定义（ ``search_engine.type`` 为 ``vanilla`` 、 ``aws`` 或已弃用的 ``cloud`` ）不会计算内容签名。在这些类型下，“重复文档”选项卡不会显示，只能使用“休眠文档”。详情请参阅 :doc:`../config/search-engine-type` 。 + +休眠文档 +======== + +按从旧到新的顺序显示最后修改时间早于指定天数（“未更新天数”，默认值为 ``docreport.dormant.days`` 的 365）的文档。没有最后修改时间的文档不会显示。启用“从未在搜索结果中被打开”后，会排除曾从搜索结果中被点击过的文档。 + +页面显示符合条件的文档数量、合计大小和文档列表。列表的翻页有上限（ ``indexer.max.result.window.size`` ），超出该上限的文档请通过 [下载 CSV] 获取。 + +设置 +==== + +可以通过 ``fess_config.properties`` 中的以下设置调整其行为。 + +.. list-table:: + :header-rows: 1 + :widths: 40 45 15 + + * - 属性 + - 说明 + - 默认值 + * - ``docreport.duplicate.group.size`` + - 页面显示的重复组最大数量 + - ``100`` + * - ``docreport.duplicate.docs.size`` + - 页面中每个组列出的文档最大数量 + - ``10`` + * - ``docreport.duplicate.export.page.size`` + - 下载 CSV 时每次请求读取的内容签名数量 + - ``10000`` + * - ``docreport.dormant.days`` + - 视为休眠文档的、距最后修改的默认天数 + - ``365`` diff --git a/zh-cn/15.10/admin/duplicatehost-guide.rst b/zh-cn/15.10/admin/duplicatehost-guide.rst new file mode 100644 index 000000000..4c325133b --- /dev/null +++ b/zh-cn/15.10/admin/duplicatehost-guide.rst @@ -0,0 +1,59 @@ +======== +重复主机 +======== + +概述 +==== + +本节介绍有关重复主机的配置。 +重复主机用于在爬取时将不同的主机名视为相同主机。 +例如，在希望将 www.example.com 和 example.com 视为同一站点的情况下可以使用。 + +管理方法 +====== + +显示方法 +------ + +要打开下图所示的重复主机设置列表页面，请点击左侧菜单中的 [爬虫 > 重复主机]。 + +|image0| + +点击设置名称可进行编辑。 + +创建设置 +-------- + +要打开重复主机设置页面，请点击新建按钮。 + +|image1| + +配置项 +------ + +常规名称 +::::: + +指定常规主机名。重复主机名将替换为常规主机名。 + +重复名称 +::::: + +指定重复的主机名。指定要替换的主机名。 + +.. note:: + + 主机名与重复名称匹配的 URL，无论是写在爬取设置“URL”（起始 URL）中的，还是爬取过程中发现的链接 URL，都会在爬取之前被替换为常规名称的 URL。 + 因此，爬取设置中的“要包含在爬网中的URL”和“要从爬网中排除的URL”是针对替换之后的 URL 进行判断的。请使用常规名称的主机名来书写。 + + 例如，常规名称为 ``example.com`` ，重复名称为 ``www.example.com`` 时，如果在“要包含在爬网中的URL”中只写 ``https://www.example.com/.*`` ，替换后的起始 URL（ ``https://example.com/`` ）就会被排除在外。 + 这种情况下不会输出任何错误或日志，也不会有任何文档被登记到索引中。 + +删除设置 +-------- + +点击列表页面的设置名称，然后点击删除按钮，将显示确认画面。 +点击删除按钮将删除该设置。 + +.. |image0| image:: ../../../resources/images/en/15.10/admin/duplicatehost-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/duplicatehost-2.png diff --git a/zh-cn/15.10/admin/elevateword-guide.rst b/zh-cn/15.10/admin/elevateword-guide.rst new file mode 100644 index 000000000..5d1cbe2e3 --- /dev/null +++ b/zh-cn/15.10/admin/elevateword-guide.rst @@ -0,0 +1,106 @@ +======== +追加词汇 +======== + +概述 +==== + +本节介绍如何配置建议词汇的附加候选项。建议会根据搜索词显示，您可以添加更多词汇。 + +管理方法 +====== + +显示方法 +------ + +要打开下图所示的追加词汇配置列表页面，请点击左侧菜单中的 [建议 > 提升词]。 + +|image0| + +要编辑配置，请点击配置名称。 + +创建配置 +-------- + +要打开追加词汇配置页面，请点击新建按钮。 + +|image1| + +配置项目 +------ + +单词 +:::: + +指定要显示为建议候选项的词汇。 + +读音 +:::: + +指定建议候选词汇的读音。 + +权限 +::::::::::: + +为词汇设置角色信息。 +只有具有配置角色的用户才能在建议中看到该词汇。 + +标签 +::::: + +为词汇设置标签。 +如果选择了配置标签以外的标签，该词汇将不会显示在建议中。 + +提升值 +:::::::: + +为词汇设置提升值。 + +删除配置 +-------- + +点击列表页面中的配置名称，然后点击删除按钮将显示确认屏幕。 +点击删除按钮后，配置将被删除。 + + +下载 +========= + +以CSV格式下载已注册的词汇。 + +|image2| + +CSV内容 +-------- + +第1行是标题行。 +第2行及以后记录追加词汇。 + +:: + +"SuggestWord","Reading","Role","Label","Boost" +"fess","ふぇす","role1","label1","100" + +上传 +========= + +以CSV格式注册词汇。 + +|image3| + +CSV内容 +-------- + +第1行是标题行。 +第2行及以后描述追加词汇。 + +:: + +"SuggestWord","Reading","Role","Label","Boost" +"fess","ふぇす","role1","label1","100" + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/elevateword-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/elevateword-2.png +.. |image2| image:: ../../../resources/images/en/15.10/admin/elevateword-3.png +.. |image3| image:: ../../../resources/images/en/15.10/admin/elevateword-4.png diff --git a/zh-cn/15.10/admin/esreq-guide.rst b/zh-cn/15.10/admin/esreq-guide.rst new file mode 100644 index 000000000..5c81d5101 --- /dev/null +++ b/zh-cn/15.10/admin/esreq-guide.rst @@ -0,0 +1,52 @@ +==================== +对OpenSearch的请求 +==================== + +概述 +==== + +本页面将 JSON 文件中描述的请求发送到 OpenSearch。 + +|image0| + +此页面不在左侧菜单中。要显示此页面，请以管理员身份登录后，在 URL 路径中输入 ``/admin/sereq/`` 。 +发送请求需要 ``admin`` 角色（管理员）或 ``admin-sereq`` 角色。 + +操作方法 +======== + +发送请求 +-------- + +将要发送给 OpenSearch 的请求创建为 JSON 文件，在“请求文件”中选择该文件，然后点击“发送”按钮，即可向 OpenSearch 发送请求。 +响应将作为文件下载。 + +配置项 +------ + +请求文件 +:::::::: + +指定描述了请求的文件。 + +在第一行用一个半角空格分隔写入 ``<方法> <路径>`` ，从第二行起写入请求正文（如查询 DSL）。 +方法可以使用 GET、POST、PUT、DELETE。路径是 OpenSearch 上的路径，开头的 ``/`` 可以省略。 +例如，文件的内容如下所示。 + +:: + + POST /_search + { + "query": { + "match_all": {} + } + } + +正文中的换行会被去掉，各行连接后发送。因此，无法发送每行一个 JSON 的格式（如 ``_bulk`` ）的请求。 + +.. warning:: + + 方法为 PUT 或 DELETE 的请求同样会原样发送到 OpenSearch。 + 根据文件内容，可能会修改或删除 |Fess| 使用的索引，导致数据丢失。发送前请仔细确认内容。 + +.. |image0| image:: ../../../resources/images/en/15.10/admin/esreq-1.png diff --git a/zh-cn/15.10/admin/failureurl-guide.rst b/zh-cn/15.10/admin/failureurl-guide.rst new file mode 100644 index 000000000..a17c33dcc --- /dev/null +++ b/zh-cn/15.10/admin/failureurl-guide.rst @@ -0,0 +1,66 @@ +====== +失败URL +====== + +概述 +==== + +本节介绍失败URL。 +爬虫时无法获取的URL会被记录，可以作为失败URL查看。 + +管理方法 +====== + +显示方法 +------ + +要打开用于查看失败URL的列表页面，请点击左侧菜单中的 [系统信息 > 失败URL]。 + +|image0| + +点击失败URL的查看链接将显示详细信息。 + +失败URL详情 +=========== + +失败URL详情中记录了爬虫时发生的异常。 + +|image1| + +详情内容 +-------- + +URL +:::: + +发生异常的URL。 + +线程名称 +:::::::: + +执行爬虫的线程名称。 +可在查看日志文件时使用。 + +类型 +:::: + +异常的类型。 + +日志 +:::: + +异常的内容。 + +错误数 +:::::::: + +此异常发生的次数。 + +上次访问时间 +:::::::::::: + +此异常发生的时间。 + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/failureurl-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/failureurl-2.png diff --git a/zh-cn/15.10/admin/fileauth-guide.rst b/zh-cn/15.10/admin/fileauth-guide.rst new file mode 100644 index 000000000..4ebaace31 --- /dev/null +++ b/zh-cn/15.10/admin/fileauth-guide.rst @@ -0,0 +1,85 @@ +========= +文件认证 +========= + +概述 +==== + +本节介绍在爬取文件时需要进行文件认证的配置方法。 +|Fess| 支持对 FTP 或 Windows 共享文件夹进行认证。 + +管理方法 +====== + +显示方法 +------ + +要打开下图所示的文件认证设置列表页面，请点击左侧菜单中的 [爬虫 > 文件认证]。 + +|image0| + +点击设置名称可进行编辑。 + +创建设置 +-------- + +要打开文件认证设置页面，请点击新建按钮。 + +|image1| + +配置项 +------ + +主机名 +:::::: + +指定需要认证的站点的主机名。 +请使用与要爬取的 URL 中的主机名相同的名称。对于使用其他名称（例如 IP 地址而不是别名）书写的 URL，不会使用此认证。 + +端口 +:::: + +指定需要认证的站点的端口。 +留空时，列表中显示“任意”。端口留空的含义因协议而异。 + +* FTP: 用于任意端口的 URL（不含端口的 URL 视为 21 号端口）。 +* SAMBA: 仅用于不含端口的 URL（ ``smb://服务器名/共享名/`` ）。不用于像 ``smb://服务器名:445/共享名/`` 这样明确写出端口的 URL。要爬取明确写出端口的 URL 时，请在此处指定相同的端口。 + +协议 +:::::: + +选择认证方法。 +可以使用 FTP 或 SAMBA（Windows 共享文件夹认证）。 + +用户名 +:::::::: + +指定登录认证站点的用户名。 + +密码 +:::::::: + +指定登录认证站点的密码。 + +参数 +::::::::: + +在需要设置登录认证站点所需的配置值时使用。对于 SAMBA，可以设置 domain 的值。设置时请按如下方式描述。 + +:: + + domain=FUGA + +文件爬取设置 +::::::::::::::: + +指定使用此认证设置的爬取配置。 + +删除设置 +-------- + +点击列表页面的设置名称，然后点击删除按钮，将显示确认画面。 +点击删除按钮将删除该设置。 + +.. |image0| image:: ../../../resources/images/en/15.10/admin/fileauth-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/fileauth-2.png diff --git a/zh-cn/15.10/admin/fileconfig-guide.rst b/zh-cn/15.10/admin/fileconfig-guide.rst new file mode 100644 index 000000000..10506f4bd --- /dev/null +++ b/zh-cn/15.10/admin/fileconfig-guide.rst @@ -0,0 +1,260 @@ +============================== +文件抓取（文件服务器搜索） +============================== + +概述 +==== + +文件抓取是将企业内部文件服务器、Windows 共享文件夹、云存储中的文档注册到 |Fess| 索引，实现全文搜索（文件服务器搜索）的功能。支持 Word、Excel、PowerPoint、PDF 等多种文件格式。 + +在文件抓取配置页面中，您可以管理对文件系统或共享网络文件夹中的文件进行抓取的配置。 + +抓取对象由“路径”中指定的协议决定： + +- ``file:/`` … 本地或已挂载的文件系统 +- ``smb://`` … Windows 文件服务器/共享文件夹（SMB/CIFS） +- ``smb1://`` … 使用旧版 SMB1 协议的 Windows 文件服务器/共享文件夹 +- ``ftp://`` … FTP 服务器 +- ``s3://`` … Amazon S3 存储桶（需要 ``fess-storage-s3`` 插件） +- ``gcs://`` … Google Cloud Storage 存储桶（需要 ``fess-storage-gcs`` 插件） + +管理方式 +====== + +显示方式 +------ + +要打开文件抓取配置的列表页面，请点击左侧菜单中的 [爬虫 > 文件系统]。 + +|image0| + +点击配置名称即可进行编辑。 + +创建配置 +------- + +点击新建按钮即可打开文件抓取配置页面。 + +|image1| + +配置项 +------ + +名称 +:::: + +配置的名称。 + +路径 +:::: + +在此路径中，指定开始抓取的位置（例如：file:/、smb://、s3://、gcs://）。 + +包含在抓取中的路径 +::::::::::::::::: + +与此项中指定的正则表达式（Java格式）匹配的路径将成为 |Fess| 爬虫的抓取对象。 + +排除在抓取外的路径 +::::::::::::::::::::: + +与此项中指定的正则表达式（Java格式）匹配的路径将不会成为 |Fess| 爬虫的抓取对象。 + +包含在搜索中的路径 +:::::::::::::: + +与此项中指定的正则表达式（Java格式）匹配的路径将成为搜索对象。 + +排除在搜索外的路径 +:::::::::::::::::: + +与此项中指定的正则表达式（Java格式）匹配的路径将不会成为搜索对象。 + +配置参数 +:::::::::::: + +可以指定抓取配置信息。 + +抓取以 ``file:`` 开头的路径（本地或已挂载的文件系统）时，可以通过 ``client.followSymlink`` 指定是否跟踪符号链接。默认值为 ``true``\ （跟踪）。指定 ``false`` 时，符号链接将被跳过，链接指向的文件不会通过该链接被抓取（被跳过的链接会以 INFO 级别记录到 ``fess-crawler.log`` 中）。跟踪链接会使链接指向的文件以包含该链接的配置的权限再次被登记，因此在抓取的共享比其链接指向的目录树拥有更多读取用户时，请考虑设置为 ``false``\ 。 + +:: + + client.followSymlink=false + +深度 +:::: + +指定要抓取的文件系统结构的深度。 + +最大访问数 +::::::::::: + +指定要索引的路径数量。 + +线程数 +:::::::: + +指定用于此配置的线程数量。 + +间隔 +:::: + +指定线程每次抓取路径时的等待时间。 + +权重值 +:::::::: + +权重值是指通过此配置索引的文档的优先级。 + +权限 +::::::::::: + +指定此配置的权限。 +权限的指定方法为，例如，要向属于developer组的用户显示搜索结果，需指定为{group}developer。 +按用户指定为{user}用户名，按角色指定为{role}角色名，按组指定为{group}组名。 + +虚拟主机 +:::::::: + +指定虚拟主机的主机名。 +详细信息请参阅 :doc:`配置指南的虚拟主机 <../config/security-virtual-host>`。 + +状态 +:::: + +当此配置启用时，默认爬虫作业将包含此配置进行抓取。 + +说明 +:::: + +可以输入说明。 + +删除配置 +-------- + +点击列表页面中的配置名称，然后点击删除按钮将显示确认画面。点击删除按钮后配置将被删除。 + +示例 +== + +抓取本地文件 +-------------------- + +如果要抓取 /home/share 下的文件，配置如下所示。 + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - 名称 + - 值 + * - 名称 + - Share 目录 + * - 路径 + - file:/home/share + +其他参数使用默认设置即可。 + +抓取Windows共享文件夹 +--------------------------- + +如果要抓取 \\SERVER\SharedFolder 下的文件，配置如下所示。 + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - 名称 + - 值 + * - 名称 + - 共享文件夹 + * - 路径 + - smb://SERVER/SharedFolder/ + +如果访问共享文件夹需要用户名/密码，则需要从左侧菜单中的 [爬虫 > 文件认证] 创建文件认证配置。 +此时的配置如下所示。 + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - 名称 + - 值 + * - 主机名 + - SERVER + * - 协议 + - SAMBA + * - 用户名 + - (请输入) + * - 密码 + - (请输入) + +抓取 Amazon S3 存储桶 +--------------------- + +如果要抓取 my-bucket 存储桶中的文件，配置如下所示。 + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - 名称 + - 值 + * - 名称 + - S3 存储桶 + * - 路径 + - s3://my-bucket/ + +访问 S3 需要认证凭据。在"配置参数"中添加以下内容： + +:: + + client.endpoint=https://s3.ap-northeast-1.amazonaws.com + client.accessKey=您的访问密钥 + client.secretKey=您的私密密钥 + client.region=ap-northeast-1 + +.. note:: + Amazon S3 与 S3 兼容存储的支持由 ``fess-storage-s3`` 插件提供，该插件不随发行包分发。请从 + 管理界面的「系统 > 插件」页面安装，或执行 ``bin/fess-setup install plugin fess-storage-s3`` 。 + +抓取 Google Cloud Storage 存储桶 +--------------------------------- + +如果要抓取 my-gcs-bucket 存储桶中的文件，配置如下所示。 + +.. tabularcolumns:: |p{4cm}|p{8cm}| +.. list-table:: + :header-rows: 1 + + * - 名称 + - 值 + * - 名称 + - GCS 存储桶 + * - 路径 + - gcs://my-gcs-bucket/ + +访问 GCS 需要认证凭据。在"配置参数"中添加以下内容： + +:: + + client.projectId=您的项目ID + client.credentialsFile=/path/to/service-account.json + +.. note:: + Google Cloud Storage 支持由 ``fess-storage-gcs`` 插件提供，该插件不随发行包分发。请从管理 + 界面的「系统 > 插件」页面安装，或执行 ``bin/fess-setup install plugin fess-storage-gcs`` 。 + +相关页面 +======== + +- :doc:`../config/crawler-basic` +- :doc:`fileauth-guide` +- :doc:`../config/datastore/ds-overview` +- :doc:`../config/search-basic` +- :doc:`../user/index` + + +.. |image0| image:: ../../../resources/images/en/15.10/admin/fileconfig-1.png +.. |image1| image:: ../../../resources/images/en/15.10/admin/fileconfig-2.png +.. pdf :height: 940 px diff --git a/zh-cn/15.10/admin/general-guide.rst b/zh-cn/15.10/admin/general-guide.rst new file mode 100644 index 000000000..7b457d665 --- /dev/null +++ b/zh-cn/15.10/admin/general-guide.rst @@ -0,0 +1,679 @@ +==== +常规 +==== + +概述 +==== + +在此管理页面,可以管理 |Fess| 的配置。 +可以在不重启 |Fess| 的情况下更改各种 |Fess| 配置。 + +配置内容 +====== + +系统 +------ + +|image0| + +JSON响应 +:::::::::::: + +指定是否启用 JSON API。 + +需要登录 +::::::::::: + +指定搜索功能是否需要登录。 + +显示登录链接 +:::::::::::::: + +设置是否在搜索界面显示登录页面的链接。 + +折叠重复结果 +:::::::::::::: + +设置是否启用重复结果折叠。 + +当 ``search_engine.type`` 为 ``vanilla`` 或 ``aws`` 时，不显示此项，折叠始终处于禁用状态（请参阅 :doc:`../config/search-engine-type` ）。 + +显示缩略图 +::::::::::: + +设置是否启用缩略图显示。 + +系统属性 +:::::::: + +配置 |Fess| 的系统属性。 +以 ``键=值`` 格式指定,每行一个。 + +默认标签值 +::::::::::::::: + +描述默认添加到搜索条件的标签值。 +按角色或组指定时,请加上 role: 或 group: 前缀,如"role:admin=label1"。 + +默认排序值 +::::::::::::::: + +描述默认添加到搜索条件的排序值。 +按角色或组指定时,请加上 role: 或 group: 前缀,如"role:admin=content_length.desc"。 + +虚拟主机 +:::::::: + +设置虚拟主机。 +详情请参考 :doc:`配置指南的虚拟主机 <../config/security-virtual-host>`。 + +热门词响应 +::::::::::::::::: + +指定是否启用热门词 API。 + +CSV文件编码 +:::::::::::::::::: + +指定下载 CSV 文件的编码。 + +添加搜索参数 +::::::::::::::::: + +在搜索结果显示中传递参数时启用。 + +搜索文件代理 +::::::::::: + +指定是否启用搜索结果的文件代理。 + +使用浏览器区域设置 +::::::::::::::::: + +指定搜索时是否使用浏览器的区域设置。 + +SSO类型 +::::::: + +指定单点登录(Single Sign-On)类型。 + +- **无**: 不使用SSO +- **OpenID Connect**: 使用OpenID Connect（需要 ``fess-sso-oidc`` 插件） +- **SAML**: 使用SAML（需要 ``fess-sso-saml`` 插件） +- **SPNEGO**: 使用SPNEGO（需要 ``fess-sso-spnego`` 插件） +- **Entra ID**: 使用Microsoft Entra ID（需要 ``fess-sso-entraid`` 插件） + +爬虫 +-------- + +|image1| + +检查上次修改时间 +:::::::::::::: + +执行差分爬取时启用。 + +对于 HTTP/HTTPS 的 URL，当无法通过 HEAD 响应的 ``Last-Modified`` 判断时（索引中没有最后修改时间、HEAD 响应中没有 ``Last-Modified``\ 、或 HEAD 返回 200/404 以外的状态），会在 GET 中附加 ``If-None-Match`` （索引中保存的 ``ETag`` ）或 ``If-Modified-Since``\ ，进行条件 GET。服务器返回 ``304 Not Modified`` 的页面与未更新的页面一样，不会被重新获取。修改设置后等需要重新获取全部内容时，请禁用此设置后再爬取。 + +同时爬虫设置 +:::::::::::::: + +指定同时执行的爬取配置数。 + +用户代理 +:::::: + +指定爬虫使用的用户代理名称。 + +删除以前的文档 +:::::::::::::::::: + +以天数指定文档的有效期。通过爬取注册或更新的文档，会将爬取开始时刻起经过该天数后设为过期时间，在下一次爬取中再次发现的文档，其过期时间会被延长。已过期的文档由调度器的 Doc Purger 作业（默认每分钟运行一次）从索引中删除。 + +默认值为 ``3`` ，可指定的值为 ``-1`` 到 ``1000`` 。指定 ``-1`` 时，之后的爬取中注册或更新的文档不会设置过期时间（已设置的过期时间不会被延长）。 + +要忽略的错误类型 +::::::::::::::: + +超过阈值的失败 URL 将被排除在爬取对象之外,但此处指定的异常名称等即使超过阈值也会作为爬取对象。 + +失败次数阈值 +:::::::::::: + +如果爬取对象的文档被记录为失败 URL 的次数超过此处指定的次数,则在下次爬取时将被排除。 + +日志记录 +------ + +搜索日志 +:::::: + +指定是否启用搜索日志记录。 + +用户日志 +:::::::: + +指定是否启用用户日志记录。 + +收藏日志 +::::::::::: + +指定是否启用收藏日志记录。 + +删除以前的搜索日志 +::::::::::::::: + +删除指定天数之前的搜索日志。默认值为 ``-1``\ ，为 ``-1`` 时不会删除日志，而是一直保留。 +点击日志、收藏日志和聊天日志也按此天数删除。 + +删除以前的作业日志 +::::::::::::::::: + +删除指定天数之前的作业日志。默认值为 ``-1``\ ，为 ``-1`` 时不会删除。 + +删除以前的用户日志 +:::::::::::::::::: + +删除指定天数之前的用户日志。默认值为 ``-1``\ ，为 ``-1`` 时不会删除。 + +要删除日志的机器人名称 +::::::::::::::::: + +指定要从搜索日志中排除的机器人名称。 + +日志级别 +:::::::: + +指定 fess.log 的日志级别。 + +建议 +-------- + +按搜索词建议 +:::::::::::::: + +指定是否从搜索日志生成建议候选。 + +按文档建议 +:::::::::::::::::: + +指定是否从已索引的文档生成建议候选。 + +删除以前的建议信息 +:::::::::::::::::::: + +删除指定天数之前的建议数据。 + +LDAP +---- + +|image2| + +LDAP URL +:::::::: + +指定 LDAP 服务器的 URL。 + +基本DN +::::::: + +指定登录搜索界面的基本识别名。 + +绑定DN +::::::: + +指定管理员的绑定DN。 + +密码 +:::::::: + +指定绑定DN的密码。 + +用户DN +::::::: + +指定用户的识别名。 + +帐户过滤器 +::::::::::::::: + +指定用户的 Common Name 或 uid 等。 + +组过滤器 +:::::::::::::: + +指定要获取的组的过滤条件。 + +memberOf属性 +::::::::::: + +指定 LDAP 服务器可用的 memberOf 属性名。 +对于 Active Directory,为 memberOf。 +对于其他 LDAP 服务器,也可能是 isMemberOf。 + +安全认证 +::::::: + +指定 LDAP 的安全认证方式（例如: simple）。 + +初始上下文工厂 +::::::::::: + +指定 LDAP 的初始上下文工厂类（例如: com.sun.jndi.ldap.LdapCtxFactory）。 + +OpenID Connect +-------------- + +|image3| + +客户端ID +::::::: + +指定 OpenID Connect 提供商的客户端 ID。 + +客户端密钥 +:::::::: + +指定 OpenID Connect 提供商的客户端密钥。 + +认证服务器URL +:::::::::: + +指定 OpenID Connect 的认证服务器 URL。 + +令牌服务器URL +:::::::::: + +指定 OpenID Connect 的令牌服务器 URL。 + +重定向URL +:::::::: + +指定 OpenID Connect 的重定向 URL。 + +范围 +:::: + +指定 OpenID Connect 的范围。 + +基础URL +:::::: + +指定 OpenID Connect 的基础 URL。 + +默认组 +::::: + +指定 OpenID Connect 认证时分配给用户的默认组。 + +默认角色 +:::::: + +指定 OpenID Connect 认证时分配给用户的默认角色。 + +SAML +---- + +|image4| + +IdP实体ID +::::::::: + +指定 IdP（Identity Provider）的实体 ID。 + +IdP SSO URL +::::::::::: + +指定 IdP 的单点登录服务 URL。 + +IdP SLO URL +::::::::::: + +指定 IdP 的单点注销服务 URL。 + +IdP X.509证书 +::::::::::::: + +指定用于 IdP 的 SAML 断言签名验证的 X.509 公钥证书。 +仅指定 Base64 编码的内容,不含 ``-----BEGIN CERTIFICATE-----`` 和 ``-----END CERTIFICATE-----`` 行。 + +SP基础URL +:::::::: + +指定 SAML Service Provider 的基础 URL。 + +SP实体ID +:::::::: + +指定 SP（Service Provider）的实体 ID。 +设置 ``SP基础URL`` 时自动配置。 + +SP ACS URL +:::::::::: + +指定接收 SAML 断言的 Assertion Consumer Service（ACS）URL。 +设置 ``SP基础URL`` 时自动配置。 + +SP SLO URL +:::::::::: + +指定 SP 的单点注销服务 URL。 +设置 ``SP基础URL`` 时自动配置。 + +SP NameID格式 +::::::::::::: + +指定 SAML 断言中使用的 NameID 格式。 + +组属性名 +:::::: + +指定从 SAML 响应中获取组的属性名。 + +角色属性名 +:::::::: + +指定从 SAML 响应中获取角色的属性名。 + +默认组 +::::: + +指定 SAML 认证时分配给用户的默认组。 + +默认角色 +:::::: + +指定 SAML 认证时分配给用户的默认角色。 + +SPNEGO +------ + +|image5| + +.. note:: + SPNEGO 相关设置在底层库中以进程级别共享，因此更改这些设置后需要重启 |Fess| 才能生效。 + +Krb5配置 +:::::: + +指定 Kerberos 5 配置文件的路径。 + +登录配置 +:::::: + +指定 JAAS（Java Authentication and Authorization Service）登录配置文件的路径。 + +登录客户端模块 +:::::::::: + +指定 JAAS 的客户端登录模块名称。 + +登录服务器模块 +:::::::::: + +指定 JAAS 的服务器登录模块名称。 + +预认证用户名 +::::::::: + +指定 SPNEGO 预认证使用的用户名。 +将用户名和密码留空时，将使用基于 keytab 的服务器登录。 + +预认证密码 +:::::::: + +指定 SPNEGO 预认证使用的密码。 + +允许Basic认证 +:::::::::: + +指定是否允许 Basic 认证回退。 + +允许非安全Basic认证 +::::::::::::::: + +指定是否允许在非安全（HTTP）连接上使用 Basic 认证。 +为防止凭据以明文形式发送，默认情况下此项处于禁用状态（HTTPS 连接仍会提供 Basic 认证）。 + +NTLM提示 +:::::: + +指定是否启用 NTLM 提示。 + +允许本地主机 +::::::::: + +指定是否允许从本地主机访问。 +出于安全考虑，默认情况下此项处于禁用状态，因为启用后，来自同一主机的请求将在不进行 Kerberos 验证的情况下以服务器操作系统用户身份进行认证。 + +允许委托 +:::::: + +指定是否允许 Kerberos 委托。 + +日志记录级别 +:::::::::: + +以 0 到 7 之间的数值指定 SPNEGO 认证的日志输出级别。 +如果留空或指定非数值，则会自动判定日志级别。 + +Entra ID +-------- + +|image6| + +租户（ID或域） +:::::::::::::: + +指定 Microsoft Entra ID 的租户 ID 或域。 + +认证机构 +:::::: + +指定 Microsoft Entra ID 的认证机构 URL。 + +客户端ID +::::::: + +指定 Microsoft Entra ID 的应用程序（客户端）ID。 + +客户端密钥 +:::::::: + +指定 Microsoft Entra ID 的客户端密钥。 + +回复URL +::::: + +指定 Microsoft Entra ID 的回复（重定向）URL。 + +状态TTL +::::: + +指定认证状态的有效期（TTL）。 + +权限字段 +:::::: + +指定从 Entra ID 获取权限信息的字段。 + +默认组 +::::: + +指定 Entra ID 认证时分配给用户的默认组。 + +默认角色 +:::::: + +指定 Entra ID 认证时分配给用户的默认角色。 + +使用域服务 +:::::::: + +指定是否使用 Entra ID 域服务。 + +公告显示 +--------- + +|image7| + +.. note:: + + 公告中可以使用 HTML。搜索主题显示公告时，只会保留允许列表中的标签和属性：`` + + + +如果网站已使用 jQuery,则无需添加 jQuery 的 script 元素。 + +建议功能使用 |Fess| 的建议 API(``/api/v2/suggest-words``)。 +请将 ``url`` 更改为与构建的 |Fess| 服务器的 URL 一致。 + +可为 ``suggestor`` 指定的主要选项如下。 + +.. list-table:: suggestor 的主要选项 + :header-rows: 1 + :widths: 25 75 + + * - 选项 + - 说明 + * - ``ajaxinfo.url`` + - 建议 API 的 URL。指定 |Fess| 服务器的 ``/api/v2/suggest-words`` 。 + * - ``ajaxinfo.fn`` + - 作为建议对象的字段名数组。可直接使用初始值 ``["_default", "content", "title"]`` 。 + * - ``ajaxinfo.num`` + - 显示的候选项的最大数量。 + * - ``ajaxinfo.lang`` + - 用于缩小建议候选项范围的语言(可省略)。 + * - ``minterm`` + - 开始建议所需的最小输入字符数。 + * - ``adjustWidthVal`` + - 在输入框宽度上加算以调整建议显示区域宽度的值(像素)。 + * - ``searchForm`` + - 选择候选项时提交的搜索表单元素。 + * - ``boxCssInfo`` + - 应用于建议显示区域的 CSS。 + * - ``listSelectedCssInfo`` + - 应用于选中候选项的 CSS(可省略)。 + * - ``listDeselectedCssInfo`` + - 应用于未选中候选项的 CSS(可省略)。 + +请为 "z-index" 指定不与其他元素重叠的值。 + +.. note:: + 当搜索表单放置在与 |Fess| 服务器不同域名的页面上时,对建议 API 的请求将成为跨源(cross-origin)通信。 + |Fess| 在初始设置中允许所有来源(``api.cors.allow.origin=*``),因此可直接使用。 + 如需限制访问,请更改 ``fess_config.properties`` 中的 ``api.cors.allow.origin`` 。 + +.. note:: + ``/api/v2/suggest-words`` 是 |Fess| 本体提供的 API。 + 早期版本中使用的 ``/api/v1/suggest-words`` 已不再由 |Fess| 本体提供,要使用它需要安装 ``fess-webapp-v1-api`` 插件。 + 新构建时请使用 ``/api/v2/suggest-words`` 。 diff --git a/zh-cn/15.10/config/search-geosearch.rst b/zh-cn/15.10/config/search-geosearch.rst new file mode 100644 index 000000000..a86cc662a --- /dev/null +++ b/zh-cn/15.10/config/search-geosearch.rst @@ -0,0 +1,347 @@ +============ +位置信息搜索 +============ + +概述 +==== + +|Fess| 可以对具有经纬度位置信息的文档执行指定地理范围的搜索。 +使用此功能可以搜索距离特定地点一定距离内的文档, +或构建与 Google 地图等地图服务集成的搜索系统。 + +在内部,使用 OpenSearch 的 geo-distance 查询,对存在于指定中心点 +指定距离以内的文档进行筛选。 + +用例 +==== + +位置信息搜索可用于以下用途。 + +- 店铺搜索: 搜索距用户当前位置较近的店铺 +- 房地产搜索: 搜索距特定车站或设施一定距离内的房产 +- 活动搜索: 搜索指定地点周边的活动信息 +- 设施搜索: 搜索旅游景点或公共设施附近 + +配置方法 +======== + +索引生成时的配置 +---------------- + +位置信息字段定义 +~~~~~~~~~~~~~~~~ + +在 |Fess| 中,\ ``location`` 作为存储位置信息的字段已标准定义。 +此字段被配置为 OpenSearch 的 ``geo_point`` 类型。 + +位置信息注册格式 +~~~~~~~~~~~~~~~~ + +索引生成时,将纬度和经度用逗号分隔设置到 ``location`` 字段中。 + +**格式:** + +:: + + 纬度,经度 + +**示例:** + +:: + + 45.17614,-93.87341 + +.. note:: + 纬度范围为 -90 到 90,经度范围为 -180 到 180。 + +数据存储爬取的配置示例 +~~~~~~~~~~~~~~~~~~~~~~ + +使用数据存储爬取时,从具有位置信息的数据源将经纬度设置到 ``location`` 字段。 + +**示例: 从数据库获取** + +如果纬度和经度分别保存在不同的列中,请在 SQL 中将其拼接为逗号分隔的字符串。 +数据存储的参数是每行一个项目,因此请在 ``sql=`` 之后用一行写出 SQL +（如果换行拆成多行,只有第一行的 ``SELECT`` 会被当作 SQL,从而导致语法错误）。 + +:: + + sql=SELECT id, name, address, CONCAT(latitude, ',', longitude) AS location FROM stores + +在数据存储配置脚本中,将获取到的值映射到 ``location`` 字段。 +在数据库数据存储中,SQL 的列名（包括用 ``AS`` 指定的别名）会直接成为脚本的变量名, +不带 ``data.`` 之类的前缀。 + +:: + + location=location + +通过脚本添加位置信息 +~~~~~~~~~~~~~~~~~~~~ + +也可以使用爬取配置的脚本功能动态向文档添加位置信息（默认使用JavaScript，也可选择Groovy）。 +直接向字段名赋值即可。 + +:: + + // 将经纬度设置到 location 字段 + location="35.681236,139.767125" + +有关脚本的详细信息,请参阅 :doc:`scripting-overview`。 + +搜索时的配置 +------------ + +要执行位置信息搜索,需在请求参数中指定搜索中心点和范围。 + +请求参数 +~~~~~~~~ + +位置信息搜索的参数名格式为 ``geo.<字段名>.point`` 和 ``geo.<字段名>.distance``\ 。 +``<字段名>`` 处填写通过 ``query.geo.fields`` 配置的字段名 +（默认为 ``location``）。 + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 参数名 + - 说明 + * - ``geo.location.point`` + - 搜索中心地点的纬度·经度（逗号分隔。示例: ``35.681236,139.767125`` ） + * - ``geo.location.distance`` + - 距中心点的搜索半径（带单位。示例: ``10km`` ） + +.. note:: + ``point`` 和 ``distance`` 须成对指定。未指定 ``distance`` 的 ``point`` 将被忽略。 + 此外, ``point`` 的值必须由"纬度,经度"两个数值组成,格式不正确时将报错。 + +.. note:: + 位置信息搜索是对搜索词 ``q`` 的进一步筛选。 ``q`` 为空时不会执行搜索本身, + 结果为 0 件。位置信息搜索的请求中请指定搜索词。 + +.. note:: + 对同一字段指定多个 ``point`` 时为 OR 条件（位于任一范围内）， + 对多个字段分别指定时为 AND 条件（同时位于所有范围内）。 + +距离单位 +~~~~~~~~ + +距离可使用以下单位。 + +- ``km``: 千米 +- ``m``: 米 +- ``mi``: 英里 +- ``yd``: 码 + +.. note:: + 距离值将直接传递给 OpenSearch,因此除上述单位外,还可使用 OpenSearch 支持的其他单位 + （ ``cm`` 、 ``mm`` 、 ``ft`` 、 ``in`` 、 ``nmi`` 等）。 + +搜索结果的排序顺序 +~~~~~~~~~~~~~~~~~~ + +位置信息搜索作为 **过滤器** 运行,将结果限定为指定范围内的文档。 +它不影响搜索评分（相关度），也不会按距中心点的远近进行排序。 +结果将按常规方式以相关度顺序（或 ``sort`` 参数指定的顺序）返回。 + +.. note:: + |Fess| 不支持按距离排序（按由近到远排列）。 + 如需按距离顺序显示,请在客户端根据响应中包含的经纬度自行排序。 + +搜索示例 +======== + +基本搜索 +-------- + +搜索东京站（35.681236, 139.767125）半径 10km 内的文档: + +:: + + http://localhost:8080/search?q=搜索关键词&geo.location.point=35.681236,139.767125&geo.location.distance=10km + +当前位置周边搜索 +---------------- + +搜索距用户当前位置 1km 内的内容: + +:: + + http://localhost:8080/search?q=拉面&geo.location.point=35.681236,139.767125&geo.location.distance=1km + +通过 API 使用 +------------- + +v2 JSON 搜索 API（ ``/api/v2/search`` ）同样支持位置信息搜索。 +将 ``geo.location.point`` 和 ``geo.location.distance`` 作为请求参数指定即可。 + +:: + + curl "http://localhost:8080/api/v2/search?q=酒店&geo.location.point=35.681236,139.767125&geo.location.distance=5km" + +搜索结果通过公共信封的 ``response.data`` 数组返回。API 的详细信息请参阅 :doc:`../api/api-search` +和 :doc:`../api/api-overview`。 + +.. note:: + ``location`` 字段默认不包含在 API 响应中。如需在搜索结果中包含经纬度, + 请在 ``fess_config.properties`` 中添加以下 2 项配置,并重启 |Fess|\ 。 + ``query.additional.response.fields`` 用于从搜索引擎中额外获取字段, + ``query.additional.api.response.fields`` 用于允许将字段输出到 API 响应中。 + 只设置其中一项时,响应中不会包含 ``location``\ 。 + + :: + + query.additional.response.fields=location + query.additional.api.response.fields=location + +字段名自定义 +============ + +更改默认字段名 +-------------- + +要更改位置信息搜索使用的字段名, +请在 ``fess_config.properties`` 中修改以下配置。 + +:: + + query.geo.fields=location + +指定多个字段名时,请用逗号分隔。 + +:: + + query.geo.fields=location,geo_point,coordinates + +.. note:: + - 请求参数名与所配置的字段名联动。例如,设置 + ``query.geo.fields=coordinates`` 时,需指定 ``geo.coordinates.point`` 和 + ``geo.coordinates.distance``\ 。 + - 此处指定的各字段必须在索引映射中定义为 ``geo_point`` 类型。 + +实现示例 +======== + +Web 应用程序实现 +---------------- + +JavaScript 获取当前位置并执行搜索的示例: + +.. code-block:: javascript + + // 使用浏览器的 Geolocation API 获取当前位置 + navigator.geolocation.getCurrentPosition(function(position) { + const latitude = position.coords.latitude; + const longitude = position.coords.longitude; + const distance = "5km"; + + // 构建搜索 URL（搜索词 q 不可省略） + const searchUrl = `/search?q=${encodeURIComponent('店铺')}&geo.location.point=${latitude},${longitude}&geo.location.distance=${distance}`; + + // 执行搜索 + window.location.href = searchUrl; + }); + +Google 地图集成 +--------------- + +在 Google 地图上用标记显示搜索结果的示例: + +.. note:: + 此示例从搜索结果中引用 ``location`` 字段。需要事先设置 + ``query.additional.response.fields=location`` 和 ``query.additional.api.response.fields=location``, + 以便在响应中包含经纬度。 + +.. code-block:: javascript + + // 初始化地图 + const map = new google.maps.Map(document.getElementById('map'), { + center: {lat: 35.681236, lng: 139.767125}, + zoom: 13 + }); + + // 使用 Fess v2 搜索 API 执行位置信息搜索 + fetch('/api/v2/search?q=店铺&geo.location.point=35.681236,139.767125&geo.location.distance=5km') + .then(response => response.json()) + .then(json => { + // 将搜索结果（response.data 数组）显示为标记 + json.response.data.forEach(doc => { + if (doc.location) { + const [lat, lng] = doc.location.split(',').map(Number); + new google.maps.Marker({ + position: {lat: lat, lng: lng}, + map: map, + title: doc.title + }); + } + }); + }); + +性能优化 +======== + +确认索引设置 +------------ + +位置信息字段在安装目录的 +``app/WEB-INF/classes/fess_indices/fess/doc.json`` 中定义为 ``geo_point`` 类型。 + +:: + + "location": { + "type": "geo_point" + } + +``geo_point`` 类型的字段使用 BKD 树进行索引,因此 geo-distance 查询可高效执行。 + +搜索范围和响应的优化 +-------------------- + +增大搜索半径时,范围内匹配的文档数量会增加,获取和渲染结果可能需要更长时间。 + +- 请根据用途设置适当的搜索半径。 +- 在地图显示等需要处理大量结果的场景中,请调整页面大小（ ``num`` 参数）以限制获取数量。 + +故障排除 +======== + +位置信息搜索无法工作 +-------------------- + +1. 请确认 ``location`` 字段中是否正确存储了数据。 +2. 请确认纬度经度格式是否正确（ ``纬度,经度`` 逗号分隔。值不为两个时将报错）。 +3. 请确认 OpenSearch 的索引映射中 ``location`` 是否定义为 ``geo_point`` 类型。 +4. 请确认是否同时指定了 ``point`` 和 ``distance``\ （未指定 ``distance`` 的 ``point`` 将被忽略）。 + +搜索结果未返回 +-------------- + +1. 请确认指定距离范围内是否存在文档。 +2. 请确认纬度经度值是否在正确范围内（纬度: -90〜90, 经度: -180〜180）。 +3. 请确认距离单位是否正确指定。 + +API 响应中不包含位置信息 +------------------------ + +``location`` 字段默认不包含在 API 响应中。 +如需在搜索结果中包含经纬度,请在 ``fess_config.properties`` 中 +同时设置 ``query.additional.response.fields=location`` 和 ``query.additional.api.response.fields=location``, +并重启 |Fess|\ 。 + +位置信息未正确注册 +------------------ + +1. 请确认爬取时 ``location`` 字段是否正确设置。 +2. 请确认数据源的纬度经度是否能够正确获取。 +3. 通过脚本设置位置信息时,请确认是否为 ``纬度,经度`` 的字符串格式。 + +参考信息 +======== + +有关位置信息搜索的详细信息,请参考以下资源。 + +- `OpenSearch Geo Queries `_ +- `OpenSearch Geo Point `_ +- `Geolocation API (MDN) `_ diff --git a/zh-cn/15.10/config/search-scroll.rst b/zh-cn/15.10/config/search-scroll.rst new file mode 100644 index 000000000..4fee6d47c --- /dev/null +++ b/zh-cn/15.10/config/search-scroll.rst @@ -0,0 +1,453 @@ +======================== +批量获取搜索结果 +======================== + +概述 +==== + +|Fess| 的常规搜索通过分页功能仅显示一定数量的搜索结果。 +如需批量获取所有搜索结果，请使用滚动搜索（Scroll Search）功能。 + +此功能适用于数据批量导出、备份、大量数据分析等 +需要处理所有搜索结果的情况。 + +用例 +==== + +滚动搜索适用于以下用途。 + +- 搜索结果全量导出 +- 数据分析用大量数据获取 +- 批处理中的数据获取 +- 与外部系统的数据同步 +- 报告生成用数据收集 + +.. warning:: + 滚动搜索会返回大量数据，与常规搜索相比 + 会消耗更多服务器资源。请仅在必要时启用。 + +配置方法 +======== + +启用滚动搜索 +------------ + +默认情况下，出于安全和性能考虑，滚动搜索被禁用。 +要启用，请在 ``app/WEB-INF/classes/fess_config.properties`` （RPM/DEB 包的情况下为 +``/etc/fess/fess_config.properties`` ）中修改以下配置。 + +:: + + api.search.scroll=true + +.. note:: + 配置变更后，需要重启 |Fess|\ 。 + +滚动上下文有效期 +---------------- + +滚动搜索的滚动上下文有效期在 |Fess| 内部固定为 ``1m`` （1分钟）。 +该值无法通过 ``fess_config.properties`` 修改。 + +.. note:: + ``index.scroll.search.timeout`` 配置项存在，但该项用于涉及索引更新、删除的 + 内部处理（update by query / delete by query），不会影响本功能（搜索 + 滚动）的超时时间。 + +响应字段配置 +------------ + +可以自定义搜索结果响应中包含的字段。 +默认返回多个字段，但可以通过以下配置追加字段。 + +:: + + query.additional.scroll.response.fields=content + query.additional.api.response.fields=content + +指定多个字段时，请用逗号分隔。 + +.. note:: + ``content`` 字段默认不包含在响应中。如需获取正文全文，需要同时使用上述两项配置： + ``query.additional.scroll.response.fields`` 用于追加从索引中获取的字段， + ``query.additional.api.response.fields`` 用于追加允许 API 响应输出的字段。只配置其中一项时，不会输出 ``content``。 + +使用方法 +======== + +基本使用方法 +------------ + +滚动搜索通过以下 URL 访问。 + +:: + + http://localhost:8080/api/v2/documents/all?q=搜索关键词 + +搜索结果以 NDJSON（Newline Delimited JSON）格式返回。 +每行以 JSON 格式输出一个文档。 + +**示例:** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=Fess" + +请求参数 +-------- + +滚动搜索可使用以下参数。 + +.. note:: + 滚动搜索仅支持 GET 方法。对于 ``POST`` 等会改变状态的方法，会先进行 CSRF 令牌的验证， + 因此没有有效 ``X-Fess-CSRF-Token`` 头的请求将返回 ``403 Forbidden`` （ ``forbidden`` ） + （参见 :doc:`../api/api-overview` ）。附带有效令牌时，将返回 + ``405 Method Not Allowed`` （ ``method_not_allowed`` ）。 + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - 参数名 + - 说明 + * - ``q`` + - 搜索查询（必需） + * - ``num`` + - 一次滚动获取的条数（默认值：10，最大值：100） + * - ``fields.label`` + - 按标签过滤 + +.. note:: + ``num`` 的最大值由 ``paging.search.page.max.size`` （默认值：100）控制。 + 指定超过最大值的数值时，将自动截断为最大值。 + 默认值使用 ``paging.search.page.size`` （默认值：10）。 + ``num`` 指定 0 以下的值时，将返回错误（``INVALID_REQUEST``）。 + +指定搜索查询 +------------ + +可以像常规搜索一样指定搜索查询。 + +**示例：关键词搜索** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=搜索引擎" + +**示例：字段指定搜索** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=title:Fess" + +**示例：全量获取（无搜索条件）** + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=*:*" + +指定获取条数 +------------ + +可以更改一次滚动获取的条数。 + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=Fess&num=100" + +.. note:: + ``num`` 参数设置过大会导致内存使用量增加。 + 默认最大值为 100。如需更大的值，请修改 + ``paging.search.page.max.size`` 配置。 + +按标签过滤 +---------- + +可以仅获取属于特定标签的文档。 + +:: + + curl "http://localhost:8080/api/v2/documents/all?q=*:*&fields.label=public" + +关于访问控制 +------------ + +.. note:: + 滚动搜索与常规搜索相同，同样会应用基于角色的访问控制（RBAC）。 + 仅返回基于请求角色信息可访问的文档， + 无查看权限的文档不会包含在结果中。 + +.. warning:: + 滚动搜索端点默认不要求认证（任何人均可访问）。 + 但返回的文档会经过上述基于角色的访问控制进行过滤。 + 如需限制端点本身的访问，请通过反向代理等设置 IP 地址限制或 + 认证。 + +响应格式 +======== + +NDJSON 格式 +----------- + +滚动搜索的响应以 NDJSON（Newline Delimited JSON）格式返回。 +Content-Type 为 ``application/x-ndjson; charset=UTF-8``\ 。 +每行表示以 ``{"data": {...}}`` 形式包装的一个文档。 + +**示例:** + +:: + + {"data":{"url":"http://example.com/page1","title":"Page 1","digest":"..."}} + {"data":{"url":"http://example.com/page2","title":"Page 2","digest":"..."}} + {"data":{"url":"http://example.com/page3","title":"Page 3","digest":"..."}} + +.. note:: + 每个文档存储在 ``data`` 键下。客户端在解析每行后， + 请引用 ``data`` 键的值。 + +错误时的行为 +------------ + +流式传输开始后若服务器端发生错误，响应的最后一行将 +输出如下错误终止行。 + +:: + + {"error":{"code":"internal_error","message":"stream error"}} + +.. note:: + 客户端可通过检查最后一行是否包含 ``error`` 键，来判断 + "流是否正常完成"还是"服务器端中途发生了错误"。 + 需要注意的是，若错误终止行本身的写入失败，则终止行不会输出， + 流将中途结束，因此请将意外断开也视为错误处理。 + +响应字段 +-------- + +默认包含的字段： + +- ``score``: 搜索评分 +- ``_id``: 文档 ID（OpenSearch 的文档 ID） +- ``doc_id``: 文档 ID（|Fess| 内部） +- ``boost``: 提升值 +- ``content_length``: 内容长度 +- ``host``: 主机名 +- ``site``: 站点 +- ``last_modified``: 最后更新时间 +- ``timestamp``: 时间戳 +- ``mimetype``: MIME 类型 +- ``filetype``: 文件类型 +- ``filename``: 文件名 +- ``created``: 创建时间 +- ``title``: 标题 +- ``digest``: 正文摘要 +- ``url``: 文档 URL +- ``thumbnail``: 缩略图 +- ``click_count``: 点击次数 +- ``favorite_count``: 收藏次数 +- ``has_cache``: 是否有缓存 +- ``content_title``: 显示用标题 +- ``content_description``: 显示用正文摘要 +- ``url_link``: 显示用链接 URL +- ``site_path``: 站点路径 + +.. note:: + 实际输出的字段仅限于 API 响应中允许的字段。 + 不存在值的字段不会输出。 + +.. note:: + ``content`` （正文全文）默认不包含在响应中。 + 同时追加到 ``query.additional.scroll.response.fields`` 和 + ``query.additional.api.response.fields`` 后才会输出（参见“响应字段配置”）。 + +数据处理示例 +============ + +Python 处理示例 +--------------- + +.. code-block:: python + + import requests + import json + + # 执行滚动搜索 + url = "http://localhost:8080/api/v2/documents/all" + params = { + "q": "Fess", + "num": 100 + } + + response = requests.get(url, params=params, stream=True) + + # 逐行处理 NDJSON 格式的响应 + for line in response.iter_lines(): + if line: + record = json.loads(line) + if "error" in record: + # 流传输中途发生错误 + print("stream error:", record["error"]) + break + doc = record["data"] + print(f"Title: {doc.get('title')}") + print(f"URL: {doc.get('url')}") + print("---") + +保存到文件 +---------- + +将搜索结果保存到文件的示例： + +.. code-block:: bash + + curl "http://localhost:8080/api/v2/documents/all?q=*:*" > all_documents.ndjson + +转换为 CSV +---------- + +使用 jq 命令转换为 CSV 的示例： + +.. code-block:: bash + + curl "http://localhost:8080/api/v2/documents/all?q=Fess" | \ + jq -r '.data | [.url, .title, .score] | @csv' > results.csv + +数据分析 +-------- + +分析获取数据的示例： + +.. code-block:: python + + import json + import pandas as pd + + # 读取 NDJSON 文件（提取每行的 data 键） + documents = [] + with open('all_documents.ndjson', 'r') as f: + for line in f: + record = json.loads(line) + if "data" in record: + documents.append(record["data"]) + + # 转换为 DataFrame + df = pd.DataFrame(documents) + + # 基本统计 + print(f"Total documents: {len(df)}") + print(f"Average score: {df['score'].mean()}") + + # URL 域名分析 + df['domain'] = df['url'].apply(lambda x: x.split('/')[2]) + print(df['domain'].value_counts()) + +性能与最佳实践 +============== + +高效使用方法 +------------ + +1. **设置适当的 num 参数** + + - 过小会增加通信开销 + - 过大会增加内存使用量 + - 默认最大值：100 + +2. **优化搜索条件** + + - 指定搜索条件以仅获取所需文档 + - 仅在确实需要时执行全量获取 + +3. **使用非高峰时段** + + - 大量数据获取请在系统负载较低的时段执行 + +4. **批处理使用** + + - 定期数据同步等作为批处理任务执行 + +内存使用量优化 +-------------- + +处理大量数据时，请使用流式处理来抑制内存使用量。 + +.. code-block:: python + + import requests + import json + + url = "http://localhost:8080/api/v2/documents/all" + params = {"q": "*:*", "num": 100} + + # 流式处理 + with requests.get(url, params=params, stream=True) as response: + for line in response.iter_lines(decode_unicode=True): + if line: + record = json.loads(line) + if "error" in record: + break + # 处理文档 + process_document(record["data"]) + +安全注意事项 +============ + +访问限制 +-------- + +滚动搜索会返回大量数据，请设置适当的访问限制。 +端点本身默认不要求认证，请根据需要考虑以下对策。 + +1. **IP 地址限制** + + 仅允许特定 IP 地址访问 + +2. **API 认证** + + 通过反向代理等使用 API 令牌或 Basic 认证 + +3. **基于角色的访问控制** + + 返回的文档经 |Fess| 的基于角色的访问控制过滤 + +速率限制 +-------- + +为防止过度访问，建议在反向代理上设置速率限制。 + +故障排除 +======== + +无法使用滚动搜索 +---------------- + +1. 请确认 ``api.search.scroll`` 是否设置为 ``true``\ 。 +2. 请确认是否已重启 |Fess|\ 。 +3. 请确认错误日志。 + +发生超时错误 +------------ + +1. 请减小 ``num`` 参数以分散处理。 +2. 请缩小搜索条件以减少获取数据量。 + +内存不足错误 +------------ + +1. 请减小 ``num`` 参数。 +2. 请增加 |Fess| 的堆内存大小。 +3. 请确认 OpenSearch 的堆内存大小。 + +响应为空 +-------- + +1. 请确认搜索查询是否正确。 +2. 请确认指定的标签和过滤条件是否正确。 +3. 基于角色的访问控制会将无查看权限的文档排除在结果之外。请确认请求的角色配置。 + +参考信息 +======== + +- :doc:`search-basic` - 搜索功能详情 +- :doc:`search-advanced` - 搜索相关配置 +- `OpenSearch Scroll API `_ diff --git a/zh-cn/15.10/config/search-semantic.rst b/zh-cn/15.10/config/search-semantic.rst new file mode 100644 index 000000000..d8dea779f --- /dev/null +++ b/zh-cn/15.10/config/search-semantic.rst @@ -0,0 +1,811 @@ +=================================================== +语义搜索（内容分块 + 向量搜索） +=================================================== + +概述 +==== + +在 |Fess| 15.10 中，**内容分块功能**\ ——将文档正文拆分为若干分块，并为每个分块生成并存储嵌入 +向量——已被整合进核心。生成的向量用于以下两个用途： + +- **语义搜索**：一种通过 Rank Fusion 将关键词（BM25）搜索与向量搜索结合起来的混合搜索。即使没有 + 精确的关键词匹配，语义上与查询相近的文档也可以被匹配到。 +- **AI 搜索模式（RAG）**：在生成回答时，仅选取与问题语义最相近的分块作为 LLM 的上下文，从而提升 + 回答质量并提高 token 使用效率。 + +以上功能默认全部禁用。除非您启用它们，否则 |Fess| 会继续像以往一样仅使用关键词搜索。如果您正在 +从 15.7 或更早版本升级 |Fess|，或此前一直在使用 ``fess-webapp-semantic-search`` 插件，请参阅 +:ref:`semantic-search-migration`\ 。 + +处理流程 +-------- + +1. 爬虫像往常一样对文档进行索引（此时尚不存在任何分块）。 +2. 调度器任务 **Content Chunk Vector Indexer** 会查找尚未处理的文档，将其正文（``content`` 字段） + 拆分为分块并生成嵌入向量，然后存入 ``content_chunk_vector`` 字段。此时 ``content`` 字段本身也会 + 被改写为分块数组（``content_length`` 仍保留原来的值）。 +3. 该处理的结果会被记录到 ``content_chunk_status`` 字段中（说明见下文）。 +4. 当 ``content_chunker.search.enabled=true`` 时，语义搜索器会在搜索时参与 Rank Fusion。 + +前提条件 +======== + +- **带 k-NN 插件的 OpenSearch**：在 |Fess| 15.10 中，无论内容分块功能是否启用，搜索索引 + （``fess.search``）的映射中始终包含 ``content_chunk_vector`` 字段（``nested`` 类型，其 + ``vector`` 子字段才是用于 ANN 的 ``knn_vector`` 类型），并且索引设置中也始终包含 + ``index.knn: true``\ 。因此，如果 OpenSearch 未安装 k-NN 插件，创建新索引会直接失败， + |Fess| 也无法启动。 + + .. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - 配置 + - k-NN 插件支持情况 + * - Docker（``ghcr.io/codelibs/fess-opensearch``）、始终连接到单独安装的外部 OpenSearch 的 + RPM/DEB 软件包，或其他外部 OpenSearch（标准发行版） + - 完全支持，包括 ``faiss``\ 。 + * - 外部 OpenSearch 的\ **最小化发行版** + - **不支持。** 由于不包含 k-NN 插件，创建新索引会失败。 + + ``content_chunker.search.knn.engine`` 在上述任何配置下都不接受 ``nmslib`` 作为取值： + ``content_chunk_vector`` 是一个 ``nested`` 字段，而 k-NN 插件仅对 ``lucene``/``faiss`` 引擎 + 支持 nested 字段（``nmslib`` 从 OpenSearch 3.0 起也已被弃用并受限）。设置该值会回退为 + ``lucene`` 并记录一条警告；其他 ANN 相关设置的可接受取值请参阅下方的配置参考。 + +- **外部集群的 OpenSearch 版本**：内置的 ``fess.search`` 索引设置会在 + ``fess_indices/fess.json``\ （以及 ``vanilla`` 、 ``aws`` 和已弃用的 ``cloud`` 所使用的 ``fess_indices/_vanilla/fess.json`` ）中始终发送 ``index.knn`` 和 + ``knn.derived_source.enabled``\ 。后者是 k-NN 插件中较新的设置，无法识别该设置的旧版 + OpenSearch 无论是否安装 k-NN 插件，创建索引都会失败。关于 |Fess| 15.10 支持的 OpenSearch + 版本，请参阅 :doc:`../install/prerequisites`\ 。 + +- **嵌入提供商**：使用以下之一。 + +.. list-table:: + :header-rows: 1 + :widths: 20 25 55 + + * - 配置值 + - 提供方 + - 说明 + * - ``opensearch`` + - |Fess| 核心（内置） + - 使用部署到 OpenSearch ML Commons 的嵌入模型。无需额外插件。默认设置。 + * - ``ollama`` + - ``fess-llm-ollama`` 插件 + - 使用 Ollama 嵌入模型（例如 ``nomic-embed-text``）。 + * - ``openai`` + - ``fess-llm-openai`` 插件 + - 使用 OpenAI 嵌入 API。 + * - ``gemini`` + - ``fess-llm-gemini`` 插件 + - 使用 Google Gemini 嵌入 API。 + * - ``bedrock`` + - ``fess-llm-bedrock`` 插件 + - 通过 Amazon Bedrock 使用 Amazon Titan Text Embeddings V2 或 Cohere Embed。 + * - ``none`` + - |Fess| 核心（内置） + - 仅将文档拆分为分块，不生成向量（仅分块模式）。 + +配置参考 +======== + +所有 ``content_chunker.*`` 配置都统一在\ **系统属性**\ （``system.properties``）这一个通道中。 +可以设置在 ``app/WEB-INF/conf/system.properties``\ （RPM/DEB 软件包为 +``/etc/fess/system.properties``\ ，Docker 为 ``/opt/fess/system.properties``）中，也可以通过启动 +选项 ``-Dfess.system.<键名>`` 提供初始值。配置值会在运行时被重新加载，因此大多数设置在更改后会立即 +生效。唯一的例外是启用 ``content_chunker.search.enabled``\ （``false`` → ``true``）：由于语义 +搜索器仅在启动时注册，**此项更改需要重启才能生效**。 + +.. note:: + + ``content_chunker.*`` 配置项只会从 ``system.properties`` 通道读取。写在 + ``fess_config.properties`` 或 ``-Dfess.config.<键名>`` 中都会被忽略，因此请务必设置在 + ``system.properties`` 中。另外，管理界面的「系统信息」→「配置信息」是查看当前值的\ **只读**\ 页面， + 无法通过该页面设置 ``content_chunker.*``\ 。 + +system.properties 配置 +------------------------ + +.. list-table:: + :header-rows: 1 + :widths: 40 15 45 + + * - 属性 + - 默认值 + - 说明 + * - ``content_chunker.enabled`` + - ``false`` + - 整个内容分块功能的总开关 + * - ``content_chunker.chunker.name`` + - ``length`` + - 分块方式 + * - ``content_chunker.length.chunk_size`` + - ``800`` + - 每个分块的目标字符数。启用边界感知切分（默认）时，这是目标值而非硬性上限：分块可能比该值短 + ``boundary.lookback_percent``\ ，也可能长 ``max(lookahead, 32)`` 个字符（默认配置下为 + 640～840 个字符）。请针对嵌入模型的 token 上限预留这一余量 + * - ``content_chunker.length.overlap`` + - ``0`` + - 各分块之间重叠的字符数。重启位置同样会对齐到边界，而对齐只会将其前移，因此实际重叠介于 + 该值与该值的两倍之间 + * - ``content_chunker.length.boundary.enabled`` + - ``true`` + - 将每个切分点移动到合适的文本边界，而不是恰好在 ``chunk_size`` 个字符处切分。候选项分为 + 多个层级，取所存在的最高层级中距离最近的一个：换行或句末优先，其次是分句符号或空格，最后是 + 书写体系变化。设为 ``false`` 可恢复此前的固定长度行为 + * - ``content_chunker.length.boundary.lookback_percent`` + - ``20`` + - 在理想切分点之前搜索边界的范围（占 ``chunk_size`` 的百分比，0～50） + * - ``content_chunker.length.boundary.lookahead_percent`` + - ``5`` + - 在理想切分点之后搜索句末或换行的范围（占 ``chunk_size`` 的百分比，0～25）。仅在切分点 + 之前未找到候选时使用 + * - ``content_chunker.max_chunks_per_document`` + - ``1000`` + - 每个文档的最大分块数。超过此值的文档将被标记为 ``skipped``\ ，并且不会生成嵌入。 + 由于边界感知切分会使分块变短，一个文档生成的分块数比固定长度切分约多 3%～25%\ ， + 因此包含超大文档的语料可能需要调高此值 + * - ``content_chunker.embedding.name`` + - ``opensearch`` + - 嵌入提供商（``opensearch`` / ``ollama`` / ``openai`` / ``gemini`` / ``bedrock`` / ``none``） + * - ``content_chunker.embedding.dimension`` + - ``768`` + - 嵌入向量的维度。创建映射时会使用该值，因此它\ **必须**\ 与您所用嵌入模型的维度一致。该值有 + 两条读取路径，行为并不相同。创建索引映射时，未设置时会\ **不带任何警告**\ 地回退为 ``768``\ ； + 为空、非数字、小于等于 0、以及超过 ``16000``\ （k-NN 插件自身的上限）的情况，则会带警告回退为 + ``768``\ 。而在执行嵌入处理时 + 没有任何回退，未设置、非数字、小于等于 0 都会直接出错。由于超过 ``16000`` 的值在运行时并 + 不会被拒绝，届时只有映射会以 ``768`` 创建，从而导致维度不一致。映射的维度在索引创建之后无法 + 更改；对于在未设置该值的情况下创建的索引，恢复方法请参阅“注意事项”中的“在未设置维度的情况下 + 创建了索引” + * - ``content_chunker.job.concurrency`` + - ``2`` + - 索引器任务的并行工作线程数 + * - ``content_chunker.job.bulk_size`` + - ``20`` + - 每批获取并写入的文档数 + * - ``content_chunker.job.max_documents_per_run`` + - ``-1``\ （无限制） + - 每次任务运行处理的最大文档数。任何小于等于 ``0`` 的值都视为无限制 + * - ``content_chunker.job.retry_failed`` + - ``false`` + - 设置为 ``true`` 时，上一次运行中以 ``content_chunk_status=fail`` 结束的文档也会被纳入下一次 + 运行的处理对象。没有自动重试或尝试次数跟踪；预期的使用方式是先修复根本原因，然后临时启用 + 此项以进行重试 + * - ``content_chunker.chat.top_k`` + - ``3`` + - AI 搜索模式生成回答时选取的分块数 + * - ``content_chunker.search.enabled`` + - ``false`` + - 语义搜索的 Rank Fusion 集成（**启用此项需要重启**） + * - ``content_chunker.search.min_score`` + - （未设置） + - 结果被纳入所需的最小余弦相似度（0-1）。未设置时不进行截断。在 ``ann`` 模式下，若 + ``search.knn.space_type`` 不是 ``cosinesimil``\ ，则无法定义基于余弦的阈值，因此会带警告 + 跳过该截断 + * - ``content_chunker.search.knn.method`` + - ``hnsw`` + - ANN 索引方法。目前唯一支持的取值是 ``hnsw``，其他取值会带警告回退为 ``hnsw``\ （会反映到 + 映射中；更改需要重新创建索引） + * - ``content_chunker.search.knn.engine`` + - ``lucene`` + - ANN 引擎。仅支持 ``lucene`` 或 ``faiss``\ （参见上方的前提条件），其他取值会带警告回退为 + ``lucene``\ （会反映到映射中；更改需要重新创建索引） + * - ``content_chunker.search.knn.space_type`` + - ``cosinesimil`` + - 距离空间。仅支持 ``cosinesimil``、``innerproduct``、``l2``，其他取值会带警告回退为 + ``cosinesimil``\ （会反映到映射中；更改需要重新创建索引） + * - ``content_chunker.search.knn.k`` + - ``100`` + - 每次 ANN 查询在每个分片上检索的邻居数量。由 |Fess| 执行融合时，有效值不会低于 + ``rank.fusion.window_size`` 除以搜索器数量（默认为 200 ÷ 2 = 100），因此更小的值不起作用。 + 由搜索引擎执行融合时按原值使用 + * - ``content_chunker.search.knn.param.ef_search`` + - （未设置） + - ANN 查询的 ``ef_search`` 参数 + +.. note:: + + 当 ``content_chunker.length.boundary.enabled=true``\ （默认值）时， + ``content_chunker.length.chunk_size`` 会从硬性上限变为一个目标值： + 每次切分都会移动到搜索窗口内所存在的最高层级中距离最近的候选项。换行或句末无论回退多远， + 都优先于分句分隔符或空格，而这些又优先于书写体系变化。移动的只是切分点本身， + 不会丢失任何字符，因此将一篇文档的所有分块拼接起来仍会与原文完全一致。 + 在切分点之后进行的搜索，最多可能使 ``chunk_size`` 按 + ``content_chunker.length.boundary.lookahead_percent`` 所允许的幅度超出。 + 此外还可能出现第二种、与之独立的超出：当切分点原本会落在一个字素簇（组合符号、变体选择符， + 或由零宽连接符连接的表情符号序列）内部时，最多会额外超出 32 个字符——这种超出不受 + ``lookahead_percent`` 控制，即使该值为 ``0`` 也会发生。 + 这两种超出不会同时出现在同一个切分点上，因此在出厂默认设置下，一个分块的长度介于 + 640～840 个字符之间。由于分块平均变短，一篇文档产生的分块数比固定长度切分约多 3%～25%\ （参见 + ``content_chunker.max_chunks_per_document``\ ）。将 + ``content_chunker.length.boundary.enabled`` 设为 ``false``\ ，或将两个百分比都设为 ``0``\ ， + 可完全复现此前的固定长度行为。修改这些设置只影响之后切分的文档：已经以分块数组形式 + 保存的文档会保留原有边界，直到被重新爬取。 + +.. note:: + + ``content_chunker.length.chunk_size`` 以字符数指定，但嵌入模型一次只能接收不超过其 token 上限的 + 文本。|Fess| 不会截断送去嵌入的文本，因此超出上限的部分可能不会反映到向量中。请根据所用模型的 + 输入上限来选择 ``chunk_size``\ 。例如，使用 ``paraphrase-multilingual-MiniLM-L12-v2``\ （最多 + 128 个 token）实测，反映到向量中的范围在英文中约为 440 个字符，在日文中约为 210 个字符（因文本 + 而异）。对于该模型，默认值 ``chunk_size=800`` 的分块的后面部分不会反映到向量中。 + +.. note:: + + HNSW 的 ``m`` 和 ``ef_construction`` 参数被硬编码在 ``doc.json`` 中（``m=16`` / + ``ef_construction=100``），无法通过配置更改。 + +opensearch 提供商的连接配置 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +内置 ``opensearch`` 提供商（OpenSearch ML Commons）的连接配置。这些配置项设置在与上面相同的 +``system.properties`` 文件中。 + +.. list-table:: + :header-rows: 1 + :widths: 50 20 30 + + * - 属性 + - 默认值 + - 说明 + * - ``content_chunker.embedding.opensearch.model.id`` + - （必填） + - 已部署到 ML Commons 的模型 ID + * - ``content_chunker.embedding.opensearch.api.url`` + - 搜索引擎的地址 + - ML Commons API 端点。未设置时，默认为 |Fess| 已在使用的搜索引擎（例如 + ``http://localhost:9200``） + * - ``content_chunker.embedding.opensearch.username`` / ``password`` + - 搜索引擎的凭据 + - 未设置时，回退使用搜索引擎连接所用的凭据——但仅在 ``api.url`` 未配置期间（即目标与 + |Fess| 已在使用的集群相同）才会如此。一旦设置了 ``api.url``，则不再回退 + * - ``content_chunker.embedding.opensearch.timeout`` + - ``60000`` + - 请求超时（毫秒） + * - ``content_chunker.embedding.opensearch.connect.timeout`` + - ``5000`` + - 连接超时（毫秒） + * - ``content_chunker.embedding.opensearch.retry.max`` + - ``3`` + - 针对瞬时错误（429、5xx 等）的最大尝试次数（包含第一次）。它不是重试次数：\ ``3`` 表示总共最多 + 发出三次请求，中间等待两次。小于等于 ``1`` 表示不重试 + * - ``content_chunker.embedding.opensearch.retry.base.delay.ms`` + - ``2000`` + - 重试的基础退避延迟（毫秒） + * - ``content_chunker.embedding.opensearch.availability.check.interval`` + - ``60`` + - 提供商可用性检查的间隔（秒） + * - ``content_chunker.embedding.opensearch.document.prefix`` / ``query.prefix`` + - （空） + - 在进行嵌入之前添加到文档/查询文本前面的前缀 + +.. warning:: + + ``system.properties`` 的内容可以在管理界面的「系统信息」→「配置信息」页面的「应用程序属性」 + 面板中查看。其中 ``content_chunker.embedding.opensearch.password`` 会在该页面上被掩码为 + ``XXXXXXXX``\ ，但 ``username`` 会原样显示。此外，通过 ``-Dfess.system.<键名>`` 指定的值会 + 在同一页面的「系统属性」面板中\ **不加掩码地**\ 显示，因此凭据请写入 ``system.properties``\ ， + 而不要放在启动选项中。 + +其他提供商（ollama / openai / gemini / bedrock） +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``ollama`` 提供商（``fess-llm-ollama`` 插件）在 ``content_chunker.embedding.ollama.`` 前缀下 +使用同样风格的配置（``api.url`` 默认值为 ``http://localhost:11434``\ ，``model`` 默认值为 +``embeddinggemma``\ ，``document.prefix`` / ``query.prefix`` 默认值分别为 +``title: none | text:`` / ``task: search result | query:``）。如果要使用 ``nomic-embed-text`` +系列的模型，请将 ``document.prefix`` / ``query.prefix`` 显式设置为 ``search_document:`` / +``search_query:``\ 。这些前缀会原样拼接到待嵌入的文本前（前后空白不会被去除），因此上述默认值 +以及 ``search_document:`` / ``search_query:`` 都 **在末尾包含一个半角空格**\ 。自行设置前缀时， +请不要遗漏这个分隔用的空格。 + +``openai`` 与 ``gemini`` 提供商的配置方式相同， +分别对应 ``content_chunker.embedding.openai.`` 和 ``content_chunker.embedding.gemini.`` 前缀。 +完整的配置项列表请参阅各插件自身的文档。 ``bedrock`` 提供商使用 ``content_chunker.embedding.bedrock.`` +前缀，并且 ``content_chunker.embedding.dimension`` 必须是所配置模型能够生成的大小， +请参阅 :doc:`llm-bedrock` 。 + +配置步骤（以 opensearch 提供商为例） +===================================== + +本节以内置的 ``opensearch`` 提供商（ML Commons）为例，介绍一个完整的配置示例。 + +1. 部署嵌入模型 +---------------- + +向 OpenSearch ML Commons 注册并部署一个嵌入模型。在单节点集群上，必须先应用以下设置。 + +.. code-block:: bash + + curl -XPUT "http://localhost:9200/_cluster/settings" \ + -H "Content-Type: application/json" -d ' + {"persistent": {"plugins.ml_commons.only_run_on_ml_node": false}}' + +注册并部署模型（示例：384 维的句子嵌入模型）： + +.. code-block:: bash + + # 注册模型（从响应的 task_id 中获取 model_id） + curl -XPOST "http://localhost:9200/_plugins/_ml/models/_register" \ + -H "Content-Type: application/json" -d ' + { + "name": "huggingface/sentence-transformers/all-MiniLM-L6-v2", + "version": "1.0.2", + "model_format": "TORCH_SCRIPT" + }' + + # 确认任务完成并获取 model_id（state 变为 COMPLETED 后会返回 model_id） + curl "http://localhost:9200/_plugins/_ml/tasks/" + + # 部署 + curl -XPOST "http://localhost:9200/_plugins/_ml/models//_deploy" + + # 检查状态：model_state 应为 DEPLOYED + curl "http://localhost:9200/_plugins/_ml/models/" + +.. note:: + + 仍处于 ``REGISTERED`` 状态的模型无法使用。请务必先部署它，并确认 ``model_state`` 已变为 + ``DEPLOYED``\ 。 + +2. 配置 |Fess| +---------------- + +``app/WEB-INF/conf/system.properties``\ （RPM/DEB 软件包为 ``/etc/fess/system.properties``\ ， +Docker 为 ``/opt/fess/system.properties``\ 。以下各项均写入同一个文件）:: + + content_chunker.enabled=true + content_chunker.embedding.name=opensearch + content_chunker.embedding.dimension=384 + content_chunker.embedding.opensearch.model.id= + +如果您还想使用语义搜索，请再添加以下内容:: + + content_chunker.search.enabled=true + +完成这些更改后重启 |Fess|\ 。 + +3. 重新创建索引（在现有部署上启用时） +--------------------------------------- + +``content_chunk_vector`` 字段的映射——包括您配置的维度和 ANN 方法设置——会在 ``fess.search`` +索引\ **被新建的那一刻**\ 应用。 + +- **全新安装**：如果您在首次启动 |Fess| 之前就已将上述设置应用到 ``system.properties``\ ，则 + 正确的映射会在索引首次创建时自动应用，因此不需要执行此步骤。 +- **索引已存在的情况**\ （即您此前至少启动过一次 |Fess|）：正在运行的索引不会自动获取新的映射， + 已有的映射事后也无法修改。请按以下方式重新创建索引： + + 打开「系统信息」→「维护」，在「重新索引」中启用「更新别名」后执行。 + + 之后您可以确认，重新创建的索引的索引设置中包含 ``index.knn: true``\ ，并且包含带有您所配置的 + 维度与 ANN 方法设置的 ``content_chunk_vector`` 映射（``index.knn`` 属于索引设置，而 ANN 方法 + 设置属于映射，两者的应用位置不同）。 + +.. warning:: + + 「重新索引」以后台异步方式运行，管理界面不会显示完成通知。``_cat/indices`` 只能说明新索引 + 已经存在（状态、文档数等），并不能说明别名指向的是哪个索引。在进行下面的索引器任务步骤 + 之前，请改用 ``_cat/aliases`` 确认 ``fess.search`` 和 ``fess.update`` 是否都已指向新索引； + |Fess| 的日志只会在失败时记录警告，因此日志安静并不代表成功，只说明没有出现已知的失败。 + 旧索引（此前 ``fess.search`` 别名所指向的实体索引，名称形如 ``fess.``）不会被 + 自动删除，请在不再需要时手动删除。在新旧两个索引同时存在期间，索引磁盘占用大约会是平时的 + 两倍。 + +4. 启用索引器任务 +------------------- + +分块与嵌入生成由调度器任务 **Content Chunk Vector Indexer**\ （ID： +``content-chunk-vector-indexer``；默认禁用；调度 ``0 13 * * *``）执行。 + +请在「系统」→「调度器」中启用此任务，然后通过「立即开始」运行一次。此后，系统会与爬取是否完成 +无关地，按照所配置的调度（默认为每天 13:00）处理尚未处理的文档。该任务并未与爬取任务串联， +因此如果希望在爬取结束后立即处理，请将其调度时间设置在爬取任务的预计完成时刻之后。 + +.. note:: + + 在多节点部署中，建议将此任务固定到某一个节点上运行。在每个节点上同时运行并不会破坏正确性， + 但每个节点都会冗余地处理并嵌入相同的文档，从而使嵌入提供商承受的负载与成本随节点数量成倍 + 增加。 + + 固定该任务需要\ **同时**\ 满足以下两项设置——仅设置其中一项无法完成固定。 + + 1. **在您希望运行该任务的节点上**：在 ``app/WEB-INF/classes/fess_config.properties``\ （RPM/DEB + 软件包为 ``/etc/fess/fess_config.properties``）中设置 + ``scheduler.target.name=<某个标识符>``\ （或通过 + ``-Dfess.config.scheduler.target.name=<某个标识符>`` 指定），然后重启该节点。（默认值为 + 空；其他所有节点保持默认值不变。） + 2. 在管理界面的「系统」→「调度器」中打开 Content Chunk Vector Indexer 任务，将其「目标」字段 + 从 ``all`` 更改为与步骤 1 中设置的相同标识符，然后保存。 + + 关于「目标」字段的含义，请参阅 :doc:`../admin/scheduler-guide`\ 。如果仅设置了 + ``scheduler.target.name``\ ，而「目标」字段仍保留为 ``all``\ ，任务将\ **不会**\ 被固定：``all`` + 被视为始终匹配的特殊值，因此仅执行步骤 1 或仅执行步骤 2 都是不够的——必须同时完成两者。 + +.. warning:: + + 固定之后，「立即开始」也必须\ **从步骤 1 中设置了标识符的那个节点的管理界面**\ 执行。如果在 + 非目标节点上点击「立即开始」，界面上虽然会显示「作业 … 已启动。」，但由于「目标」不匹配， + 任务实际上不会运行（只会在该节点的日志中输出一条 INFO 级别的 ``Ignoring job``）。 + +5. 检查处理状态 +----------------- + +您可以在每个文档的 ``content_chunk_status`` 字段中查看其处理结果。 + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - 值 + - 含义 + * - （字段不存在） + - 尚未处理（将在下次任务运行时被处理）。重新爬取后的文档也会回到此状态 + * - ``done`` + - 分块与向量生成均已完成 + * - ``chunked`` + - 仅完成分块（仅分块模式）。除了 ``embedding.name=none`` 的情况之外，当 ``embedding.name`` + 所指定的提供商对应的插件未安装时，也会进入此状态 + * - ``skipped`` + - 处理被跳过。包括正文为空（含仅有空白字符）的文档、没有生成任何分块的文档，以及超过 + ``max_chunks_per_document`` 的文档。如果 ``content_chunker.chunker.name`` 指定了不存在的 + 分块器，则找不到分块器、不会生成分块，所有文档都会进入此状态。这是终止状态：重新运行任务 + 不会再次处理该文档 + * - ``fail`` + - 处理失败（请检查日志）。这是终止状态：默认情况下，重新运行任务不会再次处理该文档。 + 将 ``content_chunker.job.retry_failed`` 设为 ``true`` 才会再次处理 + +您可以直接查询搜索引擎来查看状态分布:: + + curl -XPOST "http://localhost:9200/fess.search/_search" \ + -H "Content-Type: application/json" -d ' + {"size": 0, "aggs": {"status": {"terms": {"field": "content_chunk_status", "missing": "pending"}}}}' + +借助 ``missing`` 选项，不带 ``content_chunk_status``\ （即尚未处理）的文档会被聚合到键名为 +``pending`` 的分桶中。 + +请根据 ``content_chunk_status`` 的这一数量分布来判断分块任务的状况。如果每次运行任务时 +``pending`` 都在减少、``done``\ （仅分块模式下为 ``chunked``\ ）都在增加，说明进展顺利。 +如果出现 ``fail``\ ，请在 |Fess| 日志中确认原因。对于正文为空的文档等，出现 ``skipped`` 是正常的， +但如果几乎所有文档都是 ``skipped``\ ，请怀疑 ``content_chunker.chunker.name`` 有误（找不到分块器时 +会输出 ``Chunker not found`` 的 WARN 日志）。 + +.. warning:: + + 仅仅修正配置并不会让 ``skipped`` 和 ``fail`` 恢复原状。重新运行任务时不会选中 ``skipped`` + 文档（被重新爬取的文档会回到未处理状态），而 ``fail`` 文档只有在 + ``content_chunker.job.retry_failed`` 为 ``true`` 时才会再次成为处理对象。例如，如果 + ``content_chunker.chunker.name`` 有误的情况下运行了任务，导致所有文档都变成 ``skipped``\ ， + 请在修正名称后，先按如下方式删除 ``content_chunk_status``\ ，再重新运行任务（``skipped`` + 文档的 ``content`` 没有被改写，因此可以直接重新处理）:: + + curl -XPOST "http://localhost:9200/fess.search/_update_by_query" \ + -H "Content-Type: application/json" -d ' + { + "query": {"term": {"content_chunk_status": "skipped"}}, + "script": {"source": "ctx._source.remove(\"content_chunk_status\")"} + }' + +语义搜索的工作方式 +==================== + +设置 ``content_chunker.search.enabled=true`` 会将语义搜索器注册到 Rank Fusion 中，之后它会将 +关键词搜索结果与向量搜索结果合并。（有关 Rank Fusion 的工作原理，请参阅 :doc:`rank-fusion`\ 。） +默认情况下由 |Fess| 自身执行融合；设置 ``rank.fusion.engine.enabled=true`` 后，改由 OpenSearch +执行融合（请参阅 :ref:`rank-fusion-engine`\ ）。 +另外，搜索时还会参照 ``content_chunker.enabled``\ 。当 ``content_chunker.enabled=false`` 或 +``content_chunker.embedding.name=none`` 时，即使搜索器已经注册，也不会执行语义搜索（该判断按每次 +请求进行，因此无需重启）。 + +.. warning:: + + 由于语义搜索器是在启动时注册的，**启用此项需要重启**。禁用它（将值改回 ``false``）是按请求 + 逐次判断的，因此会立即生效。 + +exact 模式与 ann 模式 +------------------------ + +搜索方式会根据索引的状态自动选择。 + +.. list-table:: + :header-rows: 1 + :widths: 12 44 44 + + * - 模式 + - 条件 + - 特点 + * - ``ann`` + - 具有 ``index.knn`` 和 ANN 方法设置的索引 + - 使用 HNSW 进行近似最近邻搜索。适合大规模索引 + * - ``exact`` + - 除上述之外的情况（缺少 ``index.knn`` 或 ANN 方法设置中任意一项的索引，包括索引状态判定 + 失败的情况） + - 对所有向量进行精确的余弦相似度计算。适合中小规模索引 + +在 |Fess| 15.10 下新创建的任何 ``fess.search`` 索引，无论 ``content_chunker.search.enabled`` 的 +值如何，始终具有 ``index.knn`` 和 ANN 方法设置——因此通常总是使用 ``ann`` 模式。``exact`` 模式 +是为该机制引入之前创建的旧索引提供的后备方案。由于无法在事后为现有索引添加 k-NN 设置，将 +``exact`` 模式的索引切换为 ``ann`` 模式需要重新创建索引（参阅 :ref:`semantic-search-migration`）。 +另外，该判定结果会被缓存 60 秒，因此在重新创建索引之后，最多需要 60 秒才会反映出来。 + +分数阈值 +---------- + +将 ``content_chunker.search.min_score`` 设置为某个余弦相似度（0-1）后，即使是相似度最高的分块 +也达不到该值的文档，会被从语义搜索结果中排除（由于文档的分数取自其最佳分块的分数，因此该阈值 +是以文档为单位生效的）。当没有词汇重叠的查询匹配范围过广时，可用它来控制命中数量:: + + content_chunker.search.min_score=0.4 + +无论在 ``exact`` 还是 ``ann`` 模式下，该设置值都会被解释为余弦相似度（内部会转换为各模式对应的 +分数标度）。 + +.. note:: + + 仅当 ``content_chunker.search.knn.space_type`` 为 ``cosinesimil``\ （默认值）时，该阈值才会 + 生效。对于指定了 ``innerproduct`` / ``l2`` 的 ``ann`` 模式索引，由于无法定义余弦相似度， + 该阈值会被跳过，并且每次这样的搜索都会输出警告日志。 + +限制事项 +-------- + +- 查询中带字段限定的条件（``label:``、``site:``、``filetype:``、``timestamp`` / ``last_modified`` + 的范围等）会从用于嵌入的文本中分离出来，并作为过滤条件应用于向量搜索。由于查询是在组装 + **之后**\ 才被分析的，因此，即使是在内部附加此类条件的操作——指定标签、通过分面进行筛选， + 以及高级搜索中的文件类型、站点指定、日期时间指定，包括通过 ``ex_q`` 和 ``fields.*`` 参数传入的 + 条件——也仍会执行语义搜索，并按与关键词搜索相同的条件进行筛选。 +- 对于以下查询，\ **将跳过语义搜索**\ ，仅执行关键词搜索。 + + - 指定排序条件（``sort:`` 伪字段，或 ``sort`` 参数，后者在内部同样会以 ``sort:...`` 的形式附加） + - 针对未指定字段的词语的短语（``"..."``）、通配符（``*`` ``?``）、模糊搜索（``~``）或范围， + 包括高级搜索中的短语。半角的 ``?`` 会被视为通配符，因此像“……是什么?”这样以半角问号结尾的 + 自然语句也会被跳过（全角的 ``？`` 不在范围内）。 + - 排除词语（``-word``、``NOT word``\ ，包括高级搜索中的排除词）或提升权重（``word^2``） + - 无法将条件作为过滤条件分离出来的查询，例如用 ``OR`` 连接词语与条件的查询 + - ``allintitle:`` / ``allinurl:`` + - 只有条件、没有可用于嵌入的词语的查询 + - 无法解析的查询 + +- 与地理位置搜索（地理过滤）或相似文档搜索结合使用时，同样会被跳过。 +- 较深页码的处理方式取决于在何处执行融合。 + + - 由 |Fess| 执行融合时（默认），分界由 ``rank.fusion.window_size``\ （默认 ``200``）决定； + 默认情况下，搜索结果的第 101 条及以后仅来自关键词搜索。 + - 由搜索引擎执行融合时（``rank.fusion.engine.enabled=true``），所有页面都会被融合，但翻页 + 止于 ``rank.fusion.pagination_depth``\ （默认 ``1000``）条结果，无法请求其后的页面。 + + 详情请参阅 :doc:`rank-fusion`\ 。 +- 如果嵌入提供商不可访问，或发生搜索错误，|Fess| 会自动回退为仅使用关键词搜索的结果（搜索本身 + 不会因此失败）。 +- 基于角色和虚拟主机的访问控制同样适用于语义搜索结果。 + +与 AI 搜索模式的集成 +====================== + +当启用 AI 搜索模式（:doc:`rag-chat`\ ，``rag.chat.enabled=true``）时，对于 +``content_chunk_status`` 为 ``done`` 的文档，在生成回答时会计算各个分块的相似度，并 +仅将相关性最高的前 ``content_chunker.chat.top_k`` 个分块（默认值：``3``）用作 LLM 的上下文。 + +此时用于计算嵌入的并不是用户的原始提问，而是\ **意图判定阶段由 LLM 生成的检索查询**\ （若发生 +重新检索，则使用重新生成后的查询）。当没有生成检索查询时——例如用户要求对文档进行摘要——则不会 +进行分块选择。 + +因此，即使是长文档，也只有相关部分会被传递给 LLM，这有助于提高回答准确性并减少 token 用量。 +对于 ``content_chunk_status`` 为 ``chunked``\ （已有分块但没有向量）的文档，会改为基于关键词 +（高亮）匹配来选择分块，而不是计算相似度。``skipped`` / ``fail`` 以及尚未处理的文档，仍会像 +以前一样使用完整正文（或高亮摘录）。 + +此行为与 ``content_chunker.search.enabled`` 无关，但需要 ``content_chunker.enabled`` 处于启用 +状态。另外，将所选分块拼接而成的文本同样会被 ``rag.chat.content.fulltext.max.length``\ （默认 +``3000``）截断，因此即使调大 ``content_chunker.chat.top_k`` 或 +``content_chunker.length.chunk_size``\ ，传递给 LLM 的字符数也不会超过该上限。 + +.. _semantic-search-migration: + +从 15.7 及更早版本迁移 +======================== + +如果您正在从 15.7 或更早版本升级 |Fess|，根据您当前对这些功能的使用情况，会属于以下四种情形之 +一。请遵循适用于您的情形的说明。 + +全新安装 +-------- + +无需额外操作。如果您想使用向量搜索，只需在首次启动 |Fess| 之前，按照本页的\ *配置参考*\ 章节配置 +``system.properties``，正确的映射就会在索引首次创建时自动应用。（具体步骤请参阅上文的\ *配置步骤*\ 。） + +.. note:: + + 如果您此前至少启动过一次 |Fess|\ （即索引已经存在），请改为遵循下面的\ *现有用户*\ 相关情形之 + 一，而不是本情形。 + +现有用户且不想使用向量搜索 +-------------------------- + +无需任何操作。``content_chunker.enabled`` 与 ``content_chunker.search.enabled`` 默认均为 +``false``，因此升级后您的搜索结果和现有索引行为不会改变。新增的调度器任务 **Content Chunk +Vector Indexer** 会在启动时自动注册，但由于默认处于禁用状态，它不会运行，语义搜索器也不会被 +注册到 Rank Fusion 中（该任务在每次启动时都会被注册，因此即使在管理界面中将其删除，下次启动时 +也会以禁用状态重新创建）。 + +.. note:: + + 即使您不使用向量搜索，只要在 |Fess| 15.10 及以后\ **新建**\ 索引（包括重新索引），就会应用 + 包含 ``content_chunk_vector``\ （``knn_vector`` 类型）的映射以及 ``index.knn: true``\ 。在 + OpenSearch 未安装 k-NN 插件的环境中，索引会在这一时刻创建失败。详情请参阅本页的“前提条件”。 + +现有用户且想启用向量搜索 +------------------------ + +正在运行的索引不会自动获取新的映射，因此需要执行以下步骤。 + +1. 按照本页\ *配置参考*\ 中的说明，将设置应用到 ``system.properties``\ （若使用 opensearch + 提供商，具体步骤请参阅上文的\ *配置步骤*\ ）。 +2. 重启 |Fess|\ 。 +3. 在管理界面中，于「系统信息」→「维护」下运行「重新索引」，并启用「更新别名」。该操作会以 + 后台异步方式进行，不会显示完成通知。``_cat/indices`` 只能说明新索引已存在，不能说明别名是否 + 已切换——请改用 ``_cat/aliases`` 确认 ``fess.search``/``fess.update`` 是否已指向新索引 + （|Fess| 的日志只在失败时发出警告，安静不代表成功）。旧索引不会被自动删除（请在不再需要时 + 手动删除），在此之前索引磁盘占用会大约翻倍。 +4. 仅在确认上述别名切换已完成后，才在「系统」→「调度器」中启用并运行 Content Chunk Vector + Indexer 任务（无需重新爬取：该任务会从现有索引的 ``_source`` 中读取 ``content`` 字段 + 进行分块和嵌入）。 + +.. note:: + + 如果在步骤 1 中就一并写入 ``content_chunker.search.enabled=true``\ ，那么从步骤 2 的重启到 + 步骤 4 完成之前，每次搜索都只会执行查询侧的嵌入，而结果中并不会体现出来。使用 ``openai`` / + ``gemini`` / ``bedrock`` 等按量计费的提供商时，请在步骤 4 完成之后再写入 + ``content_chunker.search.enabled=true`` 并重启。 + +若您之前使用 fess-webapp-semantic-search 插件 +------------------------------------------------ + +在 |Fess| 15.7 及更早版本中提供语义搜索功能的 ``fess-webapp-semantic-search`` 插件，已在 +15.10 中并入核心，现已\ **不再需要（已弃用）**\ 。除了上文\ *现有用户且想启用向量搜索*\ 中的步骤外， +您还需要执行以下操作。 + +1. **移除插件**：从 ``app/WEB-INF/plugin/`` 中删除 ``fess-webapp-semantic-search-*.jar`` + （在 Docker 中，请将其从 ``FESS_PLUGINS`` 中排除）。 + +2. **移除旧设置**：删除所有 ``-Dfess.semantic_search.*`` 启动选项。此外，如果您曾为旧插件指定 + ``-Drank.fusion.searchers=default,semantic``\ ，也请将其删除。若保留该设置，会导致新的语义 + 搜索器（``semantic_chunk``）被排除在 Rank Fusion 之外，并在启动时记录警告日志。 + +3. **解除旧的 ingest pipeline**：如果之前设置过 ``-Dfess.semantic_search.pipeline``\ ，旧插件会在 + 创建索引时把 ``default_pipeline``\ （用于神经搜索的 ingest pipeline）写入索引设置。 + **移除插件并不会移除该 pipeline**——它会继续留在索引上并持续运行——因此请务必在执行\ *现有用户且 + 想启用向量搜索*\ 中的重新索引\ **之前**\ 将其解除。重新索引之后生成的新索引本来就不带该设置， + 所以之后再执行也没有意义。请先用 ``_cat/aliases`` 确认 ``fess.search`` 指向的 + ``fess.``\ ，并指定实体索引名而不是别名:: + + curl -XPUT "http://localhost:9200/fess./_settings" \ + -H "Content-Type: application/json" -d ' + {"index": {"default_pipeline": "_none"}}' + + 即使解除了索引设置，ingest pipeline 本身仍会留在搜索引擎中。如果今后不再使用，请将其删除:: + + curl -XDELETE "http://localhost:9200/_ingest/pipeline/" + +4. **添加新设置**：按照本页\ *配置参考*\ 中的说明，在 ``system.properties`` 中配置 + ``content_chunker.*``\ 。如果您要继续使用现有的 ML Commons 模型，请设置 + ``content_chunker.embedding.name=opensearch``\ ，并将其现有的 ``model_id`` 填入 + ``content_chunker.embedding.opensearch.model.id``\ 。 + +5. **重新创建索引并运行任务**：旧插件存储的向量字段（默认配置下为 ``content_vector``）与新的核心 + 功能所使用的 ``content_chunk_vector`` 字段是不同的字段，因此旧的向量无法被新功能使用。另一 + 方面，重新索引会原样复制 ``_source``\ ，所以旧向量仍会被复制到新索引中，并通过动态映射持续 + 占用磁盘空间。建议在重新索引\ **之前**\ 先将其清除（如果您更改过字段名，请相应替换）:: + + curl -XPOST "http://localhost:9200/fess.search/_update_by_query" \ + -H "Content-Type: application/json" -d ' + { + "query": {"exists": {"field": "content_vector"}}, + "script": {"source": "ctx._source.remove(\"content_vector\")"} + }' + + 之后，请在「系统信息」→「维护」下运行「重新索引」，然后启用并运行 Content Chunk Vector + Indexer 任务，重新生成向量。 + +注意事项 +======== + +更改嵌入模型（维度） +---------------------- + +若要切换到维度不同的嵌入模型，请按以下顺序操作。 + +1. 删除现有的旧向量。如果残留着维度不同的旧向量就执行重新索引，新映射将无法接受这些向量，相应 + 的文档不会被复制到新索引中，而处理仍会继续进行。由于 |Fess| 只检查重新索引的 HTTP 状态码， + 管理界面不会显示任何错误，文档却已经缺失:: + + curl -XPOST "http://localhost:9200/fess.search/_update_by_query" \ + -H "Content-Type: application/json" -d ' + { + "query": {"exists": {"field": "content_chunk_status"}}, + "script": {"source": "ctx._source.remove(\"content_chunk_vector\"); ctx._source.remove(\"content_chunk_status\")"} + }' + + .. note:: + + 操作对象也可以指定为 ``fess.update``\ （重新索引时的读取来源别名）。另外，此操作不会改变 + ``content`` 字段，它仍保持分块数组的形态。下次任务运行时会重新拼接并再次切分，因此如果您为 + ``content_chunker.length.overlap`` 设置了非 0 的值，重叠部分会被重复计入后再切分。若对此 + 有顾虑，请重新爬取相应的文档。 + +2. 更改 ``content_chunker.embedding.dimension`` 以及所用提供商的模型设置。 +3. 按照“配置步骤”中的“3. 重新创建索引（在现有部署上启用时）”重新创建索引，并重新运行索引器 + 任务。 + +更换为维度相同的其他模型 +-------------------------- + +将 ``content_chunker.embedding.opensearch.model.id`` 等嵌入模型设置更改为维度相同的其他模型时， +|Fess| 不会报错也不会发出警告，直接接受。因为只检查维度，创建向量所用的模型并不会记录在索引中。 +此时已存储的向量由旧模型创建，而搜索时的查询向量由新模型创建，两者处于不同的向量空间， +搜索结果的相关性会崩溃。此外，余弦相似度的数值分布因模型而异，按旧模型调整过的 +``content_chunker.search.min_score`` 对新模型可能过于严格，导致大部分结果被截掉。 + +更换模型时，请先设置新模型，再用与上面“更改嵌入模型（维度）”步骤 1 相同的 ``_update_by_query`` +删除 ``content_chunk_vector`` 和 ``content_chunk_status``\ ，然后重新运行索引器任务，为所有文档 +重新生成向量（维度相同，因此无需重新创建索引）。如果设置了 ``content_chunker.search.min_score``\ ， +请用新模型重新评估。 + +在未设置维度的情况下创建了索引 +-------------------------------- + +如果在 ``content_chunker.embedding.dimension`` 未设置的情况下创建 ``fess.search`` 索引， +``content_chunk_vector`` 的映射会不带任何警告地采用 ``768`` 维，并且之后无法更改。 +此时运行索引器任务，执行嵌入处理时无法读取维度而出错，文档会变为 ``fail``\ 。 + +- 如果所用模型的维度是 ``768``\ ，请设置 ``content_chunker.embedding.dimension=768``\ 。 + 它与映射一致，因此无需重新创建索引。 +- 否则，请设置正确的维度。在映射（``768``\ ）与设置值不一致期间，索引器任务会输出 ERROR 日志并 + 跳过本次运行。请按上面“更改嵌入模型（维度）”步骤 3 的相同方法重新创建索引。 + +无论哪种情况，已经变为 ``fail`` 的文档都不会被自动重新处理。如果重新创建索引，上面“更改嵌入模型 +（维度）”步骤 1 的 ``_update_by_query`` 也会删除 ``content_chunk_status``\ 。如果不重新创建， +请临时将 ``content_chunker.job.retry_failed`` 设为 ``true`` 后重新运行任务。 + +磁盘使用量 +---------- + +除搜索索引结构外，分块向量还会保留在 ``_source`` 中，因此每个文档会额外消耗与「分块数 × +向量维度」成正比的磁盘空间。如果磁盘空间成为问题，请调整 ``content_chunker.length.chunk_size`` +或 ``content_chunker.max_chunks_per_document``\ 。 + +chunk-only 模式 +----------------- + +设置 ``content_chunker.embedding.name=none`` 后，将只执行分块而不生成嵌入向量 +（``content_chunk_status`` 会变为 ``chunked``）。这样一来，您可以在嵌入提供商就绪之前提前进行 +分块；之后配置好提供商并重新运行任务时，系统只会为已存储的分块生成向量（不会重新分块）。 + +大规模语料库的内存配置 +------------------------ + +索引器任务的子 JVM 通过 ``fess_config.properties`` 中的 ``jvm.chunk.options``\ （默认包含 +``-Xms128m -Xmx1g`` 的 JVM 选项）启动。由于 ``content_chunker.job.max_documents_per_run`` +默认无限制，单次运行会将所有待处理的文档 ID 保留在内存中。文档 ID 是 SHA-512 摘要（128 个字符）， +每条约占用 200 字节堆内存；分块处理本身还需要 200-250MB 左右。因此，对于\ **超过 100 万至 200 万 +文档**\ 的语料库，请提高 ``jvm.chunk.options`` 中的 ``-Xmx`` 值，或者为 +``content_chunker.job.max_documents_per_run`` 设置一个有限值以分批执行。``jvm.chunk.options`` +在 ``app/WEB-INF/classes/fess_config.properties``\ （RPM/DEB 软件包为 +``/etc/fess/fess_config.properties``）中覆盖（有关 JVM 选项的概念，请参阅 +:doc:`setup-memory`）。 + +同样的无限制默认值，在使用按量计费的嵌入提供商（ ``openai`` 、 ``gemini`` 、 ``bedrock`` ）时还会带来成本上的 +影响：首次索引器运行会一次性为现有语料库全部生成嵌入，相应的费用也会一次性产生。如果希望 +将费用分摊到多次运行中，请为 ``content_chunker.job.max_documents_per_run`` 设置一个有限值。 + +参考信息 +======== + +- :doc:`rank-fusion` - Rank Fusion（混合搜索）配置 +- :doc:`rag-chat` - AI 搜索模式配置 +- :doc:`llm-overview` - LLM 集成概述 +- :doc:`llm-ollama` - Ollama 配置 +- :doc:`setup-memory` - JVM 内存设置 +- :doc:`../install/upgrade` - 升级步骤 diff --git a/zh-cn/15.10/config/security-role.rst b/zh-cn/15.10/config/security-role.rst new file mode 100644 index 000000000..5b22290fc --- /dev/null +++ b/zh-cn/15.10/config/security-role.rst @@ -0,0 +1,72 @@ +================= +基于角色的搜索配置 +================= + +关于基于角色的搜索 +================== + +|Fess| 可以根据任意认证系统认证的用户认证信息来区分搜索结果。 +例如，拥有角色a的用户A可以在搜索结果中看到角色a的信息，但不拥有角色a的用户B即使搜索也不会看到该信息。 +通过使用此功能，可以在门户网站或单点登录环境中，根据登录用户所属部门或职位实现搜索。 + +|Fess| 的基于角色的搜索可以从以下途径获取角色信息。 + +- 请求参数 + +- 请求头 + +- Cookie + +- |Fess| 的认证信息 + +在门户网站或代理型单点登录系统中，可以在认证时通过 Cookie 将认证信息保存到 |Fess| 运行的域和路径中来获取角色信息。 +此外，在反向代理型单点登录系统中，可以在访问 |Fess| 时将认证信息添加到请求参数或请求头中来获取角色信息。 + +.. note:: + 从请求参数、请求头、Cookie 获取角色信息的功能在初始状态下是禁用的。 + 如需使用这些功能，必须在 ``app/WEB-INF/classes/fess.xml`` 的 ``roleQueryHelper`` 组件中配置所引用的键名（ ``parameterKey`` 、 ``headerKey`` 、 ``cookieKey`` ）、值的加密方式（ ``encryptedParameterValue`` 等）以及分隔符（ ``valueSeparator`` 、 ``roleSeparator`` ）。 + 初始状态下仅启用基于 |Fess| 认证信息的角色搜索。 + +基于角色的搜索配置 +================= + +本文介绍使用 |Fess| 认证信息的基于角色的搜索配置方法。 + +|Fess| 管理页面配置 +--------------------- + +启动 |Fess| 并以管理员身份登录。 +创建角色和用户。 +例如，在角色管理页面创建 Role1，在用户管理页面创建属于 Role1 的用户。 +如需按组分配，可在组管理页面创建组并分配给用户。 + +接下来，在爬取配置的权限栏中输入 ``{role}Role1`` 并保存。 +按用户指定时可以用 ``{user}username`` ，按组指定时可以用 ``{group}groupname`` 来描述。 +指定多个权限时，请用换行符分隔。 + +之后使用此爬取配置进行爬取，即可创建仅属于指定角色、用户、组的用户可搜索的索引。 +登录用户会自动获得表示自身的 ``{user}username`` 、所属角色的 ``{role}`` 以及所属组的 ``{group}`` 权限，并与文档设置的权限进行匹配。 + +.. note:: + 如需明确拒绝特定角色、用户、组的访问，可在权限中加上 ``(deny)`` 前缀，例如 ``(deny){role}Role1`` （加上 ``(allow)`` 表示允许，与未指定时的处理方式相同）。 + +.. note:: + 与 LDAP 或单点登录集成时，用户的角色和组信息将从认证源获取，并以同样方式作为权限处理。 + LDAP 集成时的行为可通过 ``fess_config.properties`` 中的 ``ldap.role.search.user.enabled`` 、 ``ldap.role.search.group.enabled`` 、 ``ldap.role.search.role.enabled`` （初始值均为 ``true`` ）来控制。 + +登录 +------ + +从管理页面退出登录。 +以属于 Role1 的用户登录。 +登录成功后会重定向到搜索页面首页。 + +正常搜索时，仅显示在爬取配置中设置了 Role1 角色的内容。 + +此外，未登录状态下的搜索将作为 guest 用户的搜索。 +对于希望向未登录用户显示的文档，请在爬取配置的权限栏中设置 ``{role}guest`` （初始值由 ``role.search.guest.permissions`` 定义）。 + +登出 +-------- + +在以非管理员用户登录状态下，在搜索页面选择登出即可退出登录。 diff --git a/zh-cn/15.10/config/security-virtual-host.rst b/zh-cn/15.10/config/security-virtual-host.rst new file mode 100644 index 000000000..4d3ce2c0a --- /dev/null +++ b/zh-cn/15.10/config/security-virtual-host.rst @@ -0,0 +1,91 @@ +======== +虚拟主机 +======== + +关于虚拟主机 +============== + +可以根据访问 |Fess| 时的主机名（HTTP ``Host`` 请求头的值）来区分搜索结果。 +可以用多个主机名发布同一台 |Fess| 服务器，为每个主机名提供不同的搜索对象（爬取配置）和页面设计。 +搜索界面的外观也可以按主机区分：名称与虚拟主机名一致的静态主题将用于该主机。 + +虚拟主机功能默认处于禁用状态（未配置）。请按以下步骤进行配置。 + +系统配置 +---------- + +在 :doc:`管理员指南 > 常规配置 <../admin/general-guide>` 的"虚拟主机"中，配置访问来源主机名与虚拟主机名的对应关系。在爬取配置中指定这里配置的虚拟主机名。 + +**格式** + +每行一条，按以下格式描述一个虚拟主机。 + +:: + + 请求头名称:请求头值=虚拟主机名 + +.. list-table:: + + * - *请求头名称* + - 用于判断的 HTTP 请求头名称。通常指定 ``Host``\ 。通过反向代理访问时，也可以指定 ``X-Forwarded-Host``\ 。 + * - *请求头值* + - 上述请求头中包含的主机名（必要时使用 ``主机名:端口号`` 格式）。当客户端发送的请求头值与此处配置的值完全匹配（不区分大小写）时，该虚拟主机生效。 + * - *虚拟主机名* + - 在爬取配置中指定的虚拟主机名 + +**示例** + +:: + + Host:abc.example.com=host1 + Host:192.168.1.123:8080=host2 + +.. note:: + + 判断依据是与请求头值的字符串匹配，而非主机名的名称解析（DNS）。 + 浏览器发送的 ``Host`` 请求头，在使用标准端口（HTTP 为 80，HTTPS 为 443）访问时不包含端口号，使用其他端口访问时则以 ``主机名:端口号`` 格式包含端口号。 + 因此，在非标准端口上发布时，请像 ``Host:abc.example.com:8080=host1`` 这样明确指定包含端口号。 + +.. note:: + + 虚拟主机名只能使用字母数字字符和下划线（ ``a-z`` 、 ``A-Z`` 、 ``0-9`` 、 ``_`` ）。 + 其他字符会被自动删除。 + + 此外，以下名称为保留名称，不能用作虚拟主机名： + ``admin`` 、 ``common`` 、 ``error`` 、 ``login`` 、 ``profile`` + +各虚拟主机的页面设计 +-------------------- + +要为某个虚拟主机提供专用的搜索界面，请安装 ``theme.yml`` 中的 ``name`` 为该虚拟主机名小写形式（例如 ``host1`` ）的静态主题。 +与该虚拟主机匹配的请求将使用该主题，其他请求则使用默认主题。 +无需将该主题设为默认主题。从内置主题创建主题的方法请参见 :ref:`theme-customize-bundled` ，安装方法请参见 :doc:`../admin/theme-guide` 。 + +.. note:: + + 自 |Fess| 15.10 起，保存配置后不会再在 ``WEB-INF/view/虚拟主机名`` 中生成 JSP。 + 登录界面（ ``/login/`` ）在所有虚拟主机中都使用同一个界面（ ``WEB-INF/view/admin/login/`` ）显示，无法按虚拟主机更改。 + 按虚拟主机区分的外观，如上所述，通过与虚拟主机名同名的静态主题来更改。 + + +爬取配置 +--------- + +在 Web 爬取配置、文件爬取配置或数据存储爬取配置中指定"虚拟主机"。 +"虚拟主机"请指定系统配置中设置的虚拟主机名之一。一个爬取配置中也可以指定多个虚拟主机（每行一个）。 + +通过虚拟主机访问的搜索，只会在搜索结果中显示指定了该虚拟主机的爬取配置中的文档。 +不匹配任何虚拟主机的访问（未配置虚拟主机的普通访问）则不会进行此类筛选，将正常显示所有搜索结果。 + +**示例** + +.. list-table:: + + * - *虚拟主机* + - ``host1`` + + +用户标签 +-------- + +已登录用户添加到检索结果文档上的用户标签（我的标签）也遵循虚拟主机（启用标签功能时）。通过虚拟主机访问时创建的用户标签，只会在该虚拟主机上列出并可使用。不匹配任何虚拟主机的访问可以看到所有用户标签。带虚拟主机的用户标签只会添加到设置了该虚拟主机的爬取配置的文档上。详细信息请参阅 :doc:`../admin/tagtype-guide` 和 :doc:`../api/api-tag` 。 diff --git a/zh-cn/15.10/config/setup-memory.rst b/zh-cn/15.10/config/setup-memory.rst new file mode 100644 index 000000000..94cf4b463 --- /dev/null +++ b/zh-cn/15.10/config/setup-memory.rst @@ -0,0 +1,437 @@ +============ +内存配置 +============ + +概述 +==== + +Java 应用程序需要为每个进程设置使用的最大堆内存。 +|Fess| 需要分别为以下3个组件进行内存配置。 + +- Fess Web 应用程序 +- 爬虫进程 +- OpenSearch + +通过适当的内存配置,可以实现性能提升和稳定运行。 + +Fess Web 应用程序的内存配置 +====================================== + +需要配置的情况 +---------------- + +在以下情况下,请考虑调整内存大小。 + +- ``fess.log`` 中记录了 OutOfMemory 错误 +- 需要处理大量并发访问 +- 管理页面操作缓慢或超时 + +默认内存大小对于一般使用已经足够,但在高负载环境下需要增加。 + +环境变量配置 +------------------ + +设置环境变量 ``FESS_HEAP_SIZE``\ 。 + +:: + + export FESS_HEAP_SIZE=2g + +单位: + +- ``m``: 兆字节 +- ``g``: 吉字节 + +精细内存控制 +~~~~~~~~~~~~ + +``FESS_HEAP_SIZE`` 将 ``-Xms`` 和 ``-Xmx`` 设置为相同的值。如需分别控制初始堆大小和最大堆大小，请使用 ``FESS_MIN_MEM`` 和 ``FESS_MAX_MEM`` 环境变量。 + +:: + + export FESS_MIN_MEM=256m + export FESS_MAX_MEM=2g + +.. list-table:: 各平台默认内存设置 + :header-rows: 1 + :widths: 30 35 35 + + * - 平台 + - FESS_MIN_MEM（默认值） + - FESS_MAX_MEM（默认值） + * - Linux + - 256m + - 2g + * - Windows + - 256m + - 1g + +.. note:: + 设置 ``FESS_HEAP_SIZE`` 后，``FESS_MIN_MEM`` 和 ``FESS_MAX_MEM`` 将被忽略。 + +.. note:: + RPM/DEB 软件包的环境配置文件（ ``/etc/sysconfig/fess`` ，DEB 为 ``/etc/default/fess`` ）中已设置 ``FESS_HEAP_SIZE=512m`` 。因此堆大小固定为 512m，而不是上表中的默认值。要更改堆大小，请修改该 ``FESS_HEAP_SIZE`` 的值。 + +RPM/DEB 软件包配置 +------------------------ + +使用 RPM 软件包安装时,请编辑 ``/etc/sysconfig/fess``\ 。 + +:: + + FESS_HEAP_SIZE=2g + +使用 DEB 软件包时,请编辑 ``/etc/default/fess``\ 。 + +:: + + FESS_HEAP_SIZE=2g + +.. warning:: + 变更内存大小后,需要重启 |Fess| 服务。 + +推荐内存大小 +---------------- + +.. list-table:: + :header-rows: 1 + :widths: 30 30 40 + + * - 环境 + - 推荐堆大小 + - 备注 + * - 开发/测试环境 + - 512m〜1g + - 小规模索引 + * - 小规模生产环境 + - 1g〜2g + - 数万〜数十万文档 + * - 中规模生产环境 + - 2g〜4g + - 数十万〜数百万文档 + * - 大规模生产环境 + - 4g〜8g + - 数百万以上文档 + +爬虫的内存配置 +====================== + +需要配置的情况 +---------------- + +在以下情况下,需要增加爬虫的内存大小。 + +- 增加并行爬取数量时 +- 爬取大型文件时 +- 爬取执行中发生 OutOfMemory 错误时 + +配置方法 +-------- + +编辑 ``app/WEB-INF/classes/fess_config.properties`` 或 ``/etc/fess/fess_config.properties``\ 。 + +``jvm.crawler.options`` 是一个设置值，其中以换行（ ``\n`` ）分隔列出了爬取进程的 JVM 选项。修改该值会替换全部默认选项，因此如果只写 ``-Xmx512m`` ，则 ``-Dfile.encoding=UTF-8`` 和 G1GC 设置等其他默认选项也会随之丢失。请保留 ``fess_config.properties`` 中记载的默认值，只修改堆大小所在的行。 + +例如，要将最大堆改为 1GB，请将默认值中的 ``-Xmx512m`` 行改为如下内容。 + +:: + + -Xms128m\n\ + -Xmx1g\n\ + +.. note:: + 此配置按爬虫进程单位(调度器的任务单位)应用。 + 同时执行多个爬取任务时,每个任务都会使用指定的内存。 + +推荐配置 +-------- + +- **常规Web爬取**: 512m〜1g +- **大量并行爬取**: 1g〜2g +- **大型文件爬取**: 2g〜4g + +详细 JVM 选项 +------------------ + +爬虫的详细 JVM 选项可以通过 ``jvm.crawler.options`` 配置。 +默认配置包含以下优化。 + +**主要选项:** + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - 选项 + - 说明 + * - ``-Xms128m -Xmx512m`` + - 初始堆大小和最大堆大小 + * - ``-XX:MaxMetaspaceSize=128m`` + - Metaspace 的最大大小 + * - ``-XX:+UseG1GC`` + - 使用 G1 垃圾收集器 + * - ``-XX:MaxGCPauseMillis=60000`` + - 最大GC暂停时间目标（60秒）。这是针对爬虫工作负载的宽松设置（一般应用程序通常为200ms左右） + * - ``-XX:-HeapDumpOnOutOfMemoryError`` + - 禁用 OutOfMemory 时的堆转储 + +OpenSearch 的内存配置 +======================= + +重要注意事项 +-------------- + +OpenSearch 配置内存时需要考虑以下两点。 + +1. **Java堆内存**: OpenSearch 进程使用 +2. **OS文件系统缓存**: 对搜索性能很重要 + +.. warning:: + Java堆内存过大会导致 OS 文件系统缓存 + 可用内存减少,从而降低搜索性能。 + +配置方法 +-------- + +Linux 环境 +~~~~~~~~~ + +推荐通过编辑 ``config/jvm.options`` 配置 OpenSearch 的堆内存: + +:: + + -Xms2g + -Xmx2g + +.. note:: + 推荐将最小堆大小(``-Xms``)和最大堆大小(``-Xmx``)设置为相同的值。 + +.. note:: + ``OPENSEARCH_HEAP_SIZE`` 环境变量已被弃用。请改用 ``config/jvm.options`` 进行配置。如需通过环境变量设置，请使用 ``OPENSEARCH_JAVA_OPTS``： + + :: + + export OPENSEARCH_JAVA_OPTS="-Xms2g -Xmx2g" + +Windows 环境 +~~~~~~~~~~~ + +编辑 ``config\jvm.options`` 文件。 + +:: + + -Xms2g + -Xmx2g + +推荐内存大小 +---------------- + +.. list-table:: + :header-rows: 1 + :widths: 30 30 40 + + * - 索引大小 + - 推荐堆大小 + - 推荐总内存 + * - 〜10GB + - 2g + - 4GB以上 + * - 10GB〜50GB + - 4g + - 8GB以上 + * - 50GB〜100GB + - 8g + - 16GB以上 + * - 100GB以上 + - 16g〜31g + - 32GB以上 + +.. warning:: + OpenSearch 的堆内存请不要超过 32GB。 + 超过 32GB 会禁用 Compressed OOP,导致内存效率降低。 + +最佳实践 +------------------ + +1. **将物理内存的50%分配给堆** + + 将服务器物理内存的约50%分配给 OpenSearch 的堆。 + 其余用于 OS 和文件系统缓存。 + +2. **最大31GB** + + 堆大小最大设为 31GB,如需更多内存请增加节点数。 + +3. **生产环境确认** + + 请参考 OpenSearch 官方文档,根据环境进行最优配置。 + +建议/缩略图处理的内存配置 +====================================== + +建议生成进程 +---------------------- + +建议生成处理的内存配置通过 ``jvm.suggest.options`` 设置。 + +与爬取进程一样，该设置值包含全部默认选项，因此请只修改 ``-Xmx256m`` 所在的行，其余保持不变。 + +默认使用以下配置: + +- 初始堆: 128MB +- 最大堆: 256MB +- Metaspace最大: 128MB + +缩略图生成进程 +---------------------- + +缩略图生成处理的内存配置通过 ``jvm.thumbnail.options`` 设置。 + +与爬取进程一样，该设置值包含全部默认选项，因此请只修改 ``-Xmx256m`` 所在的行，其余保持不变。 + +默认使用以下配置: + +- 初始堆: 128MB +- 最大堆: 256MB +- Metaspace最大: 128MB + +.. note:: + 处理大型图片的缩略图生成时,需要增加内存。 + +内存监控与调优 +======================== + +内存使用情况确认 +-------------------- + +Fess 的内存使用情况 +~~~~~~~~~~~~~~~~~~~~~ + +可以在管理页面的"系统信息"中确认。 + +或者,使用 JVM 监控工具: + +:: + + jps -l # 确认Fess进程 + jstat -gcutil 1000 # 每秒显示GC统计 + +OpenSearch 的内存使用情况 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + curl -X GET "localhost:9200/_nodes/stats/jvm?pretty" + curl -X GET "localhost:9200/_cat/nodes?v&h=heap.percent,ram.percent" + +内存不足的征兆 +---------------- + +出现以下症状时,可能存在内存不足。 + +**Fess Web 应用程序:** + +- 响应缓慢 +- 日志中记录了 ``OutOfMemoryError`` +- 进程意外终止 + +**爬虫:** + +- 爬取中途停止 +- ``fess-crawler.log`` 中记录了 ``OutOfMemoryError`` +- 大型文件爬取失败 + +**OpenSearch:** + +- 搜索缓慢 +- 索引创建缓慢 +- 发生 ``circuit_breaker_exception`` 错误 + +调优步骤 +---------------- + +1. **确认当前内存使用情况** + + 监控各组件的内存使用情况。 + +2. **识别瓶颈** + + 确定哪个组件内存不足。 + +3. **逐步增加** + + 不要一次大幅增加,而是每次增加25-50%并确认效果。 + +4. **考虑系统整体平衡** + + 确保各组件的总内存不超过物理内存。 + +5. **持续监控** + + 持续监控内存使用情况,根据需要进行调整。 + +内存泄漏对策 +---------------- + +怀疑内存泄漏时: + +1. **获取堆转储** + +:: + + jmap -dump:format=b,file=heap.bin + +2. **堆转储分析** + + 使用 Eclipse Memory Analyzer (MAT) 等工具进行分析。 + +3. **问题报告** + + 发现内存泄漏时,请在 GitHub Issues 中报告。 + +故障排除 +====================== + +发生 OutOfMemoryError +--------------------------- + +**Fess Web 应用程序:** + +1. 增加 ``FESS_HEAP_SIZE``\ 。 +2. 限制并发访问数。 +3. 降低日志级别,减少日志输出的内存使用。 + +**爬虫:** + +1. 增加 ``jvm.crawler.options`` 中的 ``-Xmx``\ 。 +2. 减少并行爬取数量。 +3. 调整爬取配置以排除大型文件。 + +**OpenSearch:** + +1. 增加堆大小(最大31GB)。 +2. 重新评估索引的分片数。 +3. 检查查询的复杂度。 + +GC 停止时间过长 +---------------------- + +1. 调整 G1GC 配置。 +2. 适当设置堆大小(过大或过小都会导致GC频繁)。 +3. 考虑更新到更新的 Java 版本。 + +配置内存后性能仍未改善 +------------------------------ + +1. 检查 CPU、磁盘 I/O、网络等其他资源。 +2. 优化索引。 +3. 重新评估查询和爬取配置。 + +参考信息 +======== + +- :doc:`setup-port-network` - 端口与网络配置 +- :doc:`crawler-advanced` - 爬虫高级配置 +- :doc:`admin-logging` - 日志配置 +- `OpenSearch Memory Settings `_ +- `Java GC Tuning `_ diff --git a/zh-cn/15.10/config/setup-port-network.rst b/zh-cn/15.10/config/setup-port-network.rst new file mode 100644 index 000000000..b2c232d80 --- /dev/null +++ b/zh-cn/15.10/config/setup-port-network.rst @@ -0,0 +1,462 @@ +====================== +端口与网络配置 +====================== + +概述 +==== + +本章节介绍 |Fess| 的网络相关配置。 +包括端口号变更、代理服务器配置、HTTP通信配置等网络连接相关设置。 + +使用端口配置 +================ + +默认端口 +---------------- + +|Fess| 默认使用以下端口。 + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 服务 + - 端口号 + * - Fess Web 应用程序 + - 8080 + * - OpenSearch (HTTP) + - 9200 + * - OpenSearch (Transport) + - 9300 + +Fess Web 应用程序端口变更 +-------------------------------------- + +Linux 环境配置 +~~~~~~~~~~~~~~~~~ + +在 Linux 环境中变更端口号时,请编辑 ``bin/fess.in.sh`` 文件。 + +:: + + FESS_JAVA_OPTS="$FESS_JAVA_OPTS -Dfess.port=8080" + +例如,要使用端口 80: + +:: + + FESS_JAVA_OPTS="$FESS_JAVA_OPTS -Dfess.port=80" + +.. note:: + 使用 1024 以下的端口号时,需要 root 权限或适当的权限设置(CAP_NET_BIND_SERVICE)。 + +环境变量配置 +~~~~~~~~~~~~~~~~~~ + +也可以通过环境变量指定端口号。 + +:: + + export FESS_PORT=8080 + +.. warning:: + ``FESS_PORT`` 环境变量仅在 Linux 环境中可用。在 Windows 环境中，请直接编辑 ``bin\fess.in.bat`` 中的 ``-Dfess.port``\ 。 + +RPM/DEB 软件包配置 +~~~~~~~~~~~~~~~~~~~~~~~~ + +RPM 软件包请编辑 ``/etc/sysconfig/fess``,DEB 软件包请编辑 ``/etc/default/fess``\ 。 + +:: + + FESS_PORT=8080 + +Windows 环境配置 +~~~~~~~~~~~~~~~~~~~ + +在 Windows 环境中,请编辑 ``bin\fess.in.bat`` 文件。 + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.port=8080 + +注册为 Windows 服务时 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +在 Windows 环境中作为服务注册使用时,请同时变更 ``bin\service.bat`` 中的端口配置。 +详情请参阅 :doc:`setup-windows-service`。 + +上下文路径配置 +---------------------- + +要在子目录中发布 |Fess|,可以配置上下文路径。 + +Linux 环境: + +:: + + FESS_JAVA_OPTS="$FESS_JAVA_OPTS -Dfess.context.path=/search" + +或者使用环境变量: + +:: + + export FESS_CONTEXT_PATH=/search + +Windows 环境: + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.context.path=/search + +此配置将使您可以通过 ``http://localhost:8080/search/`` 访问。 + +.. warning:: + ``FESS_CONTEXT_PATH`` 环境变量仅在 Linux 环境中可用。在 Windows 环境中，请直接编辑 ``bin\fess.in.bat`` 中的 ``-Dfess.context.path``\ 。 + +.. warning:: + 变更上下文路径后,还需要正确配置静态文件的路径。 + +代理服务器配置 +============ + +概述 +---- + +当从内网爬取外部网站或访问外部 API 时, +通信可能会被防火墙阻止。 +在这种环境中,需要配置通过代理服务器进行通信。 + +爬虫代理服务器配置 +-------------------------- + +基本配置 +~~~~~~~~ + +在管理页面的爬虫配置中,在配置参数中指定如下内容。 + +:: + + client.proxyHost=proxy.example.com + client.proxyPort=8080 + +需要认证的代理服务器配置 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +如果代理服务器需要认证,请添加如下配置。 + +:: + + client.proxyHost=proxy.example.com + client.proxyPort=8080 + client.proxyUsername=proxyuser + client.proxyPassword=proxypass + +从代理服务器排除特定主机 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +爬虫的代理设置不支持 nonProxyHosts。 +要从代理中排除特定主机,请使用环境变量 ``FESS_NON_PROXY_HOSTS``\ 。 +此设置会被转换为 Java 系统属性 ``http.nonProxyHosts``，并应用于 Fess 的所有 HTTP 通信。 + +:: + + FESS_NON_PROXY_HOSTS=localhost|*.local|192.168.* + +爬虫默认代理配置 +------------------------------ + +当爬虫配置中未单独指定 ``client.proxyHost`` 时，可以在 ``fess_config.properties`` 中设置默认代理。 +此设置适用于爬虫的默认代理，以及 LLM 集成的 HTTP 通信和插件下载。但不适用于 SSO 认证等部分 Java 库的通信。若要为整个 Fess 应用程序（包括 SSO 认证）应用代理，请使用下文所述的环境变量（``FESS_PROXY_HOST`` 等）。 + +:: + + http.proxy.host=proxy.example.com + http.proxy.port=8080 + http.proxy.username=proxyuser + http.proxy.password=proxypass + +.. warning:: + 密码将以未加密形式保存。请设置适当的文件权限。 + +.. note:: + ``http.proxy.*`` 设置不适用于 SSO 认证等。若要为包括 SSO 认证在内的整个 Fess 应用程序（JVM 范围的 HTTP 通信）使用代理，请设置环境变量 ``FESS_PROXY_HOST`` 和 ``FESS_PROXY_PORT``\ 。详情请参阅下文"通过环境变量配置代理"。 + +通过环境变量配置代理 +~~~~~~~~~~~~~~~~~~~~ + +当 Java 库(如 SSO 认证)需要使用代理时,必须通过环境变量进行配置。 +这些环境变量会被转换为 Java 系统属性(``http.proxyHost``、``https.proxyHost`` 等)。 + +:: + + FESS_PROXY_HOST=proxy.example.com + FESS_PROXY_PORT=8080 + FESS_NON_PROXY_HOSTS=localhost|*.local|192.168.* + +对于 RPM 包,在 ``/etc/sysconfig/fess`` 中配置。对于 DEB 包,在 ``/etc/default/fess`` 中配置。 + +.. note:: + ``fess_config.properties`` 中的 ``http.proxy.*`` 设置用于爬虫的默认代理，以及 LLM 集成和插件下载。 + 若要为包括 SSO 认证在内的整个 Fess 应用程序（JVM 范围的 HTTP 通信）使用代理，请设置上述环境变量。 + +HTTP 通信配置 +============ + +文件上传限制 +-------------------------- + +可以限制从管理页面上传文件的大小。 + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - 配置项 + - 说明 + * - ``http.fileupload.max.size`` + - 最大文件上传大小(默认: 262144000字节 = 250MB) + * - ``http.fileupload.threshold.size`` + - 内存保留阈值大小(默认: 262144字节 = 256KB) + * - ``http.fileupload.max.file.count`` + - 一次可上传的文件数(默认: 10) + +``fess_config.properties`` 配置示例: + +:: + + http.fileupload.max.size=524288000 + http.fileupload.threshold.size=524288 + http.fileupload.max.file.count=20 + +OpenSearch 连接配置 +-------------------- + +您可以配置 OpenSearch 的连接 URL 和健康检查（心跳）间隔。 + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - 配置项 + - 说明 + * - ``search_engine.http.url`` + - OpenSearch的URL(默认: http://localhost:9200)。环境变量 ``SEARCH_ENGINE_HTTP_URL`` 优先(见下文)。 + * - ``search_engine.heartbeat_interval`` + - 健康检查间隔(毫秒,默认: 10000) + +OpenSearch 连接目标变更 +---------------------- + +连接目标的 URL 通过环境变量 ``SEARCH_ENGINE_HTTP_URL`` 指定。该环境变量优先于 +``fess_config.properties`` 中的 ``search_engine.http.url`` 。ZIP 版的 ``bin/fess.in.sh`` +和 RPM/DEB 版的环境配置文件默认将该环境变量设置为 ``http://localhost:9200`` ，因此即使 +修改 ``search_engine.http.url`` ，连接目标也不会改变。 + +设置位置因安装方式而异。 + +- ZIP 版：编辑 ``bin/fess.in.sh`` 中 ``SEARCH_ENGINE_HTTP_URL`` 所在的行，或在启动 + |Fess| 的环境中 export ``SEARCH_ENGINE_HTTP_URL`` （参见 :doc:`../install/install-linux` ）。 +- RPM/DEB 版： ``/etc/sysconfig/fess`` （RPM）或 ``/etc/default/fess`` （DEB）中的 + ``SEARCH_ENGINE_HTTP_URL`` +- Docker：容器的环境变量 ``SEARCH_ENGINE_HTTP_URL`` （参见 :doc:`../install/install-docker` ） +- Windows 上的 ZIP 版： ``bin\fess.in.bat`` 中 ``-Dfess.search_engine.http_address`` + 所在的行（参见 :doc:`../install/install-windows` ） + +:: + + SEARCH_ENGINE_HTTP_URL=http://opensearch-cluster.example.com:9200 + +连接多个节点 +~~~~~~~~~~~~~~~~~~ + +连接多个 OpenSearch 节点时，请用逗号分隔各个 URL。即使部分节点已停止， |Fess| 也会 +连接到其余节点。 + +:: + + SEARCH_ENGINE_HTTP_URL=http://node1:9200,http://node2:9200,http://node3:9200 + +SSL/TLS 连接配置 +----------------- + +通过 HTTPS 连接到 OpenSearch 时，请按与上文相同的方法指定 ``https://`` 的 URL。 + +:: + + SEARCH_ENGINE_HTTP_URL=https://opensearch.example.com:9200 + +CA 证书和认证信息在 ``fess_config.properties`` 中设置。 + +:: + + search_engine.http.ssl.certificate_authorities=/path/to/ca.crt + search_engine.username=admin + search_engine.password=admin_password + +.. note:: + 进行证书验证时,请在 ``certificate_authorities`` 中指定 CA 证书的路径。 + +虚拟主机配置 +============== + +概述 +---- + +可以根据访问 |Fess| 的主机名显示不同的搜索结果。 +详情请参阅 :doc:`security-virtual-host`。 + +基本配置 +-------- + +在管理界面的"系统 > 常规"（``virtual.host.headers``）中配置虚拟主机。每行指定一个虚拟主机，格式为 ``Host:主机名[:端口号]=虚拟主机名``\ 。默认值为空（未设置），虚拟主机功能处于禁用状态。 + +:: + + Host:search1.example.com=site1 + Host:search2.example.com=site2 + +.. note:: + ``virtual.host.headers`` 的值不是诸如 ``X-Forwarded-Host,Host`` 之类的标头名称列表。每行描述一个 ``标头名称:标头值=虚拟主机名`` 格式的映射。有关详细格式和约束，请参阅 :doc:`security-virtual-host`。 + +反向代理集成 +======================== + +Nginx 配置示例 +-------------- + +:: + + server { + listen 80; + server_name search.example.com; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Host $host; + } + } + +Apache 配置示例 +--------------- + +:: + + + ServerName search.example.com + + ProxyPreserveHost On + ProxyPass / http://localhost:8080/ + ProxyPassReverse / http://localhost:8080/ + + RequestHeader set X-Forwarded-Proto "http" + RequestHeader set X-Forwarded-Host "search.example.com" + + +SSL/TLS 终止 +----------- + +在反向代理上进行 SSL/TLS 终止的配置示例(Nginx): + +:: + + server { + listen 443 ssl http2; + server_name search.example.com; + + ssl_certificate /path/to/cert.pem; + ssl_certificate_key /path/to/key.pem; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto https; + proxy_set_header X-Forwarded-Host $host; + } + } + +防火墙配置 +==================== + +开放必要端口 +------------------ + +要使 |Fess| 可从外部访问,请开放以下端口。 + +**iptables 配置示例:** + +:: + + # Fess Web 应用程序 + iptables -A INPUT -p tcp --dport 8080 -j ACCEPT + + # 通过 HTTPS 访问时(经由反向代理) + iptables -A INPUT -p tcp --dport 443 -j ACCEPT + +**firewalld 配置示例:** + +:: + + # Fess Web 应用程序 + firewall-cmd --permanent --add-port=8080/tcp + firewall-cmd --reload + +安全组配置(云环境) +------------------------------------------ + +在 AWS、GCP、Azure 等云环境中,请在安全组或网络 ACL 中 +开放适当的端口。 + +推荐配置: +- 入站: 80/443端口(通过 HTTP 反向代理) +- 8080端口仅限从内部访问 +- OpenSearch 的 9200/9300 端口仅限从内部访问 + +故障排除 +====================== + +变更端口后无法访问 +------------------------------ + +1. 请确认是否已重启 |Fess|\ 。 +2. 请确认防火墙是否已开放相应端口。 +3. 请在日志文件(``fess.log``)中确认错误信息。 + +无法通过代理服务器爬取 +------------------------------ + +1. 请确认代理服务器的主机名和端口是否正确。 +2. 如代理服务器需要认证,请配置用户名和密码。 +3. 请在代理服务器日志中确认是否记录了连接尝试。 +4. 请确认 ``nonProxyHosts`` 的配置是否正确。 + +无法连接到 OpenSearch +------------------------- + +1. 请确认 OpenSearch 是否已启动。 +2. 请确认 ``search_engine.http.url`` 的配置是否正确。 +3. 请确认网络连接: ``curl http://localhost:9200`` +4. 请在 OpenSearch 日志中确认错误信息。 + +通过反向代理访问时无法正常工作 +---------------------------------------------------- + +1. 请确认 ``X-Forwarded-Host`` 头是否配置正确。 +2. 请确认 ``X-Forwarded-Proto`` 头是否配置正确。 +3. 请确认上下文路径是否配置正确。 +4. 请在反向代理日志中确认错误信息。 + +参考信息 +======== + +- :doc:`setup-memory` - 内存配置 +- :doc:`setup-windows-service` - Windows 服务配置 +- :doc:`security-virtual-host` - 虚拟主机配置 +- :doc:`crawler-advanced` - 爬虫高级配置 +- `OpenSearch Configuration `_ diff --git a/zh-cn/15.10/config/setup-windows-service.rst b/zh-cn/15.10/config/setup-windows-service.rst new file mode 100644 index 000000000..61b9ad879 --- /dev/null +++ b/zh-cn/15.10/config/setup-windows-service.rst @@ -0,0 +1,134 @@ +======================== +注册为 Windows 服务 +======================== + +注册为 Windows 服务 +==================== + +可以将 |Fess| 注册为 Windows 服务。注册为服务后，可以在系统启动时自动启动 |Fess|\ 。 +要运行 |Fess|，需要先启动 OpenSearch。 +本文档假设已将 |Fess| 安装在 ``c:\opt\fess``，OpenSearch 安装在 ``c:\opt\opensearch``\ （请根据实际环境替换路径）。 + +.. note:: + |Fess| 和 OpenSearch 仅支持 64 位版本。 + +前期准备 +-------- + +请将 ``JAVA_HOME`` 设置为系统环境变量。若未设置 ``JAVA_HOME``，``service.bat`` 将报错退出。 + +将 OpenSearch 注册为服务 +------------------------ + +以管理员权限启动命令提示符，执行 ``c:\opt\opensearch\bin\opensearch-service.bat``\ 。 + +:: + + > cd c:\opt\opensearch\bin + > opensearch-service.bat install + ... + The service 'opensearch-service-x64' has been installed. + +详情请参阅 `OpenSearch 文档 `_\ 。 + +|Fess| 的配置 +------------- + +服务通过 ``c:\opt\fess\bin\service.bat`` 进行注册。\ ``service.bat`` 在注册时会读取 ``bin\fess.in.bat``，并将其内容反映到 |Fess| 的启动选项中。 +请在 ``c:\opt\fess\bin\fess.in.bat`` 中添加连接 OpenSearch 的配置。 + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200 + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=c:/opt/opensearch/config/dictionary/ + +.. note:: + - ``fess.search_engine.http_address`` 用于指定已注册的 OpenSearch 服务的连接地址。若不进行此配置，|Fess| 将无法找到连接目标而不会启动，并报告未配置搜索引擎地址。 + - 若 OpenSearch 运行在其他主机上，请将主机名或 IP 地址修改为适当的值。 + - 路径分隔符请使用 ``/``\ 。 + +|Fess| 搜索页面和管理页面的默认端口号为 ``8080``\ 。如需更改为其他端口，请编辑 ``c:\opt\fess\bin\fess.in.bat`` 中的 ``-Dfess.port``\ 。 + +:: + + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.port=80 + +.. note:: + 注册为服务时，``bin\service.bat`` 中的 ``FESS_PARAMS`` 也硬编码了 ``-Dfess.port=8080``\ 。由于该值优先于 ``fess.in.bat`` 的配置，更改端口时请同样编辑 ``service.bat`` 中的 ``FESS_PARAMS``\ 。 + +服务自定义（可选） +------------------ + +在执行 ``service.bat install`` 之前设置环境变量，可以更改服务的配置。主要的环境变量如下。 + +.. list-table:: + :header-rows: 1 + + * - 环境变量 + - 说明 + * - ``FESS_START_TYPE`` + - 启动类型（``auto`` 或 ``manual``）。默认为 ``manual``\ 。 + * - ``FESS_HEAP_SIZE`` + - 堆大小（例如：``1g``）。如需分别指定最小和最大堆大小，请使用 ``FESS_MIN_MEM``\ （默认 ``256m``）和 ``FESS_MAX_MEM``\ （默认 ``1g``）。 + * - ``SERVICE_USERNAME`` / ``SERVICE_PASSWORD`` + - 运行服务的 Windows 账户。 + * - ``SERVICE_DISPLAY_NAME`` + - 服务的显示名称。 + * - ``SERVICE_DESCRIPTION`` + - 服务的描述。 + +注册方法 +-------- + +以管理员权限启动命令提示符，执行 ``c:\opt\fess\bin\service.bat``\ 。 + +:: + + > cd c:\opt\fess\bin + > service.bat install + ... + The service 'fess-service-x64' has been installed. + +服务配置 +-------- + +如需手动启动服务，请先启动 OpenSearch 服务，再启动 |Fess| 服务。 +如需在系统启动时自动启动，请配置启动类型和依赖关系。 + +1. 在服务的常规设置中，将启动类型设置为"自动（延迟启动）"。 +2. 在注册表中配置服务依赖关系。 + +在注册表编辑器（regedit）中添加以下键和值。 + +.. list-table:: + + * - *键* + - ``Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\fess-service-x64\DependOnService`` + * - *值* + - ``opensearch-service-x64`` + +添加后，opensearch-service-x64 将显示在 |Fess| 服务属性的依赖关系中。 + +.. note:: + 在执行 ``service.bat install`` 之前设置环境变量 ``FESS_START_TYPE=auto``，可以将启动类型注册为"自动"。但是，"自动（延迟启动）"和依赖关系的配置无法通过 ``service.bat`` 完成，请按照上述步骤进行设置。 + +服务管理 +-------- + +使用 ``service.bat`` 可以通过以下命令操作服务。 + +.. list-table:: + :header-rows: 1 + + * - 命令 + - 说明 + * - ``service.bat install`` + - 注册服务。 + * - ``service.bat remove`` + - 删除服务。 + * - ``service.bat start`` + - 启动服务。 + * - ``service.bat stop`` + - 停止服务。 + * - ``service.bat manager`` + - 启动服务管理 GUI。 diff --git a/zh-cn/15.10/config/sso-entraid.rst b/zh-cn/15.10/config/sso-entraid.rst new file mode 100644 index 000000000..8b064316e --- /dev/null +++ b/zh-cn/15.10/config/sso-entraid.rst @@ -0,0 +1,406 @@ +================================ +Microsoft Entra ID SSO配置 +================================ + +概述 +==== + +|Fess| 支持使用Microsoft Entra ID（前Azure AD）进行单点登录（SSO）认证。 +通过使用Entra ID认证，您可以将Microsoft 365环境中的用户信息和组信息与 |Fess| 的基于角色的搜索集成。 + +.. note:: + Entra ID认证的支持由 ``fess-sso-entraid`` 插件提供，该插件不随发行包分发。请从管理 + 界面的「系统 > 插件」页面安装，或执行 ``bin/fess-setup install plugin fess-sso-entraid`` 。 + 在安装之前，即使设置 ``sso.type=entraid``\ （旧名 ``aad`` 亦同），对 ``/sso/`` 的请求也 + 只会重定向回登录页面。 + +Entra ID认证的工作原理 +---------------------- + +在Entra ID认证中，|Fess| 作为OAuth 2.0/OpenID Connect客户端运行，并与Microsoft Entra ID协作进行认证。 + +1. 用户访问 |Fess| 的SSO端点（``/sso/``） +2. |Fess| 将请求重定向到Entra ID的授权端点 +3. 用户在Entra ID进行认证（Microsoft登录） +4. Entra ID将授权码重定向到 |Fess| +5. |Fess| 使用授权码获取访问令牌 +6. 用户登录 +7. |Fess| 在后台使用Microsoft Graph API获取用户的组和角色信息，解析完成后应用于基于角色的搜索 + +.. note:: + |Fess| 15.10 及以后版本会向授权端点请求 ``response_mode=query``\ ，因此步骤4的授权响应以GET方式返回。 + 15.7 及之前版本以跨站POST方式返回，而 |Fess| 的默认值 ``tomcat.sameSiteCookies = lax`` + 在该情况下不会发送会话Cookie，因此需要将其改为 ``tomcat.sameSiteCookies = none`` 作为规避方法。 + 如果您仅出于该原因设置了 ``none``\ ，现在可以恢复为默认值。 + +有关基于角色的搜索集成，请参阅 :doc:`security-role`。 + +前提条件 +======== + +在配置Entra ID认证之前，请验证以下前提条件： + +- 已安装 |Fess| 15.10或更高版本 +- Microsoft Entra ID（Azure AD）租户可用 +- |Fess| 可通过HTTPS访问（生产环境必需） +- 您有权在Entra ID中注册应用程序 + +基本配置 +======== + +启用SSO +------- + +要启用Entra ID认证，请在 ``app/WEB-INF/conf/system.properties`` 中添加以下设置： + +:: + + sso.type=entraid + +必需设置 +-------- + +配置从Entra ID获取的信息。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 属性 + - 描述 + - 默认值 + * - ``entraid.tenant`` + - 租户ID（例如：``xxx.onmicrosoft.com``） + - （必需） + * - ``entraid.client.id`` + - 应用程序（客户端）ID + - （必需） + * - ``entraid.client.secret`` + - 客户端密钥值 + - （必需） + * - ``entraid.reply.url`` + - 重定向URI（回调URL） + - 使用请求URL + +.. note:: + 除了 ``entraid.*`` 前缀外，您还可以使用旧版 ``aad.*`` 前缀以保持向后兼容性。 + +可选设置 +-------- + +可根据需要添加以下设置。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 属性 + - 描述 + - 默认值 + * - ``entraid.authority`` + - 认证服务器URL + - ``https://login.microsoftonline.com/`` + * - ``entraid.state.ttl`` + - State有效期（秒） + - ``3600`` + * - ``entraid.response.mode`` + - 授权响应的返回方式。可指定 ``query`` 或 ``form_post``\ 。 + - ``query`` + * - ``entraid.default.groups`` + - 默认组（逗号分隔）。会应用于每一个Entra ID用户。 + - （无） + * - ``entraid.default.roles`` + - 默认角色（逗号分隔）。会应用于每一个Entra ID用户。 + - （无） + * - ``entraid.permission.fields`` + - 额外用作权限值的组/角色字段（逗号分隔）。组/角色的ID（GUID）始终作为权限使用，此处指定的字段（例如 ``mail``）的值将被追加添加。只能指定值为字符串的字段。Microsoft Graph会将 ``securityEnabled`` 返回为布尔值、将 ``groupTypes`` 返回为数组，二者均无法作为权限值，因此指定这类字段时会被忽略，并在日志中输出指明该字段名的警告。 + - ``mail`` + * - ``entraid.use.ds`` + - 域服务集成。设为 ``true`` 时，对于 ``name@domain`` 格式的权限值，会同时将去除域部分后的本地部分（``name``）也添加为权限。这不仅适用于组和角色，也适用于已登录的用户本人：用户主体名称（UPN）的本地部分会作为用户级权限被添加。因此设为 ``false`` 时，不仅是组的权限，该用户级权限也不会再被添加。 + - ``true`` + +.. note:: + + 组/角色的ID（GUID）始终作为权限使用，但只有启用邮件的组才具有 ``mail`` 值。 + Microsoft 365组启用了邮件，因此组名也会注册为权限。 + 而 **安全组未启用邮件，保持默认值时只有GUID会成为权限**\ 。 + 如果文件系统的访问权限指定的是安全组名称，则权限不匹配，这些文档不会出现在搜索结果中。 + + 此时请添加所有组都具有的 ``displayName``\ ： + + .. code-block:: properties + + entraid.permission.fields=mail,displayName + + ``displayName`` 不带域限定且不唯一，因此未包含在默认值中。 + 例如，如果Entra ID中存在名为 ``Administrators`` 的组，它也会匹配访问权限指定了Windows内置组 + ``Administrators`` 的文档。添加前请确认这些名称不会与访问权限中已使用的名称冲突。 + +.. note:: + 使用默认值 ``query`` 时，授权码会包含在回调URL的查询字符串中。 + 指定 ``form_post`` 后，授权码不会出现在URL中，因此也不会留在浏览器历史记录以及前端代理或WAF的访问日志中。 + 但 ``form_post`` 会使回调成为跨站POST，因此需要 ``tomcat.sameSiteCookies = none``\ 。 + 未进行该设置时，会话Cookie不会被发送，登录将失败。 + 此外，浏览器仅对同时带有 ``Secure`` 属性的Cookie接受 ``none``\ ， + 因此使用 ``form_post`` 时必须通过HTTPS提供 |Fess| 。 + 在普通HTTP下，即使设置了 ``none``\ ，浏览器也根本不会保存会话Cookie，登录同样会失败。 + 因此大多数环境应保持默认值。 + 指定其他值时，将输出警告并按 ``query`` 处理。 + +.. warning:: + + ``entraid.default.groups`` 和 ``entraid.default.roles`` 是无法按用户区分的单个全局设置。 + |Fess| 会在登录时将它们应用于每一个Entra ID用户，并在之后每次解析时重新应用， + 因此Microsoft Graph的结果绝不会将其收回。尤其不要把 |Fess| 的管理员角色 + （在附带的 ``authentication.admin.roles`` 中为 ``admin``\ ）配置到 ``entraid.default.roles``\ ： + 这会让租户中的所有用户永久获得管理界面的访问权限。 + +Entra ID侧配置 +============== + +在Azure Portal中注册应用 +------------------------ + +1. 登录 `Azure Portal `_ + +2. 选择 **Microsoft Entra ID** + +3. 转到 **管理** → **应用注册** → **新注册** + +4. 注册应用程序： + + .. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 设置 + - 值 + * - 名称 + - 任意名称（例如：Fess SSO） + * - 支持的帐户类型 + - "仅此组织目录中的帐户" + * - 平台 + - Web + * - 重定向URI + - ``https:///sso/`` + +5. 点击 **注册** + +创建客户端密钥 +-------------- + +1. 在应用详情页面，点击 **证书和密码** + +2. 点击 **新客户端密钥** + +3. 设置描述和过期时间，然后点击 **添加** + +4. 复制并保存生成的 **值**\ （此值不会再次显示） + +.. warning:: + 客户端密钥值仅在创建后立即显示。 + 请务必在离开页面之前记录它。 + +配置API权限 +----------- + +1. 点击左侧菜单中的 **API权限** + +2. 点击 **添加权限** + +3. 选择 **Microsoft Graph** + +4. 选择 **委托的权限** + +5. 添加以下权限： + + - ``User.Read`` - 获取已登录用户的组成员关系（``/me/memberOf``）所需。创建应用注册时默认授予 + - ``GroupMember.Read.All`` - 读取组名等组属性以及解析嵌套组所需 + +6. 点击 **添加权限** + +7. 点击 **为<租户名称>授予管理员同意** + +.. note:: + 管理员同意需要租户管理员权限。 + +.. note:: + 也可以授予 ``Group.Read.All`` 或 ``Directory.Read.All`` 来代替 ``GroupMember.Read.All``\ ， + 组属性的获取与嵌套组的解析同样可以正常工作。但 ``/me/memberOf`` 无法通过 ``Group.Read.All`` + 授权，因此无论采用哪种方式都需要 ``User.Read``\ 。 + +.. note:: + 上述权限不包含目录角色的 ``displayName``\ ，Microsoft Graph 会将其返回为 null。 + 因此，即使在 ``entraid.permission.fields`` 中指定 ``displayName``\ ， + 目录角色也只有角色的 ID（GUID）会成为权限。 + 若要将角色名称用作权限值，请同时授予 ``RoleManagement.Read.Directory``\ （或 ``Directory.Read.All``\ ）。 + +.. note:: + |Fess| 在获取令牌时会请求 ``https://graph.microsoft.com/.default`` 作用域。 + 15.10 及以后版本还会向授权端点发送 ``openid profile offline_access https://graph.microsoft.com/.default``\ ，以便针对同一组权限请求同意。 + 这意味着将使用在应用注册中配置并已授予同意的所有访问权限。 + 因此，若要获取组信息，必须将上述权限添加到应用注册中，并授予管理员同意。 + +需要获取的信息 +-------------- + +以下信息用于Fess配置： + +- **应用程序（客户端）ID**：在概述页面上，显示为"应用程序(客户端) ID" +- **租户ID**：在概述页面上，显示为"目录(租户) ID"或 ``xxx.onmicrosoft.com`` 格式 +- **客户端密钥值**：在证书和密码中创建的值 + +组和角色映射 +============ + +通过Entra ID认证，|Fess| 使用Microsoft Graph API自动获取用户所属的组和角色。 +获取的组ID和组名可用于 |Fess| 的基于角色的搜索。 + +嵌套组 +------ + +|Fess| 不仅获取用户直接所属的组，还会获取这些组所属的父组（嵌套组）。 +直接所属关系的查找与父组的查找都在登录后的同一个后台任务中执行，因此登录本身不会被Microsoft Graph拖慢。 +父组的查找使用Microsoft Graph的 ``getMemberGroups`` 操作，该操作以传递方式解析：每个直接所属的组只需调用一次，即可返回其上层的所有父组，无论嵌套有多深。获取结果将被缓存一段时间。该后台任务完成后，用户的权限将被重新计算。 + +默认组设置 +---------- + +要为所有Entra ID用户分配通用组： + +:: + + entraid.default.groups=authenticated_users,entra_users + +配置示例 +======== + +最小配置（用于测试） +-------------------- + +以下是在测试环境中进行验证的最小配置示例。 + +:: + + # 启用SSO + sso.type=entraid + + # Entra ID设置 + entraid.tenant=yourcompany.onmicrosoft.com + entraid.client.id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + entraid.client.secret=your-client-secret-value + entraid.reply.url=http://localhost:8080/sso/ + +推荐配置（用于生产） +-------------------- + +以下是生产环境的推荐配置示例。 + +:: + + # 启用SSO + sso.type=entraid + + # Entra ID设置 + entraid.tenant=yourcompany.onmicrosoft.com + entraid.client.id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + entraid.client.secret=your-client-secret-value + entraid.reply.url=https://fess.example.com/sso/ + + # 默认组（可选） + entraid.default.groups=authenticated_users + +旧版配置（向后兼容） +-------------------- + +为了与以前的版本兼容，也可以使用 ``aad.*`` 前缀。 +当各 ``entraid.*`` 属性未设置时，将使用对应 ``aad.*`` 属性的值。此外，``sso.type=aad`` 与 ``sso.type=entraid`` 的处理方式相同。 + +:: + + # 启用SSO（也可使用 sso.type=aad） + sso.type=entraid + + # 旧版配置键 + aad.tenant=yourcompany.onmicrosoft.com + aad.client.id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + aad.client.secret=your-client-secret-value + aad.reply.url=https://fess.example.com/sso/ + +故障排除 +======== + +常见问题和解决方案 +------------------ + +认证后无法返回Fess +~~~~~~~~~~~~~~~~~~ + +- 验证Azure Portal应用注册中的重定向URI是否正确配置 +- 确保 ``entraid.reply.url`` 的值与Azure Portal配置完全匹配 +- 验证协议（HTTP/HTTPS）是否匹配 +- 验证重定向URI是否以 ``/`` 结尾 +- 如果将 ``entraid.response.mode`` 设置为 ``form_post``\ ，请同时确认已配置 + ``tomcat.sameSiteCookies = none``\ ，并且 |Fess| 通过 HTTPS 提供服务。使用默认值 ``lax`` 时， + 浏览器不会在回调的跨站 POST 中发送会话 Cookie；设置为 ``none`` 但仍使用普通 HTTP 时， + 由于 ``none`` 要求 ``Secure`` 属性，浏览器根本不会保存该 Cookie。 + 两种情况下登录都会当场失败一次，浏览器返回登录页面并显示“SSO登录处理失败。”， + 日志中会输出 ``Failed to process SSO login: could not validate state`` 警告 + +发生认证错误 +~~~~~~~~~~~~ + +- 验证租户ID、客户端ID和客户端密钥是否正确配置 +- 检查客户端密钥是否已过期 +- 验证是否已为API权限授予管理员同意 + +无法获取组信息 +~~~~~~~~~~~~~~ + +- 验证是否已授予 ``User.Read`` 和 ``GroupMember.Read.All`` 权限 + （``GroupMember.Read.All`` 可以用 ``Group.Read.All`` 或 ``Directory.Read.All`` 代替， + 但 ``/me/memberOf`` 仍然需要 ``User.Read``\ ） +- 验证是否已授予管理员同意 +- 检查用户是否在Entra ID中属于组 +- 如果无法解析嵌套的父组，日志中会输出 ``Not allowed to read the parent groups of ...`` 警告。 + 此时请授予 ``GroupMember.Read.All`` +- |Fess| 会在登录完成后于后台解析用户所属的组和角色，因此登录本身不会等待Microsoft Graph的响应。 + 在解析完成之前，用户拥有的仅有其自身的用户级权限，以及在 ``entraid.default.groups`` 和 + ``entraid.default.roles`` 中配置的组和角色。若两者都未配置（即附带的默认值）， + 这段时间内的搜索将一条文档都搜不到：\ ``role.search.default.permissions`` 出厂时为空， + 而按附带的 ``role.search.default.display.permissions`` 创建的爬取配置会授予 ``{role}guest``\ ， + 已登录用户并不持有该角色。这段时间为最多约1秒的调度延迟，加上Microsoft Graph调用本身 + （直接所属查询1次，再为每个直接所属的组各1次以遍历嵌套组，依次串行执行，且缓存为空时）， + 因此会随用户所属组的数量增加而变长。在此期间，搜索界面会提示用户组和角色权限仍在加载中， + 并请其稍后重新搜索 +- 如果解析未能完全成功，搜索界面会提示用户无法完整加载其组和角色权限，请其注销后重新登录， + 并在问题反复出现时联系管理员。「完全」是特意的措辞：只有直接所属查询和嵌套组遍历都成功， + 解析才算成功，因此已取得直接所属的组、但未能取得父组的用户也会看到该提示。 + 但有一个例外，即上一条所描述的情况：当因未授予 ``GroupMember.Read.All`` 而导致 + Microsoft Graph以 ``Authorization_RequestDenied`` 拒绝嵌套组查询时，\ |Fess| 不会将其视为失败， + 而是视为「该组没有父组」的回答。此时即使缺少父组的权限，解析也会被视为成功，\ **不会显示该提示**\ 。 + 唯一的线索是日志中输出的 ``Not allowed to read the parent groups of ...`` 警告， + 因此在使用嵌套组时，请确认是否出现了该警告。 + 部分解析失败最常见的原因是限流：Microsoft Graph只要返回一次HTTP 429或503，\ |Fess| 就会按 + ``Retry-After`` 标头要求的时间（无可用值时为60秒，最长60分钟）退避，在此期间即使直接所属查询仍能成功， + 整个 |Fess| 实例也会跳过嵌套组查询。但失败并不一定就是最终结果： + 每次刷新访问令牌时都会重新解析，之后一旦成功，提示即会消失，缺少的权限也会恢复。 + 先注销再重新登录即可立即重试——在保持登录状态下打开SSO登录URL，只会重定向回搜索界面 + +调试设置 +-------- + +要调查问题，您可以通过调整 |Fess| 的日志级别来输出详细的Entra ID相关日志。 + +在 ``app/WEB-INF/classes/log4j2.xml`` 中，您可以添加以下日志记录器来更改日志级别： + +:: + + + +参考 +==== + +- :doc:`security-role` - 基于角色的搜索配置 +- :doc:`sso-saml` - SAML认证SSO配置 +- :doc:`sso-oidc` - OpenID Connect认证SSO配置 diff --git a/zh-cn/15.10/config/sso-oidc.rst b/zh-cn/15.10/config/sso-oidc.rst new file mode 100644 index 000000000..469db542a --- /dev/null +++ b/zh-cn/15.10/config/sso-oidc.rst @@ -0,0 +1,322 @@ +===================================== +使用OpenID Connect进行SSO配置 +===================================== + +概述 +==== + +|Fess| 支持使用OpenID Connect（OIDC）进行单点登录（SSO）认证。 +OpenID Connect是基于OAuth 2.0的认证协议，使用ID Token（JWT）进行用户认证。 +通过使用OpenID Connect认证，由OpenID提供者（OP）认证的用户信息可以与 |Fess| 集成。 + +.. note:: + OpenID Connect认证的支持由 ``fess-sso-oidc`` 插件提供，该插件不随发行包分发。请从管理 + 界面的「系统 > 插件」页面安装，或执行 ``bin/fess-setup install plugin fess-sso-oidc`` 。 + 插件名为 ``fess-sso-oidc``\ ，而 ``sso.type`` 的取值仍为 ``oic``\ 。 + 在安装之前，即使设置 ``sso.type=oic``\ ，对 ``/sso/`` 的请求也只会重定向回登录页面。 + +OpenID Connect认证的工作原理 +---------------------------- + +在OpenID Connect认证中，|Fess| 作为依赖方（RP）运行，并与外部OpenID提供者（OP）协作进行认证。 + +1. 用户访问 |Fess| 的SSO端点（``/sso/``） +2. |Fess| 将请求重定向到OP的授权端点 +3. 用户在OP进行认证 +4. OP将授权码重定向到 |Fess| +5. |Fess| 使用授权码从令牌端点获取ID Token +6. |Fess| 校验ID Token（JWT）中的声明，获取用户信息并登录用户 + +.. note:: + |Fess| 使用授权码流程（Authorization Code Flow）。ID Token不经过浏览器，而是通过 |Fess| 与OP之间的后端通道（服务器间通信）直接从令牌端点获取。 + |Fess| 通过解码ID Token来提取声明（如 ``email`` 和 ``groups``）以构建用户信息，但不对JWT签名进行密码学验证。由于令牌是通过TLS直接从令牌端点接收的，OpenID Connect Core允许这样做，因此令牌端点URL（``oic.token.server.url``）必须为HTTPS。只有 ``localhost``、``127.x.x.x`` 和 ``::1`` 可以使用 ``http``。 + |Fess| 会校验声明：``aud`` 必须包含 ``oic.client.id``\ （``azp`` 存在时也必须与其一致），``exp`` 必须存在且尚未过期（允许最多300秒的时钟偏差），设置了 ``oic.issuer`` 时 ``iss`` 必须与其一致。未设置 ``oic.issuer`` 时不校验 ``iss``，并会在每次启动后的首次登录时记录一条警告。不使用 ``nonce`` 和PKCE。 + +有关基于角色的搜索集成，请参阅 :doc:`security-role`。 + +前提条件 +======== + +在配置OpenID Connect认证之前，请验证以下前提条件： + +- 已安装 |Fess| 15.10或更高版本 +- 有可用的OpenID Connect兼容提供者（OP） +- |Fess| 可通过HTTPS访问（生产环境必需） +- 您有权在OP侧将 |Fess| 注册为客户端（RP） + +支持的提供者示例： + +- Microsoft Entra ID（Azure AD） +- Google Workspace / Google Cloud Identity +- Okta +- Keycloak +- Auth0 +- 其他OpenID Connect兼容提供者 + +基本配置 +======== + +启用SSO功能 +----------- + +要启用OpenID Connect认证，请在 ``app/WEB-INF/conf/system.properties`` 中添加以下设置： + +:: + + sso.type=oic + +.. note:: + ``sso.type`` 以及后文说明的各项 ``oic.*`` 设置（``oic.issuer`` 除外），也可以通过管理画面的"系统 > 全局"页面进行设置和修改。 + 在管理画面中修改的设置将保存到 ``system.properties``，重启后仍会保留。 + ``oic.issuer`` 只能在 ``system.properties`` 中设置。 + +提供者配置 +---------- + +配置从OP获取的信息。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 属性 + - 描述 + - 默认值 + * - ``oic.auth.server.url`` + - 授权端点URL + - ``https://accounts.google.com/o/oauth2/auth`` + * - ``oic.token.server.url`` + - 令牌端点URL + - ``https://accounts.google.com/o/oauth2/token`` + * - ``oic.issuer`` + - 颁发者标识符（可选）。设置后，ID Token的 ``iss`` 声明必须与其完全一致（末尾的斜杠也会区分） + - (空字符串：不校验 ``iss``) + +.. note:: + 这些URL和颁发者可以从OP的Discovery端点（``/.well-known/openid-configuration``）获取，颁发者即其中的 ``issuer`` 值。 + 令牌端点URL（``oic.token.server.url``）必须为HTTPS。只有当主机是 ``localhost`` （不区分大小写）、形如 ``127.x.x.x`` 的IPv4地址或 ``::1`` 时，才允许使用 ``http``。主机按字面字符串比较，不会进行名称解析，因此Docker Compose的服务名（如 ``http://keycloak:8080/...``）或内部主机名即使指向同一台机器，使用 ``http`` 也会被拒绝。 + + 此检查只针对令牌端点，不针对授权端点（``oic.auth.server.url``）。检查在登录时进行，而不是在启动时。设置 ``oic.issuer`` 不会放宽这一规则，只是启用对 ``iss`` 声明的校验。 + +客户端配置 +---------- + +配置在OP侧注册的客户端信息。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 属性 + - 描述 + - 默认值 + * - ``oic.client.id`` + - 客户端ID + - (空字符串) + * - ``oic.client.secret`` + - 客户端密钥 + - (空字符串) + * - ``oic.scope`` + - 请求的范围 + - (空字符串) + +.. note:: + 范围必须至少包含 ``openid``\ 。 + 要获取用户的电子邮件地址，请指定 ``openid email``\ 。 + +重定向URL配置 +------------- + +配置认证后的回调URL。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 属性 + - 描述 + - 默认值 + * - ``oic.redirect.url`` + - 重定向URL（回调URL） + - ``{oic.base.url}/sso/`` + * - ``oic.base.url`` + - |Fess| 的基础URL + - ``http://localhost:8080`` + +.. note:: + 如果省略 ``oic.redirect.url``，它将从 ``oic.base.url`` 自动构建。 + 对于生产环境，请将 ``oic.base.url`` 设置为HTTPS的URL。 + +用户属性配置 +------------ + +配置分配给通过OIDC认证的用户的默认组和角色。 +用户ID、组和角色分别按如下方式确定： + +- **用户ID**：从ID Token（JWT）的 ``email`` 声明中获取。因此，范围中实际上必须包含 ``email``\ （如果无法获取 ``email`` 声明，登录将无法正常完成）。 +- **组**：从ID Token的 ``groups`` 声明中获取。如果 ``groups`` 声明不存在，则使用 ``oic.default.groups`` 的值。如果 ``groups`` 声明是空数组，则视为存在，因此不会使用 ``oic.default.groups``，该用户将被视为没有任何组。 +- **角色**：始终使用 ``oic.default.roles`` 的值（不存在从ID Token声明中获取角色的机制）。 + +.. note:: + |Fess| 直接使用 ``groups`` 声明中的值，不会查询目录，也不会展开嵌套组（父组）。 + 因此，是否包含父组完全取决于OP侧的声明配置。 + 这与通过Microsoft Graph API解析父组的 :doc:`sso-entraid` 不同。 + 声明的值会原样成为检索权限。如果OP侧配置为输出组的完整路径， + 则会发送 ``/父组/子组`` 这样的值并原样成为权限名称，与仅标记了组名的文档不匹配。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 属性 + - 描述 + - 默认值 + * - ``oic.default.groups`` + - 默认组（逗号分隔） + - (空字符串) + * - ``oic.default.roles`` + - 默认角色（逗号分隔） + - (空字符串) + +.. note:: + 使用基于角色的搜索时，需要为用户分配适当的组或角色。 + 详情请参阅 :doc:`security-role`。 + +OP侧配置 +======== + +在OP侧将 |Fess| 注册为客户端（RP）时，请配置以下信息： + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 设置项目 + - 设置值 + * - 应用程序类型 + - Web应用程序 + * - 重定向URI / 回调URL + - ``https:///sso/`` + * - 允许的范围 + - ``openid`` 以及所需的范围（``email``、``profile`` 等） + +从OP获取的信息 +-------------- + +从OP的配置界面或Discovery端点获取以下信息，用于 |Fess| 的配置： + +- **授权端点（Authorization Endpoint）**：启动用户认证的URL +- **令牌端点（Token Endpoint）**：获取令牌的URL +- **颁发者（Issuer）**：可选。Discovery文档中的 ``issuer`` 值，用于 ``oic.issuer`` +- **客户端ID**：OP颁发的客户端标识符 +- **客户端密钥**：用于客户端认证的密钥 + +.. note:: + 大多数OP允许您从Discovery端点（``https:///.well-known/openid-configuration``） + 确认授权端点和令牌端点的URL。 + +配置示例 +======== + +最小配置（用于验证环境） +------------------------ + +以下是在验证环境中进行功能确认的最小配置示例。 + +:: + + # 启用SSO + sso.type=oic + + # 提供者配置（设置从OP获取的值） + oic.auth.server.url=https://op.example.com/authorize + oic.token.server.url=https://op.example.com/token + + # 客户端配置 + oic.client.id=your-client-id + oic.client.secret=your-client-secret + oic.scope=openid email + + # 重定向URL（验证环境） + oic.redirect.url=http://localhost:8080/sso/ + +推荐配置（用于生产环境） +------------------------ + +以下是在生产环境中使用的推荐配置示例。 + +:: + + # 启用SSO + sso.type=oic + + # 提供者配置 + oic.auth.server.url=https://op.example.com/authorize + oic.token.server.url=https://op.example.com/token + + # 颁发者（Discovery文档中的"issuer"值） + oic.issuer=https://op.example.com + + # 客户端配置 + oic.client.id=your-client-id + oic.client.secret=your-client-secret + oic.scope=openid email profile + + # 基础URL（生产环境使用HTTPS） + oic.base.url=https://fess.example.com + +故障排除 +======== + +常见问题和解决方案 +------------------ + +认证后无法返回 |Fess| +~~~~~~~~~~~~~~~~~~~~~ + +- 请确认OP侧的重定向URI是否正确配置 +- 请确认 ``oic.redirect.url`` 或 ``oic.base.url`` 的值是否与OP侧的配置一致 +- 请确认协议（HTTP/HTTPS）是否一致 + +发生认证错误 +~~~~~~~~~~~~ + +- 请确认客户端ID和客户端密钥是否正确配置 +- 请确认范围中是否包含 ``openid`` +- 请确认授权端点URL和令牌端点URL是否正确 +- 如果登录失败，``fess.log`` 中会记录以 ``Failed to process the OpenID Connect callback:`` 开头的警告，后面跟着原因 +- ``The ID token was not issued for this client``：ID Token的 ``aud`` 不是 ``oic.client.id``，请确认客户端ID +- ``The ID token has expired``：|Fess| 主机与OP的时钟相差超过300秒，请同步时间（NTP） +- ``The ID token was not issued by the configured issuer``：``oic.issuer`` 与消息中显示的 ``iss`` 不同，请原样复制Discovery文档中的 ``issuer`` 值 +- ``oic.token.server.url must be https``：请使用HTTPS的令牌端点URL（只有 ``localhost``、``127.x.x.x`` 和 ``::1`` 可以使用 ``http``；指向Docker Compose服务名或内部主机名的 ``http`` 也会被拒绝） + +无法获取用户信息 +~~~~~~~~~~~~~~~~ + +- 请确认范围中是否包含所需的权限（``email``、``profile`` 等） +- 请确认OP侧是否为客户端允许了所需的范围 +- 使用Microsoft Entra ID时，除非选择了其他源属性，否则\ ``groups``\ 声明的值为组的\ ``ObjectId``\ （GUID），与组名不一致 +- 当用户所属的组超过200个时，Microsoft Entra ID将完全省略\ ``groups``\ 声明（嵌套组也计入此上限）， + 此时 |Fess| 将回退到\ ``oic.default.groups`` + +调试设置 +-------- + +要调查问题，可以通过调整 |Fess| 的日志级别来输出OpenID Connect相关的详细日志。 + +在 ``app/WEB-INF/classes/log4j2.xml`` 中，可以添加以下日志记录器来更改日志级别： + +:: + + + +.. warning:: + 将该日志记录器设置为DEBUG后，ID Token的声明（如 ``email`` 和 ``groups``）会被写入日志文件。 + 调查结束后请将日志级别恢复原状，并谨慎处理输出的日志。 + +参考信息 +======== + +- :doc:`security-role` - 基于角色的搜索配置 +- :doc:`sso-saml` - 使用SAML认证进行SSO配置 +- :doc:`sso-entraid` - Microsoft Entra ID专用的SSO配置（使用Entra ID时，也可以使用专用配置代替通用的OpenID Connect配置） diff --git a/zh-cn/15.10/config/sso-saml.rst b/zh-cn/15.10/config/sso-saml.rst new file mode 100644 index 000000000..c2e1f93f6 --- /dev/null +++ b/zh-cn/15.10/config/sso-saml.rst @@ -0,0 +1,628 @@ +==================== +SAML认证SSO配置 +==================== + +概述 +==== + +|Fess| 支持使用SAML（安全断言标记语言）2.0进行单点登录（SSO）认证。 +通过使用SAML认证，由IdP（身份提供者）认证的用户信息可以与\ |Fess|\ 集成，结合基于角色的搜索功能，可以根据用户权限显示不同的搜索结果。 + +.. note:: + SAML认证的支持由 ``fess-sso-saml`` 插件提供，该插件不随发行包分发。请从管理界面的 + 「系统 > 插件」页面安装，或执行 ``bin/fess-setup install plugin fess-sso-saml`` 。 + 在安装之前，即使设置 ``sso.type=saml``\ ，对 ``/sso/`` 的请求也只会重定向回登录页面。 + +SAML认证的工作原理 +------------------ + +在SAML认证中，|Fess|\ 作为SP（服务提供者）运行，并与外部IdP协作进行认证。 + +1. 用户访问\ |Fess|\ 的SSO端点（``/sso/``） +2. |Fess|\ 将认证请求重定向到IdP +3. 用户在IdP进行认证 +4. IdP将SAML断言发送给\ |Fess| +5. |Fess|\ 验证断言并登录用户 + +.. note:: + 仅支持如上所述从\ |Fess|\ 的SSO端点（``/sso/``）发起的SP发起（SP-Initiated）登录。 + |Fess|\ 会将每个SAML响应与自身发出的AuthnRequest的ID进行绑定校验， + 因此从IdP门户（如Okta仪表板或Microsoft Entra ID的"我的应用"）上的磁贴发起的 + IdP发起（IdP-Initiated，即未经请求的unsolicited）SSO没有可匹配的AuthnRequest，会被拒绝。 + 如果要在IdP侧放置磁贴，请将其链接指向\ |Fess|\ 的\ ``/sso/``\ 端点。 + + 请注意，在15.7中，若设置了\ ``tomcat.sameSiteCookies=none``\ ，IdP发起的登录会碰巧可用： + |Fess|\ 会将无法匹配的响应退回给IdP，而IdP会立即返回一个经过请求的断言。 + 15.10不再执行这种退回，因此IdP发起的登录无法使用。 + +有关基于角色的搜索集成，请参阅:doc:`security-role`。 + +前提条件 +======== + +在配置SAML认证之前，请验证以下前提条件： + +- 已安装\ |Fess| 15.10或更高版本 +- 有可用的SAML 2.0兼容IdP（身份提供者） +- |Fess|\ 可通过HTTPS访问（生产环境必需） +- 您有权在IdP侧将\ |Fess|\ 注册为SP + +支持的IdP示例： + +- Microsoft Entra ID（Azure AD） +- Okta +- Google Workspace +- Keycloak +- OneLogin +- 其他SAML 2.0兼容IdP + +基本配置 +======== + +启用SSO +------- + +要启用SAML认证，请在\ ``app/WEB-INF/conf/system.properties``\ 中添加以下设置： + +:: + + sso.type=saml + +.. note:: + ``sso.type`` 及基本SAML设置（IdP信息、SP信息、用户属性映射）也可以从管理界面的"系统 > 全局"页面进行配置和更改。 + 在管理界面中更改的设置将保存到 ``system.properties`` 中，重启后也会保留。 + 但是，签名/加密等安全设置以及SP证书/私钥无法在管理界面中配置，因此请直接写入 ``system.properties``\ 。 + +.. note:: + 以\ ``saml.``\ 开头的设置仅从\ ``system.properties``\ 中读取。 + 通过JVM系统属性（如\ ``-Dsaml.security....``\ 或\ ``-Dfess.saml.security....``\ ）指定不会被读取。 + 特别是\ ``saml.security.*``\ 、\ ``saml.strict``\ 和\ ``saml.debug``\ 在管理界面中也没有对应项， + 因此只能直接写入\ ``system.properties``\ 。 + +会话Cookie配置 +-------------- + +IdP 通过 **跨站 POST** 将断言返回给 |Fess| 。``SameSite=Lax`` 的 Cookie 不会随此类请求发送，因此使用 |Fess| 附带的默认值时，SAML 登录无法完成。 + +请将 ``tomcat_config.properties`` 中的 ``tomcat.sameSiteCookies`` 改为 ``none`` 。该文件在 ZIP 软件包中位于 ``lib/classes/`` ，在 DEB/RPM 软件包中位于 ``/etc/fess/`` 。 + +:: + + tomcat.sameSiteCookies = none + +.. warning:: + 浏览器仅对同时带有 ``Secure`` 属性的 Cookie 接受 ``none`` ，因此 |Fess| 必须通过 HTTPS 提供服务。在普通 HTTP 下，此设置会导致无法登录 |Fess| 。 + +.. note:: + 默认值 ``lax`` 是为回调以重定向（GET）返回的 SSO 方式设定的。SAML 的 HTTP-POST 绑定不属于此类，因此仅在使用 SAML 时才需要修改。修改设置后需要重启 |Fess| 。 + +SP（服务提供者）配置 +-------------------- + +要将\ |Fess|\ 配置为SP，请指定SP基础URL。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 属性 + - 描述 + - 默认值 + * - ``saml.sp.base.url`` + - SP基础URL + - ``http://localhost:8080`` + +.. note:: + ``saml.sp.base.url`` 的默认值为 ``http://localhost:8080``\ 。 + 在测试环境以外，请务必设置从外部访问 |Fess| 时使用的URL（生产环境中使用HTTPS）。 + +此设置会自动配置以下端点： + +- **Entity ID**：``{saml.sp.base.url}/sso/metadata`` +- **ACS URL**：``{saml.sp.base.url}/sso/`` +- **SLO URL**：``{saml.sp.base.url}/sso/logout`` + +示例:: + + saml.sp.base.url=https://fess.example.com + +单独URL配置 +~~~~~~~~~~~ + +通常情况下，设置 ``saml.sp.base.url`` 即可自动配置各端点URL，但如有需要，也可以使用以下属性明确指定各URL并进行覆盖。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 属性 + - 描述 + - 默认值 + * - ``saml.sp.entityid`` + - SP Entity ID + - ``{saml.sp.base.url}/sso/metadata`` + * - ``saml.sp.assertion_consumer_service.url`` + - 断言消费者服务URL + - ``{saml.sp.base.url}/sso/`` + * - ``saml.sp.single_logout_service.url`` + - 单点登出服务URL + - ``{saml.sp.base.url}/sso/logout`` + +IdP（身份提供者）配置 +--------------------- + +配置从您的IdP获取的信息。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 属性 + - 描述 + - 默认值 + * - ``saml.idp.entityid`` + - IdP Entity ID + - （必需） + * - ``saml.idp.single_sign_on_service.url`` + - IdP SSO服务URL + - （必需） + * - ``saml.idp.x509cert`` + - IdP签名X.509证书（Base64编码，无换行） + - （必需） + * - ``saml.idp.single_logout_service.url`` + - IdP SLO服务URL + - （可选） + +.. note:: + 对于\ ``saml.idp.x509cert``，仅指定证书的Base64编码内容，单行无换行。 + 不要包含\ ``-----BEGIN CERTIFICATE-----``\ 和\ ``-----END CERTIFICATE-----``\ 行。 + +获取SP元数据 +------------ + +启动\ |Fess|\ 后，您可以从\ ``/sso/metadata``\ 端点获取XML格式的SP元数据。 + +:: + + https://fess.example.com/sso/metadata + +将此元数据导入到您的IdP，或使用元数据内容在IdP侧手动注册SP。 + +.. note:: + 要获取元数据，您必须先完成基本SAML配置（``sso.type=saml``\ 和\ ``saml.sp.base.url``）并启动\ |Fess|\ 。 + +IdP侧配置 +========= + +在IdP侧将\ |Fess|\ 注册为SP时，配置以下信息： + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 设置 + - 值 + * - ACS URL / Reply URL + - ``https:///sso/`` + * - Entity ID / Audience URI + - ``https:///sso/metadata`` + * - Name ID Format + - ``urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress``\ （推荐） + +从IdP获取的信息 +--------------- + +从您的IdP配置界面或元数据获取以下信息，用于\ |Fess|\ 配置： + +- **IdP Entity ID**：标识IdP的URI +- **SSO URL（HTTP-Redirect）**：单点登录端点URL +- **X.509证书**：用于SAML断言签名验证的公钥证书 + +用户属性映射 +============ + +您可以将从SAML断言获取的用户属性映射到\ |Fess|\ 的组和角色。 + +组属性配置 +---------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 属性 + - 描述 + - 默认值 + * - ``saml.attribute.group.name`` + - 包含组信息的属性名 + - ``memberOf`` + * - ``saml.default.groups`` + - 默认组（逗号分隔） + - （无） + +示例:: + + saml.attribute.group.name=groups + saml.default.groups=user + +.. note:: + |Fess| 直接使用断言中的组值，不会查询目录，也不会展开嵌套组（父组）。 + 因此，是否包含父组完全取决于IdP侧的声明配置。 + 这与通过Microsoft Graph API解析父组的 :doc:`sso-entraid` 不同。 + +角色属性配置 +------------ + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 属性 + - 描述 + - 默认值 + * - ``saml.attribute.role.name`` + - 包含角色信息的属性名 + - （无） + * - ``saml.default.roles`` + - 默认角色（逗号分隔） + - （无） + +示例:: + + saml.attribute.role.name=roles + saml.default.roles=viewer + +.. note:: + 如果无法从IdP获取属性，将使用默认值。 + 使用基于角色的搜索时，请配置适当的组或角色。 + +.. warning:: + 设置\ ``saml.attribute.role.name``\ 后，IdP发送的属性值将直接成为 |Fess| 的角色。 + 由于\ ``fess_config.properties``\ 中\ ``authentication.admin.roles``\ 的默认值为\ ``admin``\ ， + 角色属性中包含\ ``admin``\ 的用户将获得 |Fess| 的管理员权限。 + 请确认IdP侧可以控制角色属性的范围，必要时将\ ``authentication.admin.roles``\ 更改为其他名称。 + +属性名重复的 IdP +---------------- + +如果 IdP 将同一个属性名拆分到多个 ```` 元素中发送，|Fess|\ 会拒绝该断言，登录本身 +随之失败。 + +Keycloak 默认发送这种形式的断言：除非启用其角色映射器和组映射器的 ``single`` 选项，否则每个值 +都会输出为独立的 ```` 元素，而每个 Keycloak 账户默认都带有多个领域角色。 + +有以下两种处理方式： + +- 在 IdP 侧将属性合并为单个元素（在 Keycloak 中启用映射器的 ``single`` 选项） +- 在 |Fess|\ 侧允许重复并合并其值 + +.. list-table:: + :header-rows: 1 + :widths: 45 40 15 + + * - 属性 + - 描述 + - 默认值 + * - ``saml.security.allow_duplicated_attribute_name`` + - 允许同一属性名出现在多个元素中并合并其值 + - ``false`` + +示例:: + + saml.security.allow_duplicated_attribute_name=true + +安全配置 +======== + +对于生产环境，建议启用以下安全设置。 + +.. note:: + 如果保留了不推荐的设置，在加载SAML设置时会向日志输出\ ``Insecure SAML settings: ...``\ 警告。 + +签名设置 +-------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 属性 + - 描述 + - 默认值 + * - ``saml.security.authnrequest_signed`` + - 对认证请求签名 + - ``false`` + * - ``saml.security.want_messages_signed`` + - 要求消息签名 + - ``false`` + * - ``saml.security.want_assertions_signed`` + - 要求断言签名 + - ``false`` + * - ``saml.security.logoutrequest_signed`` + - 对登出请求签名 + - ``false`` + * - ``saml.security.logoutresponse_signed`` + - 对登出响应签名 + - ``false`` + * - ``saml.security.reject_deprecated_alg`` + - 拒绝SHA-1等已弃用的签名算法 + - ``false`` + +.. warning:: + 安全功能默认是禁用的。 + 对于生产环境，强烈建议至少设置\ ``saml.security.want_assertions_signed=true``\ 。 + +.. note:: + 当\ ``saml.security.reject_deprecated_alg``\ 为\ ``false``\ 时，使用SHA-1（``rsa-sha1``\ 和\ ``dsa-sha1``\ ） + 签名的断言和消息同样会被接受。之所以默认不启用，是因为启用后会拒绝仍使用SHA-1签名的IdP。 + 请先确认IdP使用SHA-256或更强的算法签名，然后再设置\ ``saml.security.reject_deprecated_alg=true``\ 。 + +.. warning:: + 配置单点登出（``saml.idp.single_logout_service.url``）时，请务必同时设置\ + ``saml.security.want_messages_signed=true``\ 。 + 若保持为\ ``false``\ ，则会接受未签名的LogoutRequest，攻击者可诱导用户访问构造的URL，从而终止其已认证会话。 + 其影响是强制登出（拒绝服务），而不是账户接管。 + +加密设置 +-------- + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 属性 + - 描述 + - 默认值 + * - ``saml.security.want_assertions_encrypted`` + - 要求断言加密 + - ``false`` + * - ``saml.security.want_nameid_encrypted`` + - 要求NameID加密 + - ``false`` + * - ``saml.security.allowed_key_transport_algorithms`` + - 解密断言时接受的密钥传输算法（以逗号分隔的 URI） + - （空：接受所有算法） + +.. note:: + |Fess| 可以验证使用 XML Encryption 1.1 加密的响应。例如当前的 Keycloak 使用 + ``http://www.w3.org/2009/xmlenc11#rsa-oaep`` 并在响应中包含 ```` 元素， + 在启用架构验证的情况下也能接受此类响应。早期版本会以 + ``Invalid SAML Response. Not match the saml-schema-protocol-2.0.xsd`` 拒绝。 + 如果为此设置过 ``saml.security.want_xml_validation=false``，请将其删除。 + +.. note:: + 配置 SP 私钥时，请同时设置 ``saml.security.allowed_key_transport_algorithms``。 + 未设置时会接受所有密钥传输算法，包括旧的 ``http://www.w3.org/2001/04/xmlenc#rsa-1_5``。 + 断言消费端点无需认证，且解密在响应验证之前执行，因此未经认证的调用方可以让 SP 私钥 + 解密其选择的密文。处于这种状态时，|Fess| 会在启动时的 ``Insecure SAML settings`` + 一行中输出 ``key_transport_algorithms_not_restricted``。请将其限制为 IdP 实际使用的算法:: + + saml.security.allowed_key_transport_algorithms=http://www.w3.org/2009/xmlenc11#rsa-oaep + +SP证书与私钥配置 +---------------- + +当SP对认证请求或登出消息进行签名时（例如 ``saml.security.authnrequest_signed``），或请求对断言或NameID进行加密时（例如 ``saml.security.want_assertions_encrypted``），需要配置SP的私钥和X.509证书。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 属性 + - 描述 + - 默认值 + * - ``saml.sp.x509cert`` + - SP的X.509证书（Base64编码，无换行） + - （空） + * - ``saml.sp.privatekey`` + - SP的私钥（Base64编码，无换行） + - （空） + +.. note:: + 对于 ``saml.sp.x509cert`` 和 ``saml.sp.privatekey``，与 ``saml.idp.x509cert`` 相同，请将Base64编码的内容以单行无换行的形式指定（不包含 ``-----BEGIN ...-----`` 和 ``-----END ...-----`` 行）。 + 启用签名/加密时，还需要在IdP侧注册SP证书。SP证书将包含在 ``/sso/metadata`` 的SP元数据中进行公开。 + +其他安全设置 +------------ + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 属性 + - 描述 + - 默认值 + * - ``saml.strict`` + - 严格模式（执行严格验证） + - ``true`` + * - ``saml.security.want_xml_validation`` + - 验证消息的XML模式 + - ``true`` + * - ``saml.security.signature_algorithm`` + - 签名算法 + - ``http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`` + * - ``saml.security.requested_authncontext`` + - 请求的认证上下文 + - ``urn:oasis:names:tc:SAML:2.0:ac:classes:Password`` + * - ``saml.sp.nameidformat`` + - NameID格式 + - ``urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`` + +.. note:: + |Fess| 内部使用SAML库（java-saml），以 ``saml.`` 开头的属性将映射到该库对应的设置（``onelogin.saml2.`` 前缀）。 + 因此，除此处列出的设置外，还可以在 ``system.properties`` 中指定绑定（例如 ``saml.sp.assertion_consumer_service.binding``）、组织信息（``saml.organization.*``）、联系人信息（``saml.contacts.*``）等详细设置。 + +AuthnRequest有效期 +================== + +|Fess|\ 每次访问\ ``/sso/``\ 都会向IdP发送一个AuthnRequest，并将其ID记录在会话中。 +IdP返回的SAML响应会根据记录的ID进行校验。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 属性 + - 描述 + - 默认值 + * - ``saml.request.id.ttl`` + - 未收到响应的AuthnRequest的ID保留时长（秒） + - ``3600`` + +记录的ID在超过该时长后会被丢弃。 +如果超出有效期（例如IdP登录页面一直处于打开状态未处理），返回的断言将无法匹配，登录会当场失败一次。 + +配置示例 +======== + +最小配置（用于测试） +-------------------- + +以下是在测试环境中进行验证的最小配置示例。 + +:: + + # 启用SSO + sso.type=saml + + # SP配置 + saml.sp.base.url=https://fess.example.com + + # IdP配置（设置从IdP管理控制台获取的值） + saml.idp.entityid=https://idp.example.com/saml/metadata + saml.idp.single_sign_on_service.url=https://idp.example.com/saml/sso + saml.idp.x509cert=MIIDpDCCAoygAwIBAgI...（Base64编码的证书） + + # 默认组 + saml.default.groups=user + +推荐配置（用于生产） +-------------------- + +以下是生产环境的推荐配置示例。 + +:: + + # 启用SSO + sso.type=saml + + # SP配置 + saml.sp.base.url=https://fess.example.com + + # IdP配置 + saml.idp.entityid=https://idp.example.com/saml/metadata + saml.idp.single_sign_on_service.url=https://idp.example.com/saml/sso + saml.idp.single_logout_service.url=https://idp.example.com/saml/logout + saml.idp.x509cert=MIIDpDCCAoygAwIBAgI...（Base64编码的证书） + + # 用户属性映射 + saml.attribute.group.name=groups + saml.attribute.role.name=roles + saml.default.groups=user + + # 安全设置（生产环境推荐） + saml.security.want_assertions_signed=true + saml.security.want_messages_signed=true + + # 确认IdP使用SHA-256或更强的算法签名后再启用 + saml.security.reject_deprecated_alg=true + +故障排除 +======== + +常见问题和解决方案 +------------------ + +认证后无法返回Fess +~~~~~~~~~~~~~~~~~~ + +- 验证ACS URL是否在IdP侧正确配置 +- 确保\ ``saml.sp.base.url``\ 的值与IdP配置匹配 +- SAML断言以来自IdP的跨站POST方式发送。 + 当\ ``tomcat_config.properties``\ 中的\ ``tomcat.sameSiteCookies``\ 为\ ``lax``\ （默认值）时， + 浏览器不会随该请求发送会话Cookie，登录会当场只失败一次。 + 此时请设置\ ``tomcat.sameSiteCookies = none``\ （``SameSite=None``\ 需要HTTPS） +- 如果在IdP上的登录耗时过长，断言返回时AuthnRequest ID已经不存在，登录会当场只失败一次，需要重新开始登录 +- |Fess| 未在\ ``app/WEB-INF/web.xml``\ 中设置\ ``session-timeout``\ ，因此采用Servlet容器的默认值30分钟。 + 该值短于\ ``saml.request.id.ttl``\ 的3600秒，会话会先被丢弃， + 因此仅调大\ ``saml.request.id.ttl``\ 并不能延长用户在IdP完成登录的时间，还需要同时延长会话超时时间 + +通过反向代理时Destination验证失败 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +当\ |Fess|\ 运行在终结TLS的反向代理或负载均衡器之后时， +即使\ ``saml.sp.base.url``\ 设置正确，断言验证也可能失败。 + +断言的\ ``Destination``\ 属性会与请求到达\ |Fess|\ 时的URL进行比较。 +在终结TLS的代理之后，该URL是内部的\ ``http://``\ 地址，而不是IdP发送断言时使用的外部地址。 +``saml.sp.base.url``\ 不参与该比较，因此仅设置它无法解决问题。 + +设置\ ``saml.debug=true``\ 后，日志中会输出如下原因： + +:: + + The response was received at http://... instead of https://fess.example.com/sso/ + +此时请将\ ``tomcat_config.properties``\ 中的连接器设置调整为对外可见的协议和端口。 +以下设置默认处于注释状态： + +:: + + tomcat.secure=true + tomcat.scheme=https + tomcat.proxyPort=443 + +同时请配置反向代理，将原始的\ ``Host``\ 请求头透传给\ |Fess|\ ， +因为请求URL中的主机名部分是根据该请求头构建的。 +修改\ ``tomcat_config.properties``\ 后需要重启\ |Fess|\ 。 + +同样的验证也适用于单点登出消息，因此使用SLO时请一并配置。 + +签名验证错误 +~~~~~~~~~~~~ + +- 验证IdP证书是否正确配置 +- 确保证书未过期 +- 证书应仅指定为Base64编码的内容，无换行 + +因属性名重复而无法登录 +~~~~~~~~~~~~~~~~~~~~~~ + +- 如果日志中出现以 ``The IdP repeated an attribute name in the SAML assertion`` 开头的警告， + 说明 IdP 将同一个属性名拆分到了多个 ```` 元素中 +- 断言本身已通过校验，因此证书和时间偏差都不是原因 +- 请在 IdP 侧合并属性，或设置 ``saml.security.allow_duplicated_attribute_name=true`` + +用户组/角色未生效 +~~~~~~~~~~~~~~~~~ + +- 验证属性是否在IdP侧正确配置 +- 确保\ ``saml.attribute.group.name``\ 的值与IdP发送的属性名匹配 +- 使用Microsoft Entra ID时，除非选择了其他源属性，否则组声明的值为组的\ ``ObjectId``\ （GUID），与组名不一致 +- 当用户所属的组超过150个时，Microsoft Entra ID将完全省略组声明（嵌套组也计入此上限）， + 此时 |Fess| 将回退到\ ``saml.default.groups`` +- 启用调试模式以检查SAML断言内容 + +调试设置 +-------- + +要调查问题，您可以使用以下设置启用调试模式： + +:: + + saml.debug=true + +设置 ``saml.debug=true`` 后，当SAML认证失败时，详细原因将输出到日志中。 + +此外，通过在 ``app/WEB-INF/classes/log4j2.xml`` 中添加以下logger，可以输出详细的SAML相关日志： + +:: + + + +参考 +==== + +- :doc:`security-role` - 基于角色的搜索配置 +- :doc:`sso-oidc` - 关于使用OpenID Connect进行SSO配置 +- :doc:`sso-entraid` - 关于Microsoft Entra ID专用的SSO配置 diff --git a/zh-cn/15.10/config/sso-spnego.rst b/zh-cn/15.10/config/sso-spnego.rst new file mode 100644 index 000000000..62accfc8a --- /dev/null +++ b/zh-cn/15.10/config/sso-spnego.rst @@ -0,0 +1,480 @@ +================================= +Windows集成认证SSO配置 +================================= + +概述 +==== + +|Fess| 支持使用Windows集成认证（SPNEGO/Kerberos）进行单点登录（SSO）认证。 +通过使用Windows集成认证，登录到Windows域计算机的用户可以无需额外的登录操作即可访问 |Fess|\ 。 + +.. note:: + Windows集成认证的支持由 ``fess-sso-spnego`` 插件提供，该插件不随发行包分发。请从管理 + 界面的「系统 > 插件」页面安装，或执行 ``bin/fess-setup install plugin fess-sso-spnego`` 。 + 在安装之前，即使设置 ``sso.type=spnego``\ ，对 ``/sso/`` 的请求也只会重定向回登录页面。 + +Windows集成认证的工作原理 +------------------------- + +在Windows集成认证中，|Fess| 使用SPNEGO（简单和受保护的GSSAPI协商机制）协议进行Kerberos认证。 + +1. 用户登录到Windows域 +2. 用户访问 |Fess| +3. |Fess| 发送SPNEGO质询 +4. 浏览器获取Kerberos票证并发送到服务器 +5. |Fess| 验证票证并获取用户名 +6. 通过LDAP获取用户的组信息 +7. 用户登录，组信息应用于基于角色的搜索 + +有关基于角色的搜索集成，请参阅 :doc:`security-role`。 + +前提条件 +======== + +在配置Windows集成认证之前，请验证以下前提条件： + +- 已安装 |Fess| 15.10或更高版本 +- Active Directory（AD）服务器可用 +- |Fess| 服务器可从AD域访问 +- 您有权在AD中配置服务主体名称（SPN） +- 有用于通过LDAP获取用户信息的账户 + +Active Directory端配置 +====================== + +注册服务主体名称（SPN） +----------------------- + +您需要在Active Directory中为 |Fess| 注册SPN。 +在加入AD域的Windows计算机上打开命令提示符，运行 ``setspn`` 命令。 + +:: + + setspn -S HTTP/ + +示例： + +:: + + setspn -S HTTP/fess-server.example.local svc_fess + +验证注册： + +:: + + setspn -L + +.. note:: + 注册SPN后，如果在Fess服务器上执行了命令，请从Windows注销并重新登录。 + +基本配置 +======== + +启用SSO +------- + +要启用Windows集成认证，请在 ``app/WEB-INF/conf/system.properties`` 中添加以下设置： + +:: + + sso.type=spnego + +Kerberos配置文件 +---------------- + +创建 ``app/WEB-INF/classes/krb5.conf`` 并配置Kerberos设置。 + +:: + + [libdefaults] + default_realm = EXAMPLE.LOCAL + default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + + [realms] + EXAMPLE.LOCAL = { + kdc = AD-SERVER.EXAMPLE.LOCAL + default_domain = EXAMPLE.LOCAL + } + + [domain_realm] + example.local = EXAMPLE.LOCAL + .example.local = EXAMPLE.LOCAL + +.. note:: + 将 ``EXAMPLE.LOCAL`` 替换为您的AD域名（大写），将 ``AD-SERVER.EXAMPLE.LOCAL`` 替换为您的AD服务器主机名。 + +.. warning:: + 使用 ``permitted_enctypes`` 中未列出的加密方式加密的服务票据，会被 Kerberos 接收端以 + ``encryption type not in permitted_enctypes list`` 拒绝。 + Active Directory 通常签发 AES256 服务票据，因此必须包含 AES256。 + +.. note:: + Java 17 及以后版本默认禁用 RC4（ ``rc4-hmac`` ）、3DES 和 DES，即使列出也不会使用， + 因此上例仅指定 AES。 + ``aes256-cts-hmac-sha384-192`` 和 ``aes128-cts-hmac-sha256-128`` 是 Windows Server 2025 支持的 + AES-SHA2（RFC 8009）加密方式。 + 仅持有 RC4 密钥的服务账户无法用于 Kerberos 认证，请重置其密码以生成 AES 密钥。 + +登录配置文件 +------------ + +创建 ``app/WEB-INF/classes/auth_login.conf`` 并配置JAAS登录设置。 + +:: + + spnego-client { + com.sun.security.auth.module.Krb5LoginModule required; + }; + + spnego-server { + com.sun.security.auth.module.Krb5LoginModule required + storeKey=true + isInitiator=false; + }; + +.. note:: + ``krb5.conf`` 和 ``auth_login.conf`` 的默认文件名分别由 ``spnego.krb5.conf`` / ``spnego.login.conf`` 指定，但这两个文件本身必须事先创建好。 + SPNEGO 在首次登录时初始化，因此即使缺少这些文件 |Fess| 本身仍能启动，但 SSO 登录会失败。 + +必需设置 +-------- + +将以下设置添加到 ``app/WEB-INF/conf/system.properties``\ 。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 属性 + - 描述 + - 默认值 + * - ``spnego.preauth.username`` + - AD连接用户名 + - （不使用 keytab 时必需） + * - ``spnego.preauth.password`` + - AD连接密码 + - （不使用 keytab 时必需） + * - ``spnego.krb5.conf`` + - Kerberos配置文件路径 + - ``krb5.conf`` + * - ``spnego.login.conf`` + - 登录配置文件路径 + - ``auth_login.conf`` + +.. note:: + 如果 ``spnego.preauth.username`` 和 ``spnego.preauth.password`` 都留空，服务器端登录模块将使用 keytab。 + 如果不希望将 AD 服务账户的密码保存在 |Fess| 的配置文件中，请创建 keytab 并按如下方式配置 + ``auth_login.conf`` 中的 ``spnego-server`` 。 + + :: + + spnego-server { + com.sun.security.auth.module.Krb5LoginModule required + useKeyTab=true + keyTab="/var/lib/fess/fess.keytab" + principal="HTTP/fess-server.example.local@EXAMPLE.LOCAL" + storeKey=true + isInitiator=false; + }; + +可选设置 +-------- + +可根据需要添加以下设置。 + +.. list-table:: + :header-rows: 1 + :widths: 35 45 20 + + * - 属性 + - 描述 + - 默认值 + * - ``spnego.login.client.module`` + - 客户端模块名称 + - ``spnego-client`` + * - ``spnego.login.server.module`` + - 服务器模块名称 + - ``spnego-server`` + * - ``spnego.allow.basic`` + - 允许Basic认证 + - ``true`` + * - ``spnego.allow.unsecure.basic`` + - 允许非安全Basic认证 + - ``false`` + * - ``spnego.prompt.ntlm`` + - 收到NTLM令牌时回退到Basic认证 + - ``true`` + * - ``spnego.allow.localhost`` + - 允许localhost访问 + - ``false`` + * - ``spnego.allow.delegation`` + - 允许委托 + - ``false`` + * - ``spnego.allowed.realms`` + - 除服务器领域外还允许的 Kerberos 领域（逗号分隔） + - （无） + * - ``spnego.logger.level`` + - SPNEGO库内部日志级别（``1`` =FINEST、``2`` =FINER、``3`` =FINE、``4`` =CONFIG、``6`` =WARNING、``7`` =SEVERE。这些值以外的值（包括 ``0`` 和 ``5``）均视为INFO） + - （自动） + +.. warning:: + ``spnego.allow.unsecure.basic=true`` 可能通过未加密的连接发送Base64编码的凭据。 + 对于生产环境，强烈建议将此设置为 ``false`` 并使用HTTPS。 + +.. note:: + 当 ``spnego.allow.unsecure.basic=false`` （默认值）时，仅对 ``HttpServletRequest#isSecure()`` + 返回 ``true`` 的请求提供 Basic 认证。 + 如果在反向代理上终止 TLS 并以 HTTP 转发到 |Fess| ，该值为 ``false`` ， + 因此无法获取 Kerberos 票据而回退到 NTLM 的客户端将无法登录。 + 请在 ``tomcat_config.properties`` 中设置 ``tomcat.secure=true`` ，以告知 |Fess| 该请求来自 HTTPS。 + 该文件在 ZIP 版中位于 ``lib/classes/`` ，在 DEB/RPM 版中位于 ``/etc/fess/`` ，修改后需要重启 |Fess| 。 + +.. warning:: + 在 |Fess| 15.10 中，如果客户端主体的领域与服务器的领域不同，登录将默认被拒绝。 + 如果用户来自 AD 域树的子域或建立了信任关系的林， + 请在 ``spnego.allowed.realms`` 中以逗号分隔列出这些领域。 + 否则，在 15.7 之前能够登录的用户将因 ``Kerberos realm is not allowed`` 而被拒绝。 + +.. warning:: + |Fess| 以主体中 ``@`` 之前的部分作为用户名，因此用户名中不包含领域。 + 在 ``spnego.allowed.realms`` 中添加领域后，在多个领域中拥有相同账户名的用户 + （例如 ``alice@CORP.EXAMPLE.COM`` 与 ``alice@PARTNER.EXAMPLE.COM`` ）将被视为同一个 + |Fess| 用户，并共享该用户的组、角色和文档权限。 + 仅当账户名在所列出的所有领域中都能唯一标识一个人时，才添加该领域。 + +.. note:: + 允许列表同样适用于 Basic 认证的回退。如果用户输入 ``user@REALM`` 形式的名称， + 该领域将与 ``spnego.allowed.realms`` 进行比对，未被允许时将拒绝登录。 + 单纯的账户名或 ``DOMAIN\user`` 形式不指定领域，因此在 ``krb5.conf`` 的默认领域中进行认证。 + 由于 Basic 认证直接针对用户输入的领域进行认证，请将允许列表控制在最小范围； + 若将其作为安全边界使用，请考虑将 ``spnego.allow.basic`` 设为 ``false``\ 。 + +.. note:: + ``spnego.prompt.ntlm=true``\ （默认值）时，``spnego.allow.basic`` 也必须为 ``true``\ 。 + 若要将 ``spnego.allow.basic`` 设为 ``false``，则必须同时将 ``spnego.prompt.ntlm`` 设为 ``false``\ 。 + 不满足此条件时，SPNEGO初始化时将发生错误。 + +.. note:: + ``spnego.logger.level`` 控制SPNEGO库内部日志记录器（``java.util.logging`` 中名为 ``Spnego`` 的日志记录器）的日志级别。 + 未设置时，将根据 |Fess| 的日志级别自动确定。 + +LDAP配置 +======== + +需要LDAP配置来获取通过Windows集成认证进行身份验证的用户的组信息。 +在 |Fess| 管理面板的"系统"→"常规"中配置LDAP设置。 + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 项目 + - 示例 + * - LDAP URL + - ``ldap://AD-SERVER.example.local:389`` + * - Base DN + - ``dc=example,dc=local`` + * - Bind DN + - ``svc_fess@example.local`` + * - 密码 + - AD访问用户的密码 + * - User DN + - ``%s@example.local`` + * - 账户过滤器 + - ``(&(objectClass=user)(sAMAccountName=%s))`` + * - memberOf属性 + - ``memberOf`` + +.. note:: + |Fess| 只读取用户 ``memberOf`` 属性的一层，因此默认不会展开嵌套组（作为其他组成员的组）。 + 若要反映 AD 的嵌套组，请在管理界面「系统」→「常规」的「组过滤器」( ``ldap.group.filter`` ) + 中设置 ``(member:1.2.840.113556.1.4.1941:=%s)`` 。该展开在登录后异步执行， + 因此审计日志的登录记录中只包含展开前的组。 + +浏览器设置 +========== + +使用Windows集成认证需要客户端浏览器设置。 + +Internet Explorer / Microsoft Edge +---------------------------------- + +1. 打开Internet选项 +2. 选择"安全"选项卡 +3. 点击"本地Intranet"区域的"站点" +4. 点击"高级"并添加Fess的URL +5. 点击"本地Intranet"区域的"自定义级别" +6. 在"用户身份验证"→"登录"下，选择"仅在Intranet区域自动登录" +7. 在"高级"选项卡中，勾选"启用集成Windows身份验证" + +Google Chrome +------------- + +Chrome通常使用Windows Internet选项设置。 +如果需要额外配置，通过组策略或注册表设置 ``AuthServerAllowlist``\ 。 + +Mozilla Firefox +--------------- + +1. 在地址栏中输入 ``about:config`` +2. 搜索 ``network.negotiate-auth.trusted-uris`` +3. 设置Fess服务器URL或域（例如：``https://fess-server.example.local``） + +配置示例 +======== + +最小配置（用于测试） +-------------------- + +以下是测试环境中的最小配置示例。 + +``app/WEB-INF/conf/system.properties``: + +:: + + # 启用SSO + sso.type=spnego + + # SPNEGO设置 + spnego.preauth.username=svc_fess + spnego.preauth.password=your-password + +``app/WEB-INF/classes/krb5.conf``: + +:: + + [libdefaults] + default_realm = EXAMPLE.LOCAL + default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 + + [realms] + EXAMPLE.LOCAL = { + kdc = AD-SERVER.EXAMPLE.LOCAL + default_domain = EXAMPLE.LOCAL + } + + [domain_realm] + example.local = EXAMPLE.LOCAL + .example.local = EXAMPLE.LOCAL + +``app/WEB-INF/classes/auth_login.conf``: + +:: + + spnego-client { + com.sun.security.auth.module.Krb5LoginModule required; + }; + + spnego-server { + com.sun.security.auth.module.Krb5LoginModule required + storeKey=true + isInitiator=false; + }; + +推荐配置（用于生产） +-------------------- + +以下是生产环境的推荐配置示例。 + +``app/WEB-INF/conf/system.properties``: + +:: + + # 启用SSO + sso.type=spnego + + # SPNEGO设置 + spnego.preauth.username=svc_fess + spnego.preauth.password=your-secure-password + spnego.krb5.conf=krb5.conf + spnego.login.conf=auth_login.conf + + # 安全设置（生产环境） + spnego.allow.basic=false + spnego.allow.unsecure.basic=false + spnego.prompt.ntlm=false + spnego.allow.localhost=false + +.. note:: + 设置 ``spnego.allow.basic=false`` 时，必须同时设置 ``spnego.prompt.ntlm=false``\ 。 + 由于 ``spnego.prompt.ntlm`` 默认为 ``true``，省略此设置将导致初始化时发生错误。 + +故障排除 +======== + +常见问题和解决方案 +------------------ + +出现认证对话框 +~~~~~~~~~~~~~~ + +- 验证Fess服务器是否已添加到浏览器设置中的本地Intranet区域 +- 检查"启用集成Windows身份验证"是否已启用 +- 验证SPN是否正确注册（ ``setspn -L <用户名>`` ） + +发生认证错误 +~~~~~~~~~~~~ + +- 验证 ``krb5.conf`` 中的域名（大写）和AD服务器名称是否正确 +- 检查 ``spnego.preauth.username`` 和 ``spnego.preauth.password`` 是否正确 +- 验证与AD服务器的网络连接 + +无法获取组信息 +~~~~~~~~~~~~~~ + +- 验证LDAP设置是否正确 +- 检查Bind DN和密码是否正确 +- 验证用户是否在AD中属于组 + +登录返回 HTTP 400 +~~~~~~~~~~~~~~~~~ + +对于所属组较多的用户，Kerberos 票据（PAC）会变大， ``Authorization`` 请求头可能超过 Tomcat 的 +默认上限（8KB），从而返回 400。 +此时请求不会到达 |Fess| ，日志中也不会有任何记录。 +请在 ``tomcat_config.properties`` 中提高上限。 + +:: + + tomcat.maxHttpHeaderSize=65536 + +更改服务账户密码后无法认证 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +服务器凭据仅在首次登录时获取一次，之后会缓存到进程结束为止。 +在 AD 中更改服务账户密码或替换 keytab 后，请重启 |Fess| 。 +更改 ``spnego.*`` 设置后同样需要重启。 + +调试设置 +-------- + +要调查问题，可以输出SPNEGO相关的详细日志。 + +要输出SPNEGO库内部的详细日志，请在 ``app/WEB-INF/conf/system.properties`` 中添加以下内容。 +``spnego.logger.level=1`` 将输出最详细的日志（FINEST）。 + +:: + + spnego.logger.level=1 + +要输出 |Fess| 侧SPNEGO联动处理（``org.codelibs.fess.sso.spnego`` 包）的详细日志，请在 ``app/WEB-INF/classes/log4j2.xml`` 中添加以下日志记录器。 + +:: + + + +.. note:: + SPNEGO库本身的日志通过 ``java.util.logging`` 输出，因此通过 ``spnego.logger.level`` 而非 ``log4j2.xml`` 进行控制。 + |Fess| 侧联动处理的日志通过 ``log4j2.xml`` 中的日志记录器进行控制。 + +参考信息 +======== + +- :doc:`security-role` - 基于角色的搜索配置 +- :doc:`sso-saml` - SAML认证SSO配置 +- :doc:`sso-oidc` - OpenID Connect认证SSO配置 +- :doc:`sso-entraid` - Microsoft Entra ID SSO配置 diff --git a/zh-cn/15.10/dev/datastore-plugin.rst b/zh-cn/15.10/dev/datastore-plugin.rst new file mode 100644 index 000000000..bd65ed9b2 --- /dev/null +++ b/zh-cn/15.10/dev/datastore-plugin.rst @@ -0,0 +1,517 @@ +================================== +数据存储插件开发 +================================== + +概述 +==== + +通过开发数据存储插件，可以为 |Fess| 添加从新数据源获取内容的功能。数据存储会从数据库、 +API、文件等外部系统中获取记录，并按照在管理界面中设置的映射脚本，将其转换为索引字段后， +注册到 |Fess| 的索引中。 + +CSV、JSON、数据库、Git、各类云服务等公开的连接器（``fess-ds-*``）都是基于这一机制实现 +的。作为实现模板，官方公开了 +`fess-ds-example `__ ，创建新连接器时， +复制该模板作为起点会比较简单。 + +基本结构 +======== + +数据存储插件由以下三个要素构成： + +- 创建继承 ``AbstractDataStore`` 的类 +- 实现 ``getName()`` 和 ``storeData()`` 两个方法 +- 在 ``fess_ds++.xml`` 中注册为组件 + +最小实现 +-------- + +.. code-block:: java + + package org.codelibs.fess.ds.example; + + import java.util.Map; + + import org.codelibs.fess.ds.AbstractDataStore; + import org.codelibs.fess.ds.callback.IndexUpdateCallback; + import org.codelibs.fess.entity.DataStoreParams; + import org.codelibs.fess.opensearch.config.exentity.DataConfig; + + public class ExampleDataStore extends AbstractDataStore { + + @Override + protected String getName() { + // 用作处理器名。按照惯例返回类的简单名称 + return this.getClass().getSimpleName(); + } + + @Override + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { + + // 在此实现数据的获取与处理 + } + } + +.. note:: + + ``getName()`` 和 ``storeData()`` 都是 ``protected`` 的抽象方法。请注意，在 |Fess| + 15.x 中，``DataConfig`` 所在的包是 ``org.codelibs.fess.opensearch.config.exentity`` + （此前的 ``org.codelibs.fess.es.config.exentity`` 已被废弃）。 + +组件注册 +-------------------- + +为了让 |Fess| 识别所创建的数据存储，需要在 ``src/main/resources/fess_ds++.xml`` 中 +注册组件。 + +.. code-block:: xml + + + + + + + + + +通过 ````，组件生成后会自动调用 ``AbstractDataStore`` +所具有的 ``register()`` 方法，将自身注册到 ``DataStoreFactory`` 中。此时注册的名称即为 +``getName()`` 的返回值（上例中为 ``ExampleDataStore``），也就是在管理界面的数据存储设置 +中选择的"处理器名"。 + +AbstractDataStore +================= + +主要方法 +------------ + +.. list-table:: + :header-rows: 1 + :widths: 35 20 45 + + * - 方法 + - 类别 + - 说明 + * - ``getName()`` + - 实现（必需） + - 返回数据存储处理器名的抽象方法。按照惯例返回 ``getClass().getSimpleName()`` + * - ``storeData()`` + - 实现（必需） + - 执行数据获取、转换及索引注册的抽象方法 + * - ``register()`` + - 继承（通常无需修改） + - 由 ``fess_ds++.xml`` 的 ``postConstruct`` 自动调用，注册到 ``DataStoreFactory`` + * - ``store()`` + - 继承（框架调用） + - 框架调用的入口。准备好 ``defaultDataMap`` 等后调用 ``storeData()`` + * - ``convertValue()`` + - 继承（辅助方法） + - 通过脚本引擎对 ``scriptMap`` 的值（模板）进行求值 + * - ``getScriptType()`` + - 继承（辅助方法） + - 获取 ``script_type`` 参数（默认为 Groovy） + * - ``getReadInterval()`` + - 继承（辅助方法） + - 获取 ``readInterval`` 参数（毫秒） + * - ``sleep()`` + - 继承（辅助方法） + - 休眠指定的毫秒数（用于记录间的等待） + +storeData 的参数 +------------------------ + +传递给 ``storeData()`` 方法的参数： + +.. list-table:: + :header-rows: 1 + :widths: 25 35 40 + + * - 参数 + - 类型 + - 说明 + * - ``dataConfig`` + - ``DataConfig`` + - 数据存储设置（ID、处理器名、参数、脚本等） + * - ``callback`` + - ``IndexUpdateCallback`` + - 将生成的文档注册到索引的回调 + * - ``paramMap`` + - ``DataStoreParams`` + - 管理界面"参数"栏中设置的值。可通过 ``getAsString(key)`` / ``getAsString(key, default)`` / ``get(key)`` / ``asMap()`` / ``containsKey(key)`` 进行访问 + * - ``scriptMap`` + - ``Map`` + - 管理界面"脚本"栏中的设置。键为索引字段名，值为待求值的脚本模板 + * - ``defaultDataMap`` + - ``Map`` + - 各文档的默认字段值（配置ID、boost、role、mimetype、虚拟主机等）。由框架准备 + +.. warning:: + + ``paramMap`` 的类型不是 ``Map``，而是 ``DataStoreParams``\ 。由于 + ``DataStoreParams`` 并未实现 ``Map`` 接口，获取值时请使用返回字符串的 + ``getAsString()``，而不是 ``get()``\ 。 + +数据处理流程 +---------------- + +``storeData()`` 的实现按以下流程处理数据： + +#. 从外部系统获取源记录。 +#. 将源记录的字段合并到 ``paramMap.asMap()`` 中，构建 ``resultMap`` + （脚本将针对该 ``resultMap`` 进行求值）。 +#. 使用 ``convertValue(scriptType, template, resultMap)`` 对 ``scriptMap`` 中的每个 + 条目求值，并将结果存入 ``dataMap``\ 。需要注意的是，映射关系并非硬编码在代码中，而是由 + 管理员在"脚本"栏中定义。 +#. 调用 ``callback.store(paramMap, dataMap)``，将其作为文档注册到索引中。 + +实现示例 +======== + +简单的数据存储 +---------------------- + +以下是从外部 API 获取记录并注册到索引的示例。 + +.. code-block:: java + + @Override + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { + + // 获取参数（DataStoreParams 需使用 getAsString） + final String apiUrl = paramMap.getAsString("api.url"); + final String apiKey = paramMap.getAsString("api.key"); + + // 脚本的求值类型（默认为 Groovy） + final String scriptType = getScriptType(paramMap); + // 记录之间的等待时间（毫秒） + final long readInterval = getReadInterval(paramMap); + + try { + // 从外部系统获取数据 + final List> records = fetchRecords(apiUrl, apiKey); + + for (final Map record : records) { + // 复制默认字段以初始化 dataMap + final Map dataMap = new HashMap<>(defaultDataMap); + + // 构建合并了参数与源记录的 resultMap + // （脚本将针对此 resultMap 进行求值） + final Map resultMap = new LinkedHashMap<>(paramMap.asMap()); + resultMap.putAll(record); + + // 对 scriptMap 中的每个条目求值，生成索引字段 + for (final Map.Entry entry : scriptMap.entrySet()) { + final Object value = convertValue(scriptType, entry.getValue(), resultMap); + if (value != null) { + dataMap.put(entry.getKey(), value); + } + } + + // 注册到索引 + callback.store(paramMap, dataMap); + + if (readInterval > 0) { + sleep(readInterval); + } + } + } catch (final Exception e) { + throw new DataStoreException("Failed to crawl data from " + apiUrl, e); + } + } + +``fetchRecords()`` 是从外部系统获取记录列表的自定义方法。获取到的每条记录 +（``Map``）的字段名，即为可在 ``scriptMap`` 的脚本中引用的名称。 +``DataStoreException`` 是 ``org.codelibs.fess.exception`` 包中的类。 + +分页支持 +-------------------- + +在处理大量数据时，需要按页获取并处理数据。将每条记录的处理逻辑（构建 ``resultMap``、 +对 ``scriptMap`` 求值、调用 ``callback.store()``）拆分到类似 ``processRecord()`` 的 +方法中，可以将其与获取逻辑分离。 + +.. code-block:: java + + int offset = 0; + final int pageSize = 100; + + while (true) { + final List> records = fetchRecords(apiUrl, apiKey, offset, pageSize); + + if (records.isEmpty()) { + break; + } + + for (final Map record : records) { + processRecord(record, callback, paramMap, scriptMap, defaultDataMap); + } + + offset += pageSize; + } + +认证实现 +========== + +外部系统的认证由连接器一侧负责实现。以下是使用常见 HTTP 客户端库的实现示例，并非 +|Fess| 提供的 API。请将所使用的库作为插件的依赖项一并打包。 + +OAuth 2.0 +--------- + +.. code-block:: java + + protected String getAccessToken(final String clientId, final String clientSecret, final String refreshToken) { + // 使用刷新令牌获取访问令牌的示例 + final OkHttpClient client = new OkHttpClient(); + + final RequestBody body = new FormBody.Builder() + .add("grant_type", "refresh_token") + .add("client_id", clientId) + .add("client_secret", clientSecret) + .add("refresh_token", refreshToken) + .build(); + + final Request request = new Request.Builder() + .url("https://oauth.example.com/token") + .post(body) + .build(); + + try (Response response = client.newCall(request).execute()) { + final JsonNode json = objectMapper.readTree(response.body().string()); + return json.get("access_token").asText(); + } + } + +API密钥认证 +----------- + +.. code-block:: java + + protected Response callApi(final String url, final String apiKey) { + final Request request = new Request.Builder() + .url(url) + .addHeader("Authorization", "Bearer " + apiKey) + .build(); + + return httpClient.newCall(request).execute(); + } + +错误处理 +================== + +对于应中断处理的致命错误，请抛出 ``DataStoreException``\ 。 + +.. code-block:: java + + @Override + protected void storeData(...) { + try { + // 处理 + } catch (final AuthenticationException e) { + logger.error("Authentication failed. Check your credentials.", e); + throw new DataStoreException("Authentication failed", e); + } catch (final RateLimitException e) { + logger.warn("Rate limit exceeded. Waiting..."); + sleep(60000L); + // 重试逻辑 + } catch (final Exception e) { + logger.error("Unexpected error occurred", e); + throw new DataStoreException("Failed to crawl data", e); + } + } + +.. note:: + + 在以 ``fess-ds-example`` 为代表的实际连接器中，为了避免单条记录的错误导致整个爬取 + 中断，会以记录为单位捕获 ``CrawlingAccessException``，并将出错的 URL 记录到 + ``FailureUrlService`` 中。此外，还会利用 ``DataStoreCrawlingException`` 的中断 + 标志，来控制是否中断整个爬取过程。如需实现健壮的连接器，请参考 ``ExampleDataStore`` + 的实现。 + +测试 +====== + +单元测试 +-------------- + +|Fess| 的插件使用 UTFlute 的 ``LastaDiTestCase`` 进行测试。测试使用 JUnit 5 +（Jupiter）编写。通过将 ``IndexUpdateCallback`` 替换为收集已注册 ``dataMap`` 的实现， +无需使用模拟（mock）库即可验证映射结果。 + +.. code-block:: java + + public class ExampleDataStoreTest extends LastaDiTestCase { + + public ExampleDataStore dataStore; + + @Override + protected String prepareConfigFile() { + return "test_app.xml"; + } + + @Override + public void setUp(final TestInfo testInfo) throws Exception { + super.setUp(testInfo); + dataStore = new ExampleDataStore(); + } + + @Test + public void test_getName() { + assertEquals("ExampleDataStore", dataStore.getName()); + } + + @Test + public void test_storeData() { + final TestIndexUpdateCallback callback = new TestIndexUpdateCallback(); + final DataStoreParams paramMap = new DataStoreParams(); + + final Map scriptMap = new HashMap<>(); + scriptMap.put("title", "title"); + + dataStore.storeData(new DataConfig(), callback, paramMap, scriptMap, new HashMap<>()); + + assertFalse(callback.getDataMapList().isEmpty()); + } + + // 用于收集已注册 dataMap 的测试用回调 + private static class TestIndexUpdateCallback implements IndexUpdateCallback { + private final List> dataMapList = new ArrayList<>(); + + @Override + public void store(final DataStoreParams paramMap, final Map dataMap) { + dataMapList.add(new HashMap<>(dataMap)); + } + + @Override + public long getExecuteTime() { + return 0; + } + + @Override + public long getDocumentSize() { + return dataMapList.size(); + } + + @Override + public void commit() { + // 不执行任何操作 + } + + public List> getDataMapList() { + return dataMapList; + } + } + } + +.. note:: + + 由于基类中的 ``setUp`` 已附加了 ``@BeforeEach``，因此重写时无需在其上重新附加生命 + 周期注解。请为每个测试方法附加 ``@Test``\ （``org.junit.jupiter.api.Test``）。 + +构建与安装 +==================== + +pom.xml +------- + +插件以 ``fess-parent`` 作为父 POM，构建为 jar。对 ``fess`` 和 ``opensearch`` 的依赖， +由于在运行时由 |Fess| 本体提供，因此设置为 ``provided``\ 。 + +.. code-block:: xml + + + 4.0.0 + org.codelibs.fess + fess-ds-example + 15.10.0 + jar + + + org.codelibs.fess + fess-parent + 15.10.0 + + + + + + org.codelibs.fess + fess + provided + + + org.opensearch + opensearch + provided + + + + +测试使用 JUnit 5 和 ``org.dbflute.utflute:utflute-lastaflute``\ 。 + +构建 +------ + +.. code-block:: bash + + mvn clean package + +会在 ``target/`` 目录下生成 ``fess-ds-example-15.10.0.jar``\ 。 + +安装 +------------ + +将生成的 JAR 安装到 |Fess| 中，并重启 |Fess|\ 。安装步骤的详细信息请参考 +:doc:`../admin/plugin-guide`。安装后，从管理界面的"爬虫 > 数据存储"创建新设置，并在 +"处理器名"中指定 ``getName()`` 返回的名称（本例中为 ``ExampleDataStore``）。 + +配置示例 +======== + +管理界面中的配置示例： + +参数 +------------ + +"参数"栏中填写连接器从 ``paramMap`` 读取的键和值。 + +:: + + api.url=https://api.example.com/v1 + api.key=your_api_key + +脚本 +---------- + +"脚本"栏中以 ``左边=右边`` 的形式描述映射关系。左边为索引字段名，右边为引用源记录字段 +的脚本（新建的配置为 JavaScript；未记录脚本类型的配置将被视为 Groovy）。 +以下是源记录具有 ``url`` / ``title`` / ``content`` / +``updated_at`` / ``content_type`` 字段时的示例。 + +:: + + url=url + title=title + content=content + last_modified=updated_at + mimetype=content_type + +.. note:: + + 右边可引用的字段名，取决于连接器存入 ``resultMap`` 中的值（``paramMap`` 的值以及 + 源记录的字段）。在 CSV、JSON 等现有连接器中，可能会带有类似 ``data.*`` 的专属前缀， + 请参考各连接器的文档。 + +参考信息 +======== + +- :doc:`plugin-architecture` - 插件架构 +- :doc:`../admin/plugin-guide` - 插件安装 +- :doc:`../config/datastore/ds-overview` - 数据存储连接器概述 +- `fess-ds-example `__ - 数据存储插件的实现模板 +- `GitHub: fess-ds-* `__ - 公开连接器示例 diff --git a/zh-cn/15.10/dev/index.rst b/zh-cn/15.10/dev/index.rst new file mode 100644 index 000000000..2c4795491 --- /dev/null +++ b/zh-cn/15.10/dev/index.rst @@ -0,0 +1,28 @@ +================================== +|Fess| 开发者文档 +================================== + +|Fess| 扩展开发相关文档。 + +.. toctree:: + :maxdepth: 2 + :caption: 概述 + + overview + +.. toctree:: + :maxdepth: 2 + :caption: 插件开发 + + plugin-architecture + datastore-plugin + script-engine-plugin + webapp-plugin + ingest-plugin + +.. toctree:: + :maxdepth: 2 + :caption: 自定义 + + theme-development + diff --git a/zh-cn/15.10/dev/ingest-plugin.rst b/zh-cn/15.10/dev/ingest-plugin.rst new file mode 100644 index 000000000..ffd91f10e --- /dev/null +++ b/zh-cn/15.10/dev/ingest-plugin.rst @@ -0,0 +1,158 @@ +================================== +Ingest插件 +================================== + +概述 +==== + +Ingest插件提供在文档注册到索引之前对数据进行加工和转换的功能。 +通过抓取获取的各个文档，在发送到索引之前都会经过已注册的 Ingester。 + +用途 +==== + +- 文本规范化（全角/半角转换、空白整理等） +- 添加元数据或自定义字段 +- 敏感信息脱敏 +- 值转换（例如：解码已编码的向量嵌入） + +Ingester 类 +=============== + +Ingest 功能通过继承 ``org.codelibs.fess.ingest.Ingester`` 抽象类来实现。 +``Ingester`` 提供了根据抓取类型和处理阶段调用的 ``process`` 方法。由于 +默认实现均直接返回接收到的 ``target``\ （不做任何处理），因此只需重写 +所需的方法即可。 + +- ``protected Map process(Map target)`` + + 这是两个 ``Map`` 版本方法共同的委托目标。重写此方法后，将同时适用于 + 数据存储抓取以及 Web/文件抓取（索引注册时）的文档。在多数场景下， + 只需重写此方法即可满足需求。 + +- ``public Map process(Map target, DataStoreParams params)`` + + 在数据存储抓取时被调用。默认情况下会委托给 ``process(target)``\ 。 + +- ``public Map process(Map target, AccessResult accessResult)`` + + 在 Web/文件抓取的索引注册时被调用。默认情况下会委托给 ``process(target)``\ 。 + +- ``public ResultData process(ResultData target, ResponseData responseData)`` + + 在 Web/文件抓取的响应处理时（保存访问结果之前）被调用。默认情况下 + 会直接返回 ``target``\ 。 + +执行顺序（priority） +-------------------- + +当注册了多个 Ingester 时，将按照 ``priority`` 字段的升序（值越小越先 +执行）执行。默认值为 ``99``\ 。可以在构造函数中直接设置，也可以通过 +``setPriority(int)`` 进行修改。 + +.. code-block:: java + + public int getPriority() + public void setPriority(final int priority) + +实现示例 +====== + +以下是重写 ``process(Map)`` 方法，对内容进行规范化并 +添加自定义字段的示例： + +.. code-block:: java + + package org.codelibs.fess.ingest.example; + + import java.util.Map; + + import org.codelibs.fess.ingest.Ingester; + + public class ExampleIngester extends Ingester { + + public ExampleIngester() { + // 设置执行顺序（值越小越先执行。默认值为 99） + setPriority(50); + } + + @Override + protected Map process(final Map target) { + // 内容规范化 + final Object content = target.get("content"); + if (content instanceof String) { + target.put("content", ((String) content).trim().replaceAll("\\s+", " ")); + } + + // 添加自定义字段 + target.put("ingested_by", ExampleIngester.class.getSimpleName()); + + // 返回加工后的文档 + return target; + } + } + +.. note:: + + 在 ``process`` 方法中返回 ``null`` 会导致索引注册失败。由于没有跳过 + 文档的机制，因此请务必返回 ``target``\ 。 + +注册 +==== + +Ingester 通过 DI 容器进行注册。插件中需包含 ``fess_ingest++.xml`` +文件。文件名末尾的 ``++`` 是一种合并约定，表示将配置追加到 |Fess| +本体的 ``fess_ingest.xml``\ （其中定义了管理 Ingester 的 ``ingestFactory``）中。 + +.. code-block:: xml + + + + + + + + + +通过 ````，组件生成后会调用 +``Ingester#register()``，从而将自身注册到 ``ingestFactory`` 中。 + +关于 Ingest 功能，``fess_config.properties`` 中没有相应的配置项。 +是否启用取决于插件是否安装，执行顺序则通过 ``priority`` 控制。 + +执行流程 +========== + +在加工后的文档发送到索引之前，Ingester 会在以下位置按照 ``priority`` +的升序被调用： + +- **数据存储抓取**：在发送文档之前，会调用 + ``process(Map, DataStoreParams)``\ 。 +- **Web/文件抓取（响应处理时）**：在保存抓取结果之前，会调用 + ``process(ResultData, ResponseData)``\ 。 +- **Web/文件抓取（索引注册时）**：在发送文档之前，会调用 + ``process(Map, AccessResult)``\ 。 + +无论在哪个位置，如果某个 Ingester 抛出异常，都会输出警告日志并继续 +处理（该文档的索引注册不会中断）。 + +.. note:: + + 由于 Ingester 是注册到抓取器的运行环境（``ingestFactory``）中的， + 因此它作为抓取处理的一部分运行。 + +参考实现 +======== + +作为实现参考，以下插件已在 GitHub 的 +`CodeLibs `__ 上公开： + +- ``fess-ingest-example`` - 最小配置的示例实现 +- ``fess-webapp-multimodal`` - 包含用于解码向量嵌入的 ``EmbeddingIngester`` 的插件 + +参考信息 +======== + +- :doc:`plugin-architecture` - 插件架构 diff --git a/zh-cn/15.10/dev/overview.rst b/zh-cn/15.10/dev/overview.rst new file mode 100644 index 000000000..3be0d9bd8 --- /dev/null +++ b/zh-cn/15.10/dev/overview.rst @@ -0,0 +1,236 @@ +================================== +开发者文档概述 +================================== + +概述 +==== + +本节介绍 |Fess| 的扩展开发。 +提供插件开发、自定义连接器创建、主题定制等 +扩展 |Fess| 所需的信息。 + +目标读者 +======== + +- 想要开发 |Fess| 自定义功能的开发者 +- 想要创建插件的开发者 +- 想要理解 |Fess| 源代码的开发者 + +前提知识 +-------- + +- Java 21的基本知识 +- Maven（构建系统）基础 +- Web应用程序开发经验 +- OpenSearch的基本知识（|Fess| 使用OpenSearch作为搜索引擎） + +开发环境 +======== + +推荐环境 +-------- + +- **JDK**: OpenJDK 21以上 +- **IDE**: IntelliJ IDEA / Eclipse / VS Code +- **构建工具**: Maven（构建过程未强制规定最低版本，但推荐使用支持Java 21的较新3.x版本） +- **Git**: 版本管理 +- **OpenSearch**: 搜索引擎后端（从IDE启动时，所需的模块和插件会在构建时下载） + +环境配置 +-------- + +|Fess| 作为Maven项目进行构建。开发时最简单的方式是从IDE启动。 + +1. 获取源代码: + + :: + + git clone https://github.com/codelibs/fess.git + +2. 导入到IDE: + + 将获取到的目录作为Maven项目导入到IDE中。 + +3. 下载OpenSearch所需的模块和插件: + + 仅首次需要执行以下命令，将搜索引擎的模块和插件获取到 ``plugins`` 目录中。 + + :: + + mvn antrun:run + +4. 启动开发服务器（从IDE）: + + 在IDE中运行或以调试方式运行 ``org.codelibs.fess.FessBoot``， + 然后在浏览器中打开 http://localhost:8080/。 + 管理界面为 http://localhost:8080/admin/ （初始账号: ``admin`` / ``admin``）。 + +5. 构建软件包（生成分发包）: + + 如果需要分发包，请执行 ``package`` 目标。 + 生成的成果物会输出到 ``target/releases`` 中（如需跳过单元测试，请添加 ``-DskipTests``）。 + + :: + + mvn package + + 展开生成的分发包后，即可使用 ``bin/fess`` 启动脚本。 + + :: + + unzip target/releases/fess-*.zip + ./fess-*/bin/fess + +.. note:: + + ``bin/fess`` 启动脚本包含在分发包（zip/rpm/deb）中。 + 仅在源代码目录中执行 ``mvn package``，并不会在仓库根目录下生成 ``bin/fess``\ 。 + 在基于源代码进行开发时，请按照上文所述在IDE中运行 ``FessBoot``， + 或使用展开后的分发包中的 ``bin/fess``\ 。 + +架构概述 +======== + +|Fess| 由以下主要组件构成: + +组件构成 +-------- + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - 组件 + - 说明 + * - Web层 + - 基于LastaFlute框架的MVC实现 + * - 服务层 + - 业务逻辑 + * - 数据访问层 + - 通过DBFlute（ESFlute/FreeGen）实现的类型安全的OpenSearch访问 + * - 爬虫 + - 使用fess-crawler库进行内容收集 + * - 搜索引擎 + - 基于OpenSearch的全文搜索 + +主要框架 +-------- + +- **LastaFlute**: Web框架（Action、Form、Validation） +- **DBFlute**: 数据访问框架。面向OpenSearch的类型安全访问类（``Bhv`` / ``ConditionBean``） + 由DBFlute的FreeGen功能与ESFlute模板生成 + （重新生成命令为 ``mvn dbflute:freegen``） +- **Lasta Di**: 依赖注入容器 + +目录结构 +======== + +:: + + fess/ + ├── src/main/java/org/codelibs/fess/ + │ ├── app/ + │ │ ├── web/ # 控制器（Action） + │ │ ├── service/ # 服务 + │ │ ├── logic/ # 逻辑 + │ │ └── pager/ # 分页 + │ ├── api/ # REST API（如api/v2） + │ ├── helper/ # 辅助类 + │ ├── crawler/ # 爬虫相关 + │ ├── indexer/ # 索引处理 + │ ├── opensearch/ # OpenSearch访问（ESFlute/FreeGen生成） + │ ├── llm/ # LLM集成 + │ ├── ds/ # 数据存储连接器 + │ ├── ingest/ # Ingest（索引时的数据加工） + │ ├── script/ # 脚本引擎 + │ ├── entity/ # 实体 + │ └── mylasta/ # LastaFlute配置（DI、消息、类型安全配置） + ├── src/main/resources/ + │ ├── fess_config.properties # 配置 + │ └── fess_*.xml # DI配置（如app.xml、fess_ds.xml） + └── src/main/webapp/ + └── WEB-INF/view/ # 管理界面和登录界面的JSP + +扩展点 +====== + +|Fess| 提供以下扩展点: + +插件 +---- + +使用插件可以添加功能。 + +- **数据存储插件**: 从新数据源进行爬取（继承 ``AbstractDataStore``） +- **脚本引擎插件**: 支持新的脚本语言（实现 ``ScriptEngine``） +- **Web应用插件**: 扩展Web界面（通过Lasta Di的组件覆盖与资源合并） +- **Ingest插件**: 索引时的数据加工（继承 ``Ingester``） + +详情: :doc:`plugin-architecture` + +.. note:: + + |Fess| 本体以 ``war`` 形式打包。在本地构建插件时， + 如果无法将 |Fess| 解析为依赖项，请将 ``pom.xml`` 中的 ```` 临时改为 ``jar``， + 执行 ``mvn clean install -DskipTests``，然后再改回 ``war``\ 。 + +主题 +---- + +可以自定义搜索界面的设计。 + +详情: :doc:`theme-development` + +配置 +---- + +可以通过 ``fess_config.properties`` 自定义许多行为。 + +详情: :doc:`../config/intro` + +插件开发 +======== + +有关插件开发的详细信息，请参阅以下内容: + +- :doc:`plugin-architecture` - 插件架构 +- :doc:`datastore-plugin` - 数据存储插件开发 +- :doc:`script-engine-plugin` - 脚本引擎插件 +- :doc:`webapp-plugin` - Web应用插件 +- :doc:`ingest-plugin` - Ingest插件 + +主题开发 +======== + +- :doc:`theme-development` - 主题自定义 + +最佳实践 +======== + +编码规范 +-------- + +- 遵循 |Fess| 现有的代码风格 +- 使用 ``mvn formatter:format`` 格式化代码 +- 使用 ``mvn license:format`` 添加许可证头 + +测试 +---- + +- 单元测试（``*Test.java``）: 在默认的 ``build`` 配置文件下作为 ``mvn test`` 执行 +- 集成测试（``*Tests.java``）: 通过 ``mvn test -P integrationTests`` 执行。 + 执行集成测试需要运行中的 |Fess| 服务器与OpenSearch + +日志 +---- + +- 使用Log4j2 +- ``logger.debug()`` / ``logger.info()`` / ``logger.warn()`` / ``logger.error()`` +- 不要在日志中输出敏感信息 + +资源 +==== + +- `GitHub Repository `__ +- `Issue Tracker `__ +- `Discussions `__ diff --git a/zh-cn/15.10/dev/plugin-architecture.rst b/zh-cn/15.10/dev/plugin-architecture.rst new file mode 100644 index 000000000..c52d76f76 --- /dev/null +++ b/zh-cn/15.10/dev/plugin-architecture.rst @@ -0,0 +1,362 @@ +================================== +插件架构 +================================== + +概述 +==== + +通过 |Fess| 的插件系统，可以扩展核心功能。 +插件以 JAR 文件的形式分发，添加到类路径后，会由 DI 容器（Lasta Di） +加载其中的组件，并注册到相应的工厂或管理器中。 + +插件类型 +======== + +|Fess| 通过构件（artifact）名称的前缀来判断插件的类型 +（``PluginHelper.ArtifactType``）。主要类型如下： + +.. list-table:: + :header-rows: 1 + :widths: 20 25 55 + + * - 类型 + - 前缀 + - 说明 + * - 数据存储 + - ``fess-ds-*`` + - 从新数据源获取内容（Box、Slack、Git 等） + * - Web应用 + - ``fess-webapp-*`` + - 扩展Web界面或搜索功能 + * - 脚本引擎 + - ``fess-script-*`` + - 支持新的脚本语言 + * - Ingest + - ``fess-ingest-*`` + - 索引注册时对文档进行加工处理 + * - 缩略图 + - ``fess-thumbnail-*`` + - 添加缩略图生成方式 + * - LLM + - ``fess-llm-*`` + - 添加 RAG/聊天功能中使用的 LLM 提供方 + * - 爬虫 + - ``fess-crawler-*`` + - 扩展爬虫客户端 + * - 存储 + - ``fess-storage-*`` + - 添加爬取和存储功能中使用的对象存储后端 + * - SSO + - ``fess-sso-*`` + - 添加由 ``sso.type`` 选择的单点登录认证方式 + +.. note:: + + 提供 JSP 的 ``fess-theme-*`` （JAR 主题）种类已在 15.10 中删除。 + 搜索界面的外观不是通过插件，而是通过静态主题来更改（参见 :doc:`theme-development` ）。 + +插件结构 +======== + +基本结构 +-------- + +以数据存储插件的实现模板 +`fess-ds-example `__ 为例， +插件由"实现类"和"DI 注册文件"构成： + +:: + + fess-ds-example/ + ├── pom.xml + └── src/main/ + ├── java/org/codelibs/fess/ds/example/ + │ └── ExampleDataStore.java # 数据存储实现 + └── resources/ + └── fess_ds++.xml # DI组件注册 + +pom.xml示例 +----------- + +插件以 ``fess-parent`` 作为父 POM，构建为 jar。\ ``fess``、``opensearch`` +等在运行时由 |Fess| 本体提供的库，需以 ``provided`` 作用域声明。版本号 +及构建配置（格式化工具、许可证头等）均从父 POM 继承。 + +.. code-block:: xml + + + + 4.0.0 + + org.codelibs.fess + fess-ds-example + 15.10.0 + jar + + + org.codelibs.fess + fess-parent + 15.10.0 + + + + + + org.codelibs.fess + fess + provided + + + org.opensearch + opensearch + provided + + + + +.. note:: + + 在开发中的分支上，版本号会带有 ``-SNAPSHOT`` 后缀，例如 + ``15.10.0-SNAPSHOT``\ 。插件特有的依赖库以普通的 Maven 依赖关系声明。 + 由于这些库不包含在 |Fess| 本体中，因此需要与插件一起分发。 + +插件注册 +======== + +DI容器注册 +---------- + +插件通过文件名以 ``++`` 结尾的 DI 配置文件（如 ``fess_ds++.xml``）来 +注册组件。Lasta Di 会将在类路径中找到的带 ``++`` 的文件，自动合并到 +|Fess| 本体对应的配置文件中（本例中为 ``fess_ds.xml``）。借助这一机 +制，插件无需修改 |Fess| 本体的文件，即可添加自身的组件。 + +.. code-block:: xml + + + + + + + + + +不同类型的插件，合并目标文件也不同。例如脚本引擎使用 +``fess_se++.xml``、Ingest 使用 ``fess_ingest++.xml``、LLM 提供方使用 +``fess_llm++.xml``、Web应用使用 ``app++.xml``\ 。 + +组件初始化 +---------- + +```` 是 Lasta Di 的生命周期设置，用于 +指定组件生成后要调用的方法。对于数据存储而言，会调用 +``AbstractDataStore`` 所具有的 ``register()`` 方法，将自身注册到 +``DataStoreFactory`` 中： + +.. code-block:: java + + // AbstractDataStore 的实现（通常无需重写） + public void register() { + ComponentUtil.getDataStoreFactory().add(getName(), this); + } + +.. note:: + + 这并非 Java 的 ``@PostConstruct`` 注解，而是通过 DI 配置文件中的 + ```` 元素进行的初始化。注册的名称即为 ``getName()`` + 的返回值，也就是在管理界面中选择插件时使用的名称。 + +插件生命周期 +============ + +初始化 +------ + +1. 插件 JAR 被添加到类路径中 +2. DI 容器合并 ``fess_*++.xml``，生成组件 +3. 调用 ```` 中指定的方法（例如 ``register``） +4. 插件注册到对应的工厂/管理器中 + +终止 +---- + +1. DI 容器终止时，会调用 ```` 中指定的方法（如果已定义） +2. 清理资源 + +.. note:: + + 对于数据存储而言，正在运行的爬取会通过 ``AbstractDataStore.stop()`` + 设置停止标志，使记录处理循环安全结束。 + +依赖关系 +======== + +与Fess本体的依赖 +---------------- + +由于 |Fess| 本体的类在运行时已存在于服务器的类路径中，因此以 +``provided`` 作用域进行依赖（不会包含在插件 JAR 中）。 + +.. code-block:: xml + + + org.codelibs.fess + fess + provided + + +外部库 +------ + +插件可以包含自己的依赖库： + +.. code-block:: xml + + + com.example + example-sdk + 1.0.0 + + +由于这些库不包含在 |Fess| 本体中，因此需要与插件一起分发。 + +获取配置 +======== + +获取参数和FessConfig +-------------------- + +在数据存储的 ``storeData()`` 中，可从 ``DataStoreParams`` 获取在管理 +界面中设置的参数。获取值时请使用 ``getAsString()``\ （由于 +``DataStoreParams`` 并未实现 ``Map`` 接口，``get()`` 不会返回字符 +串）。此外，|Fess| 的配置值可通过 ``ComponentUtil.getFessConfig()`` +获取： + +.. code-block:: java + + public class ExampleDataStore extends AbstractDataStore { + + @Override + protected String getName() { + // 用作处理器名。按照惯例返回类的简单名称 + return this.getClass().getSimpleName(); + } + + @Override + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { + + // 获取参数 + final String apiKey = paramMap.getAsString("api.key"); + final String baseUrl = paramMap.getAsString("base.url"); + + // 获取FessConfig + final FessConfig fessConfig = ComponentUtil.getFessConfig(); + } + } + +关于 ``storeData()`` 的详细实现方法（数据获取、脚本求值、索引注册的 +流程），请参考 :doc:`datastore-plugin`。 + +构建与安装 +========== + +构建 +---- + +:: + + mvn clean package + +会在 ``target/`` 目录下生成 JAR 文件（例如 +``fess-ds-example-15.10.0.jar``）。 + +安装 +---- + +1. **从管理界面**： + + - 打开[系统 > 插件 > 安装] + - 从插件仓库列表中选择，或上传已构建的 JAR 文件进行安装 + +2. **手动安装**： + + - 将 JAR 文件复制到 ``app/WEB-INF/plugin/`` 目录 + - 重启 |Fess| + +安装步骤的详细信息请参考 :doc:`../admin/plugin-guide`。 + +调试 +==== + +日志输出 +-------- + +|Fess| 使用 Log4j2。日志记录器（logger）可通过 +``LogManager.getLogger()`` 获取： + +.. code-block:: java + + private static final Logger logger = LogManager.getLogger(ExampleDataStore.class); + + public void someMethod() { + logger.debug("Debug message"); + logger.info("Info message"); + } + +.. note:: + + 请不要将密码、令牌等敏感信息输出到日志中。 + +开发模式 +-------- + +开发时可以从 IDE 启动 |Fess| 进行调试： + +1. 以调试模式运行 ``org.codelibs.fess.FessBoot`` 类 +2. 将插件的源代码包含在项目中 +3. 设置断点 + +公开插件列表 +============ + +|Fess| 项目公开了大量插件，以下是其中的代表示例（并非全部列举）： + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 插件 + - 说明 + * - ``fess-ds-box`` + - Box 连接器 + * - ``fess-ds-dropbox`` + - Dropbox 连接器 + * - ``fess-ds-slack`` + - Slack 连接器 + * - ``fess-ds-atlassian`` + - JIRA / Confluence 连接器 + * - ``fess-ds-git`` + - Git 仓库连接器 + * - ``fess-llm-openai`` + - OpenAI LLM 提供方 + +除此之外，还公开了 ``fess-ds-csv`` / ``fess-ds-db`` / ``fess-ds-json`` / +``fess-ds-microsoft365`` / ``fess-ds-sharepoint`` 等数据存储连接器，以及 +``fess-llm-ollama`` / ``fess-llm-gemini`` / ``fess-llm-bedrock`` 等 LLM 提供方。这些插件已在 +`GitHub `__ 上公开，可作为开发参考。 + +参考信息 +======== + +- :doc:`datastore-plugin` - 数据存储插件开发 +- :doc:`script-engine-plugin` - 脚本引擎插件 +- :doc:`webapp-plugin` - Web应用插件 +- :doc:`ingest-plugin` - Ingest插件 +- :doc:`theme-development` - 主题自定义 +- :doc:`../admin/plugin-guide` - 插件安装 diff --git a/zh-cn/15.10/dev/script-engine-plugin.rst b/zh-cn/15.10/dev/script-engine-plugin.rst new file mode 100644 index 000000000..ee0ba750e --- /dev/null +++ b/zh-cn/15.10/dev/script-engine-plugin.rst @@ -0,0 +1,61 @@ +================================== +脚本引擎插件 +================================== + +概述 +==== + +通过开发脚本引擎插件，可以为 |Fess| 添加新的脚本语言支持。 + +基本实现 +======== + +实现 ``ScriptEngine`` 接口: + +.. code-block:: java + + package org.codelibs.fess.script.example; + + import org.codelibs.fess.script.ScriptEngine; + import java.util.Map; + + public class ExampleScriptEngine implements ScriptEngine { + + @Override + public String getName() { + return "example"; + } + + @Override + public Object evaluate(String script, Map params) { + // 脚本评估逻辑 + return executeScript(script, params); + } + } + +注册 +==== + +.. code-block:: java + + @PostConstruct + public void register() { + ComponentUtil.getScriptEngineManager().add(this); + } + +使用示例 +======== + +在管理界面中选择脚本类型: + +:: + + scriptType=example + scriptData=your script here + +参考信息 +======== + +- :doc:`plugin-architecture` - 插件架构 +- :doc:`../config/scripting-overview` - 脚本概述 + diff --git a/zh-cn/15.10/dev/theme-development.rst b/zh-cn/15.10/dev/theme-development.rst new file mode 100644 index 000000000..047eb82d6 --- /dev/null +++ b/zh-cn/15.10/dev/theme-development.rst @@ -0,0 +1,290 @@ +================================== +主题开发指南 +================================== + +概述 +==== + +在 |Fess| 15.10 中，搜索界面始终是静态主题。静态主题是使用 +``/api/v2/*`` API 的独立 SPA（单页应用程序）。主题以 ZIP 文件的形式 +分发，从管理界面上传后在管理界面中启用。未选择任何主题时， |Fess| +使用其内置的静态主题 ``bootstrap`` 。 + +要更改搜索界面的外观，可以安装其他主题（参见 :doc:`../admin/theme-guide` ）， +也可以自行制作：最快捷的方法是复制内置主题并修改副本，具体步骤参见 +`自定义内置主题`_ 。 + +.. note:: + + 静态主题可在 |Fess| 15.7 及以上版本中使用，并在 15.10 中成为默认的 + 搜索界面。替换搜索界面 JSP 的 JAR 主题插件已在 15.10 中删除； + 参见 `JAR 主题插件（已在 15.10 中删除）`_ 。 + +静态主题 +======== + +静态主题是包含 ``theme.yml`` 清单文件和 ``index.html`` 的一组静态资源。 +主题本体作为调用 |Fess| 的 ``/api/v2/*`` API 的前端应用程序来实现。 + +结构 +---- + +静态主题采用如下目录结构。 + +:: + + example/ + ├── theme.yml # 清单文件(必需) + ├── index.html # SPA 的入口 HTML + ├── assets/ # JavaScript、CSS 等静态资源 + │ └── styles.css + ├── i18n/ # 多语言消息(messages..json) + │ └── messages.en.json + ├── help/ # 帮助定义(.json) + │ └── en.json + └── thumbnail.png # 预览图片(可选) + +清单文件（theme.yml） +--------------------- + +``theme.yml`` 是必须放置在 ZIP 根目录下的清单文件。以下是最小配置的 +示例。 + +.. code-block:: yaml + + apiVersion: fess.codelibs.org/v1 + kind: StaticTheme + name: example + displayName: "Example Theme" + version: "15.10.0" + minFessVersion: "15.10" + entry: index.html + spaFallback: true + +可以指定的字段如下。 + +.. list-table:: + :header-rows: 1 + :widths: 22 12 66 + + * - 字段 + - 必需 + - 说明 + * - ``apiVersion`` + - 必需 + - 固定值 ``fess.codelibs.org/v1``\ 。 + * - ``kind`` + - 必需 + - 固定值 ``StaticTheme``\ 。 + * - ``name`` + - 必需 + - 主题名称。必须匹配 ``^[a-z0-9][a-z0-9_-]{0,63}$``\ 。 + 用作展开到 ``themes/`` 下的主题目录名（上传时该名称会根据 + ``name`` 自动确定），以及分发 URL（``/themes//``）。 + * - ``displayName`` + - 必需 + - 显示在管理界面中的名称。 + * - ``version`` + - 必需 + - 语义化版本格式（例如：``15.10.0``、``15.10.1-beta.1``）。按惯例 + ``major.minor`` 与主题面向的 |Fess| 系列一致，这样仅凭版本就能知道 + 该主题是为哪个 |Fess| 准备的。 + * - ``author`` + - 可选 + - 作者姓名。 + * - ``description`` + - 可选 + - 主题说明。 + * - ``license`` + - 可选 + - 许可证。 + * - ``homepage`` + - 可选 + - 主页 URL。 + * - ``minFessVersion`` + - 可选 + - 主题所支持的 |Fess| 最低版本。请与 ``version`` 的 ``major.minor`` + 保持一致。没有 ``maxFessVersion``\ ，参见 `发布`_\ 。 + * - ``supportedLocales`` + - 可选 + - 支持的区域设置列表（例如：``[en, ja, de]``）。 + * - ``entry`` + - 可选 + - SPA 的入口 HTML。默认值为 ``index.html``\ 。 + * - ``spaFallback`` + - 可选 + - 已弃用。为保持兼容仍可指定，但不再读取：自 15.10 起，搜索界面的 + 路径始终返回入口 HTML。 + +.. note:: + + 如果从 ZIP 上传，展开目标的目录名会根据 ``name`` 自动确定。如果要在 + ``themes/`` 目录中手动放置主题，请使目录名与 ``name`` 保持一致。 + 名称不一致的主题在重新扫描时会被忽略。 + +.. note:: + + 用于预览的缩略图，需以 ``thumbnail.png`` 这一固定文件名放置在主题的 + 根目录下（会显示在管理界面的主题列表中）。该图片并非通过清单文件的 + 字段来识别，而是通过文件名来识别。建议大小控制在 512KB 以内、 + 尺寸控制在 512×512 像素以内。 + +分发与 API +---------- + +- 静态主题在 ``/themes//`` 下分发（```` 为 ``theme.yml`` + 中的 ``name``）。 +- 在 ``/``、``/search``、``/advance``、``/help``、``/error``、 + ``/profile``、``/cache``、``/chat`` 各个路径下都会返回入口 HTML + （默认是 ``index.html``），此后的路由由 SPA 处理。自 15.10 起，无论 + ``spaFallback`` 如何设置都会这样处理；该字段不再被读取。 +- 错误也由主题渲染：请求失败时，浏览器会在所请求的 URL 上收到主题的 + 入口 HTML，并附带真实的 HTTP 状态码。 +- 管理界面（``/admin/*``）、``/api/*``、登录界面等不属于静态主题的处理 + 范围，而是由 |Fess| 本体处理。 +- 入口 HTML 中的 ``{{themePath}}`` 在返回时会被替换为 ``themes/`` 。 + 在 ``index.html`` 中引用主题自身的文件时，请写成 ``{{themePath}}/assets/styles.css`` + 这样的形式。由于页面中不直接写主题名，无论以什么名称安装，主题都会加载自身的文件。 +- 入口 HTML 在返回时附带 ``Content-Security-Policy`` 头，仅允许来自 + |Fess| 自身的脚本、样式、图片和连接（允许内联样式，不允许内联脚本）。 + 因此，来自外部 CDN 的字体或脚本不会被加载；请将它们包含在主题中。 +- 入口 HTML 的 ``Content-Security-Policy`` 中包含 ``frame-ancestors 'none'``\ ， + 并且还带有 ``X-Frame-Options: DENY`` 头，因此页面不会显示在其他页面的框架中。 + ``frame-ancestors`` 的值可以通过 ``fess_config.properties`` 中的 + ``theme.index.frame.ancestors`` （默认值： ``'none'`` ）更改。设为空值时不再附加 + ``frame-ancestors`` （ ``X-Frame-Options: DENY`` 仍会附加）。在 ``frame-ancestors 'none'`` + 下，基于 WebKit 的浏览器（如 Safari）会将主题通过 ``blob:`` URL 显示的框架 + （PDF 预览或缓存显示）显示为空白。要显示这些内容，请将该值设为空。 +- 主题的 SPA 会通过 ``/api/v2/*`` API 获取搜索结果、聊天等数据。 + +打包 +---- + +使用 `fess-themes `__ 仓库中的 +``scripts/package.sh``，可以将主题打包成用于分发的 ZIP 文件。 + +:: + + ./scripts/package.sh example + +会生成 ``dist/example-.zip``\ （```` 为 ``theme.yml`` 中的 +``version``）。 + +.. note:: + + ``theme.yml`` 必须放置在 ZIP 的根目录下。如果放在子目录中， + 上传时将无法被识别。 + +发布 +---- + +|Fess| 项目开发的主题公开在 https://maven.codelibs.org/release/org/codelibs/fess/themes/ 之下，路径为 ``//-.zip``\ ，旁边是 ``.sha1``\ ，每个主题还有一份列出已公开版本的 ``maven-metadata.xml``\ 。 ``bin/fess-setup install theme `` 会读取该元数据，挑选为正在运行的 |Fess| 构建的版本。 + +请让主题的版本与其面向的 |Fess| 系列一致，并在归档内容发生变化时提升版本。已公开的版本不会被覆盖，因此保持版本不变的修改根本不会被分发。 + +清单中没有上限字段也是同样的原因。公开的归档不会再改变，因此无法事后为在更新的 |Fess| 上不再可用的主题补加上限；不为该系列发布，就在知道的那一刻表达了同样的意思。 + +.. note:: + + 查询已公开的版本时，请使用 ``maven-metadata.xml`` 而不是目录列表。目录索引是定期生成的，新公开的主题在出现在列表中之前就已经可以通过元数据读取。 + +安装与启用 +---------- + +1. 在管理界面打开"系统"→"主题"（``/admin/theme/``）。 +2. 上传创建好的 ZIP 文件。已公开的主题也可以在命令行用 + ``bin/fess-setup install theme `` 安装，参见 + :doc:`../install/fess-setup`\\ 。 +3. 在列表页面的"默认主题"下拉菜单中选择目标主题，点击"设置"按钮启用。 + +启用机制如下所述。 + +- 点击"设置"按钮后，所选的主题名称会保存到系统属性 ``theme.default`` + 中，成为系统整体的默认主题。 +- 如果使主题名称与虚拟主机的键一致，则仅在访问该虚拟主机时才会应用该 + 主题。由此可以按虚拟主机切换主题。 +- 如果直接更新了磁盘上的 ``themes/`` 目录，可以通过"重新加载"来重新 + 扫描。 + +.. note:: + + ZIP 上传存在文件大小、展开后总大小、条目数量等方面的上限，可通过 + ``fess_config.properties`` 中的 ``theme.*`` 属性进行调整（例如： + ``theme.upload.max.size`` 默认为 50MB，``theme.directory.path`` 默认为 + ``themes``）。展开时会执行防止 ZIP Slip 和 zip bomb 的校验。 + +.. _theme-customize-bundled: + +自定义内置主题 +-------------- + +内置主题 ``bootstrap`` 位于 |Fess| 安装目录的 ``app/themes/bootstrap/`` +（RPM/DEB 软件包为 ``/usr/share/fess/app/themes/bootstrap/`` ）。请不要 +直接编辑它：升级时它会被替换，而且 ``bootstrap`` 这一名称为其保留， +既无法删除，也无法通过上传替换。请以新名称复制后再修改。 + +1. 复制该目录，例如复制为 ``mytheme`` :: + + $ cp -r app/themes/bootstrap /tmp/mytheme + +2. 在 ``theme.yml`` 中，将 ``name`` 改为 ``mytheme`` ，并修改 + ``displayName`` 。 ``name`` 必须与目录名一致。 + +3. 无需修改 ``index.html`` 。内置的 ``index.html`` 以 ``{{themePath}}/assets/...`` + 引用样式表、徽标和脚本等自身的文件，|Fess| 在返回页面时会将 ``{{themePath}}`` + 替换为 ``themes/`` （ ``theme.yml`` 中的 ``name`` ）。因此只需改名，副本就会 + 加载自身的文件。添加由 ``index.html`` 引用的文件时，也请将其 URL 写成 + ``{{themePath}}/assets/...`` 的形式。 + +4. 进行修改： + + - 配色和布局： ``assets/styles.css`` 。 + - 徽标： ``assets/logo-head.png`` （页眉）和 ``assets/logo.png`` + （搜索首页）。 + - 页脚（ ``footer.copyright_org`` ）等文本：每种语言一个的 + ``i18n/messages..json`` 文件。 + - 页面结构： ``index.html`` 。 + +5. 将该目录打包为根目录下包含 ``theme.yml`` 的 ZIP，并在管理界面的 + "系统"→"主题"中上传:: + + $ cd /tmp/mytheme && zip -r ../mytheme.zip . + + 也可以将该目录放到 ``app/themes/`` 中，然后在同一页面点击"重新加载"。 + +6. 在该页面将 ``mytheme`` 选为默认主题。 + +.. note:: + + 由于内置主题遵循其所属 |Fess| 版本的 ``/api/v2/*`` API，每次升级 + |Fess| 后，请用内置主题的新副本替换原副本，并重新应用您的修改。 + +JAR 主题插件（已在 15.10 中删除） +================================== + +将 JSP、CSS、图片放入 ``fess-theme-*`` 的 JAR 中，并作为与虚拟主机的键同名的主题来应用的 +JAR 主题插件种类，已在 |Fess| 15.10 中删除。15.10 不会展开 JAR 主题，也不会在任何界面中使用它。 + +- 即使从管理界面的「系统」→「插件」安装，它也只会作为种类为 ``jar`` 的通用 JAR 放入 + ``app/WEB-INF/plugin/`` ，界面不会有任何变化。从旧版本遗留下来的 ``fess-theme-*.jar`` + 也会以同样的方式显示，可以在该界面或使用 ``bin/fess-setup remove plugin `` 删除。 +- ``bin/fess-setup`` 不会在列表中显示 ``fess-theme-*`` ，也不会安装它。 + +请将在 JAR 主题中所做的修改迁移到静态主题。 + +- 搜索界面的配色、布局和徽标，可以复制内置主题后进行修改（参见 `自定义内置主题`_ ）。 +- 如果曾按虚拟主机更改外观，请安装与虚拟主机名同名的静态主题 + （参见 :doc:`../config/security-virtual-host` ）。 +- 登录界面（``/login/``）是所有虚拟主机共用的界面，无法通过主题更改。 + +现有主题示例 +============ + +- `fess-themes `__ - 静态主题集 + （收录了 ``codesearch``、``docsearch`` 等多个静态主题） + +参考信息 +======== + +- :doc:`plugin-architecture` - 插件架构 +- :doc:`../admin/plugin-guide` - 插件安装 diff --git a/zh-cn/15.10/dev/webapp-plugin.rst b/zh-cn/15.10/dev/webapp-plugin.rst new file mode 100644 index 000000000..5a6bfe838 --- /dev/null +++ b/zh-cn/15.10/dev/webapp-plugin.rst @@ -0,0 +1,304 @@ +================================== +Web应用插件 +================================== + +概述 +==== + +Web应用插件（``fess-webapp-*``）是用于扩展 |Fess| 的Web应用程序的插件。 +与其他类型的插件不同，它并非直接添加 Action 类或 JSP，而是通过对 DI 容器 +（Lasta Di）\ **添加或替换组件** 来扩展功能。典型的用途如下： + +- 添加新组件（辅助类、服务等） +- 替换（子类化）\ |Fess| 本体的组件 +- 添加 REST API 端点（``WebApiManager``） +- 扩展搜索行为（查询命令、Rank Fusion 等） + +.. note:: + + Web应用插件以 JAR 文件的形式分发，其中的类和 DI 配置文件会被加载到 + |Fess| 的Web应用程序的类路径中。它并不能添加 JSP 视图。如果需要自定义 + 搜索界面的设计，请参考 :doc:`theme-development`。 + +基本结构 +======== + +以Web应用插件的实现模板 +`fess-webapp-example `__ +为例，插件由"实现类"和"DI 注册文件"构成： + +:: + + fess-webapp-example/ + ├── pom.xml + └── src/main/ + ├── java/org/codelibs/fess/webapp/example/helper/ + │ ├── ExampleHelper.java # 要添加的组件 + │ └── CustomSystemHelper.java # 核心组件的替换 + └── resources/ + ├── app++.xml # 组件的添加（合并） + └── fess+systemHelper.xml # 组件的替换 + +.. note:: + + 实现类的包名使用 ``org.codelibs.fess.webapp.<插件名>``\ 。DI 配置文件 + 存放在 ``src/main/resources/`` 中。与数据存储插件不同，这里不包含 + ``src/main/webapp/`` 或 JSP。 + +pom.xml与清单文件 +================= + +Web应用插件以 ``fess-parent`` 作为父 POM，构建为 jar。由 |Fess| 本体在 +运行时提供的 ``fess``、``opensearch`` 需以 ``provided`` 作用域声明； +``lastaflute``、``dbflute-runtime``、``corelib`` 等运行时所需的库，则以 +通常的作用域声明。 + +Web应用插件中最重要的一点，是在 JAR 清单文件中添加 +``Fess-WebAppJar: true``\ 。通过这一声明，|Fess| 会将插件的类和 DI 配置 +文件挂载到Web应用程序的类加载器中。该设置通过 ``maven-jar-plugin`` +完成： + +.. code-block:: xml + + + + + maven-jar-plugin + + + + true + + + + + + + +.. warning:: + + 如果不添加 ``Fess-WebAppJar: true``，插件的类和 DI 配置文件将不会被 + 加载到Web应用程序的类路径中，组件的添加与替换也将不会生效。 + +关于 pom.xml 的完整构成（父 POM、依赖关系的声明方法等），请参考 +:doc:`plugin-architecture`。 + +扩展模式 +======== + +组件的添加（app++.xml） +----------------------- + +最基本的扩展方式是添加自己的组件。Lasta Di 会将类路径上的 ``app++.xml`` +**合并** 到由 |Fess| 本体的 ``app.xml`` 构建而成的 ``app`` 命名空间中 +（末尾的 ``++`` 是追加合并的约定）。由于添加的组件使用了 |Fess| 本体中 +不存在的名称，因此不会覆盖任何内容。 + +.. code-block:: xml + + + + + + + + +在组件的实现中，初始化使用 ``@PostConstruct``，|Fess| 本体的组件则通过 +``ComponentUtil`` 获取后复用（不进行复制或覆盖）： + +.. code-block:: java + + package org.codelibs.fess.webapp.example.helper; + + import org.codelibs.fess.helper.SystemHelper; + import org.codelibs.fess.util.ComponentUtil; + + import jakarta.annotation.PostConstruct; + + public class ExampleHelper { + + protected String pluginName = "fess-webapp-example"; + + @PostConstruct + public void init() { + // 由 DI 生成后仅调用一次的初始化处理 + } + + public String getPluginLabel() { + // 复用核心的 SystemHelper 获取正在运行的 Fess 版本 + final SystemHelper systemHelper = ComponentUtil.getSystemHelper(); + final String version = systemHelper != null ? systemHelper.getProductVersion() : "unknown"; + return pluginName + " (Fess " + version + ")"; + } + } + +.. tip:: + + 请首先考虑这种"组件的添加"方式。只要不需要修改核心功能，它就比替换 + 更安全，也更易于维护。 + +核心组件的替换（fess+componentName.xml） +----------------------------------------- + +如果想要改变 |Fess| 本体组件的行为，需要将目标类子类化，并在名为 +``+.xml`` 的 DI 配置文件中 **以相同的组件名 +重新注册**。例如，由于 ``systemHelper`` 是在 |Fess| 本体的 ``fess.xml`` +中声明的，因此替换文件应为 ``fess+systemHelper.xml``\ （而不是 +``app+systemHelper.xml``）。 + +.. code-block:: java + + package org.codelibs.fess.webapp.example.helper; + + import java.nio.file.Path; + + import org.codelibs.fess.helper.SystemHelper; + + public class CustomSystemHelper extends SystemHelper { + + @Override + protected void parseProjectProperties(final Path propPath) { + try { + super.parseProjectProperties(propPath); + } catch (final Exception e) { + // 自定义处理 + } + System.setProperty("fess.webapp.plugin", "true"); + } + } + +.. warning:: + + 替换（单个 ``+``）会 **整体** 替换组件定义。因此，替换文件中必须写出 + 核心定义所进行的所有 ````\ （例如 ``app.xml`` 中的 + ``queryHelper``）。这些内容需要随 |Fess| 的每次发布进行同步。如果继续 + 调用已从核心中删除的方法，该组件定义将因 ``BeanMethodNotFoundException`` + 而初始化失败。例如，15.10 删除了 ``systemHelper`` 的 + ``addDesignJspFileName``\ ，因此调用它的替换文件会失败。这一维护成本， + 正是相比替换更推荐使用添加方式的原因。 + +REST API的添加（fess_api++.xml） +--------------------------------- + +要添加新的 REST API 端点，需要实现 ``WebApiManager``\ 。继承 +``BaseApiManager``，并在 ``@PostConstruct`` 中向 ``WebApiManagerFactory`` +注册自身。注册后的 API 管理器会在每次请求时被 ``WebApiFilter`` 调用。 +通过 ``fess_api++.xml`` 注册组件： + +.. code-block:: xml + + + + + + + + +.. code-block:: java + + package org.codelibs.fess.webapp.example.api; + + import java.io.IOException; + + import org.codelibs.fess.api.BaseApiManager; + import org.codelibs.fess.util.ComponentUtil; + + import jakarta.annotation.PostConstruct; + import jakarta.servlet.FilterChain; + import jakarta.servlet.ServletException; + import jakarta.servlet.http.HttpServletRequest; + import jakarta.servlet.http.HttpServletResponse; + + public class ExampleApiManager extends BaseApiManager { + + public ExampleApiManager() { + // 该管理器所处理路径的前缀 + setPathPrefix("/api/example"); + } + + @PostConstruct + public void register() { + ComponentUtil.getWebApiManagerFactory().add(this); + } + + @Override + public boolean matches(final HttpServletRequest request) { + // 判断该管理器是否处理此请求 + return request.getServletPath().startsWith(pathPrefix); + } + + @Override + public void process(final HttpServletRequest request, final HttpServletResponse response, + final FilterChain chain) throws IOException, ServletException { + // 处理请求并写入响应 + } + + @Override + protected void writeHeaders(final HttpServletResponse response) { + // 设置响应头（如有需要） + } + } + +作为实现示例，可以参考提供 ``/api/v1`` 的 +`fess-webapp-v1-api `__， +以及提供 ``/json`` / ``/suggest`` 的 +`fess-webapp-classic-api `__\ 。 + +搜索界面的自定义 +================ + +Web应用插件无法添加 JSP 视图。这是因为 JSP 视图存放在 |Fess| 本体 WAR 的 +``WEB-INF/view/`` 中，而插件 JAR 是挂载到类路径（``WEB-INF/classes``） +上的。如果需要修改搜索界面的设计，请使用静态主题。静态主题用于自定义 +搜索界面的设计（HTML/CSS/JavaScript）。请参考 :doc:`theme-development`。 + +构建与安装 +========== + +:: + + mvn clean package + +会在 ``target/`` 目录下生成 JAR 文件（例如 +``fess-webapp-example-15.10.0.jar``）。生成的 JAR 可以从管理界面安装， +也可以放置到 ``app/WEB-INF/plugin/`` 目录后重启 |Fess|\ 。安装步骤的详细 +信息请参考 :doc:`../admin/plugin-guide`。 + +公开插件示例 +============ + +|Fess| 项目公开了以下Web应用插件。这些插件已在 +`GitHub `__ 上公开，可作为开发参考： + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - 插件 + - 说明 + * - ``fess-webapp-example`` + - 插件实现的模板 + * - ``fess-webapp-v1-api`` + - ``/api/v1`` REST API + * - ``fess-webapp-classic-api`` + - ``/json`` / ``/suggest`` 旧版REST API + * - ``fess-webapp-mcp`` + - MCP（Model Context Protocol）服务器 + * - ``fess-webapp-bangs`` + - DuckDuckGo 风格的 bang（``!g``），把搜索发送到其他网站 + * - ``fess-webapp-semantic-search`` + - 神经搜索/向量搜索（已弃用；已被 15.10 中的核心集成功能取代） + * - ``fess-webapp-multimodal`` + - 多模态（图像、文本）搜索 + +参考信息 +======== + +- :doc:`plugin-architecture` - 插件架构 +- :doc:`theme-development` - 主题自定义 +- :doc:`../admin/plugin-guide` - 插件安装 +- :doc:`overview` - 开发者文档概述 diff --git a/zh-cn/15.10/install/fess-setup.rst b/zh-cn/15.10/install/fess-setup.rst new file mode 100644 index 000000000..b1e1229a9 --- /dev/null +++ b/zh-cn/15.10/install/fess-setup.rst @@ -0,0 +1,243 @@ +==================== +fess-setup 命令 +==================== + +``bin/fess-setup``\ （Windows 上为 ``bin\fess-setup.bat``\ ）随 |Fess| 的 ZIP 包提供。它用于安装 |Fess| 需要但发行包中未包含的内容：带有 |Fess| 所需插件的 OpenSearch、Playwright 插件所需的 Node.js、 |Fess| 插件以及静态主题。它还可以检查安装状态。 + +请在 |Fess| 目录中运行。不带参数运行时，会显示命令列表。 + +:: + + $ cd /path/to/fess-15.10.0 + $ bin/fess-setup [options] + +退出码 +====== + +.. list-table:: + :header-rows: 1 + :widths: 15 85 + + * - 退出码 + - 含义 + * - ``0`` + - 命令执行成功。 + * - ``1`` + - 命令执行失败：例如下载失败、指定的版本不存在、OpenSearch 没有面向当前平台的发行版，或 ``check`` 发现了问题。 + * - ``2`` + - 命令行有误：未知的命令，或缺少插件名称等参数。 + +安装 OpenSearch 和 Node.js +========================== + +install opensearch +------------------ + +:: + + $ bin/fess-setup install opensearch [--dest ] [--version ] [--keep-bundled-plugins] + +将此 |Fess| 支持的 OpenSearch 版本下载到 |Fess| 目录下的 ``opensearch/`` 中，安装 |Fess| 所需的 4 个插件（\ ``opensearch-analysis-fess``\ 、\ ``opensearch-analysis-extension``\ 、\ ``opensearch-minhash`` 和 ``opensearch-configsync``\ ），并向其 ``config/opensearch.yml`` 追加以下配置： + +- ``configsync.config_path``\ ，其值为该 OpenSearch 的 ``config/dictionary`` 目录 +- ``plugins.security.disabled: true`` + +此外，还会删除 |Fess| 不使用的内置插件 ``opensearch-security-analytics`` 和 ``opensearch-performance-analyzer``，与 Docker 镜像中的 OpenSearch 配置相同。下载包中不包含的插件会被跳过。 + +``opensearch.yml`` 中已有的配置不会重复追加；如果该文件中存在任何 ``plugins.security.*`` 配置，则不会追加 ``plugins.security.disabled: true``\ 。OpenSearch 目录已存在时会跳过下载，因此对已有的安装再次运行该命令时，只会追加缺少的配置。 + +命令会显示追加的每项配置，然后显示 ``bin/fess.in.sh`` 能否自动找到此 OpenSearch。当它是 |Fess| 目录下 ``opensearch/`` 中唯一带有 ``config/dictionary`` 目录的 OpenSearch 时即可找到：此时 ``bin/fess.in.sh``\ （Windows 上为 ``bin\fess.in.bat``\ ）会将 ``FESS_DICTIONARY_PATH`` 设置为该目录，对于在同一主机上运行的 OpenSearch，无需其他配置。否则，命令会显示需要设置的 ``SEARCH_ENGINE_HTTP_URL`` 和 ``FESS_DICTIONARY_PATH`` 的值，设置方法请参阅 :doc:`install-linux` 或 :doc:`install-windows`\ 。 + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 选项 + - 说明 + * - ``--dest `` + - 指定 OpenSearch 的解压目录，以代替 |Fess| 目录下的 ``opensearch/``\ 。\ ``bin/fess.in.sh`` 不会在该目录之外查找 OpenSearch。 + * - ``--version `` + - 要安装的 OpenSearch 版本。插件也会以相同版本安装。 + * - ``--keep-bundled-plugins`` + - 保留内置插件（\ ``opensearch-security-analytics``\ 、\ ``opensearch-performance-analyzer``\ ），不删除，保持下载包原样。 + +OpenSearch 仅为 Linux 和 Windows 发布官方发行版。在 macOS 等其他平台上，该命令不会下载任何内容，而是以退出码 ``1`` 结束，并建议使用 Homebrew 安装 OpenSearch 后通过 ``install opensearch-plugins`` 添加插件，或者使用 Docker。 + +.. warning:: + + 设置了 ``plugins.security.disabled: true`` 的 OpenSearch 会接受未经认证的请求。除非设置了 ``network.host``\ ，OpenSearch 只在回环地址上监听。在让它监听其他地址之前，请改为配置安全插件；详情请参阅 :doc:`security`\ 。 + +install opensearch-plugins +-------------------------- + +:: + + $ bin/fess-setup install opensearch-plugins --opensearch-home [--version ] + +向已有的 OpenSearch 安装 |Fess| 所需的 4 个插件，可代替执行 4 次该 OpenSearch 的 ``bin/opensearch-plugin install``\ 。\ ``--opensearch-home`` 为 OpenSearch 的安装目录，必须指定。\ ``--version`` 用于设置插件版本，该版本必须与 OpenSearch 版本一致。 + +此命令不会修改 ``opensearch.yml``\ 。请按照 :doc:`install-linux` 或 :doc:`install-windows` 的说明，自行添加 ``configsync.config_path`` 等配置。 + +install nodejs +-------------- + +:: + + $ bin/fess-setup install nodejs [--dest ] [--version ] + +将 Playwright 插件（用于 Playwright 爬虫的 ``fess-crawler-playwright`` 和用于缩略图的 ``fess-thumbnail-playwright``\ ）所需的 Node.js 下载到 |Fess| 目录下的 ``nodejs/`` 中。\ ``bin/fess.in.sh``\ （Windows 上为 ``bin\fess.in.bat``\ ）会在该位置找到它并设置 ``PLAYWRIGHT_NODEJS_PATH``\ 。使用 ``--dest`` 解压到 |Fess| 目录之外时，命令会改为显示需要添加到 ``bin/fess.in.sh`` 中的 ``PLAYWRIGHT_NODEJS_PATH`` 行。\ ``--version`` 用于选择其他版本的 Node.js。关于 Playwright 爬虫，请参阅 :doc:`../config/crawler-advanced`\ 。 + +管理插件 +======== + +以下命令操作 |Fess| 安装中的插件目录 ``app/WEB-INF/plugin``\ 。安装、升级或删除插件后，请重启 |Fess|\ 。也可以在管理界面的「系统 > 插件」页面管理插件；请参阅 :doc:`../admin/plugin-guide`\ 。 + +``install plugin``\ 、\ ``list plugins``\ 、\ ``list installed``\ 、\ ``upgrade plugins``\ 、\ ``remove plugin`` 和 ``check`` 可以指定 ``--dest ``\ 。它指定用来代替 ``app/WEB-INF/plugin`` 的插件目录，即存放插件 jar 的目录本身，而不是它的上级目录。相对路径相对于执行命令时的当前目录，而不是 |Fess| 目录。 ``install opensearch`` 和 ``install nodejs`` 的 ``--dest`` 则是解压归档的目录。 + +``install plugin``\ 、\ ``list plugins`` 和 ``upgrade plugins`` 可以指定 ``--repository ``\ 。指定后，版本列表、jar 及其校验和都从该单个 Maven 仓库（例如内部镜像）获取，而不使用默认的发布仓库、快照仓库和 GitHub。 + +``--repository`` 也可以指定以 ``file:///`` 开头的 URL。在无法连接互联网的服务器上，可以将 Maven 仓库的副本放到服务器上，并指定该目录。应指定包含各插件目录（ ``/maven-metadata.xml`` 等）的目录，即与默认仓库的 ``https://maven.codelibs.org/release/org/codelibs/fess/`` 相对应的位置。版本解析和校验和验证与 HTTP 仓库相同。 + +:: + + $ bin/fess-setup install plugin fess-ds-csv --repository file:///opt/maven-repo/org/codelibs/fess/ + +``http``\ 、\ ``https``\ 、\ ``file`` 以外的协议，或没有协议的 URL，会以一行错误信息被拒绝。 + +install plugin +-------------- + +:: + + $ bin/fess-setup install plugin [:]... [--version ] [--repository ] [--dest ] + +安装一个或多个 |Fess| 插件，例如 ``fess-script-groovy`` 或 ``fess-ds-git``\ 。未指定版本的名称会安装为此 |Fess| 构建的最新版本。\ ``:`` 用于固定该插件的版本，\ ``--version`` 则作为所有未指定版本的名称的版本。新版本安装完成后，将删除同一插件之前安装的版本。 + +jar 从插件的 GitHub 发布获取；发布中没有对应文件时，则从 Maven 仓库获取，并使用 Maven 仓库公布的 SHA-1 校验和进行校验。\ |Fess| 的开发版还会安装其同一版本系列的快照构建，并优先使用快照构建。 + +使用示例请参阅 :doc:`../admin/plugin-guide`\ 。 + +只能安装 |Fess| 会加载的插件类型，即名称以 ``fess-ds-``\ 、\ ``fess-ingest-``\ 、\ ``fess-script-``\ 、\ ``fess-webapp-``\ 、\ ``fess-thumbnail-``\ 、\ ``fess-crawler-``\ 、\ ``fess-llm-``\ 、\ ``fess-storage-`` 或 ``fess-sso-`` 开头的插件，与 ``list plugins`` 显示的相同。指定其他名称（ ``fess-theme-*``\ ，或 ``fess``\ 、\ ``fess-crawler`` 等库）时，不会下载任何内容，而是显示一行错误并以退出码 2 结束。多个名称中只要有一个被拒绝，就不会安装任何插件。静态主题请使用 ``install theme`` 安装。 + +list plugins +------------ + +:: + + $ bin/fess-setup list plugins [--repository ] [--dest ] + +列出为此 |Fess| 发布的插件，并用 ``(installed: )`` 标记已安装的插件。已安装但未在仓库中发布的插件（例如本地构建的 jar）会单独列出。\ |Fess| 的开发版还会列出快照仓库中的插件。 + +list installed +-------------- + +:: + + $ bin/fess-setup list installed [--dest ] + +列出已安装的插件及其版本，不访问仓库。 + +upgrade plugins +--------------- + +:: + + $ bin/fess-setup upgrade plugins [--repository ] [--dest ] + +将所有已安装的插件以适合此 |Fess| 的版本重新安装。已经是该版本的插件保持不变。\ ``app/WEB-INF/plugin`` 中的插件是为特定的 |Fess| 发布版本构建的，因此请在升级 |Fess| 后运行此命令。 + +remove plugin +------------- + +:: + + $ bin/fess-setup remove plugin ... [--dest ] + +删除指定插件已安装的 jar。未安装的名称只会给出提示，不影响退出码。 + +.. _fess-setup-offline: + +无法连接互联网的环境 +-------------------- + +``install plugin`` 、 ``list plugins`` 、 ``upgrade plugins`` 从互联网上的仓库获取插件。管理界面「系统 > 插件」的安装页面也从仓库（ ``plugin.repositories`` ）获取可安装插件的列表，因此在无法连接外部的环境中无法显示该列表。 + +在这种环境中，请带入插件的 jar 进行安装。 + +1. 在可以连接互联网的环境中，下载 |Fess| 的 ZIP 包和所需插件的 jar。jar 可以从 ``https://maven.codelibs.org/release/org/codelibs/fess///-.jar`` 获取。请选择与此 |Fess| 对应的版本（ |Fess| 15.10 则为 15.10.x）。 +2. 在目标环境中解压 ZIP，并将 jar 放入 ``app/WEB-INF/plugin/``\ 。也可以在 |Fess| 启动后，从管理界面插件安装页面的「本地」选项卡上传（参见 :doc:`../admin/plugin-guide` ）。 +3. 启动 |Fess|\ 。如果在运行中放入了 jar，请重启。 + +也可以不逐个带入插件的 jar，而是复制 Maven 仓库中所需的部分（ ``org/codelibs/fess//`` 目录）带入服务器，然后指定 ``--repository file:///...`` 使用 ``install plugin`` 安装。这种情况下同样会验证校验和。 + +管理主题 +======== + +这些命令作用于 |Fess| 安装目录下的 ``app/themes``\ 。安装或删除主题后，请重启 |Fess|\ ，或在 [系统 > 主题] 页面点击 [重新加载]。主题也可以从该页面上传，参见 :doc:`../admin/theme-guide`\ 。 + +``install theme``\ 、\ ``list themes`` 和 ``remove theme`` 也可以同样指定 ``--dest ``\ ，用来指定代替 ``app/themes`` 的主题目录。 + +主题的版本表示该主题面向的 |Fess| 系列，即 ``15.10.0`` 是面向 |Fess| 15.10 的主题。因此只指定名称而不带版本时，与插件一样会选择为当前 |Fess| 构建的主题。 + +install theme +------------- + +:: + + $ bin/fess-setup install theme [:]... [--version ] [--repository ] [--dest ] + +安装一个或多个静态主题，例如 ``docuforge`` 或 ``voicebox``\ 。不带版本的名称会安装为当前 |Fess| 构建的最新版本。 ``:`` 固定该主题的版本， ``--version`` 适用于所有没有自带版本的名称。 + +归档会与 Maven 仓库公开的 SHA-1 校验和比对，并解压到 ``app/themes/``\ 。同名主题若已安装，会作为备份保留，保留期与从管理界面替换时相同（默认 7 天， ``theme.upload.attic.retention.days``\ ）。 + +下载、解压和清单检查都在触碰已安装内容之前完成，因此即使安装失败，已有的主题也会原样保留。 ``theme.yml`` 中名称不符的归档会被拒绝。 + +list themes +----------- + +:: + + $ bin/fess-setup list themes [--repository ] [--dest ] + +列出为当前 |Fess| 公开的主题，并为已安装的主题标注 ``(installed: )``\ 。已安装但未出现在仓库列表中的主题会单独显示。 + +该列表读取自仓库的目录索引，索引是定期生成的，因此可能无法读取。此时命令会报告尝试过的 URL，并继续显示已安装的主题：无论索引中是否列出，只要指定名称就可以安装主题。 + +remove theme +------------ + +:: + + $ bin/fess-setup remove theme ... [--dest ] + +从 ``app/themes`` 中删除指定的主题，每个都会在保留期内作为备份保留。未安装的名称会被报告，但不会改变退出码。 + +如果被删除的主题是默认主题，在选择其他主题之前， |Fess| 会回退到内置的 ``bootstrap`` 主题。 + +检查安装状态 +============ + +list +---- + +:: + + $ bin/fess-setup list + +显示 ``install`` 下载的组件（\ ``opensearch`` 和 ``nodejs``\ ）及各自的版本。 + +check +----- + +:: + + $ bin/fess-setup check [--url ] [--playwright] [--dest ] + +检查安装状态，每个检查项输出一行，并标记为 ``OK``\ 、\ ``WARN`` 或 ``FAIL``\ ： + +- 搜索引擎：能否连接、版本（各节点报告的版本不一致时为警告）、是否安装了 |Fess| 所需的 4 个插件，以及 ``configsync`` 是否响应。 +- |Fess|\ ：插件目录是否存在且可写、每个已安装的插件（为其他 |Fess| 发布版本构建的插件，以及安装了两个版本的插件，均为失败），以及 |Fess| 目录下的 ``nodejs/`` 中是否安装了 Node.js。 + +搜索引擎的 URL 为 ``--url``\ ，未指定时为环境变量 ``SEARCH_ENGINE_HTTP_URL``\ ，仍未设置时为 ``http://localhost:9200``\ 。\ ``bin/fess-setup`` 不读取 ``bin/fess.in.sh``\ ，因此当 OpenSearch 位于其他位置时，请指定 ``--url``\ 。缺少 Node.js 时只会报告，但指定 ``--playwright`` 后会视为失败。 + +没有检查项失败时，即使有警告，命令也以退出码 ``0`` 结束；否则以退出码 ``1`` 结束。 diff --git a/zh-cn/15.10/install/index.rst b/zh-cn/15.10/install/index.rst new file mode 100644 index 000000000..ffa38aabf --- /dev/null +++ b/zh-cn/15.10/install/index.rst @@ -0,0 +1,24 @@ +|Fess| 安装指南 +===================== + +说明如何在 Linux、Windows 或 Docker 上安装并启动 |Fess|，\ +并涵盖运行要求、安全设置、升级与故障排查。 + +.. toctree:: + :maxdepth: 2 + :caption: 目录 + + intro + prerequisites + install + install-linux + install-windows + install-docker + fess-setup + run + security + upgrade + uninstall + troubleshooting + + diff --git a/zh-cn/15.10/install/install-docker.rst b/zh-cn/15.10/install/install-docker.rst new file mode 100644 index 000000000..45d1202f6 --- /dev/null +++ b/zh-cn/15.10/install/install-docker.rst @@ -0,0 +1,608 @@ +======================== +使用 Docker 安装（详细） +======================== + +本页面说明使用 Docker 和 Docker Compose 安装 |Fess| 的步骤。 +使用 Docker 可以简单快速地构建 |Fess| 环境。 + +前提条件 +======== + +- 满足 :doc:`prerequisites` 中所述的系统要求 +- 已安装 Docker 20.10 或更高版本 +- 已安装 Docker Compose 2.0 或更高版本 + +确认 Docker 安装 +================ + +使用以下命令确认 Docker 和 Docker Compose 的版本。 + +:: + + $ docker --version + $ docker compose version + +.. note:: + + 如果使用旧版本的 Docker Compose，请使用 ``docker-compose`` 命令。 + 本文档使用新的 ``docker compose`` 命令格式。 + +关于 Docker 镜像 +================ + +使用 Docker Compose 启动 |Fess| 后，将运行以下 2 个容器。 + +- **Fess** (``fess01``)：全文搜索系统本体 +- **OpenSearch** (``search01``)：搜索引擎 + +官方 Docker 镜像发布于 `GitHub Container Registry `__\ 。 +Compose 文件及启动步骤由 `docker-fess `__ 仓库管理。 + +步骤 1: 获取 Docker Compose 文件 +================================ + +使用 Docker Compose 启动需要以下文件。 + +方法 1: 单独下载文件 +-------------------- + +下载以下文件： + +:: + + $ mkdir fess-docker + $ cd fess-docker + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose.yaml + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose-opensearch3.yaml + +方法 2: 使用 Git 克隆仓库 +------------------------- + +如果已安装 Git，也可以克隆整个仓库： + +:: + + $ git clone --depth 1 --branch v15.10.0 https://github.com/codelibs/docker-fess.git + $ cd docker-fess/compose + +步骤 2: 确认 Docker Compose 文件 +================================ + +``compose.yaml`` 的内容 +----------------------- + +``compose.yaml`` 包含 Fess 本体（``fess01`` 服务）的配置。 + +主要配置项： + +- **端口号**：Fess Web 界面的端口（默认：8080） +- **环境变量**：OpenSearch 的连接地址 (``SEARCH_ENGINE_HTTP_URL``)、词典文件路径 (``FESS_DICTIONARY_PATH``) 等 +- **启动顺序**：已通过 ``depends_on`` 设置为在 OpenSearch (``search01``) 变为正常状态后再启动 + +``compose-opensearch3.yaml`` 的内容 +----------------------------------- + +``compose-opensearch3.yaml`` 包含搜索引擎（``search01`` 服务，OpenSearch）的配置。 + +主要配置项： + +- **OpenSearch 镜像**：使用的 OpenSearch 镜像（``ghcr.io/codelibs/fess-opensearch``） +- **内存设置**：JVM 堆大小 +- **卷**：用于数据持久化的卷（``search01_data``：索引数据，``search01_dictionary``：词典文件） + +自定义配置（可选） +------------------ + +如需更改默认设置，请编辑 ``compose.yaml``\ 。 + +示例：更改端口号:: + + services: + fess01: + ports: + - "9080:8080" # 映射到主机的 9080 端口 + +示例：更改内存设置:: + + services: + fess01: + environment: + - "FESS_HEAP_SIZE=2g" # 将 Fess 的堆大小设置为 2GB + +镜像类型与缩略图 +---------------- + +|Fess| 的 Docker 镜像有多种类型，区别在于标签后缀（ ``-noble`` 、 ``-al2023`` 等）。没有后缀的默认镜像（基于 Alpine）不包含生成图片、PDF 和 Office 文档缩略图所需的外部工具（ImageMagick、poppler-utils、unoconv 和 LibreOffice）。使用该镜像时，只有 HTML 页面会生成缩略图，图片、PDF 和 Office 文档不会生成缩略图。 + +如果需要这些缩略图，请在 ``compose.yaml`` 的 ``image`` 中指定带有 ``-noble`` 后缀、已包含这些工具的标签。 + +:: + + services: + fess01: + image: ghcr.io/codelibs/fess:15.10.0-noble + +各镜像的支持情况如下。 + +.. list-table:: + :header-rows: 1 + :widths: 40 30 30 + + * - 标签 + - 图片和 PDF + - Office 文档 + * - ``15.10.0-noble`` + - 会生成 + - 会生成 + * - ``15.10.0-al2023`` + - 会生成 + - 不会生成 + * - ``15.10.0`` 、 ``15.10.0-slim`` 、 ``15.10.0-slim-noble`` 、 ``15.10.0-slim-al2023`` + - 不会生成 + - 不会生成 + +无论使用哪种镜像，HTML 页面的缩略图都是根据页面中的图片生成的。要显示缩略图，还需要在管理页面的常规设置中启用缩略图显示。详情请参阅 :doc:`../config/crawler-thumbnail` 。 + +步骤 3: 启动 Docker 容器 +======================== + +基本启动 +-------- + +使用以下命令启动 Fess 和 OpenSearch： + +:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +.. note:: + + - 使用 ``-f`` 选项指定多个 Compose 文件 + - 使用 ``-d`` 选项在后台运行 + +确认启动日志:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f + +按 ``Ctrl+C`` 可退出日志显示。 + +确认启动 +-------- + +确认容器状态:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps + +请确认以下容器正在运行： + +- ``fess01`` +- ``search01`` + +.. tip:: + + 启动可能需要几分钟。首先 OpenSearch (``search01``) 变为正常状态后，Fess (``fess01``) 才会启动。 + 可以通过 ``docker compose ... ps`` 确认各容器的状态，``fess01`` 启动后即可在浏览器中访问 http://localhost:8080/。 + +步骤 4: 通过浏览器访问 +====================== + +启动完成后，访问以下 URL： + +- **搜索页面**：http://localhost:8080/ +- **管理页面**：http://localhost:8080/admin + +搜索页面使用 |Fess| 内置的静态主题 ``bootstrap`` 。要更改其外观， +请参阅 :doc:`../admin/theme-guide` 。 + +默认管理员账号： + +- 用户名：``admin`` +- 密码：``admin`` + +.. warning:: + + **关于安全的重要提示** + + 在生产环境中，请务必更改管理员密码。 + 详情请参阅 :doc:`security`。 + +启用 AI 搜索模式（LLM 插件） +============================ + +自 |Fess| 15.10 起，AI 搜索模式（RAG Chat）功能已拆分为 ``fess-llm-*`` 插件。 +官方 `docker-fess `__ 仓库中附带了面向主要 LLM 提供商的 overlay 文件。 + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Overlay + - 用途 + * - ``compose-ollama.yaml`` + - Ollama（本地 LLM，会启动额外的 ``ollama01`` 服务） + * - ``compose-gemini.yaml`` + - Google Gemini（云端 API） + * - ``compose-openai.yaml`` + - OpenAI（云端 API） + +每个 overlay 都会通过 ``FESS_PLUGINS`` 自动获取相应的插件，并在 ``FESS_JAVA_OPTS`` 中设置 +``-Dfess.config.rag.chat.enabled=true`` 以启用 RAG Chat。 +对于使用云端 API 的 Gemini 和 OpenAI，还需通过 ``-Dfess.system.rag.llm.name`` 指定所使用的提供商， +并设置 API 密钥 (``rag.llm..api.key``) 和模型 (``rag.llm..model``)。 +Ollama 会直接使用 ``rag.llm.name`` 的默认值 (``ollama``)，因此无需显式指定， +只需设置连接地址 (``rag.llm.ollama.api.url``)。 + +使用 Gemini 的示例:: + + $ export GEMINI_API_KEY="AIzaSy..." + $ docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-gemini.yaml up -d + +使用 OpenAI 的示例:: + + $ export OPENAI_API_KEY="sk-..." + $ docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-openai.yaml up -d + +.. note:: + + 使用的模型可以通过 ``GEMINI_MODEL`` 和 ``OPENAI_MODEL`` 环境变量更改 + （默认值分别为 ``gemini-2.5-flash`` 和 ``gpt-5-mini``）。 + +使用 Ollama 的示例:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-ollama.yaml up -d + $ docker exec -it ollama01 ollama pull gpt-oss:20b + +.. warning:: + + ``compose-ollama.yaml`` 中的 ``ollama01`` 服务默认配置为使用 NVIDIA GPU + （需要安装 `NVIDIA Container Toolkit `__）。 + 如果要在未配备 GPU 的环境中运行，请删除或注释掉 ``compose-ollama.yaml`` 中的 ``deploy:`` 块（``reservations`` 下的 GPU 指定部分）。 + +.. tip:: + + 启动后，可以在管理界面「系统 > 全局设置」的设置页面中更改所使用的 LLM 提供商 (``rag.llm.name``) + 以及各提供商专属的设置。但这些更改会保存到容器内的配置文件中， + 一旦重新创建容器（先执行 ``docker compose down`` 再执行 ``up``），这些更改就会丢失。 + 如需持久化保存设置，请像上面的示例一样在 Compose 文件的 ``FESS_JAVA_OPTS`` 中指定。 + +数据持久化 +========== + +|Fess| 的数据（索引、抓取的文档、用户信息、设置等）全部保存在 OpenSearch 中。 +这些数据会持久化保存在 OpenSearch 的卷中，因此即使删除容器，数据也会被保留。 +Fess 本体（``fess01``）的容器本身不保存状态，也没有专用的卷。 + +确认卷:: + + $ docker volume ls + +``compose-opensearch3.yaml`` 中定义的主要卷： + +- ``search01_data``：OpenSearch 的索引数据（包含 Fess 的全部数据） +- ``search01_dictionary``：词典文件 + +.. note:: + + Docker Compose 的卷名会带有项目名称（默认为 Compose 文件所在目录的名称）作为前缀。 + 例如在 ``compose`` 目录中启动时，实际的卷名会类似于 ``compose_search01_data``\ 。 + +.. important:: + + 即使删除容器，卷也不会被删除。 + 要删除卷，需要显式执行 ``docker volume rm`` 命令。 + +停止 Docker 容器 +================ + +停止容器:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop + +停止并删除容器:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +.. warning:: + + ``down`` 命令会删除容器，但不会删除卷。 + 如果还要删除卷（如 ``search01_data`` 等），请添加 ``-v`` 选项:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down -v + + **注意**：执行此命令会删除保存在 OpenSearch 中的所有数据。 + +高级配置 +======== + +自定义环境变量 +-------------- + +通过在 ``compose.yaml`` 中添加或更改环境变量，可以进行详细配置。 + +主要环境变量： + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - 环境变量 + - 说明 + * - ``FESS_HEAP_SIZE`` + - Fess 的 JVM 堆大小（Docker 镜像的默认值：512m） + * - ``FESS_JAVA_OPTS`` + - 指定额外的 JVM 选项（例如通过 ``-Dfess.config.*`` 覆盖配置等） + * - ``FESS_PLUGINS`` + - 启动时自动安装的插件（以空格分隔的 ``name:version`` 格式。例：``fess-ds-wikipedia:15.10.0``） + * - ``SEARCH_ENGINE_HTTP_URL`` + - OpenSearch 的 HTTP 端点（``compose.yaml`` 的默认值：``http://search01:9200``） + * - ``SEARCH_ENGINE_TYPE`` + - 搜索引擎的类型（ ``default`` 、 ``vanilla`` 、 ``aws`` ）。 ``vanilla`` 需要 Fess 15.10 及更高版本的镜像，更早的镜像请使用 ``cloud`` （请参阅 :doc:`../config/search-engine-type` ）。在 15.8 镜像中，只有 ``-noble`` 版本会把该值传递给 Fess 。 + * - ``SEARCH_ENGINE_USERNAME`` / ``SEARCH_ENGINE_PASSWORD`` + - 连接到已启用认证的 OpenSearch 时使用的凭据 + * - ``FESS_DICTIONARY_PATH`` + - 词典文件的路径（与 OpenSearch 共享的目录） + * - ``FESS_PORT`` + - Fess 在容器内监听的端口（默认值：8080） + +示例:: + + services: + fess01: + environment: + - "FESS_HEAP_SIZE=4g" + +.. note:: + + 如需更改时区，请在 ``FESS_JAVA_OPTS`` 中像 ``-Duser.timezone=Asia/Tokyo`` 这样指定。 + +如何应用配置文件 +---------------- + +|Fess| 的详细设置写在 ``fess_config.properties`` 文件中。 +在 Docker 镜像中，``fess_config.properties`` 位于容器内的 ``/etc/fess``\ 。 +在 Docker 环境中应用设置有以下方法。 + +方法 1: 挂载配置文件 +~~~~~~~~~~~~~~~~~~~~ + +由于 ``/etc/fess`` 中还包含 Fess 运行所需的其他配置文件，如果直接用挂载替换整个目录，会导致启动失败。 +请改用会被添加到类路径开头的覆盖目录 ``/opt/fess``\ 。该目录初始状态为空。 + +1. 在主机端创建用于存放配置文件的目录:: + + $ mkdir -p /path/to/fess-config + +2. 获取配置文件模板（仅首次需要）:: + + $ curl -o /path/to/fess-config/fess_config.properties https://raw.githubusercontent.com/codelibs/fess/refs/tags/fess-15.10.0/src/main/resources/fess_config.properties + +3. 编辑 ``/path/to/fess-config/fess_config.properties`` 并写入所需的设置:: + + # 示例 + crawler.document.cache.enabled=false + adaptive.load.control=20 + query.facet.fields=label,host + +4. 在 ``compose.yaml`` 的 ``fess01`` 服务中添加卷挂载:: + + services: + fess01: + volumes: + - /path/to/fess-config/fess_config.properties:/opt/fess/fess_config.properties + +5. 启动容器:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +.. note:: + + 由于 ``/opt/fess`` 会被添加到类路径开头，放置在此处的 ``fess_config.properties`` + 会优先于镜像自带的 ``/etc/fess/fess_config.properties``\ 。 + 属性文件是按文件为单位加载的，不会按配置项逐项合并。 + 文件中缺少的配置项不会导致 |Fess| 无法启动：它会使用该版本自带的默认值，并为每个缺少的配置项在日志中输出一条警告。 + 因此，只包含想要更改的配置项的文件同样可以使用。若要避免这些警告，请像步骤 2 那样从完整文件开始。 + 如果只想更改部分配置项，请使用下面的「方法 2」。 + 如果同一配置项既写在此文件中，又通过「方法 2」的 ``-Dfess.config.`` 指定，则使用 ``-D`` 指定的值。 + +方法 2: 通过系统属性进行设置 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +可以通过环境变量，以系统属性的形式覆盖 ``fess_config.properties`` 中的配置项。 + +``fess_config.properties`` 中记载的配置项（例如 ``crawler.document.cache.enabled=false``）， +可以用 ``-Dfess.config.配置项名称=值`` 的格式指定。 + +在 ``compose.yaml`` 的 ``fess01`` 服务的环境变量中添加 ``FESS_JAVA_OPTS``:: + + services: + fess01: + environment: + - "FESS_JAVA_OPTS=-Dfess.config.crawler.document.cache.enabled=false -Dfess.config.adaptive.load.control=20 -Dfess.config.query.facet.fields=label,host" + +.. note:: + + ``-Dfess.config.`` 之后的部分对应 ``fess_config.properties`` 中的配置项名称。 + 如果只想覆盖部分配置项，使用这种方法更简单。 + +连接到外部 OpenSearch +--------------------- + +如果要使用现有的 OpenSearch 集群，请不使用 ``compose-opensearch3.yaml``，仅通过 ``compose.yaml`` 启动，并更改连接目标。 + +1. 启动时不指定 ``compose-opensearch3.yaml``:: + + $ docker compose -f compose.yaml up -d + +2. 在 ``compose.yaml`` 的 ``fess01`` 服务中设置连接目标:: + + environment: + - "SEARCH_ENGINE_HTTP_URL=http://your-opensearch-host:9200" + +.. note:: + + 如果要连接到已启用认证的 OpenSearch，还需要指定 ``SEARCH_ENGINE_USERNAME`` 和 ``SEARCH_ENGINE_PASSWORD``\ 。 + +其他 Overlay 与构成 +------------------- + +``docker-fess`` 仓库中除上述内容外，还包含按用途划分的 Compose 文件和目录。 + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - 文件 / 目录 + - 用途 + * - ``compose-dashboards3.yaml`` + - 添加 OpenSearch Dashboards（端口 5601，用于数据可视化） + * - ``compose-minio.yaml`` + - 添加 MinIO（对象存储），并将其用作 Fess 存储功能的保存位置 + * - ``vanilla/`` + - 与不含 CodeLibs 插件的原生 OpenSearch 组合使用的构成（ ``SEARCH_ENGINE_TYPE=vanilla`` ，需要 Fess 15.10 及更高版本的镜像，更早的镜像请使用 ``cloud`` ）。词典管理等部分功能不可用（请参阅 :doc:`../config/search-engine-type` ） + * - ``snapshot/`` + - 使用开发版（snapshot）镜像的构成（包括集群构成以及与 Elasticsearch 8 的组合） + * - ``multi-instance/`` + - 启动多个共享同一个 OpenSearch 的 Fess 实例的构成 + +Docker 网络配置 +--------------- + +如需与多个服务联动，可以使用自定义网络。 + +示例:: + + networks: + fess-network: + driver: bridge + + services: + fess01: + networks: + - fess-network + +使用 Docker Compose 的生产运维 +============================== + +在生产环境中使用 Docker Compose 时的推荐设置： + +1. **设置资源限制**:: + + deploy: + resources: + limits: + cpus: '2.0' + memory: 4G + reservations: + cpus: '1.0' + memory: 2G + +2. **设置重启策略**:: + + restart: unless-stopped + +3. **日志设置**:: + + logging: + driver: "json-file" + options: + max-size: "10m" + max-file: "3" + +4. **启用安全设置** + + 启用 OpenSearch 的安全插件，并配置适当的认证。 + 详情请参阅 :doc:`security`。 + +故障排除 +======== + +容器无法启动 +------------ + +1. 确认日志:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs + +2. 确认端口号是否冲突:: + + $ sudo ss -tuln | grep 8080 + $ sudo ss -tuln | grep 9200 + +3. 确认磁盘空间:: + + $ df -h + +内存不足错误 +------------ + +如果 OpenSearch 因内存不足而无法启动，需要增大 ``vm.max_map_count``\ 。 + +Linux 的情况:: + + $ sudo sysctl -w vm.max_map_count=262144 + +永久设置:: + + $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf + $ sudo sysctl -p + +数据初始化 +---------- + +删除所有数据并恢复到初始状态:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down -v + $ docker volume prune + +.. warning:: + + 执行此命令会彻底删除所有数据。 + +下一步 +====== + +安装完成后，请参阅以下文档： + +- :doc:`run` - |Fess| 的启动与初次设置 +- :doc:`security` - 生产环境的安全设置 +- :doc:`troubleshooting` - 故障排除 + +常见问题 +======== + +Q: 下载镜像需要多少磁盘空间？ +----------------------------- + +A：Fess 和 OpenSearch 的镜像会在首次启动时下载，合计需要几 GB 左右的磁盘空间。 +根据网络环境的不同，下载可能需要较长时间。 + +Q: 可以在 Kubernetes 上运行吗？ +------------------------------- + +A：可以。可以使用 ``kompose`` 等工具将 Docker Compose 文件转换为 Kubernetes 清单， +也可以自行编写清单进行运维（官方未提供 Helm chart）。 + +Q: 如何更新容器？ +----------------- + +A：按以下步骤进行更新： + +1. 获取最新的 Compose 文件 +2. 停止容器:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +3. 获取新镜像:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull + +4. 启动容器:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +Q: 可以配置多节点吗？ +--------------------- + +A：可以。可以参考 ``docker-fess`` 仓库中的 ``snapshot/compose-cluster.yaml``，将 OpenSearch 配置为多个节点， +也可以参考 ``multi-instance/``，配置多个共享同一个 OpenSearch 的 Fess 实例。 +不过，在生产环境中建议使用 Kubernetes 等编排工具。 diff --git a/zh-cn/15.10/install/install-linux.rst b/zh-cn/15.10/install/install-linux.rst new file mode 100644 index 000000000..f3e53e74e --- /dev/null +++ b/zh-cn/15.10/install/install-linux.rst @@ -0,0 +1,546 @@ +================================== +在 Linux 上安装（详细步骤） +================================== + +本页面说明在 Linux 环境中安装 |Fess| 的步骤。 +支持 ZIP、RPM、DEB 各种包格式。 + +.. note:: + + |Fess| 不包含搜索引擎。需要单独准备 OpenSearch 服务器， + 下面的步骤将进行构建。 + +前提条件 +============ + +- 满足 :doc:`prerequisites` 中描述的系统要求 +- 已安装 Java 21 +- OpenSearch 3.9.0 可用（或新安装） + +选择安装方法 +================ + +在 Linux 环境中，可以从以下安装方法中选择： + +.. list-table:: + :header-rows: 1 + :widths: 20 40 40 + + * - 方式 + - 推荐环境 + - 特点 + * - ZIP + - 开发环境、需要定制化的环境 + - 可解压到任意目录 + * - RPM + - RHEL、CentOS、Fedora 系 + - 可通过 systemd 进行服务管理 + * - DEB + - Debian、Ubuntu 系 + - 可通过 systemd 进行服务管理 + +运行 OpenSearch 所需的系统设置 +================================== + +为了让 OpenSearch 在 Linux 上稳定运行，需要设置以下内核参数和资源限制。 +这些设置主要在 TAR.GZ 版（手动安装 OpenSearch 的情况）中是必需的。 +在 RPM / DEB 版中，OpenSearch 和 |Fess| 的软件包会通过 systemd 设置文件描述符数量等参数，但由于 ``vm.max_map_count`` 属于主机侧的内核设置，因此无论采用哪种方式都请进行确认。 + +虚拟内存最大映射数量 +------------------------ + +由于 OpenSearch 会使用大量内存映射，需要将 ``vm.max_map_count`` 设置为 ``262144`` 以上。 + +临时设置的情况:: + + $ sudo sysctl -w vm.max_map_count=262144 + +永久设置的情况:: + + $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf + $ sudo sysctl -p + +文件描述符数量 +------------------ + +手动运行 OpenSearch 时（TAR.GZ 版），需要将运行 OpenSearch 的用户的文件描述符数量上限设置为 ``65535`` 以上。 + +在 ``/etc/security/limits.conf`` 中添加以下内容（请将 ``opensearch`` 替换为运行 OpenSearch 的用户名）:: + + opensearch - nofile 65535 + +.. note:: + + 在 RPM / DEB 版中，由于 systemd 的服务定义中已设置文件描述符数量上限，因此不需要进行此设置。 + +使用 ZIP 版安装 +====================== + +步骤 1: 安装 OpenSearch +--------------------------- + +.. important:: + + 请以普通用户而非 ``root`` 安装和运行 OpenSearch：OpenSearch 拒绝以 ``root`` 身份启动。下面的 ``bin/fess-setup`` 也请以该用户运行，以使其解压的文件归该用户所有。如果以 ``root`` 启动已经被拒绝，请参阅 :doc:`run`\ 。 + +.. tip:: + + |Fess| 附带的 ``bin/fess-setup`` 可以一条命令完成下面的步骤 1 到 3：将 OpenSearch 下载并解压到 |Fess| 目录下的 ``opensearch/`` 中，安装所需插件，并向其 ``config/opensearch.yml`` 添加 ``configsync.config_path`` 和 ``plugins.security.disabled: true``\ 。请先按照步骤 2 的说明解压 |Fess| 的 ZIP。 + + :: + + $ cd /path/to/fess-15.10.0 + $ bin/fess-setup install opensearch + + ``bin/fess.in.sh`` 会找到以这种方式安装的 OpenSearch 并自动设置 ``FESS_DICTIONARY_PATH``\ ，因此只要 OpenSearch 在同一主机上运行，步骤 2 的「配置 Fess」就无需修改。命令会显示它添加的配置，以及 ``bin/fess.in.sh`` 能否找到该安装。在让 OpenSearch 监听 ``localhost`` 以外的地址之前，请阅读第 3 步中的警告。 + + 如果想逐步确认，或者要使用已有的 OpenSearch，请按照下面的步骤操作。 + 若只需向已有的 OpenSearch 安装插件，请使用 + ``bin/fess-setup install opensearch-plugins --opensearch-home /path/to/opensearch``\ 。 + 所有命令请参阅 :doc:`fess-setup`\ 。 + +.. note:: + + OpenSearch 没有官方的 macOS 发行版，因此在 macOS 上 ``bin/fess-setup install opensearch`` 会以错误结束。请使用 Homebrew 安装 OpenSearch 并通过 ``bin/fess-setup install opensearch-plugins`` 添加插件，或者改用 :doc:`install-docker`:: + + $ brew install opensearch + $ bin/fess-setup install opensearch-plugins --opensearch-home $(brew --prefix opensearch) + + 然后按照第 3 步配置该 OpenSearch，并按照步骤 2 的「配置 Fess」设置 ``FESS_DICTIONARY_PATH``\ 。 + +1. 下载 OpenSearch + + 从 `Download OpenSearch `__ 下载 TAR.GZ 版。 + + :: + + $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.9.0/opensearch-3.9.0-linux-x64.tar.gz + $ tar -xzf opensearch-3.9.0-linux-x64.tar.gz + $ cd opensearch-3.9.0 + + 在 arm64（aarch64）机器上，请将上述文件名中的 ``linux-x64`` 替换为 ``linux-arm64``\ （例如 ``opensearch-3.9.0-linux-arm64.tar.gz``）。 + + .. note:: + + 此示例使用 OpenSearch 3.9.0。 + |Fess| 15.10 支持 OpenSearch 3.9.0。 + +2. 安装 OpenSearch 插件 + + 安装 |Fess| 所需的插件。 + + :: + + $ cd /path/to/opensearch-3.9.0 + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ ./bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + + .. important:: + + 插件版本必须与 OpenSearch 版本一致。 + 在上述示例中，所有版本都指定为 3.9.0。 + + |Fess| 的 4 个插件发布在 maven.codelibs.org 上，因此通过 URL 指定。 ``opensearch-plugin install`` 的 ``groupId:artifactId:version`` 形式只查找 Maven Central。 + +3. 配置 OpenSearch + + 在 ``config/opensearch.yml`` 中添加以下配置。 + + :: + + # 配置同步路径（使用绝对路径指定） + configsync.config_path: /path/to/opensearch-3.9.0/config/dictionary/ + + # 禁用安全插件（仅限开发环境） + plugins.security.disabled: true + + .. important:: + + ``configsync.config_path`` 请指定 OpenSearch 配置目录（本例中为 ``/path/to/opensearch-3.9.0/config/``\ ）下的目录。 + 从 OpenSearch 3.8.0 开始，如果词典文件位于配置目录之外，OpenSearch 会拒绝创建索引。 + 如果指定 ``/path/to/opensearch-3.9.0/data/config/`` 等配置目录之外的位置，|Fess| 将无法创建索引，也无法启动。 + + .. warning:: + + **关于安全的重要注意事项** + + ``plugins.security.disabled: true`` 仅应在开发环境或测试环境中使用。 + 在生产环境中，应启用 OpenSearch 的安全插件并进行适当的认证和授权配置。 + 在 OpenSearch 2.12 及更高版本中启用安全插件时，首次启动需要设置管理员密码（环境变量 ``OPENSEARCH_INITIAL_ADMIN_PASSWORD``）。 + 详情请参阅 :doc:`security`。 + + .. tip:: + + 请根据环境调整集群名称和网络设置等其他配置。 + 配置示例:: + + cluster.name: fess-cluster + node.name: fess-node-1 + network.host: 0.0.0.0 + discovery.type: single-node + + .. tip:: + + OpenSearch 的堆大小通过 ``config/jvm.options`` 中的 ``-Xms`` / ``-Xmx`` 进行设置。 + 建议将 ``-Xms`` 和 ``-Xmx`` 设置为相同的值，以不超过可用物理内存的一半且低于 32GB 为宜。 + +步骤 2: 安装 Fess +--------------------- + +1. 下载和解压 Fess + + 从 `下载站点 `__ 下载 ZIP 版。 + + :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.zip + $ unzip fess-15.10.0.zip + $ cd fess-15.10.0 + + .. note:: + + 请选择路径中不包含空格的目录（macOS 上同样如此）。路径中包含空格时，``bin/fess`` 无法启动，并输出 ``Could not find or load main class``\ 。 + +2. 配置 Fess + + 到 OpenSearch 的连接信息位于 ``bin/fess.in.sh`` 中。对于通过 ``bin/fess-setup install opensearch`` 安装到 |Fess| 目录下的 ``opensearch/`` 中、并在同一主机上运行的 OpenSearch，无需修改此文件：\ ``SEARCH_ENGINE_HTTP_URL`` 默认为 ``http://localhost:9200``\ ，\ ``FESS_DICTIONARY_PATH`` 会被设置为该 OpenSearch 的 ``config/dictionary`` 目录。 + + 在以下任一情况下，请编辑 ``bin/fess.in.sh``\ ： + + - 通过其他方式安装了 OpenSearch，例如按照上面的第 1 到 3 步或使用 Homebrew，或者使用 ``--dest`` 安装到了 |Fess| 目录之外。 + - |Fess| 目录下的 ``opensearch/`` 中有多个通过 ``bin/fess-setup`` 安装的 OpenSearch，例如两个版本。\ ``bin/fess.in.sh`` 无法判断正在使用哪一个，因此会显示警告，并且不设置 ``FESS_DICTIONARY_PATH``\ 。 + - OpenSearch 在其他主机或端口上运行。 + + :: + + $ vi bin/fess.in.sh + + 在文件开头附近，删除 ``FESS_DICTIONARY_PATH`` 行行首的 ``#`` 并设置路径，必要时更改 ``SEARCH_ENGINE_HTTP_URL`` 行中的 URL。 + + 修改前（默认状态，省略注释行）:: + + SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://localhost:9200} + #FESS_DICTIONARY_PATH=/var/lib/opensearch/config/ + + 修改后:: + + SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://localhost:9200} + FESS_DICTIONARY_PATH=/path/to/opensearch-3.9.0/config/dictionary/ + + .. note:: + + - ``FESS_DICTIONARY_PATH`` 请设置与 OpenSearch 的 ``opensearch.yml`` 中指定的 ``configsync.config_path`` 相同的路径。未设置时，|Fess| 无法创建索引，也无法启动。 + - 如果 OpenSearch 在其他主机上运行，请将 ``SEARCH_ENGINE_HTTP_URL`` 行中的 URL 更改为该主机。例: ``SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://192.168.1.100:9200}``\ 。此时 ``FESS_DICTIONARY_PATH`` 为该服务器的 ``configsync.config_path``\ 。 + - 也可以不编辑文件，而在启动 |Fess| 的环境中 export 这两个变量。export 的 ``SEARCH_ENGINE_HTTP_URL`` 优先于文件中的 URL；只要文件中的对应行保持注释状态，就会使用 export 的 ``FESS_DICTIONARY_PATH``\ 。 + - 请勿新增 ``SEARCH_ENGINE_HTTP_URL=...`` 行，而应编辑已有的行。 + + .. tip:: + + 要更改 |Fess| 的堆大小，请编辑 ``bin/fess.in.sh`` 中的 ``FESS_MIN_MEM``\ （默认：``256m``）和 ``FESS_MAX_MEM``\ （默认：``2g``），或设置环境变量 ``FESS_HEAP_SIZE``\ 。 + +3. 确认安装 + + 确认配置文件已正确编辑:: + + $ grep "SEARCH_ENGINE_HTTP_URL" bin/fess.in.sh + $ grep "FESS_DICTIONARY_PATH" bin/fess.in.sh + + OpenSearch 启动后，\ ``bin/fess-setup check`` 会报告能否连接到 OpenSearch、是否安装了 |Fess| 所需的插件，以及 ``configsync`` 是否响应。没有检查项失败时，它以退出码 ``0`` 结束。当 OpenSearch 不在 ``http://localhost:9200`` 时，请指定 ``--url``\ 。 + +步骤 3: 启动 +---------------- + +关于启动步骤，请参阅 :doc:`run`。 + +使用 RPM 版安装 +=================== + +RPM 版用于 Red Hat Enterprise Linux、CentOS、Fedora 等基于 RPM 的 Linux 发行版。 + +步骤 1: 安装 OpenSearch +--------------------------- + +1. 下载和安装 OpenSearch RPM + + 从 `Download OpenSearch `__ 下载 RPM 包并安装。 + + :: + + $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.9.0/opensearch-3.9.0-linux-x64.rpm + $ sudo rpm -ivh opensearch-3.9.0-linux-x64.rpm + + 在 arm64（aarch64）机器上，请将上述文件名中的 ``linux-x64`` 替换为 ``linux-arm64``\ （例如 ``opensearch-3.9.0-linux-arm64.rpm``）。 + + 或者，也可以添加仓库后进行安装。 + 详情请参阅 `Installing OpenSearch `__\ 。 + +2. 安装 OpenSearch 插件 + + :: + + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + +3. 配置 OpenSearch + + 在 ``/etc/opensearch/opensearch.yml`` 中添加以下配置。 + + :: + + $ sudo vi /etc/opensearch/opensearch.yml + + 要添加的配置:: + + configsync.config_path: /etc/opensearch/dictionary/ + plugins.security.disabled: true + + 创建用于存放词典文件的目录:: + + $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary + + .. important:: + + ``configsync.config_path`` 请指定 OpenSearch 配置目录 ``/etc/opensearch/`` 下的目录。 + 从 OpenSearch 3.8.0 开始，如果词典文件位于配置目录之外，OpenSearch 会拒绝创建索引。 + 如果指定 ``/var/lib/opensearch/data/config/`` 等配置目录之外的位置，|Fess| 将无法创建索引，也无法启动。 + + .. warning:: + + 在生产环境中不要使用 ``plugins.security.disabled: true``\ 。 + 请参阅 :doc:`security` 进行适当的安全配置。 + +步骤 2: 安装 Fess +--------------------- + +1. 安装 Fess RPM + + 从 `下载站点 `__ 下载 RPM 包并安装。 + + :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.rpm + $ sudo rpm -ivh fess-15.10.0.rpm + +2. 配置 Fess + + 在 RPM 版中，需要编辑环境变量配置文件 ``/etc/sysconfig/fess``\ 。 + 该文件在软件包升级时也会被保留（由于 ``/usr/share/fess/bin/fess.in.sh`` 在升级时会被覆盖，因此请勿直接编辑该文件）。 + + :: + + $ sudo vi /etc/sysconfig/fess + + 设置到 OpenSearch 的连接信息。\ ``FESS_DICTIONARY_PATH`` 的默认值 ``/var/lib/opensearch/config/`` 与步骤 3 中的 ``configsync.config_path`` 不同，因此请按如下方式进行更改。\ ``SEARCH_ENGINE_HTTP_URL`` 请根据需要进行更改:: + + SEARCH_ENGINE_HTTP_URL=http://localhost:9200 + FESS_DICTIONARY_PATH=/etc/opensearch/dictionary/ + + .. note:: + + ``FESS_DICTIONARY_PATH`` 请指定与 ``opensearch.yml`` 中的 ``configsync.config_path`` 相同的路径。 + +3. 注册和启用服务 + + 使用 systemd 启用服务（RHEL 8 及更高版本、CentOS 8 及更高版本中 systemd 为标准配置）:: + + $ sudo systemctl daemon-reload + $ sudo systemctl enable opensearch.service + $ sudo systemctl enable fess.service + + .. note:: + + 由于 |Fess| 的服务依赖于 OpenSearch 的服务，因此需要先启动 OpenSearch。 + + .. note:: + + 在不使用 systemd 的传统环境中，可以使用 ``chkconfig`` 注册 |Fess|:: + + $ sudo /sbin/chkconfig --add fess + +步骤 3: 启动 +---------------- + +关于启动步骤，请参阅 :doc:`run`。 + +使用 DEB 版安装 +=================== + +DEB 版用于 Debian、Ubuntu 等基于 DEB 的 Linux 发行版。 + +步骤 1: 安装 OpenSearch +--------------------------- + +1. 下载和安装 OpenSearch DEB + + 从 `Download OpenSearch `__ 下载 DEB 包并安装。 + + :: + + $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.9.0/opensearch-3.9.0-linux-x64.deb + $ sudo dpkg -i opensearch-3.9.0-linux-x64.deb + + 在 arm64（aarch64）机器上，请将上述文件名中的 ``linux-x64`` 替换为 ``linux-arm64``\ （例如 ``opensearch-3.9.0-linux-arm64.deb``）。 + + 或者，也可以添加仓库后进行安装。 + 详情请参阅 `Installing OpenSearch `__\ 。 + +2. 安装 OpenSearch 插件 + + :: + + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + +3. 配置 OpenSearch + + 在 ``/etc/opensearch/opensearch.yml`` 中添加以下配置。 + + :: + + $ sudo vi /etc/opensearch/opensearch.yml + + 要添加的配置:: + + configsync.config_path: /etc/opensearch/dictionary/ + plugins.security.disabled: true + + 创建用于存放词典文件的目录:: + + $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary + + .. important:: + + ``configsync.config_path`` 请指定 OpenSearch 配置目录 ``/etc/opensearch/`` 下的目录。 + 从 OpenSearch 3.8.0 开始，如果词典文件位于配置目录之外，OpenSearch 会拒绝创建索引。 + 如果指定 ``/var/lib/opensearch/data/config/`` 等配置目录之外的位置，|Fess| 将无法创建索引，也无法启动。 + + .. warning:: + + 在生产环境中不要使用 ``plugins.security.disabled: true``\ 。 + 请参阅 :doc:`security` 进行适当的安全配置。 + +步骤 2: 安装 Fess +--------------------- + +1. 安装 Fess DEB + + 从 `下载站点 `__ 下载 DEB 包并安装。 + + :: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.deb + $ sudo dpkg -i fess-15.10.0.deb + +2. 配置 Fess + + 在 DEB 版中，需要编辑环境变量配置文件 ``/etc/default/fess``\ 。 + 该文件在软件包升级时也会被保留（由于 ``/usr/share/fess/bin/fess.in.sh`` 在升级时会被覆盖，因此请勿直接编辑该文件）。 + + :: + + $ sudo vi /etc/default/fess + + 设置到 OpenSearch 的连接信息。\ ``FESS_DICTIONARY_PATH`` 的默认值 ``/var/lib/opensearch/config/`` 与步骤 3 中的 ``configsync.config_path`` 不同，因此请按如下方式进行更改。\ ``SEARCH_ENGINE_HTTP_URL`` 请根据需要进行更改:: + + SEARCH_ENGINE_HTTP_URL=http://localhost:9200 + FESS_DICTIONARY_PATH=/etc/opensearch/dictionary/ + + .. note:: + + ``FESS_DICTIONARY_PATH`` 请指定与 ``opensearch.yml`` 中的 ``configsync.config_path`` 相同的路径。 + +3. 注册和启用服务 + + 使用 systemd 启用服务:: + + $ sudo systemctl daemon-reload + $ sudo systemctl enable opensearch.service + $ sudo systemctl enable fess.service + + .. note:: + + 由于 |Fess| 的服务依赖于 OpenSearch 的服务，因此需要先启动 OpenSearch。 + +步骤 3: 启动 +---------------- + +关于启动步骤，请参阅 :doc:`run`。 + +安装后的确认 +================ + +安装完成后，请确认以下内容： + +1. **确认配置文件** + + - OpenSearch 的配置文件（opensearch.yml） + - |Fess| 的配置文件 + + - ZIP 版：``bin/fess.in.sh`` + - RPM 版：``/etc/sysconfig/fess`` + - DEB 版：``/etc/default/fess`` + +2. **目录权限** + + 确认配置中指定的目录（``configsync.config_path`` / ``FESS_DICTIONARY_PATH``）存在，并且已设置适当的权限。 + + ZIP 版的情况:: + + $ ls -ld /path/to/opensearch-3.9.0/config/dictionary/ + + RPM/DEB 版的情况:: + + $ sudo ls -ld /etc/opensearch/dictionary/ + +3. **确认内核参数** + + :: + + $ sysctl vm.max_map_count + + 确认该值为 ``262144`` 以上。 + +4. **确认 Java 版本** + + :: + + $ java -version + + 确认已安装 Java 21 或更高版本。 + +下一步 +========== + +安装完成后，请参阅以下文档： + +- :doc:`run` - |Fess| 的启动和初始设置 +- :doc:`security` - 生产环境的安全配置 +- :doc:`troubleshooting` - 故障排除 + +常见问题 +============ + +Q: OpenSearch 的其他版本也能工作吗？ +---------------------------------------- + +A: |Fess| 依赖于特定版本的 OpenSearch。 +为了确保插件兼容性，强烈建议使用推荐版本（3.9.0）。 +如果使用其他版本，需要适当调整插件版本。 + +Q: 多个 Fess 实例可以共享同一个 OpenSearch 吗？ +------------------------------------------------------- + +A: 可以，但不推荐。建议为每个 Fess 实例准备专用的 OpenSearch 集群。 +如果多个 Fess 实例共享 OpenSearch，请注意索引名称的冲突。 + +Q: 如何将 OpenSearch 配置为集群？ +------------------------------------- + +A: 请参阅 OpenSearch 官方文档 `Cluster formation `__\ 。 +配置为集群时，需要删除 ``discovery.type: single-node`` 设置并添加适当的集群配置。 diff --git a/zh-cn/15.10/install/install-windows.rst b/zh-cn/15.10/install/install-windows.rst new file mode 100644 index 000000000..51cfd077f --- /dev/null +++ b/zh-cn/15.10/install/install-windows.rst @@ -0,0 +1,348 @@ +==================================== +在 Windows 上安装（详细步骤） +==================================== + +本页面说明在 Windows 环境中安装 |Fess| 的步骤。 +介绍使用 ZIP 包的安装方法。 + +.. note:: + + |Fess| 不包含搜索引擎。需要单独准备 OpenSearch 服务器， + 下面的步骤将进行构建。 + +前提条件 +======== + +- 满足 :doc:`prerequisites` 中描述的系统要求 +- 已安装 Java 21 +- OpenSearch 3.9.0 可用（或新安装） +- 已适当设置 Windows 环境变量 ``JAVA_HOME`` + +确认 Java 安装 +============== + +打开命令提示符或 PowerShell，使用以下命令确认 Java 版本。 + +命令提示符的情况:: + + C:\> java -version + +PowerShell 的情况:: + + PS C:\> java -version + +请确认显示 Java 21 或更高版本。 + +设置环境变量 +============ + +1. 设置 ``JAVA_HOME`` 环境变量 + + 将 Java 的安装目录设置为 ``JAVA_HOME``\ 。 + + 例:: + + JAVA_HOME=C:\Program Files\Eclipse Adoptium\jdk-21.0.1.12-hotspot + +2. 添加到 ``PATH`` 环境变量 + + 将 ``%JAVA_HOME%\bin`` 添加到 ``PATH`` 环境变量。 + +.. tip:: + + 设置环境变量的方法： + + 1. 从「开始」菜单打开「设置」 + 2. 点击「系统」→「关于」→「系统高级设置」 + 3. 点击「环境变量」按钮 + 4. 在「系统环境变量」或「用户环境变量」中设置 + +步骤 1: 安装 OpenSearch +======================= + +.. tip:: + + |Fess| 附带的 ``bin\fess-setup`` 可以一条命令完成下面的步骤：将 OpenSearch 下载并解压到 |Fess| 目录下的 ``opensearch\`` 中，安装所需插件，并向其 ``config\opensearch.yml`` 添加 ``configsync.config_path`` 和 ``plugins.security.disabled: true``\ 。请先按照步骤 2 的说明解压 |Fess| 的 ZIP。 + + :: + + > cd C:\fess-15.10.0 + > bin\fess-setup install opensearch + + ``bin\fess.in.bat`` 会找到以这种方式安装的 OpenSearch，并将其 ``config\dictionary`` 目录传递给 |Fess|\ ，因此只要 OpenSearch 在同一主机上运行，步骤 2 的「配置 Fess」就无需修改。命令会显示它添加的配置，以及 ``bin\fess.in.bat`` 能否找到该安装。在让 OpenSearch 监听 ``localhost`` 以外的地址之前，请阅读「配置 OpenSearch」中的警告。 + + 如果想逐步确认，或者要使用已有的 OpenSearch，请按照下面的步骤操作。 + 若只需向已有的 OpenSearch 安装插件，请使用 + ``bin\fess-setup install opensearch-plugins --opensearch-home C:\opensearch-3.9.0``\ 。 + 所有命令请参阅 :doc:`fess-setup`\ 。 + +下载 OpenSearch +--------------- + +1. 从 `Download OpenSearch `__ 下载 Windows 用的 ZIP 包。 + +2. 将下载的 ZIP 文件解压到任意目录。 + + 例:: + + C:\opensearch-3.9.0 + + .. note:: + + 建议选择路径中不包含日文或空格的目录。 + +安装 OpenSearch 插件 +-------------------- + +以\ **管理员权限**\ 打开命令提示符，执行以下命令。 + +:: + + C:\> cd C:\opensearch-3.9.0 + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + C:\opensearch-3.9.0> bin\opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + +.. important:: + + 插件版本必须与 OpenSearch 版本一致。 + 在上述示例中，所有版本都指定为 3.9.0。 + + |Fess| 的 4 个插件发布在 maven.codelibs.org 上，因此通过 URL 指定。 ``opensearch-plugin install`` 的 ``groupId:artifactId:version`` 形式只查找 Maven Central。 + +配置 OpenSearch +--------------- + +使用文本编辑器打开 ``config\opensearch.yml``，添加以下配置。 + +:: + + # 配置同步路径（使用绝对路径指定） + configsync.config_path: C:/opensearch-3.9.0/config/dictionary/ + + # 禁用安全插件（仅限开发环境） + plugins.security.disabled: true + +.. warning:: + + **关于安全的重要注意事项** + + ``plugins.security.disabled: true`` 仅应在开发环境或测试环境中使用。 + 在生产环境中，应启用 OpenSearch 的安全插件并进行适当的认证和授权配置。 + 详情请参阅 :doc:`security`。 + +.. note:: + + 在 Windows 中，路径分隔符请使用 ``/`` 而不是 ``\``\ 。 + 应写为 ``C:/opensearch-3.9.0/config/dictionary/`` 而不是 ``C:\opensearch-3.9.0\config\dictionary\``\ 。 + +.. important:: + + ``configsync.config_path`` 请指定 OpenSearch 配置目录（本例中为 ``C:/opensearch-3.9.0/config/``\ ）下的目录。 + 从 OpenSearch 3.8.0 开始，如果词典文件位于配置目录之外，OpenSearch 会拒绝创建索引。 + 如果指定 ``C:/opensearch-3.9.0/data/config/`` 等配置目录之外的位置，|Fess| 将无法创建索引，也无法启动。 + +.. tip:: + + 其他推荐配置:: + + cluster.name: fess-cluster + node.name: fess-node-1 + network.host: 0.0.0.0 + discovery.type: single-node + +.. tip:: + + OpenSearch 的堆大小通过 ``config\jvm.options`` 中的 ``-Xms`` / ``-Xmx`` 进行设置。 + 建议将 ``-Xms`` 和 ``-Xmx`` 设置为相同的值，以不超过可用物理内存的一半且低于 32GB 为宜。 + +步骤 2: 安装 Fess +================= + +下载 Fess +--------- + +1. 从 `下载站点 `__ 下载 Windows 用的 ZIP 包。 + +2. 将下载的 ZIP 文件解压到任意目录。 + + 例:: + + C:\fess-15.10.0 + + .. note:: + + 建议选择路径中不包含日文或空格的目录。 + +配置 Fess +--------- + +对于通过 ``bin\fess-setup install opensearch`` 安装到 |Fess| 目录下的 ``opensearch\`` 中、并在同一主机上运行的 OpenSearch，此处无需任何配置。否则，例如按照上面的步骤安装了 OpenSearch、OpenSearch 在其他主机上运行，或 ``opensearch\`` 中有多个通过 ``bin\fess-setup`` 安装的 OpenSearch 时，请按以下方式配置连接。 + +使用文本编辑器打开 ``bin\fess.in.bat``\ 。 +该文件末尾附近已预先以注释状态提供了用于连接外部 OpenSearch 集群的配置。 + +修改前（默认状态）:: + + REM External opensearch cluster + REM set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200 + REM set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=C:/opensearch/config/dictionary + +删除下面两行行首的 ``REM `` 以取消注释，并将 ``fess.dictionary.path`` 的值更改为 OpenSearch 配置同步路径。 + +修改后:: + + REM External opensearch cluster + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200 + set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=C:/opensearch-3.9.0/config/dictionary/ + +.. note:: + + - ``fess.dictionary.path`` 请设置与 OpenSearch 的 ``opensearch.yml`` 中指定的 ``configsync.config_path`` 相同的路径。 + - 如果 OpenSearch 在其他主机上运行，请将 ``fess.search_engine.http_address`` 中的主机名或 IP 地址更改为适当的值。 + - 路径分隔符请使用 ``/``\ 。\ |Fess| 会将该路径插入索引设置中，其中的 ``\`` 会丢失，因此用 ``\`` 书写的路径将无法找到。 + - 请勿新增 ``set FESS_JAVA_OPTS=...`` 行，而应取消注释已有的注释行并进行编辑。重复指定相同选项可能导致意外行为。 + +.. tip:: + + 要更改 |Fess| 的堆大小，请编辑 ``bin\fess.in.bat`` 中的 ``FESS_MIN_MEM``\ （默认值：``256m``）和 ``FESS_MAX_MEM``\ （默认值：``1g``），或设置环境变量 ``FESS_HEAP_SIZE``\ 。 + +确认安装 +-------- + +确认配置文件已正确编辑。 + +在命令提示符中:: + + C:\> findstr "fess.search_engine.http_address" C:\fess-15.10.0\bin\fess.in.bat + C:\> findstr "fess.dictionary.path" C:\fess-15.10.0\bin\fess.in.bat + +步骤 3: 启动 +============ + +关于启动步骤，请参阅 :doc:`run`。 + +注册为 Windows 服务（可选） +=========================== + +通过将 |Fess| 注册为 Windows 服务，可以设置为系统启动时自动启动。 + +|Fess| 内置了用于注册 Windows 服务的 ``bin\service.bat``\ 。 +该脚本使用 Apache Commons Daemon (procrun)，无需另行准备 NSSM 等第三方工具。 + +.. note:: + + 在运行 ``service.bat`` 之前，请确认环境变量 ``JAVA_HOME`` 已正确设置。 + +注册 |Fess| 服务 +---------------- + +以\ **管理员权限**\ 打开命令提示符，执行以下命令。 + +1. 注册服务:: + + C:\> cd C:\fess-15.10.0 + C:\fess-15.10.0> bin\service.bat install + + 默认情况下，64 位环境下服务 ID 为 ``fess-service-x64``，32 位环境下为 ``fess-service-x86``。 + 如需显式指定服务 ID，请以 ``bin\service.bat install <服务ID>`` 的形式通过参数指定。 + +2. 启动和停止服务:: + + C:\fess-15.10.0> bin\service.bat start + C:\fess-15.10.0> bin\service.bat stop + +3. 确认和更改服务配置（GUI）:: + + C:\fess-15.10.0> bin\service.bat manager + +4. 删除服务:: + + C:\fess-15.10.0> bin\service.bat remove + +.. note:: + + - ``service.bat`` 内部会读取 ``bin\fess.in.bat``，因此在「配置 Fess」中设置的外部 OpenSearch 连接配置也会反映到服务中。 + - 默认启动类型为「手动」。要在系统启动时自动启动，请在注册服务前将环境变量 ``FESS_START_TYPE`` 设置为 ``auto``，或在注册后通过服务管理工具（``services.msc``）将启动类型更改为「自动」。 + - ``service.bat`` 仅能注册 |Fess| 服务。如需将 OpenSearch 注册为服务，请参阅 OpenSearch 提供的相关说明。 + +防火墙设置 +========== + +在 Windows Defender 防火墙中开放必要的端口。 + +1. 打开「控制面板」→「Windows Defender 防火墙」→「高级设置」 + +2. 在「入站规则」中创建新规则 + + - 规则类型: 端口 + - 协议和端口: TCP、8080 + - 操作: 允许连接 + - 名称: Fess Web Interface + +或者，在 PowerShell 中执行:: + + PS C:\> New-NetFirewallRule -DisplayName "Fess Web Interface" -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow + +故障排除 +======== + +端口号冲突 +---------- + +如果端口 8080 或 9200 已被使用，可以使用以下命令确认:: + + C:\> netstat -ano | findstr :8080 + C:\> netstat -ano | findstr :9200 + +请更改使用中的端口号或停止冲突的进程。 + +路径长度限制 +------------ + +Windows 对路径长度有限制。建议安装到尽可能短的路径。 + +例:: + + C:\opensearch (推荐) + C:\Program Files\opensearch-3.9.0 (不推荐 - 路径过长) + +Java 未被识别 +------------- + +如果 ``java -version`` 命令显示错误： + +1. 确认 ``JAVA_HOME`` 环境变量是否正确设置 +2. 确认 ``PATH`` 环境变量中是否包含 ``%JAVA_HOME%\bin`` +3. 重启命令提示符以反映设置 + +下一步 +====== + +安装完成后，请参阅以下文档： + +- :doc:`run` - |Fess| 的启动和初始设置 +- :doc:`security` - 生产环境的安全配置 +- :doc:`troubleshooting` - 故障排除 + +常见问题 +======== + +Q: 推荐在 Windows Server 上运行吗？ +------------------------------------ + +A: 可以在 Windows Server 上运行。 +在 Windows Server 上运行时，请注册为 Windows 服务并设置适当的监控。 + +Q: 64 位版和 32 位版有什么区别？ +---------------------------------- + +A: |Fess| 和 OpenSearch 仅支持 64 位版。 +无法在 32 位版的 Windows 上运行。 + +Q: 路径包含日文时的处理方法？ +------------------------------ + +A: 请尽可能安装到不包含日文或空格的路径。 +如果必须使用日文路径，需要在配置文件中适当转义路径。 diff --git a/zh-cn/15.10/install/install.rst b/zh-cn/15.10/install/install.rst new file mode 100644 index 000000000..f94a67bdd --- /dev/null +++ b/zh-cn/15.10/install/install.rst @@ -0,0 +1,247 @@ +==================== +选择安装方法 +==================== + +本页面说明 |Fess| 安装方法的概述。 +请根据您的环境选择适当的安装方法。 + +.. note:: + + |Fess| 不包含搜索引擎。以下任何一种安装方式都需要单独的 + OpenSearch 服务器。 + +确认前提条件 +============ + +开始安装之前，请确认系统要求。 + +详情请参阅 :doc:`prerequisites`。 + +安装方法对比 +==================== + +|Fess| 可以通过以下方法安装。请根据您的环境和用途进行选择。 + +.. list-table:: + :header-rows: 1 + :widths: 15 25 30 30 + + * - 方法 + - 目标操作系统 + - 推荐用途 + - 详细文档 + * - Docker + - Linux, Windows, macOS + - 开发・评估环境、快速设置 + - :doc:`install-docker` + * - ZIP + - Linux, macOS + - 需要定制化的环境 + - :doc:`install-linux` + * - RPM + - RHEL, CentOS, Fedora + - 生产环境（基于 RPM） + - :doc:`install-linux` + * - DEB + - Debian, Ubuntu + - 生产环境（基于 DEB） + - :doc:`install-linux` + * - ZIP + - Windows + - Windows 环境的开发・生产 + - :doc:`install-windows` + +各安装方法的特点 +====================== + +Docker 版 +-------- + +**优点:** + +- 设置最快速 +- 无需管理依赖关系 +- 最适合开发环境的构建 +- 容器启动・停止简便 + +**缺点:** + +- 需要 Docker 知识 + +**推荐环境:** 开发环境、评估环境、POC、生产环境 + +详情: :doc:`install-docker` + +Linux 包版 (ZIP/RPM/DEB) +--------------------------------- + +**优点:** + +- 原生环境的高性能 +- 可作为系统服务管理（RPM/DEB） +- 可进行细致的定制化 + +**缺点:** + +- 需要手动安装 Java 和 OpenSearch +- 配置较为繁琐 + +**推荐环境:** 生产环境（推荐使用可作为系统服务管理的 RPM/DEB）、需要定制化的环境 + +详情: :doc:`install-linux` + +Windows 版 (ZIP) +--------------- + +**优点:** + +- 在 Windows 原生环境中运行 +- 无需安装程序 + +**缺点:** + +- 需要手动安装 Java 和 OpenSearch +- 配置较为繁琐 + +**推荐环境:** Windows 环境的开发・评估、Windows Server 的生产运维 + +详情: :doc:`install-windows` + +安装的基本流程 +======================== + +所有安装方法的基本流程相同。 + +1. **确认系统要求** + + 参阅 :doc:`prerequisites`，确认满足系统要求。 + +2. **下载软件** + + 从 `下载站点 `__ 下载 |Fess|\ 。 + + Docker 版的情况下，获取 Docker Compose 文件。 + +3. **设置 OpenSearch** + + Docker 版以外的情况下，需要单独设置 OpenSearch。 + + - 安装 OpenSearch 3.9.0 + - 安装必需插件 + - 编辑配置文件 + +4. **设置 Fess** + + - 安装 Fess + - 编辑配置文件（OpenSearch 的连接信息等） + +5. **启动和确认** + + - 启动服务 + - 在浏览器中访问并确认运行 + + 详情请参阅 :doc:`run`。 + +必需组件 +================== + +运行 |Fess| 需要以下组件。 + +Fess 本体 +-------- + +全文搜索系统的主体。提供 Web 界面、爬虫、索引器等功能。 + +OpenSearch +---------- + +使用 OpenSearch 作为搜索引擎。 + +- **支持版本**: OpenSearch 3.9.0 +- **必需插件**: + + - opensearch-analysis-fess + - opensearch-analysis-extension + - opensearch-minhash + - opensearch-configsync + +.. important:: + + OpenSearch 的版本与插件的版本必须一致。 + 版本不一致可能导致启动错误或意外行为。 + +``bin/fess-setup install opensearch`` 会在 Linux 和 Windows 上连同这些插件一起准备 OpenSearch。详情请参阅 :doc:`install-linux`\ （其中也包括必须用其他方式安装 OpenSearch 的 macOS），所有命令请参阅 :doc:`fess-setup`\ 。 + +.. note:: + + 如果使用的 OpenSearch 无法安装这些插件（例如托管服务），请将 ``search_engine.type`` 指定为 ``vanilla`` （\ |Fess| 15.10 及更高版本）。此时词典管理等部分功能不可用。详情请参阅 :doc:`../config/search-engine-type` 。 + +Java (Docker 版除外) +------------------- + +ZIP/RPM/DEB 版需要 Java 21 或更高版本。 + +- 推荐: `Eclipse Temurin `__ +- 也可使用 OpenJDK 21 或更高版本 + +.. note:: + + Docker 版的情况下，Java 已包含在 Docker 镜像中，无需单独安装。 + +下一步 +========== + +确认系统要求后，请选择适当的安装方法。 + +1. :doc:`prerequisites` - 确认系统要求 +2. 选择安装方法: + + - :doc:`install-docker` - 使用 Docker 安装 + - :doc:`install-linux` - 在 Linux 上安装 + - :doc:`install-windows` - 在 Windows 上安装 + +3. :doc:`run` - |Fess| 的启动和初始设置 +4. :doc:`security` - 安全配置（生产环境） + +常见问题 +========== + +Q: OpenSearch 是必需的吗？ +-------------------------- + +A: 是的，是必需的。\ |Fess| 使用 OpenSearch 作为搜索引擎。 +Docker 版会自动设置，但其他方法需要手动安装。 + +Q: 可以从旧版本升级吗？ +---------------------------------------------- + +A: 可以。详情请参阅 :doc:`upgrade`。 + +Q: 可以使用多个服务器构成吗？ +--------------------------------- + +A: 可以。Fess 和 OpenSearch 可以在不同的服务器上运行。 +此外，通过将 OpenSearch 配置为集群，可以提高可用性和性能。 + +下载 +========== + +|Fess| 及相关组件可从以下位置下载： + +- **Fess**: `下载站点 `__ +- **OpenSearch**: `Download OpenSearch `__ +- **Java (Adoptium)**: `Adoptium `__ +- **Docker**: `Get Docker `__ + +版本信息 +============ + +本文档适用于以下版本： + +- **Fess**: 15.10.0 +- **OpenSearch**: 3.9.0 +- **Java**: 21 或更高版本 +- **Docker**: 20.10 或更高版本 +- **Docker Compose**: 2.0 或更高版本 + +关于旧版本的文档，请参阅各版本的文档。 diff --git a/zh-cn/15.10/install/intro.rst b/zh-cn/15.10/install/intro.rst new file mode 100644 index 000000000..b933e7b56 --- /dev/null +++ b/zh-cn/15.10/install/intro.rst @@ -0,0 +1,70 @@ +======== +安装简介 +======== + +关于本文档 +================== + +本安装指南说明了 |Fess| 的安装、启动、升级和卸载步骤。 +请根据您的环境选择适当的安装方法。 + +目标读者 +======== + +本文档面向负责 |Fess| 安装和卸载工作的用户。 + +阅读前须知 +============== + +本文档介绍了 |Fess| 的安装方法。您需要具备以下知识： + +- 服务器管理的基础知识 +- Linux 或 Windows 的命令行操作 +- 网络和防火墙的基本配置 +- Docker 的基础知识（如果使用 Docker 版） + +文档结构 +============== + +本安装指南包含以下部分： + +- **系统要求**：运行 |Fess| 所需的硬件和软件要求 +- **安装**：各平台的安装步骤 + + - 安装方法的选择（概述与比较） + - Linux (ZIP/RPM/DEB) 安装 + - Windows (ZIP) 安装 + - Docker 安装 + +- **启动、停止和初始设置**：|Fess| 服务器的启动、停止和初始设置 +- **安全配置**：生产环境推荐的安全设置 +- **升级**：从旧版本升级到最新版本的步骤 +- **卸载**：完全卸载 |Fess| 的步骤 +- **故障排除**：常见问题和解决方法 + +在线访问 +================= + +有关下载、专业服务、支持和其他开发者信息，请访问： + +- 项目网站: `https://fess.codelibs.org/ `__ + +技术支持联系方式 +================== + +关于本产品的技术问题或疑问，请访问： + +- Issues: `https://github.com/codelibs/fess/issues `__ + +商业支持 +--------- + +如需本产品的技术支持、维护等商业服务，请联系 `N2SM, Inc. `__\ 。 + +如何提交意见和建议 +===================== + +如有问题或改进建议，请通过以下方式提交： + +- 产品问题: `https://github.com/codelibs/fess/issues `__ +- 文档问题: `https://github.com/codelibs/fess-docs/issues `__ diff --git a/zh-cn/15.10/install/prerequisites.rst b/zh-cn/15.10/install/prerequisites.rst new file mode 100644 index 000000000..be9f88694 --- /dev/null +++ b/zh-cn/15.10/install/prerequisites.rst @@ -0,0 +1,184 @@ +============ +系统要求 +============ + +本页面说明运行 |Fess| 所需的硬件和软件要求。 + +硬件要求 +============== + +最低要求 +-------- + +以下是评估和开发环境的最低要求： + +- CPU: 2核或以上 +- 内存: 4GB或以上 +- 磁盘空间: 10GB或以上的可用空间 + +推荐配置 +-------- + +对于生产环境，推荐以下配置： + +- CPU: 4核或以上 +- 内存: 8GB或以上（根据索引大小进行扩展） +- 磁盘空间: + + - 系统空间: 20GB或以上 + - 数据空间: 索引大小的3倍或以上（包含副本） + +- 网络: 1Gbps或以上 + +.. note:: + + 如果索引大小较大或需要进行高频率爬取，请适当增加内存和磁盘空间。 + +软件要求 +============== + +操作系统 +-------------------- + +|Fess| 可在以下操作系统上运行： + +**Linux** + +- Red Hat Enterprise Linux 8 或更高版本 +- CentOS 8 或更高版本 +- Ubuntu 20.04 LTS 或更高版本 +- Debian 11 或更高版本 +- 其他 Linux 发行版（可运行 Java 21 的环境） + +**Windows** + +- Windows Server 2019 或更高版本 +- Windows 10 或更高版本 + +**其他** + +- macOS 11 (Big Sur) 及以上（仅推荐用于开发环境。OpenSearch 没有官方的 macOS 发行版，请使用 Homebrew 或 Docker 准备） +- 可运行 Docker 的环境 + +必需软件 +-------------- + +根据安装方法的不同，需要以下软件： + +ZIP/RPM/DEB 版 +~~~~~~~~~~~~~~~~~~~~ + +- **Java 21**: 推荐使用 `Eclipse Temurin `__ + + - OpenJDK 21 或更高版本 + - Eclipse Temurin 21 或更高版本 + +- **OpenSearch 3.9.0**: 必需。使用早于 OpenSearch 3 的引擎时 |Fess| 无法启动 + + - 支持版本: OpenSearch 3.9.0 + - 其他版本需要注意插件兼容性 + +Docker 版 +~~~~~~~~~ + +- **Docker**: 20.10 或更高版本 +- **Docker Compose**: 2.0 或更高版本 + +网络要求 +============== + +所需端口 +---------- + +|Fess| 使用的主要端口如下： + +.. list-table:: + :header-rows: 1 + :widths: 15 15 50 + + * - 端口 + - 协议 + - 用途 + * - 8080 + - HTTP + - |Fess| Web 界面（搜索页面・管理页面） + * - 9200 + - HTTP + - OpenSearch HTTP API（|Fess| 与 OpenSearch 的通信） + * - 9300 + - TCP + - OpenSearch 传输通信（集群配置时） + +.. warning:: + + 在生产环境中，强烈建议限制外部对端口 9200 和 9300 的直接访问。 + 这些端口应仅用于 |Fess| 与 OpenSearch 之间的内部通信。 + +防火墙设置 +------------------ + +如果要从外部访问 |Fess|，需要开放端口 8080。 + +**Linux (使用 firewalld)** + +:: + + $ sudo firewall-cmd --permanent --add-port=8080/tcp + $ sudo firewall-cmd --reload + +**Linux (使用 iptables)** + +:: + + $ sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT + $ sudo iptables-save + +浏览器要求 +============ + +对于 |Fess| 的管理页面和搜索页面，推荐使用以下浏览器： + +- Google Chrome（最新版） +- Mozilla Firefox（最新版） +- Microsoft Edge（最新版） +- Safari（最新版） + +.. note:: + + 不支持 Internet Explorer。 + +安装前检查清单 +==================== + +安装前，请确认以下项目： + +.. list-table:: + :header-rows: 1 + :widths: 50 50 + + * - 检查项目 + - 状态 + * - 是否满足硬件要求 + - □ + * - 是否已安装 Java 21（Docker 版除外） + - □ + * - 是否已安装 Docker（Docker 版） + - □ + * - 所需端口是否可用 + - □ + * - 防火墙设置是否合适 + - □ + * - 磁盘空间是否充足 + - □ + * - 网络连接是否正常（如需爬取外部网站） + - □ + +下一步 +========== + +确认系统要求后，请根据您的环境进行相应的安装： + +- :doc:`install-linux` - Linux (ZIP/RPM/DEB) 安装 +- :doc:`install-windows` - Windows (ZIP) 安装 +- :doc:`install-docker` - Docker 安装 +- :doc:`install` - 安装方法概述 diff --git a/zh-cn/15.10/install/run.rst b/zh-cn/15.10/install/run.rst new file mode 100644 index 000000000..026015ca9 --- /dev/null +++ b/zh-cn/15.10/install/run.rst @@ -0,0 +1,519 @@ +==================== +启动、停止、初始设置 +==================== + +本页面说明 |Fess| 服务器的启动、停止和初始设置步骤。 + +.. important:: + + 启动 |Fess| 前，必须先启动 OpenSearch。 + 如果 OpenSearch 未启动，|Fess| 将无法正常工作。 + +启动方法 +======== + +根据安装方法的不同，启动步骤也不同。 + +ZIP 版的情况 +------------- + +启动 OpenSearch +~~~~~~~~~~~~~~~~ + +:: + + $ cd /path/to/opensearch-3.9.0 + $ ./bin/opensearch + +在后台启动:: + + $ ./bin/opensearch -d + +.. note:: + + ``bin/fess-setup install opensearch`` 会将 OpenSearch 放在 |Fess| 目录下的 ``opensearch/opensearch-3.9.0`` 中。 + +.. important:: + + 请以普通用户启动 OpenSearch。它拒绝以 ``root`` 身份运行，并以 ``can not run opensearch as root`` 结束。被拒绝的启动仍会留下 ``config/opensearch.keystore`` 等归 ``root`` 所有的文件，之后以普通用户启动时会因 ``AccessDeniedException`` 而失败。再次启动之前，请将 OpenSearch 目录的所有者改回该用户，例如:: + + $ sudo chown -R /path/to/opensearch-3.9.0 + +启动 Fess +~~~~~~~~~~ + +:: + + $ cd /path/to/fess-15.10.0 + $ ./bin/fess + +在后台启动:: + + $ ./bin/fess -d + +.. note:: + + 启动可能需要几分钟。 + 可以在 ``logs/`` 目录的日志文件中确认启动状态。``fess.log`` 记录 |Fess| 本身的消息， + ``server_0.log`` 记录内嵌 Tomcat 的消息（包括启动完成消息）。 + +ZIP 版的情况（Windows） +--------------------- + +启动 OpenSearch +~~~~~~~~~~~~~~~~ + +1. 打开 OpenSearch 的安装目录 +2. 双击 ``bin`` 文件夹中的 ``opensearch.bat`` + +或者，从命令提示符:: + + C:\> cd C:\opensearch-3.9.0 + C:\opensearch-3.9.0> bin\opensearch.bat + +启动 Fess +~~~~~~~~~~ + +1. 打开 Fess 的安装目录 +2. 双击 ``bin`` 文件夹中的 ``fess.bat`` + +或者，从命令提示符:: + + C:\> cd C:\fess-15.10.0 + C:\fess-15.10.0> bin\fess.bat + +RPM/DEB 版的情况 (chkconfig) +-------------------------- + +启动 OpenSearch:: + + $ sudo service opensearch start + +启动 Fess:: + + $ sudo service fess start + +确认启动状态:: + + $ sudo service fess status + +RPM/DEB 版的情况 (systemd) +------------------------ + +启动 OpenSearch:: + + $ sudo systemctl start opensearch.service + +启动 Fess:: + + $ sudo systemctl start fess.service + +确认启动状态:: + + $ sudo systemctl status fess.service + +启用服务自动启动:: + + $ sudo systemctl enable opensearch.service + $ sudo systemctl enable fess.service + +Docker 版的情况 +------------- + +.. note:: + + ``compose.yaml`` 和 ``compose-opensearch3.yaml`` 并不包含在 |Fess| 本体中。 + 这些文件由 docker-fess 项目（https://github.com/codelibs/docker-fess）提供； + 请获取该仓库，并在 ``compose`` 目录中执行以下命令。 + +使用 Docker Compose 启动:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +确认启动状态:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps + +确认日志:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01 + +确认启动 +========== + +确认 |Fess| 是否正常启动。 + +健康检查 +------------ + +在浏览器或使用 curl 命令访问以下 URL:: + + http://localhost:8080/ + +如果正常启动，会显示 Fess 的搜索页面。 + +在命令行确认:: + + $ curl -I http://localhost:8080/ + +如果返回 ``HTTP/1.1 200 OK``，则正常启动。 + +确认日志 +-------- + +确认启动日志，检查是否有错误。 + +ZIP 版:: + + $ tail -f /path/to/fess-15.10.0/logs/fess.log + +RPM/DEB 版:: + + $ sudo tail -f /var/log/fess/fess.log + +或使用 journalctl:: + + $ sudo journalctl -u fess.service -f + +Docker 版:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01 + +.. tip:: + + 启动成功完成后，如下启动完成消息会写入日志目录（ZIP 版为 ``logs/``，RPM/DEB 版为 ``/var/log/fess/``）中的 + ``server_0.log``\ 。控制台和 ``fess.log`` 中都不会输出该消息:: + + ...Booting the Tomcat: port=8080 contextPath= + ... + Boot successful: url -> http://localhost:8080 + +在浏览器中访问 +==================== + +访问以下 URL 确认 Web 界面。 + +搜索页面 +-------- + +**URL**: http://localhost:8080/ + +显示 Fess 的搜索页面。初始状态下，由于未进行爬取配置，不会显示搜索结果。 + +搜索页面使用 |Fess| 内置的静态主题 ``bootstrap`` 。要更改其外观， +可以在管理页面的「系统」→「主题」中或使用 +``bin/fess-setup install theme `` （参见 :doc:`fess-setup` ）安装其他主题， +也可以复制内置主题并修改副本（参见 :ref:`theme-customize-bundled` ）。 + +管理页面 +-------- + +**URL**: http://localhost:8080/admin + +默认管理员账号： + +- **用户名**: ``admin`` +- **密码**: ``admin`` + +.. warning:: + + **关于安全的重要注意事项** + + 必须更改默认密码。 + 特别是在生产环境中，强烈建议在首次登录后立即更改密码。 + +初始设置 +============== + +登录管理页面后，进行以下初始配置。 + +步骤 1: 更改管理员密码 +------------------------------- + +1. 登录管理页面（http://localhost:8080/admin） +2. 点击左侧菜单的「用户」→「用户」 +3. 点击 ``admin`` 用户 +4. 在 [密码] 字段输入新密码 +5. 在 [密码 (确认)] 字段再次输入相同密码 +6. 点击 [更新] 按钮 + +.. important:: + + 推荐密码满足以下条件： + + - 8个字符或以上（``password.min.length`` 所设置的最低长度要求） + - 组合使用大写字母、小写字母、数字、符号 + - 不易被猜测 + + 默认情况下，仅要求满足最低长度（8个字符），不强制要求字符类型组合。 + 可通过 ``password.require.uppercase`` 等设置启用字符类型要求。 + +步骤 2: 创建爬取配置 +--------------------------- + +创建要爬取的网站或文件系统的配置。 + +1. 点击左侧菜单的「爬虫」→「网页」 +2. 点击「新建」按钮 +3. 输入必要信息： + + - **名称**: 爬取配置的名称（例：公司网站） + - **URL**: 要爬取的目标 URL（例：https://www.example.com/）。如需指定多个 URL，请每行输入一个 URL + - **最大访问数**: 爬取文档数的上限（可选） + - **间隔**: 各次访问之间的等待时间（毫秒；默认值：``10000``） + + .. note:: + + 其他项目（如用户代理、线程数、深度等）留空时将使用默认值。 + +4. 点击「创建」按钮 + +步骤 3: 执行爬取 +----------------------- + +1. 点击左侧菜单的 [系统] → [调度器] +2. 打开 [Default Crawler] 作业，点击「立即开始」按钮 +3. 等待爬取完成（可在仪表板查看进度） + +步骤 4: 确认搜索 +------------------- + +1. 访问搜索页面（http://localhost:8080/） +2. 输入搜索关键词 +3. 确认显示搜索结果 + +.. note:: + + 爬取可能需要较长时间。 + 对于大规模网站，可能需要数小时到数天。 + +其他推荐设置 +============== + +在生产环境运行时，还需要考虑以下设置。 + +通过环境变量进行主要设置 +-------------------------- + +端口号、JVM 堆大小、OpenSearch 连接 URL 等设置可通过环境变量更改。 +ZIP 版请编辑 ``bin/fess.in.sh``，RPM 版请编辑 ``/etc/sysconfig/fess``，DEB 版请编辑 ``/etc/default/fess``\ 。 +更改后需要重启 |Fess|\ 。 + +.. list-table:: + :header-rows: 1 + :widths: 30 25 45 + + * - 环境变量 + - 默认值 + - 说明 + * - ``FESS_PORT`` + - ``8080`` + - |Fess| 监听的 HTTP 端口。 + * - ``FESS_HEAP_SIZE`` + - （未设置） + - JVM 堆大小。最小值和最大值设置为相同的值。未设置时，最小值为 ``256m``，最大值为 ``2g``\ （ZIP 版（Windows）最大值为 ``1g``）；RPM/DEB 版使用 ``512m``\ 。 + * - ``SEARCH_ENGINE_HTTP_URL`` + - ``http://localhost:9200`` + - 连接的 OpenSearch 的 URL。ZIP 版由 ``bin/fess.in.sh`` 默认设置此值。当 OpenSearch 在不同端口或主机上运行时，请设置环境变量或编辑 ``bin/fess.in.sh``\ 。RPM/DEB 版通过软件包环境配置文件设置。 + * - ``FESS_LOG_LEVEL`` + - ``warn`` + - |Fess| 的日志级别。 + * - ``FESS_HEAP_NEWSIZE`` + - （未设置） + - JVM 堆新生代的大小（``-Xmn``），例如 ``256m``。未设置时由 JVM 决定。 + * - ``FESS_TEMP_PATH`` + - |Fess| 目录下的 ``temp``\ （RPM/DEB 版为 ``/var/tmp/fess``） + - 存放临时文件的目录，包括内嵌 Tomcat 的工作目录。运行 |Fess| 的用户必须对其有写入权限。 + * - ``FESS_CONF_PATH`` + - （未设置）\ （RPM/DEB 版为 ``/etc/fess``） + - 存放配置文件的目录。 ``bin/fess`` 会将该目录添加到类路径开头，并以 ``-Dfess.conf.path`` 传递给 |Fess|\ 。对于 ``lib/classes`` 中的 ``tomcat_config.properties`` 等文件，优先使用该目录中的文件。但在 ZIP 版中，Web 应用程序会先读取 ``app/WEB-INF/classes`` 中的文件，因此放在该目录中的 ``fess_config.properties`` 无法覆盖 ``app/WEB-INF/classes`` 中 ``fess_config.properties`` 的值（爬虫等子进程会先于 ``WEB-INF/classes`` 读取该目录）。在 ZIP 版中要修改 ``fess_config.properties`` 时，请编辑 ``app/WEB-INF/classes`` 中的文件。RPM/DEB 版不会在 ``app/WEB-INF/classes`` 中放置 ``fess_config.properties``\ ，只使用 ``/etc/fess`` 中的文件。 + * - ``FESS_USE_IPV4`` + - （未设置） + - 设置任意非空值后，JVM 仅使用 IPv4 协议栈（``-Djava.net.preferIPv4Stack=true``）。 + * - ``FESS_USE_GC_LOGGING`` + - （未设置） + - 设置任意非空值后，JVM 会将 GC 日志写入日志目录下的 ``gc-fess.log``\ （最多 5 个文件，每个 64 MB）。 + +.. note:: + + Windows ZIP 版的 ``bin\fess.in.bat`` 读取的环境变量，除了这些环境变量中的 + ``FESS_HEAP_SIZE``、``FESS_HEAP_NEWSIZE``、``FESS_USE_IPV4`` 和 ``FESS_USE_GC_LOGGING`` 之外， + 还有表中没有列出的以下环境变量。 + + - ``FESS_MIN_MEM``、``FESS_MAX_MEM``：分别指定最小和最大堆大小（设置了 ``FESS_HEAP_SIZE`` 时将被忽略）。 + - ``FESS_DIRECT_SIZE``：直接内存的上限（``-XX:MaxDirectMemorySize``）。 + - ``FESS_DICTIONARY_PATH``：OpenSearch 的 ``config\dictionary`` 目录。 + - ``FESS_PROXY_HOST``、``FESS_PROXY_PORT``、``FESS_NON_PROXY_HOSTS``：代理设置。 + - ``FESS_JAVA_OPTS``：``fess.in.bat`` 会将 JVM 选项追加到已设置的值之后。 + - ``PLAYWRIGHT_NODEJS_PATH``：Playwright 插件使用的 Node.js 可执行文件。 + - ``JAVA_HOME``：必需。 + + ``FESS_PORT``、``FESS_LOG_LEVEL``、``FESS_TEMP_PATH``、``FESS_CONF_PATH``、``SEARCH_ENGINE_HTTP_URL`` + 不会被读取。这些值直接写在文件中，如需更改请直接编辑 ``bin\fess.in.bat``\ 。 + +邮件服务器设置 +------------------ + +为了通过邮件接收故障通知等消息，请配置 SMTP 服务器和通知收件人地址。 + +1. 在 ``fess_env_web.properties`` 和 ``fess_env_crawler.properties`` 中，通过 ``mail.smtp.server.main.host.and.port``\ （默认值：``localhost:25``）指定 SMTP 服务器的主机名和端口。ZIP 包的这些文件位于 ``app/WEB-INF/classes/`` 中，RPM/DEB 包则位于 ``/etc/fess/`` 中。|Fess| Web 进程读取前者，发送爬取完成邮件的爬虫读取后者；不使用 ``fess_env.properties``\ 。更改后需要重启 |Fess|\ 。 +2. 在管理界面中，点击左侧菜单的 [系统] → [通用]。 +3. 在 [通知邮件] 字段输入收件人邮件地址。 +4. 点击 [更新] 按钮。 +5. 可使用 [发送测试邮件] 按钮验证邮件是否正常发送。 + +时区设置 +---------------- + +|Fess| 使用服务器（操作系统 / JVM）的时区。管理界面中没有更改时区的设置项。 +如需更改时区，请修改操作系统的时区设置，或在 ``bin/fess.in.sh`` 的 ``FESS_JAVA_OPTS`` 中添加 JVM 选项 ``-Duser.timezone=Asia/Tokyo``\ （Windows 系统请编辑 ``bin\fess.in.bat``）。 + +调整日志级别 +-------------- + +在生产环境中，可以调整日志级别以减少磁盘使用量。 + +|Fess| 的整体日志级别可通过 ``FESS_LOG_LEVEL`` 环境变量更改（默认值：``warn``）。 +如需对各个日志记录器进行精细控制，请编辑配置文件 ``app/WEB-INF/classes/log4j2.xml``\ 。 +爬取、suggest 和缩略图生成作为独立进程运行，因此请分别在 ``app/WEB-INF/env/{crawler,suggest,thumbnail}/resources/log4j2.xml`` 中配置各自的日志级别。 + +详情请参阅 :doc:`../admin/index`。 + +停止方法 +======== + +ZIP 版的情况 +----------------- + +停止 Fess +~~~~~~~~~~ + +终止进程:: + + $ ps aux | grep fess + $ kill + +或者，在前台运行时可以使用 ``Ctrl+C`` 停止。 + +停止 OpenSearch:: + + $ ps aux | grep opensearch + $ kill + +RPM/DEB 版的情况 (chkconfig) +-------------------------- + +停止 Fess:: + + $ sudo service fess stop + +停止 OpenSearch:: + + $ sudo service opensearch stop + +RPM/DEB 版的情况 (systemd) +------------------------ + +停止 Fess:: + + $ sudo systemctl stop fess.service + +停止 OpenSearch:: + + $ sudo systemctl stop opensearch.service + +Docker 版的情况 +------------- + +停止容器:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop + +停止并删除容器:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +.. warning:: + + 如果使用 ``down`` 命令时同时删除卷，请添加 ``-v`` 选项。 + 这种情况下会删除所有数据，请注意。 + +重启方法 +========== + +ZIP 版的情况 +----------------- + +先停止后启动。 + +RPM/DEB 版的情况 +-------------- + +chkconfig:: + + $ sudo service fess restart + +systemd:: + + $ sudo systemctl restart fess.service + +Docker 版的情况 +------------- + +:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml restart + +故障排除 +==================== + +无法启动的情况 +------------ + +1. **确认 OpenSearch 是否启动** + + :: + + $ curl http://localhost:9200/ + + 如果 OpenSearch 未启动，请先启动 OpenSearch。 + +2. **确认端口号冲突** + + :: + + $ sudo ss -tuln | grep 8080 + + 已安装 net-tools 的环境中，也可以使用 ``sudo netstat -tuln | grep 8080`` 获得相同的信息。 + + 如果端口 8080 已被使用，请更改端口号。 + + - ZIP 版：在 ``bin/fess.in.sh`` 中更改 ``FESS_PORT`` + - ZIP 版（Windows）：直接编辑 ``bin\fess.in.bat`` 中的 ``-Dfess.port=8080`` + - RPM 版：在 ``/etc/sysconfig/fess`` 中更改 ``FESS_PORT`` + - DEB 版：在 ``/etc/default/fess`` 中更改 ``FESS_PORT`` + +3. **确认日志** + + 确认错误消息以找出问题。 + +4. **确认 Java 版本** + + :: + + $ java -version + + 请确认已安装 Java 21 或更高版本。 + +详细的故障排除请参阅 :doc:`troubleshooting`。 + +下一步 +========== + +|Fess| 正常启动后，请参阅以下文档开始运维： + +- :doc:`../admin/index` - 爬取配置、搜索配置、系统配置的详情 +- :doc:`security` - 生产环境的安全配置 +- :doc:`troubleshooting` - 常见问题和解决方法 +- :doc:`upgrade` - 版本升级步骤 +- :doc:`uninstall` - 卸载步骤 diff --git a/zh-cn/15.10/install/security.rst b/zh-cn/15.10/install/security.rst new file mode 100644 index 000000000..740afe879 --- /dev/null +++ b/zh-cn/15.10/install/security.rst @@ -0,0 +1,355 @@ +================== +安全配置 +================== + +本页面说明在生产环境中安全运行 |Fess| 的推荐安全配置。 + +.. danger:: + + **安全非常重要** + + 强烈建议在生产环境中实施本页面描述的所有安全配置。 + 如果疏忽安全配置，将增加未经授权访问、数据泄漏、系统入侵等风险。 + +必需的安全配置 +==================== + +更改管理员密码 +-------------------- + +必须更改默认管理员密码（``admin`` / ``admin``）。 + +**步骤:** + +1. 登录管理页面: http://localhost:8080/admin +2. 点击「用户」→「用户」 +3. 选择 ``admin`` 用户 +4. 设置强密码 +5. 点击「更新」按钮 + +.. note:: + + 一旦将密码从 ``admin`` 更改后，就不能再设置回 ``admin`` 这样的简单字符串（``password.invalid.admin.passwords`` 中配置了管理员密码黑名单）。此外，在首次启动前，可以通过在 ``fess_config.properties`` 中设置 ``index.user.initial_password`` 来更改 ``admin`` 用户的初始密码。 + +**推荐密码策略:** + +|Fess| 具备强制密码最小/最大长度及字符类型要求的内置功能。请在 ``fess_config.properties`` 中设置以下属性（括号内为默认值）。 + +- ``password.min.length`` （默认值: ``8``）：最小长度。建议设置为 12 以上。 +- ``password.max.length`` （默认值: ``100``）：最大长度。 +- ``password.require.uppercase`` （默认值: ``false``）：要求包含大写字母。 +- ``password.require.lowercase`` （默认值: ``false``）：要求包含小写字母。 +- ``password.require.digit`` （默认值: ``false``）：要求包含数字。 +- ``password.require.special.char`` （默认值: ``false``）：要求包含符号。 + +.. note:: + + 默认情况下，最小长度为 ``8``，且所有字符类型要求均处于禁用状态。若要增强密码强度，请显式设置上述属性。另外，|Fess| 没有密码过期（强制定期更改）功能。如果希望将定期更改密码作为运维规则强制执行，请手动进行。 + +启用 OpenSearch 安全插件 +-------------------------------------- + +**步骤:** + +1. 从 ``opensearch.yml`` 中删除或注释掉以下行:: + + # plugins.security.disabled: true + +2. 配置安全插件:: + + plugins.security.allow_default_init_securityindex: true + plugins.security.authcz.admin_dn: + - CN=admin,OU=SSL,O=Test,L=Test,C=DE + +3. 配置 TLS/SSL 证书 + +4. 重启 OpenSearch + +5. 在 |Fess| 一侧配置连接到 OpenSearch 的信息。 + + 请通过环境变量 ``SEARCH_ENGINE_HTTP_URL`` 指定连接 URL（可编辑 ``bin/fess.in.sh`` 或服务的环境配置文件；默认值来自 ``fess_config.properties`` 中的 ``search_engine.http.url``）:: + + SEARCH_ENGINE_HTTP_URL=https://opensearch:9200 + + 请通过 ``fess_config.properties`` 中的以下属性指定认证信息（不存在 ``SEARCH_ENGINE_USERNAME`` / ``SEARCH_ENGINE_PASSWORD`` 这样的环境变量）:: + + search_engine.username=admin + search_engine.password= + +详情请参阅 `OpenSearch Security Plugin `__\ 。 + +启用 HTTPS +------------ + +HTTP 通信未加密，存在窃听或篡改的风险。在生产环境中必须使用 HTTPS。 + +**方法 1: 使用反向代理（推荐）** + +在 |Fess| 前端部署 Nginx 或 Apache，进行 HTTPS 终止。 + +Nginx 配置示例:: + + server { + listen 443 ssl http2; + server_name your-fess-domain.com; + + ssl_certificate /path/to/cert.pem; + ssl_certificate_key /path/to/key.pem; + + ssl_protocols TLSv1.2 TLSv1.3; + ssl_ciphers HIGH:!aNULL:!MD5; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + } + +**方法 2: 在 Fess 自身配置 HTTPS** + +在 ``tomcat_config.properties`` 中添加以下内容:: + + tomcat.secure=true + tomcat.scheme=https + tomcat.SSLEnabled=true + tomcat.certificateKeystoreFile=[密钥库文件路径] + tomcat.certificateKeystorePassword=[创建密钥库文件时指定的密码] + tomcat.certificateKeyAlias=[证书别名] + tomcat.sslProtocol=[SSL 协议（例如：TLS）] + tomcat.enabledProtocols=启用的协议列表（逗号分隔）（例如：TLSv1.2,TLSv1.1,TLSv1） + +推荐的安全配置 +==================== + +防火墙设置 +------------------ + +仅开放必要的端口，关闭不必要的端口。 + +**应开放的端口:** + +- **8080**\ （或 HTTPS 的 443）: |Fess| Web 界面（如需要外部访问） +- **22**: SSH（仅限管理用，仅允许可信 IP 地址） + +**应关闭的端口:** + +- **9200, 9300**: OpenSearch（仅限内部通信，阻止外部访问） + +Linux (firewalld) 配置示例:: + + $ sudo firewall-cmd --permanent --add-service=http + $ sudo firewall-cmd --permanent --add-service=https + $ sudo firewall-cmd --permanent --remove-service=opensearch # 自定义服务的情况 + $ sudo firewall-cmd --reload + +IP 地址限制:: + + $ sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="192.168.1.0/24" port port="8080" protocol="tcp" accept' + +访问控制设置 +---------------- + +考虑将管理页面的访问限制为特定 IP 地址。 + +Nginx 访问限制示例:: + + location /admin { + allow 192.168.1.0/24; + deny all; + + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + } + +角色与访问控制 +-------------------- + +|Fess| 预置了两个角色。 + +- ``admin``: 可执行包括管理页面在内的所有操作的管理员角色 +- ``guest``: 分配给未登录（匿名）用户的角色 + +除此之外的角色可以在管理页面中自由创建。\ |Fess| 中的角色只是一个仅有名称的标签，主要用于搜索结果的访问控制（决定用户可以查看哪些文档）。但是，名称为 ``admin-`` 后接管理页面名称的角色（例如 ``admin-user`` 或 ``admin-scheduler``）是打开相应管理页面的权限；带有 ``-view`` 的角色（例如 ``admin-user-view``）仅允许只读访问。 + +.. warning:: + + ``admin-*`` 角色用于将日常使用的管理页面分配给不同的运维人员，但它并不是权限边界。例如，拥有 ``admin-user`` 的用户可以将包括管理员角色在内的任意现有角色授予任意用户；``admin-accesstoken`` 可以颁发带有 ``Radmin-api`` 权限（可使用 Admin API 的全部功能）的访问令牌；``admin-scheduler`` 可以在服务器上执行脚本作业；``admin-plugin`` 可以安装插件。请将所有 ``admin-*`` 角色视同管理员角色（``authentication.admin.roles``，默认值为 ``admin``），仅授予受信任的运维人员。 + +遵循最小权限原则，管理员角色（``admin``）仅应授予执行管理业务的用户，不要授予普通搜索用户。 + +**步骤:** + +1. 在管理页面点击「用户」→「角色」 +2. 创建必要的角色 +3. 在「用户」→「用户」中为用户分配角色 + +审计日志 +-------- + +认证、管理操作等系统操作历史，默认会作为审计日志被记录。审计日志由 ``log4j2.xml`` 中定义的 ``fess.log.audit`` 记录器输出，默认输出目标为 ``audit.log``\ 。 + +由于默认已启用，无需额外配置。如需自定义输出目标或日志级别，请编辑 ``log4j2.xml`` 中的以下定义:: + + + + + +定期安全更新 +------------------------------ + +请定期应用 |Fess| 和 OpenSearch 的安全更新。 + +**推荐步骤:** + +1. 定期确认安全信息 + + - `Fess 发布信息 `__ + - `OpenSearch 安全公告 `__ + +2. 在测试环境验证更新 +3. 将更新应用到生产环境 + +数据保护 +======== + +备份加密 +------------------ + +备份数据可能包含机密信息。请加密保存备份文件。 + +加密备份示例:: + + $ tar czf fess-backup.tar.gz /var/lib/opensearch /etc/fess + $ gpg --symmetric --cipher-algo AES256 fess-backup.tar.gz + +安全最佳实践 +============================ + +最小权限原则 +------------ + +- 不要以 root 用户运行 Fess 和 OpenSearch +- 使用专用用户账号运行 +- 授予最小必要的文件系统权限 + +网络隔离 +-------------- + +- 将 OpenSearch 部署在专用网络 +- 内部通信使用 VPN 或专用网络 +- 仅将 |Fess| 的 Web 界面部署在 DMZ + +定期安全审计 +---------------------- + +- 定期确认访问日志 +- 检测异常访问模式 +- 定期实施脆弱性扫描 + +安全头配置 +------------------------ + +根据需要，在 Nginx 或 Apache 中配置安全头:: + + add_header X-Frame-Options "SAMEORIGIN" always; + add_header X-Content-Type-Options "nosniff" always; + add_header X-XSS-Protection "1; mode=block" always; + add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; + add_header Content-Security-Policy "default-src 'self'" always; + +安全检查清单 +======================== + +部署到生产环境前，请确认以下检查清单： + +基本设置 +-------- + +- [ ] 已更改管理员密码 +- [ ] 已启用 HTTPS +- [ ] 已更改默认端口号（可选） + +网络安全 +---------------------- + +- [ ] 已用防火墙关闭不必要的端口 +- [ ] 已对管理页面进行 IP 限制（如可能） +- [ ] 已将 OpenSearch 的访问限制为仅限内部网络 + +访问控制 +---------- + +- [ ] 已适当配置角色和访问权限（仅将管理员角色授予必要的用户） +- [ ] 已删除不必要的用户账号 +- [ ] 已配置密码策略 + +监控和日志 +-------- + +- [ ] 已确认审计日志已启用 +- [ ] 已配置日志保存期限 +- [ ] 已构建日志监控机制（如可能） + +备份和恢复 +-------------------- + +- [ ] 已设置定期备份计划 +- [ ] 已加密备份数据 +- [ ] 已验证恢复步骤 + +更新和补丁管理 +---------------------- + +- [ ] 已建立接收安全更新通知的机制 +- [ ] 已文档化更新步骤 +- [ ] 已建立在测试环境验证更新的体系 + +安全事件响应 +========================== + +发生安全事件时的响应步骤： + +1. **检测事件** + + - 确认日志 + - 检测异常访问模式 + - 确认系统行为异常 + +2. **初期响应** + + - 确定影响范围 + - 防止损害扩大（停止相关服务等） + - 保全证据 + +3. **调查和分析** + + - 详细分析日志 + - 确定入侵路径 + - 确定可能泄漏的数据 + +4. **恢复** + + - 修复脆弱性 + - 恢复系统 + - 加强监控 + +5. **事后处理** + + - 创建事件报告 + - 实施防止再发措施 + - 向相关人员报告 + +参考信息 +====== + +- `OpenSearch Security Plugin `__ +- `OWASP Top 10 `__ +- `CIS Benchmarks `__ + +如有安全相关的问题或疑问，请联系： + +- Issues: https://github.com/codelibs/fess/issues +- 商业支持: https://www.n2sm.net/ diff --git a/zh-cn/15.10/install/troubleshooting.rst b/zh-cn/15.10/install/troubleshooting.rst new file mode 100644 index 000000000..904513501 --- /dev/null +++ b/zh-cn/15.10/install/troubleshooting.rst @@ -0,0 +1,593 @@ +================== +故障排除 +================== + +本页面说明 |Fess| 的安装、启动、运维时的常见问题及其解决方法。 + +安装时的问题 +================== + +Java 未被识别 +----------------- + +**症状:** + +:: + + -bash: java: command not found + +或:: + + 'java' is not recognized as an internal or external command + +**原因:** + +Java 未安装，或 PATH 环境变量未正确设置。 + +**解决方法:** + +1. 确认 Java 是否已安装:: + + $ which java + $ java -version + +2. 如未安装，请安装 Java 21:: + + # Ubuntu/Debian + $ sudo apt-get update + $ sudo apt-get install openjdk-21-jdk + + # RHEL/CentOS + $ sudo yum install java-21-openjdk + + Debian 12 的标准软件源中没有 ``openjdk-21-jdk`` 软件包。在 Debian 12 上，请改为按照 `Adoptium 的 Linux 安装说明 `__ 中适用于 Debian 的步骤安装 Eclipse Temurin 21。 + +3. 设置 JAVA_HOME 环境变量:: + + $ export JAVA_HOME=/path/to/java + $ export PATH=$JAVA_HOME/bin:$PATH + + 要永久设置，请添加到 ``~/.bashrc`` 或 ``/etc/profile``。 + +插件安装失败 +------------------------------- + +**症状:** + +:: + + ERROR: Plugin installation failed + +**原因:** + +- 网络连接问题 +- 插件版本与 OpenSearch 版本不匹配 +- 权限问题 + +**解决方法:** + +1. 确认 OpenSearch 版本:: + + $ /path/to/opensearch/bin/opensearch --version + +2. 将插件版本与 OpenSearch 版本匹配:: + + $ /path/to/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + +3. 确认权限:: + + $ sudo /path/to/opensearch/bin/opensearch-plugin install ... + +4. 通过代理安装:: + + $ export ES_JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080" + $ /path/to/opensearch/bin/opensearch-plugin install ... + +启动时的问题 +========== + +Fess 无法启动 +--------------- + +**症状:** + +执行 Fess 的启动命令时出现错误或立即终止。 + +**确认项目:** + +1. **确认 OpenSearch 是否启动**:: + + $ curl http://localhost:9200/ + + 如果正常，会返回 JSON 响应。 + + 没有 OpenSearch 响应时，|Fess| 会重试约 1 分钟后停止启动，并在控制台和 ``logs/fess.log`` 中输出以下消息:: + + The search engine at http://localhost:9200 did not become available within 60221ms. Check that OpenSearch is running and reachable. If there is none yet, run bin/fess-setup install opensearch to set one up. + + 请启动 OpenSearch，或确认 ``SEARCH_ENGINE_HTTP_URL``\ 。新安装的 ZIP 版在使用 ``bin/fess-setup install opensearch`` 设置之前没有 OpenSearch；请参阅 :doc:`install-linux`\ 。 + +2. **确认端口号冲突**:: + + $ sudo ss -tuln | grep 8080 + + 如果端口 8080 已被使用，请在配置文件中更改端口号。 + +3. **确认日志文件**:: + + $ tail -f /path/to/fess/logs/fess.log + + 从错误消息中找出原因。 + +4. **确认 Java 版本**:: + + $ java -version + + 请确认已安装 Java 21 或更高版本。 + +5. **确认内存不足**:: + + $ free -h + + 如果内存不足，请调整堆大小或增加系统内存。 + +OpenSearch 无法启动 +--------------------- + +**症状:** + +:: + + ERROR: bootstrap checks failed + +**原因:** + +系统配置不满足 OpenSearch 的要求。 + +**解决方法:** + +1. **设置 vm.max_map_count**:: + + $ sudo sysctl -w vm.max_map_count=262144 + + 永久设置:: + + $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf + $ sudo sysctl -p + +2. **增加文件描述符上限**:: + + $ sudo vi /etc/security/limits.conf + + 添加以下内容:: + + opensearch - nofile 65535 + opensearch - nproc 4096 + +3. **设置内存锁定**:: + + $ sudo vi /etc/security/limits.conf + + 添加以下内容:: + + opensearch - memlock unlimited + +4. 重启 OpenSearch:: + + $ sudo systemctl restart opensearch + +无法创建索引（词典文件路径） +---------------------------- + +**症状:** + +访问 |Fess| 时返回 HTTP 404，并且 ``fess.log`` 中输出以下错误:: + + Failed to create index: index=fess, path=fess_indices/fess.json + ... reason=Resource path must be inside config directory: /var/lib/opensearch/data/config/ja/mapping.txt + +**原因:** + +从 OpenSearch 3.8.0 开始，如果词典文件位于 OpenSearch 配置目录之外，OpenSearch 会拒绝创建索引。 +``configsync.config_path`` 和 ``FESS_DICTIONARY_PATH`` 指向了配置目录之外的位置（如 ``data/config/``\ ）。 + +**解决方法:** + +1. 将 ``configsync.config_path`` 和 ``FESS_DICTIONARY_PATH`` 更改为 OpenSearch 配置目录下的目录。 + + - RPM/DEB 版：``/etc/opensearch/dictionary/`` + - ZIP 版：``/path/to/opensearch-3.9.0/config/dictionary/`` + +2. 如果已有词典文件，请将其复制到新目录。 +3. 按 OpenSearch、|Fess| 的顺序重新启动。 + +详情请参阅 :doc:`install-linux`。 + +端口号冲突 +-------------- + +**症状:** + +:: + + Address already in use + +**解决方法:** + +1. 确认使用中的端口:: + + $ sudo ss -tuln | grep 8080 + $ sudo lsof -i :8080 + +2. 停止使用中的进程，或更改 Fess 的端口号 + + 有关更改端口号，请参阅 :doc:端口与网络配置 <../config/setup-port-network>。 + +连接问题 +======== + +Fess 无法连接到 OpenSearch +------------------------------- + +**症状:** + +日志中显示以下错误:: + + Connection refused + 或 + No route to host + +**解决方法:** + +1. **确认 OpenSearch 是否启动**:: + + $ curl http://localhost:9200/ + +2. **确认连接 URL** + + 确认 ``fess.in.sh`` 或 ``fess.in.bat`` 中设置的 URL 是否正确:: + + SEARCH_ENGINE_HTTP_URL=http://localhost:9200 + +3. **确认防火墙**:: + + $ sudo firewall-cmd --list-all + + 确认端口 9200 是否开放。 + +4. **确认网络连接** + + 如果在其他主机上运行 OpenSearch:: + + $ ping opensearch-host + $ telnet opensearch-host 9200 + +无法从浏览器访问 Fess +---------------------------------- + +**症状:** + +无法在浏览器中访问 http://localhost:8080/。 + +**解决方法:** + +1. **确认 Fess 是否启动**:: + + $ ps aux | grep fess + +2. **尝试在本地主机访问**:: + + $ curl http://localhost:8080/ + +3. **确认防火墙**:: + + $ sudo firewall-cmd --list-all + + 确认端口 8080 是否开放。 + +4. **从其他主机访问** + + 确认 Fess 是否在本地主机以外监听:: + + $ ss -tuln | grep 8080 + + 如果是 ``127.0.0.1:8080``，请更改配置为 ``0.0.0.0:8080`` 或特定 IP 地址监听。 + +性能问题 +================== + +搜索速度慢 +-------- + +**原因:** + +- 索引大小大 +- 内存不足 +- 磁盘 I/O 慢 +- 查询复杂 + +**解决方法:** + +1. **增加堆大小** + + 将 ``FESS_HEAP_SIZE`` 作为环境变量传入并启动 |Fess|:: + + $ FESS_HEAP_SIZE=4g bin/fess + + 如果在 ``bin/fess.in.sh`` 中设置，请将 ``FESS_HEAP_SIZE=4g`` 写在决定堆大小的那一行（设置 ``FESS_MIN_MEM`` 默认值的那一行）\ **之前**\ 。即使追加到文件末尾，此时堆大小已经确定，因此不会生效。RPM/DEB 版请在 ``/etc/sysconfig/fess``\ （DEB 版为 ``/etc/default/fess``）中设置。 + + 同时调整 OpenSearch 的堆大小:: + + export OPENSEARCH_JAVA_OPTS="-Xms4g -Xmx4g" + +2. **使用 SSD** + + 如果磁盘 I/O 是瓶颈，请迁移到 SSD。 + +3. **启用缓存** + + 在配置文件中启用查询缓存。 + +爬取速度慢 +----------- + +**原因:** + +- 爬取间隔长 +- 目标网站响应慢 +- 线程数少 + +**解决方法:** + +1. **调整爬取间隔** + + 在管理页面的爬取配置中缩短「间隔」（毫秒单位）。 + + .. warning:: + + 间隔太短会对目标网站造成负担。请设置适当的值。 + +2. **增加线程数** + + 在管理页面中增大爬取配置的「线程数」。默认值：Web 爬取为 1，文件系统爬取为 5。 + +3. **调整超时值** + + 对于响应慢的网站，请增加超时值。 + +数据问题 +========== + +不显示搜索结果 +-------------------- + +**原因:** + +- 索引未创建 +- 爬取失败 +- 搜索查询错误 + +**解决方法:** + +1. **确认索引**:: + + $ curl http://localhost:9200/_cat/indices?v + + 确认 |Fess| 的索引是否存在。 + +2. **确认爬取日志** + + 从管理页面的「系统信息」→「日志文件」下载爬取日志（``fess-crawler.log``），检查是否有错误。 + +3. **重新执行爬取** + + 从管理页面的「系统」→「调度器」执行「Default Crawler」。 + +4. **简化搜索查询** + + 先使用简单关键词搜索，确认是否返回结果。 + +索引损坏 +------------------------ + +**症状:** + +搜索时出现错误或返回意外结果。 + +**解决方法:** + +1. **删除并重建索引** + + .. warning:: + + 删除索引会丢失所有搜索数据。请务必获取备份。 + + :: + + $ curl -X DELETE http://localhost:9200/fess* + +2. **重启 Fess** + + 索引在 |Fess| 启动时创建。刚删除之后，用户信息的索引也已丢失，因此无法登录管理页面（``/api/v2/health`` 仍会返回 ``200``）。重启 |Fess| 后，索引、默认作业和初始用户（``admin``）会被重新创建。 + +3. **重新执行爬取** + + 从管理页面执行「Default Crawler」，重新登记要检索的文档。 + +Docker 特有的问题 +=============== + +容器无法启动 +------------------ + +**症状:** + +``docker compose up`` 容器无法启动。 + +**解决方法:** + +1. **确认日志**:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs + +2. **确认内存不足** + + 增加分配给 Docker 的内存（从 Docker Desktop 的设置）。 + +3. **确认端口冲突**:: + + $ docker ps + + 确认其他容器是否在使用端口 8080 或 9200。 + +4. **确认 Docker Compose 文件** + + 确认 YAML 文件是否有语法错误:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml config + +容器启动但无法访问 Fess +---------------------------------------- + +**解决方法:** + +1. **确认容器状态**:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps + +2. **确认日志**:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs fess + +3. **确认网络设置**:: + + $ docker network ls + $ docker network inspect + +Windows 特有的问题 +================ + +路径问题 +-------- + +**症状:** + +路径包含空格或日文时出现错误。 + +**解决方法:** + +请安装到不包含空格或日文的目录。 + +例:: + + C:\opensearch (推荐) + C:\Program Files\opensearch (不推荐) + +无法注册为服务 +------------------------ + +**解决方法:** + +使用 NSSM 等第三方工具注册为 Windows 服务。 + +详情请参阅 :doc:`install-windows`。 + +其他问题 +========== + +更改日志级别 +-------------- + +要确认详细日志，请将日志级别更改为 DEBUG。 + +编辑 ``log4j2.xml``:: + + + +重置数据库 +-------------------- + +要重置配置，请删除 OpenSearch 的索引:: + + $ curl -X DELETE 'http://localhost:9200/fess_config.*' + +.. warning:: + + 执行此命令会删除所有配置数据。 + +忘记管理员密码 +-------------- + +如果忘记了管理员密码，可以直接更新 OpenSearch 的 ``fess_user.user`` 索引中的用户文档来重置密码。密码以 ``{bcrypt}$2a$...`` 形式的哈希保存在 ``password`` 字段中。更新后无需重启 |Fess| 即可生效。 + +1. 生成新密码的哈希。|Fess| 只接受以 ``$2a$`` 开头的 bcrypt 哈希，因此请将 ``htpasswd``\ （包含在 ``apache2-utils`` 或 ``httpd-tools`` 软件包中）输出的 ``$2y$`` 替换为 ``$2a$``\ 。请将 ``NewPassword`` 替换为新密码:: + + $ HASH=$(htpasswd -bnBC 10 "" 'NewPassword' | tr -d ':\n' | sed 's/^\$2y/$2a/') + +2. 更新 admin 用户文档中的密码。初始状态下 admin 用户的文档 ID 为 ``YWRtaW4=``:: + + $ curl -X POST 'http://localhost:9200/fess_user.user/_update/YWRtaW4=?refresh=true' \ + -H 'Content-Type: application/json' \ + -d "{\"doc\":{\"password\":\"{bcrypt}${HASH}\"}}" + + 要重置其他用户的密码，请用 ``curl 'http://localhost:9200/fess_user.user/_search?q=name:用户名'`` 查询 ``_id``\ ，并指定该 ID。如果为 OpenSearch 启用了认证，请在 curl 中指定认证信息。 + +3. 确认可以使用新密码登录管理页面。如果命令历史中残留了密码，请在登录后通过 [用户 > 用户] 重新设置密码。 + +支持信息 +========== + +如果问题无法解决，请使用以下支持资源： + +社区支持 +------------------ + +- **Issues**: https://github.com/codelibs/fess/issues + + 报告问题时，请包含以下信息： + + - Fess 版本 + - OpenSearch 版本 + - 操作系统和版本 + - 错误消息（从日志中摘录） + - 重现步骤 + +- **论坛**: https://discuss.codelibs.org/ + +商业支持 +---------- + +如需商业支持，请联系 N2SM, Inc.： + +- **网站**: https://www.n2sm.net/ + +收集调试信息 +================ + +报告问题时，收集以下信息会有所帮助： + +1. **版本信息**\ （``bin/fess -v`` 从 15.10 起可用）:: + + $ /path/to/fess/bin/fess -v + $ /path/to/opensearch/bin/opensearch --version + $ java -version + +2. **系统信息**:: + + $ uname -a + $ cat /etc/os-release + $ free -h + $ df -h + +3. **日志文件**:: + + $ tar czf fess-logs.tar.gz /path/to/fess/logs/ + +4. **配置文件**\ （删除机密信息后）:: + + $ tar czf fess-config.tar.gz /path/to/fess/app/WEB-INF/conf/ + +5. **OpenSearch 状态**:: + + $ curl http://localhost:9200/_cluster/health?pretty + $ curl http://localhost:9200/_cat/indices?v diff --git a/zh-cn/15.10/install/uninstall.rst b/zh-cn/15.10/install/uninstall.rst new file mode 100644 index 000000000..bc1a97735 --- /dev/null +++ b/zh-cn/15.10/install/uninstall.rst @@ -0,0 +1,480 @@ +========== +卸载步骤 +========== + +本页面说明完全卸载 |Fess| 的步骤。 + +.. warning:: + + **卸载前的重要注意事项** + + - 卸载会删除所有数据 + - 如有重要数据，请务必获取备份 + - 关于备份步骤，请参阅 :doc:`upgrade` + +卸载前的准备 +============ + +获取备份 +-------- + +请备份必要的数据： + +1. **配置数据** + + 从管理页面的「系统」→「备份」下载。 + 通过此操作，可以将各种配置（包括爬取配置）以及搜索日志等一并导出。 + +2. **定制的配置文件** + + ZIP 版:: + + $ cp -r /path/to/fess/app/WEB-INF/conf /backup/ + $ cp -r /path/to/fess/app/WEB-INF/classes /backup/ + + RPM/DEB 版:: + + $ sudo cp -r /etc/fess /backup/ + +.. note:: + + |Fess| 的索引和大部分配置都保存在 OpenSearch 中。 + 备份索引数据时，请使用 OpenSearch 的快照功能。 + 详细步骤请参阅 :doc:`upgrade`。 + +停止服务 +-------- + +卸载前，停止所有服务。 + +ZIP 版:: + + $ ps aux | grep -E 'fess|opensearch' + $ kill + $ kill + +RPM/DEB 版:: + + $ sudo systemctl stop fess.service + $ sudo systemctl stop opensearch.service + +Docker 版:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +ZIP 版的卸载 +=================== + +步骤 1: 删除 Fess +----------------- + +删除安装目录:: + + $ rm -rf /path/to/fess-15.10.0 + +步骤 2: 删除 OpenSearch +----------------------- + +删除 OpenSearch 的安装目录:: + + $ rm -rf /path/to/opensearch-3.9.0 + +步骤 3: 删除数据目录（可选） +-------------------------- + +|Fess| 的索引数据保存在 OpenSearch 中。 +默认情况下保存在 OpenSearch 的安装目录内（如 ``opensearch-3.9.0/data``）， +但如果通过 ``path.data`` 指定了其他位置，请同时删除该目录:: + + $ rm -rf /path/to/data + +步骤 4: 删除日志目录（可选） +-------------------------- + +删除日志文件:: + + $ rm -rf /path/to/fess-15.10.0/logs + $ rm -rf /path/to/opensearch-3.9.0/logs + +RPM 版的卸载 +============ + +步骤 1: 卸载 Fess +----------------- + +卸载 RPM 包:: + + $ sudo rpm -e fess + +.. note:: + + 卸载 |Fess| 包时，包的删除脚本会自动停止并禁用 ``fess`` 服务， + 并删除 ``fess`` 用户和组。 + 后续步骤用于确认这些已被确实删除，或用于手动删除数据和配置文件。 + +步骤 2: 卸载 OpenSearch +----------------------- + +:: + + $ sudo rpm -e opensearch + +步骤 3: 确认服务已禁用 +-------------------- + +通常在删除包时服务会被禁用，但如需保险起见进行确认和禁用，请执行以下命令。 + +systemd 的情况:: + + $ sudo systemctl disable fess.service + $ sudo systemctl disable opensearch.service + $ sudo systemctl daemon-reload + +旧版 SysV init（chkconfig）环境的情况:: + + $ sudo /sbin/chkconfig --del fess + $ sudo /sbin/chkconfig --del opensearch + +步骤 4: 删除数据目录 +------------------ + +.. warning:: + + 执行此操作会完全删除所有索引数据。 + +数据目录在卸载包时不会被删除，因此需要手动删除:: + + $ sudo rm -rf /var/lib/fess + $ sudo rm -rf /var/lib/opensearch + +步骤 5: 删除配置文件 +------------------ + +删除配置文件和环境配置文件:: + + $ sudo rm -rf /etc/fess + $ sudo rm -rf /etc/sysconfig/fess + $ sudo rm -rf /etc/opensearch + +.. note:: + + 在 RPM 中，``/etc/fess`` 内的配置文件可能会以 ``.rpmsave`` 的名称保留。 + 要完全删除，请如上所述手动删除。 + +步骤 6: 删除日志文件 +------------------ + +:: + + $ sudo rm -rf /var/log/fess + $ sudo rm -rf /var/log/opensearch + +步骤 7: 删除临时目录（可选） +-------------------------- + +:: + + $ sudo rm -rf /var/tmp/fess + +步骤 8: 删除用户和组（可选） +-------------------------- + +通常在删除包时 ``fess`` 用户和组会被删除。 +如果仍有残留，或要删除 OpenSearch 用的用户和组，请执行以下命令:: + + $ sudo userdel fess + $ sudo groupdel fess + $ sudo userdel opensearch + $ sudo groupdel opensearch + +DEB 版的卸载 +============ + +步骤 1: 卸载 Fess +----------------- + +卸载 DEB 包:: + + $ sudo dpkg -r fess + +如需包括配置文件和环境配置文件在内完全删除，请使用 purge:: + + $ sudo dpkg -P fess + +.. note:: + + 使用 ``dpkg -r``\ （remove）时，作为配置文件（conffile）的 ``/etc/default/fess`` 等会保留。 + 使用 ``dpkg -P``\ （purge）时，这些配置文件以及 ``fess`` 用户和组也会被删除。 + +步骤 2: 卸载 OpenSearch +----------------------- + +:: + + $ sudo dpkg -r opensearch + +或者，包括配置文件一并删除:: + + $ sudo dpkg -P opensearch + +步骤 3: 确认服务已禁用 +-------------------- + +通常在删除包时服务会被禁用。如需保险起见进行确认和禁用，请执行以下命令:: + + $ sudo systemctl disable fess.service + $ sudo systemctl disable opensearch.service + $ sudo systemctl daemon-reload + +步骤 4: 删除数据目录 +------------------ + +.. warning:: + + 执行此操作会完全删除所有索引数据。 + +:: + + $ sudo rm -rf /var/lib/fess + $ sudo rm -rf /var/lib/opensearch + +步骤 5: 删除配置文件（如未使用 dpkg -P） +------------------------------------ + +:: + + $ sudo rm -rf /etc/fess + $ sudo rm -rf /etc/default/fess + $ sudo rm -rf /etc/opensearch + +步骤 6: 删除日志文件 +------------------ + +:: + + $ sudo rm -rf /var/log/fess + $ sudo rm -rf /var/log/opensearch + +步骤 7: 删除用户和组（可选） +-------------------------- + +如果未使用 ``dpkg -P``，则 ``fess`` 用户和组会保留。 +如需删除，请执行以下命令:: + + $ sudo userdel fess + $ sudo groupdel fess + $ sudo userdel opensearch + $ sudo groupdel opensearch + +Docker 版的卸载 +=============== + +步骤 1: 删除容器和网络 +-------------------- + +删除容器，以及 Docker Compose 创建的网络（``search_net``）:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +步骤 2: 删除卷 +------------ + +.. warning:: + + 执行此操作会完全删除所有数据。 + +|Fess| 的数据（索引和词典等）保存在 OpenSearch 的卷中。 +首先，确认卷列表:: + + $ docker volume ls + +删除 OpenSearch 相关的卷:: + + $ docker volume rm _search01_data + $ docker volume rm _search01_dictionary + +.. note:: + + 卷名会带有 Docker Compose 的项目名（通常是放置 Compose 文件的目录名）作为前缀。 + 请使用 ``docker volume ls`` 确认实际名称。 + +如需一并删除容器和卷，请在 ``down`` 后加上 ``-v`` 选项:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down -v + +步骤 3: 删除镜像（可选） +---------------------- + +如需删除 Docker 镜像以释放磁盘空间:: + + $ docker images | grep fess + $ docker rmi ghcr.io/codelibs/fess:15.10.0 + $ docker rmi ghcr.io/codelibs/fess-opensearch:3.9.0 + +步骤 4: 删除 Compose 文件 +----------------------- + +:: + + $ rm compose.yaml compose-opensearch3.yaml + +确认卸载 +======== + +确认所有组件已删除。 + +确认进程 +-------- + +:: + + $ ps aux | grep fess + $ ps aux | grep opensearch + +如果没有显示任何内容，则进程已停止。 + +确认端口 +-------- + +:: + + $ sudo ss -tuln | grep 8080 + $ sudo ss -tuln | grep 9200 + +确认端口未被使用。 + +确认文件 +-------- + +ZIP 版:: + + $ ls /path/to/fess-15.10.0 # 确认目录不存在 + +RPM/DEB 版:: + + $ ls /var/lib/fess # 确认目录不存在 + $ ls /etc/fess # 确认目录不存在 + +Docker 版:: + + $ docker ps -a | grep -E 'fess01|search01' # 确认容器不存在 + $ docker volume ls | grep search01 # 确认卷不存在 + +确认包 +------ + +RPM 版:: + + $ rpm -qa | grep fess + $ rpm -qa | grep opensearch + +DEB 版:: + + $ dpkg -l | grep fess + $ dpkg -l | grep opensearch + +如果没有显示任何内容，则包已删除。 + +部分卸载 +======== + +仅删除 Fess 保留 OpenSearch +--------------------------- + +如果 OpenSearch 也被其他应用程序使用，可以仅删除 Fess。 + +1. 停止 Fess +2. 删除 Fess 的包或目录 +3. 删除 Fess 的数据目录（如 ``/var/lib/fess``） +4. 删除 OpenSearch 中创建的 |Fess| 索引 + + |Fess| 索引的名称以 ``fess`` 开头（``fess.*``、``fess_config.*``、``fess_user.*``、``fess_log.*``、``fess_crawler.*``、``fess_suggest*`` 等）。可以使用以下命令一并删除。 + + :: + + $ curl -X DELETE 'http://localhost:9200/fess*' + + 删除之前，请先用 ``curl 'http://localhost:9200/_cat/indices?v'`` 确认没有其他应用程序的索引名称以 ``fess`` 开头。用于同步词典的 ``configsync`` 索引，如果没有被其他应用程序使用，也可以删除。 + +5. 不删除 OpenSearch + +仅删除 OpenSearch 保留 Fess +--------------------------- + +.. warning:: + + 删除 OpenSearch 后，Fess 将无法工作。 + 请更改配置以连接到其他 OpenSearch 集群。 + +1. 停止 OpenSearch +2. 删除 OpenSearch 的包或目录 +3. 删除 OpenSearch 的数据目录（如 ``/var/lib/opensearch``） +4. 更新 Fess 的配置以指定其他 OpenSearch 集群 + +故障排除 +======== + +无法删除包 +---------- + +**症状:** + +``rpm -e`` 或 ``dpkg -r`` 出现错误。 + +**解决方法:** + +1. 确认服务已停止:: + + $ sudo systemctl stop fess.service + +2. 确认依赖关系:: + + $ rpm -qa | grep fess + $ dpkg -l | grep fess + +3. 强制删除（最后手段）:: + + $ sudo rpm -e --nodeps fess + $ sudo dpkg -r --force-all fess + +无法删除目录 +---------- + +**症状:** + +``rm -rf`` 无法删除目录。 + +**解决方法:** + +1. 确认权限:: + + $ ls -ld /path/to/directory + +2. 使用 sudo 删除:: + + $ sudo rm -rf /path/to/directory + +3. 确认进程是否在使用文件:: + + $ sudo lsof | grep /path/to/directory + +重新安装的准备 +============ + +如果卸载后要重新安装，请确认以下内容： + +1. 所有进程已停止 +2. 所有文件和目录已删除 +3. 端口 8080 和 9200 未被使用 +4. 没有残留以前的配置文件 + +关于重新安装步骤，请参阅 :doc:`install`。 + +下一步 +====== + +卸载完成后： + +- 要安装新版本，请参阅 :doc:`install` +- 要迁移数据，请参阅 :doc:`upgrade` +- 要考虑替代的搜索解决方案，请参阅 Fess 官方网站 diff --git a/zh-cn/15.10/install/upgrade.rst b/zh-cn/15.10/install/upgrade.rst new file mode 100644 index 000000000..1b2f9a573 --- /dev/null +++ b/zh-cn/15.10/install/upgrade.rst @@ -0,0 +1,1500 @@ +==================== +升级步骤 +==================== + +本页面说明将 |Fess| 从旧版本升级到最新版的步骤。 + +.. warning:: + + **升级前的重要注意事项** + + - 升级前必须获取备份 + - 强烈建议在测试环境提前验证升级 + - 升级期间服务会停止，请设置适当的维护时间 + - 根据版本不同，配置文件的格式可能已更改 + +支持版本 +============ + +本升级步骤支持以下版本之间的升级： + +- Fess 14.x → Fess 15.10 +- Fess 15.x → Fess 15.10 + +.. important:: + + |Fess| 14.x 对应 OpenSearch 2.x 系列，\ |Fess| 15.10 对应 OpenSearch 3.9.0。 + 由于 |Fess| 专用的 OpenSearch 插件必须与 OpenSearch 版本完全一致， + 因此从 14.x 升级时，也必须同时对 OpenSearch 进行主版本升级。 + 请参阅 :ref:`upgrade-opensearch`。 + +.. note:: + + 如果从更旧的版本（13.x 及更早）升级，可能需要逐步升级。 + 详情请确认发布说明。 + +升级前的准备 +==================== + +确认版本兼容性 +-------------------- + +请确认升级目标版本与当前版本的兼容性。 + +- `发布说明 `__ +- :doc:`prerequisites` - |Fess| 15.10 的系统要求（Java、OpenSearch 版本） + +计划停机时间 +---------------- + +升级工作需要停止系统。请考虑以下因素计划停机时间： + +- 备份时间: 10分钟 ~ 数小时（取决于数据量） +- 升级时间: 10 ~ 30分钟 +- 运行确认时间: 30分钟 ~ 1小时 +- 预留时间: 30分钟 + +**推荐维护时间**: 总计 2 ~ 4小时 + +步骤 1: 数据备份 +============================== + +升级前，请备份所有数据。 + +备份配置数据 +---------------------- + +1. **从管理页面备份** + + 登录管理页面，点击「系统信息」→「备份」。 + + 备份页面按条目列出以下配置数据。 + 点击各行下载（不是单个 ZIP 文件，而是按条目分别下载的独立文件。 + 由于没有批量下载功能，需要将所需项目逐一下载）。 + + - ``fess_basic_config.bulk`` - 配置索引（爬取设置、调度器、标签、 + 关键词匹配、角色、Web/文件认证等 19 个索引） + - ``fess_config.bulk`` - 除上述 19 个索引外，还包含爬取信息、失败 URL、作业日志、 + 缩略图队列等运行时数据，共 25 个索引（15.8 及之前；15.10 增加了保存用户标签的 + ``tag_type`` 索引，共 26 个） + - ``fess_user.bulk`` - 用户、角色、群组 + - ``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 个文件就已足够。但是，如果备份来源为 15.10 或更高版本且使用了用户标签，由于保存用户标签的 ``tag_type`` 索引不包含在 ``fess_basic_config.bulk`` 中，请同时下载 ``fess_config.bulk``\ （参见 :doc:`../admin/tagtype-guide`\ ）。 + + .. note:: + + 搜索日志、点击日志等日志数据（``search_log.ndjson``、``click_log.ndjson``、 + ``favorite_log.ndjson``、``user_info.ndjson``；15.10 中还会显示 ``chat_log.ndjson``）也可从 + 同一页面下载。 + 如果仅备份配置，则不需要下载这些文件。另外，这些 ``*.ndjson`` 文件无法 + 通过备份页面的上传功能重新导入恢复 + （请参阅「回滚步骤」）。 + +2. **备份配置文件** + + ZIP 版:: + + $ 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 版:: + + $ 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`` 等内容的环境变量文件。 + ZIP 版中与之对应的设置位于 ``bin/fess.in.sh``。 + +3. **定制的配置文件** + + 如有定制的配置文件，也请备份:: + + $ cp /path/to/fess/app/WEB-INF/classes/log4j2.xml /backup/ + $ cp /path/to/fess/lib/classes/tomcat_config.properties /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 的快照功能备份索引。 + +.. note:: + + 要注册文件系统仓库（``fs``），需要事先在 OpenSearch 的 ``opensearch.yml`` 的 + ``path.repo`` 中指定备份目标目录，并重启 OpenSearch。 + +1. 配置仓库:: + + $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup" -H 'Content-Type: application/json' -d' + { + "type": "fs", + "settings": { + "location": "/backup/opensearch/snapshots" + } + }' + +2. 创建快照:: + + $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup/snapshot_1?wait_for_completion=true" + +3. 确认快照:: + + $ curl -X GET "http://localhost:9200/_snapshot/fess_backup/snapshot_1" + +方法 2: 整体备份目录 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +停止 OpenSearch 后，备份数据目录。 + +:: + + $ sudo systemctl stop opensearch + $ sudo tar czf /backup/opensearch-data-$(date +%Y%m%d).tar.gz /var/lib/opensearch/data + $ sudo systemctl start opensearch + +Docker 版的备份 +--------------------- + +OpenSearch 的数据保存在 Docker 卷中。\ ``compose-opensearch3.yaml`` 中定义了 +用于索引数据的 ``search01_data`` 和用于词典文件的 ``search01_dictionary`` +共 2 个卷。 + +.. note:: + + 实际的卷名会附加 Compose 项目名称（默认为放置 Compose 文件的目录名）作为前缀。 + 请使用以下命令确认准确的卷名:: + + $ docker volume ls + +停止容器后，备份卷。\ ``docker run`` 的 ``-v`` 需要指定 +包含前缀的实际卷名:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml stop + $ 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。 + +ZIP 版没有附带用于停止的脚本。\ ``bin/fess`` 如果是使用 ``-p`` 选项 +启动的，可以使用 PID 文件停止:: + + $ kill $(cat /path/to/fess/fess.pid) + $ kill + +如果启动时未指定 ``-p``，请确认进程 ID 后使用 ``kill`` 停止 +（仅使用 ``-d`` 不会创建 PID 文件）。 + +RPM/DEB 版 (systemd):: + + $ sudo systemctl stop fess.service + $ sudo systemctl stop opensearch.service + +Docker 版:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml down + +.. warning:: + + 开始步骤 3 之前，请确认 |Fess| 已经停止，不要替换仍在运行的 |Fess| 的软件包或文件。 + 在运行中的 15.8 的 |Fess| 上将 DEB 软件包替换为 15.10 的软件包后，直到重启 |Fess|， + 搜索页面一直返回 ``404``\ 。软件包版可以通过 ``systemctl status fess.service`` 确认。 + +步骤 3: 安装新版本 +====================================== + +根据安装方法，步骤有所不同。 + +ZIP 版 +------------- + +1. 下载并解压新版本:: + + $ wget https://github.com/codelibs/fess/releases/download/fess-15.10.0/fess-15.10.0.zip + $ unzip fess-15.10.0.zip + + .. note:: + + |Fess| 的归档版仅以 ZIP 格式发布（不提供 + ``fess-15.10.0.tar.gz``）。 + +2. 复制旧版本的配置:: + + $ cp /path/to/old-fess/app/WEB-INF/conf/system.properties /path/to/fess-15.10.0/app/WEB-INF/conf/ + $ cp /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.10.0/app/WEB-INF/classes/ + $ cp /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.10.0/bin/ + + .. warning:: + + 如果原样复制 ``fess_config.properties`` 与 ``fess.in.sh`` ，旧版本的值会被沿用，其中也包括 + 15.10 中默认值已变更的项。例如，升级后新建的作业默认将使用 Groovy。执行最后两条命令之前， + 请将各文件与 ``fess-15.10.0`` 中的文件进行比较，只迁移自己修改过的值。需要确认的项目请参阅 + :ref:`upgrade-159-carried-over-config` 。 + +3. 如有定制内容，请同时复制以下文件:: + + # Tomcat 设置（SAML 所需的 tomcat.sameSiteCookies=none 也在此文件中） + $ cp /path/to/old-fess/lib/classes/tomcat_config.properties /path/to/fess-15.10.0/lib/classes/ + # 已安装的插件 + $ cp -r /path/to/old-fess/app/WEB-INF/plugin/. /path/to/fess-15.10.0/app/WEB-INF/plugin/ + # 自己上传的静态主题（每个主题一个目录；不要复制 bootstrap） + $ cp -r /path/to/old-fess/app/themes/ /path/to/fess-15.10.0/app/themes/ + + .. warning:: + + 如果不复制旧版本的 ``tomcat_config.properties`` ，``tomcat.sameSiteCookies`` 会在没有任何提示的 + 情况下恢复为默认值 ``lax`` ，SAML 登录将无法使用（参阅 :ref:`upgrade-159-saml` ）。 + 该文件的随附内容在 15.8.0 和 15.10 中相同，因此可以原样复制。 + + .. warning:: + + 请不要将 ``log4j2.xml`` 复制并覆盖 15.10 的文件。15.10 的文件将 ``RequestLoggingFilter`` 的 + 日志记录器固定为 ``warn`` ，而复制 15.8 的文件会丢失这一设置：将日志级别设为 DEBUG 时， + 请求头（包括 ``Authorization`` ）和请求参数（包括在登录表单中输入的密码）会被写入日志。 + 请用 ``diff`` 比较这两个文件，只将自己修改过的内容重新应用到 15.10 的文件中。 + + .. warning:: + + 请不要复制整个 ``app/themes/`` 目录。其中还包含 |Fess| 内置的主题 ``bootstrap`` ， + 将其覆盖到 15.10 的主题上，会使 15.10 的搜索界面被 15.8 版本的主题替换。 + 只复制自己创建的主题目录。对于 |Fess| 项目发布的主题，请改为使用 + ``bin/fess-setup install theme `` 安装面向 15.10 的构建（参阅 :doc:`fess-setup` ）。 + + .. warning:: + + 请不要复制在管理页面「页面设计」中编辑过的 JSP（``app/WEB-INF/view/``）。15.10 的搜索 + 界面是静态主题，不再使用这些 JSP；此类修改现在应放在何处，请参阅 + :ref:`upgrade-159-static-theme` 。 + + .. note:: + + 从 ``app/WEB-INF/plugin/`` 复制的插件是为旧版本构建的。复制后，请在 ``fess-15.10.0`` 中执行 + ``bin/fess-setup upgrade plugins`` ，将各插件替换为针对 15.10 构建的版本（参阅 + :ref:`upgrade-plugin-versions` ）。 + +4. 确认配置差异，根据需要进行调整 + +RPM/DEB 版 +---------- + +安装新版本的包:: + + # RPM + $ sudo rpm -Uvh fess-15.10.0.rpm + + # DEB + $ sudo dpkg -i fess-15.10.0.deb + +.. note:: + + RPM 版中，``/etc/fess/*`` 的配置文件被注册为 ``%config(noreplace)``， + 因此在升级时会被保留（新的默认文件会以 ``.rpmnew`` 的形式并存）。 + 如果添加了新的配置选项，需要手动调整。修改过的 ``/etc/fess/fess_config.properties`` 与 ZIP 版 + 步骤中复制的文件一样，在 15.10 中仍使用旧值。请参阅 :ref:`upgrade-159-carried-over-config` 。 + +.. warning:: + + DEB 版中，``/etc/fess`` 下的文件（如 ``fess_config.properties`` 和 + ``tomcat_config.properties`` ）与 ``/etc/default/fess``\ 、\ ``/etc/init.d/fess``\ 、 + ``/usr/lib/systemd/system/fess.service`` 一样，被注册为 conffile。从 15.8 首次升级时， + ``dpkg`` 的处理方式如下。 + + - 从未编辑过的文件，会不经询问直接替换为 15.10 的文件。 + - 对于编辑过的文件，``dpkg`` 会询问。如果保留自己的文件（默认回答，或 ``--force-confold`` ）， + 15.10 的文件会以 ``<文件名>.dpkg-dist`` 的形式并存。如果安装新文件（``Y`` 或 + ``--force-confnew`` ），自己的文件会保存为 ``<文件名>.dpkg-old`` 。 + - 无人可以回答时，``dpkg -i`` 和 ``apt-get install -y`` 会在第一个询问处停止。无人值守升级时， + 请指定 ``--force-confold`` （``--force-confdef`` 同样可以避免询问），例如 + ``sudo dpkg --force-confold -i fess-15.10.0.deb`` 或 + ``sudo apt-get install -y -o Dpkg::Options::=--force-confold ./fess-15.10.0.deb`` 。 + + 无论哪种情况，都请事先备份 ``/etc/fess`` （步骤 1）。保留下来的文件仍是 15.8 的值， + 因此不要原样使用，请与 ``.dpkg-dist`` 文件比较（参阅 :ref:`upgrade-159-carried-over-config` ）。 + 另外，``/etc/fess/system.properties`` 是不包含在软件包中的运行时生成文件， + 因此不会被覆盖。 + +Docker 版 +--------- + +1. 获取新版本的 Compose 文件:: + + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose.yaml + $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.10.0/compose/compose-opensearch3.yaml + +2. 获取新镜像:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull + +.. _upgrade-opensearch: + +步骤 4: 升级 OpenSearch +==================================== + +|Fess| 15.10 对应 OpenSearch 3.9.0。如果所连接的 OpenSearch 版本比这更旧， +请按照以下步骤升级。 + +.. note:: + + 本步骤适用于 ZIP 版及 RPM/DEB 版中手动运维 OpenSearch 的情况。 + 对于 Docker 版，在步骤 3 中获取新镜像时，OpenSearch 和插件也会一并更新， + 因此无需执行本步骤。 + +.. important:: + + 无论是否使用分块向量搜索（语义搜索），\ |Fess| 15.10 都会在搜索索引的设置中始终 + 包含 ``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 升级时必然属于这种情况。 + + 在 OpenSearch 3.9.0 上创建的快照无法恢复到 OpenSearch 3.8.0 及更早版本。请保留升级前创建的快照，以备回滚。 + +1. 安装新版本的 OpenSearch + +2. 重新安装插件:: + + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip + $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip + + .. note:: + + 这些插件的版本必须与所使用的 OpenSearch 版本一致。 + |Fess| 15.10 对应 OpenSearch 3.9.0。如果版本不一致， + 插件安装将会失败。 + + |Fess| 的 4 个插件发布在 maven.codelibs.org 上，因此通过 URL 指定。 ``opensearch-plugin install`` 的 ``groupId:artifactId:version`` 形式只查找 Maven Central。 + +3. 将词典目录移至 OpenSearch 配置目录下 + + 从 OpenSearch 3.8.0 开始，如果词典文件位于 OpenSearch 配置目录之外，OpenSearch 会拒绝创建索引。 + 如果按照以前的步骤在 ``configsync.config_path`` 中指定了 ``/var/lib/opensearch/data/config/``\ （ZIP 版为 ``/path/to/opensearch/data/config/``\ ）等配置目录之外的位置， + |Fess| 将无法创建索引，也无法启动。 + 对于 RPM/DEB 版，请按如下方式将词典文件复制到 ``/etc/opensearch/dictionary/``:: + + $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary + $ sudo cp -a /var/lib/opensearch/data/config/. /etc/opensearch/dictionary/ + $ sudo chown -R opensearch:opensearch /etc/opensearch/dictionary + + 然后，将 ``/etc/opensearch/opensearch.yml`` 中的 ``configsync.config_path`` 和 |Fess| 的 ``FESS_DICTIONARY_PATH``\ （RPM 版为 ``/etc/sysconfig/fess``\ ，DEB 版为 ``/etc/default/fess``\ ）都更改为 ``/etc/opensearch/dictionary/``\ 。 + 对于 ZIP 版，请使用 OpenSearch 的 ``config/dictionary/``\ 。详情请参阅 :doc:`install-linux`。 + +4. 启动 OpenSearch:: + + $ sudo systemctl start opensearch.service + +步骤 5: 启动新版本 +================================ + +ZIP 版:: + + $ cd /path/to/fess-15.10.0 + $ ./bin/fess -d -p /path/to/fess-15.10.0/fess.pid + +.. note:: + + 指定 ``-p`` 后会创建 PID 文件，下次停止时可以使用 + ``kill $(cat /path/to/fess-15.10.0/fess.pid)`` 来停止。 + +RPM/DEB 版:: + + $ sudo systemctl start opensearch.service + $ sudo systemctl start fess.service + +Docker 版:: + + $ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d + +步骤 6: 运行确认 +================== + +1. **确认日志** + + 确认没有错误。 + + 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/。 + +3. **登录管理页面** + + 访问 http://localhost:8080/admin 并使用管理员账号登录。 + +4. **确认版本** + + 在管理页面点击「系统信息」→「配置信息」，确认「系统属性」中显示的 + ``fess.version`` 已更新为新版本。 + +5. **确认搜索运行** + + 在搜索页面执行搜索，确认正常返回结果。 + +步骤 7: 重建索引（推荐） +==================================== + +对于主版本升级，建议重建索引。 + +.. note:: + + 以下步骤只是重新执行爬取，并不会更新索引映射（字段定义）。如果需要进行会更新映射的重新 + 索引——例如要新启用分块向量搜索（语义搜索）时——请在管理界面的「系统信息」→「维护」中 + 单独运行「重新索引」。详情请参阅 :ref:`semantic-search-migration`\ （:doc:`../config/search-semantic`）。 + + 如果继续使用由 15.8 或更早版本创建的文档索引，另请参阅 :ref:`upgrade-reindex-new-fields`\ 。 + +.. warning:: + + OpenSearch 3.9.0 会拒绝 15.8 曾接受的字典条目，例如重复保存的同一条 ``mapping`` 条目，或 + 含有空格的 ``kuromoji`` 词元。存在此类条目时，「重新索引」不会创建新的文档索引：``fess.log`` + 中只会输出 ``Failed to create index`` ，旧索引继续提供搜索。请在「系统」→「字典」下载字典， + 删除重复或无效的行后重新上传，然后再次运行「重新索引」。15.10 不再保存的条目请参阅 + :ref:`upgrade-159-api-requests` 。 + +1. 确认现有爬取计划 +2. 从「系统」→「调度器」执行「Default Crawler」 +3. 等待爬取完成 +4. 确认搜索结果 + +.. warning:: + + 由于重新索引会以新的映射重建索引，在没有 k-NN 插件的 OpenSearch 中会失败。 + 请确认步骤 4 中的注意事项。 + +从 15.8 升级到 15.10 +=================== + +若从 15.8 升级，以下为不向后兼容的变更。若从 15.7 及更早版本升级，这些变更同样适用：请阅读从 +「内嵌 OpenSearch 的移除」到「将新字段和假名规范化应用到现有文档索引」的所有小节（内嵌 +OpenSearch、脚本引擎、S3 与 SSO 插件、Index Exporter 作业等），以及本页末尾的 +「15.10 特有的迁移工作」。 + +内嵌 OpenSearch 的移除 +---------------------- + +15.8 之前，未设置 ``SEARCH_ENGINE_HTTP_URL`` 而启动 ``bin/fess`` 时，|Fess| 会在自身的 JVM 内 +启动 OpenSearch 节点。15.10 移除了该配置，搜索引擎始终是独立的服务器。 + +``bin/fess.in.sh`` 现在默认设置 ``SEARCH_ENGINE_HTTP_URL=http://localhost:9200``\ 。 +如果没有可连接的 OpenSearch，|Fess| 将无法启动。可以使用 ``bin/fess-setup install opensearch`` +进行安装（仅限 Linux 和 Windows。OpenSearch 没有官方的 macOS 发行版，请使用 Homebrew 或 +Docker）。 + +|Fess| 还需要 ``FESS_DICTIONARY_PATH`` 与该 OpenSearch 的 ``opensearch.yml`` 中的 ``configsync.config_path`` 一致；否则 |Fess| 无法创建索引。当 |Fess| 目录下的 ``opensearch/`` 中恰好只有一个通过 ``bin/fess-setup install opensearch`` 安装的 OpenSearch 时，15.10 的 ``bin/fess.in.sh``\ （Windows 上为 ``bin\fess.in.bat``\ ）会自动设置该变量。使用其他 OpenSearch 时，请按照 :doc:`install-linux` 或 :doc:`install-windows` 的说明进行设置。 + +以下内容也一并移除： + +- ``es/`` 目录（``es/modules``、``es/plugins``、``es/data``） +- ``-Dfess.es.dir`` 和 ``SEARCH_ENGINE_HOME`` +- ``bin/module.xml`` 和 ``bin/plugin.xml`` +- 对旧 ``elasticsearch.*`` 配置键的回退处理 + +此外，连接早于 OpenSearch 3 的版本时，15.8 只记录错误日志并继续运行，而 15.10 将启动失败。 +这些版本未实现遍历全部文档的处理所依赖的 ``_shard_doc`` 排序，通过 HTTP 时此类请求不会失败， +而是不返回响应。 + +.. warning:: + + 使用内嵌 OpenSearch 运行时的索引数据无法继承。请新建外部 OpenSearch 服务器，通过管理界面的 + 「备份」迁移配置后重新爬取。备份包含爬取配置、用户和日志，**不包含已爬取的文档**。 + +.. note:: + + 将 15.8 的备份恢复到新的 15.10 服务器时，请注意以下两点。 + + - 作业仅在比服务器上的作业更新时才会恢复。因此，在 15.8 中从未编辑过的内置作业会保留 15.10 的 JavaScript 版本。 + 在 15.8 中编辑或创建的作业会以保存时的脚本引擎恢复（内置作业为 ``groovy``），没有 ``fess-script-groovy`` + 插件时会因 ``groovy is not found`` 而失败。请安装该插件，或将这些作业切换为 JavaScript； + 两种做法都在 :ref:`upgrade-159-script-engine` 中说明。 + - Web 认证、爬取配置和数据存储配置的参数中保存的密码和密钥，是用 ``app.cipher.key`` 加密的。 + 请将旧环境的值设置到新服务器的 ``fess_config.properties`` 中（参阅 + :ref:`upgrade-159-carried-over-config` ）。否则无法解密。 + +Playwright 爬虫移至插件 +----------------------- + +Playwright 爬虫及其使用的 Node.js 可执行文件不再包含在发行包中。 +在 ``fess-15.8.0.zip``\ （457.1 MiB）中，收纳 Node.js 可执行文件的 Playwright 驱动包占用了 204.3 MiB。 + +如果爬取配置的设置参数中指定了 Playwright 客户端（例如 +``client.crawlerClients=playwright:http://.*``\ ），请同时安装插件与 Node.js。 +插件也可以从管理界面的「系统 > 插件」页面安装。 ``bin/fess.in.sh`` 会检测 Node.js +的安装位置并设置 ``PLAYWRIGHT_NODEJS_PATH``\ 。 + +:: + + $ bin/fess-setup install plugin fess-crawler-playwright + $ bin/fess-setup install nodejs + +没有插件时，此类配置仍会被爬取，但使用的是普通 HTTP 客户端，因此只有 JavaScript 才会生成的 +文本不会被索引。爬取作业仍会正常结束，也不会记录失败 URL。每次爬取时， ``fess-crawler.log`` +会按每个爬取配置记录一条警告，其中给出插件名称和上面的两条命令。 + +使用 Playwright 为 HTML 页面生成缩略图的 ``fess-thumbnail-playwright`` 插件同样依赖 Node.js 运行。 +如果使用该插件，请同样通过 ``bin/fess-setup install nodejs`` 安装 Node.js，同一份安装由两个插件共用。 + +如果既不使用 Playwright 爬虫，也不使用 ``fess-thumbnail-playwright`` 插件，则无需处理。 + +Google Cloud Storage 移至插件 +----------------------------- + +Google Cloud Storage 的 SDK 不再包含在发行包中， ``gcs://`` 爬取与 ``gcs`` 存储类型改由 +``fess-storage-gcs`` 插件提供。请从管理界面的「系统 > 插件」页面安装，或执行以下命令。 + +:: + + $ bin/fess-setup install plugin fess-storage-gcs + +``crawler.file.protocols`` 的随附取值中也去掉了 ``gcs``\ ，现为 +``file,smb,smb1,ftp``\ 。安装插件后会重新加入。在此之前，路径以 ``gcs:`` 开头的文件 +爬取配置只会记录一条警告，且什么都取不到。升级后的现有安装会保留自己的 +``crawler.file.protocols``\ ，因此路径仍被接受，但没有可处理它的爬虫客户端；新安装中 +``gcs:`` 不是已配置的协议，管理界面会拒绝保存该路径，而先前保存的路径会被当作本地文件 +路径处理。存储页面同样会记录警告，并把失败作为错误显示出来，文字中包含需要安装的插件 +名称；此前它只显示一个空的文件列表。 + +如果不使用 Google Cloud Storage，则无需处理。Amazon S3 以及 MinIO 等兼容 S3 的存储也以 +同样的方式移至插件，请参阅下一节。 + +Amazon S3 移至插件 +------------------ + +AWS SDK 不再包含在发行包中， ``s3://`` 爬取与 ``s3``\ 、 ``s3_compat`` 存储类型改由 +``fess-storage-s3`` 插件提供。请从管理界面的「系统 > 插件」页面安装，或执行以下命令。 + +:: + + $ bin/fess-setup install plugin fess-storage-s3 + +``crawler.file.protocols`` 的随附取值中也去掉了 ``s3``\ ，现为 ``file,smb,smb1,ftp``\ 。 +安装插件后会重新加入。 ``storage.type`` 的默认值仍为 ``auto``\ ，未设置端点时会解析为 +S3，因此即使从未显式指定 ``s3``\ ，在安装插件之前管理界面的存储功能也无法使用。 +``storage.*`` 的取值位于 ``WEB-INF/conf/system.properties``\ ，因此会保留下来，现有的 +``crawler.file.protocols`` 也不会被升级覆盖。 + +如果不使用 Amazon S3 或 MinIO 等兼容 S3 的存储，则无需处理。 + +SSO 认证移至插件 +---------------- + +四种 SSO 认证均不再包含在发行包中，每个 ``sso.type`` 取值改由各自的插件提供，插件中同时 +附带所需的认证库： ``saml`` 对应 ``fess-sso-saml``\ ， ``spnego`` 对应 +``fess-sso-spnego``\ ， ``entraid``\ （旧名 ``aad`` 亦同）对应 ``fess-sso-entraid``\ ， +``oic`` 对应 ``fess-sso-oidc``\ 。请注意最后一组：插件名为 ``fess-sso-oidc``\ ，而 +``sso.type`` 的取值仍为 ``oic``\ ，两者不一致的地方仅此一处。请从管理界面的 +「系统 > 插件」页面安装所需的插件，或执行以下命令。 + +:: + + $ bin/fess-setup install plugin fess-sso-saml + +``sso.type`` 与 ``saml.*``\ 、 ``spnego.*``\ 、 ``entraid.*``\ 、 ``aad.*``\ 、 ``oic.*`` +各项位于 ``WEB-INF/conf/system.properties``\ ，因此设置值会保留下来。管理页面 +「系统」→「常规」也仍将四种类型全部列为选项，设置项也保留。这是因为插件无法提供 JSP， +因此该页面不会提示插件尚未安装。 + +安装插件之前，对 ``/sso/`` 的请求会被重定向回登录页面，页面上会提示 SSO 登录失败，无法 +通过 SSO 登录。15.10 会将包含所查找的组件名与提供方插件名的警告记录到 ``fess.log``\ ； +15.8 之前在任何日志级别下都不会输出任何内容。 + +``oic`` 插件的校验比 15.8 的认证功能更严格。 ``oic.token.server.url`` 必须为 HTTPS（只有 +``localhost``、``127.x.x.x`` 和 ``::1`` 可以使用 ``http``），并会校验 ID Token 的 ``aud`` 与 +``exp`` 声明；设置了新增的 ``oic.issuer`` 键时，还会校验 ``iss``。详情请参阅 +:doc:`../config/sso-oidc`。 + +在 15.8 中，``oic.token.server.url`` 可以指定任意主机的 ``http`` URL。在 15.10 中，指向Docker Compose服务名（如 ``http://keycloak:8080/...``）或内部主机名的 ``http`` 会被拒绝，即使它指向同一台机器。被拒绝时登录失败，``fess.log`` 中会输出以 ``Failed to process the OpenID Connect callback: oic.token.server.url must be https`` 开头的警告。请在更新前将令牌端点改为HTTPS的URL。 + +此外，建议将 ``oic.issuer`` 设置为OP的Discovery文档中 ``issuer`` 的值。未设置时不会校验 ``iss``，并在启动后的首次登录时输出警告。设置 ``oic.issuer`` 不会放宽HTTPS规则。 + +如果不使用 SSO，即 ``sso.type`` 为 ``none`` 或未设置，则无需处理。 + +.. _upgrade-159-script-engine: + +内置脚本引擎由 Groovy 改为 JavaScript +------------------------------------- + +15.8 之前内置的脚本引擎为 Groovy， ``job.default.script`` 的默认值也是 ``groovy`` 。15.10 中内置 +引擎为 JavaScript，默认值为 ``javascript`` 。Groovy 已不再内置，改由 ``fess-script-groovy`` +插件提供；要让 ``scriptType`` 的 ``groovy`` 生效，必须安装该插件。 + +升级不会更改各设置中保存的脚本引擎，而 15.10 之前保存且未记录引擎的设置会被视为 ``groovy`` 。 +没有该插件时，以下内容将无法正常工作： + +- 以 ``groovy`` 保存的计划任务。 + **15.8 自行注册的任务也属于这种情况。**\ Default Crawler、Suggest Indexer、Config Reloader、 + Log Aggregator、Doc Purger 等随附任务都以 ``groovy`` 保存，而 15.10 启动时只会添加尚不存在的 + 随附任务，因此不会改动它们。这些任务每次按计划触发都会失败，Default Crawler 也不再进行爬取。 + 大多数随附任务的「日志记录」处于关闭状态，因此失败不会出现在作业日志中，只会在 ``fess.log`` + 中留下 ``Failed to execute job`` 警告。 +- 在「配置参数」中编写了字段脚本（ ``field.script.<字段名>`` ）的 Web 爬取配置和文件爬取配置。 + 该配置的所有文档都会因 ``ScriptEngineException`` 失败并记录为失败 URL，而爬取作业本身仍会 + 正常结束。 +- 设置了「脚本」的数据存储配置。除参数名本身以外的值无法求值。请参阅 + :doc:`../config/datastore/ds-overview` 。 +- 文档提升规则。该规则不会提升任何文档。 +- 「替换」以 ``groovy:`` 开头的路径映射。该映射不会被应用，URL 保持不变。 + +首次启动后，请在 ``fess.log`` 中查找以 +``Settings use the script engine groovy, which is not registered`` 开头的警告。\ |Fess| 会在 +启动时检查一次上述设置，并按类型输出使用了没有任何插件提供的引擎的设置数量。如果从 15.8 沿用的 +``fess_config.properties`` 中仍为 ``job.default.script=groovy`` ，警告中也会列出该项，此时升级后 +新建的任务同样会使用 Groovy（参阅 :ref:`upgrade-159-carried-over-config` ）。请采用以下任一方式 +处理： + +- 安装该插件并重启 |Fess| 。已保存的 Groovy 脚本可原样运行，警告也不再输出。也可以在管理页面 + 「系统」→「插件」中安装该插件。 + + :: + + $ bin/fess-setup install plugin fess-script-groovy + +- 将各设置改用 JavaScript。先改写只有 Groovy 才接受的语法，再选择 JavaScript： + + - 计划任务：在管理页面「系统」→「调度器」中将「执行方法」改为 ``javascript`` 。随附任务的 + 脚本除以下两项外，原样即是有效的 JavaScript：Thumbnail Purger 使用了 Groovy 的 ``long`` + 字面量 ``1000L`` ，在 JavaScript 中会成为语法错误（请写成 ``1000`` ）；Index Exporter + 需要进行 :ref:`upgrade-159-index-exporter` 中所述的修改。JavaScript 的数组字面量会自动转换为 + Java 的 ``String[]`` ，因此不再需要 Groovy 写法中的 ``as String[]`` 。 + + :: + + return container.getComponent("crawlJob").logLevel("info").webConfigIds(["1", "2"]).fileConfigIds(["1"]).dataConfigIds([]).execute(executor); + + - Web 爬取配置和文件爬取配置：在「配置参数」中添加 ``config.script.type=javascript`` 。 + - 数据存储配置：在「参数」中添加 ``script_type=javascript`` 。 + - 文档提升规则：将「脚本类型」改为 ``javascript`` 。 + - 路径映射：将「替换」的开头由 ``groovy:`` 改为 ``javascript:`` 。 + - ``job.default.script`` ：在从 15.8 沿用的 ``fess_config.properties`` 中将其设置为 + ``javascript`` 。 + +``crawler.default.script`` 已删除 +--------------------------------- + +``fess_config.properties`` 中已不存在 ``crawler.default.script`` 。请从配置中删除该项； +以该名称保留的值不会生效。 + +爬取协议 ``storage`` 已删除 +--------------------------- + +``crawler.file.protocols`` 中不再接受 ``storage`` ，随附的值为 ``file,smb,smb1,ftp`` 。 +请改用 ``s3`` ，并将路径以 ``storage:`` 开头的文件爬取配置改为 ``s3:`` 路径。 ``s3`` 需要 +``fess-storage-s3`` 插件。 + +.. _upgrade-159-index-exporter: + +Index Exporter 作业引用了已删除的包 +----------------------------------- + +15.10 不再包含 ``org.opensearch`` 的类，作业脚本使用的查询构建器已移至 +``org.codelibs.fesen.opensearch`` 下。15.8 为 Index Exporter 作业保存的脚本引用了 +``org.opensearch.index.query.QueryBuilders`` ，而升级不会替换该脚本，因此即使安装了 +``fess-script-groovy`` ，该作业仍会失败。该作业随附时处于禁用状态且没有计划，因此只有在运行它时 +才会受到影响。请在管理页面「系统」→「调度器」中打开该作业，将脚本中的包改为 15.10 所用的包： + +:: + + return new org.codelibs.fess.job.IndexExportJob().query(org.codelibs.fesen.opensearch.index.query.QueryBuilders.matchAllQuery()).execute() + +如果自行编写的脚本中引用了 ``org.opensearch.index.query`` ，也请以同样方式修改。更多查询示例请 +参阅 :doc:`../config/admin-index-export` 。 + +.. _upgrade-159-carried-over-config: + +从 15.8 沿用的配置文件 +---------------------- + +步骤 3 的 ZIP 版步骤会从旧安装中复制 ``fess_config.properties`` 与 ``bin/fess.in.sh`` ；RPM 版 +升级则会保留修改过的 ``/etc/fess/fess_config.properties`` （15.10 的文件以 +``fess_config.properties.rpmnew`` 的形式并存）。DEB 版升级在询问时保留自己的版本，也是同样的 +结果（15.10 的文件以 ``fess_config.properties.dpkg-dist`` 的形式并存）。无论哪种情况，15.10 都会以 +15.8 的值运行，15.10 中随附值已变更的键也不例外。请至少确认以下各键。 + +.. list-table:: + :header-rows: 1 + + * - 键 + - 15.8.0 + - 15.10 + - 保留 15.8 的值时的影响 + * - ``job.default.script`` + - ``groovy`` + - ``javascript`` + - 在管理页面「系统」→「调度器」中新建的作业默认使用 ``groovy`` ，没有 + ``fess-script-groovy`` 插件时会失败。 + * - ``job.template.script`` + - 含 ``as String[]`` 的 Groovy 写法 + - JavaScript 写法 + - 从爬取配置创建的作业会得到 Groovy 脚本。 + * - ``crawler.file.protocols`` + - ``file,smb,smb1,ftp,storage,s3,gcs`` + - ``file,smb,smb1,ftp`` + - 以 ``s3:`` 或 ``gcs:`` 开头的路径即使没有对应插件也会被接受，爬取时记录警告并跳过。 + ``storage`` 已不再受支持。 + * - ``search_engine.http.url`` + - ``http://localhost:9201`` + - ``http://localhost:9200`` + - 在未设置 ``SEARCH_ENGINE_HTTP_URL`` 时使用。从 15.8 复制的 ``bin/fess.in.sh`` 中未设置 + 该变量时即属于这种情况，此时 |Fess| 会在 9201 端口查找 OpenSearch，即 15.10 已移除的内嵌 + OpenSearch 所用的端口。 + * - ``jvm.crawler.options``\ 、\ ``jvm.thumbnail.options`` + - ``-Djcifs.smb.client.*``\ 、\ ``-Djcifs.smb1.smb.client.*`` + - ``-Djcifs.client.*`` + - SMB 超时保持为 jcifs 的默认值。请参阅 :ref:`upgrade-159-jcifs` 。 + * - ``response.headers`` + - 包含 ``text/html=Content-Security-Policy: reflected-xss block`` 这一行 + - 已删除该行 + - 登录页面、管理界面等由 |Fess| 自身渲染的页面，其响应会带有浏览器无法识别的 + ``Content-Security-Policy: reflected-xss block`` 头，浏览器控制台会输出 + ``Unrecognized Content-Security-Policy directive 'reflected-xss'`` 。该头不起任何限制作用。 + 请按下文说明删除该行。 + * - ``app.encrypt.property.pattern`` + - ``.*password|.*key|.*token|.*secret`` + - ``.*password|.*passphrase|.*key|.*token|.*secret`` + - 名称以 ``passphrase`` 结尾的参数（例如数据存储配置的 ``ssh.passphrase`` ）会以明文保存。 + 之前已保存的值会一直是明文，直到用 15.10 的模式重新保存该设置。 + * - ``index.backup.log.targets`` + - ``click_log.ndjson,favorite_log.ndjson,search_log.ndjson,user_info.ndjson`` + - ``chat_log.ndjson,click_log.ndjson,favorite_log.ndjson,search_log.ndjson,user_info.ndjson`` + - 「系统信息」→「备份」页面不会显示 ``chat_log.ndjson`` 。 + * - ``index.export.exclude.fields`` + - ``cache`` + - ``cache,tag`` + - 保存用户标签的 ``tag`` 字段，不再从 Index Export 作业写出的文件中排除。 + * - ``crawler.default.script``\ 、\ ``theme.allowed.archive.extensions``\ 、 + ``theme.assets.cache.max.age``\ 、\ ``theme.assets.precompressed``\ 、 + ``rag.chat.message.max.length``\ 、\ ``supported.uploaded.js.extentions``\ 、 + ``supported.uploaded.css.extentions``\ 、\ ``supported.uploaded.media.extentions``\ 、 + ``supported.uploaded.files``\ 、\ ``online.help.name.design`` + - 存在 + - 已删除 + - 不起作用，请删除。 + +15.0 至 15.8 随附的 ``response.headers`` 中包含 +``text/html=Content-Security-Policy: reflected-xss block`` 这一行。 ``reflected-xss`` 是 +Content-Security-Policy 早期草案中的指令，现在的浏览器已不再识别，因此该头不起任何限制作用，只会在 +控制台中产生错误。15.10 的随附值已删除这一行（ ``X-XSS-Protection`` 与 ``X-Frame-Options`` 两行保持不变）， +但从 15.8 沿用的 ``response.headers`` 仍会保留它。请仅从 ``fess_config.properties`` 的 +``response.headers`` 中删除下面这一行。每行末尾的 ``\n\`` 表示值在下一行继续，因此删除整行后，其余各行 +可以原样使用:: + + text/html=Content-Security-Policy: reflected-xss block\n\ + +如果是通过 ``-Dfess.config.response.headers`` 指定 ``response.headers`` ，请从该值中删除相同的项。 + +从 15.8 复制的 ``bin/fess.in.sh`` 还缺少 15.10 文件中的以下两点。15.10 会将 +``SEARCH_ENGINE_HTTP_URL`` 设置为 ``http://localhost:9200`` ，而 15.8 的文件除非自行设置，否则 +保持未设置状态。此外，它不会查找通过 ``bin/fess-setup install nodejs`` 安装的 Node.js，因此除非 +自行设置 ``PLAYWRIGHT_NODEJS_PATH`` ，否则 Playwright 插件找不到 Node.js。 + +请不要整体复制这两个文件，而是以 15.10 随附的文件为基础，重新应用自己修改过的值。可以用 +``diff`` 查看这些值:: + + $ diff /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.10.0/app/WEB-INF/classes/fess_config.properties + $ diff /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.10.0/bin/fess.in.sh + +RPM 版请以同样方式比较 ``/etc/fess/fess_config.properties`` 与 +``/etc/fess/fess_config.properties.rpmnew`` ，DEB 版升级则比较 ``/etc/fess/fess_config.properties`` +与 ``/etc/fess/fess_config.properties.dpkg-dist`` 。DEB 版升级时，从未编辑过的 +``fess_config.properties`` 会被替换为 15.10 的文件（参阅步骤 3），因此从 15.10 的值开始。 + +``app.cipher.key`` 是即使 15.10 没有变更也必须沿用的值。它是对 Web 认证、爬取配置和数据存储配置 +的参数中保存的密码和密钥进行加密的密钥。如果新环境使用的密钥与保存这些内容时的密钥不同 +（因为使用了随附的 ``fess_config.properties`` ，或将备份恢复到了新服务器），就无法解密： +``fess-crawler.log`` 中会记录 ``CipherFailureException`` ，包含此类配置的爬取将无法索引任何内容。 + +.. note:: + + |Fess| 15.10 同样使用 ``app.cipher.key`` 加密保存 Web 认证和文件认证的 ``password`` ，因此备份中的 + ``fess_basic_config.bulk`` 和 ``fess_config.bulk`` 包含加密后的值。恢复到其他安装环境时请沿用相同的 ``app.cipher.key`` ； + 密钥不同时，使用这些认证信息的爬取会因错误而失败。15.10 之前创建的备份以明文包含这些值，可以继续正常使用 + （详见 :doc:`../admin/backup-guide` ）。 + +.. _upgrade-159-jcifs: + +SMB 超时改用 jcifs 3 的属性名 +----------------------------- + +|Fess| 爬取 SMB 文件服务器时使用的 jcifs 在版本 3 中更改了属性名： ``jcifs.smb.client.*`` 改为 +``jcifs.client.*`` ，SMB1 专用的 ``jcifs.smb1.smb.client.*`` 也合并到了相同的属性中。15.8 之前， +``jvm.crawler.options`` 与 ``jvm.thumbnail.options`` 仍传递旧名称，而 jcifs 不读取这些名称，因此 +SMB 爬取一直以 jcifs 的默认值运行。15.10 传递新名称： + +:: + + -Djcifs.client.responseTimeout=30000 + -Djcifs.client.soTimeout=35000 + -Djcifs.client.connTimeout=60000 + -Djcifs.client.sessionTimeout=60000 + +因此，连接超时与会话超时首次生效，从 jcifs 默认的 35 秒延长到 60 秒：对于没有响应的 SMB +服务器，爬取现在最多会等待 60 秒。响应超时与套接字超时与 jcifs 的默认值相同，因此不会变化。 + +如果修改过这些超时，请在两个选项中改用新名称。使用旧名称时，它们在 15.8 中同样不起作用。从 15.8 +沿用的 ``fess_config.properties`` 会保留旧名称，也就仍使用 jcifs 的默认值。 + +删除了四个不起作用的属性 +------------------------ + +以下键已从 ``fess_config.properties`` 中删除。\ |Fess| 从未从该文件读取它们，因此以这些名称保留的 +值与以前一样不起作用。 + +- ``theme.allowed.archive.extensions`` +- ``theme.assets.cache.max.age`` +- ``theme.assets.precompressed`` +- ``rag.chat.message.max.length`` + +``rag.chat.message.max.length`` 设定的上限仍然有效，但会作为系统属性读取：请按照 +:doc:`../config/rag-chat` 中的说明，在 ``app/WEB-INF/conf/system.properties`` 中或通过 +``-Dfess.system.rag.chat.message.max.length`` 进行设置。 + +.. _upgrade-159-static-theme: + +搜索界面现已改为静态主题 +------------------------ + +除非选择了其他主题，搜索界面由 |Fess| 内置的静态主题 ``bootstrap`` 提供。这适用于 ``/``、 +``/search``、``/advance``、``/help``、``/profile``、``/cache``、``/chat`` 以及错误页面。在 15.8 +及之前的版本中，除非设置了默认主题，这些页面都是 JSP。 + +升级时同样会进行切换。从未设置过默认主题的 15.8 环境， ``system.properties`` 中没有 +``theme.default`` ，因此升级后会显示静态主题；不会向配置写入任何内容，也不会输出任何日志。 +没有可以恢复 JSP 搜索界面的设置。如果在 15.8 中设置了默认主题，该设置会被保留；请安装该主题 +面向 15.10 的构建（ ``bin/fess-setup install theme `` ），因为若默认主题指定的是未安装的 +主题，将回退到 ``bootstrap`` ，并在 ``fess.log`` 中输出警告。 + +如果通过管理界面的「页面设计」或 JAR 主题插件修改过搜索界面的 JSP、CSS 或图片，这些修改将 +不再显示。请在静态主题中进行修改：按照 :ref:`theme-customize-bundled` 的说明复制内置主题并 +修改副本，或者从管理界面的「系统」→「主题」或使用 ``bin/fess-setup install theme `` +安装已发布的主题。按虚拟主机区分的外观现在是以虚拟主机命名的静态主题；参阅 +:doc:`../config/security-virtual-host` 。 + +以下两项也已不再提供。 + +- 按虚拟主机区分的登录界面。在 15.8 之前，保存「系统」→「常规」时，包括登录界面在内的 JSP + 会被复制到 ``WEB-INF/view/<虚拟主机名>/`` ，可以按虚拟主机分别编辑。15.10 不再创建这些副本。 + 登录界面（ ``/login/`` ）仍然是 JSP，但所有虚拟主机都显示共用的 ``WEB-INF/view/admin/login/`` + 中的界面。以前复制的 JSP 不会被使用。 +- JAR 主题插件（ ``fess-theme-*`` ）。即使安装，它也只会作为种类为 ``jar`` 的通用 JAR 放置， + 界面不会改变。遗留的 JAR 可以在「系统」→「插件」页面或使用 + ``bin/fess-setup remove plugin `` 删除（参见 :doc:`../dev/theme-development` ）。 + +如果在 15.8 中曾在 JSP 的搜索结果中显示自定义字段，除了 ``query.additional.response.fields`` +之外，还请在 ``query.additional.api.response.fields`` 中添加相同的字段。静态主题从 +``/api/v2/search`` 获取搜索结果。 ``query.additional.response.fields`` 只是增加从搜索引擎 +获取的字段，而该 API 在响应中只包含 ``query.additional.api.response.fields`` 中列出的字段 +（参见 :doc:`../config/search-advanced` ）。另外，请修改主题以显示该字段。 + +客户端看到的变化 +~~~~~~~~~~~~~~~~ + +错误现在会在所请求的 URL 上直接渲染，并返回真实的 HTTP 状态码。浏览器（ ``Accept`` 头中包含 +``text/html`` 的请求）会收到主题的错误页面；其他客户端会收到一行 ``text/plain`` 正文（例如 +``404`` 时为 ``Not Found.`` ）。在 15.8 及之前的版本中，大多数错误会以 ``302`` 重定向到 +``/error/...`` 页面，而该页面本身返回 ``200`` 。请检查监控、健康检查，以及跟随 ``Location`` +头或期望 ``/error/`` URL 的客户端。 + +.. list-table:: + :header-rows: 1 + + * - 请求 + - 15.8 及之前 + - 15.10 + * - 缺少参数，或针对不存在的文档的 ``/go/`` + - ``200`` ，或 ``302`` 到 ``/error/`` + - ``400`` 或 ``404`` + * - 缺少参数、针对未知文档或没有缩略图的 ``/thumbnail/`` + - ``200`` 或 ``302`` + - ``400`` 或 ``404`` + * - 所配置的 SSO 类型不处理时的 ``/sso/metadata`` 和 ``/sso/logout`` + - ``302`` 到 ``/error/badrequest/`` + - ``400`` + * - ``/api/v1/*``、``/json`` 以及任何未知 URL + - ``302`` 到 ``/error/notfound/`` + - ``404`` + * - 未捕获的异常（包括管理 API 中的异常） + - ``302`` 到 ``/error/systemerror/`` + - ``500`` ，正文为 ``System Error.`` （不是 JSON） + * - ``/error/notfound/``、``/error/badrequest/``、``/error/systemerror/`` 本身 + - ``200`` + - ``404``、``400``、``500`` + +在 ``login.required=true`` 时，搜索页面不再重定向匿名用户。它们会返回 ``200`` 和主题，由主题提示 +用户登录，而其背后的数据则会被拒绝：除 ``/health``、``/auth/*`` 和 ``/ui/config`` 以外的所有 +``/api/v2/`` 端点（包括 ``/api/v2/search`` ）在用户登录之前都会返回 ``401`` 。 ``/go/``、 +``/thumbnail/`` 和 ``/osdd`` 仍会重定向到登录页面。期望匿名请求 ``/`` 时发生重定向的检查，需要改为 +检查 ``/api/v2/search`` 是否返回 ``401`` 。 + +搜索界面也通过 ``/api/v2/search`` 进行搜索，因此搜索日志是在调用该 API 时记录的，而不是在请求 +``/search`` 时记录。不执行 JavaScript 的客户端会收到没有搜索结果的页面。 + +搜索界面的 HTML 带有 ``X-Frame-Options: DENY``，以及包含 ``frame-ancestors 'none'`` 的 ``Content-Security-Policy`` ，因此其他页面无法将它放入框架中显示。15.8 的 JSP 搜索界面按 ``response.headers`` 的默认值发送 ``X-Frame-Options: SAMEORIGIN`` ，可以显示在同源页面的 ``iframe`` 中。如果已将搜索界面嵌入同源的 ``iframe`` ，请在 ``fess_config.properties`` 中把 ``theme.index.frame.ancestors`` （默认值 ``'none'`` ）设置为 ``'self'`` 。如需从其他源嵌入，请指定该源（参见 :doc:`../dev/theme-development` ）。 + +删除了管理界面的「页面设计」 +---------------------------- + +删除了管理界面中的 [系统 > 页面设计]。无法再从管理界面编辑搜索界面的 JSP、CSS 和图片。 +如需更改搜索界面的外观，请使用静态主题（参见 :ref:`theme-customize-bundled`）。 + +以下键也已从 ``fess_config.properties`` 中删除。以这些名称保留的值不会被使用。 + +- ``supported.uploaded.js.extentions`` +- ``supported.uploaded.css.extentions`` +- ``supported.uploaded.media.extentions`` +- ``supported.uploaded.files`` +- ``online.help.name.design`` + +``admin-design`` 和 ``admin-design-view`` 角色不再授予任何权限。仅拥有这些角色的用户登录后会进入 +搜索界面，而不是管理界面。 + +``api.access.token.required`` 已删除 +------------------------------------ + +``fess_config.properties`` 中已不存在 ``api.access.token.required`` 。以该名称保留的值不会生效， +包括从 15.8 沿用的 ``fess_config.properties`` 中的值。设置为 ``true`` 时，它会拒绝所有来自未登录用户的 +API 请求。由于搜索界面现在通过 ``/api/v2/search`` 进行搜索，该设置还会使匿名用户看到没有结果的搜索界面。 + +曾将其设置为 ``true`` 的环境，现在会像对待搜索界面一样，以访客角色响应匿名用户的 API 请求。 +如需禁止匿名用户搜索，请设置 ``login.required=true`` 。访问令牌的行为不变：带有已注册访问令牌的请求 +会获得该令牌的权限，带有未注册或已过期令牌的请求会被拒绝。 + +.. _upgrade-159-api-requests: + +API 现在会拒绝的请求 +-------------------- + +15.10 会拒绝以下 15.8 曾接受的请求。请检查为 15.8 编写的客户端和脚本是否发送了这些请求。管理 API 以 HTTP ``400`` 拒绝请求，响应正文中的 ``status`` 为 ``1`` 。 + +.. list-table:: + :header-rows: 1 + + * - 请求 + - 15.8 及之前 + - 15.10 + * - 向 ``/api/v2/search`` 同时指定 ``facet.field`` 或 ``facet.query`` 与小于等于 ``0`` 的 ``facet.size`` ，或者不是整数的 ``facet.size`` 、 ``facet.minDocCount`` + - ``200`` 。但结果为空： ``record_count`` 为 ``0`` ， ``partial`` 为 ``true`` + - ``400`` （ ``invalid_request`` ）。 ``facet.size`` 必须大于等于 ``1`` + * - 指定 ``track_total_hits=false`` 。如果把 ``query.track.total.hits`` 设置为 ``false`` ，所有搜索都会受到影响 + - ``200`` 。但没有搜索结果 + - 搜索会被拒绝（ ``/api/v2/search`` 返回 ``400`` 和 ``invalid_request`` ）。 ``true`` 和正整数的行为不变 + * - 通过管理 API 向 ``mapping`` 或 ``kuromoji`` 字典添加或更新与已有条目重复的条目 + - 会被保存。之后加载字典时失败，可能导致无法搜索 + - ``400`` + * - 通过管理 API 向 ``kuromoji`` 字典添加或更新 ``token`` 含有空格的条目，或 ``segmentation`` 与 ``reading`` 按空格分隔的词数不同的条目 + - 会被保存。与上面相同，加载字典时失败 + - ``400`` + * - 没有删除任何内容的 ``DELETE /api/admin/searchlist/doc/{doc_id}`` （不存在的 ``doc_id`` ，或像文档列表所返回的 ``_id`` 那样不是 ``doc_id`` 的值） + - ``200`` （ ``status`` 为 ``0`` ）。文档不会被删除 + - ``400`` + * - 在管理 API 的用户的 ``roles`` 、 ``groups`` 中指定角色名、组名 + - 会被保存，但所指定的名称不会作为角色起作用。对于某些名称，读取该用户会失败 + - ``400`` 。请指定角色、组的 ID（ ``GET /api/admin/role/settings`` 、 ``GET /api/admin/group/settings`` 所返回的 ``id`` ） + * - 为管理 API 的用户设置违反密码策略（例如 ``password.min.length`` ，默认值 ``8`` ）的密码；创建时省略密码；发送与 ``password`` 不一致的 ``confirm_password`` + - 会被保存，该用户可以用该密码登录 + - ``400`` + +``/api/v2/documents/all`` 的每一行不再带有 ``score`` 。15.8 及之前，每个文档都带有搜索得分；15.10 使用 point in time 和 ``search_after`` 获取全部结果，因此不会产生得分。旧 API 插件的 ``/json?type=scroll`` 和 ``/api/v1/documents/all`` 也是如此。读取 ``score`` 的脚本需要能够处理该值不存在的情况。 + +管理 API 的文件上传（6 种字典、 ``badword`` 、 ``elevateword`` 、 ``storage`` ）通过 ``POST`` 接收。15.8 的文档曾介绍使用 ``PUT`` ，但 ``multipart/form-data`` 的 ``PUT`` 不会传送文件，因此在 15.8 和 15.10 中都会因“需要文件”的验证错误而失败。 ``PUT`` 端点仍然保留，但上传请使用 ``POST`` 。 + +``search_engine.type`` 的 ``cloud`` 已弃用 +------------------------------------------ + +15.10 为 ``search_engine.type`` 新增了 ``vanilla`` 值，用于不含 CodeLibs 插件的原生 OpenSearch（请参阅 :doc:`../config/search-engine-type` ）。 ``cloud`` 成为 ``vanilla`` 的已弃用别名，仍可继续使用，但启动时会在日志中输出警告。在 15.10 上运行后，请改为 ``vanilla`` 。 ``aws`` 的行为与之前相同。 + +* ``vanilla`` 需要 15.10 及更高版本。\ |Fess| 15.8 及更早版本无法识别该值，因此在仍有可能回退到 15.8 期间，请保持 ``cloud`` 不变。 +* ``aws`` 和 ``cloud`` 的索引定义现在从 ``fess_indices/_vanilla/`` 读取。随附的 ``fess_indices/_aws/`` 和 ``fess_indices/_cloud/`` 已不存在，自行添加的 ``fess_indices/_aws/`` 或 ``fess_indices/_cloud/`` 也不再被读取，请将修改内容移到 ``fess_indices/_vanilla/`` 。已存在的索引不会改变。 +* 15.8 保存在搜索引擎中的建议（suggest）设置会自动迁移，无需任何操作。 + +CSV 数据存储会解析带引号的字段 +------------------------------ + +15.10 的 ``fess-ds-csv`` 插件默认会解释引号。 ``"山田, 太郎"`` 这样的字段会成为一列，而 15.8.0 的 +插件会在逗号处将其拆分。执行 ``bin/fess-setup upgrade plugins`` 之后，请检查读取含有带引号字段的 +CSV 文件的数据存储配置。要保持 15.8 的行为，请在「参数」中添加 ``quote_disabled=true`` ； +请参阅 :doc:`../config/datastore/ds-csv` ，其中也说明了引号不匹配时的行为。 + +.. _upgrade-reindex-new-fields: + +将新字段和假名规范化应用到现有文档索引 +-------------------------------------- + +15.10 在启动时会向配置、日志和用户索引添加新字段。对于文档索引，只会添加保存用户标签的 ``tag`` +字段（``keyword``），映射的其余部分和分析设置不会更改。如果继续使用由 15.8 或更早版本创建的 +文档索引，以下 15.10 的变更不会生效。 + +- **文件的所有者和最后修改者**\ （\ ``owner``\ 、\ ``last_modifier``\ ）: 文件系统、SMB 和 FTP 爬取时新索引的 + 字段。现有文档索引中没有它们的定义，因此会根据首次爬取的值被自动映射为 ``text`` 类型， + ``owner:alice`` 之类的搜索和 ``facet.field=owner`` 无法按预期工作。 +- **ETag**\ （\ ``etag``\ ）: 爬虫保存所爬取页面 ETag 的字段，15.10 会将其作为 ``If-None-Match`` + 回传，以避免重复获取未更改的页面。现有文档索引中同样没有它的定义，因此会被自动映射为 ``text`` + 类型，而不是随附的不索引的 ``keyword`` 。使用该映射时条件请求仍可正常工作。 +- **假名异体和代替长音符号书写的破折号的规范化**\ （例如将 ``サ―バ－`` 视为与 ``サーバー`` 相同的词）: + 规则位于文档索引的分析设置和词典 ``mapping.txt`` 中，因此不会应用到现有索引。 + +要同时应用两者，请在管理界面的「系统信息」→「维护」中启用「更新别名」和「重置字典」，然后运行 +「重新索引」。重新索引会将现有文档复制到新索引，因此无需重新爬取。 + +.. warning:: + + 「重置字典」会用随附的词典文件覆盖 OpenSearch 端的词典。如果在管理界面的「字典」中编辑过同义词等， + 请事先下载，并在重新索引后重新应用：从下载的文件中删除重复或无效的条目（参阅步骤 7）， + 上传后，在「系统信息」→「维护」的“重新加载文档索引”中单击 [重新加载]。在此之前，文档索引的 + 分析器会继续使用随附的词典，恢复的同义词无论等待多久都不会匹配。在索引时生效的词典，还需要 + 重新爬取文档；请参阅 :ref:`dict-apply-changes` 。 + +.. note:: + + 由 15.8 或更早版本索引的文件没有所有者和最后修改者的值。增量爬取不会重新获取未更改的文件， + 因此要添加这些值，请暂时禁用「系统」→「常规」中的「检查上次修改时间」后再进行爬取。 + + +15.10 特有的迁移工作 +=================== + +从 15.7 及更早版本升级到 15.10 时，需要根据所使用的功能执行以下工作。 + +若此前使用过语义搜索 +---------------------------------- + +在 |Fess| 15.7 及更早版本中提供语义搜索功能的 ``fess-webapp-semantic-search`` 插件， +已在 15.10 中并入核心，现已不再需要（已弃用）。需要移除该插件、删除 +``-Dfess.semantic_search.*`` 及 ``-Drank.fusion.searchers=default,semantic``\ ， +并解除旧的 ingest pipeline。详细步骤请参阅 +:ref:`semantic-search-migration`\ （:doc:`../config/search-semantic`）。 + +若此前使用过 AI 搜索模式（RAG Chat） +--------------------------------------------- + +自 15.10 起，AI 搜索模式（RAG Chat）功能已拆分为 ``fess-llm-ollama``\ 、\ ``fess-llm-openai``\ 、 +``fess-llm-gemini`` 等插件。请在管理页面「系统」→「插件」中安装与所使用的 +提供商对应的插件。15.10 还新增了面向 Amazon Bedrock 的 +``fess-llm-bedrock`` 。 + +若此前使用过 SPNEGO（Windows 集成认证） +--------------------------------------- + +自 15.10 起，如果客户端主体的 Kerberos 领域与服务器的领域不同，SPNEGO 登录将被拒绝。 +如果用户来自 AD 域树的子域或建立了信任关系的林，请在管理页面「系统」→「通用」或 +``app/WEB-INF/conf/system.properties`` 的 ``spnego.allowed.realms`` 中以逗号分隔列出 +这些领域。否则，在 15.7 之前能够登录的用户将因 ``Kerberos realm is not allowed`` 而被拒绝。 +详细内容请参阅 :doc:`../config/sso-spnego`\ 。 + +此外，15.10 中 ``spnego.allow.unsecure.basic`` 与 ``spnego.allow.localhost`` 的代码默认值也从 +``true`` 改为了 ``false`` 。在 ``app/WEB-INF/conf/system.properties`` 中不存在这些键的环境中， +升级后会自动采用更严格的行为。特别是当 ``spnego.allow.unsecure.basic=false`` 时，SPNEGO 库仅对 +``HttpServletRequest#isSecure()`` 返回 ``true`` 的请求提供 Basic 认证， +因此在反向代理上终止 TLS 并以 HTTP 转发的环境中，此前回退到 Basic 认证的客户端将无法登录。 +此时请在 ``tomcat_config.properties`` 中设置 ``tomcat.secure=true`` 。 +详细内容请参阅 :doc:`../config/sso-spnego`\ 。 + +.. warning:: + + 代码默认值仅在该键不存在时才生效，而管理页面「系统」→「通用」每次保存都会写入所有 + ``spnego.*`` 键。因此，在 15.7 中曾经在该页面上执行过更新的环境，仍然保存着 + ``spnego.allow.unsecure.basic=true`` 与 ``spnego.allow.localhost=true`` ， + 升级到 15.10 并不会使其变得更严格：宽松的行为会被静默沿用，15.10 只会在 SPNEGO 初始化时 + 向 ``fess.log`` 输出一条警告。请在管理页面「系统」→「通用」或 ``system.properties`` 中 + 有意识地关闭这两项。其中 ``spnego.allow.localhost=true`` 更为危险：SPNEGO 库会把来自同一 + 主机的请求以服务器的 OS 用户身份进行认证，完全不做 Kerberos 验证，在同一主机上部署反向 + 代理时并不安全。 + +.. _upgrade-159-saml: + +若此前使用过 SAML 认证（SSO） +----------------------------- + +自 15.10 起，|Fess| 会将每个 SAML 响应与自身发出的 AuthnRequest 的 ID 进行绑定校验， +因此 IdP 发起（未经请求的 unsolicited）的 SSO 无法再使用。从 IdP 门户（如 Okta 仪表板或 +Microsoft Entra ID 的「我的应用」）中的 |Fess| 磁贴发起的登录没有可匹配的 AuthnRequest， +会被拒绝。在 15.7 之前它之所以可用，是因为 |Fess| 会将无法匹配的响应退回给 IdP， +而 IdP 会立即返回一个经过请求的断言。如果要在 IdP 侧放置磁贴，请将其链接指向 |Fess| 的 +``/sso/`` 端点，使登录由 SP 发起。 + +此外，IdP 通过跨站 POST 返回断言，因此必须将 ``tomcat_config.properties`` 中的 +``tomcat.sameSiteCookies`` 设置为 ``none``\ 。使用附带的默认值 ``lax`` 时，会话 Cookie +不会随该请求发送，SAML 登录无法完成。该文件在 ZIP 软件包中位于 ``lib/classes/``\ ， +在 DEB/RPM 软件包中位于 ``/etc/fess/``\ ，修改后需要重启 |Fess|\ 。浏览器仅对同时带有 +``Secure`` 属性的 Cookie 接受 ``none``\ ，因此 |Fess| 必须通过 HTTPS 提供服务。 +在 15.7 之前，同样的配置错误不会产生明确的错误，而是表现为不断重定向到 IdP 的死循环， +因此即使站点看起来正常，也请确认该设置。15.10 不再循环，而是一次性失败。 +详细内容请参阅 :doc:`../config/sso-saml`\ 。 + +若此前使用过 Microsoft Entra ID（Azure AD） +------------------------------------------- + +自 15.10 起，向授权端点请求的响应模式默认值由 ``form_post`` 变更为 ``query``\ 。15.7 之前回调以 +跨站 POST 返回，而 |Fess| 的默认值 ``tomcat.sameSiteCookies = lax`` 不会随该请求发送会话 +Cookie，因此需要将其改为 ``tomcat.sameSiteCookies = none``\ 。如果仅为此才设置了 ``none``\ ， +可以恢复为默认值。若要保持原有行为，请指定 ``entraid.response.mode=form_post`` 并保留 +``tomcat.sameSiteCookies = none``\ 。浏览器仅对同时带有 ``Secure`` 属性的 Cookie 接受 +``none``\ ，因此这种方式同样要求通过 HTTPS 提供 |Fess| 。 + +自 15.10 起，|Fess| 还会在登录完成后于后台解析用户所属的组和角色，而不再让登录等待 Microsoft +Graph。在解析完成之前——或解析未能完全成功时——用户拥有的仅有其自身的用户级权限，以及在 +``entraid.default.groups`` 和 ``entraid.default.roles`` 中配置的组和角色。若两者都未配置 +（即附带的默认值），这段时间内的搜索将一条文档都搜不到，因为按附带的默认值创建的爬取配置会授予 +``{role}guest``\ ，而已登录用户并不持有该角色。解析进行期间，搜索界面会显示相应提示， +未能完全成功时则显示另一条提示（只有直接所属查询和嵌套组遍历都成功，解析才算成功）。 +每次刷新访问令牌时都会重新解析，之后一旦成功，提示即会消失，因此对于持续时间超过令牌有效期的会话，失败并不一定就是 +最终结果；若要立即重试，请先注销再重新登录。 +详细内容请参阅 :doc:`../config/sso-entraid`\ 。 + +在后台解析还带来一个影响：在解析完成之前，尚无法得知用户已解析的角色。因此， +管理员会被重定向到搜索界面而不是管理仪表板，在此期间打开管理页面也会被送回搜索界面。 +这段时间为最多约 1 秒的调度延迟，加上 Microsoft Graph 调用本身（直接所属查询 1 次， +再为每个直接所属的组各 1 次以遍历嵌套组，依次串行执行，且缓存为空时）， +因此会随用户所属组的数量增加而变长。在此期间访问只会被拒绝，绝不会被放行；而且无需任何配置即可度过这段时间：授权会在同一会话的每个请求上 +重新评估，因此解析完成后重新打开管理界面即可正常访问，无需重新登录。 + +.. warning:: + + 请勿通过把 |Fess| 的管理员角色配置到 ``entraid.default.roles`` 来缩短这段时间。 + 该属性是单个全局值，\ |Fess| 会在登录时将其应用于每一个 Entra ID 用户， + 并在之后每次解析时重新应用，这会让租户中的所有用户永久获得 |Fess| 管理员权限。 + +使用 LDAP / Active Directory 集成的情况 +------------------------------------------ + +从 15.10 开始，组和角色的权限名称取自条目 RDN 的值，而不再是从 DN 文本中截取的片段。CN 中包含 +在 DN 内被转义的字符（通常是逗号）的组，其权限名称将与 15.7 之前不同。 + +.. list-table:: + :header-rows: 1 + + * - 组条目的 DN + - 15.7 之前的权限名称 + - 15.10 的权限名称 + * - ``CN=Sales\, EMEA,CN=Users,...`` + - ``2Sales`` + - ``2Sales, EMEA`` + * - ``CN=Sales\, APAC,CN=Users,...`` + - ``2Sales`` + - ``2Sales, APAC`` + +在 15.7 之前，逗号之前部分相同的多个组会合并为同一个权限名称，因此 ``Sales, EMEA`` 与 +``Sales, APAC`` 的成员可以读取对方的文档以及 ``Sales`` 组的文档。在 15.10 中，各自获得独立的权限 +名称，这种跨组访问不会再发生。 + +作为代价，\ **以旧权限名称索引的文档将不再对该组的用户可见**\ 。如果爬取设置的「权限」中配置了 +旧的权限名称，请更新为新的权限名称并重新爬取（或重新索引）。如果没有使用 CN 中包含逗号等转义字符 +的组，权限名称不会发生变化。 + +``ldap.role.search.user.enabled`` 的行为变更 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +在 15.7 之前，即使设置了 ``ldap.role.search.user.enabled=false``\ ，仍会授予从用户名派生的权限 +（``role.search.user.prefix`` 加用户名）。从 15.10 开始该设置将实际生效，为 ``false`` 时不再授予。 + +在设置为 ``false`` 的环境中，升级后用户会失去以自身命名的权限，因此针对单个用户设置了权限的文档 +将无法被该用户检索到。若要保持原有行为，请恢复为随附的默认值 ``true``\ 。 + +若此前修改过 /api/v2 配置键 +------------------------------------------------ + +从 15.8.0 起，有四个配置键去掉了 ``api.v2.`` 前缀。其取值、默认值和行为均未改变，但\ +**没有保留向后兼容的别名**\ ：仍使用旧名称的设置会被静默忽略，实际生效的是随附的默认值。 + +.. list-table:: + :header-rows: 1 + + * - 15.7 及以前 + - 15.8.0 及以后 + - 默认值 + * - ``api.v2.chat.stream.keepalive.interval.ms`` + - ``api.chat.stream.keepalive.interval.ms`` + - ``15000`` + * - ``api.v2.param.max.length`` + - ``api.param.max.length`` + - ``1000`` + * - ``api.v2.param.max.array.size`` + - ``api.param.max.array.size`` + - ``100`` + * - ``api.v2.click.max.rt`` + - ``api.click.max.timestamp`` + - ``9999999999999`` + +如果曾在 ``fess_config.properties`` 中或通过 ``-Dfess.config.<键>`` JVM 参数设置过这些键，\ +请改用新名称。只有显式设置过的情况才会受影响；从未修改过的环境无需处理。 + +第一个键决定 ``POST /api/v2/chat/stream`` 等待模型响应期间发送 keep-alive 帧的间隔，\ +因此设置失效会在 AI 搜索模式中显现。最后一个键的改名也是为了更准确：它限制的是点击日志中\ +``rt`` 的取值上限，而该值是时间戳而非响应时间。 + + +.. _upgrade-plugin-versions: + +插件版本更新 +------------------------ + +安装在 ``app/WEB-INF/plugin/`` 中的插件，需要替换为与 |Fess| 版本对应的版本。 +``bin/fess-setup upgrade plugins`` 会针对所有已安装的插件，安装为此 |Fess| 构建的版本并删除旧版本。 +之后请重启 |Fess| 。 ``bin/fess-setup check`` 会报告 OpenSearch 及其插件、已安装的 |Fess| 插件的 +状态，出现问题时以退出码 1 结束。它不会读取 ``bin/fess.in.sh`` 、 ``/etc/sysconfig/fess`` 和 +``/etc/default/fess`` ，因此当 OpenSearch 不在 ``http://localhost:9200`` 时，请指定 ``--url`` ， +或在运行它的 shell 中设置 ``SEARCH_ENGINE_HTTP_URL`` ；否则它会报告无法连接到引擎。 + +:: + + $ bin/fess-setup upgrade plugins + $ bin/fess-setup check + +``upgrade plugins`` 只处理已安装的插件。 ``fess-script-groovy`` 等用于补充 15.10 从发行包中移除 +部分的插件，请按照前面各节的说明，使用 ``bin/fess-setup install plugin`` 安装。 + +如果在 Docker 版中指定了 ``FESS_PLUGINS``，请按照 ``fess-ds-wikipedia:15.10.0`` +的形式更新版本号部分。 + +回滚步骤 +============== + +如果升级失败，可以按照以下步骤回滚。 + +步骤 1: 停止新版本 +------------------------------ + +:: + + $ sudo systemctl stop fess.service + $ sudo systemctl stop opensearch.service + +步骤 2: 恢复旧版本 +---------------------------- + +从备份恢复配置文件和数据。 + +RPM/DEB 版的情况:: + + $ sudo rpm -Uvh --oldpackage --nodeps fess-.rpm + +或:: + + $ sudo dpkg -i fess-.deb + +.. note:: + + RPM 需要 ``--nodeps`` 。15.8.0 的软件包要求存在 ``fess`` 和 ``opensearch`` 用户及组，不指定时 + ``rpm`` 会以 ``Failed dependencies: group(fess) is needed by fess-15.8.0`` 拒绝降级。 + +.. warning:: + + 15.8.0 的 DEB 软件包没有将 ``/etc/fess/*`` 注册为 conffile，因此 ``dpkg -i`` 会覆盖编辑过的 + ``/etc/fess/fess_config.properties`` 等文件，且不保留副本。请从步骤 1 中获取的备份恢复。 + +步骤 3: 恢复数据 +---------------------- + +从快照恢复。请保持 OpenSearch 运行，|Fess| 停止： + +1. 启动 OpenSearch:: + + $ sudo systemctl start opensearch.service + +2. 快照无法恢复到已存在的索引之上，因此请先删除所有 Fess 的索引，包括升级后（例如通过重新索引） + 创建的索引，以及 OpenSearch 插件创建的 ``configsync`` 索引。如果只删除快照中包含的索引， + 重新索引创建的索引会残留，``fess.search`` 会指向两个索引，15.8.0 无法启动:: + + $ curl "http://localhost:9200/_cat/indices/fess*,configsync?h=index" + $ curl -X DELETE "http://localhost:9200/" + + 对第一条命令列出的每个索引，分别执行第二条命令。 + +3. 恢复快照:: + + $ curl -X POST "http://localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true" + +.. note:: + + 词典目录（``configsync.config_path`` ，其中包含词典文件）必须与以前一样存在。在丢失了该目录的 + 机器上，恢复虽然会完成，但使用词典的索引会一直是 red 状态。 + +或从备份恢复目录（请指定步骤 1 中创建的归档文件名）:: + + $ sudo systemctl stop opensearch + $ sudo rm -rf /var/lib/opensearch/data/* + $ sudo tar xzf /backup/opensearch-data-.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 个文件。 + 搜索日志等 ``*.ndjson`` 文件不被接受，会导致错误。 + +.. warning:: + + 上传 ``fess.json`` 和 ``doc.json`` 会覆盖 |Fess| 自带的索引定义文件本身。 + 升级后如果上传旧版本的 ``fess.json`` 或 ``doc.json``，会导致新版本的索引设置和映射丢失。 + 请勿在回滚以外的目的下上传这些文件。 + +.. note:: + + 上传的 ``system.properties`` 仅会加载到内存中，不会写入文件。 + 因此 ``system.properties`` 的内容会在 |Fess| 重启后丢失。 + 如需确保可靠恢复，请将备份的文件直接放置到指定位置（ZIP 版为 + ``app/WEB-INF/conf/``\ ，RPM/DEB 版为 ``/etc/fess/``\ ）后再启动。 + +.. note:: + + 导入操作以异步方式执行，画面上仅会显示已开始的提示。 + 请通过 ``fess.log`` 确认是否真正成功。 + +步骤 4: 启动和确认服务 +---------------------------- + +:: + + $ sudo systemctl start opensearch.service + $ sudo systemctl start fess.service + +确认运行并验证已恢复正常。 + +常见问题 +========== + +Q: 可以无停机时间升级吗？ +-------------------------------------------- + +A: Fess 的升级需要停止服务。要最小化停机时间，请考虑以下方法： + +- 提前在测试环境确认步骤 +- 提前获取备份 +- 确保充足的维护时间 + +Q: 需要升级 OpenSearch 吗？ +------------------------------------------------- + +A: 每个 |Fess| 版本对应特定的 OpenSearch 版本。 +|Fess| 15.10 对应 OpenSearch 3.9.0。 +由于 ``opensearch-analysis-fess`` 等 |Fess| 专用 OpenSearch 插件必须与 OpenSearch 版本完全一致， +因此在升级 OpenSearch 时，请同时将插件更新为对应版本（3.9.0）。 + +另外，|Fess| 15.10 强制要求安装 k-NN 插件，并会在索引设置中始终发送 +``knn.derived_source.enabled``。如果 OpenSearch 版本过旧，会导致新索引创建失败， +因此实质上必须升级 OpenSearch。详情请参阅步骤 4。 + +Q: 需要重建索引吗？ +------------------------------------------ + +A: 对于 |Fess| 的小版本升级（15.x → 15.10），如果不使用分块向量搜索， +通常不需要重建索引。现有索引可以直接使用，\ ``content_chunker.enabled`` 等选项默认为 +禁用，因此行为不会改变。 + +以下情况需要重建索引并重新索引。 + +- **新启用分块向量搜索（语义搜索）时**: 由于现有索引不会反映新的映射， + 必须进行重新索引。详情请参阅 + :ref:`semantic-search-migration`\ （:doc:`../config/search-semantic`）。 +- **从 14.x 升级时**: 由于 OpenSearch 会从 2.x 主版本升级到 3.x， + 建议重建索引。 +- **在由 15.8 或更早版本创建的文档索引上使用所有者搜索或假名规范化时**: 需要重新索引。 + 详情请参阅 :ref:`upgrade-reindex-new-fields`\ 。 + +.. warning:: + + 新建索引的操作（包括重新索引）在没有 k-NN 插件的 OpenSearch 中会失败。 + 请确认步骤 4 中的注意事项。 + +Q: 升级后搜索结果不显示 +------------------------------------------ + +A: 请确认以下内容： + +1. 确认 OpenSearch 是否启动 +2. 确认索引是否存在（``curl http://localhost:9200/_cat/indices``） +3. 重新执行爬取 + +下一步 +========== + +升级完成后： + +- :doc:`run` - 确认启动和初始设置 +- :doc:`security` - 重新检查安全配置 +- :doc:`../config/search-semantic` - 分块向量搜索（语义搜索）的配置与迁移步骤 +- 在发布说明中确认新功能 diff --git a/zh-cn/15.10/user/advanced-search.rst b/zh-cn/15.10/user/advanced-search.rst new file mode 100644 index 000000000..33f0dde75 --- /dev/null +++ b/zh-cn/15.10/user/advanced-search.rst @@ -0,0 +1,79 @@ +======== +高级检索 +======== + +在高级检索界面可以通过组合多个条件进行更高级的检索。 + +使用方法 +-------- + +可以从搜索界面的搜索选项中的“高级检索”链接访问高级检索界面。从搜索结果界面打开时,已输入的检索关键字会带入“包含所有单词”字段中。 + +|image0| + +在各个字段中输入条件,然后单击页面下部的搜索按钮即可进行检索。输入的多个字段会组合成一个检索条件。 + +项目列表 +-------- + +包含所有单词 +:::::::::::: + +可以检索包含输入的所有单词的文档（AND 检索）。多个单词以空格分隔指定。 + +包括词序的完全匹配 +:::::::::::::::::: + +可以检索完全包含输入字符串（含词序）的文档（短语检索）。由于包含空格在内的整个字符串会作为一个短语处理,因此无法拆分为各个单词进行检索。 + +包含任一单词 +:::::::::::: + +可以检索包含输入的任一单词的文档（OR 检索）。多个单词以空格分隔指定。 + +不包含的单词 +:::::::::::: + +可以检索不包含输入单词的文档。多个单词以空格分隔指定,指定的所有单词都会从检索结果中排除。 + +显示数量 +:::::::: + +可以指定每页显示的搜索结果数量。可以从 10、20、30、40、50、100 中选择。如果不指定,则使用默认显示数量（初始值为 10）。 + +排序 +:::: + +可以指定搜索结果的排序基准。可以从按分数、文件名、日期、大小、上次修改时间中选择,每种都可选择升序或降序。当启用相应功能时,还可以按点击数或收藏数排序。 + +优先语言 +:::::::: + +可以指定搜索结果中优先的语言。可以选择多种语言。如果选择“所有语言”,则不优先特定语言。 + +标签 +:::: + +可以通过标签筛选检索。可以选择多个标签。如果没有注册标签,或者没有当前用户可查看的标签,则不会显示。 + +更新日期 +:::::::: + +可以通过文档的更新日期时间筛选检索。可以从不限、过去24小时、过去1周、过去1个月、过去1年中选择。 + +文件格式 +:::::::: + +可以通过文档的文件格式筛选检索。可以从所有类型、HTML、PDF、MS Word、MS Excel、MS PowerPoint 中选择。 + +检索对象 +:::::::: + +可以指定检索的位置。可以从整个页面、页面标题、页面URL中选择。如果选择页面标题或页面URL选项,则仅分别在标题或 URL 中检索输入的单词。 + +网站或域名 +:::::::::: + +可以通过输入的网站或域名筛选检索。当只想检索特定网站或域名中包含的文档时指定。 + +.. |image0| image:: ../../../resources/images/en/15.10/user/advanced-search-1.png diff --git a/zh-cn/15.10/user/chat-search.rst b/zh-cn/15.10/user/chat-search.rst new file mode 100644 index 000000000..2eb7e9f47 --- /dev/null +++ b/zh-cn/15.10/user/chat-search.rst @@ -0,0 +1,254 @@ +========== +AI搜索模式 +========== + +概述 +==== + +使用 |Fess| 的AI搜索模式功能（RAG聊天），除了传统的关键词搜索之外， +还可以通过自然对话的形式查找信息。输入问题后，AI助手会检索相关文档， +并基于文档内容生成易于理解的回答。 + +.. note:: + AI搜索模式在初始状态下处于禁用状态。若要使用该功能，需要系统管理员先启用 + 该功能，并配置好LLM（大语言模型）提供商。配置方法请参阅 + :doc:`../config/rag-chat` 和 :doc:`../config/llm-overview`。 + +AI搜索模式的特点 +================ + +对话形式的搜索 +-------------- + +无需构思关键词，就可以像日常对话一样提问。 + +示例: + +- 「请告诉我Fess的安装方法」 +- 「应该如何爬取文件？」 +- 「搜索结果不显示时该如何处理？」 + +理解上下文的回答 +---------------- + +AI助手会分析问题的意图，检索相关文档，并从多个搜索结果中提取 +所需信息，以整理好的形式进行回答。 + +明示来源 +-------- + +回答的下方会以“来源”的形式，列出作为回答依据的文档。每个来源都是 +带编号的链接，点击即可直接查看原始文档。此外，回答正文中有时会以 +``[1]``、``[2]`` 之类的编号显示引用，这些编号与来源列表中的编号 +相对应。 + +延续对话 +-------- + +提问不止一次即结束，还可以继续对话。 +AI助手会结合之前问题和回答的上下文，回答追加的问题。 + +聊天搜索的使用方法 +================== + +打开AI搜索模式 +-------------- + +1. 打开 |Fess| 的搜索画面 +2. 点击画面顶部导航栏中的“AI搜索”链接（机器人图标） +3. 显示AI搜索模式的画面 + +.. note:: + “AI搜索”链接仅在AI搜索模式已启用且LLM提供商可用时才会显示。 + 如果链接未显示，请参阅\ `常见问题`_\ 。 + +输入问题 +-------- + +1. 在画面下方的文本框中输入问题（每次提问最多4000个字符） +2. 点击“发送消息”按钮（纸飞机图标），或按 Enter 键 +3. AI助手开始生成回答 + +.. note:: + 如果需要换行，请按 Shift+Enter 键代替 Enter 键。 + +.. note:: + 生成回答可能需要几秒到十几秒的时间。处理过程中，会以进度显示 + （分析 → 搜索 → 评估 → 获取 → 回答）的形式展示当前处理阶段， + 并显示类似“思考中...”、“搜索中...”、“正在检查搜索结果...”、 + “正在获取文档...”、“正在生成回答...”的消息。搜索完成后， + 还会显示找到的文档数量。 + +确认回答 +-------- + +系统会显示AI助手的回答。回答中包含以下信息: + +- **回答正文**: 针对问题的回答（以Markdown格式排版） +- **来源**: 作为回答依据的文档链接列表（带编号的链接，点击后会在新标签页中打开原始文档） + +回答正文中可能包含 ``[1]``、``[2]`` 之类的引用编号，这些编号与来源列表中的编号相对应。 +每个回答都带有复制按钮，可以将回答内容复制到剪贴板。 + +.. note:: + AI仅会将其判断为相关性较高的靠前文档用作回答依据。因此， + “来源”的数量可能会少于搜索命中的文档数量。 + +缩小搜索范围 +------------ + +根据主题不同，可以通过画面上方的“筛选”按钮，使用标签、文件类型、更新时间、 +大小等条件来缩小搜索范围。当只想针对特定范围内的文档向AI提问时， +这个功能会很有用。 + +继续对话 +-------- + +如果还有其他问题，可以直接继续提问: + +- 「请再详细说明一下」 +- 「还有其他方法吗？」 +- 「关于〇〇的详细说明」 + +AI助手会结合之前的对话上下文进行回答。 + +开始新对话 +---------- + +如果想询问其他主题，请点击“新对话”按钮（+图标）。 +这样会清除之前的对话历史，从而开始新的对话。 + +有效提问的技巧 +============== + +具体提问 +-------- + +相比模糊的问题，具体的问题更容易得到恰当的回答。 + +.. list-table:: + :header-rows: 1 + :widths: 50 50 + + * - 模糊的问题 + - 具体的问题 + * - 设置方法是什么？ + - 如何更改Fess的内存设置？ + * - 出现错误 + - 搜索时出现“找不到索引”的错误 + * - 关于爬取 + - 爬取网站时应该如何设置排除规则？ + +包含背景信息 +------------ + +包含具体情况和目的，可以获得更恰当的回答。 + +好的示例: + +- 「我在Docker环境中运行Fess。想更改日志的保存位置，该怎么做？」 +- 「我是第一次使用Fess。首先应该做什么？」 + +分步提问 +-------- + +复杂的问题通过分步提问会更容易理解。 + +1. 「Fess可以爬取文件共享吗？」 +2. 「请告诉我SMB协议的连接方法」 +3. 「如果是需要认证的共享文件夹，该怎么办？」 + +常见问题 +======== + +Q: 未显示AI搜索模式 +------------------- + +A: AI搜索模式可能尚未启用。 +“AI搜索”链接仅在功能已启用（``rag.chat.enabled=true``）且LLM提供商 +（OpenAI、Gemini、Ollama等）已配置并可用时才会显示。 +请向系统管理员确认AI搜索模式是否已启用，以及LLM提供商是否配置正确 +（详情请参阅 :doc:`../config/rag-chat`）。 + +Q: 需要一段时间才能显示回答 +--------------------------- + +A: 由于AI需要先分析问题，再对文档进行搜索和评估，然后才生成回答， +因此可能需要几秒到十几秒的时间。处理过程中，会显示当前的处理阶段 +（“思考中...”、“搜索中...”、“正在检查搜索结果...”、“正在获取文档...”、 +“正在生成回答...”）。 + +Q: “来源”看起来不正确 +--------------------- + +A: 请点击“来源”链接，确认原始文档。 +AI是基于搜索结果生成回答的，但解释内容有时可能存在误差。 +建议对重要信息务必在原始文档中进行确认。 + +Q: 之前的对话似乎被遗忘了 +------------------------- + +A: 对话会话可能已超时。 +如果在一定时间内（默认为30分钟）没有任何操作，对话历史就会被清除。 +此外，对话历史仅临时保存在服务器的内存中，因此服务器重启后也会丢失。 +这种情况下，请开始新的对话。 + +.. note:: + 这里所说的“会话”是指AI搜索模式的对话会话，与 |Fess| 的登录会话是两回事。 + +Q: 针对特定问题无法获得回答 +--------------------------- + +A: 可能存在以下原因: + +- 搜索目标文档中没有相关信息 +- 问题过于模糊，无法进行恰当的搜索 +- 已达到速率限制（超过每分钟请求数上限，或超过并发数上限） + +请换一种方式表述问题，或稍等片刻后重试。 + +Q: 可输入的字符数有限制吗？ +--------------------------- + +A: 每次提问最多可输入4000个字符。文本框下方会显示字符数计数器， +接近上限时会出现警告提示。如果问题较长，请提炼要点并进行精简。 + +Q: 可以用日语以外的语言提问吗？ +------------------------------- + +A: 可以，大多数情况下，也可以使用英语或其他语言提问。 +AI会根据浏览器或画面的显示语言，尽可能使用同一种语言进行回答。 +不过，这只是尽力而为的处理方式，根据具体情况，有时可能无法得到 +预期语言的回答。 + +注意事项 +======== + +关于AI的回答 +------------ + +- AI的回答是基于搜索结果生成的 +- 不保证回答内容的准确性 +- 进行重要判断时，请务必确认原始文档（来源） +- 最新信息请以官方文档为准进行确认 + +关于隐私 +-------- + +- 输入的问题会用于搜索，以及由所配置的LLM提供商进行AI处理 +- 如果配置为使用外部LLM服务（如OpenAI、Gemini等），问题内容和搜索结果会被发送到该服务。 + 如果希望仅在公司内部进行处理，请与管理员协商是否可以使用在本地运行的提供商（如Ollama等） +- 对话历史会临时保存在服务器内存中，会话超时、执行“新对话”或服务器重启都会将其删除 +- 与普通搜索一样，系统会应用基于角色（权限）和标签的访问控制，无法查看的文档不会成为回答的对象 +- 根据系统设置，可能会记录日志 + +参考信息 +======== + +- :doc:`../config/rag-chat` - AI搜索模式功能的配置（面向管理员） +- :doc:`../config/llm-overview` - LLM提供商的配置 +- :doc:`../api/api-chat` - Chat API（通过程序调用） +- :doc:`search-and` - AND搜索的使用方法 +- :doc:`search-not` - NOT搜索的使用方法 +- :doc:`search-field` - 字段搜索的使用方法 +- :doc:`advanced-search` - 高级搜索功能 diff --git a/zh-cn/15.10/user/index.rst b/zh-cn/15.10/user/index.rst new file mode 100644 index 000000000..41da04238 --- /dev/null +++ b/zh-cn/15.10/user/index.rst @@ -0,0 +1,28 @@ +|Fess| 用户指南 +================== + +说明在 |Fess| 中编写搜索条件的方法，涵盖 AND、OR、NOT、\ +字段搜索与标签搜索、排序、通配符、范围、加权、模糊搜索、邻近搜索和地理搜索。 + +.. toctree:: + :maxdepth: 2 + + intro + search-and + search-or + search-not + search-bangs + search-label + search-field + search-sort + search-wildcard + search-range + search-boost + search-fuzzy + search-proximity + search-geo + search-additional + role-search + special-char + advanced-search + chat-search diff --git a/zh-cn/15.10/user/intro.rst b/zh-cn/15.10/user/intro.rst new file mode 100644 index 000000000..5ed2d025f --- /dev/null +++ b/zh-cn/15.10/user/intro.rst @@ -0,0 +1,50 @@ +======== +搜索简介 +======== + +目标读者 +====== + +|Fess| 是一款企业级搜索服务器,可对网站、文件、数据库等中包含的文档进行全文检索。 + +本文档面向使用 |Fess| 的用户。 + +阅读前须知 +============ + +本文档介绍了 |Fess| 的搜索方法。除了基本的关键词搜索外,还将介绍如何使用高级检索界面进行筛选检索,以及可以通过自然对话形式查找信息的AI搜索模式。需要具备计算机操作的基础知识。 + +在线访问 +================= + +有关下载、专业服务、支持和其他开发者信息,请访问: + +- 项目网站: https://fess.codelibs.org/ + +技术支持联系方式 +================== + +如果您对本产品有技术问题,并且在文档中找不到解决方案,请访问: + +- Issues: + `https://github.com/codelibs/fess/issues `__ + +商业支持 +--------- + +如果您需要技术支持或维护等商业服务,请联系 `N2SM, Inc. `__\ 。 + +关于第三方网站的参考 +============================= + +|Fess| 项目不对本文档中提及的第三方网站的有效性负责。\ |Fess| 项目不对通过这些网站或资源提供的内容、广告、产品、服务或其他材料提供任何保证、责任或义务。\ |Fess| 项目不对因使用或信赖通过这些网站或资源提供的内容、广告、产品、服务或其他材料而产生或声称的任何损害或损失承担责任或义务。 + +评论和建议的提交方式 +===================== + +|Fess| +项目致力于改进本文档,并欢迎读者提供评论和建议。 + +- Issues: + `https://github.com/codelibs/fess-docs/issues `__ + diff --git a/zh-cn/15.10/user/role-search.rst b/zh-cn/15.10/user/role-search.rst new file mode 100644 index 000000000..e6688f8c3 --- /dev/null +++ b/zh-cn/15.10/user/role-search.rst @@ -0,0 +1,57 @@ +======== +角色检索 +======== + +|Fess| 提供用户管理功能，登录用户可以根据自己所属的角色进行检索。\ |Fess| 管理的用户在登录后，既可以使用角色检索，也可以更改自己的密码。 + +在角色检索中，系统会将内容中设置的权限（角色、组、用户）与检索用户所持有的权限进行核对，仅在检索结果中显示允许访问的内容。有关角色和用户的创建方法，以及为内容分配权限的方法等基于角色的检索配置，请参阅 :doc:`../config/security-role`。 + + +检索方法 +------ + +在设置角色并完成爬取和索引后，检索结果可以只显示给拥有该角色的用户。 +如果用户处于登录状态，将根据该用户所属的角色或组进行检索。 +如果未登录，则以 guest 用户身份进行检索，仅显示面向 guest 公开的内容。 + +.. note:: + 已登录用户的检索仅依据该用户本人及其所属角色、组的权限进行，面向 guest 公开（``{role}guest``）的内容不在检索范围内。因此，仅面向 guest 公开的内容，未登录的访客可以看到，但已登录的用户（包括没有任何角色或组的用户）看不到。如果希望已登录的用户也能看到某些内容，请在爬取配置的权限中，除 ``{role}guest`` 之外，再设置该用户所拥有的角色（要让所有用户都能看到时，设置授予所有用户的角色）。 + +登录 +------ + +点击检索界面上部显示的登录链接，将显示登录界面。输入用户名和密码进行登录后，将返回检索界面，此后的检索将基于该用户所属的角色进行。 + +.. note:: + 如果与单点登录或 LDAP 集成，则按各自的认证方式登录。此外，登录链接是否显示可以通过设置进行更改。 + +更改密码 +------------ + +登录后，点击检索界面上部显示的用户名，将显示菜单。 + +|image0| + +在菜单中点击「更改密码」，将显示更改密码界面。 + +|image1| + +输入当前密码、新密码以及用于确认的新密码（再次输入），点击更新按钮即可更新密码。 +更改密码后会被注销，请使用新密码重新登录。 +该界面是检索界面主题的 ``/profile`` 页面，密码通过 ``POST /api/v2/auth/password`` 进行更改（参见 :doc:`../api/api-auth` ）。 + +.. note:: + 「更改密码」菜单仅显示给 |Fess| 管理的用户（以及被允许编辑的 LDAP 用户）。通过单点登录认证的用户不会显示该菜单。 + 新密码可能会应用长度、可使用字符类型等密码策略。 + +注销 +-------- + +在登录状态下，点击检索界面上部显示的用户名，从菜单中选择「注销」即可退出登录。 +如果用户拥有管理员权限，也可以从同一菜单中选择「管理」，进入管理界面。 + + +.. |image0| image:: ../../../resources/images/en/15.10/user/role-search-1.png +.. pdf :width: 200 px +.. |image1| image:: ../../../resources/images/en/15.10/user/role-search-2.png +.. pdf :width: 300 px diff --git a/zh-cn/15.10/user/search-additional.rst b/zh-cn/15.10/user/search-additional.rst new file mode 100644 index 000000000..42460a268 --- /dev/null +++ b/zh-cn/15.10/user/search-additional.rst @@ -0,0 +1,30 @@ +======= +非显示检索条件 +======= + +如果您希望在不将条件文字显示在屏幕上的情况下传递特定的检索条件,可以使用 ``ex_q`` 参数。指定给 ``ex_q`` 的条件不会显示在检索关键词输入框中,即使通过分页或分面筛选更新屏幕,该条件也会保持。 + +``ex_q`` 中可以使用与常规检索关键词(``q``)相同的查询语法(``field:value`` 格式、短语、范围指定、``OR`` 等运算符)。指定的条件默认会与 ``q`` 的条件通过 AND 组合后执行检索。也就是说,与 ``ex_q`` 条件不匹配的文档将从检索结果中排除。 + +使用方法 +---- + +执行检索时(例如通过检索表单等),将 ``ex_q`` 的值作为隐藏表单字段或 URL 查询参数附加后执行检索。这样即可在不将条件显示在屏幕上的情况下进行检索。 + +``ex_q`` 可以指定多个。如下例所示,传递多个 ``ex_q`` 时,每个值都会作为检索条件被追加(空值或重复值将被忽略)。 + +.. code-block:: none + + /search?q=keyword&ex_q=label:manual&ex_q=filetype:pdf + +分页时的保持 +------ + +对于分页(下一页、上一页等)和分面筛选的链接,Fess 会自动附加 ``ex_q`` 的值。因此,即使通过这些操作更新屏幕,\ ``ex_q`` 的条件也会保持。 + +另一方面,如果通过标准的检索关键词输入框(搜索框)输入关键词并重新检索,\ ``ex_q`` 不会被继承。如果希望通过搜索框也能保持条件,请在自己的检索表单中准备 ``ex_q`` 的隐藏字段,并在每次检索时发送 ``ex_q``\ 。 + +.. note:: + + * ``ex_q`` 的各个值的长度超过 ``query.max.length`` (默认值:1000 字符)时,该值不会报错,而是被忽略。 + * ``ex_q`` 不仅可用于 Web 界面的检索,也可用于检索 API(``/api/v2``)。在 API 中,适用每次请求 ``ex_q`` 元素数量的上限(``api.v2.param.max.array.size``,默认值:100)以及各元素长度的上限(``api.v2.param.max.length``,默认值:1000 字符)。 diff --git a/zh-cn/15.10/user/search-and.rst b/zh-cn/15.10/user/search-and.rst new file mode 100644 index 000000000..b3eaea596 --- /dev/null +++ b/zh-cn/15.10/user/search-and.rst @@ -0,0 +1,46 @@ +======= +AND 检索 +======= + +当您想搜索同时包含多个搜索词的文档时,可以使用 AND 检索。在搜索输入字段中以空格分隔输入多个词时,默认为 AND 检索,因此即使省略 AND 也会得到相同的结果。 + +使用方法 +------ + +使用 AND 检索时,在搜索词之间输入 AND。AND +必须使用半角大写字母,前后需要空格。 +也可以省略 AND。 + +例如,如果想搜索包含"搜索词1"和"搜索词2"的文档,在搜索表单中输入如下内容: + +:: + + 搜索词1 AND 搜索词2 + +省略 AND 并如下书写,也会得到相同的结果: + +:: + + 搜索词1 搜索词2 + +也可以用 AND 连接 3 个以上的搜索词。 + +:: + + 搜索词1 AND 搜索词2 AND 搜索词3 + +.. note:: + + AND 必须使用半角大写字母书写。如果像 ``and`` 这样使用小写字母书写,则不会被视为运算符,而是作为普通搜索词"and"进行搜索。\ ``&&`` 也可以表示与 AND 相同的含义。 + +使用圆括号 ``( )`` 可以将 AND 检索与其他检索条件组合使用。例如,如果想搜索包含"搜索词1",并且包含"搜索词2"或"搜索词3"中任意一个的文档,请按如下方式输入: + +:: + + 搜索词1 AND (搜索词2 OR 搜索词3) + +也可以指定字段进行 AND 检索。以下示例搜索 title 字段中包含"搜索词1",并且 content 字段中包含"搜索词2"的文档。 + +:: + + title:搜索词1 AND content:搜索词2 diff --git a/zh-cn/15.10/user/search-bangs.rst b/zh-cn/15.10/user/search-bangs.rst new file mode 100644 index 000000000..5be2063b8 --- /dev/null +++ b/zh-cn/15.10/user/search-bangs.rst @@ -0,0 +1,80 @@ +============================= +Bang 检索（在其他网站上搜索） +============================= + +Bang 会把搜索发送到其他网站，而不是在 |Fess| 中搜索。它的用法与 DuckDuckGo 的 bang 相同：在检索词中加入 ``!`` 和一个简短的触发词，|Fess| 就会把检索词的其余部分发送到该触发词所代表的网站。 + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - 检索词 + - 发送到 + * - ``airplane !g`` + - Google，搜索 ``airplane`` + * - ``!w Ohm's law`` + - Wikipedia，搜索 ``Ohm's law`` + * - ``!g`` + - Google 首页 + * - ``airplane !unknown`` + - |Fess| 中的普通检索（``!`` 表示 NOT，请参阅 :doc:`search-not`） + +Bang 由 ``fess-webapp-bangs`` 插件提供，需要 |Fess| 15.10 或更高版本。请在管理界面的[系统 > 插件]中，或使用 ``bin/fess-setup install plugin fess-webapp-bangs`` 安装（请参阅 :doc:`../admin/plugin-guide`），然后重启 |Fess|。 + +Bang 的识别条件 +=============== + +- Bang 是 ``!`` 后接触发词，需作为独立的词书写。触发词不区分大小写。 +- Bang 会从检索词中移除，检索词的其余部分会被发送到该 bang 的 URL。 +- 检索词中包含多个已定义的 bang 时，只有第一个生效。 +- 未定义的触发词不是 bang。``!unknown`` 照常检索，并排除词 ``unknown``。 +- ``-g`` 和 ``NOT g`` 仍然排除词 ``g``。只有 ``!g`` 是 bang。 + +搜索页面和 ``/api/v2/search`` 支持重定向：API 返回 ``redirect_url`` （请参阅 :doc:`../api/api-search`），|Fess| 自带的 ``bootstrap`` 主题会跳转到该 URL。其他主题需要进行同样的处理。 + +聊天、MCP、v1 API 和经典 JSON API、管理界面的搜索等无法重定向的调用方，不会把搜索发送到其他网站。它们会移除 bang，并检索检索词的其余部分。 + +定义 Bang +========= + +Bang 通过系统属性 ``bangs.definitions`` 定义。可以写在 ``app/WEB-INF/conf/system.properties`` 中，也可以作为 ``-Dfess.system.bangs.definitions=...`` 传入。对 ``system.properties`` 的修改无需重启 |Fess| 即可生效。 + +值是以空白分隔的 ``触发词=URL`` 条目列表。URL 中的 ``{query}`` 会被替换为经过 URL 编码的其余检索词： + +:: + + bangs.definitions=g=https://www.google.com/search?q={query} w=https://en.wikipedia.org/wiki/Special:Search?search={query} + +- 触发词不能包含空白、 ``(`` 、 ``)`` 、 ``!`` 、 ``"`` 、 ``=`` 或 ``:`` 。 +- 只接受绝对 URL 的 ``http`` 或 ``https`` 。 +- 不符合这些规则的条目不会被使用。|Fess| 日志中会输出警告，其他条目保持有效。 +- 同一个触发词被定义两次时，使用第一个定义。 +- 值为空时，所有 bang 都会被关闭。 + +未设置 ``bangs.definitions`` 时，可以使用以下 5 个 bang： + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - 触发词 + - 网站 + * - ``g`` + - Google + * - ``b`` + - Bing + * - ``ddg`` + - DuckDuckGo + * - ``w`` + - Wikipedia（英文） + * - ``gh`` + - GitHub + +设置 ``bangs.definitions`` 后，这个列表会被替换。若想保留默认的 bang 并再增加一个，请写出所需的全部条目。 + +相关主题 +======== + +- :doc:`search-not` - NOT 检索 +- :doc:`special-char` - 特殊字符与转义 +- :doc:`../api/api-search` - 检索 API diff --git a/zh-cn/15.10/user/search-boost.rst b/zh-cn/15.10/user/search-boost.rst new file mode 100644 index 000000000..20a7c95e9 --- /dev/null +++ b/zh-cn/15.10/user/search-boost.rst @@ -0,0 +1,46 @@ +========= +提升检索 +========= + +提升检索(加权检索) +==================== + +当您想优先处理特定搜索词时,可以使用提升检索。通过使用提升检索,可以根据搜索词的重要程度进行检索。 + +使用方法 +------ + +要使用提升检索,需要在搜索词后以"^提升值"的格式指定提升值(加权值)。搜索词与提升值之间请不要加空格。 + +例如,在搜索"苹果 橘子"时,如果想优先显示"苹果",可以在搜索表单中输入如下内容: + +:: + + 苹果^100 橘子 + +该示例仅对"苹果"应用了提升值,对"橘子"不应用提升值。 + +提升值 +------ + +提升值需指定数值。除了整数外,还可以指定如 ``2.5`` 这样的小数。 + +- 指定大于 1 的值时,该搜索词的权重会增加。 +- 指定大于 0 且小于 1 的值(例如 ``0.5``)时,该搜索词的权重会降低。 + +提升值并非绝对地决定搜索结果的得分,而是用于调整与其他搜索词之间的相对权重。 + +与其他检索语法的组合 +-------------------- + +提升检索可以与其他检索语法组合使用。例如,也可以在指定了字段的搜索词上附加提升值。 + +:: + + title:苹果^100 橘子 + +该示例中,由于并列多个搜索词时适用默认运算符 (AND),因此只会检索 title 字段包含"苹果"并且同时包含"橘子"的文档。如果希望优先显示包含"苹果"的文档,同时也保留不包含"苹果"的文档,请使用 OR 连接。 + +:: + + title:苹果^100 OR 橘子 diff --git a/zh-cn/15.10/user/search-field.rst b/zh-cn/15.10/user/search-field.rst new file mode 100644 index 000000000..87926eaf2 --- /dev/null +++ b/zh-cn/15.10/user/search-field.rst @@ -0,0 +1,127 @@ +====================================== +字段指定检索（按标题、URL 等缩小范围） +====================================== + +字段指定检索 +============== + +通过对特定字段进行检索(字段指定检索),可以将检索范围缩小到仅标题、仅 URL 等。\ |Fess| 爬取的结果按标题、正文等字段分别保存。通过指定这些字段进行搜索,可以按文档类型、大小等设置详细的搜索条件。 + +可用字段 +--------------- + +默认情况下,可以指定以下字段进行搜索。 + +.. list-table:: + :header-rows: 1 + + * - 字段名 + - 说明 + - 数据类型 + * - url + - 爬取的 URL + - 关键字 + * - host + - 爬取的 URL 中包含的主机名 + - 关键字 + * - site + - 从 URL 中去除协议和查询字符串后的字符串(主机名和路径)。以前缀匹配方式进行搜索 + - 关键字 + * - title + - 标题 + - 文本 + * - content + - 正文 + - 文本 + * - content_length + - 文档大小(字节) + - 数值 + * - last_modified + - 文档的最后更新日期时间 + - 日期 + * - timestamp + - 文档的注册日期时间(无法获取最后更新日期时间时,为爬取执行时刻) + - 日期 + * - mimetype + - 文档的 MIME 类型(例如: ``text/html``) + - 关键字 + * - filetype + - 由 MIME 类型决定的文件类型(例如: ``html``、``word``、``pdf``\ 。不属于以上情况时为 ``others``) + - 关键字 + * - filename + - URL 路径末尾的文件名 + - 关键字 + * - label + - 文档被赋予的标签值 + - 关键字 + * - lang + - 文档的语言代码(例如: ``ja``、``en``) + - 关键字 + * - anchor + - 从 HTML 页面中提取的链接目标 URL(仅限 Web 爬取) + - 关键字 + * - click_count + - 文档被点击的次数 + - 数值 + * - favorite_count + - 文档被收藏的次数 + - 数值 + * - owner + - 文件所有者的账户名 + - 关键字 + * - last_modifier + - 文件的最后修改者 + - 关键字 + +表: 可用字段列表 + +"数据类型"表示各字段搜索方式的不同。 + +* 关键字: 以整个值为对象进行完全匹配搜索。也可以与通配符检索、前缀检索组合使用。 +* 文本: 以经过分词处理(如形态素分析)得到的词为对象进行全文检索。title、content 等字段属于此类。 +* 数值、日期: 可以使用 :doc:`范围指定检索 `。 + +如果未指定字段,则以 title 和 content 为搜索对象。根据设置,也可以添加作为搜索对象的字段。 + +.. note:: + 根据爬取对象的不同,有些字段可能不会被注册值。例如,anchor 仅在 Web 爬取时才会被注册。lang 会注册 HTML 的语言属性,或根据文档正文判定出的语言;无法判定语言,或判定出的语言不在 ``supported.languages`` 中时,则不会注册。此外,还可以指定 segment(表示爬取执行单位的会话 ID)、doc_id(系统分配编号的内部 ID)等字段,但通常的搜索中不会使用它们。 + +owner 和 last_modifier 会在爬取文件服务器等时注册。owner 中存放通过 SMB、文件系统、FTP 爬取获取的文件所有者的账户名（ ``DOMAIN\alice`` 这样的值会变为 ``alice`` ）。last_modifier 中存放从 Office 文档等中提取的最后修改者，无法获取时存放所有者。Web 爬取的 HTML 不会注册 owner。例如，可以像 ``owner:alice`` 或 ``last_modifier:"Taro Yamada"`` 这样搜索。在内置主题中，可以在高级搜索中指定所有者和最后修改者。管理员可以通过 ``crawler.document.file.owner.enabled`` 和 ``crawler.document.file.last.modifier.enabled`` （默认均为 ``true`` ）切换是否注册。 + +当 HTML 文件作为搜索对象时,title 标签注册为 title 字段,body 标签以下的字符串注册为 content 字段。 + +使用方法 +------ + +进行字段指定检索时,以"字段名:搜索词"的格式,用冒号(:)分隔字段名和搜索词,在搜索表单中输入并搜索。 + +对 title 字段以 fess 为搜索词进行搜索时,输入如下内容: + +:: + + title:fess + +通过上述搜索,将显示 title 字段包含 fess 的文档作为搜索结果。 + +对 url 字段进行搜索时,输入如下内容: + +:: + + url:https\:\/\/fess.codelibs.org\/ja\/15.10\/* + url:"https://fess.codelibs.org/ja/15.10/*" + +前者可以使用通配符检索,因此也可以写成 ``url:*\/\/fess.codelibs.org\/*`` 这样的形式。url 中包含的":"和"/"是搜索查询中的特殊字符,请使用 ``\`` 进行转义(请参阅 :doc:`special-char`)。后者不能使用通配符检索,但末尾为 ``*`` 的词将作为前缀(前方匹配)检索处理。 + +.. tip:: + 如果想通过 URL 的一部分进行搜索,可以使用 ``inurl:`` 对 URL 进行部分匹配检索。例如 ``inurl:15.10`` 会搜索 URL 中包含 ``15.10`` 的文档。 + +对于像 mimetype、filetype、site 这样值中包含"/"的字段,请像 ``mimetype:"text/html"`` 这样用引号括起来,或者像 ``mimetype:text\/html`` 这样进行转义。 + +关于相关的搜索语法,另请参阅 :doc:`通配符检索 ` 、 :doc:`范围指定检索 ` 、 :doc:`排序检索 ` 、 :doc:`特殊字符 ` 。 + +相关主题 +------------ + +- :doc:`search-range` - 范围指定检索 +- :doc:`search-wildcard` - 通配符检索 +- :doc:`special-char` - 特殊字符与转义 diff --git a/zh-cn/15.10/user/search-fuzzy.rst b/zh-cn/15.10/user/search-fuzzy.rst new file mode 100644 index 000000000..bcb1a7cd3 --- /dev/null +++ b/zh-cn/15.10/user/search-fuzzy.rst @@ -0,0 +1,66 @@ +====== +模糊检索 +====== + +模糊检索（Fuzzy 检索） +============== + +如果想要搜索与检索词不完全一致的单词，可以使用模糊检索（Fuzzy 检索）。模糊检索是指，当检索词与索引中登记的单词之间的差异（编辑距离）在一定范围内时，将该单词视为匹配进行检索的方法。编辑距离是指将某个单词转换为另一个单词所需的字符插入、删除、替换等操作的最小次数。\ |Fess| 默认在这些操作的基础上，还会将相邻 2 个字符的互换也计为 1 次差异，采用达梅劳-莱文斯坦距离（最优字符串对齐）。 + +使用方法 +---- + +在希望应用模糊检索的检索词后面添加"~"。 + +例如，如果想对"fess"这个单词进行模糊检索，可以按如下方式在搜索表单中输入，从而搜索包含与"fess"相近的词（如"fes"等）的文档。 + +:: + + fess~ + +在"~"后面加上数字，可以指定允许的编辑距离（即允许相差多少个字符）。可指定的值为 0、1、2 中的整数。 + +:: + + fess~1 + +上述示例将搜索与"fess"编辑距离在 1 以内的单词。 + +如果省略数字，仅指定"~"，则按编辑距离 2 处理。编辑距离的最大值为 2，即使指定 3 以上的值，也会按 2 处理。 + +也可以指定字段进行模糊检索。下面的示例将在 title 字段中搜索包含与"fess"相近的词的文档。 + +:: + + title:fess~ + +如果不指定字段，将以 title 和 content 字段为对象进行模糊检索。 + +使用条件 +---- + +使用模糊检索时，请注意以下几点。 + +* 模糊检索以单词为单位应用，无法应用于用引号括起来的短语。此外，短语后面添加的数字（例如 ``"Fess Search"~2``）不是模糊检索，而是表示单词间距离的\ :doc:`邻近检索 `\ 。 +* 模糊检索针对索引中已登记的单词进行，检索词不会被重新解析。因此，对于通过 bi-gram 或形态素解析进行分词的日语等文本，可能无法按预期工作。模糊检索主要对英数字单词有效。 +* 模糊检索的检索词会连同大小写在内，原样计算编辑距离。登记到索引中的英文单词通常已转换为小写，因此检索词请使用小写。例如 ``Fess~1`` 仅开头的大写 ``F`` 就用掉了编辑距离 1，所以结果与 ``fess~1`` 不同。另外，``Fess~0`` 由于索引中没有与大写单词 ``Fess`` 匹配的词，因此什么都匹配不到（小写的 ``fess~0`` 是完全匹配）。 +* 对 1～2 个字符等非常短的单词添加"~"（编辑距离 2）时，替换字符数接近单词长度的词也会匹配。例如 ``ab~`` 除了 ``ab`` 和 ``ac`` 之外，还会匹配两个字符都不同的 ``xy``\ 。这会增加意料之外的结果，因此对于短单词，请像 ``ab~1`` 这样指定较小的编辑距离。 + +.. note:: + + 模糊检索的行为可以通过 ``fess_config.properties`` 进行调整。 + + * ``query.fuzzy.prefix_length``\ （默认值：``0``）：从开头起完全匹配的字符数。该值越大，允许出现差异的范围就越窄。 + * ``query.fuzzy.expansions``\ （默认值：``50``）：作为匹配候选展开的单词的最大数量。 + * ``query.fuzzy.transpositions``\ （默认值：``true``）：指定是否将相邻 2 个字符的互换计为 1 次编辑。当为 ``true`` 时采用达梅劳-莱文斯坦距离，当为 ``false`` 时采用经典莱文斯坦距离。 + +.. note:: + + 即使是不添加"~"的普通检索，|Fess| 也会针对长度达到一定长度以上（默认为 4 个字符以上）的检索词，出于提高相关度的目的，自动附加轻微加权的模糊匹配作为辅助（``query.boost.fuzzy.*``）。这主要是用于调整检索结果排序的功能，与通过"~"进行的模糊检索是不同的机制。不过，这种辅助性的匹配也会包含在检索结果中，因此可能会有不包含检索词本身、只包含相差 1 个字符的单词的文档加入结果（包含检索词本身的文档会排在更靠前的位置）。如果想停止这一行为，请将 ``query.boost.fuzzy.min.length`` 设置为负值（例如 ``-1``）。 + +相关主题 +------ + +- :doc:`search-wildcard` - 通配符检索 +- :doc:`search-proximity` - 邻近检索 +- :doc:`special-char` - 特殊字符与转义 diff --git a/zh-cn/15.10/user/search-geo.rst b/zh-cn/15.10/user/search-geo.rst new file mode 100644 index 000000000..1bd64d371 --- /dev/null +++ b/zh-cn/15.10/user/search-geo.rst @@ -0,0 +1,56 @@ +============ +位置信息检索 +============ + +通过在生成索引时为每个文档添加纬度、经度位置信息,可以在检索时以与指定地点之间的距离作为条件对结果进行筛选。 + +概述 +---- + +位置信息检索仅将位于以指定地点(纬度、经度)为中心的半径范围内的文档纳入检索结果。该筛选是作为使用 OpenSearch 的 geo_distance 查询的过滤器(filter)应用的,因此不会影响得分(相关度)。此外,不支持按距离进行排序。 + +用于存储位置信息的字段,必须在 OpenSearch 的映射(mapping)中定义为 ``geo_point`` 类型。默认情况下,\ ``location`` 字段已被定义为 ``geo_point`` 类型。但是,标准功能中并未提供向 ``location`` 字段写入值的处理,因此需要用户通过数据存储爬取的字段映射、脚本,或向搜索引擎注册文档的 API 等方式,自行存储位置信息。 + +使用方法 +-------- + +位置信息检索通过在检索请求中附加以下参数来指定。默认情况下可用于 ``location`` 字段。 + +.. list-table:: + :header-rows: 1 + + * - 参数 + - 说明 + * - ``geo..point`` + - 以 ``纬度,经度`` 的格式指定作为中心的地点的纬度和经度。值为十进制度数(Double 类型),用逗号分隔两个数值。例: ``35.681236,139.767125`` + * - ``geo..distance`` + - 指定与中心地点之间的距离(半径)。例: ``10km`` + +表: 请求参数 + +```` 指定存储位置信息的字段名。只能指定已在 ``query.geo.fields`` 中注册的字段,默认情况下为 ``location``\ 。如需使用其他字段,需先将其映射为 ``geo_point`` 类型,然后在 ``fess_config.properties`` 的 ``query.geo.fields`` 中以逗号分隔追加该字段。 + +例如,如果要检索位于纬度 35.681236、经度 139.767125(东京站附近)半径 10km 以内的文档,请在检索请求中附加以下参数。 + +:: + + geo.location.point=35.681236,139.767125&geo.location.distance=10km + +距离单位 +-------- + +``geo..distance`` 的值会被解释为 OpenSearch 的距离单位。除了 ``km``\ (千米)之外,还可以使用 ``mm``、``cm``、``m``、``in``、``ft``、``yd``、``mi``\ (英里)、``nmi``\ (海里)等单位。如果省略单位仅指定数值,则会被视为以米为单位(例如: ``500`` 表示 500 米)。 + +多重指定 +-------- + +* 如果对同一字段多次指定 ``geo..point``,则会检索位于其中任意一个地点半径范围内的文档(OR 条件)。 +* 如果针对不同字段分别指定位置信息,则只会检索满足所有条件的文档(AND 条件)。 + +.. note:: + + ``geo..point`` 与 ``geo..distance`` 必须同时指定。如果未指定 ``distance``,则该 ``point`` 的条件将被忽略。此外,如果 ``point`` 的值不是 ``纬度,经度`` 的格式(以逗号分隔的两个数值),或无法解析为数值,则会发生错误。 + +.. note:: + + 位置信息搜索是对搜索词的进一步筛选，因此搜索词为空时不会执行搜索，结果为 0 件。位置信息搜索的请求中请指定搜索词。 diff --git a/zh-cn/15.10/user/search-label.rst b/zh-cn/15.10/user/search-label.rst new file mode 100644 index 000000000..3b4ce1bb3 --- /dev/null +++ b/zh-cn/15.10/user/search-label.rst @@ -0,0 +1,29 @@ +=========== +标签指定检索 +=========== + +标签指定检索(分类检索) +======================= + +通过为搜索对象的文档添加用于分类的标签信息,可以在搜索时指定标签进行筛选检索。使用标签后,例如可以按部门、网站、文档类型等限定搜索范围。 + +在管理界面中预先注册标签后,就可以在搜索界面中使用标签进行筛选搜索。可用的标签可以在搜索时从下拉菜单中选择多个,如果选择了多个标签,则会检索出被赋予其中任意一个标签的文档。如果没有注册标签,则不会显示标签下拉框。 + +.. note:: + 由于可以为标签设置权限,因此下拉菜单中只会显示允许检索用户访问的标签。此外,根据虚拟主机或语言区域(语言)的不同,显示的标签也可能会有所变化。因此,即使已注册了标签,对于某些用户来说,该标签也可能不会显示在下拉菜单中。 + +标签是通过 URL 路径的正则表达式来指定要附加标签的对象进行定义的。关于标签的注册方法和设置项,请参考 :doc:`标签管理指南 <../admin/labeltype-guide>` 。 + +使用方法 +------ + +搜索时可以选择标签信息。单击选项按钮,在显示的搜索选项中可以选择标签信息。 + +|image0| + +通过设置标签并创建索引,可以按照设置了标签的文档进行搜索。不指定标签的搜索与通常的全文检索相同。 + +为文档赋予标签是在爬取并创建索引时,通过将文档的 URL 与标签中设置的路径进行比对来完成的。因此,如果新增或更改了标签的定义(目标路径或排除路径),其内容不会自动反映到已经建立索引的文档中。要使更改生效,请重新爬取目标文档,或执行调度器中注册的"Label Updater"作业来更新索引。 + +.. |image0| image:: ../../../resources/images/en/15.10/user/search-label-1.png +.. pdf :width: 300 px diff --git a/zh-cn/15.10/user/search-not.rst b/zh-cn/15.10/user/search-not.rst new file mode 100644 index 000000000..64b812876 --- /dev/null +++ b/zh-cn/15.10/user/search-not.rst @@ -0,0 +1,44 @@ +==================== +NOT 检索（排除检索） +==================== + +当您想搜索不包含某个词的文档时,可以使用 NOT 检索。这种方式也称为排除检索,当您想通过排除特定关键词来减少检索结果中的噪音时非常有用。 + +使用方法 +------ + +NOT 检索在不包含的词前加上 NOT 进行搜索。NOT +必须使用半角大写字母,前后需要空格。 + +例如,如果想搜索包含"搜索词1"但不包含"搜索词2"的文档,输入并搜索如下内容: + +:: + + 搜索词1 NOT 搜索词2 + +.. note:: + + NOT 必须使用半角大写字母书写。如果像 ``not`` 这样使用小写字母书写,则不会被视为运算符,而是作为普通搜索词"not"进行搜索。此外,在想要排除的词前直接加上 ``-``,写成 ``搜索词1 -搜索词2``,也可以表示与 NOT 相同的含义。 + +使用圆括号 ``( )`` 可以将 NOT 检索与其他检索条件组合使用。例如,如果想搜索包含"搜索词1"或"搜索词2"中任意一个,但不包含"搜索词3"的文档,请按如下方式输入: + +:: + + (搜索词1 OR 搜索词2) NOT 搜索词3 + +也可以指定字段进行 NOT 检索。以下示例搜索 title 字段中包含"搜索词1",但 title 字段中不包含"搜索词2"的文档。 + +:: + + title:搜索词1 NOT title:搜索词2 + +.. note:: + + 安装 ``fess-webapp-bangs`` 插件后，``!g`` 这样已定义的 bang 不再是排除检索，而是把搜索发送到其他网站。请参阅 :doc:`search-bangs`。 + +相关主题 +------ + +- :doc:`search-and` - AND 检索 +- :doc:`search-or` - OR 检索 +- :doc:`special-char` - 特殊字符与转义 diff --git a/zh-cn/15.10/user/search-or.rst b/zh-cn/15.10/user/search-or.rst new file mode 100644 index 000000000..71820fc0e --- /dev/null +++ b/zh-cn/15.10/user/search-or.rst @@ -0,0 +1,39 @@ +========================= +OR 检索（包含任一搜索词） +========================= + +当您想搜索包含任一搜索词的文档时,可以使用 OR 检索。在搜索输入字段中输入多个词时,默认为 AND 检索。 + +使用方法 +------ + +使用 OR 检索时,在搜索词之间输入 OR。OR +必须使用半角大写字母,前后需要空格。 + +例如,如果想搜索包含"搜索词1"或"搜索词2"的文档,在搜索表单中输入如下内容: + +:: + + 搜索词1 OR 搜索词2 + +也可以用 OR 连接 3 个以上的搜索词。 + +:: + + 搜索词1 OR 搜索词2 OR 搜索词3 + +.. note:: + + OR 必须使用半角大写字母书写。如果像 ``or`` 这样使用小写字母书写,则不会被视为运算符,而是作为普通搜索词"or"进行搜索。\ ``||`` 也可以表示与 OR 相同的含义。 + +使用圆括号 ``( )`` 可以将 OR 检索与其他检索条件组合使用。例如,如果想搜索包含"搜索词1"或"搜索词2"中任意一个,并且包含"搜索词3"的文档,请按如下方式输入: + +:: + + (搜索词1 OR 搜索词2) 搜索词3 + +也可以指定字段进行 OR 检索。以下示例搜索 title 字段中包含"搜索词1",或者 content 字段中包含"搜索词2"的文档。 + +:: + + title:搜索词1 OR content:搜索词2 diff --git a/zh-cn/15.10/user/search-proximity.rst b/zh-cn/15.10/user/search-proximity.rst new file mode 100644 index 000000000..a09a2c2fd --- /dev/null +++ b/zh-cn/15.10/user/search-proximity.rst @@ -0,0 +1,70 @@ +========== +邻近检索 +========== +邻近检索（单词距离检索） +========================== + +邻近检索是指，即使短语中的单词没有紧挨在一起，只要它们的位置相互靠近，也能检索到相应文档的方法。当要查找的单词之间可能夹有其他词语时，该方法非常有用。 + +使用方法 +---------- + +用双引号将单词括起来，并在右侧引号后面添加"~"和数字。 + +例如，按如下方式输入，可以检索"Fess"与"检索"之间距离在 3 以内的文档。 + +:: + + "Fess 检索"~3 + +数字表示单词之间允许的位置移动次数的最大值（详见下文"距离的计算方式"）。数字越大，允许单词相隔得越远。 + +也可以指定字段进行邻近检索。下面的示例将检索 title 字段。 + +:: + + title:"Fess 检索"~3 + +如果省略数字，仅指定"~"（例如 ``"Fess 检索"~``），则按要求单词相邻的普通短语检索处理。如果指定小数，小数部分将被舍去（``~2.5`` 按 ``~2`` 处理）。 + +也可以与权重（boost）组合使用。下面的示例对邻近检索应用 2 倍权重（请参见 :doc:`search-boost`）。 + +:: + + "Fess 检索"~5^2 + +距离的计算方式 +---------------- + +* 数字表示单词之间允许的位置移动次数的最大值。它以目标字段的分析器生成的词元（token）为单位计数，而不是字符数或以空格分隔的单词数。对于英文文本，大致相当于词语之间夹着的单词数。分析时作为停用词被去除的单词也会被计入。 +* 单词的顺序可以不同，但顺序颠倒时需要更大的数字。例如，包含"quick brown fox"的文档可以匹配 ``"quick fox"~1``，但要匹配 ``"fox quick"``，则需要 ``~3`` 或更大的数字。 + +:: + + "quick fox"~1 + "fox quick"~3 + +中文等 CJK 文本 +----------------- + +对于中文、日语、韩语等 CJK 文本，计算距离的单位因字段而异。 + +* 在 title、content 等通用字段中，距离接近于单词之间的字符数。 +* 在各语言专用字段中，以形态素（词素）为单位计数，被去除的助词等也会被计入。 + +因此，请用空格分隔单词，并将数字指定得宽松一些。 + +:: + + "全文 检索"~5 + "大阪 好吃"~10 + +不含空格的字符串（例如 ``"大阪好吃"~10``）在通用字段中会作为一个连续的字符串进行匹配，因此可能无法按预期作为单词之间的邻近检索工作。请用空格分隔单词。距离无法精确换算为字符数，因此建议先指定较大的数字，再根据检索结果逐步缩小。 + +相关主题 +---------- + +- :doc:`search-fuzzy` - 模糊检索 +- :doc:`search-boost` - 提升检索 +- :doc:`search-field` - 字段指定检索 +- :doc:`special-char` - 特殊字符与转义 diff --git a/zh-cn/15.10/user/search-range.rst b/zh-cn/15.10/user/search-range.rst new file mode 100644 index 000000000..7f4507303 --- /dev/null +++ b/zh-cn/15.10/user/search-range.rst @@ -0,0 +1,73 @@ +============ +范围指定检索 +============ + +当字段中存储了数值、日期时间等可以指定范围的数据时,可以对该字段进行范围指定检索。 + +使用方法 +-------- + +要进行范围指定检索,请在搜索表单中输入“字段名:[值 TO 值]”。范围的分隔符使用半角大写的 ``TO``\ 。 + +例如,要搜索 content_length 字段中处于 1K 字节到 10K 字节范围内的文档时,请在搜索表单中输入如下内容: + +:: + + content_length:[1000 TO 10000] + +方括号 ``[ ]`` 包含范围的端点(即“以上”“以下”),花括号 ``{ }`` 不包含范围的端点(即“大于”“小于”)。两者也可以组合使用。例如 ``content_length:{1000 TO 10000]`` 表示大于 1000 且小于等于 10000 的文档。 + +将一侧指定为 ``*`` 时,表示仅指定上限或下限的开放范围。\ ``content_length:[1000 TO *]`` 表示 1000 以上,\ ``content_length:[* TO 10000]`` 表示 10000 以下。 + +范围指定检索仅对已注册为检索对象的字段有效。默认情况下,可以对 content_length、last_modified、timestamp、click_count、favorite_count 等字段进行范围指定检索。 + +时间范围指定检索 +---------------- + +要进行时间(日期时间)范围指定检索,请在搜索表单中输入“last_modified:[日期时间1 TO 日期时间2]”(日期时间1 < 日期时间2)。另外,即使日期时间1晚于日期时间2,也不会出现错误,只是检索结果为 0 件。 + +日期时间以 ISO 8601 格式指定。格式为 ``YYYY-MM-DDThh:mm:ss.SSSZ``,时间部分可以省略。 + +.. list-table:: + :header-rows: 1 + + * - 指定内容 + - 示例 + * - 仅年月日 + - 2012-12-02 + * - 年月日及时分秒 + - 2012-12-02T10:45:23Z + * - 年月日及时分秒(精确到毫秒) + - 2012-12-02T10:45:23.235Z + +指定日期时间时,可以使用以当前日期时间为基准的日期时间运算。可使用的符号如下所示。 + +.. list-table:: + :header-rows: 1 + + * - 符号 + - 含义 + * - ``now`` + - 当前日期时间 + * - ``y`` / ``M`` / ``w`` / ``d`` / ``h`` / ``m`` / ``s`` + - 年 / 月 / 周 / 日 / 时 / 分 / 秒 + * - ``+`` / ``-`` + - 加法 / 减法 + * - ``/`` + - 舍入(以 ``/`` 后面的单位进行舍入) + +以 now 或日期时间为基准时,可以添加 +、-(加法、减法)或 /(舍入)等符号。但是,如果基准不是 now 而是特定的日期时间,则需要在日期时间和符号之间加入 ``||``\ (例如:``2016-01-01||+1M/d``)。 + +``/`` 是以 ``/`` 后面的单位进行舍入的符号。\ ``now-1d/d`` 表示无论今天几点执行,都是指从本日 00:00 减去 1 天后的前一天 00:00。 + +另外,这些日期时间运算由检索引擎(OpenSearch)一侧进行求值,仅对日期时间类型的字段有效。 + +例如,要搜索 last_modified 字段中在从当前日期时间(假设为 2016 年 2 月 21 日 20 时)起 30 天前到现在之间更新的文档时,请在搜索表单中输入如下内容: + +:: + + last_modified:[now-30d TO now] + +上述内容在当前日期时间为 2016 年 2 月 21 日 20 时(UTC)的情况下,大致相当于 ``[2016-01-22T20:00:00Z TO 2016-02-21T20:00:00Z]`` 的范围。 + + diff --git a/zh-cn/15.10/user/search-sort.rst b/zh-cn/15.10/user/search-sort.rst new file mode 100644 index 000000000..19736c0cb --- /dev/null +++ b/zh-cn/15.10/user/search-sort.rst @@ -0,0 +1,76 @@ +======== +排序检索 +======== + +可以指定搜索日期等字段对搜索结果进行排序。 + +排序对象字段 +--------------- + +默认情况下,可以指定以下字段进行排序。 + +.. list-table:: + :header-rows: 1 + + * - 字段名 + - 说明 + * - created + - 爬取的日期和时间 + * - content_length + - 爬取的文档大小 + * - last_modified + - 爬取的文档的最后修改日期和时间 + * - filename + - 文件名 + * - score + - 评分值 + * - timestamp + - 文档索引的日期和时间 + * - click_count + - 文档的点击次数 + * - favorite_count + - 文档的收藏次数 + +表: 排序对象字段列表 + + +也可以添加自己的字段作为排序对象。添加时,在 ``fess_config.properties`` 的 ``query.additional.sort.fields`` 中,用逗号分隔指定要作为排序对象的字段名(初始值为空)。在此指定的字段将被添加到上述标准字段中,从而可用于排序。另外,作为排序对象的字段必须事先在索引中注册。 + +使用方法 +------ + +搜索时可以选择排序条件。单击选项按钮,在显示的搜索选项对话框中可以选择排序条件。 + +|image0| + +此外,在搜索字段中进行排序时,以"sort:字段名"的格式,用冒号(:)分隔 sort 和字段名,在搜索表单中输入并搜索。 + +以下以 fess 为搜索词,按文档大小升序排序。 + +:: + + fess sort:content_length + +降序排序时,在字段名后添加 ``.desc``\ 。 + +:: + + fess sort:content_length.desc + +字段名后可以指定的是 ``.asc`` (升序)或 ``.desc`` (降序),省略时默认为升序。 + +按多个字段排序时,如下所示以逗号(,)分隔指定。优先采用先指定的字段,该字段值相同的文档将按下一个字段进行排序。 + +:: + + fess sort:content_length.desc,last_modified + +.. note:: + 在搜索词的 ``sort:`` 中指定排序对象字段列表中不存在的字段名,或指定 ``asc``,\ ``desc`` 以外的排序顺序,不会出现错误。 + 此时 ``sort:`` 不会被当作排序条件,而是将整个搜索词中的符号(如 ``:``)当作普通字符重新搜索。 + 结果不会被排序,而且在大多数情况下搜索结果为0件。 + + 在搜索 API 的 ``sort`` 参数中指定相同的值时,会出现错误(400 Bad Request)。 + +.. |image0| image:: ../../../resources/images/en/15.10/user/search-sort-1.png +.. pdf :width: 300 px diff --git a/zh-cn/15.10/user/search-wildcard.rst b/zh-cn/15.10/user/search-wildcard.rst new file mode 100644 index 000000000..17d28bd18 --- /dev/null +++ b/zh-cn/15.10/user/search-wildcard.rst @@ -0,0 +1,53 @@ +============== +通配符检索 +============== + +可以在搜索词中使用单字符或多字符通配符。? 可以指定为单字符通配符,\* 可以指定为多字符通配符。通配符的使用对象是单词。不能对句子进行通配符检索。 + +使用方法 +------ + +使用单字符通配符时,使用 ? ,如下所示。 + +:: + + te?t + +上述情况下,? 所在位置可以匹配任意 1 个字符,如 text、test 等。 + +使用多字符通配符时,使用 \* ,如下所示。 + +:: + + test* + +上述情况下,\* 所在位置可以匹配 0 个以上的任意字符,如 test、tests、tester 等。此外, + +:: + + te*t + +也可以像这样在检索词中间使用。另外, + +:: + + *test + +也可以像这样在检索词开头使用通配符。 + +也可以指定字段进行通配符检索。下面的示例将在 title 字段中搜索包含以 te 开头、以 t 结尾的单词的文档。 + +:: + + title:te*t + +如果不指定字段,将以 title 和 content 字段为对象进行通配符检索。 + +使用条件 +------ + +使用通配符检索时,请注意以下几点。 + +* 通配符针对索引中注册的字符串 (令牌) 进行匹配。由于搜索词不会被重新解析,因此如果使用 bi-gram 等方式创建索引,日语会被当作没有意义的固定长度字符串处理,日语通配符检索将无法达到预期效果。在日语中使用通配符时,请在使用形态素分析的字段中使用。 +* 在搜索词的开头或中间包含通配符 (``*``・``?``) 的模式区分大小写。由于注册到索引中的单词通常会转换为小写,因此请在模式中使用小写字母。例如 ``Te*t``、``Te?t``、``*Test`` 无法匹配已转换为小写注册的 ``test``\ 。另一方面,仅末尾为 ``*`` 的模式 (如 ``Test*``) 属于前缀匹配,搜索词会被转换为小写后再解析,因此 ``Test*`` 也能匹配 ``test``\ 。 +* 在开头添加通配符的检索 (例如 ``*test``) 会扫描索引内的所有单词,因此可能需要较长的处理时间。 diff --git a/zh-cn/15.10/user/special-char.rst b/zh-cn/15.10/user/special-char.rst new file mode 100644 index 000000000..0c9c2eba0 --- /dev/null +++ b/zh-cn/15.10/user/special-char.rst @@ -0,0 +1,89 @@ +====== +特殊字符 +====== + +以下字符在搜索查询语法中具有特殊含义，因此在搜索词中被视为特殊字符。如果要将这些字符作为普通搜索字符使用，需要对其进行转义。 + +:: + + + - && || ! ( ) { } [ ] ^ " ~ * ? : \ / + +这些字符用于调用必需词与排除词（``+`` ``-``）、布尔运算符（``&&`` ``||`` ``!``）、分组（``( )``）、范围搜索（``[ ]`` ``{ }``）、权重搜索（``^``）、短语搜索（``"``）、模糊搜索与邻近搜索（``~``）、通配符搜索（``*`` ``?``）以及字段搜索（``:``）等搜索功能。 + +例如，搜索词中包含 URL 或文件路径里的"/"、":"，或程序代码中的"+"、"-"等符号时，如果直接搜索而不加转义，可能会得到意料之外的搜索结果。转义方法请参见下文。 + +特殊字符一览 +------------ + +.. list-table:: + :header-rows: 1 + + * - 特殊字符 + - 含义 + - 相关页面 + * - ``+`` ``-`` + - 指定必需词与排除词（AND 检索 / NOT 检索） + - :doc:`search-and` / :doc:`search-not` + * - ``&&`` ``||`` + - AND 检索 / OR 检索 + - :doc:`search-and` / :doc:`search-or` + * - ``!`` + - NOT 检索（排除检索） + - :doc:`search-not` + * - ``( )`` + - 对检索条件进行分组 + - :doc:`advanced-search` + * - ``[ ]`` ``{ }`` + - 范围指定检索（``[ ]`` 包含边界值，``{ }`` 不包含边界值） + - :doc:`search-range` + * - ``^`` + - 提升检索（加权检索） + - :doc:`search-boost` + * - ``"`` + - 短语检索（将引号内的内容作为一个整体检索词处理，也可代替转义使用） + - :doc:`advanced-search` + * - ``~`` + - 模糊检索（用于单词后）/ 邻近检索（用于短语后） + - :doc:`search-fuzzy` / :doc:`search-proximity` + * - ``*`` ``?`` + - 通配符检索 + - :doc:`search-wildcard` + * - ``:`` + - 指定检索字段 + - :doc:`search-field` + * - ``\`` + - 转义字符 + - （本页面） + * - ``/`` + - 斜杠（包含在 URL 等中时需要转义） + - :doc:`search-field` + + +使用方法 +------ + +如果要将特殊字符作为普通搜索字符处理，请使用以下任一方法。 + +* 在字符前紧跟加上 ``\`` 进行转义。紧随其后的单个字符将被视为普通字符，而不是查询语法。 +* 用 ``"`` 将搜索词括起来。括起来的字符串将被视为短语搜索，其中的特殊字符不会被解释为查询语法。但需要注意的是，由于会变成短语搜索，因此无法使用通配符搜索（``*`` ``?``）等功能。 + +:: + + aaa\/bbb + "aaa/bbb" + +例如，要将"C++"作为搜索词进行检索时，可以按如下方式转义。 + +:: + + C\+\+ + "C++" + +相关主题 +------------ + +- :doc:`search-field` - 字段指定检索 +- :doc:`search-wildcard` - 通配符检索 +- :doc:`search-fuzzy` - 模糊检索 +- :doc:`search-proximity` - 邻近检索 +- :doc:`advanced-search` - 高级检索