Configuration de base du robot d’indexation

Présentation

Le robot d’indexation (crawler) de Fess est une fonctionnalité qui collecte automatiquement du contenu à partir de sites Web et de systèmes de fichiers, et l’enregistre dans l’index de recherche. Ce guide explique les concepts de base et les méthodes de configuration du robot d’indexation.

Concepts de base du robot d’indexation

Qu’est-ce qu’un robot d’indexation

Un robot d’indexation (Crawler) est un programme qui collecte automatiquement du contenu en suivant des liens à partir d’une URL ou d’un chemin de fichier spécifié.

Le robot d’indexation de Fess présente les caractéristiques suivantes :

Support multi-protocole : HTTP/HTTPS, système de fichiers, SMB, FTP, etc.
Exécution planifiée : Indexation périodique automatique
Indexation incrémentale : Mise à jour uniquement du contenu modifié
Traitement parallèle : Indexation simultanée de plusieurs URLs
Conformité aux règles des robots : Respect du fichier robots.txt

Types de robots d’indexation

Fess propose les types de robots d’indexation suivants selon la cible.

Types de robots d’indexation
Type	Cible	Usage
Robot Web	Sites Web (HTTP/HTTPS)	Sites Web publics, sites Web intranet
Robot de fichiers	Système de fichiers, SMB, FTP	Serveurs de fichiers, dossiers partagés
Robot de base de données	Bases de données	Sources de données RDB, CSV, JSON, etc.

Création de la configuration d’indexation

Ajout d’une configuration d’indexation de base

Accéder à l’interface d’administration

Accédez à http://localhost:8080/admin dans votre navigateur et connectez-vous en tant qu’administrateur.
Ouvrir l’écran de configuration du robot d’indexation

Dans le menu de gauche, sélectionnez « Robot d’exploration » → « Web » ou « Système de fichiers ».
Créer une nouvelle configuration

Cliquez sur le bouton « Nouveau ».
Saisir les informations de base
- Nom : Nom d’identification de la configuration d’indexation (ex : Wiki d’entreprise)
- URL : URL de départ de l’indexation (ex : https://wiki.example.com/)
- Intervalle : Intervalle d’accès par URL en millisecondes (ex : 10000)
- Nombre de threads : Nombre d’indexations parallèles (ex : 5)
- Profondeur : Profondeur des niveaux de liens à suivre (ex : 3)
Enregistrer

Cliquez sur le bouton « Créer » pour enregistrer la configuration.

Exemples de configuration du robot Web

Indexation d’un site intranet d’entreprise

Indexation d’un site Web public

Exemples de configuration du robot de fichiers

Système de fichiers local

SMB/CIFS (Partage de fichiers Windows)

Configuration des informations d’authentification

Pour accéder à des sites ou des serveurs de fichiers nécessitant une authentification, configurez les informations d’authentification.

Dans l’interface d’administration, sélectionnez « Robot d’exploration » → « Authentification Web » (ou « Authentification de fichier » pour les serveurs de fichiers)
Cliquez sur « Nouveau »
Saisissez les informations d’authentification :
```
Nom d'hôte : wiki.example.com
Port : 443
Schéma : Basic
Nom d'utilisateur : crawler_user
Mot de passe : ********
```
Note

Le champ « Schéma » permet de choisir parmi Basic / Digest / NTLM / Form. Vous devez également sélectionner la configuration d’indexation cible dans le champ « Web Config » (ou la configuration de système de fichiers pour l’authentification de fichier). Les informations d’authentification sont associées à une configuration d’indexation.
Cliquez sur « Créer »

Exécution de l’indexation

Exécution manuelle

Pour exécuter immédiatement une indexation configurée, démarrez le travail d’indexation depuis le menu « Planificateur » :

Ouvrez le menu « Planificateur »
Sélectionnez le travail « Default Crawler »
Cliquez sur le bouton « Démarrer maintenant »
Vérifiez l’état d’exécution du travail

Note

Les pages de liste des configurations d’indexation (Web / Système de fichiers) ne comportent pas de bouton « Démarrer » individuel. Les indexations s’exécutent au niveau du travail planificateur. Le travail « Default Crawler » s’exécute sur toutes les configurations d’indexation activées.

Exécution planifiée

Pour exécuter l’indexation périodiquement :

Ouvrez le menu « Planificateur »
Sélectionnez le travail « Default Crawler »

Configurez l’expression de planification (format Cron)

Cliquez sur « Mettre à jour »

Note

Le planificateur de Fess utilise des expressions cron4j à 5 champs (minute heure jour mois jour-de-semaine). Il n’y a pas de champ « secondes » et le caractère ? n’est pas supporté (contrairement à Quartz). Le jour de la semaine est exprimé de 0 (dimanche) à 6 (samedi).

Vérification de l’état de l’indexation

Pour vérifier l’état de l’indexation en cours :

Ouvrez le menu « Scheduler »
Vérifiez les travaux en cours d’exécution
Consultez les détails dans les journaux :
```
tail -f /var/log/fess/fess-crawler.log
```
Note

Le chemin ci-dessus correspond aux installations par paquets RPM/DEB. Pour les déploiements zip/tar.gz, les journaux se trouvent dans le répertoire logs/.

Paramètres de configuration de base

Limitation des cibles d’indexation

Limitation par motif d’URL

Vous pouvez cibler ou exclure des motifs d’URL spécifiques pour l’indexation.

Motifs d’URL à inclure (expression régulière) :

Motifs d’URL à exclure (expression régulière) :

Limitation de profondeur

Limiter la profondeur des niveaux de liens à suivre :

0 : URL de départ uniquement
1 : URL de départ et pages liées à partir de celle-ci
vide (non défini) : Illimitée (suivre tous les liens)

Note

Le champ « Profondeur » de l’interface d’administration n’accepte que des entiers supérieurs ou égaux à 0. Pour une profondeur illimitée, laissez le champ vide (traité en interne comme -1, ce qui signifie illimité).

Nombre maximum d’accès

Limite supérieure du nombre de pages à indexer :

L’indexation s’arrête après 1000 pages. Laisser le champ vide signifie illimité (aucune limite supérieure).

Nombre d’indexations parallèles (nombre de threads)

Spécifie le nombre d’URLs à indexer simultanément.

Nombre de threads recommandé
Environnement	Valeur recommandée	Description
Petits sites (jusqu’à 10 000 pages)	3 à 5	Réduire la charge sur le serveur cible
Sites moyens (10 000 à 100 000 pages)	5 à 10	Configuration équilibrée
Grands sites (plus de 100 000 pages)	10 à 20	Indexation rapide nécessaire
Serveurs de fichiers	3 à 5	Tenir compte de la charge d’E/S des fichiers

Avertissement

L’augmentation excessive du nombre de threads impose une charge excessive sur le serveur cible. Veuillez définir une valeur appropriée.

Note

Le nombre de threads par défaut à la création est de 1 pour le robot Web et de 5 pour le robot de fichiers. L’intervalle entre les requêtes (intervalle) est par défaut de 10000 millisecondes pour le robot Web et de 1000 millisecondes pour le robot de fichiers.

Intervalle d’indexation

Spécifie la fréquence d’exécution de l’indexation.

Configuration de la taille des fichiers

Vous pouvez définir la limite supérieure de la taille des fichiers à indexer.

Limite supérieure de la taille des fichiers à récupérer

Ajoutez ce qui suit aux « Paramètres de configuration » de la configuration du robot d’indexation :

Récupère les fichiers jusqu’à 10 Mo. Par défaut, il n’y a pas de limite.

Note

Lors de l’indexation de fichiers volumineux, ajustez également les paramètres de mémoire. Consultez Configuration de la mémoire pour plus de détails.

Limite supérieure de la taille des fichiers à indexer

Vous pouvez définir la limite supérieure de la taille à indexer pour chaque type de fichier.

Valeurs par défaut :

Fichiers HTML : 2,5 Mo
Autres fichiers : 10 Mo

Fichier de configuration : app/WEB-INF/classes/crawler/contentlength.xml

Configuration par défaut :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE components PUBLIC "-//DBFLUTE//DTD LastaDi 1.0//EN"
        "http://dbflute.org/meta/lastadi10.dtd">
<components namespace="fessCrawler">
        <include path="crawler/container.xml" />

        <component name="contentLengthHelper"
                class="org.codelibs.fess.crawler.helper.ContentLengthHelper" instance="singleton">
                <property name="defaultMaxLength">10485760</property><!-- 10M -->
                <postConstruct name="addMaxLength">
                        <arg>"text/html"</arg>
                        <arg>2621440</arg><!-- 2.5M -->
                </postConstruct>
        </component>
</components>

Exemple de personnalisation (ajout du traitement des fichiers PDF jusqu’à 5 Mo) :

Avertissement

Lors de l’augmentation de la taille des fichiers traités, augmentez également les paramètres de mémoire du robot d’indexation.

Note

Si la taille du document dépasse 50 Mo, vous devez également modifier les paramètres d’OpenSearch. OpenSearch limite par défaut la longueur maximale des champs de chaîne dans le contenu JSON à 50 Mo.

Ajoutez ce qui suit dans opensearch.yml :

L’exemple ci-dessus définit la limite à 100 Mo. Pour plus de détails, consultez la documentation OpenSearch.

Limitation de la longueur des mots

Présentation

Les longues chaînes de caractères alphanumériques uniquement ou les symboles consécutifs entraînent une augmentation de la taille de l’index et une dégradation des performances. Par conséquent, Fess impose par défaut les limites suivantes :

Caractères alphanumériques consécutifs : jusqu’à 20 caractères
Symboles consécutifs : jusqu’à 10 caractères

Méthode de configuration

Modifiez fess_config.properties.

Configuration par défaut :

Exemple : pour assouplir les limites

Note

Si vous devez rechercher de longues chaînes alphanumériques (ex : numéros de série, tokens, etc.), augmentez cette valeur. Cependant, la taille de l’index augmentera.

Configuration du proxy

Présentation

Lors de l’indexation de sites externes depuis un intranet, ils peuvent être bloqués par un pare-feu. Dans ce cas, effectuez l’indexation via un serveur proxy.

Méthode de configuration

Dans la configuration d’indexation de l’interface d’administration, ajoutez ce qui suit aux « Paramètres de configuration ».

Configuration proxy de base :

Proxy nécessitant une authentification :

Exclure des hôtes spécifiques du proxy :

Les hôtes à exclure du proxy ne sont pas configurés dans les paramètres de configuration de l’indexation, mais via les propriétés système JVM. Définissez la variable d’environnement FESS_NON_PROXY_HOSTS dans fess.in.sh (Linux/Mac) ou fess.in.bat (Windows).

Proxy commun à toutes les configurations d’indexation

Si vous souhaitez appliquer un proxy à toutes les configurations d’indexation qui ne définissent pas leur propre client.proxyHost / client.proxyPort, configurez-le dans fess_config.properties :

Cette configuration s’applique à toutes les configurations d’indexation. Si une configuration d’indexation définit client.proxyHost / client.proxyPort, c’est cette valeur qui est prioritaire.

Proxy système global (JVM)

Pour que l’ensemble du trafic HTTP de Fess (robot d’indexation, SSO, LLM, etc.) passe par un proxy, définissez les variables d’environnement dans fess.in.sh (Linux/Mac) ou fess.in.bat (Windows). Ces variables sont converties en propriétés système JVM (-Dhttp.proxyHost, etc.).

Note

FESS_PROXY_HOST / FESS_PROXY_PORT s’appliquent à la fois à HTTP et à HTTPS. Les variables d’environnement shell http_proxy / https_proxy / no_proxy ne sont pas lues par la JVM et n’ont donc aucun effet.

Configuration de robots.txt

Présentation

robots.txt est un fichier qui indique aux robots d’indexation s’ils peuvent ou non indexer. Fess respecte robots.txt par défaut.

Méthode de configuration

Pour ignorer robots.txt, modifiez fess_config.properties.

La valeur par défaut de cette propriété est false : Fess respecte robots.txt. Définissez-la à true pour l’ignorer.

Pour ignorer également les balises meta robots HTML (noindex, nofollow, etc.), utilisez la propriété suivante (valeur par défaut : false) :

Avertissement

Lors de l’indexation de sites externes, respectez robots.txt. L’ignorer peut imposer une charge excessive sur le serveur ou violer les conditions d’utilisation.

Configuration du User-Agent

Vous pouvez modifier le User-Agent du robot d’indexation.

Pour le robot Web

Le robot Web dispose d’un champ dédié « User Agent » dans l’écran de modification de la configuration d’indexation. Saisissez la valeur souhaitée dans ce champ.

Note

Pour les configurations d’indexation Web, spécifier client.userAgent dans les « Paramètres de configuration » sera écrasé par la valeur du champ dédié « User Agent ». Utilisez toujours le champ dédié pour le robot Web.

Pour le robot de fichiers et autres

Pour les robots qui ne disposent pas d’un champ User Agent dédié, ajoutez le paramètre suivant aux « Paramètres de configuration » de la configuration d’indexation :

Configuration de l’encodage

Encodage des données d’indexation

Configurez dans fess_config.properties :

Encodage des noms de fichiers

Encodage des noms de fichiers du système de fichiers :

Dépannage de l’indexation

L’indexation ne démarre pas

Points à vérifier :

Vérifier si le planificateur est activé
- Dans le menu « Scheduler », vérifiez si le travail « Default Crawler » est activé
Vérifier si la configuration d’indexation est activée
- Dans la liste des configurations d’indexation, vérifiez si la configuration cible est activée

Vérifier les journaux

L’indexation s’arrête en cours de route

Causes possibles :

Mémoire insuffisante
- Vérifiez s’il y a des OutOfMemoryError dans fess-crawler.log
- Augmenter la mémoire du robot d’indexation (voir Configuration de la mémoire)
Erreur réseau
- Ajustez les délais d’attente via les « Paramètres de configuration » de la configuration d’indexation :
```
client.connectionTimeout=5000
client.soTimeout=30000
```
  client.connectionTimeout est le délai d’établissement de la connexion et client.soTimeout est le délai de réception des données, tous deux en millisecondes.
Erreur de la cible d’indexation
- Vérifier s’il y a de nombreuses erreurs 404
- Vérifier les détails des erreurs dans les journaux

Une page spécifique n’est pas indexée

Points à vérifier :

Vérifier les motifs d’URL
- Vérifier si elle ne correspond pas aux motifs d’URL exclus
Vérifier robots.txt
- Vérifier /robots.txt du site cible
Vérifier l’authentification
- Pour les pages nécessitant une authentification, vérifier les paramètres d’authentification
Limitation de profondeur
- Vérifier si la hiérarchie des liens dépasse la limite de profondeur
Nombre maximum d’accès
- Vérifier si le nombre maximum d’accès a été atteint

L’indexation est lente

Solutions :

Augmenter le nombre de threads
- Augmenter le nombre d’indexations parallèles (mais attention à la charge sur le serveur cible)
Exclure les URLs inutiles
- Ajouter les images et les fichiers CSS aux motifs d’URL exclus
Ajuster les paramètres de timeout
- Pour les sites à réponse lente, réduire le timeout
Augmenter la mémoire du robot d’indexation
- Voir Configuration de la mémoire

Bonnes pratiques

Recommandations pour la configuration d’indexation

Définir un nombre de threads approprié

Définissez un nombre de threads approprié pour ne pas imposer une charge excessive sur le serveur cible.
Optimisation des motifs d’URL

En excluant les fichiers inutiles (images, CSS, JavaScript, etc.), vous réduisez le temps d’indexation et améliorez la qualité de l’index.
Configuration de la limitation de profondeur

Définissez une profondeur appropriée en fonction de la structure du site. Laissez le champ Profondeur vide (illimitée) uniquement pour indexer l’ensemble du site.
Configuration du nombre maximum d’accès

Définissez une limite supérieure pour éviter d’indexer un nombre inattendu de pages.
Ajustement de l’intervalle d’indexation

Définissez un intervalle approprié en fonction de la fréquence de mise à jour. - Sites fréquemment mis à jour : toutes les 1 heure à quelques heures - Sites rarement mis à jour : tous les 1 jour à 1 semaine

Recommandations pour la configuration de la planification

Exécution nocturne

Exécutez pendant les périodes de faible charge du serveur (ex : 2h du matin).
Éviter les exécutions en double

Configurez pour démarrer l’indexation suivante après la fin de l’indexation précédente.
Notification en cas d’erreur

Configurez une notification par e-mail en cas d’échec de l’indexation.

Informations de référence

Configuration avancée du robot d’indexation - Configuration avancée du robot d’indexation
Configuration des vignettes - Configuration des vignettes
Configuration de la mémoire - Configuration de la mémoire
Configuration des journaux - Configuration des journaux