Files
live-hub-py/docs/斗鱼/DOUYU_PROTOCOL_OVERVIEW.md
T

401 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 斗鱼协议总览
更新时间:2026-11-21
本文是斗鱼协议、状态判定和线上排障的统一入口。代码是最终依据;本文记录代码
难以直接表达的协议语义、字段优先级、已验证边界和历史踩坑,避免重复分析。
后续模块重构和任务调度实施以
[斗鱼账号平台最终实施设计](斗鱼账号平台最终实施设计.md) 为主线。
## 维护规则
每次修改斗鱼协议相关代码时,同一个提交必须同步更新本文:
1. 新增或修改字段时,补字段真值表和影响范围;
2. 新增 `actAlias`、接口或任务类型时,说明它在多渠道判定中的职责;
3. 修复线上问题时,在“踩坑记录”追加日期、现象、根因、判定变化和回归用例;
4. 抓包只能证明当时行为,不能直接覆盖已由代码和线上回归验证的结论;
5. CK、Cookie、手机号、订单号和完整设备标识不得写入本文。
## 权威代码入口
| 范围 | 唯一权威入口 |
| --- | --- |
| 斗鱼 HTTP 协议与原始字段解析 | `core/douyu/activity_client.py` |
| 绑定业务状态和 pending 判定 | `web/backend/services/account_binding.py` |
| 二维码、轮询、确认绑定状态机 | `web/backend/services/douyu_runner_bind.py` |
| 账号探针和多 alias 角色汇总 | `web/backend/services/douyu_account_probe.py` |
| 只读查询统一入口 | `web/backend/services/douyu_activity_query.py` |
| 任务类型和入口校验 | `web/backend/services/douyu_service.py` |
| 任务并发与任务槽 | `web/backend/services/task_runtime.py` |
| 履约投影和客户侧会话 | `web/backend/services/platform_fulfillment/` |
页面、履约、外部单协作和自动化不得自行解释 `bindAct` / `needBindAct`,只能消费
`binding_snapshot()`、`binding_pending_decision()` 及其派生结果。
## 凭证与请求约束
- 业务请求依赖斗鱼登录 Cookie;写请求还可能需要 `cvl_csrf_token` / `acf_ccn`。
- 查询和绑定扫码任务直连,不走代理;兑换、支付、充值、开通和送礼等写操作按任务
从代理配置取代理。
- `Origin`、`Referer` 必须与当前浏览器流程一致,不能只复制 URL。
- 日志只记录脱敏状态,不记录 Cookie、CSRF、完整二维码签名或账号密码。
## 腾讯游戏角色绑定
### 接口
| 动作 | 方法 | 地址/常量 | 关键参数 |
| --- | --- | --- | --- |
| 查询绑定信息 | GET | `/wgapi/ordnc/live/memberthird/tencent/bindInfo` | `actAlias` |
| 生成角色二维码 | GET | `/wgapi/ordnc/live/memberthird/tencent/bindRoleParam` | `actAlias` |
| 确认绑定 | POST multipart | `/wgapi/ordnc/live/memberthird/tencent/actBind` | `actAlias`、`acf_ccn` |
### alias 职责
站内绑定信息不是单一数据源,`actAlias` 必须按职责区分:
| 来源 | 典型值 | 职责 | 不能做什么 |
| --- | --- | --- | --- |
| 活动动作 alias | `20260120QYOOB` | 当前精英宝典二维码、待确认和最终确认的权威动作通道 | 不能被 legacy 的旧角色覆盖 |
| legacy 最新态 | `cjm` | 补充最新换绑/扫码角色,常更早暴露新角色 | 不能单独代表当前活动已确认;不能覆盖活动 alias 当前状态 |
| 历史查询 alias | `20250213NQCYX` 等配置值 | 兼容旧活动查询 | 不作为当前动作主通道 |
`query_act_aliases` 是“要查哪些来源”的集合;`action_act_aliases` 是“哪些来源可以
执行确认”的集合。两者不能混用。查询顺序不是业务优先级;最终角色由 pending 判定
和动作 alias 规则选出。
### 字段真值表
| 字段 | 语义 |
| --- | --- |
| `bindAccount=1` | 已绑定腾讯账号 |
| `bindRole=1` | 已选中游戏角色 |
| `bindAct=1` | 最终活动绑定已生效,这是唯一 `bound` 信号 |
| `bindAct=0 + bindRole=1` | 角色已选中但未最终生效,是可确认 pending;允许在生成新二维码前已存在 |
| `needBindAct=1` | 当前活动允许继续绑定;这是长期能力标志,不等于本轮刚扫码 |
| `needBindRole=1` | 当前流程仍需要角色选择/角色信息 |
| `changeRoleWaitTime` | 换绑倒计时;只有 `bindAct=1` 时才可能是真实冷却 |
| `canChangeTime` | 可换绑绝对时间;未确认绑定不能据此拦截 |
| `canChangeRole` | 页面/接口的换绑可用提示,必须结合 `bindAct` 解释 |
绑定响应没有游戏 UID、角色 ID、OpenID。不要尝试从角色名推导稳定角色身份。
### pending 判定顺序
单个候选按以下顺序解释,详细结果由 `binding_pending_decision()` 返回:
1. 没有角色名:不可确认;
2. 当前 `bindAct=1`:已经最终绑定,不可确认,原因 `already_bound`;
3. 角色名与 baseline 不同:可确认,原因 `role_changed`;
4. 同 alias 从 `bindAct=1` 变为 `bindAct=0`:可确认,原因
`same_alias_after_bound_transition`;
5. 同 alias 从 `needBindAct=0` 变为 `needBindAct=1`,且当前 `bindAct=0`:
可确认,原因 `same_alias_after_pending_transition`;
6. 动作 alias 当前是 `bindAct=0 + needBindAct=1 + roleName`:可确认,原因
`existing_actionable_pending`。即使它在二维码生成前已经存在、没有发生
状态迁移,官网也允许直接 `actBind`;
7. 没有 baseline 且不是动作 alias pending:不可确认,原因
`pending_without_baseline`;
8. 角色名相同但缺少完整 baseline 快照:不可确认;
9. 其他同名角色:视为旧残留。baseline 本身是 pending 时原因
`same_role_stale_pending`,否则为 `same_role_stale`。
2026-11-22 生产历史证明:账号早已 `bind_ok confirmed`,但活动 alias 长期同时返回
`bindAct=1 + needBindAct=1`。因此 `needBindAct=1` 不能单独证明 pending;
真正决定 pending 的是 `bindAct=0`,不是角色名是否变化。
二维码预检若发现动作 alias 已有 `bindAct=0` pending,会发布二维码并立即进入
`role_ready`;没有合法 pending 时才进入 `waiting_scan`。历史错误的
`bindAct=1` `role_ready` 会被 `refresh_binding()` 记录为
`binding_stale_role_ignored` 并自动退回未开始状态。
### 完整流程
```text
查询所有 query_act_aliases
-> 找当前 bindAct=1(bound)
-> 找动作 alias 上真实的 bindAct=0 pending
-> 保存扫码前 baseline,用于识别新角色和状态迁移
-> 生成二维码
-> 持久化 baseline、候选来源、判定原因
-> binding_poll 每轮先查 legacy(cjm)
-> 角色/状态变化、每 3 轮或最后一轮再补查动作 alias(QYOOB)
-> 官方直接返回 bindAct=1 时立即结束为 confirmed
-> 找到确认条件:任务 success + bind_ready_for_confirm=true
-> actBind
-> 回查 bindAct=1
-> 写 accounts 当前角色和 role_bind_status=bound
```
二维码任务不能在 worker 内长时间阻塞;出码后写 `binding_poll`、`next_run_at` 和
`run_deadline_at`,由数据库调度器继续轮询。轮询窗口为 20 分钟,平台展示的二维码
TTL 为 21 分钟,留 1 分钟收尾余量。
轮询间隔按任务生命周期退避:
| 已等待时间 | 间隔 |
| --- | --- |
| 0-2 分钟 | 5 秒 |
| 2-10 分钟 | 10 秒 |
| 10-20 分钟 | 20 秒 |
`binding_poll` 有 6 个独立执行槽,但不会每轮同时请求所有 alias。生产常态是每轮
只查 `cjm`,动作 alias 仅在 legacy 状态变化、每 3 轮巡检和最后一轮补查。这样既能
承接十几个客服并发扫码,也不会把几十个二维码放大成持续的双倍官方请求。
### 确认前保护
- 传 `expected_role_name` 时,回查角色变化必须失败,不能确认另一个角色。
- 确认失败时保留 `before_bound` 的已生效角色,不能把待确认角色写入账号。
- `bindAct=0` 时 `changeRoleWaitTime` 再大也不是真实换绑冷却。
- 只有确认后的 `bindAct=1` 才允许写 `bound` 和 `role_change_available_at`。
## 诊断日志
### 多渠道判定
日志关键字:`绑定多渠道判定 |`
每次输出一条 JSON,包含:
- `task_id`、`stage`:任务和阶段,如 `qr_preflight`、`poll:N`、
`query_game_name`、`confirm_precheck`;
- `action_aliases`:允许确认的活动来源;
- `baseline_alias`、`baseline_role`、`baseline_bind_act`;
- `selected_alias`;
- `candidates[]`:每个 alias 的角色、`bindAct`、`bindRole`、`needBindAct`、
`needBindRole`、是否动作 alias、是否可确认以及原因。
### 其他绑定日志
- `绑定前状态`:二维码生成前所有 alias、baseline、cooldown 和 pending 命中情况;
- `轮询绑定#N`:每轮选中候选和摘要;
- `确认前状态`:确认目标、expected role 和候选摘要;
- `绑定判定`:确认/失败后的最终收敛。
任务结果持久化字段:
- `action_act_aliases`
- `bind_decision`
- `bind_candidate_decisions`
- `pending_role_name`
- `bind_summary`
### 角色接口原始响应留档
关键角色接口的原始响应写入 `douyu_role_api_logs`,用于还原不同 alias 在
扫码、待确认、确认和回查各阶段到底返回了什么。记录内容:
- 账号、任务、作用域、阶段和 alias;
- `role_name`、`bindAct`、`bindRole`、`needBindAct`、`needBindRole`、
换绑倒计时和可换绑时间;
- 请求摘要与原始响应 JSON;
- 入库前的 Cookie、token、CSRF 等敏感键脱敏结果。
轮询不会把相同响应每 5 秒重复入库,只在 legacy 状态变化、动作 alias 响应变化、
二维码预检、确认前、确认接口返回和确认后回查时写入。
建议的生产只读查询:
```sql
SELECT id, task_type, status, message, created_at, finished_at,
JSON_EXTRACT(result, '$.bind_decision') AS decision,
JSON_EXTRACT(result, '$.bind_candidate_decisions') AS candidates,
JSON_EXTRACT(result, '$.bind_summary') AS summary
FROM douyu_tasks
WHERE account_id = ?
ORDER BY id DESC
LIMIT 20;
```
角色接口原始响应查询:
```sql
SELECT id, task_id, stage, act_alias, role_name,
is_bound_act, need_bind_act, change_role_wait_time,
response_json, created_at
FROM douyu_role_api_logs
WHERE account_id = ?
ORDER BY id DESC
LIMIT 100;
```
日志检索:
```bash
docker compose logs douyu-login | grep '绑定多渠道判定'
docker compose logs douyu-login | grep '确认前状态'
```
## 精英宝典与兑换
当前精英宝典活动由 `manual_id`、`rid` 和配置中的活动 alias 共同确定。商品、积分、
限兑、兑换记录和锁单查询统一走 `douyu_activity_query.py`。
| 范围 | 关键接口 |
| --- | --- |
| 手册用户信息 | `/wgapi/ordnc/activity/peace/getUserInfo` |
| 商品列表 / 全量账号资格 | `/wgapi/ordnc/activity/peace/storehome` |
| 商品详情 | `/wgapi/ordnc/activity/peace/storedetail` |
| 批量兑换上限 | `/wgapi/ordnc/activity/peace/batchExchangeLimit` |
| 锁单 | `/wgapi/ordnc/activity/peace/createExchangeOrder` |
| 支付锁单 | `/wgapi/ordnc/activity/peace/payExchangeOrder` |
| 锁单列表 | `/wgapi/ordnc/activity/peace/getExchangeOrderList` |
| 兑换记录 | `/wgapi/ordnc/activity/peace/exchangeList` |
`storehome` 一次返回当前活动完整商品列表,每项的账号级 `status` 已经表示该账号是否
达到该商品限兑上限。账号商品资格刷新、限兑批量扫描和自动选号不得按礼包逐个调用
`storedetail` 或 `batchExchangeLimit`。详细字段、分类顺序和抓包证据见
[精英宝典商品资格与全量快照](精英宝典商品资格与全量快照.md)。
兑换成功的唯一业务收口必须是 `payExchangeOrder` 成功后写入兑换事件;预约到货、
预兑和等待开放即使返回 `success`,也不能当成真实兑换。
## 鱼翅、积分与支付
2026-11-21 新抓包确认,鱼翅页面和支付链路已统一迁到
`https://www.douyu.com/japi/web/gold/*`,不再使用旧的
`cz.douyu.com/item/gold/account` 查询余额。
- 鱼翅初始化:`POST /japi/web/gold/init`
- 表单:`ctn=<acf_ccn>&scene=web`
- 返回当前账号、支付渠道和可充值商品面值
- 鱼翅余额:`GET /japi/web/gold/account`
- 返回 `data.amount`,单位是 **0.01 鱼翅**
- 页面余额和本地 `gold_balance` 使用 `amount / 100`
- 鱼翅支付码:`GET /japi/web/gold/getQrCode`
- 参数:`payType`、`productId`、`number`、`source`、`toName`
- 返回 `token`、`code_url`、`polling_url`
- 鱼翅支付状态:`GET /japi/web/gold/getQrState?token=...`
- `state=-2`:等待支付
- `state=0`:支付处理中
- `state=2`:支付成功,同时返回 `quantity` 和 `orderId`
- 支付码生成任务保存 `payment_token`;轮询优先使用官方 `state=2` 收口,
成功后立即刷新鱼翅余额。旧 token 或状态接口不可用时才回退到余额增量判断。
- 积分余额:`POST /japi/oms/web/peace/credit/balance`
- 2026-11-21 页面使用 `multipart/form-data`,表单只传 `uid`
- `acf_ccn` 从 Cookie 复用;缺失时才请求补 token
- 返回 `balance`、`recentlyWillExpireBalance`、`willExpireTime`
- 积分到期批次:`POST /japi/oms/web/peace/credit/balanceDetail`
- JSON:`userId`、`current`、`pageSize`
- `records[]` 包含 `count` 和 `expireTime`
- 积分流水:`POST /japi/oms/web/peace/credit/colJournal`
- JSON:`uid`、`pageNum`、`pageSize`
- 可用于赠送、兑换后的积分增减精确核对
- 钱包兑换余额:`https://www.douyu.com/wjapi/nc/exchange/fim`
- 支付码:`/japi/oms/web/pay/getQrCode`
- 供应商鱼翅直充按供应商协议执行;到账必须核对斗鱼余额相对下单前基线增加,
供应商长期“待处理”不能覆盖实际到账事实。
- 供应商 API 返回成功时,执行器会再次调用鱼翅余额查询,任务结果写入
`gold_refreshed_after_success=true`;刷新失败不回滚已经成功的充值终态。
- 支付任务只负责出码和记录基线,到账轮询进入 `payment_poll` 独立任务槽。
- 精英宝典开通成功后必须再次刷新积分,任务结果写入
`points_refreshed_after_elite_opened=true`。
- 赠送精英令成功后必须短轮询积分到账,任务结果写入
`points_refreshed_after_gift=true`;未达到预期积分时保留
`gift_points_confirmed=false`。
## 电竞手册、和平小店与送礼
- 电竞手册绑定复用腾讯 `bindInfo` / `bindRoleParam` / `actBind`,但活动页、
`manual_id`、`actAlias` 和账号字段必须独立,不能写成精英宝典数据。
- 和平小店绑定和下单来自道聚城接口,确认逻辑仍遵守
`bindAct=0` 为 pending、`bindAct=1` 为 bound。
- 送礼是写操作,必须走写任务槽和代理;查询余额/积分不能替代送礼结果回查。
## 已知踩坑
### 2026-11-21:同名 pending 导致确认按钮一直灰
现象:二维码已出,界面显示“当前绑定”和角色,但 `pending=0`,确认按钮禁用。
生产证据:账号 `23385` 的二维码任务轮询 106 次后 `role_timeout`;`cjm` 与
`20260120QYOOB` 返回同名角色,`cjm.needBindAct=0`,
`QYOOB.bindAct=0 + needBindAct=1`。旧逻辑只接受“角色名变化”或“同 alias 从
`bindAct=1` 转为 pending”,把已经存在的活动 pending 误判成旧残留。
初次修复:动作 alias 已存在同名 pending 时直接视为可确认,原因
`existing_actionable_pending`;二维码预检也会立即收敛为 `role_ready`。
回归:`tests/test_douyu_binding_state.py`、`tests/test_douyu_account_probe.py`、
`tests/test_douyu_task_concurrency.py`。
> 2026-11-22 更正:该修复把长期静态的 `needBindAct=1` 当成了新扫码结果,已废弃。
> 当前规则见上方“pending 判定顺序”。
### 2026-11-21:扫码成功但轮询超时、确认按钮不稳定
生产失败任务中大量出现 `role_timeout`,但 `result` 实际已经带回角色,且部分
`bindAct=1`。原因是 10 分钟轮询窗口偏短、每轮无条件查两个 alias,以及只把
`bindAct=0 + bindRole=1` 当成功。
修复:轮询窗口延长到 20 分钟;分阶段退避;legacy 每轮查询、动作 alias 按变化/
周期/末轮补查;直接 `bindAct=1` 立即收敛;前端自动轮询期间仍允许“立即查询角色”;
关键接口响应进入 `douyu_role_api_logs`。
### 2026-11-21:同名角色被误判为已经绑定
生产接口留档显示,活动 alias 可以同时返回 `bindAct=1`、`needBindAct=1` 和与上次
相同的角色名。旧判定先看 `bindAct=1` 并直接返回 `already_bound`,导致用户重新
绑定同名角色时任务一直等待。
初次修复:只要动作 alias 仍返回 `needBindAct=1`,同名角色也进入可确认状态。
> 2026-11-22 更正:该结论不成立。`needBindAct=1` 在该活动里可以长期存在;同名角色
> 不能只靠它进入 pending。最终规则是 `bindAct=0` 才算 pending,`bindAct=1` 已绑定。
### 2026-11-22:历史绑定记录证明静态 pending 会误报
生产账号 `2212`、`24372` 的 `bind_ok` 历史分别确认于 2026-10-22 和 2026-11-15,
但二维码预检仍长期看到同名角色和 `bindAct=1 + needBindAct=1`。旧逻辑把该状态
写成 `role_ready`,随后客服页和履约页都显示“待确认角色”,实际用户尚未扫码。
初次修复错误地要求所有同名 pending 都必须有状态迁移。这样虽然挡住了
`bindAct=1` 历史角色误报,却也会让合法的已有 `bindAct=0` pending 超时。
### 2026-11-22:最新 HAR 重新确认 pending 与平台冷却
`11.22-绑定成功-1.har`:二维码轮询 70 次都没有出现新的 `isScan=true`,但活动
alias 和 `cjm` 一开始就有 `bindAct=0 + bindRole=1 + roleName=只为爱杰宝`;
官网仍允许直接 `actBind` 并成功,随后回查变为 `bindAct=1`。
`11.22-绑定-换绑失败.har`:扫码已经出现 `isCompleted=true`,`cjm` 也返回了新角色
`巫师基尔斯84`,但活动 alias 仍绑定旧角色,且 `canChangeTime=1795449600`
(2026-11-24 00:00 CST)。`actBind` 返回:
```json
{"error":-200001,"msg":"该平台账号未到可换绑时间,请使用其他平台账号"}
```
这说明 `-200001` 限制的是斗鱼平台账号,不是腾讯游戏角色。失败时必须保留活动
alias 上的旧角色,不能把 `cjm` 的新角色写入账号库。
最终修复:`bindAct=0` 的已有 pending 可确认;`bindAct=1` 永远不是 pending;
二维码预检遇到平台账号冷却时不发码;确认接口保留原始 error code,结构化为
`account_role_cooldown`;失败前后都只写回活动 alias 的原绑定角色。
### 历史固定规则
- 不要把 `bindRole=1` 当成已绑定;
- 不要把未确认时的换绑倒计时当成冷却;
- 不要用 `cjm` 的旧角色覆盖活动 alias 当前状态;
- `bindAct=0` 是 pending,可以在发新二维码前已经存在;
- `bindAct=1` 是 bound,即使同时返回 `needBindAct=1` 也不是 pending;
- 不要把 `needBindAct=1` 单独当成本轮扫码结果;
- `actBind=-200001` 是当前斗鱼账号冷却,不是客户游戏角色冷却;
- `actBind` 失败后必须保留旧绑定,不能写入新扫码角色;
- 不要在页面层重新实现 `bindAct/needBindAct` 判断;
- 不要把原始 `bind_summary` 当业务文案,它只用于排障。
## 变更记录
| 日期 | 变更 |
| --- | --- |
| 2026-11-21 | 建立斗鱼协议总览;补充多 alias 职责、pending 真值表、结构化判定日志和同名 pending 修复记录 |
| 2026-11-21 | 补充 `storehome` 单账号全量商品资格、`storedetail`/`batchExchangeLimit` 边界和抓包证据入口 |
| 2026-11-21 | 补充同名重绑、轮询退避、直接绑定识别和角色接口原始响应留档 |
| 2026-11-21 | 按最新 HAR 更新鱼翅余额/充值二维码/支付状态、积分 multipart、到期批次和积分流水协议 |
| 2026-11-22 | 按成功/失败 HAR 重构绑定判定:已有 `bindAct=0` 可确认,`bindAct=1` 不误报,`-200001` 归为斗鱼账号冷却并保留旧角色 |