Risolvere il problema di un repository multimediale di Matrix Synapse che sta occupando troppo spazio su disco.

Un repository multimediale di Matrix Synapse può consumare spazio su disco più velocemente del database del server principale perché contiene diverse classi di file: file multimediali caricati dagli utenti locali, miniature, file multimediali memorizzati nella cache e recuperati da server remoti, e risorse utilizzate per le anteprime degli URL. La soluzione corretta non è eliminare file a caso dalla directory multimediale. Innanzitutto, identifica quali file stanno crescendo, quindi utilizza l'API di amministrazione di Synapse o i controlli di conservazione per mantenere coerenti i metadati del database e i file su disco.

A ottobre 2026, la versione corrente di Synapse è la 1.162 e la documentazione ufficiale sulla gestione dei media include API per interrogare i media, eliminare i media locali, svuotare la cache dei media remoti e configurare la conservazione automatica. Se la tua installazione è significativamente più vecchia, consulta le versioni ufficiali di Synapse , poiché il comportamento degli endpoint e le opzioni di configurazione possono variare tra le diverse versioni.

Lista di controllo rapida per il triage

1. Confermare che il problema di spazio su disco risiede nel repository multimediale.

Inizia dal filesystem, non da Synapse. Esegui:

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

Il percorso è specifico dell'installazione. media_store_pathL'impostazione di Synapse definisce la directory utilizzata per le immagini e gli allegati caricati e il suo valore predefinito documentato è media_storerelativo alla directory dei dati di Synapse. I pacchetti di distribuzione e le implementazioni in container spesso impostano un percorso esplicito, quindi è consigliabile esaminare la configurazione effettiva anziché presumere una posizione predefinita.

Didascalia: Confronta l'utilizzo del filesystem con le dimensioni dell'archivio multimediale Synapse configurato prima di decidere che la pulizia dei supporti sia la soluzione corretta.

Se il disco è quasi pieno, evitate di eseguire operazioni ricorsive su larga scala che creano file temporanei di grandi dimensioni o backup sullo stesso filesystem. Se rischiate di rimanere senza spazio, interrompete innanzitutto le operazioni di scrittura intensive non correlate o aggiungete capacità temporanea, quindi eseguite la pulizia in modo controllato.

2. Verificare la configurazione dei supporti attivi e identificare cosa sta crescendo

Apri il file attivo homeserver.yamle trova media_store_path. Esamina anche max_upload_size, eventuali media_storage_providerse qualsiasi blocco esistente . Il manuale di configurazionemedia_retention ufficiale di Synapse documenta queste opzioni.

Didascalia: Verificare l'impostazione attiva media_store_pathprima di misurare o modificare lo spazio di archiviazione. Il percorso mostrato qui è un esempio di configurazione.

Successivamente, misurate le sottocartelle di primo livello:

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

La documentazione del repository multimediale di Synapse descrive le categorie importanti presenti sul disco. I caricamenti locali vengono memorizzati di seguito local_content, le miniature locali di seguito local_thumbnails, i file remoti memorizzati nella cache di seguito remote_content, le miniature remote di seguito remote_thumbnaile i dati di anteprima URL di seguito url_cachee url_cache_thumbnails.

Didascalia: Una suddivisione delle dimensioni a livello di directory aiuta a distinguere la cache remota recuperabile dai caricamenti locali dell'utente, che potrebbero essere l'unica copia memorizzata dal server domestico.

Non utilizzare rm -rfqueste directory come normale metodo di pulizia. Synapse tiene traccia anche dei file multimediali nel suo database. Ignorare i percorsi di pulizia supportati può lasciare metadati che fanno riferimento a file che non esistono più o rimuovere contenuti che gli utenti si aspettano ancora di recuperare.

3. Recupera prima la cache multimediale remota quando è il consumatore principale

I file multimediali remoti memorizzati nella cache rappresentano solitamente la soluzione a minor rischio per recuperare spazio. Synapse memorizza copie dei file multimediali originariamente ospitati su altri homeserver. L'API ufficiale Purge Remote Media rimuove dalla cache i file multimediali remoti a cui si è avuto accesso prima di una determinata data e ora. Se un utente richiede nuovamente tali file, Synapse li richiederà nuovamente all'homeserver di origine.

L'API di amministrazione richiede un token di accesso server-admin. Synapse consiglia di mantenerlo /_synapse/admin/...nascosto all'accesso pubblico e di utilizzarlo normalmente in locale. Consultare la guida ufficiale dell'API di amministrazione .

Ad esempio, calcola una data limite di 30 giorni nel passato ed elimina dalla cache remota i dati più vecchi di tale periodo:

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"

La risposta include un deletedconteggio. Il limite temporale si basa sull'ultimo accesso, non semplicemente sull'ora di modifica del file. Scegli un periodo che corrisponda alla frequenza con cui gli utenti solitamente consultano i contenuti. I contenuti remoti eliminati possono essere recuperati solo se il server di origine li rende ancora disponibili.

4. Tratta i supporti locali come dati permanenti a meno che tu non abbia una politica di conservazione

I file multimediali locali sono diversi. Sono stati caricati sul tuo server domestico, quindi eliminarli potrebbe compromettere in modo permanente allegati, immagini o altri riferimenti MXC. Prima di eliminare in blocco i file multimediali locali, controlla gli elementi rappresentativi o i file multimediali dell'utente tramite l'API di amministrazione.

Per interrogare un particolare elemento multimediale:

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

La risposta può includere media_length, created_ts, last_access_ts, tipo MIME e stato di quarantena. La documentazione ufficiale dell'API Media Admin definisce questi campi e le operazioni di eliminazione supportate.

Didascalia: Interroga i metadati dei file multimediali prima di applicare le regole di eliminazione, in modo che le decisioni relative all'età e alle dimensioni si basino sui record di Synapse anziché sui timestamp del file system.

Synapse può eliminare i file multimediali locali in base alla data dell'ultimo accesso e, facoltativamente, in base alle dimensioni:

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è un timestamp Unix in millisecondi e si riferisce all'ultimo accesso. size_gtè una soglia di byte; il suo valore predefinito è zero. keep_profiles=trueè l'impostazione predefinita e preserva i file multimediali ancora utilizzati come immagini del profilo o della stanza. Mantieni questa protezione a meno che tu non abbia un motivo specifico per rimuovere tali immagini.

È inoltre possibile elencare o eliminare i file multimediali caricati da uno specifico utente locale /_synapse/admin/v1/users/<user_id>/media. Questa funzione è utile quando un account è responsabile di una crescita insolita. Prima di utilizzare l'operazione di eliminazione, consultare la documentazione dell'API di amministrazione utenti , in particolare i parametri relativi all'ordinamento e al limite.

5. Impedire al Media Store di riempire nuovamente il disco

Abilita la conservazione automatica dei supporti

Per il controllo continuo, Synapse fornisce media_retention. Un esempio basato sul formato di configurazione ufficiale è:

media_retention:
  local_media_lifetime: 180d
  remote_media_lifetime: 30d

I file multimediali possono essere rimossi se non sono stati consultati per il periodo di tempo configurato. Se non sono mai stati consultati, Synapse utilizza la data di creazione. Vengono rimossi sia il file originale che le miniature. Se uno dei due periodi di tempo viene omesso o impostato su null, la categoria corrispondente non viene eliminata automaticamente.

Scegliete il valore locale con cautela: a differenza della cache remota, i file multimediali locali eliminati non possono essere ricostruiti semplicemente richiedendo l'originale a un altro homeserver. I file multimediali in quarantena non vengono eliminati dalla conservazione automatica e, in base alla documentazione di configurazione, vengono esclusi anche i file multimediali locali protetti.

Utilizzare i controlli di caricamento per la crescita futura

max_upload_sizeLimita ogni singolo caricamento; non impone un limite alla dimensione totale del repository. Synapse supporta anche media_upload_limitsla limitazione della quantità di dati che un utente può caricare in determinati periodi di tempo. Questi controlli riducono la crescita, ma non sostituiscono il monitoraggio della conservazione o della capacità.

Quando il file system locale rappresenta il collo di bottiglia, è opportuno valutare un fornitore di servizi di archiviazione.

Synapse supporta diverse opzioni media_storage_providers, tra cui un provider di file system che consente di posizionare i supporti in un'altra directory. Questo può essere utile quando si dispone di un volume o di un livello di storage dedicato. Si tratta di una modifica all'architettura di storage, non di un comando di pulizia d'emergenza, quindi è necessario testare i backup, le autorizzazioni, l'accesso dei worker e il comportamento di ripristino prima di migrare i supporti di produzione.

Verifica dopo la pulizia

Dopo ogni operazione di pulizia, verificare sia la capacità che il comportamento dell'applicazione:

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

• Apri un allegato caricato di recente in locale in un client Matrix.
• Apri un vecchio allegato remoto e verifica che sia possibile recuperarlo nuovamente.
• Controlla i log di Synapse per eventuali errori relativi al media worker o al file system.
• Se si utilizzano worker dedicati per i media, verificare che le richieste API di amministrazione vengano instradate a un worker del repository multimediale. La documentazione di Synapse relativa ai worker elenca gli endpoint di amministrazione specifici per i media che devono essere gestiti in tale server.
• Registra le dimensioni del mediastore dopo la pulizia e confrontale nuovamente dopo alcuni giorni per misurare il tasso di crescita effettivo.

Riferimento rapido alle decisioni

In conclusione

Quando un repository multimediale di Matrix Synapse riempie un disco, è necessario innanzitutto individuare la classe di supporti responsabile. La cache remota è solitamente la prima opzione più sicura, poiché Synapse dispone di un'API di pulizia dedicata e può normalmente recuperare nuovamente il contenuto. I supporti locali richiedono una politica molto più rigorosa, in quanto potrebbero rappresentare l'unica copia lato server di un allegato. Una volta recuperato lo spazio disponibile, è necessario configurare media_retentione monitorare la velocità di crescita dell'archivio multimediale, in modo che la pulizia diventi una manutenzione prevedibile anziché un'emergenza.