Magento 2 fora do ar após deploy: como localizar a falha e recuperar a loja

Magento 2 fora do ar após deploy não significa necessariamente que todo o código publicado esteja errado. A indisponibilidade pode ser causada por modo de manutenção ativo, dependência incompatível, atualização incompleta do banco, arquivos gerados ausentes, permissões incorretas ou um serviço que não voltou a responder.

Antes de limpar caches, recompilar tudo ou restaurar o servidor, preserve as mensagens de erro e identifique até onde a requisição consegue chegar. O roteiro abaixo ajuda a recuperar a operação com menos tentativas às cegas e reduz o risco de esconder a causa original.

Magento 2 fora do ar após deploy: descubra primeiro o alcance da falha

Comece testando separadamente a página inicial, uma página de produto, o checkout, o Admin e uma URL estática. Também verifique a resposta diretamente na origem, quando houver balanceador, CDN ou Varnish na frente da aplicação.

Os resultados ajudam a delimitar o problema:

• Frontend e Admin indisponíveis: investigue PHP, dependências, banco, permissões e serviços compartilhados.
• Frontend quebrado, mas Admin acessível: verifique tema, conteúdo estático, JavaScript, Full Page Cache e customizações do storefront.
• Somente Admin indisponível: avalie rota administrativa, autenticação, sessão, cookies e módulos executados nessa área.
• HTML abre sem estilos: a falha provavelmente está na publicação ou entrega dos arquivos estáticos.
• Erro apenas no checkout: priorize módulos de pagamento, frete, impostos e customizações ativadas no deploy.

Registre URL, horário, código HTTP e identificador apresentado na tela. Se a resposta for HTTP 500, siga também o roteiro específico para diagnosticar erro 500 no Magento 2 sem apagar evidências.

1. Confirme se o modo de manutenção continua ativo

Um pipeline interrompido pode ativar o modo de manutenção e não executar a etapa final que o desativa. Consulte o estado usando o mesmo usuário do sistema responsável pelos arquivos da aplicação:

php bin/magento maintenance:status

Se o deploy terminou corretamente e as verificações básicas foram concluídas, o modo pode ser desativado com:

php bin/magento maintenance:disable

Não faça isso enquanto houver atualização de banco, compilação ou troca incompleta de artefatos. Liberar tráfego durante essas operações pode expor aos clientes uma aplicação inconsistente.

2. Preserve os erros antes de executar correções

Copie os registros correspondentes ao momento do deploy. Os locais variam conforme a infraestrutura, mas normalmente incluem:

• var/log/system.log e var/log/exception.log;
• arquivos em var/report/;
• logs do PHP-FPM e do servidor web;
• saída do pipeline, Composer e comandos do Magento;
• eventos do contêiner, balanceador ou plataforma de hospedagem.

Procure a primeira exceção, e não apenas mensagens produzidas em cascata. Uma classe ausente, por exemplo, pode gerar vários erros posteriores de injeção de dependência e cache. Anote também o commit, pacote ou artefato implantado para que a equipe consiga reproduzir a mesma combinação.

3. Verifique PHP, extensões e pacotes do Composer

Se o artefato foi construído em uma máquina e executado em outra, o ambiente de produção pode não atender aos mesmos requisitos. Compare a versão do PHP utilizada pela linha de comando com a usada pelo PHP-FPM e confira os requisitos declarados pelos pacotes:

php -v
composer check-platform-reqs
composer validate --no-check-publish

Mensagens como “class not found”, “interface not found” ou falha de autoload podem indicar diretório vendor incompleto, pacote removido ou autoloader gerado com dependências diferentes. Não execute uma atualização ampla do Composer diretamente na produção para tentar corrigir o problema. Reproduza a instalação a partir dos arquivos composer.json e composer.lock aprovados, preferencialmente no processo de construção do artefato.

4. Confira se código, configuração e módulos estão alinhados

Um módulo pode estar presente no código, mas desabilitado na configuração — ou o contrário. Consulte o estado antes de ativar ou remover componentes:

php bin/magento module:status

Compare também o app/etc/config.php implantado com a versão esperada no repositório. Se o deploy removeu uma extensão sem atualizar corretamente a configuração e o banco, o bootstrap pode tentar carregar classes inexistentes.

Evite editar config.php manualmente como primeira medida. Identifique primeiro se houve falha na geração, versionamento ou implantação desse arquivo.

5. Descubra se o banco exige atualização

Quando o código novo espera tabelas, colunas ou patches de dados ainda não aplicados, a loja pode falhar logo após a publicação. Verifique o estado com:

php bin/magento setup:db:status

Se houver alterações pendentes, confirme se o pacote implantado é o correto, faça backup compatível com o procedimento de reversão e execute a atualização dentro da janela de manutenção:

php bin/magento setup:upgrade --keep-generated

Esse comando altera o banco e não deve ser usado apenas para “ver se resolve”. Em especial, uma reversão de código pode não desfazer mudanças de esquema ou dados. O plano de rollback precisa considerar aplicação e banco como partes do mesmo release.

6. Inspecione arquivos gerados, estáticos e permissões

Uma publicação incompleta pode deixar classes geradas ou conteúdo estático incompatíveis com o código atual. Antes de recompilar, confira o modo da aplicação, o espaço disponível e a existência dos diretórios esperados:

php bin/magento deploy:mode:show
df -h
df -i

Disco cheio ou falta de inodes pode interromper a extração do artefato sem produzir uma mensagem clara no navegador. Se o HTML abre, mas CSS, fontes ou JavaScript retornam 404, confira a publicação de pub/static, os idiomas utilizados e a configuração de URLs estáticas.

A compilação de dependências e o deploy de conteúdo estático devem seguir o modo da aplicação e o processo definido para o ambiente:

php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f pt_BR en_US

Execute essas rotinas em produção somente durante manutenção ou na construção do artefato, conforme a arquitetura da loja. Não aplique chmod 777 como correção genérica. Ajuste proprietário, grupo e permissões de acordo com os usuários reais do servidor web, PHP e pipeline.

7. Teste Redis, busca, banco e outros serviços

O deploy pode estar correto enquanto uma dependência externa permanece indisponível. Verifique conectividade, resolução de nomes, portas, credenciais e limites dos serviços usados pela aplicação. Entre os componentes mais comuns estão banco de dados, Redis, OpenSearch, filas e armazenamento compartilhado.

Se os erros indicarem conexão recusada, timeout ou limite de clientes no cache, consulte o diagnóstico de Redis lento ou indisponível no Magento 2. Reiniciar o serviço sem coletar métricas pode aliviar temporariamente o sintoma e eliminar pistas sobre consumo de memória ou excesso de conexões.

8. Limpe somente o cache necessário e valide por camadas

Confira o estado dos caches antes de invalidar tudo:

php bin/magento cache:status

Depois de corrigir a causa, limpe os tipos relacionados à alteração e reteste diretamente na aplicação. Em seguida, avance para Varnish, CDN e balanceador. Essa ordem impede que uma resposta antiga seja confundida com falha do código novo.

Se a origem responde corretamente, mas o domínio público continua indisponível ou entrega páginas antigas, verifique a camada de cache. O guia sobre HIT, MISS e PASS no Varnish do Magento 2 ajuda a interpretar o comportamento sem atribuir toda falha ao servidor.

Quando é melhor reverter o deploy?

A reversão tende a ser a opção mais segura quando a causa não pode ser corrigida dentro da janela operacional, o checkout permanece comprometido ou o release introduziu inconsistência ampla. Porém, o rollback precisa ser controlado.

Confirme antes:

• se a versão anterior do artefato está íntegra e identificada;
• se o deploy alterou o esquema ou os dados do banco;
• se arquivos enviados por clientes ficam fora da troca de release;
• se caches e processos assíncronos carregam código antigo;
• se pedidos ou pagamentos foram processados durante a falha.

Após recuperar o acesso, teste criação de conta, login, carrinho, frete, checkout, pagamento, e-mails e rotinas agendadas. Uma página inicial disponível não comprova que a operação voltou por completo.

Como evitar que o próximo deploy derrube a loja

Inclua no pipeline verificações de requisitos do PHP, instalação determinística do Composer, compilação, publicação de estáticos e testes mínimos de saúde. O artefato deve ser imutável, identificável e semelhante ao que foi validado em homologação.

Também defina critérios objetivos de continuidade e reversão: código HTTP da página de saúde, acesso ao banco e ao cache, abertura de produto, disponibilidade do checkout e execução de uma operação segura no Admin. Para problemas que aparecem como degradação, e não indisponibilidade total, use os testes de performance antes de ampliar o servidor.

Conclusão

Quando o Magento 2 fica fora do ar após deploy, a recuperação mais segura começa pela preservação dos erros e pela separação das camadas afetadas. Manutenção, Composer, módulos, banco, arquivos gerados, permissões e serviços devem ser verificados em uma ordem previsível antes de limpar tudo ou restaurar o ambiente.

Se a equipe não consegue identificar a primeira falha ou precisa recuperar a loja sem comprometer pedidos e pagamentos, um diagnóstico técnico especializado pode ajudar a definir entre correção pontual e rollback controlado.

Perguntas frequentes

Por que o Magento 2 fica fora do ar depois de um deploy?

As causas comuns incluem modo de manutenção ativo, dependências incompatíveis, banco desatualizado, módulo ausente, conteúdo estático incompleto, permissões incorretas, falta de espaço ou indisponibilidade de serviços como Redis e banco de dados.

Posso executar setup:upgrade para tentar recuperar a loja?

Somente após confirmar que existem atualizações de banco pendentes e que o código implantado é o correto. O comando pode alterar esquema e dados, por isso exige backup, janela de manutenção e plano de reversão.

Limpar todos os caches resolve uma falha após deploy?

Pode remover respostas antigas, mas não corrige pacote ausente, erro de banco, classe inexistente ou serviço indisponível. Limpar tudo antes de coletar evidências também pode dificultar o diagnóstico.

Quando devo fazer rollback do deploy?

Considere a reversão quando a causa não puder ser corrigida com segurança dentro da janela operacional ou quando checkout e pedidos estiverem comprometidos. Verifique antes se houve mudanças no banco que não são revertidas apenas pelo retorno do código.