sgcWebSockets实战指南：Delphi实时通信从安装到wss压测

简介：sgcWebSockets-Enterprise-V2023.5-FS是一套面向企业环境的WebSocket服务器软件包，适用于在线游戏、实时分析仪表板、金融交易应用、聊天服务等需要高并发双向低延迟通信的场景，帮助开发者在自有系统中快速构建稳定可靠的实时消息通道。资源以单个7z压缩包形式发布，大小约66.64MB，由于上游未提供内部文件清单，暂无法罗列具体文件类型与数量，但整体打包便于下载后统一解压部署。已有145人学习/下载，适合具备Socket编程或服务端架构经验的开发者用于选型评估或二次开发。该企业版在标准WebSocket协议基础上，往往集成更精细的权限控制、SSL加密通道、负载均衡、集群支持、访问控制列表及日志审计等能力，可满足大型组织对数据安全与运维监控的要求；其API设计通常会兼顾易用性与扩展性，配合文档可快速接入现有业务系统。由于WebSocket本身具备跨平台特性，该软件包通常可运行于Windows、Linux、macOS等环境，具体API与配置方式以解压后官方文档为准。

1. 认识 sgcWebSockets-Enterprise-V2023.5-FS：一个 7z 背后的实时通信库

维护着一套十几年的 Delphi 服务，某天来了个需求：生产线告警要实时推到网页大屏。轮询被否后，团队第一反应是找 WebSocket 库，而 sgcWebSockets 几乎是 Delphi 这边绕不开的名字。标题里的 V2023.5 是发版代号，Enterprise 代表企业授权，FS 是 Full Source——意味着不仅能跑起来，还能读到库内部实现。7z 只是压缩封装，跟功能无关。

下面把拿到这个压缩包之后最该做的事走一遍：理清目录与 IDE 注册，跑通服务端和客户端最小工程，处理 wss 加密链路，最后补上压测、抓包与内存排查。适合正在维护 Delphi 项目、被实时需求推着走的工程师，也适合想定制协议行为的团队。直接进入解压环节。

2. 解压与 IDE 注册：把 V2023.5 变成可用的组件面板

2.1 从 7z 到源码目录：FS 包的常见布局

拿到sgcWebSockets-Enterprise-V2023.5-FS.7z，第一步当然是解压。常见做法不是在资源管理器里双击，而是用命令行，便于把路径固定下来：

7z x sgcWebSockets-Enterprise-V2023.5-FS.7z -oD:\ThirdParty\sgcWebSockets

x表示保留压缩包内目录结构完整解压，-o指定输出目录，注意-o与路径之间不能有空格；如果目录里已有同名文件，命令会停下来问是否覆盖，批量部署时建议先确认目录是干净的。解压完成后，一个标准的 FS（Full Source）包通常能看到下面几类目录：

不同构建版本对目录命名不完全一致，但 FS 包的核心一定是 src 和 samples 两处。拿到手先打开 samples 里任意一个工程编译一遍，能过说明当前 IDE 版本和库匹配；过不了就先不要研究功能，先把环境差异解决掉。这一步能省下后面大量排查时间。

2.2 两条安装路径：选预编译 bpl 还是选 dpk

安装方式取决于你要不要改库内部行为。如果只是想正常使用，走预编译包最快：打开 Delphi IDE，主菜单Component > Install Packages > Add，在解压目录里选中与当前 IDE 版本对应的.bpl文件，确定后组件面板会出现 sgcWebSockets 分类。32 位和 64 位目标平台通常有各自的 bpl，安装时看准后缀，别把 Win32 的包装进 Win64 工程里。

需要改动源码或者跟踪连接状态内部实现时，得走第二条路：用File > Open Project打开库自带的.dpk工程文件，编译并 Install。这里有一个容易忽略的细节：一个 FS 包里可能同时存在 Runtime Package 与 Design Time Package 两组工程，先装 Runtime 再装 Design Time，否则 IDE 会报找不到类。装完后在任意新建工程里点开组件面板，确认能看到 WebSocketServer、WebSocketClient、Socket.IO 等条目再继续。

提示：解压和 IDE 注册全程会被杀毒软件或 Windows Defender 拦下，尤其是 dcu、bpl 这类二进制文件。项目目录加入白名单再操作，避免装到一半文件被隔离。

2.3 全源码编译配置：把 src 挂进 Search Path

预编译 bpl 隐藏了源码实现，而 FS 版的价值恰恰在于可以读源码、断点进库内部。因此我一般建议团队统一走源码编译。配置很直接：在工程Project > Options > Delphi Compiler里，把 Search Path 追加到解压目录的src路径，然后打开任意 sample 工程重新编译。

需要留意的是，库内部可能依赖第三方单元，比如 OpenSSL 相关 binding。若编译报找不到.pas，回解压目录看是否有thirdparty或lib子目录，把其中与当前平台匹配的源码路径也加进 Search Path。Enterprise 版通常比 Standard 版多出 MQTT、Socket.IO、负载均衡扩展组件，这些扩展可能有额外依赖，按编译错误一条条补路径即可。

编译完成后随手在 Form 上拖一个TSgcWebSocketServer组件看属性面板是否弹出——这一步能同时验证 bpl 加载和源码路径没配错。如果属性面板空白，多半是 DesignTime 包未注册，重跑一遍 2.2 的 Install 流程。

3. 服务端最小工程：用 TSgcWebSocketServer 拉起 7777 端口

3.1 组件初始化：代码创建还是从面板拖

在 Form 上拖一个组件最直观，但代码创建更便于团队统一版本管理。两种方式都常见，我的习惯是代码初始化，因为端口、绑定地址、回调函数集中在 FormCreate 里，换了机器改一处就能跑。下面是一个最小启动过程：

procedure TMainForm.FormCreate(Sender: TObject); begin FServer := TSgcWebSocketServer.Create(Self); FServer.Port := 7777; FServer.Bind := '0.0.0.0'; FServer.MaxConnections := 2048; FServer.OnConnect := ServerConnect; FServer.OnMessage := ServerMessage; FServer.OnDisconnect := ServerDisconnect; try FServer.Active := True; except on E: Exception do Log('监听失败: %s', [E.Message]); end; end;

Port指定 TCP 监听端口，开发环境用 7777 这类高位端口不需要管理员权限；生产环境如果前面有负载均衡或 Nginx，这里的端口只对内网开放。Bind指向监听网卡，0.0.0.0表示所有网卡都接受连接，能让局域网内的测试机直接连；如果只想本地调试，改成127.0.0.1更安全。MaxConnections是一个软上限，超过后新连接会被拒绝，具体数值取决于单连接内存占用和系统 fd 限制，不要盲目调大。Active置 True 才真正开始监听，这一步绑定端口失败会直接抛异常，所以外层必须包 try/except。

不同构建版本里这个组件在面板上可能叫TTsgcWebSocketServer或别的变体名，以安装后实际类名为准。代码里用TSgcWebSocketServer是最常见写法，但类名前缀差异不影响后续属性使用。

3.2 三个核心回调：连接、消息、断开

服务端的业务逻辑基本都写在事件回调里。回调触发时机和参数含义决定了你该在哪处理什么，下面这张表列出几个最常用的事件：

OnMessage 是核心，里面能拿到当前连接上下文和客户端发来的文本数据。处理完逻辑后通过Connection.WriteData回写，即可把结果推给单个客户端。实现片段：

procedure TMainForm.ServerMessage(Connection: TsgcWSConnection; Data: string); begin if Data = 'ping' then begin Connection.WriteData('pong'); Exit; end; HandleBusinessMessage(Connection, Data); end;

Data默认按文本帧处理；如果客户端发的是二进制帧，部分版本会有独立的二进制回调或DataType参数，以 samples 里的完整签名为准。Connection是一条连接的上下文对象，整个连接生命周期内复用，要保存用户态数据时可以直接挂在它关联的会话对象上，不要自己维护字典。

回调运行在 socket 工作线程里，直接访问 VCL 控件会引发跨线程访问错误。我一般会把所有界面刷新用TThread.Queue包一层：

TThread.Queue(nil, procedure begin mmoLog.Lines.Add(Format('[%s] 收到消息: %s', [Now.ToString, Data])); end);

这里TThread.Queue把匿名过程丢回主线程执行，不阻塞当前 socket 线程。虽然 sgcWebSockets 内部对部分操作做了同步，但自己写业务回调时默认控件都不是线程安全的，养成这个习惯能避免诡异闪退。

3.3 启动时序与浏览器端回环测试

启动过程有个容易忽略的点：Active := True不是异步的，它会在当前线程里完成端口绑定和监听创建。因此 FormCreate 里如果写了其他耗时操作，要保证它们不会阻塞在组件初始化前面太久，否则窗口假死。端口被占用时异常从这里抛出，错误信息里会带 socket error code 10048，看到它基本就是端口冲突，换端口或释放占用即可。

服务端启动后，可以用浏览器控制台快速验证链路是否真的通了。打开任意网页，F12 进入 Console 粘贴：

const ws = new WebSocket('ws://127.0.0.1:7777'); ws.onopen = () => ws.send('ping'); ws.onmessage = (ev) => console.log('服务端返回：', ev.data);

这段脚本创建一条 WebSocket 连接，握手成功后发送文本ping，收到回包就打印内容。如果onopen不触发，先检查服务端是不是真的在监听：Windows 下用netstat -ano | findstr 7777，Linux 下用ss -lntp | grep 7777，确认端口存在再深入排查。能收到pong，说明服务端的监听、握手、消息分发、回调回写这套主链路已经跑通，可以开始接业务了。

4. 客户端与 wss：从 ws:// 平滑切换到加密链路

4.1 TSgcWebSocketClient 的最小连接代码

服务端就绪后，客户端通常用同一套库实现，这样握手细节和帧解析逻辑可以复用。常见做法是拖一个TSgcWebSocketClient到独立客户端工程，或者在代码里创建。连接只需要指定三个要素：目标地址、端口、路径。

FClient := TSgcWebSocketClient.Create(Self); FClient.Host := '10.0.0.8'; FClient.Port := 7777; FClient.URI := '/ws'; FClient.SSL := False; try FClient.Active := True; except on E: Exception do Log('连接失败: %s', [E.Message]); end;

Host填目标服务器 IP 或域名都可以，Port必须与服务器监听端口一致。URI是握手阶段的 HTTP 路径，如果服务端没做路由区分，保持/或/ws都行；如果后面要按路径分流，这个字段就是服务端区分业务模块的依据。SSL置False时走明文ws://，置True时改用wss://。Active触发的是同步连接逻辑，目标不可达时会在 TLS 握手或 TCP 建立阶段抛异常，用 try/except 包住才能拿到具体错误原因。

回环测试时，客户端连自己本机就用127.0.0.1。如果 7777 端口服务端没有开启 TLS，客户端这里绝不能把SSL打开，否则握手阶段双方协议不匹配，连接直接失败。

4.2 证书与 SSL 驱动：PFX、PEM 到底怎么选

切到wss://之后，敏感数据在网络上就是密文传输，但同时也引入证书配置问题。sgcWebSockets 底层支持 OpenSSL 与 Windows SChannel 两种 TLS 驱动，常见做法是 Windows 上走 SChannel 直接加载 PFX，Linux 容器里走 OpenSSL 加载 PEM 证书和私钥。

从证书商拿到的文件通常是一张 CRT 证书和一把 KEY 私钥，而 Windows 下 SChannel 更习惯 PFX 这种把两者打成一个文件的格式。转换命令很少需要背，抄下来改文件名就行：

openssl pkcs12 -export -in server.crt -inkey server.key -out server.pfx

pkcs12是格式转换子命令，-export表示输出一个 PKCS#12 文件，-in指定证书文件，-inkey指定私钥文件，-out是输出路径。转换过程中会要求设置导出密码，这个密码后面在组件属性里要对应填上。开发环境自签证书经常遇到客户端报证书校验失败，排查时先确认系统时间是否正确，再确认证书链是否完整，这两个是自签名环境里最常见的两个坑。

如果不想让桌面进程直接处理证书，也可以把 TLS 终结放在 Nginx Stream 或云负载均衡上，后端服务继续走明文。这样证书更新、协议版本控制都收敛到接入层，后端组件保持简单。具体取舍看团队运维能力，内网环境自签证书省事，暴露到公网还是建议前置一层统一管理。

4.3 子协议与数据帧类型：不止文本消息

WebSocket 握手阶段有一个容易被忽略的字段叫 Subprotocol，用来让客户端和服务端协商一个上层协议名。服务端配置了允许的子协议后，客户端握手时必须带一个匹配值，否则连接会被拒绝。这个机制适合用来做版本隔离：比如只允许带v1.chat的客户端接入，老版本客户端如果发的是空协议或旧协议名，在握手阶段就被挡住，不会进到业务层。

数据帧类型也同样值得注意。文本帧适合传 JSON，可读性高；二进制帧适合传原始字节流。比如从老旧系统拿到的数据是 GBK 编码，直接塞进 JSON 里转义很麻烦，用二进制帧发过去更省事。库的回调通常会区分文本和二进制两种消息入口，打开 samples 里的对应 demo 看一眼方法签名，按类型分流处理即可。

客户端断线重连是生产环境逃不掉的需求。企业版组件里一般有重连相关属性，比如重连开关和重连间隔，按业务场景设置成 3 到 5 秒一次比较稳妥。间隔太短会在服务端重启期间打出一堆无效连接，间隔太长用户感知明显，5 秒是大多数团队的默认选择。

5. 上线前三件事：压测、抓包与内存回收

5.1 用 Python 快速灌连接，验证并发握手

服务端写完后不要急着接业务，先用脚本把连接数和回包延迟摸一遍。Python 的websockets库够用，脚本控制在几十行内就能出结果：

import asyncio import time import websockets async def one_round(i): async with websockets.connect('ws://127.0.0.1:7777') as ws: t0 = time.perf_counter() await ws.send('ping') await ws.recv() return time.perf_counter() - t0 async def main(): results = await asyncio.gather(*[one_round(i) for i in range(200)]) results.sort() p99 = results[198] * 1000 print(f'200 连接完成后 p99 延迟: {p99:.1f} ms') asyncio.run(main())

这段脚本使用asyncio.gather并发创建 200 条连接，每条连接发送ping等待pong后关闭，最后排出第 99 百分位延迟。它测的是握手加一次消息往返的开销，不是吞吐，吞吐要用每连接连续多发消息配合并发数一起来看。如果 p99 超过 50ms，先检查服务端回调里有没有做同步磁盘写或数据库访问，这些往往是延迟元凶。

5.2 Wireshark 过滤与 Full Source 内存排查

延迟异常时抓包是最快的定位手段。Wireshark 里过滤条件写tcp.port == 7777，抓到 WebSocket 帧后右键选择Decode As > WebSocket，就能看到握手请求、响应码和后续数据帧。握手阶段最常见的失败码是 400 和 403，分别对应子协议不匹配和鉴权拒绝，响应头里会带具体原因。TLS 环境下证书问题则表现为握手中断在 Client Hello 之后，这时关掉 Wireshark 的 TLS 解密或配置好私钥再抓。

内存问题在长连接服务里比延迟更隐蔽。FS 全源码的优势在这里能发挥出来：在TsgcWSConnection的释放相关入口打断点，观察连接断开后会话对象是否被正确清理。如果回调里创建了自定义对象而在 OnDisconnect 中忘了释放，长时间运行后内存会缓慢爬升。Delphi 工程的 DPR 文件里加上ReportMemoryLeaksOnShutdown := True;，退出时后会输出泄漏报告，里面会列出泄漏对象的类名和数量。把报告里的类名在源码里搜一下，基本就能定位到没有释放的位置，再顺着调用栈往回找是哪个回调漏了处理。这个方法比反复用任务管理器看内存曲线高效得多。

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