Como Configurar uma Instância Mastodon com Modo de Manutenção Somente Leitura

Você precisa impedir que usuários publiquem, editem ou excluam conteúdo em sua instância Mastodon, mantendo a linha do tempo pública e os perfis acessíveis. Isso é chamado de modo de manutenção somente leitura. O modo permite que visitantes naveguem por postagens existentes, mas impede operações de escrita como toots, impulsionamentos, seguidores ou alterações de conta. Este artigo explica como ativar o modo somente leitura em uma instância Mastodon usando ferramentas de linha de comando e alterações de configuração.

O que o Modo de Manutenção Somente Leitura Faz em uma Instância Mastodon

O modo de manutenção somente leitura impede que qualquer usuário realize operações de escrita na instância. Quando ativado, a API do Mastodon retorna um erro 503 Service Unavailable para todas as requisições POST, PUT, PATCH e DELETE. Isso interrompe a criação ou modificação de novos toots, impulsionamentos, favoritos, seguidores, atualizações de conta, uploads de mídia e mensagens diretas.

A linha do tempo pública, as páginas de perfil e as páginas de status permanecem totalmente acessíveis. Os usuários podem visualizar conteúdo existente e pesquisar postagens públicas. O modo é útil antes de migrações de banco de dados, atualizações de software ou manutenção do sistema de arquivos que exija um estado de dados estável.

O Mastodon fornece dois comandos integrados através do utilitário tootctl: maintenance mode enable e maintenance mode disable. Esses comandos modificam as configurações da instância no banco de dados e sinalizam ao servidor de aplicação para rejeitar requisições de escrita.

Os pré-requisitos para usar o modo de manutenção incluem acesso SSH ao servidor, uma conta de usuário com privilégios sudo e o diretório da aplicação Mastodon localizado em /home/mastodon/live por padrão. Os serviços do Mastodon devem estar em execução para que os comandos tootctl se comuniquem com o banco de dados.

Passos para Ativar o Modo de Manutenção Somente Leitura no Mastodon

Siga estes passos exatamente na ordem. Pular qualquer etapa pode deixar a instância em um estado parcialmente bloqueado.

1. Conecte-se via SSH ao seu servidor Mastodon
   Abra um terminal e conecte-se ao seu servidor usando ssh usuario@ip-do-seu-servidor. Use a conta de usuário mastodon ou mude para ela com sudo su - mastodon.
2. Navegue até o diretório da aplicação Mastodon
   Execute cd /home/mastodon/live. Este é o caminho de instalação padrão. Se sua instância usar um diretório diferente, ajuste o caminho conforme necessário.
3. Ative o modo de manutenção usando tootctl
   Execute RAILS_ENV=production bin/tootctl maintenance mode enable. O comando atualiza a configuração no banco de dados e retorna OK quando bem-sucedido. O modo entra em vigor imediatamente para todas as novas requisições à API.
4. Verifique se o modo de manutenção está ativo
   Execute RAILS_ENV=production bin/tootctl maintenance mode status. A saída deve dizer Maintenance mode is enabled. Você também pode testar enviando uma requisição POST para a API da sua instância usando curl -X POST https://sua-instancia.example/api/v1/statuses. A resposta deve ser um erro 503.
5. Informe os usuários sobre a janela de manutenção
   Publique um anúncio na página “Sobre” da sua instância ou envie uma notificação através do painel de administração. Os usuários verão o erro 503 se tentarem interagir, mas uma mensagem proativa reduz a confusão.

Após concluir as tarefas de manutenção, execute RAILS_ENV=production bin/tootctl maintenance mode disable a partir do mesmo diretório para restaurar o acesso total de escrita. Verifique novamente com o comando de status.

Configurando uma Página de Manutenção no Nginx

Quando você interrompe completamente os serviços do Mastodon para trabalhos no banco de dados ou sistema de arquivos, o servidor de aplicação não responde a nenhuma requisição. Nesse caso, configure o Nginx para servir uma página de manutenção estática para todos os endpoints de escrita. Isso fornece uma mensagem amigável em vez de um erro genérico de conexão recusada.

Crie um arquivo HTML de manutenção em /usr/share/nginx/html/maintenance.html. O arquivo deve explicar que a instância está em manutenção e quando o serviço normal será retomado.

1. Edite o arquivo de configuração do site Nginx
   Abra /etc/nginx/sites-available/mastodon com um editor de texto como root. Localize o bloco location / que faz proxy das requisições para o servidor de aplicação Mastodon.
2. Adicione um bloco de localização para endpoints de escrita
   Insira o seguinte bloco dentro do bloco server, mas antes do bloco location / principal:
   location ~ ^/(api|auth|inbox|push|oauth) {
return 503;
error_page 503 /maintenance.html;
}
   Isso captura todos os caminhos de API e autenticação e retorna um status 503 com a página de manutenção personalizada.
3. Teste e recarregue o Nginx
   Execute nginx -t para verificar a sintaxe. Se o teste passar, execute systemctl reload nginx para aplicar as alterações.
4. Pare os serviços do Mastodon
   Execute systemctl stop mastodon-* para parar todos os processos do Mastodon. As regras do Nginx agora servem a página de manutenção para requisições de escrita, enquanto conteúdo estático como avatares de usuários e arquivos CSS permanecem acessíveis.

Quando a manutenção terminar, inicie os serviços do Mastodon com systemctl start mastodon-* e remova o bloco de localização de manutenção da configuração do Nginx. Recarregue o Nginx para restaurar o roteamento normal.

Erros Comuns ao Configurar o Modo de Manutenção Somente Leitura

Modo de manutenção ativado, mas serviços estão parados

Executar o comando tootctl enquanto os serviços do Mastodon não estão em execução não define o modo no banco de dados. O comando requer um processo Sidekiq em execução para gravar a configuração. Sempre verifique se mastodon-sidekiq e mastodon-web estão ativos antes de executar os comandos de ativação ou desativação.

Usuários ainda podem postar via clientes de terceiros

O modo de manutenção bloqueia todos os endpoints de escrita da API, independentemente do cliente. Se um usuário ainda puder postar, o modo não está ativado. Verifique o status com RAILS_ENV=production bin/tootctl maintenance mode status. Se mostrar desativado, execute novamente o comando de ativação.

A página de manutenção não aparece após a configuração do Nginx

O bloco de localização deve aparecer antes do bloco de proxy principal na configuração do Nginx. Se o bloco de proxy corresponder primeiro, a requisição nunca chega à regra 503. Coloque o bloco de localização de manutenção no topo do bloco server.

O modo de manutenção persiste após o comando de desativação

Se o comando de desativação falhar silenciosamente, a flag no banco de dados permanece definida. Execute o comando de desativação novamente e verifique com o comando de status. Se o problema continuar, verifique os logs do Mastodon em /home/mastodon/live/log/production.log para erros de conexão com o banco de dados.

Item	Modo de Manutenção tootctl	Bloco de Localização 503 no Nginx
Propósito	Bloqueia a API de escrita no nível da aplicação	Bloqueia requisições de escrita quando o servidor de aplicação está offline
Requer serviços em execução	Sim, Sidekiq e web devem estar ativos	Não, funciona com serviços parados
Visibilidade para o usuário	Erro 503 no cliente	Página HTML de manutenção personalizada
Acesso a conteúdo estático	Totalmente acessível	Totalmente acessível
Método de configuração	Linha de comando tootctl	Arquivo de configuração Nginx

O modo de manutenção somente leitura para sua instância Mastodon agora está configurado e verificado. Você pode realizar com segurança migrações de esquema de banco de dados, atualizações de software ou operações no sistema de arquivos sem corrupção de dados devido a escritas concorrentes de usuários. Para futuras janelas de manutenção, considere agendar o modo durante horários de baixo tráfego e publicar um aviso prévio na página “Sobre” da instância. O comando tootctl status é a maneira mais rápida de confirmar o modo atual antes e depois de qualquer sessão de manutenção.