Para remover dados antigos do Matrix Synapse com segurança, trate o histórico da sala e a mídia como tarefas separadas. Use a API de administração de limpeza de histórico para eventos antigos da sala, a API de exclusão de mídia para mídias locais e a API de cache de mídia remota para arquivos baixados de outros servidores domésticos. Para limpeza recorrente, configure políticas de retenção para mensagens e mídias. A exclusão de linhas do banco de dados nem sempre reduz o tamanho do arquivo de banco de dados em disco imediatamente.
Escolha a limpeza que melhor se adequa ao seu objetivo.
| O que está ocupando espaço? | Usar | Limite importante |
| Mensagens antigas e outros eventos da sala | API de administração para limpeza do histórico ou retenção automática de mensagens. | A limpeza do histórico é específica para cada sala. O estado da sala é preservado; o Synapse mantém pelo menos uma mensagem em cada sala. |
| Mídia armazenada pelo seu servidor doméstico | API de exclusão de mídia local ou retenção de mídia local | Os arquivos de mídia usados em perfis e avatares de salas são protegidos por padrão pelo endpoint de data/tamanho. |
| Mídia armazenada em cache de outros servidores domésticos | API de limpeza de mídia remota ou retenção remota de mídia | Se solicitado novamente, o Synapse busca o dado novamente no servidor de origem. |
Esses controles afetam o próprio banco de dados e repositório de mídia do Synapse. Se você usa um repositório de mídia externo, como o Matrix Media Repository, o endpoint de exclusão de mídia local do Synapse não remove os arquivos armazenados lá. Consulte a documentação e a política de backup desse repositório antes de excluir dados.
Prepare-se antes de se purificar.
- Confirme qual instância do Synapse está gerenciando a mídia. Em uma implantação com workers, a limpeza de mídia é executada no worker com o parâmetro `--media-cleanup`
enable_media_repo: true; este pode ser o processo principal. Confirme seu roteamento e configuração antes de diagnosticar uma limpeza que aparentemente não está sendo executada.
- Faça backup do banco de dados e do armazenamento de mídia. Crie um backup atual e restaurável antes de uma exclusão irreversível. Anote o ID da sala e o horário limite e use um token de acesso de administrador do servidor. Não cole o token no histórico do shell compartilhado nem o publique nos logs.
- Planeje o horário limite com cuidado. Os endpoints de limpeza aceitam timestamps em milissegundos Unix. Use um horário limite derivado do UTC e verifique o número antes de enviar a solicitação. Um horário limite não é uma pré-visualização: ele pode remover permanentemente dados elegíveis.
Nos exemplos abaixo, substitua ` https://matrix.example.com<URL base>` pela URL do cliente do seu servidor doméstico, defina um ID de sala válido e exporte um token de administrador em `<URL ADMIN_TOKENbase>`. Mantenha o token de portador em sigilo.
Remover histórico de mensagens antigas de uma sala
A API Purge History remove eventos mais antigos que um ponto especificado do banco de dados do Synapse. Ela não oculta mensagens de outros servidores e não é o mesmo que remover uma sala. Por padrão, o Synapse exclui eventos enviados por usuários remotos, mas mantém os eventos de usuários locais; defina delete_local_events`isOnly` trueapenas se você pretende remover também esses eventos. O estado da sala, como a participação e o tópico, é preservado.
Por exemplo, para definir um prazo limite de 180 dias antes da hora atual em um host Linux, calcule o timestamp em milissegundos, verifique-o e, em seguida, envie a solicitação para uma única sala:
export SYNAPSE_URL='https://matrix.example.com'
export ROOM_ID='!roomid:example.com'
export ADMIN_TOKEN='replace-with-a-server-admin-token'
PURGE_BEFORE_MS=$(python3 -c 'import time; print(int((time.time() - 180*86400) * 1000))')
printf 'Cutoff (Unix milliseconds): %s\n' "$PURGE_BEFORE_MS"
curl -sS -X POST "$SYNAPSE_URL/_synapse/admin/v1/purge_history/$ROOM_ID" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H 'Content-Type: application/json' \
-d "{\"purge_up_to_ts\":$PURGE_BEFORE_MS,\"delete_local_events\":true}"
Omita delete_local_eventsou defina como falsese desejar o comportamento padrão do Synapse. Se a API retornar um valor purge_id, a limpeza foi iniciada; não necessariamente concluída. Consulte o endpoint de status até que ele reporte algo completeou investigue seu errorstatus se for failed:
curl -sS "$SYNAPSE_URL/_synapse/admin/v1/purge_history_status/$PURGE_ID" \
-H "Authorization: Bearer $ADMIN_TOKEN"
Grandes expurgos podem levar vários minutos ou mais. Durante a operação, os usuários podem ficar impossibilitados de navegar para páginas anteriores daquela sala a partir do ponto em que o expurgo está sendo feito. O Synapse mantém pelo menos uma mensagem em cada sala, portanto, esta API não deixará a linha do tempo da sala completamente vazia.
Exclua arquivos de mídia antigos e arquivos remotos em cache.
Para uma limpeza única de arquivos de mídia local usados pela última vez antes de um determinado limite, use o endpoint de mídia local atual. Ele before_tsé um timestamp Unix em milissegundos e também aceita size_gtarquivos acima de um limite de bytes. O padrão mantém os arquivos de mídia usados para imagens de perfil ou avatares de sala; não configure isso keep_profiles=falsea menos que você queira remover esses arquivos intencionalmente.
curl -sS -X POST "$SYNAPSE_URL/_synapse/admin/v1/media/delete?before_ts=$PURGE_BEFORE_MS" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H 'Content-Type: application/json' \
-d '{}'
Analise os IDs de mídia da resposta totale os IDs de mídia excluídos. O endpoint exclui os originais locais e as miniaturas. Evite o caminho antigo que contém /media/<server_name>/delete; a documentação do Synapse marca essa rota como obsoleta desde a versão 1.78.0. O endpoint de mídia local atual não opera em um repositório de mídia externo separado.
Mídia remota em cache é uma categoria separada. Para remover mídia remota do cache que foi acessada pela última vez antes do mesmo horário limite, use:
curl -sS -X POST "$SYNAPSE_URL/_synapse/admin/v1/purge_media_cache?before_ts=$PURGE_BEFORE_MS" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H 'Content-Type: application/json' \
-d '{}'
A resposta informa quantos itens em cache foram excluídos. Se os usuários solicitarem esses arquivos posteriormente, o Synapse poderá baixá-los novamente do servidor de origem; portanto, essa operação troca o uso do disco local por possível tráfego de rede e atraso na recuperação.
Configure a retenção recorrente em vez de repetir as limpezas manuais.
A retenção de mensagens do Synapse está desativada por padrão. Para impor um padrão em todo o servidor para salas sem estado de retenção próprio, adicione uma política à configuração e ative-a. Este exemplo define um máximo de um ano:
retention:
enabled: true
default_policy:
max_lifetime: 1y
Use as unidades de duração suportadas pelo Synapse, como ddias e yanos. Administradores e moderadores de salas também podem definir o m.room.retentionestado de um evento de sala, enquanto administradores de servidor podem limitar a duração máxima permitida com `max_times` allowed_lifetime_mine ` max_times` allowed_lifetime_max. Revise sua política completa antes de habilitá-la: eventos elegíveis são removidos permanentemente por tarefas de limpeza em segundo plano. O Synapse oculta eventos expirados dos clientes assim que expiram, mas a limpeza do banco de dados é executada periodicamente, portanto, as linhas podem permanecer até que uma tarefa seja executada. Eventos de estado não são cobertos pela retenção de mensagens.
Para mídias, adicione media_retentiontempos de vida, por exemplo:
media_retention:
local_media_lifetime: 90d
remote_media_lifetime: 14d
Esses tempos de vida representam períodos de inatividade, não apenas um limite de tempo de upload: quando um arquivo é acessado, o Synapse usa o último acesso registrado; para mídias nunca acessadas, ele usa a data de criação. Os arquivos originais e as miniaturas são removidos. Mídias em quarentena e mídias locais protegidas contra quarentena não são removidas por essa limpeza. Configure a retenção de mídia no processo que hospeda o repositório de mídia e, em seguida, valide a configuração com o manual de configuração da versão do Synapse que você está usando.
Leia a documentação oficial da API de Limpeza do Histórico , da API de Administração de Mídia , o manual de configuração do Synapse e a política de retenção de mensagens antes de aplicar as alterações. O comportamento da API descrito aqui reflete a documentação oficial verificada em 10 de outubro de 2026; confirme os endpoints e a configuração com a sua versão instalada.
Verificar se o espaço de armazenamento foi recuperado
- Verifique o status da limpeza do histórico até que ele indique "Concluído"
complete; mantenha o ID da limpeza e a resposta para seu registro de manutenção.
- Verifique as respostas do cache local e remoto para obter a contagem de itens excluídos e, em seguida, inspecione os registros do Synapse e o uso do sistema de arquivos após a limpeza.
- Não assuma que menos linhas no banco de dados signifiquem automaticamente um arquivo de banco de dados menor. A documentação do Synapse observa que o PostgreSQL pode reutilizar o espaço liberado sem devolvê-lo ao sistema operacional. Para o PostgreSQL,
VACUUM FULLé possível recuperar espaço em disco, mas isso requer um bloqueio exclusivo; agende essa operação considerando o tempo de inatividade/impacto e siga a documentação do VACUUM do PostgreSQL . Para o SQLite, a documentação de retenção do Synapse identifica VACUUMa operação correspondente.
- Confirme se os arquivos esperados ou eventos antigos não estão mais sendo exibidos e verifique se o seu backup permanece disponível antes de encerrar a tarefa de manutenção.