MediaCrawler/mac-agent-os-main/03_knowledge/99_system/matrix/douyin-login-pitfalls.md

title, tags, created, updated, nature

title	tags	created	updated	nature
抖音登录流程 — 全链路知识与踩坑记录	douyin login sms verification iframe selector timing	2026-06-28	2026-06-28	reference

抖音登录流程 — 全链路知识与踩坑记录

本文包含 2026-06-28 大规模调试中积累的所有登录经验。 适用于 douyin_ops.py 的 _ensure_logged_in() 和 sms_login() 方法。

---

一、登录状态检测

1.1 判断已登录的方法（按可靠性排序）

方法	选择器	可靠性	说明
data-e2e 用户信息区	[data-e2e="user-info"]	⭐⭐⭐ 最高	抖音官方 e2e 标记，有就必已登录
头像元素	[class*="avatar"] 或 [data-e2e*="avatar"]	⭐⭐ 中	部分页面没有这个选择器
登录按钮不可见	button:has-text("登录") 不可见	⭐ 低	仅作兜底，不精确

1.2 判断未登录的方法

• 右上角可见的**「登录」按钮**
• 选择器：button:has-text("登录"), span:has-text("登录"), div:has-text("登录")
• 注意：首页推荐流中这个按钮始终存在，要用 is_visible() 确认

1.3 关键注意事项

• 首次打开抖音首页加载慢，至少要等 6 秒才能做登录检测（我们试过 2s→3s→5s→6s，6s 最稳定）
• 登录弹窗可能在上次会话的 cookie 有效时不弹出，直接显示已登录状态
• 登录成功后必须重新导航到 /user/self，因为弹窗处理改变了页面 URL

---

二、登录弹窗检测

2.1 弹窗位置：iframe

抖音的登录弹窗（passport 护照页）是在 iframe 中加载的，iframe URL 模式：

• passport.douyin.com
• sso.douyin.com
• 域名含 login

2.2 弹窗选择器

用途	选择器	说明
弹窗容器	.second-verify-panel, .uc-ui-verify_sms-verify	覆盖新旧两版 class
二维码区域	div[class*=qrcode], img[class*=qrcode], canvas[class*=qrcode]	用于二维码检测

2.3 ⚠️ iframe 查找顺序（重要！）

必须先查 iframe，再查主页面！

❌ 错误做法（我们踩过的坑）：
   1. 主页面查 verify_panel → 匹配到遮罩层（`.second-verify-panel`）
   2. login_frame = page（主页面）
   3. 在主页面搜手机输入框 → 找不到 ❌（因为输入框在 iframe 内）

✅ 正确做法（修复后）：
   1. 遍历所有 iframe，找 passport/login 域的 verify_panel
   2. 找到 → login_frame = iframe
   3. 在 iframe 内搜手机输入框 → 能找到 ✅
   4. iframe 没找到 → fallback 到主页面

2.4 弹窗类型判断

弹窗可能有三种状态：

弹窗出现
  ├─ 一键登录 → 有 "一键登录" 按钮，无手机号输入框
  ├─ 验证码登录 → 有手机号输入框 + 获取验证码按钮
  └─ 二维码登录 → 有二维码图片/画布，需切 tab

一键登录特征

• 选择器：button:has-text("一键登录"), span:has-text("一键登录")
• 点击后等 5 秒
• 可能直接登录成功，也可能跳到验证码页（继续走 sms）

验证码登录特征

• 手机号输入框：input[placeholder*="手机"]（匹配 placeholder="请输入手机号"）
• 验证码输入框：input[placeholder*="验证码"]（匹配 placeholder="请输入验证码"）
• 获取验证码按钮：button:has-text("获取验证码")

二维码登录特征

• 检测：div[class*=qrcode], img[class*=qrcode], canvas[class*=qrcode]
• 处理：找到「验证码登录」tab 并点击切换

---

三、SMS 验证码流程

3.1 完整流程

1. 导航到登录页（如果不在）
2. 查找 passport iframe（最多 5 次尝试，每次间隔 2 秒）
3. 等 3 秒渲染
4. 检测二维码 → 切「验证码登录」tab
5. 找手机号输入框 → 填入手机号（3 次重试，每次间隔 1 秒）
6. 点击「获取验证码」
7. 轮询 SMS API 获取验证码（最多 6 次，共 60 秒超时）
8. 填入验证码
9. 点击「登录」
10. 判断是否登录成功

3.2 手机号输入框查找（带重试）

phone_sel = "input[placeholder*='手机'], input[type='tel'], input[name='mobile'], input[id*='phone'], input[id*='mobile']"
for retry in range(3):
    for sel in [phone_sel, "input:first-of-type"]:
        inp = await login_frame.query_selector(sel)
        if inp and await inp.is_visible():
            # 填入手机号
            break
    if phone_filled:
        break
    await asyncio.sleep(1)

注意：input:first-of-type 会匹配到首页搜索框，所以优先用 placeholder 选择器。

3.3 验证码输入框查找

code_sel = "input[placeholder*='验证码'], input[maxlength='6'], input[maxlength='4'], input[autocomplete='one-time-code']"

3.4 登录成功判断

判断方法	说明
URL 变化	"passport" in current_url → 仍在登录页 / not → 登录成功
右上角头像	[data-e2e="user-info"] 存在且可见 → 登录成功（兜底方案）

两者都用！ 如果 URL 变了但右上角还没渲染出头像，等 3 秒再查一次。

---

四、时序控制（重要）

4.1 各步骤等待时间

步骤	等待时间	原因
首次打开后检测	6 秒	抖音首页加载慢，特别是第一打开，推荐流+弹窗需要完整渲染
切换 tab 后	3 秒	tab 切换动画 + 新内容渲染
填手机号后	1 秒	防抖 + 输入框状态同步
点击获取验证码后	2 秒	等待 SMS 发送
填入验证码后	1 秒	防抖
点击登录后	3-5 秒	等待页面跳转
登录成功后重导航	3 秒	等待 /user/self 渲染

4.2 超时控制

• SMS 验证码轮询：最长 60 秒（6 次 × 10 秒）
• 单次 iframe 查找：最长 10 秒（5 次 × 2 秒）
• 页面 goto 超时：20 秒

---

五、选择器备忘（抖音 Web 版）

5.1 官方 data-e2e 选择器

这些是抖音官方的自动化测试标记，最稳定：

用途	选择器
用户信息区（已登录标志）	[data-e2e="user-info"]
用户头像	[data-e2e="user-avatar"]（不一定存在）
搜索输入框	[data-e2e="searchbar-input"]
点赞按钮	[data-e2e="video-player-digg"]
收藏按钮	[data-e2e="video-player-collect"]
分享按钮	[data-e2e="video-player-share"]
评论列表	[data-e2e="comment-list"]
评论点赞	[data-e2e="comment-digg"]
粉丝数	[data-e2e="user-info-fans"]（值可能混合中文）
关注数	[data-e2e="user-info-follow"]
获赞数	[data-e2e="user-info-like"]

5.2 登录弹窗选择器（不定期变化）

这些 class 名由抖音前端动态生成，每次发布可能变化：

用途	6月28日已确认的 class
手机号输入框	yKcGN1NT X5L8kib_
验证码输入框	tnpNAdqe _Yqor1vk
获取验证码按钮	gKXDWaPG KX2Mhb6E
验证码 tab	zad3EGHJ

因此，不要依赖 class 名，用 placeholder/text 代替。

5.3 推荐做法：文本/属性匹配

# ✅ 稳定
input[placeholder*="手机"]     # 匹配 "请输入手机号"
input[placeholder*="验证码"]    # 匹配 "请输入验证码"
button:has-text("获取验证码")   # 匹配按钮文字
div:has-text("验证码登录")      # 匹配 tab 文字

# ❌ 不稳定（class 会变）
.tnpNAdqe                      # 下个版本可能就改了
.yKcGN1NT                      # 同上

---

六、已踩过的坑（必读）

坑 1：logger 未定义导致 executor 闪退

现象：任务提交后状态一直 "running"，实际已挂，slots 空但 active_tasks 有残留。

根因：executor.py 中使用了 logger.info() 但 logger = logging.getLogger("guardd.executor") 未定义，NameError 抛出，executor 闪退但任务状态来不及更新。

修复：添加 logger = logging.getLogger("guardd.executor")。

坑 2：主页面遮罩层匹配导致 iframe 检测失败

现象：弹窗出现了但手机号输入框找不到。

根因：verify_panel 选择器 .second-verify-panel 在主页面遮罩层上匹配成功，login_frame 设为主页面（不是 iframe），在主页面搜手机输入框当然搜不到。

修复：先查 iframe，再查主页面。

坑 3：登录后页面 URL 变化导致采集到首页数据

现象：采集任务显示完成，但 profiles.json 中昵称/粉丝数据为空或为首页标题。

根因：登录弹窗处理后，页面 URL 从 /user/self 变成了首页或其他地址，但 goto_profile() 继续刮取当前页面内容（首页推荐流），拿不到用户数据。

修复：登录成功后重新 goto("/user/self")。

坑 4：2 秒等待不够

现象：浏览器打开后鼠标立即动了，此时页面还没渲染完，弹窗还没出现。

根因：抖音首页首次加载~4-5 秒，2 秒时 _has_avatar() 判断为未登录（因为没渲染完），然后触发弹窗检测也找不到弹窗，最后点了"登录"按钮导致页面刷新。

修复：初始等待时间从 2 秒改为 6 秒。

坑 5：_build_cmd 按字段拼装导致 command_line 出错

现象：采集任务一直失败，executor 日志显示 --blueprints= 为空。

根因：executor._build_cmd() 从 task.get("blueprint") 读蓝图名，但 CommandBus 传的 blueprint 字段是空字符串（没传对），拼出了 mc run --blueprints= --rounds=1。

修复：优先使用 task.command_line（CommandBus 已渲染好的完整命令），_build_cmd 按字段拼装仅作 fallback。

坑 6：5kecheng 双 guardd 进程

现象：远程机器任务不执行，所有请求都返回空。

根因：SSH 部署时 pkill -9 -f guardd + nohup python3 guardd.py 启动了一个新实例，而 launchd 也管理了一个旧实例。两个 guardd 争抢端口 9090，其中一个没有 HTTP 服务。

修复：统一用 launchd 管理，不用 nohup。

坑 7：登录后 URL 不变（前端 overlay 形式）

现象：登录成功了但 sms_login 返回 False。

根因：有的登录弹窗是前端 overlay（不在 passport 域名下），URL 不变化。sms_login 只检查 URL，误判为失败。

修复：加 _has_avatar() 兜底判断。

坑 8：profiles.json 同步走本地文件违反联邦对等

现象：7kecheng 采集了数据，但 Dashboard 看不到。

根因：AccountService._get_profile_for_account() 直接读本机 profiles.json，不走 guardd API。

修复：改为统一通过 guardd HTTP API (/accounts/profiles) 读取，本机远程无差别。

---

七、录制文件分析指南

录制的 JSON 文件位于 agent-local/tools/matrix/recordings/。

7.1 关键字段含义

字段	含义
t	事件类型（click/hover/key/scroll）
tag	HTML 标签
text	元素文本内容
cls	元素的 CSS class（关键！）
placeholder	input 元素的占位符
type	input 类型
e2e	data-e2e 属性值
vis	元素是否可见
before_state.selectors	录制前页面状态快照
before_state.text_snippet	页面文本片段

7.2 如何从录制中提取特征码

# 找手机号输入框
grep -B5 -A3 "请输入手机号" recording_xxx.json

# 找验证码输入框
grep -B5 -A3 "请输入验证码" recording_xxx.json

# 找登录按钮
grep -B5 -A3 "获取验证码" recording_xxx.json

# 查看页面文本快照（了解页面状态）
grep "text_snippet" recording_xxx.json | head -1 | python3 -c "import json,sys;print(json.load(sys.stdin)['text_snippet'][:500])"

---

八、蓝图登录检测覆盖范围

当前 _ensure_logged_in() 被以下操作调用：

蓝图操作	在流程中调用位置
goto_home	execute_op() 中 goto 首页后
dy_goto_profile	execute_op() 中 goto 个人主页后
goto_profile	独立方法中被调用
_ensure_logged_in 自身	无弹窗时递归调用

设计原则

所有涉及浏览器导航的操作（goto_home、goto_url、goto_profile）都应该调用 _ensure_logged_in()。目前 goto_url 还没有加，待补。

---

九、相关文件索引

文件	内容
douyin_ops.py	抖音原子操作 + _ensure_logged_in + sms_login
matrix_modules/account/sms_login.py	SMS 登录模块
matrix_modules/account/douyin_login.py	抖音登录模块
matrix_modules/account/login_state_machine.py	登录状态机
03_knowledge/99_system/matrix/matrix-known-pitfalls.md	已知坑（浏览器/系统）
03_knowledge/99_system/matrix/matrix-sms-verification.md	SMS 验证码自动接收配置