Synapse OIDC를 통해 Element Web을 Keycloak에 연결합니다.
Element Web 사용자가 클라이언트 암호를 노출하지 않고 ID 서버를 통해 로그인할 수 있도록 Keycloak OIDC 클라이언트와 Synapse 공급자를 구성하십시오.
클라이언트 동기화 중에 Matrix Synapse의 메모리가 부족해지는 경우, 먼저 Linux에서 Synapse 프로세스가 실제로 종료되었는지 확인한 다음 정상적인 /_matrix/client/v3/sync작업 부하 상태에서 메모리 사용량을 측정하십시오. 캐시 증가가 원인인 경우, 즉시 극도로 낮은 제한값으로 설정하기보다는 캐시 크기를 약간 조정하십시오. 데이터베이스 응답 속도가 느려지면 요청 백로그가 발생하여 문제가 악화될 수 있습니다.
2026년 10월 10일 현재, Synapse 공식 릴리스 기록 에 따르면 최신 안정 버전은 1.162.0(9월 29일)이고, 사전 릴리스 버전은 1.163.0rc1입니다. 오래된 설치 버전을 업데이트하는 것이 좋지만, 릴리스 번호만으로는 동기화 관련 메모리 부족 문제를 진단하거나 해결을 보장할 수 없습니다.
무한 동기화, 게이트웨이 오류 또는 연결 끊김 세션을 표시하는 클라이언트는 그 자체로 OOM(메모리 부족) 이벤트를 발생시키지 않습니다. 일반적인 Linux systemd 설치 환경에서는 클라이언트 오류 발생 시점의 커널 및 서비스 저널을 확인하십시오.
sudo journalctl -k --since "1 hour ago" | grep -Ei 'oom|out of memory|killed process'
sudo journalctl -u matrix-synapse --since "1 hour ago" --no-pager
Synapse 또는 Python 프로세스의 이름을 명시하는 커널 OOM-killer 메시지, systemd 상태 메시지(예: `--output-output-name`) oom-kill또는 Python 오류 메시지를 찾아보세요 MemoryError. 이러한 메시지는 서로 다른 오류 발생 메커니즘을 나타냅니다. 커널은 호스트 또는 컨테이너의 메모리 경계에 도달했을 때 프로세스를 종료할 수 있으며, ` MemoryError--output-name` 오류는 시스템 전체의 OOM 종료가 발생하기 전에 Python 프로세스 내에서 발생할 수 있습니다. 서비스 이름은 패키지마다 다르므로 실제 장치 또는 컨테이너 이름으로 바꿔야 합니다.
다음으로, 일반적인 동기화를 재현하는 동안 호스트 부하와 가장 큰 프로세스를 기록합니다.
free -h
ps -eo pid,rss,%mem,args --sort=-rss | head -n 12
systemctl show matrix-synapse -p MemoryCurrent -p MemoryMax
RSS킬로바이트 단위의 상주 메모리는 애플리케이션 고유의 메모리 사용량을 정확하게 나타내는 수치가 아닙니다. 공유 페이지는 여러 프로세스에서 계산될 수 있습니다. Docker 환경에서는 docker stats컨테이너의 메모리 제한도 확인해야 합니다. PostgreSQL, Redis, 그리고 여러 Synapse 워커가 호스트를 공유하는 경우, 메인 Synapse 프로세스 하나만 탓하기보다는 전체 메모리 사용량을 평가해야 합니다.
Synapse는 동기화 요청을 신속하게 처리하기 위해 최근 이벤트 및 회의실 데이터를 메모리에 유지합니다. 기본 설정 caches.global_factor값은 100으로 되어 있으며 0.5, 이 값을 줄이면 일반적으로 캐시 크기가 줄어들지만 데이터베이스 작업량이 증가할 가능성이 높아집니다. Synapse 관리자 FAQ에서는 속도가 느린 저장 장치에 지나치게 작은 캐시를 사용하면 요청이 누적되어 전체 메모리 사용량이 더욱 증가할 수 있다고 경고합니다.
활성 상태를 백업하고 homeserver.yaml기존 caches:블록이 있는지 확인한 다음 관련 값만 변경합니다. 이는 캐시 사용량이 증가하는 인스턴스를 위한 시험 구성 이며 , 범용 튜닝 대상이 아닙니다.
caches:
global_factor: 0.3
sync_response_cache_duration: 1m
동기화 응답 캐시 설정은 완료된 /sync결과가 캐시에 유지되는 기간을 제어합니다. Synapse 문서에는 2m기본값이 나와 있습니다. 캐시 기간을 짧게 설정하면 유지되는 응답 수가 줄어들 수 있지만, 연결이 불안정한 클라이언트의 경우 작업량이 증가할 수 있습니다. 이미 키가 있는 경우 두 번째 키를 추가하지 마십시오 caches:. 설치 SYNAPSE_CACHE_FACTOR환경에서 서비스 또는 컨테이너 환경에 설정된 경우 해당 변수가 YAML 요소보다 우선 적용됩니다.
Synapse 설치에 사용된 Python 환경으로 파일의 유효성을 검사하고 필요에 따라 구성 경로를 조정하십시오.
python -m synapse.config -c /etc/matrix-synapse/homeserver.yaml
유효성 검사 후에만 재시작하십시오. 데비안 스타일의 systemd 패키징에서는 일반적으로 이 과정이 필요하며 sudo systemctl restart matrix-synapse, 컨테이너 배포는 자체 오케스트레이션을 사용합니다. 재시작 직후 서비스 로그에서 구성 오류를 확인하십시오. Synapse 구성 참조에는 캐시 요소를 다시 로드하는 방법도 설명되어 있지만 SIGHUP, 이는 동기화 응답 보존을 포함한 다른 설정도 다시 로드할 수 있음을 의미하지는 않습니다. 두 설정을 모두 변경할 때는 제어된 재시작이 더 명확합니다.
클라이언트가 멈춰 있는 동안 메모리 사용량이 계속 증가하는 경우 캐시를 더 낮추는 것은 오히려 역효과를 초래할 수 있습니다. RSS 증가 시점을 CPU 사용률, 디스크 I/O 및 데이터베이스 활동과 비교해 보세요. 호스트 사용량이 많거나 PostgreSQL 쿼리 속도가 느린 경우, 동시에 처리 중인 요청이 많아지고 각 요청이 완료될 때까지 데이터가 유지될 수 있습니다.
먼저 데이터베이스 응답성과 디스크 공간 및 I/O 상태가 양호한지 확인하십시오. Synapse 구성 참조 문서 에 명시된 바와 같이, 프로덕션 Synapse는 SQLite가 아닌 PostgreSQL을 사용하도록 설계되었습니다 . 만약 기존의 SQLite 기반 인스턴스를 사용 중이라면, 검증된 백업을 활용하여 지원되는 데이터베이스 마이그레이션을 계획하십시오. 메모리 부족 문제를 해결하기 위한 임시 방편으로 운영 중인 데이터베이스를 임의로 교체하지 마십시오.
global_factor이전에 극단적인 값으로 낮췄다 가 동기화 지연 시간이 악화되었다면, 이전 값으로 복원하거나 응답 시간과 총 메모리 사용량을 모두 확인하면서 약간 더 높은 값으로 테스트해 보세요. Synapse 관리자 FAQ 에서는 느린 백엔드로 인해 큐가 발생하는 경우 캐시 용량을 늘리면 도움이 될 수 있다고 명시적으로 언급하고 있습니다. 모든 회의실 수, 페더레이션 부하 및 배포 레이아웃에 적합한 안전한 고정 RAM 목표값은 없습니다.
여러 프로세스가 동시에 실행되는 환경에서는 메인 프로세스 또는 특정 동기화 워커 중 어느 쪽의 사용량이 증가하는지 파악해야 합니다. 워커를 사용하면 클라이언트 동기화 트래픽을 분산할 수 있지만, 각 워커에도 메모리가 필요하므로 용량 증설 없이 워커를 추가하면 호스트의 메모리 부족(OOM) 문제가 악화될 수 있습니다. 필요한 공유 구성 없이 임의의 워커로 클라이언트 요청을 라우팅하는 대신 Synapse 워커 설명서를 참조하여 구성하십시오.
적절한 jemalloc 설정이 이미 지원되고 검증된 시스템에서 Synapse는 다음과 같은 기능을 제공합니다 cache_autotuning. Synapse는 문서에 명시된 세 가지 값 max_cache_memory_usage(,, target_cache_memory_usage및 min_cache_ttl)을 모두 필요로 하며, 캐시 제거 기능을 사용하여 캐시 사용량을 목표치 근처로 유지합니다. 다음 그림은 예시이며, Python, 데이터베이스, 기타 서비스 및 활성 요청 급증을 수용할 수 있도록 적절한 크기로 조정해야 합니다.
caches:
cache_autotuning:
max_cache_memory_usage: 512M
target_cache_memory_usage: 384M
min_cache_ttl: 5m
기존 캐시 설정을 교체하는 대신 이 블록을 기존 설정과 병합하십시오. 이 수치는 캐시 예산이지 프로세스 RSS 제한이 아닙니다 . 따라서 이 값을 사용한다고 해서 프로세스가 512MiB 미만으로 유지된다는 보장은 없습니다. Synapse 구성 참조에서는 이 기능을 위해 jemalloc이 필요하며, Synapse 관리자 FAQ에서는 Python의 할당자가 jemalloc의 회계 처리에 영향을 줄 수 있으므로 추가 설정이 필요할 수 있다고 경고합니다 PYTHONMALLOC=malloc. 할당자 사전 로드 경로와 패키징은 시스템마다 다르므로 변경하기 전에 배포 환경의 실제 라이브러리와 시작 환경을 확인하십시오 LD_PRELOAD. 아키텍처별 라이브러리 경로를 맹목적으로 복사하지 마십시오.
각 변경 후에는 이전에 오류를 발생시켰던 것과 동일한 실제 클라이언트 활동을 수행하십시오. 기존 클라이언트를 다시 연결하고, 가능한 경우 초기 동기화를 허용하고, 여러 번의 정상적인 증분 동기화가 완료될 때까지 기다리십시오. 모든 Synapse 프로세스의 최대 RSS, 스왑 활동, 데이터베이스 응답성, 그리고 커널 로그에 또 다른 OOM 이벤트가 기록되는지 여부를 기록하십시오. 재시작 직후의 일시적인 성능 저하는 영구적인 해결책의 증거가 아닙니다. 캐시는 원래 초기화 시 초기화 상태가 아니기 때문입니다.
모니터링이 활성화된 경우 Synapse의 메트릭 엔드포인트를 사용하여 시간 경과에 따른 프로세스 메모리 사용량 및 요청 동작을 비교할 수 있습니다. Synapse 모니터링 문서에 따르면 워커는 메트릭을 독립적으로 노출하므로 별도로 모니터링해야 합니다. 따라서 내부 데이터를 공개적으로 게시하는 대신 메트릭 엔드포인트를 비공개 또는 보호된 상태로 유지하십시오.
클라이언트가 반복적인 재연결 없이 동기화를 완료하고, 로그에 새로운 메모리 강제 종료가 기록되지 않으며, 동일한 작업 부하에서 메모리가 안정적인 수준으로 안정화된다면 변경 사항이 효과가 있는 것입니다. 동기화 지연 시간이 적절하고 캐시를 신중하게 조정했음에도 불구하고 메모리 부족 오류가 계속 발생한다면, 다음 단계는 임의로 권장되는 서버 크기가 아닌 실제 최대 메모리 사용량을 기준으로 사용 가능한 RAM을 늘리거나 호스트당 작업 부하를 줄이는 것입니다.
Element Web 사용자가 클라이언트 암호를 노출하지 않고 ID 서버를 통해 로그인할 수 있도록 Keycloak OIDC 클라이언트와 Synapse 공급자를 구성하십시오.
복구 키를 저장하고, Element 세션을 확인하고, 암호화된 메시지 키를 백업과 계정 암호를 혼동하지 않고 복원할 수 있는지 확인하십시오.
Synapse 동기화 중 메모리 부족 오류를 진단하고, 캐싱을 안전하게 조정하고, 요청 백로그를 식별하고, 안정적인 메모리 사용을 확인합니다.
보안 검사를 비활성화하지 않고 매트릭스 페더레이션 인증서 오류를 올바른 서버로 추적하고, TLS 체인 또는 CA 신뢰를 복구하고, 수정 사항을 확인합니다.
Cloudflare의 HTTPS 443 포트를 통해 Matrix 클라이언트와 페더레이션을 라우팅하여 Synapse 검색 기능을 유지하고 API 트래픽 캐싱이나 미디어 업로드 오류를 방지합니다.
pg_dump를 사용하여 Synapse를 백업하고, 서명 키와 미디어를 보호하고, 오래된 일회용 키를 재사용하지 않고 깨끗한 PostgreSQL 데이터베이스에 복원하세요.
Mjölnir를 전용 Matrix 계정, 암호화된 관리실, Docker Compose, 정책 목록 및 권한 검사와 함께 설정하십시오.
기존 프록시를 건너뛰고 Synapse에 내장된 슬라이딩 동기화 기능을 구성하십시오. 클라이언트 검색을 확인한 다음 호환되는 전화기에서 회의실 목록 로딩 및 재연결 동작을 측정하십시오.
Element Web을 정적 사이트로 배포하고, Matrix 홈서버를 가리키도록 설정하고, HTTPS를 추가하고, Nginx를 구성하여 오래된 파일 없이 업데이트를 제공하도록 하십시오.
64비트 라즈베리 파이 4에 Conduit를 설치하여 영구 데이터 저장, HTTPS 연동, 보호된 회원가입, 그리고 홈서버 작동 여부 확인 기능을 구성합니다.