Matrix Synapse에서 페더레이션을 설정하는 방법: 단계별 가이드

Matrix 페더레이션을 사용하면 Synapse 홈서버가 다른 홈서버와 회의실 이벤트를 교환하여 서로 다른 서버를 사용하는 사용자도 같은 회의실에 참여할 수 있습니다. 설정하려면 Synapse의 페더레이션 API가 HTTPS를 통해 접근 가능하도록 하고, 올바른 서버 검색 정보를 게시하고, 필요한 네트워크 트래픽을 허용하고, 공용 엔드포인트를 테스트해야 합니다. DNS, TLS 또는 프록시 라우팅이 잘못된 경우 Synapse를 시작하거나 8448번 포트를 여는 것만으로는 충분하지 않습니다.

이 가이드에서는 일반적인 리버스 프록시 배포 구성을 사용합니다. Matrix ID 도메인은 `<matrix.h>`이고 example.org, Synapse는 `<matrix.h>`에서 실행되며 matrix.example.org, 프록시는 443번 포트에서 TLS를 처리합니다. 예시 도메인 두 개를 실제 도메인으로 바꾸십시오. Synapse가 이미 `<matrix.h>`에서 HTTPS를 통해 접근 가능한 경우 example.org:8448, 일반적으로 위임이 필요하지 않습니다. 명령어와 파일 경로는 Synapse를 패키지, 가상 환경 또는 컨테이너에서 설치했는지에 따라 달라집니다.

연방제가 성공적으로 작동하기 위해서는 무엇이 반드시 충족되어야 할까요?

• Synapse 서버에는 안정적인 공용 도메인이 있습니다 server_name. 이 이름은 Matrix ID 등에 나타나며 @alex:example.org, 나중에 변경하는 것은 일반적인 호스트 이름 편집 작업이 아닙니다.
• 다른 홈서버는 HTTPS를 통해 페더레이션 API에 접속하여 TLS 인증서를 검증할 수 있습니다.
• 서버 검색을 통해 원격 홈 서버는 올바른 호스트와 포트로 연결됩니다. 표준 페더레이션 포트는 8448이며, 위임은 443 포트의 HTTPS를 가리킬 수 있습니다.
• 방화벽 규칙은 사용자가 선택한 페더레이션 엔드포인트에 대한 인바운드 트래픽과 아웃바운드 페더레이션 연결을 허용합니다.

페더레이션은 서버 간 통신에 관한 것입니다. 비공개 방을 자동으로 공개 방으로 만들거나 다른 사용자를 초대하는 기능은 없습니다. 사용자는 여전히 방에 참여하거나 초대받아야 하며, 방 멤버십 및 방 설정에 따라 참여 자격이 결정됩니다. 먼저 Matrix ID의 형식을 정한 다음 Synapse와 동일한 도메인을 사용하세요 server_name.

1단계: Synapse 서버 이름과 배포 상태를 확인합니다.

활성화된 도메인을 열고 해당 도메인을 유지할 것인지 homeserver.yaml확인하십시오 . 일반적인 구성은 다음과 같습니다.server_name

server_name: "example.org"
public_baseurl: "https://matrix.example.org/"

server_name사용자의 Matrix ID에 있는 도메인을 결정합니다. public_baseurl공개 클라이언트용 URL(예: 사용자가 클라이언트에 입력하는 URL)이며, 리버스 프록시 뒤에서는 프록시 URL을 지정해야 합니다. 이 두 가지는 용도가 다르므로 서버 이름을 백엔드 컨테이너 이름으로 바꾸거나 서브도메인과 일치하도록 변경하지 마십시오. 서버가 이미 사용 중인 경우 네트워크 설정을 변경하기 전에 구성 및 데이터베이스를 백업하십시오.

Synapse의 설치 및 관리 방식을 확인하십시오. systemd 서비스, Docker Compose 스택, Kubernetes 배포 및 관리형 호스팅 제품은 재시작 및 네트워킹 절차가 서로 다릅니다. 아래 예제를 올바른 구성 파일에 적용하고 기존 리스너 및 사용자 지정 설정을 유지하십시오.

2단계: 8448 포트에서 직접 연동 또는 443 포트로의 위임을 선택합니다.

연합 가입에는 일반적으로 두 가지 경로가 있습니다.

• 기본 포트 8448을 사용하려면 도메인 의 DNS를 server_name해당 서버로 지정하고, 포트 8448에서 HTTPS를 노출하고, 해당 도메인에 유효한 인증서를 제공해야 합니다. Synapse 설명서에 따르면 API가 지정된 도메인의 server_name포트 8448에서 사용 가능한 경우 위임은 필요하지 않습니다.
• 위임 기능을 사용하여 포트 443을 사용하십시오.https://example.org/.well-known/matrix/server JSON 형식으로 다른 서버를 실제 엔드포인트로 연결하는 서비스를 제공합니다 (예: {"m.server":"matrix.example.org:443"}). 위임된 호스트 이름은 공개적으로 확인되어야 하며 유효한 인증서를 제시해야 합니다 matrix.example.org.

모든 배포 환경에서 포트 8448이 필수적인 것은 아닙니다. 443 포트로 위임하는 경우, 인바운드 페더레이션은 443 포트를 사용할 수 있습니다. 아웃바운드 연결이 송신 방화벽에 의해 제한되는 경우, 원격 서버에서 443 포트 또는 8448 포트를 사용할 수 있으므로 두 포트 모두 허용해야 합니다. 수신 경로 하나를 선택하고 DNS 레코드, TLS 인증서, 리버스 프록시 및 방화벽이 해당 경로와 일치하도록 설정하십시오.

3단계: Synapse의 페더레이션 API를 리버스 프록시를 통해 라우팅합니다.

Synapse는 일반적으로 리버스 프록시 뒤에서 HTTP 포트 8008을 사용합니다. 프록시는 HTTPS를 종료하고 Matrix 엔드포인트를 Synapse로 전달합니다. 관련 homeserver.yaml리스너에서 HTTP 리스너가 클라이언트 및 페더레이션 리소스를 모두 포함하고 프록시 헤더를 신뢰하도록 설정해야 합니다.

listeners:
  - port: 8008
    type: http
    tls: false
    x_forwarded: true
    bind_addresses: ['127.0.0.1']
    resources:
      - names: [client, federation]

이것은 예시 리스너일 뿐이며, 모든 설치 환경의 전체 구성을 대체하는 것은 아닙니다. Synapse가 컨테이너에서 실행되는 경우, 127.0.0.1컨테이너 내부의 바인딩 주소로 인해 프록시 컨테이너가 Synapse에 접근할 수 없게 될 수 있습니다. 이 경우 서비스 네트워크와 적절한 바인딩 주소를 사용하십시오. 백엔드 리스너는 비공개로 유지하고, 의도한 대로 프록시만 노출하십시오.

프록시가 포트 8008로 요청을 전달하도록 구성하려면 /_matrix및 설정 을 지정 하십시오. NGINX의 경우 필수 설정 위치는 다음과 같습니다./_synapse/clientX-Forwarded-ForX-Forwarded-Proto

location ~ ^(/_matrix|/_synapse/client) {
    proxy_pass http://127.0.0.1:8008;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $host;
}

호스트 또는 컨테이너 네트워크에 맞는 올바른 업스트림 주소를 사용하십시오. 경로를 재작성하여 추가하지 마십시오 proxy_pass. Synapse의 프록시 지침에 따르면 인코딩된 요청 경로를 정규화하면 페더레이션 서명 검증 오류가 발생할 수 있습니다. 사용자가 더 큰 파일을 업로드해야 하는 경우 프록시 업로드 크기 제한을 Synapse 미디어 업로드 설정과 일치시키십시오.

4단계: TLS 및 DNS 구성

페더레이션을 제공하는 호스트 이름에 대한 공개적으로 신뢰할 수 있는 TLS 인증서를 발급받으세요. 위에서 설명한 리버스 프록시 설정의 경우, matrix.example.org해당 호스트로 위임을 사용할 때 필요합니다. 프록시가 전체 인증서 체인을 제공하고, 인증서를 자동으로 갱신하며, 원격 서버가 접속할 포트에 올바른 인증서를 제공하는지 확인하세요. 자체 서명된 인증서 또는 잘못된 호스트 이름에 대한 인증서는 다른 홈 서버에서 유효성 검사를 통과하지 못합니다.

프록시를 가리키는 공개 A 레코드를 생성하고, IPv6를 사용하는 경우 AAAA 레코드도 생성하십시오 matrix.example.org. 두 레코드가 의도한 서비스에 도달하는지 확인하십시오. AAAA 레코드가 잘못되면 IPv4에서는 정상적으로 작동하더라도 IPv6를 지원하는 원격 서버에서 오류가 발생할 수 있습니다. 포트 8448을 직접 사용하는 경우 DNS는 example.org리스너를 가리켜야 하며 해당 인증서가 일치해야 합니다 example.org.

5단계: 서버 검색 정보 게시

위임된 예제의 경우, 아래 HTTPS URL이 상태 코드 200과 정확한 엔드포인트를 포함하는 JSON을 반환하도록 하세요.

https://example.org/.well-known/matrix/server

{
  "m.server": "matrix.example.org:443"
}

해당 파일을 다음과 같이 제공하십시오 application/json. 로그인 없이 공개적으로 읽을 수 있는지, 무한 루프에 빠지지 않는지, 호스트 이름과 포트가 TLS 프록시와 일치하는지 확인하십시오. matrix.example.org프록시가 실제로 다른 곳으로 페더레이션을 라우팅하는 경우 해당 파일을 게시하지 마십시오.

serve_server_wellknown: trueSynapse는 요청이 Synapse로 적절하게 라우팅될 때만 이 파일을 직접 제공할 수 있습니다 https://<server_name>/. 서버 이름이 example.org이지만 Synapse가 에 호스팅되어 있는 경우 matrix.example.org, 에 있는 정적 웹 서버 또는 리버스 프록시가 example.org위임 응답을 제공하기에 더 적합한 위치일 수 있습니다.

흔히 서버 파일과 클라이언트 파일을 같은 것으로 혼동하는 경우가 있습니다 /.well-known/matrix/client. /.well-known/matrix/server서버 파일은 다른 홈서버가 수신되는 페더레이션을 검색하는 데 도움을 줍니다. 클라이언트 파일은 클라이언트에게 표시되는 홈서버 URL을 제공하며 페더레이션에 있어 선택 사항입니다. 호환되는 클라이언트가 사용자의 Matrix ID를 통해 클라이언트 URL을 검색할 수 있도록 하려면 클라이언트 파일을 별도로 설정하십시오.

6단계: 필요한 방화벽 경로를 엽니다.

직접 연결 페더레이션의 경우, TLS 리스너 또는 프록시로 들어오는 TCP 8448 포트를 허용하십시오. 위임 연결 예시의 경우, 프록시로 들어오는 TCP 443 포트를 허용하십시오. 클라이언트 연결은 일반적으로 443 포트에서 HTTPS를 사용합니다. 외부 네트워크 액세스가 제한된 경우, Synapse가 TCP 443 및 8448 포트를 통해 원격 홈 서버에 연결할 수 있도록 허용하십시오. 리버스 프록시를 공용 진입점으로 사용하려는 경우, Synapse 백엔드 포트 8008을 공용 인터넷에 개방하지 마십시오.

서버가 클라우드 방화벽, 라우터, 컨테이너 네트워크 및 호스트 방화벽 뒤에 있는 경우 각 계층을 확인하십시오. 포트 8008에 대한 로컬 요청이 성공했다는 것은 Synapse가 로컬에서 응답한다는 것만 증명할 뿐이며, 원격 Matrix 서버가 도메인을 확인하거나 TLS 유효성을 검사하거나 공용 수신기에 연결할 수 있다는 것을 증명하는 것은 아닙니다.

7단계: 안전하게 재시작하고 공용 엔드포인트를 확인합니다.

재시작하기 전에 설치 방법에 따라 지원되는 유효성 검사 명령을 사용하여 YAML 파일의 유효성을 검사하십시오. 그런 다음 Synapse 서비스 또는 배포를 다시 시작하고 로그에서 구성 또는 리스너 오류를 확인하십시오. 개인 네트워크 외부의 컴퓨터에서 검색 파일과 페더레이션 버전 엔드포인트를 요청하십시오.

curl -i https://example.org/.well-known/matrix/server
curl -i https://matrix.example.org/_matrix/federation/v1/version

첫 번째 명령의 경우, 올바른 정보가 포함된 JSON 본문이 있는 HTTPS 응답을 받게 됩니다 m.server. 두 번째 명령의 경우, 프록시 오류, 인증서 경고 또는 연결 시간 초과가 아닌 Synapse에서 성공적인 HTTPS 응답을 받게 됩니다. 정확한 응답 본문은 Synapse 버전에 따라 다를 수 있습니다.

다음으로 Matrix Federation Tester 에 Matrix server_name(예: , example.org반드시 프록시 호스트 이름일 필요는 없음) 를 입력합니다 . 보고된 DNS, 위임, 인증서 또는 엔드포인트 오류를 ​​수정하고 테스트를 다시 실행합니다. 마지막으로 다른 홈서버의 사용자를 테스트룸에 초대하거나 다른 곳에서 호스팅되는 테스트룸에 참여합니다. 테스트 결과가 성공적이면 공용 연결 상태를 확인하는 데 유용하지만, 모든 원격 서버, 테스트룸 정책, 방화벽 또는 클라이언트 구성이 동일하게 작동한다는 것을 보장하지는 않습니다.

잘못된 인식으로 인해 예상치 못한 상황이 발생하거나 시스템이 제대로 작동하지 않는 경우가 있습니다.

• "항상 8448번 포트를 노출해야 하나요?" 아닙니다. 기본값은 8448번이지만, 서버 위임에 따라 수신되는 페더레이션 요청을 443번 포트로 보낼 수 있습니다. 게시된 검색 경로에서 실제로 사용하는 포트를 여십시오.
• "클라이언트 고유 파일이 페더레이션을 가능하게 합니다." 그렇지 않습니다. 페더레이션 검색은 서버 고유 엔드포인트 또는 지원되는 DNS 대체 정보를 사용하며, 클라이언트 엔드포인트는 다른 용도로 사용됩니다.
• "연합 기능을 사용하면 모든 로컬 룸이 공개됩니다." 아닙니다. 연합 기능은 서버 간 통신을 가능하게 할 뿐입니다. 룸 공개 여부와 멤버십은 여전히 ​​참여 여부를 결정합니다. 필요한 사용 사례를 확인하려면 테스트 룸에 원격 계정을 초대해 보세요.
• "로컬 상태 점검에서 녹색으로 표시되면 페더레이션이 성공한 것입니다." 아닙니다. 로컬 점검은 공용 DNS, 외부 TLS 유효성 검사, NAT, 클라우드 방화벽 규칙 또는 프록시 라우팅을 테스트하지 않습니다. 외부에서 페더레이션 테스터를 사용하여 테스트하십시오.

Synapse 공식 문서에서는 TLS 종료를 위해 리버스 프록시 사용을 권장하며, 클라이언트 및 페더레이션 포트를 별도로 사용하도록 안내합니다. 리버스 프록시 구성 , 수신 페더레이션 위임 , Synapse 구성 옵션 , 방화벽 및 보안 지침 에 대한 자세한 내용은 공식 가이드를 참조하십시오 . 서버 검색 규칙은 Matrix 서버-서버 API 사양을 참조하십시오 . 여기에 제시된 예제는 HTTPS 리버스 프록시 뒤에 있는 표준 Synapse 환경을 가정합니다. 컨테이너 네트워킹, 관리형 배포 및 사용자 지정 리스너 레이아웃의 경우 다른 값이 필요할 수 있습니다.