Matrix Synapse에서 오래된 메시지 기록 및 미디어를 삭제하는 방법

예시 시나리오(설명용): 가상의 비영리 단체인 노스스타 커뮤니티(Northstar Community)에서 Matrix Synapse 홈서버를 운영하고 있습니다. 데이터베이스와 미디어 저장소가 계속 증가함에 따라 관리자는 현재 토론이나 프로필 이미지를 실수로 삭제하지 않고 오래된 토론 기록과 미디어를 제거하려고 합니다. 이 예시는 실제 배포 사례나 테스트 결과를 보고하는 것이 아닙니다.

핵심은 메시지 기록과 미디어를 별도의 정리 작업으로 처리하는 것입니다. Synapse는 회의실 기록 삭제 API와 별도의 미디어 정리 도구를 제공하며, 미디어 보존 설정을 통해 파일을 삭제하면서도 해당 파일을 참조하는 Matrix 이벤트는 유지할 수 있습니다. 먼저 보존해야 할 항목을 결정한 다음 데이터베이스와 미디어 저장소를 백업하고 적절한 방법을 선택한 후 두 저장 영역을 모두 검증하십시오.

서버에서 "오래된"이라는 것이 무엇을 의미하는지 결정하세요.

설정을 변경하거나 파괴적인 엔드포인트를 호출하기 전에 보존 규칙을 작성하십시오. 노스스타의 사례를 예로 들면, 이사회에서 일반 회의실 사용 기록은 180일 동안 보관하고, 로컬 업로드 파일도 비슷한 정책에 따라 보관하며, 원격 미디어는 필요할 경우 다시 가져올 수 있는 캐시로 처리하기로 승인했다고 가정해 보겠습니다. 다른 조직에서는 법적, 운영적 또는 커뮤니티 관련 이유로 수년간의 보존 기간이 필요할 수도 있습니다. 이러한 기간은 예시일 뿐이며, 보편적인 권장 사항은 아닙니다.

데이터를 두 가지 범주로 분류하세요.

• 회의실 이벤트: Synapse 데이터베이스에 저장된 메시지 및 기타 이벤트입니다. 이벤트를 삭제하면 사용자가 회의실에서 이전 기록을 탐색할 수 있는 기간이 변경됩니다.
• 미디어: 업로드된 파일, 썸네일, 다른 홈서버에서 캐시된 파일 사본. 이러한 파일은 미디어 저장소 또는 구성된 외부 저장소에 저장됩니다.

Synapse 공식 문서에서는 이벤트 보존 정책과 미디어 정리 정책을 별도로 설명합니다. 회의실 기록을 삭제한다고 해서 미디어 저장소가 정리되었다는 것을 보장할 수 없으며, 미디어 파일을 삭제한다고 해서 해당 파일과 연결된 이벤트가 삭제되는 것도 아닙니다. 먼저 데이터베이스 크기, 미디어 저장소 크기, 영향을 받는 회의실, 그리고 정리 종료 시점을 기록해 두십시오. 자세한 내용은 Synapse 구성 설명서를 참조하십시오 .

삭제하기 전에 백업하세요

사용하는 데이터베이스 엔진에 권장되는 절차에 따라 데이터베이스를 백업하고, 미디어 저장소 또는 외부 미디어 저장소도 백업하십시오. 데이터베이스 백업만으로는 업로드된 파일을 보존할 수 없으며, 미디어 백업만으로는 회의실 이벤트를 복원할 수 없습니다. 백업 파일을 읽을 수 있는지, 그리고 복원 방법을 숙지하고 있는지 확인한 후 진행하십시오. Synapse가 컨테이너에서 실행되거나 개별 워커를 사용하는 경우, 관련 구성 및 스토리지 볼륨을 유지 관리 계획에 포함하십시오.

노스스타의 가상 서버에서 관리자는 공유 공간을 건드리기 전에 데이터베이스 및 미디어 저장소 크기를 기록하고 최근 복원 지점을 확인합니다. 이는 "정리" 작업이 필요한 콘텐츠는 복구 가능한 상태로 유지하면서 의도한 데이터만 제거해야 성공적이라고 할 수 있기 때문에 유용합니다.

지속적인 정리 작업을 위해 정기적인 보존 일정을 선택하세요.

Synapse에서 정책을 계속 적용하려면 홈서버 구성에서 이벤트 보존 기간과 미디어 보존 기간을 별도로 설정해야 합니다. 예를 들어 관리자는 회의실 기록 및 로컬 미디어에 대해 승인된 정책을 180일로 설정하고 원격 미디어 캐시를 30일로 설정하는 서버에 맞게 이 예시를 수정할 수 있습니다.

retention:
  enabled: true
  default_policy:
    max_lifetime: 180d

media_retention:
  local_media_lifetime: 180d
  remote_media_lifetime: 30d

이는 예시적인 구성이며, 모든 서버에 적용할 수 있는 정책이 아닙니다. Synapse 문서에 따르면 이벤트 보존 기능은 기본적으로 비활성화되어 있습니다. 이 설정은 상태 이벤트가 default_policy없는 회의실에 적용됩니다 m.room.retention. 회의실 관리자는 회의실 정책을 설정할 수 있으며, 서버 관리자는 문서에 명시된 allowed-lifetime 설정을 통해 정책 보존 기간을 제한할 수 있습니다. 일관된 상한값을 설정해야 하는 경우, 기본 설정이 모든 회의실에 적용된다고 가정하기보다는 이미 사용 중인 회의실 정책과 해당 제어 기능을 검토하십시오.

미디어 수명은 미디어 항목에 마지막으로 액세스된 시점을 기준으로 합니다. 항목에 한 번도 액세스되지 않은 경우 Synapse는 생성 시간을 사용합니다. 이 설정은 원본 및 썸네일에 적용되며, 수명이 설정되지 않았거나 null인 경우 해당 미디어 범주는 삭제되지 않습니다. 원격 캐시된 항목은 삭제된 후에도 원본에서 다시 요청할 수 있습니다. 격리된 미디어와 로컬 보호 미디어는 예외이며 이러한 보존 설정의 적용을 받지 않습니다. 미디어 정리 작업은 이 enable_media_repo기능이 활성화된 Synapse 프로세스 또는 워커에서 실행됩니다. 현재 보존 설정 및 media_retention 참조를 확인한 후 설치에 맞는 일반적인 재시작 또는 배포 절차를 사용하여 구성을 적용하십시오.

샘플을 도입하기 전에 해당 동작 방식을 사용자의 요구 사항과 비교해 보세요. 회의실 메시지와 첨부 파일이 180일 동안 읽을 수 있도록 유지되어야 하는 경우, 메시지가 로컬에 저장된 파일보다 오래 남아 있을 수 있다는 점을 감안하지 않고는 더 짧은 미디어 수명을 선택하지 마세요. 미디어가 Synapse 자체에 저장되어 있는지 아니면 외부 미디어 저장소에 저장되어 있는지 확인하세요. Synapse의 로컬 미디어 삭제 API는 외부 저장소에 저장된 미디어를 삭제하지 않습니다.

오래된 룸 이벤트를 요청 시 삭제합니다.

일회성 정리를 위해서는 Synapse 관리자 API(Purge History Admin API)를 사용하십시오. 이 API를 사용하려면 서버 관리자 액세스 토큰이 필요하며, 개별 회의실 관리자 권한과는 다릅니다. Synapse는 관리자 API를 공개적으로 접근할 수 없도록 숨기고, 일반적으로 서버 또는 신뢰할 수 있는 관리 호스트에서 이러한 요청을 수행할 것을 권장합니다. 공유 셸 기록, 티켓 또는 로그에 실제 액세스 토큰을 붙여넣지 마십시오.

요청에는 이벤트 ID 또는 밀리초 단위의 유닉스 타임스탬프를 사용하여 마감 시간을 지정해야 합니다. 다음 셸 예제는 이해를 돕기 위한 것입니다. 홈서버, 룸 ID, 토큰 변수 및 샘플 마감 시간은 검토한 값으로 대체하십시오. 이 예제는 로컬 사용자 메시지 이벤트 삭제도 명시적으로 요청합니다.

export SYNAPSE_ADMIN_TOKEN='replace-with-a-server-admin-token'
PURGE_CUTOFF_MS=1760000000000  # replace with the approved UTC cutoff

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $SYNAPSE_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  --data "{\"purge_up_to_ts\": $PURGE_CUTOFF_MS, \"delete_local_events\": true}" \
  "https://matrix.example.org/_synapse/admin/v1/purge_history/!room:example.org"

이 옵션을 사용하지 않으면 delete_local_events: trueSynapse는 기본적으로 로컬 사용자가 보낸 이벤트를 보존합니다. 원격으로 보낸 이벤트는 삭제할 수 있습니다. 멤버십 및 토픽 상태와 같은 룸 상태는 보존됩니다. 또한 Synapse는 각 룸에서 최소 하나의 메시지를 보관합니다. 삭제 작업은 몇 분 이상 소요될 수 있으며, 작업이 진행되는 동안 사용자는 삭제 중인 부분을 이전 페이지로 이동할 수 없습니다. API는 삭제 ID를 즉시 반환합니다. /_synapse/admin/v1/purge_history_status/<purge_id>상태가 '완료'가 될 때까지 폴링 complete하거나, '실패'인 경우 오류를 조사하십시오 . 삭제 시점을 선택하기 전에 삭제 기록 API 문서를failed 참조하십시오 . 특히 로컬 이벤트 삭제가 룸에 적합한지 검토하십시오.

로컬 미디어와 원격 캐시를 각각 정리합니다.

정기적인 정리 작업의 경우, media_retention사용자에게 약속한 가용성에 맞는 수명 기간을 선택하세요. 일회성 정리 작업을 위해서는 Synapse에서 제공하는 별도의 엔드포인트를 사용할 수 있습니다.

• 로컬 미디어: POST /_synapse/admin/v1/media/delete?before_ts=<timestamp_ms> 마지막 사용 시간을 기준으로 삭제 대상 로컬 미디어를 제거합니다. API는 크기 임계값도 지원합니다. 프로필 및 룸 아바타 미디어는 기본적으로 유지됩니다. 결과를 신중하게 검토하지 않은 이상 해당 보호 기능을 비활성화하지 마십시오.
• 캐시된 원격 미디어: POST /_synapse/admin/v1/purge_media_cache?before_ts=<timestamp_ms> 지정된 시간 이전에 마지막으로 액세스한 캐시된 원격 미디어를 제거합니다. 사용자가 나중에 제거된 원격 파일을 요청하는 경우 Synapse는 해당 파일을 원래 홈서버에 다시 요청할 수 있습니다.

두 엔드포인트 모두 밀리초 단위의 양수 Unix 타임스탬프를 사용하며, 미디어 삭제는 업로드 또는 생성 날짜가 아닌 마지막 액세스 시간을 기준으로 합니다. 로컬 미디어 삭제 API는 Synapse 자체 저장소(원격 파일의 로컬 캐시된 복사본 포함)에서 파일과 썸네일을 삭제합니다. 외부 미디어 저장소는 삭제하지 않습니다. 응답에는 삭제된 항목 수가 표시됩니다. 요청을 실행하기 전에 Synapse 미디어 관리 API에서 최신 매개변수 및 엔드포인트 세부 정보를 확인하십시오.

Northstar의 경우, 관리자는 먼저 승인된 정책에 따라 차단 기준을 테스트하고 엔드포인트에서 반환된 ID 또는 개수가 예상과 일치하는지 확인합니다. 원격 캐시가 유일한 증가 원인이라면 로컬 업로드를 삭제하는 것은 잘못된 작업입니다. 로컬 업로드를 계속 사용할 수 있어야 하는 경우, 로컬 보존 기간을 더 길게 설정하거나 로컬 미디어 삭제 엔드포인트를 사용하지 않아야 합니다.

결과를 측정하고 필요에 따라 방향을 전환하십시오.

각 작업 후에는 삭제가 성공적으로 완료되었는지 확인하고, API 응답 횟수를 검토하고, 대표 룸에 예상되는 기록 경계가 표시되는지 확인하고, 데이터베이스 및 미디어 저장소 사용량을 각각 비교하십시오. 데이터베이스 행 수가 줄어들더라도 운영 체제 디스크 사용량이 즉시 동일하게 줄어들지는 않을 수 있습니다. 데이터베이스 공간 회수는 데이터베이스 엔진 및 유지 관리 절차에 따라 달라집니다. 데이터베이스 파일을 수동으로 삭제하는 대신 데이터베이스 공급업체의 지침을 따르십시오.

데이터베이스 크기는 줄어들었지만 미디어 저장소 크기는 줄어들지 않는 경우, 미디어 보존 정책, 미디어 워커의 enable_media_repo격리 또는 보호 상태, 그리고 파일이 외부 저장소에 저장되는지 여부를 검토하십시오. 미디어 사용량은 줄었지만 이전 메시지가 남아 있는 경우, 미디어만 삭제되었을 때 발생하는 정상적인 현상입니다. 이벤트가 예기치 않게 남아 있는 경우, 보존 정책이 활성화되어 있는지, 회의실에 자체 보존 상태가 있는지, 로컬 이벤트가 의도적으로 보존되었는지, 그리고 삭제 상태가 완료되었는지 확인하십시오.

Northstar의 성공 기준은 단순히 "디스크 크기가 줄었다"는 것이 아닙니다. 승인된 이전 기록 경계가 명확하게 표시되고, 필요한 최신 메시지와 첨부 파일이 여전히 작동하며, 의도한 미디어 범주가 정리되었고, 두 백업 모두 사용 가능한 상태여야 합니다. 이러한 검사를 통과하지 못하면 추가 삭제를 중지하고 정리 범위를 확대하기 전에 룸 정책, API 응답, 작업자 구성 및 스토리지 백엔드를 검사해야 합니다.

염두에 두어야 할 제한 사항

보존 정책은 조직의 법적 또는 기록 보존 검토를 대체할 수 없습니다. 페더레이션으로 인해 다른 홈서버가 이벤트 또는 미디어의 자체 사본을 보유할 수 있으며, Synapse는 해당 서버에서 데이터가 완전히 삭제되었음을 보장할 수 없습니다. 원격 미디어 삭제는 이 서버의 캐시를 제거할 뿐이며, 원본 홈서버의 소스 파일을 삭제하는 것은 아닙니다. 마찬가지로 Synapse에서 로컬 이벤트 또는 미디어 개체를 삭제해도 다른 참가자가 이미 다운로드한 사본은 회수되지 않습니다.

반복 가능한 정책이 필요할 때는 예약된 보존 기능을 사용하고, 검토를 거친 특정 대상 정리 작업에는 관리자 API를 사용하세요. 두 작업의 성공 신호와 효과가 다르므로 변경 기록에서 두 작업을 분리하여 관리해야 합니다.