简介这是一份基于Go语言开发的自托管消息推送服务源码包适合需要搭建WebSocket实时收发消息、架设Web管理界面的服务端开发者。服务端通过REST API发送消息客户端经WebSocket实时接收消息同时支持用户、应用与客户端管理并附带界面时尚的Web管理前端可替代不少商业推送服务。压缩包共226个文件核心代码包含113个Go文件实现后端逻辑、29个TypeScript与27个TSX文件实现前端交互另有Dockerfile、YAML配置、Markdown文档、PNG图标等分别承担容器部署、环境配置、项目说明与界面素材等用途整体仅1.11MB结构紧凑清晰。目前已有221人浏览学习。资源采用MIT许可证完整提供前后端源码、容器化部署配置及项目文档适合自托管爱好者、Golang与React开发者学习参考也便于直接二次改造或扩展为个人推送服务平台。1. 一个「简单WebSocket服务器 时尚Web UI」到底值不值得动手很多人做实时消息第一反应就是上框架Socket.io一接就完事。但这个标题给了一条完全不同的路不依赖第三方库自己握手、自己解析帧、自己写一个能让消息实时流动起来的界面。说白了它是一套能跑通的最小实时通信系统——浏览器打开页面输入消息同一时刻连上来的所有客户端都能看到服务器收到的消息也实时推回来。它适合两类人前端想补一点服务器功底想彻底弄懂WebSocket到底在收发什么以及小团队想快速搭一个内部实时看板、消息推送工具但不值得为此引入成体系的后端框架。下面按服务器、UI、联调、避坑、扩展的顺序把这条链路从零讲明白。2. 先把服务器立起来握手、帧格式与最小 Node 实现2.1 一次握手后连接常驻HTTP Upgrade 与 101 切换协议WebSocket 与普通 HTTP 请求最大的差别在于HTTP 是“你问我答”一次请求对应一次响应而 WebSocket 在建立连接之后两边谁都可以随时开口不需要等对方提问。这个“先建立再常驻”的过程靠的是 HTTP 协议里的 Upgrade 机制。客户端发一个普通 HTTP GET 请求在请求头里带上Upgrade: websocket、Connection: Upgrade以及一个随机生成的Sec-WebSocket-Key服务器如果同意切换就返回HTTP/1.1 101 Switching Protocols并在Sec-WebSocket-Accept里回填一段校验值双方从这一刻起就不再按 HTTP 规则通信改用 WebSocket 的二进制帧格式。这里最有价值的一步是服务器计算方法把客户端发来的Sec-WebSocket-Key拼上一个固定的 GUID然后做 SHA-1 摘要再转 base64。这个 GUID 是协议写死的不用记但一定要拼对。拼错一个字符客户端就能在握手响应里判断出来直接断开连接。很多初学 WebSocket 的人翻车就翻在这一行字符串拼接上后面避坑章节我会单独说。2.2 帧格式拆解为什么客户端消息一定要带掩码握手完成之后所有业务消息都封装成帧。一个最小帧长这样第一个字节的高位是 FIN表示这是不是最后一帧低四位是 opcode0x1代表文本消息0x2是二进制0x8是关闭连接0x9是 ping0xA是 pong。第二个字节的最高位是 MASK 位低 7 位是载荷长度。如果载荷长度小于 126直接写在第二个字节里如果等于 126说明真实长度在接下来两个字节里如果是 127说明真实长度在接下来八个字节里。这就是为什么一个帧最短 2 个头字节最长却可能带十几字节的扩展头。掩码是 WebSocket 一个反直觉的设计协议明确规定客户端发送给服务器的帧必须把 MASK 位置 1并在载荷数据前附上 4 字节的掩码键而服务器发给客户端的帧 MASK 位必须为 0。掩码不是加密而是防止恶意客户端构造出能被中间缓存设备误解的 HTTP 响应。解码方法很直接把载荷的每个字节轮流与掩码键的四个字节做异或。注意这个过程本身消耗 CPU在高并发场景下是一个容易被低估的性能点。2.3 零依赖的服务器核心代码接收、解码、广播很多教程会直接带你装现成的 WebSocket 库但这个项目标题写的是“一个简单的服务器”我建议你至少亲手写一遍原生版本之后再用库你会非常清楚它帮你做了什么事。下面这段代码只用 Node.js 内置的http和crypto两个模块完成握手、解析、文本广播三件事// server.js —— 零依赖 WebSocket 服务器 const http require(http); const crypto require(crypto); const PORT 8080; const WS_GUID 258EAFA5-E914-47DA-95CA-C5AB0DC85B11; const clients new Set(); const server http.createServer((req, res) { res.writeHead(200, { Content-Type: text/plain; charsetutf-8 }); res.end(WebSocket server is running.\n); }); server.on(upgrade, (req, socket) { // 只接受 /ws 这个路径其余直接断开 if (req.url ! /ws) { socket.destroy(); return; } const key req.headers[sec-websocket-key]; if (!key) { socket.write(HTTP/1.1 400 Bad Request\r\n\r\n); socket.destroy(); return; } const accept crypto .createHash(sha1) .update(key WS_GUID) .digest(base64); socket.write( HTTP/1.1 101 Switching Protocols\r\n Upgrade: websocket\r\n Connection: Upgrade\r\n Sec-WebSocket-Accept: ${accept}\r\n\r\n ); clients.add(socket); socket.on(data, (buf) handleFrame(socket, buf)); socket.on(close, () clients.delete(socket)); socket.on(error, () clients.delete(socket)); }); function handleFrame(socket, buffer) { const opcode buffer[0] 0x0f; const masked (buffer[1] 0x80) ! 0; let payloadLen buffer[1] 0x7f; let offset 2; if (payloadLen 126) { payloadLen buffer.readUInt16BE(2); offset 4; } else if (payloadLen 127) { payloadLen Number(buffer.readBigUInt64BE(2)); offset 10; } if (!masked) { socket.end(); return; } const maskKey buffer.subarray(offset, offset 4); offset 4; const payload Buffer.alloc(payloadLen); for (let i 0; i payloadLen; i) { payload[i] buffer[offset i] ^ maskKey[i % 4]; } if (opcode 0x1) { broadcast(payload.toString(utf8)); } else if (opcode 0x8) { socket.end(); } // ping(0x9) 和 pong(0xA) 先忽略第 4 章补上 } function encodeLength(len) { if (len 126) return Buffer.from([len]); if (len 65536) { const b Buffer.alloc(3); b.writeUInt8(126, 0); b.writeUInt16BE(len, 1); return b; } const b Buffer.alloc(9); b.writeUInt8(127, 0); b.writeBigUInt64BE(BigInt(len), 1); return b; } function broadcast(text) { // 0x81 FIN(1) 文本帧(1)服务器帧不带掩码 const frame Buffer.concat([ Buffer.from([0x81]), encodeLength(Buffer.byteLength(text)), Buffer.from(text, utf8) ]); for (const s of clients) s.write(frame); } server.listen(PORT, () { console.log(listening on ws://localhost:${PORT}/ws); });这段代码干了三件事握手时校验路径和Sec-WebSocket-Key收到数据时解析帧头、做掩码异或组装文本帧广播给所有连接。注意几个参数含义clients这个Set同时承担了“在线列表”和“广播目标”两个职责0x81是十六进制写法代表 FIN 位加文本帧操作码encodeLength按协议把长度编码成 1、3、9 字节三种形态小于 126 用 1 字节在 126 到 65535 之间用 3 字节再大的用 9 字节。启动方式直接node server.js前端页面在浏览器里打开本地 HTML 文件即可。不过这里埋了一个明显的坑data事件传进来的 buffer 不一定正好是一个完整的 WebSocket 帧可能一次事件带了两帧也可能一帧被拆成两次到达。严格地说上面代码只是教学解还缺一个粘包拆包逻辑这个我在第 5 章会给出完整补丁。先把主要链路跑通再回头补这个洞是学协议最舒服的节奏。3. Web UI 从零搭暗色界面与前端 WebSocket 客户端3.1 界面结构规划三块区域不引框架也能“时尚”标题里特意写了“时尚的 Web UI”对实时消息工具来说所谓的时尚不是花哨而是信息层次清楚、状态反馈即时、视觉上跟得上当下的纯前端审美。我一般把界面切成三块最上面的状态栏用一个小圆点和一句话显示当前是连接中、已连接、已断开中间是消息列表消息气泡区分自己和别人底部是输入框和发送按钮。三块区域用弹性布局纵向排列整体宽度控制在 400 到 500 像素在桌面浏览器里居中显示手机上也能直接用。不引 Vue、React 或者 UI 组件库的原因很简单这个项目只有一条消息流原生 DOM 操作完全够用少一层框架就少一层包体积和构建步骤。样式上用暗色渐变背景加细边框分隔自己发的消息用高饱和色块右对齐收到的消息用低饱和色块左对齐整个页面打开就是“能用且不难看”的状态。界面代码我在 3.3 一起给先把连接管理单独拆出来讲因为连接逻辑才是前端这部分真正容易写坏的地方。3.2 前端连接管理四个回调函数 一个重连问题浏览器内置的WebSocket对象对新手极其友好你只需要关注四个回调。但恰恰是这四个回调的时序容易想当然onerror之后大概率会跟着onclose所以不要在onerror里做重连否则一次断线会触发两次重连逻辑。另外重连定时器必须每次先清掉再设置否则网络抖动几次之后定时器叠起来服务器会收到一连串无效连接请求。let ws null; let reconnectTimer null; function connect() { // 如果已经有一个连接在先关掉避免重复建连 if (ws) ws.close(); // 路径要和服务器 upgrade 里校验的保持一致 ws new WebSocket(ws://localhost:8080/ws); ws.onopen () { setStatus(已连接, #00d4aa); }; ws.onmessage (event) { // 消息格式先按文本处理第 4 章改成 JSON appendMessage(event.data, in); }; ws.onclose () { setStatus(已断开稍后重连, #ff6b6b); clearTimeout(reconnectTimer); reconnectTimer setTimeout(connect, 2000); }; ws.onerror (err) { console.error(连接异常, err); // 不在这里重连等 onclose }; } function setStatus(text, color) { const el document.getElementById(status); el.textContent text; el.style.color color; }这段代码的逻辑要点在重连部分onclose里先clearTimeout再setTimeout保证同一时刻只有一个重连定时器在跑setStatus单独抽出来是为了后面把连接状态同步到界面时不用在每个回调里重复操作 DOM。参数2s是一个起步值实际项目里建议接上指数退避第 5 章我会把它和“重连风暴”一起讨论。3.3 消息渲染与发送气泡、自动滚动、回车发送界面渲染部分要处理两件事消息气泡的插入以及面板自动滚动到底部。很多人忽略了自动滚动结果消息多了之后新消息被挤出可视区用户以为服务器没推过来。正确做法是在每一条消息插入之后把滚动条直接拉到scrollHeight。注意这里的时机必须在 DOM 插入完成后否则高度还没更新拉过去也是停在旧位置。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleWebSocket 实时消息/title style body { margin: 0; background: linear-gradient(135deg, #1a1a2e, #16213e); display: flex; justify-content: center; font-family: system-ui, -apple-system, sans-serif; } .container { width: 440px; height: 100vh; display: flex; flex-direction: column; background: rgba(0, 0, 0, 0.2); } .header { padding: 16px 20px; color: #e0e0e0; font-size: 18px; border-bottom: 1px solid rgba(255, 255, 255, 0.08); } .status { padding: 6px 20px; font-size: 12px; color: #888; } #messages { flex: 1; overflow-y: auto; padding: 12px 20px; display: flex; flex-direction: column; gap: 10px; } .msg { padding: 10px 14px; border-radius: 14px; max-width: 75%; font-size: 14px; line-height: 1.5; word-break: break-word; } .msg.in { background: #2e3440; color: #d8dee9; align-self: flex-start; } .msg.out { background: #5e81ac; color: #fff; align-self: flex-end; } .input-bar { display: flex; gap: 10px; padding: 12px 20px; border-top: 1px solid rgba(255, 255, 255, 0.08); } #input { flex: 1; padding: 10px 14px; border: none; border-radius: 10px; background: #2e3440; color: #fff; outline: none; } #send { padding: 10px 22px; border: none; border-radius: 10px; background: #5e81ac; color: #fff; cursor: pointer; } /style /head body div classcontainer div classheaderWebSocket 实时消息/div div classstatus idstatus连接中.../div div idmessages/div div classinput-bar input idinput placeholder输入消息回车发送 / button idsend发送/button /div /div script const messageBox document.getElementById(messages); const inputBox document.getElementById(input); function appendMessage(text, type) { const div document.createElement(div); div.className msg (type out ? out : in); div.textContent text; messageBox.appendChild(div); messageBox.scrollTop messageBox.scrollHeight; } function sendMessage() { const text inputBox.value.trim(); if (!text) return; appendMessage(text, out); // 本地立即回显 if (ws ws.readyState WebSocket.OPEN) { ws.send(text); } inputBox.value ; } document.getElementById(send).addEventListener(click, sendMessage); inputBox.addEventListener(keydown, (e) { if (e.key Enter) sendMessage(); }); // 把第 3.2 节的 connect() 和 setStatus() 定义贴到这里 connect(); /script /body /html这段 HTML 有几个参数可以按需调width: 440px决定页面在桌面端的展示宽度改成 100% 就是移动端全屏.msg.max-width: 75%限制气泡最大宽度避免超长英文单词撑破布局输入框的outline: none是为了去掉默认焦点框改成自定义的边框色更干净。代码里用的是textContent而不是innerHTML原因很直接用户输入的内容会被当成文本渲染防住 XSS 注入做实时消息工具这个习惯要一开始就养成。4. 前后端对齐协议JSON 消息、心跳保活、广播边界4.1 裸字符串够用但 JSON 能表达更多如果只是聊天裸字符串确实够了。但真实场景下同一个 WebSocket 连接里会混着聊天消息、系统通知、错误提示甚至还有后面的 ping/pong 心跳前端收到之后怎么区分我一般用最朴素的方案所有消息统一包一层 JSON结构固定下来{ type: chat, payload: 你好, ts: 1720000000 }type字段决定这条消息去哪个渲染流程payload是正文ts是毫秒时间戳。type的取值范围根据业务定chat、system、ping、pong、error。服务器收到消息先JSON.parse解析失败就当成裸文本广播回去不要把异常直接吞掉。前端收到也先 parsetype为 ping 时回 pongtype为 chat 时渲染气泡type为 system 时在列表里插入一条居中灰色提示。这样做的好处是协议可扩展后面要加用户名、加房间、加消息 ID都只需要扩字段不用改连接层。坏处也很明显每次收发多一次序列化开销。对“简单的服务器”这个定位来说这点开销完全可接受。4.2 心跳保活浏览器发不了 ping 帧怎么让连接不掉WebSocket 建连之后如果长时间没数据流中间的网络设备路由器、负载均衡、NAT 网关可能把这条空闲连接回收掉。表现就是页面还开着但消息已经收不到了而且不会触发onclose因为 TCP 层还没感知到断线。解决办法是心跳保活但这里有个坑——浏览器 WebSocket API 没有暴露 ping/pong 帧的接口你没法直接发协议层 ping只能在应用层模拟。服务器端要同时处理两套协议层的 ping/pong 帧以及 JSON 里的{ type: ping }。先给服务器端补上协议层响应// 在 handleFrame 里解析出 payload 与 offset 之后追加 if (opcode 0x9) { // 收到协议 ping原样回 pong 帧 const pong Buffer.concat([ Buffer.from([0x8A]), // FIN pong encodeLength(payload.length), payload ]); socket.write(pong); return; }然后前端每 30 秒发一次应用层心跳setInterval(() { if (ws ws.readyState WebSocket.OPEN) { ws.send(JSON.stringify({ type: ping, payload: , ts: Date.now() })); } }, 30000);服务器收到这个 JSON 后回一个{ type: pong }同时更新该连接的最近活跃时间。每隔一段时间扫一遍超过 120 秒没活跃的就主动socket.end()。这个 120 秒阈值不是拍脑袋中间设备最常见的空闲回收时间是 60 到 120 秒心跳间隔取 30 秒给了三次重试余量。阈值调太短会产生大量无效断开调太长又起不到保活效果一般建议心跳间隔的 4 倍以内。4.3 广播边界给所有人还是只给同一间房第 2 章的broadcast是遍历所有连接这在只有一个频道的场景下没问题。但只要你开始有“不同页面各聊各的”需求就得引入房间概念。常见做法是把单一的Set换成Map房间名, Setsocketconst rooms new Map(); function joinRoom(socket, roomName) { if (!rooms.has(roomName)) rooms.set(roomName, new Set()); rooms.get(roomName).add(socket); socket.roomName roomName; } function leaveRoom(socket) { const room rooms.get(socket.roomName); if (room) { room.delete(socket); if (room.size 0) rooms.delete(socket.roomName); } } function broadcastToRoom(roomName, text) { const list rooms.get(roomName); if (!list) return; const frame Buffer.concat([ Buffer.from([0x81]), encodeLength(Buffer.byteLength(text)), Buffer.from(text, utf8) ]); for (const s of list) s.write(frame); }房间的实现原理不复杂关键在leaveRoom里把空房间从Map删除否则房间列表会越积越大。对“一个简单的服务器”来说房间粒度到这一步就够用了再往上的鉴权、消息持久化都属于另一个话题。5. 连不上、秒断、重连风暴服务器与 UI 联调的 5 个具体坑5.1 端口或路径不一致Connection failed 的最常见原因现象浏览器控制台报WebSocket connection to ws://localhost:8080/ws failed服务器端没有任何日志。原因前端连接地址里写的端口和server.listen不一致或者路径对不上。最常见的翻车是把server.listen(PORT)挂在 8080前端却写了 8081另一个是忘了在第 2 章的upgrade事件里校验req.url前端连/路径服务器直接destroy这在浏览器里表现同样是连接失败。解决把前端地址、监听端口、路径校验三处做成统一配置。我用环境变量的方式WS_PORT8080 WS_PATH/ws node server.js前端从页面 URL 推断后端地址而不是写死一个localhost。开发阶段可以接受写死但一定要和服务器文件里保持一致。5.2 握手响应非法Sec-WebSocket-Accept 计算错误现象连接建立后几秒内被断开浏览器控制台提示Error during WebSocket handshake: Incorrect Sec-WebSocket-Accept header value。原因Sec-WebSocket-Accept算错了。最常见的两个错误一是 GUID 少写或多写字符二是拼接时在 key 和 GUID 之间多加了空格或换行。协议要求的拼接是key GUID中间没有任何分隔符。解决对照协议原文检查拼接然后用下面这段代码自测const crypto require(crypto); const testKey dGhlIHNhbXBsZSBub25jZQ; const accept crypto .createHash(sha1) .update(testKey 258EAFA5-E914-47DA-95CA-C5AB0DC85B11) .digest(base64); console.log(accept); // 期望输出 s3pPLMBiTxaQ9kYGzzhZRbKxOo如果输出不一致回去看拼接部分。这个值协议里给了标准示例拿它当测试用例能快速隔离问题。5.3 粘包与拆包只解析第一帧的服务器迟早翻车现象客户端连发两条消息服务器只广播了第一条或者一条长消息显示成乱码。原因底层 TCP 是流不是帧。一次data事件里可能装了多个 WebSocket 帧也可能一个帧被拆成两次到达。第 2 章的handleFrame拿到 buffer 直接解析第一帧剩下的数据就被丢掉了。解决给每个 socket 维护一个接收缓冲区把所有data拼进去然后循环解析每解析完一帧就从前面对应长度切掉socket.recvBuf Buffer.alloc(0); socket.on(data, (chunk) { socket.recvBuf Buffer.concat([socket.recvBuf, chunk]); while (true) { const frameLen calcFrameLength(socket.recvBuf); if (frameLen 0 || socket.recvBuf.length frameLen) { // 帧不完整等下一片数据 break; } const frame socket.recvBuf.subarray(0, frameLen); handleFrame(socket, frame); socket.recvBuf socket.recvBuf.subarray(frameLen); } }); function calcFrameLength(buf) { if (buf.length 2) return -1; let payloadLen buf[1] 0x7f; let offset 2; if (payloadLen 126) { if (buf.length 4) return -1; payloadLen buf.readUInt16BE(2); offset 4; } else if (payloadLen 127) { if (buf.length 10) return -1; payloadLen Number(buf.readBigUInt64BE(2)); offset 10; } if (buf[1] 0x80) offset 4; // 客户端帧带掩码 return offset payloadLen; }这段代码是第 2 章那个教学版最重要的补丁。calcFrameLength只负责算出完整帧需要多少字节算不出来就返回负数或者大于当前缓冲区表示数据还没到齐。这个模式在 Node 原生写法里属于必背套路换到任何语言都一样。5.4 中文乱码解码时机不对现象发英文正常发中文变成一堆乱码或者锟斤拷。原因没有按帧边界解码。如果拆包逻辑没做某一次data只拿到了一个中文字符的一部分字节提前调toString(utf8)半个汉字就会被替换成占位符。另一个原因是拼接 buffer 时用了号而不是Buffer.concat字符串拼接会把 Buffer 隐式转成字符串再拼一旦涉及多字节字符就出错。解决先完整切割帧再用payload.toString(utf8)解码。buffer和string之间不要做隐式拼接所有二进制操作都用Buffer.concat。还有一个细节encodeLength算长度时要用Buffer.byteLength(text)而不是text.length因为中文字符在 UTF-8 下占 3 字节text.length只会数出字符个数长度算错会导致客户端无法解析。5.5 重连风暴多个页面同时重连把服务器拖垮现象网络抖动一下办公室所有打开的页面几乎同时进入重连服务器 CPU 瞬间飙升日志里全是连接建立和断开的记录。原因所有客户端用同一个固定重连间隔比如第 3 章的setTimeout(connect, 2000)。断网恢复后它们在同一时刻发起连接形成周期性脉冲。这个现象在公网环境特别明显。解决重连间隔加随机抖动和指数退避。我用的是间隔 基础值 × 2^次数 随机毫秒数次数上限 6 次let retryCount 0; function scheduleReconnect() { const base Math.min(30000, 1000 * Math.pow(2, retryCount)); const jitter Math.floor(Math.random() * 1000); retryCount; clearTimeout(reconnectTimer); reconnectTimer setTimeout(connect, base jitter); }同时服务器端应该限制单个 IP 的连接频率最简单的做法是在upgrade事件里对同一 IP 做滑动窗口计数超过阈值直接拒绝。对内部工具来说指数退避已经能解决绝大多数问题。6. 从简单到可用分片帧、wss 与反代部署项目做到“能聊”之后下一步是让它在真实环境里站得住这里有三件事逃不掉。第一支持大消息。WebSocket 协议规定超过 65535 字节的载荷必须分片发送客户端发来的消息如果超过这个长度浏览器会自动分片但服务器端不处理分片就只会收到第一片。处理逻辑不复杂收到第一个 opcode 为 0x1 的帧时如果 FIN 位是 0就把载荷暂存起来之后所有 opcode 为 0x0 的帧都视为续片拼到缓冲区直到遇到 FIN 位为 1 的帧才整体解码。我一般在handleFrame里加两个模块级变量fragmentedOpcode和fragmentedPayload代码量不大但省掉它线上迟早会有一次“消息发不出来”的工单。第二上 wss。浏览器对混合内容限制很严页面在 HTTPS 下访问ws://地址会被直接拦截所以部署到公网必须用wss://。常见做法是把 TLS 终结放在反向代理Node 服务本身继续监听内网端口。以 Nginx 为例关键配置就三行proxy_set_header Upgrade、proxy_set_header Connection upgrade、proxy_read_timeout拉长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_read_timeout 3600s; proxy_send_timeout 3600s; }第三上线前过一遍检查清单服务器进程要接守护我习惯用 Node 内置的 cluster 或者系统级的 systemd心跳超时要能主动断开僵尸连接消息大小要做上限协议层 127 长度支持到 64 位整数但不代表业务上允许那么大的单条消息日志里要能追踪每个 socket 的建立和断开原因。做完这三件事这个项目就完成了从“本地 Demo”到“可用工具”的转换。我自己最初写这类服务器时总想一步到位把框架、数据库、认证全塞进去结果每次都被复杂度和调试成本劝退。后来换了个思路先用最小代码把 WebSocket 收发的每一条帧都搞明白再按需加东西。这条路径的收益在于之后不管换什么语言、换什么框架协议层的坑你都能一眼认出来。希望这个方案对你有帮助。本文还有配套的精品资源点击获取