Deep Dive: Nextcloud su K3s – pod PHP, database sull'host e office nel browser

Nextcloud è una grande applicazione PHP con job in background, notifiche push, anteprime, una suite office e decine di app. Come si incastrano le sue parti qui su due server, cosa le tiene veloci, quali avvisi sono previsti – e gli errori che hanno insegnato di più.

Illustrazione per la serie Deep Dive

🌐 Anche in: English · Deutsch · Français · Español · Português · Nederlands · Polski

Deep Dive della serie attorno all’Ansible Tour. Il tour spiega i ruoli, i deep dive la tecnologia sottostante: come funziona, perché qui è usata così e cosa è andato storto strada facendo.

Su questo setup girano due server Nextcloud, uno per un’organizzazione con circa 150 account e quasi 400 GB di file, uno per un piccolo gruppo. Entrambi sono costruiti dagli stessi ruoli (parte 4 del tour). Questo post spiega com’è fatto Nextcloud, come i pezzi sono distribuiti tra host e cluster e cosa ha insegnato finora gestirlo.

Indice

🧭 Come funziona Nextcloud

Un’applicazione PHP, molti punti d’ingresso

Nextcloud è PHP. Ogni pagina del browser, ogni richiesta WebDAV di un client di sincronizzazione e ogni chiamata API delle app mobili è una richiesta PHP che passa da nginx a PHP-FPM. I file stanno in una directory dei dati; il database conosce ogni file tramite la tabella della file cache – nome, dimensione, ETag, permessi – così gli elenchi non devono mai toccare il disco.

Locking e caching

Quando due client modificano lo stesso file, il transactional file locking decide chi vince. I lock devono essere visibili a tutti i processi PHP contemporaneamente, ed è per questo che vivono in Redis. Accanto, APCu fa cache per processo e Redis fa cache tra processi.

Job in background

Pulizia, scadenza di cestino e versioni, notifiche, controlli degli aggiornamenti delle app, pre-generazione delle anteprime – Nextcloud tiene una coda di job nel database. Qualcosa deve eseguire regolarmente cron.php per smaltirla; Nextcloud consiglia ogni cinque minuti.

Push, anteprime, office

  • notify_push è un piccolo demone Rust distribuito dentro un’app. I client tengono aperto verso di lui un WebSocket e vengono a sapere subito dei cambiamenti invece di chiedere ogni 30 secondi.
  • Le anteprime sono miniature, generate alla prima visualizzazione o in anticipo dall’app Preview Generator, e salvate nella cartella dati delle app.
  • Nextcloud Office è l’app richdocuments più un server Collabora Online. Il browser carica l’editor da Collabora; Collabora scarica e salva il documento da Nextcloud tramite il protocollo WOPI, con un token per sessione.

App e occ

Quasi tutto ciò che va oltre i file è un’app – calendario, contatti, Talk, cartelle di gruppo. occ è lo strumento a riga di comando per tutta l’amministrazione: stato, upgrade, modalità manutenzione, configurazione, scansioni dei file, riparazioni del database.

🛡️ Perché è qui

  • File, calendari, contatti e office in un unico posto, per persone che non dovrebbero aver bisogno di sapere cos’è WebDAV.
  • I dati restano sui server dell’organizzazione. Nessun fornitore decide su accessi, prezzi o funzioni.
  • Un ecosistema. App per quasi ogni esigenza, client per ogni piattaforma, una grande community.

🔧 Cosa fa questo repository

Cosa gira dove

ComponenteDoveRuolo
nginx + PHP-FPM + exporterPod nextcloudnext_k3s_deploy
notify_pushDeployment proprio, stessa immaginenext_k3s_deploy
Collabora OnlineDeployment proprionext_k3s_deploy
Job in backgroundCronJob ogni 5 minnext_k3s_deploy
MariaDBHost, mysqld_tnext_mariadb
RedisHost, redis_tnext_redis
Impostazioni, app, WOPI, policy delle passwordvia occnext_config

I componenti pesanti e preziosi – database e dati – vivono sull’host, con la sandbox systemd completa e i loro domini SELinux. Quelli sostituibili – PHP, Collabora, il demone push – girano nel cluster. Servizi Kubernetes senza selettori, che puntano all’IP del nodo, rendono MariaDB e Redis raggiungibili per i pod con i nomi mariadb e redis; nftables permette quella porta solo dalla rete dei pod. Il codice PHP (/srv/nextcloud-www) e i dati (/data) sono volumi hostPath con le proprie etichette SELinux.

Configurazione a strati

Nextcloud legge config.php e poi ogni *.config.php nella directory di configurazione in ordine alfabetico, e i file successivi vincono. Il repository sfrutta questo: custom.config.php da una ConfigMap porta le impostazioni (cache, anteprime, proxy, logging), redis.config.php da un Secret porta la password di Redis. Entrambi sono montati con subPath, che in un pod in esecuzione non si aggiorna mai; un checksum di tutto ciò che è montato è un’annotation sul pod, così una modifica lo fa ripartire. In origine quel checksum copriva solo le ConfigMap – una volta una nuova impostazione delle anteprime è rimasta un giorno nella ConfigMap mentre il pod usava ancora il vecchio file. Da questa serie copre anche il Secret, dopo che il deep dive su Redis ha scoperto che una password ruotata non avrebbe raggiunto il pod.

Collabora

Il TLS termina all’ingress, quindi Collabora gira in HTTP semplice dietro di esso e viene informato di questo. num_prealloc_children tiene avviati in anticipo altrettanti processi per i documenti; aprire un documento ne prende uno, e se non ce n’è nessuno pronto l’utente aspetta che ne parta uno nuovo. L’occasionale “caricamento fallito, riprovando funziona” subito dopo un riavvio di Collabora è esattamente questo. Il server più grande ne tiene pronti dieci, quello più piccolo sei. next_config imposta l’allowlist WOPI sulla rete dei pod – solo Collabora può chiamare gli endpoint WOPI – e fa rileggere a Nextcloud il documento di discovery di Collabora dopo ogni modifica a Collabora.

Un dettaglio d’installazione mi è costato un pomeriggio: occ app:install richdocuments troncava in modo riproducibile un file dell’app durante l’estrazione, e dopo il controllo d’integrità falliva. Il ruolo quindi scarica il tarball dall’app store da solo, lo estrae con tar e verifica le firme dell’app con occ integrity:check-app.

Il succo: un avviso d’integrità dopo un’installazione è reale. Qui la causa era lo strumento che troncava un file durante lo spacchettamento, non l’app.

Aggiornamenti di due tipi

Un cambio di versione è un nuovo tag d’immagine in versions.yml e un’esecuzione del playbook principale; l’entrypoint del container esegue occ upgrade all’avvio. Nextcloud stesso si rifiuta di saltare una versione major, quindi un salto dalla 32 alla 34 sono due passi. Le immagini ricostruite – Docker Hub ricostruisce tag invariati per correzioni dell’immagine base, e K3s non fa mai pull di nuovo da solo – sono compito di nextcloud-update.yml. Si rifiuta di girare senza --limit (un server alla volta), si rifiuta di partire su un’istanza in modalità manutenzione o con un upgrade del database in sospeso, riavvia solo i Deployment la cui immagine è davvero cambiata, esegue occ upgrade come rete di sicurezza, aggiorna le app, riavvia una seconda volta (OPcache non controlla i timestamp, vedi il deep dive su PHP-FPM) e controlla lo stato. Se qualcosa fallisce, un blocco rescue raccoglie lo stato per una decisione a mano. Entrambi i server girano con Nextcloud 34.

Dal 26 ottobre 2026 il pod di Nextcloud si aggiorna senza downtime finché l’immagine resta la stessa – per modifiche di configurazione e ricostruzioni dello stesso tag: il nuovo pod diventa pronto, poi il vecchio si ferma. Quando l’immagine cambia, resta su Recreate. L’entrypoint allora copia il nuovo codice in /var/www/html ed esegue occ upgrade, e nel frattempo nessun vecchio pod può servire pagine dalla stessa directory.

Il succo: un rolling update è sicuro solo se due versioni possono girare contemporaneamente. Durante un cambio di versione di Nextcloud non possono.

Isolamento

  • Una NetworkPolicy permette a Collabora di parlare solo con Nextcloud e il DNS, e di accettare connessioni solo da Nextcloud e dal nodo. Il pod di Nextcloud e il demone push non ne hanno ancora – a differenza del blog, dove ogni pod è isolato. In un cluster che non contiene nient’altro non è una porta aperta, ma è uno strato che manca; trovato mentre scrivevo questo articolo e proposto.
  • Una admission policy ammette solo immagini da un’allowlist di registry – compresa l’immagine dell’ACME solver di cert-manager, che gira in questo namespace; sul blog la sua assenza una volta ha lasciato una richiesta di certificato in sospeso senza alcun errore.
  • Nessun token di service account nei pod – niente lì dentro parla con l’API di Kubernetes.
  • ClamAV scansiona i file in background alle 04:30, con anteprime e formati multimediali esclusi – prima di questa modifica la scansione era la causa di un server che appariva “occupato” senza motivo visibile.

📊 Misurato

Nextcloud ANextcloud B
Versione34.0.534.0.5
Account / attivi negli ultimi 7 giorni152 / 2726 / 1
Dati388 GB16 GB
Voci della file cache73.0617.415
App attive / disattivate43 / 2261 / 8
Esecuzione dei job in background (cron.php)8–16 s ogni 5 min6–8 s ogni 5 min
Job singolo più lungo133 s (controllo aggiornamenti)59 s (controllo aggiornamenti)
Panoramica admintutti i controlli verdiun errore nel log, previsto (vedi sotto)

La file cache del server più grande aveva più di dieci volte tante voci dopo la migrazione dal vecchio server: il database ripristinato conteneva ancora l’intero indice dei file del vecchio server, e occ files:cleanup non faceva niente finché esisteva la riga di storage del vecchio percorso. Un quarto di ciò che restava apparteneva ad avanzi di un’app office usata in precedenza. Entrambi sono stati rimossi – dopo un backup e dopo aver contato le righe vive, perché i dati delle app disattivate per principio si tengono, nel caso qualcuno li rivoglia.

Il succo: un database ripristinato si porta dietro l’indice dei file del vecchio server. occ files:cleanup lo rimuove solo dopo che è stata cancellata la voce del vecchio storage.

🧰 Amministrazione quotidiana

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

Avvisi previsti

  • “Errori nel log” sul server più piccolo: un errore del database alle 03:30 – il riavvio notturno, durante il quale un pod di job in background non riusciva a risolvere mariadb. Innocuo, ma resta nella panoramica finché il log non ruota.
  • “Caricamento di Office fallito, riprovando funziona” subito dopo un riavvio: Collabora non aveva ancora un processo pre-avviato.
  • Gli avvisi d’integrità dopo una modifica manuale nella directory delle app sono reali: Nextcloud firma il suo codice, e ogni file modificato salta fuori. Mai modificare il codice delle app sul posto.

Backup e ripristino

Ogni notte una macchina di backup scarica via SSH il dump del database, config.php e la directory dei dati e li versiona per 365 giorni. Un ripristino è l’inverso più occ maintenance:data-fingerprint, che dice ai client di sincronizzazione che lo stato del server è cambiato, così non cancellano ciò che credono nuovo.

🆘 Bigino: sintomo → comando

La versione breve di questo articolo per il momento in cui qualcosa non va. Da eseguire sull’host come root; <…> sono segnaposto. occ e wp sono le funzioni di shell dei deep dive su Nextcloud e WordPress.

SintomoComando
Primo sguardoocc status
occ setupchecks
Bloccato in modalità manutenzioneocc maintenance:mode --off
Mancano file modificati fuori da Nextcloudocc files:scan --path="/<user>/files"
Codice vecchio dopo un aggiornamento di appk3s kubectl -n nextcloud rollout restart deployment/nextcloud
I job in background sono in ritardoocc background-job:list --limit=20
k3s kubectl -n nextcloud get cronjob nextcloud-cron
I documenti Office non si apronok3s kubectl -n nextcloud logs deploy/collabora --tail=50
occ richdocuments:activate-config
I client non sincronizzano subitoocc notify_push:self-test
k3s kubectl -n nextcloud logs deploy/notify-push --tail=20
Le anteprime divorano il discoocc preview:cleanup # never rm: previews live in the database
Avvisi dopo un upgradeocc db:add-missing-indices
occ app:list --disabled
Dopo il ripristino di un backupocc maintenance:data-fingerprint

🎯 Le lezioni

  • Ciò che è prezioso – database e dati – va sull’host, ciò che è sostituibile nel cluster.
  • Configurazione a strati: i file *.config.php successivi vincono, notify_push legge solo config.php.
  • Dopo occ upgrade o app:update riavvia il pod, altrimenti continua a girare il vecchio bytecode.
  • Un rolling update solo dove due versioni possono girare contemporaneamente.
  • Dopo una migrazione, ripulisci il vecchio indice dei file.

⚖️ Alternative – e perché Nextcloud

OpzionePunto di forzaPerché non qui
SeafileSincronizzazione molto più veloce, storage a blocchiMeno funzioni di groupware, dati non salvati come semplici file.
ownCloud Infinite ScaleGo, niente PHP, niente databaseArchitettura diversa, ecosistema di app più piccolo, significherebbe migrare tutto.
Un cloud proprietarioNiente da gestireDati e accessi decisi da un fornitore – l’opposto dell’obiettivo.
NextcloudFunzioni, app, client, community, i dati esistentiScelto.

Nextcloud non è difficile da installare; è impegnativo da gestire bene, perché è una dozzina di servizi che fingono di essere uno solo. Dividerli secondo “prezioso o sostituibile” – database e file sull’host, PHP e office nel cluster – ha reso ogni parte più semplice da ragionare. Gli errori di questo post stavano quasi tutti nelle giunture tra di loro.

Alcuni testi e immagini di questo sito sono creati con l’aiuto dell’IA o generati dall’IA. Dettagli