AI 内容创作 / 系统课时

WebSocket 控制通道

WebSocket 控制通道

数字人的控制消息需要低延迟、可双向推送且能保持会话状态。WebSocket 适合承载初始化、指令、状态通知和心跳,但必须额外设计消息信封、超时、幂等与恢复机制,才能在网络抖动或页面切换后继续同一会话。

学习目标

  • 区分 WebSocket 控制通道与音视频媒体通道的职责
  • 设计会话初始化、指令、状态、心跳和恢复消息
  • 实现一个可运行的服务端、客户端与单次断线重连示例

控制通道的职责边界

WebSocket 建立在 TCP 之上,连接成功后客户端与服务端都可以主动发送消息。数字人系统通常用它传递“开始说话”“停止生成”“切换角色”“当前正在渲染”等小型控制数据,而连续音视频帧应交给 WebRTC 或专门的流媒体协议,避免大媒体数据阻塞控制指令。

WebSocket 控制通道的会话、心跳与重连流程

一个稳定协议至少要包含 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:

js
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"));
        }
    });
}

创建目录、安装依赖并运行:

bash
mkdir websocket-control-demo
cd websocket-control-demo
npm init -y
npm install ws@8
node index.cjs

预期输出:

text
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 网络穿透和实时播放链路。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

WebSocket 控制通道

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通