# sxran-im-center

**Repository Path**: sxran-im/sxran-im-center

## Basic Information

- **Project Name**: sxran-im-center
- **Description**: sxran-im的通讯中心，主要目标降低即时通讯门槛，快速打造低成本接入在线IM系统，通过极简洁的消息格式就可以实现多端不同协议间的消息发送如内置(Http、Websocket、Tcp自定义IM协议)等，并提供通过http协议的api接口进行消息发送无需关心接收端属于什么协议，一个消息格式搞定一切！
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: wlh-dev-v2
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3502
- **Created**: 2023-11-17
- **Last Updated**: 2025-12-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 即时通讯, 客服, 聊天, 社交, IM

## README


````markdown
# 🚀 WebSocket Relay Gateway（HTTP 上行 + WebSocket 下行 通信中间层）

> 一款统一上行 HTTP 与下行 WebSocket 的高性能通信中间层，专为微服务架构、实时推送场景设计。

---

## 📖 产品简介

**WebSocket Relay Gateway** 是一个支持：
- **HTTP 上行（前端 → 后端）**
- **WebSocket 下行（后端 → 前端）**

的通用通信中间层。

它的设计灵感来源于实际项目（如 `yudao-cloud` 架构）中对实时消息的统一管理需求，旨在简化 WebSocket 连接的管理、解耦消息推送逻辑，并为未来扩展 MQTT、Kafka、RocketMQ 等实时通道打下基础。

---

## 🧩 设计理念

在复杂系统中，实时消息往往面临以下痛点：

1. **WebSocket 上行编码复杂**  
   WebSocket 需要长期保持连接状态，消息封装与错误处理不如 HTTP 简单直观。

2. **微服务多点连接问题**  
   不同服务提供不同的业务能力，但前端无法同时维持多个 WebSocket 连接。

3. **统一下行消息通道缺乏**  
   各模块各自实现推送逻辑，导致维护困难。

因此我们提出统一方案：

| 类型 | 通道协议 | 描述 |
|------|-----------|------|
| 上行 | **HTTP** | 前端通过 HTTP 调用业务接口（标准 RESTful） |
| 下行 | **WebSocket** | 后端通过中间层（Relay Gateway）推送实时消息 |

---

## 🏗️ 系统架构

```text
         ┌──────────────────────────────┐
         │          前端应用             │
         │    ├─ HTTP 请求  ─────────┐   │
         │    └─ WebSocket 连接 ─────┤   │
         └──────────────────────────────┘
                        │
                        ▼
         ┌──────────────────────────────┐
         │   WebSocket Relay Gateway    │
         │    （统一 WebSocket 服务）   │
         │                              │
         │ 1️⃣ 管理客户端连接            │
         │ 2️⃣ 接收业务系统推送          │
         │ 3️⃣ 转发至对应 WebSocket 客户 │
         └──────────────────────────────┘
                        ▲
                        │
          ┌────────────────────────────┐
          │       各业务微服务         │
          │  通过 HTTP 上行接收请求    │
          │  通过 RPC / MQ 调用 Gateway │
          │  下行推送实时消息           │
          └────────────────────────────┘
````

---

## ⚙️ 典型通信流程

### 1️⃣ 上行（前端 → 后端）

* 协议：HTTP
* 流程：

  ```
  前端 HTTP → 业务服务接口（如 system-server）
  ```
* 作用：提交业务请求、数据上报、用户操作指令等。

### 2️⃣ 下行（后端 → 前端）

* 协议：WebSocket
* 流程：

  ```
  后端（任意服务） → Gateway 推送接口 → WebSocket 客户端
  ```
* 作用：通知推送、状态更新、实时消息。

---

## 🔄 与方案一（纯 WebSocket）对比

| 对比项   | 方案一：纯 WebSocket | 方案二：HTTP + WebSocket（推荐） |
| ----- | --------------- | ------------------------ |
| 上行协议  | WebSocket       | HTTP                     |
| 下行协议  | WebSocket       | WebSocket                |
| 编码复杂度 | 高，需要维护状态        | 低，标准 HTTP 请求             |
| 微服务支持 | 需要多个连接          | ✅ 单一 Gateway 统一转发        |
| 消息追踪  | 不易调试            | ✅ HTTP 请求天然可追踪           |
| 扩展性   | 较差              | ✅ 可平滑升级至 MQTT / Kafka    |

---

## 💡 应用场景

* 聊天、通知、告警推送系统
* 实时看板、监控平台
* IoT 设备网关（可替换为 MQTT）
* 微服务集群中统一下行消息中心

---

## 🧰 技术实现参考

* WebSocket 服务：Spring Boot + Netty（或使用 `spring-websocket`）
* 上行接口：标准 Spring MVC REST API
* 消息中转：Redis / RabbitMQ / Kafka（可选）
* 客户端鉴权：JWT / Session / API Token
* 扩展支持：MQTT 协议桥接（EMQX、Aliyun MQTT、Tencent MQTT）

---

## 🚀 快速部署

```bash
# 1. 克隆仓库
git clone https://github.com/your-org/websocket-relay-gateway.git
cd websocket-relay-gateway

# 2. 启动服务
mvn spring-boot:run

# 3. 前端连接 WebSocket
wss://your-domain/ws/connect?token=xxx
```

---

## 💬 推送示例

### 服务端推送接口（HTTP）

```http
POST /api/push
Content-Type: application/json

{
  "userId": "1001",
  "type": "notice",
  "content": "您的订单已发货"
}
```

### 前端接收（WebSocket）

```js
const ws = new WebSocket("wss://your-domain/ws/connect?token=xxx");

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("📩 收到消息：", data);
};
```

---

## 🧱 模块划分

| 模块              | 说明                           |
| --------------- | ---------------------------- |
| `infra-server`  | 提供 WebSocket 服务，管理连接与推送      |
| `system-server` | 业务逻辑层，通过 HTTP 上行接收请求         |
| `relay-client`  | SDK，封装后端推送 HTTP 调用逻辑         |
| `gateway`（可选）   | 微服务网关，转发 HTTP 与 WebSocket 请求 |

---

## 🔒 安全性设计

* WebSocket 连接支持 **JWT 鉴权**
* 支持按用户、租户、会话隔离
* 推送接口受 **API Token** 或 **内部服务认证** 控制
* 可配置消息加密与压缩（如 gzip / deflate）

---

## 📦 未来规划

* [ ] 支持 MQTT 协议桥接（EMQX、阿里云 MQTT）
* [ ] 支持消息持久化与离线推送
* [ ] 提供多语言 SDK（JavaScript / Java / Go）
* [ ] 控制台管理界面（查看连接、推送日志）

---

## [📖 API接口说明](./API.md) 



## 📜 License

Apache License 2.0

---

## ❤️ 致谢

本项目设计思想参考自：

* [Yudao Cloud 微服务架构](https://github.com/YunaiV/yudao-cloud)
* [EMQX MQTT Broker](https://www.emqx.io)
* [Spring WebSocket 文档](https://docs.spring.io/spring-framework/reference/web/websocket.html)

```

---

是否希望我帮你继续生成该产品的 **目录结构（含 Java 模块划分与示例代码）**？  
那样可以让你直接创建一个可运行的初版项目骨架（`infra-server` + `system-server` + `relay-client`）。
```