Dove Nextcloud in Docker salva i file

Dove Nextcloud in Docker archivia i file

Nextcloud in Docker archivia i file in una directory dati all'interno del container. Il percorso reale sul server è il volume o il bind mount collegato al container. Con l'immagine linuxserver.io, lscr.io/linuxserver/nextcloud, i file degli utenti si trovano in /data. L'installazione di Nextcloud e il relativo config.php si trovano in /config. Entrambi sono percorsi del container. Un comando mostra il percorso dell'host associato a questi percorsi. Il resto di questa guida tratta la parte più complessa della domanda: tutto ciò che la directory dati non contiene.

Blocca il tag dell'immagine. I percorsi dipendono dall'immagine, non da Nextcloud, e un tag mobile può cambiare senza preavviso. Ad agosto 2026, il tag stabile corrente per questa immagine è 34.0.3.

services:
  nextcloud:
    image: lscr.io/linuxserver/nextcloud:34.0.3
    container_name: nextcloud
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
    volumes:
      - nextcloud_config:/config
      - nextcloud_data:/data
    ports:
      - 443:443
    restart: unless-stopped

  nextcloud-db:
    image: mariadb:11.8
    container_name: nextcloud-db
    environment:
      - MARIADB_ROOT_PASSWORD=${MARIADB_ROOT_PASSWORD}
      - MARIADB_DATABASE=nextcloud
      - MARIADB_USER=nextcloud
      - MARIADB_PASSWORD=${NEXTCLOUD_DB_PASSWORD}
    volumes:
      - nextcloud_db:/var/lib/mysql
    restart: unless-stopped

volumes:
  nextcloud_config:
  nextcloud_data:
  nextcloud_db:

Le due password provengono da un file .env accanto al file compose, quindi non vengono inserite nel file compose stesso. La risposta comprende tre volumi, ma solo uno contiene i file degli utenti.

Questi percorsi del container provengono dalla documentazione di quella specifica immagine. Un'altra immagine Nextcloud può avere una struttura del filesystem diversa e mantenere l'installazione nella propria web root. Di conseguenza, un percorso copiato da un post del forum è solo un'ipotesi. Verifica i percorsi effettivi nel container in esecuzione.

docker inspect nextcloud

La sezione Mounts di quell'output elenca ogni mount, con Source sul lato dell'host e Destination sul lato del container. Questo elenco fornisce la risposta per la tua configurazione, indipendentemente dall'immagine scelta.

Come trovo il percorso reale sull'host dietro al volume?

Un volume denominato è gestito da Docker, quindi non scegli tu il relativo percorso. Devi richiederlo a Docker.

docker volume ls
docker volume inspect nextcloud_nextcloud_data

Il nome è importante. Docker Compose antepone ai nomi dei volumi il nome del progetto, che per impostazione predefinita corrisponde al nome della directory che contiene il file Compose. Di conseguenza, un volume indicato come nextcloud_data nel file di solito esiste su disco con il nome nextcloud_nextcloud_data. docker volume ls mostra i nomi effettivi. L'output di inspect è simile al seguente, abbreviato:

[
    {
        "CreatedAt": "2026-08-18T09:12:44Z",
        "Driver": "local",
        "Mountpoint": "/var/lib/docker/volumes/nextcloud_nextcloud_data/_data",
        "Name": "nextcloud_nextcloud_data",
        "Scope": "local"
    }
]

Mountpoint è la risposta. Leggilo dal comando invece di presumerlo, perché può cambiare. Con Docker rootless, l'intera radice dei dati Docker si trova nella home directory dell'utente che esegue il daemon, quindi il percorso inizia da una posizione diversa.

Un bind mount elimina il problema. Scrivi - /srv/nextcloud/data:/data nel file Compose: il percorso sull'host è quello indicato da te, che docker inspect riporta come Source. La scelta modifica più del semplice percorso, perché volumi denominati e bind mount si comportano in modo diverso per proprietà e backup.

Perché la directory dei dati non è un backup

Il manuale di Nextcloud indica cinque elementi che un backup deve conservare: la directory di configurazione, la directory delle app personalizzate, la directory dei dati, la directory del tema e il database. Con questa image, le directory di configurazione, delle app e del tema si trovano tutte in /config, mentre il database viene eseguito nel proprio container con il proprio volume. Se copi solo /data, hai salvato la parte meno importante del problema.

Il database è importante perché l’interfaccia web non elenca le directory. Elenca le righe della cache dei file. Per questo il manuale indica di eseguire una scansione dopo aver copiato manualmente i file nella directory dei dati. Se ripristini /data accanto a un database vuoto, ottieni byte senza indice: nessun utente, nessuna condivisione e nulla nell’elenco dei file. Se ripristini il database accanto a un /data vuoto, ogni riga punta a un file che non esiste più.

config.php contiene le credenziali del database e i domini attendibili. Contiene anche l’ID dell’istanza, che corrisponde al nome della directory dei dati dell’applicazione all’interno della directory dei dati. Verifica questi valori sull’istanza in esecuzione invece di basarti su valori ricordati.

docker exec -it nextcloud occ config:system:get datadirectory
docker exec -it nextcloud occ config:system:get instanceid

Il primo comando mostra la directory dei dati effettivamente utilizzata da questa istanza, che qui è /data. Questa image include un wrapper occ nel PATH, quindi eseguilo direttamente tramite docker exec. Non copiare la forma più lunga sudo e php occ dal manuale di Nextcloud, perché è scritta per un’installazione esterna a un container.

Che cosa sta riempiendo silenziosamente il volume dei dati?

Le anteprime e la cronologia per utente si trovano nello stesso volume dei file, ma nessuna delle due viene inclusa nella quantità di spazio mostrata all’utente nell’interfaccia web.

• Le anteprime sono miniature generate automaticamente. Si trovano nella cartella dei dati dell’applicazione, all’interno della directory dei dati, con un nome formato da appdata_ seguito dall’ID dell’istanza.
• I file eliminati restano nel cestino. trashbin_retention_obligation è impostato per impostazione predefinita su auto: conserva i file per 30 giorni e li elimina solo dopo tale periodo, quando è necessario liberare spazio. I file eliminati continuano a essere conteggiati nella quota dell’utente. Quando la quota viene superata, l’impostazione di conservazione viene ignorata e il cestino viene ridotto finché la quota non rientra nei limiti.
• Anche le versioni precedenti restano disponibili. versions_retention_obligation è impostato per impostazione predefinita su auto. L’app Versions non utilizza mai più del 50% dello spazio attualmente libero dell’utente. Quando elimina le versioni in eccesso, rimuove prima quelle più vecchie e conserva le due più recenti. Una versione a cui l’utente ha assegnato manualmente un nome non viene mai eliminata.

Misurare prima di eliminare qualsiasi elemento.

docker exec -it nextcloud sh -c 'du -sh /data/*'
docker exec -it nextcloud sh -c 'du -sh /data/appdata_*'

La prima riga mostra un numero per ogni cartella utente e uno per la cartella dei dati dell’applicazione. Se il numero relativo ai dati dell’applicazione è elevato, la causa sono le anteprime. I comandi di pulizia riportati di seguito sono documentati e ognuno di essi elimina intenzionalmente dei dati.

docker exec -it nextcloud occ trashbin:cleanup --all-users
docker exec -it nextcloud occ versions:cleanup alice
docker exec -it nextcloud occ preview:cleanup

preview:cleanup rimuove tutte le anteprime generate. Nextcloud le genera nuovamente quando gli utenti aprono i file corrispondenti. Lo spazio si riempie quindi di nuovo gradualmente e il carico viene trasferito alla CPU. Se il volume è solo una parte di un problema più ampio relativo al disco, le vecchie immagini e la cache di build obsoleta sono generalmente l’altra causa.

Perché i file che copio sull'host non compaiono in Nextcloud?

Nextcloud legge l'indice dei file dal database, non direttamente dalla directory. La copia ha creato un file sul disco senza una riga corrispondente nel database, quindi l'interfaccia Web non ha nulla da elencare. Il manuale descrive esattamente questo caso: dopo avere copiato i file direttamente nella directory dei dati, è necessaria una scansione.

docker exec -it nextcloud occ files:scan --path="/alice/files/Photos"
docker exec -it nextcloud occ files:scan --unscanned -v
docker exec -it nextcloud occ files:scan --all

L'argomento --path mostra anche la struttura della directory dei dati: ogni utente ha una cartella con il proprio nome utente e, al suo interno, files contiene ciò che l'utente vede nell'interfaccia Web. Eseguire la scansione di un solo percorso quando si sa dove sono stati copiati i file. --all attraversa tutti gli utenti e può richiedere molto tempo su un'istanza di grandi dimensioni. --unscanned elabora soltanto i file contrassegnati come non ancora completamente scansionati. -v visualizza ogni file durante l'elaborazione; questa è la differenza tra un comando che sembra bloccato e uno di cui è possibile monitorare l'avanzamento.

La proprietà dei file determina se la scansione è sufficiente. Se l'utente del container non può scrivere un file, questo viene indicizzato ma non può essere spostato. Di conseguenza, l'elenco appare corretto, mentre la ridenominazione o l'eliminazione dall'interfaccia Web fallisce.

Perché le scritture non riescono dopo aver impostato PUID e PGID?

Perché il kernel confronta i numeri, non i nomi. PUID e PGID impostano l'ID numerico dell'utente (uid) e del gruppo (gid) con cui viene eseguito il processo nel container. Anche ogni file sull'host ha un proprietario numerico. Se i due numeri sono diversi, la scrittura viene negata, indipendentemente dai nomi visualizzati nei due ambienti.

docker exec -it nextcloud id abc
sudo ls -ln /var/lib/docker/volumes/nextcloud_nextcloud_data/_data

id abc stampa uid e gid effettivamente utilizzati dal container, cioè i valori PUID e PGID impostati. ls -ln stampa i proprietari numerici e -n è importante: il semplice ls -l converte quei numeri usando l'elenco degli utenti dell'host e mostra un nome che nel container non ha alcun significato. Confronta i due numeri.

Poi verifica la scrittura invece di procedere per tentativi.

docker exec -u abc -it nextcloud touch /data/writetest

Un Permission denied che assegna il nome /data è la conferma. Correggi la proprietà dall'interno del container, quindi esegui di nuovo lo stesso test.

docker exec -u 0 -it nextcloud chown -R abc:abc /data
docker exec -u abc -it nextcloud touch /data/writetest
docker exec -u abc -it nextcloud rm /data/writetest

Esegui l'operazione dall'interno per un motivo preciso. Con Docker rootless, gli ID utente del container vengono mappati attraverso l'intervallo subordinato in /etc/subuid, quindi uid 1000 all'interno del container corrisponde a un uid molto più alto sull'host. Un chown 1000:1000 eseguito sull'host imposta quindi un proprietario che il container non può utilizzare e la scrittura continua a non riuscire. Eseguire chown all'interno del container usa la stessa mappatura utilizzata dal processo Nextcloud, quindi i numeri corrispondono per costruzione. Per questo PUID e PGID devono corrispondere al proprietario sul disco prima di iniziare qualsiasi altra attività di debug.

Come eseguire un backup in modo che il ripristino funzioni davvero?

Acquisisci il database e le directory nello stesso momento. La modalità di manutenzione impedisce l'accesso, quindi nessun caricamento viene completato tra l'esportazione e la copia.

docker exec -it nextcloud occ maintenance:mode --on
docker exec nextcloud-db mariadb-dump --single-transaction -u nextcloud -p"$NEXTCLOUD_DB_PASSWORD" nextcloud > nextcloud-sqlbkp.sql
docker run --rm -v nextcloud_nextcloud_data:/data:ro -v "$PWD":/backup alpine:3.22 tar czf /backup/nextcloud-data.tgz -C /data .
docker run --rm -v nextcloud_nextcloud_config:/config:ro -v "$PWD":/backup alpine:3.22 tar czf /backup/nextcloud-config.tgz -C /config .
docker exec -it nextcloud occ maintenance:mode --off

Nota cosa non contiene la riga di esportazione: un flag -t. Un TTY riscrive i caratteri di fine riga e un dump SQL che è passato attraverso un TTY si corrompe in un modo che viene rilevato soltanto durante il ripristino. Inoltre, una password specificata nella riga di comando è visibile nell'output di ps mentre il comando è in esecuzione. Per questo, leggila dal file .env nella shell invece di digitarla. Le immagini di database meno recenti includono mysqldump invece di mariadb-dump; il manuale documenta entrambe le opzioni.

Per eseguire il ripristino, carica il dump in un database vuoto, estrai entrambi gli archivi in volumi nuovi, avvia i container, quindi disattiva la modalità di manutenzione. Se le directory e il dump provengono da momenti diversi, la cache dei file e il database non sono coerenti e occ files:scan --all corregge soltanto una delle due direzioni. Individua i file che esistono senza una riga corrispondente. Non può ripristinare un file a cui fa riferimento una riga.

Conserva il risultato fuori dal server. Una copia che si trova nella stessa VPS viene persa insieme alla VPS. Per questo restic verso un repository esterno al server fa parte di questa procedura e uno snapshot del provider è uno strumento diverso da un backup. Se stai ancora configurando lo stack, un'installazione completa di Nextcloud su una VPS descrive il reverse proxy e il certificato TLS (transport layer security) che questa guida non tratta.

FAQ

Dove si trova la directory dei dati di Nextcloud in un container Docker?

Con l'immagine linuxserver.io si trova in /data all'interno del container, mentre l'installazione con config.php si trova in /config. Questi sono percorsi del container. Per individuare il percorso sull'host, esegui docker inspect nextcloud e leggi il valore Source nella sezione Mounts, oppure esegui docker volume inspect sul volume e leggi Mountpoint. Le altre immagini Nextcloud usano percorsi diversi nel container. Consulta quindi la documentazione relativa al tag bloccato e verifica con docker exec -it nextcloud occ config:system:get datadirectory.

Perché i file copiati nel volume non vengono visualizzati in Nextcloud?

Nextcloud elenca le righe della cache dei file nel database, invece di leggere direttamente la directory. Un file aggiunto senza passare da Nextcloud non ha quindi una riga associata e resta invisibile. Esegui docker exec -it nextcloud occ files:scan --path="/alice/files/Photos" per una singola cartella oppure occ files:scan --all per tutti gli utenti. Se i file vengono visualizzati ma non possono essere spostati o eliminati, la causa sono i proprietari: l'utente del container deve poter scrivere sui file.

È sufficiente una copia del volume dei dati per ripristinare Nextcloud?

No. Il volume dei dati contiene il contenuto dei file. Il database contiene l'indice dei file, oltre agli utenti e alle condivisioni, mentre config.php contiene le credenziali del database e l'ID dell'istanza. Per un ripristino funzionante servono la directory dei dati, la directory di configurazione, il database e le directory delle app e del tema personalizzati, se utilizzati. Acquisiscili tutti nello stesso momento, perché un database più recente dei file può contenere riferimenti a file inesistenti.

Perché il volume dei dati è molto più grande dei file visualizzati dagli utenti?

Le anteprime, i file eliminati e le versioni precedenti si trovano nello stesso volume, ma non sono inclusi nella quantità mostrata all'utente. Misura lo spazio con docker exec -it nextcloud sh -c 'du -sh /data/*'. Per impostazione predefinita, il cestino conserva i file eliminati per 30 giorni e li rimuove prima solo quando è necessario liberare spazio. L'app Versions può utilizzare fino alla metà dello spazio libero attualmente disponibile per un utente. Rimuovili con occ trashbin:cleanup --all-users, occ versions:cleanup alice e occ preview:cleanup. Considera che le anteprime aumenteranno nuovamente quando gli utenti apriranno i file.

Posso spostare la directory dei dati di Nextcloud su un altro disco?

Monta la nuova posizione sullo stesso percorso del container, invece di modificare il percorso noto a Nextcloud. Arresta il container, copia il contenuto precedente sul nuovo disco preservando i proprietari (cp -a oppure rsync -aAX), imposta la nuova posizione per il volume o il bind mount nel file compose, quindi avvia nuovamente il container. Nextcloud continuerà a vedere /data, quindi non sarà necessario modificare alcuna riga del database. Verifica con docker exec -it nextcloud occ config:system:get datadirectory ed esegui un caricamento di prova.