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.

Avertissement

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.9

• Fess 15.x → Fess 15.9

Important

Fess 14.x est compatible avec la série OpenSearch 2.x, tandis que Fess 15.9 est compatible avec OpenSearch 3.8.0. Les plugins OpenSearch pour Fess doivent correspondre exactement à la version d’OpenSearch ; une mise à niveau depuis la 14.x implique donc obligatoirement une mise à niveau majeure d’OpenSearch également. Voir Étape 4 : Mise à niveau d’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

• Configuration requise - Configuration requise pour Fess 15.9 (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)

   • 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.

   Note

   Les données de journaux tels que les journaux de recherche et les journaux de clics (search_log.ndjson, click_log.ndjson, favorite_log.ndjson, user_info.ndjson) peuvent également être téléchargées depuis la même page. Elles ne sont pas nécessaires si vous ne sauvegardez que la configuration. 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/
   

   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

Avertissement

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 <opensearch_pid>

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

É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.9.0/fess-15.9.0.zip
   $ unzip fess-15.9.0.zip
   

   Note

   La version archive de Fess n’est distribuée qu’au format ZIP (fess-15.9.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.9.0/app/WEB-INF/conf/
   $ cp /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.9.0/app/WEB-INF/classes/
   $ cp /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.9.0/bin/
   

   Avertissement

   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.9 : 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.9.0 et ne reportez que les valeurs que vous avez modifiées vous-même. Voir Fichiers de configuration repris de la 15.8 pour les éléments à vérifier.

3. Si vous avez des personnalisations, copiez également ce qui suit

   # Configuration des journaux
   $ cp /path/to/old-fess/app/WEB-INF/classes/log4j2.xml /path/to/fess-15.9.0/app/WEB-INF/classes/
   # Plugins installés
   $ cp -r /path/to/old-fess/app/WEB-INF/plugin/. /path/to/fess-15.9.0/app/WEB-INF/plugin/
   # Thème
   $ cp -r /path/to/old-fess/app/themes/. /path/to/fess-15.9.0/app/themes/
   

   Avertissement

   Ne copiez pas tel quel les JSP (app/WEB-INF/view/) modifiés depuis l’écran d’administration « Design ». Si la structure des JSP de la nouvelle version a changé, l’affichage risque d’être incorrect. Réappliquez vos modifications sur les JSP de la nouvelle version.

   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.9.0 pour remplacer chacun d’eux par la version construite pour la 15.9 ; voir Mise à jour de la version des plugins.

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.9.0.rpm

# DEB
$ sudo dpkg -i fess-15.9.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.9, comme un fichier copié dans la procédure ZIP ; voir Fichiers de configuration repris de la 15.8.

Avertissement

Dans la version DEB, /etc/fess/* n’est pas enregistré en tant que conffile (les seuls conffiles sont /etc/default/fess, /etc/init.d/fess et /usr/lib/systemd/system/fess.service). Par conséquent, l’exécution de dpkg -i écrase des fichiers tels que /etc/fess/fess_config.properties avec ceux de la nouvelle version. Cela se fait sans confirmation et sans conserver de copie des anciens fichiers : sauvegardez-les donc au préalable (étape 1). Après la mise à niveau, réappliquez vos modifications aux nouveaux fichiers plutôt que de restaurer les anciens fichiers en entier (voir Fichiers de configuration repris de la 15.8). 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.9.0/compose/compose.yaml
   $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.9.0/compose/compose-opensearch3.yaml
   

2. Récupérez la nouvelle image

   $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull
   

Étape 4 : Mise à niveau d’OpenSearch

Fess 15.9 est compatible avec OpenSearch 3.8.0. Si l’OpenSearch auquel vous vous connectez est antérieur à cette version, effectuez la mise à niveau en suivant la procédure ci-dessous.

Note

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.9 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 Recherche sémantique (chunking de contenu + recherche vectorielle).

Avertissement

Procédez avec précaution lors d’une mise à niveau majeure d’OpenSearch. Des problèmes de compatibilité d’index peuvent survenir. Fess 14.x utilise la série OpenSearch 2.x ; une mise à niveau depuis la 14.x correspond donc toujours à ce cas de figure.

1. Installez la nouvelle version d’OpenSearch

2. Réinstallez les plugins

   $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.8.0
   $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.8.0
   $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-minhash:3.8.0
   $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-configsync:3.8.0
   

   Note

   La version de ces plugins doit correspondre à la version d’OpenSearch utilisée. Fess 15.9 est compatible avec OpenSearch 3.8.0. Si les versions ne correspondent pas, l’installation du plugin échouera.

3. Démarrez OpenSearch

   $ sudo systemctl start opensearch.service
   

Étape 5 : Démarrage de la nouvelle version

Version ZIP

$ cd /path/to/fess-15.9.0
$ ./bin/fess -d -p /path/to/fess-15.9.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.9.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 Migration depuis la version 15.7 ou antérieure (Recherche sémantique (chunking de contenu + recherche vectorielle)) pour plus de détails.

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

Avertissement

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.9

Si vous effectuez une mise à niveau depuis la 15.8, les changements suivants ne sont pas rétrocompatibles.

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.9 : 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.9 (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 Installation sur Linux (Procédure détaillée) ou Installation sur Windows (Procédure détaillée).

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.

Avertissement

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.

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.

Rien à faire si vous n’utilisez pas le robot 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.9 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.

Rien à faire si vous n’utilisez pas le SSO, c’est-à-dire si sso.type vaut none ou n’est pas défini.

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.9, 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.9 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.9 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.<nom du champ>). 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 Aperçu des connecteurs DataStore.

• 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 Fichiers de configuration repris de la 15.8). 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 La tâche Index Exporter désigne un paquet supprimé. 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.

La tâche Index Exporter désigne un paquet supprimé

La 15.9 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.9 :

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 Fonction d’exportation d’index pour d’autres exemples de requêtes.

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.9 est placé à côté sous le nom fess_config.properties.rpmnew). Dans les deux cas, la 15.9 fonctionne ensuite avec les valeurs de la 15.8, y compris celles dont la valeur fournie a changé en 15.9. Vérifiez au moins les clés suivantes.

Clé	15.8.0	15.9	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.9.
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 Les délais d’attente SMB utilisent les noms de propriétés de jcifs 3.
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.

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.9. Il laisse SEARCH_ENGINE_HTTP_URL non défini, sauf si vous l’avez défini vous-même, alors que la 15.9 définit http://localhost:9200, et il ne recherche pas le Node.js installé par bin/fess-setup install nodejs : le robot Playwright ne trouve 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.9 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.9.0/app/WEB-INF/classes/fess_config.properties
$ diff /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.9.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. Une mise à niveau DEB écrase au contraire /etc/fess/fess_config.properties (voir l’étape 3) : elle part donc des valeurs de la 15.9 et seules vos propres modifications sont à réappliquer.

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.9 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 Configuration du mode de recherche IA.

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 Guide de développement des thèmes).

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é.

Migrations spécifiques à la 15.9

Si vous effectuez une mise à niveau depuis la version 15.7 ou antérieure vers la 15.9, 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.9. 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 Migration depuis la version 15.7 ou antérieure (Recherche sémantique (chunking de contenu + recherche vectorielle)).

Si vous utilisiez le mode de recherche IA (chat RAG)

À partir de la 15.9, 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.

Si vous utilisiez SPNEGO (authentification intégrée Windows)

À partir de la 15.9, 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 Configuration SSO avec Auth Intégrée Windows.

Par ailleurs, en 15.9, 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 Configuration SSO avec Auth Intégrée Windows.

Avertissement

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.9 ne la durcit pas : elle conserve silencieusement le comportement permissif, et la 15.9 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.

Si vous utilisiez l’authentification SAML (SSO)

À partir de la 15.9, 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.9, la connexion échoue une seule fois au lieu de boucler. Pour plus de détails, consultez Configuration SSO avec authentification SAML.

Si vous utilisiez Microsoft Entra ID (Azure AD)

À partir de la 15.9, 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.9, 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 Configuration SSO avec Entra ID.

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.

Avertissement

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.9, 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.

DN de l’entrée du groupe	Nom de permission jusqu’à 15.7	Nom de permission en 15.9
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.9, 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.9, 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.

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.<clé>, 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.

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.

$ 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.9, 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.9.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 fess-<old-version>.rpm

Ou

$ sudo dpkg -i fess-<old-version>.deb

Étape 3 : Restauration des données

Restauration depuis le snapshot

$ curl -X POST "http://localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true"

Ou restauration du répertoire depuis la sauvegarde

$ sudo systemctl stop opensearch
$ sudo rm -rf /var/lib/opensearch/data/*
$ sudo tar xzf /backup/opensearch-data-backup.tar.gz -C /
$ sudo systemctl start opensearch

Pour la version Docker, revenez au fichier Compose de l’ancienne version, puis restaurez le contenu du volume

$ docker compose -f compose.yaml -f compose-opensearch3.yaml down
$ PROJECT=$(basename "$(pwd)")
$ docker run --rm -v ${PROJECT}_search01_data:/data -v $(pwd):/backup ubuntu \
    sh -c "rm -rf /data/* && tar xzf /backup/search01-data-backup.tar.gz -C /"
$ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d

Note

Les données de configuration téléchargées depuis l’écran d’administration 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.

Avertissement

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.9 est compatible avec OpenSearch 3.8.0. Les plugins OpenSearch pour Fess tels que opensearch-analysis-fess doivent correspondre exactement à la version d’OpenSearch ; si vous mettez à niveau OpenSearch, mettez également à jour les plugins vers la version correspondante (3.8.0).

Notez par ailleurs que Fess 15.9 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.9) 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 Migration depuis la version 15.7 ou antérieure (Recherche sémantique (chunking de contenu + recherche vectorielle)) 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.

Avertissement

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 :

• Démarrage, arrêt et configuration initiale - Vérification du démarrage et de la configuration initiale

• Configuration de la sécurité - Révision de la configuration de sécurité

• Recherche sémantique (chunking de contenu + recherche vectorielle) - 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