# ss-im

**Repository Path**: harrisonxin/ss-im

## Basic Information

- **Project Name**: ss-im
- **Description**: ss-im 是一款简单便捷的即时通讯工具，基于Netty高性能框架实现。目前仅支持文字单聊,后面还会支持图片、语音、视频等。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2024-12-01
- **Last Updated**: 2026-07-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ss-im

## 介绍

ss-im 是一款简单便捷的即时通讯工具，基于 Netty 高性能框架实现。目前仅支持文字单聊，后面还会支持图片、语音、视频等。

## 模块结构

| 模块 | 说明 |
|---|---|
| `ss-im-code` | 核心 SDK，以 Maven 依赖方式对外发布 |
| `ss-im-server` | 基于 Spring Boot 的参考实现，可作为开发起点 |

源码根包：`xin.harrison.im`（早期版本曾使用 `cn.legaltech.lb.im`，已迁移）。

## 安装教程

maven 添加依赖：

```xml
<dependency>
    <groupId>io.gitee.harrisonxin</groupId>
    <artifactId>ss-im-code</artifactId>
    <version>1.0.2</version>
</dependency>
```

## 使用说明

### 1. 添加配置文件，使用 `@NettyServer` 注解与 `@MessageMapping` 注解

#### `@NettyServer` 注解

- `port` 端口，默认 8086
- `wsPath` WebSocket 路径，默认 `/ws`
- `packageName` 消息处理类所在包名，框架会扫描该包下所有带 `@MessageMapping` 的方法并自动注册

#### `@MessageMapping` 注解

| 属性 | 说明 |
|---|---|
| `value` | 消息类型，与客户端发送的 `type` 字段对应 |
| `async` | 是否异步处理，默认同步；异步通过 `ctx.executor().execute` 提交，建议耗时操作才开 |
| `priority` | 优先级，默认 0（当前未实现排序逻辑，仅占位） |
| `authRequired` | 是否需要鉴权，默认 false；启用后框架只检查 Channel 上是否存在 `token` 属性，**不会自动调用 `JwtUtil.validateToken`**，业务处理器需自行校验 |

#### `@RequiresPermission` 注解

当前仅定义、未被框架调用，请勿依赖。

### 2. ⚠️ 关键陷阱：默认 Pipeline 不走注解路由

`ChildHandlerServerInitializer` 当前默认在 Pipeline 末端添加的是 `WebSocketServerMsgHandler`（简易 echo 版），**不会**调用 `MessageDispatcher.dispatch`。

这意味着：

- 框架通过 `ScannerHandler` 反射注册的 `@MessageMapping` 方法**全部不会生效**
- 业务 handler 即使被 `ScannerHandler` 加载，也永远不会被分发调用

要让注解路由真正生效，需要把 Pipeline 末端替换为 `WebSocketServerHandler`（`xin.harrison.im.handler.WebSocketServerHandler`），它内部会调用 `MessageDispatcher.dispatch` 完成路由。

修改方式：编辑 `ChildHandlerServerInitializer.java` 第 68 行，将 `new WebSocketServerMsgHandler()` 改为 `new WebSocketServerHandler()`。

### 3. 启动服务

`ss-im-server` 参考实现：

```bash
mvn -pl ss-im-server spring-boot:run
```

启动后：

- Spring HTTP：`http://localhost:8080`
- Netty WebSocket：`ws://localhost:8086/ws`

## 消息协议

客户端发送 JSON 文本帧：

```json
{
  "type": "chat",
  "content": "toUserId:body",
  "senderId": "u1",
  "targetId": "u2"
}
```

`content` 字段约定（业务字符串切片，不是 JSON 字段）：

- 私聊：`toUserId:content`
- 加入房间：`roomId:userId`
- 房间广播：`roomId:content:senderId`

已实现消息类型：`auth` / `login` / `logout` / `chat` / `text` / `file` / `image` / `audio` / `video` / `private_message` / `broadcast` / `get_online_users` / `ping` / `join_room` / `leave_room` / `broadcast_room`。

## JWT 配置

密钥解析优先级：`JWT_SECRET_KEY` 环境变量 → `jwt.secret.key` 系统属性 → `application.yml` 中 `jwt.secret-key` → 自动生成 256 位随机密钥（开发模式告警）。

详细说明见 [`ss-im-server/README-JWT.md`](./ss-im-server/README-JWT.md)。

## 状态管理

`xin.harrison.im.dispatcher` 包下的 `UserChannelManager`、`RoomManager`、`MessageProcessorManager` 均为静态集合，单进程内存态，**不支持集群部署**。

注意：`ScannerHandler` 通过 classpath 文件系统扫描识别 `.class`，**不支持 jar 包内类扫描**，业务 handler 必须与应用代码同 classloader。

## 参考文档

- [`ss-im-server/README.md`](./ss-im-server/README.md) —— 服务端消息格式
- [`ss-im-server/README-JWT.md`](./ss-im-server/README-JWT.md) —— JWT 密钥管理
- [`ss-im-server/README-ONE-TO-ONE-CHAT.md`](./ss-im-server/README-ONE-TO-ONE-CHAT.md) —— 一对一聊天完整协议 + JavaScript 客户端示例
- [`ss-im-server/env.example`](./ss-im-server/env.example) —— 环境变量模板