上個月幫一個客戶排查JSSIP通話只響鈴不出聲的問題從UA配置翻到SIP服務端再翻到瀏覽器控制臺最后定位到的根因既不是JSSIP的Bug也不是服務器的策略問題而是瀏覽器側的ICE候選一直沒收集到中繼地址。這類問題在基于WebRTC和WebSocket構建的網(wǎng)頁通話項目里太典型了表面上是JSSIP在用實際信令走WebSocket、媒體走WebRTC三者的分工一旦沒有理清楚排查時就會繞遠路。這篇文章適合已經(jīng)在用或者準備用JSSIP做網(wǎng)頁軟電話、呼叫中心坐席工作臺、在線客服音視頻通話的團隊。我會先把JSSIP、WebRTC、WebSocket三者之間的真實關系講透再給出一套可以照著抄的最小可用實現(xiàn)然后把我實際踩過的幾個高頻問題的完整排查鏈路拆開來講最后補充一些工程化集成和線上排障的經(jīng)驗。1. 先把三件事的分工搞明白JSSIP、WebRTC、WebSocket各管哪一段很多人一開始接觸JSSIP容易把它理解成一個打電話的SDK其實這個理解不夠準確。JSSIP的核心工作是讓瀏覽器能跑SIP協(xié)議但瀏覽器本身既沒有SIP棧也沒法直接用UDP和SIP服務器通信。JSSIP負責把SIP消息封裝成JavaScript對象再通過WebSocket發(fā)給服務器。真正傳輸音頻和視頻的是WebRTC。這三者的關系可以用一條鏈路來看。1.1 一個瀏覽器電話從撥打到接通信令和媒體分別走什么路徑瀏覽器里的一個呼叫流程大致是這樣的瀏覽器加載頁面JSSIP創(chuàng)建UAUser AgentUA通過WebSocket和SIP服務器建立長連接。用戶點擊撥號JSSIP生成一條SIP INVITE消息通過WebSocket發(fā)送給SIP服務器。SIP服務器把INVITE路由到被叫端。如果被叫端也是瀏覽器那它的JSSIP會通過WebSocket收到這條消息然后彈出來電。雙方在SIP的SDP offer/answer流程中交換媒體參數(shù)包括IP地址、端口、編解碼器、ICE候選。媒體協(xié)商完成后瀏覽器之間的音頻/視頻流通過WebRTC的SRTP/DTLS通道直接傳輸不再經(jīng)過JSSIP。這里面有個關鍵點SIP負責說服對方接聽信令WebRTC負責把聲音和畫面送到對方耳朵和屏幕媒體。JSSIP只關心信令部分媒體部分的建立和維持都是WebRTC在做。1.2 WebSocket在JSSIP方案里是傳輸層而不是業(yè)務層WebSocket在這里的作用是把SIP消息從瀏覽器安全地送到服務器。為什么不用HTTP輪詢因為SIP協(xié)議本身是一個有狀態(tài)的、雙向的會話協(xié)議服務器隨時可能主動推送消息給瀏覽器比如來電請求。HTTP的一次性請求/響應模型很難做這種雙向通信。WebSocket是長連接服務器可以隨時下發(fā)SIP消息。按照RFC 7118的定義SIP over WebSocket是專門的標準化方案。JSSIP就是按照這套規(guī)范實現(xiàn)的。所以你在配置JSSIP的時候socket地址必須是ws://或者wss://開頭不能寫成http://。1.3 為什么很多JSSIP問題最終都出在媒體面實際排查中我發(fā)現(xiàn)很多人一遇到JSSIP打電話不成功就懷疑是JSSIP配置錯誤或者SIP服務器出了問題于是瘋狂看REGISTER、INVITE這些信令。但真正的坑往往在媒體面。信令面只要能注冊、能發(fā)起呼叫說明SIP協(xié)議層面的交互是通的。等到對方接聽之后發(fā)現(xiàn)自己聽不到對方說話、或者對方聽不到自己說話這時候問題幾乎100%是WebRTC的媒體協(xié)商、ICE連接、設備權限導致的。所以理解信令和媒體分離這個模型是排查JSSIP問題的第一課。信令不通查WebSocket和SIP媒體不通查WebRTC。2. 從零接入JSSIP最小可運行撥號器的完整代碼這部分我直接給一套可運行的最小實現(xiàn)包含注冊、撥打、接聽、掛斷、無應答處理。代碼基于JSSIP 3.x版本它是最穩(wěn)定的一個大版本。2.1 安裝與引入方式工程化項目推薦用npmnpm install jssip然后在模塊里引入import { JsSIP } from jssip;如果只是做個Demo或者沒有構建工具的頁面直接用CDN更省事script srchttps://unpkg.com/jssip/dist/jssip.min.js/script引入之后全局會掛一個JsSIP對象。需要注意JSSIP在瀏覽器環(huán)境下使用不要在Node.js直接跑它依賴window對象和WebRTC API。2.2 UA初始化與注冊每個參數(shù)都必須知道為什么不填會出事UA配置是整個項目的核心。先看一段完整代碼import { JsSIP } from jssip; const socket new JsSIP.WebSocketInterface(wss://sip.example.com:7443); const configuration { sockets: [socket], uri: sip:1001sip.example.com, password: 123456, register: true, session_timers: false, stun_servers: [stun:stun.l.google.com:19302], turn_servers: [ { urls: [turn:turn.example.com:3478?transportudp], username: turnuser, credential: turnpass, }, ], user_agent: MySoftPhone/1.0, display_name: 張三, }; const ua new JsSIP.UA(configuration); ua.on(connected, () { console.log(WebSocket connected); }); ua.on(disconnected, () { console.log(WebSocket disconnected); }); ua.on(registered, () { console.log(UA registered); }); ua.on(registrationFailed, (data) { console.error(Registration failed:, data.cause); }); ua.start();逐個拆開看這些參數(shù)sockets必須是一個數(shù)組即使只有一個WebSocket地址也要寫成數(shù)組?？梢耘渲枚鄠€地址JSSIP會在連接失敗時自動切換。uri是你在SIP服務器上的身份格式必須是sip:分機號域名。這里最容易犯的錯是只寫分機號不寫域名或搞混了SIP域名和WebSocket地址的域名。register: true表示啟動UA后自動向服務器發(fā)送REGISTER請求。如果不需要注冊只想作為被叫接聽也要寫register: true除非你的SIP服務端不強制注冊。session_timers: false是為了關掉會話定時器。這個定時器本身是SIP標準的一部分但某些服務器實現(xiàn)不完整開啟后通話到幾分鐘就自動斷開排查起來非常頭疼。沒有特殊需求建議直接關掉。stun_servers和turn_servers是給WebRTC用的。很多教科書只強調(diào)設置STUN但在企業(yè)網(wǎng)絡環(huán)境下沒有TURN是打不通音的。2.3 撥打、接聽、掛斷事件驅(qū)動的呼叫模型發(fā)起呼叫const session ua.call(sip:1002sip.example.com, { mediaConstraints: { audio: true, video: false }, rtcOfferConstraints: { offerToReceiveAudio: true, offerToReceiveVideo: false, }, pcConfig: { iceServers: [ { urls: stun:stun.l.google.com:19302 }, { urls: turn:turn.example.com:3478?transportudp, username: turnuser, credential: turnpass, }, ], }, }); session.on(progress, () { console.log(calling...); }); session.on(confirmed, () { console.log(call established); }); session.on(ended, () { console.log(call ended); }); session.on(failed, (data) { console.error(call failed:, data.cause); });接聽來電需要監(jiān)聽UA的newRTCSession事件ua.on(newRTCSession, (data) { const session data.session; if (session.direction incoming) { session.on(accepted, () { console.log(incoming call accepted); }); session.answer({ mediaConstraints: { audio: true, video: false }, pcConfig: { iceServers: [ { urls: stun:stun.l.google.com:19302 }, { urls: turn:turn.example.com:3478?transportudp, username: turnuser, credential: turnpass, }, ], }, }); } });掛斷就一行session.terminate();還有一種情況是主叫取消呼叫被叫端會收到failed事件需要在這個事件里處理界面回到空閑狀態(tài)。2.4 為什么pcConfig里的iceServers要單獨傳一遍UA配置里有stun_servers和turn_servers但因為JSSIP的初始化參數(shù)和每個會話的媒體參數(shù)是分開的為了保險每個會話的pcConfig里也要把ICE服務器重新傳一遍。否則某些場景下JSSIP可能沒有正確地把UA級別的ICE服務器配置應用到RTCPeerConnection里導致呼叫建立后媒體發(fā)不出去。我遇到過不止一次這種情況每次都找不到原因后來干脆統(tǒng)一在會話級設置問題就消失了。配置位置作用范圍建議UA級stun_servers注冊階段或默認媒體協(xié)商配置一套全局默認會話級pcConfig.iceServers每次呼叫/接聽的媒體協(xié)商每次都顯式傳最穩(wěn)會話級mediaConstraints是否采集音頻/視頻按產(chǎn)品需求設置3. 信令通道的坑WebSocket連接建立與保持WebSocket是JSSIP的命根子。UA的一切SIP消息都要從這條通道走。這里的坑如果不提前踩一次線上出問題的時候會非常被動。3.1 連接一直pendingUA沒有任何注冊回執(zhí)現(xiàn)象很統(tǒng)一前端調(diào)ua.start()控制臺既不打印connected也不打印disconnected好像網(wǎng)絡請求被卡在半路。第一步先打開瀏覽器DevTools的Network面板找到WS分類看這條WebSocket連接是不是一直處于pending狀態(tài)。如果WebSocket握手沒完成直接把問題定位在服務器地址的連通性而不是JSSIP配置。我常用的驗證方式是在服務器本機用curl測一下WebSocket端點curl -i -N -H Connection: Upgrade -H Upgrade: websocket -H Sec-WebSocket-Version: 13 -H Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw http://sip.example.com:7443/如果服務器沒有正確響應101狀態(tài)碼說明WebSocket服務沒啟動或者防火墻把端口擋了。還要注意很多SIP服務器軟件比如FreeSWITCH、Asterisk需要單獨開啟WebSocket模塊默認只監(jiān)聽UDP/TCP的5060端口。需要排查的其他點協(xié)議是ws://還是wss://一定不能寫錯。如果是wss證書是否有效瀏覽器有沒有直接攔截。WebSocket端口是否被防火墻或安全組屏蔽。3.2 401/403注冊被拒從UA配置到SIP服務端逐層排查如果WebSocket已經(jīng)連通但注冊不成功JSSIP會觸發(fā)registrationFailed事件并帶上cause。最常見的cause是Unauthorized和Forbidden。Unauthorized通常意味著SIP服務端要求認證但沒有收到正確的認證信息。檢查順序UA的uri和password是否和服務器上的分機賬號一致。服務器是不是要求摘要認證Digest authenticationJSSIP默認支持不需要額外配置。SIP服務器有沒有在數(shù)據(jù)庫里啟用該分機。Forbidden意味著賬號本身沒有權限注冊。比如某些服務器限制了來源IP或者該分機已經(jīng)在其他地方注冊導致互踢。很多PBX系統(tǒng)默認一個分機只能在一個終端注冊如果瀏覽器剛注冊完服務器就把舊連接踢掉了或者反過來前端沒做斷開清理UA反復注冊導致服務器覺得是異常行為。這里有一個很實用的排查技巧打開JSSIP的調(diào)試日志它會打印完整的SIP消息和響應碼。看到401之后是否繼續(xù)發(fā)送帶Authorization的REGISTER就能確定認證流程是否走完。3.3 網(wǎng)絡切換導致WebSocket斷開重連策略WebSocket長連接最怕遇到網(wǎng)絡切換。手機從WiFi切到4G/5G或者公司網(wǎng)絡斷了幾秒TCP連接就斷了。更麻煩的是斷線之后TCP可能在半開狀態(tài)瀏覽器要等TCP超時才能感知這段時間UA會一直覺得連接還在。監(jiān)聽disconnected事件然后做重連是基本的?；罘桨竨a.on(disconnected, (data) { console.warn(WebSocket disconnected:, data); // 等待網(wǎng)絡恢復后重新啟動 setTimeout(() { if (!ua.isConnected()) { ua.start(); } }, 3000); });但這里有個坑如果在斷線時還有正在進行的通話直接ua.start()不一定能恢復媒體流。因為媒體流是通過WebRTC直接傳輸?shù)腤ebSocket只影響信令。所以在重連策略里必須區(qū)分場景沒有通話時斷線重連注冊即可。有通話時WebSocket斷線先保持頁面狀態(tài)等WebSocket重連成功后再繼續(xù)通話如果通話中需要掛斷等操作要等信令通道恢復后才能執(zhí)行。另外一個實際經(jīng)驗是不要做無限重連。我見過一個項目每1秒重試一次最后把SIP服務器打到拒絕服務。推薦用指數(shù)退避加最大次數(shù)的策略比如最多重試10次間隔從1秒開始倍增。3.4 ws還是wss混合內(nèi)容與Nginx代理的常見配置生產(chǎn)環(huán)境必須用wss://。瀏覽器有混合內(nèi)容安全策略HTTPS頁面加載ws://資源時會被直接攔截控制臺會明確報錯。如果頁面恰好是HTTP環(huán)境且SIP服務器是WS開發(fā)環(huán)境可以跑但生產(chǎn)環(huán)境幾乎不可能用HTTP。很多項目WebSocket地址和HTTPS頁面不在同一臺機器上需要Nginx做反向代理。這里最容易漏掉的是WebSocket的Upgrade頭。一段可用的Nginx配置如下location /ws { proxy_pass http://127.0.0.1:7443; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_read_timeout 3600s; proxy_send_timeout 3600s; }proxy_read_timeout和proxy_send_timeout建議設長一些否則空閑的WebSocket連接會被Nginx在默認60秒后掐斷導致SIP服務器認為UA掉了。4. 媒體鏈路的坑撥通之后聽不到聲音信令通了對方也接聽了但聽不到聲音或只有單邊聲音這是JSSIP項目里出現(xiàn)頻率最高的一類問題。4.1 單向音頻的排查順序單向音頻是指一方能聽到另一方但另一方聽不到。這種問題在傳統(tǒng)SIP里常見的原因是NAT和防火墻不對稱在瀏覽器環(huán)境下最多的原因有兩個SDP方向?qū)傩圆黄ヅ浠蛘咴O備權限只給了一半。排查時先做一件事雙方都在瀏覽器控制臺執(zhí)行session._connection或者直接看JSSIP調(diào)試日志把SDP打印出來看音頻流的direction字段。正常的情況下本端采集到麥克風SDP里m行會有sendrecv或sendonly對端應答之后如果只想聽會被記為recvonly。如果發(fā)現(xiàn)本端SDP中是inactive或沒有send說明瀏覽器沒有采集到麥克風數(shù)據(jù)檢查設備權限。我遇到過一種隱蔽情況電腦插了USB耳機但系統(tǒng)默認音頻輸入設備是麥克風陣列瀏覽器彈出的權限選擇框用戶在慌亂中選了忽略。這種問題在控制臺看不出明顯的報錯只有通過檢測媒體流軌道才能發(fā)現(xiàn)session.on(peerconnection, (data) { const audioTracks data.stream.getAudioTracks(); if (!audioTracks.length) { console.warn(No audio track detected); } });4.2 ICE候選收集失敗與STUN/TURN的關系如果WebRTC的ICE協(xié)商沒有完成通話會卡在正在連接然后過一會兒自動掛斷。ICE的作用是讓雙方找到一條可達的媒體路徑。STUN是幫你發(fā)現(xiàn)公網(wǎng)映射地址TURN是當P2P直連不通時作為中轉服務器轉發(fā)媒體。在局域網(wǎng)環(huán)境里host候選可能就夠了。但跨網(wǎng)絡通話、公司有嚴格防火墻、雙方都在NAT后面時特別需要TURN。判斷方式很簡單打開JSSIP日志或chrome://webrtc-internals看ICE候選列表里有沒有relay類型的候選。如果沒有說明TURN沒配或者沒生效。配TURN服務器時要注意transportudp/tcp參數(shù)。UDP轉發(fā)性能好但某些企業(yè)網(wǎng)絡會封UDP如果TURN server只配了UDP就可能在UDP不通的時候徹底失敗。穩(wěn)妥的做法是兩個都配上turn_servers: [ { urls: [ turn:turn.example.com:3478?transportudp, turn:turn.example.com:3478?transporttcp, ], username: user, credential: pass, }, ]一個容易被忽略的細節(jié)TURN的username和credential不能只在UA配置寫一次每個呼叫的pcConfig.iceServers里也要帶上。有些項目為了省事只配了STUN測試時內(nèi)網(wǎng)能通上線后外網(wǎng)用戶通話質(zhì)量一團糟。4.3 瀏覽器權限與安全上下文問題getUserMedia獲取麥克風/攝像頭權限有三個硬性條件頁面必須在HTTPS或localhost環(huán)境下。用戶必須授權設備權限。如果瀏覽器沒有捕獲到設備MediaStream里是空的。排查時可以手動在控制臺執(zhí)行navigator.mediaDevices.getUserMedia({ audio: true }) .then((stream) { console.log(Device OK, stream.getAudioTracks().length); stream.getTracks().forEach((track) track.stop()); }) .catch((err) { console.error(Device error:, err); });如果這條命令都報錯那就跟JSSIP無關是頁面環(huán)境和瀏覽器權限設置的問題。還遇到過Chrome在Windows上某些版本對特定USB聲卡兼容性不好導致沒有音頻軌道這個只能靠換音頻設備或者改瀏覽器設置規(guī)避。4.4 編解碼器協(xié)商失敗的隱蔽情況JSSIP默認的音頻編碼是opus視頻是VP8。如果你的SIP服務端或?qū)Χ嗣襟w網(wǎng)關不支持opus那么SDP協(xié)商可能會失敗。在服務器上可能表現(xiàn)為488 Not Acceptable Here或者媒體流建立后完全沒有聲音。如果服務器只支持PCMA/PCMUG.711需要讓JSSIP在SDP offer里也帶上這些編碼。可以修改ua.call()的rtcOfferConstraints或通過擴展手段調(diào)整SDP。但最干凈的方案是讓服務器端把opus打開因為瀏覽器端對opus支持最好很多SIP媒體網(wǎng)關默認就支持opus。還有一種情況是視頻編解碼器協(xié)商。如果只想做純音頻務必在mediaConstraints里把video: false寫清楚否則JSSIP可能默認采集視頻而你的服務器又無法處理VP8/VP9/H.264導致整個會話建立失敗。5. 工程化集成把JSSIP嵌進Vue/React項目JSSIP本身不挑框架但工程化集成時如果不想清楚幾個問題后面維護會很痛苦。5.1 單例UA的封裝很多人在每個頁面組件里都創(chuàng)建一個新的UA實例結果同一用戶在多個頁面注冊了多個SIP賬號服務器那邊分機互踢表現(xiàn)為剛登錄就被踢下線。正確做法是把UA封裝成全局單例。在Vue項目里可以放到store里在React項目里可以放到context或一個獨立的module里。一個簡單的實現(xiàn)// jssip-singleton.js let uaInstance null; export function getUA() { return uaInstance; } export function initUA(config) { if (uaInstance) { uaInstance.stop(); } uaInstance new JsSIP.UA(config); uaInstance.start(); return uaInstance; } export function destroyUA() { if (uaInstance) { uaInstance.stop(); uaInstance null; } }這樣保證整個應用生命周期內(nèi)只有一個UA避免重復注冊和互踢。5.2 組件卸載時清理事件監(jiān)聽JSSIP的事件監(jiān)聽器如果不清理組件卸載后依然會觸發(fā)回調(diào)。在Vue的onUnmounted或React的useEffectcleanup里需要把UA上的監(jiān)聽器移除或者用removeListener。一個更省心的做法是抽象一個簡單的發(fā)布訂閱層只在全局單例上綁定一次事件然后通過業(yè)務事件廣播給組件。這樣組件卸載與否不會影響UA的運行狀態(tài)。另外頁面在關閉或刷新前最好調(diào)用ua.stop()讓服務器知道分機下線?？梢员O(jiān)聽beforeunload事件window.addEventListener(beforeunload, () { if (ua) { ua.stop(); } });這樣能減少服務器上的僵尸注冊。5.3 多標簽頁重復注冊的問題瀏覽器產(chǎn)品很容易出現(xiàn)用戶開多個標簽頁每個標簽頁都創(chuàng)建一個UA的情況。解決辦法通常有三個用window.open的返回引用限制只能有一個通話窗口。利用BroadcastChannel做標簽頁間通信新標簽頁檢測到已有在線標簽頁時提示用戶。使用localStorage加鎖標記但要注意清理。就穩(wěn)定性而言我推薦第一種或第二種。JSSIP不是一個多實例友好的庫同一分機在兩個標簽頁里同時注冊大概率會出現(xiàn)來電只在一個標簽頁振鈴、另一邊毫無反應的隨機問題。6. 問題排查的調(diào)試工具與自檢清單最后分享一套我在JSSIP項目里實際在用的排查工具和自檢流程。6.1 開啟JSSIP的調(diào)試日志JSSIP自帶debug日志系統(tǒng)。在引入庫之后執(zhí)行JsSIP.debug.enable(JsSIP:*);控制臺會打印所有SIP消息包括發(fā)出的和收到的。這是一個非常強大的排查工具REGISTER發(fā)沒發(fā)、401返回了沒有、INVITE里帶了什么樣的SDP全都一覽無余。正式環(huán)境發(fā)布前記得關掉避免日志刷屏。6.2 用chrome://webrtc-internals和DevTools配合chrome://webrtc-internals這個內(nèi)置頁面是WebRTC排障神器。地址欄直接輸入打開然后重新發(fā)起一次呼叫它會記錄這一段時間內(nèi)所有的WebRTC內(nèi)部狀態(tài)包括getUserMedia是否成功每一幀音頻/視頻的發(fā)送和接收情況ICE候選的收集過程每條候選的連接狀態(tài)SDP offer/answer詳情配合DevTools的Network面板看WebSocket幀就能同時看到信令和媒體兩條鏈路的狀態(tài)。6.3 一張表快速定位常見故障現(xiàn)象優(yōu)先排查方向典型原因注冊一直失敗WebSocket連通狀態(tài)防火墻攔截、端口不通、wss證書錯誤401/403注冊被拒賬號密碼、分機狀態(tài)密碼錯誤、分機未啟用、互踢能打出去但對方無聲音SDP和ICE本端麥克風未采集、TURN未配置撥打后長時間connectingICE協(xié)商內(nèi)網(wǎng)到外網(wǎng)無TURN中轉、STUN失效通話進行中隨機斷開服務器配置/網(wǎng)絡切換session_timers開啟、WebSocket超時被動斷開頁面報DevicesNotFoundError設備權限瀏覽器權限被拒、沒有可用麥克風視頻通話只有畫面沒聲音SDP中音頻m行服務器不支持opus、只做了視頻協(xié)商我自己在做線上支持時通常先問三個問題有沒有開啟調(diào)試日志W(wǎng)ebSocket是connected還是disconnectedwebrtc-internals里有沒有relay候選這三個問題基本能過濾掉80%的場景。JSSIP的官方文檔信息量很大但真正能讓你少走彎路的往往是這些從實際項目里踩出來的判斷順序。比如看到注冊失敗先別急著改代碼先確認WebSocket連接本身是健康的看到單向音頻也別先去翻防火墻先確認瀏覽器有沒有真正采集到麥克風數(shù)據(jù)。把信令和媒體這兩個維度分開JSSIP的使用會簡單很多因為你始終知道該去哪一端找證據(jù)。