Matrix Synapse 서버를 페더레이션에 사용할 수 있도록 설정하세요

Matrix Synapse 홈서버를 페더레이션하려면 서버 이름이 HTTPS를 통해 공용 인터넷에서 검색되고 접근 가능하도록 설정한 다음, Matrix 서버 간 요청을 Synapse로 라우팅해야 합니다. 일반적인 설정에서는 리버스 프록시가 443번 포트에서 TLS를 처리하고, /.well-known/matrix/server파일에서 Matrix 도메인을 해당 프록시로 지정합니다. Synapse가 이미 서버 이름 도메인의 8448번 포트에서 응답하는 경우 위임이 필요하지 않을 수 있습니다.

이 안내서에서는 example.comMatrix 서버 이름을 영구적인 서버 이름으로, matrix.example.com머신 또는 프록시 엔드포인트 이름을 으로 사용합니다. 두 이름 모두 실제 사용 환경에 맞게 변경하십시오. 홈서버는 Matrix 계정과 룸을 저장하며, 페더레이션을 통해 홈서버 간 통신이 가능합니다. DNS, 방화벽 규칙, 프록시 구문, 컨테이너 네트워킹 및 인증서는 호스트에 따라 다릅니다.

설정을 변경하기 전에

사용자의 Matrix ID 형식을 @name:example.com또는 중 하나로 결정하세요. 의 @name:matrix.example.com값은 Matrix ID와 회의실 주소의 일부가 됩니다. Synapse 설치 설명서에서는 설치 전에 이 값을 선택하라고 권장하는데, 설치 후에는 변경할 수 없으며 변경 시 문제가 발생할 수 있기 때문입니다. Synapse를 이미 사용 중인 경우, 웹 주소와 일치시키기 위해 변경하지 마세요. 기존 ID를 유지하려면 위임 기능을 사용하세요.server_namehomeserver.yaml

YAML 편집기에는 server_name: example.com과 설치 전에 값을 선택하라는 알림이 표시됩니다.
서버 이름은 Matrix ID의 일부이므로 계속 진행하기 전에 확인하십시오.

편집하기 전에 Synapse, 프록시 및 공용 DNS에 액세스할 수 있는지, 그리고 페더레이션 엔드포인트에 유효한 TLS 인증서가 있는지 확인하십시오. homeserver.yaml홈서버의 ID를 설정하는 서명 키를 백업하십시오. 이 키는 안전하게 보관하십시오. 일반적인 페더레이션 설정 과정에서는 키를 다시 생성할 필요가 없습니다.

공공 경로를 설정하세요

1. Synapse의 HTTP 리스너를 확인합니다.

Synapse는 일반적으로 리버스 프록시 뒤의 포트에서 HTTP 요청을 수신합니다 8008. 프록시 트래픽을 수락하는 리스너에서 Synapse가 프록시가 전달한 클라이언트 주소와 스키마를 사용할 수 있도록 설정 해야 합니다. 프록시는 외부 클라이언트가 제공하는 임의의 값을 전달하는 대신 적절한 헤더를 설정 x_forwarded: true해야 합니다 .X-Forwarded-ForX-Forwarded-Proto

YAML 리스너 발췌본은 Synapse가 HTTP 포트 8008에서 실행되고 x_forwarded가 활성화되었으며 루프백 바인딩 주소가 지정되었음을 보여줍니다.
리스너는 로컬 프록시에서 HTTP 요청을 수락하고 Synapse의 전달 헤더 처리를 활성화합니다.

프록시가 동일 호스트에서 실행될 때 바인딩 방식을 127.0.0.1사용하는 것이 적합합니다. 프록시가 다른 컨테이너나 머신에 있는 경우에는 해당 주소가 프록시에서 접근 가능한 주소가 아니면 바인딩 방식을 사용하는 것이 적합하지 않습니다. 컨테이너 환경에서는 프록시가 접근 가능한 네트워크 주소 또는 서비스 이름을 사용하고, 컨테이너 네트워크 또는 방화벽을 통해 접근을 제한해야 합니다. 기존 리스너 구조를 유지하고 관련 값을 수정하십시오. 기존 설정 위에 아무렇게나 일부를 붙여넣지 마십시오.

2. 프록시를 통한 라우트 매트릭스 경로

프록시의 HTTPS 가상 호스트를 구성하여 두 경로 모두 Synapse의 HTTP 리스너로 전달하도록 하십시오 /_matrix. /_synapse/client첫 번째 경로는 페더레이션을 포함한 Matrix API를 전달하고, 두 번째 경로는 Synapse 클라이언트 엔드포인트에 사용됩니다. 사용하는 프록시 소프트웨어의 공식 예제를 참조하여 요청 경로를 그대로 유지하고 Synapse에서 예상하는 전달 헤더를 전송하십시오. URI 경로를 정규화, 디코딩 또는 변경하지 마십시오. 프록시가 인코딩된 경로를 변경하면 Matrix 요청 서명이 실패할 수 있습니다.

리버스 프록시 구성 편집기에는 Matrix API 및 Synapse 클라이언트 경로가 포워딩된 헤더와 함께 localhost 포트 8008로 라우팅되는 것이 표시됩니다.
프록시는 URI를 변경하지 않고 Matrix API 경로 두 개를 모두 Synapse에 전달해야 합니다.

정확한 구성 방법은 Nginx, Caddy, Apache, 로드 밸런서 및 관리형 호스팅 환경에 따라 다릅니다. 각 공급업체의 최신 구문과 Synapse 역방향 프록시 문서를 참조하십시오. 웹 클라이언트를 제공하지만 페더레이션 API 경로를 생략하는 프록시 규칙으로는 충분하지 않습니다.

3. DNS, HTTPS 및 선택한 포트가 일치하는지 확인하십시오.

예시의 경우, matrix.example.com해당 경로는 프록시 또는 로드 밸런서로 연결되어야 하며, 포트는 443외부에서 접근 가능해야 합니다. 프록시는 해당 경로에 대한 유효한 인증서가 필요합니다 matrix.example.com. 만약 페더레이션을 직접 제공하는 경우 example.com:8448, 해당 경로와 인증서를 게시하고 포트를 열어주세요 8448. 일반적인 기본값인 8448 포트를 직접 사용하거나, 443 포트와 같은 다른 호스트의 포트로 위임할 수 있습니다.

DNS, 방화벽 또는 클라우드 보안 그룹 규칙과 사설 네트워크 외부의 인증서를 확인하십시오. CDN 또는 터널이 앞에 있는 경우, 필요한 Matrix 트래픽을 지원하는지 여부는 해당 서비스의 현재 구성에 따라 달라집니다. 호환성을 가정하기보다는 해당 서비스의 문서를 확인하고 실제 경로를 테스트하십시오.

필요할 때 연합 검색 결과를 게시합니다.

4. 별도의 엔드포인트에 대한 서버 위임을 추가합니다.

Matrix ID 도메인이 비어 있지만 example.comSynapse에 에서 접속 가능한 경우 matrix.example.com:443, 이 JSON을 HTTPS를 통해 에서 제공하십시오 https://example.com/.well-known/matrix/server.

{
  "m.server": "matrix.example.com:443"
}
example.com/.well-known/matrix/server의 브라우저 스타일 JSON 보기에는 m.server 값이 matrix.example.com:443으로 표시됩니다.
이 페더레이션 검색 레코드는 example.com을 포트 443의 matrix.example.com에 있는 HTTPS 엔드포인트로 위임합니다.

이 예제에서는 포트 443이 명시적으로 지정되어 있습니다. 포트를 생략하면 Matrix 검색은 기본값인 8448을 사용합니다. 이 파일은 /.well-known/matrix/client클라이언트가 클라이언트-서버 API를 찾는 데 도움이 되는 파일과 혼동하지 마십시오. 이 파일은 서버 간 연동과는 별개입니다. Synapse는 서버 이름 도메인이 Synapse로 직접 연결되는 경우 서버 잘 알려진 파일을 자체적으로 제공할 수 있지만, 별도의 엔드포인트를 사용하는 경우 일반적으로 서버 이름 도메인의 웹 서버에 파일을 게시합니다.

연합 검색은 Matrix에서 정의하고 Synapse에서 문서화합니다. Matrix 사양에 따르면 검색은 를 통해 이루어집니다 /.well-known/matrix/server. SRV 레코드와 같은 다른 방법을 선택하기 전에 Synapse 위임 지침을 확인하십시오. 이는 TLS 기대치에도 영향을 미칩니다.

서버 외부에서 테스트

5. 레코드를 확인한 후 페더레이션 검사를 실행합니다.

서버의 사설 네트워크 외부의 컴퓨터에서 검색 URL을 요청하십시오. 그러면 로그인 페이지, HTML 리디렉션, 인증서 경고 또는 관련 없는 웹사이트 없이 HTTPS를 통해 위의 JSON 객체가 반환되어야 합니다. 그런 다음 위임된 호스트 이름이 확인되는지, 인증서가 유효한지, 그리고 광고된 포트가 Synapse에 도달하는지 확인하십시오. 테스트하기 전에 프록시의 구성 검사기를 사용하고 프록시를 다시 로드하십시오.

마지막으로 공식 Matrix Federation Tester 에 서버 이름(예: example.com, 위임된 호스트 이름이 아닌 실제 서버 이름 )을 입력하십시오 . Synapse 페더레이션 가이드에서는 와 같은 공개 회의실에 참여하여 테스트하는 것도 권장합니다 . 테스트가 성공하면 일반적인 검색 및 연결 가능성 검사가 통과되었음을 확인하는 것이며, 원격 정책 및 네트워크 환경이 다를 수 있으므로 모든 원격 서버 또는 모든 회의실 작업이 정상적으로 작동한다는 것을 보장하는 것은 아닙니다.server_name#synapse:matrix.org

테스터가 서버에 연결할 수 없다고 보고하는 경우, 시도한 도메인 및 포트, DNS, 방화벽 규칙, 인증서 이름, 프록시 경로, 전달된 헤더, 그리고 리디렉션으로 인해 요청이 변경되었는지 확인하십시오. 현재 Synapse 페더레이션 문서에서는 Synapse 페더레이션 서버가 경우에 따라 HTTP 308 리디렉션을 따르지 않을 수 있다고 명시적으로 경고합니다. 페더레이션 엔드포인트에 308 리디렉션을 사용하지 말고, 문제를 해결한 후 다시 테스트하십시오. 버전별 동작에 대해서는 설치된 Synapse 릴리스에 해당하는 문서를 참조하십시오.

페더레이션을 사용하려면 원격 홈 서버가 페더레이션 API를 검색하고 연결해야 합니다. 모든 원격 서버에서 이 기능이 제대로 작동하는지는 구성만으로는 알 수 없습니다. 테스터를 사용하여 실제 룸에 참여해 경로를 확인한 후, 문제가 발생하는 특정 엔드포인트 또는 오류를 조사하십시오.

이 인터페이스 패널은 구성 및 검색 데이터의 개략적인 예시이며, 실제 서버의 스크린샷이 아닙니다. 문서 참조는 2026년 10월 10일에 확인되었습니다.

댓글 남기기

Matrix Room 관리자 권한 오류를 해결하려면 다음 단계를 따르세요.

M_FORBIDDEN 오류의 원인을 방의 전력 수준, 멤버십 또는 Synapse 서버 관리자 액세스 권한으로 추적한 다음, 차단된 작업에 필요한 권한만 복원하십시오.

Matrix Synapse 서버를 페더레이션에 사용할 수 있도록 설정하세요

Matrix Synapse 서버를 페더레이션에 사용할 수 있도록 설정하세요

Synapse 검색, HTTPS 및 프록시 라우팅을 구성하여 다른 Matrix 홈서버가 서버를 찾고 연결할 수 있도록 하십시오.

Synapse OIDC를 통해 Element Web을 Keycloak에 연결합니다.

Element Web 사용자가 클라이언트 암호를 노출하지 않고 ID 서버를 통해 로그인할 수 있도록 Keycloak OIDC 클라이언트와 Synapse 공급자를 구성하십시오.

Element Key 백업 및 교차 서명을 안전하게 설정하는 방법

Element Key 백업 및 교차 서명을 안전하게 설정하는 방법

복구 키를 저장하고, Element 세션을 확인하고, 암호화된 메시지 키를 백업과 계정 암호를 혼동하지 않고 복원할 수 있는지 확인하십시오.

클라이언트 동기화 중 Matrix Synapse 메모리 충돌 방지

Synapse 동기화 중 메모리 부족 오류를 진단하고, 캐싱을 안전하게 조정하고, 요청 백로그를 식별하고, 안정적인 메모리 사용을 확인합니다.

Synapse Federation TLS 인증서 오류 해결

보안 검사를 비활성화하지 않고 매트릭스 페더레이션 인증서 오류를 올바른 서버로 추적하고, TLS 체인 또는 CA 신뢰를 복구하고, 수정 사항을 확인합니다.

Synapse Matrix 서버를 Cloudflare 뒤에 안전하게 배치하세요

Synapse Matrix 서버를 Cloudflare 뒤에 안전하게 배치하세요

Cloudflare의 HTTPS 443 포트를 통해 Matrix 클라이언트와 페더레이션을 라우팅하여 Synapse 검색 기능을 유지하고 API 트래픽 캐싱이나 미디어 업로드 오류를 방지합니다.

PostgreSQL 덤프를 사용하여 Matrix Synapse를 안전하게 복원하세요

pg_dump를 사용하여 Synapse를 백업하고, 서명 키와 미디어를 보호하고, 오래된 일회용 키를 재사용하지 않고 깨끗한 PostgreSQL 데이터베이스에 복원하세요.

Docker를 사용하여 Mjölnir를 Matrix Room 관리 봇으로 실행하세요

Docker를 사용하여 Mjölnir를 Matrix Room 관리 봇으로 실행하세요

Mjölnir를 전용 Matrix 계정, 암호화된 관리실, Docker Compose, 정책 목록 및 권한 검사와 함께 설정하십시오.

모바일 로딩 속도 향상을 위해 네이티브 매트릭스 슬라이딩 동기화를 활성화하세요.

모바일 로딩 속도 향상을 위해 네이티브 매트릭스 슬라이딩 동기화를 활성화하세요.

기존 프록시를 건너뛰고 Synapse에 내장된 슬라이딩 동기화 기능을 구성하십시오. 클라이언트 검색을 확인한 다음 호환되는 전화기에서 회의실 목록 로딩 및 재연결 동작을 측정하십시오.