tt-help-cli-ycl 1.4.85 → 1.4.87

package/src/watchdog/agent.js

@@ -20,7 +20,7 @@ import {
   isGlobalInstall,
   startUpgradeChecker,
 } from "./upgrader.js";
-import { writeFileSync, existsSync, readFileSync } from "fs";
+import { writeFileSync, existsSync, readFileSync, openSync } from "fs";
 import { spawn } from "child_process";
 import { join, dirname } from "path";
 import { homedir, tmpdir } from "os";
@@ -30,6 +30,47 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const homeDir = homedir() || process.env.HOME || process.env.USERPROFILE || "";
 const TT_HELP_CONFIG = join(homeDir, ".tt-help.json");
 
+// ── 业务日志错误统计 → 触发节点切换 ──
+// 识别采集程序日志里已有的错误分类标签（explore 等已打标），连续错误达标则切换出口节点
+const NETWORK_ERROR_PATTERNS = [
+  "CDN限流",
+  "网络异常",
+  "net::",
+  "ERR_CONNECTION",
+  "ECONN",
+  "ETIMEDOUT",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "ESOCKETRESET",
+  "connection.*refused",
+  "connection.*reset",
+  "Timeout",
+  "被封:",
+];
+const NETWORK_ERROR_RE = new RegExp(NETWORK_ERROR_PATTERNS.join("|"), "i");
+const ERROR_SCAN_INTERVAL_MS = 30_000; // 日志扫描间隔
+const ERROR_TRIGGER_COUNT = 10; // 连续错误阈值
+const ERROR_MIN_MS = 5 * 60 * 1000; // 最小持续时间（时间只做最小值判断）
+const ERROR_BREAK_MS = 120_000; // 两次错误间隔超过则视为连续中断，重置计数
+// 只统计采集类命令，排除 webserver/watchdog 自身
+const COLLECTOR_KEYWORDS = [
+  "explore",
+  "auto",
+  "refresh",
+  "search",
+  "precheck",
+  "recheck",
+  "attach",
+  "scrape",
+  "videos",
+  "comments",
+];
+
+function isCollectorCommand(cmdDef) {
+  const s = `${cmdDef?.command || ""} ${cmdDef?.name || ""}`.toLowerCase();
+  return COLLECTOR_KEYWORDS.some((k) => s.includes(k));
+}
+
 /** 自动发现 daemon.js 路径 */
 function findDaemonPath() {
   // 1. 内部打包路径优先（npm publish 后 src/clash/daemon.js，升级即最新）
@@ -140,9 +181,20 @@ export class WatchdogAgent {
     this._lastCmdCount = -1; // 上次命令数
     // clash daemon 集成
     this.clashDaemon = null; // daemon 子进程引用
+    this._daemonStopping = false; // 主动关闭标记（停止/升级时不再重启）
+    this._daemonRestartCount = 0; // 连续异常退出次数
+    this._daemonRestartBackoffMs = 3000; // 重启退避（3s 起，指数递增，上限 30s）
+    this._daemonRestartTimer = null; // 重启定时器
     this.gracePeriodMs = 120_000; // 启动宽限期 2 分钟
     this.startTime = 0; // 启动时间戳
     this._graceEnded = false; // 宽限期是否已结束
+    // 业务日志错误统计 → 触发节点切换
+    this._errorStates = new Map(); // cmdId -> {consecutive, firstErrorAt, lastErrorAt}
+    this._errorTriggerTimer = null;
+    this._errorTriggerEnabled = false; // 默认不启用（后端下发开启才生效）
+    this._errorTriggerCount = ERROR_TRIGGER_COUNT;
+    this._errorTriggerMinMs = ERROR_MIN_MS;
+    this._errorTriggerBreakMs = ERROR_BREAK_MS;
   }
 
   /**
@@ -164,6 +216,13 @@ export class WatchdogAgent {
     this._setupSignalHandlers();
 
     // 启动 clash daemon（保代理通道，--no-daemon 可关闭）
+    this._daemonStopping = false;
+    if (this._daemonRestartTimer) {
+      clearTimeout(this._daemonRestartTimer);
+      this._daemonRestartTimer = null;
+    }
+    this._daemonRestartCount = 0;
+    this._daemonRestartBackoffMs = 3000;
     if (this.spawnDaemon) this._spawnClashDaemon();
 
     // 首次立即发送心跳
@@ -179,11 +238,16 @@ export class WatchdogAgent {
       this.processManager.checkThresholds();
     }, 5000);
 
-    // 假死检测：每 60s 检查各进程是否有日志输出，超 30 分钟无日志则重启
+    // 假死检测：每 60s 检查各进程是否有日志输出，超 15 分钟无日志则重启
     this.staleTimer = setInterval(() => {
       this.processManager.checkStaleProcesses();
     }, 60000);
 
+    // 业务日志错误统计：连续错误达标则触发节点切换（每 30s）
+    this._errorTriggerTimer = setInterval(() => {
+      this._checkProcessErrors();
+    }, ERROR_SCAN_INTERVAL_MS);
+
     // LLM 日志分析（每 10 分钟调服务端接口）
     this._startLlmAnalyzer();
 
@@ -208,6 +272,10 @@ export class WatchdogAgent {
       clearInterval(this.staleTimer);
       this.staleTimer = null;
     }
+    if (this._errorTriggerTimer) {
+      clearInterval(this._errorTriggerTimer);
+      this._errorTriggerTimer = null;
+    }
     if (this.llmAnalyzerTimer) {
       clearInterval(this.llmAnalyzerTimer);
       this.llmAnalyzerTimer = null;
@@ -216,12 +284,96 @@ export class WatchdogAgent {
       this.upgradeChecker.stop();
       this.upgradeChecker = null;
     }
-    // 停止 clash daemon
+    // 停止 clash daemon（标记主动关闭，exit 时不再自动重启）
+    this._daemonStopping = true;
+    if (this._daemonRestartTimer) {
+      clearTimeout(this._daemonRestartTimer);
+      this._daemonRestartTimer = null;
+    }
     this._killClashDaemon();
     this.processManager.stopAll();
     console.error("[watchdog] 看门狗已停止");
   }
 
+  /** 应用服务端下发的错误触发切换配置（控制启用与参数，默认不启用） */
+  _applyErrorTriggerConfig(cfg) {
+    this._errorTriggerEnabled = !!cfg?.enabled;
+    if (cfg?.triggerCount > 0) this._errorTriggerCount = cfg.triggerCount;
+    if (cfg?.minMinutes > 0)
+      this._errorTriggerMinMs = cfg.minMinutes * 60 * 1000;
+    if (cfg?.breakSeconds > 0)
+      this._errorTriggerBreakMs = cfg.breakSeconds * 1000;
+    console.error(
+      `[watchdog] 错误触发切换: ${this._errorTriggerEnabled ? "已启用" : "已禁用"} (连续${this._errorTriggerCount}次 / 持续${this._errorTriggerMinMs / 60000}min / 中断${this._errorTriggerBreakMs / 1000}s)`,
+    );
+  }
+
+  /**
+   * 扫描各采集进程日志，统计连续网络/限流/封禁类错误，达标则触发 daemon 故障切换。
+   * 触发条件：连续错误 ≥ _errorTriggerCount 且 持续时间 ≥ _errorTriggerMinMs（时间只做最小值判断）
+   */
+  _checkProcessErrors() {
+    if (!this.running || !this._errorTriggerEnabled) return;
+    const now = Date.now();
+    const scanned = this.processManager.scanErrorLogs(NETWORK_ERROR_RE);
+    for (const { cmdId, cmdDef, newErrors } of scanned) {
+      if (!isCollectorCommand(cmdDef)) continue;
+      let st = this._errorStates.get(cmdId) || {
+        consecutive: 0,
+        firstErrorAt: 0,
+        lastErrorAt: 0,
+      };
+      for (const line of newErrors) {
+        // 错误间隔超阈值 → 连续中断，重新计数
+        if (
+          st.lastErrorAt &&
+          now - st.lastErrorAt > this._errorTriggerBreakMs
+        ) {
+          st.consecutive = 0;
+          st.firstErrorAt = now;
+        }
+        st.consecutive++;
+        if (!st.firstErrorAt) st.firstErrorAt = now;
+        st.lastErrorAt = now;
+        // 连续错误达标 且 至少持续了最小时间 → 触发切换
+        if (
+          st.consecutive >= this._errorTriggerCount &&
+          now - st.firstErrorAt >= this._errorTriggerMinMs
+        ) {
+          console.error(
+            `[watchdog] ${cmdId} 连续 ${st.consecutive} 次错误（≥${this._errorTriggerCount}次，持续≥${this._errorTriggerMinMs / 60000}min），触发节点切换`,
+          );
+          this._triggerFailover(cmdId);
+          // 切换后重新计数
+          st = { consecutive: 0, firstErrorAt: 0, lastErrorAt: 0 };
+        }
+      }
+      this._errorStates.set(cmdId, st);
+    }
+    // 无新错误的进程：长时间无错误则重置连续计数
+    for (const [cmdId, st] of this._errorStates) {
+      if (
+        st.consecutive > 0 &&
+        now - st.lastErrorAt > this._errorTriggerBreakMs
+      ) {
+        st.consecutive = 0;
+        st.firstErrorAt = 0;
+        this._errorStates.set(cmdId, st);
+      }
+    }
+  }
+
+  /** 下发 failover 命令给 daemon（候选集切下一个可用节点） */
+  async _triggerFailover(cmdId) {
+    try {
+      const ipc = await import("../clash/ipc.js");
+      ipc.writeCommand({ action: "failover" });
+      console.error(`[watchdog] 已下发 failover 命令 (触发源: ${cmdId})`);
+    } catch (e) {
+      console.error(`[watchdog] 下发 failover 失败: ${e.message}`);
+    }
+  }
+
   /** 构建心跳请求体 */
   _buildHeartbeatBody() {
     const sys = getSystemInfo();
@@ -288,19 +440,23 @@ export class WatchdogAgent {
         }
       }
 
-      // 处理 Clash daemon 命令（写 clash-cmd.json，daemon 轮询拾取）
+      // 处理 Clash daemon 命令（一次写入数组，daemon 轮询整批处理）
       if (Array.isArray(data.clashCommands) && data.clashCommands.length > 0) {
         const ipc = await import("../clash/ipc.js");
-        for (const cmd of data.clashCommands) {
-          ipc.writeCommand(cmd);
-          console.error(`[watchdog] 下发 Clash 命令: ${JSON.stringify(cmd)}`);
-        }
+        ipc.writeCommand(data.clashCommands);
+        console.error(
+          `[watchdog] 下发 Clash 命令: ${JSON.stringify(data.clashCommands)}`,
+        );
       }
 
       // 服务端下发的客户端配置（远程修改 ~/.tt-help.json）
       if (data.clientConfig) {
         applyClientConfig(data.clientConfig);
       }
+      // 服务端下发的错误触发切换配置（默认不启用，后端下发控制）
+      if (data.errorTrigger) {
+        this._applyErrorTriggerConfig(data.errorTrigger);
+      }
 
       // 心跳日志：仅状态变化或每 10 次打印一次
       this._heartbeatSeq++;
@@ -398,7 +554,8 @@ export class WatchdogAgent {
     this.upgradeChecker = startUpgradeChecker({
       onUpdateAvailable: async ({ current, latest }) => {
         console.error(`[upgrade] ${current} → ${latest}`);
-        // 停掉所有子进程与 clash daemon，避免新旧并存
+        // 升级流程：先标记 daemon 主动关闭（避免 kill 后被崩溃自愈重新拉起旧版），再停业务与 daemon
+        this._daemonStopping = true;
         this.processManager.stopAll();
         this._killClashDaemon();
 
@@ -412,7 +569,11 @@ export class WatchdogAgent {
           this._restartSelf();
           return;
         }
-        console.error(`[upgrade] 失败: ${result.output.substring(0, 200)}`);
+        // 升级失败：恢复 daemon 与业务，保持当前进程运行
+        console.error(
+          `[upgrade] 失败: ${result.output.substring(0, 200)}，恢复运行`,
+        );
+        this._recoverAfterFailedUpgrade();
         await this._sendHeartbeat();
       },
     });
@@ -456,6 +617,10 @@ export class WatchdogAgent {
           `[watchdog] clash daemon 退出 (code=${code}, signal=${signal})`,
         );
         this.clashDaemon = null;
+        // 主动关闭（watchdog 停止/升级自重启）或已停止时不再自动重启
+        if (this._daemonStopping || !this.running || !this.spawnDaemon) return;
+        // 异常退出 → 退避自动重启，防止崩溃循环
+        this._scheduleDaemonRestart(code, signal);
       });
 
       child.on("error", (err) => {
@@ -463,12 +628,50 @@ export class WatchdogAgent {
         this.clashDaemon = null;
       });
 
+      // 运行稳定（60s 未退出）后重置崩溃计数与退避
+      setTimeout(() => {
+        if (this.clashDaemon === child && child.exitCode === null) {
+          this._daemonRestartCount = 0;
+          this._daemonRestartBackoffMs = 3000;
+        }
+      }, 60_000);
+
       this.clashDaemon = child;
     } catch (e) {
       console.error(`[watchdog] clash daemon 启动异常: ${e.message}`);
     }
   }
 
+  /**
+   * daemon 异常退出后的退避自动重启（防崩溃循环）
+   * 连续异常退出超过阈值则停止自动重启，避免无限循环
+   */
+  _scheduleDaemonRestart(code, signal) {
+    this._daemonRestartCount++;
+    if (this._daemonRestartCount > 5) {
+      console.error(
+        `[watchdog] clash daemon 连续异常退出 ${this._daemonRestartCount - 1} 次，停止自动重启（请人工排查）`,
+      );
+      this._daemonRestartCount = 0;
+      this._daemonRestartBackoffMs = 3000;
+      return;
+    }
+    const delay = this._daemonRestartBackoffMs;
+    this._daemonRestartBackoffMs = Math.min(
+      this._daemonRestartBackoffMs * 2,
+      30_000,
+    );
+    console.error(
+      `[watchdog] clash daemon 异常退出，${(delay / 1000).toFixed(1)}s 后自动重启 (第 ${this._daemonRestartCount} 次, code=${code}, signal=${signal})`,
+    );
+    if (this._daemonRestartTimer) clearTimeout(this._daemonRestartTimer);
+    this._daemonRestartTimer = setTimeout(() => {
+      this._daemonRestartTimer = null;
+      if (!this.running || !this.spawnDaemon || this._daemonStopping) return;
+      this._spawnClashDaemon();
+    }, delay);
+  }
+
   /**
    * 停止 clash daemon 子进程
    */
@@ -491,7 +694,8 @@ export class WatchdogAgent {
 
   /**
    * 升级后重启自身进程（加载新代码）
-   * 用 cli.js watchdog 子进程替换当前进程，保证新版本内部 daemon 路径逻辑生效
+   * 用 cli.js watchdog 子进程替换当前进程，保证新版本内部 daemon 路径逻辑生效。
+   * 带存活确认与兜底：新进程确认存活后才退出旧进程；启动失败则回退保持旧进程运行。
    */
   _restartSelf() {
     const cliPath = join(__dirname, "..", "..", "cli.js");
@@ -503,23 +707,88 @@ export class WatchdogAgent {
       "--interval",
       String(Math.max(5, Math.round(this.intervalMs / 1000))),
     );
+
+    // 新进程日志重定向到文件，启动崩溃时有据可查
+    let logFd = undefined;
+    try {
+      const logPath = join(
+        tmpdir(),
+        `tt-help-watchdog-restart-${Date.now()}.log`,
+      );
+      logFd = openSync(logPath, "a");
+      console.error(`[upgrade] 新进程日志: ${logPath}`);
+    } catch {}
+    const out = logFd ?? "ignore";
+
     let child;
     try {
       child = spawn(process.execPath, [cliPath, ...args], {
         detached: true,
-        stdio: "ignore",
+        stdio: ["ignore", out, out],
         windowsHide: true, // Windows 隐藏控制台窗口
       });
-      child.unref();
     } catch (e) {
-      console.error(`[upgrade] 重启自身失败: ${e.message}`);
+      console.error(`[upgrade] 重启自身失败: ${e.message}，保持旧进程运行`);
+      this._recoverAfterFailedUpgrade();
       return;
     }
+    // 新进程独立存活（父进程退出不影响）
+    child.unref();
+
+    // 存活确认：轮询新进程是否正常存活，确认后才退出旧进程
+    let exited = false;
+    let exitCode = null;
+    let exitSignal = null;
+    child.once("exit", (c, s) => {
+      exited = true;
+      exitCode = c;
+      exitSignal = s;
+    });
+
     console.error(
-      `[upgrade] 新版 watchdog 已启动 (pid=${child.pid})，当前进程退出`,
+      `[upgrade] 新版 watchdog 已启动 (pid=${child.pid})，等待存活确认...`,
     );
-    this.stop();
-    setTimeout(() => process.exit(0), 500);
+    let attempts = 0;
+    const confirm = () => {
+      attempts++;
+      if (exited) {
+        console.error(
+          `[upgrade] 新版 watchdog 启动后即退出 (code=${exitCode}, signal=${exitSignal})，回退保持旧进程`,
+        );
+        this._recoverAfterFailedUpgrade();
+        return;
+      }
+      try {
+        process.kill(child.pid, 0); // 抛错说明进程已不存在
+      } catch {
+        console.error(
+          `[upgrade] 新版 watchdog 进程不存在 (pid=${child.pid})，回退保持旧进程`,
+        );
+        this._recoverAfterFailedUpgrade();
+        return;
+      }
+      if (attempts >= 6) {
+        console.error(`[upgrade] 新版 watchdog 存活确认，旧进程退出`);
+        this.stop();
+        setTimeout(() => process.exit(0), 500);
+        return;
+      }
+      setTimeout(confirm, 1000);
+    };
+    setTimeout(confirm, 1000);
+  }
+
+  /**
+   * 升级/重启失败后的回退恢复：重新拉起 daemon 并同步业务进程
+   */
+  _recoverAfterFailedUpgrade() {
+    this._daemonStopping = false;
+    if (this.spawnDaemon && !this.clashDaemon) {
+      console.error(`[upgrade] 恢复 clash daemon...`);
+      this._spawnClashDaemon();
+    }
+    console.error(`[upgrade] 恢复业务进程（等待心跳同步命令）...`);
+    this._sendHeartbeat().catch(() => {});
   }
 
   /**

package/src/watchdog/process-manager.js

@@ -22,7 +22,7 @@ const MAX_RESTART = 3;
 const MAX_LOG_LINES = 500; // 每个进程最多保留的日志行数
 const IS_WIN = process.platform === "win32";
 const SPAWN_STAGGER_MS = 30000; // 批量启动时每个进程间隔 30 秒，避免抢网络
-const STALE_LOG_TIMEOUT_MS = 30 * 60 * 1000; // 30 分钟无日志输出视为假死
+const STALE_LOG_TIMEOUT_MS = 15 * 60 * 1000; // 15 分钟无日志输出视为假死
 
 // 从命令行中提取 CDP 端口列表（解析 --base-port 和 --port-count）
 function extractCdpPorts(cmdLine) {
@@ -377,6 +377,28 @@ export class ProcessManager extends EventEmitter {
     return result;
   }
 
+  /**
+   * 增量扫描各进程日志中的错误行（只读，不清空日志，与 LLM 分析互不影响）
+   * 用 _errSeen 偏移记录每个进程已扫描过的日志行数，只返回新增的错误行
+   * @param {RegExp} pattern - 错误匹配正则
+   * @returns {Array<{cmdId:string, cmdDef:object, newErrors:string[]}>} 本轮新增的错误日志
+   */
+  scanErrorLogs(pattern) {
+    const result = [];
+    for (const [cmdId, info] of this.processes) {
+      if (info.stopped || !info.logs || info.logs.length === 0) continue;
+      // 日志可能被 LLM 分析清空过，偏移需收敛到当前长度
+      const seen = Math.min(info._errSeen || 0, info.logs.length);
+      const newLines = info.logs.slice(seen);
+      info._errSeen = info.logs.length;
+      if (!newLines.length) continue;
+      const hits = newLines.filter((l) => pattern.test(l));
+      if (hits.length)
+        result.push({ cmdId, cmdDef: info.cmdDef, newErrors: hits });
+    }
+    return result;
+  }
+
   /**
    * 获取所有进程的日志快照（供 LLM 分析）
    * @returns {Array<{cmdId:string, logs:string[], uptimeSeconds:number, restartCount:number}>}

package/src/watchdog/upgrader.js

@@ -9,11 +9,45 @@ import { exec } from "child_process";
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
 import { dirname, join } from "path";
+import { homedir } from "os";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_PATH = join(__dirname, "..", "..", "package.json");
 const PACKAGE = "tt-help-cli-ycl";
 const REGISTRY = "https://registry.npmjs.org";
+const homeDir = homedir() || process.env.HOME || process.env.USERPROFILE || "";
+const TT_HELP_CONFIG = join(homeDir, ".tt-help.json");
+
+/**
+ * 升级检测源：TT_HELP_REGISTRY 环境变量 > ~/.tt-help.json 的 npmRegistry > 官方 npmjs.org
+ * 注意：检测源应与本机 npm install 使用的 registry 保持一致（默认 npm 自身配置）
+ */
+function getRegistry() {
+  const trim = (s) => String(s).replace(/\/+$/, "");
+  if (process.env.TT_HELP_REGISTRY) return trim(process.env.TT_HELP_REGISTRY);
+  try {
+    const cfg = JSON.parse(readFileSync(TT_HELP_CONFIG, "utf-8"));
+    if (cfg.npmRegistry) return trim(cfg.npmRegistry);
+  } catch {}
+  return REGISTRY;
+}
+
+/** 语义化版本比较：a<b → -1, a>b → 1, a==b → 0（避免字符串比较漏掉 1.4.9→1.4.10 这类升级） */
+export function compareVersions(a, b) {
+  const pa = String(a)
+    .split(".")
+    .map((n) => parseInt(n, 10) || 0);
+  const pb = String(b)
+    .split(".")
+    .map((n) => parseInt(n, 10) || 0);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
 
 /** 从 package.json 读取当前版本 */
 export function getVersion() {
@@ -38,7 +72,7 @@ export function isGlobalInstall() {
 export async function checkForUpdates() {
   const current = getVersion();
   try {
-    const resp = await fetch(`${REGISTRY}/${PACKAGE}/latest`, {
+    const resp = await fetch(`${getRegistry()}/${PACKAGE}/latest`, {
       signal: AbortSignal.timeout(15_000),
     });
     if (!resp.ok)
@@ -52,7 +86,10 @@ export async function checkForUpdates() {
     return {
       current,
       latest,
-      hasUpdate: latest !== "?" && current !== "unknown" && latest !== current,
+      hasUpdate:
+        latest !== "?" &&
+        current !== "unknown" &&
+        compareVersions(latest, current) > 0,
     };
   } catch (e) {
     return { current, latest: "?", hasUpdate: false, error: e.message };

package/src/webserver/server.mjs

@@ -88,6 +88,7 @@ let consecutiveErrors = 0;
 const MAX_CONSECUTIVE_ERRORS = 10;
 let warmTimer = null;
 let lastWarmTime = 0;
+let healthTimer = null; // 每 10 分钟健康心跳日志（始终输出，防假死检测误判重启）
 // 滑动窗口错误率追踪（用于 /health 上报，不触发重启）
 let recentTotal = 0;
 let recentErrors = 0;
@@ -192,6 +193,33 @@ function stopWarmTimer() {
   }
 }
 
+// ---- 健康心跳日志（每 10 分钟一行，始终输出，不依赖 --log） ----
+// 目的：无 --log 时 webserver 正常无错误会长时间静默，
+//       若被看门狗 ProcessManager 管理，15 分钟无日志会被假死检测误判重启。
+const HEALTH_LOG_INTERVAL_MS = 10 * 60 * 1000;
+
+function logHealth() {
+  const scraperState = scraperInstance && !scraperClosing ? "运行中" : "未就绪";
+  const windowRate =
+    recentTotal > 0 ? Math.round((recentErrors / recentTotal) * 100) : 0;
+  console.error(
+    `[webserver] 健康: scraper=${scraperState} | 连续错误=${consecutiveErrors}/${MAX_CONSECUTIVE_ERRORS} | 近1min=${recentErrors}/${recentTotal} (${windowRate}%)`,
+  );
+}
+
+function startHealthTimer() {
+  if (healthTimer) return;
+  healthTimer = setInterval(logHealth, HEALTH_LOG_INTERVAL_MS);
+  healthTimer.unref?.();
+}
+
+function stopHealthTimer() {
+  if (healthTimer) {
+    clearInterval(healthTimer);
+    healthTimer = null;
+  }
+}
+
 // ---- API 处理器 ----
 
 const AVAILABLE_APIS = [
@@ -579,6 +607,9 @@ export async function startWebserver(
     console.error(`[webserver] server error: ${err.message}`);
   });
 
+  // 启动健康心跳日志（每 10 分钟一行，防假死误判）
+  startHealthTimer();
+
   return new Promise((resolve, reject) => {
     server.listen(port, () => {
       const localIP = getLocalIP();
@@ -608,6 +639,7 @@ export async function closeServer(server) {
 
 export async function closeScraper() {
   stopWarmTimer();
+  stopHealthTimer();
   if (scraperInstance && !scraperClosing) {
     scraperClosing = true;
     await scraperInstance.close();