Quando seu servidor Mastodon não consegue se comunicar com outras instâncias, o conteúdo pode deixar de chegar nas timelines federadas ou mensagens diretas podem não atingir o destino. Essas falhas são causadas por timeouts de rede, incompatibilidades de certificado SSL, versões de protocolo incompatíveis ou limitação de taxa do servidor remoto. Este artigo explica como acessar e interpretar os logs de erros de federação do painel de administração do Mastodon para que você possa diagnosticar e resolver problemas de conectividade rapidamente.
Principais Pontos: Painel de Erros de Federação do Mastodon
- Administração > Federação > Filas do Sidekiq: Visualize jobs de entrega atrasados ou com falha que indicam quais instâncias remotas estão inacessíveis.
- Administração > Logs > Sidekiq: Inspecione os stacks de falha de jobs individuais para distinguir erros de timeout de rejeições HTTP 4xx.
- Administração > Federação > Domínios > Bloqueios de Domínio: Verifique se o domínio remoto foi suspenso ou silenciado acidentalmente, o que bloqueia todo o tráfego de federação.
O Que os Erros de Federação Revelam Sobre a Saúde da Instância
O Mastodon usa um sistema de jobs em segundo plano chamado Sidekiq para enviar e receber conteúdo de instâncias remotas. Quando uma ação de federação falha, o Sidekiq armazena a mensagem de erro, o código de resposta HTTP e o timestamp. O painel de administração exibe esses registros em dois locais principais: na seção Federação e nos logs do Sidekiq. Entender esses erros ajuda a decidir se o problema é temporário, como uma instabilidade de rede, ou permanente, como um domínio que não existe mais.
Tipos comuns de erro incluem:
- HTTP 401 Não Autorizado — O servidor remoto rejeitou a assinatura da sua instância. O administrador remoto pode ter bloqueado seu domínio.
- HTTP 410 Removido — A conta ou instância remota foi excluída.
- Net::OpenTimeout — O servidor remoto não respondeu dentro do tempo limite, geralmente devido a regras de firewall ou alta carga.
- OpenSSL::SSL::SSLError — O servidor remoto apresentou um certificado inválido ou autoassinado.
Por padrão, o Mastodon não registra todas as entregas com falha no painel principal. Você precisa navegar até as subpáginas corretas de administração para ver a saída bruta do erro.
Acessando os Logs de Erro de Federação no Painel de Administração
O painel de administração está disponível apenas para usuários com função de Administrador ou Moderador. Siga estas etapas para localizar os logs de erro.
- Abra o painel de Administração
Na interface web do Mastodon, clique no menu hambúrguer (três linhas horizontais) no canto superior direito. Selecione Preferências e depois clique em Administração na barra lateral esquerda. - Vá para Federação > Sidekiq
Em Administração, clique em Federação. No topo da página de Federação, clique na aba Sidekiq. Esta página mostra o número de jobs na fila, em retry e mortos. Jobs mortos são entregas que esgotaram todas as tentativas de retry. - Clique em um job morto para ver o erro
Na seção de Jobs Mortos, clique no ID do job ou no link da mensagem de erro. Uma janela modal abre mostrando o backtrace completo do erro, o código de resposta HTTP e a URL de destino. A URL de destino contém o domínio da instância remota e o endpoint específico da API que falhou. - Revise a classe e a mensagem de erro
Procure pela classe de erro no backtrace. Por exemplo,Mastodon::UnexpectedResponseErrorsignifica que o servidor remoto retornou um status HTTP inesperado. A mensagem de erro geralmente inclui o código HTTP exato, comoHTTP 503. Copie essas informações para análise posterior.
Você também pode filtrar jobs por nome de fila. As filas de federação padrão são push (entregas de saída para seguidores em instâncias remotas) e pull (buscas de entrada de instâncias remotas). Use o menu suspenso de filtro de fila para restringir os erros a uma direção.
Verificando Bloqueios de Domínio que Interferem na Federação
Às vezes o erro não está no servidor remoto, mas no seu. Se sua instância tiver um bloqueio de domínio que silencia ou suspende o domínio remoto, todo o tráfego de federação para e daquele domínio é interrompido. Para verificar:
- Navegue para Administração > Federação > Domínios
Clique em Domínios na seção Federação. A tabela lista todos os domínios que foram bloqueados ou limitados manualmente. - Procure pelo domínio remoto na lista
Se o domínio aparecer com status Suspenso ou Silenciado, remova ou modifique o bloqueio. Clique no nome do domínio e depois em Editar. Altere a severidade para Nenhum e salve. - Aguarde o Sidekiq tentar novamente
Após remover o bloqueio, o Sidekiq tentará automaticamente os jobs com falha em alguns minutos. Você pode tentar manualmente um job morto clicando no botão Tentar novamente na lista de Jobs Mortos do Sidekiq.
Se os Erros de Federação Persistirem Após Verificar o Painel
Alguns erros exigem investigação mais aprofundada além do painel de administração. Os problemas a seguir são comuns e têm soluções específicas.
Erros HTTP 401 que Aparecem Aleatoriamente
Um erro 401 Não Autorizado significa que o servidor remoto rejeitou a assinatura HTTP anexada à sua solicitação de entrega. Isso geralmente acontece quando sua instância muda de nome de domínio ou quando a instância remota atualiza sua lista de domínios permitidos. Verifique se o domínio da sua instância está configurado corretamente em Preferências > Administração > Configurações do Servidor > Sobre. O domínio deve corresponder ao hostname usado na assinatura.
Erros de Certificado SSL para um Único Domínio
Se você vir OpenSSL::SSL::SSLError para um domínio remoto, o servidor remoto provavelmente tem um certificado expirado ou mal configurado. Você não pode corrigir o servidor remoto, mas pode instruir o Mastodon a parar de tentar entregas para aquele domínio para liberar recursos do Sidekiq. Vá para Administração > Federação > Domínios, clique em Adicionar novo bloqueio de domínio, insira o domínio e escolha Suspender. Isso interrompe todas as tentativas futuras de entrega. Quando o administrador remoto corrigir o certificado, remova o bloqueio.
Fila do Sidekiq Crescendo de Forma Anormalmente Grande
Um tamanho grande de fila sem erros visíveis na lista de Jobs Mortos indica que os jobs estão sendo repetidos silenciosamente. Abra a aba Sidekiq e observe o contador de Tentativas. Clique em Tentativas para ver a lista de jobs aguardando a próxima tentativa. Cada entrada de retry mostra os mesmos detalhes de erro que um job morto. Se a fila continuar crescendo, considere aumentar o número de workers do Sidekiq na configuração de sua implantação ou bloquear temporariamente o domínio remoto problemático.
Painel de Administração vs Interface Web do Sidekiq: Visibilidade de Erros de Federação
| Item | Painel de Administração do Mastodon | Interface Web do Sidekiq |
|---|---|---|
| Caminho de acesso | Preferências > Administração > Federação > Sidekiq | https://suainstancia.com/sidekiq (requer autenticação separada) |
| Visibilidade do backtrace de erro | Backtrace completo exibido em modal | Backtrace completo exibido na página de detalhes do job |
| Filtrar por fila | Menu suspenso para push, pull, default | Abas de fila para cada fila nomeada |
| Tentar novamente jobs mortos | Botão de retry por job | Botão de retry por job ou retry em lote |
| Integração com bloqueio de domínio | Link direto para página de Domínios | Sem integração |
Agora você pode localizar erros de federação no painel de administração do Mastodon, interpretar os códigos de status HTTP e classes de erro, e decidir se deve tentar novamente o job, remover um bloqueio de domínio ou suspender uma instância remota problemática. Da próxima vez que uma postagem remota falhar ao chegar, verifique primeiro a lista de Jobs Mortos do Sidekiq. Para monitoramento avançado, considere habilitar a interface web do Sidekiq e configurar alertas para limites de tamanho de fila.