如何設定音訊和視訊通話的 Matrix Coturn TURN/STUN 伺服器

目前 Matrix 呼叫變更會影響發現機制，但不會影響 Coturn 的 TURN 憑證或連接埠。 Matrix.org 在 2026 年 8 月 21 日的更新中報告稱，Element Call 0.24 已棄用透過 homeserver/.well-known/matrix/client檔案發現 MatrixRTC 傳輸的方式。獨立部署的 Element Call 應支援 MatrixRTC 傳輸端點；Element Web/Desktop 和 Element X 在用戶端過渡期間保留了舊的發現方法作為備用方案。這與傳統的 TURN 設定無關。

本指南配置 Coturn 以支援 Synapse 的 TURN 服務，該服務為使用傳統 WebRTC 通話的用戶端提供臨時 ICE 憑證。目前的 Element Call 和 MatrixRTC 群組呼叫使用 LiveKit 選擇性轉送單元 (SFU) 和 MatrixRTC 授權服務。 Coturn 本身並不能取代這些組件。如果您的目標是自架 Element Call，請使用官方 Element Call 指南中所述的 LiveKit 路徑；僅當您選擇的媒體架構需要單獨的 TURN 服務時才新增 Coturn。

首先選擇正確的呼叫路徑。

呼叫路徑	需要配置什麼	本Coturn指南適用範圍
傳統或舊式 WebRTC 通話	Coturn 加上 Synapse`turn_uris`和一個共同的秘密	當用戶端從 Synapse 的端點要求 TURN 憑證時，請使用下列設定`/voip/turnServer`。
MatrixRTC / 元素調用	LiveKit SFU、MatrixRTC 授權服務和 homeserver 傳輸發現	Coturn 並非 LiveKit 的替代品。 LiveKit 內建可選的 TURN 服務；請遵循其自身的網路和 TURN 配置。

對於 Synapse 上的 MatrixRTC，目前的 Element Call 自架指南使用matrix_rtc.transports並啟用了 homeserver 傳輸註冊表，這可以透過文件中記錄的實驗性功能標誌來實現。 Matrix.org 2026 年的通知指出，此發現變更對獨立 Element Call 部署最為重要；其他管理員可以準備端點，而受支援的用戶端則保留了備用方案。請查看指南，了解您實際執行的客戶端和 Synapse 版本。

Coturn 的功能

STUN 允許 WebRTC 用戶端發現它可以通告的公有網路位址。 TURN 在兩個客戶端無法透過路由器或防火牆建立直接連線時進行媒體中繼。 Coturn 同時實現了這兩種服務。如果沒有可達的中繼，當參與者位於受限網路或不相關的網路中時，通話可能會響鈴但一直處於「正在連線」狀態。

TURN 伺服器需要一個公用 IP 位址，或一個具有公用 IP 位址和正確轉送規則的 NAT 閘道。僅供私有網路使用的伺服器無法充當遠端 Matrix 使用者的網際網路中繼。對於小型 Synapse 部署，您可以將 Coturn 安裝在主伺服器上，或使用單獨的公網主機。單獨的主機可以提供更清晰的防火牆邊界和獨立的擴充能力；在同一台主機上安裝雖然更簡單，但需要精心配置防火牆規則，以防止中繼暴露私有服務。

1. 安裝 Coturn 並準備共用金鑰

在 Debian 或 Ubuntu 系統上，安裝發行版軟體套件：

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-secret啟用 Synapse 使用的限時 TURN 憑證機制。請勿配置匿名存取或暴露開放式中繼。以上配額值僅供參考，參考 Synapse 的 Coturn 指南；請依照預期使用者數量和容量進行調整。此設定no-tcp-relay可防止客戶端請求中繼連線到任意 TCP 目標；但這並不表示您必須停用 TCP 作為客戶端到 TURN 的傳輸方式。

TURN 可能被濫用，用作連接內部或敏感網路位址的中繼。請套用目前 Synapse Coturn 安全性範例中完整的拒絕對等位址範圍，包括與您的 IPv4 和 IPv6 網路相關的範圍。如果使用者確實需要存取私人網路對等方，請在複製規則之前仔細審查。此外，請確保 Coturn 已安裝所有補丁，並監控其日誌和配額。

當 Coturn 位於 NAT 之後時，請設定公網位址。

如果 TURN 主機位於路由器之後，請將其公共位址新增至設定中，以便 Coturn 可以通告可達的中繼位址：

external-ip=YOUR_PUBLIC_IPV4
listening-ip=YOUR_PRIVATE_IPV4

將範例值替換為實際位址；如果 Coturn 已綁定到正確的接口，則監聽位址為可選。將路由器上的 TURN 監聽器和中繼範圍轉送到此伺服器。外部位址不符是導致相同區域網路內呼叫成功但不同網路間呼叫失敗的常見原因。

3. 開啟監聽埠和中繼埠

在主機防火牆和任何雲端防火牆或路由器中允許與您的 Coturn 設定相符的連接埠：

TCP 和 UDP 3478 用於常規 TURN 監聽器。
預設中繼埠範圍為 UDP 49152–65535（如上所示）。如果選擇較小的連接埠範圍，請在 Coturn 和防火牆中配置相同的連接埠範圍。
TCP 5349 用於透過 TLS 進行 TURN 通信，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 管理控制介面發佈到 Internet。

4. 配置 Synapse 以頒發 Coturn 憑證

通常情況下，請將下列 TURN 設定新增至目前 Synapse 設定中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>` 的 URI turns:turn.example.org:5349?transport=tcp。除非證書、監聽器、防火牆和用戶端相容性都已就緒，否則請勿發布turns:URI。 Coturn 的 TLS 憑證和私鑰在其組態中分別透過 `<configuration>`cert和 ` <configuration>` 設定pkey。

請根據您的房間和訪客政策進行設置turn_allow_guests。啟用此功能後，未經身份驗證的訪客用戶即可要求 TURN 憑證，這對於訪客通話可能必不可少，但會增加濫用風險。停用此功能可能會導致訪客通話不穩定。無論啟用或停用，都建議使用監控和配額機制。

修改檔案後，請重新啟動 Coturn 和 Synapse：

sudo systemctl restart coturn
sudo systemctl restart matrix-synapse

如果 Synapse systemd 單元名稱與此處不同，請使用實際名稱。重新載入或重新啟動受影響的用戶端；Synapse 的 TURN 設定會定期刷新，因此用戶端可能不會立即看到變更。

是否應該啟用 TURN over TLS？

首先在 3478 連接埠啟用 UDP/TCP TURN 協議，並確認中繼候選連接埠是否正常運作。僅當使用者網路需要時才啟用基於 TLS 的 TURN 協議，例如企業防火牆允許類似 TLS 的流量但阻止普通 UDP 流量。 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) 以及您配置的 TURN URI。請勿公開分享此回應；這些憑證是您中繼伺服器的臨時存取權杖。

使用官方的 WebRTC Trickle ICE 範例，並輸入 Synapse 傳回的使用者名稱和密碼進行測試。新增您的 TURN URI 和憑證，執行 ICE 收集測試，並尋找類型為「伺服器反射」的候選relay伺服器。僅回應 STUN 的伺服器可能會顯示伺服器反射候選伺服器，但仍無法轉送媒體。使用行動網路連線或區域網路以外的網路進行測試，然後在不同網路上的參與者之間發起實際通話。

診斷常見故障

未顯示 TURN 憑證：請檢查 Synapse 是否已載入正確的設定、是否已成功重新啟動以及是否已設定共用金鑰。檢查請求回應/voip/turnServer。
憑證已顯示，但沒有中繼候選表單：驗證 TCP/UDP 3478、已通告的主機名稱、金鑰匹配、Coturn 日誌以及通過每個防火牆的 UDP 中繼範圍。
在同一區域網路內通話正常，但跨網路通話失敗：需要檢查external-ip連接埠轉送和返迴路由。 Coturn 必須發佈用戶端可以存取的公共位址。
只有在停用 TLS 時，呼叫才會連線：確認憑證鏈、TLS 監聽器、通告的turns:URI 和用戶端特定的相容性。
傳統通話功能正常，但 Element Call 功能無法使用：請單獨檢查 MatrixRTC/LiveKit 傳輸設定。 Coturn 測試成功並不能驗證 LiveKit SFU 或 MatrixRTC 授權服務。