# 斗鱼协议总览 更新时间: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=&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` 归为斗鱼账号冷却并保留旧角色 |