Matrix Coturn TURN/STUN 서버를 설정하여 음성 및 영상 통화를 가능하게 하는 방법

최근 Matrix의 호출 방식 변경으로 인해 검색에는 영향을 미치지만 Coturn의 TURN 자격 증명이나 포트에는 영향을 미치지 않습니다. Matrix.org는 2026년 8월 21일 업데이트에서 Element Call 0.24 버전부터 홈서버 /.well-known/matrix/client파일을 통한 MatrixRTC 전송 검색 기능이 더 이상 사용되지 않는다고 발표했습니다. 독립형 Element Call 배포 환경에서는 MatrixRTC 전송 엔드포인트를 지원해야 하지만, Element Web/Desktop 및 Element X는 클라이언트 전환이 진행되는 동안 기존 검색 방식을 대체 수단으로 유지하고 있습니다. 이는 기존 TURN 설정과는 별개입니다.

이 가이드는 기존 WebRTC 통화를 사용하는 클라이언트에 임시 ICE 자격 증명을 제공하는 Synapse의 TURN 서비스를 위해 Coturn을 구성하는 방법을 설명합니다. 현재 Element Call 및 MatrixRTC 그룹 통화는 LiveKit 선택적 전달 장치(SFU)와 MatrixRTC 인증 서비스를 사용합니다. Coturn만으로는 이러한 구성 요소를 대체할 수 없습니다. 자체 호스팅 Element Call을 구축하려는 경우 공식 Element Call 가이드에 설명된 LiveKit 방식을 사용하십시오. 선택한 미디어 아키텍처에 별도의 TURN 서비스가 필요한 경우에만 Coturn을 추가하십시오.

먼저 올바른 통화 경로를 선택하세요.

Synapse에서 MatrixRTC를 사용하는 경우, 현재 Element Call 자체 호스팅 가이드에서는 matrix_rtc.transports문서화된 실험적 기능 플래그를 통해 홈서버 전송 레지스트리를 사용하고 활성화합니다. Matrix.org 2026 공지에 따르면 이 검색 변경 사항은 독립형 Element Call 배포에 가장 중요하며, 다른 관리자는 지원되는 클라이언트를 위한 대체 기능을 유지하면서 엔드포인트를 준비할 수 있습니다. 실제로 사용 중인 클라이언트 및 Synapse 릴리스에 대한 가이드를 확인하십시오.

코턴이 하는 일

STUN은 WebRTC 클라이언트가 공개적으로 알릴 수 있는 네트워크 주소를 검색할 수 있도록 합니다. TURN은 두 클라이언트가 라우터나 방화벽을 통해 직접 연결을 설정할 수 없을 때 미디어를 중계합니다. Coturn은 이 두 가지 서비스를 모두 구현합니다. 연결 가능한 중계기가 없으면 통화 참여자가 제한적인 네트워크 또는 서로 관련 없는 네트워크에 있는 경우 통화는 연결되지만 "연결 중" 상태로 유지될 수 있습니다.

TURN 서버는 공용 IP 주소 또는 공용 IP 주소와 올바른 포워딩 규칙이 설정된 NAT 게이트웨이가 필요합니다. 개인 전용 서버는 원격 Matrix 사용자를 위한 인터넷 릴레이 역할을 할 수 없습니다. 소규모 Synapse 구축의 경우 홈 서버에 Coturn을 설치하거나 별도의 공용 호스트를 사용할 수 있습니다. 별도의 호스트를 사용하면 방화벽 경계를 명확히 하고 독립적인 확장이 가능합니다. 동일 호스트에 설치하는 것은 더 간단하지만, 릴레이 서버가 개인 서비스를 노출하지 않도록 방화벽 규칙을 신중하게 설정해야 합니다.

1. Coturn을 설치하고 공유 비밀 키를 준비합니다.

데비안 또는 우분투에서 배포 패키지를 설치하세요.

sudo apt update
sudo apt install coturn

이 패키지는 systemd 서비스를 제공하며, 주요 설정 파일은 일반적으로 입니다 /etc/turnserver.conf. 다른 배포판에서는 자체적인 패키지 이름, 서비스 관리 방식 및 설정 경로를 사용합니다.

강력하고 안전한 비밀 키를 생성하세요. 예를 들면 다음과 같습니다.

openssl rand -hex 32

Coturn과 Synapse에서 동일한 비밀 키를 사용하세요. 비밀번호처럼 취급해야 합니다. 문서에 있는 예시 값을 재사용하거나, 공개 저장소에 커밋하거나, 공개 버그 보고서에 포함하지 마세요. Synapse 버전에서 지원하는 경우 turn_shared_secret_path, YAML 파일에 직접 입력하는 대신 보호된 파일에 비밀 키를 저장할 수 있습니다. Synapse는 버전 1.116.0부터 이 설정을 추가했습니다. 사용하기 전에 배포된 버전을 확인하세요.

2. 인증된 릴레이를 위해 Coturn을 구성합니다.

서비스 이름과 공유 비밀 키 인증을 편집 /etc/turnserver.conf하고 설정합니다. 도메인 및 비밀 키 자리 표시자를 교체하십시오.

listening-port=3478
tls-listening-port=5349

fingerprint
use-auth-secret
static-auth-secret=REPLACE_WITH_THE_SAME_RANDOM_SECRET
realm=turn.example.org

min-port=49152
max-port=65535

no-tcp-relay
no-multicast-peers
user-quota=12
total-quota=1200

syslog

use-auth-secretSynapse에서 사용하는 시간 제한 TURN 자격 증명 메커니즘을 활성화합니다. 익명 액세스를 구성하거나 오픈 릴레이를 노출하지 마십시오. 위의 할당량 값은 Synapse의 Coturn 지침을 기반으로 한 시작점이며, 예상 사용자 수 및 용량에 맞게 조정하십시오. no-tcp-relay클라이언트가 릴레이에 임의의 TCP 대상에 연결을 요청하는 것을 방지합니다. 이는 클라이언트-TURN 전송에서 TCP를 비활성화해야 한다는 의미가 아닙니다.

TURN은 내부 또는 민감한 네트워크 주소로 향하는 중계 경로로 악용될 수 있습니다. 현재 Synapse Coturn 보안 예제에 있는 차단 피어 주소 범위를 IPv4 및 IPv6 네트워크에 관련된 범위를 포함하여 모두 적용하십시오. 사용자가 사설 네트워크 피어에 접근해야 하는 경우, 규칙을 복사하기 전에 검토하십시오. 또한 Coturn의 패치를 최신 상태로 유지하고 로그 및 할당량을 모니터링하십시오.

Coturn이 NAT 뒤에 있을 때 공용 주소를 설정하세요.

TURN 호스트가 라우터 뒤에 있는 경우, Coturn이 도달 가능한 릴레이 주소를 광고하도록 라우터의 공용 주소를 구성에 추가하십시오.

external-ip=YOUR_PUBLIC_IPV4
listening-ip=YOUR_PRIVATE_IPV4

샘플 값을 실제 주소로 교체하십시오. Coturn이 이미 올바른 인터페이스에 바인딩된 경우 수신 주소는 선택 사항입니다. 라우터에서 이 서버로 TURN 수신자와 릴레이 범위를 전달하십시오. 외부 주소가 일치하지 않으면 동일한 LAN에서는 통화가 되지만 다른 네트워크 간에는 통화가 실패하는 경우가 많습니다.

3. 리스너 및 릴레이 포트를 엽니다.

호스트 방화벽과 클라우드 방화벽 또는 라우터 모두에서 Coturn 구성과 일치하는 포트를 허용하십시오.

• 일반적인 TURN 리스너는 TCP 및 UDP 3478 포트를 사용합니다.
• 위에서 표시된 기본 릴레이 범위는 UDP 49152~65535입니다. 더 작은 범위를 선택하는 경우 Coturn과 방화벽 모두에서 동일한 범위를 구성해야 합니다.
• TCP 5349 포트는 TLS를 통한 데이터 전송에 사용되며, UDP 5349 포트는 DTLS를 활성화하고 제공하려는 경우에만 사용됩니다.

UFW의 경우 기본적인 UDP/TCP 리스너 및 UDP 릴레이 규칙 세트는 다음과 같습니다.

sudo ufw allow 3478/tcp
sudo ufw allow 3478/udp
sudo ufw allow 49152:65535/udp

해당 TLS 또는 DTLS 리스너가 구성되고 광고되는 경우에만 5349 규칙을 추가하십시오. 공급자의 보안 그룹도 확인하십시오. 호스트 수준의 UFW 규칙은 차단된 클라우드 인그레스 규칙을 재정의할 수 없습니다. Coturn 관리 제어 인터페이스를 인터넷에 공개하지 마십시오.

4. Synapse에서 Coturn 자격 증명을 발급하도록 구성합니다.

활성 Synapse 구성(일반적으로 )에 다음 TURN 설정을 추가하십시오 homeserver.yaml. 호스트 이름은 TURN 호스트로 공개적으로 확인되어야 합니다.

turn_uris:
  - "turn:turn.example.org:3478?transport=udp"
  - "turn:turn.example.org:3478?transport=tcp"
turn_shared_secret: "REPLACE_WITH_THE_SAME_RANDOM_SECRET"
turn_user_lifetime: 1h
turn_allow_guests: true

처음 두 개의 URI는 3478번 포트에서 일반 TURN 전송을 알립니다. TLS가 구성 및 테스트된 경우 와 같은 URI도 알릴 수 있습니다 turns:turn.example.org:5349?transport=tcp. 인증서, 리스너, 방화벽 및 클라이언트 호환성이 모두 갖춰지지 않은 경우에는 URI를 알릴 수 없습니다 . Coturn의 TLS 인증서와 개인 키는 구성 파일의 와 를 turns:사용하여 설정됩니다 .certpkey

객실 및 투숙객 정책에 따라 설정하십시오 turn_allow_guests. 이 기능을 활성화하면 인증되지 않은 투숙객이 TURN 자격 증명을 요청할 수 있는데, 이는 투숙객 통화에 필요할 수 있지만 악용 위험이 증가할 수 있습니다. 반대로 비활성화하면 투숙객의 통화가 불안정해질 수 있습니다. 어떤 경우든 모니터링 및 할당량 설정을 활용하십시오.

파일 변경 후 Coturn과 Synapse를 다시 시작하십시오.

sudo systemctl restart coturn
sudo systemctl restart matrix-synapse

실제 Synapse systemd 유닛 이름이 다른 경우 해당 이름을 사용하십시오. 영향을 받는 클라이언트를 다시 로드하거나 재시작하십시오. Synapse의 TURN 설정은 주기적으로 새로 고쳐지므로 클라이언트에서 변경 사항이 즉시 표시되지 않을 수 있습니다.

TLS를 통해 TURN을 활성화해야 할까요?

먼저 UDP/TCP TURN 설정을 3478 포트에서 활성화하고 릴레이 후보가 제대로 작동하는지 확인하십시오. 사용자 네트워크에 필요한 경우에만 TLS TURN 설정을 추가하십시오. 예를 들어, 일반 UDP 트래픽은 차단하지만 TLS와 유사한 트래픽은 허용하는 기업 방화벽이 있는 경우에 필요합니다. TLS는 연결성을 확장하지만, 인증서 갱신, 추가 리스너, 클라이언트 호환성 검사 등의 추가 절차가 필요합니다.

Matrix 관련 주의사항이 있습니다. 현재 Synapse Coturn 가이드에서는 Let's Encrypt 인증서를 사용한 TLS/DTLS가 Chromium의 WebRTC 라이브러리를 사용하는 Matrix 클라이언트(Element Android 및 iOS 포함)에서 작동하지 않는다고 경고하고 있습니다. TLS URI를 게시하기 전에 클라이언트 버전의 호환성을 확인하십시오. 또한 해당 가이드에서는 기본 서비스를 먼저 설정한 후 TLS/DTLS를 추가하는 것을 권장합니다.

5. 자격 증명을 확인하고 외부 네트워크에서 테스트합니다.

먼저 Coturn이 실행 중인지 확인하고 로그를 검토하십시오.

sudo systemctl status coturn
sudo journalctl -u coturn -f

인증된 Matrix 클라이언트 세션에서 Synapse의 현재 클라이언트-서버 API 엔드포인트에 대한 요청을 확인하십시오 /_matrix/client/v3/voip/turnServer. 성공적인 응답에는 사용자 이름, 비밀번호, TTL(Time-to-Live) 및 구성한 TURN URI가 포함되어야 합니다. 해당 응답을 공개적으로 공유하지 마십시오. 자격 증명은 릴레이를 위한 임시 액세스 토큰입니다.

Synapse에서 반환된 사용자 이름과 비밀번호를 사용하여 공식 WebRTC Trickle ICE 샘플을 테스트해 보세요. TURN URI와 자격 증명을 추가하고 ICE 수집 테스트를 실행한 다음, 유형이 인 후보를 찾으세요 relay. STUN에만 응답하는 서버는 서버 반사형 후보를 표시할 수 있지만 미디어 릴레이에는 실패할 수 있습니다. 모바일 연결이나 LAN 외부 네트워크에서 테스트한 다음, 서로 다른 네트워크에 있는 참가자 간에 실제 통화를 진행하세요.

흔히 발생하는 고장을 진단하세요

• TURN 자격 증명이 표시되지 않습니다. Synapse가 올바른 구성을 로드했는지, 성공적으로 다시 시작되었는지, 공유 암호가 설정되었는지 확인하십시오. 요청 응답을 검사하십시오 /voip/turnServer.
• 자격 증명은 표시되지만 릴레이 후보가 생성되지 않습니다. TCP/UDP 3478 포트, 광고된 호스트 이름, 비밀 키 일치 여부, Coturn 로그 및 모든 방화벽을 통한 UDP 릴레이 범위를 확인하십시오.
• 하나의 LAN 내에서는 통화가 작동하지만 다른 네트워크로 이동하면 실패합니다.external-ip 포트 포워딩 및 반환 경로를 확인하십시오 . Coturn은 클라이언트가 도달할 수 있는 공용 주소를 알려야 합니다.
• TLS가 비활성화된 경우에만 통화가 연결됩니다. 인증서 체인, TLS 리스너, 광고된 turns:URI 및 클라이언트별 호환성을 확인하십시오.
• 기존 통화는 작동하지만 Element Call은 작동하지 않습니다. MatrixRTC/LiveKit 전송 설정을 별도로 확인하십시오. Coturn 테스트가 성공했다고 해서 LiveKit SFU 또는 MatrixRTC 인증 서비스가 검증되는 것은 아닙니다.

브라우저 클라이언트의 경우, 브라우저의 WebRTC 진단 도구를 통해 미디어가 릴레이 후보를 선택했는지 확인할 수 있습니다. MatrixRTC의 경우, Synapse에서 전송 엔드포인트를 게시하고 LiveKit WebSocket 및 인증 경로에 접근할 수 있는지 확인하십시오. 현재 엔드포인트와 지원하는 클라이언트에 필요한 문서화된 검색 대체 기능을 모두 테스트하십시오.

구성 참조

• Synapse: TURN 서버 구성하기
• Synapse: Coturn 설치, 보안, NAT 및 TLS 구성
• TURN 및 MatrixRTC용 시냅스 구성 참조
• Coturn의 공식 turnserver.conf 예제
• Element Call: MatrixRTC 자체 호스팅 가이드
• LiveKit 배포 및 TURN 구성
• Matrix.org의 Element Call 0.24 전송 검색 업데이트
• Matrix 클라이언트-서버 API 사양(TURN 자격 증명 엔드포인트 포함)