Fila de Federação do Mastodon Travada no Sidekiq: Passos para Recuperação

Quando a fila de federação do Mastodon trava, novas postagens de outras instâncias param de aparecer na sua timeline federada. Mensagens de saída para servidores remotos também falham. Este problema é quase sempre causado por um processo worker no Sidekiq que está processando um job que nunca termina. Este artigo explica por que a fila congela e fornece os passos exatos para limpar o job travado e reiniciar a federação normal.

Por que a Fila de Federação Para no Sidekiq

O Mastodon usa o Sidekiq para processar jobs em segundo plano, incluindo todas as tarefas de federação. Cada job representa uma ação como entregar um status a um servidor remoto ou processar uma mensagem ActivityPub recebida. O Sidekiq executa múltiplas threads worker, mas a fila de federação é processada por um processo sidekiq dedicado chamado sidekiq_federation por padrão.

Quando um job nesta fila encontra um erro que não consegue tratar, o job pode entrar em um loop de retry ou ficar travado em estado de execução. Uma causa comum é um payload ActivityPub malformado de uma instância remota mal configurada. O job tenta desserializar o payload, encontra uma exceção não tratada e tenta novamente indefinidamente. Como o Sidekiq processa jobs sequencialmente dentro de uma fila, este único job travado bloqueia todos os outros jobs de federação atrás dele.

Outra causa é um timeout de rede que nunca se resolve. Se um servidor remoto está offline mas não fecha a conexão TCP, o worker do Sidekiq espera o timeout expirar. O timeout padrão no Mastodon é de 10 segundos por requisição HTTP. Se o worker fica travado esperando uma resposta que nunca chega, toda a fila de federação congela até que você intervenha manualmente.

Passos para Limpar uma Fila de Federação Travada

Execute estes passos no servidor que roda o Mastodon. Você precisa de acesso SSH e privilégios sudo.

1. Acesse a Interface Web do Sidekiq
   Abra https://sua-instancia.exemplo.com/sidekiq em um navegador. Se você não configurou a interface web do Sidekiq, pode habilitá-la adicionando a gem sidekiq ao seu Gemfile e montando a rota em config/routes.rb. As credenciais padrão são as mesmas do seu login de admin do Mastodon se você usar a integração require 'sidekiq/web'.
2. Identifique o job travado na aba Busy
   Clique na aba Busy. Procure por um job que está rodando há mais de 10 minutos. Um job de federação normal completa em menos de 5 segundos. O job travado mostrará um tempo decorrido longo, frequentemente excedendo 30 minutos. Anote o ID do job, que é uma string de caracteres hexadecimais.
3. Mate o job travado pela linha de comando
   Conecte-se via SSH ao seu servidor Mastodon. Execute o seguinte comando para matar o processo Sidekiq específico que está lidando com o job travado:
   sudo systemctl kill -s SIGTERM mastodon-sidekiq
   Isso envia um sinal de terminação graciosa para todos os workers Sidekiq. O job travado será interrompido e movido para a fila de retry. Se o job não parar, use sudo systemctl kill -s SIGKILL mastodon-sidekiq para forçar a parada. Em seguida, reinicie o Sidekiq com sudo systemctl restart mastodon-sidekiq.
4. Delete o job travado da fila de retry
   Após reiniciar, abra novamente a interface web do Sidekiq e clique na aba Retries. Encontre o job que você matou. Clique no botão Delete ao lado dele para removê-lo permanentemente. Não tente novamente o job, pois ele provavelmente falhará novamente com o mesmo erro.
5. Verifique os logs para encontrar a causa raiz
   Execute sudo journalctl -u mastodon-sidekiq -n 100 para ver as últimas 100 linhas de log. Procure por mensagens de erro relacionadas ao job travado. Erros comuns incluem falhas do ActivityPub::DeliveryWorker com timeout HTTP ou falhas do ActivityPub::ProcessingWorker com erros de parsing JSON. Anote o domínio do servidor remoto mencionado no log de erro.
6. Remova a conta remota problemática
   Se o erro envolver repetidamente uma conta remota específica, remova essa conta da sua instância. Use o seguinte comando:
   RAILS_ENV=production bin/tootctl accounts unfollow @
   Isso remove todos os follows e interrompe futuras tentativas de federação com essa conta.

Se a Fila de Federação Ainda Parar Após a Recuperação

Job travado reaparece após reinicialização

Se o mesmo job reaparecer na fila de retry depois de deletá-lo, a instância remota está enviando dados malformados repetidamente. Bloqueie toda a instância remota. Execute RAILS_ENV=production bin/tootctl domain block . Isso impede qualquer federação futura com esse domínio. Após o bloqueio, reinicie o Sidekiq novamente com sudo systemctl restart mastodon-sidekiq.

Fila de federação cresce mas nunca diminui

Se o tamanho da fila aumenta mas os jobs não estão sendo concluídos, você pode ter um problema de memória. Verifique o uso de memória do Sidekiq com sudo systemctl status mastodon-sidekiq e procure pela coluna de memória. Se o uso de memória exceder 500 MB por worker, aumente o número de workers ou reduza a configuração de concorrência. Edite .env.production e adicione SIDEKIQ_CONCURRENCY=5 para limitar threads concorrentes. Reinicie o Sidekiq após a alteração.

Interface Web do Sidekiq não mostra aba Busy mas a fila está travada

Se a interface web do Sidekiq não mostrar workers ocupados mas a fila de federação não está se movendo, o processo sidekiq pode ter travado silenciosamente. Verifique o status do processo com ps aux | grep sidekiq. Se nenhum processo sidekiq estiver rodando, inicie-os com sudo systemctl start mastodon-sidekiq. Em seguida, monitore os logs para ver se a fila começa a processar.

Fila de Federação do Sidekiq vs Fila Padrão do Sidekiq

Item	Fila de Federação	Fila Padrão
Propósito	Entregar e receber mensagens ActivityPub de e para instâncias remotas	Processar tarefas locais como enviar e-mails, gerar miniaturas e atualizar timelines
Nome do processo worker	sidekiq_federation	sidekiq_default
Duração típica do job	Menos de 5 segundos	Menos de 2 segundos
Bloqueado por um único job travado	Sim, porque processa jobs sequencialmente	Geralmente não, porque múltiplos workers rodam em paralelo
Ação de recuperação	Matar o job travado e deletá-lo dos retries	Reiniciar o processo sidekiq ou aumentar o número de workers

Agora você pode identificar e limpar uma fila de federação travada no Mastodon usando a interface web do Sidekiq e as ferramentas de linha de comando. Após remover o job ofensor e opcionalmente bloquear a instância remota problemática, a fila de federação deve retomar o processamento normal. Como dica avançada, considere configurar um alerta de monitoramento que notifique se algum job do Sidekiq rodar por mais de 60 segundos. Use uma ferramenta como Prometheus com a métrica sidekiq_job_duration_seconds para automatizar essa verificação.