AI 内容创作 / 系统课时
WebSocket 控制通道
WebSocket 控制通道
数字人的控制消息需要低延迟、可双向推送且能保持会话状态。WebSocket 适合承载初始化、指令、状态通知和心跳,但必须额外设计消息信封、超时、幂等与恢复机制,才能在网络抖动或页面切换后继续同一会话。
学习目标
- 区分 WebSocket 控制通道与音视频媒体通道的职责
- 设计会话初始化、指令、状态、心跳和恢复消息
- 实现一个可运行的服务端、客户端与单次断线重连示例
控制通道的职责边界
WebSocket 建立在 TCP 之上,连接成功后客户端与服务端都可以主动发送消息。数字人系统通常用它传递“开始说话”“停止生成”“切换角色”“当前正在渲染”等小型控制数据,而连续音视频帧应交给 WebRTC 或专门的流媒体协议,避免大媒体数据阻塞控制指令。

一个稳定协议至少要包含 type、sessionId、requestId 和 payload。type 决定消息语义,requestId 用于把响应与请求对应起来,sessionId 用于断线后恢复上下文,payload 只保存当前消息需要的数据。
| 消息类型 | 方向 | 作用 | 关键字段 |
|---|---|---|---|
session.init |
客户端到服务端 | 创建或绑定会话 | sessionId、鉴权信息 |
command.speak |
客户端到服务端 | 请求数字人播报文本 | requestId、text |
status.changed |
服务端到客户端 | 推送工作状态 | status、requestId |
heartbeat.request |
服务端到客户端 | 检测应用层会话是否活跃 | sequence |
session.resume |
客户端到服务端 | 恢复已存在的会话 | sessionId、最后确认序号 |
会话、心跳与重连规则
建立连接后不要立即发送业务指令,应先完成鉴权和 session.init,收到 session.ready 后再开放输入。浏览器的 WebSocket API 不暴露协议层 ping 和 pong,若前端需要主动判断应用会话是否活跃,可另加应用层心跳。服务端可以用协议层 Ping/Pong 检测死连接;浏览器自动处理协议层控制帧。
断线重连不能只做无限循环。生产环境应采用指数退避并加入随机抖动,例如从 500 ms、1 s、2 s 逐步增加,同时设置最大间隔和最大尝试次数。恢复时携带稳定的 sessionId、最后收到的事件序号和未完成请求标识,服务端据此决定续传、重放或拒绝恢复。
对可能重复执行的命令,应使用 requestId 做幂等判断。客户端重连后再次发送同一请求时,服务端返回原结果或当前状态,而不是再次触发播报、扣费或资源分配。
完整可运行示例
下面的 Node.js 示例在同一进程中启动 WebSocket 服务端和测试客户端。第一次连接完成初始化、状态通知和心跳后,服务端主动断开;客户端执行一次重连,并通过 session.resume 恢复原会话。
示例在回环地址运行,使用内存中的固定测试会话,重连后重发同一命令并取回已记录的状态。它不实现生产鉴权、跨进程持久化或事件重放。将代码保存为 index.cjs:
const { WebSocketServer, WebSocket } = require("ws");
const SESSION_ID = "demo-session";
const statusByRequest = new Map();
let initialized = false;
let reconnectCount = 0;
let statusSeq = 0;
// 回环网络与临时端口,仅用于本机演示。
const server = new WebSocketServer({ host: "127.0.0.1", port: 0, maxPayload: 4096 });
server.on("listening", () => {
console.log("server ready");
connectClient("init");
});
const send = (socket, message) => socket.send(JSON.stringify(message));
server.on("connection", socket => {
console.log("client connected");
let bound = false;
socket.on("error", error => console.error(error.message));
socket.on("message", (buffer, binary) => {
let message;
try {
message = binary ? null : JSON.parse(buffer.toString("utf8"));
} catch {
socket.close(1007, "invalid JSON");
return;
}
if (!message || typeof message !== "object" || Array.isArray(message)
|| message.sessionId !== SESSION_ID) {
socket.close(1008, "invalid message or session");
return;
}
if (!bound) {
if (message.type === "session.init" && !initialized) {
initialized = bound = true;
send(socket, { type: "session.ready", sessionId: SESSION_ID });
} else if (message.type === "session.resume" && initialized) {
bound = true;
send(socket, { type: "session.resumed", sessionId: SESSION_ID, sequence: statusSeq });
} else {
socket.close(1008, "session not bound");
}
return;
}
if (message.type === "command.speak") {
const { requestId, payload } = message;
if (typeof requestId !== "string" || !requestId ||
typeof payload?.text !== "string" || !payload.text.trim()) {
socket.close(1008, "invalid command");
return;
}
if (statusByRequest.has(requestId)) {
const previous = statusByRequest.get(requestId);
if (previous.text !== payload.text) {
socket.close(1008, "request ID reused with different text");
return;
}
send(socket, { ...previous.result, replay: true });
return;
}
console.log("server received: command.speak");
send(socket, { type: "status.changed", requestId, sequence: ++statusSeq, status: "speaking" });
const result = { type: "status.changed", requestId, sequence: ++statusSeq, status: "idle" };
statusByRequest.set(requestId, { text: payload.text, result });
send(socket, result);
send(socket, { type: "heartbeat.request", sequence: 1 });
} else if (message.type === "heartbeat.ack" && message.sequence === 1) {
console.log("heartbeat ok");
socket.close(4001, "demo disconnect");
}
});
});
function connectClient(mode) {
const client = new WebSocket("ws://127.0.0.1:" + server.address().port);
const reply = message => send(client, { ...message, sessionId: SESSION_ID });
const speak = () => reply({
type: "command.speak", requestId: "req-001", payload: { text: "你好,数字人" },
});
client.on("error", error => console.error(error.message));
client.on("open", () => reply({ type: "session." + mode }));
client.on("message", buffer => {
const message = JSON.parse(buffer.toString("utf8"));
if (message.type === "session.ready" || message.type === "session.resumed") {
console.log(message.type.replace(".", " ") + ": " + message.sessionId);
speak();
} else if (message.type === "status.changed") {
console.log((message.replay ? "replayed status: " : "status: ") + message.status);
if (message.replay) client.close(1000, "done");
} else if (message.type === "heartbeat.request") {
reply({ type: "heartbeat.ack", sequence: message.sequence });
}
});
client.on("close", code => {
console.log("connection closed: " + code);
if (code === 4001 && reconnectCount === 0) {
reconnectCount += 1;
console.log("reconnect scheduled");
setTimeout(() => connectClient("resume"), 100);
} else {
if (code !== 1000) process.exitCode = 1;
server.close(() => console.log("demo complete"));
}
});
}创建目录、安装依赖并运行:
mkdir websocket-control-demo
cd websocket-control-demo
npm init -y
npm install ws@8
node index.cjs预期输出:
server ready
client connected
session ready: demo-session
server received: command.speak
status: speaking
status: idle
heartbeat ok
connection closed: 4001
reconnect scheduled
client connected
session resumed: demo-session
replayed status: idle
connection closed: 1000
demo complete工程验证与常见问题
调试时应同时记录连接状态、消息方向、sessionId、requestId 和关闭码,但不要把令牌、用户文本或完整鉴权头写入普通日志。关闭码 1000 表示正常结束,自定义业务关闭码应统一登记,客户端据此判断是否重连。
若连接建立后立即关闭,先检查反向代理是否正确转发 Upgrade 和 Connection 头,再检查鉴权是否过期。若连接看似正常但收不到状态,重点检查消息 type、JSON 解析异常和服务端是否把事件发到了错误的会话。若重连后重复执行命令,应补充幂等存储,而不是只在前端去重。
生产接入使用 WSS,并由服务端验证来源、认证身份与会话归属;会话编号只是查找键。将请求 ID、参数摘要、状态与授权身份持久绑定,服务重启后才能继续核对。上线前验证弱网断开、服务端重启、令牌过期、页面后台和多标签页。服务端还应限制单连接消息大小、发送频率和空闲时长,避免控制通道被大消息或异常客户端占满。
本课总结
- WebSocket 负责低延迟双向控制,不应代替连续音视频传输
- 稳定协议需要会话标识、请求幂等、应用层心跳和可判定的关闭码
- 重连成功不等于状态恢复,客户端与服务端必须显式执行
session.resume
下一课预告
下一课将学习“WebRTC 音视频传输”,把本课的 WebSocket 通道作为信令入口,完成媒体轨道、编解码协商、ICE 网络穿透和实时播放链路。