修復 BigBlueButton FreeSWITCH SIP 註冊逾時問題：實用診斷指南

BigBlueButton 會議可以正常加載，但與會者在加入音訊時卻卡住不動。管理員可能會在日誌或監控工具中看到「SIP 註冊逾時」、「FreeSWITCH 未註冊」或音訊連線錯誤等資訊。這些錯誤訊息並不總是指向同一個故障。在標準的 BigBlueButton 部署中，音訊連線失敗可能是由於 FreeSWITCH 進程停止、SIP 或事件套接字連線被阻止、NAT 後位址錯誤或 WebRTC 媒體被阻止等原因造成的。營運商或 PBX 閘道的實際註冊逾時則屬於另一種情況。

首先確定哪個組件逾時。然後依序檢查服務運作狀況、本機監聽器、網路路徑和位址。在確定受影響的路徑之前，請勿變更 SIP 設定或開啟連接埠。

首先，要先明確「註冊超時」指的是什麼。

BigBlueButton 目前的音訊協定堆疊使用該bbb-webrtc-sfu服務與 FreeSWITCH 協調媒體傳輸。 BigBlueButton 文件描述了 SFU 如何連接到 FreeSWITCH 的 SIP 服務和事件通訊端層 (ESL)。這與 FreeSWITCH 向外部 SIP 提供者註冊出站網關不同。

• BigBlueButton 音訊連線問題：使用者無法加入音頻，FreeSWITCH 無法存取，或 SFU 報告逾時。請檢查 FreeSWITCH、ESL、配置的 SIP 位址和連接埠、NAT 以及 WebRTC 傳輸。
• 外部網關註冊問題： FreeSWITCH 報告已設定的網關已關閉或未註冊。請檢查提供者的主機名稱、憑證、傳輸協定、防火牆路徑以及提供者端帳戶狀態。

如果您不確定具體情況，請儲存完整的錯誤文字以及記錄該錯誤訊息的服務名稱。 「註冊逾時」本身並不足以構成更改 SIP 設定檔的理由。

1. 運行 BigBlueButton 的設定檢查

在伺服器上，運行 BigBlueButton 推薦的診斷程序：

sudo bbb-conf --check

仔細查看所有輸出，尤其是標題為「檢查」的部分Potential problems。該部分會檢查所需進程是否正在運行，並報告常見的配置問題。警告訊息可能反映了有意進行的自訂設置，因此請將其與您的實際配置進行比較，而不是自動套用所有建議的修復方案。

然後檢查服務狀態：

sudo bbb-conf --status
sudo systemctl status freeswitch --no-pager
sudo systemctl status bbb-webrtc-sfu --no-pager

在較早的 BigBlueButton 版本中，服務名稱或元件架構可能有所不同。請sudo bbb-conf --version使用對應的文件確認您安裝的版本。以下路徑和範例主要參考 BigBlueButton 4.0 的文檔，目前處於開發階段。

2. 確認 FreeSWITCH 正在運作並接受本機連接

如果freeswitch.service該服務處於非活動狀態、運行失敗或重複重啟，請在編輯配置之前閱讀其日誌：

sudo journalctl -u freeswitch.service -b --no-pager -n 100

請檢查最近一次啟動前後是否有綁定失敗、模組載入錯誤、權限問題或資料庫錯誤。 BigBlueButton 的故障排除指南記錄了 FreeSWITCH 無法綁定到 IPv4 或 ESL 連接埠 8021 的具體情況。指南還指出，重新啟動後 FreeSWITCH 資料庫損壞可能是原因之一，但建議僅在出現相應的資料庫錯誤時才進行資料庫清理。

檢查哪些位址和連接埠正在監聽：

sudo ss -luntp | grep -E ':(5060|5066|8021)\b'

具體的 SIP 監聽器取決於您的 BigBlueButton 版本和配置。如果缺少監聽器，則表示 FreeSWITCH 未能啟動該設定檔或綁定到了其他位址。在典型的軟體包安裝中，連接埠 8021 是本機 ESL 控制介面；通常情況下，它應該僅限於本機或受信任的專用網路。請勿將其暴露在公共互聯網上。

如果 FreeSWITCH 處於活動狀態，您可以使用其 CLI 檢查 SIP 設定檔狀態。標準的 FreeSWITCH 命令是 `<profile_statement_statement>` sofia status；請使用伺服器顯示的設定檔名稱，而不是假設每個部署都使用相同的名稱。標記為 `<profile_statement_statement_statement>` 的設定檔RUNNING確認該設定檔已啟動，但並未證明遠端瀏覽器可以存取音訊媒體路徑。

3. 將錯誤與故障的網路路徑進行匹配

BigBlueButton 的防火牆指南區分了 WebSocket 訊號故障和 ICE/媒體故障。這種區分縮小了搜尋範圍：

• WebRTC 錯誤 1002：瀏覽器無法建立 WebSocket 連線。請檢查 FreeSWITCH 是否正在運作、SIP over WebSocket 路由和反向代理配置，以及任何影響該訊號路徑的防火牆規則。
• WebRTC 錯誤 1007： WebSocket 已連接，但瀏覽器無法使用傳回的位址候選值建立媒體連接。請檢查已聲明的 IP 位址以及雙向 UDP 可及性。

對於預設的 BigBlueButton 防火牆配置，官方指南列出了16384–32768即時媒體所需的 UDP 連接埠。請在雲端安全群組或邊界防火牆以及主機防火牆中都允許所需的連接埠範圍。請將規則限制在伺服器和所需的流量範圍內；廣泛開放無關的 SIP 連接埠並不能取代正確的 NAT 和 WebRTC 配置。

例如，如果您使用 UFW 並且已確認此範圍適合您的安裝，請檢查現有規則並新增媒體範圍：

sudo ufw status numbered
sudo ufw allow 16384:32768/udp

雲端防火牆和提供者安全群組也必須允許流量通過。主機級規則無法覆蓋上游防火牆的封鎖。如果只有受限網路上的使用者連線失敗而其他使用者連線正常，請檢查其網路路徑或 TURN 配置，而不是重複重新啟動 FreeSWITCH。

4. 檢查 NAT 和通告的 IP 位址

即使伺服器位於 NAT 之後，其本機監聽器配置正確，仍可能向瀏覽器通告一個無法存取的私人位址。請驗證外部 IP 位址、連接埠轉送和 FreeSWITCH 設定是否一致。 BigBlueButton 的 4.0 防火牆指南在其 NAT 範例中使用了 [此處應填寫/opt/freeswitch/conf/vars.xml範例/opt/freeswitch/conf/sip_profiles/external.xml名稱]，並指向 [/etc/bigbluebutton/bbb-webrtc-sfu/production.yml此處應填寫相關 SFU 覆蓋設定]。

請勿複製範例 IP 位址，也不要假設所有欄位都應填寫公網 IP 位址。在 NAT 設定中，FreeSWITCH 本地綁定的位址可能與其通告的公有網路位址不同。請根據您的網路拓撲套用特定版本的說明，然後檢查相關的防火牆轉送設定。如果伺服器的外部位址最近發生了更改，請驗證 DNS 以及 BigBlueButton 設定中維護的任何位址值。

當伺服器進程必須存取其自身的公網主機名稱時，回環NAT或本機主機名稱解析也可能發揮作用。官方防火牆指南討論了在/etc/hosts這種情況下如何將公網主機名稱對應到防火牆位址。僅當故障模式指向通過外部主機名稱的回環時才測試此方法；它並非解決註冊逾時問題的通用方案。

5. 如果日誌中提到了外部 SIP 網關

如果故障項是指定的運營商網關而非 BigBlueButton 的內部音訊路徑，請單獨檢查網關狀態。 FreeSWITCH 文件sofia status gateway <name>中提供了網關狀態和sofia status已載入設定檔及網關狀態的相關資訊。請驗證提供者主機名稱是否能從伺服器解析，配置的 SIP 使用者名稱和密碼是否匹配，所選傳輸方式和連接埠是否符合提供者的要求，以及出站防火牆規則是否允許訊號流量通過。

請勿重置 BigBlueButton 內建的 SIP 配置來修復運營商帳戶。避免公開分享完整的 SIP 追蹤日誌：其中可能包含電話號碼、IP 位址、帳戶名稱或身分驗證相關詳細資訊。在請求服務提供者或管理員查看日誌之前，請務必對敏感資訊進行編輯。

6. 應用目標變更並重新啟動一次

確認服務、地址或防火牆問題後，請使用 BigBlueButton 支援的命令重新啟動 BigBlueButton：

sudo bbb-conf --restart

僅當特定版本文件或診斷證據要求時才使用sudo bbb-conf --clean。它並非針對所有 SIP 逾時的通用回應。同樣，除非出現文件中記錄的資料庫損壞症狀，否則請勿刪除 FreeSWITCH 資料庫檔案；在進行任何會移除狀態的修復之前，請務必保留日誌和設定備份。

確認維修狀況

再次運作sudo bbb-conf --check並確認 FreeSWITCHbbb-webrtc-sfu運作正常。從伺服器網路以外的瀏覽器加入測試會議，選擇麥克風或僅收聽音頻，並確認連接成功。如果 NAT 或防火牆發生更改，請至少從先前連接失敗的網路進行測試。僅憑服務狀態顯示為綠色並不能證明 UDP 媒體可以順利通過網路。

如果逾時問題仍然存在，請收集 BigBlueButton 版本、完整錯誤文字、相關bbb-conf --check輸出、服務狀態、最近的 FreeSWITCH 和 SFU 日誌條目以及網路拓撲結構。請對敏感資訊和公開用戶資料進行編輯。這些資訊有助於區分失效的監聽器、ESL 逾時、錯誤的通告位址、被封鎖的媒體範圍以及真正的 SIP 閘道註冊失敗。

官方參考資料

• BigBlueButton 4.0故障排除指南
• BigBlueButton 4.0 防火牆配置
• FreeSWITCH CLI 和 API 指令參考
• 使用 Sofia 的 FreeSWITCH SIP 設定文件

文件已於 2026 年 10 月 6 日核實。 BigBlueButton 4.0 的文件將此版本標記為開發中；請根據伺服器上安裝的版本確認路徑和命令。