Skip to content

feat: 新增 --check_session 预检命令,开爬前确认 cookie/代理是否可用 (#960) - #963

Open
SergiorCode wants to merge 1 commit into
NanmiCoder:mainfrom
SergiorCode:feat/session-preflight
Open

feat: 新增 --check_session 预检命令,开爬前确认 cookie/代理是否可用 (#960)#963
SergiorCode wants to merge 1 commit into
NanmiCoder:mainfrom
SergiorCode:feat/session-preflight

Conversation

@SergiorCode

Copy link
Copy Markdown

Closes #960.

开爬之前先确认登录态与代理是否可用,只发一次请求就退出:

uv run main.py --platform xhs --check_session
========================================================================
Session preflight
proxy: off
========================================================================
[FAIL] xhs    xiaohongshu  failed - session expired or cookie is invalid (the platform answered 'not logged in' (source: browser_data/xhs_user_data_dir))
========================================================================
ok 0 / failed 1 / unknown 0

全部通过退出码 0,有失败退出码 1,方便写进定时任务。不自动登录,也不刷新 token。

几个实现上的选择

没有复用各平台的 pong() 五个平台的 pong() 内部都是 except Exception: return False,直接复用的话代理不通、被限流、响应异常全都会被报成「cookie 失效」——正好是这个 issue 想避免的那种误导。所以这里调用 pong() 内部的那一个请求,让异常冒出来再归类:cookie 失效 / 缺关键字段 / 代理不可用 / 网络不通 / 被限流 / 响应异常 / 超时。

登录态从用户实际使用的地方读。 优先 config.COOKIES--cookies),否则读 --lt qrcode 登录留下的 browser_data/ profile,因为默认流程根本不会往 config.COOKIES 写东西。两条路径都只发一次平台请求。

能不发请求就先报错的情况:xhs 缺 a1 会让 sign_with_xhshowValueError,zhihu 缺 d_c0 会让 _pre_headers 抛异常,这两种直接提示「cookie 缺少关键字段,可能来自其他平台」。

抖音和贴吧标记为 unknown 而不是给结论。 这两个平台的 pong() 读的是浏览器 localStorage / cookie,没有可探测的登录态接口。抖音的 pong() 先看 localStorage.HasUserLogin,cookie 里的 LOGIN_STATUS 只是兜底,所以 cookie 里没有它并不能证明未登录。unknown 不计入失败,否则这两个平台的定时任务会永远是红的。

weibo 绕开了 client.request():它带 5 次重试(一次预检就要 12s 以上),而且响应不是 JSON 时会去解引用 playwright_page,预检里那是 None

预检放在 --init_db 之前 —— 两个参数一起写时,--init_dbreturn 会让预检被静默跳过。

测试与文档

tests/test_session_check.py 33 个用例,全部离线:探测那一步被 monkeypatch,不构造真实 client,也不发任何请求。覆盖每种失败归因、超时、退出码契约(含 unknown 与 failed 混合的场景)、main() 的接线,以及两种 cookie 来源。

uv run pytest tests/     # 129 passed

README(中/英/西)的运行示例和 docs/常见问题.md 各补了一条。

CLI 参数用 --check_session(下划线),与仓库现有的 20 个参数保持一致;issue 里写的是 --check-session,如果更希望用连字符我可以加个别名。

English summary

Adds --check_session: loads the saved login state (from config.COOKIES, else the browser_data/ profile left by qrcode login), makes exactly one low-impact authenticated request per platform, and prints pass/fail with a likely cause — expired cookie, missing cookie field, dead proxy, network, platform block, unexpected response, timeout. Exit code 0 when nothing failed, 1 otherwise.

It deliberately does not reuse each platform's pong(): those swallow every exception and return False, which would report a dead proxy as "your cookie expired". douyin and tieba have no probeable login endpoint, so they report unknown with a cookie-level hint rather than a fake verdict, and unknown does not affect the exit code.

33 offline tests; uv run pytest tests/ → 129 passed.

…#960)

在开爬之前用一次低成本的登录态请求确认 cookie / 代理是否可用,并给出失败原因,
避免跑起来才发现 session 已经过期。

  uv run main.py --platform xhs --check_session

实现要点:

- 只发一次平台请求,不自动登录、不刷新 token;全部通过退出码 0,有失败退出码 1,
  方便定时任务判断。
- 不复用各平台的 pong()。pong() 内部 `except Exception: return False`,一旦复用,
  代理不通、被限流、响应异常都会被报成“cookie 失效”。这里直接调用 pong() 内部的
  那一个请求,让异常冒出来再归类:cookie 失效 / 缺关键字段 / 代理不可用 / 网络不通
  / 被限流 / 响应异常 / 超时。
- 登录态从用户实际使用的地方读:优先 config.COOKIES(--cookies),否则读 qrcode
  登录留下的 browser_data/ profile,两条路径都只发一次请求。
- 缺 cookie 关键字段时不发请求就先报错:xhs 缺 a1 会让签名抛 ValueError,
  zhihu 缺 d_c0 会让 _pre_headers 抛异常。
- 抖音与贴吧的 pong() 读的是浏览器 localStorage / cookie,没有可探测的登录态接口,
  所以只给 cookie 层面的线索并标记 unknown,不伪装成结论;unknown 不影响退出码。
- weibo 绕开 client.request():它带 5 次重试(一次预检要 12s 以上),且响应不是
  JSON 时会解引用 playwright_page(预检里是 None)。

预检放在 --init_db 之前,否则两个参数一起写时 --init_db 的 return 会让预检被静默
跳过。README(中/英/西)与常见问题各补了一条说明。

测试 33 个,全部离线:探测那一步被 monkeypatch,不构造真实 client、不发请求。
uv run pytest tests/ -> 129 passed。
@dosubot dosubot Bot added size:XL This PR changes 500-999 lines, ignoring generated files. enhancement New feature or request labels Aug 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request size:XL This PR changes 500-999 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add a lightweight preflight check for cookies/proxy before starting a crawl

1 participant