Erro 503 no Magento 2 depois do deploy: é o .maintenance.flag

Confirma em dez segundos

Um comando responde:

php bin/magento maintenance:status

A saída é literalmente esta:

Status: maintenance mode is enabled
List of exempt IP-addresses: none

Se o bin/magento também estiver quebrado (acontece quando o módulo que derrubou o deploy nem carrega), olhe o arquivo direto:

ls -la var/.maintenance.flag

É um arquivo vazio, criado com touch. Ele não guarda nada; a existência dele já é a informação.

O caminho dentro do Magento é curto: o bootstrap vê a flag, para com o código de erro 901 e inclui o pub/errors/503.php, que responde HTTP 503 e desenha a página 503.phtml. Por isso não aparece exception nenhuma: do ponto de vista do aplicativo, nada deu errado.

Tira do ar do jeito certo

Com a CLI funcionando:

php bin/magento maintenance:disable

Com a CLI quebrada, apagar o arquivo resolve na hora e é seguro:

rm var/.maintenance.flag

Só que antes de tirar, pense por que ela ficou lá. Se o deploy morreu no setup:upgrade, o banco pode estar num estado meio migrado. Nessa situação eu rodo primeiro:

php bin/magento setup:db:status

Se ele disser que o schema ou os dados estão desatualizados, o certo é terminar o setup:upgrade com a loja ainda fechada, e só então liberar. Abrir a loja com migração pela metade é como colher pedido para um banco que ainda vai mudar.

Depois de liberar, um php bin/magento cache:flush evita que Varnish ou FPC sirvam a página de 503 que ficou guardada.

Da próxima vez, libere só o seu IP

Manutenção sem exceção de IP é manutenção que você não consegue testar. A forma certa de ligar é:

php bin/magento maintenance:enable --ip=203.0.113.10

A opção repete: --ip=203.0.113.10 --ip=203.0.113.11. Isso grava var/.maintenance.ip ao lado da flag. Para mexer na lista sem ligar ou desligar nada, existe um comando próprio:

php bin/magento maintenance:allow-ips 203.0.113.10 --add
php bin/magento maintenance:allow-ips --none

O --add soma à lista atual em vez de substituir, e o --none limpa tudo. Detalhe que pouca gente sabe: a comparação aceita faixa, então 203.0.113.0/24 funciona e vale para o escritório inteiro.

Um aviso que já me custou meia hora: o Magento compara com o REMOTE_ADDR, e por padrão ele não olha cabeçalho de proxy. Atrás de Cloudflare ou de um load balancer sem real_ip configurado no nginx, o IP que chega é o do proxy — o seu nunca vai bater, e você continua vendo 503 mesmo estando na lista.

Quando não é a flag

Se o maintenance:status disser disabled e a loja continuar em 503, o erro está antes do Magento. Os dois casos que eu mais vejo:

• php-fpm fora. O nginx devolve 502 ou 503 quando não consegue falar com o pool. Confira com systemctl status php8.4-fpm e olhe o log de erro do nginx, não o do Magento.
• Varnish sem backend saudável. Com o backend reprovado no health check, o Varnish serve 503 Backend fetch failed — texto diferente do 503 do Magento, e é assim que dá para distinguir os dois olhando só a página.

Vale ler o corpo da resposta antes de sair mexendo. A página de manutenção do Magento tem o título Error 503: Service Unavailable; a do Varnish e a do nginx são outras. Meio segundo de leitura poupa vinte minutos de caça errada.