Corrigir o problema da página em branco/tela branca da morte no ownCloud: escolha o caminho de recuperação correto

Comece por decidir que tipo de página em branco você realmente tem.

A "tela branca da morte" do ownCloud é um sintoma, não um diagnóstico. A melhor solução depende de se o navegador recebeu um erro do servidor, recebeu HTML válido, mas não conseguiu carregar o JavaScript ou o CSS, ou acessou um proxy reverso que não conseguiu se conectar ao ownCloud.

Essa distinção é importante porque as vantagens e desvantagens são muito diferentes. Desativar um aplicativo de terceiros apresenta um risco relativamente baixo quando uma exceção do PHP identifica esse aplicativo. Alterar a propriedade de arquivos em toda a instalação é muito mais invasivo e não deve ser a primeira resposta a um erro de JavaScript. Da mesma forma, reiniciar todos os serviços pode mascarar temporariamente um problema sem revelar se ele foi causado pelo PHP, por um proxy, por uma atualização ou por um aplicativo.

Este guia abrange o ownCloud Classic. De acordo com a documentação atual do ownCloud Classic 11, a versão 11 é suportada como uma implantação baseada em Docker, com o sistema operacional, o ambiente de execução PHP, o banco de dados e o Apache dentro dos contêineres fornecidos pelo ownCloud. Instalações mais antigas, da versão 10.x, ainda podem usar um layout tradicional de servidor web e PHP-FPM. Use o branch de comando que corresponde à sua implantação. Consulte os requisitos de sistema do ownCloud Classic 11 .

1. A página em branco está retornando HTTP 500 ou o navegador está apresentando falha após o HTTP 200?

Abra as ferramentas de desenvolvedor do navegador e examine as guias Rede e Console . Teste também o endpoint a partir de um terminal:

curl -I https://cloud.example.com/
curl -sS -o /dev/null -w '%{http_code}\n' https://cloud.example.com/

Legenda: Uma resposta 500 do lado do servidor aponta para o ownCloud, PHP, o banco de dados ou a pilha web, em vez de um simples problema de renderização do navegador.

Se o documento principal retornar 500 ou 502/503 , priorize os logs do servidor e do proxy. Se o documento principal retornar 200 , mas os pacotes JavaScript falharem com 404, 403 ou exceções de script, priorize os caminhos dos recursos, a reescrita do proxy reverso, os temas, o cache ou a compatibilidade do aplicativo. Se apenas um navegador for afetado, teste em uma janela anônima e em outro navegador compatível antes de alterar o servidor.

2. O problema começou após uma atualização do ownCloud ou do PHP?

Esta é uma das perguntas mais importantes, pois pode restringir imediatamente a origem da falha. As notas de lançamento atuais do ownCloud indicam que o ownCloud Classic 11 elevou a versão mínima do PHP para PHP 8.3 e que o ownCloud Classic 11 é compatível apenas com Docker. Uma instalação legada do ownCloud 10.x segue regras de compatibilidade de PHP diferentes, portanto, não copie recomendações de PHP de outra versão principal.

Para uma instalação tradicional do ownCloud 10.x, execute o comando a partir do diretório do ownCloud:

sudo -u www-data ./occ status
php -v

Para o ownCloud Classic 11, execute o OCC por meio da implantação do Compose:

docker compose exec owncloud occ status
docker compose exec owncloud php -v

Legenda: Verificar as versões instaladas do ownCloud e do PHP é especialmente importante quando a tela branca aparece imediatamente após uma atualização.

Compare o resultado com as notas de lançamento da versão que você está usando. As notas de lançamento oficiais do ownCloud são a fonte correta para as versões mínimas atuais e alterações que podem causar incompatibilidade. Fazer um downgrade não é uma solução genérica segura: a documentação do ownCloud alerta que o downgrade não é suportado, pois pode corromper os dados.

3. Qual registro lhe fornece o primeiro erro concreto?

Os registros geralmente são mais úteis do que alterações de configuração por tentativa e erro. O manual de administração do ownCloud recomenda o uso do registro do ownCloud para diagnosticar problemas; por padrão, o registro é armazenado no diretório de dados configurado, a menos que um diretório diferente logfileseja definido.

Em uma instalação tradicional, os exemplos incluem:

tail -n 100 /path/to/owncloud/data/owncloud.log
journalctl -u php-fpm --since "15 minutes ago"
journalctl -u apache2 --since "15 minutes ago"
journalctl -u nginx --since "15 minutes ago"

No ownCloud Classic 11, inspecione os serviços do Compose:

docker compose logs --tail=200 owncloud
docker compose ps

Legenda: Um erro fatal do PHP ou um rastreamento de pilha que nomeia um aplicativo ou classe oferece um alvo de solução de problemas muito mais seguro do que alterar configurações de servidor não relacionadas.

Procure pela primeira exceção fatal relacionada à requisição com falha, e não apenas pela sequência final de erros. Categorias comuns incluem uma classe PHP ausente, um aplicativo incompatível, falha na conexão com o banco de dados, configuração ilegível, arquivos de código ausentes ou uma exceção durante uma atualização incompleta.

A documentação de registro de logs do ownCloud afirma que o registro de DEBUG pode ajudar durante o diagnóstico, mas gera uma quantidade substancial de informações e pode afetar o desempenho. Se você aumentar temporariamente o nível de log, retorne-o para um valor menos detalhado após coletar as evidências. Consulte a configuração de registro de logs do ownCloud .

4. Devo desativar um aplicativo de terceiros?

Escolha este caminho quando o erro mencionar um aplicativo não essencial, quando a página em branco aparecer após a instalação ou atualização de um aplicativo ou quando a falha ocorrer durante uma atualização do ownCloud. As orientações de solução de problemas do ownCloud recomendam explicitamente desativar aplicativos de terceiros para solucionar problemas e antes de atualizações.

Liste os aplicativos primeiro. No ownCloud 10.x:

sudo -u www-data ./occ app:list
sudo -u www-data ./occ app:disable APP_ID

No ownCloud 11:

docker compose exec owncloud occ app:list
docker compose exec owncloud occ app:disable APP_ID

Legenda: Desativar apenas o aplicativo implicado pelos registros é menos disruptivo do que desativar vários componentes ou alterar toda a pilha da web.

A desvantagem é a funcionalidade: os usuários perdem o acesso ao aplicativo até que ele seja atualizado ou reativado. Isso geralmente é preferível a desativar os serviços principais do ownCloud. A documentação do OCC também observa que vários aplicativos principais não podem ser desativados, incluindo DAV, FederatedFileSharing, Files e Files_External. Consulte as orientações gerais oficiais para solução de problemas e a referência de comandos do OCC .

5. Quando vale a pena corrigir as permissões?

Problemas de permissões são fortes suspeitos quando o log contém erros Permission denied, como uma implantação recente que copiou arquivos app/config como o usuário errado ou uma atualização que substituiu arquivos com proprietários incorretos. São suspeitos com pouca probabilidade quando a única evidência é um erro de JavaScript no navegador.

Coloque o sistema em modo de manutenção antes de realizar trabalhos de reparo que interrompam as operações. Para ownCloud 11:

docker compose exec owncloud occ maintenance:mode --on

Para uma implementação tradicional da versão 10.x:

sudo -u www-data ./occ maintenance:mode --on

Legenda: O modo de manutenção reduz a atividade do usuário enquanto você investiga erros de propriedade ou permissões de arquivo que já foram comprovados por evidências de registro.

Não execute chmod 777receitas recursivas genéricas nem copie permissões de uma versão não relacionada. O manual atual do ownCloud 11 documenta a propriedade e os modos específicos para arquivos adicionados manualmente em diretórios montados pelo Docker apps: configpropriedade www-data:root, arquivos do aplicativo 0644, diretórios do aplicativo 0751e arquivos de configuração adicionados 0644. Ele também documenta 0640as alterações manuais .htaccess. .user.iniUse a documentação de atualização manual do ownCloud 11 como referência específica da versão.

6. Você deve alterar os módulos PHP, o OPcache ou as configurações de memória?

Somente quando os registros ou verificações de compatibilidade apontarem para isso. Essa abordagem tem um impacto muito maior do que desativar um único aplicativo problemático. A ausência de uma extensão PHP necessária pode impedir a execução do código, enquanto uma configuração PHP incorreta pode afetar todos os aplicativos PHP no host.

Para uma infraestrutura PHP legada gerenciada pelo host, verifique o que o ambiente de execução da web realmente carrega:

php -m
php --ini
php -r 'phpinfo();' | grep opcache.enable

Legenda: As verificações de módulos PHP e OPcache são úteis quando os logs do servidor indicam ausência de extensões ou incompatibilidade em tempo de execução, mas não devem ser a primeira alteração feita sem justificativa.

Para o ownCloud 11, a imagem oficial gerencia o ambiente de execução do PHP, portanto, alterar os pacotes PHP do host geralmente não é a melhor abordagem. O ownCloud documenta que o OPcache está habilitado por padrão em sua imagem Docker. Consulte a documentação de cache de memória do ownCloud .

Se você suspeitar de cache de opcode desatualizado após substituir manualmente arquivos PHP em uma instalação antiga, reiniciar o PHP-FPM ou o serviço web/PHP relevante pode limpar o cache de opcode local do processo. A desvantagem é uma breve interrupção e o desempenho do cache frio posteriormente. Faça isso após corrigir os arquivos subjacentes, e não como um substituto para identificar o erro.

7. Houve alguma interrupção na atualização ou os arquivos principais estão inconsistentes?

Se a página em branco aparecer durante ou imediatamente após uma atualização, verifique primeiro o estado da atualização. A documentação de atualização do ownCloud recomenda o uso do OCC para o processo de atualização e reparo, em vez de manipular o banco de dados manualmente.

Para ownCloud 11:

docker compose exec owncloud occ status
docker compose exec owncloud occ upgrade
docker compose exec owncloud occ maintenance:repair
docker compose exec owncloud occ integrity:check-core

Para o ownCloud 10.x, utilize os comandos OCC equivalentes sob o usuário do servidor web:

sudo -u www-data ./occ status
sudo -u www-data ./occ maintenance:repair
sudo -u www-data ./occ integrity:check-core

Legenda: O reparo do OCC é apropriado para uma atualização interrompida ou inconsistente, enquanto as verificações de integridade podem identificar arquivos principais assinados modificados ou ausentes.

Os resultados de integridade de código precisam de interpretação. Os documentos do ownCloud INVALID_HASH, como `<code-signing>`, FILE_MISSING`<code-signing>` e `<code-signing>`, EXTRA_FILEsão condições distintas. Não edite o arquivo signature.jsonpara fazer os avisos desaparecerem. A documentação atual do ownCloud 11 também torna a assinatura de aplicativos de terceiros obrigatória para instalação, atualizações e ativação. Consulte a documentação de assinatura de código do ownCloud .

8. Como você deve verificar a correção?

Uma boa recuperação não se resume a "a página deixar de estar branca". Verifique todo o caminho da requisição:

• A página principal do ownCloud retorna o status HTTP esperado em vez de 500/502/503.
• As ferramentas de desenvolvedor do navegador não mostram nenhum erro fatal recorrente de JavaScript ou pacote principal ausente.
• O log do ownCloud não registra imediatamente uma nova exceção fatal para a mesma solicitação.
• occ statusO relatório indica uma instância instalada e nenhuma necessidade inesperada de atualização.
• O modo de manutenção é desativado após a conclusão da manutenção.
• Um usuário de teste pode fazer login e abrir a página Arquivos.

Para ownCloud 11:

docker compose exec owncloud occ maintenance:mode --off
docker compose exec owncloud occ status
curl -I https://cloud.example.com/

Legenda: A recuperação deve ser confirmada em ambas as camadas: a interface do ownCloud carrega e o status do servidor e as verificações HTTP permanecem íntegros.

Qual solução oferece a melhor relação risco-benefício?

O que não fazer quando o ownCloud exibe uma tela branca.

• Não habilite o PHP display_errorsem um site de produção público apenas para expor rastreamentos de pilha ao navegador; use os logs do servidor em vez disso.
• Não defina recursivamente todas as permissões da árvore ownCloud como de escrita para todos.
• Não faça downgrade do ownCloud como uma reversão rápida, a menos que esteja restaurando um backup compatível em um ambiente compatível.
• Não exclua aleatoriamente o diretório de dados, os dados do aplicativo, as tabelas do banco de dados ou os diretórios de cache.
• Não desative todos os aplicativos de uma vez quando for possível isolar um aplicativo específico.
• Não edite arquivos principais assinados signature.jsonapenas para suprimir erros de integridade.

Quando é que se deve intensificar as medidas em vez de continuar a experimentar?

Pare de fazer alterações quando os registros indicarem corrupção do banco de dados, problemas com a chave de criptografia, falhas repetidas de integridade do núcleo após uma restauração limpa ou um estado de atualização que não pode ser concluído com o fluxo de trabalho OCC documentado. Além disso, acione o suporte técnico quando a página em branco afetar um cluster de produção e você não puder isolar um único nó sem comprometer a consistência dos dados.

Antes de abrir um chamado de suporte, a ownCloud recomenda coletar um relatório de configuração e os logs relevantes. Para a versão 10.x da ownCloud, o comando documentado é:

sudo -u www-data ./occ configreport:generate > config_report.txt

Utilize o método de execução do OCC correspondente à sua implementação e revise a saída em busca de segredos antes de compartilhá-la fora da sua organização. O guia de coleta de logs e configurações do ownCloud explica o que os engenheiros de suporte normalmente precisam.

Referências oficiais

• Solução de problemas gerais do ownCloud Classic 11
• Requisitos de sistema do ownCloud Classic 11
• Notas de lançamento do servidor ownCloud
• Atualização manual do ownCloud Classic 11
• Configuração de registro do ownCloud