跳转到主要内容

​
WuKongIM协议

WuKongIM 协议是一个高效的二进制通信协议，专为即时通讯场景设计。本文档详细描述了协议的报文结构、控制类型和编码规范。

​
📋 控制报文结构

每个 WuKongIM 控制报文都由以下三个部分组成：
参数名类型说明
Fixed header1 byte固定报头
Variable headerbytes可变报头
Payloadbytes消息体

​
🔧 固定报头

每个 WuKongIM 控制报文都包含一个固定报头，用于标识报文类型和长度信息。
Bit76543210
byte 1WuKongIM控制报文的类型WuKongIM控制报文的类型WuKongIM控制报文的类型WuKongIM控制报文的类型用于指定控制报文类型的标志位用于指定控制报文类型的标志位用于指定控制报文类型的标志位用于指定控制报文类型的标志位
byte 2…剩余长度剩余长度剩余长度剩余长度剩余长度剩余长度剩余长度剩余长度

​
📝 WuKongIM 控制报文类型

WuKongIM 协议定义了10种不同的控制报文类型，每种类型都有特定的用途和数据结构。
名字值描述
Reserved0保留位
CONNECT1客户端请求连接到服务器(c2s)
CONNACK2服务端收到连接请求后确认的报文(s2c)
SEND3发送消息(c2s)
SENDACK4收到消息确认的报文(s2c)
RECV5收取消息(s2c)
RECVACK6收取消息确认(c2s)
PING7ping请求
PONG8对ping请求的相应
DISCONNECT9请求断开连接
EVENT10事件通知

​
🏷️ 控制报文标志位

不同的协议报文使用不同的标志位来控制消息行为： Send和Recv协议中的标志位
bit3210
byteDUPSyncOnceRedDotNoPersist
Connack协议中的标志位
bit3210
byteReservedReservedReservedHasServerVersion
Chunk协议中的标志位
bit3210
byteReservedReservedReservedEnd
标志位说明：
  • DUP: 是否是重复的消息(客户端重发消息的时候需要将DUP标记为1)
  • SyncOnce: 只同步一次 在多端设备的情况下 如果有一个设备拉取过此消息，其他设备将不会再拉取到此消息（比如加好友消息）
  • RedDot: 客户端收到消息是否显示红点
  • NoPersist: 是否不存储此消息
  • Reserved: 保留位
  • HasServerVersion: 是否有服务端版本号
  • End: 是否是结束的消息块

​
📏 剩余长度编码

剩余长度字段表示在当前消息中剩余的字节数，包含可变头部和负荷(内容)。这是一个可变长度编码字段。
编码规则：
  • 单个字节最大值：01111111 (0x7F, 127)
  • 第八位（最高位）为 1 表示还有后续字节
  • 最多允许 4 个字节表示剩余长度
  • 最大长度：0xFF,0xFF,0xFF,0x7F = 268,435,455 byte = 256MB
字节范围：
DigitsFromTo
10 (0x00)127 (0x7F)
2128 (0x80, 0x01)16 383 (0xFF, 0x7F)
316 384 (0x80, 0x80, 0x01)2 097 151 (0xFF, 0xFF, 0x7F)
42 097 152 (0x80, 0x80, 0x80, 0x01)268 435 455 (0xFF, 0xFF, 0xFF, 0x7F)
编码理解：
  • 第1字节基数：1
  • 第2字节基数：128 (2^7)
  • 第3字节基数：128×128 = 2^14
  • 第4字节基数：128×128×128 = 2^21
编码示例： 表达 321 = 65 + 2×128 (2字节)：11000001 00000010 
第一个字节 193 (11000001)：
  - 最高位为1，表示还有后续字节
  - 低7位为1000001 (65)

第二个字节 2 (00000010)：
  - 最高位为0，表示结束
  - 低7位为0000010 (2)

计算：321 = 65 + 2 × 128 = 65 + 256
字节顺序：第一个字节是低位，后续字节是高位，但字节内部是低位在右，高位在左。

​
🔤 字符串 UTF-8 编码

WuKongIM 采用修改版的 UTF-8 编码格式：
bit76543210
byte 1String Length MSBString Length MSBString Length MSBString Length MSBString Length MSBString Length MSBString Length MSBString Length MSB
byte 2String Length MSBString Length MSBString Length MSBString Length MSBString Length MSBString Length MSBString Length MSBString Length MSB
bytes 3…Encoded Character DataEncoded Character DataEncoded Character DataEncoded Character DataEncoded Character DataEncoded Character DataEncoded Character DataEncoded Character Data

​
🔄 可变报头

某些控制报文包含一个可变报头部分，位于固定报头和有效载荷之间。可变报头的内容根据报文类型的不同而不同。

​
📡 协议报文规范

​
🔌 CONNECT 连接报文

客户端向服务端发起连接请求时使用的报文格式。
参数名类型说明
Packet Type0.5 byte报文类型(1)
Flag0.5 byte标示位
Remaining Length… byte报文剩余长度
Protocol Versionint8协议版本号
Device Flagint8设备标示(同标示同账号互踢)
Device IDstring设备唯一ID
UIDstring用户ID
Tokenstring用户的token
Client Timestampint64客户端当前时间戳(13位时间戳,到毫秒)
Client Keystring客户端KEY (客户端KEY (base64编码的DH公钥))

​
✅ CONNACK 连接确认

CONNACK 报文由服务端发送，作为对客户端 CONNECT 报文的响应。如果客户端在合理时间内没有收到 CONNACK 报文，应该关闭网络连接。
参数名类型说明
Packet Type0.5 byte报文类型(2)
Flag0.5 byte标示位
Remaining Length… byte报文剩余长度
ServerVersionuint8服务器支持的最大版本 flag包含HasServerVersion的时候有效
Time Diffint64客户端时间与服务器的差值，单位毫秒。
Reason Codeuint8连接原因码（见附件）
Server Keystring服务端base64的DH公钥
Saltstring安全码

​
📤 SEND 发送消息

客户端向服务端发送消息时使用的报文格式。
参数名类型说明
Packet Type0.5 byte报文类型(3)
Flag0.5 byte标示位
Remaining Length… byte报文剩余长度
Setting1 byte消息设置
Client Sequint32客户端消息序列号(由客户端生成，每个客户端唯一)
Client Msg Nostring客户端唯一标示，用于客户端消息去重
StreamNostring流式消息编号（setting里需要开启Stream）
Channel Idstring频道ID（如果是个人频道ChannelId为个人的UID）
Channel Typeint8频道类型（1.个人 2.群组）
Expireuint32消息过期时间（单位秒） version>=3
Msg Keystring用于验证此消息是否合法（仿中间人篡改）
Topicstring话题ID（只有setting开启了topic才有此字段）
Payload… byte消息内容

​
✅ SENDACK 发送消息确认

服务端对客户端发送消息的确认响应。
参数名类型说明
Packet Type0.5 byte报文类型(4)
Flag0.5 byte标示位
Remaining Length… byte报文剩余长度
Message IDuint64服务端的消息ID(全局唯一)
Client Sequint32客户端消息序列号
Message Sequint32消息序号（有序递增，频道唯一）
Reason Codeuint8发送原因代码 1表示成功

​
📥 RECV 收消息

服务端向客户端推送消息时使用的报文格式。
参数名类型说明
Packet Type0.5 byte报文类型(5)
Flag0.5 byte标示位
Remaining Length… byte报文剩余长度
Setting1 byte消息设置（见下 版本4有效）
Msg Keystring用于验证此消息是否合法（仿中间人篡改）
From UIDstring发送者UID
Channel IDstring频道ID
Channel Typeint8频道类型
Expireuint32消息过期时间（单位秒） version>=3
Client Msg Nostring客户端唯一标示，用于客户端消息去重
StreamNostring流式消息编号，根据setting是否开启stream判断是否有此字段
StreamIduint32流序号，根据setting是否开启stream判断是否有此字段
Message IDuint64服务端的消息ID(全局唯一)
Message Sequint32服务端的消息序列号(有序递增，频道唯一)
Message Timestampint32服务器消息时间戳(10位，到秒)
Topicstring话题ID（只有setting开启了topic才有此字段）
Payload… byte消息内容

​
✅ RECVACK 收消息确认

客户端对服务端推送消息的确认响应。
参数名类型说明
Packet Type0.5 byte报文类型(6)
Flag0.5 byte标示位
Remaining Length… byte报文剩余长度
Message IDuint64服务端的消息ID(全局唯一)
Message Sequint32序列号

​
🏓 PING

客户端发送的心跳请求报文，用于保持连接活跃。
参数名类型说明
Packet Type0.5 byte报文类型(7)
Flag0.5 byte标示位

​
🏓 PONG

服务端对客户端 PING 请求的响应报文。
参数名类型说明
Packet Type0.5 byte报文类型(8)
Flag0.5 byte标示位

​
🔌 DISCONNECT

客户端或服务端请求断开连接时使用的报文格式。
参数名类型说明
Packet Type0.5 byte报文类型(9)
Flag0.5 byte标示位
Remaining Length… byte报文剩余长度
ReasonCodeuint8原因代码
Reasonstring原因

​
📢 EVENT 事件通知

服务端向客户端推送事件通知时使用的报文格式。事件通知用于传递系统状态变化、用户行为通知等非消息类型的信息。
参数名类型说明
Packet Type0.5 byte报文类型(10)
Flag0.5 byte标示位
Remaining Length… byte报文剩余长度
Idstring事件ID（事件唯一标识符）
Typestring事件类型（如：user_online、user_offline、channel_update等）
Timestampint64事件时间戳（13位时间戳，到毫秒）
Payload… byte事件数据内容
事件类型示例：
  • user_online: 用户上线事件
  • user_offline: 用户下线事件
  • channel_update: 频道信息更新事件
  • member_join: 成员加入频道事件
  • member_leave: 成员离开频道事件
  • typing: 用户正在输入事件

​
⚙️ 消息设置

​
📊 消息设置位字段

消息设置为 1 byte (8 bit)，用于控制消息的各种行为特性。
bit76543210
byteReceiptReservedSignalNoEncryptTopicReservedStreamReserved

​
🔧 设置位说明

各位功能说明：
  • Receipt: 消息已读回执，此标记表示此消息需要已读回执
  • Reserved: 保留位，暂未用到
  • Signal: 加密标记
  • NoEncrypt: 消息是否不开启加密
  • Topic: 消息是否包含 topic（如果为 1 则发送包和接受包都将包含 topic 字段）
  • Reserved: 保留位，暂未用到
  • Stream: 流式消息标记
  • Reserved: 保留位，暂未用到
完整协议文档: 本文档包含了 WuKongIM 协议的核心部分。完整的协议规范还包括 Payload 推荐结构、普通消息格式、系统消息格式等详细内容，请参考源文档获取完整信息。