Quando o Mastodon não encontra um usuário remoto pelo identificador completo, a federação quebra. Você vê erros como “Usuário não encontrado” ou “Falha ao buscar conta” ao pesquisar alguém em outra instância. Isso acontece porque a consulta Webfinger, o protocolo que o Mastodon usa para resolver o endereço de um usuário em uma URL de perfil, está falhando. Este artigo explica as causas raiz das falhas na consulta Webfinger e fornece correções passo a passo para administradores e usuários.
Webfinger é um protocolo de descoberta definido na RFC 7033. O Mastodon envia uma requisição HTTPS para o domínio remoto pedindo informações sobre um recurso, geralmente um endereço no formato email como usuario@exemplo.com. Se essa requisição falhar ou retornar dados incorretos, o perfil remoto não pode ser carregado.
Você aprenderá a diagnosticar falhas no Webfinger, corrigir configurações incorretas comuns em sua própria instância e entender o que verificar no servidor remoto. Este guia cobre tanto as configurações do servidor Mastodon quanto as configurações de DNS que afetam a federação.
Principais Conclusões: Diagnosticando e Corrigindo Falhas na Consulta Webfinger do Mastodon
- Preferências > Conta > Mover de uma conta diferente: Verifica se seu próprio registro Webfinger está sendo servido corretamente antes da migração.
- Registro CNAME / A de DNS para webfinger.exemplo.com: Necessário se a instância remota usa um subdomínio para o Mastodon, mas o identificador do usuário usa o domínio principal.
- Fila sidekiq do Mastodon e log de erros do nginx: Onde as requisições Webfinger com falha são registradas para diagnóstico.
Por que a Consulta Webfinger do Mastodon Falha
O Webfinger funciona enviando uma requisição GET para https://dominio.com/.well-known/webfinger?resource=acct:usuario@dominio.com. O servidor deve retornar um documento JSON contendo um link para o perfil ActivityPub do usuário. Se qualquer etapa dessa cadeia quebrar, o Mastodon não consegue federar com esse usuário.
As causas raiz mais comuns são:
- Endpoint .well-known/webfinger ausente ou mal configurado no servidor remoto. O servidor web (nginx ou Apache) pode não estar roteando as requisições para o Mastodon corretamente.
- Falha na resolução de DNS para o domínio usado no identificador do usuário. Se o identificador for
usuario@exemplo.commas o Mastodon estiver emmastodon.exemplo.com, a requisição Webfinger vai paraexemplo.com, que deve servir a resposta Webfinger ou redirecionar paramastodon.exemplo.com. - Incompatibilidade de certificado SSL/TLS. O certificado apresentado pelo domínio remoto deve corresponder ao hostname na requisição Webfinger. Um certificado para
exemplo.comnão cobreexemplo.coma menos que seja explicitamente incluído. - Firewall ou proxy reverso bloqueando o caminho
.well-known. Alguns scanners de segurança bloqueiam caminhos que começam com ponto. - Versão do Mastodon incompatível. Instâncias muito antigas do Mastodon podem não suportar o formato de resposta Webfinger necessário.
O Fluxo da Requisição Webfinger
Quando você pesquisa por @usuario@instanciaremota.com, sua instância Mastodon faz o seguinte:
- Extrair o domínio
Sua instância analisa o identificador e extraiinstanciaremota.comcomo o domínio de destino. - Enviar requisição Webfinger
Sua instância envia um GET parahttps://instanciaremota.com/.well-known/webfinger?resource=acct:usuario@instanciaremota.com. - Analisar a resposta
Se a resposta for HTTP 200 com um corpo JSON válido contendo um linkselfcomtype="application/activity+json", sua instância extrai a URL do perfil. - Buscar o perfil
Sua instância então busca o perfil a partir da URL fornecida na resposta Webfinger.
Se a etapa 2 ou 3 falhar, você vê a falha na consulta.
Como Corrigir Falhas na Consulta Webfinger
A correção depende se você controla o servidor remoto, seu próprio servidor, ou nenhum. Abaixo estão os passos para cada cenário.
Se Você Controla o Servidor Remoto Que Não Pode Ser Encontrado
Este é o cenário mais comum: usuários de outras instâncias não conseguem encontrar seus usuários pelo identificador. Siga estes passos para verificar e corrigir seu servidor.
- Testar Webfinger manualmente
Abra um terminal e execute:curl -v "https://seudominio.com/.well-known/webfinger?resource=acct:seuusuario@seudominio.com". Substituaseuusuarioeseudominio.compelos valores reais. Verifique se você obtém uma resposta 200 com JSON. - Verificar o roteamento do nginx
Se você obtiver um 404 ou 403, seu servidor web não está passando as requisições para o Mastodon. No nginx, certifique-se de ter um bloco location para/.well-known/webfingerque faça proxy para seu backend Mastodon (geralmentehttp://localhost:3000). No Apache, certifique-se de queRewriteRuleouProxyPassesteja configurado. - Verificar o certificado SSL
Execute:curl -vI https://seudominio.com/.well-known/webfinger. Verifique se o certificado é válido e corresponde exatamente aseudominio.com. Se você usar um certificado curinga paraseudominio.com, ele não cobreseudominio.coma menos que o certificado inclua explicitamente o domínio nu. - Verificar os logs do Mastodon
No seu servidor Mastodon, execute:journalctl -u mastodon-sidekiq -n 50. Procure por erros contendo "Webfinger" ou "webfinger". Erros comuns incluem "Failed to fetch resource" ou "JSON parse error". - Reiniciar os serviços do Mastodon
Após qualquer alteração de configuração, reinicie o Mastodon:systemctl restart mastodon-web mastodon-sidekiq mastodon-streaming.
Se Você É o Usuário Tentando Encontrar um Usuário Remoto
Verificar o formato do identificador
Certifique-se de estar usando o formato completo do identificador @usuario@dominio.com incluindo o @ antes do nome de usuário. O Mastodon requer o prefixo acct: internamente, mas a caixa de pesquisa espera o identificador completo.
- Tentar a URL Webfinger manualmente
Em um navegador, vá parahttps://dominio.com/.well-known/webfinger?resource=acct:usuario@dominio.com. Substituadominio.comeusuario. Se você obtiver uma resposta JSON, o servidor remoto está funcionando. Se obtiver um 404 ou erro, o servidor remoto está mal configurado. - Verificar se o domínio remoto é um redirecionamento
Algumas instâncias usam um subdomínio comomastodon.dominio.commas o identificador usadominio.com. O servidor remoto deve ter um redirecionamento dehttps://dominio.com/.well-known/webfingerparahttps://mastodon.dominio.com/.well-known/webfinger. Você pode testar isso com:curl -v "https://dominio.com/.well-known/webfinger?resource=acct:usuario@dominio.com"e verificar se há um redirecionamento 301 ou 302. - Contatar o administrador da instância remota
Se o endpoint Webfinger retornar um erro, envie ao administrador uma cópia da saída do curl. Ele pode seguir os passos da seção anterior.
Se Você Não Consegue Alcançar Nenhum Usuário Remoto
Se todas as consultas remotas falharem, o problema provavelmente está na sua própria instância.
- Verificar seu DNS
Certifique-se de que seu servidor consegue resolver domínios externos. Execute:nslookup instanciaremota.com. Se o DNS falhar, verifique seu arquivo/etc/resolv.conf. - Verificar regras de firewall de saída
Seu servidor Mastodon deve fazer conexões HTTPS de saída para servidores remotos. Verifique se a porta 443 não está bloqueada em seu firewall. - Testar com uma instância conhecida
Tente pesquisar por@gargron@mastodon.social(o criador do Mastodon). Se falhar, sua instância tem um problema geral de federação. - Reiniciar o Mastodon
Reinicie todos os serviços do Mastodon:systemctl restart mastodon-web mastodon-sidekiq mastodon-streaming.
Se o Webfinger Ainda Falhar Após a Correção Principal
Webfinger Retorna HTTP 404 para Todos os Usuários
Isso geralmente significa que o diretório .well-known não está configurado no nginx ou Apache. No nginx, certifique-se de ter:
location ~ ^/.well-known/webfinger {
proxy_pass http://localhost:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}No Apache, use:
ProxyPass /.well-known/webfinger http://localhost:3000/.well-known/webfinger
ProxyPassReverse /.well-known/webfinger http://localhost:3000/.well-known/webfingerWebfinger Retorna JSON mas Sem um Link "self"
Isso indica uma entrada de banco de dados corrompida ou incompleta para aquele usuário. No servidor remoto, execute:
RAILS_ENV=production bin/tootctl accounts refresh <usuario>Substitua <usuario> pelo nome de usuário real. Este comando regenera a resposta Webfinger para aquele usuário.
Webfinger Retorna HTTP 500
Verifique o log web do Mastodon: journalctl -u mastodon-web -n 50. Causas comuns são falhas de conexão com o banco de dados ou gems faltando. Execute bundle install no diretório do Mastodon e reinicie.
Webfinger do Mastodon vs. Federação Baseada em DNS
| Item | Consulta Webfinger | Federação Baseada em DNS |
|---|---|---|
| Protocolo | HTTPS GET para /.well-known/webfinger | Consulta de registro SRV |
| Usado para | Resolver identificadores de usuário em URLs de perfil | Descobrir endpoints do servidor Mastodon (opcional) |
| Necessário para federação | Sim | Não |
| Sintoma de erro | "Usuário não encontrado" ou "Falha ao buscar conta" | Nenhum efeito em consultas básicas |
| Local da configuração | Servidor web (nginx/Apache) + Mastodon | Arquivo de zona DNS |
Webfinger é obrigatório para a federação do Mastodon. Registros DNS SRV são opcionais e usados apenas para otimização da comunicação servidor a servidor.
Após aplicar as correções acima, sua instância Mastodon deve resolver com sucesso usuários remotos via Webfinger. Teste com um identificador conhecido como @gargron@mastodon.social. Se a consulta for bem-sucedida, a federação está restaurada. Para monitoramento contínuo, configure um cron job que execute curl contra seu próprio endpoint Webfinger semanalmente e alerte se o código de resposta não for 200.