Delphi WebSocket服务端开发：从握手到帧解析的完整实战

简介：基于Delphi编写的WebSocket服务端控件源程序包，由作者老吴整理，面向需要在Delphi项目里快速搭建WebSocket服务的开发人员。控件已实现接收和发送客户端文本消息、二进制流消息，支持Ping心跳、广播、全部断开、在线客户端列表与数量统计、各客户端收发消息计数等功能；当前尚未支持wss加密通信，更适合普通网络条件下的消息服务开发。压缩包共包含34个文件，以pas源程序、dpk控件包、dproj工程文件为核心，另外还有exe演示程序、dfm窗体文件、res资源与png图标等，整体容量仅951KB，结构清晰，方便直接查看控件源码和运行效果。目前已有2098人学习下载，对想掌握Delphi实现WebSocket协议或直接复用控件代码的开发者来说，代码包内含完整可编译控件、配套Demo和可执行程序，能够显著减少从零搭建服务端的时间和精力。

1. 为什么 Delphi 写 WebSocket 服务端仍然值得看一眼

一个 Delphi 老项目要加实时推送，这是最现实的开局：业务逻辑、数据库访问、历史报表全在 Windows 服务端上，重写语言是不可能的，轮询却又把内存和带宽吃得很厉害。WebSocket 刚好是协议层最后一段拼图，而“WebSocket Delphi server 服务端源代码.rar”这套东西，解决的就是“Delphi 能不能自己扛一个 WebSocket 服务端”的疑问。把源码包编译成 exe 跑在服务器上，不引入重量级框架，不依赖外部网关，客户端用浏览器直连，这是它最有吸引力的地方。

适合读这篇文章的人也很明确：你手上有一个 Delphi 7 到 Delphi 10 之间的遗留系统，需要给前端或 App 加实时通知、聊天、看板刷新；或者你拿到这份源码包但还没跑起来，想先弄明白里面哪些单元是关键、哪些参数是摆设。这里不会把协议背一遍给你听，只讲服务端代码里绕不开的握手、帧解析、线程模型，以及源码包里最常出问题的那几个位置。

2. 先跨过两道门槛：握手校验和 WebSocket 帧解析

2.1 握手不是“答一句 101”就行：Accept Key 少算一位就连不上

WebSocket 握手本质是一次 HTTP Upgrade。客户端发来的请求长这样：GET / 带有 Upgrade: websocket、Sec-WebSocket-Key、Sec-WebSocket-Version: 13。服务端回应 101 之外，必须返回正确的 Sec-WebSocket-Accept 头。很多第一次做的人以为随便回一句“101 Switching Protocols”就行，结果浏览器直接报 “Error during WebSocket handshake”。

Accept 的计算只有三步：把客户端传来的 Sec-WebSocket-Key 拼接固定 GUID 258EAFA5-E914-47DA-95CA-C5AB0DC85B11；对这个字符串做 SHA1；再做 Base64。常量是 RFC 6455 写死的，不是随便选的。坑往往出在拼接时带着原请求里的回车换行、或者只在末尾补了空格再哈希，算出来的 Accept 完全不一样。

uses System.NetEncoding, System.Hash; function ComputeAcceptKey(const AKey: string): string; var LCombined: string; LDigest: TBytes; begin // RFC 6455 固定的 GUID，不能改，也不能把它当版本号去掉 LCombined := AKey + '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'; LDigest := THashSHA1.GetHashBytes(LCombined, TEncoding.UTF8); Result := TBase64Encoding.Base64.Encode(LDigest); end;

这段代码的输入 AKey 必须原样保留客户端请求里的 Sec-WebSocket-Key，不要 Trim、不要大小写转换。SHA1 是对 UTF-8 字节做的，不是对 UnicodeString 内存直接哈希。很多新版 Delphi 的隐性 bug 就出在 GetHashBytes 默认编码上，所以这里显式传了 TEncoding.UTF8。Base64 之后按规范不带换行符，响应的 HTTP 头里也用 CRLF 结尾。

响应头拼装时顺序不重要，但别少了 Upgrade 和 Connection 两个头。常见的错误是把 Connection 写成 keep-alive，或者把 Sec-WebSocket-Accept 的大小写写错，浏览器对头内容是大小写不敏感的，对值敏感。

2.2 客户端字节流不是消息：帧头、掩码和 64 位长度

握手完成后，WebSocket 的数据都是“帧”的形式。没有经验的开发者最容易犯的错是：把一次 socket 接收到的字节当成一个完整消息来解。TCP 是流协议，一帧数据可能分三次到达，三帧消息也可能一次到齐。

先记住帧头布局。第一字节：高四位是 FIN，表示这是不是最后一个分片；低四位是 opcode，1 表示文本帧，2 表示二进制帧，8 表示关闭，9 是 ping，10 是 pong。第二字节：最高位是 MASK，客户端发来的帧必须置 1；低七位是 payload 长度，如果值小于 126，这个值就是实际长度；等于 126，则后面两字节才是长度；等于 127，则后面八字节是长度。

服务端解析时有个细节经常被忽略：客户端帧必须带掩码，掩码 key 是四个字节，紧接着扩展长度字段。payload 的每个字节要依次和掩码 key 的四个字节做异或，key 用完一轮继续循环。很多源码包在写 demo 时只处理短消息，长度一超过 125 就错位，因为没有跟进第二段和第三段的长度字段。

procedure ParseWebSocketFrame(const AData: TBytes; var AOpcode: Byte; var APayload: TBytes); var B1: Byte; LPayloadLen: UInt64; LIndex, i: Integer; LMaskKey: array[0..3] of Byte; begin if Length(AData) < 2 then Exit; AOpcode := AData[0] and $0F; B1 := AData[1]; LPayloadLen := B1 and $7F; LIndex := 2; if LPayloadLen = 126 then begin LPayloadLen := (AData[LIndex] shl 8) or AData[LIndex + 1]; Inc(LIndex, 2); end else if LPayloadLen = 127 then begin LPayloadLen := 0; // 网络字节序，高字节在前，逐字节拼进来 for i := 0 to 7 do LPayloadLen := (LPayloadLen shl 8) or AData[LIndex + i]; Inc(LIndex, 8); end; // 客户端帧必须带掩码，这是 RFC 6455 的强制要求 if (B1 and $80) <> 0 then begin Move(AData[LIndex], LMaskKey[0], 4); Inc(LIndex, 4); SetLength(APayload, LPayloadLen); Move(AData[LIndex], APayload[0], LPayloadLen); for i := 0 to LPayloadLen - 1 do APayload[i] := APayload[i] xor LMaskKey[i mod 4]; end else begin SetLength(APayload, LPayloadLen); Move(AData[LIndex], APayload[0], LPayloadLen); end; end;

这段代码的关键在 127 那个分支。八字节长度按网络字节序排列，高字节在低地址，直接套 Int64 的话需要先做字节反转。源码包里如果看到有人直接用了 LPayloadLen := PInt64(@AData[LIndex])^，那就是隐患。另外实时现场往往不能这样静态解析：你要先确认缓冲区里凑够了二字节帧头、扩展长度字节和四字节 mask key，再动 payload，否则 Length 判断会失效。

2.3 最小服务端线程：从 socket 按“完整帧”读，不是等“完整消息”

帧解析只是工具，真正跑起来要靠 socket 循环。Delphi 服务端源码包最常见的线程实现是“一个监听线程 + 每连接一个工作线程”。工作线程的任务很单一：循环读取字节，喂给一个连接级缓冲区，每次尝试从缓冲区里取出一帧，取出后回调业务层。

关键习惯是写一个“读满 N 字节”的工具函数。socket 不是每调用一次 Recv 就恰好返回你要的长度，尤其在高并发下，返回值经常小于请求值。

function ReadExact(ASocket: TSocket; ABuf: PByte; ACount: Integer): Integer; var LRead, LLeft: Integer; begin Result := 0; LLeft := ACount; while LLeft > 0 do begin LRead := Recv(ASocket, ABuf, LLeft, 0); if LRead <= 0 then Break; // 连接关闭或出错 Inc(ABuf, LRead); Inc(Result, LRead); Dec(LLeft, LRead); end; end;

调用方在使用时先读两字节帧头，然后再根据帧头里的长度字段决定要不要继续读扩展长度和 payload。这样既能避免半帧问题，也能天然处理多条消息合并到达的情况。源码包里凡是出现“直接把 Recv 结果当整包消息解析”的代码，都应该怀疑它的稳定性。我在实际维护中会额外做一层缓冲：把每次 Recv 的数据追加到 TBytesList，然后尝试循环取出所有完整帧，剩余部分留在缓冲里等下一个 Recv 周期。

3. 把服务端源码包跑起来：编译、依赖、第一个 WebSocket 客户端

3.1 先看清压缩包里的常用文件：不是每个单元都要改

你手里的压缩包可能命名不完全一样，但结构上有很大的共性。我一般会先打开包看五个位置，确认每个文件职责以后再编译，避免在命令行瞎试。

如果压缩包里还带一个 client 目录或者 HTML 页面，那是调试用的，不是服务端必须的一部分。先不要把客户端代码也编译进服务端，保持入口干净，后面排错容易定位。有的源码包会带 Indy 依赖，那你还要确认 Indy 版本和当前 Delphi 版本匹配，Indy 10 和 Indy 9 在字符串处理上有明显差异。

3.2 编译工程：先解决 Unicode、路径和运行库这三处卡点

老代码拿到新编译环境，最常见的报错是“E2010 Incompatible types: ‘AnsiChar’ and ‘Char’”这类。根源大多是源码用 Delphi 7 或更早版本写的，默认字符串是 AnsiString，而新版 Delphi 默认是 UnicodeString。握手响应头里到处是字节拷贝，处处都可能版本不兼容。

program WebSocketServer; {$APPTYPE CONSOLE} {$H+} // 确保长字符串模式，否则 string 会退化成短字符串 uses System.SysUtils, System.Classes, WSConst in 'WSConst.pas', WSServer in 'WSServer.pas'; var LPort: Integer; begin LPort := WSConst.ServerPort; try WSServer.Start(LPort); WriteLn('WebSocket server listening on port ' + IntToStr(LPort)); except on E: Exception do begin WriteLn('Startup failed: ' + E.Message); ExitCode := 1; end; end; end.

编译前先看一下项目文件里 uses 部分是否包含业务无关的单元，比如登录框、数据库组件，这些在服务端源码包里多半是从某个 GUI demo 抄来的，应该删掉。{$H+} 是关键，不加的话在旧版 Delphi 兼容模式下 string 只有 255 字节长度，握手响应头稍微长一点就被截断。

依赖方面，如果源码包用了 Indy，需要把 Indy 的 IdGlobal、IdHashSHA1、IdBase64Component 等单元路径加进 IDE 搜索路径。不要用“编译一次报错再搜一次”的土办法，先把包的根目录加到 Library Path，编译错误会少很多。编译完成后先别急着双击 exe，用命令行跑一次，观察标准输出的监听日志，确认端口是否真的被 bind 住。

3.3 用浏览器页面当第一个客户端：连接、发消息、收消息

服务端源码包跑没跑通，最直接的验证工具是浏览器而不是另一个 Delphi 程序。浏览器对握手协议的实现非常严格，Accept Key 有半个字节不对都会立刻断开，比拿自定义客户端测会更早暴露问题。

<!DOCTYPE html> <html lang="zh-CN"> <head><meta charset="utf-8"><title>ws debug page</title></head> <body> <input id="msg" value="hello server" style="width: 240px;"> <button onclick="sendMsg()">发送</button> <div id="log"></div> <script> var ws = new WebSocket('ws://127.0.0.1:9000'); ws.onopen = function () { log('连接已建立'); }; ws.onmessage = function (e) { log('收到: ' + e.data); }; ws.onclose = function () { log('连接已关闭'); }; ws.onerror = function () { log('发生错误'); }; function sendMsg() { var val = document.getElementById('msg').value; ws.send(val); } function log(s) { var d = document.createElement('p'); d.textContent = s; document.getElementById('log').appendChild(d); } </script> </body> </html>

这个页面的地址要用 ws:// 而不是 wss://，服务端没有配置 TLS 证书时不能用加密连接，否则会报安全错误。调试时把服务端地址写成 127.0.0.1 能避开一部分 Windows 防火墙弹窗，但真正部署到局域网时是 0.0.0.0 端口，需要在防火墙里放行。

打开页面后如果日志停在“连接已建立”但收不到回应，说明握手通了但服务端的消息回写逻辑没工作；如果直接停在“发生错误”然后关闭，多半是握手响应没通过。不要急着改业务代码，先把握手响应头和标椎 RFC 6455 样例对一遍。

3.4 源码包里自带的客户端工程：调试用还是演示用

不少源码包会把“Delphi 客户端”和“服务端”一起打包。客户端演示程序的意义在于同一个项目里可以直接按 F9 就能跑交互，不依赖浏览器。但请注意区分：客户端的握手和服务端是两套逻辑，客户端要对自己发出的帧做掩码，服务端则严禁对响应帧做掩码。如果源码包里两份代码共用了同一个编解码单元，往往要仔细看条件和分支。

我在调试时会把客户端工程里的连接地址改成本机回环地址，先确认客户端自身没有依赖服务端启动顺序，再换局域网 IP。客户端不是必须的，真正上线时绝大多数前端只会用浏览器或移动端 SDK，源码包里的客户端工程跑通了也只是说明协议兼容初步没问题，不能替代服务端的并发验证。

4. Delphi WebSocket 服务端的 5 个踩坑记录：连接、粘包、中文、线程、死连接

4.1 连接刚建立就被客户端断开：Accept Key 计算错或响应头格式不完整

现象：浏览器控制台报握手失败，服务端日志显示客户端连接后 0 到 3 秒内就关闭；抓包能看到服务端回了 101，但紧接着客户端发 RST。 原因：Sec-WebSocket-Accept 值不对，或者响应头里把 Upgrade 写成了小写之外的变体，又或者 HTTP 头之间用了 LF 而不是 CRLF。 解决：独立写一个函数专门计算 Accept Key，对着标准样例做单元测试。常用的样例是 Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==，期望输出 s3pPLMBiTxaQ9kYGzzhZRbK+xOo=。如果这个样例没过，就别往下查业务代码。响应头最后统一用 #13#10 拼行，最后的空行也是 CRLF，不要只用 #10。

这个样例是 RFC 6455 官方文档里现成的，任何语言的 WebSocket 库都拿它做回归测试。我每次升级 Delphi 版本后都会先跑一遍这个样例，免得编译器对字符串字面量的编码处理变动把结果带偏。

4.2 超过 125 字节的消息解析错位：长度字段处理顺序没跟上

现象：短消息收发正常，一旦消息超过 125 字节，收到的内容变乱，有时后半段被丢了，有时直接触发异常。 原因：帧头第二字节的低 7 位在 126 和 127 时要走不同的扩展长度分支，很多源码包只写了“小于 126”和“等于 126”两种情况，把 127 的八字节长度漏了；有的虽然写了，但没做字节序处理，按整型读出来是 0X0102030405060708 这样反着的值。 解决：把长度解析单独抽成函数，逐字节左移拼接，不要用 Cast 方式直接转 Int64。写完后用 126、127 和 125 三种边界场景做自测，分别发送 124、125、126、65535 字节的消息。65535 这个长度正好触发七位=127 的分支，最容易看出问题。

4.3 服务端偶发“一帧变两帧”“两帧合体”：TCP 粘包与半包

现象：客户端发一句话，服务端收到两条空消息或者内容截半；反过来，客户端连发两条消息，服务端只收到一条，payload 变成两段内容拼接。 原因：WebSocket 是消息协议，TCP 是字节流协议。Recv 一次返回几个字节由底层网络决定，和发送方的 Write 次数没有固定对应关系。 解决：服务端必须实现“读两字节帧头，再按帧头长度读完整 body”的机制。可以用循环读满指定长度，也可以维护每连接的接收缓冲区，缓冲区够一帧才解析。源码包里如果解析函数做完立刻清空缓冲区，那基本都会踩这个坑。正确习惯是：先 TryParse，剩余数据保留在缓冲里，等下一次 Recv 继续追加。

4.4 一开多人界面就假死：回调跑在连接线程里直接操作 UI

现象：单连接调试正常，开到三五个浏览器标签后服务端界面卡住，窗口拖不动，最小化恢复很慢；用“开始”按钮发的指令半天才有反应。 原因：Delphi 的 VCL 组件只能由主线程操作。很多 demo 为了方便把收到的消息直接往 Memo.Lines.Add 里送，Socket 工作线程一旦并发往 VCL 塞数据，界面就锁死，严重时整个进程崩溃。 解决：工作线程里只做协议解析和业务处理，界面更新统一用 TThread.Queue 或 TThread.Synchronize 排到主线程。服务端如果不需要界面，最稳妥的做法是写成控制台程序或 Windows 服务，彻底去掉 VCL 依赖。源码包如果自带窗体，建议把窗体压缩成托盘通知或者干脆退役。

4.5 客户端拔网线，服务端连接越攒越多：没有心跳机制

现象：连接数长时间只增不减，任务管理器里句柄数持续上涨，内存占用缓慢爬升；重启进程后数字一下子降下来。 原因：TCP 协议本身的 keepalive 在应用层看不见，默认参数在 Windows 上通常在两小时左右才感知断线。客户端断电、退出 App 时可能连 FIN 都没发，服务端的 socket 看起来还活着。 解决：源码包里必须有心跳。服务端每隔 30 到 60 秒发一次 ping 帧，客户端在协议层面应当回 pong。连续两三个周期没收到 pong，就把连接主动 Close。注意心跳要放在独立定时器线程里，不要塞在某个连接的 receive 循环里，否则这个请求频次低时心跳也会被拖慢。

5. 服务端参数怎么定：心跳间隔、缓冲区、线程模型和超时值

5.1 心跳和超时：源码包里 ping/pong 是怎么定的

心跳参数直接决定死连接能存活多久。我自己压测过一组组合，心跳周期 30 秒、允许连续丢两个 pong 就断开，是比较可靠的默认值。太短则频繁发 ping 占用带宽，太长则死连接清理不及时。

这里要区分“心跳间隔”和“读写超时”。读超时设的比心跳周期长是合理的，不然网络抖动一次就断开正常连接。客户端如果通过 Nginx 反向代理，Nginx 自带 proxy_read_timeout 默认 60 秒，所以服务端心跳周期设成 30 秒不会和代理冲突。源码包如果只写了 ping 没写 pong 处理，也要补上，因为协议规范要求在收到 ping 时回 pong。

5.2 缓冲区和线程分配：值定得越狠，性能掉得越快

连接数不多时缓冲区怎么设都看不出问题，到千级连接时参数就是生死线。每连接一个固定缓冲区的做法最直白，但 1000 个连接每个 64KB 就是 64MB 内存，这还不算业务处理过程中的临时副本。我一般把接收缓冲设为 4KB 起步、按需扩容到 64KB，长时间空闲的连接保持 4KB 即可。

线程模式是大头。每连接一线程写起来简单，但 2000 个连接就是 2000 个线程，Windows 上线程栈默认 1MB，光栈空间就占 2GB 虚拟内存。Delphi 源码包如果没有引入完成端口，基本都是每连接一线程，这种方案跑到 500 连接附近先看 CPU 再看内存，压力多数来自线程切换，而不是协议解析本身。要上大规模就在架构层面分割多实例，不追求单进程硬扛。

5.3 把参数从常量改成配置的 3 处修改

源码包里参数通常会写死在 WSConst.pas 里，方便但不利于部署。我一般会改成读取同目录下的 ini 文件，保留默认值兜底。

type TWSConfig = record Port: Integer; BindIP: string; MaxConnections: Integer; HeartbeatIntervalSec: Integer; RecvBufferSize: Integer; end; function LoadConfig(const AFileName: string): TWSConfig; var LIni: TIniFile; begin Result.Port := 9000; Result.BindIP := '0.0.0.0'; Result.MaxConnections := 1000; Result.HeartbeatIntervalSec := 30; Result.RecvBufferSize := 64 * 1024; if not FileExists(AFileName) then Exit; LIni := TIniFile.Create(AFileName); try Result.Port := LIni.ReadInteger('server', 'port', Result.Port); Result.BindIP := LIni.ReadString('server', 'bind_ip', Result.BindIP); Result.MaxConnections := LIni.ReadInteger('server', 'max_connections', Result.MaxConnections); Result.HeartbeatIntervalSec := LIni.ReadInteger('server', 'heartbeat_sec', Result.HeartbeatIntervalSec); Result.RecvBufferSize := LIni.ReadInteger('server', 'recv_buffer_size', Result.RecvBufferSize); finally LIni.Free; end; end;

注意 RecvBufferSize 是初始分配的单个连接缓冲区大小，不是所有连接的共享池。调大它只在该连接收到密集型消息时有效，对峰值并发用处不大。真正要调的是 MaxConnections 和 HeartbeatIntervalSec。上线前把配置文件和服务端 exe 放在同目录，改配置不用重新编译，省掉很多来回。

6. 收尾：用这几个验证动作确定服务端不会在你走后出生产问题

服务端源码包能编译、能跑出 hello world，只是第一步。真正可以放心上线，必须按下面这套动作做一遍验证，缺一项都可能留隐患。

先做协议合规验证。浏览器页面连上后，分别发送 1 字节、125 字节、126 字节、64KB 的消息，再发一段中文和一段 Emoji，确认服务端回显完整。这一步能同时覆盖掩码、长度分支和 UTF-8 解码。Emoji 是四字节 UTF-8，很多源码包只用三字节 UTF-8 会在这里翻车。

再做并发与注意状态验证。用 Python 写一个短脚本同时开 200 个 WebSocket 连接，每个连接循环发 100 条消息，观察服务端内存和句柄数是否平稳，断开一半连接后句柄是否落回来。

import asyncio import websockets async def client(i: int): uri = "ws://127.0.0.1:9000" async with websockets.connect(uri) as ws: for j in range(20): await ws.send(f"client-{i}-{j}") resp = await ws.recv() assert isinstance(resp, str) async def main(): tasks = [client(i) for i in range(200)] await asyncio.gather(*tasks, return_exceptions=True) # 脚本退出后，去服务端看句柄是否回落到基线 asyncio.run(main())

这个脚本用的是 websockets 库，不是标准库里的东西，但它是 Python 生态里验证 WebSocket 服务端最常用的工具。跑的时候注意在 Windows 命令行里把事件循环策略设成 WindowsSelectorEventLoopPolicy，否则 Windows 上可能报事件循环错误。

最后做断电模拟。在保持一批连接打开的状态下直接关闭客户端进程，等一个心跳周期加超时时间，再数服务端的活动连接。如果服务端能在一个心跳周期内清掉死连接，说明心跳代码是真的在工作。如果连接数不动，回去查第 4.5 小节，多半是心跳只发了 ping 没有检测 pong。

我自己的习惯是上线前把这些检查记成一张两页纸的核对单，部署时照着勾选。Delphi 写 WebSocket 服务端这事儿，真正困难的不是语法和组件，而是把 RFC 6455 的字节细节和 Windows 网络栈的脾气都摸透。等这套流程走顺了，服务端新加一条消息类型、一个鉴权逻辑，成本都很低。希望这篇文章能让你手里的源码包少走几夜弯路，也希望你写的服务端能扎扎实实跑住在线业务。

本文还有配套的精品资源，点击获取