建服務(wù)端通信示例（TaoToken統(tǒng)一Key/API通道實踐）)
1. 從輪詢到全雙工為什么前端和 C 服務(wù)端需要 WebSocket如果你做過設(shè)備控制面板、實時日志看板或者在線協(xié)作工具大概率遇到過這樣的場景前端點一下按鈕后端要花幾秒處理處理完還得讓前端知道結(jié)果。用 HTTP 輪詢的話前端只能每隔一兩秒問一次“好了沒”問十次有九次是白問帶寬和 CPU 都浪費在重復(fù)的請求頭上。WebSocket 解決的正是這個問題——它基于 TCP用一次 HTTP 握手把連接升級成全雙工通道之后客戶端和服務(wù)端任何一方都能主動推消息不需要誰先問誰后答。這篇文章聚焦一個很具體的組合前端用原生 JavaScript 的 WebSocket 客戶端服務(wù)端用 C 的 mongoose.cpp 網(wǎng)絡(luò)庫。mongoose 是一個單文件、事件驅(qū)動、非阻塞的 C 網(wǎng)絡(luò)庫把 mongoose.h 和 mongoose.cpp 拖進項目就能編譯特別適合嵌入式網(wǎng)關(guān)、桌面工具后端或者需要跟硬件打交道的場景。我會把握手細節(jié)、幀結(jié)構(gòu)、斷線重連、以及怎么通過 TaoToken 統(tǒng)一 Key/API 通道做聯(lián)調(diào)驗證全部拆成可復(fù)制的步驟。適合誰看有基本 C 編譯能力、寫過一點前端 JS、想搞懂 WebSocket 底層而不是只會調(diào)庫的開發(fā)者。讀完之后你能自己搭一個本地 ws 服務(wù)用瀏覽器頁面收發(fā)消息并且知道 401、握手失敗、幀解析異常這些坑怎么排。2. TaoToken 統(tǒng)一 Key/API 通道聯(lián)調(diào)前的環(huán)境準備在動手寫 mongoose 服務(wù)端之前先把聯(lián)調(diào)環(huán)境理順。很多同學(xué)卡住不是因為 WebSocket 代碼寫錯而是 Key 管理混亂、Base URL 填錯、模型 ID 對不上。TaoToken 提供統(tǒng)一 Key 和 API 通道把模型對話、Coding Plan、控制臺、API Keys 管理都收在同一個入口省得你在多個平臺之間來回切換。先明確幾個地址后面配置里會反復(fù)用到官網(wǎng)入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基地址https://taotoken.net/api模型對話頁https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite控制臺https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文檔https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteClaude Code Anthropic 接入https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite為什么 WebSocket 聯(lián)調(diào)要提這些因為你的 mongoose 服務(wù)端往往不只是轉(zhuǎn)發(fā)消息它可能還要在收到前端指令后去調(diào)用模型接口做推理再把結(jié)果推回前端。這時候統(tǒng)一 Key 就派上用場了一個 Key 走通模型調(diào)用和業(yè)務(wù)接口不用為每個服務(wù)單獨申請憑證。我試過把 Key 散落在多個配置文件里后來排查一個 401 花了半小時最后發(fā)現(xiàn)是某個服務(wù)讀的是舊 Key。統(tǒng)一管理之后這類問題基本消失。操作上先去 API Keys 頁面生成一個 Key復(fù)制保存好它只會完整顯示一次。然后確認你要用的模型 ID在模型對話頁能看到當(dāng)前可用的模型列表。如果你打算長期跑編碼類 AgentCoding Plan 頁面有對應(yīng)的套餐說明按需選擇即可。接入文檔里有完整的請求示例和參數(shù)說明遇到字段不確定的時候優(yōu)先查文檔比在群里問快得多。環(huán)境變量建議這樣組織避免硬編碼進代碼export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_MODEL_ID你的模型IDC 側(cè)讀取環(huán)境變量用std::getenvJS 側(cè)在瀏覽器里沒法直接讀環(huán)境變量所以前端只負責(zé) WebSocket 通信模型調(diào)用放在 mongoose 服務(wù)端做Key 不暴露給瀏覽器。這一點很重要任何寫在前端 JS 里的 Key 都等于公開別這么干。3. mongoose.cpp 服務(wù)端可復(fù)制配置與握手實現(xiàn)現(xiàn)在進入正題。mongoose 的版本迭代比較快網(wǎng)上很多老代碼用的是mg_bind、mg_set_protocol_http_websocket這套 API新版本改成了mg_http_listen和事件回調(diào)里判斷MG_EV_WS_OPEN、MG_EV_WS_MSG。我這里給一份兼容性較好的寫法同時說明新舊差異你按自己下載的版本調(diào)整。先看項目結(jié)構(gòu)保持簡單ws_demo/ ├── mongoose.h ├── mongoose.c // 或 mongoose.cpp ├── server.cpp └── CMakeLists.txtmongoose 是單文件庫把 .h 和 .c/.cpp 放進目錄即可。用 CMake 編譯cmake_minimum_required(VERSION 3.10) project(ws_demo CXX) set(CMAKE_CXX_STANDARD 17) add_executable(server server.cpp mongoose.c) target_link_libraries(server pthread)服務(wù)端核心代碼我按新版 API 寫同時把舊版對應(yīng)關(guān)系注釋清楚#include mongoose.h #include string #include cstring static const char *s_listen_url http://0.0.0.0:10086; // 每個連接的私有數(shù)據(jù)用來標記是否已完成 WebSocket 升級 struct ConnState { bool is_ws false; }; static void fn(struct mg_connection *c, int ev, void *ev_data) { if (ev MG_EV_OPEN) { c-data[0] 0; // 初始化標記 } else if (ev MG_EV_HTTP_MSG) { // 收到 HTTP 請求嘗試升級為 WebSocket struct mg_http_message *hm (struct mg_http_message *) ev_data; if (mg_http_match_uri(hm, /ws)) { mg_ws_upgrade(c, hm, NULL); c-data[0] 1; // 標記為 WebSocket 連接 } else { mg_http_reply(c, 200, Content-Type: text/plain\r\n, WebSocket server alive\n); } } else if (ev MG_EV_WS_OPEN) { // 握手完成舊版對應(yīng) MG_EV_WEBSOCKET_HANDSHAKE_DONE const char *hello Connect Success!; mg_ws_send(c, hello, strlen(hello), WEBSOCKET_OP_TEXT); } else if (ev MG_EV_WS_MSG) { // 收到 WebSocket 數(shù)據(jù)幀舊版對應(yīng) MG_EV_WEBSOCKET_FRAME struct mg_ws_message *wm (struct mg_ws_message *) ev_data; // 回顯收到的內(nèi)容并附加服務(wù)端標識 std::string reply server echo: ; reply.append(wm-data.buf, wm-data.len); mg_ws_send(c, reply.c_str(), reply.size(), WEBSOCKET_OP_TEXT); } else if (ev MG_EV_CLOSE) { // 連接關(guān)閉可在這里做資源清理 } } int main() { struct mg_mgr mgr; mg_mgr_init(mgr); mg_log_set(MG_LL_DEBUG); // 調(diào)試期打開能看到握手和幀日志 mg_http_listen(mgr, s_listen_url, fn, NULL); for (;;) { mg_mgr_poll(mgr, 500); } mg_mgr_free(mgr); return 0; }幾個關(guān)鍵點解釋一下。mg_http_match_uri(hm, /ws)判斷請求路徑只有訪問/ws才升級其他路徑返回普通 HTTP 響應(yīng)這樣同一個端口既能跑 WebSocket 又能跑健康檢查。mg_ws_upgrade內(nèi)部會校驗Sec-WebSocket-Key、計算Sec-WebSocket-Accept、返回 101 狀態(tài)碼這些握手細節(jié)庫幫你處理了你不用手寫。MG_EV_WS_OPEN觸發(fā)時握手已經(jīng)完成可以安全地發(fā)第一條消息。MG_EV_WS_MSG里的wm-data是mg_str結(jié)構(gòu)包含 buf 指針和 len 長度注意它不一定以\0結(jié)尾所以拼接時用append(buf, len)而不是當(dāng) C 字符串用。如果你用的是舊版 mongoose把mg_http_listen換成mg_bindmg_ws_upgrade換成mg_set_protocol_http_websocket事件名換成MG_EV_WEBSOCKET_HANDSHAKE_DONE和MG_EV_WEBSOCKET_FRAME邏輯一致。舊版里mg_send_websocket_frame(nc, WEBSOCKET_OP_TEXT, data, len)對應(yīng)新版的mg_ws_send。編譯運行mkdir build cd build cmake .. make ./server看到日志里打印監(jiān)聽 10086 端口就說明起來了。這時候用curl http://127.0.0.1:10086/應(yīng)該返回WebSocket server alive說明 HTTP 部分正常。4. JavaScript 客戶端連接與消息收發(fā)驗證服務(wù)端跑起來后寫前端就簡單了。原生 WebSocket API 只有四個核心回調(diào)onopen、onmessage、onerror、onclose。我建議把重連邏輯也一起寫上因為實際網(wǎng)絡(luò)環(huán)境里斷線是常態(tài)。先給一個最小可用的 HTML 頁面!DOCTYPE html html langzh-CN head meta charsetUTF-8 titleWebSocket 聯(lián)調(diào)/title /head body div idstatus未連接/div input idmsgInput typetext placeholder輸入消息 / button onclicksendMsg()發(fā)送/button button onclickconnect()連接/button pre idlog/pre script let ws null; let reconnectTimer null; let reconnectDelay 1000; const MAX_DELAY 30000; function log(text) { document.getElementById(log).textContent text \n; } function connect() { if (ws ws.readyState WebSocket.OPEN) return; ws new WebSocket(ws://127.0.0.1:10086/ws); ws.onopen function () { document.getElementById(status).textContent 已連接; reconnectDelay 1000; // 連接成功重置退避 log([open] 連接建立); }; ws.onmessage function (event) { log([message] event.data); }; ws.onerror function (event) { log([error] 發(fā)生錯誤); }; ws.onclose function (event) { document.getElementById(status).textContent 已斷開; log([close] code event.code reason event.reason); scheduleReconnect(); }; } function scheduleReconnect() { if (reconnectTimer) return; reconnectTimer setTimeout(function () { reconnectTimer null; log([reconnect] 嘗試重連延遲 reconnectDelay ms); connect(); reconnectDelay Math.min(reconnectDelay * 2, MAX_DELAY); }, reconnectDelay); } function sendMsg() { if (!ws || ws.readyState ! WebSocket.OPEN) { log(未連接無法發(fā)送); return; } const text document.getElementById(msgInput).value; ws.send(text); log([send] text); } connect(); /script /body /html這段代碼里幾個設(shè)計值得說。reconnectDelay從 1 秒開始每次失敗翻倍上限 30 秒這是指數(shù)退避避免服務(wù)端剛重啟時被大量重連打爆。onclose里才觸發(fā)重連onerror只記日志因為 error 之后通常緊跟 close兩個都重連會重復(fù)。readyState判斷用WebSocket.OPEN常量而不是數(shù)字 1可讀性更好。驗證流程把 HTML 保存為client.html用瀏覽器直接打開file:// 協(xié)議下 WebSocket 可以連本地 ws但部分瀏覽器對混合內(nèi)容有限制建議用python3 -m http.server 8080起個靜態(tài)服務(wù)再訪問http://127.0.0.1:8080/client.html。頁面加載后應(yīng)該看到狀態(tài)變成“已連接”日志里出現(xiàn)[open] 連接建立和[message] Connect Success!。在輸入框打字點發(fā)送服務(wù)端會回server echo: 你的內(nèi)容日志里能看到往返。如果你想在服務(wù)端收到消息后調(diào)用模型接口把結(jié)果推回前端可以在MG_EV_WS_MSG分支里加一段 HTTP 客戶端邏輯用mg_http_connect請求https://taotoken.net/api對應(yīng)的接口帶上Authorization: Bearer $TAOTOKEN_API_KEY頭。模型 ID 從環(huán)境變量讀別寫死。這樣前端只管 WebSocket模型調(diào)用和 Key 都在服務(wù)端安全邊界清晰。5. 常見報錯排查401、握手失敗與幀解析異常聯(lián)調(diào)階段最容易卡在幾個固定報錯上我按實際遇到的頻率排一下。401 Unauthorized。這個通常不是 WebSocket 本身的問題而是你在服務(wù)端調(diào)用模型接口時 Key 不對。檢查三件事Key 是否從 API Keys 頁面正確復(fù)制注意前后空格、請求頭是否是Authorization: Bearer sk-xxx格式、Base URL 是否寫成了https://taotoken.net/api而不是帶路徑的完整地址。如果用的是 Codex 的 auth.json 或 Cline MCP 配置確認字段名沒寫錯Base URL、Key、Model ID 三件套要齊全。我見過把api_key寫成apikey導(dǎo)致 401 的對照接入文檔的示例逐字核對。local proxy failed / 握手返回非 101。瀏覽器控制臺報WebSocket connection to ws://... failed先看服務(wù)端日志有沒有收到請求。如果服務(wù)端完全沒日志檢查監(jiān)聽地址是不是0.0.0.0而不是127.0.0.1后者只接受本機回環(huán)某些容器環(huán)境會連不上。如果服務(wù)端收到了但返回 400多半是路徑不匹配確認前端連的是ws://127.0.0.1:10086/ws服務(wù)端判斷的是/ws。舊版 mongoose 如果沒調(diào)mg_set_protocol_http_websocket握手會失敗返回普通 HTTP 響應(yīng)。reading choices 相關(guān)報錯。這個一般出現(xiàn)在你調(diào)模型接口解析響應(yīng)時返回體結(jié)構(gòu)和預(yù)期不符。先打印原始響應(yīng)體看看到底返回了什么別直接按文檔結(jié)構(gòu)取字段。常見原因是模型 ID 寫錯導(dǎo)致返回了錯誤對象或者請求體 JSON 格式有問題。用curl先單獨驗證接口通不通再集成進 C 代碼。幀解析異常 / 收到亂碼。mongoose 的MG_EV_WS_MSG里wm-data不是以\0結(jié)尾的如果你用printf(%s, wm-data.buf)打印后面會帶出內(nèi)存里的臟數(shù)據(jù)。正確做法是用%.*s加長度或者轉(zhuǎn)成std::string(buf, len)。前端側(cè)如果JSON.parse報錯先console.log(event.data)看原始內(nèi)容可能是服務(wù)端發(fā)了非 JSON 的純文本。OAuth 相關(guān)報錯。如果你在配置 Claude Code Anthropic 接入時遇到 OAuth 流程問題確認走的是文檔里說明的接入方式不要混用多套憑證。統(tǒng)一用 TaoToken 的 Key 通道減少變量。排查通用思路先確認 TCP 層通不通telnet 127.0.0.1 10086再確認 HTTP 握手curl -i看 101最后才看 WebSocket 幀。分層定位比一上來就盯著業(yè)務(wù)代碼快得多。6. 把聯(lián)調(diào)跑通之后統(tǒng)一通道下的持續(xù)驗證服務(wù)端和前端能互相收發(fā)消息之后建議做幾輪壓力驗證。開多個瀏覽器標簽同時連觀察 mongoose 的mg_mgr_poll是否穩(wěn)定把服務(wù)端 kill 掉再重啟看前端指數(shù)退避重連是否按預(yù)期工作發(fā)一條超長消息比如 100KB 的字符串確認幀分片和重組沒問題。這些動作能幫你提前發(fā)現(xiàn)只在邊界條件下暴露的 bug。模型調(diào)用側(cè)把 Key 和 Base URL 收進環(huán)境變量或配置文件別散落在代碼里。需要切換模型時只改 Model ID 一個地方。長期跑編碼類任務(wù)的話Coding Plan 的額度管理比按次調(diào)用省心具體在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 看說明。API Keys 的輪換和權(quán)限在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 管理接入細節(jié)查 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。模型對話頁可以用來快速驗證某個模型 ID 是否可用不用改代碼就能試。最后留一個實用技巧在 mongoose 的MG_EV_WS_MSG里加一行日志把收到的幀長度和 opcode 打出來聯(lián)調(diào)期非常有用。上線前把mg_log_set(MG_LL_DEBUG)改成MG_LL_ERROR避免日志刷屏。WebSocket 本身不復(fù)雜復(fù)雜的是連接生命周期管理和錯誤邊界把這兩塊處理好剩下的就是業(yè)務(wù)邏輯了。 WebSocket詳解：前端js客戶端與C++使用mongoose.cpp創(chuàng)建服務(wù)端通信示例（TaoToken統(tǒng)一Key/API通道實踐）
1. 從輪詢到全雙工為什么前端和 C 服務(wù)端需要 WebSocket如果你做過設(shè)備控制面板、實時日志看板或者在線協(xié)作工具大概率遇到過這樣的場景前端點一下按鈕后端要花幾秒處理處理完還得讓前端知道結(jié)果。用 HTTP 輪詢的話前端只能每隔一兩秒問一次“好了沒”問十次有九次是白問帶寬和 CPU 都浪費在重復(fù)的請求頭上。WebSocket 解決的正是這個問題——它基于 TCP用一次 HTTP 握手把連接升級成全雙工通道之后客戶端和服務(wù)端任何一方都能主動推消息不需要誰先問誰后答。這篇文章聚焦一個很具體的組合前端用原生 JavaScript 的 WebSocket 客戶端服務(wù)端用 C 的 mongoose.cpp 網(wǎng)絡(luò)庫。mongoose 是一個單文件、事件驅(qū)動、非阻塞的 C 網(wǎng)絡(luò)庫把 mongoose.h 和 mongoose.cpp 拖進項目就能編譯特別適合嵌入式網(wǎng)關(guān)、桌面工具后端或者需要跟硬件打交道的場景。我會把握手細節(jié)、幀結(jié)構(gòu)、斷線重連、以及怎么通過 TaoToken 統(tǒng)一 Key/API 通道做聯(lián)調(diào)驗證全部拆成可復(fù)制的步驟。適合誰看有基本 C 編譯能力、寫過一點前端 JS、想搞懂 WebSocket 底層而不是只會調(diào)庫的開發(fā)者。讀完之后你能自己搭一個本地 ws 服務(wù)用瀏覽器頁面收發(fā)消息并且知道 401、握手失敗、幀解析異常這些坑怎么排。2. TaoToken 統(tǒng)一 Key/API 通道聯(lián)調(diào)前的環(huán)境準備在動手寫 mongoose 服務(wù)端之前先把聯(lián)調(diào)環(huán)境理順。很多同學(xué)卡住不是因為 WebSocket 代碼寫錯而是 Key 管理混亂、Base URL 填錯、模型 ID 對不上。TaoToken 提供統(tǒng)一 Key 和 API 通道把模型對話、Coding Plan、控制臺、API Keys 管理都收在同一個入口省得你在多個平臺之間來回切換。先明確幾個地址后面配置里會反復(fù)用到官網(wǎng)入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基地址https://taotoken.net/api模型對話頁https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite控制臺https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文檔https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteClaude Code Anthropic 接入https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite為什么 WebSocket 聯(lián)調(diào)要提這些因為你的 mongoose 服務(wù)端往往不只是轉(zhuǎn)發(fā)消息它可能還要在收到前端指令后去調(diào)用模型接口做推理再把結(jié)果推回前端。這時候統(tǒng)一 Key 就派上用場了一個 Key 走通模型調(diào)用和業(yè)務(wù)接口不用為每個服務(wù)單獨申請憑證。我試過把 Key 散落在多個配置文件里后來排查一個 401 花了半小時最后發(fā)現(xiàn)是某個服務(wù)讀的是舊 Key。統(tǒng)一管理之后這類問題基本消失。操作上先去 API Keys 頁面生成一個 Key復(fù)制保存好它只會完整顯示一次。然后確認你要用的模型 ID在模型對話頁能看到當(dāng)前可用的模型列表。如果你打算長期跑編碼類 AgentCoding Plan 頁面有對應(yīng)的套餐說明按需選擇即可。接入文檔里有完整的請求示例和參數(shù)說明遇到字段不確定的時候優(yōu)先查文檔比在群里問快得多。環(huán)境變量建議這樣組織避免硬編碼進代碼export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_MODEL_ID你的模型IDC 側(cè)讀取環(huán)境變量用std::getenvJS 側(cè)在瀏覽器里沒法直接讀環(huán)境變量所以前端只負責(zé) WebSocket 通信模型調(diào)用放在 mongoose 服務(wù)端做Key 不暴露給瀏覽器。這一點很重要任何寫在前端 JS 里的 Key 都等于公開別這么干。3. mongoose.cpp 服務(wù)端可復(fù)制配置與握手實現(xiàn)現(xiàn)在進入正題。mongoose 的版本迭代比較快網(wǎng)上很多老代碼用的是mg_bind、mg_set_protocol_http_websocket這套 API新版本改成了mg_http_listen和事件回調(diào)里判斷MG_EV_WS_OPEN、MG_EV_WS_MSG。我這里給一份兼容性較好的寫法同時說明新舊差異你按自己下載的版本調(diào)整。先看項目結(jié)構(gòu)保持簡單ws_demo/ ├── mongoose.h ├── mongoose.c // 或 mongoose.cpp ├── server.cpp └── CMakeLists.txtmongoose 是單文件庫把 .h 和 .c/.cpp 放進目錄即可。用 CMake 編譯cmake_minimum_required(VERSION 3.10) project(ws_demo CXX) set(CMAKE_CXX_STANDARD 17) add_executable(server server.cpp mongoose.c) target_link_libraries(server pthread)服務(wù)端核心代碼我按新版 API 寫同時把舊版對應(yīng)關(guān)系注釋清楚#include mongoose.h #include string #include cstring static const char *s_listen_url http://0.0.0.0:10086; // 每個連接的私有數(shù)據(jù)用來標記是否已完成 WebSocket 升級 struct ConnState { bool is_ws false; }; static void fn(struct mg_connection *c, int ev, void *ev_data) { if (ev MG_EV_OPEN) { c-data[0] 0; // 初始化標記 } else if (ev MG_EV_HTTP_MSG) { // 收到 HTTP 請求嘗試升級為 WebSocket struct mg_http_message *hm (struct mg_http_message *) ev_data; if (mg_http_match_uri(hm, /ws)) { mg_ws_upgrade(c, hm, NULL); c-data[0] 1; // 標記為 WebSocket 連接 } else { mg_http_reply(c, 200, Content-Type: text/plain\r\n, WebSocket server alive\n); } } else if (ev MG_EV_WS_OPEN) { // 握手完成舊版對應(yīng) MG_EV_WEBSOCKET_HANDSHAKE_DONE const char *hello Connect Success!; mg_ws_send(c, hello, strlen(hello), WEBSOCKET_OP_TEXT); } else if (ev MG_EV_WS_MSG) { // 收到 WebSocket 數(shù)據(jù)幀舊版對應(yīng) MG_EV_WEBSOCKET_FRAME struct mg_ws_message *wm (struct mg_ws_message *) ev_data; // 回顯收到的內(nèi)容并附加服務(wù)端標識 std::string reply server echo: ; reply.append(wm-data.buf, wm-data.len); mg_ws_send(c, reply.c_str(), reply.size(), WEBSOCKET_OP_TEXT); } else if (ev MG_EV_CLOSE) { // 連接關(guān)閉可在這里做資源清理 } } int main() { struct mg_mgr mgr; mg_mgr_init(mgr); mg_log_set(MG_LL_DEBUG); // 調(diào)試期打開能看到握手和幀日志 mg_http_listen(mgr, s_listen_url, fn, NULL); for (;;) { mg_mgr_poll(mgr, 500); } mg_mgr_free(mgr); return 0; }幾個關(guān)鍵點解釋一下。mg_http_match_uri(hm, /ws)判斷請求路徑只有訪問/ws才升級其他路徑返回普通 HTTP 響應(yīng)這樣同一個端口既能跑 WebSocket 又能跑健康檢查。mg_ws_upgrade內(nèi)部會校驗Sec-WebSocket-Key、計算Sec-WebSocket-Accept、返回 101 狀態(tài)碼這些握手細節(jié)庫幫你處理了你不用手寫。MG_EV_WS_OPEN觸發(fā)時握手已經(jīng)完成可以安全地發(fā)第一條消息。MG_EV_WS_MSG里的wm-data是mg_str結(jié)構(gòu)包含 buf 指針和 len 長度注意它不一定以\0結(jié)尾所以拼接時用append(buf, len)而不是當(dāng) C 字符串用。如果你用的是舊版 mongoose把mg_http_listen換成mg_bindmg_ws_upgrade換成mg_set_protocol_http_websocket事件名換成MG_EV_WEBSOCKET_HANDSHAKE_DONE和MG_EV_WEBSOCKET_FRAME邏輯一致。舊版里mg_send_websocket_frame(nc, WEBSOCKET_OP_TEXT, data, len)對應(yīng)新版的mg_ws_send。編譯運行mkdir build cd build cmake .. make ./server看到日志里打印監(jiān)聽 10086 端口就說明起來了。這時候用curl http://127.0.0.1:10086/應(yīng)該返回WebSocket server alive說明 HTTP 部分正常。4. JavaScript 客戶端連接與消息收發(fā)驗證服務(wù)端跑起來后寫前端就簡單了。原生 WebSocket API 只有四個核心回調(diào)onopen、onmessage、onerror、onclose。我建議把重連邏輯也一起寫上因為實際網(wǎng)絡(luò)環(huán)境里斷線是常態(tài)。先給一個最小可用的 HTML 頁面!DOCTYPE html html langzh-CN head meta charsetUTF-8 titleWebSocket 聯(lián)調(diào)/title /head body div idstatus未連接/div input idmsgInput typetext placeholder輸入消息 / button onclicksendMsg()發(fā)送/button button onclickconnect()連接/button pre idlog/pre script let ws null; let reconnectTimer null; let reconnectDelay 1000; const MAX_DELAY 30000; function log(text) { document.getElementById(log).textContent text \n; } function connect() { if (ws ws.readyState WebSocket.OPEN) return; ws new WebSocket(ws://127.0.0.1:10086/ws); ws.onopen function () { document.getElementById(status).textContent 已連接; reconnectDelay 1000; // 連接成功重置退避 log([open] 連接建立); }; ws.onmessage function (event) { log([message] event.data); }; ws.onerror function (event) { log([error] 發(fā)生錯誤); }; ws.onclose function (event) { document.getElementById(status).textContent 已斷開; log([close] code event.code reason event.reason); scheduleReconnect(); }; } function scheduleReconnect() { if (reconnectTimer) return; reconnectTimer setTimeout(function () { reconnectTimer null; log([reconnect] 嘗試重連延遲 reconnectDelay ms); connect(); reconnectDelay Math.min(reconnectDelay * 2, MAX_DELAY); }, reconnectDelay); } function sendMsg() { if (!ws || ws.readyState ! WebSocket.OPEN) { log(未連接無法發(fā)送); return; } const text document.getElementById(msgInput).value; ws.send(text); log([send] text); } connect(); /script /body /html這段代碼里幾個設(shè)計值得說。reconnectDelay從 1 秒開始每次失敗翻倍上限 30 秒這是指數(shù)退避避免服務(wù)端剛重啟時被大量重連打爆。onclose里才觸發(fā)重連onerror只記日志因為 error 之后通常緊跟 close兩個都重連會重復(fù)。readyState判斷用WebSocket.OPEN常量而不是數(shù)字 1可讀性更好。驗證流程把 HTML 保存為client.html用瀏覽器直接打開file:// 協(xié)議下 WebSocket 可以連本地 ws但部分瀏覽器對混合內(nèi)容有限制建議用python3 -m http.server 8080起個靜態(tài)服務(wù)再訪問http://127.0.0.1:8080/client.html。頁面加載后應(yīng)該看到狀態(tài)變成“已連接”日志里出現(xiàn)[open] 連接建立和[message] Connect Success!。在輸入框打字點發(fā)送服務(wù)端會回server echo: 你的內(nèi)容日志里能看到往返。如果你想在服務(wù)端收到消息后調(diào)用模型接口把結(jié)果推回前端可以在MG_EV_WS_MSG分支里加一段 HTTP 客戶端邏輯用mg_http_connect請求https://taotoken.net/api對應(yīng)的接口帶上Authorization: Bearer $TAOTOKEN_API_KEY頭。模型 ID 從環(huán)境變量讀別寫死。這樣前端只管 WebSocket模型調(diào)用和 Key 都在服務(wù)端安全邊界清晰。5. 常見報錯排查401、握手失敗與幀解析異常聯(lián)調(diào)階段最容易卡在幾個固定報錯上我按實際遇到的頻率排一下。401 Unauthorized。這個通常不是 WebSocket 本身的問題而是你在服務(wù)端調(diào)用模型接口時 Key 不對。檢查三件事Key 是否從 API Keys 頁面正確復(fù)制注意前后空格、請求頭是否是Authorization: Bearer sk-xxx格式、Base URL 是否寫成了https://taotoken.net/api而不是帶路徑的完整地址。如果用的是 Codex 的 auth.json 或 Cline MCP 配置確認字段名沒寫錯Base URL、Key、Model ID 三件套要齊全。我見過把api_key寫成apikey導(dǎo)致 401 的對照接入文檔的示例逐字核對。local proxy failed / 握手返回非 101。瀏覽器控制臺報WebSocket connection to ws://... failed先看服務(wù)端日志有沒有收到請求。如果服務(wù)端完全沒日志檢查監(jiān)聽地址是不是0.0.0.0而不是127.0.0.1后者只接受本機回環(huán)某些容器環(huán)境會連不上。如果服務(wù)端收到了但返回 400多半是路徑不匹配確認前端連的是ws://127.0.0.1:10086/ws服務(wù)端判斷的是/ws。舊版 mongoose 如果沒調(diào)mg_set_protocol_http_websocket握手會失敗返回普通 HTTP 響應(yīng)。reading choices 相關(guān)報錯。這個一般出現(xiàn)在你調(diào)模型接口解析響應(yīng)時返回體結(jié)構(gòu)和預(yù)期不符。先打印原始響應(yīng)體看看到底返回了什么別直接按文檔結(jié)構(gòu)取字段。常見原因是模型 ID 寫錯導(dǎo)致返回了錯誤對象或者請求體 JSON 格式有問題。用curl先單獨驗證接口通不通再集成進 C 代碼。幀解析異常 / 收到亂碼。mongoose 的MG_EV_WS_MSG里wm-data不是以\0結(jié)尾的如果你用printf(%s, wm-data.buf)打印后面會帶出內(nèi)存里的臟數(shù)據(jù)。正確做法是用%.*s加長度或者轉(zhuǎn)成std::string(buf, len)。前端側(cè)如果JSON.parse報錯先console.log(event.data)看原始內(nèi)容可能是服務(wù)端發(fā)了非 JSON 的純文本。OAuth 相關(guān)報錯。如果你在配置 Claude Code Anthropic 接入時遇到 OAuth 流程問題確認走的是文檔里說明的接入方式不要混用多套憑證。統(tǒng)一用 TaoToken 的 Key 通道減少變量。排查通用思路先確認 TCP 層通不通telnet 127.0.0.1 10086再確認 HTTP 握手curl -i看 101最后才看 WebSocket 幀。分層定位比一上來就盯著業(yè)務(wù)代碼快得多。6. 把聯(lián)調(diào)跑通之后統(tǒng)一通道下的持續(xù)驗證服務(wù)端和前端能互相收發(fā)消息之后建議做幾輪壓力驗證。開多個瀏覽器標簽同時連觀察 mongoose 的mg_mgr_poll是否穩(wěn)定把服務(wù)端 kill 掉再重啟看前端指數(shù)退避重連是否按預(yù)期工作發(fā)一條超長消息比如 100KB 的字符串確認幀分片和重組沒問題。這些動作能幫你提前發(fā)現(xiàn)只在邊界條件下暴露的 bug。模型調(diào)用側(cè)把 Key 和 Base URL 收進環(huán)境變量或配置文件別散落在代碼里。需要切換模型時只改 Model ID 一個地方。長期跑編碼類任務(wù)的話Coding Plan 的額度管理比按次調(diào)用省心具體在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 看說明。API Keys 的輪換和權(quán)限在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 管理接入細節(jié)查 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。模型對話頁可以用來快速驗證某個模型 ID 是否可用不用改代碼就能試。最后留一個實用技巧在 mongoose 的MG_EV_WS_MSG里加一行日志把收到的幀長度和 opcode 打出來聯(lián)調(diào)期非常有用。上線前把mg_log_set(MG_LL_DEBUG)改成MG_LL_ERROR避免日志刷屏。WebSocket 本身不復(fù)雜復(fù)雜的是連接生命周期管理和錯誤邊界把這兩塊處理好剩下的就是業(yè)務(wù)邏輯了。