Como Adicionar um CDN na Frente do Endpoint de Mídia de uma Instância Mastodon

Instâncias Mastodon armazenam imagens, vídeos e outros arquivos de mídia enviados pelos usuários localmente no servidor por padrão. Conforme sua instância cresce, servir esses arquivos diretamente do servidor de aplicação aumenta o tempo de carregamento e os custos de banda. Uma CDN (Content Delivery Network) armazena em cache os arquivos de mídia em pontos de presença mais próximos dos usuários, reduzindo a latência e a carga no servidor. Este artigo explica como configurar uma CDN para servir mídia da sua instância Mastodon sem alterar o tráfego das demais funcionalidades.

Por que uma CDN Melhora a Entrega de Mídia no Mastodon

O Mastodon armazena arquivos de mídia no diretório public/system do servidor da instância. Cada vez que um usuário visualiza uma postagem com imagem ou vídeo, o servidor de aplicação Mastodon lê o arquivo do disco e o envia pela rede. Esse processo consome CPU e memória, especialmente quando vários usuários solicitam o mesmo arquivo simultaneamente. Uma CDN armazena o arquivo em cache em servidores distribuídos geograficamente. Solicitações subsequentes para o mesmo arquivo são atendidas pelo cache da borda, não pelo servidor de origem. Isso reduz a carga no servidor, acelera o carregamento de páginas para usuários distantes da instância e diminui os custos de banda.

A configuração da CDN não afeta a API, streaming ou conexões WebSocket do Mastodon. Apenas o endpoint de mídia, geralmente servido sob /system/, é roteado através da CDN. Essa separação exige uma configuração cuidadosa do NGINX para garantir que a CDN puxe a mídia do local correto enquanto o restante do aplicativo permanece direto.

Pré-requisitos Antes de Adicionar uma CDN

Antes de começar, verifique se você possui o seguinte:

• Acesso SSH root ao servidor da sua instância Mastodon.
• NGINX instalado e configurado como proxy reverso para o Mastodon.
• Uma conta de provedor de CDN como Cloudflare, Bunny CDN, Fastly ou AWS CloudFront.
• Um domínio ou subdomínio personalizado para o endpoint da CDN, por exemplo media.suainstancia.social.
• Acesso ao DNS para adicionar um registro CNAME apontando o subdomínio da CDN para o provedor de CDN.

Este guia assume que você usa NGINX como servidor web. Se usar Apache ou Caddy, adapte a sintaxe do bloco de localização conforme necessário.

Passos para Configurar a CDN para Mídia do Mastodon

Passo 1: Crie um Subdomínio Dedicado para Mídia

Escolha um subdomínio que será usado exclusivamente para entrega de mídia. Escolhas comuns são media.suainstancia.social ou files.suainstancia.social. No seu provedor de DNS, adicione um registro CNAME para este subdomínio apontando para o endpoint do provedor de CDN. Por exemplo, com Cloudflare, crie um registro CNAME para media apontando para sua-cdn.seuprovedorcdn.com. Aguarde a propagação do DNS, que geralmente leva alguns minutos.

Passo 2: Configure o NGINX para Servir Mídia Através do Subdomínio da CDN

Edite o arquivo de configuração NGINX do Mastodon, geralmente localizado em /etc/nginx/sites-available/mastodon. Você precisa adicionar um segundo bloco de servidor que escute no subdomínio de mídia e sirva apenas a localização /system/. Este bloco de servidor atuará como a origem para a CDN. Abaixo está um exemplo de configuração:

server {
    listen 443 ssl http2;
    server_name media.suainstancia.social;

    ssl_certificate /etc/letsencrypt/live/suainstancia.social/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/suainstancia.social/privkey.pem;

    root /home/mastodon/live/public;

    location /system/ {
        alias /home/mastodon/live/public/system/;
        expires 365d;
        add_header Cache-Control "public, immutable";
        add_header X-Content-Type-Options nosniff;
        try_files $uri =404;
    }

    location / {
        return 404;
    }
}

Pontos-chave nesta configuração:

• O server_name corresponde ao seu subdomínio de mídia.
• O root aponta para o diretório público do Mastodon.
• O bloco location /system/ usa alias para mapear o caminho da URL para o diretório físico system.
• Cabeçalhos de cache são definidos para um ano com immutable porque os arquivos de mídia nunca mudam após o upload.
• Todas as outras requisições ao subdomínio retornam 404, impedindo que qualquer tráfego não relacionado a mídia alcance esta origem.

Após salvar o arquivo, teste a configuração e recarregue o NGINX:

sudo nginx -t
sudo systemctl reload nginx

Passo 3: Configure a CDN para Puxar do Subdomínio de Mídia

No painel do seu provedor de CDN, crie um novo endpoint ou distribuição de CDN. Defina o servidor de origem como https://media.suainstancia.social. Configure as seguintes opções:

• Protocolo de origem: HTTPS (corresponda à configuração SSL da sua instância).
• Comportamento de cache: Armazene em cache todas as extensões de arquivos estáticos (jpg, png, gif, webp, mp4, webm, etc.) com um TTL de pelo menos 24 horas.
• Encaminhamento de string de consulta: Desative ou encaminhe apenas chaves de cache padrão para evitar fragmentação do cache.
• Certificado SSL: A CDN deve fornecer um certificado SSL gratuito para o subdomínio de mídia, ou você pode enviar o seu próprio.

Após a distribuição da CDN estar ativa, anote o hostname fornecido pela CDN, por exemplo d1234.cloudfront.net ou suainstancia.bunnycdn.com. Em seguida, atualize o registro CNAME do DNS para media.suainstancia.social apontando para este hostname da CDN. Dessa forma, as requisições ao subdomínio de mídia são atendidas pela CDN, que puxa o conteúdo do seu servidor NGINX de origem conforme necessário.

Passo 4: Atualize a Configuração de Ambiente do Mastodon

O Mastodon usa a variável de ambiente CDN_HOST para reescrever as URLs de mídia nas respostas HTML e da API. Edite o arquivo .env.production no diretório home do Mastodon (/home/mastodon/live). Adicione ou atualize a seguinte linha:

CDN_HOST=https://media.suainstancia.social

Se sua CDN suportar domínios personalizados, este valor é o mesmo que seu subdomínio de mídia. Se sua CDN exigir um hostname específico do provedor, use esse hostname. Após salvar o arquivo, reinicie os serviços do Mastodon:

cd /home/mastodon/live
RAILS_ENV=production bundle exec rails assets:precompile
sudo systemctl restart mastodon-web

Passo 5: Atualize a Política de Segurança de Conteúdo

A Política de Segurança de Conteúdo (CSP) do Mastodon controla quais domínios podem servir imagens, mídia e scripts. Se você não atualizar a CSP, os navegadores podem bloquear a mídia carregada do domínio da CDN. Adicione o domínio da CDN ao S3_ALIAS_HOST ou diretamente às diretivas CSP. No .env.production, adicione ou modifique:

S3_ALIAS_HOST=https://media.suainstancia.social

Se você usar um hostname do provedor de CDN em vez de um domínio personalizado, defina S3_ALIAS_HOST para esse hostname. Em seguida, reinicie o Mastodon novamente:

sudo systemctl restart mastodon-web

Problemas Comuns Após Adicionar uma CDN

Arquivos de Mídia Retornam Erro 404

Se os usuários virem imagens quebradas, verifique o caminho do alias no NGINX. A diretiva alias deve apontar para o diretório exato onde o Mastodon armazena a mídia. Verifique o caminho executando ls -la /home/mastodon/live/public/system/. Confirme também se a URL de origem da CDN corresponde exatamente ao subdomínio de mídia, incluindo a barra final se necessário.

Avisos de Conteúdo Misto no Navegador

Se a CDN servir mídia via HTTP enquanto a instância principal usa HTTPS, os navegadores bloqueiam o conteúdo. Certifique-se de que a CDN suporta HTTPS e que o valor de CDN_HOST começa com https://. A maioria dos provedores de CDN oferece certificados SSL gratuitos através do Let’s Encrypt ou de seu próprio gerenciador de certificados.

Conteúdo Antigo em Cache Após Atualização de Mídia

Os arquivos de mídia do Mastodon são imutáveis após o upload, portanto, o cache de conteúdo antigo geralmente não é um problema. No entanto, se você substituir um arquivo manualmente, limpe o cache da CDN para essa URL específica. A maioria dos painéis de CDN possui uma ferramenta de limpeza. Você também pode definir um TTL mais curto durante os testes e depois aumentá-lo para 365 dias quando tudo estiver funcionando.

Item	Servidor Direto	Com CDN
Latência para usuários distantes	Alta (depende da localização do servidor)	Baixa (cache na borda)
Carga de CPU do servidor por requisição	Alta (lê do disco a cada vez)	Baixa (maioria das requisições em cache)
Custo de banda	Pago pelo proprietário da instância	Geralmente incluído ou reduzido
Complexidade da configuração	Mínima (configuração padrão)	Moderada (DNS, NGINX, CDN)
Invalidação de cache	Não se aplica	Limpeza manual necessária

Agora sua instância Mastodon serve mídia através de uma CDN, reduzindo a carga no servidor e acelerando a entrega de conteúdo para usuários em todo o mundo. Para verificar a configuração, abra as ferramentas de desenvolvedor do seu navegador e inspecione a aba de rede para uma URL de mídia. A resposta deve mostrar um cabeçalho cf-cache-status ou similar indicando um cache hit. Para otimização avançada, considere ativar a compressão Brotli na CDN ou configurar uma CDN separada para ativos estáticos como arquivos JavaScript e CSS.