Deep Dive : Nextcloud sur K3s – des pods PHP, des bases de données sur l’hôte et la bureautique dans le navigateur

🌐 Aussi en: English · Deutsch · Español

Deep Dive de la série autour de l’Ansible Tour. Niveau : administration Linux avancée. Le tour explique les rôles ; les deep dives expliquent la technique en dessous – comment elle fonctionne, pourquoi elle est là, ce que cette installation en fait exactement, comment l’exploiter au quotidien et ce qui aurait existé d’autre.

Deux serveurs Nextcloud tournent sur cette installation, l’un pour une organisation d’environ 150 comptes et près de 400 Go de fichiers, l’autre pour un petit groupe. Tous deux sont construits à partir des mêmes rôles (partie 4 du tour). Cet article explique comment Nextcloud est construit, comment les morceaux sont répartis entre l’hôte et le cluster, et ce que l’exploitation a appris jusqu’ici.

🧭 Comment fonctionne Nextcloud

Une application PHP, de nombreuses entrées

Nextcloud, c’est du PHP. Chaque page du navigateur, chaque requête WebDAV d’un client de synchronisation et chaque appel d’API des applications mobiles est une requête PHP qui passe par nginx vers PHP-FPM. Les fichiers eux-mêmes sont dans un répertoire de données ; la base connaît chaque fichier par la table file cache – nom, taille, ETag, droits – pour que les listages n’aient jamais à toucher le disque.

Verrous et caches

Quand deux clients modifient le même fichier, le verrouillage transactionnel de fichiers décide qui l’emporte. Les verrous doivent être visibles immédiatement par chaque processus PHP, c’est pourquoi ils vivent dans Redis. À côté, APCu met en cache par processus et Redis entre processus.

Tâches de fond

Nettoyage, expiration de la corbeille et des versions, notifications, vérifications de mises à jour des apps, génération anticipée des aperçus – Nextcloud tient une file de tâches dans la base. Quelque chose doit exécuter cron.php régulièrement pour la traiter ; Nextcloud recommande toutes les cinq minutes.

Push, aperçus, bureautique

• notify_push est un petit démon Rust livré dans une app. Les clients gardent un WebSocket ouvert vers lui et apprennent les changements immédiatement, au lieu de demander toutes les 30 secondes.
• Les aperçus sont des vignettes, générées au premier affichage ou à l’avance par l’app Preview Generator, et stockées dans le dossier de données des apps.
• Nextcloud Office, c’est l’app richdocuments plus un serveur Collabora Online. Le navigateur charge l’éditeur depuis Collabora ; Collabora récupère et enregistre le document auprès de Nextcloud par le protocole WOPI, avec un jeton par session.

Apps et occ

Presque tout ce qui dépasse les fichiers est une app – agenda, contacts, Talk, dossiers de groupe. occ est l’outil en ligne de commande de toute l’administration : statut, mises à niveau, mode maintenance, configuration, analyses de fichiers, réparations de la base.

🛡️ Pourquoi il est là

• Fichiers, agendas, contacts et bureautique au même endroit, pour des personnes qui ne devraient pas avoir à savoir ce qu’est WebDAV.
• Les données restent sur les serveurs de l’organisation. Aucun fournisseur ne décide des accès, des prix ou des fonctions.
• Un écosystème. Des apps pour presque tous les besoins, des clients pour toutes les plateformes, une grande communauté.

🔧 Ce que fait ce dépôt

Qu’est-ce qui tourne où

Les composants lourds et précieux – base et données – sont sur l’hôte, avec le bac à sable systemd complet et leurs propres domaines SELinux. Les remplaçables – PHP, Collabora, le démon de push – tournent dans le cluster. Des Services Kubernetes sans sélecteur, pointant vers l’IP du nœud, rendent MariaDB et Redis accessibles aux pods sous les noms mariadb et redis ; nftables n’autorise ces ports que depuis le réseau des pods. Le code PHP (/srv/nextcloud-www) et les données (/data) sont des volumes hostPath avec leurs propres étiquettes SELinux.

Une configuration en couches

Nextcloud lit config.php, puis chaque *.config.php du répertoire de configuration dans l’ordre alphabétique, les fichiers suivants l’emportant. Le dépôt s’en sert : custom.config.php, issu d’une ConfigMap, porte les réglages (caches, aperçus, proxys, journalisation), redis.config.php, issu d’un Secret, le mot de passe de Redis. Tous deux sont montés avec subPath, qui ne se met jamais à jour dans un pod en marche ; une somme de contrôle de tout ce qui est monté est une annotation du pod, si bien qu’un changement le redéploie. Cette somme ne couvrait au départ que les ConfigMaps – un nouveau réglage d’aperçus est resté un jour entier dans la ConfigMap alors que le pod utilisait encore l’ancien fichier. Depuis cette série, elle couvre aussi le Secret, après que le deep dive Redis a montré qu’un mot de passe changé ne serait pas arrivé jusqu’au pod.

Collabora

extra_params: --o:ssl.enable=false --o:ssl.termination=true
              --o:num_prealloc_children=10 --o:per_document.max_concurrency=6

Le TLS se termine à l’ingress, donc Collabora tourne derrière en HTTP simple et en est informé. num_prealloc_children garde autant de processus de documents démarrés à l’avance ; ouvrir un document en prend un, et s’il n’y en a aucun de prêt, l’utilisateur attend qu’un nouveau démarre. Le « échec du chargement, réessayer fonctionne » occasionnel juste après un redémarrage de Collabora, c’est exactement cela. Le plus grand serveur en garde dix prêts, le plus petit six. next_config règle la liste d’autorisation WOPI sur le réseau des pods – seul Collabora peut appeler les points d’accès WOPI – et fait relire à Nextcloud le document de découverte de Collabora après chaque changement de celui-ci.

Un détail d’installation a coûté un après-midi : occ app:install richdocuments tronquait de façon reproductible un fichier de l’app à l’extraction, et le contrôle d’intégrité échouait ensuite. Le rôle télécharge donc lui-même l’archive depuis le magasin d’apps, l’extrait avec tar et vérifie les signatures de l’app avec occ integrity:check-app.

Deux sortes de mises à jour

Un changement de version, c’est un nouveau tag d’image dans versions.yml et un passage du playbook principal ; le point d’entrée du conteneur lance occ upgrade au démarrage. Nextcloud refuse lui-même de sauter une version majeure, un saut de 32 à 34 se fait donc en deux étapes. Les images reconstruites – Docker Hub reconstruit des tags inchangés pour des correctifs de l’image de base, et K3s ne retélécharge jamais de lui-même – sont l’affaire de nextcloud-update.yml. Il refuse de tourner sans --limit (un serveur à la fois), refuse de démarrer sur une instance en mode maintenance ou avec une mise à niveau de base en attente, ne redémarre que les Deployments dont l’image a réellement changé, lance occ upgrade comme filet de sécurité, met à jour les apps, redémarre une seconde fois (OPcache ne vérifie pas les dates, voir le deep dive PHP-FPM) et contrôle le statut. Si quelque chose échoue, un bloc rescue rassemble l’état pour une décision manuelle. Les deux serveurs tournent sous Nextcloud 34.

Isolation

• Une NetworkPolicy ne laisse Collabora parler qu’à Nextcloud et au DNS, et n’accepter de connexions que de Nextcloud et du nœud. Le pod Nextcloud et le démon de push n’en ont pas encore – contrairement au blog, où chaque pod est isolé. Dans un cluster qui ne contient rien d’autre, ce n’est pas une porte ouverte, mais c’est une couche manquante ; trouvé en écrivant cet article et proposé.
• Une politique d’admission n’accepte que des images issues d’une liste de registres autorisés – y compris l’image du solveur ACME de cert-manager, qui tourne dans ce namespace ; sur le blog, son absence a un jour laissé une demande de certificat en attente sans le moindre message d’erreur.
• Aucun jeton de compte de service dans les pods – rien en eux ne parle à l’API Kubernetes.
• ClamAV analyse les fichiers en arrière-plan à 04:30, aperçus et formats médias exclus – avant ce changement, l’analyse était la cause d’un serveur qui apparaissait « occupé » sans raison visible.

📊 Mesuré

Le file cache du plus grand serveur comptait plus de dix fois plus d’entrées après la migration depuis l’ancien serveur : la base restaurée contenait encore tout l’index de fichiers de l’ancien serveur, et occ files:cleanup ne faisait rien tant que la ligne de stockage de l’ancien chemin existait. Un quart du reste appartenait aux restes d’une app bureautique utilisée auparavant. Les deux ont été supprimés – après une sauvegarde et après avoir compté les lignes vivantes, car les données des apps désactivées sont conservées par principe, au cas où quelqu’un voudrait les retrouver.

🧰 Exploitation au quotidien

occ() { k3s kubectl -n nextcloud exec deploy/nextcloud -c nextcloud-fpm -- \
  runuser -u www-data -- php /var/www/html/occ "$@"; }

occ status
occ setupchecks                       # the admin overview, on the command line
occ maintenance:mode --on             # before anything that touches data
occ files:scan --path="/alice/files"  # after files were changed outside Nextcloud
occ db:add-missing-indices
occ background-job:list --limit=20
occ app:list --disabled

Avertissements attendus

• « Erreurs dans le journal » sur le plus petit serveur : une erreur de base à 03:30 – le redémarrage nocturne, pendant lequel un pod de tâches de fond n’a pas pu résoudre mariadb. Inoffensif, mais cela reste dans la vue d’ensemble jusqu’à la rotation du journal.
• « Échec du chargement d’Office, réessayer fonctionne » juste après un redémarrage : Collabora n’avait encore aucun processus prédémarré.
• Les avertissements d’intégrité après une modification manuelle dans le répertoire des apps sont réels : Nextcloud signe son code, et tout fichier modifié se voit. Ne jamais modifier le code d’une app sur place.

Sauvegardes et restauration

Chaque nuit, une machine de sauvegarde récupère par SSH le dump de la base, config.php et le répertoire de données, et les versionne pendant 365 jours. Une restauration est le chemin inverse plus occ maintenance:data-fingerprint, qui signale aux clients de synchronisation que l’état du serveur a changé, pour qu’ils ne suppriment pas ce qu’ils croient nouveau.

🆘 Antisèche : symptôme → commande

La version courte de cet article, pour le moment où quelque chose ne va pas. À lancer sur l’hôte en root ; <…> sont des espaces réservés. occ et wp sont les fonctions shell des deep dives Nextcloud et WordPress.

🔭 La suite

• Nextcloud 35, une fois la première version corrective sortie, d’abord sur le plus petit serveur.
• S3 comme stockage principal rendrait les données indépendantes du disque de l’hôte – pertinent seulement avec plus d’un nœud.
• Le backend haute performance de Talk, si les appels vidéo deviennent un jour plus qu’occasionnels.

⚖️ Alternatives – et pourquoi Nextcloud

Nextcloud n’est pas difficile à installer ; il est exigeant à bien exploiter, parce que c’est une douzaine de services qui font semblant d’en être un seul. Les répartir selon « précieux ou remplaçable » – base et fichiers sur l’hôte, PHP et bureautique dans le cluster – a rendu chaque partie plus simple à comprendre. Les erreurs de cet article se trouvaient presque toutes aux jointures entre elles.