douyin-downloader 登录态失效自动重新登录auto-relogin全解析从 2483 错误到自动重试一次【免费下载链接】douyin-downloaderA practical Douyin downloader for both single-item and profile batch downloads, with progress display, retries, SQLite deduplication, and browser fallback support. 抖音批量下载工具去水印支持视频、图集、合集、音乐(原声)。项目地址: https://gitcode.com/GitHub_Trending/do/douyin-downloader本文基于douyin-downloader仓库的设计文档《登录态失效自动重新登录auto-relogin设计》docs/superpowers/specs/2026-06-25-auto-relogin-design.md 及其实现计划 docs/superpowers/plans/2026-06-25-auto-relogin.md 展开。文章聚焦该项目中「抖音登录 cookie 过期后CLI 如何自动检测、自动打开浏览器重新登录并重试一次原命令」这一完整链路。读完你将掌握2483 登录态失效的判定原理、异常如何在共享 API 客户端中单点抛出、fetch_cookies可复用登录入口、interactive_relogin交互重登流程、_run_with_relogin顶层捕获重试包装器以及桌面端同步策略与对应的测试矩阵。一、背景与问题搜索返回空 data真实原因是登录态失效设计文档给出的排查起点是一个非常典型的真实场景运行--search 手机 --search-max 10输出data为空。经排查抖音实际返回的响应体是{status_code: 2483, status_msg: 请先登录再继续搜索吧}此时config/cookies.json文档示例时间戳 2026-02-18里的登录会话已经过期。关键排查结论是cookie 确实被发往了douyin.comsessionid、sid_tt等字段都在请求里所以这不是传输层 bug而是服务端登录态失效。设计文档指出的现有体验缺陷在于CLI 会把这种情况当成「成功 0 条」print_success(搜索结果已保存0 条)真实原因需要重新登录被埋没看起来像是一个 bug。这正是 auto-relogin 特性要解决的根因问题。二、目标与非目标只重试一次不做预探测设计文档明确界定了特性边界目标正常运行任意命令时若检测到抖音返回「未登录」2483自动打开浏览器引导登录、抓取新 cookie、然后自动重试一次原命令覆盖所有命令下载 / 搜索 / 热榜。非目标不做主动 pre-flight 登录探测公开作品下载本就不需要登录避免误触发。不在桌面端实现终端浏览器登录流程桌面有自己的 GUI 登录。不处理无限重试只重试一次。这三条「非目标」决定了后续架构的形态检测必须是响应级的而不是请求前的重登编排只存在于 CLI且必须有一个护栏保证绝不形成死循环。三、总体方案Option A单点检测抛异常 CLI 顶层捕获重试设计文档采用「三层分工」的架构对应关系如下层文件是否同步到 desktop检测 LoginRequiredErrorcore/api_client.py core/init.py 导出逐字节同步终端浏览器登录的可复用入口tools/cookie_fetcher.py同步加法式交互式重新登录 捕获重试cli/login_flow.py新、cli/main.py仅 CLI这样设计的关键动机是检测逻辑必须覆盖所有命令。由于所有 endpoint 都走共享的_request_json通道在通道内做单点检测一处落点天然覆盖下载、搜索、热榜等全部命令无需在每个子命令里各自加判断。四、检测层LoginRequiredError与_is_login_required4.1 异常类设计在 core/api_client.py 顶部新增了异常类携带三个属性status_code、status_msg、path并在__init__中构造一条信息完整的异常消息class LoginRequiredError(Exception): Raised when Douyin rejects a request because the session is not logged in. Signalled by status_code 2483 (or a status_msg asking to log in). Higher layers (CLI) catch this to trigger an interactive re-login retry. def __init__(self, status_code: int, status_msg: str, path: str): self.status_code status_code self.status_msg status_msg self.path path super().__init__(flogin required (status_code{status_code}) at {path}: {status_msg})同时该异常在 core/init.py 中被 re-exportfrom .api_client import DouyinAPIClient, LoginRequiredError并加入__all__使上层可以统一从core导入。4.2 检测谓词窄、可扩展检测逻辑是「窄谓词 可扩展」的设计见 core/api_client.py_LOGIN_REQUIRED_STATUS_CODES {2483} def _is_login_required(data: object) - bool: if not isinstance(data, dict): return False code data.get(status_code) msg str(data.get(status_msg) or ) # Match by message, not by the bare status_code8: 8 is a generic # Douyin error code, but 用户未登录 is unambiguously not logged in # (returned by /profile/self/ and other endpoints on an expired # session). Message-matching avoids misreading an unrelated code-8. return code in _LOGIN_REQUIRED_STATUS_CODES or 请先登录 in msg or 用户未登录 in msg要点解读非 dict 直接返回 False避免对非 JSON 结构误判。代码集合与消息双路命中status_code 2483是硬编码的判定主通道消息包含「请先登录」是兜底通道。实现相对设计文档的演进当前源码在「2483 / 请先登录」之外还加入了用户未登录 in msg这一消息匹配。源码注释解释了原因抖音的/profile/self/等端点在会话过期时返回通用的status_code8但消息是「用户未登录」按消息匹配可以避免把某个无关端点上恰好为 8 的错误码误判成登出。这是「窄谓词可扩展」原则的实例化——通过为消息匹配增加关键词来扩展覆盖面而不是放宽状态码集合。4.3 落点_request_json成功返回前立即抛出关键落点在 core/api_client.py_request_json解析出datadict之后、return之前调用检测命中即立即抛LoginRequiredErrorresult data if isinstance(data, dict) else {} _log_api_response(path, attempt, max_retries, body, result, started) if _is_login_required(result): raise LoginRequiredError( int(result.get(status_code) or 0), str(result.get(status_msg) or ), path, ) return result两个关键设计点不消耗那 3 次重试_request_json默认max_retries3但重试登录态响应毫无意义——服务端已经明确告诉你会话失效换签名、换 UA 重试也不会成功。因此检测命中后立即抛出同时代码中except LoginRequiredError: raise见 core/api_client.py保证该异常不会被普通的请求异常捕获逻辑吞掉。与反爬空响应重试逻辑不冲突设计文档特别注明2483 响应是 HTTP 200 非空 JSON body会正常通过 empty-body 重试判断、被解析成 dict然后命中检测既有的反爬空响应empty 200重试逻辑完全不受影响。二者是正交的两条路径空 body 是反爬信号可重试非空 body 里的 2483 是登录态信号不可重试。另外值得注意的是桌面端独有的一条路径_payload_from_bridge_result也做了同样的检测core/api_client.py并且_request_json_gated会把页面桥的NOT_LOGGED_IN错误转换为LoginRequiredError(0, page bridge: not logged in, path)——说明「单点检测」在页面桥通道上同样成立。五、可复用登录入口fetch_cookies参数化薄封装原有 tools/cookie_fetcher.py 中capture_cookies(args: argparse.Namespace)依赖 argparse上层调用者如果直接使用它就得伪造一个Namespace。为此新增了一个参数化薄封装tools/cookie_fetcher.pyasync def fetch_cookies( *, output: Path, config: Optional[Path] None, url: str DEFAULT_URL, browser: str chromium, headless: bool False, include_all: bool False, ) - int: Parameterised entry to the manual-login cookie capture flow. Thin wrapper around :func:capture_cookies so callers (e.g. the CLI auto-relogin flow) dont have to fake an argparse.Namespace. args argparse.Namespace( outputoutput, configconfig, urlurl, browserbrowser, headlessheadless, include_allinclude_all, ) return await capture_cookies(args)设计要点纯加法main()保持不变仍走 argparse →capture_cookies新增封装不改变既有 CLI 行为。参数即契约output必填写 cookie 的目标路径其余参数有默认值url默认DEFAULT_URL https://www.douyin.com/浏览器默认chromiumheadlessFalseinclude_allFalse。返回值约定返回 int 退出码0 表示成功、非 0 表示失败Playwright 未安装、用户中止等情况。上层据此判断重登是否完成。测试 tests/test_cookie_fetcher_fetch.py 验证了该封装的核心行为monkeypatch 掉capture_cookies后断言fetch_cookies构造的 Namespace 各字段与默认值一致browser chromium、headless is False、include_all is False、url DEFAULT_URL、config is None。六、交互式重新登录cli/login_flow.py仅 CLI新增文件 cli/login_flow.py 是 CLI 独有的编排层模块 docstring 明确说明「NOT shared with the desktop project」。它本身不负责检测而是由cli.main在LoginRequiredError冒泡上来时调用。6.1 交互护栏can_interactive_logindef can_interactive_login(*, serve: bool False) - bool: True only when we can safely open a browser and read a terminal Enter. if serve: return False try: return bool(sys.stdin.isatty()) except (AttributeError, ValueError): return False条件是两个非--serve服务模式stdin 是 TTY。非交互环境CI、服务模式、管道重定向一律不自动开浏览器只清晰报错并停止。isatty()可能抛出的AttributeError/ValueError如 I/O 流已关闭也被兜底为 False。6.2 重登编排interactive_reloginasync def interactive_relogin( cookies_path: Path _DEFAULT_COOKIES_PATH, ) - Optional[dict]: Open a browser, guide login, capture cookies. Returns fresh cookies or None. print( \n[登录态已失效] 抖音要求重新登录。即将打开浏览器请完成抖音登录 登录成功后回到本终端按 Enter。\n ) try: rc await fetch_cookies(outputcookies_path) except Exception as exc: # noqa: BLE001 — surface, dont crash the run logger.error(Interactive relogin failed to launch: %s, exc) print( [ERROR] 无法启动登录流程。请确认已安装 Playwright \n pip install playwright playwright install chromium \n或手动更新 config/cookies.json 后重试。 ) return None if rc ! 0: print([ERROR] 登录流程未成功完成已中止。) return None try: raw json.loads(Path(cookies_path).read_text(encodingutf-8)) except (OSError, json.JSONDecodeError) as exc: logger.error(Could not read captured cookies from %s: %s, cookies_path, exc) return None cookies sanitize_cookies(raw if isinstance(raw, dict) else {}) if not cookies.get(sessionid): print([ERROR] 登录后未获取到有效会话缺少 sessionid请重试。) return None return cookies流程与失败面打印中文引导提示随后调用fetch_cookies(outputconfig/cookies.json)打开浏览器。Playwright 未安装capture_cookies内部在ImportError时打印安装提示并返回 1tools/cookie_fetcher.py这里对fetch_cookies的异常和返回码都做了捕获并给出pip install playwright playwright install chromium或手动更新config/cookies.json的替代路径——不崩溃。成功后从磁盘读回新 cookie经sanitize_cookies清洗。关键校验cookie 中必须包含sessionid否则视为登录未成功返回None可能用户关掉了浏览器、或者登录未完成。七、顶层捕获 重试一次cli/main.py的_run_with_relogin7.1 包装器实现cli/main.py 中的_run_with_relogin是整条链路的中枢async def _run_with_relogin(make_coro, cookie_manager, *, serveFalse): Run make_coro(); on LoginRequiredError, relogin once and retry. make_coro is a zero-arg callable returning a fresh coroutine each call, so the retry re-creates its own DouyinAPIClient with refreshed cookies. Refreshed cookies propagate through cookie_manager as a clean replace (not a merge), and both call sites read their cookies from it on retry. for attempt in range(2): try: return await make_coro() except LoginRequiredError as exc: interactive can_interactive_login(serveserve) if attempt 1 or not interactive: display.print_error( f登录态失效需要重新登录status {exc.status_code} f{exc.status_msg or 请先登录}。 ) if not interactive: display.print_warning( 当前为非交互环境未自动打开浏览器。请手动更新 config/cookies.json或运行 python tools/cookie_fetcher.py 登录。 ) raise display.print_warning( f检测到未登录status {exc.status_code}开始重新登录… ) new_cookies await interactive_relogin() if not new_cookies: display.print_error(重新登录未完成已中止。) raise cookie_manager.set_cookies(new_cookies) display.print_success(已更新登录态正在重试…)核心机制逐条拆解make_coro是零参协程工厂每次调用返回一个新的协程因此重试时download_url/_run_discovery_subcommand会重新构建自己的DouyinAPIClient自动用上新 cookie。这是「重试必须带新登录态」的关键前提。for attempt in range(2)最多尝试两次——原始执行 重登后重试一次。第二次仍然抛LoginRequiredErrorattempt 1则不再重登明确报错并向上抛由main()顶层 handler 统一处理并以 exit code 1 退出。非交互护栏can_interactive_login(serveserve)为 False 时直接报错并raise绝不自动开浏览器。这与设计文档的错误处理矩阵一致。cookie 更新是「干净替换」而非合并cookie_manager.set_cookies(new_cookies)会整体替换。测试 tests/test_relogin_retry.py 特意预置了一个过期 keystale_csrf断言重登后该 key 不再存在——证明刷新不会把旧 cookie 的残留字段带进新会话。7.2 应用点一discovery 子命令搜索 / 热榜在 cli/main.py独立子命令分支被包上重登包装if args.hot_board is not None or args.search: discovery_cm CookieManager() discovery_cm.set_cookies(config.get_cookies()) await _run_with_relogin( lambda: _run_discovery_subcommand(args, config, discovery_cm), discovery_cm, serveFalse, ) return搜索 / 热榜是单次调用重试语义干净重登成功后整个子命令重新执行一遍。7.3 应用点二per-URL 下载循环在 cli/main.py 附近下载循环里对每个 URL 的download_url调用套上包装器并使用默认参数uurl捕获循环变量避免 late-binding 陷阱result await _run_with_relogin( lambda uurl: download_url( u, config, cookie_manager, database, progress_reporterdisplay, ), cookie_manager, serveFalse, )下载场景的安全保障来自两个既有机制的配合重登后cookie_manager被更新后续 URL 各自新建的DouyinAPIClient自动用上新 cookie已下载文件会被既有的 skip 去重机制跳过因此即使某条 URL 在重登前已经处理过重试也不会造成重复下载整体安全。八、错误处理矩阵设计文档给出了完整的错误处理矩阵实现与之一一对应情况行为2483 / 「请先登录」/「用户未登录」抛LoginRequiredError→ CLI 触发重登 → 重试一次重登成功、重试仍 2483第二次抛出后不再重登明确报错中止attempt 1分支非交互环境--serve/ 非 TTY不开浏览器打印「请手动更新 cookie」并中止Playwright 未安装打印安装指引pip install playwright playwright install chromium并中止不崩溃用户关掉浏览器 / 没登录成功interactive_relogin返回None→ 明确报错中止九、测试矩阵检测、封装、流程、重试四类测试实现计划按 TDD 方式为每个任务配套了测试当前仓库中均已存在tests/test_api_client_login_required.pycore 层_is_login_required参数化真值表覆盖 2483 命中、消息命中status_code0 「请先登录后再试」、status_code8 「用户未登录」命中、正常响应status_code0 ok不命中、10000限流不命中、空 dict 不命中、非 dict 不命中LoginRequiredError字段断言status_code/status_msg/path与消息内容从core包 re-export 的同一性断言用_FakeSession/_FakeResp伪造 HTTP 200 2483 body断言_request_json向上抛LoginRequiredError正常 body 则正常返回 dict。tests/test_cookie_fetcher_fetch.pytools 层monkeypatchcapture_cookies后断言fetch_cookies正确构造 Namespace 并委托返回码透传。tests/test_login_flow.pycli 层can_interactive_loginTTY 非 serve 为 Trueserve 模式为 False非 TTY 为 Falseisatty()抛ValueError时兜底为 Falseinteractive_relogin成功路径写盘后读回完整 cookie dict且保证含sessionid失败路径fetch_cookies返回 1 → None写盘 cookie 缺sessionid→ None。tests/test_relogin_retry.pycli 层第一次抛LoginRequiredError、第二次成功的重试语义断言make_coro被调用 2 次且cookie_manager被更新为全新 cookie非交互环境不调用interactive_relogin直接抛错重登失败返回 None时中止并抛错。回归保障方面tests/test_discovery.py与 api_client 相关既有测试保持全绿——因为既有 fakes 不会产生 2483 响应检测逻辑的加入对正常路径零影响。十、桌面端同步清单desktop设计文档专门用一节说明桌面端的同步策略核心是有意分叉桌面端没有抖音搜索功能GUI 的「搜索」框只是任务列表本地过滤/api/v1/history?q不是抖音内容搜索。但检测是 endpoint 无关的——桌面端的个人内容端点/api/v1/my-content/likes、/collects、/collectmixes、/self同样走共享_request_json、同样需要登录会话失效时同样返回 2483。桌面端的收益来自这些 my-content 流程而非搜索因此同步不搬任何搜索代码。必做同步LoginRequiredError_is_login_required_request_json检测落点逐字节同步进桌面端core/api_client.py该文件与 CLI 逐字节相同零冲突并在core/__init__.py同步导出同步tools/cookie_fetcher.py的fetch_cookies薄封装加法式。不搬到桌面cli/login_flow.py、cli/main.py的重登包装桌面用自己的 GUI 登录这是有意分叉。桌面端的安全网server/jobs.py的JobManager._run已有 catch-allexcept Exception会把LoginRequiredError转成 FAILED SSE error 事件前端正常显示不会崩溃。桌面端可选增强非本次范围在_run专门 catchLoginRequiredError给出明确的「登录态失效请重新登录」 特定事件前端弹「重新登录」按钮复用其POST /api/v1/cookiesGUI 登录。从当前仓库结构看CLI 侧的实现已完整落地core/api_client.py、core/init.py、tools/cookie_fetcher.py、cli/login_flow.py、cli/main.py 及四份对应测试均在仓库中设计文档中的「待评审」状态与实现计划的任务清单Task 1–5可作为读者理解该特性演进脉络的参考。十一、小结这套设计的可复用要点单点检测优于分散判断让所有 API 调用汇聚到一个通道_request_json登录态检测只需一处落点天然覆盖全部命令后续新增 endpoint 也自动获得该能力。登录态失效与可重试错误正交2483 / 「请先登录」是确定性业务信号重试无意义必须立即抛出且不消耗常规重试次数空 body、403/429 则是瞬时反爬信号走既有重试调度。二者在_request_json中被清晰分流。只重试一次是硬约束通过for attempt in range(2)和can_interactive_login双重护栏保证非交互环境不开浏览器、交互环境至多重试一次绝不形成死循环。复用既有登录基础设施fetch_cookies薄封装让重登编排直接复用 cookie_fetcher 的 Playwright 抓取能力无需重写浏览器登录逻辑Playwright 缺失时优雅降级为手动更新 cookie 的指引。跨仓库共享与分叉边界明确检测 异常 可复用登录入口逐字节同步到桌面端交互编排只留在 CLI——共享层零冲突、CLI 层有意分叉桌面端依靠既有异常捕获安全网降级。【免费下载链接】douyin-downloaderA practical Douyin downloader for both single-item and profile batch downloads, with progress display, retries, SQLite deduplication, and browser fallback support. 抖音批量下载工具去水印支持视频、图集、合集、音乐(原声)。项目地址: https://gitcode.com/GitHub_Trending/do/douyin-downloader创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考