Mover uma instância Mastodon auto-hospedada para um novo servidor pode parecer uma operação de alto risco. Você precisa transferir contas de usuário, postagens, arquivos de mídia e o banco de dados relacional sem perder dados ou quebrar a federação. Este artigo explica o processo completo de migração usando as ferramentas oficiais de backup e restauração do Mastodon.
A causa raiz da complexidade da migração é a dependência do Mastodon em PostgreSQL, Redis e armazenamento de objetos. Se algum componente estiver fora de sincronia, a nova instância pode falhar ao exibir timelines ou aceitar novas postagens. Este guia cobre as etapas exatas para exportar dados do servidor antigo e importá-los no novo servidor.
Após a leitura, você será capaz de mover sua instância com tempo de inatividade mínimo e verificar se a federação continua funcionando. A seção final aborda problemas comuns, como incompatibilidades de certificado SSL e erros de codificação do banco de dados.
Principais Conclusões: Migração de Instância Mastodon Entre Servidores
- pg_dump e pg_restore: Exporte e importe o banco de dados PostgreSQL com a flag –format=custom para preservar índices e restrições.
- rsync para arquivos de mídia: Copie os diretórios system-media- e a pasta public/system para o novo servidor preservando permissões.
- RAILS_ENV=production bundle exec rake db:migrate: Execute as migrações do banco de dados após a restauração para atualizar o esquema para a versão atual do Mastodon.
Por que a Migração do Mastodon Exige um Dump do Banco de Dados e Sincronização de Mídia
O Mastodon armazena todos os dados de usuário, postagens e relacionamentos em um banco de dados PostgreSQL. Arquivos de mídia como imagens, vídeos e emojis personalizados residem no sistema de arquivos ou no armazenamento de objetos. Para migrar, você deve transferir tanto o banco de dados quanto os arquivos de mídia. O dump do banco de dados deve ser criado com pg_dump --format=custom porque este formato preserva o esquema exato, incluindo índices, sequências e restrições. Um dump SQL simples pode causar violações de chave estrangeira durante a restauração no novo servidor.
Os dados do cache Redis não precisam ser migrados. O Mastodon regenera os caches a partir do banco de dados após a primeira requisição. No entanto, você deve copiar o arquivo de configuração .env.production porque ele contém as chaves secretas para tokens OAuth, chaves VAPID e a senha do banco de dados. Sem esses segredos, a nova instância emitirá novos tokens e invalidará todas as sessões de usuário existentes.
Usuários de armazenamento de objetos (S3/MinIO) podem pular a etapa de sincronização de mídia. Em vez disso, atualize as variáveis de ambiente S3_ no .env.production para apontar para o mesmo bucket. O novo servidor servirá a mídia diretamente desse bucket.
Passos para Migrar uma Instância Mastodon Auto-Hospedada para um Novo Servidor
Preparar o Novo Servidor
- Instalar dependências do Mastodon
No novo servidor, instale o mesmo sistema operacional e versões de software do servidor antigo. Use o guia oficial de instalação do Mastodon para sua distribuição. Instale PostgreSQL 12 ou superior, Redis 6 ou superior, Ruby 3.0+, Node.js 16+ e todos os pacotes de sistema necessários. - Criar o usuário e diretórios do Mastodon
Executeadduser --disabled-login mastodone crie o diretório/home/mastodon/live. Defina a propriedade para o usuário mastodon. - Clonar o código do Mastodon
Como usuário mastodon, executegit clone https://github.com/mastodon/mastodon.git /home/mastodon/livee faça checkout da mesma tag de versão do servidor antigo. Usegit checkout v4.2.0(substitua pela sua versão). - Instalar gems Ruby e pacotes Node
Executebundle install --deployment --without development testeyarn install --pure-lockfiledentro de/home/mastodon/live.
Exportar Dados do Servidor Antigo
- Parar serviços do Mastodon
No servidor antigo, executesystemctl stop mastodon-para parar os processos web, streaming e sidekiq. Isso impede que novos dados sejam gravados durante a exportação. - Dump do banco de dados PostgreSQL
Executepg_dump --format=custom mastodon_production > /tmp/mastodon_db.dumpcomo usuário postgres. Substituamastodon_productionpelo nome real do seu banco de dados. O formato custom é necessário para uma restauração confiável. - Copiar o arquivo .env.production
Copie/home/mastodon/live/.env.productionpara um local seguro. Este arquivo contém SECRET_KEY_BASE, OTP_SECRET e chaves VAPID. Sem ele, o novo servidor não conseguirá descriptografar tokens de usuário existentes. - Sincronizar arquivos de mídia com rsync
Executersync -avz --delete /home/mastodon/live/public/system/ user@new-server:/home/mastodon/live/public/system/. A flag –delete remove arquivos no novo servidor que não existem mais no servidor antigo. Se você usa armazenamento de objetos, pule esta etapa.
Importar Dados para o Novo Servidor
- Copiar o dump do banco de dados e .env.production para o novo servidor
Use scp ou rsync para transferir/tmp/mastodon_db.dumpe.env.productionpara o novo servidor. Coloque.env.productionem/home/mastodon/live/e defina a propriedade para o usuário mastodon. - Restaurar o banco de dados PostgreSQL
Crie um banco de dados vazio no novo servidor:createdb -O mastodon mastodon_production. Depois restaure:pg_restore --dbname=mastodon_production /tmp/mastodon_db.dumpcomo usuário postgres. A restauração recriará todas as tabelas, índices e sequências. - Executar migrações do banco de dados
Mude para o usuário mastodon e executecd /home/mastodon/live && RAILS_ENV=production bundle exec rails db:migrate. Isso atualiza o esquema para a versão atual do código. Se você pular esta etapa, a instância pode lançar erros ActiveRecord::StatementInvalid. - Pré-compilar assets
ExecuteRAILS_ENV=production bundle exec rails assets:precompile. Isso gera arquivos CSS e JavaScript para a interface web. - Iniciar serviços do Mastodon
Executesystemctl start mastodon-web mastodon-streaming mastodon-sidekiq. Verifique os logs comjournalctl -u mastodon-web -fpara erros de inicialização.
Verificar a Migração
- Testar a interface web
Abra a URL da instância em um navegador. Você deve ver a página de login e postagens existentes. Faça login com uma conta existente e verifique se a timeline inicial mostra postagens anteriores à migração. - Verificar a federação
Pesquise por uma conta remota de uma instância diferente. Se a pesquisa retornar resultados, a federação está funcionando. Caso contrário, verifique se o registro DNS A e o DNS reverso para o IP do novo servidor estão corretos. - Enviar uma postagem de teste
Crie uma nova postagem e verifique se ela aparece na timeline pública após alguns segundos. Verifique se os anexos de mídia carregam corretamente.
Problemas Comuns de Migração e Suas Soluções
Falha na Restauração do Banco de Dados com “ERROR: role ‘mastodon’ does not exist”
O comando pg_restore requer a role PostgreSQL que possui o banco de dados. Crie a role no novo servidor com createuser -s mastodon antes de executar a restauração. A flag -s concede privilégios de superusuário, necessários para algumas extensões.
Arquivos de Mídia Não Carregam Após a Migração
Se os arquivos de mídia estiverem faltando, verifique se o caminho /home/mastodon/live/public/system existe no novo servidor e tem a propriedade correta. Execute chown -R mastodon:mastodon /home/mastodon/live/public/system. Se você usa armazenamento de objetos, certifique-se de que a variável S3_ENABLED está definida como true no .env.production e o nome do bucket está correto.
Sessões de Usuário Invalidadas Após a Migração
Isso acontece quando SECRET_KEY_BASE no .env.production não corresponde ao valor antigo. Copie o arquivo exato do servidor antigo. Não regenere o segredo. Se você perdeu o arquivo, os usuários devem fazer logout e login novamente. Você pode forçar uma reinicialização da sessão executando RAILS_ENV=production bundle exec rails db:seed no novo servidor, mas isso excluirá todas as sessões existentes.
Federação Quebrada Após Mudança de IP
O Mastodon usa o nome de domínio da instância para federação, não o endereço IP. Atualize o registro DNS A para apontar para o IP do novo servidor antes de iniciar os serviços do Mastodon. Aguarde a propagação do DNS (tempo TTL). Após a propagação, outras instâncias enviarão atividades para o novo IP automaticamente.
| Item | Armazenamento no Sistema de Arquivos | Armazenamento de Objetos (S3) |
|---|---|---|
| Método de transferência de mídia | rsync do diretório public/system | Apenas atualizar variáveis de ambiente S3_ |
| Tempo de inatividade necessário | Médio (tempo de sincronização de mídia) | Baixo (apenas banco de dados) |
| Risco de perda de dados | Alto se rsync for interrompido | Baixo (mídia já remota) |
| Largura de banda de rede | Alta (cópia completa da mídia) | Nenhuma para mídia |
Agora você pode migrar uma instância Mastodon auto-hospedada para um novo servidor exportando o banco de dados PostgreSQL, copiando o arquivo .env.production e sincronizando os arquivos de mídia via rsync ou armazenamento de objetos. Após restaurar o banco de dados e executar as migrações, verifique a interface web e a federação. Para uma migração mais rápida com menos tempo de inatividade, mude para armazenamento de objetos no servidor antigo antes de mover. Isso elimina completamente a etapa de sincronização de mídia.