Como Resolver o Erro ‘Falha no Upload de Armazenamento de Objetos’ no Mastodon com S3

Instâncias do Mastodon que usam armazenamento de objetos compatível com S3 para arquivos de mídia podem encontrar o erro “Falha no Upload de Armazenamento de Objetos” quando usuários tentam anexar imagens, vídeos ou outros arquivos a postagens. Esse erro geralmente aparece como uma faixa vermelha na interface web ou como uma falha registrada nos jobs sidekiq do Mastodon. A causa raiz é quase sempre uma configuração incorreta nas variáveis de ambiente do Mastodon que controlam o acesso ao S3 ou uma restrição no nível de rede bloqueando a solicitação de upload. Este artigo explica os valores de configuração específicos que devem estar corretos, fornece instruções passo a passo para verificar e corrigir cada configuração e cobre padrões de falha relacionados, como timeouts e erros de permissão.

Por que o Mastodon Falha ao Fazer Upload de Mídia para o Armazenamento de Objetos S3

O Mastodon armazena mídias enviadas por usuários, como fotos de perfil, imagens de cabeçalho e anexos de postagens. Por padrão, o Mastodon salva esses arquivos no sistema de arquivos local. Quando você ativa o armazenamento de objetos compatível com S3, o Mastodon usa o AWS SDK para Ruby para fazer upload de arquivos para um bucket remoto. O processo de upload envolve várias etapas: o processo web do Mastodon recebe o arquivo, o sidekiq processa o job de upload e o SDK envia uma solicitação PUT para o endpoint S3. Se alguma das variáveis de ambiente que controlam esse processo estiver ausente, incorreta ou desalinhada com os requisitos do provedor S3, o upload falha.

As causas raiz mais comuns são:

• S3_ENABLED ausente ou incorreto: O Mastodon ignora todas as configurações S3 se esta variável não estiver definida como true.
• S3_PROTOCOL ou S3_HOSTNAME errados: Para provedores S3 que não são da AWS, como DigitalOcean Spaces ou MinIO, você deve definir esses valores para a URL de endpoint correta.
• Permissões do bucket: O usuário IAM ou a chave de acesso deve ter permissões s3:PutObject e s3:PutObjectAcl no bucket.
• Rede ou firewall bloqueando: O servidor Mastodon deve conseguir acessar o endpoint S3 via HTTPS na porta 443.

Passos para Diagnosticar e Corrigir o Erro de Upload S3 no Mastodon

Siga estes passos em ordem. Teste após cada alteração fazendo upload de um arquivo de imagem pequeno em qualquer postagem do Mastodon.

1. Verifique o arquivo de ambiente do Mastodon
   Acesse via SSH o servidor Mastodon como usuário mastodon. Abra o arquivo .env.production localizado no diretório home do Mastodon, geralmente /home/mastodon/live/.env.production. Execute: sudo -u mastodon nano /home/mastodon/live/.env.production. Verifique se as seguintes linhas existem e não estão comentadas:
2. Confirme que S3_ENABLED está definido como true
   Procure pela linha S3_ENABLED=true. Se estiver ausente ou definida como false, o Mastodon não usará S3 e tentará salvar arquivos localmente, o que também pode falhar se o caminho de armazenamento local estiver mal configurado.
3. Verifique as credenciais AWS
   Certifique-se de que estas linhas estão presentes:
   AWS_ACCESS_KEY_ID=sua-chave-de-acesso
AWS_SECRET_ACCESS_KEY=sua-chave-secreta
   A chave de acesso deve ter permissões de escrita no bucket S3. Se não tiver certeza, gere um novo par de chaves no painel de controle do seu provedor S3.
4. Defina o nome e a região corretos do bucket
   Verifique se S3_BUCKET=nome-do-seu-bucket corresponde exatamente ao bucket que você criou. Para a região, use S3_REGION=us-east-1 ou a região que seu provedor usa. O DigitalOcean Spaces usa a região nyc3 ou ams3.
5. Configure o endpoint S3 para provedores que não são AWS
   Se você usa um provedor diferente da AWS, defina:
   S3_PROTOCOL=https
S3_HOSTNAME=nyc3.digitaloceanspaces.com
   Substitua o hostname pelo endpoint do seu provedor. Para MinIO, use o IP ou domínio do seu servidor MinIO.
6. Defina S3_ALIAS_HOST se necessário
   Se o seu bucket S3 for acessado por meio de um domínio personalizado ou CDN, defina S3_ALIAS_HOST=https://media.seudominio.com. Isso informa ao Mastodon para servir URLs de mídia a partir desse domínio em vez do endpoint S3 direto.
7. Reinicie os serviços do Mastodon
   Após salvar o arquivo de ambiente, reinicie todos os processos do Mastodon para que as alterações entrem em vigor. Execute:
   sudo systemctl restart mastodon-web mastodon-sidekiq mastodon-streaming
8. Teste o upload
   Faça login na sua instância do Mastodon como administrador ou usuário comum. Crie um novo toot e anexe um arquivo de imagem com menos de 5 MB. Se o upload for bem-sucedido, o erro está resolvido.

Se o Mastodon Ainda Mostrar Falha no Upload Após as Alterações de Configuração

Configuração CORS do bucket S3 bloqueia uploads

Mesmo com as configurações corretas do Mastodon, o próprio bucket S3 pode rejeitar uploads devido a cabeçalhos CORS ausentes ou incorretos. Faça login no painel de controle do seu provedor S3 e adicione a seguinte regra CORS ao bucket:

[
  {
    "AllowedHeaders": [""],
    "AllowedMethods": ["PUT", "POST", "GET", "HEAD"],
    "AllowedOrigins": ["https://sua-instancia-mastodon.com"],
    "ExposeHeaders": ["ETag"]
  }
]

Substitua a origem pelo domínio da sua instância Mastodon. Se estiver testando localmente, use http://localhost:3000.

Política do bucket nega PutObject para a chave de acesso

O usuário IAM ou a chave de acesso deve ter uma política que permita s3:PutObject. Uma política típica é assim:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:PutObjectAcl",
        "s3:GetObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::nome-do-seu-bucket/"
    }
  ]
}

Anexe esta política ao usuário associado à chave de acesso. Para DigitalOcean Spaces, use a chave de acesso Spaces com as permissões apropriadas no painel de controle Spaces.

Firewall ou DNS bloqueia o endpoint S3

A partir do servidor Mastodon, teste a conectividade com o endpoint S3 usando curl. Execute:
curl -I https://nyc3.digitaloceanspaces.com
Se o comando travar ou retornar um timeout, verifique as regras de firewall do seu servidor. Certifique-se de que o tráfego HTTPS de saída para o intervalo de IP do endpoint S3 seja permitido. Verifique também se a resolução DNS funciona para o hostname.

Tamanho do arquivo excede o limite do bucket S3 ou do Mastodon

O Mastodon tem um limite de tamanho de arquivo padrão de 8 MB para anexos. Alguns provedores S3 impõem um limite menor. Verifique a documentação do seu provedor. Você pode ajustar o limite do Mastodon definindo MAX_IMAGE_SIZE e MAX_VIDEO_SIZE no arquivo de ambiente, mas o provedor S3 deve aceitar o tamanho maior.

Configuração S3 do Mastodon vs Armazenamento Local: Principais Diferenças

Item	Armazenamento de Objetos S3	Sistema de Arquivos Local
Local de armazenamento	Bucket remoto em provedor compatível com S3	Disco local no servidor Mastodon
Variável de ambiente necessária	S3_ENABLED=true mais credenciais AWS e endpoint	Nenhuma variável S3 necessária
Escalabilidade	Alta; armazenamento independente do disco do servidor	Limitada pela capacidade do disco do servidor
Estratégia de backup	Replicação gerenciada pelo provedor ou bucket de backup separado	Backup manual do diretório public/system
Causa da falha de upload	Configuração incorreta do ambiente, permissões do bucket ou rede	Disco cheio, permissões incorretas em diretórios locais
Correção típica	Verificar S3_ENABLED, credenciais, endpoint e CORS	Liberar espaço em disco ou corrigir propriedade de /home/mastodon/live/public/system

Agora você pode resolver o erro “Falha no Upload de Armazenamento de Objetos” verificando cada variável de ambiente S3 no arquivo .env.production do Mastodon, reiniciando os serviços e confirmando que as políticas CORS e IAM do bucket permitem operações de escrita. Se o problema persistir, teste a conectividade de rede com o endpoint S3 e verifique os logs do sidekiq do Mastodon para mensagens de erro detalhadas usando journalctl -u mastodon-sidekiq -n 50. Para manutenção contínua, monitore o uso de armazenamento do bucket e configure políticas de ciclo de vida para excluir arquivos de mídia antigos automaticamente.