自 自在知识库
首页归档分类标签图谱关于
Admin Core

即时通讯模块（IM）技术文档

即时通讯模块基于 WebSocket 协议与 Redis 消息队列构建，提供客户端与服务端双向实时通信能力。该模块支持模块数据同步、用户实时通知等应用场景，通过标准化配置与事件驱动机制，实现消息低延迟传输及精准分发。

· 8 分钟阅读 ·更新于 2026.06.13

概述

即时通讯模块基于 WebSocket 协议与 Redis 消息队列构建，提供客户端与服务端双向实时通信能力。该模块支持模块数据同步、用户实时通知等应用场景，通过标准化配置与事件驱动机制，实现消息低延迟传输及精准分发。

本文档聚焦模块刷新场景，详细说明配置规范、消息收发流程及开发注意事项，助力开发者快速完成业务集成。

1. 配置说明

1.1 服务端配置

文件路径：MyCompanyName.Modules.ImServer.Host/appsettings.json

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "ImServerConfig": {
    "RedisClientConnectionString": "127.0.0.1:6379,password=,poolsize=10,defaultDatabase=6",
    "Servers": ["127.0.0.1:17010"],
    "Server": "127.0.0.1:17010",
    "InputEncodingName": "GB2312",
    "OutputEncodingName": "GB2312",
    "HealthChecks": {
      "Enable": true,
      "Path": "/health"
    }
  }
}

关键配置项说明：

配置项 说明
RedisClientConnectionString Redis 客户端连接字符串
Servers 集群节点地址列表（单机部署填写当前节点地址）
Server 当前服务节点标识
HealthChecks 健康检查配置

1.2 客户端配置

文件路径：MyCompanyName.Modules.System.Host/imconfig.json

1
2
3
4
5
6
7
8
{
  "ImConfig": {
    "Enable": true,
    "Servers": ["127.0.0.1:17010"],
    "Server": "ws://127.0.0.1:17010",
    "RedisConnectionString": "127.0.0.1:6379,password=,defaultDatabase=6"
  }
}

关键配置项说明：

配置项 说明
Enable 是否启用 IM 功能
RedisConnectionString 需与服务端 Redis 配置完全一致
Server WebSocket 连接地址，协议头需为ws:// 或 wss://

2. 消息推送机制

2.1 后端推送代码示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// ModuleService.cs
public async Task<long> AddAsync(ModuleAddInput input)
{
    // ...业务逻辑...

    if (_imConfig.Enable)
    {
        // 推送 IM 消息
        ImHelper.SendMessage(
            senderId: 0,                     // 系统消息发送者 ID
            receiveUserIds: [User.Id],        // 接收用户 ID 列表
            message: new
            {
                evts = new[]
                {
                    new
                    {
                        name = "refreshModule",  // 事件名称
                        data = new { }           // 事件数据（可扩展）
                    }
                }
            }
        );
    }
    else
    {
        throw ResultOutput.Exception(_adminLocalizer["请开启im即时通讯"]);
    }
}

2.2 参数说明

参数 说明
senderId 0 表示系统消息
receiveUserIds 指定接收用户 ID 列表（支持群发）
message 消息体需包含evts 事件数组

3. 消息接收机制

3.1 前端事件类型定义

1
2
3
4
// types/mitt.d.ts
declare type MittType<T = any> = {
  refreshModule?: T  // 模块刷新事件
}

3.2 Vue 组件监听实现

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<!-- sys/module/index.vue -->
<script lang="ts" setup>
import eventBus from '/@/utils/mitt'

onMounted(() => {
  // 注册事件监听
  eventBus.on('refreshModule', async () => {
    await reloadTable()      // 刷新表格数据
    ElMessage.success('模块已更新')
  })
})

onBeforeMount(() => {
  // 组件卸载时移除监听
  eventBus.off('refreshModule')
})
</script>

3.3 生命周期控制说明

  • onMounted：初始化事件监听
  • onBeforeMount：移除事件监听，避免内存泄漏
  • 使用 off() 确保单例监听正确清理

4. 完整流程示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
前端提交请求
      ↓
业务后端处理
      ↓
IM 服务端存储消息（Redis 消息队列）
      ↓
Redis 确认推送
      ↓
IM 服务端推送消息（WebSocket）
      ↓
前端事件触发（mitt）
      ↓
前端重新请求数据
      ↓
业务后端返回最新数据

详细流程说明：

  1. 前端提交请求：前端向业务后端发送新增模块的请求
  2. 业务后端处理：业务后端接收请求，通过 ImHelper 向 IM 服务端发送 refreshModule 事件
  3. IM 服务端存储消息：IM 服务端将消息存储到 Redis 的消息队列中
  4. Redis 确认推送：Redis 完成消息存储后，通知 IM 服务端消息推送已就绪
  5. IM 服务端推送消息：IM 服务端通过 WebSocket 将消息推送到前端
  6. 前端事件触发：前端接收到消息后，通过 mitt 触发 refreshModule 事件
  7. 前端重新请求数据：前端向业务后端重新请求模块列表数据
  8. 业务后端返回数据：业务后端返回最新的模块列表数据给前端

5. 注意事项

5.1 Redis 一致性校验

确保服务端 ImServerOptions.RedisClient 与客户端 ImConfig.RedisConnectionString 的配置保持一致：

  • 数据库编号一致
  • 密码配置一致
  • 连接池配置合理

5.2 WebSocket 地址协议

环境 协议 说明
开发环境 ws:// 非加密连接
生产环境 wss:// 需配置 SSL 证书

5.3 事件命名规范

建议使用 [业务模块][操作类型] 格式，例如：

  • userLogout
  • orderStatusUpdate
  • refreshModule

5.4 性能优化

  • 高频事件建议添加防抖处理
  • 批量操作时合并事件推送

5.5 调试建议

  • 使用 Redis 桌面工具监控消息队列
  • 使用浏览器开发者工具查看 WebSocket 连接状态

#消息队列 #Redis #分布式/消息传递 #配置文件 #API接口