feat: v2.8.0 无头运行器、考试自动交卷、改为退避重试不跳课

新增无头运行能力,解决 Linux 无图形化服务器上无法常驻的问题;同时改掉
"遇到考试课/无进展课就跳过"的策略,改为在同门课上退避重试。

- runner/:自己起无头 Chromium,用 CDP 把构建产物注入页面主世界(等价
  @grant none),不装插件、不需要桌面环境或 Xvfb;含浏览器探测与启动参数、
  持久化 profile、陈旧 SingletonLock 清理、优雅退出、日志轮转、启动预检
- runner.config.mjs / start-headless.cmd:通用配置 + Windows 一键入口;
  凭据只走 YUN_XUE_TANG_USR / YUN_XUE_TANG_PWD 环境变量
- src/exam.js:含考试章节的课程自动进考试 → 开始/继续 → 空卷提交 → 确定,
  交卷后靠平台记账推进课程;maxExamTries 限制同门课交卷次数,防不记账时死循环
- 去掉跳过与黑名单:没学完就退避重试(30s 起翻倍,最长 5 分钟),
  同门课超过 maxCourseRetries 次才停整轮并提示,替代原 maxConsecutiveFailures
- 每完成一门都重新拉列表接口取平台实时状态再选下一门,避免用陈旧队列
- 学习进度改存 sessionStorage(yun-xue-tang-run-state-v3),整页跳转/刷新可续;
  运行开关不跨会话,浏览器重启后必须显式开跑
- dev/:新增 real-cdp / real-run / real-test / real-e2e 实跑脚本与 check.mjs
  统一静态检查(JS 22 + 批处理 2),替代逐文件 node --check
- docs/evidence/headless-linux-evidence.txt + 实跑截图,README 补无头部署章节
This commit is contained in:
void committed 2026-10-25 23:04:40 +08:00
1 parent 8193326b70
commit ae117222df
47 files changed
+6198 -837

No files matched your search

+271
View File
@@ -0,0 +1,271 @@
// 浏览器探测与启动:Linux 无图形化服务器(含 root / 容器)与 Windows 无人值守都适配。
//
// 关键点:
// - 无显示环境下必须 --headless=new(或回退 --headless),否则 Chrome 起不来;
// - 以 root 运行时 Chromium 拒绝启动,必须 --no-sandbox;
// - 容器里 /dev/shm 通常只有 64MB,必须 --disable-dev-shm-usage,否则标签页会崩;
// - 服务器上没有 GPU/音频设备,关闭相关初始化可减少噪声与卡顿;
// - user-data-dir 固定到可配置目录(持久化 cookie),并清理上次被强杀留下的残局:
// Linux 的 SingletonLock 符号链接、Windows 的 lockfile,以及两个平台上
// 「被任务管理器/ kill -9 杀掉后留下来占着端口的孤儿浏览器进程」。
//
// 平台相关的判断(有无图形会话、沙箱参数、进程树怎么收)全部在 platform.mjs,
// 这里只负责「探测路径 + 拼参数 + 启动 + 等端口就绪」。
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { spawn } from 'node:child_process';
import { httpJson, sleep } from './cdp.mjs';
import {
isWindows, isLinux, isRunningAsRoot, safetyArgs, killTree, killProfileOrphans,
} from './platform.mjs';
// 由本模块统一再导出,老的调用方(dev/real-cdp.mjs 等)不用改
// (hasDisplay / safetyArgs 只在这里转发,本模块内部不直接用)
export {
hasDisplay, safetyArgs, isRunningAsRoot, platformName, noDisplayReason,
} from './platform.mjs';
// 各平台常见的 Chrome / Chromium 安装位置(按优先级)
const CANDIDATES = [
process.env.YUN_XUE_TANG_CHROME_BIN,
process.env.YUN_XUE_TANG_CHROME,
// Linux(发行版包管理器)
'/usr/bin/google-chrome',
'/usr/bin/google-chrome-stable',
'/usr/bin/chromium',
'/usr/bin/chromium-browser',
'/snap/bin/chromium',
'/opt/google/chrome/chrome',
// 常见容器镜像(playwright / puppeteer 预装)
'/root/.cache/ms-playwright/chromium-latest-linux/chrome-linux/chrome',
'/ms-playwright/chromium-*/chrome-linux/chrome',
'/usr/lib/chromium/chromium',
'/usr/lib/chromium-browser/chromium-browser',
// Windows:Chrome / Edge / Chromium 的常见安装位置(含按用户安装的 LOCALAPPDATA)
process.env.LOCALAPPDATA && path.join(process.env.LOCALAPPDATA, 'Google/Chrome/Application/chrome.exe'),
process.env.LOCALAPPDATA && path.join(process.env.LOCALAPPDATA, 'Chromium/Application/chrome.exe'),
process.env.PROGRAMFILES && path.join(process.env.PROGRAMFILES, 'Google/Chrome/Application/chrome.exe'),
process.env['PROGRAMFILES(X86)'] && path.join(process.env['PROGRAMFILES(X86)'], 'Google/Chrome/Application/chrome.exe'),
process.env.PROGRAMFILES && path.join(process.env.PROGRAMFILES, 'Microsoft/Edge/Application/msedge.exe'),
process.env['PROGRAMFILES(X86)'] && path.join(process.env['PROGRAMFILES(X86)'], 'Microsoft/Edge/Application/msedge.exe'),
'C:/Program Files/Google/Chrome/Application/chrome.exe',
'C:/Program Files (x86)/Google/Chrome/Application/chrome.exe',
'C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe',
'C:/Program Files/Microsoft/Edge/Application/msedge.exe',
// macOS
'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
'/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
'/Applications/Chromium.app/Contents/MacOS/Chromium',
].filter(Boolean);
// 运行时的可执行名(Windows 上文件名带 .exe,Linux 上可执行名不带扩展名)
const EXE_RE = /(^|[\/])(chrome|chromium|msedge)(\.exe)?$/i;
function isFile(p) {
try { return fs.statSync(p).isFile(); } catch (e) { return false; }
}
// 通配符路径(例如 playwright 缓存目录带哈希后缀)逐个展开
function expandGlob(patterns) {
const out = [];
const seen = new Set();
const walk = function (dir, depth) {
if (depth > 6) return;
let entries;
try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (e) { return; }
for (const en of entries) {
const full = path.join(dir, en.name);
if (en.isFile() && EXE_RE.test(full) && isFile(full)) {
if (!seen.has(full)) { seen.add(full); out.push(full); }
} else if (en.isDirectory()) {
walk(full, depth + 1);
}
}
};
for (const p of patterns) {
if (p.indexOf('*') < 0) continue;
const base = p.slice(0, p.indexOf('*'));
walk(base.endsWith('/') ? base : base.slice(0, base.lastIndexOf('/') + 1), 0);
}
return out;
}
export function resolveBrowser() {
const globbed = expandGlob(CANDIDATES);
const all = CANDIDATES.concat(globbed);
for (const p of all) {
if (p && p.indexOf('*') < 0 && isFile(p)) return p;
}
return null;
}
export function listCandidatePaths() {
return CANDIDATES.concat(expandGlob(CANDIDATES));
}
// 上次进程被强杀(kill -9 / 任务管理器「结束任务」)时,profile 目录会留下锁文件,
// Chrome 可能因此拒绝启动或一直弹「配置文件正在使用中」。
//
// 两套锁的名字不同:
// POSIX SingletonLock / SingletonSocket / SingletonCookie,lock 是指向 hostname-pid 的符号链接,
// 目标 pid 不存在即视为陈旧(还存在就说明真有浏览器在跑,不能动)。
// Windows 用普通的空文件 lockfile;Windows 上没法从文件反查 pid,
// 所以由调用方先用 killProfileOrphans() 把残留进程收掉,再清文件。
export function cleanStaleSingleton(profileDir) {
const names = isWindows
? ['lockfile', 'SingletonLock', 'SingletonSocket', 'SingletonCookie']
: ['SingletonLock', 'SingletonSocket', 'SingletonCookie'];
for (const name of names) {
const p = path.join(profileDir, name);
let st;
try { st = fs.lstatSync(p); } catch (e) { continue; }
try {
if (st.isSymbolicLink()) {
const target = fs.readlinkSync(p);
const m = /-(\d+)$/.exec(target);
const pid = m ? Number(m[1]) : 0;
let alive = false;
if (pid > 0) {
try { process.kill(pid, 0); alive = true; } catch (e) { alive = false; }
}
if (alive) continue; // 真的有浏览器在跑,别动
fs.unlinkSync(p);
} else {
fs.unlinkSync(p);
}
} catch (e) { /* ignore */ }
}
}
export function buildArgs({
profileDir, port, headless, noSandbox, windowSize = '1360,940', extraArgs = [],
}) {
const args = [
`--remote-debugging-port=${port}`,
`--remote-debugging-address=127.0.0.1`,
`--user-data-dir=${profileDir}`,
'--no-first-run',
'--no-default-browser-check',
'--disable-sync',
'--disable-background-networking',
'--disable-component-update',
'--disable-features=Translate,MediaRouter,OptimizationHints',
// 后台标签页/最小化时不要把定时器与视频节流,否则「持续听课」测不准
'--disable-background-timer-throttling',
'--disable-renderer-backgrounding',
'--disable-backgrounding-occluded-windows',
// 无人值守必须自己能起播,不能等用户手势
'--autoplay-policy=no-user-gesture-required',
'--mute-audio',
// 服务器 / 无人值守机器上没有可用的 GPU 加速,关掉能少一类崩溃与噪声
'--disable-gpu',
'--window-size=' + windowSize,
];
// 下面这些都是 POSIX 概念,Windows 上不认(加了也无害,但没必要)
if (!isWindows) {
args.push(
// 容器里 /dev/shm 通常只有 64MB,不加会随机崩标签页
'--disable-dev-shm-usage',
// 部分发行版 / 容器里 zygote 起不来
'--no-zygote',
);
}
if (noSandbox && (isLinux || isRunningAsRoot())) {
// Linux 服务器常见两种情况都需要它:以 root 运行、容器内 namespace 受限
args.push('--no-sandbox', '--disable-setuid-sandbox');
}
// 本平台额外需要的稳定性参数(Windows:不弹崩溃恢复气泡,免得无人值守时卡在等点击)
args.push(...safetyArgs());
if (headless) args.push('--headless=new', '--hide-scrollbars');
// 去重:上面手写的 Linux 参数和 safetyArgs() 有重叠,同一个开关重复传给 Chrome 没意义
// (但 --disable-features 这类「后面的覆盖前面的」要注意,所以按首次出现保留并合并)
return [...new Set(args)].concat(extraArgs, ['about:blank']);
}
// 启动浏览器并等 CDP 端口就绪。失败时回退到老的无头开关(老版本 Chromium 不认 --headless=new)。
export async function launchBrowser(opts) {
const {
binary, profileDir, port, headless = true, noSandbox = true,
extraArgs = [], timeoutMs = 45000, log = () => {},
} = opts;
fs.mkdirSync(profileDir, { recursive: true });
// 先收残留进程(被强杀后留下的孤儿会一直占着 CDP 端口),再清锁文件
const orphans = await killProfileOrphans(profileDir, { log });
if (orphans) log('[浏览器] 已清理 ' + orphans + ' 个残留浏览器进程');
cleanStaleSingleton(profileDir);
// headless=true 先试 --headless=new,起不来再试 --headless
const modes = headless ? [true, 'old'] : [false];
let lastErr = null;
for (const mode of modes) {
const isNew = mode === true || mode === 'old';
let args = buildArgs({
profileDir, port, headless: isNew, noSandbox, extraArgs,
});
if (mode === 'old') {
args = args.map((a) => (a === '--headless=new' ? '--headless' : a));
}
log('[浏览器] 启动:' + binary + ' ' + (isNew ? (mode === 'old' ? '(headless 旧模式)' : '(headless=new)') : '(有界面)'));
// windowsHide:Windows 上不加会闪一个黑色控制台窗口,无人值守时必须隐藏
const child = spawn(binary, args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
let stderrTail = '';
child.stderr.on('data', (b) => { stderrTail = (stderrTail + String(b)).slice(-4000); });
child.stdout.on('data', () => {});
let exited = false;
child.on('exit', (code, signal) => {
exited = true;
if (code !== 0 && code !== null) log('[浏览器] 进程退出 code=' + code + ' signal=' + signal);
});
const started = Date.now();
let version = null;
while (Date.now() - started < timeoutMs) {
if (exited) break;
try {
const v = await httpJson(`http://127.0.0.1:${port}/json/version`);
if (v && v.webSocketDebuggerUrl) { version = v; break; }
} catch (e) { /* 还没起来 */ }
await sleep(300);
}
if (version) {
return {
child, version, args,
headless: isNew,
kill: function () {
// 跨平台收进程树(Windows 走 TerminateProcess + taskkill /T,POSIX 走 SIGTERM→SIGKILL)
return killTree(child, { log });
},
};
}
await killTree(child, { log, timeoutMs: 3000 });
await sleep(500);
lastErr = new Error('CDP 端口未就绪(' + port + ')');
if (stderrTail.trim()) {
lastErr.message += '\n浏览器 stderr(尾部):\n' + stderrTail.trim().split('\n').slice(-12).join('\n');
}
// 只有 headless 才需要回退,非 headless 直接报错
if (!headless) break;
}
throw lastErr || new Error('浏览器启动失败');
}
// 建议的持久化 profile 目录:默认放项目内的 .run-profile(可用 YUN_XUE_TANG_PROFILE_DIR 覆盖)
export function defaultProfileDir(root) {
if (process.env.YUN_XUE_TANG_PROFILE_DIR) return path.resolve(process.env.YUN_XUE_TANG_PROFILE_DIR);
return path.join(root, '.run-profile');
}
export function tmpProfileDir(prefix = 'yun-xue-tang-headless-') {
return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
}