20 KiB
斗鱼协议总览
更新时间:2026-11-21
本文是斗鱼协议、状态判定和线上排障的统一入口。代码是最终依据;本文记录代码 难以直接表达的协议语义、字段优先级、已验证边界和历史踩坑,避免重复分析。
后续模块重构和任务调度实施以 斗鱼账号平台最终实施设计 为主线。
维护规则
每次修改斗鱼协议相关代码时,同一个提交必须同步更新本文:
- 新增或修改字段时,补字段真值表和影响范围;
- 新增
actAlias、接口或任务类型时,说明它在多渠道判定中的职责; - 修复线上问题时,在“踩坑记录”追加日期、现象、根因、判定变化和回归用例;
- 抓包只能证明当时行为,不能直接覆盖已由代码和线上回归验证的结论;
- 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() 返回:
- 没有角色名:不可确认;
- 当前
bindAct=1:已经最终绑定,不可确认,原因already_bound; - 角色名与 baseline 不同:可确认,原因
role_changed; - 同 alias 从
bindAct=1变为bindAct=0:可确认,原因same_alias_after_bound_transition; - 同 alias 从
needBindAct=0变为needBindAct=1,且当前bindAct=0: 可确认,原因same_alias_after_pending_transition; - 动作 alias 当前是
bindAct=0 + needBindAct=1 + roleName:可确认,原因existing_actionable_pending。即使它在二维码生成前已经存在、没有发生 状态迁移,官网也允许直接actBind; - 没有 baseline 且不是动作 alias pending:不可确认,原因
pending_without_baseline; - 角色名相同但缺少完整 baseline 快照:不可确认;
- 其他同名角色:视为旧残留。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_aliasesbind_decisionbind_candidate_decisionspending_role_namebind_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
- 2026-11-21 页面使用
- 积分到期批次:
POST /japi/oms/web/peace/credit/balanceDetail- JSON:
userId、current、pageSize records[]包含count和expireTime
- JSON:
- 积分流水:
POST /japi/oms/web/peace/credit/colJournal- JSON:
uid、pageNum、pageSize - 可用于赠送、兑换后的积分增减精确核对
- JSON:
- 钱包兑换余额:
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 归为斗鱼账号冷却并保留旧角色 |