Erro 504 no WordPress: alojamento ou site

#O que significa o erro 504 no WordPress?

A MDN, com base no RFC 9110, define o 504 como a situação em que um servidor que atua como gateway ou proxy “did not get a response in time from the upstream server”. É diferente do 502 Bad Gateway: aí a resposta chegou, mas era inválida. No 504 não chegou nada.

Num alojamento WordPress típico, a cadeia é esta: navegador, opcionalmente uma CDN, nginx, PHP-FPM, base de dados e, eventualmente, cache de objetos. O código 504 é gerado pelo elo que ficou à espera. Isso já indica onde procurar. Se o nginx espera pelo PHP, o problema está no PHP, na base de dados ou na fila para o PHP. Se quem espera é a CDN, o problema está no servidor de origem.

A documentação da MDN assinala também que as causas são várias e que a correção costuma exigir análise por parte do administrador do servidor. Por isso, daqui em diante não há uma correção mágica, há uma ordem de verificações.

#O 504 é culpa do alojamento ou do site?

O âmbito do erro decide a questão. A tabela abaixo é um atalho de decisão, não uma sentença.

A responsabilidade do alojamento começa onde os limites (número de workers, memória, CPU) são pequenos demais para o tráfego normal do site. A responsabilidade do site começa onde um único pedido faz tanto trabalho que bloqueia o worker durante dezenas de segundos. Na prática, muitas vezes atuam as duas coisas em simultâneo: os pedidos lentos ocupam os workers e o pool pequeno não tem folga.

#Como verificar onde o pedido ficou preso?

Comece por três sítios, por esta ordem.

1. Registo de erros do servidor web da hora da falha. No nginx, uma entrada upstream timed out confirma que o servidor ficou à espera do PHP.
2. Registo do PHP-FPM. A mensagem de que o pm.max_children foi atingido significa que o pool estava cheio e os pedidos seguintes ficaram em fila. A opção pm.max_children, como descreve a documentação do PHP, define o limite de pedidos simultâneos servidos pelo pool.
3. Registo do WordPress. No wp-config.php, defina WP_DEBUG como true, WP_DEBUG_LOG como true e WP_DEBUG_DISPLAY como false. Os erros vão para wp-content/debug.log em vez de aparecerem no ecrã. É assim que a documentação do WordPress o descreve. Desative o debug depois do diagnóstico.

Quando o alojamento dá acesso ao slowlog do PHP-FPM, defina request_slowlog_timeout e o PHP regista o backtrace dos pedidos que demoram mais do que o limite. Por predefinição a opção está desativada (valor 0). O backtrace mostra em que função do plugin ou do tema o PHP ficou à espera.

Num alojamento partilhado, muitas vezes não há acesso a estes registos. Nesse caso, o acesso a eles e às métricas do pool PHP é a primeira coisa a pedir ao suporte, juntamente com a hora da falha e o endereço que devolveu o 504.

#Porque é que um pool PHP-FPM demasiado pequeno dá 504?

Cada pedido dinâmico ocupa um worker do PHP-FPM até ao fim da resposta. Quando todos os workers estão ocupados, os novos pedidos esperam. Se esperarem mais do que o limite do proxy, o visitante vê um 504.

O fastcgi_read_timeout predefinido no nginx é de 60 segundos e a documentação do nginx assinala que o limite é contado entre duas leituras consecutivas do servidor FastCGI, não para a resposta inteira. Em alojamentos geridos o valor pode ser outro, por isso não parta do princípio de que no seu caso são precisamente 60 segundos.

Aumentar o pm.max_children só ajuda se o servidor tiver memória para isso. Cada worker de um WordPress com alguns plugins ocupa uma fatia considerável, pelo que um valor demasiado alto acaba em esgotamento de RAM e processos terminados à força, ou seja, um estado pior do que a fila. A configuração do pool é tarefa para o administrador, que vê o consumo de memória.

#Como é que consultas lentas e opções com carregamento automático causam 504?

Quando o 504 afeta o site inteiro e o pool não está cheio por causa do tráfego, verifique a base de dados. A documentação do WordPress chama a atenção para o facto de o WordPress repetir muitas consultas a cada pedido e de as opções marcadas como autoload serem carregadas em cada visita. Recomenda mantê-las abaixo de 800 KB, e as recomendações completas estão descritas no guia de otimização. Um plugin que grava dados volumosos em wp_options com autoload empurra-os para cada pedido. O tamanho do autoload verifica-se com uma consulta SQL pela coluna autoload na tabela de opções.

Para identificar consultas lentas serve a constante SAVEQUERIES. Regista cada consulta, o tempo de execução e a função que a chamou em $wpdb->queries. Tem custo de desempenho, por isso ative-a por pouco tempo e, se possível, num ambiente de staging.

#Quando é que a cache de objetos e o Redis causam 504?

Uma cache de objetos persistente reduz o número de consultas à base de dados e normalmente acelera o site. Exige, no entanto, um servidor de cache a funcionar e o ficheiro drop-in wp-content/object-cache.php.

A falha funciona no sentido inverso quando esse ficheiro existe e o servidor Redis não responde. Cada pedido tenta então ligar-se à cache, espera pelo timeout da ligação e só depois segue em frente ou desiste. O sintoma é um 504 logo após um reinício ou uma falha do serviço de cache no alojamento, apesar de o código do site não ter mudado.

O teste é simples: mude o nome do object-cache.php para outro. Se o 504 desaparecer, a culpa é da cache e não do WordPress. Reponha o ficheiro apenas depois de reparar o serviço.

#Como é que o WP-Cron, o admin-ajax e as APIs externas provocam 504?

Convém verificar em separado três origens de pedidos lentos isolados.

• WP-Cron. A documentação do WordPress explica que o WP-Cron é executado quando alguém visita o site, não como processo permanente. Tarefas pesadas em atraso (cópias de segurança, importações, envios) podem assim sobrecarregar o pedido normal de um visitante. Passar as chamadas para o cron do sistema do alojamento alivia o front-end.
• admin-ajax.php. Os plugins enviam aqui pedidos do painel e do front-end. Se o 504 surgir precisamente aqui, procure o plugin que faz uma operação pesada em segundo plano.
• APIs externas. Um plugin que espera por um sistema externo lento (pagamentos, ERP, expedição) segura o worker enquanto o outro sistema demorar a responder. A falta de um timeout curto e próprio nesse plugin transforma a falha de terceiros no seu 504.

#Em que difere o 504 do 502 e do 524?

• 502 Bad Gateway: o servidor atrás do proxy respondeu, mas a resposta era inválida. Muitas vezes é um processo PHP-FPM que caiu.
• 504 Gateway Timeout: sem resposta a tempo. Na maioria dos casos, sobrecarga ou um pedido lento.
• 524: código da Cloudflare. A documentação da Cloudflare indica que surge quando o servidor de origem não responde nos 125 segundos predefinidos. A Cloudflare aconselha a pedir ao alojamento que verifique processos longos e sobrecarga, e a mover as operações grandes para um canal sem proxy.

Atrás de uma CDN pode, portanto, ver dois códigos diferentes para a mesma causa, consoante o elo que perdeu primeiro a paciência.

#Quando aumentar o timeout e quando não?

Aumentar o fastcgi_read_timeout ou o limite de tempo do PHP justifica-se para uma única operação deliberadamente longa, por exemplo uma importação manual. Para um site que mostra 504 aos visitantes, é mascarar o problema: o pedido lento continua a ocupar o worker, só que durante mais tempo, e o pool enche-se mais depressa.

O PHP-FPM tem outro mecanismo de segurança, o request_terminate_timeout. A documentação descreve-o como o limite a partir do qual o processo que serve o pedido é terminado e indica o valor predefinido 0, ou seja, desativado. Definido com bom senso, protege o pool de um único script bloqueado.

#Como corrigir o 504 passo a passo?

1. Determine o âmbito: site inteiro, um endereço ou apenas o wp-admin.
2. Leia os registos do servidor e do PHP-FPM da hora da falha.
3. Ative o debug.log e reproduza o erro.
4. Desative os plugins (via WP-CLI ou mudando o nome da pasta), depois ative-os um a um e meça o tempo de resposta.
5. Se existir o object-cache.php, desative-o como teste.
6. Verifique as opções com carregamento automático e as tarefas do WP-Cron em atraso.
7. Só no fim considere aumentar o pool ou os timeouts, em conjunto com o administrador do alojamento.

Se o 504 apareceu logo a seguir a uma atualização, consulte também o guia sobre como recuperar o WordPress após uma atualização falhada.

#Quando é trabalho para um especialista?

Quando os registos apontam para o pool PHP-FPM, mas o alojamento não dá acesso à sua configuração. Quando o 504 volta depois de cada correção. Quando a loja perde encomendas durante a falha. Numa auditoria que deve separar o custo do alojamento do custo do código, ajuda a otimização do desempenho de um site WordPress. Quando o site está em baixo neste momento e a causa é desconhecida, a salvação é a reparação e o suporte técnico WordPress.