Onde o Nextcloud no Docker guarda os ficheiros

Onde o Nextcloud no Docker armazena os ficheiros

O Nextcloud no Docker armazena os ficheiros num diretório de dados dentro do contentor. A localização real no servidor é o volume ou bind mount que associou ao contentor. Com a imagem linuxserver.io, lscr.io/linuxserver/nextcloud, os ficheiros dos utilizadores ficam em /data, e a instalação do Nextcloud, com o respetivo config.php, fica em /config. Ambos são caminhos dentro do contentor. Um comando mostra o caminho correspondente no host. O resto deste guia aborda a parte mais difícil da questão: tudo o que o diretório de dados não contém.

Fixe a tag da imagem. Os caminhos pertencem à imagem, não ao Nextcloud, e uma tag flutuante pode mudar sem aviso. Em agosto de 2026, a tag estável atual desta imagem é 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:

As duas palavras-passe vêm de um ficheiro .env junto ao ficheiro compose. Assim, não ficam no próprio ficheiro compose. A resposta contém três volumes, mas apenas um armazena os ficheiros dos utilizadores.

Esses caminhos dentro do contentor vêm da documentação dessa imagem específica. Uma imagem Nextcloud diferente organiza o sistema de ficheiros de outra forma e mantém a instalação no seu próprio web root. Por isso, um caminho copiado de uma publicação num fórum é apenas uma suposição. Consulte a informação real no contentor que está a executar.

docker inspect nextcloud

A secção Mounts desse resultado lista todas as montagens, com Source no lado do host e Destination no lado do contentor. Essa listagem responde à questão no seu ambiente, independentemente da imagem escolhida.

Como encontro o caminho real no host por trás do volume?

Um volume nomeado é gerido pelo Docker, por isso não escolhe o respetivo caminho. Consulte-o.

docker volume ls
docker volume inspect nextcloud_nextcloud_data

O nome é importante. O Docker Compose acrescenta o nome do projeto aos nomes dos volumes. Por predefinição, o nome do projeto é o nome do diretório que contém o ficheiro compose. Por isso, um volume escrito como nextcloud_data no ficheiro normalmente existe como nextcloud_nextcloud_data no disco. docker volume ls mostra os nomes reais. A saída de inspect tem este aspeto, abreviado:

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

Mountpoint é a resposta. Leia-o a partir do comando em vez de o presumir, porque o caminho pode mudar. No Docker sem root, toda a raiz de dados do Docker fica dentro do diretório home do utilizador que executa o daemon. Por isso, esse caminho começa noutro local.

Um bind mount elimina esta questão. Escreva - /srv/nextcloud/data:/data no ficheiro compose. O caminho no host será o que indicou. docker inspect apresenta-o como Source. A escolha altera mais do que o caminho, porque volumes nomeados e bind mounts têm comportamentos diferentes relativamente à propriedade dos ficheiros e às cópias de segurança.

Por que o diretório de dados não é um backup

O manual do Nextcloud lista cinco elementos que um backup precisa preservar: a pasta de configuração, a pasta de aplicações personalizadas, a pasta de dados, a pasta do tema e a base de dados. Nesta imagem, as pastas de configuração, aplicações e tema ficam todas em /config, enquanto a base de dados é executada no seu próprio contentor, com o seu próprio volume. Copie apenas /data e terá guardado a parte menos importante do problema.

A base de dados é importante porque a interface web nunca lista um diretório. Ela lista linhas da cache de ficheiros. Por isso, o manual indica que deve executar uma verificação depois de copiar ficheiros manualmente para o diretório de dados. Restaure /data junto de uma base de dados vazia e terá bytes sem índice: sem utilizadores, sem partilhas e sem nada na lista de ficheiros. Restaure a base de dados junto de um /data vazio e cada linha apontará para um ficheiro que já não existe.

config.php contém as credenciais da base de dados e os domínios confiáveis. Também contém o ID da instância, que corresponde ao nome da pasta de dados da aplicação dentro do diretório de dados. Consulte a instância em execução em vez de confiar em qualquer um destes valores guardados de memória.

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

O primeiro comando mostra o diretório de dados que esta instância utiliza efetivamente, que neste caso é /data. Esta imagem inclui um wrapper occ no PATH, portanto execute-o diretamente através de docker exec. Não copie a forma mais longa sudo e php occ do manual do Nextcloud, que foi escrita para uma instalação fora de um contentor.

O que está a ocupar silenciosamente o volume de dados?

As pré-visualizações e o histórico de cada utilizador ficam no mesmo volume que os ficheiros, mas nenhum dos dois aparece no valor de armazenamento que o utilizador vê na interface web.

• As pré-visualizações são miniaturas geradas. Ficam na pasta de dados da aplicação, dentro do diretório de dados, com o nome appdata_ seguido do ID da instância.
• Os ficheiros eliminados permanecem na reciclagem. trashbin_retention_obligation tem o valor predefinido auto, que os mantém durante 30 dias e só os remove depois desse período quando é necessário libertar espaço. Os ficheiros eliminados continuam a contar para a quota do utilizador. Quando a quota é excedida, a definição de retenção é ignorada e a reciclagem é reduzida até a quota voltar a ser respeitada.
• As versões antigas também permanecem. versions_retention_obligation também tem o valor predefinido auto. A aplicação Versions nunca utiliza mais de 50% do espaço atualmente livre na conta de um utilizador. Quando faz a limpeza, elimina primeiro as versões mais antigas e mantém as duas mais recentes. Uma versão nomeada manualmente por um utilizador nunca é eliminada.

Meça antes de eliminar qualquer coisa.

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

A primeira linha apresenta um valor para cada pasta de utilizador e outro para a pasta de dados da aplicação. Se o valor da aplicação for elevado, a causa são as pré-visualizações. Os comandos de limpeza abaixo estão documentados, e todos eliminam dados deliberadamente.

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 remove todas as pré-visualizações geradas. O Nextcloud volta a gerá-las quando os utilizadores abrem esses ficheiros, por isso o espaço é ocupado gradualmente outra vez e o CPU suporta esse processamento. Se o volume for apenas uma parte de um problema mais amplo no disco, imagens antigas e cache de builds obsoleta são normalmente a outra parte.

Por que os ficheiros que copio para o host não aparecem no Nextcloud?

Porque o Nextcloud lê a cache de ficheiros na base de dados, e não o diretório. A cópia criou um ficheiro no disco sem uma linha correspondente na base de dados, por isso a interface web não tem nada para listar. O manual descreve exatamente este caso: é necessário executar uma verificação depois de copiar ficheiros diretamente para o diretório de dados.

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

O argumento --path também mostra a estrutura dentro do diretório de dados: cada utilizador tem uma pasta com o seu nome de utilizador, e files dentro dessa pasta contém o que o utilizador vê na interface web. Verifique um único caminho quando souber onde os ficheiros foram colocados. --all percorre todos os utilizadores e demora bastante numa instância grande. --unscanned só processa os ficheiros marcados como ainda não totalmente verificados. -v apresenta cada ficheiro à medida que é processado. Esta é a diferença entre um comando que parece bloqueado e um comando que pode monitorizar.

As permissões de proprietário determinam se a verificação será suficiente. Um ficheiro no qual o utilizador do contentor não pode escrever é indexado, mas depois não pode ser movido. Assim, a listagem parece correta, mas a alteração do nome ou a eliminação pela interface web falha.

Por que as gravações falham depois de definir PUID e PGID?

Porque o kernel compara números, não nomes. PUID e PGID definem o ID numérico do utilizador (uid) e o ID do grupo (gid) com que o processo do contentor é executado. Cada ficheiro no host também tem um proprietário numérico. Quando os dois números são diferentes, a gravação é recusada, independentemente dos nomes apresentados em cada lado.

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

id abc mostra o uid e o gid que o contentor está realmente a utilizar. São os valores definidos em PUID e PGID. ls -ln mostra os proprietários numéricos, e -n é importante: ls -l simples traduz esses números através da lista de utilizadores do host e mostra um nome que não tem significado dentro do contentor. Compare os dois números.

Depois, teste a gravação em vez de presumir o resultado.

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

Um Permission denied que nomeia /data é a confirmação. Corrija o proprietário a partir de dentro do contentor e execute novamente o mesmo teste.

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

Faça isso a partir de dentro do contentor por uma razão. Com o Docker rootless, os IDs de utilizador do contentor são mapeados através do intervalo subordinado em /etc/subuid. Por isso, o uid 1000 dentro do contentor corresponde a um uid muito mais elevado no host. Um chown 1000:1000 executado no host define então um proprietário que o contentor não pode utilizar, e a gravação continua a falhar. Executar chown dentro do contentor utiliza o mesmo mapeamento que o processo do Nextcloud utiliza, pelo que os números ficam alinhados por construção. É também por isso que PUID e PGID têm de corresponder ao proprietário no disco antes de começar a investigar qualquer outra coisa.

Como faço o backup para que a restauração funcione de facto?

Faça o backup da base de dados e das pastas no mesmo momento. O modo de manutenção impede os logins, para que nenhum upload seja feito entre o dump e a cópia.

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

Observe o que falta na linha do dump: uma flag -t. Um TTY reescreve as terminações de linha, e um dump SQL que passa por um TTY fica corrompido de uma forma que só é detetada durante a restauração. Observe também que uma palavra-passe na linha de comandos fica visível na saída de ps enquanto o comando é executado. Por isso, leia-a do seu ficheiro .env para a shell em vez de a escrever. As imagens de bases de dados mais antigas disponibilizam mysqldump em vez de mariadb-dump, e o manual documenta ambos.

Para restaurar, carregue o dump numa base de dados vazia, extraia os dois arquivos para volumes novos, inicie os contentores e, depois, desative o modo de manutenção. Se as pastas e o dump forem de momentos diferentes, a cache de ficheiros e o disco ficam inconsistentes, e occ files:scan --all corrige apenas uma direção. Encontra ficheiros que existem sem uma linha correspondente. Não consegue recuperar um ficheiro para o qual uma linha aponta.

Mantenha o resultado fora do servidor. Uma cópia armazenada no mesmo VPS deixa de existir com o VPS. Por isso, restic para um repositório fora do servidor faz parte deste processo. Da mesma forma, um snapshot do fornecedor é uma ferramenta diferente de um backup. Se ainda estiver a montar a stack, uma instalação completa do Nextcloud num VPS aborda o reverse proxy e o certificado TLS (transport layer security) que este guia não inclui.

FAQ

Onde fica o diretório de dados do Nextcloud num contentor Docker?

Com a imagem linuxserver.io, ele fica em /data dentro do contentor, e a instalação com config.php fica em /config. Estes são caminhos do contentor. Para obter o caminho no host, execute docker inspect nextcloud e leia o valor de Source na secção Mounts, ou execute docker volume inspect no volume e leia Mountpoint. Outras imagens do Nextcloud usam caminhos diferentes dentro do contentor. Consulte a documentação da tag que fixou e confirme com docker exec -it nextcloud occ config:system:get datadirectory.

Porque é que os ficheiros que copio para o volume não aparecem no Nextcloud?

O Nextcloud lista os registos da cache de ficheiros na base de dados, em vez de ler o diretório. Por isso, um ficheiro que chega sem passar pelo Nextcloud não tem registo e permanece invisível. Execute docker exec -it nextcloud occ files:scan --path="/alice/files/Photos" para uma pasta ou occ files:scan --all para todos os utilizadores. Se os ficheiros aparecem, mas depois não podem ser movidos ou eliminados, a causa são as permissões de proprietário: o utilizador do contentor tem de poder escrever neles.

Uma cópia do volume de dados é suficiente para restaurar o Nextcloud?

Não. O volume de dados contém o conteúdo dos ficheiros. A base de dados contém o índice dos ficheiros, além dos utilizadores e partilhas, e config.php contém as credenciais da base de dados e o ID da instância. Uma restauração funcional precisa da pasta de dados, da pasta de configuração, da base de dados e das pastas de aplicações e temas personalizados, se forem utilizadas. Obtenha todos estes elementos no mesmo momento, porque uma base de dados mais recente do que os ficheiros aponta para ficheiros que não existem.

Porque é que o meu volume de dados é muito maior do que os ficheiros visíveis para os utilizadores?

As pré-visualizações, os ficheiros eliminados e as versões antigas ficam no mesmo volume. Nenhum deles aparece no valor apresentado ao utilizador. Meça com docker exec -it nextcloud sh -c 'du -sh /data/*'. A reciclagem mantém os ficheiros eliminados durante 30 days por predefinição e só os elimina antes disso quando é necessário libertar espaço. A aplicação Versions pode utilizar até metade do espaço livre que um utilizador tem atualmente. Limpe-os com occ trashbin:cleanup --all-users, occ versions:cleanup alice e occ preview:cleanup. Espere que as pré-visualizações voltem a crescer à medida que os utilizadores abrem os ficheiros.

Posso mover o diretório de dados do Nextcloud para outro disco?

Monte a nova localização no mesmo caminho do contentor, em vez de alterar o caminho que o Nextcloud conhece. Pare o contentor e copie o conteúdo antigo para o novo disco, preservando o proprietário (cp -a ou rsync -aAX). Depois, aponte o volume ou o bind mount para a nova localização no ficheiro compose e inicie novamente o contentor. O Nextcloud continua a ver /data, pelo que não é necessário alterar nenhum registo na base de dados. Verifique com docker exec -it nextcloud occ config:system:get datadirectory e faça um upload de teste.