Corrigir um repositório de mídia do Matrix Synapse que está ocupando muito espaço em disco.

Um repositório de mídia do Matrix Synapse pode consumir espaço em disco mais rapidamente do que o banco de dados do servidor doméstico, pois armazena diversas classes de arquivos: mídias enviadas por usuários locais, miniaturas, mídias em cache obtidas de servidores domésticos remotos e recursos usados ​​para pré-visualizações de URLs. A solução correta não é excluir arquivos aleatórios do diretório de mídia. Primeiro, identifique o que está aumentando de tamanho e, em seguida, use a API de administração do Synapse ou os controles de retenção para que os metadados do banco de dados e os arquivos em disco permaneçam consistentes.

Em outubro de 2026, a versão mais recente do Synapse era a 1.162, e a documentação oficial de gerenciamento de mídia incluía APIs para consultar mídias, excluir mídias locais, limpar mídias remotas em cache e configurar a retenção automática. Consulte as versões oficiais do Synapse se sua instalação for significativamente antiga, pois o comportamento dos endpoints e as opções de configuração podem variar entre as versões.

Lista de verificação de triagem rápida

1. Confirme se o repositório de mídia é a causa do problema de espaço em disco.

Comece pelo sistema de arquivos, não pelo Synapse. Execute:

df -h
du -sh /path/to/media_store

O caminho é específico da instalação. media_store_pathA configuração do Synapse define o diretório usado para imagens e anexos enviados, e o padrão documentado é media_storerelativo ao diretório de dados do Synapse. Pacotes de distribuição e implantações em contêineres geralmente definem um caminho explícito, portanto, verifique sua configuração real em vez de presumir um local.

Legenda: Compare o uso do sistema de arquivos com o tamanho do armazenamento de mídia do Synapse configurado antes de decidir que a limpeza de mídia é a solução correta.

Se o disco estiver quase cheio, evite executar operações recursivas extensas que criem arquivos temporários grandes ou backups no mesmo sistema de arquivos. Se você corre o risco iminente de ficar sem espaço, primeiro interrompa tarefas não relacionadas que exigem muita gravação ou adicione capacidade temporária e, em seguida, execute a limpeza de forma controlada.

2. Verifique a configuração da mídia ativa e identifique o que está crescendo.

Abra o arquivo ativo homeserver.yamle encontre media_store_path. Verifique também max_upload_size, quaisquer media_storage_providerse quaisquer media_retentionblocos existentes. O manual de configuração oficial do Synapse documenta essas opções.

Legenda: Confirme a configuração ativa media_store_pathantes de medir ou alterar o armazenamento de mídia. O caminho mostrado aqui é um exemplo de configuração.

Em seguida, meça os subdiretórios de primeiro nível:

du -sh /path/to/media_store/* 2>/dev/null | sort -h

A documentação do repositório de mídia do Synapse descreve as categorias importantes em disco. Os uploads locais são armazenados abaixo de local_content, as miniaturas locais abaixo de local_thumbnails, os arquivos remotos em cache abaixo de remote_content, as miniaturas remotas abaixo de remote_thumbnaile os dados de pré-visualização de URL abaixo de url_cachee url_cache_thumbnails.

Legenda: Uma análise detalhada do tamanho dos arquivos em nível de diretório ajuda a distinguir o cache remoto recuperável dos uploads locais do usuário, que podem ser a única cópia armazenada pelo seu servidor doméstico.

Não utilize rm -rfesses diretórios como método de limpeza padrão. O Synapse também armazena arquivos de mídia em seu banco de dados. Ignorar os caminhos de limpeza recomendados pode deixar metadados referentes a arquivos que não existem mais ou remover conteúdo que os usuários ainda esperam recuperar.

3. Recupere primeiro o cache de mídia remoto quando ele for o consumidor principal.

Geralmente, o armazenamento em cache de mídia remota é o local de menor risco para recuperar espaço. O Synapse armazena cópias de mídias originalmente hospedadas por outros servidores domésticos. A API oficial de Limpeza de Mídia Remota remove mídias remotas em cache cujo último acesso ocorreu antes de um determinado registro de data e hora. Se um usuário solicitar essa mídia novamente, o Synapse a solicitará novamente do servidor doméstico de origem.

A API de administração requer um token de acesso de administrador do servidor. A Synapse recomenda manter esse token /_synapse/admin/...oculto do acesso público e, normalmente, chamá-lo localmente. Consulte o guia oficial da API de administração .

Por exemplo, calcule um limite de 30 dias no passado e limpe o cache remoto mais antigo que isso:

export SYNAPSE_ADMIN_TOKEN='your-admin-token'
CUTOFF_MS=$(( $(date -d '30 days ago' +%s) * 1000 ))

curl -sS -X POST   -H "Authorization: Bearer $SYNAPSE_ADMIN_TOKEN"   "http://127.0.0.1:8008/_synapse/admin/v1/purge_media_cache?before_ts=$CUTOFF_MS"

A resposta inclui uma deletedcontagem. O limite é baseado no último acesso, não apenas na data de modificação do arquivo. Escolha um período que corresponda ao histórico de navegação dos usuários. O conteúdo remoto excluído só poderá ser recuperado se o servidor de origem ainda o disponibilizar.

4. Trate a mídia local como dados permanentes, a menos que você tenha uma política de retenção.

Mídias locais são diferentes. Elas foram carregadas para o seu servidor doméstico, portanto, excluí-las pode quebrar permanentemente anexos, imagens ou outras referências MXC. Antes de excluir mídias locais em massa, inspecione itens representativos ou mídias do usuário por meio da API de administração.

Para consultar um item de mídia específico:

curl -sS   -H "Authorization: Bearer $SYNAPSE_ADMIN_TOKEN"   "http://127.0.0.1:8008/_synapse/admin/v1/media/example.org/MEDIA_ID"

A resposta pode incluir media_lengtho tipo MIME e o status de quarentena. A documentação oficial created_tsda API Media Admin define esses campos e as operações de exclusão suportadas.last_access_ts

Legenda: Consulte os metadados da mídia antes de aplicar as regras de exclusão para que as decisões sobre idade e tamanho sejam baseadas nos registros do Synapse, em vez dos carimbos de data/hora do sistema de arquivos.

O Synapse pode excluir mídias locais por data de último acesso e, opcionalmente, por tamanho:

CUTOFF_MS=$(( $(date -d '180 days ago' +%s) * 1000 ))

curl -sS -X POST   -H "Authorization: Bearer $SYNAPSE_ADMIN_TOKEN"   "http://127.0.0.1:8008/_synapse/admin/v1/media/delete?before_ts=$CUTOFF_MS&size_gt=0&keep_profiles=true"

before_tsé um timestamp Unix em milissegundos e se refere ao último acesso. size_gté um limite de bytes; seu valor padrão é zero. keep_profiles=trueé o padrão e preserva as mídias ainda usadas como imagens de perfil ou de sala. Mantenha essa proteção, a menos que você tenha um motivo específico para remover essas imagens.

Você também pode listar ou excluir mídias enviadas por um usuário local específico com /_synapse/admin/v1/users/<user_id>/media. Isso é útil quando uma conta é responsável por um crescimento incomum. Consulte a documentação da API de Administração de Usuários antes de usar a operação de exclusão, especialmente os parâmetros de ordenação e limite.

5. Impedir que o Media Store preencha o disco novamente

Ativar retenção automática de mídia

Para controle contínuo, o Synapse fornece [instruções específicas media_retention]. Um exemplo baseado no formato de configuração oficial é:

media_retention:
  local_media_lifetime: 180d
  remote_media_lifetime: 30d

Os arquivos de mídia podem ser removidos quando não forem acessados ​​durante o período de tempo configurado. Se nunca forem acessados, o Synapse usa a data de criação. Tanto o arquivo original quanto as miniaturas são removidos. Se o período de tempo for omitido ou definido como nulo, a categoria não será excluída automaticamente.

Escolha o valor local com cautela: ao contrário do cache remoto, mídias locais excluídas não podem ser reconstruídas simplesmente solicitando o arquivo original a outro servidor doméstico. Mídias em quarentena não são excluídas pela retenção automática, e mídias locais protegidas também são excluídas, conforme a documentação de configuração.

Utilize controles de upload para crescimento futuro.

max_upload_sizelimita cada upload individual; não limita o tamanho total do repositório. O Synapse atual também oferece suporte media_upload_limitspara limitar a quantidade de uploads que um usuário pode fazer durante períodos de tempo definidos. Esses controles reduzem o crescimento, mas não substituem o monitoramento de retenção ou capacidade.

Considere um provedor de armazenamento quando o sistema de arquivos local for o gargalo.

O Synapse oferece suporte a isso media_storage_providers, incluindo um provedor de sistema de arquivos que pode colocar mídias em outro diretório. Isso pode ser útil quando você tem um volume ou camada de armazenamento dedicado. Trata-se de uma alteração na arquitetura de armazenamento, não de um comando de limpeza de emergência; portanto, teste backups, permissões, acesso de workers e comportamento de recuperação antes de migrar mídias de produção.

Verificação após a limpeza

Após qualquer limpeza, verifique a capacidade e o comportamento do aplicativo:

df -h
du -sh /path/to/media_store
du -sh /path/to/media_store/* 2>/dev/null | sort -h

• Abra um anexo carregado localmente recentemente em um cliente Matrix.
• Abra um anexo remoto antigo e confirme se ele pode ser recuperado novamente.
• Verifique os registros do Synapse em busca de erros relacionados ao media-worker ou ao sistema de arquivos.
• Se você utiliza workers dedicados para mídia, confirme se as requisições da API de administração estão sendo roteadas para um worker de repositório de mídia. A documentação do worker do Synapse lista os endpoints de administração específicos para mídia que devem ser tratados lá.
• Registre o tamanho do armazenamento de mídia após a limpeza e compare-o novamente após alguns dias para medir a taxa de crescimento real.

Referência rápida para tomada de decisões

Conclusão

Quando um repositório de mídia do Matrix Synapse preenche um disco, primeiro determine qual classe de mídia é responsável. O cache remoto geralmente é o alvo inicial mais seguro, pois o Synapse possui uma API de limpeza dedicada e normalmente consegue recuperar esse conteúdo. A mídia local requer uma política muito mais rigorosa, pois pode ser a única cópia de um anexo no servidor. Assim que o espaço imediato for recuperado, configure media_retentione monitore a taxa de crescimento do armazenamento de mídia para que a limpeza se torne uma manutenção previsível, em vez de uma emergência.