Deep Dive: Nextcloud no K3s – pods PHP, bancos de dados no host e Office no navegador
O Nextcloud é uma grande aplicação PHP com jobs em segundo plano, notificações push, previews, uma suíte de escritório e dezenas de apps. Como as partes se encaixam aqui em dois servidores, o que as mantém rápidas, quais avisos são esperados – e os erros que mais ensinaram.

🌐 Também em: English · Deutsch · Français · Español · Italiano · Nederlands · Polski
Deep Dive da série em torno do Ansible Tour. O tour explica as roles, os deep dives explicam a tecnologia por baixo: como funciona, por que é usada desta forma aqui e o que deu errado no caminho.
Dois servidores Nextcloud rodam neste setup, um para uma organização com cerca de 150 contas e quase 400 GB de arquivos, outro para um grupo pequeno. Ambos são construídos a partir das mesmas roles (parte 4 do tour). Este post explica como o Nextcloud é montado, como as peças são distribuídas entre host e cluster e o que operá-lo ensinou até agora.
Índice
🧭 Como o Nextcloud funciona
Uma aplicação PHP, muitos pontos de entrada
O Nextcloud é PHP. Cada página no navegador, cada requisição WebDAV de um cliente de sincronização e cada chamada de API dos apps móveis é uma requisição PHP que passa pelo nginx até o PHP-FPM. Os arquivos em si ficam em um diretório de dados; o banco de dados conhece cada arquivo pela tabela file cache – nome, tamanho, ETag, permissões –, de modo que as listagens nunca precisam tocar o disco.
Locking e caching
Quando dois clientes alteram o mesmo arquivo, o transactional file locking decide quem vence. Os locks precisam ser visíveis para todos os processos PHP ao mesmo tempo, e é por isso que ficam no Redis. Ao lado disso, o APCu faz cache por processo e o Redis faz cache entre processos.
Jobs em segundo plano
Limpeza, expiração de lixeira e versões, notificações, verificação de atualizações de apps, pré-geração de previews – o Nextcloud mantém uma fila de jobs no banco de dados. Algo precisa rodar o cron.php regularmente para processá-la; o Nextcloud recomenda a cada cinco minutos.
Push, previews, office
- notify_push é um pequeno daemon em Rust distribuído dentro de um app. Os clientes mantêm um WebSocket aberto com ele e ficam sabendo das mudanças imediatamente, em vez de perguntar a cada 30 segundos.
- Previews são miniaturas, geradas na primeira visualização ou antecipadamente pelo app Preview Generator, e guardadas na pasta de dados dos apps.
- Nextcloud Office é o app richdocuments mais um servidor Collabora Online. O navegador carrega o editor do Collabora; o Collabora busca e salva o documento no Nextcloud pelo protocolo WOPI, com um token por sessão.
Apps e occ
Quase tudo além dos arquivos é um app – calendário, contatos, Talk, group folders. occ é a ferramenta de linha de comando para toda a administração: status, upgrades, modo de manutenção, configuração, varredura de arquivos, reparos no banco de dados.
🛡️ Por que está aqui
- Arquivos, calendários, contatos e office em um só lugar, para pessoas que não deveriam precisar saber o que é WebDAV.
- Os dados ficam nos servidores da própria organização. Nenhum fornecedor decide sobre acesso, preços ou funcionalidades.
- Um ecossistema. Apps para quase toda necessidade, clientes para todas as plataformas, uma grande comunidade.
🔧 O que este repositório faz
O que roda onde
| Componente | Onde | Role |
|---|---|---|
| nginx + PHP-FPM + exporter | Pod nextcloud | next_k3s_deploy |
| notify_push | Deployment próprio, mesma imagem | next_k3s_deploy |
| Collabora Online | Deployment próprio | next_k3s_deploy |
| Jobs em segundo plano | CronJob a cada 5 min | next_k3s_deploy |
| MariaDB | Host, mysqld_t | next_mariadb |
| Redis | Host, redis_t | next_redis |
| Configurações, apps, WOPI, política de senhas | via occ | next_config |
Os componentes pesados e preciosos – banco de dados e dados – vivem no host, com o sandbox completo do systemd e domínios SELinux próprios. Os substituíveis – PHP, Collabora, o daemon de push – rodam no cluster. Services do Kubernetes sem selectors, apontando para o IP do node, tornam MariaDB e Redis acessíveis aos pods pelos nomes mariadb e redis; o nftables libera essa porta apenas a partir da rede dos pods. O código PHP (/srv/nextcloud-www) e os dados (/data) são volumes hostPath com labels SELinux próprios.
Configuração em camadas
O Nextcloud lê o config.php e depois cada *.config.php no diretório de configuração em ordem alfabética, com os arquivos posteriores vencendo. O repositório aproveita isso: custom.config.php, vindo de um ConfigMap, carrega as configurações (caches, previews, proxies, logging), e redis.config.php, vindo de um Secret, carrega a senha do Redis. Ambos são montados com subPath, que nunca é atualizado em um pod em execução; um checksum de tudo o que é montado é uma annotation no pod, então uma mudança faz o pod ser recriado. Originalmente esse checksum cobria apenas os ConfigMaps – uma nova configuração de previews ficou um dia inteiro no ConfigMap enquanto o pod ainda rodava o arquivo antigo. Desde esta série ele cobre também o Secret, depois que o deep dive sobre Redis descobriu que uma senha rotacionada não teria chegado ao pod.
Collabora
O TLS termina no ingress, então o Collabora roda HTTP simples por trás dele e é informado disso. num_prealloc_children mantém essa quantidade de processos de documento iniciados antecipadamente; abrir um documento consome um, e se nenhum estiver pronto o usuário espera até um novo iniciar. O ocasional “falha ao carregar, tentar de novo funciona” logo após um restart do Collabora é exatamente isso. O servidor maior mantém dez prontos, o menor seis. next_config define a allowlist do WOPI para a rede dos pods – só o Collabora pode chamar os endpoints WOPI – e faz o Nextcloud reler o documento de discovery do Collabora após cada mudança no Collabora.
Um detalhe de instalação custou uma tarde: occ app:install richdocuments truncava de forma reproduzível um arquivo do app ao extraí-lo, e a verificação de integridade falhava em seguida. Por isso a role baixa o tarball da app store por conta própria, extrai com tar e verifica as assinaturas do app com occ integrity:check-app.
A lição: Um aviso de integridade depois de uma instalação é real. Aqui a causa foi a ferramenta que cortou um arquivo ao descompactar, não o app.
Atualizações de dois tipos
Uma mudança de versão é uma nova tag de imagem em versions.yml e uma execução do playbook principal; o entrypoint do container roda occ upgrade ao iniciar. O próprio Nextcloud se recusa a pular uma versão major, então um salto de 32 para 34 são dois passos. Imagens reconstruídas – o Docker Hub reconstrói tags inalteradas para correções da imagem base, e o K3s nunca faz pull de novo por conta própria – são trabalho do nextcloud-update.yml. Ele se recusa a rodar sem --limit (um servidor por vez), se recusa a começar em uma instância que está em modo de manutenção ou tem um upgrade de banco pendente, reinicia apenas os Deployments cuja imagem realmente mudou, roda occ upgrade como rede de segurança, atualiza os apps, reinicia uma segunda vez (o OPcache não verifica timestamps, veja o deep dive sobre PHP-FPM) e verifica o status. Se algo falhar, um bloco rescue coleta o estado para uma decisão manual. Ambos os servidores rodam Nextcloud 34.
Desde 26 de outubro de 2026 o pod do Nextcloud é atualizado sem downtime enquanto a imagem permanece a mesma – para mudanças de configuração e rebuilds da mesma tag: o novo pod fica pronto, depois o antigo para. Quando a imagem muda, continua com Recreate. O entrypoint então copia o código novo para /var/www/html e roda occ upgrade, e nesse meio-tempo nenhum pod antigo pode servir páginas do mesmo diretório.
A lição: Um rolling update só é seguro se duas versões puderem rodar ao mesmo tempo. Durante uma mudança de versão do Nextcloud, elas não podem.
Isolamento
- Uma NetworkPolicy permite que o Collabora fale apenas com o Nextcloud e o DNS, e aceite conexões apenas do Nextcloud e do node. O pod do Nextcloud e o daemon de push ainda não têm nenhuma – ao contrário do blog, onde cada pod está isolado. Em um cluster que não contém mais nada isso não é uma porta aberta, mas é uma camada faltando; descoberto ao escrever este artigo e já proposto.
- Uma admission policy só admite imagens de uma allowlist de registries – incluindo a imagem do ACME solver do cert-manager, que roda neste namespace; no blog, a ausência dela uma vez deixou uma requisição de certificado pendente sem erro nenhum.
- Nenhum token de service account nos pods – nada neles fala com a API do Kubernetes.
- O ClamAV varre os arquivos em segundo plano às 04:30, com previews e formatos de mídia excluídos – antes dessa mudança, a varredura era a causa de um servidor que aparecia como “ocupado” sem motivo visível.
📊 Medido
| Nextcloud A | Nextcloud B | |
|---|---|---|
| Versão | 34.0.5 | 34.0.5 |
| Contas / ativas nos últimos 7 dias | 152 / 27 | 26 / 1 |
| Dados | 388 GB | 16 GB |
| Entradas no file cache | 73.061 | 7.415 |
| Apps ativados / desativados | 43 / 22 | 61 / 8 |
| Execução dos jobs (cron.php) | 8–16 s a cada 5 min | 6–8 s a cada 5 min |
| Job individual mais longo | 133 s (verificação de atualizações) | 59 s (verificação de atualizações) |
| Visão geral de administração | todas as verificações verdes | um erro de log, esperado (veja abaixo) |
O file cache do servidor maior tinha mais de dez vezes mais entradas depois da migração do servidor antigo: o banco de dados restaurado ainda continha todo o índice de arquivos do servidor antigo, e occ files:cleanup não fazia nada enquanto existisse a linha de storage do caminho antigo. Um quarto do que restou pertencia a sobras de um app de office usado anteriormente. Ambos foram removidos – depois de um backup e de contar as linhas ativas, porque dados de apps desativados são mantidos por princípio, caso alguém os queira de volta.
A lição: Um banco de dados restaurado traz junto o índice de arquivos do servidor antigo. occ files:cleanup só o remove depois que a entrada do storage antigo foi apagada.
🧰 Administração do dia a dia
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
Avisos esperados
- “Erros no log” no servidor menor: um erro de banco de dados às 03:30 – o reboot noturno, durante o qual um pod de job em segundo plano não conseguiu resolver
mariadb. Inofensivo, mas fica na visão geral até o log rotacionar. - “O Office falhou ao carregar, tentar de novo funciona” logo após um restart: o Collabora ainda não tinha nenhum processo pré-iniciado.
- Avisos de integridade após uma mudança manual no diretório de apps são reais: o Nextcloud assina seu código, e qualquer arquivo editado aparece. Nunca edite código de app no lugar.
Backups e restauração
Toda noite uma máquina de backup puxa o dump do banco, o config.php e o diretório de dados via SSH e os versiona por 365 dias. Uma restauração é o caminho inverso mais occ maintenance:data-fingerprint, que avisa aos clientes de sincronização que o estado do servidor mudou, para que eles não apaguem o que acham que é novo.
🆘 Cola: sintoma → comando
A versão curta deste artigo para o momento em que algo está errado. Rode no host como root; <…> são placeholders. occ e wp são as funções de shell dos deep dives sobre Nextcloud e WordPress.
| Sintoma | Comando |
|---|---|
| Primeira olhada | occ statusocc setupchecks |
| Preso no modo de manutenção | occ maintenance:mode --off |
| Arquivos alterados fora do Nextcloud não aparecem | occ files:scan --path="/<user>/files" |
| Código antigo após atualizar um app | k3s kubectl -n nextcloud rollout restart deployment/nextcloud |
| Jobs em segundo plano atrasados | occ background-job:list --limit=20k3s kubectl -n nextcloud get cronjob nextcloud-cron |
| Documentos do Office não abrem | k3s kubectl -n nextcloud logs deploy/collabora --tail=50occ richdocuments:activate-config |
| Clientes não sincronizam na hora | occ notify_push:self-testk3s kubectl -n nextcloud logs deploy/notify-push --tail=20 |
| Previews comem o disco | occ preview:cleanup # never rm: previews live in the database |
| Avisos após um upgrade | occ db:add-missing-indicesocc app:list --disabled |
| Depois de restaurar um backup | occ maintenance:data-fingerprint |
🎯 As lições
- O que é valioso – banco de dados e dados – pertence ao host, o que é substituível, ao cluster.
- Configuração em camadas: arquivos
*.config.phpposteriores vencem, o notify_push lê apenas oconfig.php. - Depois de
occ upgradeouapp:update, reinicie o pod, senão o bytecode antigo continua rodando. - Rolling update só onde duas versões podem rodar ao mesmo tempo.
- Depois de uma migração, limpe o índice de arquivos antigo.
⚖️ Alternativas – e por que Nextcloud
| Opção | Ponto forte | Por que não aqui |
|---|---|---|
| Seafile | Sincronização muito mais rápida, armazenamento em nível de bloco | Menos recursos de groupware, dados não guardados como arquivos simples. |
| ownCloud Infinite Scale | Go, sem PHP, sem banco de dados | Arquitetura diferente, ecossistema de apps menor, significaria migrar tudo. |
| Uma nuvem proprietária | Nada para operar | Dados e acesso decididos por um fornecedor – o oposto do objetivo. |
| Nextcloud | Funcionalidades, apps, clientes, comunidade, os dados existentes | Escolhido. |
O Nextcloud não é difícil de instalar; é exigente de operar bem, porque é uma dúzia de serviços fingindo ser um só. Separá-los pelo critério “precioso ou substituível” – banco de dados e arquivos no host, PHP e office no cluster – tornou cada parte mais simples de entender. Os erros deste post estiveram quase todos nas costuras entre elas.
