前言

几年来一直用GatewayWorker，因其文档完善、上手简单，当前已能够熟练使用。

因项目需要RPC（远程过程调用）调用一个硬件设备，对go语言多少懂一点，想着用AI写一个WebSocket单机版本的服务，所有API参考GatewayWorker来设计、新增一个RPC调用接口，编译后只有一个可执行文件（13.65 MB），运行时不依赖任何中间件，得益于go语言的goroutine和跨平台特性，性能出乎意料的好。

我给她起了个名字 SuWS （Simple Universal WebSocket Server）寓意：

1. S - Simple 简单、简洁易用特性
2. U - Universal 通用、具有广泛的适用性和跨平台能力
3. W - WebSocket 仅支持WebSocket协议
4. S - Server 服务器端实现

开发过程就是AI对话，使用的阿里 通义 大模型。成品后，全部代码2500多行。

核心功能特性

1. WebSocket连接管理

• 支持WebSocket客户端连接和断开管理
• 自动生成客户端ID和认证信息
• 支持心跳检测机制（Ping/Pong）
• 自动清理超时连接（45秒无心跳）

2. 客户端管理

• 客户端身份标识（client_id）
• 客户端级Session管理
• 客户端在线状态查询
• 主动断开指定客户端连接

3. 用户绑定系统（UID）

• 支持将客户端与用户ID（UID）绑定/解绑
• 用户在线状态管理
• 支持向指定UID的所有客户端发送消息
• 用户级Session管理

4. 群组管理

• 客户端加入/离开群组
• 群组解散功能
• 群组内消息广播
• 群组成员查询和统计

5. 消息推送功能

• 向所有客户端广播消息
• 向指定客户端发送消息
• 向指定UID的所有客户端发送消息
• 向群组内客户端发送消息
• 支持排除特定客户端或用户

6. RPC调用支持

• 支持向客户端发起RPC调用
• 等待并处理客户端RPC响应
• 超时机制（10秒）

7. 安全认证机制

• Token认证模式
• 签名验证模式（安全模式）
• 认证失败次数限制和IP封禁
• 请求签名验证（基于时间戳）

8. 监控和统计

• 服务运行状态监控
• 内存使用情况统计
• 在线客户端和用户统计
• 群组信息统计
• 健康检查接口
• 运行时信息查看

9. 配置管理

• JSON配置文件支持
• 配置热重载功能
• Webhook配置支持
• 连接池配置

10. Webhook通知

• 客户端绑定/解绑事件通知
• 用户上线/下线事件通知
• 心跳事件通知
• 可配置的Webhook超时和连接池

11. 错误处理和日志

• 详细的错误码和错误信息
• 可配置的日志级别（调试/发布模式）
• 结构化日志输出

12. 性能优化

• 细粒度读写锁提高并发性能
• 连接池管理
• 心跳检测间隔自适应调整
• 内存使用优化

13. API接口

• 完整的RESTful API接口
• 分组管理（公共接口/认证接口）
• 丰富的查询和管理接口

14. 部署特性

• 命令行参数支持（配置文件路径、版本信息、安全模式）
• 版本信息管理
• 灵活的端口配置

SuWS 提供了完整的实时通信解决方案，支持大规模客户端连接管理、用户身份管理、群组通信、安全认证等多种企业级特性。

开源仓库及相关链接

• SuWS 服务端 https://github.com/ledccn/suws/releases
• SuWS PHP-SDK https://github.com/ledccn/suws-php-sdk
• 接口文档，可以在线调试 https://docs.apipost.net/docs/509d32d3087e000?locale=zh-cn
• SuWS官网，建设中 https://suws.cn

安装 Installation

composer require ledc/websocket

运行环境

PHP版本：>=8.3

接口文档

https://docs.apipost.net/docs/509d32d3087e000?locale=zh-cn

快速开始 Quick Start

可以在 .env 文件中配置环境变量

SUWS_TOKEN=管理令牌（与SUWS服务端配置一致）
SUWS_URL=http://127.0.0.1:8788/api
SUWS_TIMEOUT=5

或者通过函数设置环境变量：

\Ledc\Websocket\suws_set_env('管理Token', 'http://127.0.0.1:8788/api', 5);

然后，使用单例模式调用：

use Ledc\Websocket\SuWS;

// 向所有客户端或者指定的客户端发送数据
$result = SuWS::getInstance()->sendToAll();

// 向指定的客户端发送数据
$result = SuWS::getInstance()->sendToClient();

// 关闭指定的客户端的连接
$result = SuWS::getInstance()->closeClient();

// 判断指定客户端是否在线
$result = SuWS::getInstance()->isOnline();

// 获取ClientId会话信息
$result = SuWS::getInstance()->getSession();

// 设置ClientId会话信息
$result = SuWS::getInstance()->setSession();

// 获取所有在线ClientId总数量
$result = SuWS::getInstance()->getAllClientIdCount();
$result = SuWS::getInstance()->getAllClientCount();

// 获取所有在线ClientId列表
$result = SuWS::getInstance()->getAllClientIdList();

// 获取所有在线Client会话信息
$result = SuWS::getInstance()->getAllClientSessions();

// 将client_id与uid绑定
$result = SuWS::getInstance()->bindUid();

// 解除client_id与uid的绑定
$result = SuWS::getInstance()->unbindUid();

// 判断用户是否在线
$result = SuWS::getInstance()->isUidOnline();

// 发送消息给指定UID
$result = SuWS::getInstance()->sendToUid();

// 通过UID获取ClientIds
$result = SuWS::getInstance()->getClientIdByUid();

// 通过ClientId获取UID
$result = SuWS::getInstance()->getUidByClientId();

// 获取所有在线UID列表
$result = SuWS::getInstance()->getAllUidList();

// 获取所有在线UID总数量
$result = SuWS::getInstance()->getAllUidCount();

// 获取UID会话信息
$result = SuWS::getInstance()->getUidSession();

// 设置UID会话信息
$result = SuWS::getInstance()->setUidSession();

// RPC调用
$result = SuWS::getInstance()->rpc();

// 加入群组
$result = SuWS::getInstance()->joinGroup();

// 离开群组
$result = SuWS::getInstance()->leaveGroup();

// 解散群组
$result = SuWS::getInstance()->ungroup();

// 发送消息给群组
$result = SuWS::getInstance()->sendToGroup();

// 获取群组在线ClientId总数量
$result = SuWS::getInstance()->getClientIdCountByGroup();

// 获取群组在线客户端的会话信息
$result = SuWS::getInstance()->getClientSessionsByGroup();

// 获取群组在线ClientId列表
$result = SuWS::getInstance()->getClientIdListByGroup();

// 获取群组在线UID列表
$result = SuWS::getInstance()->getUidListByGroup();

// 获取群组在线UID总数量
$result = SuWS::getInstance()->getUidCountByGroup();

// 获取所有群组名称列表
$result = SuWS::getInstance()->getAllGroupIdList();

// 获取UID加入的群组名称列表
$result = SuWS::getInstance()->getGroupByUid();

// 重新加载配置文件
$result = SuWS::getInstance()->reloadConfig();

// 获取配置
$result = SuWS::getInstance()->getConfig();