# suws

**Repository Path**: ledc/suws

## Basic Information

- **Project Name**: suws
- **Description**: Su WebSocket是一个go语言编写的高性能WebSocket服务器，支持客户端连接管理、UID管理、群组管理、消息推送、RPC调用等功能；完全参考GatewayWorker设计的HTTP管理API接口。
- **Primary Language**: Go
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: https://suws.cn
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-09-24
- **Last Updated**: 2025-12-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Su WebSocket服务

SuWS是一个轻量级高性能的WebSocket服务器，支持客户端连接管理、用户身份管理、群组通信、安全认证、RPC调用等功能。

## 核心功能特性

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

## 启动服务

```shell
# 默认使用 config.json 配置文件
./suws

# 指定配置文件
./suws -c /path/to/config.json
```

## 配置文件

```json
{
  "token": "your_api_token",
  "webhook": "https://your-webhook-url.com/webhook",
  "webhook_timeout": 5,
  "log": {
    "verbose": false
  }
}
```

## WebSocket连接

### 连接地址

- ws://localhost:8788/ws
- ws://localhost:8788/websocket

### 连接流程

1. 客户端连接WebSocket服务器
2. 服务器返回初始化信息:

    ```json
    {
      "event": "init",
      "client_id": "客户端唯一标识",
      "auth": "认证字符串"
    }
    ```

3. 管理端可以使用返回的 `client_id` 和 `auth` 进行UID绑定

## API管理接口

所有HTTP 管理API接口都需要在请求头中包含 `token` 字段进行认证。