Cloudflare 프록시 뒤에 Matrix 서버를 설정하는 방법

Matrix 서버는 Cloudflare 뒤에 위치할 수 있지만, 설정 방법은 클라이언트와 다른 홈 서버가 서버를 어떻게 검색하는지에 따라 달라집니다. Cloudflare의 표준 HTTP 프록시는 443번 포트에서 HTTPS를 지원합니다. Synapse 페더레이션은 일반적으로 8448번 포트를 기본으로 사용하는데, 이 포트는 Cloudflare의 표준 프록시 포트 목록에 포함되어 있지 않습니다. 안정적인 구성 방법은 Synapse를 443번 포트의 리버스 프록시를 통해 노출하고, 클라이언트와 페더레이션 트래픽을 해당 호스트 이름으로 연결하는 Matrix WNL(Well-Known Record)을 게시하는 것입니다. 또는 페더레이션을 8448번 포트에 유지하고 해당 DNS 레코드를 DNS 전용으로 설정할 수도 있습니다.

이 가이드에서는 Matrix의 공식 홈서버 구현인 Synapse를 사용하며, 예시 Matrix ID @alice:example.com와 클라이언트 엔드포인트를 제공 matrix.example.com합니다. 이러한 이름과 주소는 사용자의 환경에 맞게 변경해야 합니다. 본 가이드의 지침은 Synapse와 HTTPS 리버스 프록시가 이미 설치되어 있다고 가정합니다. 모든 홈서버 구현에 동일하게 적용되는 것은 아닙니다. 2026년 10월 6일 기준 Cloudflare 및 Element Synapse의 최신 문서를 기준으로 작성되었습니다.

올바른 네트워크 레이아웃을 선택하세요

Cloudflare의 orange-cloud 프록시는 HTTP/HTTPS 리버스 프록시입니다. 클라이언트와 원본 서버 사이에 위치하여 웹 요청을 프록시합니다. 모든 TCP 포트를 프록시하는 것은 아닙니다. 표준 HTTPS 포트는 443과 8443이지만, Synapse에서 일반적으로 사용하는 페더레이션 포트인 8448은 지원하지 않습니다. Cloudflare에서 지원하는 네트워크 포트 및 프록시 제한 사항을 참조하십시오 .

아래는 첫 번째 레이아웃입니다. 프록시된 DNS 레코드 자체만으로는 Matrix 검색, 역방향 프록시, TLS 또는 방화벽 정책을 구성하지 않습니다.

1. DNS를 구성하기 전에 Matrix 서버 이름을 결정하십시오.

Matrix 서버 이름은 사용자 ID에서 콜론 뒤에 오는 부분입니다. 이 예시에서는 `<matrix_server_name>`이므로 example.com사용자는 `<matrix_server_name>`과 같은 ID를 갖게 됩니다 @alice:example.com. 기술적인 클라이언트 호스트 이름은 `<matrix_server_name>`입니다 matrix.example.com. 이러한 구분 덕분에 사용자 ID에 사용되는 도메인은 안정적으로 유지되면서 트래픽은 다른 호스트 이름으로 위임됩니다. Synapse가 이미 초기화된 경우 함부로 변경하지 마십시오 server_name. Synapse는 사용자 및 회의실 ID의 일부이며, 이를 변경하는 것은 프록시 설정이 아닌 마이그레이션 작업입니다.

서버 이름 도메인에서 두 개의 작은 JSON 검색 문서를 제공할 계획입니다.

• https://example.com/.well-known/matrix/client호환되는 클라이언트에게 사용하도록 지시합니다 https://matrix.example.com.
• https://example.com/.well-known/matrix/server다른 홈서버들에게 연합에 접속하도록 안내합니다 matrix.example.com:443.

클라이언트 문서에는 Access-Control-Allow-Origin: *응답 헤더가 필요합니다. Synapse 위임 가이드에는 이러한 레코드와 예상 구조에 대한 예제가 포함되어 있습니다. Synapse 연합 위임을 참조하세요 .

2. Cloudflare DNS 레코드를 생성합니다.

Cloudflare DNS에서 서버의 공용 IPv4 주소를 가리키는 A레코드를 생성합니다. 원본 서버에 IPv6 연결이 정상적으로 작동하고 IPv6 방화벽이 구성된 경우에만 레코드를 추가합니다. 웹 호스트 이름의 프록시 상태를 ' 프록시됨 '(주황색 구름 아이콘)으로 설정합니다. 루트 도메인도 이 서버를 가리키고 잘 알려진 파일을 제공하는 경우, 해당 웹 레코드도 프록시로 설정합니다.matrixAAAA

메일 레코드를 포함한 관련 없는 레코드는 적절한 DNS 전용 설정으로 유지하십시오. MX 및 TXT 레코드는 프록시되지 않습니다. Cloudflare는 프록시된 A, AAAA 또는 CNAME 레코드가 HTTP/HTTPS 요청을 Cloudflare를 통해 라우팅하는 반면, DNS 전용은 원본 주소를 직접 반환한다고 설명합니다. 자세한 내용은 Cloudflare 프록시 상태 동작을 참조하십시오 .

Cloudflare에서 오리진 서버로의 인바운드 HTTPS를 허용하세요. 더욱 강력한 보호를 위해 오리진 방화벽을 Cloudflare에서 공개한 IP 범위로 제한하고 해당 범위를 최신 상태로 유지하세요. 영역이 활성화되기 전에 서버 IP가 노출된 경우 DNS 프록시를 사용해도 이전 주소가 무효화되지 않으므로 활성화 후 오리진 IP를 변경하는 것을 고려하세요. 주황색 ​​구름 아이콘만으로 직접 오리진 액세스를 차단한다고 생각하지 마세요.

3. Cloudflare와 원본 서버 간에 HTTPS를 구성합니다.

Cloudflare의 SSL/TLS 설정에서 원본 서버가 호스트 이름에 대한 유효한 인증서(예: 공개적으로 신뢰되는 인증서 또는 Cloudflare Origin CA 인증서)를 제공하는 경우 전체(엄격) 모드를 사용 하십시오. 전체(엄격) 모드는 Cloudflare와 원본 서버 간의 연결을 암호화하고 원본 서버의 인증서를 검증합니다. 유연 모드는 이와 같은 종단 간 TLS 경로를 제공하지 않습니다. 자세한 내용은 Cloudflare의 전체(엄격) 모드 관련 문서를 참조하십시오 .

인증서와 개인 키는 Synapse가 아닌 리버스 프록시에 설치해야 합니다. 리버스 프록시는 공용 포트 443에서 수신 대기하고 Matrix 요청을 Synapse의 HTTP 수신 포트(일반적으로 8008)로 내부적으로 전달해야 합니다. 리버스 프록시가 유일한 진입점인 경우 Synapse 수신 포트를 공개적으로 노출하지 마십시오.

4. Synapse에 신뢰할 수 있는 역방향 프록시 뒤에 있음을 알려줍니다.

해당 HTTP 리스너에서 homeserver.yaml전달된 헤더 처리를 활성화하십시오. 컨테이너화되지 않은 서버의 간소화된 예는 다음과 같습니다.

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

전체 구성을 교체하는 대신 이러한 설정을 기존 리스너에 병합하십시오. Synapse에서 관리하는 문서에서는 x_forwarded: true리버스 프록시 뒤에서 실행하는 것을 권장하며, 프록시가 동일한 호스트에서 실행되는 경우 localhost에 바인딩하도록 제안합니다. 컨테이너 배포의 경우 Synapse를 컨테이너의 루프백에 바인딩하면 호스트 프록시가 Synapse에 접근하지 못할 수 있습니다. 대신 컨테이너 또는 서비스의 네트워크 주소를 사용하고 해당 경로에 방화벽을 설정하십시오. 리스너 설정을 변경하기 전에 최신 Synapse 리버스 프록시 가이드를 참조하십시오 .

전달된 헤더는 Synapse가 사용자가 관리하는 프록시에서 오는 트래픽을 수락할 때만 신뢰할 수 있습니다. Cloudflare가 유일한 인터넷 연결 경로인 경우, 원본에 대한 직접적인 공개 액세스를 차단하고 프록시가 올바른 클라이언트 주소를 전달하도록 구성하십시오. $remote_addr그렇지 않으면 Cloudflare가 Nginx에 연결되어 있으므로 Nginx의 IP 주소는 Cloudflare 주소가 됩니다. Nginx의 real-IP 모듈이 Cloudflare에서 게시한 소스 범위만 신뢰하도록 구성한 후 사용하십시오 CF-Connecting-IP. 임의의 인터넷 클라이언트에서 오는 해당 헤더는 절대 신뢰하지 마십시오. Synapse 관리자 API는 특별한 이유가 없는 한 비공개로 유지하십시오.

5. 경로를 재작성하지 않고 경로 매트릭스를 생성합니다.

리버스 프록시를 구성하여 두 가지 요청 모두 Synapse로 전송하도록 하십시오 /_matrix. /_synapse/client요청 URI는 정확하게 유지해야 합니다. 프록시가 인코딩된 경로 세그먼트를 디코딩하거나 정규화하는 경우 Synapse 연동 요청 서명이 실패할 수 있습니다.

다음은 Nginx를 사용한 간략한 예시입니다 matrix.example.com. 이 예시는 해당 서버 블록에 대한 TLS 인증서 지시문이 이미 구성되어 있고, 리버스 프록시와 Synapse가 동일한 호스트에서 실행되고 있다고 가정합니다.

server {
    listen 443 ssl;
    server_name matrix.example.com;

    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_http_version 1.1;
        client_max_body_size 50M;
    }
}

이 정규 표현식 위치에 URI 접미사를 추가하지 마십시오 proxy_pass. Synapse 프록시 문서에서는 URI 정규화가 페더레이션 서명 오류의 원인이라고 지적합니다. 또한 client_max_body_sizeSynapse 업로드 제한 및 영역에 적용되는 Cloudflare 요금제 제한에 맞게 값을 조정하십시오. 50M위의 값은 예시일 뿐이며, 일반적인 권장 사항은 아닙니다.

Cloudflare는 자사 플랜에서 WebSocket을 지원하며, Matrix 클라이언트는 장시간 연결을 사용할 수 있습니다. 프록시에서 업그레이드를 허용하는지, 그리고 WAF 또는 속도 제한 규칙이 정상적인 Matrix 요청을 거부하지 않는지 확인하십시오. Cloudflare의 WebSockets 문서에서 업그레이드된 연결 처리 방식에 대한 설명을 확인할 수 있습니다.

6. 잘 알려진 답변들을 발표하십시오.

다음 두 가지 응답을 example.comHTTPS를 통해 제공하십시오. 웹 서버, 고정 호스트 또는 별도의 가상 호스트에서 반환할 수 있습니다. 클라이언트 문서와 페더레이션 문서는 서로 구분하여 관리하십시오.

GET /.well-known/matrix/client
HTTP/1.1 200 OK
Content-Type: application/json
Access-Control-Allow-Origin: *

{"m.homeserver":{"base_url":"https://matrix.example.com"}}

GET /.well-known/matrix/server
HTTP/1.1 200 OK
Content-Type: application/json

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

Matrix 검색 요구 사항 및 클라이언트 동작을 확인하지 않고 관련 없는 호스트로 리디렉션하는 것을 대체 방법으로 사용하지 마십시오. 서버 이름 호스트에 유효한 HTTPS 인증서가 있는지, 그리고 변경하는 동안 Cloudflare가 오래된 검색 응답을 캐시하지 않는지 확인하십시오.

7. API 트래픽을 유동적으로 유지하고 업로드량을 제한 범위 내로 유지하십시오.

인증된 Matrix API 응답은 캐시하지 마십시오. 특정 공개 응답을 다르게 처리해야 할 타당한 이유가 있는 경우가 아니라면, Matrix API 경로(및 )에 대한 캐시를 우회하도록 Cloudflare 캐시 규칙을 추가하십시오. /_matrix/*페더레이션 /_synapse/client/*엔드포인트를 차단하거나 차단하는 광범위한 WAF 또는 봇 규칙은 피하십시오. 페더레이션 요청은 여러 독립적인 홈 서버에서 발생합니다. 보안 규칙이 필요한 경우, 일반적으로 적용하기 전에 클라이언트 로그인, 동기화, 미디어 업로드 및 페더레이션에 대해 테스트하십시오.

업로드에는 여러 가지 독립적인 제한이 있습니다. 클라이언트, Cloudflare의 요금제 또는 영역 업로드 설정, 리버스 프록시의 본문 크기 제한, 그리고 Synapse의 제한이 그것입니다 max_upload_size. 413 오류는 이러한 제한 중 하나가 요청을 거부했음을 의미합니다. Cloudflare는 요금제별 업로드 제한을 명시하고 있으며, 이러한 설정은 명시된 제약 조건 내에서 조정할 수 있다고 안내합니다. 자세한 내용은 Cloudflare의 413 문제 해결 페이지를 참조하십시오 . 필요한 만큼만 제한을 높이고, 추가로 제한을 높이기 전에 설정된 제한보다 작은 파일로 테스트해 보십시오.

8. 클라이언트 액세스, 검색 및 페더레이션을 확인합니다.

서버 네트워크 외부의 컴퓨터에서 다음 검사를 실행하십시오. 예시 호스트 이름을 실제 호스트 이름으로 바꾸십시오.

curl -i https://example.com/.well-known/matrix/client
curl -i https://example.com/.well-known/matrix/server
curl -i https://matrix.example.com/_matrix/client/versions
curl -i https://matrix.example.com/health

처음 두 요청은 HTTP 200 응답 코드, JSON 콘텐츠 및 예상 값을 반환해야 합니다. 클라이언트 문서에는 CORS 헤더가 포함되어야 합니다. 클라이언트 버전 엔드포인트는 Cloudflare를 통해 Synapse에서 제공하는 JSON 데이터를 반환해야 합니다. Synapse 상태 엔드포인트는 구성된 리스너를 통해 접속할 경우 HTTP 200 응답 코드를 반환하지만, 로그인 또는 페더레이션 상태 확인을 대체할 수는 없습니다.

그런 다음 ID가 로 끝나는 Matrix 클라이언트로 로그인하고 :example.com, 다른 곳에서 호스팅되는 방에 참여한 후 메시지와 멤버십 업데이트가 동기화되는지 확인하십시오. Matrix 페더레이션 테스터 또는 두 번째 홈서버를 사용하여 서버 검색 및 페더레이션을 검증하십시오. 에 대한 요청이 성공하면 /_matrix/client/versions클라이언트 측 경로가 작동한다는 것만 입증될 뿐, 페더레이션 검색, 서명 또는 외부 페더레이션이 올바르게 작동한다는 것을 입증하는 것은 아닙니다.

성공의 모습은 무엇이며, 언제 설계를 바꿔야 할까요?

• 클라이언트는 Cloudflare를 통해 연결합니다. DNS는 Cloudflare 주소로 확인되고, HTTPS는 의도된 인증서를 사용하며, Matrix 클라이언트 API는 응답을 반환합니다.
• 검색 결과가 정확합니다. 잘 알려진 두 URL 모두 올바른 JSON을 반환하며 클라이언트 문서는 교차 출처 검사를 통과합니다.
• 페더레이션이 정상적으로 작동하는 경우, 원격 서버가 사용자가 알린 엔드포인트를 검색하고 회의실 상태를 교환할 수 있습니다. 443 포트 위임이 실패하지만 8448 포트 직접 연결은 성공하는 경우, 잘 알려진 레코드, 프록시 경로 라우팅 및 WAF 규칙을 점검하십시오.
• 업로드는 예상 크기로 작동합니다. 대표적인 업로드 파일을 테스트해 보세요. 작은 파일은 성공하지만 큰 파일 업로드 시 413 오류가 발생하는 경우, Synapse 설정만 변경하지 말고 네 가지 크기 제한을 모두 비교해 보세요.
• 해당 출발지는 대체 공용 경로가 아닙니다. 출발지에 대한 직접 요청은 설계된 대로 차단되거나 제한되어야 합니다. 그럼에도 불구하고 Matrix 서비스에 도달하는 경우 방화벽 및 신뢰 프록시 구성을 수정하십시오.

요구 사항이나 구현상의 제약으로 443번 포트를 통한 페더레이션 라우팅이 불가능한 경우, 8448번 포트에서 DNS 전용 페더레이션을 사용할 수 있습니다. 단, 이 경우 원본 주소가 노출되고 해당 호스트 이름에 대한 Cloudflare의 HTTP 프록시 보호 기능이 제거된다는 점을 유의하십시오. Spectrum은 비표준 포트를 사용하는 또 다른 옵션이지만, 제품 가용성 및 요금제 제약 조건에 따라 이용이 제한될 수 있습니다. Cloudflare 프록싱을 사용하면 원본 서버와의 두 번째 TLS 연결이 이루어지기 전에 Cloudflare에서 TLS 연결이 종료됩니다. Matrix 종단 간 암호화는 암호화된 메시지 콘텐츠를 보호하지만, 연결 메타데이터나 종단 간 암호화되지 않은 콘텐츠는 HTTP 요청을 처리하는 서비스에서 숨길 수 없습니다. 개인 정보 보호, 페더레이션 및 가용성 요구 사항에 따라 토폴로지를 선택한 후, DNS, 인증서, Synapse 또는 Cloudflare 규칙을 변경한 후 다시 테스트하십시오.