Mastodon ‘Cloudflare 502 Bad Gateway’ na Web: Causas

Ao tentar abrir uma instância do Mastodon no navegador e ver um erro 502 Bad Gateway com a marca Cloudflare, o servidor web não conseguiu completar sua requisição. Esse erro significa que o Cloudflare, o proxy reverso na frente do servidor Mastodon, recebeu uma resposta inválida do servidor de origem. O problema quase sempre está no lado do servidor, não na sua rede local ou navegador. Este artigo explica as três causas técnicas mais comuns desse erro em instâncias do Mastodon e o que os administradores podem fazer para corrigi-las.

Por que o Cloudflare retorna um erro 502 em instâncias do Mastodon

O Cloudflare fica entre o navegador do usuário e o servidor de origem do Mastodon. Quando você visita uma instância do Mastodon, seu navegador envia uma requisição para a borda do Cloudflare, que então a encaminha para o servidor de origem. O servidor de origem deve retornar uma resposta HTTP válida dentro de um período de timeout específico, geralmente 100 segundos. Se a origem não responder, responder com um cabeçalho incompleto ou retornar um pacote TCP RST (reset), o Cloudflare gera um erro 502 Bad Gateway.

No Mastodon, o servidor de origem é tipicamente uma combinação de um proxy reverso como Nginx e um servidor de aplicação como Puma ou Unicorn. O servidor de aplicação executa o código Ruby on Rails do Mastodon. Um erro 502 quase sempre aponta para um problema nessa pilha. As três causas raiz mais comuns são:

1. Timeout upstream: Puma ou Unicorn demora demais

O servidor de aplicação do Mastodon deve servir uma resposta antes que o timeout do proxy do Cloudflare expire. O timeout padrão do Cloudflare é de 100 segundos para requisições HTTP em planos gratuitos e pro. Se uma página do Mastodon, como a linha do tempo federada ou um post com muitas mídias, disparar uma consulta lenta no banco de dados, o servidor de aplicação pode exceder esse limite. O Cloudflare então abandona a conexão e mostra um erro 502.

2. Travamento ou reinicialização do servidor de aplicação

O Puma ou Unicorn pode travar devido a esgotamento de memória, um bug em uma atualização do Mastodon ou esgotamento do pool de conexões do banco de dados. Quando o processo para, o Nginx não consegue encaminhar a requisição para um worker saudável. A conexão com o Cloudflare ou fica pendente ou retorna uma resposta vazia. O Cloudflare interpreta isso como um gateway inválido.

3. Firewall da origem bloqueando IPs do Cloudflare

Alguns servidores Mastodon executam firewalls que bloqueiam tráfego de endereços IP desconhecidos. Se o administrador configurar uma regra de firewall que acidentalmente bloqueie as faixas de IP do proxy do Cloudflare, o servidor de origem recusa a conexão. O Cloudflare recebe um reset TCP ou nenhuma resposta e retorna um erro 502.

Como diagnosticar e corrigir cada causa no servidor

Essas correções exigem acesso à linha de comando do servidor Mastodon. Você precisa de privilégios root ou sudo.

1. Verifique o log de erros do Nginx para timeouts upstream
   Execute sudo tail -f /var/log/nginx/error.log enquanto reproduz o erro 502. Procure por linhas contendo “upstream timed out” ou “504 Gateway Time-out”. Isso confirma que o servidor de aplicação está muito lento.
2. Aumente o timeout do worker Puma na configuração do Mastodon
   Edite o arquivo .env.production e adicione ou altere a linha STREAMING_API_BASE_URL=http://localhost:4000 e WEB_CONCURRENCY=2 para reduzir a carga. Para o timeout, adicione PUMA_WORKER_TIMEOUT=120. Em seguida, reinicie o Mastodon com systemctl restart mastodon-web.
3. Verifique se o Puma ou Unicorn está em execução
   Execute systemctl status mastodon-web ou ps aux | grep puma. Se o processo estiver ausente, reinicie-o com systemctl restart mastodon-web. Verifique o journal para motivos de travamento: journalctl -u mastodon-web -n 50.
4. Permita as faixas de IP do Cloudflare no firewall
   Baixe a lista atual de faixas IPv4 do Cloudflare com curl -s https://www.cloudflare.com/ips-v4. Adicione cada faixa ao seu firewall, por exemplo com UFW: sudo ufw allow from 173.245.48.0/20 to any port 443 proto tcp. Depois recarregue: sudo ufw reload.
5. Teste a origem diretamente, ignorando o Cloudflare
   Defina temporariamente uma entrada no arquivo hosts local apontando seu domínio para o IP do servidor. Acesse o site diretamente. Se a página carregar sem erro 502, o problema é configuração do Cloudflare ou bloqueio de IP. Se o erro persistir, o problema está no servidor de origem.

Padrões de falha relacionados e suas causas

Erro 502 apenas em certas páginas, como a linha do tempo federada

Se o erro aparecer apenas ao navegar pela linha do tempo federada ou por uma página de um usuário com muitas mídias, o servidor de aplicação provavelmente está excedendo o timeout devido a uma consulta lenta no banco de dados. A linha do tempo federada consulta a tabela statuses por posts públicos de instâncias remotas. Um conjunto de resultados grande sem indexação adequada pode levar mais de 100 segundos. A correção é adicionar índices no banco de dados ou aumentar o puma_worker_timeout.

Erro 502 após uma atualização do Mastodon

Após executar mastodon update ou git pull, o servidor de aplicação pode falhar ao iniciar devido a gems faltantes ou uma migração de banco de dados que não foi concluída. Verifique o status da migração com RAILS_ENV=production bundle exec rails db:migrate:status. Execute quaisquer migrações pendentes com RAILS_ENV=production bundle exec rails db:migrate e depois reinicie o processo web.

Erro 502 durante picos de tráfego intenso

Quando uma instância do Mastodon se torna popular, o número padrão de workers do Puma pode ser muito baixo. Cada worker lida com uma requisição por vez. Se todos os workers estiverem ocupados, novas requisições entram em fila e eventualmente excedem o timeout. Aumente o valor de WEB_CONCURRENCY em .env.production para corresponder ao número de núcleos de CPU. Reinicie o Mastodon após alterar esse valor.

Cloudflare 502 vs outros erros 5xx no Mastodon

Item	Cloudflare 502 Bad Gateway	503 Service Unavailable (Cloudflare)	504 Gateway Timeout (Cloudflare)
Descrição	Cloudflare recebeu uma resposta inválida ou vazia da origem	Servidor de origem sobrecarregado ou temporariamente fora do ar	Origem não respondeu dentro da janela de timeout do Cloudflare
Causa típica no Mastodon	Travamento do Puma, bloqueio de firewall ou resposta HTTP incompleta	Servidor sob DDoS ou sem memória	Consulta lenta no banco de dados ou poucos workers do Puma
Comportamento de repetição do Cloudflare	Sem repetição automática; o usuário precisa atualizar	Pode repetir após alguns segundos se configurado	Sem repetição automática; o usuário vê uma página de erro
Prioridade de correção	Verifique os logs do servidor de aplicação e as regras de firewall primeiro	Escalone os recursos do servidor ou ative a proteção DDoS do Cloudflare	Aumente o timeout do Puma ou otimize as consultas ao banco de dados

Entender qual erro 5xx específico aparece ajuda a restringir a causa raiz. Um erro 502 quase sempre exige verificar o status do servidor de aplicação e a configuração do firewall, enquanto um 504 aponta para ajustes de desempenho.

Após diagnosticar a causa, você pode tomar a ação apropriada: aumentar timeouts, reiniciar processos travados ou permitir IPs do Cloudflare no firewall. Se o erro persistir após todas as correções, execute curl -I https://suainstancia.social do próprio servidor. Uma resposta bem-sucedida com código de status 200 confirma que a origem está saudável. A partir daí, reexamine as configurações de proxy do Cloudflare e verifique se os registros DNS estão configurados como Proxied (nuvem laranja).