디스크 공간을 과도하게 차지하는 Matrix Synapse 미디어 저장소 문제를 해결하세요

Matrix Synapse 미디어 저장소는 로컬 사용자가 업로드한 미디어, 썸네일, 원격 홈서버에서 가져온 캐시된 미디어, URL 미리보기에 사용되는 리소스 등 여러 종류의 파일을 저장하기 때문에 홈서버 데이터베이스보다 디스크 공간을 더 빨리 소모할 수 있습니다. 올바른 해결책은 미디어 디렉터리에서 임의의 파일을 삭제하는 것이 아닙니다. 먼저 어떤 파일의 크기가 증가하는지 파악한 다음 Synapse의 관리자 API 또는 보존 제어 기능을 사용하여 데이터베이스 메타데이터와 디스크에 저장된 파일의 일관성을 유지해야 합니다.

2026년 10월 현재 Synapse의 최신 릴리스 버전은 1.162이며, 공식 미디어 관리 문서에는 미디어 조회, 로컬 미디어 삭제, 캐시된 원격 미디어 삭제, 자동 보존 설정 등을 위한 API가 포함되어 있습니다. 설치된 Synapse 버전이 이보다 훨씬 오래된 경우, 엔드포인트 동작 및 구성 옵션이 릴리스별로 다를 수 있으므로 공식 Synapse 릴리스를 확인하십시오.

신속 환자 분류 체크리스트

1. 미디어 저장소가 디스크 공간 부족의 원인인지 확인하십시오.

Synapse를 실행하지 말고 파일 시스템부터 시작하세요. 다음 명령을 실행하세요.

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

경로는 설치 환경에 따라 다릅니다. Synapse media_store_path설정은 업로드된 이미지와 첨부 파일을 저장하는 데 사용되는 디렉터리를 정의하며, 문서에 명시된 기본값은 media_storeSynapse의 데이터 디렉터리를 기준으로 합니다. 배포 패키지 및 컨테이너 배포 시에는 명시적인 경로가 설정되는 경우가 많으므로, 위치를 추측하기보다는 실제 구성을 확인하십시오.

설명: 미디어 정리가 올바른 해결책인지 판단하기 전에 파일 시스템 사용량과 구성된 Synapse 미디어 저장소의 크기를 비교해 보세요.

디스크 공간이 거의 꽉 찼다면 동일한 파일 시스템에 대용량 임시 파일이나 백업을 생성하는 광범위한 재귀 작업을 실행하지 마십시오. 공간 부족 위험이 임박한 경우, 먼저 관련 없는 쓰기 작업이 많은 작업을 중지하거나 임시 용량을 추가한 다음, 체계적인 방식으로 정리 작업을 수행하십시오.

2. 활성 미디어 구성을 확인하고 증가 중인 항목을 파악합니다.

활성화된 항목을 열고 homeserver.yaml를 찾으세요 media_store_path. 또한 max_upload_size, 모든 항목 media_storage_providers및 기존 media_retention블록을 검토하세요. 공식 Synapse 구성 설명서에 이러한 옵션이 설명되어 있습니다.

설명: media_store_path측정 또는 저장 매체 변경 전에 활성 상태를 확인하십시오. 여기에 표시된 경로는 예시 구성입니다.

다음으로 최상위 하위 디렉터리의 크기를 측정합니다.

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

Synapse의 미디어 저장소 문서에는 디스크에 저장되는 중요한 범주가 설명되어 있습니다. 로컬 업로드 파일은 아래에 local_content, 로컬 썸네일은 아래에 local_thumbnails, 캐시된 원격 파일은 아래에 remote_content, 원격 썸네일은 아래에 remote_thumbnail, URL 미리보기 데이터는 아래에 저장 url_cache됩니다 url_cache_thumbnails.

캡션: 디렉터리 수준의 크기 분석을 통해 복구 가능한 원격 캐시와 홈 서버에 저장된 유일한 사본일 수 있는 로컬 사용자 업로드 파일을 구분할 수 있습니다.

rm -rf이러한 디렉터리 내부를 일반적인 정리 방법으로 사용하지 마십시오 . Synapse는 데이터베이스에서 미디어 파일도 추적합니다. 지원되는 정리 경로를 무시하면 더 이상 존재하지 않는 파일을 참조하는 메타데이터가 남거나 사용자가 여전히 검색해야 하는 콘텐츠가 삭제될 수 있습니다.

3. 원격 미디어 캐시가 주요 소비 대상일 경우 먼저 해당 캐시를 회수하십시오.

캐시된 원격 미디어는 일반적으로 공간을 확보하는 데 있어 가장 위험 부담이 적은 곳입니다. Synapse는 다른 홈서버에서 호스팅된 미디어의 복사본을 저장합니다. 공식 원격 미디어 삭제 API는 지정된 타임스탬프 이전에 마지막으로 액세스된 캐시된 원격 미디어를 제거합니다. 사용자가 해당 미디어를 다시 요청하면 Synapse는 원래 홈서버에 다시 요청합니다.

관리자 API를 사용하려면 서버 관리자 액세스 토큰이 필요합니다. Synapse는 이 토큰을 /_synapse/admin/...공개적으로 접근할 수 없도록 숨기고 일반적으로 로컬에서 호출하는 것을 권장합니다. 자세한 내용은 공식 관리자 API 안내를 참조하십시오 .

예를 들어, 30일 전을 기준으로 기간을 설정하고 그보다 오래된 원격 캐시를 삭제하도록 할 수 있습니다.

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"

응답에는 deleted카운트가 포함됩니다. 삭제 시점은 파일 수정 시간이 아닌 마지막 액세스 시간을 기준으로 합니다. 사용자가 일반적으로 검색하는 기간을 고려하여 적절한 기간을 선택하세요. 삭제된 원격 콘텐츠는 원본 서버에서 해당 콘텐츠를 계속 제공하는 경우에만 다시 가져올 수 있습니다.

4. 보존 정책이 없는 한 로컬 미디어는 영구 데이터로 취급하십시오.

로컬 미디어는 다릅니다. 홈 서버에 업로드된 미디어이므로 삭제하면 첨부 파일, 이미지 또는 기타 MXC 참조가 영구적으로 손상될 수 있습니다. 로컬 미디어를 일괄 삭제하기 전에 관리자 API를 통해 대표 항목이나 사용자 미디어를 검사하십시오.

특정 미디어 항목을 조회하려면:

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

응답에는 media_length, created_ts, last_access_ts, MIME 유형 및 격리 상태가 포함될 수 있습니다. 공식 미디어 관리자 API 문서에서 이러한 필드와 지원되는 삭제 작업을 정의합니다.

캡션: 삭제 규칙을 적용하기 전에 미디어 메타데이터를 조회하여 파일 시스템 타임스탬프가 아닌 Synapse의 기록을 기반으로 사용 기간 및 크기를 결정하도록 합니다.

Synapse는 마지막 접근 날짜를 기준으로 로컬 미디어를 삭제할 수 있으며, 선택적으로 크기를 기준으로 삭제할 수도 있습니다.

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는 밀리초 단위의 유닉스 타임스탬프이며 마지막 액세스 시간을 나타냅니다. size_gt는 바이트 임계값이며 기본값은 0입니다. keep_profiles=true는 기본값이며 프로필 또는 룸 이미지로 계속 사용되는 미디어를 보존합니다. 특별한 이유로 해당 이미지를 삭제하지 않는 한 이 보호 기능을 유지하십시오.

특정 로컬 사용자가 업로드한 미디어를 나열하거나 삭제할 수도 있습니다 /_synapse/admin/v1/users/<user_id>/media. 이는 특정 계정의 미디어 업로드 수가 비정상적으로 증가할 때 유용합니다. 삭제 작업을 사용하기 전에 사용자 관리 API 문서를 검토하여 특히 순서 및 제한 매개변수에 대해 자세히 알아보세요.

5. 미디어 저장소가 디스크 용량을 다시 채우지 않도록 방지합니다.

자동 미디어 보존 기능을 활성화합니다.

Synapse는 지속적인 제어를 위해 다음과 같은 기능을 제공합니다 media_retention. 공식 설정 형식을 기반으로 한 예시는 다음과 같습니다.

media_retention:
  local_media_lifetime: 180d
  remote_media_lifetime: 30d

미디어는 설정된 수명 기간 동안 액세스되지 않은 경우 삭제 대상이 됩니다. 한 번도 액세스되지 않은 경우 Synapse는 생성 시간을 기준으로 삭제합니다. 원본 미디어와 썸네일 이미지가 모두 삭제됩니다. 수명 기간 중 하나라도 생략되거나 null로 설정된 경우 해당 미디어 범주는 자동으로 삭제되지 않습니다.

로컬 미디어 저장 시 값을 신중하게 선택하십시오. 원격 캐시와 달리 삭제된 로컬 미디어는 다른 홈서버에 원본을 요청하는 것만으로는 복구할 수 없습니다. 격리된 미디어는 자동 보존 과정에서 삭제되지 않으며, 구성 문서에 따라 보호된 로컬 미디어 또한 삭제 대상에서 제외됩니다.

향후 성장을 위해 업로드 제어 기능을 사용하세요.

max_upload_size개별 업로드 용량을 제한하는 것이지, 전체 저장소 크기를 제한하는 것은 아닙니다. 현재 Synapse는 media_upload_limits사용자가 특정 기간 동안 업로드할 수 있는 용량을 제한하는 기능도 지원합니다. 이러한 제어 기능은 데이터 증가를 줄여주지만, 보존 기간이나 용량 모니터링을 대체하는 것은 아닙니다.

로컬 파일 시스템이 병목 현상인 경우 스토리지 제공업체를 고려해 보세요.

Synapse는 media_storage_providers파일 시스템 공급자를 포함하여 미디어를 다른 디렉터리에 배치할 수 있는 기능을 지원합니다. 이는 전용 스토리지 볼륨 또는 계층을 사용하는 경우에 유용할 수 있습니다. 이는 스토리지 아키텍처 변경이지 긴급 정리 명령이 아니므로 프로덕션 미디어를 마이그레이션하기 전에 백업, 권한, 작업자 액세스 및 복구 동작을 테스트해야 합니다.

정리 후 검증

데이터 삭제 후에는 용량과 애플리케이션 동작을 모두 확인하십시오.

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

• Matrix 클라이언트에서 최근에 로컬에 업로드한 첨부 파일을 엽니다.
• 이전에 연결했던 원격 파일을 열고 다시 가져올 수 있는지 확인하십시오.
• Synapse 로그에서 media-worker 또는 파일 시스템 오류를 확인하십시오.
• 전용 미디어 워커를 사용하는 경우 관리자 API 요청이 미디어 저장소 워커로 라우팅되는지 확인하십시오. Synapse의 워커 문서에는 해당 워커에서 처리해야 하는 미디어별 관리자 엔드포인트 목록이 나와 있습니다.
• 정리 후 미디어 저장소 크기를 기록하고 며칠 후 다시 비교하여 실제 성장률을 측정하십시오.

빠른 결정 참조

결론

Matrix Synapse 미디어 저장소가 디스크 공간을 가득 채우면 먼저 어떤 미디어 클래스가 원인인지 파악해야 합니다. 원격 캐시는 Synapse에 전용 삭제 API가 있고 일반적으로 해당 콘텐츠를 다시 가져올 수 있으므로 가장 안전한 우선 처리 대상입니다. 로컬 미디어는 첨부 파일의 서버 측 복사본이 하나뿐일 수 있으므로 훨씬 엄격한 정책이 필요합니다. 즉시 공간을 확보한 후에는 media_retention미디어 저장소 증가율을 구성하고 모니터링하여 정리가 비상 상황이 아닌 예측 가능한 유지 관리 작업이 되도록 해야 합니다.