@wenbin_wb/dsh-bridge 2.10.12 → 2.10.14

package/lib/cloudflared-manager.mjs

@@ -1,11 +1,25 @@
-import { spawn, execSync } from 'node:child_process';
-import { createWriteStream, createReadStream, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { spawn, execFileSync } from 'node:child_process';
+import { createWriteStream, createReadStream, existsSync, mkdirSync, readFileSync, statSync, renameSync, writeFileSync } from 'node:fs';
 import { chmod, stat, unlink, rename } from 'node:fs/promises';
 import { homedir, platform, arch } from 'node:os';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import { createHash } from 'node:crypto';
 import { get as httpsGet } from 'node:https';
+import { get as httpGet } from 'node:http';
+
+// 参数化执行外部命令，替代原先的 execSync(`"${path}" --version`) 字符串拼接
+// （CodeQL js/shell-command-constructed-from-input）。execFileSync 不经过 shell，
+// 参数以数组传递，路径里的引号 / $( ) / 反引号不再具备注入语义。
+//
+// Windows 例外：.cmd / .bat 无法被 execFileSync 直接执行（Node 要求经 shell），
+// 官方 cloudflared 在 Windows 是 .exe 走参数化路径，只有测试注入的假二进制是
+// .cmd，故按扩展名决定是否需要 shell。macOS / Linux 恒为 false。
+const IS_WINDOWS = process.platform === 'win32';
+function execBinSync(bin, args, options) {
+  const needsShell = IS_WINDOWS && /\.(cmd|bat)$/i.test(bin);
+  return execFileSync(bin, args, { ...options, shell: needsShell });
+}
 
 const CLOUDFLARED_VERSION = '2024.10.0';
 const DOWNLOAD_TIMEOUT = 5 * 60 * 1000; // 5 分钟
@@ -15,6 +29,47 @@ const RETRY_BASE_MS = 5 * 1000; // 自愈退避起点 5s
 const RETRY_MAX_MS = 5 * 60 * 1000; // 自愈退避封顶 5min
 const DEFAULT_MAX_RETRIES = 12; // 连续失败超过该次数转为 error，不再无限重试
 
+// ── 运行时健康探针 ────────────────────────────────────────────────────────
+// 事故背景：cloudflared 与 Cloudflare 边缘的连接全部掉光后进程仍存活（"半死/假死"），
+// 既不退出也不报错，因此只监听 exit 的旧自愈逻辑永远不会触发，隧道会静默失效
+// （现象：公网 530 + 正文 error code: 1033，持续 2 天无人发现）。
+//
+// 关键约束（一手源码 cloudflared 2024.10.0 `tunnelstate/conntracker.go`）：/ready 的
+// readyConnections 取自 CountActiveConns()，而 Disconnected / Reconnecting /
+// RegisteringTunnel / Unregistering 全部把 IsConnected 置 false —— 即
+// **正常重连期间 /ready 同样是 503**。因此单次 503 无法区分"连接器假死"与
+// "网络暂时全断、cloudflared 正按自身退避重连"。唯一能区分的是"持续多久"，
+// 故采用两级升级，且强制重建永不进入终态（见 _scheduleRestart 的 terminal 选项）。
+const HEALTH_PROBE_INTERVAL_MS = 30 * 1000; // 探活间隔
+const HEALTH_PROBE_TIMEOUT_MS = 5 * 1000; // 单次探活总时限（远程调用防失控）
+const HEALTH_DEGRADED_THRESHOLD = 3; // 连续失败达此数 → 面板可见降级（约 90s 发现）
+const HEALTH_RESTART_THRESHOLD = 10; // 连续失败达此数 → 终止进程强制重建（约 5min）
+
+// ── cloudflared 输出落盘 ──────────────────────────────────────────────────
+// 事故时 journal 里查不到任何 cloudflared 日志，导致事后无法定位断连时间点与原因。
+export const CLOUDFLARED_LOG_NAME = 'cloudflared.log';
+const CLOUDFLARED_LOG_MAX_BYTES = 5 * 1024 * 1024; // 超限轮转为 .1（覆盖旧的）
+
+// 从 cloudflared 自报日志中解析 metrics 服务地址（运行时健康探针的唯一入口）。
+// 真实输出形如：INF Starting metrics server on 127.0.0.1:41143/metrics
+// 解析不到 → 显式告警并跳过探活（绝不静默降级，也绝不因探测不到而误杀进程）。
+//
+// 必须在这里就把非法地址拦掉：node:http 的 get() 对畸形 URL 会**同步抛错**
+// （ERR_INVALID_URL），异常会穿透探针 Promise 造成未处理 rejection ——
+// Node 默认 unhandled-rejections=throw 会直接结束整个 DSH 主进程，
+// 也就是说"本该保护服务的探针"反而会把服务干掉。端口必须落在 1..65535。
+export function parseMetricsAddress(text) {
+  if (!text) return null;
+  const m = /Starting metrics server on (\S+?)\/metrics/.exec(text);
+  if (!m) return null;
+  const addr = m[1];
+  const parts = /^([A-Za-z0-9._-]+|\[[0-9A-Fa-f:]+\]):(\d{1,5})$/.exec(addr);
+  if (!parts) return null;
+  const port = Number(parts[2]);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return null;
+  return addr;
+}
+
 // ── 确定性失败特征：cloudflared 因配置/用法错误退出（非网络瞬态）─────────
 // 这类失败重试无意义，识别后直接置 error 让用户看到明确原因，而不是
 // 误判成"意外退出"退避重连 N 次（issue #35 作者建议）。
@@ -116,7 +171,7 @@ function findSystemCloudflared() {
       if (bin.includes('/') || bin.includes('\\')) {
         if (!existsSync(bin)) continue;
       }
-      execSync(`"${bin}" --version`, { stdio: 'ignore', timeout: 3000 });
+      execBinSync(bin, ['--version'], { stdio: 'ignore', timeout: 3000 });
       return bin;
     } catch {}
   }
@@ -138,10 +193,26 @@ export class CloudflaredManager {
    * @param {number} [opts.handshakeTimeoutMs=90000] 等待隧道就绪的握手超时（测试可注入小值）。
    * @param {object} [opts.spawnOptions] 透传给 child_process.spawn 的额外选项（测试注入用，
    *   如 Windows 下需 shell:true 才能运行 .cmd mock；生产不传）。
+   * @param {number} [opts.healthProbeIntervalMs=30000] 就绪后运行时探活间隔。
+   * @param {number} [opts.healthProbeTimeoutMs=5000] 单次探活总时限。
+   * @param {number} [opts.healthDegradedThreshold=3] 连续失败达此数即在面板上显示降级
+   *   （默认约 90s——这是"发现故障"的时点）。
+   * @param {number} [opts.healthRestartThreshold=10] 连续失败达此数才终止进程强制重建
+   *   （默认约 5min）。必须显著大于 degraded 阈值：/ready 无法区分"假死"与
+   *   "正在自行重连"，只有持续时长能区分，过早重建会误杀本可自愈的连接器。
+   * @param {string|null} [opts.logFilePath=null] cloudflared stdout/stderr 落盘路径；
+   *   null 表示不落盘（默认）。生产由调用方显式传入（见 lib/index.js），
+   *   避免库的默认行为在单测里往真实运维日志目录写测试内容。
+   * @param {number} [opts.logMaxBytes=5242880] 单文件超限后轮转为 `<logFilePath>.1`。
    */
   constructor({ port, home, token, hostname, onStateChange, logger,
     binaryPath, retryPolicy, noAutoupdate = true, binaryVersion = CLOUDFLARED_VERSION,
-    handshakeTimeoutMs = HANDSHAKE_TIMEOUT_MS, spawnOptions = null }) {
+    handshakeTimeoutMs = HANDSHAKE_TIMEOUT_MS, spawnOptions = null,
+    healthProbeIntervalMs = HEALTH_PROBE_INTERVAL_MS,
+    healthProbeTimeoutMs = HEALTH_PROBE_TIMEOUT_MS,
+    healthDegradedThreshold = HEALTH_DEGRADED_THRESHOLD,
+    healthRestartThreshold = HEALTH_RESTART_THRESHOLD,
+    logFilePath = null, logMaxBytes = CLOUDFLARED_LOG_MAX_BYTES }) {
     this.port = port;
     this.home = home || join(homedir(), '.dsh-bridge');
     this.token = token ? String(token).trim() : null;
@@ -170,18 +241,42 @@ export class CloudflaredManager {
     // 测试注入的 spawn 选项（如 Windows 的 shell）；生产为 null 不影响默认行为
     this._spawnOptions = spawnOptions || null;
 
+    // 运行时健康探针参数（测试可注入小值）
+    this.healthProbeIntervalMs = healthProbeIntervalMs;
+    this.healthProbeTimeoutMs = healthProbeTimeoutMs;
+    this.healthDegradedThreshold = healthDegradedThreshold;
+    this.healthRestartThreshold = healthRestartThreshold;
+    this.logFilePath = logFilePath || null;
+    this.logMaxBytes = logMaxBytes;
+
     this.process = null;
     this.url = null;
     this.binaryPath = null;
     this._stopped = false;
     this._retryTimer = null;
     this._restartCount = 0; // 连续启动失败/意外退出次数，就绪后清零
+
+    this._metricsAddress = null; // 本次 spawn 的 cloudflared metrics 地址（探活入口）
+    this._metricsParseTail = ''; // metrics 日志行的跨 chunk 拼接缓冲
+    this._probeTimer = null;
+    this._probeFailures = 0;
+    this._probeInFlight = false; // 防重叠探活堆积
+    this._probeCount = 0; // 已完成的探活次数（供测试断言探针确实在跑）
+    this._probeLogFailures = 0; // 探针日志通道自身抛错的次数（供自查是否丢过日志）
+    this._spawnSeq = 0; // spawn 代数：探活结果据此作废，避免算到新进程头上
+    this._healthRecovering = false; // 健康探针触发的重建链路中（此期间不允许终态）
+    this._readyState = null; // 最近一次 ready 状态，供探活恢复后回写
+    this._logStream = null;
+    this._logBytesWritten = 0;
+    this._redactCarry = ''; // 跨 chunk 的脱敏残留（防 Token 被切分而漏网）
   }
 
   // 异步启动，立即返回——调用方不需要 await
   start() {
     this._stopped = false;
     this._restartCount = 0;
+    this._healthRecovering = false;
+    this._probeInFlight = false;
     if (this._retryTimer) {
       clearTimeout(this._retryTimer);
       this._retryTimer = null;
@@ -206,6 +301,9 @@ export class CloudflaredManager {
   }
 
   // 退避自愈调度：唯一入口在"启动失败"与"就绪后意外退出"。stop()/超限 终止。
+  // _healthRecovering 期间（健康探针判定假死后触发的整条重建链路，含重启后握手失败）
+  // 永不进入终态——必须覆盖整条链路而不只是那次 kill：重启时网络往往仍不通，
+  // 新进程握手失败仍会走这里，若在此处转 error 就把"可自愈的断网"变成人工故障。
   _scheduleRestart(reason) {
     if (this._stopped) return; // 用户已停止，绝不复活
     if (this._retryTimer) return; // 已在倒计时中，避免叠加调度
@@ -215,15 +313,25 @@ export class CloudflaredManager {
     }
     this._restartCount++;
     if (this._restartCount > this.retry.maxRetries) {
-      this._setState('error', `${reason}（已自动重试 ${this.retry.maxRetries} 次仍失败，请检查网络/Token，或点击「关闭」停止）`);
-      return;
+      if (!this._healthRecovering) {
+        this._setState('error', `${reason}（已自动重试 ${this.retry.maxRetries} 次仍失败，请检查网络/Token，或点击「关闭」停止）`);
+        return;
+      }
+      // 健康探针触发的重建链路永不进入终态：长时断网时 cloudflared 自身也是无限退避
+      // 重连，这里保持同样语义。退避仍随 _restartCount 增长并封顶 maxDelayMs，
+      // 不会退化成高频重启风暴；重新就绪（tryResolve）后该标记自动清除。
     }
     const delay = Math.min(
       this.retry.baseDelayMs * 2 ** (this._restartCount - 1),
       this.retry.maxDelayMs
     );
-    this._setState('reconnecting',
-      `${reason}，${Math.max(1, Math.round(delay / 1000))}s 后自动重连（第 ${this._restartCount}/${this.retry.maxRetries} 次）`);
+    // 文案必须如实：健康重建链路会故意突破 maxRetries 持续重试，
+    // 若沿用"第 N/M 次"会出现"第 9/2 次"这种自相矛盾的提示，反而误导排障。
+    const delayText = delay >= 1000 ? `${Math.round(delay / 1000)}s` : `${delay}ms`;
+    const beyondCap = this._restartCount > this.retry.maxRetries;
+    this._setState('reconnecting', beyondCap
+      ? `${reason}，${delayText} 后继续自动重连（已重试 ${this._restartCount} 次；隧道长时间无法建立，请检查网络与 Token）`
+      : `${reason}，${delayText} 后自动重连（第 ${this._restartCount}/${this.retry.maxRetries} 次）`);
     this._retryTimer = setTimeout(() => {
       this._retryTimer = null;
       this._restartAttempt();
@@ -261,7 +369,7 @@ export class CloudflaredManager {
   // 校验自管理二进制是否匹配期望版本；系统级二进制不校验（尊重用户安装）
   _checkManagedBinaryVersion(binPath) {
     try {
-      const out = execSync(`"${binPath}" --version`, { encoding: 'utf8', timeout: 3000 });
+      const out = execBinSync(binPath, ['--version'], { encoding: 'utf8', timeout: 3000 });
       const ver = parseCloudflaredVersion(out);
       if (!ver) return { ok: false, reason: `无法解析版本输出: ${(out || '').trim().slice(0, 80)}` };
       if (ver !== this.binaryVersion) {
@@ -309,7 +417,7 @@ export class CloudflaredManager {
             if (platform() !== 'win32') {
               await chmod(binPath, 0o755).catch(() => {});
               if (platform() === 'darwin') {
-                try { execSync(`xattr -d com.apple.quarantine "${binPath}"`, { stdio: 'ignore' }); } catch {}
+                try { execBinSync('xattr', ['-d', 'com.apple.quarantine', binPath], { stdio: 'ignore' }); } catch {}
               }
             }
             // 版本钉死校验：cloudflared autoupdate 可能已把钉死的版本自替换成新版，
@@ -345,7 +453,7 @@ export class CloudflaredManager {
 
       if (url.endsWith('.tgz') || url.endsWith('.tar.gz')) {
         try {
-          execSync(`tar -xzf "${tempPath}" -C "${binDir}"`);
+          execBinSync('tar', ['-xzf', tempPath, '-C', binDir]);
           await unlink(tempPath).catch(() => {});
         } catch (tarErr) {
           this.logger?.error('解压 cloudflared 压缩包失败: %s', tarErr.message);
@@ -359,7 +467,7 @@ export class CloudflaredManager {
       if (platform() !== 'win32') {
         await chmod(binPath, 0o755).catch(() => {});
         if (platform() === 'darwin') {
-          try { execSync(`xattr -d com.apple.quarantine "${binPath}"`, { stdio: 'ignore' }); } catch {}
+          try { execBinSync('xattr', ['-d', 'com.apple.quarantine', binPath], { stdio: 'ignore' }); } catch {}
         }
       }
 
@@ -402,6 +510,14 @@ export class CloudflaredManager {
       });
       this.process = proc;
 
+      // 本次 spawn 独立状态：metrics 地址与日志流都随进程生命周期重建；
+      // 代数（_spawnSeq）用于让飞行中的旧探活结果作废——重启后 cloudflared 很
+      // 可能复用同一个 metrics 端口，仅比对地址字符串不足以识别"这是新进程"。
+      this._metricsAddress = null;
+      this._metricsParseTail = '';
+      this._spawnSeq++;
+      this._openLogStream();
+
       let resolved = false;
       let timeoutTimer = null;
       // 累积 stderr 尾部（供 exit 时判断确定性失败：CLI 用法错误 / 配置错误）
@@ -418,8 +534,10 @@ export class CloudflaredManager {
             clearTimeout(timeoutTimer);
             timeoutTimer = null;
           }
-          // 就绪即证明链路可用，连续失败计数清零
+          // 就绪即证明链路可用：连续失败计数清零，并退出"健康重建"模式
           this._restartCount = 0;
+          this._healthRecovering = false;
+          this._startHealthProbe(); // 就绪后才探活：启动阶段的问题由握手超时/exit 负责
           resolve();
         }
       };
@@ -460,10 +578,34 @@ export class CloudflaredManager {
         }
       };
 
-      proc.stdout.on('data', (d) => parseUrl(d.toString()));
+      // metrics 地址必须先于就绪文本被记录：cloudflared 是先起 metrics 服务再注册连接。
+      // 两处稳健性处理：
+      //  1) 该日志行本身也可能被 chunk 切断 → 用滚动缓冲拼接后再匹配；
+      //  2) 地址可能"迟到"（就绪时还没解析到）→ 一旦补上就补启探活，否则安全网永久不启用。
+      const captureMetricsAddress = (text) => {
+        if (this._metricsAddress) return;
+        const buffered = (this._metricsParseTail + text).slice(-512);
+        this._metricsParseTail = buffered;
+        const addr = parseMetricsAddress(buffered);
+        if (!addr) return;
+        this._metricsAddress = addr;
+        if (resolved && !this._stopped && !this._probeTimer) {
+          this._probeLog('info', 'metrics 地址在就绪后才解析到，补启运行时健康探活: %s', addr);
+          this._startHealthProbe();
+        }
+      };
+
+      proc.stdout.on('data', (d) => {
+        const text = d.toString();
+        this._appendCloudflaredLog(text);
+        captureMetricsAddress(text);
+        parseUrl(text);
+      });
       proc.stderr.on('data', (d) => {
         const text = d.toString();
         this.logger?.debug('cloudflared: %s', text.trim());
+        this._appendCloudflaredLog(text);
+        captureMetricsAddress(text);
         stderrTail = (stderrTail + text).slice(-2000); // 只保留尾部 2KB
         parseUrl(text);
         if (text.includes('Registered tunnel') && !resolved) {
@@ -476,6 +618,9 @@ export class CloudflaredManager {
           clearTimeout(timeoutTimer);
           timeoutTimer = null;
         }
+        // 探活定时器与日志流都绑定本次 spawn，退出即回收（自愈会重新建立）
+        this._stopHealthProbe();
+        this._closeLogStream();
         // exit 时"仍是当前进程"才允许清理引用 + 调度自愈。
         // 自愈已 spawn 新进程后，旧进程迟到的 exit 不满足 stillCurrent → 静默，
         // 避免"新进程连接中、旧 exit 又触发一次重启"的竞态（否则会叠出第三进程）。
@@ -491,7 +636,8 @@ export class CloudflaredManager {
           if (isFatalCloudflaredError(stderrTail)) err.fatal = true;
           reject(err);
         } else if (!this._stopped && stillCurrent) {
-          // 就绪后的意外退出（崩溃 / OOM / 误杀 / autoupdate 残留自替换）→ 退避自愈
+          // 就绪后的意外退出（崩溃 / OOM / 误杀 / autoupdate 残留自替换 / 健康探针判定假死）
+          // → 退避自愈。是否允许终态由 _scheduleRestart 依 _healthRecovering 判定。
           this._scheduleRestart(`cloudflared 进程意外退出 (code=${code ?? ''}${signal ? `, ${signal}` : ''})`);
         } else {
           this._setState('idle', '');
@@ -503,6 +649,8 @@ export class CloudflaredManager {
           clearTimeout(timeoutTimer);
           timeoutTimer = null;
         }
+        this._stopHealthProbe();
+        this._closeLogStream();
         if (!resolved) reject(err);
       });
 
@@ -518,7 +666,298 @@ export class CloudflaredManager {
     });
   }
 
-  _setState(phase, detail) {
+  // ── cloudflared 输出落盘（含 Token 脱敏与大小轮转）──────────────────────
+
+  // Token 属敏感凭据，落盘前一律替换；不依赖上游是否会自行脱敏。
+  //
+  // 关键：stderr 的 'data' 事件不保证按行对齐，Token 可能被切分在两个块之间。
+  // 这里用**逐字符扫描**而不是"整块 split 替换"：
+  //   - 任意位置命中完整 Token → 替换为 ***（完整 Token 绝不会明文落盘）；
+  //   - 只在"剩余不足一个 Token 长度、且恰好是 Token 前缀"时才扣住，等下一块补齐。
+  // 不能退化成"扣掉最长的 Token 前缀后缀"这种简化写法：若 Token 自身存在 border
+  // （例如首尾字符相同），完整 Token 结尾处也会被误判成前缀而扣下一截，结果前半段
+  // 与扣下的那截先后写出、在文件里重新拼成完整 Token（已实测的泄漏路径）。
+  _redactToken(text) {
+    if (!this.token) return text;
+    const token = this.token;
+    const L = token.length;
+    const combined = this._redactCarry + text;
+    this._redactCarry = '';
+    let out = '';
+    let i = 0;
+    while (i < combined.length) {
+      if (i + L <= combined.length && combined.startsWith(token, i)) {
+        out += '***';
+        i += L;
+        continue;
+      }
+      if (i + L > combined.length) {
+        const rest = combined.slice(i);
+        if (token.startsWith(rest)) {
+          this._redactCarry = rest; // 可能是被切开的 Token 前半段
+          break;
+        }
+      }
+      out += combined[i];
+      i++;
+    }
+    return out;
+  }
+
+  _openLogStream() {
+    this._closeLogStream(); // 幂等：自愈重启时先关掉上一个进程的流，避免句柄堆积
+    if (!this.logFilePath) return;
+    try {
+      mkdirSync(dirname(this.logFilePath), { recursive: true });
+      // 同步把文件建出来：createWriteStream 是异步 open，若不在此时落地，
+      // 紧随其后的轮转判定会遇到"文件还没存在"而 rename 落空（运行中轮转失效）。
+      writeFileSync(this.logFilePath, '', { flag: 'a' });
+      this._rotateIfOversize();
+      this._logBytesWritten = existsSync(this.logFilePath) ? statSync(this.logFilePath).size : 0;
+    } catch (err) {
+      // 目录创建/建文件/取大小失败：不阻断日志写入，但必须让问题可见
+      this.logger?.warn('cloudflared 日志目录或文件准备失败（本次可能不落盘）: %s', err.message);
+    }
+    try {
+      const stream = createWriteStream(this.logFilePath, { flags: 'a' });
+      stream.on('error', (err) => {
+        // 流已不可写：置空引用，避免后续继续往死流写并重复刷同一条告警
+        this._logStream = null;
+        this.logger?.warn('cloudflared 日志写入失败: %s', err.message);
+      });
+      this._logStream = stream;
+    } catch (err) {
+      this._logStream = null;
+      this.logger?.warn('无法打开 cloudflared 日志文件 %s: %s', this.logFilePath, err.message);
+    }
+  }
+
+  _rotateIfOversize() {
+    if (!this.logFilePath) return;
+    try {
+      if (existsSync(this.logFilePath) && statSync(this.logFilePath).size >= this.logMaxBytes) {
+        renameSync(this.logFilePath, `${this.logFilePath}.1`);
+        this._logBytesWritten = 0;
+      }
+    } catch (err) {
+      this.logger?.warn('cloudflared 日志轮转失败（继续追加写）: %s', err.message);
+    }
+  }
+
+  _closeLogStream() {
+    // 无论流是否可用，carry 都必须清空——否则残留的 Token 片段会污染下一个
+    // 进程的第一行日志（流先报 error 置空、随后 close 早退的场景实测可复现）。
+    const carry = this._redactCarry;
+    this._redactCarry = '';
+    if (!this._logStream) return;
+    // 流关闭时仍扣着的必然是 Token 的一个前缀（见 _redactToken）：以占位符收尾。
+    // 取舍说明：这会牺牲最多 token.length-1 个正常字符的日志保真度，
+    // 但换来"任何 Token 片段都不落盘"。极端情况下宁可少一行尾巴，不可留密钥片段。
+    if (carry) this._logStream.write('***');
+    this._logStream.end();
+    this._logStream = null;
+  }
+
+  _appendCloudflaredLog(text) {
+    if (!this._logStream || !text) return;
+    const out = this._redactToken(text);
+    if (!out) return;
+    const bytes = Buffer.byteLength(out, 'utf8');
+    // 运行中也检查轮转：只在 spawn 时检查会让长寿命进程把日志写爆。
+    // 这里按"本次运行已写入字节数"判定，不依赖 statSync——写流是异步的，
+    // 刚写完就 stat 可能仍是旧大小，会造成轮转判定抖动。
+    if (this._logBytesWritten + bytes >= this.logMaxBytes) {
+      this._closeLogStream();
+      this._renameToRotated();
+      this._openLogStream();
+      if (!this._logStream) return;
+    }
+    this._logStream.write(out);
+    this._logBytesWritten += bytes;
+  }
+
+  _renameToRotated() {
+    if (!this.logFilePath) return;
+    try {
+      if (existsSync(this.logFilePath)) renameSync(this.logFilePath, `${this.logFilePath}.1`);
+    } catch (err) {
+      this.logger?.warn('cloudflared 日志轮转失败（继续追加写）: %s', err.message);
+    }
+    this._logBytesWritten = 0;
+  }
+
+  // ── 运行时健康探针 ──────────────────────────────────────────────────────
+
+  // 就绪后启动探活。metrics 地址解析失败时显式告警并跳过——绝不静默降级，
+  // 也绝不在没有可信探活通道的情况下误杀进程；同时把降级写进面板可见的状态详情，
+  // 否则"整个安全网失效"只会是一行没人看的 journal warning（本次事故的教训）。
+  // 探针专用安全日志：探针跑在定时器与子进程数据回调里，异常没有任何上层接住，
+  // 一旦 logger 自身抛错就会变成未处理 rejection —— Node 默认 unhandled-rejections=throw
+  // 会直接结束宿主进程，即"本该保护服务的探针把服务干掉"。故此处绝不允许抛出。
+  _probeLog(level, msg, ...args) {
+    try {
+      this.logger?.[level]?.(msg, ...args);
+    } catch (logErr) {
+      // 日志通道本身故障：此处再抛就会拖垮宿主进程，故刻意吞掉。
+      // 这不是"静默降级"——要输出的降级信息本身就在这条已损坏的通道上，无处可写；
+      // 且关键降级仍经 _setState → 面板独立可见，不依赖 logger。
+      // 注意：该计数目前只在单测中被读取，生产尚无出口（后续可接入面板/统计），
+      // 因此不要把它当作"生产可自查"的手段。
+      this._probeLogFailures++;
+    }
+  }
+
+  _startHealthProbe() {
+    this._stopHealthProbe();
+    if (!this._metricsAddress) {
+      const detail = `${this._readyState?.detail || '隧道已建立'}；⚠️ 运行时健康探活未启用`
+        + '（未识别到 cloudflared metrics 地址），连接器若静默假死将无法自动发现';
+      this._probeLog('warn', '未从 cloudflared 输出识别到 metrics 地址，本次运行跳过健康探活'
+        + '（连接器若静默假死将无法自动发现，请检查 cloudflared 版本是否变更了 metrics 日志文案）');
+      // record:false —— 这是降级提示，不能污染"纯净的 ready 详情"，
+      // 否则地址迟到后补启探活时将无法把面板文案恢复成正常状态。
+      this._setState('ready', detail, { record: false });
+      return;
+    }
+    // 地址迟到后补启探活：把面板文案恢复为正常的 ready 详情
+    if (this._readyState) this._setState(this._readyState.phase, this._readyState.detail);
+    this._probeTimer = setInterval(() => {
+      // 必须显式 catch：探针里任何逃逸的异常（如畸形 metrics 地址让 http.get 同步抛错）
+      // 都会变成未处理 rejection，而 Node 默认 unhandled-rejections=throw 会直接
+      // 结束整个 DSH 主进程 —— 那正是探针本该防止的"服务整体消失"。
+      // 用 _probeLog 而非 logger 直调：catch 处理器自身也不允许再抛。
+      this._probeOnce().catch((err) => {
+        this._probeLog('warn', '健康探活出现未预期异常（已忽略，不影响连接器运行）: %s', err?.message ?? err);
+      });
+    }, this.healthProbeIntervalMs);
+    this._probeTimer.unref?.(); // 不因探活定时器而阻止进程退出
+  }
+
+  _stopHealthProbe() {
+    if (this._probeTimer) {
+      clearInterval(this._probeTimer);
+      this._probeTimer = null;
+    }
+    this._probeFailures = 0;
+  }
+
+  async _probeOnce() {
+    // 防重叠：单次探活最长 healthProbeTimeoutMs，若上一轮还没结论就不再叠加请求
+    if (this._probeInFlight) return;
+    const addr = this._metricsAddress;
+    if (!addr) return;
+    const seq = this._spawnSeq; // spawn 代数：据此识别"结果属于哪个进程"
+
+    this._probeInFlight = true;
+    let result;
+    try {
+      result = await this._checkTunnelReady(addr);
+    } catch (err) {
+      // 兜底：探针内部任何异常都不得向外逃逸（见 setInterval 处的说明）
+      result = { healthy: false, reason: `探针内部异常: ${err?.message ?? err}` };
+    } finally {
+      this._probeInFlight = false;
+    }
+    this._probeCount++;
+
+    // 探活期间可能已被 stop()、或已自愈重启到新进程 → 结果作废。
+    // 必须比对代数而非地址：重启后 cloudflared 很可能复用同一个 metrics 端口。
+    if (this._stopped || this._spawnSeq !== seq) return;
+
+    if (result.healthy) {
+      if (this._probeFailures >= this.healthDegradedThreshold) {
+        this._probeLog('info', '隧道健康探活已自行恢复（此前连续失败 %d 次）', this._probeFailures);
+        if (this._readyState) this._setState(this._readyState.phase, this._readyState.detail);
+      }
+      this._probeFailures = 0;
+      return;
+    }
+
+    this._probeFailures++;
+    const fails = this._probeFailures;
+    const why = result.reason || '未知原因';
+
+    if (fails === this.healthDegradedThreshold) {
+      // 第一级：可见降级。此时不杀进程——/ready 为 503 也可能只是 cloudflared
+      // 正在按自身退避重连，过早介入反而会把本可自愈的故障变成人工故障。
+      this._probeLog('warn', '隧道健康探活连续 %d 次失败（%s）：连接器可能已无健康边缘连接，'
+        + '转入降级观察，达 %d 次将强制重建', fails, why, this.healthRestartThreshold);
+      this._setState('reconnecting', `健康探活连续 ${fails} 次失败：连接器已无健康边缘连接，`
+        + `正在观察能否自行恢复（${fails}/${this.healthRestartThreshold}）`);
+    } else if (fails < this.healthDegradedThreshold) {
+      this._probeLog('warn', '隧道健康探活失败（第 %d/%d 次）: %s；原因: %s',
+        fails, this.healthRestartThreshold, addr, why);
+    } else {
+      this._probeLog('warn', '隧道健康探活仍失败（第 %d/%d 次）: %s', fails, this.healthRestartThreshold, why);
+    }
+
+    if (fails < this.healthRestartThreshold) return;
+
+    // 第二级：持续不恢复 → 判定假死，强制重建。
+    // 置 _healthRecovering：整条重建链路（含重启后握手失败）都不允许进入终态。
+    this._probeLog('error', '隧道连接器连续 %d 次探活失败（约 %d 分钟）：判定为假死，'
+      + '终止进程以触发重建；该重建不设终态上限，网络恢复后仍会自愈',
+    fails, Math.round(fails * this.healthProbeIntervalMs / 60000));
+    this._stopHealthProbe();
+    this._healthRecovering = true;
+    this._terminateProcess(); // 不自行重启：交给 exit → _scheduleRestart 既有链路
+  }
+
+  // 探活判据：HTTP 200 且 readyConnections > 0（与 cloudflared 官方 /ready 语义一致）。
+  // 返回 { healthy, reason }：reason 会进入 warn 级日志，生产关闭 debug 时也能看到原因。
+  // 注意：http 的 timeout 选项只是 **socket 不活动** 超时，不是总时限——对"持续滴流
+  // 字节"的响应永不触发，因此这里额外加一个绝对截止时间兜底。
+  _checkTunnelReady(addr) {
+    return new Promise((resolve) => {
+      let settled = false;
+      let deadline = null;
+      let req = null;
+      const done = (healthy, reason) => {
+        if (settled) return;
+        settled = true;
+        if (deadline) clearTimeout(deadline);
+        try { req?.destroy(); } catch { /* 已结束的请求 destroy 无害 */ }
+        resolve({ healthy, reason });
+      };
+
+      deadline = setTimeout(() => {
+        done(false, `探活超过总时限 ${this.healthProbeTimeoutMs}ms`);
+      }, this.healthProbeTimeoutMs);
+
+      // httpGet 对畸形 URL 会同步抛错；虽然 parseMetricsAddress 已在入口校验，
+      // 这里再兜一层，确保该函数永不向外抛（否则会变成未处理 rejection 拖垮主进程）。
+      try {
+        req = httpGet(`http://${addr}/ready`, { timeout: this.healthProbeTimeoutMs }, (res) => {
+          let body = '';
+          res.setEncoding('utf8');
+          res.on('data', (chunk) => { body += chunk; });
+          res.on('end', () => {
+            if (res.statusCode !== 200) {
+              done(false, `HTTP ${res.statusCode}`);
+              return;
+            }
+            try {
+              const parsed = JSON.parse(body);
+              const conns = Number(parsed?.readyConnections);
+              done(conns > 0, conns > 0 ? '' : `HTTP 200 但 readyConnections=${parsed?.readyConnections}`);
+            } catch (err) {
+              done(false, `响应无法解析为 JSON: ${err.message}`);
+            }
+          });
+        });
+      } catch (err) {
+        done(false, `无法发起探活请求（地址可能非法）: ${err.message}`);
+        return;
+      }
+      req.on('timeout', () => { done(false, `socket 不活动超过 ${this.healthProbeTimeoutMs}ms`); });
+      req.on('error', (err) => { done(false, `请求失败: ${err.message}`); });
+    });
+  }
+
+  _setState(phase, detail, { record = true } = {}) {
+    // 记住最近一次"纯净"的 ready 状态：探活由降级恢复、或地址迟到后补启探活时
+    // 要回写它，避免面板长期停留在降级文案上（record:false 用于降级提示本身）。
+    if (phase === 'ready' && record) this._readyState = { phase, detail };
     this.onStateChange?.({ phase, detail });
   }
 
@@ -529,6 +968,8 @@ export class CloudflaredManager {
       this._retryTimer = null;
     }
     this._restartCount = 0;
+    this._stopHealthProbe();
+    this._closeLogStream();
     if (this.process) {
       this.logger?.info('停止 cloudflared...');
       this._terminateProcess();