深入解析 WebSocket 协议原理，对比其与 HTTP 的差异，详述握手流程、数据帧结构及关闭机制。基于 libwebsockets 库提供 C++ 服务端与客户端完整代码，涵盖连接管理、回声响应、心跳保活及断线重连。同时介绍 WSS 安全配置、Nginx 反向代理及常见工程问题排查方案。
WebSocket 是 HTML5 规范定义的基于 TCP 的全双工、双向、持久化应用层通信协议（RFC 6455），核心解决了 HTTP 协议'请求 - 响应'半双工模型无法满足实时通信需求的痛点。
HTTP 协议自设计之初就围绕'客户端请求、服务端响应'的单向模型，在实时通信场景（如聊天、行情推送、物联网数据上报）中存在致命问题：
| 特性 | HTTP | WebSocket |
|---|---|---|
| 通信方向 | 客户端主动请求，服务端被动响应 | 全双工，双向主动通信 |
| 连接状态 | 短连接（Keep-Alive 仅延长） | 持久连接（主动关闭前一直存活） |
| 头部开销 | 大（包含 Cookie、User-Agent 等） | 极小（最小 2 字节帧头） |
| 主动推送 | 不支持 | 原生支持 |
| 数据格式 | 需封装 HTTP 头，仅文本/二进制 | 帧化数据（文本/二进制/控制帧） |
| 关闭方式 | 响应完成后自动关闭 | 协商式关闭（Close 帧） |
WebSocket 连接的建立依赖 HTTP 101（Switching Protocols）升级机制，全程基于 TCP 连接（默认端口 80，WSS 为 443），分为'客户端请求'和'服务端验证响应'两步：
客户端向服务端发送 HTTP GET 请求，核心头字段决定了升级能否成功：
GET /chat HTTP/1.1
Host: example.com:8080
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
Sec-WebSocket-Protocol: chat
Sec-WebSocket-Extensions: permessage-deflate
服务端必须完成 Sec-WebSocket-Key 的验证，否则客户端会拒绝建立连接：
Sec-WebSocket-Key 与固定 UUID 字符串 258EAFA5-E914-47DA-95CA-C5AB0DC85B11 拼接；Sec-WebSocket-Accept；HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Protocol: chat
握手成功后，TCP 连接从 HTTP 协议切换为 WebSocket 协议，后续所有通信均使用 WebSocket 帧格式。
WebSocket 所有数据（文本、二进制、控制指令）均封装为'帧（Frame）'传输，帧格式是协议的核心，每个字段的含义和规则必须严格遵守：
| 字段 | 长度（位） | 核心含义与规则 |
|---|---|---|
| FIN | 1 | 帧结束标记：1=当前帧是消息最后一帧；0=消息分片，后续还有帧 |
| RSV1/RSV2/RSV3 | 1*3 | 保留位，仅启用扩展时非 0（如 permessage-deflate 用 RSV1），未启用时必须为 0（否则关闭连接） |
| Opcode | 4 | 帧类型： |
| 0=继续帧（分片消息的后续帧） | ||
| 1=文本帧（UTF-8 编码） | ||
| 2=二进制帧 | ||
| 8=关闭帧 | ||
| 9=Ping 帧（心跳） | ||
| 10=Pong 帧（心跳响应） | ||
| Mask | 1 | 掩码标记：客户端发的帧必须为 1（需掩码加密），服务端发的帧必须为 0（无需掩码） |
| Payload len | 7/7+16/7+64 | 负载长度： |
| 0~125=直接表示长度； | ||
| 126=后续 2 字节（16 位无符号整数）表示长度； | ||
| 127=后续 8 字节（64 位无符号整数）表示长度 | ||
| Masking-key | 0/32 | 掩码密钥：仅 Mask=1 时存在（4 字节），客户端用于加密负载数据 |
| Payload data | 可变 | 实际传输的数据（文本/二进制/控制指令），Mask=1 时需用 Masking-key 解密 |
客户端发送的所有数据帧必须用 Masking-key 加密，解密公式为：
decoded_byte = encoded_byte ^ masking_key[i % 4]
其中 i 是负载数据的字节索引，%4 表示掩码密钥 4 字节循环使用。示例：
0x41（字符'A'）0x1F0x41 ^ 0x1F = 0x5E（字符'^'）服务端接收后需反向解密，而服务端发送的帧无需掩码，客户端可直接解析。
当消息体积较大时，可拆分为多个帧传输：
WebSocket 禁止直接断开 TCP 连接，必须通过'Close 帧'完成协商式关闭，避免数据丢失：
| 状态码 | 含义 | 适用场景 |
|---|---|---|
| 1000 | 正常关闭 | 业务完成后主动关闭 |
| 1001 | 端点离开 | 客户端关闭浏览器/服务端停机 |
| 1002 | 协议错误 | 帧格式非法/Opcode 不支持 |
| 1003 | 不支持的数据类型 | 接收非 UTF8 的文本帧 |
| 1006 | 连接异常关闭 | TCP 连接被强制断开（非协商） |
| 1011 | 服务端内部错误 | 服务端处理消息时崩溃 |
由于 NAT 超时、防火墙清理、网络波动等原因，WebSocket 连接可能出现'假死'（TCP 连接存在但无法通信），需通过 Ping/Pong 帧实现心跳：
C++ 无原生 WebSocket 库，主流选择有两个：
本文以libwebsockets为例（工业界更常用），提供完整的服务端和客户端实现。
# 安装依赖（SSL/压缩/线程）
sudo apt install libssl-dev libz-dev libpthread-stubs0-dev # Ubuntu/Debian
brew install openssl zlib # macOS
# 编译安装 libwebsockets
git clone https://github.com/warmcat/libwebsockets.git
cd libwebsockets && mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=/usr/local -DLWS_WITH_SSL=ON ..
make -j4 && sudo make install
以下代码实现了一个完整的 WebSocket 服务端，支持客户端连接管理、消息回声、心跳保活、协商式关闭：
#include <libwebsockets.h>
#include <string.h>
#include <unistd.h>
#include <vector>
#include <mutex>
// 全局变量：客户端连接管理（线程安全）
std::vector<struct lws*> g_clients;
std::mutex g_client_mutex;
// 心跳配置：30 秒未收到 Pong 则关闭连接
#define HEARTBEAT_INTERVAL 30
#define HEARTBEAT_TIMEOUT 10
// 每个客户端的上下文数据（存储心跳时间）
struct PerClientData {
time_t last_pong_time; // 最后一次收到 Pong 的时间
};
/**
* @brief WebSocket 事件回调函数（核心）
* @param wsi 连接句柄
* @param reason 事件类型
* @param user 自定义数据（PerClientData）
* @param in 输入数据
* @param len 输入数据长度
*/
static int ws_callback(struct lws* wsi, enum lws_callback_reasons reason, void* user, void* in, size_t len) {
PerClientData *client_data = (PerClientData*)user;
switch(reason) {
// 新客户端连接建立
case LWS_CALLBACK_ESTABLISHED: {
std::lock_guard<std::mutex> lock(g_client_mutex);
g_clients.push_back(wsi);
client_data->last_pong_time = time(NULL); // 初始化心跳时间
lwsl_notice("Client connected: %p, total clients: %zu\n", wsi, g_clients.size());
break;
}
// 收到客户端数据帧
case LWS_CALLBACK_RECEIVE: {
// libwebsockets 要求数据缓冲区预留 LWS_PRE 字节（避免内存越界）
char buf[LWS_PRE + 4096] = {0};
memcpy(buf + LWS_PRE, in, len);
lwsl_notice("Received from client %p: %s (len: %zu)\n", wsi, buf + LWS_PRE, len);
// 回声响应：将收到的消息回发给客户端
int ret = lws_write(wsi, (unsigned char*)buf + LWS_PRE, len, LWS_WRITE_TEXT);
if(ret < 0) {
lwsl_err("Failed to write to client %p\n", wsi);
}
break;
}
// 收到 Ping 帧（客户端心跳）
case LWS_CALLBACK_SERVER_PING: {
client_data->last_pong_time = time(NULL); // 更新心跳时间
lwsl_notice("Received Ping from client %p\n", wsi);
// libwebsockets 自动回复 Pong 帧，无需手动处理
break;
}
// 定时检查心跳（由 lws_service 触发）
case LWS_CALLBACK_SERVER_HEARTBEAT: {
std::lock_guard<std::mutex> lock(g_client_mutex);
time_t now = time(NULL);
for(auto it = g_clients.begin(); it != g_clients.end();) {
struct lws* client_wsi = *it;
PerClientData *data = (PerClientData*)lws_wsi_user(client_wsi);
// 心跳超时：关闭连接
if(now - data->last_pong_time > HEARTBEAT_INTERVAL + HEARTBEAT_TIMEOUT) {
lwsl_notice("Client %p heartbeat timeout, closing\n", client_wsi);
lws_close_reason(client_wsi, LWS_CLOSE_STATUS_NORMAL, (unsigned char*)"timeout", 7);
it = g_clients.erase(it);
} else {
// 发送 Ping 帧（心跳检测）
lws_callback_on_writable(client_wsi);
++it;
}
}
break;
}
// 可写事件：发送 Ping 帧
case LWS_CALLBACK_SERVER_WRITEABLE: {
// 发送 Ping 帧（负载为空）
lws_write(wsi, NULL, 0, LWS_WRITE_PING);
break;
}
// 客户端连接关闭
case LWS_CALLBACK_CLOSED: {
std::lock_guard<std::mutex> lock(g_client_mutex);
for(auto it = g_clients.begin(); it != g_clients.end(); ++it) {
if(*it == wsi) {
g_clients.erase(it);
lwsl_notice("Client disconnected: %p, total clients: %zu\n", wsi, g_clients.size());
break;
}
}
break;
}
// 其他事件默认处理
default:
break;
}
return 0;
}
// WebSocket 协议配置
static struct lws_protocols ws_protocols[] = {
{"ws-echo-protocol", // 协议名称（对应客户端 Sec-WebSocket-Protocol）
ws_callback,
sizeof(PerClientData),
4096,
0,
NULL,
0},
{NULL, NULL, 0, 0} // 协议列表结束标记
};
int main(int argc, char** argv) {
// 日志级别：NOTICE 及以上
lws_set_log_level(LLL_NOTICE | LLL_ERR | LLL_WARN, NULL);
// 上下文配置（服务端核心配置）
struct lws_context_creation_info ctx_info;
memset(&ctx_info, 0, sizeof(ctx_info));
ctx_info.port = 8080; // 监听端口
ctx_info.protocols = ws_protocols; // 协议列表
ctx_info.gid = -1;
ctx_info.uid = -1;
ctx_info.options = LWS_SERVER_OPTION_VALIDATE_UTF8 | // 验证 UTF8 文本帧
LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT; // 初始化 SSL（支持 WSS）
// 创建上下文（WebSocket 服务端核心对象）
struct lws_context* ctx = lws_create_context(&ctx_info);
if(!ctx) {
lwsl_err("Failed to create lws context\n");
return -1;
}
lwsl_notice("WebSocket server started on ws://localhost:8080\n");
lwsl_notice("Heartbeat interval: %d seconds, timeout: %d seconds\n", HEARTBEAT_INTERVAL, HEARTBEAT_TIMEOUT);
// 事件循环：处理客户端连接和消息
while(1) {
// 处理事件（超时 50ms，避免 CPU 占用过高）
lws_service(ctx, 50);
usleep(10000); // 10ms 休眠
}
// 释放资源（实际不会执行到，需通过信号处理退出）
lws_context_destroy(ctx);
return 0;
}
以下代码实现了 WebSocket 客户端，支持连接服务端、发送消息、接收响应、心跳处理：
#include <libwebsockets.h>
#include <string.h>
#include <unistd.h>
// 客户端自定义数据
struct PerClientData {
char send_buf[LWS_PRE + 4096]; // 发送缓冲区
int send_len; // 待发送数据长度
};
/**
* @brief 客户端事件回调函数
*/
static int ws_client_callback(struct lws* wsi, enum lws_callback_reasons reason, void* user, void* in, size_t len) {
PerClientData *client_data = (PerClientData*)user;
switch(reason) {
// 连接服务端成功
case LWS_CALLBACK_CLIENT_ESTABLISHED: {
lwsl_notice("Connected to WebSocket server\n");
// 准备发送测试消息
const char* msg = "Hello WebSocket Server (C++)";
client_data->send_len = strlen(msg);
memcpy(client_data->send_buf + LWS_PRE, msg, client_data->send_len);
// 触发可写事件，发送消息
lws_callback_on_writable(wsi);
break;
}
// 可写事件：发送数据
case LWS_CALLBACK_CLIENT_WRITEABLE: {
if(client_data->send_len > 0) {
// 发送文本帧
int ret = lws_write(wsi, (unsigned char*)client_data->send_buf + LWS_PRE, client_data->send_len, LWS_WRITE_TEXT);
if(ret > 0) {
lwsl_notice("Sent to server: %s\n", client_data->send_buf + LWS_PRE);
client_data->send_len = 0; // 清空待发送数据
}
}
break;
}
// 收到服务端数据
case LWS_CALLBACK_CLIENT_RECEIVE: {
char buf[4096] = {0};
memcpy(buf, in, len);
lwsl_notice("Received from server: %s (len: %zu)\n", buf, len);
break;
}
// 收到服务端 Ping 帧，自动回复 Pong
case LWS_CALLBACK_CLIENT_PING: {
lwsl_notice("Received Ping from server\n");
break;
}
// 连接关闭
case LWS_CALLBACK_CLIENT_CLOSED: {
lwsl_notice("Disconnected from server\n");
break;
}
default:
break;
}
return 0;
}
// 客户端协议配置
static struct lws_protocols ws_client_protocols[] = {
{"ws-echo-protocol", ws_client_callback, sizeof(PerClientData), 4096, 0, NULL, 0},
{NULL, NULL, 0, 0}
};
int main(int argc, char** argv) {
lws_set_log_level(LLL_NOTICE | LLL_ERR | LLL_WARN, NULL);
// 上下文配置
struct lws_context_creation_info ctx_info;
memset(&ctx_info, 0, sizeof(ctx_info));
ctx_info.protocols = ws_client_protocols;
ctx_info.gid = -1;
ctx_info.uid = -1;
struct lws_context* ctx = lws_create_context(&ctx_info);
if(!ctx) {
lwsl_err("Failed to create client context\n");
return -1;
}
// 客户端连接参数
struct lws_client_connect_info conn_info;
memset(&conn_info, 0, sizeof(conn_info));
conn_info.context = ctx;
conn_info.address = "localhost"; // 服务端地址
conn_info.port = 8080; // 服务端端口
conn_info.path = "/"; // 服务端路径
conn_info.host = conn_info.address; // Host 头
conn_info.origin = conn_info.address;
conn_info.protocol = "ws-echo-protocol"; // 子协议（需与服务端一致）
// 建立连接
struct lws* wsi = lws_client_connect_via_info(&conn_info);
if(!wsi) {
lwsl_err("Failed to connect to server\n");
lws_context_destroy(ctx);
return -1;
}
// 事件循环
while(1) {
lws_service(ctx, 50);
usleep(10000);
}
lws_context_destroy(ctx);
return 0;
}
g++ -o ws_server ws_server.cpp -lwebsockets -lpthread -lssl -lcrypto -lz
g++ -o ws_client ws_client.cpp -lwebsockets -lpthread -lssl -lcrypto -lz
# 启动服务端
./ws_server
# 新开终端启动客户端
./ws_client
运行后客户端会向服务端发送消息，服务端回声响应，同时服务端会定时发送 Ping 帧检测客户端心跳。
生产环境必须使用 WSS（基于 TLS/SSL 加密），避免数据明文传输。libwebsockets 配置 WSS 只需修改上下文配置：
// 新增 SSL 配置
ctx_info.ssl_cert_filepath = "/path/to/server.crt"; // 证书文件
ctx_info.ssl_private_key_filepath = "/path/to/server.key"; // 私钥文件
ctx_info.port = 443; // WSS 默认端口
直接在应用层配置 SSL 易出问题，推荐通过 Nginx 反向代理实现 WSS：
server {
listen 443 ssl;
server_name example.com;
# SSL 证书配置
ssl_certificate /path/to/fullchain.pem;
ssl_certificate_key /path/to/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
# 反向代理 WebSocket
location /ws {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_read_timeout 86400; // 延长超时时间（避免心跳中断）
}
}
网络波动会导致连接断开，需实现断线重连逻辑（指数退避策略，避免频繁重试）：
// 客户端重连逻辑示例
int reconnect_count = 0;
const int MAX_RECONNECT = 10;
const int BASE_RECONNECT_INTERVAL = 1; // 基础重连间隔（秒）
while(reconnect_count < MAX_RECONNECT) {
// 建立连接
struct lws* wsi = lws_client_connect_via_info(&conn_info);
if(wsi) {
reconnect_count = 0; // 重连成功，重置计数
break;
}
// 指数退避：1s → 2s → 4s → ... → 512s
int interval = BASE_RECONNECT_INTERVAL * (1 << reconnect_count);
interval = std::min(interval, 512); // 最大间隔 512 秒
lwsl_notice("Reconnect failed, retry in %d seconds (count: %d)\n", interval, reconnect_count);
sleep(interval);
reconnect_count++;
}
启用压缩扩展：配置 permessage-deflate 扩展，压缩文本数据（减少带宽）：
// 启用压缩扩展
ctx_info.extensions = lws_get_internal_extensions();
| 问题 | 根因 | 解决方案 |
|---|---|---|
| 握手失败（400 错误） | Sec-WebSocket-Version≠13 或 Key 验证失败 | 确保客户端使用版本 13，服务端正确计算 Accept |
| 连接立即关闭 | 子协议不匹配 | 客户端和服务端 Sec-WebSocket-Protocol 一致 |
| 数据乱码 | 文本帧非 UTF8 编码 | 强制使用 UTF8 编码，验证数据格式 |
| 心跳超时 | 防火墙拦截 Ping/Pong 帧 | 调整心跳间隔，通过 Nginx 转发时延长超时时间 |
| 高并发下连接不稳定 | 文件描述符耗尽 | 调整系统最大文件描述符（ulimit -n 65535） |
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online
将JSON字符串修饰为友好的可读格式。 在线工具，JSON美化和格式化在线工具，online