# websocket

**Repository Path**: lyr421/websocket

## Basic Information

- **Project Name**: websocket
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-07
- **Last Updated**: 2026-02-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WebSocket服务器项目

## 项目简介

这是一个基于Spring Boot 4.0.2的高性能WebSocket服务器，支持高并发连接、消息推送、JWT认证和Redis集群模式，适用于实时通信场景。

### 核心特性

- ✅ **高并发支持**：基于Undertow容器，支持20万+并发连接
- ✅ **虚拟线程**：Spring Boot 4.0.2默认开启，提升性能
- ✅ **JWT认证**：WebSocket连接握手时进行身份验证
- ✅ **集群支持**：集成Redis，支持多实例部署
- ✅ **消息推送**：支持向单个用户或多个用户推送消息
- ✅ **健康检查**：集成Spring Boot Actuator，支持Kubernetes探针
- ✅ **Docker部署**：提供Dockerfile和docker-compose配置

## 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Spring Boot | 4.0.2 | 应用框架 |
| Java | 21 | 开发语言 |
| WebSocket | - | 实时通信 |
| JWT | 0.13.0 | 身份认证 |
| Redis | - | 集群支持 |
| Undertow | - | 高性能容器 |
| Actuator | - | 健康检查 |
| Docker | - | 容器化部署 |

## 项目结构

```
com.example.websocket
├── common/                # 通用模块
│   ├── exception/         # 异常处理
│   ├── result/            # 响应结果
│   └── util/              # 工具类
├── config/                # 配置模块
│   ├── auth/              # 认证相关配置
│   ├── JwtConfig.java     # JWT配置
│   ├── RedisStreamConfig.java # Redis Stream配置
│   └── WebSocketConfig.java # WebSocket配置
├── web/                   # HTTP API模块
│   ├── vo/                # 数据传输对象
│   ├── JwtTokenController.java # JWT令牌控制器
│   └── WebSocketPushController.java # WebSocket推送控制器
├── websocket/             # WebSocket核心模块
│   ├── constant/          # 常量定义
│   ├── handler/           # 消息处理器
│   ├── manager/           # 会话管理器
│   └── service/           # 业务服务
└── WebsocketApplication.java # 应用启动类
```

## 快速开始

### 环境要求

- JDK 21+
- Maven 3.6+
- Docker（可选，用于容器化部署）
- Redis（可选，用于集群模式）

### 本地运行

1. **克隆代码**
   ```bash
   git clone https://gitee.com/lyr421/websocket.git
   cd websocket
   ```

2. **编译项目**
   ```bash
   ./mvnw clean package -DskipTests
   ```

3. **运行应用**
   ```bash
   java -jar target/websocket-0.0.1-SNAPSHOT.jar
   ```

4. **访问服务**
   - WebSocket握手路径：`ws://localhost:8899/ws-server/ws/connect`
   - HTTP推送接口前缀：`http://localhost:8899/ws-server/api/websocket/push`
   - 健康检查接口：`http://localhost:8899/ws-server/actuator/health`

### Docker部署

1. **使用Docker Compose**
   ```bash
    git  clone https://gitee.com/lyr421/websocket.git
    git checkout dev
    git pull
    docker-compose up -d --build
   
   # 查看所有分支
   git branch -a

   # 停止所有服务（保留容器）
    docker compose stop
    # 停止并删除容器、网络，保留数据卷
    docker compose down
    # 停止并删除所有（容器、网络、数据卷、镜像）
    docker compose down -v --rmi all
   # 查看运行状态
    docker compose ps
   ```
   


2. **环境变量配置**
   可在`compose.yaml`文件中修改环境变量配置。

## API文档

### WebSocket接口

#### 连接建立
- **路径**：`/ws/connect`
- **参数**：需在查询参数中携带JWT令牌，例如：`?token=your-jwt-token`
- **说明**：建立WebSocket连接并进行身份验证

#### 消息格式

客户端发送消息格式：
```json
{
  "type": "message",
  "content": "消息内容",
  "target": "目标用户ID（可选）"
}
```

服务器推送消息格式：
```json
{
  "type": "push",
  "content": "消息内容",
  "timestamp": 1678901234567
}
```

### HTTP接口

#### 获取JWT令牌
- **路径**：`/api/jwt/token`
- **方法**：GET
- **参数**：`userId`（用户ID）
- **返回**：JWT令牌

#### 推送消息给单个用户
- **路径**：`/api/websocket/push/single`
- **方法**：POST
- **参数**：
  ```json
  {
    "userId": "用户ID",
    "message": "消息内容"
  }
  ```
- **返回**：推送结果

## 配置说明

### 核心配置文件

- `application.yaml`：基础配置
- `application-dev.yaml`：开发环境配置
- `application-prod.yaml`：生产环境配置

### 主要配置项

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| server.port | 服务端口 | 8899 |
| server.servlet.context-path | 上下文路径 | /ws-server |
| jwt.secret | JWT秘钥 | springboot4-websocket-secret-key-2025 |
| jwt.expire-time | Token过期时间（毫秒） | 86400000 |
| websocket.redis-enabled | 是否启用Redis | false |
| websocket.instance-id | 实例ID | 默认生成 |

## 集群部署

### Redis配置

1. **启用Redis**
   在配置文件中设置：
   ```yaml
   websocket:
     redis-enabled: true
   ```

2. **Redis连接配置**
   在`application.yaml`中添加Redis连接配置：
   ```yaml
   spring:
     redis:
       host: redis
       port: 6379
       password: your-redis-password
   ```

### Kubernetes部署

项目提供了Kubernetes部署配置文件：`deploy/k8s-deploy.yaml`

## 监控与运维

### 健康检查

- **健康状态**：`/actuator/health`
- **就绪检查**：`/actuator/health/readiness`
- **存活检查**：`/actuator/health/liveness`

### 日志管理

- 应用日志：默认输出到控制台
- 生产环境建议配置ELK或其他日志收集系统

## 开发指南

### 代码风格

- 遵循Spring Boot代码风格
- 使用Lombok简化代码
- 方法和变量命名清晰明了

### 测试

运行测试：
```bash
./mvnw test
```

## 故障排查

### 常见问题

1. **WebSocket连接失败**
   - 检查JWT令牌是否有效
   - 检查网络连接是否正常
   - 检查服务器端口是否开放

2. **消息推送失败**
   - 检查用户是否在线
   - 检查Redis连接是否正常（集群模式）
   - 检查消息格式是否正确

3. **集群模式不工作**
   - 检查Redis配置是否正确
   - 检查所有实例是否使用相同的Redis
   - 检查实例ID是否唯一

## 版本历史

| 版本 | 日期 | 变更内容 |
|------|------|----------|
| 0.0.1-SNAPSHOT | 2025 | 初始版本 |

## 许可证

本项目采用MIT许可证。

## 联系方式

- 项目地址：https://gitee.com/lyr421/websocket.git
- 作者：springboot4-websocket