Jak skonfigurować serwer Matrix Coturn TURN/STUN do połączeń audio i wideo

Obecna zmiana w wywołaniu Matrix wpływa na wykrywanie, ale nie na dane uwierzytelniające ani porty TURN Coturna. W aktualizacji z 21 sierpnia 2026 roku organizacja Matrix.org poinformowała, że ​​Element Call 0.24 wycofał wykrywanie transportów MatrixRTC poprzez /.well-known/matrix/clientplik serwera domowego. Samodzielne wdrożenia Element Call powinny obsługiwać punkt końcowy transportów MatrixRTC; Element Web/Desktop i Element X zachowały starą metodę wykrywania jako rozwiązanie awaryjne podczas migracji klientów. Jest to niezależne od klasycznej konfiguracji TURN.

Ten przewodnik konfiguruje Coturn dla usługi TURN firmy Synapse, która dostarcza klientom tymczasowe dane uwierzytelniające ICE za pomocą tradycyjnych wywołań WebRTC. Aktualne wywołania Element Call i grupowe MatrixRTC korzystają z jednostki LiveKit Selective Forwarding Unit (SFU) oraz usługi autoryzacji MatrixRTC. Sam Coturn nie zastępuje tych komponentów. Jeśli Twoim celem jest samodzielne hostowanie wywołania Element Call, skorzystaj ze ścieżki LiveKit opisanej w oficjalnym przewodniku Element Call; dodaj Coturn tylko wtedy, gdy wybrana architektura multimediów wymaga osobnej usługi TURN.

Najpierw wybierz właściwą ścieżkę wywołania

W przypadku MatrixRTC w Synapse, aktualny przewodnik po samodzielnym hostowaniu Element Call wykorzystuje matrix_rtc.transportsi włącza rejestr transportu serwera domowego za pośrednictwem udokumentowanej flagi funkcji eksperymentalnej. W komunikacie Matrix.org z 2026 roku podano, że ta zmiana w odnajdywaniu ma największe znaczenie w przypadku samodzielnych wdrożeń Element Call; inni administratorzy mogliby przygotować punkt końcowy, podczas gdy wspierani klienci zachowaliby wersję zapasową. Sprawdź przewodnik dotyczący klientów i wersji Synapse, z których faktycznie korzystasz.

Co robi Coturn

STUN pozwala klientowi WebRTC na odkrycie publicznego adresu sieciowego, który może rozgłosić. TURN przekazuje dane, gdy dwóch klientów nie może nawiązać bezpośredniego połączenia przez swoje routery lub zapory sieciowe. Coturn implementuje obie usługi. Bez dostępnego przekaźnika połączenie może dzwonić, ale pozostać w stanie „Łączenie”, gdy uczestnicy znajdują się w sieciach o ograniczonym dostępie lub w sieciach niezależnych.

Serwer TURN wymaga publicznego adresu IP lub bramy NAT z publicznym adresem IP i prawidłowymi regułami przekierowywania. Serwer prywatny nie może pełnić funkcji przekaźnika internetowego dla zdalnych użytkowników Matrix. W przypadku małej instalacji Synapse można zainstalować Coturn na serwerze domowym lub użyć oddzielnego hosta publicznego. Oddzielny host zapewnia wyraźniejsze granice zapory sieciowej i niezależne skalowanie; instalacja na tym samym hoście jest prostsza, ale wymaga starannych reguł zapory sieciowej, aby przekaźnik nie ujawniał usług prywatnych.

1. Zainstaluj Coturn i przygotuj współdzielony klucz tajny

W systemie Debian lub Ubuntu zainstaluj pakiet dystrybucyjny:

sudo apt update
sudo apt install coturn

Pakiet udostępnia usługę systemd, a główny plik konfiguracyjny to zazwyczaj /etc/turnserver.conf. Inne dystrybucje używają własnej nazwy pakietu, zarządzania usługami i ścieżki konfiguracji.

Wygeneruj silny, prywatny sekret. Na przykład:

openssl rand -hex 32

Użyj tego samego klucza tajnego w Coturn i Synapse. Traktuj go jak hasło: nie używaj przykładowej wartości z dokumentacji, nie zatwierdzaj jej w publicznym repozytorium ani nie dołączaj do publicznego zgłoszenia błędu. Jeśli Twoja wersja Synapse obsługuje turn_shared_secret_path, możesz zapisać klucz tajny w pliku chronionym, a nie w tekście w YAML. Synapse dodał to ustawienie w wersji 1.116.0; sprawdź wersję wdrożoną przed jego użyciem.

2. Skonfiguruj Coturn dla uwierzytelnionego przekaźnika

Edytuj /etc/turnserver.confi ustaw nazwę usługi oraz uwierzytelnianie za pomocą współdzielonego klucza tajnego. Zastąp symbole zastępcze domeny i klucza tajnego:

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-secretWłącza ograniczony czasowo mechanizm uwierzytelniania TURN, z którego korzysta Synapse. Nie konfiguruj dostępu anonimowego ani nie udostępniaj otwartego przekaźnika. Powyższe wartości limitów stanowią punkt wyjścia zaczerpnięty z wytycznych Coturn firmy Synapse; dostosuj je do oczekiwanej liczby użytkowników i przepustowości. no-tcp-relayZapobiega to żądaniu przez klientów połączenia z przekaźnikiem z dowolnymi docelowymi adresami TCP; nie oznacza to, że należy wyłączyć protokół TCP jako transport klient-TURN.

Protokół TURN może być wykorzystywany jako przekaźnik do wewnętrznych lub wrażliwych adresów sieciowych. Zastosuj kompletne zakresy adresów peer-to-peer w bieżącym przykładzie zabezpieczeń Synapse Coturn, w tym zakresy istotne dla sieci IPv4 i IPv6. Przejrzyj reguły przed ich skopiowaniem, jeśli użytkownicy mają uzasadnioną potrzebę dostępu do peerów w sieci prywatnej. Dbaj również o poprawność działania Coturn oraz monitoruj jego logi i limity.

Ustaw adres publiczny, gdy Coturn znajduje się za NAT-em

Jeżeli host TURN znajduje się za routerem, dodaj jego adres publiczny do konfiguracji, aby Coturn reklamował osiągalny adres przekaźnikowy:

external-ip=YOUR_PUBLIC_IPV4
listening-ip=YOUR_PRIVATE_IPV4

Zastąp przykładowe wartości rzeczywistymi adresami; adres nasłuchu jest opcjonalny, jeśli Coturn jest już powiązany z właściwym interfejsem. Przekieruj nasłuch TURN i zakres przekaźników z routera do tego serwera. Niezgodność adresu zewnętrznego jest częstą przyczyną połączeń, które działają w tej samej sieci LAN, ale kończą się niepowodzeniem między różnymi sieciami.

3. Otwórz porty nasłuchujące i przekaźnikowe

Zezwól na porty, które odpowiadają Twojej konfiguracji Coturn zarówno w zaporze hosta, jak i w dowolnej zaporze chmurowej lub routerze:

• TCP i UDP 3478 dla standardowego odbiornika TURN.
• UDP 49152–65535 dla domyślnego zakresu przekaźników pokazanego powyżej. Jeśli wybierzesz mniejszy zakres, skonfiguruj ten sam zakres w Coturn i zaporze.
• TCP 5349 dla protokołu TURN przez TLS i UDP 5349 tylko wtedy, gdy włączysz i zamierzasz oferować protokół DTLS.

W przypadku UFW podstawowy zestaw reguł nasłuchiwania UDP/TCP i przekazywania UDP może wyglądać następująco:

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

Dodaj reguły 5349 tylko wtedy, gdy odpowiedni odbiornik TLS lub DTLS jest skonfigurowany i rozgłaszany. Sprawdź również grupę zabezpieczeń swojego dostawcy; reguła UFW na poziomie hosta nie może zastąpić reguły zablokowanego ruchu przychodzącego do chmury. Nie publikuj interfejsu kontroli administracyjnej Coturn w internecie.

4. Skonfiguruj Synapse do wydawania poświadczeń Coturn

Dodaj następujące ustawienia TURN do aktywnej konfiguracji Synapse, zazwyczaj homeserver.yaml: Nazwa hosta musi być publicznie rozpoznawana jako host 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

Pierwsze dwa identyfikatory URI reklamują zwykłe transporty TURN na porcie 3478. Jeśli protokół TLS jest skonfigurowany i przetestowany, można również reklamować identyfikator URI, taki jak turns:turn.example.org:5349?transport=tcp. Nie reklamuj identyfikatora turns:URI, dopóki certyfikat, nasłuchiwacz, zapora sieciowa i klient nie są zgodne. Certyfikat TLS i klucz prywatny Coturn są ustawione w konfiguracji za pomocą opcji certi .pkey

Ustaw turn_allow_guestszgodnie z zasadami obowiązującymi w Twoim pokoju i dla gości. Włączenie tej opcji może umożliwić niezweryfikowanym gościom żądanie danych uwierzytelniających TURN, co może być niezbędne do połączeń z gośćmi, ale może zwiększyć ryzyko nadużyć. Wyłączenie tej opcji może sprawić, że połączenia będą niestabilne dla gości. Korzystaj z monitorowania i limitów w obu przypadkach.

Uruchom ponownie Coturn i Synapse po zmianie ich plików:

sudo systemctl restart coturn
sudo systemctl restart matrix-synapse

Użyj rzeczywistej nazwy jednostki systemd Synapse, jeśli jest inna. Przeładuj lub uruchom ponownie klientów, których dotyczy problem; ustawienia TURN Synapse są odświeżane okresowo, więc klient może nie zauważyć zmiany od razu.

Czy warto włączyć protokół TURN zamiast protokołu TLS?

Zacznij od TURN UDP/TCP na 3478 i sprawdź, czy kandydat na przekaźnik działa. Dodaj TURN przez TLS tylko wtedy, gdy sieci Twoich użytkowników tego wymagają, na przykład zapory korporacyjne, które zezwalają na ruch podobny do TLS, ale blokują zwykły UDP. TLS rozszerza łączność, ale dodaje odnawianie certyfikatów, kolejnego nasłuchiwacza i sprawdzanie zgodności klienta.

Istnieje pewne zastrzeżenie specyficzne dla Matrix: aktualny przewodnik Synapse Coturn ostrzega, że ​​TLS/DTLS z certyfikatami Let's Encrypt nie działa z klientami Matrix korzystającymi z biblioteki WebRTC Chromium, w tym Element Android i iOS, jak wspomniano w tym przewodniku. Przed opublikowaniem identyfikatora URI TLS należy sprawdzić kompatybilność wersji klienta. Ten sam przewodnik zaleca najpierw skonfigurowanie usługi podstawowej, a następnie dodanie TLS/DTLS.

5. Zweryfikuj dane uwierzytelniające i przetestuj z sieci zewnętrznej

Najpierw sprawdź, czy Coturn działa i przejrzyj jego logi:

sudo systemctl status coturn
sudo journalctl -u coturn -f

Następnie, z uwierzytelnionej sesji klienta Matrix, sprawdź żądanie do bieżącego punktu końcowego API klient-serwer Synapse /_matrix/client/v3/voip/turnServer. Pomyślna odpowiedź powinna zawierać nazwę użytkownika, hasło, czas życia (TTL) oraz skonfigurowane identyfikatory URI TURN. Nie udostępniaj tej odpowiedzi publicznie; dane uwierzytelniające to tymczasowe tokeny dostępu do Twojego przekaźnika.

Użyj oficjalnej próbki WebRTC Trickle ICE do przetestowania z nazwą użytkownika i hasłem zwróconymi przez Synapse. Dodaj swój URI i dane uwierzytelniające TURN, uruchom test zbierania danych ICE i poszukaj kandydata o typie relay. Serwer, który odpowiada jedynie na STUN, może wyświetlić kandydata zwrotnego względem serwera, ale nadal nie będzie mógł przekazać danych. Przetestuj z połączenia mobilnego lub sieci spoza sieci LAN, a następnie nawiąż połączenie między uczestnikami w różnych sieciach.

Diagnozuj typowe awarie

• Brak danych uwierzytelniających TURN: sprawdź, czy Synapse załadował prawidłową konfigurację, pomyślnie uruchomił się ponownie i ma ustawiony wspólny klucz tajny. Sprawdź odpowiedź na żądanie pod kątem /voip/turnServer.
• Pojawiają się dane uwierzytelniające, ale nie pojawiają się żadne formularze kandydatów na przekaźniki: sprawdź protokół TCP/UDP 3478, reklamowaną nazwę hosta, dopasowanie klucza tajnego, dzienniki Coturn i zakres przekaźników UDP przez każdą zaporę.
• Połączenia działają w jednej sieci LAN, ale nie działają w innych sieciach: inspekcja external-ip, przekierowanie portów i trasa powrotna. Coturn musi ogłosić adres publiczny, do którego klienci mogą dotrzeć.
• Połączenia są nawiązywane tylko wtedy, gdy protokół TLS jest wyłączony: należy potwierdzić łańcuch certyfikatów, nasłuchiwacz protokołu TLS, reklamowany turns:identyfikator URI i zgodność specyficzną dla klienta.
• Tradycyjne wywołania działają, ale Element Call nie: sprawdź osobno konfigurację transportu MatrixRTC/LiveKit. Pomyślny test Coturn nie weryfikuje usługi autoryzacji LiveKit SFU ani MatrixRTC.

W przypadku klientów przeglądarek diagnostyka WebRTC przeglądarki może pokazać, czy media wybrały kandydata na przekaźnik. W przypadku MatrixRTC sprawdź, czy Synapse publikuje punkt końcowy transportu oraz czy LiveKit WebSocket i trasy autoryzacji są osiągalne. Przetestuj zarówno bieżący punkt końcowy, jak i wszelkie udokumentowane procedury awaryjne wykrywania wymagane przez obsługiwane przez Ciebie klientów.

Odniesienia do konfiguracji

• Synapse: Konfigurowanie serwera TURN
• Synapse: instalacja, zabezpieczenia, NAT i konfiguracja TLS Coturn
• Odniesienie do konfiguracji Synapse dla TURN i MatrixRTC
• Oficjalny przykład turnserver.conf Coturna
• Element Call: przewodnik po samodzielnym hostingu MatrixRTC
• Wdrożenie LiveKit i konfiguracja TURN
• Aktualizacja Matrix.org dotycząca wykrywania transportu w Element Call 0.24
• Specyfikacja interfejsu API klienta-serwera Matrix, obejmująca punkt końcowy poświadczeń TURN