ellm-proxy 0.0.3 → 0.0.6

package/utils/autostart.js

@@ -0,0 +1,219 @@
+// 开机自启核心（跨平台，登录时触发，均无需管理员权限）：状态探测 / 注册 / 移除 / 首启自愈。
+// 被 CLI（bin/commands/autostart.js）与管理服务（manager/api/service-settings.js）复用。
+// 本模块只做平台操作并返回数据，人读文案由调用方输出；错误以 throw 抛出（文案是契约的一部分）。
+// 自启项内容三平台一致：登录时执行 <nodePath> <包内 pm2 bin> resurrect（恢复最后一次 pm2 dump）：
+//   Windows: 启动文件夹 ellm-proxy-autostart.cmd（shell:startup——schtasks onlogon 需管理员，实测被拒）
+//   macOS:   LaunchAgent ~/Library/LaunchAgents/com.ellm-proxy.autostart.plist（launchctl load）
+//   Linux:   systemd user unit ~/.config/systemd/user/ellm-proxy.service（systemctl --user enable）
+// opt-out 标记（<appDir>/autostart.opt-out）：用户显式关闭过自启后，首启自愈不再自动重开
+//   （尊重用户选择）；enableAutostart 成功时清除，disableAutostart 成功时写入。
+import { writeFileSync, rmSync, existsSync, mkdirSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { defaultAppDir } from "./paths.js";
+import { resolveInterpreter } from "./interpreter.js";
+import { pm2BinJs } from "./pm2.js";
+
+const AUTOSTART_CMD = "ellm-proxy-autostart.cmd"; // Windows
+const PLIST_LABEL = "com.ellm-proxy.autostart"; // macOS
+const LINUX_UNIT = "ellm-proxy.service"; // Linux
+const OPT_OUT_FILE = "autostart.opt-out"; // appDir 下的 opt-out 标记文件名
+
+/** opt-out 标记路径（用户显式关闭过自启的持久标记，首启自愈据此跳过） */
+function optOutPath() {
+  return join(defaultAppDir, OPT_OUT_FILE);
+}
+
+/** 用户启动文件夹（Windows shell:startup）：登录时自动执行其中的脚本 */
+function windowsStartupDir() {
+  const dir = process.env["APPDATA"];
+  if (!dir) throw new Error("无法定位启动文件夹（APPDATA 环境变量未设置）。");
+  return join(dir, "Microsoft", "Windows", "Start Menu", "Programs", "Startup");
+}
+
+/** spawn 执行外部命令，返回退出码；进程无法启动（ENOENT 等）返回 127 */
+function runExit(cmd, args) {
+  return new Promise((resolvePromise) => {
+    const child = spawn(cmd, args, { stdio: "ignore", shell: false });
+    child.on("error", () => resolvePromise(127));
+    child.on("exit", (code) => resolvePromise(code ?? 1));
+  });
+}
+
+/** 各平台自启项路径（探测用；未知平台为 null） */
+function platformItemPath() {
+  switch (platform()) {
+    case "win32":
+      return join(windowsStartupDir(), AUTOSTART_CMD);
+    case "darwin":
+      return join(homedir(), "Library", "LaunchAgents", `${PLIST_LABEL}.plist`);
+    case "linux":
+      return join(homedir(), ".config", "systemd", "user", LINUX_UNIT);
+    default:
+      return null;
+  }
+}
+
+// —— 注册（各平台） ————————————————————————————————————————————————
+
+async function windowsOn(nodePath, pm2Js) {
+  // cmd 内容全 ASCII（含中文的注释交给外部帮助输出，避免 cmd 在 GBK 代码页下乱码）
+  const body = [
+    "@echo off",
+    `rem Auto-generated by "ellm-proxy autostart on". Disable with "ellm-proxy autostart off".`,
+    `"${nodePath}" "${pm2Js}" resurrect >nul 2>&1`,
+    "",
+  ].join("\r\n");
+  const itemPath = join(windowsStartupDir(), AUTOSTART_CMD);
+  writeFileSync(itemPath, body, "utf-8");
+  return itemPath;
+}
+
+async function darwinOn(nodePath, pm2Js) {
+  const itemPath = join(homedir(), "Library", "LaunchAgents", `${PLIST_LABEL}.plist`);
+  const logPath = join(defaultAppDir, "logs", "autostart.log");
+  mkdirSync(join(defaultAppDir, "logs"), { recursive: true });
+  const body = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    "<dict>",
+    `  <key>Label</key><string>${PLIST_LABEL}</string>`,
+    "  <key>ProgramArguments</key>",
+    "  <array>",
+    `    <string>${nodePath}</string>`,
+    `    <string>${pm2Js}</string>`,
+    "    <string>resurrect</string>",
+    "  </array>",
+    "  <key>RunAtLoad</key><true/>",
+    `  <key>StandardOutPath</key><string>${logPath}</string>`,
+    `  <key>StandardErrorPath</key><string>${logPath}</string>`,
+    "</dict>",
+    "</plist>",
+    "",
+  ].join("\n");
+  writeFileSync(itemPath, body, "utf-8");
+  // 先卸载旧定义再加载（幂等；未加载过时 unload 报错属正常）
+  await runExit("launchctl", ["unload", itemPath]);
+  const code = await runExit("launchctl", ["load", itemPath]);
+  if (code !== 0) {
+    throw new Error(`launchctl load 失败（退出码 ${code}）。请手动执行: launchctl load "${itemPath}"`);
+  }
+  return itemPath;
+}
+
+async function linuxOn(nodePath, pm2Js) {
+  const itemPath = join(homedir(), ".config", "systemd", "user", LINUX_UNIT);
+  mkdirSync(join(homedir(), ".config", "systemd", "user"), { recursive: true });
+  const body = [
+    "[Unit]",
+    "Description=ellm-proxy autostart (pm2 resurrect)",
+    "After=default.target",
+    "",
+    "[Service]",
+    "Type=oneshot",
+    `ExecStart="${nodePath}" "${pm2Js}" resurrect`,
+    "",
+    "[Install]",
+    "WantedBy=default.target",
+    "",
+  ].join("\n");
+  writeFileSync(itemPath, body, "utf-8");
+  const reload = await runExit("systemctl", ["--user", "daemon-reload"]);
+  if (reload !== 0) {
+    throw new Error(
+      `systemctl --user daemon-reload 失败（退出码 ${reload}）。当前环境可能无 systemd（WSL/容器），请手动启用或删除: ${itemPath}`,
+    );
+  }
+  const enable = await runExit("systemctl", ["--user", "enable", LINUX_UNIT]);
+  if (enable !== 0) {
+    throw new Error(
+      `systemctl --user enable 失败（退出码 ${enable}）。请手动执行: systemctl --user enable ${LINUX_UNIT}`,
+    );
+  }
+  return itemPath;
+}
+
+// —— 移除（各平台） ————————————————————————————————————————————————
+
+async function windowsOff() {
+  const itemPath = join(windowsStartupDir(), AUTOSTART_CMD);
+  if (!existsSync(itemPath)) return false;
+  rmSync(itemPath, { force: true });
+  return true;
+}
+
+async function darwinOff() {
+  const itemPath = join(homedir(), "Library", "LaunchAgents", `${PLIST_LABEL}.plist`);
+  if (!existsSync(itemPath)) return false;
+  await runExit("launchctl", ["unload", itemPath]);
+  rmSync(itemPath, { force: true });
+  return true;
+}
+
+async function linuxOff() {
+  const itemPath = join(homedir(), ".config", "systemd", "user", LINUX_UNIT);
+  if (!existsSync(itemPath)) return false;
+  await runExit("systemctl", ["--user", "disable", LINUX_UNIT]); // 容错：未启用过时报错不影响删除
+  rmSync(itemPath, { force: true });
+  await runExit("systemctl", ["--user", "daemon-reload"]);
+  return true;
+}
+
+// —— 对外 API ——————————————————————————————————————————————————————
+
+/** 自启状态：enabled = 平台自启项是否存在；itemPath 未知平台为 null */
+export async function autostartStatus() {
+  const itemPath = platformItemPath();
+  return {
+    platform: platform(),
+    enabled: itemPath ? existsSync(itemPath) : false,
+    itemPath,
+    /** 用户是否显式关闭过（首启自愈据此跳过） */
+    optOut: existsSync(optOutPath()),
+  };
+}
+
+/** 注册自启项（幂等：重复注册覆盖旧文件；macOS 先 unload 再 load）。成功返回 { itemPath } */
+export async function enableAutostart() {
+  const pf = platform();
+  if (pf !== "win32" && pf !== "darwin" && pf !== "linux") {
+    throw new Error(`暂不支持的平台: ${pf}。可改用 pm2 自带的 pm2 startup。`);
+  }
+  const nodePath = await resolveInterpreter();
+  const pm2Js = pm2BinJs();
+  const itemPath = await (pf === "win32" ? windowsOn : pf === "darwin" ? darwinOn : linuxOn)(nodePath, pm2Js);
+  rmSync(optOutPath(), { force: true }); // 显式开启 = 清除 opt-out，首启自愈不再被视为已关闭
+  return { itemPath };
+}
+
+/** 移除自启项。返回 removed（此前是否存在）；成功后写 opt-out 标记（首启自愈不再自动重开） */
+export async function disableAutostart() {
+  const pf = platform();
+  if (pf !== "win32" && pf !== "darwin" && pf !== "linux") {
+    throw new Error(`暂不支持的平台: ${pf}。可改用 pm2 自带的 pm2 startup。`);
+  }
+  const removed = await (pf === "win32" ? windowsOff : pf === "darwin" ? darwinOff : linuxOff)();
+  mkdirSync(defaultAppDir, { recursive: true });
+  writeFileSync(optOutPath(), new Date().toISOString(), "utf-8");
+  return { removed };
+}
+
+/** 首启自愈（doStart 末尾静默调用）：自启项已存在或用户 opt-out 过则跳过，否则注册并提示一句。
+ *  失败不抛出（不阻塞启动，console.warn 提示手动路径）。 */
+export async function ensureAutostartOnStart() {
+  try {
+    const status = await autostartStatus();
+    if (!status.itemPath || status.enabled) return; // 未知平台 / 已注册
+    if (status.optOut) {
+      console.log("已按此前设置保持开机自启关闭（如需开启：ellm-proxy autostart on 或管理台设置页）。");
+      return;
+    }
+    const { itemPath } = await enableAutostart();
+    console.log(`已自动注册开机自启（登录时 pm2 resurrect）: ${itemPath}`);
+    console.log("禁用方式: ellm-proxy autostart off 或管理台设置页。");
+  } catch (err) {
+    console.warn(`开机自启注册失败（不影响本次启动）: ${err?.message ?? err}`);
+  }
+}

package/utils/interpreter.js

@@ -1,14 +1,14 @@
-// 服务解释器解析：保证 dist/server.js（node:sqlite）运行在 Node >= MIN_NODE 上。
-// CLI 自身 node 满足 → process.execPath；否则 get-node 解析（缺失时下载一次并缓存），
-// pm2 daemon 的 node 版本无关紧要（interpreter 由本模块保证）。
-import getNode from "get-node";
-import { MIN_NODE } from "./paths.js";
-
-export async function resolveInterpreter() {
-  const [maj, min] = process.version.replace(/^v/, "").split(".").map(Number);
-  if (maj > 22 || (maj === 22 && min >= 13)) return process.execPath;
-  console.log(`当前 node ${process.version} 不满足 ${MIN_NODE}，正在解析可用版本（缺失时自动下载一次并缓存）...`);
-  const { path, version } = await getNode(MIN_NODE, { progress: true });
-  console.log(`服务将使用 node ${version}: ${path}`);
-  return path;
-}
+// 服务解释器解析：保证 dist/server.js（node:sqlite）运行在 Node >= MIN_NODE 上。
+// CLI 自身 node 满足 → process.execPath；否则 get-node 解析（缺失时下载一次并缓存），
+// pm2 daemon 的 node 版本无关紧要（interpreter 由本模块保证）。
+import getNode from "get-node";
+import { MIN_NODE, FALLBACK_NODE } from "./paths.js";
+
+export async function resolveInterpreter() {
+  const [maj, min] = process.version.replace(/^v/, "").split(".").map(Number);
+  if (maj > 22 || (maj === 22 && min >= 13)) return process.execPath;
+  console.log(`当前 node ${process.version} 不满足 ${MIN_NODE}，正在解析可用版本（缺失时自动下载一次并缓存）...`);
+  const { path, version } = await getNode(FALLBACK_NODE, { progress: true });
+  console.log(`服务将使用 node ${version}: ${path}`);
+  return path;
+}

package/utils/paths.js

@@ -1,44 +1,45 @@
-// 共享常量与路径工具：包根/应用目录常量、配置查找链、首次配置自愈、选项绝对化。
-// 供 CLI（bin/）与管理服务（manager/）两侧复用；工具一律返回数据，人读文案由调用方输出。
-import { readFileSync, mkdirSync, existsSync, copyFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-/** 本文件在 utils/ 下，包根为上一级 */
-export const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-export const defaultAppDir = join(homedir(), ".ellm-proxy");
-export const pkg = JSON.parse(readFileSync(join(pkgRoot, "package.json"), "utf-8"));
-export const APP_NAME = "ellm-proxy"; // 主服务（dist/server.js）的 pm2 进程名
-export const MANAGER_APP_NAME = "ellm-proxy-manager"; // 管理服务（manager/index.js）的 pm2 进程名
-export const MIN_NODE = ">=22.13.0"; // node:sqlite 最低版（与包 engines 一致）
-
-/** 配置文件路径：--config > ELLM_CONFIG 环境变量 > ~/.ellm-proxy/ellm.config.json（与 server 端查找链一致） */
-export function configPath(override) {
-  if (override) return resolve(override);
-  return process.env["ELLM_CONFIG"] ? resolve(process.env["ELLM_CONFIG"]) : join(defaultAppDir, "ellm.config.json");
-}
-
-/** 首次配置自愈：不存在则从包内示例复制创建，并提示两种修改方式 */
-export function ensureConfig(override) {
-  const config = configPath(override);
-  if (existsSync(config)) return config;
-  const example = join(pkgRoot, "ellm.config.example.json");
-  if (!existsSync(example)) {
-    throw new Error(`缺少示例配置 ${example}，无法自动创建配置文件`);
-  }
-  mkdirSync(dirname(config), { recursive: true });
-  copyFileSync(example, config);
-  console.log(`已创建配置文件: ${config}`);
-  console.log("可直接编辑该文件（填入供应商 apiKey），或经管理台在线修改（实时热更新）。");
-  return config;
-}
-
-/** 路径类选项统一转绝对路径（相对按调用方当前目录展开；CLI cwd 与 node 进程工作目录基准不同，透传相对串会错位） */
-export function absolutize(opts) {
-  const out = { ...opts };
-  for (const key of ["config", "dataDir", "workingDir", "serverJs"]) {
-    if (out[key]) out[key] = resolve(out[key]);
-  }
-  return out;
-}
+// 共享常量与路径工具：包根/应用目录常量、配置查找链、首次配置自愈、选项绝对化。
+// 供 CLI（bin/）与管理服务（manager/）两侧复用；工具一律返回数据，人读文案由调用方输出。
+import { readFileSync, mkdirSync, existsSync, copyFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** 本文件在 utils/ 下，包根为上一级 */
+export const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+export const defaultAppDir = join(homedir(), ".ellm-proxy");
+export const pkg = JSON.parse(readFileSync(join(pkgRoot, "package.json"), "utf-8"));
+export const APP_NAME = "ellm-proxy"; // 主服务（dist/server.js）的 pm2 进程名
+export const MANAGER_APP_NAME = "ellm-proxy-manager"; // 管理服务（manager/index.js）的 pm2 进程名
+export const MIN_NODE = ">=22.13.0"; // node:sqlite 最低版（与包 engines 一致）
+export const FALLBACK_NODE = "22"; // 兜底解释器锁定的主版本（满足 MIN_NODE，与 nve 22 口径一致）
+
+/** 配置文件路径：--config > ELLM_CONFIG 环境变量 > ~/.ellm-proxy/ellm.config.json（与 server 端查找链一致） */
+export function configPath(override) {
+  if (override) return resolve(override);
+  return process.env["ELLM_CONFIG"] ? resolve(process.env["ELLM_CONFIG"]) : join(defaultAppDir, "ellm.config.json");
+}
+
+/** 首次配置自愈：不存在则从包内示例复制创建，并提示两种修改方式 */
+export function ensureConfig(override) {
+  const config = configPath(override);
+  if (existsSync(config)) return config;
+  const example = join(pkgRoot, "ellm.config.example.json");
+  if (!existsSync(example)) {
+    throw new Error(`缺少示例配置 ${example}，无法自动创建配置文件`);
+  }
+  mkdirSync(dirname(config), { recursive: true });
+  copyFileSync(example, config);
+  console.log(`已创建配置文件: ${config}`);
+  console.log("可直接编辑该文件（填入供应商 apiKey），或经管理台在线修改（实时热更新）。");
+  return config;
+}
+
+/** 路径类选项统一转绝对路径（相对按调用方当前目录展开；CLI cwd 与 node 进程工作目录基准不同，透传相对串会错位） */
+export function absolutize(opts) {
+  const out = { ...opts };
+  for (const key of ["config", "dataDir", "workingDir", "serverJs"]) {
+    if (out[key]) out[key] = resolve(out[key]);
+  }
+  return out;
+}

package/utils/pm2.js

@@ -1,130 +1,130 @@
-// pm2 JS API 封装：连接包裹/回调转 promise/应用查询/探活轮询/安全 dump/包内 pm2 CLI 定位/env 白名单。
-import { rmSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import { createRequire } from "node:module";
-import pm2 from "pm2";
-import { APP_NAME, MANAGER_APP_NAME } from "./paths.js";
-import { dot, endOk, endFail } from "./ui.js";
-
-/** pm2.connect 包裹：fn 内可调 pm2.xxx（回调式），结束后自动 disconnect */
-export function withPm2(fn) {
-  return new Promise((resolvePromise, reject) => {
-    pm2.connect((connectErr) => {
-      if (connectErr) return reject(connectErr);
-      Promise.resolve(fn(pm2)).then(
-        (value) => pm2.disconnect(() => resolvePromise(value)),
-        (err) => {
-          try {
-            pm2.disconnect();
-          } catch {
-            /* 已断开 */
-          }
-          reject(err);
-        },
-      );
-    });
-  });
-}
-
-/** pm2 回调式方法转 promise */
-export function pm2cb(method, ...args) {
-  return new Promise((resolvePromise, reject) => {
-    pm2[method](...args, (err, ...out) => (err ? reject(err) : resolvePromise(...out)));
-  });
-}
-
-/** 查询应用当前进程记录（list 中按 name 匹配；不存在返回 undefined）。
- *  name 缺省 = 主服务 ellm-proxy；管理服务传 MANAGER_APP_NAME */
-export async function findApp(name = APP_NAME) {
-  const list = (await pm2cb("list")) || [];
-  return list.find((p) => p.name === name);
-}
-
-/** 启动探活：轮询 status 至 online（每 pollMs 一次，全程打进度点）——比固定等待更快成功
- *  （online 即返回），也能容忍慢启动（默认 15s 上限，固定 1.5s 在慢机器上会误报）；errored/stopped
- *  提前失败（脚本秒崩不必等满超时）。failHint 是失败文案的线索部分（文案是契约的一部分）。
- *  quiet = 静默轮询不打点（多服务并行等待时输出由调用方合并，避免多组进度点交错）。 */
-export async function waitOnline(name, failHint, { timeoutMs = 15000, pollMs = 300, quiet = false } = {}) {
-  const deadline = Date.now() + timeoutMs;
-  let last = null;
-  for (;;) {
-    last = await findApp(name);
-    const status = last?.pm2_env?.status;
-    if (status === "online") {
-      if (!quiet) endOk();
-      return last;
-    }
-    if (status === "errored" || status === "stopped" || Date.now() >= deadline) {
-      if (!quiet) endFail();
-      throw new Error(`${name} 启动后状态异常（${status ?? "已退出"}）。${failHint}`);
-    }
-    if (!quiet) dot();
-    await new Promise((r) => setTimeout(r, pollMs));
-  }
-}
-
-/** 安全 dump（start/stop 成功后调用）：pm2 不允许 dump 空列表会报错——此时说明全部进程已删，
- *  清掉旧 dump.pm2 与滚动备份 dump.pm2.bak（resurrect 无 dump.pm2 时会回落 .bak），防止开机
- *  resurrect 把已停止的服务拉起来 */
-export async function safeDump() {
-  try {
-    await pm2cb("dump");
-  } catch {
-    try {
-      rmSync(join(homedir(), ".pm2", "dump.pm2"), { force: true });
-      rmSync(join(homedir(), ".pm2", "dump.pm2.bak"), { force: true });
-    } catch {
-      /* 清理失败不影响 stop 语义 */
-    }
-  }
-}
-
-/** 当前包内 pm2 CLI 入口绝对路径（autostart cmd 用；resolve 兼容 npm 全局平铺与 pnpm 布局） */
-export function pm2BinJs() {
-  const pm2PkgRoot = dirname(createRequire(import.meta.url).resolve("pm2/package.json"));
-  return join(pm2PkgRoot, "bin", "pm2");
-}
-
-/** 清洗 pm2 子进程透传的 env：pm2 托管的进程自身 env 带 pm_id/pm2_env/unique_id 等
- *  内部变量与 bash 注入的 `_`，原样传回 pm2.start 会污染新进程注册——实测主服务
- *  （name=ellm-proxy）被注册成管理服务的名字，导致探活误判「已退出」。
- *  黑名单清洗实测仍有漏网（多键组合触发），故改用白名单：
- *  只透传主服务必需的业务键（ELLM_* 前缀，含 ELLM_PORT / ELLM_MANAGER_PORT）与 Windows node 运行所需的系统键。
- *  PM2_HOME 保留（pm2 API 连接 daemon 需要，主服务自身不用）。 */
-const PM2_ENV_WHITELIST = new Set([
-  "PATH",
-  "SYSTEMROOT",
-  "WINDIR",
-  "SYSTEMDRIVE",
-  "COMSPEC",
-  "PATHEXT",
-  "OS",
-  "TEMP",
-  "TMP",
-  "USERPROFILE",
-  "HOMEDRIVE",
-  "HOMEPATH",
-  "APPDATA",
-  "LOCALAPPDATA",
-  "PROGRAMDATA",
-  "PROGRAMFILES",
-  "ALLUSERSPROFILE",
-  "PUBLIC",
-  "USERNAME",
-  "USERDOMAIN",
-  "COMPUTERNAME",
-  "NUMBER_OF_PROCESSORS",
-  "HTTP_PROXY",
-  "HTTPS_PROXY",
-  "NO_PROXY",
-]);
-
-export function sanitizePm2Env(env) {
-  const out = {};
-  for (const [key, value] of Object.entries(env)) {
-    if (key === "PM2_HOME" || key.startsWith("ELLM_")) out[key] = value;
-    else if (PM2_ENV_WHITELIST.has(key.toUpperCase())) out[key] = value;
-  }
-  return out;
-}
+// pm2 JS API 封装：连接包裹/回调转 promise/应用查询/探活轮询/安全 dump/包内 pm2 CLI 定位/env 白名单。
+import { rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+import pm2 from "pm2";
+import { APP_NAME, MANAGER_APP_NAME } from "./paths.js";
+import { dot, endOk, endFail } from "./ui.js";
+
+/** pm2.connect 包裹：fn 内可调 pm2.xxx（回调式），结束后自动 disconnect */
+export function withPm2(fn) {
+  return new Promise((resolvePromise, reject) => {
+    pm2.connect((connectErr) => {
+      if (connectErr) return reject(connectErr);
+      Promise.resolve(fn(pm2)).then(
+        (value) => pm2.disconnect(() => resolvePromise(value)),
+        (err) => {
+          try {
+            pm2.disconnect();
+          } catch {
+            /* 已断开 */
+          }
+          reject(err);
+        },
+      );
+    });
+  });
+}
+
+/** pm2 回调式方法转 promise */
+export function pm2cb(method, ...args) {
+  return new Promise((resolvePromise, reject) => {
+    pm2[method](...args, (err, ...out) => (err ? reject(err) : resolvePromise(...out)));
+  });
+}
+
+/** 查询应用当前进程记录（list 中按 name 匹配；不存在返回 undefined）。
+ *  name 缺省 = 主服务 ellm-proxy；管理服务传 MANAGER_APP_NAME */
+export async function findApp(name = APP_NAME) {
+  const list = (await pm2cb("list")) || [];
+  return list.find((p) => p.name === name);
+}
+
+/** 启动探活：轮询 status 至 online（每 pollMs 一次，全程打进度点）——比固定等待更快成功
+ *  （online 即返回），也能容忍慢启动（默认 15s 上限，固定 1.5s 在慢机器上会误报）；errored/stopped
+ *  提前失败（脚本秒崩不必等满超时）。failHint 是失败文案的线索部分（文案是契约的一部分）。
+ *  quiet = 静默轮询不打点（多服务并行等待时输出由调用方合并，避免多组进度点交错）。 */
+export async function waitOnline(name, failHint, { timeoutMs = 15000, pollMs = 300, quiet = false } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  let last = null;
+  for (;;) {
+    last = await findApp(name);
+    const status = last?.pm2_env?.status;
+    if (status === "online") {
+      if (!quiet) endOk();
+      return last;
+    }
+    if (status === "errored" || status === "stopped" || Date.now() >= deadline) {
+      if (!quiet) endFail();
+      throw new Error(`${name} 启动后状态异常（${status ?? "已退出"}）。${failHint}`);
+    }
+    if (!quiet) dot();
+    await new Promise((r) => setTimeout(r, pollMs));
+  }
+}
+
+/** 安全 dump（start/stop 成功后调用）：pm2 不允许 dump 空列表会报错——此时说明全部进程已删，
+ *  清掉旧 dump.pm2 与滚动备份 dump.pm2.bak（resurrect 无 dump.pm2 时会回落 .bak），防止开机
+ *  resurrect 把已停止的服务拉起来 */
+export async function safeDump() {
+  try {
+    await pm2cb("dump");
+  } catch {
+    try {
+      rmSync(join(homedir(), ".pm2", "dump.pm2"), { force: true });
+      rmSync(join(homedir(), ".pm2", "dump.pm2.bak"), { force: true });
+    } catch {
+      /* 清理失败不影响 stop 语义 */
+    }
+  }
+}
+
+/** 当前包内 pm2 CLI 入口绝对路径（autostart cmd 用；resolve 兼容 npm 全局平铺与 pnpm 布局） */
+export function pm2BinJs() {
+  const pm2PkgRoot = dirname(createRequire(import.meta.url).resolve("pm2/package.json"));
+  return join(pm2PkgRoot, "bin", "pm2");
+}
+
+/** 清洗 pm2 子进程透传的 env：pm2 托管的进程自身 env 带 pm_id/pm2_env/unique_id 等
+ *  内部变量与 bash 注入的 `_`，原样传回 pm2.start 会污染新进程注册——实测主服务
+ *  （name=ellm-proxy）被注册成管理服务的名字，导致探活误判「已退出」。
+ *  黑名单清洗实测仍有漏网（多键组合触发），故改用白名单：
+ *  只透传主服务必需的业务键（ELLM_* 前缀，含 ELLM_PORT / ELLM_MANAGER_PORT）与 Windows node 运行所需的系统键。
+ *  PM2_HOME 保留（pm2 API 连接 daemon 需要，主服务自身不用）。 */
+const PM2_ENV_WHITELIST = new Set([
+  "PATH",
+  "SYSTEMROOT",
+  "WINDIR",
+  "SYSTEMDRIVE",
+  "COMSPEC",
+  "PATHEXT",
+  "OS",
+  "TEMP",
+  "TMP",
+  "USERPROFILE",
+  "HOMEDRIVE",
+  "HOMEPATH",
+  "APPDATA",
+  "LOCALAPPDATA",
+  "PROGRAMDATA",
+  "PROGRAMFILES",
+  "ALLUSERSPROFILE",
+  "PUBLIC",
+  "USERNAME",
+  "USERDOMAIN",
+  "COMPUTERNAME",
+  "NUMBER_OF_PROCESSORS",
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "NO_PROXY",
+]);
+
+export function sanitizePm2Env(env) {
+  const out = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (key === "PM2_HOME" || key.startsWith("ELLM_")) out[key] = value;
+    else if (PM2_ENV_WHITELIST.has(key.toUpperCase())) out[key] = value;
+  }
+  return out;
+}