Upgrade do Moodle 5.2 interrompido: como recuperamos o site sem perder dados

Caso real de produção, contado sem identificar o cliente. Uma entidade que oferece cursos online, com quase 2 mil usuários cadastrados, decidiu atualizar o Moodle do 5.0 para o 5.2. A atualização parou no meio do caminho e o site inteiro saiu do ar. O suporte da hospedagem tentou, não achou a causa, e a plataforma ficou parada com alunos matriculados esperando.

O final é bom: nenhum usuário, curso, nota ou matrícula foi perdido. Mas o caminho até lá mostra bem por que o salto para o Moodle 5.1 ou mais novo pede preparação.

O que aconteceu

O código do Moodle foi trocado pela versão 5.2 e o banco de dados chegou a ser atualizado. A configuração do servidor e o arquivo config.php, porém, continuaram no formato antigo, de antes do 5.1. Resultado: todas as páginas, inclusive a de login, passaram a mostrar um erro, e ninguém conseguia entrar.

Esse estado é o pior dos dois mundos. O banco já estava no 5.2, então voltar o código antigo não resolvia. E o código novo não rodava, porque o ambiente não estava preparado para ele.

A mensagem de erro enganava

A tela mostrava algo como "Class cache not found". Quem lê isso pensa em cache corrompido, plugin quebrado ou banco danificado, e começa a limpar caches, desativar plugins e mexer onde não precisa. Foi o que tinha sido tentado.

Para achar a causa real, montamos uma cópia do código e do banco num ambiente de teste e reproduzimos o erro com o registro detalhado ligado. Por trás da mensagem genérica estava outra: o Moodle não encontrava um dos seus próprios subsistemas, porque estava procurando os arquivos no lugar errado.

A causa real: a pasta public

A partir do Moodle 5.1, os arquivos acessíveis pela web ficam numa pasta public, e o servidor precisa apontar para ela. Explicamos essa mudança em detalhe em página em branco ou 404 depois de atualizar. Neste caso, o config.php continuava dizendo ao Moodle que tudo estava na raiz, no formato antigo, enquanto o código novo esperava a estrutura nova. Cada página quebrava logo no começo do carregamento.

A conclusão mais importante do diagnóstico: o banco de dados e a pasta de arquivos dos alunos estavam sãos. Usuários, cursos e matrículas estavam todos lá. O que precisava ser refeito era só o código e a forma como o servidor o entregava.

O backup que não baixava inteiro

A primeira ideia de todo mundo é "restaura o backup". Havia dois backups automáticos no painel da hospedagem: um feito logo depois da quebra, que só guardava o problema, e um da madrugada anterior, que servia. Só que o download do backup completo era cortado no meio por um limite do painel e nunca chegava inteiro. O banco de dados sozinho, bem menor, baixava sem problema.

Isso não impediu a recuperação, porque os dados de produção estavam sãos. Mas é um alerta: backup que você nunca tentou baixar e restaurar não é um plano. Veja como fazer backup do Moodle do jeito certo.

Como recuperamos sem apagar nada

1. Cópia limpa ao ladoInstalamos o pacote oficial do Moodle 5.2, já na estrutura com a pasta public, numa subpasta da própria hospedagem do cliente, ligada ao banco de dados e aos arquivos reais. Os plugins e o tema em uso foram copiados e conferidos.
2. Site principal em manutençãoEnquanto isso, o endereço principal mostrava uma página de manutenção, para os alunos não verem erro.
3. Validação pelo clienteA equipe do cliente entrou na cópia, conferiu login, cursos e conteúdos e aprovou a troca.
4. Troca de pastasA instalação quebrada foi movida inteira para uma pasta de arquivo, fora do alcance da web, e a cópia limpa passou a ocupar o lugar dela. Depois, só dois ajustes: o endereço do site no config.php e a regra de reescrita do servidor.
5. Conferência no arPágina inicial, login, tema e imagens respondendo normalmente, com caches limpos.

Depois da virada: o que ainda estava errado

Site no ar não é o fim. Na revisão pós-virada apareceram dois problemas que vinham de antes:

• O cron estava parado desde o dia da quebra. As tarefas agendadas apontavam para uma cópia antiga e incompleta do Moodle, que morria ao iniciar. Sem cron, e-mails, conclusões e limpezas não rodam. Ficou uma única tarefa, a cada minuto, apontando para a instalação certa. Veja cron do Moodle que não roda.
• Uma tarefa limpava todos os caches a cada minuto. A origem não estava documentada. Ela deixava o Moodle mais lento o tempo todo, porque o cache nunca chegava a funcionar. Foi removida.

Resultado final: o mesmo Moodle de antes, agora na versão 5.2, com todos os usuários, cursos e matrículas, e a instalação antiga guardada fora da web caso fosse preciso consultar algo.

Checklist antes do seu upgrade para o 5.1 ou mais novo

• Teste numa cópia com o banco de dados real antes de mexer na produção.
• Prepare o servidor para a pasta public antes de trocar o código. Em hospedagem compartilhada, confira se o painel permite mudar a raiz do domínio.
• Confira a versão do PHP exigida pela versão de destino. Veja qual versão do PHP o Moodle pede.
• Tenha um backup que você já baixou e restaurou, com banco de dados e arquivos da mesma data.
• Não apague a instalação antiga até a nova estar validada.
• Depois da virada, confira o cron e as tarefas agendadas do servidor.
• Vindo de uma versão bem antiga? O caminho é outro: upgrade encadeado, versão por versão.

Perguntas frequentes

Leia também

Suporte MoodleMoodle em branco ou 404 depois de atualizarCaso técnicoMigrar um Moodle 3.x muito antigo: o upgrade encadeadoSegurança & backupComo fazer backup do Moodle (e restaurar sem susto)