Provedor de Captcha da Instância Mastodon: Como Trocar o hCaptcha

Se você administra uma instância Mastodon, provavelmente usa o hCaptcha para evitar registros automatizados de spam. No entanto, o hCaptcha mudou seu modelo de preços e agora cobra por verificação, o que pode ficar caro para instâncias maiores. Este artigo explica como trocar o provedor de captcha da sua instância Mastodon do hCaptcha para uma alternativa como MastoCaptcha ou uma solução personalizada. Você aprenderá as edições exatas nos arquivos de configuração e as mudanças nas variáveis de ambiente necessárias para concluir a troca.

Por que Trocar o hCaptcha na Sua Instância Mastodon

O Mastodon usa um provedor de captcha para verificar se novos registros de conta são feitos por humanos e não por scripts automatizados. Por padrão, o Mastodon integra-se com o hCaptcha, uma alternativa focada em privacidade ao reCAPTCHA. No entanto, o hCaptcha mudou seu modelo de preços em 2024, introduzindo uma taxa por verificação que pode custar aos administradores de instância vários dólares por mil verificações. Para uma instância de médio porte com centenas de novos registros por dia, esse custo aumenta rapidamente.

O Mastodon também suporta outras soluções de captcha. A alternativa integrada é o MastoCaptcha, um sistema de captcha auto-hospedado que não requer chamadas de API externas. O MastoCaptcha gera desafios simples de matemática ou texto e armazena o estado da verificação localmente. Isso elimina custos contínuos e mantém todos os dados do usuário no seu servidor. Você também pode desativar os captchas completamente definindo o provedor como none, embora isso não seja recomendado para instâncias públicas.

Para trocar de provedor, você deve modificar dois arquivos no seu servidor Mastodon: o arquivo .env.production e o arquivo de configuração mastodon.yml. As alterações exatas dependem do provedor escolhido. Este guia cobre a troca para MastoCaptcha e a desativação completa dos captchas.

Passos para Alterar o Provedor de Captcha no Mastodon

Antes de começar, certifique-se de ter acesso SSH ao seu servidor Mastodon e privilégios sudo. Faça backup dos seus arquivos de configuração atuais. Os passos a seguir assumem que você está usando uma instalação padrão do Mastodon com arquivos de serviço systemd.

Trocar para MastoCaptcha

1. Acesse seu servidor Mastodon
   Conecte-se via SSH ao seu servidor usando um terminal. Por exemplo: ssh admin@seu-ip-do-servidor. Mude para o usuário Mastodon: sudo su - mastodon.
2. Abra o arquivo .env.production
   Use um editor de texto como nano: nano /home/mastodon/live/.env.production. Encontre a linha que contém CAPTCHA_PROVIDER=hcaptcha. Altere para CAPTCHA_PROVIDER=mastocaptcha. Se a linha não existir, adicione-a ao final do arquivo. Salve o arquivo com Ctrl+O e saia com Ctrl+X.
3. Abra o arquivo de configuração mastodon.yml
   Execute nano /home/mastodon/live/config/mastodon.yml. Localize a seção production. Encontre ou adicione a chave captcha_provider e defina como mastocaptcha. A seção deve ficar assim:
   production:
captcha_provider: mastocaptcha
   Salve e saia.
4. Reinicie os serviços do Mastodon
   Saia da sessão do usuário mastodon com exit. Execute os seguintes comandos para reiniciar todos os serviços do Mastodon:
   sudo systemctl restart mastodon-web
sudo systemctl restart mastodon-sidekiq
sudo systemctl restart mastodon-streaming
5. Teste o novo captcha
   Abra a página de registro da sua instância em uma janela privada do navegador. Preencha o formulário de registro. Você deve ver um desafio do MastoCaptcha em vez do widget do hCaptcha. Se o captcha não aparecer, verifique os logs do Mastodon: journalctl -u mastodon-web -n 50.

Desativar Captchas Completamente

1. Edite .env.production
   Abra o arquivo conforme descrito no método anterior. Altere ou adicione CAPTCHA_PROVIDER=none.
2. Edite mastodon.yml
   Abra o arquivo de configuração e defina captcha_provider: none na seção production.
3. Reinicie os serviços do Mastodon
   Execute os mesmos três comandos systemctl restart mostrados acima.
4. Verifique a alteração
   Visite sua página de registro. A seção de captcha deve estar completamente ausente. Novos usuários podem se registrar sem completar nenhum desafio.

Problemas Comuns Após Trocar o Provedor de Captcha

MastoCaptcha Não Aparece na Página de Registro

Se o widget do MastoCaptcha não aparecer, a causa mais comum é uma chave secreta ausente ou incorreta. O MastoCaptcha não requer uma chave de API externa, mas o Mastodon espera que SECRET_KEY_BASE esteja presente em .env.production. Se essa chave estiver faltando, execute RAILS_ENV=production bundle exec rails secret a partir do diretório live do Mastodon e adicione a saída como SECRET_KEY_BASE=sua-nova-chave em .env.production. Em seguida, reinicie os serviços do Mastodon.

Página de Registro Mostra um Erro Após Trocar o Provedor de Captcha

Um erro de registro geralmente indica um erro de sintaxe no mastodon.yml. YAML é sensível à indentação. Certifique-se de que a linha captcha_provider esteja indentada exatamente com dois espaços sob production. Verifique também se não foram usadas tabulações. Execute ruby -c /home/mastodon/live/config/mastodon.yml para validar a sintaxe do arquivo. Corrija quaisquer erros relatados e reinicie os serviços.

Usuários Existentes Não Conseguem Registrar Após Trocar o Provedor de Captcha

Esse problema ocorre se a alteração do provedor de captcha não for aplicada aos processos workers do Sidekiq. Reiniciar apenas o serviço web não é suficiente. Sempre reinicie todos os três serviços do Mastodon — web, sidekiq e streaming — conforme mostrado nos passos acima. Se o problema persistir, limpe o cache do Rails: RAILS_ENV=production bundle exec rails tmp:cache:clear a partir do diretório live do Mastodon.

Provedores de Captcha do Mastodon: hCaptcha vs MastoCaptcha vs Nenhum

Item	hCaptcha	MastoCaptcha	Nenhum
Descrição	Serviço de captcha externo com preço por verificação	Captcha auto-hospedado integrado ao Mastodon	Nenhuma verificação de captcha no registro
Custo	Pague por verificação após o nível gratuito	Gratuito	Gratuito
Privacidade de dados	Dados do usuário enviados aos servidores do hCaptcha	Todos os dados permanecem na sua instância	Nenhum dado de captcha coletado
Complexidade de configuração	Requer chaves de API do hCaptcha	Nenhuma chave externa necessária	Nenhuma configuração além da alteração no config
Acessibilidade	Desafio de áudio disponível	Nenhum desafio de áudio	Não se aplica

Agora você pode trocar o provedor de captcha da sua instância Mastodon do hCaptcha para MastoCaptcha ou desativá-lo completamente. Use a variável de ambiente CAPTCHA_PROVIDER e a chave captcha_provider no mastodon.yml para fazer a alteração. Após a troca, teste a página de registro em um navegador privado para confirmar que o novo captcha funciona. Para um equilíbrio entre segurança e custo, o MastoCaptcha é a alternativa recomendada, pois bloqueia bots sem dependências externas. Considere ativar a limitação de taxa no endpoint de registro como uma camada adicional de proteção se você desativar os captchas.