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.

Podpis: Przed pomiarem lub zmianą nośnika należy potwierdzić aktywność media_store_path. Przedstawiona tutaj ścieżka to przykładowa konfiguracja.

Następnie zmierz podkatalogi pierwszego poziomu:

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

Dokumentacja repozytorium multimediów Synapse opisuje ważne kategorie na dysku. Poniżej przechowywane są lokalne pliki do przesłania local_content, poniżej lokalne miniatury local_thumbnails, poniżej buforowane pliki zdalne remote_content, poniżej zdalne miniatury , a poniżej remote_thumbnaildane podglądu URL .url_cacheurl_cache_thumbnails

Podpis: Podział rozmiarów na poziomie katalogów pomaga odróżnić odzyskiwalną zdalną pamięć podręczną od lokalnych plików przesłanych przez użytkownika, które mogą być jedyną kopią przechowywaną na serwerze domowym.

Nie należy używać rm -rftych katalogów jako standardowej metody czyszczenia. Synapse śledzi również multimedia w swojej bazie danych. Pominięcie obsługiwanych ścieżek czyszczenia może spowodować pozostawienie metadanych odnoszących się do plików, które już nie istnieją, lub usunięcie treści, które użytkownicy nadal chcieliby odzyskać.

3. Najpierw odzyskaj pamięć podręczną multimediów zdalnych, gdy jest ona głównym odbiorcą

Zdalne nośniki w pamięci podręcznej to zazwyczaj miejsce o najniższym ryzyku odzyskiwania przestrzeni. Synapse przechowuje kopie multimediów pierwotnie hostowanych na innych serwerach domowych. Oficjalny interfejs API Purge Remote Media usuwa zbuforowane zdalne nośniki, do których ostatni dostęp był uzyskiwany przed znacznikiem czasu. Jeśli użytkownik ponownie zażąda tych multimediów, Synapse zażąda ich ponownie z serwera domowego, z którego pochodzą.

Interfejs API administratora wymaga tokena dostępu administratora serwera. Synapse zaleca, aby /_synapse/admin/...nie był on publicznie dostępny i zazwyczaj wywoływany lokalnie. Zapoznaj się z oficjalnymi wytycznymi interfejsu API administratora .

Na przykład, oblicz punkt odcięcia oddalony o 30 dni i usuń zdalną pamięć podręczną starszą od tego momentu:

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"

Odpowiedź zawiera deletedliczbę. Próg jest oparty na ostatnim dostępie, a nie tylko na czasie modyfikacji pliku. Wybierz okres, który odpowiada temu, jak daleko wstecz użytkownicy najczęściej przeglądają pliki. Usuniętą zawartość zdalną można pobrać ponownie tylko wtedy, gdy serwer źródłowy nadal ją udostępnia.

4. Traktuj lokalne media jako dane trwałe, chyba że masz politykę ich przechowywania

Media lokalne są inne. Zostały przesłane na Twój serwer domowy, więc ich usunięcie może trwale uszkodzić załączniki, obrazy lub inne odniesienia MXC. Przed zbiorczym usunięciem mediów lokalnych, sprawdź reprezentatywne elementy lub media użytkownika za pomocą interfejsu API administratora.

Aby zapytać o konkretny element multimedialny:

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

Odpowiedź może zawierać media_length, created_ts, last_access_ts, typ MIME i status kwarantanny. Oficjalna dokumentacja API Media Admin definiuje te pola i obsługiwane operacje usuwania.

Podpis: Przed zastosowaniem reguł usuwania należy sprawdzić metadane multimediów, aby decyzje dotyczące wieku i rozmiaru były podejmowane na podstawie rekordów Synapse, a nie znaczników czasu systemu plików.

Synapse może usuwać lokalne media według daty ostatniego dostępu i opcjonalnie według rozmiaru:

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_tsto znacznik czasu systemu Unix w milisekundach, odnoszący się do ostatniego dostępu. size_gtto próg bajtów; domyślnie wynosi zero. keep_profiles=trueto wartość domyślna i zachowuje media nadal używane jako obrazy profili lub pomieszczeń. Zachowaj tę ochronę, chyba że masz konkretny powód, aby usunąć te obrazy.

Możesz również wyświetlić lub usunąć multimedia przesłane przez konkretnego użytkownika lokalnego za pomocą /_synapse/admin/v1/users/<user_id>/media. Jest to przydatne, gdy jedno konto odpowiada za nietypowy wzrost. Przed użyciem operacji usuwania zapoznaj się z dokumentacją interfejsu API administratora użytkowników , a zwłaszcza z parametrami kolejności i limitów.

5. Zapobiegaj ponownemu zapełnieniu dysku przez magazyn multimediów

Włącz automatyczne zatrzymywanie multimediów

Synapse zapewnia ciągłą kontrolę media_retention. Przykład oparty na oficjalnym formacie konfiguracji:

media_retention:
  local_media_lifetime: 180d
  remote_media_lifetime: 30d

Media kwalifikują się do usunięcia, jeśli nie uzyskano do nich dostępu przez skonfigurowany czas istnienia. Jeśli nigdy nie uzyskano do nich dostępu, Synapse bierze pod uwagę czas ich utworzenia. Zarówno oryginał, jak i miniatury są usuwane. Jeśli którykolwiek z parametrów czasu istnienia zostanie pominięty lub ustawiony na null, kategoria nie zostanie automatycznie usunięta.

Wybierz wartość lokalną ostrożnie: w przeciwieństwie do zdalnej pamięci podręcznej, usuniętych nośników lokalnych nie można odtworzyć, po prostu prosząc inny serwer domowy o oryginał. Nośniki poddane kwarantannie nie są usuwane przez automatyczne przechowywanie, a chronione nośniki lokalne są również wykluczane zgodnie z dokumentacją konfiguracji.

Użyj kontroli przesyłania w celu przyszłego rozwoju

max_upload_sizeOgranicza każde pojedyncze przesyłanie danych; nie ogranicza całkowitego rozmiaru repozytorium. Aktualna wersja Synapse obsługuje również media_upload_limitslimity ilości danych, jakie użytkownik może przesłać w określonych przedziałach czasowych. Te ograniczenia ograniczają rozrost, ale nie zastępują monitorowania retencji ani pojemności.

Rozważ dostawcę pamięci masowej, gdy wąskim gardłem jest lokalny system plików

Synapse obsługuje media_storage_providers, w tym dostawcę systemu plików, który może umieścić nośniki w innym katalogu. Może to być pomocne, gdy posiadasz dedykowany wolumin lub warstwę pamięci masowej. Jest to zmiana architektury pamięci masowej, a nie polecenie awaryjnego czyszczenia, dlatego przed migracją nośników produkcyjnych należy przetestować kopie zapasowe, uprawnienia, dostęp roboczy i zachowanie odzyskiwania.

Weryfikacja po czyszczeniu

Po każdym czyszczeniu należy sprawdzić zarówno pojemność, jak i zachowanie aplikacji:

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

• Otwórz ostatnio przesłany lokalnie załącznik w kliencie Matrix.
• Otwórz starszy załącznik zdalny i sprawdź, czy można go ponownie pobrać.
• Sprawdź logi Synapse pod kątem błędów media-worker lub systemu plików.
• Jeśli korzystasz z dedykowanych pracowników obsługi multimediów, upewnij się, że żądania API administratora są kierowane do pracownika repozytorium multimediów. Dokumentacja pracownika Synapse zawiera listę punktów końcowych administratora specyficznych dla multimediów, które muszą być obsługiwane przez ten pracownik.
• Zanotuj rozmiar nośnika po oczyszczeniu i porównaj go ponownie po kilku dniach, aby zmierzyć rzeczywistą szybkość wzrostu.

Szybkie odniesienie decyzyjne

Podsumowanie

Gdy repozytorium multimediów Matrix Synapse zapełnia dysk, należy najpierw ustalić, która klasa multimediów jest za to odpowiedzialna. Zdalna pamięć podręczna jest zazwyczaj najbezpieczniejszym pierwszym celem, ponieważ Synapse posiada dedykowane API czyszczenia i zazwyczaj może ponownie pobrać tę zawartość. Lokalne nośniki wymagają znacznie bardziej rygorystycznej polityki, ponieważ mogą być jedyną kopią załącznika po stronie serwera. Po odzyskaniu natychmiastowego miejsca należy skonfigurować media_retentioni monitorować tempo wzrostu magazynu multimediów, aby czyszczenie stało się przewidywalną konserwacją, a nie sytuacją awaryjną.