文档(虎牙): 新增绑定协议解码与角色UID参考

This commit is contained in:
yml
2026-11-20 16:27:44 +08:00
parent 4eda3f6972
commit 98ac7e7d1b
2 changed files with 430 additions and 0 deletions
+1
View File
@@ -35,6 +35,7 @@
| [行业电子凭证](行业电子凭证/) | 快手行业电子凭证协议 |
| [发货平台-2](发货平台-2/) | 历史发货平台协议 |
| [履约配置](履约配置/) | 专项接入与排障参考 |
| [虎牙绑定协议解码与角色 UID](履约配置/虎牙绑定协议解码与角色UID.md) | WUP/TAF、角色字段、`roleId` 与真实 UID 边界 |
| [微博微豆-CK接口与兑换链路确认-2026-11-07](微博微豆-CK接口与兑换链路确认-2026-11-07.md) | 微博微豆接口与兑换链路 |
| [打手重复奖励核对-2026-10-27](打手重复奖励核对-2026-10-27.md) | 历史财务核对记录 |
@@ -0,0 +1,429 @@
---
type: external-platform-protocol-reference
description: 虎牙绑定 WUP/TAF 解码、角色字段、换绑时间与游戏角色 UID 边界。
status: reference
version: 1.0
updated_at: 2026-11-20
evidence_har: 11.20-虎牙换绑角色-1.har
evidence_sha256: da089fb13d21ce120e1e6cdc522b456e2dfeae144e1f4a69916ebde025684a6e
---
# 虎牙绑定协议解码与角色 UID 参考 v1.0
> 本文是外部平台协议和排障参考,不定义订单、履约、成本或财务业务口径。
> 业务口径仍以 [统一订单履约与财务模型-权威版](../统一订单履约与财务模型-权威版.md) 为准。
## 1. 文档用途
本文记录以下内容:
- 虎牙绑定 HTTP/WSS 报文的实际解码链路。
- `checkUserBindGameAccount` 和 `confirmBindActAccount` 的字段结构。
- 虎牙 `roleId`、腾讯角色 ID、虎牙账号 UID、客户游戏角色 UID 的区别。
- `changeBindTime` 和 `changeBindDay` 的真实语义。
- 新抓包到来时如何验证协议是否升级。
- 当前尚未拿到的字段和下一步抓包目标。
## 2. 版本与证据基线
### 2.1 本文版本
当前版本:`1.0`。
版本规则:
| 变更类型 | 版本变化 | 示例 |
| --- | --- | --- |
| 文字澄清、样例修正、无字段变化 | Patch | `1.0 -> 1.0.1` |
| 新抓包验证、新增兼容字段、新增旁路接口 | Minor | `1.0 -> 1.1` |
| WUP 外层、TAF 结构、角色语义或绑定流程变化 | Major | `1.0 -> 2.0` |
每次更新必须同时修改:
1. 顶部 `version`。
2. 顶部 `updated_at`。
3. 文末“版本记录”。
4. 新抓包的证据基线和结论。
### 2.2 本版证据
| 项目 | 值 |
| --- | --- |
| 抓包日期 | 2026-11-20 |
| 文件名 | `11.20-虎牙换绑角色-1.har` |
| 文件大小 | `58,588,070` 字节 |
| HAR 条目数 | `490` |
| SHA-256 | `da089fb13d21ce120e1e6cdc522b456e2dfeae144e1f4a69916ebde025684a6e` |
| 场景 | 已有绑定角色,换绑到另一角色,确认绑定成功后回查 |
原始 HAR 属于本机证据,不提交仓库。文档只记录字段结论和脱敏样例。
## 3. 完整解码链路
### 3.1 报文层级
```text
HAR
→ _webSocketMessages[].payload.buffer
→ Base64 解码
→ HUYA.WebSocketCommand
→ command + vData
→ WUP
→ WUP tag7 sBuffer
→ Map<tReq | tRsp>
→ TAF 结构体
→ checkUserBindGameAccount / confirmBindActAccount 字段
```
关键点:
- WUP/TAF 是二进制序列化协议,不是业务加密。
- WebSocket `command=0x03` 表示 RPC 请求,`command=0x04` 表示 RPC 响应。
- WUP 的 tag7 是 `sBuffer`,其中通常是 `tReq` 或 `tRsp`。
- `tRsp` 是独立 TAF 结构体,需要按字段 tag 继续解码。
- TAF 解析必须消费结构结束标记,并跳过服务端新增的兼容字段。
### 3.2 项目内解析代码
| 文件 | 用途 |
| --- | --- |
| `apps/backend/src/services/semi-auto/huya-native/taf.ts` | TAF/WUP 编解码、tag 查找、结构体尾部兼容 |
| `apps/backend/src/services/semi-auto/huya-native/huya-rpc.ts` | 虎牙 RPC 请求和绑定结构体字段解析 |
| `apps/backend/src/services/semi-auto/huya-native/huya-native-connector.ts` | 登录、查询、换绑确认、会话状态 |
| `apps/backend/src/services/semi-auto/binding-role-id.ts` | 加密 role token 与数值角色 UID 类型判断 |
| `apps/backend/scripts/audit-huya-binding-identity.ts` | 账号 UID、role token、客户角色 UID 只读审计 |
## 4. `checkUserBindGameAccount` 完整字段
### 4.1 顶层 `tRsp`
| tag | 字段 | 类型 | 说明 |
| --- | --- | --- | --- |
| 0 | `status` | int | `200` 表示成功 |
| 1 | `msg` | string | 平台消息 |
| 2 | `accountData` | struct | 账号和角色绑定事实 |
| 3 | `gameName` | string | 游戏名称 |
| 4 | `gameAuthScene` | string | 授权场景 |
| 5 | `changeBindDay` | int | 平台配置的换绑窗口天数 |
### 4.2 `accountData`
| tag | 字段 | 类型 | 说明 |
| --- | --- | --- | --- |
| 0 | `isBindAccount` | int | 是否已绑定游戏账号 |
| 1 | `isBindRole` | int | 是否已绑定角色 |
| 2 | `isNeedActCheck` | int | 平台活动检查标志 |
| 3 | `gameAccount` | struct | 游戏账号信息 |
| 4 | `gameRole` | struct | 游戏角色信息 |
| 5 | `changeBindTime` | int | 下一次可换绑时间的 Unix 秒 |
| 6 | 未命名兼容字段 | int | 2026-11-20 抓包固定为 `0`,不是 UID |
### 4.3 `gameAccount`
| tag | 字段 | 2026-11-20 实测 |
| --- | --- | --- |
| 0 | `openId` | 空 |
| 1 | `appId` | 空 |
| 2 | `type` | `wx` 或 `qq` |
| 3 | `faceUrl` | 空 |
| 4 | `nick` | 游戏账号昵称,例如 `微信用户`、`随遇而安` |
| 5 | `accessToken` | 空 |
| 6 | `extendInfo` | 空 |
这些字段中可能有游戏账号昵称,但没有游戏角色 UID。
### 4.4 `gameRole`
| tag | 字段 | 2026-11-20 实测 |
| --- | --- | --- |
| 0 | `roleId` | 40 位十六进制不透明角色 token,可能是加密值或摘要 |
| 1 | `roleName` | 有值,例如 `吃鸡199706` |
| 2 | `areaName` | 有值,例如 `微信`、`手Q` |
| 3 | `platName` | 有值,例如 `苹果(iOS)` |
| 4 | `partitionName` | 空 |
| 5 | `gameSerial` | 空 |
| 6 | `extendInfo` | 空 |
完整解析后,`gameRole` 没有遗漏的 tag7、tag8 或其他隐藏字段。
## 5. 本版换绑事实
### 5.1 换绑前
同一时间存在当前角色和待确认角色:
| 类型 | 角色名 | 区服 | role token |
| --- | --- | --- | --- |
| 当前角色 | `巫师基尔斯84` | `苹果(iOS) / 微信` | `e5649c6b...456b4c89` |
| 待确认角色 | `吃鸡199706` | `苹果(iOS) / 手Q` | `4245d97f...8103cf` |
### 5.2 确认换绑
`confirmBindActAccount` 请求只携带账号授权、`gid` 和活动参数,不携带独立游戏角色 UID。
平台响应:
```text
status = 200
msg = 请求成功
```
### 5.3 换绑后
回查时当前角色变成:
| 字段 | 值 |
| --- | --- |
| `roleName` | `吃鸡199706` |
| `areaName` | `手Q` |
| `platName` | `苹果(iOS)` |
| `roleId` | `4245d97f...8103cf` |
结论:
- `roleId` 在同一角色重复查询时保持稳定。
- 换到不同角色后 `roleId` 变化。
- 因此 `roleId` 可以作为平台角色身份变化判断,但不是可展示的游戏角色 UID。
## 6. `roleId` 的性质和边界
### 6.1 已确认
- 长度为 40 个十六进制字符。
- 二进制长度为 20 字节。
- 线路上没有密钥、IV、加密块边界或明文字段。
- 相同角色稳定,不同角色不同。
- 不能把 `roleId` 与 9 到 19 位数字游戏角色 UID 直接比较。
- 不能用虎牙账号 UID、客户角色 UID 或腾讯账号 UID 回填该字段。
### 6.2 未确认
仅凭当前报文无法证明其具体算法。它可能是:
- SHA-1/HMAC 一类的角色指纹。
- 平台侧不可逆映射。
- 平台内部加密后只暴露 token。
对本项目而言,结论一致:把它当作不透明 token 使用。
允许:
- 在 Connector 内判断前后两次查询是否仍是同一角色。
- 在确认 pending 角色时防止页面快照和平台 pending 不一致。
禁止:
- 展示为客户游戏角色 UID。
- 从 token 推导 UID。
- 用 token 与客户填写的 UID 比较。
- 把 token 写入 `platform_game_role_uid`。
## 7. `changeBindTime` 语义
2026-11-20 换绑 HAR 实证:
| 场景 | `changeBindTime` | `changeBindDay` |
| --- | --- | --- |
| 换绑前当前角色 | `1794758400`,即 `2026-11-16 00:00 +08:00` | `7` |
| 换绑后当前角色 | `1795708800`,即 `2026-11-27 00:00 +08:00` | `7` |
结论:
- `changeBindTime` 是平台给出的“下一次可换绑时间”。
- `changeBindDay` 是平台配置的窗口天数。
- 不得把 `changeBindTime` 当成上次换绑时间再叠加 7 天。
- 当 `changeBindTime` 缺失时,才允许用 `changeBindDay` 做保守估算。
## 8. 腾讯 `livelink` 侧的真实角色标识
### 8.1 本 HAR 实际调用的接口
本次虎牙绑定页实际只调用了腾讯二维码链路:
```text
POST /api/qrcode/getMiniAppQrcode
POST /api/qrcode/poolingQrcodeStatus
```
二维码状态只有:
```json
{
"isScan": true,
"isExpired": false,
"isCompleted": true
}
```
没有返回角色名或角色 UID。
### 8.2 腾讯前端包中存在的角色接口
`livelink.qq.com` 前端包声明了以下接口:
```text
POST /api/h5/getBoundGameRoleInfoInH5
POST /api/h5/GetBoundGameRoleInfoWithSessionInH5
POST /api/h5/getGameRolesByGameInfo
POST /api/h5/getRelatedGameRolesByGameToken
```
前端使用字段:
```text
gameRoleStr = gameOpenId|roleId|platId|areaId|partitionId
```
前端代码会把 `gameRoleStr` 按 `|` 拆成五段:
```js
const [gameOpenId, roleId, platId, areaId, partitionId] = gameRoleStr.split('|')
```
其中第二段 `roleId` 才是腾讯角色 UID 的候选来源。
### 8.3 为什么本 HAR 仍拿不到
本次用户在微信或 QQ 小程序里选择角色,角色列表请求发生在小程序网络环境,
没有被 Chrome HAR 捕获。
本 HAR 没有调用:
```text
/api/h5/getGameRolesByGameInfo
/api/h5/getBoundGameRoleInfoInH5
/api/h5/getRelatedGameRolesByGameToken
```
因此当前只能确认腾讯侧存在角色 ID,不能确认其具体值,也不能确认它和虎牙
40 位 `roleId` 的映射关系。
### 8.4 下一次需要补抓的报文
需要补抓上述任一接口的成功响应,重点保存:
```text
gameRoleStr
roleName
platName
areaName
partitionName
gameOpenId
```
如果 `gameRoleStr` 第二段是纯数字,并且与客户填写的游戏角色 UID 一致,才能作为
`platform_game_role_uid` 的真实来源。
## 9. 项目当前处理规则
| 身份 | 来源 | 用途 | 是否可展示 |
| --- | --- | --- | --- |
| 虎牙账号 UID | 登录 Cookie / 登录响应 | WUP 请求身份 | 可展示账号 UID |
| 虎牙 `roleId` | `gameRole.roleId` | 平台前后角色一致性判断 | 不展示 |
| 客户游戏角色 UID | 客户填写 | 订单目标角色资料 | 可展示为目标 UID |
| 平台游戏角色 UID | `gameSerial` / `extendInfo` 明确数值字段 | 与客户 UID 比对 | 仅真实返回时展示 |
| 腾讯 `gameRoleStr.roleId` | 腾讯角色接口 | 候选真实 UID | 需要先抓包确认 |
当前自动比对规则:
1. 角色名和区服必须一致。
2. 平台明确返回数值 UID 时,再额外比较 UID。
3. 加密 `roleId` 只用于判断 current 与 pending 是否变化。
4. 没有真实 UID 时不得伪造,也不得声称已经拿到平台角色 UID。
只读审计命令:
```bash
cd apps/backend
npm run audit:huya-binding-identity
npm run audit:huya-binding-identity -- --strict
```
## 10. 新抓包更新流程
### 10.1 保存证据
1. 新 HAR 使用“日期-场景-序号”命名。
2. 记录文件大小、条目数和 SHA-256。
3. 原始 HAR 不提交,保留在本机抓包目录。
4. 文档只记录脱敏字段和结论。
### 10.2 解析 WSS 帧
1. 读取 `_webSocketMessages[].payload.buffer`。
2. Base64 解码。
3. 解 WebSocket command 和 `vData`。
4. 解 WUP tag7 `sBuffer`。
5. 解 `tReq` / `tRsp` TAF 结构。
6. 记录所有顶层、嵌套结构实际出现的 tag。
7. 检查结构结束标记之后是否还有新增字段。
### 10.3 必查接口
```text
webActUI.checkUserBindGameAccount
webActUI.confirmBindActAccount
webActUI.getLiveLinkParam
huyauserui.getUserProfile
```
如果页面进入腾讯角色列表,还要检查:
```text
/api/h5/getGameRolesByGameInfo
/api/h5/getBoundGameRoleInfoInH5
/api/h5/getRelatedGameRolesByGameToken
```
### 10.4 必查字段
```text
roleName
roleId
gameSerial
extendInfo
gameAccount.openId
gameAccount.extendInfo
changeBindTime
changeBindDay
gameRoleStr
```
### 10.5 版本更新
1. 字段语义不变,只补样例或说明:Patch。
2. 新增字段、新旁路接口或新 HAR 验证:Minor。
3. WUP/TAF 外形或角色语义改变:Major。
4. 更新顶部版本、日期、证据哈希和文末版本记录。
5. 如果业务规则发生变化,只更新唯一权威文档,不在本文另立业务口径。
## 11. 数据安全
文档和日志禁止记录:
- 完整 Cookie。
- `udb_cred`、`udb_biztoken`。
- 二维码 token。
- 短信验证码。
- 完整账号级凭证。
允许记录:
- 字段名。
- 字段类型。
- 脱敏后的角色 token。
- 角色名和区服样例。
- 接口路径和解析结论。
## 12. 当前未解决问题
1. 虎牙 `roleId` 的具体生成算法没有证据,按不透明 token 处理。
2. 当前 HAR 没有腾讯角色接口响应,真实游戏角色 UID 仍未取得。
3. 腾讯 `gameRoleStr` 第二段是否就是目标游戏角色 UID,需要新抓包验证。
4. 小程序内角色选择请求需要小程序抓包或腾讯 H5 登录链路才能覆盖。
## 13. 版本记录
| 版本 | 日期 | 变更 |
| --- | --- | --- |
| 1.0 | 2026-11-20 | 建立文档;完整解析虎牙绑定 WUP/TAF;确认 `roleId` 为不透明 token、`gameSerial` 和 `extendInfo` 为空;修正 `changeBindTime` 为下一次可换绑时间;确认腾讯侧存在 `gameRoleStr` 角色接口但本 HAR 未调用 |