ellm-proxy 0.0.1

package/manager/api/harness/index.js

@@ -0,0 +1,118 @@
+// harness 代理开关聚合：Claude Code / Codex CLI / DeepSeek Harness 流量指向本机 ellm-proxy 网关。
+//   纯开关实现：claude-code.js（~/.claude/settings.json）/ codex.js（~/.codex/config.toml）/
+//   dsh.js（~/.dsh/settings.yaml + ~/.dsh/.credentials.yaml）/ backup.js（共用备份还原）
+//   createHarnessApp = HTTP 路由子应用（挂载于 /harness）：状态查询 + 开关切换（含 masterKey 校验与提示文案）
+import { Hono } from "hono";
+import { readFileSync } from "node:fs";
+import { resolveGatewayBase } from "../../../utils/service.js";
+import { claudeCodeStatus, claudeCodeEnable, claudeCodeDisable } from "./claude-code.js";
+import { codexStatus, codexEnable, codexDisable } from "./codex.js";
+import { dshStatus, dshEnable, dshDisable } from "./dsh.js";
+
+/** 配置文件顶层 masterKey（Claude Code 代理的 AUTH_TOKEN 取值；网关侧用它做鉴权） */
+function readMasterKey(configFile) {
+  try {
+    return JSON.parse(readFileSync(configFile, "utf-8")).masterKey || "";
+  } catch {
+    return "";
+  }
+}
+
+/** harness 开关子应用（挂载于 /harness）：GET / · POST /claude-code · POST /codex · POST /dsh（body {enabled}） */
+export function createHarnessApp({ startOpts }) {
+  const app = new Hono();
+
+  // GET /harness：三个开关状态
+  app.get("/", (c) => {
+    const { base } = resolveGatewayBase(startOpts.config);
+    return c.json({ ok: true, claudeCode: claudeCodeStatus(base), codex: codexStatus(), dsh: dshStatus(base), gatewayBase: base });
+  });
+
+  /** 读 body 并校验 enabled；合法返回 boolean，非法返回 400 Response（调用方直接 return 该响应） */
+  const requireEnabled = async (c) => {
+    let enabled;
+    try {
+      enabled = (await c.req.json())?.enabled;
+    } catch {
+      return c.json({ ok: false, error: "请求体不是合法 JSON" }, 400);
+    }
+    if (typeof enabled !== "boolean") {
+      return c.json({ ok: false, error: 'body 需为 {"enabled": true|false}' }, 400);
+    }
+    return enabled;
+  };
+
+  app.post("/claude-code", async (c) => {
+    const enabled = await requireEnabled(c);
+    if (enabled instanceof Response) return enabled;
+    const { base, configFile } = resolveGatewayBase(startOpts.config);
+    if (enabled) {
+      const masterKey = readMasterKey(configFile);
+      if (!masterKey) {
+        return c.json(
+          {
+            ok: false,
+            error: `配置未设置 masterKey，Claude Code 代理无法鉴权。请先在配置文件中设置 masterKey: ${configFile}`,
+          },
+          400,
+        );
+      }
+      claudeCodeEnable({ gatewayBase: base, token: masterKey });
+      return c.json({
+        ok: true,
+        claudeCode: true,
+        file: "~/.claude/settings.json",
+        note: "已备份原文件为 settings.json.ellm-bak，重启 Claude Code 会话后生效",
+      });
+    }
+    const changed = claudeCodeDisable(base);
+    return c.json({ ok: true, claudeCode: false, changed, note: changed ? "已从备份还原" : "原本未开启，无操作" });
+  });
+
+  app.post("/codex", async (c) => {
+    const enabled = await requireEnabled(c);
+    if (enabled instanceof Response) return enabled;
+    const { base, configFile } = resolveGatewayBase(startOpts.config);
+    if (enabled) {
+      codexEnable({ gatewayBase: base });
+      const masterKey = readMasterKey(configFile);
+      return c.json({
+        ok: true,
+        codex: true,
+        file: "~/.codex/config.toml",
+        note: masterKey
+          ? `已备份原文件为 config.toml.ellm-bak；请设置环境变量 ELLM_PROXY_API_KEY=${masterKey}（Codex 以 env_key 读取鉴权）`
+          : "已备份原文件为 config.toml.ellm-bak；请设置环境变量 ELLM_PROXY_API_KEY（网关未配 masterKey 时取值任意）",
+      });
+    }
+    const changed = codexDisable();
+    return c.json({ ok: true, codex: false, changed, note: changed ? "已从备份还原" : "原本未开启，无操作" });
+  });
+
+  app.post("/dsh", async (c) => {
+    const enabled = await requireEnabled(c);
+    if (enabled instanceof Response) return enabled;
+    const { base, configFile } = resolveGatewayBase(startOpts.config);
+    const masterKey = readMasterKey(configFile);
+    if (enabled) {
+      dshEnable({ gatewayBase: base, masterKey });
+      return c.json({
+        ok: true,
+        dsh: true,
+        file: "~/.dsh/settings.yaml",
+        note: masterKey
+          ? "已写入 settings.yaml（llm-deepseek.baseURL）与 .credentials.yaml（refs.DEEPSEEK_API_KEY），原文件备份为 *.ellm-bak。注意：进程环境里已设 DEEPSEEK_API_KEY 时其优先级更高，需自行改用网关 masterKey；模型请在 dsh 内选择与网关部署名一致的模型"
+          : "已写入 settings.yaml 与 .credentials.yaml（网关未配 masterKey，密钥为占位值即可放行），原文件备份为 *.ellm-bak。模型请在 dsh 内选择与网关部署名一致的模型",
+      });
+    }
+    const changed = dshDisable(base, masterKey);
+    return c.json({ ok: true, dsh: false, changed, note: changed ? "已从备份还原（或移除本开关写入的字段）" : "原本未开启，无操作" });
+  });
+
+  return app;
+}
+
+// 纯开关函数同时聚合导出（供不经过 HTTP 的调用方直接使用）
+export * from "./claude-code.js";
+export * from "./codex.js";
+export * from "./dsh.js";

package/manager/api/service.js

@@ -0,0 +1,157 @@
+// 主服务进程控制 api 子应用：状态查询与启停。
+// 注意 stop 语义 = 只停主服务（与 CLI ellm-proxy stop 的全停语义不同）——
+// 管理服务若自杀，再无人能远程拉起主服务。
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import { Hono } from "hono";
+import { APP_NAME, MANAGER_APP_NAME } from "../../utils/paths.js";
+import { withPm2, findApp, pm2cb, safeDump } from "../../utils/pm2.js";
+import { doStart, resolveGatewayBase, resolvePort } from "../../utils/service.js";
+
+// 本文件在 manager/api/ 下，包根为上两级
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/** ellm-proxy 进程状态（pm2 视角） */
+async function statusPayload(startOpts) {
+  const proc = await withPm2(() => findApp());
+  const { base } = resolveGatewayBase(startOpts.config);
+  return {
+    running: !!proc,
+    pid: proc?.pid ?? null,
+    pm2Status: proc?.pm2_env?.status ?? null,
+    uptime: proc?.pm2_env?.pm_uptime ?? null,
+    gatewayBase: base,
+  };
+}
+
+/** pm2 依赖树内的 pidusage（realpath 穿透 pnpm 符号链接）：pm2 守护进程自身的内存/CPU 采样 */
+function loadPidusage() {
+  const pm2PkgJson = realpathSync(join(pkgRoot, "node_modules", "pm2", "package.json"));
+  return createRequire(pm2PkgJson)("pidusage");
+}
+
+/** 统一行形状：role = daemon | manager | main（前端按 main 判定可操作行） */
+function row(role, { pid = null, status = "stopped", port = null, startedAt = null, memory = null, cpu = null, restarts = null }) {
+  return {
+    role,
+    pid,
+    status,
+    port,
+    address: port ? `http://127.0.0.1:${port}` : null,
+    startedAt,
+    memory,
+    cpu,
+    restarts,
+  };
+}
+
+/** pm2 守护进程行：PID 读 PM2_HOME/pm2.pid（文件只在 daemon 启动时写，mtime 即启动时刻）；
+ *  内存/CPU 用 pidusage 采样（pm2 jlist 不含 daemon 自身） */
+async function daemonRow() {
+  const pm2Home = process.env.PM2_HOME || join(homedir(), ".pm2");
+  const pidFile = join(pm2Home, "pm2.pid");
+  let pid = null;
+  let startedAt = null;
+  try {
+    pid = Number(readFileSync(pidFile, "utf8").trim()) || null;
+    startedAt = statSync(pidFile).mtimeMs;
+  } catch {
+    /* 无 pm2.pid = daemon 未运行 */
+  }
+  if (!pid) return row("daemon");
+  let memory = null;
+  let cpu = null;
+  try {
+    const stat = await loadPidusage()(pid);
+    memory = stat.memory ?? null;
+    cpu = stat.cpu != null ? Math.round(stat.cpu * 10) / 10 : null;
+  } catch {
+    /* pid 文件存在但进程已死（采样 reject）：按未运行处理 */
+    pid = null;
+  }
+  return row("daemon", { pid, status: pid ? "online" : "stopped", port: null, startedAt, memory, cpu });
+}
+
+/** pm2 托管进程行：monit（内存/CPU，pm2 周期采样）+ pm_uptime（启动时刻）+ restart_time */
+function appRow(proc, role, { port }) {
+  if (!proc) return row(role);
+  const env = proc.pm2_env ?? {};
+  const monit = proc.monit ?? {};
+  return row(role, {
+    pid: proc.pid ?? null,
+    status: env.status ?? "unknown",
+    port: port ?? null,
+    startedAt: env.pm_uptime ?? null,
+    memory: monit.memory ?? null,
+    cpu: monit.cpu != null ? Math.round(monit.cpu * 10) / 10 : null,
+    restarts: env.restart_time ?? null,
+  });
+}
+
+/** 全进程列表：pm2 守护进程 / 管理服务 / 主服务。
+ *  端口口径：主服务 = pm2 注入的 ELLM_PORT（含占用顺延后的实际值）> env > 配置文件；
+ *  管理服务 = ELLM_MANAGER_PORT env > 主端口 + 1（与 manager/index.js 的预算口径一致）。 */
+async function processesPayload(startOpts) {
+  const list = (await withPm2(() => pm2cb("list"))) || [];
+  const main = list.find((p) => p.name === APP_NAME);
+  const manager = list.find((p) => p.name === MANAGER_APP_NAME);
+  const mainPort =
+    Number(main?.pm2_env?.env?.ELLM_PORT) || resolvePort(process.env.ELLM_PORT, startOpts.config) || null;
+  const managerPort = Number(process.env.ELLM_MANAGER_PORT) || (mainPort ? mainPort + 1 : null);
+  return [
+    await daemonRow(),
+    appRow(manager, "manager", { port: managerPort }),
+    appRow(main, "main", { port: mainPort }),
+  ];
+}
+
+/** 仅停止主服务（管理服务保持存活）；管理服务仍在 dump 列表中，resurrect 后它会先起来继续提供远程启停 */
+async function stopMainOnly() {
+  return withPm2(async () => {
+    const proc = await findApp();
+    if (!proc) return "already-stopped";
+    await pm2cb("delete", APP_NAME);
+    await safeDump();
+    return "stopped";
+  });
+}
+
+/** pm2 启停：start / stop / restart（restart = 停主服务 + start，
+ *  start 时管理服务已在线会被 doStart 的幂等检查跳过） */
+async function runStartStop(action, startOpts) {
+  if (action === "stop") return stopMainOnly();
+  if (action === "start") return doStart(startOpts);
+  await stopMainOnly();
+  await doStart(startOpts);
+}
+
+/** 进程控制子应用（挂载于根路径）：GET /status · GET /processes · POST /start|stop|restart */
+export function createServiceApp({ startOpts }) {
+  const app = new Hono();
+
+  app.get("/status", async (c) => c.json({ ok: true, ...(await statusPayload(startOpts)) }));
+
+  // 全进程列表（三行固定：pm2 守护进程 / 管理服务 / 主服务）；启停操作仍只走
+  // /start|stop|restart 的主服务语义——daemon 与管理服务不允许被远程操控（自杀失联风险）
+  app.get("/processes", async (c) =>
+    c.json({ ok: true, processes: await processesPayload(startOpts) }),
+  );
+
+  app.post("/start", async (c) => {
+    await runStartStop("start", startOpts);
+    return c.json({ ok: true, action: "start" });
+  });
+  app.post("/stop", async (c) => {
+    await runStartStop("stop", startOpts);
+    return c.json({ ok: true, action: "stop" });
+  });
+  app.post("/restart", async (c) => {
+    await runStartStop("restart", startOpts);
+    return c.json({ ok: true, action: "restart" });
+  });
+
+  return app;
+}

package/manager/index.js

@@ -0,0 +1,170 @@
+// ellm-proxy 管理服务入口（独立常驻脚本）：随 `ellm-proxy start` 一并由 pm2 托管（name=ellm-proxy-manager）；
+// 也可手动 `node manager/index.js` 运行。本文件 = 创建 app（中间件 + api 聚合挂载）+ 启动 HTTP 服务；
+// 各 api 域实现在 api/ 下：service.js（进程控制，命名对齐 backend/src/api/service.ts）、harness/（代理开关域）。
+//
+// 为什么独立于 backend：ellm-proxy 与 backend 同进程，进程自杀后管理台与转发层同时失联，
+// 无法返回操作结果——启停必须由活在外面的本服务执行。
+//
+// 管理界面托管：本服务同进程托管 web-ui 构建产物（根路径 /，hash 路由），并反代 /api/* 到主服务——
+// web-ui 全部接口（/api/* 管理台 + /status /restart /harness 等进程/开关域）同源可达，config.js 留空零配置。
+//
+// 接口（CORS 全放开，均返回 {ok, ...} 或 {ok:false, error}）：
+//   GET  /                    web-ui 管理界面（静态托管，产物缺失时仅告警跳过）
+//   GET  /api/*               反代主服务管理台 API（端口 = ELLM_PORT env > 配置文件 port，每请求解析）
+//   GET  /status                ellm-proxy 运行状态（running/pid/status/uptime/网关端口）
+//   GET  /processes             全进程列表（pm2 守护进程/管理服务/主服务：状态/PID/端口/内存/CPU/运行时长）
+//   POST /start | /stop | /restart   pm2 启动/停止/重启 ellm-proxy（复用 utils/service.js，含探活）
+//   GET  /harness               Claude Code / Codex / DeepSeek Harness 代理开关状态
+//   POST /harness/claude-code   body {enabled}；开 = 写 ~/.claude/settings.json（备份），关 = 还原备份
+//   POST /harness/codex         body {enabled}；开 = 写 ~/.codex/config.toml（备份），关 = 还原备份
+//   POST /harness/dsh           body {enabled}；开 = 写 ~/.dsh/settings.yaml + .credentials.yaml（备份），关 = 还原
+//
+// 配置来源（env 优先，argv 可覆盖，缺省兜底）：
+//   监听端口  ELLM_MANAGER_PORT（doStart 统一预算 = 主服务端口+1）> argv --port > 29771
+//   web-ui 产物 ELLM_WEBUI_DIR（可选覆盖）> 按本文件位置推导：包模式 <pkgRoot>/dist/web-ui → 仓库模式 <repoRoot>/web-ui/dist
+//   主服务参数 与 ellm-proxy start 注入的 env 同源：ELLM_CONFIG / ELLM_DATA_DIR / ELLM_APP_DIR / ELLM_PORT /
+//             ELLM_SERVER_JS（主服务 dist/server.js 路径，restart 重启主服务时使用，保证参数不漂移）
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { proxy } from "hono/proxy";
+import { serve } from "@hono/node-server";
+import { serveStatic } from "@hono/node-server/serve-static";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import mri from "mri";
+import { absolutize } from "../utils/paths.js";
+import { resolveGatewayBase } from "../utils/service.js";
+import { ICONS, say } from "../utils/ui.js";
+import { createServiceApp } from "./api/service.js";
+import { createHarnessApp } from "./api/harness/index.js";
+
+const DEFAULT_SERVER_PORT = 29771; // 手动运行且无 env 时的兜底（默认网关 29770 + 1）
+// 本文件在 manager/ 下，包根为上一级
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+// web-ui 构建产物目录：ELLM_WEBUI_DIR 优先；缺省按本文件位置推导（包模式 dist/web-ui 与 server.js 同级，
+// 仓库模式落到 monorepo 的 web-ui/dist）。启动时判定一次，缺失则跳过静态托管（接口不受影响）。
+const WEBUI_DIST_DIR = process.env.ELLM_WEBUI_DIR
+  ? resolve(process.cwd(), process.env.ELLM_WEBUI_DIR)
+  : ([join(pkgRoot, "dist", "web-ui"), resolve(pkgRoot, "..", "web-ui", "dist")].find((p) =>
+      existsSync(join(p, "index.html")),
+    ) ?? join(pkgRoot, "dist", "web-ui"));
+const HAS_WEBUI = existsSync(join(WEBUI_DIST_DIR, "index.html"));
+
+/** web-ui 管理界面静态托管：/ 出 index.html（hash 路由唯一服务端入口），assets/ 补长缓存头。
+ *  须在 api 聚合与 /api 反代之后注册——serve-static 未命中才放行，不会遮蔽接口。 */
+function registerWebUi(app) {
+  if (!HAS_WEBUI) return;
+  // serve-static 的 root 只接受相对 cwd 的路径：把绝对定位换算成当前 cwd 表达（仓库/发布包/任意 cwd 均成立）
+  const root = relative(process.cwd(), WEBUI_DIST_DIR);
+  app.get("/", async (c) => {
+    try {
+      const buf = await readFile(join(WEBUI_DIST_DIR, "index.html"));
+      return c.body(new Uint8Array(buf), 200, {
+        "Content-Type": "text/html; charset=utf-8",
+        "Cache-Control": "no-cache",
+      });
+    } catch {
+      return c.text("Not Found", 404);
+    }
+  });
+  app.use("/*", (c, next) => {
+    if (c.req.path === "/") return next(); // 根路径由上面的 serveIndex 处理
+    return serveStatic({
+      root,
+      onFound: (_p, ctx) => {
+        if (ctx.req.path.startsWith("/assets/")) ctx.header("Cache-Control", "public, max-age=31536000, immutable");
+      },
+    })(c, next);
+  });
+}
+
+/** 创建管理服务 app：CORS 全放开 + api 聚合挂载 + /api 反代主服务 + web-ui 静态托管 + 统一 404/500 */
+function createApp({ startOpts }) {
+  const app = new Hono();
+
+  // CORS 全放开（OPTIONS 预检由中间件自动处理）
+  app.use("*", cors());
+
+  // api 聚合：进程控制（GET /status · POST /start|stop|restart）与 harness 开关（GET /harness · POST /harness/claude-code|codex|dsh）
+  app.route("/", createServiceApp({ startOpts }));
+  app.route("/harness", createHarnessApp({ startOpts }));
+
+  // 反代主服务管理台 API（web-ui 同源访问的 /api/*）：端口与 start 口径一致（ELLM_PORT env > 配置文件），
+  // 每请求解析——主服务端口顺延漂移无感知
+  app.all("/api/*", (c) => {
+    const { base } = resolveGatewayBase();
+    const port = Number(new URL(base).port);
+    if (!port) {
+      return c.json(
+        { ok: false, error: "主服务端口无法解析（ELLM_PORT env 与配置文件 port 均缺失），无法转发 /api/*" },
+        502,
+      );
+    }
+    // 目标 URL 必须带上原始查询串：c.req.path 只有 pathname，漏拼 search 会把
+    // ?id=... / ?page=... 等查询参数全部丢掉（主服务按缺参返回 400 或默认分页）
+    const incoming = new URL(c.req.raw.url);
+    return proxy(new URL(incoming.pathname + incoming.search, base), {
+      method: c.req.method,
+      headers: c.req.raw.headers,
+      body: c.req.method === "GET" || c.req.method === "HEAD" ? undefined : c.req.raw.body,
+      duplex: "half", // body 为流时 undici 必需
+    });
+  });
+
+  registerWebUi(app);
+
+  app.notFound((c) =>
+    c.json(
+      {
+        ok: false,
+        error: `未知接口: ${c.req.method} ${c.req.path}（可用: GET /（管理界面）, GET /api/*（反代主服务）, GET /status, GET /processes, POST /start|stop|restart, GET /harness, POST /harness/claude-code|codex|dsh）`,
+      },
+      404,
+    ),
+  );
+  app.onError((err, c) => {
+    console.error(`[ellm-proxy-manager] ${c.req.method} ${c.req.path} 失败:`, err?.message ?? err);
+    return c.json({ ok: false, error: err?.message ?? String(err) }, 500);
+  });
+
+  return app;
+}
+
+async function main() {
+  // argv 解析（mri）：仅 --port（其余主服务参数一律走 env，与 start 注入链同源）
+  const argv = mri(process.argv.slice(2));
+  const listenPort = Number(argv.port) || Number(process.env.ELLM_MANAGER_PORT) || DEFAULT_SERVER_PORT;
+  // 主服务启动参数（start/restart 时透传给 doStart）：ELLM_* env 与 CLI start 注入链同源
+  const startOpts = absolutize({
+    config: process.env.ELLM_CONFIG,
+    dataDir: process.env.ELLM_DATA_DIR,
+    workingDir: process.env.ELLM_APP_DIR,
+    serverJs: process.env.ELLM_SERVER_JS || join(pkgRoot, "dist", "server.js"),
+  });
+
+  const app = createApp({ startOpts });
+
+  const server = serve({ fetch: app.fetch, port: listenPort, hostname: "127.0.0.1" });
+  server.on("error", (err) => {
+    console.error(
+      `错误：管理服务监听 ${listenPort} 失败（${err.code ?? err.message}）${err.code === "EADDRINUSE" ? "，端口被占用" : ""}`,
+    );
+    process.exit(1);
+  });
+
+  say(`ellm-proxy 管理服务已启动: http://127.0.0.1:${listenPort}`, ICONS.rocket);
+  say(
+    HAS_WEBUI
+      ? `   管理界面: http://127.0.0.1:${listenPort}/（web-ui，/api/* 反代主服务）`
+      : `   管理界面未托管：web-ui 构建产物缺失（${WEBUI_DIST_DIR}），仓库根执行 pnpm build:web 后重启本服务`,
+  );
+  say(
+    "   接口: GET /status /processes · POST /start /stop /restart · GET /harness · POST /harness/claude-code /harness/codex /harness/dsh",
+  );
+  say("   CORS 已全放开（仅监听 127.0.0.1，不对外）");
+}
+
+main();

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "ellm-proxy",
+  "version": "0.0.1",
+  "description": "Self-hosted LLM gateway with admin web UI (pm2-managed)",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "bin": {
+    "ellm-proxy": "bin/ellm-proxy.js"
+  },
+  "files": [
+    "bin",
+    "manager",
+    "utils",
+    "dist",
+    "docs",
+    "ellm.config.example.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build-package.mjs",
+    "prepack": "node scripts/build-package.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^22.12.1"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.19.17",
+    "cac": "^6.7.14",
+    "get-node": "^15.0.4",
+    "hono": "^4.13.5",
+    "mri": "^1.2.0",
+    "pm2": "^7.0.4",
+    "smol-toml": "^1.8.0",
+    "yaml": "^2.9.0"
+  }
+}

package/utils/interpreter.js

@@ -0,0 +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;
+}

package/utils/paths.js

@@ -0,0 +1,44 @@
+// 共享常量与路径工具：包根/应用目录常量、配置查找链、首次配置自愈、选项绝对化。
+// 供 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;
+}

package/utils/pm2.js

@@ -0,0 +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;
+}