Résoudre le problème de blocage du mode maintenance de Nextcloud avec OCC

Vous avez terminé une mise à jour de Nextcloud, mais la page de maintenance reste visible pour tous. Il se peut aussi qu'une mise à niveau ait été interrompue et que le site ne soit jamais revenu en ligne. La commande OCC permettant de désactiver le mode maintenance est courte, mais l'exécuter avant de vérifier l'état de la mise à niveau peut révéler une installation inachevée. Commencez par identifier l'instance Nextcloud que vous administrez et vérifiez si une mise à niveau de la base de données est toujours nécessaire.

Exemple illustratif : Imaginez un petit bureau utilisant Nextcloud sur Ubuntu. Une mise à jour planifiée a été interrompue après le déploiement de nouveaux fichiers de code, et la page web indique toujours que le serveur est en maintenance. Cet exemple est hypothétique ; il sert à illustrer les vérifications décrites ci-dessous, et non à rapporter un incident ou un test réel.

Que signifie le mode maintenance ?

Le mode maintenance de Nextcloud bloque l'accès utilisateur pendant qu'un administrateur effectue des opérations telles qu'une mise à jour ou une sauvegarde. Cet état affecte l'ensemble du serveur ; les utilisateurs peuvent donc voir une notification de maintenance même lorsque le serveur web est en cours d'exécution. Le manuel d'administration actuel de Nextcloud décrit la commande OCC permettant d'activer ou de désactiver ce mode et précise qu'il peut être nécessaire d'actualiser le navigateur après sa désactivation.

Dans le cas présent, la page de maintenance ne suffit pas à indiquer à l'administrateur si la mise à niveau est terminée. Il est nécessaire d'interroger Nextcloud directement avant de modifier le mode.

Étape 1 : Confirmez le type d’installation et le chemin OCC

Les exemples de commandes présentés ici concernent une installation Nextcloud classique basée sur une archive sous Ubuntu, avec le code source dans le répertoire d'installation /var/www/nextcloudet le compte serveur web nommé « npmwww-data ». Nextcloud indique que ce fichier occse trouve dans le répertoire d'installation et doit être exécuté en tant qu'utilisateur HTTP ; sous Debian et Ubuntu, cet utilisateur est généralement « npm » www-data.

Pour cette configuration standard, saisissez le répertoire d'installation :

cd /var/www/nextcloud

Si vos fichiers Nextcloud se trouvent ailleurs, utilisez leur emplacement exact. Snap, Docker, les appliances et l'hébergement géré utilisent des interfaces de commande ou des structures de fichiers différentes. N'exécutez pas la commande `host` sur une installation conteneurisée et ne présumez pas que le chemin d'accès aux archives s'applique à ces déploiements. Suivez les instructions de mise à jour correspondant à votre méthode d'installation, telles que décrites dans le guide de mise à niveau officiel de Nextcloud .

Dans l'exemple du bureau, l'administrateur vérifie les notes de déploiement et confirme qu'il s'agit d'une installation d'archive avant d'exécuter OCC.

Étape 2 : Vérifiez l’état de Nextcloud avant de désactiver la maintenance.

Exécutez OCC en tant que compte serveur web afin que les fichiers et la configuration conservent leur propriétaire habituel :

sudo -E -u www-data php occ status

Examinez les champs «maintenance and » needsDbUpgrade. Les versions actuelles prennent également en charge un code de sortie d'état :

sudo -E -u www-data php occ status -e
echo $?

Les codes de sortie documentés sont utiles lors de la vérification des résultats par un script : 0indique un fonctionnement normal, 1signifie que le mode maintenance est activé et 2signifie qu'une opération occ upgradeest requise. Il convient également d'examiner le simple message d'état ; ne vous fiez pas uniquement au code de sortie pour décider de la réouverture du site.

Pour le serveur de bureau hypothétique, si needsDbUpgradela condition est vraie ou si status -ela valeur est renvoyée 2, la prochaine étape appropriée consiste à effectuer la mise à niveau, et non pas simplement à désactiver le mode maintenance.

Étape 3 : Terminer d’abord une mise à niveau incomplète

Si une mise à jour du code Nextcloud a été déployée intentionnellement et qu'OCC signale qu'une mise à jour de la base de données est nécessaire, effectuez ou vérifiez une sauvegarde récente de la base de données, de la configuration et des données avant de poursuivre. Exécutez ensuite la commande documentée depuis le répertoire d'installation :

sudo -E -u www-data php occ upgrade

Lisez le résultat de la commande et attendez la fin du processus. Ne l'interrompez pas, car la page web reste inchangée pendant les migrations. Le programme de mise à jour intégré peut laisser le mode maintenance activé en cas occ upgraded'échec du remplacement du code. Si le programme de mise à jour n'a pas terminé le remplacement du code, consultez son journal et reprenez le processus de mise à jour approprié à votre installation au lieu de passer directement à la suite . Les instructions du programme de mise à jour intégrémaintenance:mode --off de Nextcloud expliquent les différentes phases de la mise à jour et indiquent que le journal de mise à jour est une ressource de diagnostic.

Dans cet exemple, l'administrateur système n'exécuterait la commande que occ upgradesi l'état indiquait que la migration de la base de données était toujours en cours et que le nouveau code attendu était en place. Si la commande signalait une erreur, le serveur serait mis hors service afin d'analyser l'erreur.

Étape 4 : Désactivez le mode maintenance avec l’OCC

Une fois la mise à niveau terminée et l'état n'indiquant plus qu'une mise à niveau de la base de données est requise, désactivez le mode maintenance à l'aide de la commande intégrée de Nextcloud :

sudo -E -u www-data php occ maintenance:mode --off

Une commande réussie indique que le mode maintenance a été désactivé. Il s'agit de la méthode recommandée pour modifier le mode dans une installation standard ; elle permet également de conserver la modification d'état au sein de l'interface de commande de Nextcloud, sans avoir à modifier manuellement le fichier de configuration config.php.

L'administrateur du bureau, dans cet exemple, n'exécute désormais cette commande qu'une fois la migration terminée. Si aucune mise à niveau n'était en cours et que l'état indiquait que l'installation était prête, cette même commande permet de désactiver un indicateur de maintenance resté actif après une maintenance planifiée.

Étape 5 : Vérifier l’état et l’interface web

Vérifiez à nouveau le statut :

sudo -E -u www-data php occ status
sudo -E -u www-data php occ status -e

Pour une installation réussie, attendez-vous à un message d'erreur maintenance: falseet needsDbUpgrade: falseà un code de sortie normal 0. Ouvrez ensuite le site depuis une nouvelle fenêtre de navigation privée et connectez-vous avec un compte administrateur. Demandez à un utilisateur lambda d'actualiser son navigateur avant de conclure que sa session est toujours bloquée.

Dans ce scénario, la réussite signifie que l'état du centre de contrôle opérationnel (OCC) et la page web confirment que l'instance est de nouveau en ligne. Cet exemple hypothétique ne présuppose pas l'exécution d'une commande ni la réparation d'un serveur réel.

Si la page de maintenance reste

OCC affirme que la maintenance est fausse

Vérifiez que vous avez exécuté OCC sur la même installation qui héberge l'URL. Ceci est important dans le cas d'un déploiement à charge équilibrée, d'un hôte Docker avec plusieurs conteneurs ou d'un serveur hébergeant des répertoires Nextcloud anciens et nouveaux côte à côte. Vérifiez le chemin racine du document ou du conteneur et interrogez l'instance associée à l'URL concernée. Si chaque nœud web possède sa propre configuration, assurez-vous que tous les nœuds partagent la configuration et la base de données prévues.

Si l'instance appropriée signale une maintenance désactivée, comparez la page provenant de l'origine du serveur avec l'URL publique. Un proxy inverse ou un cache peut renvoyer une réponse obsolète. Ne videz ou ne contournez ce cache qu'après avoir vérifié quelle couche a renvoyé la page de maintenance.

OCC ne peut pas s'exécuter ou renvoie une erreur PHP

Vérifiez que la commande utilise la version PHP CLI et les extensions requises compatibles avec l'installation web. Nextcloud indique qu'APCu est désactivé par défaut pour PHP CLI et peut provoquer des erreurs OCC lorsqu'il est configuré comme cache local. Sa documentation explique comment l'activer apc.enable_clidans la configuration PHP CLI ou l'ajouter --define apc.enable_cli=1à la commande PHP, le cas échéant.

sudo -E -u www-data php --define apc.enable_cli=1 occ status

N'utilisez cette solution que si l'erreur indique un problème avec l'interface de ligne de commande APCu ; elle ne résout pas tous les problèmes PHP. Vérifiez également que la commande est exécutée avec le compte utilisateur web approprié et depuis le répertoire d'installation correct.

La mise à jour de la base de données est toujours nécessaire

Ne désactivez pas l'indicateur de maintenance pour masquer cet état. Vérifiez à nouveau les résultats et les journaux de la mise à jour, assurez-vous que la version correcte de Nextcloud est installée et suivez la procédure de mise à niveau recommandée pour votre type d'installation. Consultez la documentation officielle du système OCC et des commandes de maintenancemaintenance:mode , statusainsi que la procédure de mise à niveau en ligne de commande.

Maintenir la fenêtre de maintenance sous contrôle

La désactivation du mode maintenance permet aux utilisateurs de reprendre l'accès à l'instance. Assurez-vous donc que la mise à niveau de la base de données et tout remplacement de code nécessaire sont terminés au préalable. Évitez de supprimer manuellement les fichiers de mise à jour ou de modifier le paramètre de maintenance dans le fichier de configuration dans un premier temps ; cela pourrait masquer le problème sans résoudre la cause de l'activation du mode maintenance.

Dans un environnement de bureau hypothétique, la solution la plus sûre est simple : vérifier l’installation, contrôler l’état du système, effectuer les mises à jour nécessaires, puis exécuter maintenance:mode --offet vérifier OCC et le navigateur. Si la mise à jour échoue, laissez le mode maintenance activé et consultez le journal des mises à jour ou la procédure de récupération spécifique à votre installation.