二进制协议

WuKongIM 通信协议详细规范和报文结构说明

​

WuKongIM协议

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

---

​

📋 控制报文结构

每个 WuKongIM 控制报文都由以下三个部分组成：

参数名	类型	说明
Fixed header	1 byte	固定报头
Variable header	bytes	可变报头
Payload	bytes	消息体

---

​

🔧 固定报头

每个 WuKongIM 控制报文都包含一个固定报头，用于标识报文类型和长度信息。

Bit	7	6	5	4	3	2	1	0
byte 1	WuKongIM控制报文的类型	WuKongIM控制报文的类型	WuKongIM控制报文的类型	WuKongIM控制报文的类型	用于指定控制报文类型的标志位	用于指定控制报文类型的标志位	用于指定控制报文类型的标志位	用于指定控制报文类型的标志位
byte 2…	剩余长度	剩余长度	剩余长度	剩余长度	剩余长度	剩余长度	剩余长度	剩余长度

​

📝 WuKongIM 控制报文类型

WuKongIM 协议定义了10种不同的控制报文类型，每种类型都有特定的用途和数据结构。

名字	值	描述
Reserved	0	保留位
CONNECT	1	客户端请求连接到服务器(c2s)
CONNACK	2	服务端收到连接请求后确认的报文(s2c)
SEND	3	发送消息(c2s)
SENDACK	4	收到消息确认的报文(s2c)
RECV	5	收取消息(s2c)
RECVACK	6	收取消息确认(c2s)
PING	7	ping请求
PONG	8	对ping请求的相应
DISCONNECT	9	请求断开连接
EVENT	10	事件通知

​

🏷️ 控制报文标志位

不同的协议报文使用不同的标志位来控制消息行为：

Send和Recv协议中的标志位

bit	3	2	1	0
byte	DUP	SyncOnce	RedDot	NoPersist

Connack协议中的标志位

bit	3	2	1	0
byte	Reserved	Reserved	Reserved	HasServerVersion

Chunk协议中的标志位

bit	3	2	1	0
byte	Reserved	Reserved	Reserved	End

标志位说明：

• DUP: 是否是重复的消息(客户端重发消息的时候需要将DUP标记为1)
• SyncOnce: 只同步一次 在多端设备的情况下 如果有一个设备拉取过此消息，其他设备将不会再拉取到此消息（比如加好友消息）
• RedDot: 客户端收到消息是否显示红点
• NoPersist: 是否不存储此消息
• Reserved: 保留位
• HasServerVersion: 是否有服务端版本号
• End: 是否是结束的消息块

​

📏 剩余长度编码

剩余长度字段表示在当前消息中剩余的字节数，包含可变头部和负荷(内容)。这是一个可变长度编码字段。

编码规则：

• 单个字节最大值：01111111 (0x7F, 127)
• 第八位（最高位）为 1 表示还有后续字节
• 最多允许 4 个字节表示剩余长度
• 最大长度：0xFF,0xFF,0xFF,0x7F = 268,435,455 byte = 256MB

字节范围：

Digits	From	To
1	0 (0x00)	127 (0x7F)
2	128 (0x80, 0x01)	16 383 (0xFF, 0x7F)
3	16 384 (0x80, 0x80, 0x01)	2 097 151 (0xFF, 0xFF, 0x7F)
4	2 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 编码格式：

bit	7	6	5	4	3	2	1	0
byte 1	String Length MSB	String Length MSB	String Length MSB	String Length MSB	String Length MSB	String Length MSB	String Length MSB	String Length MSB
byte 2	String Length MSB	String Length MSB	String Length MSB	String Length MSB	String Length MSB	String Length MSB	String Length MSB	String Length MSB
bytes 3…	Encoded Character Data	Encoded Character Data	Encoded Character Data	Encoded Character Data	Encoded Character Data	Encoded Character Data	Encoded Character Data	Encoded Character Data

---

​

🔄 可变报头

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

---

---

​

📡 协议报文规范

​

🔌 CONNECT 连接报文

客户端向服务端发起连接请求时使用的报文格式。

参数名	类型	说明
Packet Type	0.5 byte	报文类型(1)
Flag	0.5 byte	标示位
Remaining Length	… byte	报文剩余长度
Protocol Version	int8	协议版本号
Device Flag	int8	设备标示(同标示同账号互踢)
Device ID	string	设备唯一ID
UID	string	用户ID
Token	string	用户的token
Client Timestamp	int64	客户端当前时间戳(13位时间戳,到毫秒)
Client Key	string	客户端KEY (客户端KEY (base64编码的DH公钥))

​

✅ CONNACK 连接确认

CONNACK 报文由服务端发送，作为对客户端 CONNECT 报文的响应。如果客户端在合理时间内没有收到 CONNACK 报文，应该关闭网络连接。

参数名	类型	说明
Packet Type	0.5 byte	报文类型(2)
Flag	0.5 byte	标示位
Remaining Length	… byte	报文剩余长度
ServerVersion	uint8	服务器支持的最大版本 flag包含HasServerVersion的时候有效
Time Diff	int64	客户端时间与服务器的差值，单位毫秒。
Reason Code	uint8	连接原因码（见附件）
Server Key	string	服务端base64的DH公钥
Salt	string	安全码

​

📤 SEND 发送消息

客户端向服务端发送消息时使用的报文格式。

参数名	类型	说明
Packet Type	0.5 byte	报文类型(3)
Flag	0.5 byte	标示位
Remaining Length	… byte	报文剩余长度
Setting	1 byte	消息设置
Client Seq	uint32	客户端消息序列号(由客户端生成，每个客户端唯一)
Client Msg No	string	客户端唯一标示，用于客户端消息去重
StreamNo	string	流式消息编号（setting里需要开启Stream）
Channel Id	string	频道ID（如果是个人频道ChannelId为个人的UID）
Channel Type	int8	频道类型（1.个人 2.群组）
Expire	uint32	消息过期时间（单位秒） version>=3
Msg Key	string	用于验证此消息是否合法（仿中间人篡改）
Topic	string	话题ID（只有setting开启了topic才有此字段）
Payload	… byte	消息内容

​

✅ SENDACK 发送消息确认

服务端对客户端发送消息的确认响应。

参数名	类型	说明
Packet Type	0.5 byte	报文类型(4)
Flag	0.5 byte	标示位
Remaining Length	… byte	报文剩余长度
Message ID	uint64	服务端的消息ID(全局唯一)
Client Seq	uint32	客户端消息序列号
Message Seq	uint32	消息序号（有序递增，频道唯一）
Reason Code	uint8	发送原因代码 1表示成功

​

📥 RECV 收消息

服务端向客户端推送消息时使用的报文格式。

参数名	类型	说明
Packet Type	0.5 byte	报文类型(5)
Flag	0.5 byte	标示位
Remaining Length	… byte	报文剩余长度
Setting	1 byte	消息设置（见下 版本4有效）
Msg Key	string	用于验证此消息是否合法（仿中间人篡改）
From UID	string	发送者UID
Channel ID	string	频道ID
Channel Type	int8	频道类型
Expire	uint32	消息过期时间（单位秒） version>=3
Client Msg No	string	客户端唯一标示，用于客户端消息去重
StreamNo	string	流式消息编号，根据setting是否开启stream判断是否有此字段
StreamId	uint32	流序号，根据setting是否开启stream判断是否有此字段
Message ID	uint64	服务端的消息ID(全局唯一)
Message Seq	uint32	服务端的消息序列号(有序递增，频道唯一)
Message Timestamp	int32	服务器消息时间戳(10位，到秒)
Topic	string	话题ID（只有setting开启了topic才有此字段）
Payload	… byte	消息内容

​

✅ RECVACK 收消息确认

客户端对服务端推送消息的确认响应。

参数名	类型	说明
Packet Type	0.5 byte	报文类型(6)
Flag	0.5 byte	标示位
Remaining Length	… byte	报文剩余长度
Message ID	uint64	服务端的消息ID(全局唯一)
Message Seq	uint32	序列号

​

🏓 PING

客户端发送的心跳请求报文，用于保持连接活跃。

参数名	类型	说明
Packet Type	0.5 byte	报文类型(7)
Flag	0.5 byte	标示位

​

🏓 PONG

服务端对客户端 PING 请求的响应报文。

参数名	类型	说明
Packet Type	0.5 byte	报文类型(8)
Flag	0.5 byte	标示位

​

🔌 DISCONNECT

客户端或服务端请求断开连接时使用的报文格式。

参数名	类型	说明
Packet Type	0.5 byte	报文类型(9)
Flag	0.5 byte	标示位
Remaining Length	… byte	报文剩余长度
ReasonCode	uint8	原因代码
Reason	string	原因

​

📢 EVENT 事件通知

服务端向客户端推送事件通知时使用的报文格式。事件通知用于传递系统状态变化、用户行为通知等非消息类型的信息。

参数名	类型	说明
Packet Type	0.5 byte	报文类型(10)
Flag	0.5 byte	标示位
Remaining Length	… byte	报文剩余长度
Id	string	事件ID（事件唯一标识符）
Type	string	事件类型（如：user_online、user_offline、channel_update等）
Timestamp	int64	事件时间戳（13位时间戳，到毫秒）
Payload	… byte	事件数据内容

事件类型示例：

• user_online: 用户上线事件
• user_offline: 用户下线事件
• channel_update: 频道信息更新事件
• member_join: 成员加入频道事件
• member_leave: 成员离开频道事件
• typing: 用户正在输入事件

---

​

⚙️ 消息设置

​

📊 消息设置位字段

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

bit	7	6	5	4	3	2	1	0
byte	Receipt	Reserved	Signal	NoEncrypt	Topic	Reserved	Stream	Reserved

​

🔧 设置位说明

各位功能说明：

• Receipt: 消息已读回执，此标记表示此消息需要已读回执
• Reserved: 保留位，暂未用到
• Signal: 加密标记
• NoEncrypt: 消息是否不开启加密
• Topic: 消息是否包含 topic（如果为 1 则发送包和接受包都将包含 topic 字段）
• Reserved: 保留位，暂未用到
• Stream: 流式消息标记
• Reserved: 保留位，暂未用到

---

完整协议文档: 本文档包含了 WuKongIM 协议的核心部分。完整的协议规范还包括 Payload 推荐结构、普通消息格式、系统消息格式等详细内容，请参考源文档获取完整信息。