簡(jiǎn)介這份資源是面向WebRTC語音通信開發(fā)者的實(shí)戰(zhàn)示例包聚焦sipjs與FreeSWITCH的整合應(yīng)用解決網(wǎng)頁端實(shí)現(xiàn)電話呼入、呼出、轉(zhuǎn)移與保持等核心功能的落地問題。適合具備一定前端與SIP協(xié)議基礎(chǔ)、希望快速驗(yàn)證軟電話能力的開發(fā)者參考。壓縮包共4個(gè)文件包含1個(gè)html頁面、1個(gè)js腳本、1個(gè)css樣式表與1個(gè)txt說明文檔整體約79KB結(jié)構(gòu)精簡(jiǎn)其中html承載界面與呼叫邏輯js負(fù)責(zé)SIP信令交互css處理通話面板樣式txt提供使用指引。在谷歌瀏覽器下運(yùn)行后只需將分機(jī)號(hào)、密碼與服務(wù)器地址替換為自己的配置即可直接進(jìn)行功能測(cè)試省去從零搭建信令環(huán)境的成本。目前已有2315人學(xué)習(xí)下載可作為理解sipjs呼叫流程、排查注冊(cè)與媒體協(xié)商問題的實(shí)用起點(diǎn)。1. 瀏覽器里跑起一通真實(shí)電話SIP.js 加 FreeSWITCH 的 WebRTC 落地場(chǎng)景很多做企業(yè)通信的團(tuán)隊(duì)都遇到過這個(gè)需求客戶不想裝軟電話就想在瀏覽器網(wǎng)頁里直接打電話——能呼入、能呼出、能轉(zhuǎn)接、能保持。聽起來簡(jiǎn)單真動(dòng)手才發(fā)現(xiàn)坑不少信令走不通、媒體沒聲音、轉(zhuǎn)接后對(duì)方聽不到、保持之后恢復(fù)不了。這套基于 SIP.js 加 FreeSWITCH 的 WebRTC 網(wǎng)頁端示例解決的正是這個(gè)場(chǎng)景。它把瀏覽器當(dāng) SIP 終端通過 WebSocket 連 FreeSWITCH 做信令用 WebRTC 承載媒體實(shí)現(xiàn)完整的呼叫控制。適合做呼叫中心、客服工作臺(tái)、內(nèi)部通信面板的前后端工程師也適合想搞懂 WebRTC 電話鏈路的技術(shù)負(fù)責(zé)人。下面按「是什么、怎么搭、坑在哪、怎么進(jìn)階」的順序拆開講。2. 信令與媒體怎么分工SIP.js 和 FreeSWITCH 的職責(zé)邊界2.1 為什么是 SIP.js 而不是自己擼 WebSocket瀏覽器原生沒有 SIP 協(xié)議棧要打電話就得有人把 SIP 消息翻譯成 WebSocket 幀。SIP.js 干的就是這件事它把 REGISTER、INVITE、ACK、BYE、REFER 這些 SIP 方法封裝成 JavaScript API開發(fā)者調(diào)invite()、hold()、transfer()就行不用手拼 SIP 報(bào)文。常見做法是前端只關(guān)心「撥號(hào)、掛斷、保持、轉(zhuǎn)接」四個(gè)動(dòng)作底層信令交給 SIP.js 的 UserAgent 和 Session 對(duì)象管理。選型上要注意版本差異。SIP.js 0.21 之后 API 改動(dòng)較大SimpleUser和UserAgent兩套用法并存。示例里如果用SimpleUser代碼量少但可控性弱用UserAgent加Registerer加Inviter手動(dòng)組裝靈活但要多寫幾十行。我一般建議先跑通SimpleUser確認(rèn)鏈路沒問題再換成底層 API 做定制。2.2 FreeSWITCH 側(cè)要開哪些口子FreeSWITCH 在這里扮演 SIP 代理加媒體網(wǎng)關(guān)。瀏覽器發(fā)來的 WebSocket 信令走mod_sofia的 WSS 監(jiān)聽媒體走mod_rtc或內(nèi)置的 WebRTC 支持。關(guān)鍵配置集中在 sofia profile 里!-- conf/sip_profiles/internal.xml 關(guān)鍵片段 -- param namewss-binding value:7443/ param namertp-secure-media valuemandatory/ param nameapply-candidate-acl valuewan_v4.auto/wss-binding指定 WebSocket Secure 監(jiān)聽端口瀏覽器必須用wss://連接ws://在 HTTPS 頁面下會(huì)被瀏覽器直接攔掉。rtp-secure-media設(shè)為mandatory強(qiáng)制 SRTP因?yàn)?WebRTC 的媒體必須加密明文 RTP 會(huì)被瀏覽器拒絕。apply-candidate-acl決定 FreeSWITCH 怎么處理 ICE candidate內(nèi)網(wǎng)環(huán)境可以放寬公網(wǎng)部署要配合 STUN/TURN。2.3 一次呼出到底走了哪些步驟把呼出流程拆開看每一步都有對(duì)應(yīng)的代碼位置頁面加載后創(chuàng)建UserAgent傳入wss://freeswitch:7443和分機(jī)賬號(hào)密碼。調(diào)用register()發(fā) REGISTERFreeSWITCH 返回 200 OK狀態(tài)變Registered。用戶點(diǎn)撥號(hào)invite()發(fā) INVITESDP 里帶 WebRTC 的 offer含 ICE、DTLS 指紋。FreeSWITCH 回 200 OK 帶 answer SDP雙方做 ICE 連通性檢查和 DTLS 握手。媒體通道建立session.state變Established可以通話。掛斷時(shí)發(fā) BYEFreeSWITCH 回 200會(huì)話銷毀。// 呼出核心邏輯基于 SIP.js UserAgent const ua new SIP.UserAgent({ uri: SIP.UserAgent.makeURI(sip:1001freeswitch), transportOptions: { server: wss://freeswitch:7443 }, authorizationUsername: 1001, authorizationPassword: secret, delegate: { onInvite(invitation) { // 呼入時(shí)觸發(fā)決定接聽還是拒絕 invitation.accept(); } } }); // 注冊(cè) const registerer new SIP.Registerer(ua); await ua.start(); await registerer.register(); // 呼出 const target SIP.UserAgent.makeURI(sip:1002freeswitch); const inviter new SIP.Inviter(ua, target); await inviter.invite();這段代碼里transportOptions.server必須是wss://authorizationUsername對(duì)應(yīng) FreeSWITCH 里的分機(jī)號(hào)。onInvite是呼入入口不接就掛。inviter.invite()返回 Promiseresolve 只代表信令通了媒體是否通要看session.state和實(shí)際有沒有聲音。提示ua.start()和registerer.register()都要 await順序不能反。先 start 再 register否則 REGISTER 發(fā)不出去。3. 呼入、呼出、轉(zhuǎn)移、保持四個(gè)動(dòng)作的代碼實(shí)現(xiàn)與參數(shù)3.1 呼入接聽與自動(dòng)應(yīng)答呼入的處理入口在delegate.onInvite。默認(rèn)行為是彈個(gè)提示讓用戶點(diǎn)接聽但客服場(chǎng)景往往要自動(dòng)應(yīng)答。自動(dòng)應(yīng)答直接調(diào)invitation.accept()但要注意瀏覽器麥克風(fēng)權(quán)限沒授權(quán)之前 accept 會(huì)失敗媒體流拿不到。delegate: { onInvite(invitation) { // 先檢查麥克風(fēng)權(quán)限 navigator.mediaDevices.getUserMedia({ audio: true }) .then(() { invitation.accept({ sessionDescriptionHandlerOptions: { constraints: { audio: true, video: false } }}); }) .catch(err { console.error(麥克風(fēng)未授權(quán), err); invitation.reject(); }); } }constraints里audio: true是必須的video: false表示純語音。如果要做視頻通話就改成video: true但 FreeSWITCH 側(cè)要額外配視頻編解碼。accept()之后會(huì)話進(jìn)入Establishing等 ICE 和 DTLS 完成才變Established。3.2 呼出參數(shù)與超時(shí)控制呼出時(shí)除了目標(biāo) URI還要控制超時(shí)和早期媒體。默認(rèn) SIP.js 的 INVITE 超時(shí)是 60 秒左右太長客服場(chǎng)景一般 30 秒沒接就取消。const inviter new SIP.Inviter(ua, target, { sessionDescriptionHandlerOptions: { constraints: { audio: true, video: false } }, earlyMedia: true // 接收回鈴音等早期媒體 }); // 30 秒超時(shí)取消 const timeout setTimeout(() { if (inviter.state SIP.SessionState.Establishing) { inviter.cancel(); } }, 30000); inviter.stateChange.addListener((state) { if (state SIP.SessionState.Established) { clearTimeout(timeout); } }); await inviter.invite();earlyMedia: true讓瀏覽器能播對(duì)方回鈴音不然撥號(hào)后一片安靜用戶以為沒反應(yīng)。inviter.cancel()發(fā) CANCEL 取消未接通的 INVITE和bye()不同后者是已接通后掛斷。3.3 保持與恢復(fù)re-INVITE 的門道保持的本質(zhì)是發(fā)一個(gè) re-INVITE把 SDP 里的媒體方向改成ainactive或asendonly。SIP.js 封裝成session.hold()和session.unhold()。// 保持 await session.hold(); // 此時(shí) session.state 仍是 Established但媒體停了 // 恢復(fù) await session.unhold();坑在于有些 FreeSWITCH 配置下hold()之后對(duì)方聽到的是靜音而不是保持音樂需要在 dialplan 里配hold_music。另外保持期間如果瀏覽器切到后臺(tái)定時(shí)器可能被節(jié)流恢復(fù)時(shí) re-INVITE 延遲表現(xiàn)為「點(diǎn)了恢復(fù)沒反應(yīng)」實(shí)際是消息晚了幾秒。3.4 轉(zhuǎn)移REFER 與 attended transfer 的區(qū)別轉(zhuǎn)移分兩種。盲轉(zhuǎn)blind transfer用 REFER把對(duì)方直接甩給第三方自己退出。 attended transfer 是先保持當(dāng)前通話再呼第三方接通后把兩路橋接。SIP.js 對(duì)盲轉(zhuǎn)支持較好// 盲轉(zhuǎn)把當(dāng)前通話轉(zhuǎn)給 1003 const referTarget SIP.UserAgent.makeURI(sip:1003freeswitch); await session.refer(referTarget);refer()發(fā) REFERFreeSWITCH 收到后代替發(fā)起方去呼 1003。注意 REFER 的接受方是 FreeSWITCH 不是對(duì)方終端所以 dialplan 要允許 REFER 處理。 attended transfer 在 SIP.js 里沒有現(xiàn)成 API要手動(dòng)組合先hold()當(dāng)前會(huì)話再invite()第三方接通后調(diào)session.refer()帶Replaces頭。這塊復(fù)雜度高示例里如果只做盲轉(zhuǎn)先跑通再擴(kuò)展。注意轉(zhuǎn)移失敗最常見的原因是 FreeSWITCH 的transfer權(quán)限沒開或者 dialplan 里沒匹配 REFER 的目標(biāo)分機(jī)。4. 避坑與排查媒體不通、注冊(cè)失敗、轉(zhuǎn)接斷線的血淚經(jīng)驗(yàn)4.1 注冊(cè)失敗401 和 403 怎么區(qū)分現(xiàn)象registerer.register()報(bào)錯(cuò)狀態(tài)一直是Unregistered。原因401 是認(rèn)證挑戰(zhàn)說明賬號(hào)密碼不對(duì)或authorizationUsername和 URI 里的用戶不一致403 是 FreeSWITCH 直接拒絕通常是 ACL 限制或分機(jī)沒啟用。解決先看 FreeSWITCH 控制臺(tái)sofia status profile internal reg有沒有注冊(cè)記錄。401 就核對(duì)authorizationUsername和authorizationPassword注意 URI 里的 domain 要和 FreeSWITCH 的sip_domain一致。403 檢查conf/directory/default/下分機(jī) XML 是否存在且enabled。4.2 能振鈴但沒聲音ICE 和 DTLS 的鍋現(xiàn)象撥號(hào)后對(duì)方振鈴接起來雙方都聽不到聲音但信令顯示Established。原因媒體通道沒建起來。要么 ICE candidate 交換失敗要么 DTLS 握手沒過。WebRTC 強(qiáng)制 SRTPFreeSWITCH 如果沒開rtp-secure-media就會(huì)協(xié)商失敗。解決瀏覽器開chrome://webrtc-internals看 ICE 狀態(tài)和 DTLS 狀態(tài)。ICE 卡在checking說明 candidate 不通內(nèi)網(wǎng)檢查防火墻有沒有放行 UDP 端口段公網(wǎng)要配 STUN。DTLS 失敗看 FreeSWITCH 日志有沒有DTLS handshake failed有就確認(rèn)rtp-secure-media是mandatory或optional。4.3 轉(zhuǎn)接后原通話斷掉現(xiàn)象點(diǎn)轉(zhuǎn)移當(dāng)前通話直接掛斷第三方也沒振鈴。原因REFER 發(fā)出去后 FreeSWITCH 沒正確處理或者refer()的 target 格式不對(duì)。SIP.js 的refer()要求傳入U(xiǎn)RI對(duì)象傳字符串會(huì)靜默失敗。解決確認(rèn)SIP.UserAgent.makeURI()返回的不是 undefined。再看 FreeSWITCH dialplan 里有沒有transfer的 extension。如果用的是session.refer()后原會(huì)話立刻Terminated說明 FreeSWITCH 把 REFER 當(dāng)成了掛斷檢查mod_sofia的refer相關(guān)參數(shù)。4.4 保持后恢復(fù)沒反應(yīng)現(xiàn)象hold()成功unhold()調(diào)了但對(duì)方還是聽不到。原因re-INVITE 的 SDP 方向沒更新或者瀏覽器定時(shí)器節(jié)流導(dǎo)致消息延遲。解決unhold()后監(jiān)聽session.stateChange確認(rèn)回到Established。如果狀態(tài)對(duì)但沒聲音抓包看 re-INVITE 的 SDP 里asendrecv有沒有恢復(fù)。瀏覽器后臺(tái)節(jié)流問題可以在頁面 visible 時(shí)再調(diào)unhold()或者用setInterval?；睢?.5 HTTPS 頁面下 wss 連不上現(xiàn)象本地http://localhost能連部署到https://域名后 WebSocket 直接報(bào)錯(cuò)。原因?yàn)g覽器混合內(nèi)容策略HTTPS 頁面不允許連ws://必須wss://。而且wss的證書要受信任自簽證書會(huì)被拒。解決FreeSWITCH 的wss-binding配成:7443并掛有效證書。開發(fā)階段可以用mkcert生成本地信任證書生產(chǎn)環(huán)境用正規(guī) CA 證書。確認(rèn)證書鏈完整不然瀏覽器報(bào)ERR_CERT_AUTHORITY_INVALID。5. 進(jìn)階用 SIP.js 事件鉤子做通話質(zhì)量監(jiān)控與自動(dòng)重連跑通基本呼叫之后真正讓這套東西能上生產(chǎn)的是兩件事通話質(zhì)量可觀測(cè)以及斷線能自愈。SIP.js 提供了session.sessionDescriptionHandler和ua.transport的事件鉤子可以拿到 WebRTC 的統(tǒng)計(jì)信息和連接狀態(tài)。先看質(zhì)量監(jiān)控。WebRTC 的RTCPeerConnection.getStats()能拿到丟包率、抖動(dòng)、往返時(shí)延。在session.stateChange變成Established后掛一個(gè)定時(shí)器采集session.stateChange.addListener(async (state) { if (state SIP.SessionState.Established) { const pc session.sessionDescriptionHandler.peerConnection; const statsTimer setInterval(async () { const stats await pc.getStats(); stats.forEach(report { if (report.type inbound-rtp report.kind audio) { console.log(丟包, report.packetsLost, 抖動(dòng), report.jitter); } if (report.type candidate-pair report.state succeeded) { console.log(RTT, report.currentRoundTripTime); } }); }, 5000); session.statsTimer statsTimer; } if (state SIP.SessionState.Terminated) { clearInterval(session.statsTimer); } });packetsLost持續(xù)增長說明網(wǎng)絡(luò)丟包jitter超過 30ms 語音會(huì)卡頓currentRoundTripTime超過 300ms 會(huì)有明顯延遲。這些指標(biāo)可以上報(bào)到監(jiān)控面板客服主管就能看到哪通電話質(zhì)量差。再看自動(dòng)重連。WebSocket 斷開時(shí)ua.transport會(huì)觸發(fā)onDisconnect默認(rèn)不會(huì)自動(dòng)重連。加一段重連邏輯ua.transport.onDisconnect () { console.warn(WebSocket 斷開5 秒后重連); setTimeout(async () { try { await ua.reconnect(); await registerer.register(); console.log(重連并重新注冊(cè)成功); } catch (e) { console.error(重連失敗, e); } }, 5000); };ua.reconnect()重建 WebSocketregisterer.register()重新注冊(cè)。注意重連后原來的 session 已經(jīng)失效如果通話中斷要提示用戶重新?lián)芴?hào)。重連間隔別設(shè)太短5 秒起步避免頻繁重試把 FreeSWITCH 打滿。監(jiān)控指標(biāo)正常范圍異常處理packetsLost每分鐘小于 5檢查網(wǎng)絡(luò)鏈路jitter小于 30ms排查 Wi-Fi 干擾RTT小于 300ms確認(rèn)服務(wù)器位置DTLS 狀態(tài)connected檢查證書和 SRTP 配置最后說個(gè)習(xí)慣。我每次部署這套東西都會(huì)先在chrome://webrtc-internals里完整走一遍呼出、保持、恢復(fù)、轉(zhuǎn)移確認(rèn) ICE 和 DTLS 全綠再交付。有一次偷懶跳過結(jié)果客戶那邊防火墻攔了 UDP排查了一下午。從那以后我每次上線前都強(qiáng)制走一遍完整鏈路驗(yàn)證包括斷網(wǎng)重連。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取