Como Criar um Backup Automático do Mastodon para o S3

O Mastodon armazena seus dados, incluindo publicações, mídias e seguidores, no servidor que você escolheu. Se perder o acesso a esse servidor ou ele for desativado, seus dados podem desaparecer. A exportação manual pela interface web cria um arquivo de backup, mas você precisa baixá-lo toda vez e armazená-lo localmente. Este artigo explica como automatizar esse processo de exportação e enviar o arquivo diretamente para um bucket Amazon S3 usando um script simples e uma tarefa agendada.

A automação usa a API do Mastodon para disparar uma exportação e uma ferramenta de linha de comando para enviar o arquivo resultante ao S3. Você não precisa de habilidades avançadas de programação. Basta ter um token de acesso do Mastodon, uma conta AWS com um bucket S3 e um sistema que possa executar um script em um cronograma. Após a configuração, seu backup será executado sem intervenção manual.

Este guia cobre todo o processo: gerar um token de API do Mastodon, criar um script Python para buscar a exportação, instalar a AWS CLI para o upload e agendar o script no Windows ou Linux. Você também aprenderá a lidar com erros comuns, como tokens expirados ou falhas de upload.

Como funciona a automação da exportação do Mastodon

O Mastodon fornece um endpoint da API REST que dispara uma exportação completa da conta. A exportação inclui seus toots, anexos de mídia, listas, favoritos e dados de seguidores. O servidor gera um arquivo zip e retorna uma URL de download. Você deve autenticar com um token de acesso que tenha o escopo read.

O script de automação envia uma requisição POST para o endpoint de exportação, aguarda a geração do arquivo e então baixa o arquivo. Após o download, o script chama a AWS CLI para copiar o arquivo para o seu bucket S3. O script também faz a limpeza excluindo o arquivo local após o upload bem-sucedido.

Pré-requisitos

Antes de escrever o script, prepare o seguinte:

• Uma conta no Mastodon em qualquer instância. A instância deve suportar acesso à API, o que a maioria das instâncias públicas faz.
• Uma conta AWS com um bucket S3. O bucket deve ter permissões de gravação para o usuário ou função IAM que você usar.
• AWS CLI instalada e configurada na máquina que executará o script. Execute aws configure para definir sua chave de acesso, chave secreta e região.
• Python 3.6 ou superior com a biblioteca requests instalada. Instale com pip install requests.

Passos para criar o script de backup automático

Passo 1: Gerar um token de acesso à API do Mastodon

1. Acesse as configurações da sua conta no Mastodon
   Clique no ícone de engrenagem na interface web do Mastodon e selecione Preferências.
2. Navegue até Desenvolvimento
   Na barra lateral esquerda, clique em Desenvolvimento.
3. Crie um novo aplicativo
   Clique no botão Novo Aplicativo.
4. Configure o aplicativo
   Digite um nome como “Script de Backup Automático”. Em Escopos, selecione apenas read. Não selecione escopos write ou follow.
5. Envie e copie o token
   Clique em Enviar. Na próxima página, copie o valor de Seu token de acesso. Armazene-o com segurança. Você o adicionará ao script posteriormente.

Passo 2: Escrever o script de backup em Python

Crie um novo arquivo chamado mastodon_backup.py e cole o código a seguir. Substitua os valores de espaço reservado pelos seus próprios.

import requests
import os
import subprocess
from datetime import datetime

# Configuração
MASTODON_INSTANCE = "https://sua-instancia.example"  # Substitua pela URL da sua instância
ACCESS_TOKEN = "seu_token_de_acesso_aqui"               # Substitua pelo seu token
S3_BUCKET = "s3://seu-nome-de-bucket/backups/"          # Substitua pelo caminho do seu bucket
LOCAL_DIR = "/tmp/mastodon_backup"                    # Diretório temporário para download

# Cria o diretório temporário se não existir
os.makedirs(LOCAL_DIR, exist_ok=True)

# Passo 1: Solicitar exportação
export_url = f"{MASTODON_INSTANCE}/api/v1/exports"
headers = {"Authorization": f"Bearer {ACCESS_TOKEN}"}
response = requests.post(export_url, headers=headers)

if response.status_code != 200:
    print(f"Falha ao solicitar exportação: {response.status_code}")
    exit(1)

data = response.json()
export_id = data.get("id")
status_url = f"{MASTODON_INSTANCE}/api/v1/exports/{export_id}"

# Passo 2: Aguardar até que a exportação esteja pronta
import time
while True:
    status_response = requests.get(status_url, headers=headers)
    if status_response.status_code != 200:
        print(f"Falha ao verificar status da exportação: {status_response.status_code}")
        exit(1)
    status_data = status_response.json()
    if status_data.get("processed"):
        download_url = status_data.get("url")
        break
    time.sleep(10)

# Passo 3: Baixar o arquivo
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
local_file = os.path.join(LOCAL_DIR, f"mastodon_export_{timestamp}.zip")
print(f"Baixando exportação para {local_file}")
download_response = requests.get(download_url, headers=headers)
with open(local_file, "wb") as f:
    f.write(download_response.content)

# Passo 4: Enviar para o S3
print(f"Enviando para {S3_BUCKET}")
result = subprocess.run(["aws", "s3", "cp", local_file, S3_BUCKET], capture_output=True, text=True)
if result.returncode != 0:
    print(f"Falha no upload: {result.stderr}")
    exit(1)

# Passo 5: Limpar arquivo local
os.remove(local_file)
print("Backup concluído com sucesso")

Passo 3: Testar o script manualmente

1. Abra um terminal ou prompt de comando
   Navegue até o diretório que contém mastodon_backup.py.
2. Execute o script
   Digite python mastodon_backup.py. O script solicitará a exportação, baixará e enviará para o S3. Verifique a saída do console em busca de erros.
3. Verifique o upload
   Faça login no Console de Gerenciamento da AWS, abra seu bucket S3 e confirme se o arquivo zip aparece na pasta backups/.

Passo 4: Agendar o script para execução automática

Escolha o método de agendamento para seu sistema operacional.

Windows: Agendador de Tarefas

1. Abra o Agendador de Tarefas
   Pressione Win+R, digite taskschd.msc e pressione Enter.
2. Crie uma nova tarefa
   Clique em Criar Tarefa no painel Ações. Dê um nome como “Backup Mastodon”.
3. Defina o gatilho
   Vá para a guia Gatilhos e clique em Novo. Defina a frequência como semanal ou mensal. Clique em OK.
4. Defina a ação
   Vá para a guia Ações e clique em Novo. Defina Ação como Iniciar um programa. Em Programa/script, insira o caminho completo para python.exe. Em Adicionar argumentos, insira o caminho completo para mastodon_backup.py. Clique em OK.
5. Configure condições
   Desmarque Iniciar a tarefa apenas se o computador estiver na alimentação CA se quiser que execute na bateria. Clique em OK para salvar.

Linux: cron

1. Abra o editor crontab
   Execute crontab -e no terminal.
2. Adicione uma linha cron
   Adicione a seguinte linha para executar o script todo domingo às 3h:
   0 3 0 /usr/bin/python3 /home/usuario/mastodon_backup.py
3. Salve e saia
   O cron habilitará automaticamente o job.

Problemas comuns e como resolvê-los

API do Mastodon retorna 401 Não Autorizado

O token de acesso está incorreto ou expirou. Gere um novo token em Preferências > Desenvolvimento. Certifique-se de que o token tenha o escopo read. Copie o novo token para o script.

Solicitação de exportação retorna 422 Entidade Não Processável

Sua conta no Mastodon pode ter muitas exportações pendentes. Aguarde 15 minutos e tente novamente. O servidor limita a frequência com que você pode solicitar uma exportação completa. Se o erro persistir, verifique a documentação do limite de taxa da API da instância.

Falha no upload da AWS CLI com Acesso Negado

O usuário ou função IAM usado pela AWS CLI não tem permissão para gravar no bucket S3. Anexe a política AmazonS3FullAccess ao usuário IAM ou use uma política mais restritiva que inclua s3:PutObject no ARN do bucket.

Script é executado, mas nenhum arquivo aparece no S3

Verifique a saída do console em busca de mensagens de erro. O script pode ter falhado durante o download ou upload. Execute o script manualmente com python mastodon_backup.py para ver a saída completa. Verifique se a AWS CLI está configurada com a região e credenciais corretas.

Exportação manual vs backup automatizado para S3: principais diferenças

Item	Exportação manual via interface web	Script de backup automatizado para S3
Método de disparo	Clicar em um botão em Preferências > Exportar	Requisição à API a partir de um script agendado
Local de armazenamento	Pasta de download do computador local	Bucket Amazon S3 (nuvem)
Frequência	Deve ser feita manualmente a cada vez	Executa em um cronograma (cron ou Agendador de Tarefas)
Retenção de arquivos	Depende dos hábitos de backup local do usuário	Mantido automaticamente no S3 com versionamento, se ativado
Segurança	Arquivo armazenado no disco local, sem criptografia em repouso por padrão	S3 suporta criptografia do lado do servidor (SSE-S3 ou SSE-KMS)

Agora você tem um sistema totalmente automatizado que exporta seus dados do Mastodon e os armazena com segurança no Amazon S3. O script é executado em um cronograma definido por você, então nunca precisará lembrar de fazer backup manualmente. Para proteção extra, ative o versionamento do S3 no seu bucket para reter várias cópias de backup. Se você gerencia várias contas no Mastodon, modifique o script para percorrer o token e o caminho do bucket de cada conta.