Corrigir o modo de manutenção do Nextcloud travado com OCC

Você concluiu uma atualização do Nextcloud, mas todos ainda veem a página de manutenção. Ou uma atualização foi interrompida e o site nunca mais voltou a ficar online. O comando OCC para desativar o modo de manutenção é curto, mas executá-lo antes de verificar o estado da atualização pode expor uma instalação incompleta. Comece confirmando qual instância do Nextcloud você está administrando e se uma atualização do banco de dados ainda é necessária.

Exemplo ilustrativo: Imagine um pequeno escritório executando o Nextcloud no Ubuntu. Uma atualização agendada foi interrompida após a implantação de novos arquivos de código, e a página da web ainda indica que o servidor está em modo de manutenção. Este exemplo é hipotético; trata-se de um tópico para aplicar as verificações abaixo, não um relato de um incidente ou teste real.

O que significa modo de manutenção?

O modo de manutenção do Nextcloud bloqueia o acesso normal do usuário enquanto um administrador realiza tarefas como uma atualização ou backup. Trata-se de um estado que afeta todo o servidor, portanto, os usuários podem ver um aviso de manutenção mesmo quando o servidor web estiver em execução. O Manual de Administração atual do Nextcloud documenta o comando OCC para ativar ou desativar esse modo e observa que os usuários podem precisar atualizar o navegador após a desativação.

No exemplo de escritório, a página de manutenção sozinha não informa ao administrador se a atualização foi concluída. É necessário consultar o próprio Nextcloud antes de alterar o modo.

Etapa 1: Confirme o tipo de instalação e o caminho do OCC

Os exemplos de comando aqui apresentados são para uma instalação convencional do Nextcloud baseada em arquivos no Ubuntu, com o código em /var/www/nextcloude a conta do servidor web denominada www-data. O Nextcloud documenta que occreside no diretório de instalação e deve ser executado como o usuário HTTP; no Debian e no Ubuntu, esse usuário é normalmente www-data.

Para este layout padrão, insira o diretório de instalação:

cd /var/www/nextcloud

Se seus arquivos do Nextcloud estiverem em outro local, use o caminho real. Snap, Docker, appliances e hospedagem gerenciada usam wrappers de comando ou layouts de sistema de arquivos diferentes. Não execute o comando `host` em uma instalação de contêiner nem assuma que o caminho do arquivo se aplica a essas implantações. Siga as instruções de atualização para o seu método de instalação, conforme descrito no guia oficial de atualização do Nextcloud .

No exemplo do Office, o administrador verifica as notas de implantação e confirma que se trata de uma instalação de arquivo antes de executar o OCC.

Passo 2: Verifique o status do Nextcloud antes de desativar a manutenção.

Execute o OCC como a conta do servidor web para que os arquivos e a configuração mantenham a propriedade esperada:

sudo -E -u www-data php occ status

Observe os campos maintenancee needsDbUpgrade. As versões atuais também suportam um código de saída de status:

sudo -E -u www-data php occ status -e
echo $?

Os códigos de saída documentados são úteis quando a saída está sendo verificada por um script: 0indica operação normal, 1significa que o modo de manutenção está ativado e 2significa que occ upgradeé necessário. A saída de status simples também deve ser revisada; não use apenas o código de saída para decidir se deve reabrir o site.

Para o hipotético servidor de escritório, se needsDbUpgrade`is` for verdadeiro ou status -eretornar `true` 2, o próximo passo correto é concluir a atualização, e não simplesmente desativar o modo de manutenção.

Etapa 3: Conclua primeiro uma atualização incompleta.

Se uma atualização de código do Nextcloud foi implantada intencionalmente e o OCC relata que a atualização do banco de dados é necessária, faça ou verifique um backup atual do banco de dados, da configuração e dos dados antes de prosseguir. Em seguida, execute o comando documentado a partir do diretório de instalação:

sudo -E -u www-data php occ upgrade

Leia a saída do comando e aguarde a conclusão. Não interrompa o processo, pois a página da web pode parecer inalterada enquanto as migrações estão em andamento. O atualizador integrado pode manter o modo de manutenção ativado quando a substituição do código occ upgradefalhar. Se o próprio atualizador não concluir a substituição do código, consulte o registro de alterações e retome o processo de atualização apropriado para sua instalação, em vez de prosseguir diretamente para a atualização . As instruções do atualizador integradomaintenance:mode --off do Nextcloud explicam as fases da atualização e indicam o registro de alterações como um recurso de diagnóstico.

No exemplo, o administrador do escritório só executaria o comando occ upgradese o status indicasse que a migração do banco de dados ainda está pendente e o novo código esperado já está implementado. Se o comando reportar um erro, o servidor permanecerá indisponível e o erro será investigado primeiro.

Passo 4: Desative o modo de manutenção com o OCC

Quando a atualização estiver concluída e o status não indicar mais que uma atualização do banco de dados é necessária, desative o modo de manutenção usando o comando integrado do Nextcloud:

sudo -E -u www-data php occ maintenance:mode --off

Um comando executado com sucesso informa que o modo de manutenção foi desativado. Esta é a maneira recomendada de alterar o modo para uma instalação padrão; além disso, mantém a alteração de estado dentro da própria interface de comando do Nextcloud, em vez de depender de edições manuais no arquivo config.php.

O administrador do escritório de exemplo agora executa esse comando somente após a conclusão da migração. Se nenhuma atualização estiver em andamento e o status indicar que a instalação está pronta, o mesmo comando pode limpar um indicador de manutenção que tenha sido deixado ativado após uma manutenção planejada.

Etapa 5: Verifique o estado e a interface web.

Verifique o status novamente:

sudo -E -u www-data php occ status
sudo -E -u www-data php occ status -e

Para uma instalação bem-sucedida, espere ver as mensagens `<exit>` maintenance: false, needsDbUpgrade: false`<exit>` e um código de saída normal 0. Em seguida, abra o site em uma nova janela anônima do navegador e faça login com uma conta de administrador. Peça a um usuário comum que atualize a página antes de presumir que a sessão dele ainda está bloqueada.

No cenário ilustrativo, sucesso significa que tanto o status do OCC quanto a página da web confirmam que a instância está online novamente. O exemplo hipotético não afirma que qualquer comando foi de fato executado ou que um servidor real foi reparado.

Se a página de manutenção permanecer

OCC afirma que a manutenção é falsa.

Confirme se você executou o OCC na mesma instalação que serve a URL. Isso é importante em uma implantação com balanceamento de carga, um host Docker com vários contêineres ou um servidor com diretórios Nextcloud antigos e novos lado a lado. Verifique o caminho real do diretório raiz ou do contêiner e consulte a instância por trás da URL afetada. Se cada nó da web tiver sua própria configuração, confirme se todos os nós compartilham a configuração e o banco de dados desejados.

Se a instância correta reportar que a manutenção está desativada, compare a página da origem do servidor com o URL público. Um proxy reverso ou cache pode estar fornecendo uma resposta desatualizada. Limpe ou ignore esse cache somente após verificar qual camada retornou a página de manutenção.

O OCC não pode ser executado ou retorna um erro do PHP.

Verifique se o comando utiliza a versão do PHP CLI e as extensões necessárias compatíveis com a instalação web. O Nextcloud observa que o APCu está desativado por padrão para o PHP CLI e pode causar erros de OCC quando o APCu está configurado como um cache local. O manual do Nextcloud documenta como ativá-lo apc.enable_clina configuração do PHP CLI ou adicioná-lo --define apc.enable_cli=1ao comando PHP quando apropriado.

sudo -E -u www-data php --define apc.enable_cli=1 occ status

Use esta solução apenas quando o erro indicar um problema com a CLI do APCu; ela não resolve todos os erros do PHP. Verifique também se o comando está sendo executado com o usuário web correto e a partir do diretório de instalação correto.

A atualização do banco de dados ainda é necessária.

Não force a desativação do sinalizador de manutenção para ocultar este status. Verifique novamente a saída e os registros do atualizador, certifique-se de que a versão correta do código Nextcloud esteja instalada e conclua o procedimento de atualização compatível com o seu tipo de instalação. Consulte os documentos de referência oficiais do sistema OCC e do comando de manutençãomaintenance:mode , statusbem como o guia de atualização pela linha de comando.

Mantenha o período de manutenção controlado.

Desativar o modo de manutenção permite que os usuários acessem a instância novamente, portanto, confirme se a atualização do banco de dados e qualquer substituição de código necessária foram concluídas primeiro. Evite excluir manualmente os arquivos de atualização ou editar a configuração de manutenção no arquivo de configuração como primeira medida; isso pode mascarar o problema sem concluir o trabalho que acionou o modo de manutenção.

Para o escritório hipotético, a decisão segura é simples: verifique se a instalação está correta, inspecione o status, conclua qualquer atualização necessária e, em seguida, execute maintenance:mode --offe verifique o OCC e o navegador. Se a atualização não puder ser concluída sem problemas, mantenha o modo de manutenção ativado e solucione o problema a partir do log do atualizador ou do procedimento de recuperação específico da instalação.