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 :
Vérifiez si Java est installé
$ which java $ java -version
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
Configurez la variable d’environnement JAVA_HOME
$ export JAVA_HOME=/path/to/java $ export PATH=$JAVA_HOME/bin:$PATH
Pour une configuration permanente, ajoutez à
~/.bashrcou/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 :
Vérifiez la version d’OpenSearch
$ /path/to/opensearch/bin/opensearch --version
Adaptez la version du plugin à celle d’OpenSearch
$ /path/to/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.3.2
Vérifiez les permissions
$ sudo /path/to/opensearch/bin/opensearch-plugin install ...
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 :
Vérifiez qu’OpenSearch est démarré
$ curl http://localhost:9200/
Si le démarrage est normal, une réponse JSON est retournée.
Vérifiez les conflits de ports
$ sudo netstat -tuln | grep 8080
Si le port 8080 est déjà utilisé, modifiez le numéro de port dans le fichier de configuration.
Vérifiez les fichiers journaux
$ tail -f /path/to/fess/logs/fess.log
Identifiez la cause à partir des messages d’erreur.
Vérifiez la version de Java
$ java -version
Vérifiez que Java 21 ou ultérieur est installé.
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 :
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
Augmentation de la limite des descripteurs de fichiers
$ sudo vi /etc/security/limits.conf
Ajoutez
opensearch - nofile 65535 opensearch - nproc 4096
Configuration du verrouillage mémoire
$ sudo vi /etc/security/limits.conf
Ajoutez
opensearch - memlock unlimited
Redémarrez OpenSearch
$ sudo systemctl restart opensearch
Conflit de numéros de port
Symptôme :
Address already in use
Solution :
Vérifiez les ports utilisés
$ sudo netstat -tuln | grep 8080 $ sudo lsof -i :8080
Arrêtez le processus utilisé, ou modifiez le numéro de port de Fess
Modifiez le numéro de port dans le fichier de configuration (
system.properties)server.port=9080
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 :
Vérifiez qu’OpenSearch est démarré
$ curl http://localhost:9200/
Vérifiez l’URL de connexion
Vérifiez que l’URL configurée dans
fess.in.shoufess.in.batest correcteSEARCH_ENGINE_HTTP_URL=http://localhost:9200
Vérifiez le pare-feu
$ sudo firewall-cmd --list-all
Vérifiez que le port 9200 est ouvert.
Vérifiez la connexion réseau
Si vous exécutez OpenSearch sur un autre hôte
$ ping opensearch-host $ telnet opensearch-host 9200
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 :
Augmentez la taille du tas
Modifiez
fess.in.shFESS_HEAP_SIZE=4g
Ajustez également la taille du tas d’OpenSearch
export OPENSEARCH_JAVA_OPTS="-Xms4g -Xmx4g"
Optimisation de l’index
Exécutez régulièrement l’optimisation depuis « Système » → « Planificateur » dans l’écran d’administration.
Utilisez un SSD
Si les E/S disque sont le goulot d’étranglement, migrez vers un SSD.
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 :
Ajustez l’intervalle d’exploration
Raccourcissez l”« Intervalle » de la configuration d’exploration dans l’écran d’administration (en millisecondes).
Avertissement
Un intervalle trop court peut surcharger le site cible. Configurez une valeur appropriée.
Augmentez le nombre de threads
Augmentez le nombre de threads d’exploration dans le fichier de configuration
crawler.thread.count=10
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 :
Vérifiez l’index
$ curl http://localhost:9200/_cat/indices?v
Vérifiez que l’index de Fess existe.
Vérifiez les journaux d’exploration
Vérifiez les journaux d’exploration depuis « Système » → « Journal » dans l’écran d’administration pour rechercher les erreurs.
Réexécutez l’exploration
Exécutez « Default Crawler » depuis « Système » → « Planificateur » dans l’écran d’administration.
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 :
Supprimez et recréez l’index
Avertissement
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*
Réexécutez l’exploration
Exécutez « Default Crawler » depuis l’écran d’administration pour recréer l’index.
Problèmes spécifiques à Docker
Le conteneur ne démarre pas
Symptôme :
Le conteneur ne démarre pas avec docker compose up.
Solution :
Vérifiez les journaux
$ docker compose -f compose.yaml -f compose-opensearch3.yaml logs
Vérifiez la mémoire insuffisante
Augmentez la mémoire allouée à Docker (depuis les paramètres de Docker Desktop).
Vérifiez les conflits de ports
$ docker ps
Vérifiez qu’aucun autre conteneur n’utilise les ports 8080 ou 9200.
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 :
Vérifiez l’état du conteneur
$ docker compose -f compose.yaml -f compose-opensearch3.yaml ps
Vérifiez les journaux
$ docker compose -f compose.yaml -f compose-opensearch3.yaml logs fess
Vérifiez la configuration réseau
$ docker network ls $ docker network inspect <network_name>
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 Installation sur Windows (Procédure détaillée).
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
<Logger name="org.codelibs.fess" level="debug"/>
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*
Avertissement
L’exécution de cette commande supprimera toutes les données de configuration.
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 :
Informations de version
$ cat /path/to/fess/VERSION $ /path/to/opensearch/bin/opensearch --version $ java -version
Informations système
$ uname -a $ cat /etc/os-release $ free -h $ df -h
Fichiers journaux
$ tar czf fess-logs.tar.gz /path/to/fess/logs/
Fichiers de configuration (après suppression des informations confidentielles)
$ tar czf fess-config.tar.gz /path/to/fess/app/WEB-INF/conf/
État d’OpenSearch
$ curl http://localhost:9200/_cluster/health?pretty $ curl http://localhost:9200/_cat/indices?v