Per rimuovere in modo sicuro i vecchi dati di Matrix Synapse, tratta la cronologia delle stanze e i file multimediali come processi separati. Utilizza l'API di amministrazione per la pulizia della cronologia per gli eventi delle stanze obsoleti, l'API di eliminazione dei file multimediali per i file multimediali locali e l'API della cache dei file multimediali remota per i file scaricati da altri homeserver. Per una pulizia periodica, configura le policy di conservazione per messaggi e file multimediali. La pulizia delle righe del database non sempre riduce immediatamente le dimensioni del file del database su disco.
Scegli la pulizia più adatta al tuo obiettivo
| Cosa occupa spazio? | Utilizzo | Limite importante |
| Vecchi messaggi e altri eventi della stanza | Elimina la cronologia tramite API di amministrazione o conserva automaticamente i messaggi. | La cancellazione della cronologia è specifica per ogni stanza. Lo stato della stanza viene preservato; Synapse conserva almeno un messaggio in ogni stanza. |
| File multimediali archiviati dal tuo homeserver | Elimina l'API dei media locali o la conservazione dei media locali | I contenuti multimediali utilizzati nei profili e negli avatar delle stanze sono protetti per impostazione predefinita dall'endpoint data/dimensione. |
| I file multimediali memorizzati nella cache da altri server domestici | Eliminazione dell'API per i media remoti o conservazione dei media remoti | Se richiesto nuovamente, Synapse lo recupera di nuovo dal server di origine. |
Questi controlli influiscono sul database e sul repository multimediale di Synapse. Se si utilizza un repository multimediale esterno, come Matrix Media Repository, l'endpoint di eliminazione dei file multimediali locali di Synapse non rimuove i file ivi archiviati. Prima di eliminare i dati, consultare la documentazione e le politiche di backup del repository in questione.
Preparati prima di purificarti
- Verifica quale istanza di Synapse gestisce i file multimediali. In una distribuzione worker, la pulizia dei file multimediali viene eseguita sul worker con
enable_media_repo: true; questo potrebbe essere il processo principale. Verifica il routing e la configurazione prima di diagnosticare un problema di pulizia che sembra non essere in esecuzione.
- Eseguire il backup del database e dell'archivio multimediale. Effettuare un backup aggiornato e ripristinabile prima di procedere a un'eliminazione irreversibile. Annotare l'ID della stanza e l'orario limite, e utilizzare un token di accesso dell'amministratore del server. Non incollare il token nella cronologia della shell condivisa né pubblicarlo nei log.
- Pianifica attentamente la data limite. Gli endpoint di eliminazione accettano timestamp in millisecondi Unix. Utilizza una data limite derivata dall'UTC e verifica il valore prima di inviare la richiesta. La data limite non è un'anteprima: può rimuovere definitivamente i dati idonei.
Negli esempi seguenti, sostituisci https://matrix.example.comcon l'URL di base rivolto al client per il tuo homeserver, imposta un ID stanza valido ed esporta un token amministratore in ADMIN_TOKEN. Mantieni privato il token bearer.
Rimuovi la vecchia cronologia dei messaggi da una stanza
L'API Purge History rimuove dal database di Synapse gli eventi più vecchi di una data specificata. Non oscura i messaggi per altri server e non è equivalente alla rimozione di una stanza. Per impostazione predefinita, Synapse elimina gli eventi inviati da utenti remoti, ma conserva quelli degli utenti locali; impostare delete_local_eventsquesta opzione truesolo se si intende rimuovere anche questi ultimi. Lo stato della stanza, come l'appartenenza e l'argomento, viene mantenuto.
Ad esempio, per impostare un limite temporale di 180 giorni prima dell'ora corrente su un host Linux, calcolare il timestamp in millisecondi, esaminarlo e quindi inviare la richiesta per una singola stanza:
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}"
Omettilo delete_local_eventso impostalo su falsese desideri il comportamento predefinito di Synapse. Se l'API restituisce un purge_id, la pulizia è iniziata; non è necessariamente terminata. Interroga l'endpoint di stato finché non segnala completeo indaga sul suo errorse lo stato è failed:
curl -sS "$SYNAPSE_URL/_synapse/admin/v1/purge_history_status/$PURGE_ID" \
-H "Authorization: Bearer $ADMIN_TOKEN"
Le operazioni di eliminazione di grandi quantità di messaggi possono richiedere diversi minuti o anche di più. Durante l'operazione, gli utenti potrebbero non essere in grado di tornare indietro nella pagina della stanza dal punto in cui si sta effettuando l'eliminazione. Synapse conserva almeno un messaggio in ogni stanza, quindi questa API non svuoterà completamente la timeline della stanza.
Elimina i vecchi file multimediali e i file remoti memorizzati nella cache
Per una pulizia una tantum dei file multimediali locali utilizzati prima di una determinata soglia, utilizzare l'endpoint corrente per i file multimediali locali. Si tratta before_tsdi un timestamp Unix in millisecondi e può anche accettare size_gtfile di destinazione che superano una soglia di byte. L'impostazione predefinita mantiene i file multimediali ancora utilizzati per le immagini del profilo o dell'avatar della stanza; non impostarla keep_profiles=falsea meno che non si desideri intenzionalmente rimuovere tali file.
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 '{}'
Esamina gli totalID dei media della risposta e quelli eliminati. L'endpoint elimina gli originali locali e le miniature. Evita il percorso precedente contenente /media/<server_name>/delete; la documentazione di Synapse contrassegna tale percorso come obsoleto dalla versione 1.78.0. L'endpoint per i media locali corrente non opera su un repository multimediale esterno separato.
I contenuti multimediali remoti memorizzati nella cache costituiscono una categoria a parte. Per rimuovere i contenuti multimediali remoti presenti nella cache a cui si è avuto accesso prima dello stesso limite temporale, utilizzare:
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 '{}'
La risposta indica quanti elementi memorizzati nella cache sono stati eliminati. Se gli utenti richiedono tali file in un secondo momento, Synapse potrebbe scaricarli nuovamente dal server di origine; pertanto, questa operazione comporta un compromesso tra l'utilizzo del disco locale e un possibile traffico di rete e un ritardo nel recupero dei dati.
Imposta la conservazione ricorrente anziché ripetere le eliminazioni manuali.
La conservazione dei messaggi di Synapse è disabilitata per impostazione predefinita. Per imporre un'impostazione predefinita a livello di server per le stanze senza un proprio stato di conservazione, aggiungi una policy alla configurazione e abilitala. Questo esempio imposta un massimo di un anno:
retention:
enabled: true
default_policy:
max_lifetime: 1y
Utilizza le unità di durata supportate da Synapse, ad esempio dper giorni e yper anni. Gli amministratori e i moderatori delle stanze possono anche impostare gli m.room.retentioneventi di stato di una stanza, mentre gli amministratori del server possono limitare la durata massima consentita con allowed_lifetime_mine allowed_lifetime_max. Rivedi la tua policy completa prima di abilitarla: gli eventi idonei vengono rimossi definitivamente dai processi di pulizia in background. Synapse nasconde gli eventi scaduti ai client non appena scadono, ma la pulizia del database viene eseguita periodicamente, quindi le righe possono rimanere fino all'esecuzione di un processo. Gli eventi di stato non sono coperti dalla conservazione dei messaggi.
Per i media, aggiungi media_retentionla durata di vita, ad esempio:
media_retention:
local_media_lifetime: 90d
remote_media_lifetime: 14d
Questi periodi di conservazione si riferiscono a intervalli di inattività, non semplicemente a un limite di tempo per il caricamento: quando un file è stato consultato, Synapse utilizza l'ora dell'ultimo accesso; per i file multimediali mai consultati, utilizza l'ora di creazione. I file originali e le miniature vengono rimossi. I file multimediali in quarantena e i file multimediali locali protetti dalla quarantena non vengono rimossi da questa pulizia. Configurare la conservazione dei file multimediali sul processo che ospita il repository multimediale, quindi verificare l'impostazione confrontandola con il manuale di configurazione della versione di Synapse in uso.
Prima di apportare modifiche, consultare la documentazione ufficiale relativa all'API Purge History , all'API Media Admin , al manuale di configurazione di Synapse e alla documentazione sui criteri di conservazione dei messaggi . Il comportamento dell'API qui descritto riflette la documentazione ufficiale verificata il 10 ottobre 2026; verificare gli endpoint e la configurazione in base alla versione installata.
Verificare che lo spazio di archiviazione sia stato recuperato.
- Controlla lo stato di eliminazione della cronologia finché non viene visualizzato
complete; conserva l'ID di eliminazione e la risposta per il tuo registro di manutenzione.
- Verifica il numero di elementi eliminati nelle risposte della cache locale e remota, quindi esamina i log di Synapse e l'utilizzo del filesystem dopo la pulizia.
- Non dare per scontato che un minor numero di righe nel database implichi automaticamente un file di database più piccolo. La documentazione di Synapse indica che PostgreSQL può riutilizzare lo spazio liberato senza restituirlo al sistema operativo. Per PostgreSQL,
VACUUM FULLè possibile recuperare spazio su disco, ma ciò richiede un blocco esclusivo; pianifica l'operazione tenendo conto dei tempi di inattività e del relativo impatto, e segui la documentazione relativa a VACUUM per PostgreSQL . Per SQLite, la documentazione di Synapse sulla conservazione dei dati identifica VACUUMl'operazione corrispondente.
- Prima di chiudere l'attività di manutenzione, accertati che i file o gli eventi meno recenti previsti non siano più disponibili e verifica che il backup sia ancora presente.