简介面向Delphi 12.3开发者的sgcWebSockets企业版WebSocket服务器控件压缩包是一份面向企业级实时通信场景的专业组件资源适合正在构建聊天室、行情推送系统、远程监控平台或需要WebSocket高并发服务端的开发团队使用。压缩包整体约151.44MB内附企业版核心组件、安装配置文档及多组可供调用的高级API能够帮助开发者在Delphi中直接借助标准WebSocket协议完成双向通信不再需要自行封装底层数据帧。已有169人学习下载尤其适合熟悉Delphi却希望快速补齐实时通信功能的中高级程序员。借助这份压缩包可获得带身份验证、安全加密、负载均衡、高级路由等特性的现成功能模块随附的说明文件则具体讲解了在Delphi 12.3环境下的安装、服务器参数定制、安全选项调整以及服务端代码编写清单足以帮助开发者缩短从下载到部署的熟悉周期将更多精力集中在业务逻辑之上高效交付实时网络应用。1. 从 HTTP 轮询到全双工Delphi 12.3 里为什么值得换 WebSocket做实时监控和行情推送老方案是几秒一次 HTTP 轮询延迟和服务器负载都大变化也要一个请求周期才能到达。WebSocket 在 TCP 上做全双工通信握手上是 HTTP 升级之后服务端可以主动推送浏览器端体验完全不同。sgcWebSockets Enterprise V2023.5 就是给 Delphi 12.3 准备的服务端 WebSocket 控件。FS 代表带完整源码D12 对应 Delphi 12 的目标版本。它把握手、连接管理、身份校验、心跳保活、广播推送这些环节做成组件事件适合用 Delphi 写桌面端和服务端、又要把数据实时推到网页或移动端的团队。2. 解压即编译sgcWebSockets Enterprise V2023.5 在 Delphi 12.3 的安装路线安装这类控件最怕的是版本名和 IDE 版本对不上。先看后缀FS 指 Full Source包内会带上 .pas 单元而不是只有 .dcuD12 表示这个包按 Delphi 12 系列编译V2023.5 是 sgcWebSockets 的版本快照。压缩包里通常还带一个安装说明.txt我一般先读这份文件因为里面会写清楚它测试过的 IDE 版本和依赖项比网上二手教程可靠。2.1 解压后先做目录规划建议不要解压到 Delphi 的安装目录而是放到独立的第三方库目录例如D:\ThirdParty\sgcWebSockets_V2023.5。原因是后续升级 IDE 或换版本时只需要改 Library 路径不用动系统目录。解压后应该能看到sgcWebSocket.pas、sgcWebSocketServer.pas、sgcWebSocketClient.pas等服务端和客户端的核心单元以及一组.dpk包文件。这里给一个常见的包文件命名习惯实际以你解压出来的为准文件后缀含义D12对应 Delphi 12包名里通常带 D12 或 IDE 版本号Enterprise企业版包含 TLS/SSL、压缩、高级认证等增强功能FSFull Source附带完整 .pas 源代码安装说明.txt官方安装步骤务必先读2.2 配置 Library 搜索路径在 Delphi 12.3 菜单里打开Tools - Options - Language - Delphi - Library把D:\ThirdParty\sgcWebSockets_V2023.5和它的源码子目录加进 Library path。这里有一个常用技巧把源码根目录整个加进去之后Delphi 会递归搜索 .pas 文件但有些版本只认显式目录不见得识别子目录。所以要对包裹结构把src或sources目录也手动加进去。加完路径后可以用下面这段代码在编译期确认组件单元被找得到省得等编译到一半才报找不到sgcWebSocket{$IF not DECLARED(TsgcWebSocketServer)} {$MESSAGE ERROR sgcWebSockets source path not found} {$IFEND}这段代码放在任一单元顶部即可。DECLARED是编译器判定标识符是否可见的指令找不到类型时直接中止编译比链接期报错更好排查。2.3 用 IDE 编译并注册组件在项目管理器里打开对应 Delphi 12 的包.dpk文件名通常带 D12 或 IDE 版本号右键执行 Build如果提示缺少依赖优先回头检查 Library 路径而不是急着装包。Build 成功后再打开带 Design 前缀的包文件右键执行 InstallDesign 页面会多出一组sgcWebSocketServer、sgcWebSocketClient等图标。安装完成后新建一个 VCL 或 FMX 工程往窗体上拖一个TsgcWebSocketServer控件检查 Object Inspector 里能看到 Port、BindIPs、Active 等属性就说明安装成功。注意如果你的 Delphi 装的是 Community Edition同样按 D12 的包编译即可这控件不区分社区版还是专业版。如果想系统学一遍 Delphi 服务端开发我建议装完后直接按 F12 追进sgcWSServer.pas看连接状态机怎么迁移比单看示例代码收益高。提示Library 路径加错是最常见的安装失败原因报错多集中在找不到 *.dcu 或 *.pas。先确认目录里有对应的单元文件再检查 IDE 的 Library 配置不要急着重装包。3. 让服务端跑起来TsgcWebSocketServer 的连接事件与消息收发安装完成只是热身真正要理解的是这套控件的事件模型。sgcWebSockets 把连接生命周期拆成了 OnConnect、OnMessage、OnDisconnect 几个事件每个事件都拿到一个TsgcWSConnection对象。这个对象代表一条 WebSocket 连接发送、关闭、读取 Header 这些操作都挂在它上面。事件回调运行在 IO 线程里不是 VCL 主线程所以不能在事件里直接访问窗体控件这是个新手很容易踩的坑。3.1 最小监听服务端口、绑定 IP 与握手在窗体上放一个按钮和一个TsgcWebSocketServer代码里配置监听端口和绑定地址procedure TForm1.btnStartServerClick(Sender: TObject); begin WebSocketServer1.Port : 8080; WebSocketServer1.BindIPs.Clear; WebSocketServer1.BindIPs.Add(0.0.0.0); WebSocketServer1.OnConnect : ServerConnect; WebSocketServer1.OnMessage : ServerMessage; WebSocketServer1.OnDisconnect : ServerDisconnect; WebSocketServer1.Active : True; end;Port用 8080 而不是 80是因为 80 容易被其他服务占用调试阶段也要避开系统保留端口。BindIPs里0.0.0.0表示监听本机所有网卡部署时建议收敛到内网 IP避免把服务暴露到公网。Active : True会立刻完成监听端口初始化和握手前的 HTTP 监听准备但并不代表已经有客户端连接。3.2 三个关键事件OnConnect / OnMessage / OnDisconnect下面是最常用的事件骨架事件签名按常见版本写如果你的库里多了TextType之类的参数按实际声明补齐即可procedure TForm1.ServerConnect(Sender: TObject; Connection: TsgcWSConnection); begin // 连接建立时给客户端打个招呼 Connection.WriteData(welcome); end; procedure TForm1.ServerMessage(Sender: TObject; Connection: TsgcWSConnection; const Text: string); begin // 收到客户端消息原样返回 Connection.WriteData(Text); end; procedure TForm1.ServerDisconnect(Sender: TObject; Connection: TsgcWSConnection); begin // 清理和这个连接相关的状态 end;WriteData是连接对象上发送文本的方法sgcWebSockets 不同小版本里也出现过SendData、SendMessage这样的同名方法以你源码里TsgcWSConnection公开的方法为准。OnConnect里可以读握手请求OnDisconnect在连接被正常关闭或异常断开时都会触发适合清理会话。事件触发时机典型用途OnConnectWebSocket 握手完成、连接进入就绪状态鉴权、写入在线列表、发送初始化数据OnMessage收到完整的文本或二进制帧处理业务请求、转发消息OnDisconnect连接关闭包括异常断开移除在线列表、结束会话OnErrorIO 层异常记录日志、补偿重连为什么异常断开也要走 OnDisconnect因为 WebSocket 的关闭帧不一定每次都能收到网络闪断、对端进程崩溃都不会正常发关闭帧。sgcWebSockets 在 TCP 层发现连接失效后最终还是会触发 OnDisconnect所以在线状态清理放这里最稳妥。3.3 从 Echo 到广播维护在线列表并定向推送实际业务很少只做回声。要做群发前先用TDictionary保存连接FConnections : TDictionarystring, TsgcWSConnection.Create; procedure TForm1.ServerConnect(Sender: TObject; Connection: TsgcWSConnection); begin FConnections.Add(Connection.Guid, Connection); Connection.WriteData(welcome); end; procedure TForm1.ServerDisconnect(Sender: TObject; Connection: TsgcWSConnection); begin FConnections.Remove(Connection.Guid); end; procedure TForm1.BroadcastAll(const AMessage: string); var LConn: TsgcWSConnection; begin for LConn in FConnections.Values do LConn.WriteData(AMessage); end;用Connection.Guid作为 Key是因为同一个客户端断开重连后会拿到新连接对象靠 IP 区分不靠谱。如果你安装的版本里没有Guid属性用IntToHex(NativeInt(Connection))也能凑合但可读性和稳定性都差一些。广播时如果想跳过某个连接就在循环里判断LConn CurrentConnection。库本身也提供Broadcast方法底层逻辑就是遍历连接逐个写但自带实现的过滤条件少自己维护字典还有个好处可以在 OnDisconnect 后立刻移除失效连接避免向死连接写数据触发异常。注意TDictionary在System.Generics.Collections单元里VCL 和 FMX 工程都要手动加上这个 uses。事件回调发生在 IO 线程如果这里碰了上市窗体上的TLabel.Caption大概率会在运行期收到线程安全错误稳妥做法是同步到主线程再更新界面。4. 企业级参数调优心跳、认证、反向代理与 1006 断线真实环境里客户端和服务器之间隔了交换机、防火墙、反向代理空闲连接很容易被中间设备回收。最常见的问题表现是连接静置几分钟后用 WebSocket King 一测客户端收到[websocket] onclose, code: 1006, reason:, reconnect: true。面试里如果被问 1006 是什么记住它是异常关闭码和正常的 1000 关闭码相对。这种异常关闭表示连接在没有收到关闭帧的情况下被切断几乎可以断定是链路超时或服务端没发心跳。4.1 心跳参数HeartBeatInterval 与 1006 的处理sgcWebSockets 的服务器组件上有心跳相关属性常见的是HeartBeatInterval和HeartBeatTimeout。前者控制每隔多少毫秒发送一次 PING 帧后者控制等待 PONG 回来的最长时间超出就判定连接失效并主动关闭。经验值我会设HeartBeatInterval : 3000030 秒一次心跳能穿过大多数防火墙的空闲超时阈值HeartBeatTimeout给 5000 到 10000避免网络抖动直接误杀。场景HeartBeatIntervalHeartBeatTimeout说明普通内网6000015000内网丢包率低心跳不需要太快跨公网或经 nginx3000010000公网和代理设备容易掐空闲连接高并发长连接4500010000心跳太频繁会放大 IO 线程压力收到 1006 后客户端必须靠断线重连逻辑恢复会话。服务端这边能做的是在 OnDisconnect 里记录时间和会话数据等客户端重连回来时根据握手 Header 里的会话 ID 恢复现场而不是把消息直接丢掉。心跳参数往大调不是万能药如果中间设备的空闲超时是 15 秒那 60 秒一次心跳照样会被掐反过来心跳太密又会在几万连接时明显增加线程开销所以先查一下网络设备的 TCP idle timeout 再从下往上设。4.2 用握手 Header 做身份校验对接 JWTWebSocket 也不建议裸奔。sgcWebSockets 的TsgcWSConnection上可以读到客户端握手时带来的 HTTP Header比如Authorization: Bearer token。在 OnConnect 里校验 token校验失败就调用连接的关闭方法让握手阶段直接失败function TForm1.ValidateToken(const AHeader: string): Boolean; begin Result : Copy(AHeader, 1, 7) Bearer ; end; procedure TForm1.ServerConnect(Sender: TObject; Connection: TsgcWSConnection); begin // 有些版本里属性叫 Connection.Header按实际 TsgcWSConnection 声明调整 if not ValidateToken(Connection.Headers[Authorization]) then begin Connection.Close; Exit; end; FConnections.Add(Connection.Guid, Connection); Connection.WriteData(welcome); end;Headers返回请求头集合取不到对应字段时返回空串。实际项目里建议在更早的OnConnecting或OnValidateAuthentication阶段做避免无效连接消耗资源。签名校验要做防篡改时间戳和随机数也要进去单纯 Base64 解码不等于安全。如果你用的是 JWT就按 RS256/HS256 验签验签通过后再把用户 ID 存到一个业务字典里后续 OnMessage 直接取不用重复解析 token。注意Connection.Close只是关闭当前连接如果已经写入了在线字典紧接着要手动移除否则下一次广播会拿到一个已经断开的连接对象。4.3 nginx 反向代理与负载均衡下的 WebSocket 参数当客户端不直连 Delphi 服务端而是先走到 nginx 时代理层必须显式升级连接。否则会看到服务端有握手但客户端一直停在 Connecting。nginx 里对应 location 的配置location /ws/ { proxy_pass http://delphi_ws_backend; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_read_timeout 60s; }proxy_pass指向上游 Delphi 服务器的 HTTP 端口比如一台机器上开 8080。关键参数是Upgrade和Connection upgrade缺了它们 nginx 会把 WebSocket 当成普通 HTTP 请求转发握手永远完成不了。proxy_read_timeout要和心跳间隔匹配我一般设成心跳间隔加 10 秒否则 nginx 这边的空闲超时比服务端心跳还短连接照样会被切断。负载均衡如果挂在多台 Delphi 服务之间注意 WebSocket 会话通常有粘性。因为服务端会话状态在内存里轮询会把同一个用户的连接分到不同机器。方案有两个nginx 上按客户端 IP 或自定义 Header 做ip_hash或者把会话数据外置到 Redis。sgcWebSockets 本身不自带集群会话同步外置状态是更干净的思路。这类排错经验通用Go 的 gin WebSocket 和 Java 的 Spring WebSocket 在 nginx 层配置几乎一样都是改这几个proxy_set_header所以你在别的项目里踩过的坑可以直接搬过来。5. 实战技巧把业务逻辑交给线程别在 OnMessage 里做重活连上几十个客户端后容易发现某个客户端发来一个慢查询其他客户端推送全部卡住。原因就是 OnMessage 跑在 IO 线程里你在里面执行数据库查询或远程调用等于把整个接收线程堵死。正确姿势是 OnMessage 只做两件事解析消息、把任务丢进队列业务线程处理完后再统一通过服务器组件推送。5.1 用 TThreadedQueue 解耦耗时任务我这里用TThreadedQueue做一个简单任务队列。OnMessage 收到消息后把任务对象放进去后台线程取出执行执行完成后推送动作本身是线程安全的可以直接调用服务器组件发送type TJob record ConnectionGuid: string; Payload: string; end; FQueue : TThreadedQueueTJob.Create(1000);后台任务线程里用PopItem取出任务调用业务逻辑后从连接字典取出TsgcWSConnection再写数据。注意不要让队列无限增长Create的第一个参数是队列容量默认 Push/Pop 超时是 0表示立即返回。我习惯容量设 1000处理不过来时宁愿阻塞接收也不把消息丢进一个无界队列把内存写爆。5.2 联调验证用 WebSocket King 连本地服务写完推送逻辑后用 WebSocket King 这类客户端连ws://127.0.0.1:8080验证。连接成功后先看服务端有没有触发 OnConnect再在客户端发一条消息看回包确认心跳时间点。如果从外部网络连推荐用浏览器控制台直接跑一行脚本const ws new WebSocket(ws://127.0.0.1:8080); ws.onmessage (e) console.log(e.data); ws.onclose (e) console.log(close, e.code, e.reason);服务端推送验证时在线状态维护的准确性最关键。我看过不少现场广播时报错说找不到连接往下追是字典里保留了已断开的连接。所以推送前至少要做一次连接状态判断或者直接 catch 发送异常后再在 OnDisconnect 里补一次清理。最稳的一步是在 OnDisconnect 里调用FConnections.Remove前把返回值和 Count 打日志if not FConnections.Remove(Connection.Guid) then OutputDebugString(PChar(warn: missing connection Connection.Guid));调试阶段这行日志能立刻暴露重复清理或连接未注册的问题频繁重连的场景下只看 warn 频率就能判断是心跳太慢还是代理超时太短不用再猜。本文还有配套的精品资源点击获取