WebSocket 客户端消息接口文档

本文档描述 客户端与 WebSocket 服务 的交互：连接方式、消息格式、主/子命令字及请求响应示例，供客户端（App/Web）对接使用。协议概要见同目录上级 PROTOCOL.md。

1. 连接说明

URL: ws://{host}:{port}/

握手参数 (Query Parameters):

dsuid: 用户唯一标识 (Required, 格式: 字母/数字/下划线, 1-50字符)

token: 认证 Token (Required, 用于校验用户身份)

连接成功响应:
连接建立后，服务器会主动推送一条连接成功消息：

{
  "mainCmd": 2,
  "subCmd": 2,
  "data": {
    "tid": 0,
    "code": 200,
    "msg": "连接成功",
    "data": {
      "dsuid": "用户ID",
      "timestamp": 1678888888,
      "rooms": [1001, 1002]
    }
  }
}

rooms：当前用户在服务端实际所在房间 ID 列表（来自 Redis）。用于锁屏/断线重连后同步界面：

若本地认为「在房间 A」但 rooms 里没有 A（例如锁屏期间连接被清理），说明已不在该房，客户端应清除「在房」状态并提示「连接已恢复，请重新进入房间」或退回房间列表。

若 rooms 非空，可与本地当前房间对比，一致则保持「在房」展示；不一致则以 rooms 为准。

2. 消息协议

客户端与服务器交互统一采用 JSON 格式。

客户端发送消息格式

{
  "mainCmd": <int>,       // 主指令
  "subCmd": <int>,        // 子指令
  "data": {               // 业务数据
      "tid": <int>,       // 事务ID (可选，用于对应响应)
      ...
  }
}

服务器响应消息格式

{
  "mainCmd": <int>,       // 主指令
  "subCmd": <int>,        // 子指令 (通常与请求一致，或是特定的推送指令)
  "data": {
      "tid": <int>,       // 对应的事务ID
      "code": <int>,      // 状态码 (200=成功, 400=请求错误, 401=未认证, 500=服务器错误)
      "msg": <string>,    // 提示信息
      "data": { ... }     // 业务响应数据
  }
}

3. 基础指令

心跳检测

保持连接活跃，建议每 30-60 秒发送一次。

请求: mainCmd: 0, subCmd: 0

响应: mainCmd: 0, subCmd: 0

{
  "timestamp": 1678888888
}

单点登录：被踢下线

当同一账号在其它设备/标签页建立新连接时，旧连接会收到此推送后断开（closeCode 4001）。

服务器推送: mainCmd: 2, subCmd: 12

{
  "code": 4001,
  "msg": "账号在其他设备登录"
}

客户端收到后应提示用户并跳转登录页或引导重新连接；连接关闭时 code 为 4001 表示单点登录踢下线。

4. 语音房指令 (mainCmd: 3)

所有语音房相关的操作主指令均为 3。

4.1 加入/离开房间

加入房间

请求: subCmd: 1

{
  "roomid": 1001 // 房间ID
}

响应 (个人): subCmd: 1

data.data:

roomid: 房间ID

seats: 全量麦位列表（按房间 roomlabel 决定数量，空麦位字段留空；roomlabel=1 为 0-8 共 9 个）

online_count: 当前在线人数

online_top3: 在线榜单前三名头像，[ {"headimgurl":"","name":""}, ... ] 最多 3 条

进房后麦位通知 (个人): 进房成功后会再收到一条 mainCmd: 3, subCmd: 200 的麦位信息，格式同「麦位列表更新广播」（type: "mic_update", seats, locked_seats），便于前端统一用同一逻辑处理麦位展示。

广播 (房间内其他人): subCmd: 101

{
  "dsuid": "用户ID",
  "action": "join",
  "online_count": 123,
  "online_top3": [ {"headimgurl": "https://...", "name": "昵称"}, ... ]
}

离开房间

请求: subCmd: 2

{
  "roomid": 1001
}

响应 (个人): subCmd: 2

广播 (房间内其他人): subCmd: 102

{
  "dsuid": "用户ID",
  "action": "leave",
  "online_count": 122,
  "online_top3": [ {"headimgurl": "https://...", "name": "昵称"}, ... ]
}

4.2 聊天与麦位

发送公聊消息

请求: subCmd: 3

{
  "roomid": 1001,
  "content": "你好，大家好！"
}

广播 (房间内所有人): subCmd: 3

{
  "from_dsuid": "发送者ID",
  "user_info": {
      "dsuid": "发送者ID",
      "nickname": "Tom",
      "avatar": "http://...",
      "sex": 1,
      "nobility": 1,
      "is_vip": true,
      "role": 30 // 0:普通, 10:管理, 20:超管, 30:房主
  },
  "content": "你好，大家好！",
  "type": "text",
  "timestamp": 1678888888
}

错误响应: subCmd: 3 (仅发给请求者)

{
  "code": 403,
  "msg": "您已被本房间禁言" // 或 "您已被全服禁言", "内容包含敏感词"
}

上麦

请求: subCmd: 4

{
  "roomid": 1001,
  "seat_index": 0 // 麦位索引 (0-8)
}

响应 (个人): subCmd: 4

成功: code: 200, msg: "上麦成功", data.players: 当前麦位列表

失败: code: 400

msg: "该麦位已有人" — 麦位已被占用

msg: "该麦位已锁定" — 房主/管理员已锁麦，普通用户不能上该麦

msg: "麦位无效" — seat_index 不在 0-8

msg: "你已经在麦上" — 当前用户已在其他麦位

下麦

请求: subCmd: 5

{
  "roomid": 1001
}

响应 (个人): subCmd: 5

换麦

请求: subCmd: 19

{
  "roomid": 1001,
  "target_seat_index": 1 // 目标麦位索引 (0-8)
}

响应 (个人): subCmd: 19

{
  "code": 200,
  "msg": "换麦成功"
}

麦位列表更新广播

当有人上麦、下麦、管理员锁麦/解锁/抱人上麦等导致麦位变化时触发。

广播 (房间内所有人): subCmd: 200

{
  "type": "mic_update",
  "seats": [
    {
      "account": "用户ID",
      "seat": 0,
      "mic_status": 1,
      "name": "昵称",
      "headimgurl": "头像URL"
    }
  ],
  "locked_seats": [0, 2]
}

seats: 全量麦位列表，按房间 roomlabel 决定数量；空麦位字段留空（account/name/headimgurl 为空，mic_status=0），有人/锁麦的才有完整字段。mic_status: 0=闭麦, 1=开麦, 2=封麦, 3=锁麦(空位锁定)。暂定 roomlabel=1 为普通模式，麦位 0-8 共 9 个。

locked_seats: 被锁定的麦位下标数组，空麦位被锁后普通用户无法上该麦

麦位管理 (房主/管理员/超管)

仅房主、房间管理员 (job≥10)、全局超管 可调用。无权限时返回 code: 403, msg: "无权操作"。

请求: subCmd: 6

{
  "roomid": 1001,
  "type": "lock_seat | unlock_seat | kick | lock | mute | unmute | invite",
  "seat_index": 0,
  "target_dsuid": "用户ID"
}

type 说明：

lock_seat — 锁麦：锁定空麦位，其他人不能上该麦；麦位有人时不可锁

unlock_seat — 解锁麦位

kick — 抱下麦：把该麦位上的人抱下麦

lock — 封麦：禁言该麦位用户 (mic_status=2)

mute — 闭麦：关闭该麦位用户麦克风 (mic_status=0)

unmute — 解麦：开启该麦位用户麦克风 (mic_status=1)

invite — 抱人上麦：指定用户上指定麦位，需传 target_dsuid；麦位已锁定时需先解锁

seat_index: 麦位索引 (0-8)，除 invite 外必填

target_dsuid: 仅 invite 时必填，被抱上麦的用户 ID

响应 (操作者): subCmd: 6

成功: code: 200, msg: "xxx成功", type: "操作类型"

常见错误: code: 400

"该麦位已有人" / "该麦位无人" / "麦位无效"

"该麦位已锁定" / "该麦位已锁定，请先解锁" (invite 时)

"未指定用户" / "用户不在房间内" / "用户已在麦上" (invite 时)

通知 (被抱上麦用户): subCmd: 201 (仅 type=invite 时)

{
  "type": "invited_on_mic",
  "seat_index": 0,
  "operator": "操作者ID"
}

4.3 互动功能

发送跑马灯

请求: subCmd: 7

{
  "roomid": 1001,
  "content": "跑马灯内容",
  "scope": 1 // 1: 当前房间, 2: 全服广播
}

响应 (个人): subCmd: 7

广播 (房间/全服): subCmd: 300

{
  "type": "marquee",
  "content": "跑马灯内容",
  "sender": "发送者ID",
  "scope": 1,
  "timestamp": 1678888888
}

发红包

请求: subCmd: 10

{
  "roomid": 1001,
  "total_amount": 100, // 总金额(分/钻石)
  "total_count": 10,   // 红包个数
  "wish_text": "恭喜发财"
}

响应 (个人): subCmd: 10

全服广播 (所有在线用户): subCmd: 400

{
  "type": "red_packet_notify",
  "roomid": 1001,
  "room_name": "房间名",
  "sender_name": "发送者昵称",
  ...
}

房间内推送: subCmd: 401

{
  "type": "red_packet_created",
  "red_packet_id": "12345",
  ...
}

抢红包

需先进入房间。

请求: subCmd: 11

{
  "roomid": 1001,
  "red_packet_id": "12345"
}

响应 (个人): subCmd: 11

data.data:

amount: 抢到的金额

remain_count: 剩余个数

广播 (房间内): subCmd: 402 (有人抢到了红包)

获取房间红包列表

请求: subCmd: 12

{
  "roomid": 1001
}

响应 (个人): subCmd: 12

data.data.list: 红包列表数组

4.4 PK 系统

接受 PK 邀请

请求: subCmd: 8

{
  "roomid": 1001,
  "target_roomid": 2002
}

拒绝 PK 邀请

请求: subCmd: 9

{
  "roomid": 1001,
  "target_roomid": 2002
}

PK 相关广播 (Server Push)

subCmd: 57: PK 邀请 (收到别人的PK邀请)

subCmd: 58: PK 已接受

subCmd: 59: PK 已拒绝

subCmd: 60: PK 邀请已取消

subCmd: 61: PK 匹配状态更新 (status: 1=开始匹配, 0=取消匹配)

subCmd: 62: PK 开始 (包含双方房间信息)

subCmd: 63: PK 结束 (包含结果)

subCmd: 64: PK 实时数据更新 (分数/贡献值变化)

4.5 房间管理

设置房间密码

请求: subCmd: 13

{
  "roomid": 1001,
  "password": "xxxx"
}

响应 (个人): subCmd: 13

广播 (房间内所有人): subCmd: 202

{
  "type": "room_info_update",
  "data": {
      "passwdStatus": "1"
  }
}

取消房间密码

请求: subCmd: 14

{
  "roomid": 1001
}

响应 (个人): subCmd: 14

广播 (房间内所有人): subCmd: 202

{
  "type": "room_info_update",
  "data": {
      "passwdStatus": "0"
  }
}

设置房间职位 (管理员/超管)

请求: subCmd: 15

{
  "roomid": 1001,
  "target_dsuid": "user_id",
  "job_type": 10 // 10: 管理员, 20: 超级管理员, 0: 取消职位
}

响应 (个人): subCmd: 15

广播 (房间内所有人): subCmd: 203

{
  "type": "room_job_update",
  "roomid": 1001,
  "target_dsuid": "user_id",
  "job_type": 10
}

踢出房间 (Kick)

请求: subCmd: 16

{
  "roomid": 1001,
  "target_dsuid": "user_id"
}

响应 (个人): subCmd: 16

{
  "code": 200,
  "msg": "踢出成功"
}

通知 (被踢者): subCmd: 16

{
  "code": 200, // 注意这里不是错误码，而是特定业务通知
  "msg": "您已被移出房间，60分钟内无法再次进入",
  "ban_minutes": 60
}

广播 (房间内所有人): subCmd: 204

{
  "type": "kick_user",
  "operator_dsuid": "operator_id",
  "target_dsuid": "target_id",
  "ban_minutes": 60
}

拉黑用户 (加入黑名单)

请求: subCmd: 17

{
  "roomid": 1001,
  "target_dsuid": "user_id"
}

响应 (个人): subCmd: 17

广播 (房间内所有人): subCmd: 205

{
  "type": "blacklist_add",
  "operator_dsuid": "operator_id",
  "target_dsuid": "target_id"
}

移除黑名单

请求: subCmd: 18

{
  "roomid": 1001,
  "target_dsuid": "user_id"
}

响应 (个人): subCmd: 18

5. 其他服务器推送 (MainCmd: 2)

以下为服务端主动推送，无需客户端请求。多数由 API/Redis game_server_broadcast 或 lobby_server_broadcast 触发，WebSocket 解析后推送给对应房间或用户。

5.1 房间送礼（服务端推送）

送礼由 HTTP 接口完成，成功后通过 Redis 通知 WebSocket，再推送给房间内所有连接。

房间送礼详情（单次送礼）

推送: mainCmd: 2, subCmd: 4（仅推送给该房间内用户）

data 字段说明：

字段	类型	说明
sendaccount	string	送礼用户 ID
acceptaccount	string	收礼用户 ID
giftid	string	礼物配置 ID
giftname	string	礼物名称
sendnum	string	赠送数量
sendtype	string	送礼类型（如 2=麦上的人，3=房间所有人）
totolmoney	string	总价值（如钻石/金币）
data	string	扩展数据（JSON 字符串，含礼物配置等）
roomid	string	房间 ID
roomtype	string	房间类型
jsqtzstatus	string	计算/统计状态（如是否最后一笔）
blindboxstatus	string	盲盒状态（0=否，1=是）

示例：

{
  "mainCmd": 2,
  "subCmd": 4,
  "data": {
    "sendaccount": "10001",
    "acceptaccount": "10002",
    "giftid": "gift_001",
    "giftname": "玫瑰",
    "sendnum": "10",
    "sendtype": "1",
    "totolmoney": "1000",
    "data": "{\"giftmoney\":100,...}",
    "roomid": "1001",
    "roomtype": "120",
    "jsqtzstatus": "1",
    "blindboxstatus": "0"
  }
}

房间送礼详情（变体）

推送: mainCmd: 2, subCmd: 18

data 结构与 subCmd: 4 一致，用于盲盒、全房间广播等场景。客户端可按同一结构解析并展示动画/跑马灯等。

送礼完成后房间刷新

推送: mainCmd: 2, subCmd: 9（仅推送给该房间内用户）

说明: 一次送礼流程（可能含多人）全部结束后下发，客户端收到后应刷新房间信息（如贡献榜、礼物统计等）。

{
  "mainCmd": 2,
  "subCmd": 9,
  "data": {
    "roomid": "1001",
    "roomtype": "120"
  }
}

建议处理顺序：先处理 subCmd: 4 / 18 做礼物动画或列表更新，再在收到 subCmd: 9 时拉取或刷新房间整体数据。

5.2 其他 MainCmd: 2 推送

subCmd: 2: 连接成功（见第 1 节）

subCmd: 11: 全服通用广播（如个人资料刷新）

subCmd: 47: 游戏/房间广播，data: {"roomid": ..., "data": ...}

subCmd: 50: 大厅/需求广播

subCmd: 62: 房间服务数据更新（通用 JSON 数据推送）

subCmd: 70: 房间话题标题更新，data: {"roomid", "roomtype", "roomnoticetitle"}

subCmd: 71: 房间话题内容更新，data: {"roomid", "roomtype", "roomexplain"}

subCmd: 72: 房间公告更新，data: {"roomid", "roomtype", "roomnotice"}

subCmd: 73: 房间名称更新，data: {"roomid", "roomtype", "roomname"}

6. 错误码说明

Code	说明
200	成功
400	请求参数错误 / 业务逻辑错误
401	未认证 / Token 无效
402	余额不足
4001	单点登录：账号在其他设备登录（被踢下线）
4002	您已不在房间内，请重新进入房间（见下方说明）
403	无权限 / 禁言等
413	消息过大
500	服务器内部错误

6.1 锁屏/断线后不在房间 (code: 4002)

场景：用户手机锁屏或网络断开一段时间后，服务端会因心跳超时清理该用户的连接与房间成员关系（不会踢下麦，麦位保留）。用户再次打开 App 时，若未根据「连接成功」的 data.rooms 同步界面，可能仍显示「在房间内」，但 Redis 中该用户已不在房间成员列表，此时进行上麦、下麦、发消息等操作会收到 code: 4002。用户再次进房后仍会看到自己在原麦位，其他人在此期间看到的麦位也不变。

服务器返回：data.code === 4002，data.msg === "您已不在房间内，请重新进入房间"（各 subCmd 的响应里均可能携带）。

客户端处理建议：

连接成功时同步在房状态：收到「连接成功」(mainCmd: 2, subCmd: 2) 时，读取 data.rooms。若本地有「当前房间」但 rooms 中不包含该房间（常见于锁屏/断线重连后被服务端清理），应立即清除本地在房状态并提示「连接已恢复，请重新进入房间」或退回房间列表，这样不会出现“界面还在房内”的错觉。

收到任意房间相关响应的 code === 4002 时，提示用户「您已不在房间内，请重新进入房间」。

自动重进房：若本地仍保存当前房间 ID，可自动发送一次「加入房间」(subCmd: 1, roomid) 重新进房，成功后刷新麦位/列表即可。

或退回房间列表：清除本地「当前房间」状态，退回大厅/房间列表，由用户再次点击进入房间。

这样可避免用户锁屏再打开后界面仍显示在房内但操作被拦截的困惑。

6.2 断线重连 API（判断是否在房）

场景：用户杀进程或切后台后重新打开 App，在建立 WebSocket 之前可先调用 HTTP 断线重连接口（如 brokenLineReconnection），判断用户断线前是否在语音房内。

接口约定（与主站 API 约定一致即可）：

请求带 dsuid（及登录态）。

若用户断线前在语音房内，返回 code: 200，data 含：

in_voice_room: true

rooms: 断线前所在房间 ID 数组，如 [1001]

roomid: 首个房间 ID，便于直接重进该房

若不在房或未断线记录，按现有逻辑返回（如 data 为空或走其他断线重连逻辑）。

客户端建议：App 启动或从后台回到前台时调用该接口；若 data.in_voice_room === true 且 data.rooms.length > 0，可提示「是否重新进入房间」并带 data.roomid，用户确认后建立 WebSocket 并发送「加入房间」(subCmd: 1, roomid)。

WebSocket 接口文档

WebSocket 客户端消息接口文档#

1. 连接说明#

2. 消息协议#

客户端发送消息格式#

服务器响应消息格式#

3. 基础指令#

心跳检测#

单点登录：被踢下线#

4. 语音房指令 (mainCmd: 3)#

4.1 加入/离开房间#

加入房间#

离开房间#

4.2 聊天与麦位#

发送公聊消息#

上麦#

下麦#

换麦#

麦位列表更新广播#

麦位管理 (房主/管理员/超管)#

4.3 互动功能#

发送跑马灯#

发红包#

抢红包#

获取房间红包列表#

4.4 PK 系统#

接受 PK 邀请#

拒绝 PK 邀请#

PK 相关广播 (Server Push)#

4.5 房间管理#

设置房间密码#

取消房间密码#

设置房间职位 (管理员/超管)#

踢出房间 (Kick)#

拉黑用户 (加入黑名单)#

移除黑名单#

5. 其他服务器推送 (MainCmd: 2)#

5.1 房间送礼（服务端推送）#

房间送礼详情（单次送礼）#

房间送礼详情（变体）#

送礼完成后房间刷新#

5.2 其他 MainCmd: 2 推送#

6. 错误码说明#

6.1 锁屏/断线后不在房间 (code: 4002)#

6.2 断线重连 API（判断是否在房）#