Des fichiers existent sur le stockage, mais ils n’apparaissent pas dans l’interface ? En 2026, la commande Nextcloud files:scan peut réindexer un utilisateur ou un chemin dans le cache des fichiers. Elle ne doit pourtant pas devenir une réponse automatique à chaque document absent.
Un scan global peut solliciter longtemps le stockage et la base sans réparer la cause réelle. Ce tutoriel explique ce que la commande modifie, quand l’utiliser, comment commencer par un périmètre ciblé et quelles limites connaître avant de lancer --all.
Que fait réellement la commande Nextcloud files:scan ?
Nextcloud ne relit pas toute l’arborescence physique à chaque ouverture de dossier. Il conserve dans sa base un cache des fichiers avec les chemins, tailles, dates, types et autres métadonnées nécessaires à l’interface et aux applications. Les opérations effectuées normalement depuis le web, un client de synchronisation ou WebDAV actualisent ce cache pendant leur traitement.
La commande occ files:scan parcourt un espace de stockage et rapproche son contenu du cache. Elle peut ajouter des entrées pour des fichiers détectés, actualiser des métadonnées et signaler des éléments retirés. Le manuel officiel des commandes de fichiers affiche ensuite un récapitulatif avec le nombre de dossiers, fichiers, éléments nouveaux, actualisés, supprimés et erreurs.
| Situation | Ce que files:scan peut faire | Ce qu’il ne remplace pas |
|---|---|---|
| Fichier présent mais absent du cache | Réindexer le chemin concerné | Corriger une permission système incorrecte |
| Stockage externe modifié hors Nextcloud | Détecter des changements accessibles | Rétablir un montage indisponible |
| Base restaurée avec des données cohérentes | Vérifier un périmètre si la procédure le demande | Recréer les comptes, partages ou métadonnées perdus |
| Fichier physique manquant | Constater son absence | Restaurer son contenu |
Pour replacer le cache, Files et la base dans l’architecture générale, consultez le guide complet de Nextcloud.
Quand faut-il lancer un scan, et quand faut-il l’éviter ?
Un scan est pertinent lorsqu’un administrateur sait que le stockage contient des éléments que le cache ne connaît pas. Cela peut arriver après un import contrôlé, une intervention documentée sur un stockage externe ou une récupération qui laisse un écart vérifié entre le disque et l’interface. Le guide du stockage SMB dans Nextcloud détaille aussi le rôle de cron et des notifications lorsque des fichiers changent directement sur un NAS.
En revanche, n’utilisez pas files:scan --all comme première réponse à une erreur 500, une synchronisation bloquée ou un montage hors ligne. Vérifiez d’abord si le fichier existe réellement, si le stockage est monté, si le serveur web peut le lire et si le journal Nextcloud indique une erreur précise. Une analyse ne corrige ni un certificat expiré, ni une clé S3 invalide, ni un disque plein.
Après une migration complète, la base et les données doivent être transférées dans un état cohérent. Le guide pour migrer Nextcloud vers un nouveau serveur déconseille donc un scan global par réflexe lorsque le cache a déjà été restauré avec la base. Une commande massive peut masquer le défaut de la procédure au lieu de l’expliquer.
Ne modifiez pas le dossier data comme un partage réseau
Le répertoire de données local n’est pas une arborescence à alimenter librement par SMB ou SFTP. Passez par Nextcloud ou par une méthode d’import prévue, puis utilisez un scan seulement dans un scénario administré et sauvegardé.
Comment lancer d’abord une analyse ciblée ?
Exécutez occ depuis le répertoire de Nextcloud avec le compte du serveur web. L’exemple suivant utilise www-data, courant sur Debian et Ubuntu. Le chemin, le compte et la commande PHP peuvent différer sur un conteneur, un NAS ou une offre gérée.
cd /var/www/nextcloud
sudo -E -u www-data php occ files:scan --help
Commencez par un seul identifiant utilisateur, pas par son nom affiché :
sudo -E -u www-data php occ files:scan alice
Pour limiter l’analyse à un dossier, la documentation demande un chemin qui commence par l’identifiant, puis files :
sudo -E -u www-data php occ files:scan \
--path="/alice/files/Clients/2026"
Vérifiez les guillemets si le chemin contient des espaces. Contrôlez aussi la casse et l’identifiant exact du compte. Un chemin mal formé peut ne rien analyser alors que la commande se lance correctement.
Quelles options utiliser avant un scan global ?
La sortie de files:scan --help reste la référence de la version installée. Plusieurs options permettent de réduire la charge ou de répondre à un cas précis.
| Option | Usage | Précaution |
|---|---|---|
--path | Scanner un dossier précis d’un utilisateur | Respecter la forme /utilisateur/files/chemin |
--unscanned | Traiter les fichiers encore non analysés | Ne corrige pas toutes les incohérences existantes |
--shallow | Examiner seulement le premier niveau | Les sous-dossiers ne sont pas parcourus |
--home-only | Limiter l’analyse au stockage principal des comptes | Les montages externes sont exclus |
--all | Scanner tous les utilisateurs | À réserver à un besoin démontré et à une fenêtre surveillée |
Sur une instance volumineuse, testez d’abord un dossier représentatif. Notez la durée, la charge de la base, les entrées et sorties du stockage, puis estimez le temps du périmètre suivant. Évitez de lancer plusieurs analyses qui se chevauchent. Gardez assez d’espace libre pour les journaux, les fichiers temporaires et les opérations normales des utilisateurs.
La commande files:scan-app-data concerne le dossier appdata utilisé par certaines applications. Elle ne remplace pas le scan des fichiers utilisateurs. De la même façon, files:cleanup et files:repair-tree répondent à d’autres problèmes. Ne les enchaînez pas sans diagnostic, sauvegarde et documentation correspondant à votre version.
Comment lire le résultat et vérifier l’interface ?
À la fin, Nextcloud affiche un tableau de compteurs. Un nombre de fichiers nouveaux confirme que le scan a ajouté des entrées au cache. Des éléments actualisés indiquent que des métadonnées ont changé. Une ligne d’erreurs impose de lire le message complet et les journaux avant de relancer la même commande.
Effectuez ensuite une recette simple : ouvrez le dossier avec le compte concerné, téléchargez un fichier détecté, vérifiez sa taille et sa date, puis contrôlez un partage existant. Si un client de bureau utilise ce compte, laissez-le terminer sa synchronisation avant de conclure. N’effacez pas une copie de sécurité parce que l’élément est simplement visible dans l’interface.
Un scan ne recrée pas les anciennes versions, la corbeille, les partages ou les clés de chiffrement à partir du seul contenu physique. Ces informations dépendent aussi de la base et de la configuration. La méthode de sauvegarde Nextcloud explique pourquoi une restauration doit réunir données, base et configuration dans un état compatible.
Pourquoi files:scan échoue ou ne retrouve rien ?
Commencez par le message exact. Une erreur de permission signifie souvent que le compte HTTP ne peut pas traverser un dossier ou lire un fichier. Un chemin vide peut venir d’un mauvais identifiant, d’une casse différente ou d’un stockage non monté. Une interruption peut révéler un manque de mémoire, une session distante coupée ou une dépendance de stockage instable.
Avec un stockage externe, vérifiez l’endpoint, le certificat, les identifiants et l’état du montage avant de scanner. Avec un stockage objet primaire, les noms et l’arborescence résident dans la base. Le guide du stockage S3 avec Nextcloud rappelle qu’un bucket seul ne permet pas de reconstruire l’interface visible. files:scan n’est donc pas une méthode de reprise après perte de la base.
Si le scan s’arrête, réduisez le périmètre jusqu’au dossier fautif. Consignez le premier chemin en erreur, contrôlez son propriétaire, ses droits et son accessibilité depuis le serveur Nextcloud. Relancez uniquement ce sous-ensemble après correction. Cette méthode produit une preuve exploitable, contrairement à plusieurs scans globaux successifs.
Conclusion : scanner le plus petit périmètre utile
files:scan sert à rapprocher un stockage accessible du cache de fichiers Nextcloud. La bonne méthode consiste à confirmer l’écart, lire l’aide de la version installée, cibler un utilisateur ou un chemin, puis contrôler les compteurs et l’interface. Réservez --all aux situations documentées et surveillées. La commande ne remplace ni une restauration cohérente, ni des permissions correctes, ni la base associée à un stockage objet primaire.