Como limpar o histórico de mensagens e arquivos de mídia antigos no Matrix Synapse

Cenário de exemplo (apenas ilustrativo): A Northstar Community, uma organização sem fins lucrativos hipotética, utiliza um servidor doméstico Matrix Synapse. Seu banco de dados e armazenamento de mídia estão crescendo, e o administrador deseja remover o histórico de salas antigas e mídias desatualizadas sem excluir acidentalmente discussões atuais ou imagens de perfil. Este exemplo não se refere a uma implementação real ou a um resultado comprovado em testes.

A chave é tratar o histórico de mensagens e a mídia como tarefas de limpeza separadas. O Synapse possui uma API para limpeza do histórico de salas e ferramentas separadas para limpeza de mídia; uma configuração de retenção de mídia também pode remover arquivos, enquanto os eventos do Matrix que os referenciam permanecem. Primeiro, decida o que deve permanecer disponível, depois faça backup do banco de dados e do armazenamento de mídia, escolha o método apropriado e verifique ambas as áreas de armazenamento posteriormente.

Decida o que "antigo" significa para o seu servidor.

Antes de alterar a configuração ou acionar um endpoint destrutivo, defina uma regra de retenção. No exemplo da Northstar, suponha que o conselho aprove a retenção do histórico de salas comuns por 180 dias, a manutenção de uploads locais sob uma política semelhante e o tratamento de mídias remotas como um cache que pode ser recuperado quando necessário. Uma organização diferente pode precisar de anos de retenção por motivos legais, operacionais ou relacionados à comunidade. Esses períodos são exemplos, não recomendações universais.

Separe os dados em duas categorias:

• Eventos da sala: mensagens e outros eventos armazenados no banco de dados do Synapse. A exclusão de eventos altera o período de navegação que os usuários podem realizar na sala.
• Mídia: arquivos enviados, miniaturas e cópias em cache de arquivos de outros servidores domésticos. Esses itens ficam armazenados no repositório de mídia ou em um repositório externo configurado.

A documentação oficial do Synapse descreve as políticas de retenção para eventos e limpeza de mídia de forma independente. A limpeza do histórico de salas não comprova, por si só, que o armazenamento de mídia foi limpo, e a exclusão de um arquivo de mídia não apaga o evento a ele vinculado. Comece registrando o tamanho do banco de dados, o tamanho do armazenamento de mídia, as salas afetadas e o prazo limite pretendido. Consulte o manual de configuração do Synapse .

Faça um backup antes de excluir.

Faça um backup do banco de dados usando o procedimento recomendado para o seu mecanismo de banco de dados e também faça backup do repositório de mídia ou armazenamento de mídia externo. Um backup do banco de dados sozinho não preserva os arquivos enviados; um backup de mídia sozinho não restaura os eventos da sala. Confirme se os backups são legíveis e se você sabe como restaurá-los antes de prosseguir. Se o Synapse for executado em contêineres ou usar nós de trabalho separados, inclua a configuração e os volumes de armazenamento relevantes em seu plano de manutenção.

Para o servidor hipotético da Northstar, o administrador registra os tamanhos do banco de dados e do armazenamento de mídia e confirma um ponto de restauração recente antes de acessar as salas compartilhadas. Isso é útil porque uma "limpeza" só é bem-sucedida se remover os dados pretendidos, deixando o conteúdo necessário recuperável.

Selecione a retenção programada para limpeza contínua.

Se você deseja que o Synapse continue aplicando uma política, configure a retenção de eventos e a retenção de mídia separadamente na configuração do servidor doméstico. Por exemplo, um administrador poderia adaptar este exemplo para um servidor cuja política aprovada seja de 180 dias para o histórico de salas e mídia local, com um cache de mídia remota de 30 dias:

retention:
  enabled: true
  default_policy:
    max_lifetime: 180d

media_retention:
  local_media_lifetime: 180d
  remote_media_lifetime: 30d

Esta é uma configuração ilustrativa, não uma política padrão para todos os servidores. O Synapse documenta que o recurso de retenção de eventos está desativado por padrão. Isso default_policyse aplica a salas que não possuem um m.room.retentionevento de estado; os administradores de sala podem definir políticas para a sala, enquanto os administradores de servidor podem limitar a duração das políticas com as configurações de tempo de vida permitido documentadas. Se você precisar de um limite superior consistente, revise esses controles e as políticas de sala já em uso, em vez de presumir que o padrão abrange todas as salas.

O tempo de vida dos arquivos de mídia é baseado no tempo decorrido desde o último acesso a um item de mídia. Se um item nunca foi acessado, o Synapse usa a data de sua criação. Essa configuração se aplica a originais e miniaturas; tempos de vida não definidos ou nulos não removem essa categoria de mídia. Um item armazenado em cache remotamente pode ser solicitado novamente de sua origem após ter sido removido. Mídias em quarentena e mídias protegidas localmente são exceções e não são removidas por essas configurações de retenção. A limpeza de mídia é executada no processo ou worker do Synapse que a enable_media_repohabilitou. Consulte a documentação atual sobre retenção e media_retention e, em seguida, aplique a configuração usando o procedimento normal de reinicialização ou implantação da sua instalação.

Antes de adotar o exemplo, compare seu comportamento com suas necessidades. Se uma mensagem de sala precisar permanecer legível com seu anexo por 180 dias, não escolha um tempo de vida útil de mídia menor, a menos que você aceite que a mensagem possa sobreviver ao arquivo disponível localmente. Verifique se sua mídia está armazenada no próprio Synapse ou em um repositório de mídia externo; a API de exclusão de mídia local do Synapse não remove mídias armazenadas em um repositório externo.

Excluir eventos antigos da sala sob demanda

Para uma limpeza única, utilize a API de Administração de Limpeza de Histórico do Synapse. Isso requer um token de acesso de administrador do servidor ; ser administrador de uma sala individual não é a mesma coisa. O Synapse recomenda manter a API de Administração oculta da visualização pública e, normalmente, fazer essas solicitações a partir do servidor ou de um host de administração confiável. Não cole um token de acesso ativo no histórico de shell compartilhado, em tickets ou em logs.

A solicitação deve especificar um limite usando um ID de evento ou um timestamp Unix em milissegundos. O exemplo de shell a seguir é ilustrativo. Substitua o servidor doméstico, o ID da sala, a variável de token e o limite de exemplo pelos valores que você analisou. O exemplo também solicita explicitamente a exclusão de eventos de mensagens de usuários locais:

export SYNAPSE_ADMIN_TOKEN='replace-with-a-server-admin-token'
PURGE_CUTOFF_MS=1760000000000  # replace with the approved UTC cutoff

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $SYNAPSE_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  --data "{\"purge_up_to_ts\": $PURGE_CUTOFF_MS, \"delete_local_events\": true}" \
  "https://matrix.example.org/_synapse/admin/v1/purge_history/!room:example.org"

Sem o delete_local_events: trueparâmetro `--cuttime`, o Synapse preserva, por padrão, os eventos enviados por usuários locais; eventos enviados remotamente podem ser excluídos. O estado da sala, como a associação e o estado do tópico, é preservado. O Synapse também mantém pelo menos uma mensagem em cada sala. A operação pode levar vários minutos ou mais, e os usuários não podem navegar para páginas anteriores da seção que está sendo excluída enquanto ela estiver em execução. A API retorna um ID de exclusão imediatamente; faça polling /_synapse/admin/v1/purge_history_status/<purge_id>até que o status seja `true` completeou investigue o erro se for `false` failed. Consulte a documentação da API de Exclusão do Histórico antes de selecionar um limite. Em particular, verifique se a remoção de eventos locais é apropriada para suas salas.

Limpe a mídia local e o cache remoto separadamente.

Para limpezas recorrentes, use media_retentione escolha tempos de vida que correspondam à disponibilidade prometida aos usuários. Para uma limpeza única, o Synapse oferece endpoints distintos:

• Mídia local: POST /_synapse/admin/v1/media/delete?before_ts=<timestamp_ms> remove mídias locais elegíveis com base no horário do último uso. A API também aceita um limite de tamanho. Mídias de perfil e avatares de sala são mantidas por padrão; não desative essa proteção a menos que você tenha analisado cuidadosamente as consequências.
• Mídia remota em cache: POST /_synapse/admin/v1/purge_media_cache?before_ts=<timestamp_ms> remove a mídia remota em cache cujo último acesso ocorreu antes do horário limite. Se um usuário solicitar um arquivo remoto removido posteriormente, o Synapse poderá solicitá-lo novamente do servidor de origem.

Ambos os endpoints usam um timestamp Unix positivo em milissegundos, e o limite de exclusão de mídia é baseado no último acesso, não apenas na data de upload ou criação. A API de exclusão de mídia local remove o arquivo e as miniaturas do armazenamento do Synapse, incluindo cópias em cache local de arquivos remotos; ela não limpa um repositório de mídia externo. A resposta informa o número de itens excluídos. Consulte a API de administração de mídia do Synapse para obter os parâmetros atuais e os detalhes do endpoint antes de executar uma solicitação.

No exemplo do Northstar, um administrador primeiro testaria o limite em relação à política aprovada e verificaria se os IDs ou contagens retornados pelo endpoint correspondem às expectativas. Se o cache remoto for a única fonte de crescimento, excluir os uploads locais seria a operação errada. Se os uploads locais precisarem permanecer disponíveis, escolha um tempo de vida local mais longo ou evite o endpoint de exclusão de mídia local.

Meça o resultado e mude de rumo quando necessário.

Após cada tarefa, verifique se a limpeza foi concluída com sucesso, revise a contagem de respostas da API, confirme se as salas representativas exibem o limite de histórico esperado e compare o uso do banco de dados e do armazenamento de mídia separadamente. Uma redução no número de linhas do banco de dados pode não se refletir imediatamente em uma redução equivalente no uso de disco do sistema operacional; a recuperação de espaço no banco de dados depende do mecanismo do banco de dados e de seus procedimentos de manutenção. Siga as orientações do fornecedor do banco de dados em vez de excluir arquivos do banco de dados manualmente.

Se o banco de dados diminuir, mas o armazenamento de mídia não, verifique a retenção de mídia, o enable_media_repostatus do processo de mídia (em quarentena ou proteção) e se os arquivos estão armazenados externamente. Se o uso de mídia cair, mas mensagens antigas permanecerem, isso é esperado quando apenas a mídia foi excluída. Se eventos permanecerem inesperadamente, verifique se a retenção está habilitada, se a sala possui seu próprio estado de retenção, se eventos locais foram preservados intencionalmente e se o status de exclusão foi concluído.

Para o Northstar, o critério de sucesso não é simplesmente "o disco está menor". É que o limite do histórico antigo aprovado esteja visível, as mensagens e anexos atuais necessários ainda funcionem, a categoria de mídia pretendida tenha sido limpa e ambos os backups permaneçam disponíveis. Se essas verificações falharem, interrompa as limpezas adicionais e inspecione a política da sala, a resposta da API, a configuração do worker e o backend de armazenamento antes de ampliar a limpeza.

Limitações a ter em mente

As políticas de retenção não substituem a análise jurídica ou de retenção de registros de uma organização. A federação significa que outros servidores domésticos podem manter suas próprias cópias de eventos ou mídias, e o Synapse não pode garantir a exclusão desses dados desses servidores. A limpeza remota de mídia remove o cache deste servidor; ela não exclui o arquivo original no servidor doméstico de origem. Da mesma forma, excluir um evento local ou um objeto de mídia do Synapse não recupera uma cópia que outro participante já tenha baixado.

Use a retenção agendada quando precisar de uma política repetível; use as APIs de administração para uma limpeza direcionada e revisada. Mantenha as duas operações separadas no seu registro de alterações, pois seus sinais de sucesso e efeitos são diferentes.