Matrix Synapse 동기화 중 메모리 부족 오류 해결 방법

2026년 10월 6일 현재, Matrix Synapse의 최신 안정 버전은 2026년 9월 29일에 출시된 1.162.0입니다. 클라이언트 동기화 중에 홈서버의 메모리가 부족해지는 경우, 최신 지원 버전으로 업그레이드하는 것이 먼저 확인해 볼 만한 방법이지만, 근본적인 해결책은 마법 같은 설정 변경보다는 운영상의 조치인 경우가 많습니다. Synapse는 일반적인 요청 속도를 높이기 위해 최근 회의실 데이터와 메타데이터를 메모리에 유지합니다. 공식 관리자 문서에서는 캐시를 너무 과도하게 줄이면 오히려 느린 요청이 누적되어 메모리 부족 현상이 악화될 수 있다고 경고합니다.

이 가이드는 초보 관리자가 안전하게 사용할 수 있는 경로를 안내합니다. 즉, "동기화"의 의미를 이해하고, 프로세스가 실제로 메모리 한계에 도달했는지 확인하고, 불필요한 캐시 부하를 줄이고, 필요한 경우 비정상적으로 많은 초기 동기화 트래픽을 분리하고, 결과를 모니터링하는 것입니다. 목표는 단순히 상주 메모리 크기를 줄이는 것이 아닙니다. 홈서버의 응답성을 유지하면서 메모리 부족으로 인한 시스템 충돌을 방지하는 것이 목표입니다.

Matrix Synapse에서 "동기화"란 무엇을 의미하는가

Matrix 클라이언트는 메시지, 회의실 상태, 계정 데이터, 현재 상태 정보 및 장치 업데이트와 같은 새로운 이벤트를 수신하기 위해 클라이언트-서버 API를 반복적으로 호출합니다 /_matrix/client/v3/sync. 일반적인 동기화 과정에는 since토큰이 포함되므로 Synapse는 이전 동기화 시점 이후의 변경 사항만 반환하면 됩니다.

초기 동기화는 일반적인 동기화 와는 다릅니다. 이는 장치 또는 세션에 대한 첫 번째 동기화이며 이전 토큰이 없습니다 since. Synapse 워커 공식 문서에서는 이러한 요청이 상당한 리소스를 소모할 수 있다고 설명합니다. 대규모 홈서버의 경우 Synapse는 초기 동기화를 지속적인 동기화와 별도로 라우팅하여 몇 건의 비용이 많이 드는 첫 번째 동기화로 인해 다른 사용자가 영향을 받지 않도록 지원합니다.

변경하기 전에 최신 Synapse 관리자 FAQ , 구성 참조 및 공식 작업자 가이드를 검토하십시오 . 사용 가능한 옵션은 Synapse 버전 및 배포 모델에 따라 다릅니다.

변경하기 전에

• Synapse 버전과 설치 방법을 기록해 두세요.
• homeserver.yaml평소 백업 절차에 따라 워커 구성 파일, 리버스 프록시 구성 및 PostgreSQL 데이터베이스를 백업하십시오 .
• Synapse가 단일 프로세스로 실행되는지, 컨테이너에서 실행되는지, 아니면 메인 프로세스와 워커 프로세스로 실행되는지 확인하십시오.
• 실제 메모리 제한을 확인하세요. 컨테이너, systemd 유닛, Kubernetes Pod 또는 VM은 물리적 서버보다 낮은 메모리 제한을 가질 수 있습니다.
• 프로덕션 환경에서 PostgreSQL을 사용하고 있는지 확인하십시오. 현재 Synapse 설치 설명서에는 SQLite는 테스트용이며 특히 대규모 환경에서 프로덕션 워크로드에 적합하지 않다고 나와 있습니다.

1단계: 실제 실패 원인이 메모리 고갈인지 확인합니다.

캐시 값을 변경하는 것부터 시작하지 마십시오. 먼저 어떤 Synapse 프로세스가 메모리를 소비하고 있는지, 그리고 해당 프로세스가 운영 체제에 의해 종료되는지 아니면 컨테이너 제한에 의해 종료되는지를 파악하십시오.

리눅스 호스트에서는 다음과 같은 명령어를 사용하면 빠르게 초기 상태를 확인할 수 있습니다.

ps -eo pid,rss,cmd | grep synapse
free -h
journalctl -u matrix-synapse -n 200

Docker, Podman, Kubernetes 또는 다른 스케줄러를 사용하는 경우 컨테이너 또는 Pod의 메모리 제한도 확인하십시오. 수 기가바이트의 여유 메모리가 있는 호스트라도 Synapse 프로세스가 훨씬 작은 cgroup 제한에 의해 제한되면 Synapse가 종료될 수 있습니다.

반복 가능한 패턴을 찾아보세요. 특정 사용자가 새 기기에서 로그인할 때만 메모리 사용량이 증가하나요? 하루 종일 점진적으로 증가하나요? 메인 프로세스는 안정적인 상태를 유지하는 동안 일반 작업자 프로세스 하나만 사용량이 증가하나요? 이러한 관찰을 통해 초기 동기화로 인한 사용량 급증을 일반적인 캐시 증가 또는 요청 백로그와 구분할 수 있습니다.

2단계: 캐시 설정을 낮추기 전에 확인하세요

캐시 는 Synapse가 동일한 정보를 반복적으로 재계산하거나 다시 로드할 필요가 없도록 RAM에 저장하는 데이터입니다. Synapse는 여러 개의 캐시와 이벤트 캐시를 가지고 있습니다. 현재 구성 참조 문서에는 기본값 caches.global_factor0.5, event_cache_size전역 계수가 적용되기 전 기본값 10K, 시간 기반 캐시 만료, 그리고 sync_response_cache_duration기본값 2분이 명시되어 있습니다.

가장 쉬운 해결책은 전역 캐시 크기를 최대한 낮게 설정하는 것입니다. 하지만 맹목적으로 그렇게 해서는 안 됩니다. Synapse 관리자 FAQ에서는 캐시 크기가 너무 작으면 시스템 속도가 더욱 느려져 요청이 누적되고, 캐시 항목 대신 백로그로 인해 메모리 사용량이 폭발적으로 증가할 수 있다고 명시적으로 경고합니다.

프로파일링 결과 캐시 메모리가 실제로 가장 큰 리소스 소비처이고 요청 처리량이 양호한 상태라면 급격한 감소보다는 약간의 감소를 시도해 보세요. 예를 들면 다음과 같습니다.

event_cache_size: 10K

caches:
  global_factor: 0.25
  expire_caches: true
  cache_entry_ttl: 30m
  sync_response_cache_duration: 0s

이 값은 문제 해결 예시일 뿐이며 모든 서버에 권장되는 값은 아닙니다. 값을 sync_response_cache_duration0으로 설정하면 완료된 /sync응답 캐싱이 비활성화됩니다. 동기화 응답을 많이 저장해야 하는 경우 메모리를 절약할 수 있지만, 재연결하는 클라이언트의 작업량이 증가할 수 있습니다. 실제 작업 부하에서 테스트해 보시기 바랍니다.

Synapse는 `cache autotuning` max_cache_memory_usage, target_cache_memory_usage`cache autotuning`, `cache autotuning` 세 가지 설정을 제공합니다 min_cache_ttl. 공식 문서에 따르면 이 기능은 대체 메모리 할당자인 `jemalloc`을 필요로 하며 , 세 가지 설정을 모두 제공해야 합니다. 한두 가지 값만 활성화하지 마십시오. 문서에서는 불완전한 구성으로 인해 불안정한 동작이 발생할 수 있다고 경고합니다.

3단계: 데이터베이스에 요청 백로그가 발생하지 않는지 확인하십시오.

동기화 중 메모리 문제가 발생하는 원인은 캐시된 데이터 양 때문만은 아닙니다. 속도가 느린 데이터베이스는 동시에 여러 요청을 처리할 수 있으며, 각 요청은 메모리를 소모합니다. 따라서 이미 속도가 느린 데이터베이스에서 캐시 크기를 줄이면 오히려 역효과를 초래할 수 있습니다.

실제 운영 환경에서는 Synapse PostgreSQL 공식 가이드를 따르세요 . 데이터베이스 CPU 사용량, 스토리지 지연 시간, 연결 포화도, 장시간 실행되는 쿼리, 그리고 PostgreSQL 서버 자체의 스왑 발생 여부를 확인하십시오. 동기화 지연 시간이 상주 메모리 사용량과 동시에 증가하는 경우, 캐시를 다시 줄이기 전에 백로그 문제를 조사하십시오.

최근에 대규모 공용 공간으로 이전했거나, 훨씬 더 큰 커뮤니티로 통합되었거나, 활성 사용자가 많이 추가되었다면, 기존 구성으로는 처리하기 어려웠던 작업 부하가 이제는 감당할 수 없게 되었을 수 있습니다. 이러한 경우, 캐시 크기를 약간 줄이는 것보다 데이터베이스 튜닝과 워커 격리가 훨씬 더 중요할 수 있습니다.

4단계: 대규모 홈서버에서 초기 동기화를 분리합니다.

Synapse는 단일 모놀리스 (즉, 하나의 메인 홈서버 프로세스)로 실행될 수도 있고, 작업을 워커 로 분산시켜 동일한 PostgreSQL 데이터베이스를 공유하는 추가 Synapse 프로세스로 실행할 수도 있습니다. 워커 모델은 개별 워크로드를 독립적으로 확장해야 하는 대규모 설치 환경에 적합합니다.

워커 문서에는 일반 워커가 /sync와 를 처리할 수 있다고 명시되어 있습니다. 또한 초기 동기화 요청은 리소스 소모가 매우 클 수 있으므로 매개변수가 /initialSync없는 동기화 요청에 대해서는 별도의 처리를 고려하는 것이 좋습니다 .since

실용적인 건축이란 다음과 같습니다.

• 리버스 프록시는 Matrix 클라이언트 트래픽을 수신합니다.
• 진행 중인 /sync요청은 하나 이상의 일반 작업자에게 전달됩니다.
• 초기 동기화 요청은 별도의 일반 작업자 그룹으로 전송됩니다.
• 주요 프로세스는 위임되지 않은 책임을 계속 처리합니다.
• 모든 Synapse 프로세스는 PostgreSQL을 공유합니다.

Synapse 복제 리스너를 공용 인터넷에 노출하지 마십시오. 현재 워커 문서에서는 복제 암호가 구성되지 않은 경우 복제 트래픽이 암호화되지 않고 인증되지 않는다고 경고합니다.

소규모 홈서버에는 워커를 바로 추가하는 것이 적합하지 않습니다. Synapse 자체 가이드라인에서도 소규모 인스턴스에는 모놀리식 모드를 권장합니다. 특정 워크로드에 격리 또는 수평 확장이 필요하다는 증거가 있을 때 워커를 추가하십시오.

5단계: 캐시 요소를 안전하게 다시 로드하고 결과를 확인합니다.

Synapse는 캐시 요소를 다시 로드할 수 있도록 합니다 SIGHUP. 구성 참조에는 다음 예가 나와 있습니다.

kill -HUP PID_OF_SYNAPSE_PROCESS

패키지된 systemd 서비스가 이를 지원하는 경우 systemctl reload matrix-synapse동일한 작업을 수행할 수 있습니다. 워커 배포의 경우 공식 문서에 따르면 관련 워커 구성을 업데이트해야 하며 각 워커는 개별적으로 재로드 신호를 받아야 합니다.

변경 후에는 서버가 정상적인 트래픽 패턴에 도달할 때까지 충분한 시간을 주십시오. 상주 메모리, 요청 지연 시간, 데이터베이스 부하 및 활성 작업자 상태를 함께 모니터링하십시오. 동기화 지연 시간이 두 배로 증가하는 동안 메모리 그래프가 하락하는 것은 성공적인 수정이 아닙니다.

6단계: 반복 가능한 진단을 위해 Prometheus 메트릭을 활성화합니다.

일회성 사고를 넘어선 모든 상황에 대해서는 Synapse 메트릭을 활성화하고 Prometheus를 사용하여 수집하십시오. 공식 모니터링 가이드에는 enable_metrics: true전용 내부 메트릭 리스너에 대한 문서가 나와 있습니다. 메트릭 엔드포인트는 내부 인터페이스에 두거나 리버스 프록시에서 보호해야 하며, 불필요하게 노출해서는 안 됩니다.

최신 리스너 구문은 Synapse Prometheus 모니터링 공식 가이드를 참조하십시오 . 워커 배포 환경에서는 워커 메트릭이 메인 프로세스에 자동으로 집계되지 않으므로 각 워커를 개별적으로 모니터링해야 합니다.

흔히 저지르는 실수들을 피하는 방법

서버 속도가 느려질 때까지 SYNAPSE_CACHE_FACTOR 값을 낮춥니다.

캐시 크기가 작을수록 항목당 메모리 사용량은 줄어들지만 데이터베이스 및 연산 작업량은 증가합니다. 이러한 추가 작업으로 인해 미완료 요청이 누적되면 전체 메모리 사용량이 오히려 증가할 수 있습니다. 따라서 캐시 크기를 조금씩 줄여나가면서 지연 시간을 항상 모니터링해야 합니다.

모든 /sync 요청의 비용이 동일하다고 가정할 때

토큰을 사용한 지속적인 동기화 since와 토큰 없이 수행하는 초기 동기화는 리소스 프로필이 매우 다릅니다. 서버 전체를 확장하기 전에 진단 과정에서 이 두 가지를 구분해야 합니다.

SQLite를 사용하는 동안에도 워커를 계속 사용합니다.

Synapse 워커는 PostgreSQL 데이터베이스를 공유합니다. 워커 문서에 따르면 SQLite는 데모 또는 테스트 용도로만 사용되며 워커 기반 프로덕션 배포의 기반이 될 수 없습니다.

스왑을 주요 해결책으로 사용

소량의 스왑은 갑작스러운 프로세스 종료를 방지할 수 있지만, 과도한 스왑은 동기화 속도를 현저히 저하시키고 동일한 백로그 악순환을 초래할 수 있습니다. 스왑은 용량 계획이 아닌 단기적인 트래픽 급증에 대한 보호 장치로 활용해야 합니다.

여러 메모리 설정을 한 번에 변경하기

캐시 크기를 줄이고, 워커 라우팅을 변경하고, PostgreSQL 설정을 바꾸고, 컨테이너 제한을 늘리는 등의 작업을 동시에 수행하면 어떤 변경 사항이 문제를 해결했는지 알 수 없습니다. 한 번에 하나의 제어된 변경만 수행하고 동일한 지표를 비교하십시오.

실질적인 의사결정 경로

최종 체크리스트

• 현재 지원되는 Synapse 릴리스를 실행하십시오. 2026년 10월 6일 기준 최신 안정 릴리스는 버전 1.162.0입니다.
• 운영 환경에는 PostgreSQL을 사용하세요.
• 실제로 RSS를 소비하는 프로세스가 무엇인지, 그리고 해당 프로세스에 적용되는 메모리 제한은 무엇인지 확인하십시오.
• 일반적인 점진적 동기화와 초기 동기화를 구분하십시오.
• 캐시 만료 기능을 활성화하고 캐시 요소를 점진적으로 조정하세요.
• jemalloc을 사용 중이고 필요한 모든 값이 구성된 경우가 아니면 캐시 자동 튜닝을 활성화하지 마십시오.
• 대규모 배포의 경우 초기 동기화를 분리하거나 측정 결과에 따라 일반 동기화 작업자를 추가하십시오.
• 변경 사항이 발생할 때마다 메모리 사용량과 지연 시간을 함께 모니터링하십시오.

Synapse는 성능 전략의 일환으로 캐싱을 활용하기 때문에 의도적으로 메모리 사용량을 많이 소모합니다. 따라서 동기화 관련 OOM(메모리 부족) 오류를 해결하는 올바른 방법은 균형을 맞추는 것입니다. 불필요한 캐시 유지를 제거하고, 데이터베이스 또는 요청 백로그를 없애고, 일반적인 동기화 속도를 유지하는 캐시에 과부하를 주지 않으면서 예외적인 워크로드를 격리해야 합니다. 이러한 접근 방식이 가장 높은 RSS(리스크 동기화 속도) 값 자체를 문제로 간주하는 것보다 더 안정적입니다.

최신 릴리스 정보는 Element Synapse 공식 릴리스 페이지를 참조하십시오 .