云学堂助手 · 无头运行(Linux 无图形化服务器)证据 ================================================== 一、需求 - 用户诉求:「支持无头模式运行在linux无图形化服务器上」。 - 澄清后的范围:新增无头运行器 + 部署说明;常驻方式为手动前台跑(tmux/nohup, 不做 systemd / Docker);持久化 profile,掉登录时用环境变量账号自动重登。 二、方案 新增 `runner/`,不装 Tampermonkey、不装桌面环境、不需要 Xvfb: | 文件 | 作用 | | --- | --- | | runner/headless.mjs | 入口(约 90 行):解析参数 → 预检 → 交给 supervisor | | runner/config.mjs | 命令行参数与环境变量(--max / YUN_XUE_TANG_* 集中在此) | | runner/preflight.mjs | 启动前检查:产物、Node 版本、凭据、浏览器、调试端口 | | runner/log.mjs | 终端 + 文件日志(5MB 轮转) | | runner/stop.mjs | SIGINT / SIGTERM 优雅退出(注册式收尾) | | runner/browser.mjs | 浏览器探测(含 Linux/容器常见路径)、启动参数、陈旧 SingletonLock 清理 | | runner/cdp.mjs | 极简 CDP 客户端(Node 22+ 原生 WebSocket + fetch,无第三方依赖) | | runner/page.mjs | 注入后要调用的页面 JS 表达式 + page.evalJS/json/tryEval | | runner/session.mjs | 单次会话:起浏览器 → 注入 → 自动重登 → 起批量 → 监控 → 收尾 | | runner/selfcheck.mjs | --check 的只读环境自检 | | runner/supervisor.mjs | 崩溃重启循环与退出码 | 依赖方向是单向的:headless → supervisor → session → page/selfcheck → cdp,无循环引用。 按需求不打包:node runner/headless.mjs 直接跑多文件 ESM,部署时整个 runner/ 目录一起带走。 改脚本内部 API(window.__yunXueTangAuto 上的方法)时只需要改 runner/page.mjs。 注入方式与 Tampermonkey 等价:用 `Runtime.evaluate` 把构建产物源码注入页面主世界 (脚本 `@grant none`,不需要沙箱隔离),因此每次整页跳转(新 document)都要重新注入, 运行器用 1.5 秒的看护循环检测 `window.__yunXueTangAuto` 是否存在并补注入。 三、Linux 无图形化环境的三个必踩坑(与代码对应) 1) 没有 DISPLAY:有界面模式直接报 `Missing X server or $DISPLAY` 并退出。 - `runner/browser.mjs:hasDisplay()` 判 `DISPLAY` / `WAYLAND_DISPLAY`; - `runner/headless.mjs` 里 `VISIBLE = WANT_VISIBLE && hasDisplay()`, 即**即使传了 `--visible` 也会被强制无头并打警告**; - `dev/tests/real-cdp.mjs:forceHeadless()` 让三个真机测试脚本同样自动无头。 2) root 运行:Chromium 拒绝启动(`Running as root without --no-sandbox is not supported`)。 - `safetyArgs()` 在 `process.getuid()===0` 时补 `--no-sandbox --disable-setuid-sandbox --disable-gpu`; - `buildArgs()` 在 Linux 上恒加 `--no-sandbox --disable-setuid-sandbox`。 3) 容器 /dev/shm 只有 64MB:标签页会莫名崩溃(`Target closed`)。 - Linux 上恒加 `--disable-dev-shm-usage`。 另外补的稳定性参数:`--no-zygote`、`--disable-gpu`、`--mute-audio`、 `--autoplay-policy=no-user-gesture-required`(无人值守必须能自己起播)、 `--disable-background-timer-throttling` / `--disable-renderer-backgrounding` / `--disable-backgrounding-occluded-windows`(后台标签页不节流,否则计时会停)。 实测(在 Windows 上把 process.platform 覆盖成 linux、getuid 覆盖成 0 验证分支取值): safetyArgs() root ["--disable-dev-shm-usage","--no-sandbox","--disable-setuid-sandbox","--disable-gpu"] hasDisplay() 无 DISPLAY false hasDisplay() 有 DISPLAY true 关键参数(root 无头) ["--autoplay-policy=no-user-gesture-required","--mute-audio","--disable-dev-shm-usage", "--disable-gpu","--no-zygote","--no-sandbox","--disable-setuid-sandbox","--headless=new"] 有界面+关沙箱 [] ← 非 Linux 不注入任何沙箱参数,保留本机 Chrome 沙箱 陈旧的 `SingletonLock`(上次被 kill -9 留下的符号链接指向已不存在的 pid)会被清理, 活跃的锁保留;清理后普通文件形式的 `SingletonCookie` 也一并删除(实测:lock=false, cookie=false)。 四、可观测能力与容错 - 持久化:profile 固定到 `./.run-profile`(`YUN_XUE_TANG_PROFILE_DIR` 可改),cookie / localStorage 都在里面; 删掉该目录 = 重置登录态 + 进度缓存。 - 自动重登:看护循环每 1.5 秒读一次 `isLoginPage()`,是登录页就填账号密码 + 勾协议 + 点登录; 20 秒限速、连续 5 次失败则退出码 3(多半是密码错或站点要验证码)。 - 崩溃自愈:CDP 断线 / 90 秒读不到脚本状态 → 抛错 → 外层等 15s、30s… 最多 120s 后重建浏览器, 进度由页面 localStorage(`yun-xue-tang-batch-v2`)接续。 - 无进展保护:课程/课时/进度/视频任一有变化即重置计时,连续 30 分钟(`YUN_XUE_TANG_IDLE_RESTART_MINUTES`) 没变化则判定卡死退出。 - 编解码自检:`--check` 会探测 `video/mp4; codecs="avc1.42E01E"`;运行中若 `video.error.code >= 3` 立刻告警「这个 Chromium 不带 H.264/AAC」。 - 优雅退出:SIGINT/SIGTERM → 页面内 `pauseAllMedia()` + `S.running=false` + `save()` → 关浏览器。 - 日志:终端 + `./run-logs/headless.log`,超 5MB 轮转成 `.1`。 - 端口占用:启动前先探 `/json/version`,被占时直接提示 `pkill -f "remote-debugging-port=9336"` 或换 `--port`(实测提示正确,exit 2)。 五、实跑验证(真实站点 kfmic.yunxuetang.cn,真实账号) 1) 环境自检 `npm run headless:check`(只读、不登录、不动进度): PASS 页面可访问 → https://kfmic.yunxuetang.cn/login.html PASS 脚本已注入 window.__yunXueTangAuto → object PASS 面板渲染唯一 → {"面板数":1,"可见":true} PASS 脚本版本可读 → "v2.7.0" PASS 视频编解码 H.264 可用 → {"h264":"probably","aac":"probably","vp9":"probably"} 页面识别的路由:other 是否登录页:true 2) 真跑 `node runner/headless.mjs --max 1`(无头、自动登录、真实刷课): 浏览器就绪:Chrome/155.0.8059.85 已注入脚本(第 1 次):https://kfmic.yunxuetang.cn/login.html 登录页:自动登录(第 1 次尝试) 已注入脚本(第 2 次):https://kfmic.yunxuetang.cn/sparring/#/web/drillmate 已注入脚本(第 3 次):https://kfmic.yunxuetang.cn/kng/#/list?... 页面:优先短课程:共 5109 门待学,最短 2 分钟 页面:跳过:如何制定渠道战略(课程包含考试/测验章节) 页面:起点已对齐:第 1 节 视频如何读懂留存曲线? 页面:学习中:视频如何读懂留存曲线? 页面:课程完成: 如何读懂留存曲线? 第 1 门,返回列表选下一门 页面:本次已完成 1 门,已停止。 本次会话结束:已完成 1 门(达到 --max 上限) 用时 2 分 19 秒 本次完成 1 门,累计 1 门 === 运行器退出 === (退出码 0) 3) 崩溃自愈(kill -F 掉浏览器主进程后): 会话异常:CDP 连接断开,重启浏览器 浏览器/连接异常,15 秒后重试(第 1 次) --- 第 2 次尝试 --- 浏览器就绪:Chrome/ ... 登录页:自动登录(第 1 次尝试) ← profile 里的 cookie 过期后被站点踢回登录页,自动重登成功 已注入脚本(第 3 次):...#/list... ← 列表页新 document 重新注入 状态:进入课程(3 分钟):什么是增长黑客 页面:点击开始学习 继续学习 页面:学习中:视频什么是增长黑客? 4) 优雅退出(kill -TERM 运行器进程): [浏览器] 进程退出 code=143 ← 浏览器被 SIGTERM 收掉 残留 chrome 进程数:0 ← 没有孤儿进程 5) 缺凭据时直接拒绝并给原因:`缺少环境变量 YUN_XUE_TANG_USR / YUN_XUE_TANG_PWD。`,退出码 2。 六、回归(改动没有破坏原有链路) - `npm run check`:24 个文件逐个 `node --check` 全通过(新增 runner/*.mjs 与 dev/tests/real-run.mjs 也已纳入)。 - `npm run test:real:headless`(真机只读断言):**24/24 通过,失败 0**。 - `node dev/tests/real-e2e.mjs --headless`:**12/12 通过,失败 0**(真实登录 → 新 document → 列表 16 张卡片 / 322 页)。 - `node dev/tests/real-run.mjs --headless --scan`:**3/3 通过,失败 0**。 七、已知限制 - 无头环境无法完成滑块/拼图类验证码:需要先在有界面模式(本机或 `xvfb-run` + `x11vnc`) 人工登录一次,之后靠持久化 profile 的 cookie 免登录。 - 服务器上如果装的是 `chromium`(Debian/Ubuntu 的 Chromium 包),可能不带 H.264/AAC: 课程视频会一直 0 秒。`--check` 会直接给出提示,改装 `google-chrome-stable` 即可。 - 运行器是前台进程,进程管理交给 tmux / nohup / screen,不内置守护模式(按需求如此)。 八、拆分重构(单文件过长 → 模块化)与回归 ------------------------------------------ 用户反馈「单文件代码太多了,考虑拆分」。runner/headless.mjs 从 626 行拆成 11 个模块、 入口只剩 90 行(结构见第二节表格),**不引入打包步骤**(按用户选择:保持直接 import)。 同时把 package.json 的 check 从「一长串 node --check a && node --check b …」 改成 scripts/check.mjs 自动遍历 runner/、dev/、scripts/ 与 config/ —— 以前新增模块必须手改那行命令, 漏改就会静默不被检查。现在输出:语法检查:20/20 个文件通过。 拆分过程中发现并修掉 3 个真实缺陷(都是原单文件里藏着的): 1) 端口占用检查被自己的 try/catch 吞掉 - preflight 里 fail() 在 try 块内抛出,又被同一个 catch 接住,等于端口占用永不报警; - 而 Chrome 起来后会拒绝启动,外层只是不断重试。现在只捕获探测本身的异常。 - 实测:假 CDP 服务占住 9336 → 退出码 2,三行提示(占用者、pkill 命令、换端口建议)。 2) 连续登录失败不会退出(最严重) - 原代码在看护循环里 throw,但 setInterval 的 catch 把它当「看护循环异常」打印成警告, 主循环永远看不到这个错误:错误凭据下会无限刷日志、永不退出。 - 修法:致命错误寄存到 fatalError + 停掉定时器,主循环抛出;supervisor 据此返回退出码 3。 - 实测(故意错的账号密码):5 次尝试(每次 20 秒限速)→ 会话异常:连续 5 次登录失败:请检查 YUN_XUE_TANG_USR / YUN_XUE_TANG_PWD,… → 退出码 3。 3) 会话抛错时浏览器没收干净 - 异常路径跳过了 disposeSession,浏览器进程残留会占住 CDP 端口,下一轮重启撞端口。 - 修法:session 暴露 disposeActiveSession()(幂等),supervisor 在 catch 里先调用它。 - 实测:退出码 3 之后残留 chrome 进程数 0。 回归(重构后全部重跑,真实站点、真实账号): npm run check 语法检查:20/20 个文件通过(原 12 个,新增 8 个模块) npm run headless:check 5/5 PASS,退出码 0 node runner/headless.mjs --max 1 真实完成 1 门,退出码 0(多次重跑:2 分 16 秒 / 3 分 39 秒) kill 浏览器主进程 会话异常:CDP 连接断开 → 15 秒后第 2 次尝试 → 自动重登 → 继续刷课 SIGTERM 浏览器 code=143,残留 chrome 进程数 0 npm run test:real:headless 24/24 通过 node dev/tests/real-e2e.mjs --headless 12/12 通过 node dev/tests/real-run.mjs --headless --scan 3/3 通过 stop.mjs 的单元核查(一次性脚本,未入库):注册的收尾函数全部执行、已注销的不执行、 重复信号不重复执行、收尾后调用 onExit(0)。 stop.mjs 全部断言通过:{"order":["browser.kill","log.close"],"exited":0,"lines":["收到 SIGTERM,正在收尾…"]} ====================================================================== 九、跨平台适配(追加 Windows / macOS 支持,实测于 Windows) ====================================================================== 背景:无头运行器最初只按「Linux 无图形化服务器」设计,但项目主开发机是 Windows。 实际运行暴露了一批 Windows 专属问题(强杀后残留、锁文件名字不同、SIGTERM 收不到、 Session 0 没有桌面、spawn 会闪黑框),因此把平台差异从各模块里抽出来集中处理。 9.1 新增 runner/platform.mjs(平台差异唯一出口) isWindows / isLinux / isMac / platformName isRunningAsRoot() getuid()===0 hasDisplay() 有无图形会话;支持 YUN_XUE_TANG_HAS_DISPLAY=0/1 强制覆盖 Linux 看 DISPLAY/WAYLAND_DISPLAY Windows 看 SESSIONNAME(Services = Session 0,无桌面) noDisplayReason() 给日志用的人话原因 safetyArgs() 本平台需要的额外启动参数 Linux: --disable-dev-shm-usage(+ root: --no-sandbox 等) Windows: 不注入 --no-sandbox;只加 --disable-session-crashed-bubble --hide-crash-restore-bubble(避免无人值守时弹窗等人点) killTree(child) 进程树收尾:POSIX SIGTERM→SIGKILL;Windows TerminateProcess + 兜底 taskkill /T /F killProfileOrphans(profileDir) 按 --user-data-dir 找残留浏览器进程并杀掉(自愈) Linux: ps -eo pid=,args= Windows: Get-CimInstance Win32_Process + taskkill portInUseHint(port) 按平台出排查命令 browserInstallHint() / residentHint() 按平台出安装与常驻建议 browser.mjs 转发 platform.mjs 的导出(safetyArgs / hasDisplay / isRunningAsRoot 等), 老的调用方(dev/tests/real-cdp.mjs、dev/tests/real-*.mjs)不需要改 import。 9.2 各模块的改动点 browser.mjs CANDIDATES 补 Windows 用户级安装(LOCALAPPDATA)与 Edge/Chromium 路径, 可执行名匹配改为 EXE_RE(认 .exe); buildArgs 把 --disable-dev-shm-usage / --no-zygote 限定为非 Windows; spawn 加 windowsHide(否则无人值守时闪黑框); kill() 改为 platform.killTree(); cleanStaleSingleton 在 Windows 上额外清 lockfile(普通文件,无法反查 pid, 所以先 killProfileOrphans 再清)。 preflight.mjs 浏览器缺失提示、Node 升级提示、端口排查命令全部按平台出; 端口被占时先 killProfileOrphans 自愈一次,再判断是否真的失败。 stop.mjs 监听 SIGINT + SIGBREAK + SIGHUP(Windows 上 SIGTERM 根本收不到, Ctrl+C 是 SIGINT,Ctrl+Break 是 SIGBREAK,关窗口是 SIGHUP)。 config.mjs VISIBLE = WANT_VISIBLE && hasDisplay(),导出 platformName / noDisplayReason。 supervisor.mjs 启动横幅打平台名;--visible 被忽略时用 noDisplayReason() 说原因。 headless.mjs 注释补 Windows 用法(set / $env:)与代码结构。 dev/tests/real-*.mjs spawn 补 windowsHide: true。 9.3 实测(Windows 11 / Chrome 155.0.8059.85 / Node v24.19.0) 平台判断 hasDisplay() → true(SESSIONNAME=Console) safetyArgs() → ["--disable-session-crashed-bubble", "--hide-crash-restore-bubble"] buildArgs 平台相关参数 → --disable-gpu / --disable-session-crashed-bubble / --hide-crash-restore-bubble / --headless=new (无 --no-sandbox / --disable-dev-shm-usage) 模拟 SESSIONNAME=Services → hasDisplay() false,--visible 被忽略 killTree(进程树收尾) 启动后同 profile chrome 进程数 10 b.kill() 返回用时 206ms kill 后进程数 0 ✔ 无残留 killProfileOrphans(残留自愈)—— 用 detached 造出「父进程退出后仍活着」的浏览器 detached 浏览器进程数 10 端口 9358 可响应 true killProfileOrphans 返回 10 清理后进程数 / 端口 9358 0 / false ✔ 预检自愈(端到端) 先用残留浏览器占住默认端口 9336 端口可响应 true node runner/headless.mjs --check [预检] 已清理 11 个占用本 profile 的残留进程,重新检测端口… PASS 页面可访问 / 脚本已注入 / 面板渲染唯一 / 版本可读 / H.264 可用 退出码 0 ✔ 自愈成功(不再误报退出码 2) Windows 上的信号事实(一次性脚本核查,未入库) process.kill(pid, 'SIGINT') 子进程被直接终止,SIGINT 处理函数不执行 process.kill(pid, 'SIGTERM') 报 ESRCH,不可用 taskkill /pid (不带 /F) 报「无法终止」;必须 /F,而 /F 是 TerminateProcess → 结论:Windows 上跨进程没有优雅信号,只有当前控制台的 Ctrl+C 能触发 SIGINT。 因此 stop.mjs 监听 SIGINT/SIGBREAK/SIGHUP,并把「强杀留下残局」交给 killProfileOrphans 兜底。 真实链路回归(真实站点 kfmic.yunxuetang.cn、真实账号) npm run headless:check 5/5 PASS,退出码 0 node runner/headless.mjs --max 1 已完成 1 门(用时 3 分 9 秒),退出码 0 npm run test:real:headless 24/24 通过 node dev/tests/real-e2e.mjs --headless 12/12 通过 node dev/tests/real-run.mjs --headless --scan 3/3 通过 npm run check(scripts/check.mjs) 24/24 个文件通过 9.4 Windows 额外交付 scripts/start-headless.cmd 一键启动(自动构建 / 检查 Node / 退出码说明 + pause) README「无头运行」一节 改成 Linux / Windows 双栏,补「Windows 常驻三种方式」 与按平台分的「无图形环境常见坑」表 环境变量 YUN_XUE_TANG_HAS_DISPLAY 0/1 强制认定有无图形会话(自动判断不准时用) 9.5 buildArgs 参数去重(Linux 分支在 Windows 上模拟验证) platform.mjs 在模块加载时就用 process.platform 定下了常量,因此模拟 Linux 必须在 import 之前改写(一次性脚本 .run-tmp/linux-sim.mjs,用 Object.defineProperty 覆盖 process.platform='linux'、process.getuid=()=>0、清掉 DISPLAY/WAYLAND_DISPLAY)。 hasDisplay() → false(无 DISPLAY) noDisplayReason() → 当前环境没有图形显示(DISPLAY / WAYLAND_DISPLAY 都为空) safetyArgs() → ["--disable-dev-shm-usage","--no-sandbox", "--disable-setuid-sandbox","--disable-gpu"] buildArgs(去重后) → --disable-gpu / --disable-dev-shm-usage / --no-zygote / --no-sandbox / --disable-setuid-sandbox / --headless=new portInUseHint(9336) → ["ss -lptn \"sport = :9336\"", "pkill -f \"remote-debugging-port=9336\""] 发现并修掉:手写的 Linux 参数与 safetyArgs() 有重叠(--disable-dev-shm-usage / --no-sandbox / --disable-setuid-sandbox 各出现两次),Chrome 收到重复开关没有意义, 改为 [...new Set(args)] 去重后再拼 extraArgs。Windows 侧核查重复项:无。 ====================================================================== 十、Windows 批处理启动脚本的编码陷阱(scripts/start-headless.cmd 报「不是内部或外部命令」) ====================================================================== 10.1 现象 双击 scripts/start-headless.cmd,控制台输出: 'e' 不是内部或外部命令,也不是可运行的程序或批处理文件。 '鍏?npm' 不是内部或外部命令,也不是可运行的程序或批处理文件。 'rofile' 不是内部或外部命令,也不是可运行的程序或批处理文件。 'nner' 不是内部或外部命令,也不是可运行的程序或批处理文件。 '姝e父鏀跺熬' 不是内部或外部命令,也不是可运行的程序或批处理文件。 即:整行被拆成几段、中文乱码(UTF-8 字节被按 GBK 解释)、还丢了字符。 10.2 根因(两个独立问题叠加) a) 行尾是裸 LF。cmd.exe 逐行读取批处理,但它只认 CRLF;只有 LF 时会漏掉换行, 把上一行的尾部当成下一行命令的一部分 —— 于是出现 'e' / 'rofile' / 'nner' 这种「从单词中间开始」的片段。 b) 文件里有非 ASCII 字符(中文)。cmd.exe 按当前代码页(中文 Windows 是 936/GBK) 逐字节读,UTF-8 编码的中文占 3 字节,被当成 3 个 GBK 字符,行读取指针随之错位, 后续命令也跟着被截断 —— 于是出现 '鍏?npm'(UTF-8 的「关」被读成 GBK 乱码, 连后面的空格和 npm 一起粘进来)和 '姝e父鏀跺熬'(「正常收尾」的乱码)。 对照实验(同一台机器,同一目录): CRLF + chcp 65001 + 中文 → 输出「中文提示 CRLF」「second line」 ✔ 正常 LF + chcp 65001 + 中文 → '01' 不是内部或外部命令 / '文提示' 不是内部或外部命令 ✘ 错位 所以 chcp 65001 并不能救 UTF-8 中文 —— 偏移发生在解析阶段,而不是显示阶段。 GBK 编码 + 不 chcp 的方案虽然能执行,但显示是乱码(终端代码页不匹配), 且文件必须随系统区域设置改动,不适合入库。 10.3 采用方案:批处理只用 ASCII,中文交给 Node 输出 scripts/start-headless.cmd 与 scripts/start-dev.cmd 全部改写为纯 ASCII + CRLF: - 注释里写明「本文件必须保持纯 ASCII」及原因,避免以后有人手改回去; - 所有面向用户的提示(构建中 / 启动中 / 退出码含义 / 缺 Node)改用英文短句 (如 [build] / [run] / [exit] / [error]),中文提示由 Node 侧日志输出; - 文件仍保留 chcp 65001,这样 Node 输出的 UTF-8 中文在控制台正常显示。 验证: file scripts/start-headless.cmd → DOS batch file, ASCII text, with CRLF line terminators 非 ASCII 字节数 → 0(scripts/start-dev.cmd 同样为 0,原为 50) cmd /c scripts\start-headless.cmd --check → 5/5 PASS,退出码 0 cmd /c scripts\start-headless.cmd(错误凭据)→ 连续 5 次登录失败 → [exit] code 3 → pause 10.4 防回归:scripts/check.mjs 增加批处理检查 `npm run check` 原来只跑 node --check,对 .cmd 完全无感知(所以这个 bug 是双击才发现)。 现在 scripts/check.mjs 同时遍历 *.cmd / *.bat 并断言两件事: 1. 不含任何 >0x7F 的字节(报错时给出首次出现的偏移与上下文片段); 2. LF 与 CRLF 数量相等(存在裸 LF 就报错)。 自测(临时文件,验证完即删): 造一个 UTF-8 + LF 的坏文件 → FAIL,两条都被指出 造一个 ASCII + CRLF 的对照文件 → PASS 现在输出:静态检查:23/23 个文件通过(JS 21 · 批处理 2) 同时把这两条写进 README 的「无图形环境常见的坑」表(新增一行,症状列直接给出 '鍏?npm' / '01' / 'rofile' 这三个典型报错原文,方便以后按报错搜索)。