1. 为什么要在 Qt 与嵌入式端之间用 mongoose + websocket + protobuf

如果你正在做 Qt 上位机 + 嵌入式设备（MCU、Linux 小板子、工控盒子）的通讯，大概率会遇到这几个问题：串口太慢、TCP 裸包要自己处理粘包、JSON 体积大且解析吃内存。mongoose 这个库刚好卡在一个很舒服的位置——它只有一个mongoose.h和一个mongoose.c，拖进工程就能编译，同时内置了 websocket 客户端/服务端、事件循环、定时器，不用再拉一堆依赖。再配上 protobuf 做二进制序列化，一条消息能压到几十字节，嵌入式端解析也不费劲。

这套组合适合谁？适合手上有 Qt 客户端、又要在资源受限设备上跑通讯链路的同学。典型场景是：设备端用 mongoose 起一个 websocket client（或者反过来做 server），Qt 端用QWebSocketServer接收，双方约定用 protobuf 定义消息体，文本通道传控制指令、二进制通道传结构化数据。我试过在几百 KB 内存的设备上跑这套，只要不一次性发超大包，稳定性是够的。

这里有个容易踩的坑：很多人一上来就把 protobuf 消息直接reinterpret_cast成结构体发出去，结果跨平台对齐不一样，接收端读出来全是乱码。正确做法是老老实实用SerializeToArray/ParseFromArray，让 protobuf 自己管字节序和字段编码。下面我会把 config.toml、settings.json 骨架、.proto 定义、收发联调、报错排查一条龙写清楚，你照着改就能跑通最小闭环。

另外提一句，如果你后面要把这套链路接到大模型能力上（比如设备端语音指令转文本、Qt 端做 Agent 调度），模型调用这一层可以用 TaoToken 统一走 API，省得每个端各配一套 Key。这个放到最后说，先把通讯本身跑通。

2. mongoose 与 Qt 双端环境准备：config.toml 与 settings.json 骨架

先把工程骨架定下来。mongoose 的集成方式很简单：把mongoose.h和mongoose.c放到third_party/mongoose/下，Qt 的.pro里加一行SOURCES += third_party/mongoose/mongoose.c，再INCLUDEPATH += third_party/mongoose就行。protobuf 那边需要先编译出静态库，.pro里链接libprotobuf-lite（用LITE_RUNTIME能显著减小体积）。

为了让配置不写死在代码里，我习惯用两个配置文件：设备端（mongoose 侧）用config.toml，Qt 侧用settings.json。这样换 IP、换端口、换心跳间隔不用重新编译。

先看设备端的config.toml：

# config.toml - mongoose 客户端侧配置 [server] url = "ws://192.168.1.100:8000/websocket" reconnect_interval_ms = 3000 handshake_timeout_ms = 5000 [heartbeat] enabled = true interval_ms = 10000 payload = "ping" [proto] max_message_bytes = 65535 binary_channel = true [log] level = "info"

再看 Qt 服务端的settings.json：

{ "server": { "listen_address": "0.0.0.0", "port": 8000, "name": "WSSERVER", "secure_mode": false }, "proto": { "max_message_bytes": 65535, "schema_version": "1.0.0" }, "heartbeat": { "timeout_ms": 30000 } }

这两个文件的关键字段要对应上：url里的端口必须等于settings.json的port，max_message_bytes两边保持一致，否则大包会被截断。secure_mode为 false 时走ws://，mongoose 侧用mg_ws_connect即可；如果要上wss://，mongoose 需要开MG_ENABLE_OPENSSL，Qt 侧换成QWebSocketServer::SecureMode并加载证书，这一步先不展开，最小闭环用明文就够。

protobuf 的.proto文件建议单独放一个proto/目录，编译命令统一走脚本：

protoc --cpp_out=./generated proto/ubasestruct.proto

生成ubasestruct.pb.h和ubasestruct.pb.cc后，Qt 的.pro里这样写：

INCLUDEPATH += $$PWD/generated $$PWD/third_party/protobuf/include HEADERS += $$PWD/generated/ubasestruct.pb.h SOURCES += $$PWD/generated/ubasestruct.pb.cc LIBS += -L$$PWD/third_party/protobuf/lib -lprotobuf-lite

设备端如果是 CMake 工程，对应写target_link_libraries(your_app protobuf-lite mongoose)就行。环境准备好之后，下一步就是定义消息体，这是整条链路能不能对齐的核心。

3. protobuf 消息定义与可复制配置片段

消息定义决定了双端能不能对上。我建议把登录、心跳、数据上报分成独立 message，用oneof做统一信封，这样以后加消息类型不用改解析逻辑。先写proto/ubasestruct.proto：

syntax = "proto3"; package WS; option optimize_for = LITE_RUNTIME; message req_login { string username = 1; string password = 2; } message heartbeat { uint64 timestamp_ms = 1; string device_id = 2; } message sensor_data { uint32 channel = 1; double value = 2; uint64 ts = 3; } message envelope { uint32 seq = 1; oneof payload { req_login login = 2; heartbeat hb = 3; sensor_data sensor = 4; } }

optimize_for = LITE_RUNTIME很关键，它砍掉了反射和描述符，生成的库小很多，嵌入式端友好。字段编号一旦发布就别改，改编号等于破坏兼容。

编译后，mongoose 客户端发送 protobuf 数据的核心代码是这样：

#include "mongoose.h" #include "ubasestruct.pb.h" static void fn(struct mg_connection *c, int ev, void *ev_data, void *fn_data) { if (ev == MG_EV_WS_OPEN) { WS::envelope env; env.set_seq(1); WS::req_login *login = env.mutable_login(); login->set_username("device_01"); login->set_password("token_abc"); int size = env.ByteSizeLong(); char *buf = (char *) malloc(size); env.SerializeToArray(buf, size); mg_ws_send(c, buf, size, WEBSOCKET_OP_BINARY); free(buf); } else if (ev == MG_EV_WS_MSG) { struct mg_ws_message *wm = (struct mg_ws_message *) ev_data; WS::envelope env; if (env.ParseFromArray(wm->data.ptr, wm->data.len)) { if (env.has_login()) { LOG(LL_INFO, ("login ack: %s", env.login().username().c_str())); } } } }

Qt 服务端接收并反序列化：

QObject::connect(pSocket, &QWebSocket::binaryMessageReceived, [](const QByteArray &message) { WS::envelope env; if (!env.ParseFromArray(message.constData(), message.size())) { qWarning() << "parse error, size =" << message.size(); return; } if (env.has_login()) { qDebug() << "user:" << QString::fromStdString(env.login().username()) << "pwd:" << QString::fromStdString(env.login().password()); } });

这里有个细节：ParseFromArray的第二个参数是字节数，不是QByteArray::count()之外的东西，两者一致。如果你用message.data()在 Qt5 里返回的是char*，Qt6 返回const char*，传参时注意 const 正确性，否则编译报错。

配置片段汇总一下，方便你直接抄：

两边max_message_bytes必须一致，心跳超时建议是间隔的 2~3 倍，避免网络抖动误判断线。

4. 完整收发联调：从握手到 protobuf 回包验证

配置和消息定义都齐了，现在跑一次完整联调。顺序是：先起 Qt 服务端，再起 mongoose 客户端，观察握手、发送、接收三个阶段。

Qt 服务端启动代码：

QWebSocketServer server(QString("WSSERVER"), QWebSocketServer::NonSecureMode); if (!server.listen(QHostAddress::Any, 8000)) { qCritical() << "listen failed:" << server.errorString(); return -1; } qDebug() << "server listening on 8000"; QObject::connect(&server, &QWebSocketServer::newConnection, [&server]() { QWebSocket *pSocket = server.nextPendingConnection(); qDebug() << "client connected:" << pSocket->peerAddress().toString(); QObject::connect(pSocket, &QWebSocket::binaryMessageReceived, [pSocket](const QByteArray &message) { WS::envelope env; if (!env.ParseFromArray(message.constData(), message.size())) { qWarning() << "parse error"; return; } // 回一个 ack WS::envelope ack; ack.set_seq(env.seq()); ack.mutable_login()->set_username("server_ack"); int size = ack.ByteSizeLong(); QByteArray out(size, 0); ack.SerializeToArray(out.data(), size); pSocket->sendBinaryMessage(out); }); QObject::connect(pSocket, &QWebSocket::disconnected, []() { qDebug() << "client disconnected"; }); });

mongoose 客户端主循环：

int main(void) { struct mg_mgr mgr; mg_mgr_init(&mgr); struct mg_connection *c = mg_ws_connect(&mgr, "ws://192.168.1.100:8000/websocket", fn, NULL, NULL); if (c == NULL) { LOG(LL_ERROR, ("connect failed")); return -1; } for (;;) { mg_mgr_poll(&mgr, 1000); } mg_mgr_free(&mgr); return 0; }

联调时你会看到这样的输出。Qt 端：

server listening on 8000 client connected: "192.168.1.50" user: "device_01" pwd: "token_abc"

mongoose 端：

login ack: server_ack

到这里最小闭环就跑通了。验证要点有三个：一是MG_EV_WS_OPEN触发说明握手成功，如果一直不触发，多半是 URL 路径不对（/websocket要和 Qt 端QWebSocketServer的路径匹配，Qt 默认接受任意路径，但 mongoose 会带上）；二是ParseFromArray返回 true 说明字节流对齐；三是回包能收到说明双向通道都通。

如果你想再压测一下，可以在MG_EV_WS_OPEN里循环发 100 条sensor_data，观察 Qt 端是否全部解析成功。注意别超过max_message_bytes，超了 websocket 会分帧，mongoose 的MG_EV_WS_MSG可能一次只给一帧，需要自己做粘包处理——这也是为什么建议单条消息控制在 64KB 以内。

5. 常见报错排查：401、local proxy failed、reading choices、OAuth

联调阶段最容易卡在几个固定报错上，我按出现频率排一下。

握手失败 / 连接被拒：mongoose 端打印MG_EV_ERROR，内容是connect failed或Connection refused。先确认 Qt 服务端listen返回 true，再确认防火墙没拦 8000 端口。如果是跨网段，ping一下设备到 PC 的连通性。这个错误和local proxy failed类似，后者通常出现在你给 mongoose 配了http_proxy环境变量但代理不可达，清掉环境变量即可。

401 Unauthorized：如果你在 websocket 握手时带了 token，Qt 端校验失败会返回 401。mongoose 侧表现为MG_EV_ERROR里带401。检查config.toml里的 token 和 Qt 端校验逻辑是否一致。注意 websocket 的 401 是在 HTTP Upgrade 阶段返回的，不是消息层。

reading choices 报错：这个一般出现在 protobuf 解析时，ParseFromArray返回 false 且日志里有reading choices字样。原因是发送端和接收端的.proto版本不一致，字段编号对不上。解决办法是双端用同一份.proto重新protoc生成，别手动改生成文件。

OAuth 相关报错：如果你把这条链路接到需要 OAuth 的模型服务上，token 过期会返回 401 或invalid_token。这时候别在 mongoose 里硬编码 token，改成从config.toml读取并支持刷新。模型调用这层建议统一走 TaoToken 的 API，它的 Key 管理在控制台里，换 Key 不用改设备固件。

二进制包解析出乱码：九成是发送端用了WEBSOCKET_OP_TEXT发 protobuf 数据。protobuf 是二进制，必须用WEBSOCKET_OP_BINARY，Qt 端对应binaryMessageReceived信号。文本通道只用来传 JSON 控制指令或心跳字符串。

心跳超时误判断线：settings.json里timeout_ms设太小，网络一抖就断。建议设成心跳间隔的 3 倍，并且 mongoose 侧在MG_EV_WS_MSG里收到任何消息都刷新一次计时。

排查时养成看两端日志的习惯：mongoose 用LOG(LL_ERROR, ...)打错误，Qt 用qWarning()打解析失败。两边日志时间戳对一下，能快速定位是发送端没发出去还是接收端没解析。

6. 把通讯链路接到模型能力：TaoToken 接入与 CTA

通讯跑通之后，很多同学下一步就是让设备端能调用大模型——比如语音指令转文本、Qt 端做 Agent 调度。这时候建议把模型调用这层单独抽出来，用 TaoToken 统一走 API，设备端只负责发 protobuf 消息，Qt 端或网关层负责调模型。

接入方式很简单，在 Qt 侧用QNetworkAccessManager发 HTTP 请求即可。Base URL 用https://taotoken.net/api，Key 在控制台的 API Keys 页面生成，Model ID 按你需要的模型填。三件套配齐：

• Base URL：https://taotoken.net/api
• API Key：控制台生成
• Model ID：按需选择

如果你用的是 Claude Code 做开发辅助，可以走 Coding Plan，长期编码和 Agent 场景更划算。想先验证模型通不通，直接用模型对话页面测一条请求最快。接入文档里有各语言的示例，照着改就行。

设备端这边，建议把模型请求封装成一个 protobuf message，比如llm_request和llm_response，通过 websocket 转发给 Qt 网关，网关再调 TaoToken API。这样设备固件不用内置 HTTP 栈，省内存。实测下来，一条 200 字节的 protobuf 请求经网关转发到模型，端到端延迟主要花在模型推理上，通讯本身可以忽略。

最后留个实用技巧：mongoose 的mg_mgr_poll超时别设太大，1000ms 足够，设太大断线重连反应慢；Qt 的QWebSocketServer记得在析构时close()，否则端口释放不及时，重启会报Address already in use。这两点踩过一次就记住了。