@lancewu602/mihomo-dash 0.0.0-stage → 0.6.1

package/server/src/kernel/lifecycle.js

@@ -0,0 +1,339 @@
+/**
+ * 面板自有内核（面板「内核」页装的那个）的进程生命周期：
+ * detached 拉起 / 探活 / 停止 / 日志。
+ *
+ * 默认只服务状态目录下的内核，启动时读的是同一份 config.yaml —— 所以
+ * external-controller 端口已经有东西在响应时会直接失败，这里提前拦一道并给提示。
+ * 所有函数都返回结果、不自行退出，退出码由调用方（面板端点 / runner 的 `kernel` job）决定。
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { bareVersion, readKernelVersion } from '../kernel/binary.js';
+import { getController, normalizeUrl, readControllerConfig } from '../kernel/client.js';
+import {
+  KERNEL_BIN,
+  KERNEL_LOG_FILE,
+  KERNEL_META_FILE,
+  KERNEL_PID_FILE,
+  detectMihomoDir,
+  ensureCliDir,
+} from '../shared/paths.js';
+import { readTailLines, rotateLogFile } from '../shared/log-file.js';
+
+/** pid 活着没（不发信号判断，避免误杀） */
+export function isAlive(pid) {
+  const n = Number(pid);
+  if (!Number.isInteger(n) || n <= 0) return false;
+  try {
+    process.kill(n, 0);
+    return true;
+  } catch (err) {
+    return err?.code === 'EPERM';
+  }
+}
+
+/** 把内核日志尾部写给调用方（CLI 的 tail 场景），与 daemon 无关 */
+export function tailLogFile({ file, tail = 200, write = (t) => process.stdout.write(t) } = {}) {
+  write(readTailLines(file, { lines: tail }).join('\n'));
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** 启动等待上限：内核要读配置、拉订阅、起监听，给宽一点 */
+const READY_TIMEOUT_MS = 15000;
+const READY_INTERVAL_MS = 300;
+/** 测试用：把这些间隔调小，行为不变（不设则用上面的默认值） */
+const envMs = (name, fallback) => {
+  const value = Number(process.env[name]);
+  return Number.isFinite(value) && value > 0 ? value : fallback;
+};
+const readyIntervalMs = () => envMs('MIHOMO_DASH_READY_INTERVAL_MS', READY_INTERVAL_MS);
+const stopIntervalMs = () => envMs('MIHOMO_DASH_STOP_INTERVAL_MS', 200);
+/** 停止时留给内核优雅退出的时间（它要把 selected 写进 cache.db） */
+const STOP_TIMEOUT_MS = 5000;
+/** 启动失败时回显的日志尾部行数 */
+const FAIL_TAIL = 20;
+
+export function readKernelPid() {
+  try {
+    return Number(fs.readFileSync(KERNEL_PID_FILE, 'utf8').trim()) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+export function readKernelMeta() {
+  try {
+    return JSON.parse(fs.readFileSync(KERNEL_META_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** 面板自有内核是否在跑（pid 文件 + 进程存活） */
+export function ownKernelRunning() {
+  const pid = readKernelPid();
+  const alive = isAlive(pid);
+  return { running: alive, pid: alive ? pid : 0, meta: readKernelMeta() };
+}
+
+function cleanupRunFiles() {
+  for (const f of [KERNEL_PID_FILE, KERNEL_META_FILE]) {
+    try {
+      fs.unlinkSync(f);
+    } catch {
+      /* 已删则忽略 */
+    }
+  }
+}
+
+/**
+ * 探控制接口：拿到 /version 说明有内核在监听（可能是别人的）。
+ * @returns {Promise<{ url: string, version: string }|null>}
+ */
+export async function probeKernel(timeoutMs = 1200) {
+  const { url, secret } = getController();
+  try {
+    const res = await fetch(`${url}/version`, {
+      headers: secret ? { authorization: `Bearer ${secret}` } : {},
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) return null;
+    const data = await res.json();
+    // 内核回的就是 `v1.19.32`，统一成裸版本号，让调用方自己拼 v（否则会打印出 vv1.19.32）
+    return { url, version: `${bareVersion(data.version)}${data.meta ? ' (Meta)' : ''}` };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 启动前的校验：配置目录 → 配置里的控制接口 → 二进制 → 是否已在跑 → 控制接口是否被占。
+ * 抽出来是为了让「后台启动」与「受服务管理器监管的前台启动」走同一套前置检查。
+ *
+ * 关于前两项为何卡这么死（2026-10 实测踩过）：内核只在配置文件里认 `external-controller`，
+ * 配置里没这个键（或目录里压根没有 config.yaml，内核会自己生成一份只开 mixed-port 的初始配置）时，
+ * 它根本不会开控制接口 —— 拉起来也只会得到一个面板永远连不上、还占着 mixed-port 的裸内核。
+ * @param {{ bin?: string, dir?: string }} opts
+ * @returns {Promise<{ ok: boolean, dir?: string, bin?: string, api?: string, panelUrl?: string, configFile?: string, reason?: string }>}
+ */
+async function checkBeforeStart(opts = {}) {
+  const dir = opts.dir || detectMihomoDir();
+  const configFile = path.join(dir, 'config.yaml');
+  if (!fs.existsSync(configFile)) {
+    console.error(
+      `${dir} 里没有 config.yaml：内核会自己生成一份只开 mixed-port 的初始配置（没有控制接口），`,
+      '面板永远连不上它',
+    );
+    return { ok: false, reason: 'no-config-in-dir', dir, configFile };
+  }
+  // 读的是文件当下内容，不是 getController() 那份缓存（这里要判断二者是否已经对不上）
+  const { external } = readControllerConfig(dir);
+  if (!external) {
+    console.error(
+      `${configFile} 里没有 external-controller：内核不会开控制接口，面板连不上它。`,
+      '\n加一行 external-controller: 127.0.0.1:8190（面板「配置文件」页），再重启内核',
+    );
+    return { ok: false, reason: 'no-controller', dir, configFile };
+  }
+  const api = normalizeUrl(external);
+  const panelUrl = getController().url;
+  if (api !== panelUrl) {
+    console.error(
+      `配置里的控制接口是 ${api}，面板记的是 ${panelUrl}（启动面板时读的）：`,
+      'external-controller 改完要重启面板才生效',
+    );
+    return { ok: false, reason: 'controller-changed', dir, configFile, api, panelUrl };
+  }
+
+  const bin = opts.bin || KERNEL_BIN;
+  if (!fs.existsSync(bin)) {
+    console.error(
+      `没有可用的内核二进制：${bin}\n先在面板「内核」页安装（面板只跑自己装的那个内核）`,
+    );
+    return { ok: false, reason: 'no-binary' };
+  }
+  const own = ownKernelRunning();
+  if (own.running) {
+    console.error(`自有内核已在运行（pid ${own.pid}），要重启用侧栏底部的「重启内核」`);
+    return { ok: false, reason: 'already-running' };
+  }
+  cleanupRunFiles();
+
+  const occupied = await probeKernel(800);
+  if (occupied) {
+    console.error(
+      `控制接口 ${occupied.url} 已被占用（有 v${occupied.version} 在响应）：两个实例会抢同一个端口。\n` +
+        '先停掉占着它的那个进程（可能是上次没退干净的实例，或你自己另外启的 mihomo），或改 config.yaml 的 external-controller',
+    );
+    return { ok: false, reason: 'port-occupied' };
+  }
+  return { ok: true, dir, bin };
+}
+
+/** 把 pid / 运行时元数据落盘（kernel stop / status 靠它们）；`supervised` = 由系统服务管理器拉起（runner 的 `kernel` job） */
+function writeRunFiles(pid, { bin, dir, supervised }) {
+  fs.writeFileSync(KERNEL_PID_FILE, String(pid));
+  fs.writeFileSync(
+    KERNEL_META_FILE,
+    JSON.stringify(
+      {
+        pid,
+        bin,
+        dir,
+        api: getController().url,
+        supervised: !!supervised,
+        startedAt: Date.now(),
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+/**
+ * 拉起自有内核：detached 子进程，pid / 元数据 / 日志都落状态目录，然后等控制接口就绪。
+ *
+ * `foreground: true` 时（runner 的 `kernel` job 用，见 `bin/mihomo-dash-runner.js`）不 detach、
+ * 不 unref，并且等内核退出后把退出码回传 —— 这样服务管理器那一层才有真实的常驻进程可看。
+ * @param {{ bin?: string, dir?: string, foreground?: boolean }} [opts]
+ * @returns {Promise<{ ok: boolean, pid?: number, exitCode?: number, reason?: string }>}
+ */
+export async function kernelStart(opts = {}) {
+  const pre = await checkBeforeStart(opts);
+  if (!pre.ok) return pre;
+  const { dir, bin } = pre;
+
+  ensureCliDir();
+  // 内核日志只追加、无大小上限（实测能到几十 MB）：启动前轮转一份，避免无限长大。
+  // 前台（服务管理器监管）模式不轮转：那时 stdout 的 fd 是 launchd / systemd 自己开的，
+  // 在我们手里 rename 会把它们的写入甩到 `.1` 上。
+  if (!opts.foreground) rotateLogFile(KERNEL_LOG_FILE);
+  const logFd = fs.openSync(KERNEL_LOG_FILE, 'a');
+  const child = spawn(bin, ['-d', dir], {
+    detached: !opts.foreground,
+    stdio: ['ignore', logFd, logFd],
+  });
+  if (!opts.foreground) child.unref();
+  fs.closeSync(logFd);
+  writeRunFiles(child.pid, { bin, dir, supervised: !!opts.foreground });
+
+  const interval = readyIntervalMs();
+  for (let waited = 0; waited < READY_TIMEOUT_MS; waited += interval) {
+    if (!isAlive(child.pid)) break;
+    const ready = await probeKernel(600);
+    if (ready) {
+      if (opts.foreground) return waitChildExit(child);
+      console.log(`内核已启动: ${ready.url}（pid ${child.pid}，v${ready.version}）`);
+      return { ok: true, pid: child.pid };
+    }
+    await sleep(interval);
+  }
+
+  if (isAlive(child.pid)) {
+    try {
+      process.kill(child.pid, 'SIGKILL');
+    } catch {
+      /* 已退出 */
+    }
+  }
+  cleanupRunFiles();
+  console.error('内核启动失败：控制接口没起来。日志尾部：');
+  tailLogFile({ file: KERNEL_LOG_FILE, tail: FAIL_TAIL, write: (t) => process.stderr.write(t) });
+  return {
+    ok: false,
+    pid: child.pid,
+    reason: 'not-ready',
+    dir,
+    api: getController().url,
+  };
+}
+
+/**
+ * 前台模式下等内核退出：正常退出或被停掉都算 0（不保活，所以退出码只用于日志好看），
+ * 只有内核自己以非 0 退出（配置坏等）才把退出码透传给服务管理器。
+ * @param {import('node:child_process').ChildProcess} child
+ */
+function waitChildExit(child) {
+  return new Promise((resolve) => {
+    child.on('exit', (code, signal) => {
+      cleanupRunFiles();
+      const how = signal ? `被 ${signal} 结束` : `退出码 ${code}`;
+      console.log(`内核已退出（pid ${child.pid}，${how}）`);
+      resolve({ ok: true, pid: child.pid, exitCode: signal ? 0 : code || 0 });
+    });
+  });
+}
+
+/**
+ * 停止自有内核（只杀 pid 文件里那一个，绝不碰这个进程之外的任何东西）。
+ * @param {{ quiet?: boolean }} [opts]
+ * @returns {Promise<boolean>} 真的停掉了一个进程返回 true
+ */
+export async function kernelStop(opts = {}) {
+  const pid = readKernelPid();
+  if (!isAlive(pid)) {
+    cleanupRunFiles();
+    if (!opts.quiet) console.log('自有内核未在运行');
+    return false;
+  }
+  try {
+    process.kill(pid, 'SIGTERM');
+  } catch {
+    /* 刚好自己退了 */
+  }
+  const step = stopIntervalMs();
+  for (let waited = 0; waited < STOP_TIMEOUT_MS && isAlive(pid); waited += step) {
+    await sleep(step);
+  }
+  if (isAlive(pid)) {
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      /* 同上 */
+    }
+  }
+  cleanupRunFiles();
+  if (!opts.quiet) console.log(`内核已停止（pid ${pid}）`);
+  return true;
+}
+
+/** 重启自有内核：优先沿用 start 时记下的二进制与配置目录（那才是它真正在跑的），没记过才用传入值 */
+export async function kernelRestart(opts = {}) {
+  const meta = readKernelMeta();
+  await kernelStop({ quiet: true });
+  return kernelStart({ bin: meta?.bin || opts.bin, dir: meta?.dir || opts.dir });
+}
+
+/**
+ * 运行状态：自有内核进程 + 控制接口（后者可能是别的进程，会明说）。
+ * @returns {Promise<{ running: boolean, pid: number, api: string|null, version: string|null }>}
+ */
+export async function kernelStatus() {
+  const { running, pid, meta } = ownKernelRunning();
+  const probe = await probeKernel();
+  const { url: apiUrl } = getController();
+
+  if (running) {
+    const binVersion = meta?.bin ? await readKernelVersion(meta.bin) : null;
+    console.log(`自有内核: 运行中（pid ${pid}）`);
+    console.log(`二进制:   ${meta?.bin || KERNEL_BIN}${binVersion ? `（v${binVersion}）` : ''}`);
+  } else {
+    console.log('自有内核: 未运行（用侧栏底部的「启动内核」拉起）');
+  }
+  if (probe) {
+    const who = running ? '' : '（这个内核不是面板拉起的）';
+    console.log(`控制接口: ${probe.url} → v${probe.version}${who}`);
+  } else {
+    console.log(`控制接口: ${apiUrl} 无响应`);
+  }
+  return { running, pid, api: probe?.url || null, version: probe?.version || null };
+}
+
+/**
+ * 看自有内核日志（stdout/stderr 都写在这里）。
+ * @param {{ follow?: boolean, tail?: number }} [opts]
+ */
+export function kernelLogs(opts = {}) {
+  tailLogFile({ ...opts, file: KERNEL_LOG_FILE });
+}

package/server/src/kernel/run.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * 内核的前台入口：系统服务管理器的 `kernel` job 指向它（`[Unit]` 里没有 job 参数，
+ * 内核入口就是这一个文件）。**不给人手敲**，面板侧栏底部的「启动内核」走的是
+ * `kernelStart()`（后台 detached），这条路径只服务「开机自启」。
+ */
+import { kernelStart } from './lifecycle.js';
+
+const res = await kernelStart({ foreground: true });
+if (!res.ok) process.exit(1);
+if (res.exitCode) process.exit(res.exitCode);

package/server/src/shared/args.js

@@ -0,0 +1,57 @@
+/** 轻量参数解析：--k=v / --k v / 布尔开关 / -f 这类短别名，子命令固定所以不引第三方。 */
+
+const VALUE_FLAGS = new Set(['port', 'host', 'tail']);
+const ALIASES = { f: 'follow', o: 'open', h: 'help', V: 'version' };
+
+/**
+ * @param {string[]} argv 不含 node 与脚本路径的参数
+ * @returns {{ positionals: string[], flags: Record<string, string|boolean> }}
+ */
+export function parseArgs(argv) {
+  const positionals = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      if (eq !== -1) {
+        flags[a.slice(2, eq)] = a.slice(eq + 1);
+      } else {
+        const key = a.slice(2);
+        const next = argv[i + 1];
+        if (VALUE_FLAGS.has(key) && next !== undefined && !next.startsWith('-')) {
+          flags[key] = next;
+          i++;
+        } else {
+          flags[key] = true;
+        }
+      }
+    } else if (a.startsWith('-') && a.length > 1) {
+      for (const c of a.slice(1)) {
+        flags[ALIASES[c] || c] = true;
+      }
+    } else {
+      positionals.push(a);
+    }
+  }
+  return { positionals, flags };
+}
+
+/**
+ * 整数选项解析：非整数、布尔 true（只写了开关没给值）或超出 `min`-`max` 时报错退出。
+ * @param {string|boolean|undefined} value 原始值；undefined 表示没给，直接返回 fallback
+ * @param {number} fallback
+ * @param {{ label?: string, min?: number, max?: number }} [opts]
+ */
+export function parseIntFlag(value, fallback, { label = '数值', min = 1, max = 65535 } = {}) {
+  if (value === undefined) return fallback;
+  const n = typeof value === 'boolean' ? Number.NaN : Number(value);
+  if (!Number.isInteger(n) || n < min || n > max) {
+    console.error(`无效${label}: ${value === true ? '(缺值)' : value}`);
+    process.exit(2);
+  }
+  return n;
+}
+
+/** 端口解析（1-65535 的整数，否则报错退出） */
+export const parsePort = (value, fallback) => parseIntFlag(value, fallback, { label: '端口' });

package/server/src/shared/atomic-file.js

@@ -0,0 +1,41 @@
+/**
+ * 原子写文件：**同目录临时文件 → rename 覆盖**。
+ *
+ * 配置类文件以前都是 `fs.writeFileSync(p, text)` 直接覆盖主文件：写到一半崩溃 / 断电 / 磁盘满
+ * 就会留下一个截断的 config.yaml，而它是用户唯一的配置（内核二进制那条路径早就是 rename 原子的，
+ * 这里对齐）。rename 在同一文件系统内是原子的：读者只会看到「旧内容」或「新内容」，不会看到半份。
+ *
+ * 权限沿用原文件（新建时按 umask 走默认）。临时文件带 `.` 前缀 + pid + 时间戳，写失败会自己清掉；
+ * 它和主文件同目录，所以 rename 不会跨设备（`EXDEV`）。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * 原子地把 `text` 写到 `file`。
+ * @param {string} file 目标路径（父目录必须已存在）
+ * @param {string} text
+ * @returns {string} 目标路径
+ */
+export function writeFileAtomic(file, text) {
+  const tmp = path.join(
+    path.dirname(file),
+    `.${path.basename(file)}.tmp-${process.pid}-${Date.now()}`,
+  );
+  /** 已存在文件的权限原样保留；新文件交给默认 umask */
+  let mode = null;
+  try {
+    mode = fs.statSync(file).mode & 0o777;
+  } catch {
+    /* 新文件 */
+  }
+  try {
+    fs.writeFileSync(tmp, text);
+    if (mode !== null) fs.chmodSync(tmp, mode);
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    fs.rmSync(tmp, { force: true });
+    throw err;
+  }
+  return file;
+}

package/server/src/shared/exec.js

@@ -0,0 +1,44 @@
+/**
+ * 外部命令执行助手（系统代理 / 开机自启 / 内核版本探测 / 解压共用）。
+ *
+ * 项目里所有外部命令都是**固定 argv 直接 execFile、不经过 shell**：调用方拼好参数数组，
+ * 这里只管执行与超时，绝不接受拼接后的命令串。
+ *
+ * **异步**（2026-11 从 spawnSync 改成 execFile）：面板是单进程 Node 服务，spawnSync 会把整个
+ * 事件循环卡住（最长 5s / 条命令）—— `service status` 一次就要串行跑好几条 launchctl /
+ * systemctl，期间所有 REST 请求都排队。调用方一律 `await`，返回结构保持不变。
+ */
+import { execFile } from 'node:child_process';
+
+const RUN_TIMEOUT_MS = 5000;
+/** 单条命令的输出上限（launchctl print 之类的输出能到几十 KB，留足余量） */
+const MAX_OUTPUT = 4 * 1024 * 1024;
+
+/**
+ * 默认执行器：固定 argv、不走 shell、带超时。
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{ timeout?: number }} [opts]
+ * @returns {Promise<{ ok: boolean, status: number, stdout: string, stderr: string }>}
+ */
+export function defaultRun(cmd, args, opts = {}) {
+  const timeout = opts.timeout || RUN_TIMEOUT_MS;
+  return new Promise((resolve) => {
+    execFile(
+      cmd,
+      args,
+      { encoding: 'utf8', timeout, maxBuffer: MAX_OUTPUT },
+      (err, stdout, stderr) => {
+        // Node 在非 0 退出时会往 stderr 前面拼一行「Command failed: <cmd>」：界面文案里不需要它
+        const errText = (stderr || '').replace(/^Command failed: [^\n]*\n?/, '');
+        resolve({
+          ok: !err,
+          // 正常退出 0；子进程自己的非 0 退出码挂在 err.code（数字）；启动失败（ENOENT 等）给 -1
+          status: err ? (typeof err.code === 'number' ? err.code : -1) : 0,
+          stdout: stdout || '',
+          stderr: errText || (err ? (err.killed ? `命令超时（${timeout}ms）` : err.message) : ''),
+        });
+      },
+    );
+  });
+}

package/server/src/shared/kernel-config.js

@@ -0,0 +1,27 @@
+/** 读一次内核 config.yaml（CLI 与面板共用）：不存在/解析失败都返回原因，不抛异常。 */
+import fs from 'node:fs';
+import yaml from 'js-yaml';
+import { configPath } from './paths.js';
+
+/**
+ * @returns {{ path: string|null, config: any, error: string|null }}
+ */
+export function loadKernelConfig() {
+  const file = configPath();
+  if (!fs.existsSync(file)) {
+    return {
+      path: file,
+      config: null,
+      error: `配置目录里没有 config.yaml（${file}）：去面板「配置文件」页写好并保存就会创建`,
+    };
+  }
+  try {
+    const config = yaml.load(fs.readFileSync(file, 'utf8')) || {};
+    if (typeof config !== 'object' || Array.isArray(config)) {
+      return { path: file, config: null, error: '顶层不是映射（YAML 结构不对）' };
+    }
+    return { path: file, config, error: null };
+  } catch (err) {
+    return { path: file, config: null, error: err?.message || String(err) };
+  }
+}

package/server/src/shared/log-file.js

@@ -0,0 +1,92 @@
+/**
+ * 日志文件的两个操作：**尾部读取**与**启动前轮转**。
+ *
+ * 为什么单独一个模块：`daemon.log`（面板 job 的 stdout）/ `kernel.log` 是**只追加、没有任何大小上限**的文件
+ * （内核 `log-level: info` 跑一段时间就是几十 MB，实测 71.8 MB / 33 万行）。以前两处都用
+ * `readFileSync(整个文件)` 再切最后 N 行：
+ * - 内核页每 2s 轮询一次 `GET /api/kernel-admin/logs?tail=400`，每次全量读 ≈ 95ms 直接把
+ *   面板的事件循环按住；
+ * - 以前的 `daemon logs`、现在的内核日志尾读，都一样把整个文件读进内存。
+ * 所以这里按块从文件末尾往前读，读到够行数就停（默认最多读 4 MB）。
+ *
+ * 轮转只在**启动进程之前**做（没有任何进程正持有该文件的写 fd 时最安全），保留一份 `.1`。
+ */
+import fs from 'node:fs';
+
+/** 单次尾部读取最多往回读多少字节（够几千行了） */
+const MAX_TAIL_BYTES = 4 * 1024 * 1024;
+/** 每次往回读的块大小 */
+const READ_CHUNK = 64 * 1024;
+/** 日志超过这个大小就在下次启动前轮转成 `<file>.1` */
+export const ROTATE_BYTES = 5 * 1024 * 1024;
+
+/**
+ * 读文件尾部若干行（不把整个文件读进内存）。
+ * @param {string} file
+ * @param {{ lines?: number, maxBytes?: number }} [opts]
+ * @returns {{ lines: string[], missing: boolean, truncated: boolean }}
+ *   `truncated` = 读到上限还没覆盖全文（返回的只是尾部）
+ */
+export function readTailLines(file, { lines = 200, maxBytes = MAX_TAIL_BYTES } = {}) {
+  const want = Math.max(1, Math.floor(Number(lines) || 1));
+  const cap = Math.max(1, Math.floor(Number(maxBytes) || MAX_TAIL_BYTES));
+
+  let size;
+  try {
+    size = fs.statSync(file).size;
+  } catch {
+    return { lines: [], missing: true, truncated: false };
+  }
+  if (size === 0) return { lines: [], missing: false, truncated: false };
+
+  /** @type {Buffer[]} */
+  const chunks = [];
+  let read = 0;
+  let pos = size;
+  let newlines = 0;
+  let fd;
+  try {
+    fd = fs.openSync(file, 'r');
+    while (pos > 0 && read < cap) {
+      const len = Math.min(READ_CHUNK, pos, cap - read);
+      const buf = Buffer.alloc(len);
+      fs.readSync(fd, buf, 0, len, pos - len);
+      chunks.unshift(buf);
+      read += len;
+      pos -= len;
+      for (const byte of buf) if (byte === 0x0a) newlines++;
+      // 多要一行：拿到第 want+1 个换行才能确定尾部正好有 want 行
+      if (newlines > want) break;
+    }
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+
+  const text = Buffer.concat(chunks).toString('utf8');
+  const all = text.split('\n');
+  // 从文件中间开始读时，第一段是被截断的半行，丢掉
+  const atStart = pos === 0;
+  if (!atStart) all.shift();
+  // 文件以换行结尾时 split 会留一个空尾巴
+  if (all.length && all[all.length - 1] === '') all.pop();
+  return { lines: all.slice(-want), missing: false, truncated: !atStart };
+}
+
+/**
+ * 日志轮转：超过 `maxBytes` 就改名成 `<file>.1`（覆盖旧的那份），返回轮转后的路径。
+ * 只在启动进程前调用 —— 那时没有进程持有这个文件的写 fd。
+ * @param {string} file
+ * @param {number} [maxBytes]
+ * @returns {string|null} 没轮转（文件不存在 / 不够大 / 出错）返回 null
+ */
+export function rotateLogFile(file, maxBytes = ROTATE_BYTES) {
+  try {
+    if (fs.statSync(file).size <= maxBytes) return null;
+    const rotated = `${file}.1`;
+    fs.rmSync(rotated, { force: true });
+    fs.renameSync(file, rotated);
+    return rotated;
+  } catch {
+    return null;
+  }
+}

package/server/src/shared/panel.js

@@ -0,0 +1,58 @@
+/**
+ * 面板进程探活：**不再有 daemon.pid / daemon.json**（2026-11 去掉守护进程后）。
+ *
+ * 为什么不看 pid 文件：进程被 kill -9 后文件残留、pid 还会被系统复用，都会骗人；
+ * 直接打面板自己的 `/api/health` 是唯一直接证据，顺带能拿到版本与运行时长。
+ */
+
+import { DEFAULT_HOST, DEFAULT_PORT } from './paths.js';
+
+/**
+ * 0.0.0.0 / :: 这类监听地址不能直接连，换成回环。
+ * @param {string} [host]
+ * @returns {string}
+ */
+export function connectHost(host) {
+  if (!host || host === '0.0.0.0' || host === '::' || host === '[::]') return '127.0.0.1';
+  return host;
+}
+
+/**
+ * @param {{ host?: string, port?: number }} [target]
+ * @returns {{ url: string, host: string, port: number }}
+ */
+export function panelTarget(target = {}) {
+  const port = Number(target.port) || DEFAULT_PORT;
+  const host = connectHost(target.host || DEFAULT_HOST);
+  return { url: `http://${host}:${port}`, host, port };
+}
+
+/**
+ * 探一次面板。连不上 / 超时 / 不是 mihomo-dash 都算「没在跑」，不抛异常。
+ * @param {{ host?: string, port?: number, timeoutMs?: number }} [target]
+ * @returns {Promise<{ running: boolean, url: string, host: string, port: number,
+ *   version: string|null, uptime: number|null, pid: number|null }>}
+ */
+export async function probePanel(target = {}) {
+  const { url, host, port } = panelTarget(target);
+  const dead = { running: false, url, host, port, version: null, uptime: null, pid: null };
+  try {
+    const res = await fetch(`${url}/api/health`, {
+      signal: AbortSignal.timeout(target.timeoutMs ?? 1500),
+    });
+    if (!res.ok) return dead;
+    const body = await res.json();
+    if (body?.name !== 'mihomo-dash') return dead;
+    return {
+      running: true,
+      url,
+      host,
+      port,
+      version: typeof body.version === 'string' ? body.version : null,
+      uptime: typeof body.uptime === 'number' ? body.uptime : null,
+      pid: typeof body.pid === 'number' ? body.pid : null,
+    };
+  } catch {
+    return dead;
+  }
+}