tt-help-cli-ycl 1.4.139 → 1.4.140

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tt-help-cli-ycl",
-  "version": "1.4.139",
+  "version": "1.4.140",
   "description": "TikTok user & video data scraper - extract ttSeller, verified, locationCreated from HTML source",
   "type": "module",
   "bin": {

package/scripts/test-webserver-error-classify.mjs

@@ -0,0 +1,379 @@
+// 回归测试：webserver 错误分类（IP 风控 → CDN 自愈，重启竞态 → 不计连续错误）
+// 运行：node scripts/test-webserver-error-classify.mjs
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import {
+  TikTokScraper,
+  classifyGotoError,
+} from "../src/lib/tiktok-scraper.mjs";
+import {
+  classifyError,
+  switchClashNode,
+  settleCooldownWindow,
+} from "../src/webserver/server.mjs";
+import { CDNBlockedError, TikTokStatusError } from "../src/lib/parse-ssr.mjs";
+import { configure, resetConfig } from "../src/clash/api.js";
+import { parseNetstatListeningPids } from "../src/lib/browser/cdp.js";
+import { findListeningPids, killListeningOnPort } from "../src/lib/port.js";
+
+let passed = 0;
+let failed = 0;
+const checks = [];
+function check(name, fn) {
+  checks.push({ name, fn });
+}
+
+async function runAll() {
+  for (const { name, fn } of checks) {
+    try {
+      await fn();
+      passed++;
+      console.error(`PASS ${name}`);
+    } catch (e) {
+      failed++;
+      console.error(`FAIL ${name}: ${e.message}`);
+    }
+  }
+  console.error(`\n结果: ${passed} 通过, ${failed} 失败`);
+  process.exitCode = failed > 0 ? 1 : 0;
+}
+
+// ---- classifyGotoError ----
+check("goto 非2xx + status=403 → CDNBlockedError 带状态码", () => {
+  const err = classifyGotoError(
+    "page.goto: net::ERR_HTTP_RESPONSE_CODE_FAILURE at view-source:https://www.tiktok.com/@x/video/1",
+    403,
+  );
+  assert.ok(err instanceof CDNBlockedError);
+  assert.equal(err.name, "CDNBlockedError");
+  assert.match(err.message, /status=403/);
+});
+
+check("goto 非2xx + status=429 → CDNBlockedError", () => {
+  const err = classifyGotoError(
+    "page.goto: net::ERR_HTTP_RESPONSE_CODE_FAILURE at view-source:https://x",
+    429,
+  );
+  assert.ok(err instanceof CDNBlockedError);
+  assert.match(err.message, /status=429/);
+});
+
+check("goto 非2xx + status=null → CDNBlockedError 标 unknown", () => {
+  const err = classifyGotoError(
+    "page.goto: net::ERR_HTTP_RESPONSE_CODE_FAILURE at view-source:https://x",
+    null,
+  );
+  assert.ok(err instanceof CDNBlockedError);
+  assert.match(err.message, /status=unknown/);
+});
+
+check("goto 非2xx + status=404 → TikTokStatusError（业务结果）", () => {
+  const err = classifyGotoError(
+    "page.goto: net::ERR_HTTP_RESPONSE_CODE_FAILURE at view-source:https://www.tiktok.com/@x/video/9",
+    404,
+  );
+  assert.ok(err instanceof TikTokStatusError);
+  assert.equal(err.statusCode, 404);
+});
+
+check("goto ERR_ABORTED → null（原样冒泡）", () => {
+  assert.equal(
+    classifyGotoError(
+      "page.goto: net::ERR_ABORTED at view-source:https://x",
+      null,
+    ),
+    null,
+  );
+});
+
+check("goto frame detached → null（原样冒泡）", () => {
+  assert.equal(
+    classifyGotoError("page.goto: net::ERR_ABORTED; maybe frame was detached?"),
+    null,
+  );
+});
+
+check("goto 非字符串 → null", () => {
+  assert.equal(classifyGotoError(undefined), null);
+  assert.equal(classifyGotoError(null), null);
+});
+
+// ---- classifyError ----
+check("CDNBlockedError → cdn/503/retryable/不计连续错误", () => {
+  const c = classifyError(new CDNBlockedError("CDN限流"));
+  assert.deepEqual(c, {
+    kind: "cdn",
+    status: 503,
+    retryable: true,
+    countConsecutive: false,
+  });
+});
+
+check("goto 包装的 CDNBlockedError → cdn", () => {
+  const err = classifyGotoError(
+    "page.goto: net::ERR_HTTP_RESPONSE_CODE_FAILURE at view-source:https://www.tiktok.com/@x/video/2",
+    403,
+  );
+  const c = classifyError(err);
+  assert.equal(c.kind, "cdn");
+  assert.equal(c.status, 503);
+});
+
+check("TikTokStatusError(404) → business/200/不计连续错误", () => {
+  const c = classifyError(new TikTokStatusError(404, "TikTok HTTP 404"));
+  assert.deepEqual(c, {
+    kind: "business",
+    status: 200,
+    retryable: false,
+    countConsecutive: false,
+    statusCode: 404,
+  });
+});
+
+check("Server is shutting down → shutdown/503/不计", () => {
+  const c = classifyError(new Error("Server is shutting down"));
+  assert.deepEqual(c, {
+    kind: "shutdown",
+    status: 503,
+    retryable: true,
+    countConsecutive: false,
+  });
+});
+
+check("Timeout → timeout/504/计", () => {
+  const c = classifyError(new Error("page.goto: Timeout 15000ms exceeded"));
+  assert.deepEqual(c, {
+    kind: "timeout",
+    status: 504,
+    retryable: true,
+    countConsecutive: true,
+  });
+});
+
+check("重启竞态产物 → browser/503/不计", () => {
+  const cases = [
+    "browserContext.newPage: Target page, context or browser has been closed",
+    "page.goto: net::ERR_ABORTED at view-source:https://www.tiktok.com/@x/video/3",
+    "page.goto: net::ERR_ABORTED; maybe frame was detached?",
+    "Cannot read properties of null (reading 'newPage')",
+    "Execution context was destroyed, most likely because of a navigation.",
+    "Protocol error (Page.navigate): Target closed.",
+  ];
+  for (const msg of cases) {
+    const c = classifyError(new Error(msg));
+    assert.equal(c.kind, "browser", msg);
+    assert.equal(c.status, 503, msg);
+    assert.equal(c.retryable, true, msg);
+    assert.equal(c.countConsecutive, false, msg);
+  }
+});
+
+check("未知错误 → unknown/500/计", () => {
+  const c = classifyError(new Error("some random parse failure"));
+  assert.deepEqual(c, {
+    kind: "unknown",
+    status: 500,
+    retryable: false,
+    countConsecutive: true,
+  });
+});
+
+// ---- TikTokScraper 关闭标记（重启竞态防护）----
+check("closing=true 时 _ensurePage 抛 Server is shutting down", async () => {
+  const s = new TikTokScraper({ poolSize: 1 });
+  s.closing = true;
+  await assert.rejects(() => s._ensurePage({}), /Server is shutting down/);
+});
+
+check("context=null 时 _ensurePage 抛 Server is shutting down", async () => {
+  const s = new TikTokScraper({ poolSize: 1 });
+  s.closing = false;
+  s.context = null;
+  await assert.rejects(() => s._ensurePage({}), /Server is shutting down/);
+});
+
+// ---- switchClashNode（mock Clash API，不碰真实 9097）----
+/** 起一个 mock Clash 控制端，返回处理函数闭包里的状态 */
+function startMockClash(handler) {
+  return new Promise((resolve) => {
+    const server = createServer((req, res) => {
+      const url = new URL(req.url, "http://127.0.0.1");
+      let body = "";
+      req.on("data", (c) => (body += c));
+      req.on("end", () => {
+        const reply = (status, data) => {
+          res.statusCode = status;
+          if (data === undefined) {
+            res.end();
+            return;
+          }
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify(data));
+        };
+        handler(req, url, body ? JSON.parse(body) : null, reply);
+      });
+    });
+    server.listen(0, "127.0.0.1", () => resolve(server));
+  });
+}
+
+check("switchClashNode：选第一个 delay 通过的候选并切换", async () => {
+  let switchedTo = null;
+  const server = await startMockClash((req, url, body, reply) => {
+    if (req.method === "GET" && url.pathname === "/proxies/GLOBAL") {
+      reply(200, { now: "A", all: ["A", "B", "C"] });
+    } else if (req.method === "GET" && url.pathname.endsWith("/delay")) {
+      reply(200, { delay: 120, timeout: false });
+    } else if (req.method === "PUT" && url.pathname === "/proxies/GLOBAL") {
+      switchedTo = body.name;
+      reply(204);
+    } else {
+      reply(404, {});
+    }
+  });
+  const port = server.address().port;
+  configure({ port });
+  try {
+    const picked = await switchClashNode("测试切节点");
+    assert.equal(picked, "B"); // 跳过当前节点 A，选第一个探测通过的 B
+    assert.equal(switchedTo, "B");
+  } finally {
+    resetConfig();
+    await new Promise((r) => server.close(r));
+  }
+});
+
+check("switchClashNode：候选均探测不通 → 抛错", async () => {
+  const server = await startMockClash((req, url, body, reply) => {
+    if (req.method === "GET" && url.pathname === "/proxies/GLOBAL") {
+      reply(200, { now: "A", all: ["A", "B"] });
+    } else if (req.method === "GET" && url.pathname.endsWith("/delay")) {
+      reply(200, { delay: -1, timeout: true });
+    } else {
+      reply(404, {});
+    }
+  });
+  configure({ port: server.address().port });
+  try {
+    await assert.rejects(() => switchClashNode("测试"), /候选均探测不通/);
+  } finally {
+    resetConfig();
+    await new Promise((r) => server.close(r));
+  }
+});
+
+check("switchClashNode：无候选节点（组内只有当前节点）→ 抛错", async () => {
+  const server = await startMockClash((req, url, body, reply) => {
+    if (req.method === "GET" && url.pathname === "/proxies/GLOBAL") {
+      reply(200, { now: "A", all: ["A"] });
+    } else {
+      reply(404, {});
+    }
+  });
+  configure({ port: server.address().port });
+  try {
+    await assert.rejects(() => switchClashNode("测试"), /无候选节点/);
+  } finally {
+    resetConfig();
+    await new Promise((r) => server.close(r));
+  }
+});
+
+// ---- 端口占用清理 ----
+check("parseNetstatListeningPids：精确端口匹配（3000 不误匹配 30001）", () => {
+  const out = [
+    "  TCP    0.0.0.0:3000       0.0.0.0:0              LISTENING       1234",
+    "  TCP    0.0.0.0:30001      0.0.0.0:0              LISTENING       5678",
+    "  TCP    127.0.0.1:3000     0.0.0.0:0              LISTENING       1234",
+    "  TCP    [::]:3000          [::]:0                 LISTENING       4321",
+  ].join("\r\n");
+  assert.deepEqual(parseNetstatListeningPids(out, 3000), ["1234", "4321"]);
+});
+
+check("killListeningOnPort：杀掉占用端口的子进程并可重新监听", async () => {
+  // 先占一个随机端口拿到端口号，再释放
+  const holder = createServer();
+  await new Promise((r) => holder.listen(0, "127.0.0.1", r));
+  const port = holder.address().port;
+  await new Promise((r) => holder.close(r));
+
+  // spawn 独立子进程占住该端口
+  const child = spawn(
+    process.execPath,
+    [
+      "-e",
+      `require("http").createServer((q,s)=>s.end("ok")).listen(${port},"127.0.0.1");setInterval(()=>{},1000);`,
+    ],
+    { stdio: "ignore" },
+  );
+  await new Promise((r) => setTimeout(r, 800)); // 等子进程监听
+
+  // 确认端口确实被占用
+  const before = findListeningPids(port);
+  assert.ok(
+    before.includes(String(child.pid)),
+    `预期子进程 ${child.pid} 在监听 ${port}，实际: ${before.join(",")}`,
+  );
+
+  // 先注册 exit 监听（kill 后进程瞬间退出，后注册会丢失事件）
+  const exitedPromise = new Promise((resolve) => {
+    const t = setTimeout(() => resolve(false), 3000);
+    child.once("exit", () => {
+      clearTimeout(t);
+      resolve(true);
+    });
+  });
+
+  await killListeningOnPort(port);
+
+  const exited = await exitedPromise;
+  assert.equal(exited, true, "子进程应被杀死");
+
+  // 端口应可重新监听
+  const s2 = createServer();
+  await new Promise((r) => s2.listen(port, "127.0.0.1", r));
+  await new Promise((r) => s2.close(r));
+});
+
+// ---- 5 分钟窗口结算（只数限流窗口，成功请求不参与）----
+const WINDOW = 5 * 60 * 1000;
+check("settleCooldownWindow：无窗口 → 不结算原样返回", () => {
+  assert.deepEqual(settleCooldownWindow(0, 0, 1000, WINDOW, 2), {
+    shouldSwitch: false,
+    count: 0,
+    windowStartAt: 0,
+  });
+});
+check("settleCooldownWindow：窗口内 → 不结算原样返回", () => {
+  assert.deepEqual(
+    settleCooldownWindow(1, 1000, 1000 + WINDOW - 1, WINDOW, 2),
+    {
+      shouldSwitch: false,
+      count: 1,
+      windowStartAt: 1000,
+    },
+  );
+});
+check("settleCooldownWindow：超 5 分钟且限流窗口 ≥2 → 切换并重新计数", () => {
+  assert.deepEqual(
+    settleCooldownWindow(2, 1000, 1000 + WINDOW + 1, WINDOW, 2),
+    {
+      shouldSwitch: true,
+      count: 0,
+      windowStartAt: 0,
+    },
+  );
+});
+check("settleCooldownWindow：超 5 分钟但限流窗口 <2 → 重新计算不切换", () => {
+  assert.deepEqual(
+    settleCooldownWindow(1, 1000, 1000 + WINDOW + 1, WINDOW, 2),
+    {
+      shouldSwitch: false,
+      count: 0,
+      windowStartAt: 0,
+    },
+  );
+});
+
+await runAll();

package/src/clash/checker.js

@@ -403,11 +403,18 @@ export function loadHealthyList(country = null) {
     if (!existsSync(_healthyFile)) return _emptyList();
     const d = JSON.parse(readFileSync(_healthyFile, "utf-8"));
     const allNodes = Array.isArray(d.nodes) ? d.nodes : [];
+    const allDelays = d.delays && typeof d.delays === "object" ? d.delays : {};
     const filter = country || CONFIG.nodeCountryFilter;
     const { filtered, excluded } = filterNodesByCountry(allNodes, filter);
+    const delays = {};
+    for (const n of filtered) {
+      const v = allDelays[n];
+      if (typeof v === "number" && v > 0) delays[n] = v;
+    }
     return {
       updated: d.updated || "",
       nodes: filtered,
+      delays,
       totalNodes: allNodes.length,
       excluded,
       countryFilter: filter || null,
@@ -418,11 +425,15 @@ export function loadHealthyList(country = null) {
   return _emptyList();
 }
 
-export function saveHealthyList(nodes) {
+export function saveHealthyList(nodes, delays = {}) {
   try {
     writeFileSync(
       _healthyFile,
-      JSON.stringify({ updated: new Date().toISOString(), nodes }, null, 2),
+      JSON.stringify(
+        { updated: new Date().toISOString(), nodes, delays: delays || {} },
+        null,
+        2,
+      ),
       "utf-8",
     );
   } catch (e) {
@@ -434,6 +445,7 @@ function _emptyList() {
   return {
     updated: "",
     nodes: [],
+    delays: {},
     totalNodes: 0,
     excluded: 0,
     countryFilter: null,

package/src/clash/daemon.js

@@ -552,7 +552,12 @@ export class ClashDaemon {
         country: checker.CONFIG.nodeCountryFilter,
       });
       const elapsed = ((Date.now() - start) / 1000).toFixed(0);
-      checker.saveHealthyList(r.nodes);
+      const delays = {};
+      for (const it of r.results || []) {
+        if (typeof it.delay === "number" && it.delay > 0)
+          delays[it.node] = it.delay;
+      }
+      checker.saveHealthyList(r.nodes, delays);
       // 清理切换历史中已不在候选集的节点，防止 Map 无限增长
       if (c._switchHistory && c._switchHistory.size) {
         const keep = new Set(r.nodes);
@@ -771,6 +776,7 @@ export class ClashDaemon {
       healthyNodesCount: list.nodes.length,
       healthyNodesTotal: list.totalNodes,
       healthyNodes: list.nodes.slice(0, 50),
+      healthyNodeDelays: list.delays || {},
     });
     return base;
   }

package/src/cli/comments.js

@@ -284,10 +284,11 @@ class CdpSessionManager {
     this.browser = await ensureBrowserReady(opts);
     this.page = await this._ensurePage();
     this.lastRecycleAt = Date.now();
-    // 端口切换时重置运行计时
-    if (oldPort !== undefined && oldPort !== this.port) {
-      this.sessionStartTime = Date.now();
-    }
+    // 重建会话后重置运行计时（无论是否换端口）。
+    // 旧逻辑只在换端口时重置，而默认 switchPortOnRecycle=false，
+    // 导致 48min 定时轮换触发后计时不归零，之后每次内存采样（30s）
+    // 都再次满足超时条件 → 每 30s 反复重建会话（“一直在切换”）
+    this.sessionStartTime = Date.now();
   }
 
   /** 内存检查 + 定时轮换 + 按需回收（每 30s 最多采样一次） */

package/src/lib/args.js

@@ -414,8 +414,8 @@ function parseWebserverArgs(args) {
   let webserverLog = false;
   // 默认安全限速：3 请求/秒。限速突发容量自动跟随 pool-size（见下方返回）。
   let webserverRate = 3;
-  // CDN 限流冷却时长（秒），默认 180（3 分钟）
-  let webserverCooldown = 180;
+  // CDN 限流冷却时长（秒），默认 100（2 次重启 + 切节点流程节奏）
+  let webserverCooldown = 100;
   // 默认汇报到 ~/.tt-help.json 中配置的 server 地址
   let webserverNotify = defaultServer;
 
@@ -438,10 +438,10 @@ function parseWebserverArgs(args) {
     } else if (arg === "--cooldown") {
       const next = args[i + 1];
       if (next && !next.startsWith("--")) {
-        webserverCooldown = parseInt(next) || 180;
+        webserverCooldown = parseInt(next) || 100;
         i++;
       } else {
-        webserverCooldown = 180; // 缺省回退到默认值
+        webserverCooldown = 100; // 缺省回退到默认值
       }
     } else if (arg === "--log") {
       webserverLog = true;

package/src/lib/constants.js

@@ -291,7 +291,7 @@ const HELP_TEXT = [
   "      --proxy <地址>         HTTP 代理（如 127.0.0.1:7897）",
   "      --rate <请求/秒>       对 TikTok 的全局请求速率限制，默认 3（0=不限制）",
   "                            （限速突发容量自动跟随 --pool-size，无需单独设置）",
-  "      --cooldown <秒>        CDN 限流自动冷却时长：首次限流后冷却，到期仍限流则单次重启，默认 180",
+  "      --cooldown <秒>        CDN 限流自动冷却时长，默认 100（冷却→探活→最多2次重启→自动切 Clash 节点）",
   "      --log                   显示 API 成功日志（默认不显示，错误日志始终输出）",
   "      --notify [地址]         验证码通知，默认 http://117.71.53.99:17301",
   "    API:",

package/src/lib/parse-ssr.mjs

@@ -1,5 +1,5 @@
 /**
- * CDN 限流错误（Akamai Access Denied）
+ * CDN 限流错误（Akamai Access Denied / HTTP 非 2xx 风控）
  */
 export class CDNBlockedError extends Error {
   constructor(message = "CDN限流 (Access Denied)", reference) {
@@ -9,6 +9,18 @@ export class CDNBlockedError extends Error {
   }
 }
 
+/**
+ * TikTok 明确 HTTP 状态码错误（goto 阶段被非 2xx 拒绝，如 404 视频/用户不存在）。
+ * 与 CDNBlockedError 区分：业务结果而非风控，webserver 返回 200 + statusCode。
+ */
+export class TikTokStatusError extends Error {
+  constructor(statusCode, message) {
+    super(message || `TikTok HTTP ${statusCode}`);
+    this.name = "TikTokStatusError";
+    this.statusCode = statusCode;
+  }
+}
+
 /**
  * 检测 HTML 是否为 CDN Access Denied
  * 返回 { isBlocked: true, reference: "xxx" } 或 null

package/src/lib/port.js

@@ -0,0 +1,72 @@
+/**
+ * 端口占用清理：webserver 启动前检查目标端口，若被占用直接杀掉占用进程。
+ * Windows 走 netstat -ano + taskkill；macOS/Linux 走 lsof + SIGKILL。
+ */
+import { execSync } from "node:child_process";
+import { parseNetstatListeningPids } from "./browser/cdp.js";
+
+const KILL_WAIT_MS = 500; // 杀完等端口释放（Windows 进程退出有延迟，立即 listen 仍可能 EADDRINUSE）
+
+function delay(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/** 返回监听指定端口的 PID 列表（字符串数组） */
+export function findListeningPids(port) {
+  if (process.platform === "win32") {
+    try {
+      const out = execSync("netstat -ano -p TCP", {
+        encoding: "utf-8",
+        timeout: 5000,
+        windowsHide: true,
+      });
+      return parseNetstatListeningPids(out, port);
+    } catch (e) {
+      console.error(`[port] netstat 查询失败: ${e.message}`);
+      return [];
+    }
+  }
+  // POSIX：lsof 找不到监听时退出码非 0 且无输出，属正常情况
+  try {
+    const out = execSync(`lsof -nP -iTCP:${port} -sTCP:LISTEN -t`, {
+      encoding: "utf-8",
+      timeout: 5000,
+    });
+    return out
+      .split(/\r?\n/)
+      .map((s) => s.trim())
+      .filter((s) => /^\d+$/.test(s));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 杀掉监听指定端口的全部进程（排除自身 PID），供启动前清理端口占用。
+ * 不区分进程类型：谁占谁死（用户拍板）。
+ */
+export async function killListeningOnPort(port) {
+  const pids = findListeningPids(port).filter((p) => p !== String(process.pid));
+  if (!pids.length) return;
+  console.error(
+    `[webserver] 端口 ${port} 被占用，直接清理进程 PID: ${pids.join(", ")}`,
+  );
+  for (const pid of pids) {
+    try {
+      if (process.platform === "win32") {
+        execSync(`taskkill /F /T /PID ${pid}`, {
+          encoding: "buffer",
+          timeout: 15000,
+          windowsHide: true,
+        });
+      } else {
+        process.kill(parseInt(pid, 10), "SIGKILL");
+      }
+      console.error(`[webserver] 已杀 PID ${pid}`);
+    } catch (e) {
+      console.error(`[webserver] 杀 PID ${pid} 失败: ${e.message}`);
+    }
+  }
+  // 等待端口释放，避免立即 listen 仍 EADDRINUSE
+  await delay(KILL_WAIT_MS);
+}