ShangCloudMMO 网络协议接入文档 (v3.4.16)

本规范定义了客户端与 ShangCloudMMO 边缘节点进行通信的 TCP/UDP 协议标准。所有通信均需经过 AES-256-GCM 加密与重放保护。

1. 核心安全机制 (统一规范)

无论 TCP 还是 UDP，底层均采用相同的加密协议：

1.1 加密算法

算法: AES-256-GCM

Nonce: 12 字节（随机生成）

载荷结构 (Ciphertext):
[12B Nonce][AES-GCM 密文(8B 时间戳ms + 实际数据 + 16B GCM Tag)]

1.2 防重放机制

滑动窗口: 20秒。

校验: 客户端发包时，载荷前 8 字节必须为当前毫秒时间戳（BigEndian）。服务端会检查 Nonce 是否在 20 秒内出现过，且时间戳漂移是否在允许范围内。

2. TCP 协议接入规范

TCP 使用长度前缀帧 (Length-Prefix Framing) 解决黏包问题。

2.1 连接与认证流程

握手: 客户端连接后，立即发送 32 字节的 密钥种子 (Seed) (明文)。

派生: 服务端利用 SHA256(Seed) 派生出 32 字节 AES 密钥。

认证: 客户端发送加密后的认证帧（内容为 connect_key），服务端校验后返回 __auth_ok__。

2.2 数据帧格式

每一帧数据包结构：
[4B 大端长度前缀][加密载荷]

4B 长度: uint32，表示后续加密载荷的长度（最大 1MB）。

加密载荷: 见 1.1 节。

3. UDP 协议接入规范

UDP 为无连接协议，需通过 ConnectId 进行会话绑定。

3.1 握手认证

客户端发送认证包，connectId 字段置为 0：

包结构: [8B connectId(0)][32B 密钥种子][12B Nonce][AES-GCM 密文(8B 时间戳 + connect_key)]

服务端验证后，后续通信将使用分配的 connectId。

3.2 数据包格式

已认证会话的报文结构：
[8B BigEndian connectId][加密载荷]

8B connectId: 服务端在认证成功后指定的唯一 ID。

加密载荷: 见 1.1 节。

注意: 如果网络环境发生 NAT 变动（如移动网络切换），客户端应继续使用旧的 connectId 发包，服务端会自动更新对应的 RemoteAddr。

4. 通用命令规范

所有业务数据载荷（解密后的 plaintext）遵循以下约定：

命令/标记	说明
`__hb__`	心跳包。客户端需每隔 1-5 秒发送一次该字符串，否则将被服务器主动断开。
`__auth_ok__`	认证成功（服务端返回）。
`__closed__`	服务端强制关闭连接通知。
`__ping__`	查询房间人数及列表。
`__join__`	业务加入房间，格式：`{"type": "__join__", "uid": "...", "nickname": "..."}`。
`__leave__`	离开房间通知。

5. 开发检查清单 (Checklist)

密钥管理: TCP 发送 32B Seed，UDP 发送 32B Seed 到认证包开头。

序列化: 强制使用 BigEndian (大端序)。

时间戳: 确保发送载荷的前 8 字节为 UnixMilli，且与服务器时间误差在 20 秒以内。

Nonce: 每次发送必须生成唯一的 12 字节随机数。

线程安全: 确保网络接收线程与游戏主线程通过队列进行调度。

TCP/UDP协议联机

ShangCloudMMO 网络协议接入文档 (v3.4.16)#

1. 核心安全机制 (统一规范)#

1.1 加密算法#

1.2 防重放机制#

2. TCP 协议接入规范#

2.1 连接与认证流程#

2.2 数据帧格式#

3. UDP 协议接入规范#

3.1 握手认证#

3.2 数据包格式#

4. 通用命令规范#

5. 开发检查清单 (Checklist)#