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

20 KiB
Raw Blame History

斗鱼协议总览

更新时间:2026-11-21

本文是斗鱼协议、状态判定和线上排障的统一入口。代码是最终依据;本文记录代码 难以直接表达的协议语义、字段优先级、已验证边界和历史踩坑,避免重复分析。

后续模块重构和任务调度实施以 斗鱼账号平台最终实施设计 为主线。

维护规则

每次修改斗鱼协议相关代码时,同一个提交必须同步更新本文:

  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 并自动退回未开始状态。

完整流程

查询所有 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 响应变化、 二维码预检、确认前、确认接口返回和确认后回查时写入。

建议的生产只读查询:

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;

角色接口原始响应查询:

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;

日志检索:

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。详细字段、分类顺序和抓包证据见 精英宝典商品资格与全量快照。

兑换成功的唯一业务收口必须是 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 返回:

{"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 归为斗鱼账号冷却并保留旧角色