Fix a Matrix Synapse Media Repository That Is Filling Up Disk Space

A Matrix Synapse media repository can consume disk space faster than the homeserver database because it holds several different classes of files: media uploaded by local users, thumbnails, cached media fetched from remote homeservers, and resources used for URL previews. The right fix is not to delete random files from the media directory. First identify what is growing, then use Synapse's Admin API or retention controls so the database metadata and on-disk files stay consistent.

As of October 2026, the current Synapse release line is 1.162, and the official media-management documentation includes APIs for querying media, deleting local media, purging cached remote media, and configuring automatic retention. Check the official Synapse releases if your installation is significantly older, because endpoint behavior and configuration options can differ across releases.

Quick Triage Checklist

1. Confirm That the Media Repository Is the Disk-Space Problem

Start with the filesystem, not with Synapse. Run:

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

The path is installation-specific. Synapse's media_store_path setting defines the directory used for uploaded images and attachments, and its documented default is media_store relative to Synapse's data directory. Distribution packages and container deployments often set an explicit path, so inspect your actual configuration rather than assuming a location.

Caption: Compare filesystem usage with the size of the configured Synapse media store before deciding that media cleanup is the correct fix.

If the disk is nearly full, avoid running broad recursive operations that create large temporary files or backups on the same filesystem. If you are at immediate risk of running out of space, first stop unrelated write-heavy jobs or add temporary capacity, then perform cleanup in a controlled way.

2. Verify the Active Media Configuration and Identify What Is Growing

Open the active homeserver.yaml and find media_store_path. Also review max_upload_size, any media_storage_providers, and any existing media_retention block. The official Synapse configuration manual documents these options.

Bildunterschrift: Prüfen Sie die aktive Einstellung, media_store_pathbevor Sie den Speicher messen oder ändern. Der hier gezeigte Pfad ist eine Beispielkonfiguration.

Messen Sie als Nächstes die Unterverzeichnisse der ersten Ebene:

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

Die Dokumentation zum Medien-Repository von Synapse beschreibt die wichtigsten Kategorien auf der Festplatte. Lokale Uploads werden unterhalb von local_content, lokale Miniaturansichten unterhalb von local_thumbnails, zwischengespeicherte Remote-Dateien unterhalb von remote_content, Remote-Miniaturansichten unterhalb von remote_thumbnailund URL-Vorschaudaten unterhalb von url_cacheund gespeichert url_cache_thumbnails.

Bildunterschrift: Eine Größenaufschlüsselung auf Verzeichnisebene hilft dabei, wiederherstellbaren Remote-Cache von lokalen Benutzer-Uploads zu unterscheiden, bei denen es sich möglicherweise um die einzige Kopie handelt, die auf Ihrem Homeserver gespeichert ist.

Verwenden Sie rm -rfdiese Verzeichnisse nicht als normale Bereinigungsmethode. Synapse speichert Mediendateien auch in seiner Datenbank. Wenn Sie die unterstützten Bereinigungspfade umgehen, können Metadaten auf nicht mehr vorhandene Dateien verbleiben oder Inhalte entfernt werden, die Benutzer noch abrufen möchten.

3. Zuerst den Remote-Mediencache freigeben, wenn dieser der Hauptverbraucher ist.

Zwischengespeicherte Remote-Medien bieten in der Regel das geringste Risiko, Speicherplatz freizugeben. Synapse speichert Kopien von Medien, die ursprünglich auf anderen Homeservern gehostet wurden. Die offizielle API zum Löschen von Remote-Medien entfernt zwischengespeicherte Remote-Medien, auf die zuletzt vor einem bestimmten Zeitstempel zugegriffen wurde. Fordert ein Benutzer diese Medien erneut an, fordert Synapse sie erneut vom ursprünglichen Homeserver an.

Die Admin-API benötigt ein Serveradministrator-Zugriffstoken. Synapse empfiehlt, dieses /_synapse/admin/...vor der Öffentlichkeit zu verbergen und es normalerweise lokal aufzurufen. Weitere Informationen finden Sie in der offiziellen Dokumentation zur Admin-API .

Beispielsweise kann ein Stichtag von 30 Tagen in der Vergangenheit festgelegt und der Remote-Cache, der älter als dieser Zeitraum ist, gelöscht werden:

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"

Die Antwort enthält eine deletedZählung. Der Stichtag basiert auf dem letzten Zugriff, nicht nur auf dem Änderungsdatum der Datei. Wählen Sie einen Zeitraum, der dem üblichen Suchverhalten der Nutzer entspricht. Gelöschte Inhalte können nur dann erneut abgerufen werden, wenn der Ursprungsserver sie noch bereitstellt.

4. Behandeln Sie lokale Medien als permanente Daten, sofern Sie keine Aufbewahrungsrichtlinie haben.

Lokale Mediendateien verhalten sich anders. Da sie auf Ihren Heimserver hochgeladen wurden, kann deren Löschung Anhänge, Bilder oder andere MXC-Referenzen dauerhaft beschädigen. Bevor Sie lokale Mediendateien in großen Mengen löschen, überprüfen Sie repräsentative Elemente oder Benutzermedien über die Admin-API.

So fragen Sie ein bestimmtes Medienelement ab:

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

Die Antwort kann media_lengthInformationen created_tswie last_access_tsMIME-Typ und Quarantänestatus enthalten. Die offizielle Dokumentation der Media Admin API definiert diese Felder und die unterstützten Löschvorgänge.

Bildunterschrift: Vor der Anwendung von Löschregeln sollten die Metadaten der Medien abgefragt werden, damit Entscheidungen über Alter und Größe auf den Datensätzen von Synapse und nicht auf den Zeitstempeln des Dateisystems basieren.

Synapse kann lokale Medien nach dem Datum des letzten Zugriffs und optional nach Größe löschen:

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_tsist ein Unix-Zeitstempel in Millisekunden und bezieht sich auf den letzten Zugriff. size_gtist ein Byte-Schwellenwert; der Standardwert ist null. keep_profiles=trueist die Standardeinstellung und bewahrt Medien, die noch als Profil- oder Raumabbilder verwendet werden. Behalten Sie diesen Schutz bei, es sei denn, Sie haben einen triftigen Grund, diese Bilder zu entfernen.

Sie können auch die von einem bestimmten lokalen Benutzer hochgeladenen Medien auflisten oder löschen /_synapse/admin/v1/users/<user_id>/media. Dies ist hilfreich, wenn ein Konto für ein ungewöhnlich hohes Wachstum verantwortlich ist. Lesen Sie die Dokumentation der Benutzerverwaltungs-API , bevor Sie die Löschfunktion verwenden, insbesondere die Parameter für Reihenfolge und Limit.

5. Verhindern, dass der Medienspeicher die Festplatte erneut füllt

Automatische Medienaufbewahrung aktivieren

Für die laufende Steuerung bietet Synapse folgende Möglichkeiten media_retention: Ein Beispiel basierend auf dem offiziellen Konfigurationsformat ist:

media_retention:
  local_media_lifetime: 180d
  remote_media_lifetime: 30d

Mediendateien können gelöscht werden, wenn sie innerhalb der konfigurierten Gültigkeitsdauer nicht aufgerufen wurden. Wurde noch nie auf eine Datei zugegriffen, verwendet Synapse deren Erstellungszeitpunkt. Sowohl das Original als auch die Miniaturansichten werden entfernt. Wird eine der Gültigkeitsdauern nicht angegeben oder auf „null“ gesetzt, wird die entsprechende Kategorie nicht automatisch gelöscht.

Wählen Sie den lokalen Wert vorsichtig: Im Gegensatz zum Remote-Cache können gelöschte lokale Medien nicht einfach durch eine Anfrage an einen anderen Homeserver wiederhergestellt werden. Unter Quarantäne stehende Medien werden nicht automatisch gelöscht, und geschützte lokale Medien sind gemäß der Konfigurationsdokumentation ebenfalls ausgeschlossen.

Nutzen Sie Upload-Steuerelemente für zukünftiges Wachstum

max_upload_sizeDie Upload-Geschwindigkeit wird für jeden einzelnen Upload begrenzt; die Gesamtgröße des Repositorys bleibt jedoch unberührt. Synapse bietet aktuell auch die Möglichkeit media_upload_limits, die Upload-Menge pro Benutzer innerhalb bestimmter Zeiträume zu begrenzen. Diese Maßnahmen reduzieren das Datenwachstum, ersetzen aber nicht die Datenspeicherung oder die Kapazitätsüberwachung.

Ziehen Sie einen Speicheranbieter in Betracht, wenn das lokale Dateisystem den Flaschenhals darstellt.

Synapse unterstützt die Migration von media_storage_providersMediendateien, einschließlich eines Dateisystemanbieters, der Mediendateien in einem anderen Verzeichnis ablegen kann. Dies ist hilfreich, wenn Sie ein dediziertes Speichervolume oder eine dedizierte Speicherebene verwenden. Es handelt sich um eine Änderung der Speicherarchitektur und nicht um einen Notfallbereinigungsbefehl. Testen Sie daher Backups, Berechtigungen, Workerzugriff und das Wiederherstellungsverhalten, bevor Sie Produktionsmedien migrieren.

Überprüfung nach der Bereinigung

Nach jeder Bereinigung sollten Sie sowohl die Kapazität als auch das Anwendungsverhalten überprüfen:

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

• Öffnen Sie einen kürzlich lokal hochgeladenen Anhang in einem Matrix-Client.
• Öffnen Sie einen älteren Remote-Anhang und vergewissern Sie sich, dass er erneut abgerufen werden kann.
• Überprüfen Sie die Synapse-Protokolle auf Media-Worker- oder Dateisystemfehler.
• Wenn Sie dedizierte Media-Worker verwenden, stellen Sie sicher, dass die Anfragen an die Admin-API an einen Media-Repository-Worker weitergeleitet werden. Die Worker-Dokumentation von Synapse listet die medienspezifischen Admin-Endpunkte auf, die dort verarbeitet werden müssen.
• Notieren Sie die Größe des Medienspeichers nach der Bereinigung und vergleichen Sie sie nach einigen Tagen erneut, um die tatsächliche Wachstumsrate zu messen.

Schnellentscheidungsreferenz

Fazit

Wenn ein Matrix Synapse-Medienrepository eine Festplatte füllt, ermitteln Sie zunächst die verantwortliche Medienklasse. Der Remote-Cache ist in der Regel das sicherste Ziel, da Synapse über eine dedizierte Bereinigungs-API verfügt und die Inhalte normalerweise wieder abrufen kann. Lokale Medien erfordern deutlich strengere Richtlinien, da es sich möglicherweise um die einzige serverseitige Kopie eines Anhangs handelt. Sobald wieder Speicherplatz verfügbar ist, konfigurieren media_retentionund überwachen Sie die Wachstumsrate des Medienspeichers, damit die Bereinigung zu einer planbaren Wartung und nicht zu einem Notfall wird.