PostgreSQL 덤프를 사용하여 Matrix Synapse를 안전하게 복원하세요
pg_dump를 사용하여 Synapse를 백업하고, 서명 키와 미디어를 보호하고, 오래된 일회용 키를 재사용하지 않고 깨끗한 PostgreSQL 데이터베이스에 복원하세요.
최신 Matrix 모바일 클라이언트를 사용하는 경우, 기존의 독립형 슬라이딩 동기화 프록시를 Docker Compose에 추가하지 마십시오. 해당 프록시는 2025년 11월에 서비스가 종료되었으며, Synapse 1.114 버전부터 기본적으로 활성화된 간소화된 슬라이딩 동기화 기능을 Synapse 자체에서 제공합니다. Synapse를 지원되는 버전으로 업데이트하고, 공개 URL을 통해 클라이언트가 기본 기능을 사용할 수 있는지 확인한 후, 해당 기능을 지원하는 클라이언트에서 부하를 측정하십시오.
"슬라이딩 동기화"는 원래 Synapse 앞에 위치하며 별도의 서비스 및 검색 설정이 필요했던 MSC3575 프록시 구현을 지칭했습니다. Matrix 사양이 발전하면서 MSC4186(간소화된 슬라이딩 동기화)이 해당 설계를 대체했습니다. 공식 프록시 저장소는 보관 처리되었으며 최신 클라이언트에서는 더 이상 작동하지 않을 것으로 예상됩니다. Synapse는 MSC3575 및 MSC4186에 대한 네이티브 지원을 추가하고 Synapse 변경 로그 에 기록된 대로 v1.114.0부터 기본적으로 활성화했습니다 .
이 가이드는 Synapse가 이미 Docker Compose를 사용하여 공개 HTTPS URL(예: ) 뒤에서 실행되고 있다고 가정합니다 https://matrix.example.org. Compose 프로젝트에 대한 셸 액세스 권한, 이미지 태그 및 홈서버 구성을 편집할 수 있는 방법, 그리고 현재 버전에서 네이티브 슬라이딩 동기화를 지원하는 모바일 앱이 필요합니다. 슬라이딩 동기화를 지원하지 않는 클라이언트에서 초기 로딩 속도만 향상시키려는 경우, 프록시를 추가해도 해당 클라이언트가 슬라이딩 동기화 기능을 사용하게 되지는 않습니다.
새로운 배포를 과거의 최소 기능 버전으로 고정하는 대신, 현재 유지 관리되는 Synapse 릴리스를 사용하십시오. 공식 Synapse 릴리스 와 이전 버전의 업그레이드 노트를 검토하십시오 . 업그레이드하기 전에 데이터베이스와 Synapse 데이터/구성 볼륨을 백업하고, 노트에 중간 업그레이드 단계가 필요한지 확인하십시오. 특히 오래된 설치 환경에서는 이 부분이 중요합니다. Synapse의 슬라이딩 동기화 룸 상태 노출 관련 보안 권고 에 따르면 영향을 받는 릴리스는 v1.120.0까지이며, v1.120.1에서 수정되었습니다. 단순히 최초 패치 버전이 아닌, 최신 수정 사항이 포함된 현재 지원되는 릴리스를 선택하십시오.
Compose 파일에서 Synapse 서비스 키와 해당 서비스에서 사용하는 이미지 태그를 확인하세요. 태그가 이전 버전으로 고정되어 있으면 선택한 지원되는 릴리스로 변경하세요. 그런 다음 해당 서비스만 풀(pull)하고 다시 생성하세요. synapse서비스 이름이 다른 경우 아래 내용을 바꿔주세요.

docker compose pull synapse

docker compose up -d synapse
docker compose logs --tail=100 synapse
계속 진행하기 전에 시작 오류 및 완료된 데이터베이스 업그레이드에 대한 로그를 검토하십시오. 시작에 실패할 경우, 버전별 업그레이드 지침을 참조하여 데이터베이스에 적합한 복구 프로세스를 사용하여 백업만 복원하십시오.
Synapse는 일반적으로 기본적으로 슬라이딩 동기화 기능을 활성화하므로 새로 설치할 때 추가 YAML 파일이 필요하지 않은 경우가 많습니다. 이 설정은 이전 MSC라는 이름을 유지하고 있어 혼동을 줄 수 있지만, Synapse의 기본 구현을 제어하는 것이며 더 이상 사용되지 않는 프록시를 실행하라는 요청이 아닙니다. 기존 설정에서 homeserver.yaml명시적으로 false 값이 설정되어 있는지 확인하십시오. 만약 그렇다면 기존 기능 블록에서 해당 값을 변경하십시오.

experimental_features:
msc3575_enabled: true
이미 존재하는 경우 experimental_features, 중복된 YAML 키를 추가하는 대신 해당 블록을 편집하십시오. 설정이 없거나 이미 true인 경우에는 그대로 두십시오. 구성 변경 후 Synapse 서비스를 다시 생성하고 로그를 확인하십시오. YAML 들여쓰기 오류로 인해 Synapse가 시작되지 않을 수 있습니다.
에서 제공되는 JSON을 검사하십시오 https://matrix.example.org/.well-known/matrix/client. 이전 속성이 포함되어 있으면 org.matrix.msc3575.proxy관련 없는 클라이언트 검색 항목은 유지하면서 해당 속성을 제거하십시오. 또한 Matrix 클라이언트 요청을 더 이상 사용하지 않는 프록시로 보내는 모든 역방향 프록시 규칙을 제거하십시오. 표준 /_matrix/client/API 경로는 Synapse에 도달해야 합니다. MSC4186에 대한 새 프록시 포트를 추가하거나 프록시 URL을 광고하지 마십시오. 홈서버 URL을 포함하여 설정에 필요한 다른 잘 알려진 값은 그대로 유지하십시오.
공용 홈서버에 접속 가능한 컴퓨터에서 클라이언트-서버 버전 엔드포인트를 쿼리합니다. 이렇게 하면 개인 Docker 네트워크의 컨테이너만 확인하는 것이 아니라 클라이언트가 실제로 검색하는 서비스를 확인할 수 있습니다.

curl -fsS https://matrix.example.org/_matrix/client/versions | jq '.unstable_features["org.matrix.simplified_msc3575"]'
네이티브 지원이 활성화되고 엔드포인트가 올바르게 라우팅된 Synapse 릴리스의 경우, 이 명령은 를 출력해야 합니다 true. jq를 사용할 수 없는 경우, curl파이프(|) 없이 요청을 실행하고 JSON 필드를 검사하십시오. 값이 없거나 거짓인 경우 유용한 오류 신호입니다. DNS 및 HTTPS가 예상 서버에 도달하는지, 리버스 프록시가 클라이언트 API 경로를 Synapse에 전달하는지, 실행 중인 이미지가 선택한 버전인지, 명시적인 구성으로 해당 기능이 비활성화되지 않았는지 확인하십시오. 진단 출력을 공유할 때 액세스 토큰을 노출하지 마십시오. 이 공개 버전 요청에는 액세스 토큰이 필요하지 않습니다.
비교에 사용할 동일한 계정과 휴대폰을 사용하여 네이티브 프로토콜을 지원하는 클라이언트 버전으로 로그인하거나 다시 연결하십시오. 가능하면 서버를 변경하기 전에 기준선을 기록하십시오. 로컬 앱 데이터를 삭제하거나 재구축한 후 앱을 완전히 종료한 후의 콜드 스타트 결과를 비교하십시오. 단, 이 과정이 캐시된 콘텐츠를 제거한다는 점을 이해하는 경우에만 해당합니다. 그 다음에는 일반적인 웜 스타트 결과와 휴대폰이 오프라인 상태였다가 다시 연결된 후의 결과를 비교하십시오. 네트워크, 계정, 회의실 설정 및 테스트 방법을 일관되게 유지하십시오.
빠른 첫 번째 방 목록 표시 속도와 재연결 후 깔끔한 동기화는 클라이언트가 예상 경로를 사용하고 있음을 나타내는 실질적인 지표입니다. 하지만 모든 경우에 속도 향상이 보장되는 것은 아닙니다. 클라이언트 구현 및 로컬 캐시, 네트워크 지연 시간, 데이터베이스 성능, 계정 방 개수, 서버 부하 등 모든 요소가 결과에 영향을 미칩니다. 슬라이딩 동기화는 미디어 다운로드 속도를 높이거나 과부하된 데이터베이스를 복구하지 않습니다. 기능 검사를 통과했지만 앱 속도가 여전히 느리다면, 다른 지원되는 클라이언트와 비교하여 병목 현상을 조사한 후 프록시 또는 캐시 설정을 변경하십시오. 단종된 MSC3575 프록시에 의존하는 이전 클라이언트를 사용하는 경우, 이전 검색 경로를 제거하기 전에 호환성을 별도로 테스트하십시오. 하나의 엔드포인트가 모든 클라이언트 세대를 지원한다고 가정하지 마십시오.
pg_dump를 사용하여 Synapse를 백업하고, 서명 키와 미디어를 보호하고, 오래된 일회용 키를 재사용하지 않고 깨끗한 PostgreSQL 데이터베이스에 복원하세요.
Mjölnir를 전용 Matrix 계정, 암호화된 관리실, Docker Compose, 정책 목록 및 권한 검사와 함께 설정하십시오.
기존 프록시를 건너뛰고 Synapse에 내장된 슬라이딩 동기화 기능을 구성하십시오. 클라이언트 검색을 확인한 다음 호환되는 전화기에서 회의실 목록 로딩 및 재연결 동작을 측정하십시오.
Element Web을 정적 사이트로 배포하고, Matrix 홈서버를 가리키도록 설정하고, HTTPS를 추가하고, Nginx를 구성하여 오래된 파일 없이 업데이트를 제공하도록 하십시오.
64비트 라즈베리 파이 4에 Conduit를 설치하여 영구 데이터 저장, HTTPS 연동, 보호된 회원가입, 그리고 홈서버 작동 여부 확인 기능을 구성합니다.
Element 또는 Matrix API를 사용하여 권한, Synapse 명명 및 연동을 확인하고 Matrix 회의실에 도메인에서 쉽게 공유할 수 있는 주소를 부여하세요.
coturn과 Synapse를 일치하는 TURN 자격 증명으로 구성하고, 필요한 릴레이 포트를 열고, Matrix 클라이언트가 릴레이 후보를 가져올 수 있는지 확인합니다.
Docker Compose, PostgreSQL, 비공개 설정 파일, 그리고 HTTPS를 통해 노출하기 전에 필요한 검사 기능을 사용하여 Synapse 홈 서버를 영구적으로 설정합니다.
Element 웹 배포에 브랜드 이름, 사용자 지정 색상 및 로그인 자산을 설정하는 동시에 Element 브랜드로 유지되는 부분을 파악하세요.
Synapse가 프로세스별 파일 열기 제한에 도달했는지 진단하고, 해당 서비스 또는 워커에 대한 systemd 드롭인을 설정하고, 실제 제한을 확인합니다.