ellm-proxy 0.0.1

package/utils/port.js

@@ -0,0 +1,35 @@
+// 端口可用性探测：试绑 listen（全部成功=空闲，任一 EADDRINUSE 等错误=占用），供 service.js 启动前预算端口。
+// Windows 的 wildcard/specific 共存语义（bind 0.0.0.0 与 bind 127.0.0.1 可同端口并存，实测）会让单维度
+// 探测漏报"bind 成功但 IPv4 流量被占用者抢走"的假活，故主服务探测 0.0.0.0 + 127.0.0.1 双维度；
+// IPv6-only 占用极罕见（漏报由 pm2 探活失败兜底）。管理服务固定监听 127.0.0.1 → 探测 ["127.0.0.1"]。
+// 探测与实际 bind 之间存在毫秒级竞态窗口（TOCTOU），极端时被抢占 → 仍由 pm2 探活失败兜底。
+import { createServer } from "node:net";
+
+/** 单 host 试绑：成功=空闲（等 close 回调 socket 释放后才返回 true，避免误占探测端口） */
+function isHostFree(port, host) {
+  return new Promise((resolve) => {
+    const srv = createServer();
+    srv.once("error", () => resolve(false)); // EADDRINUSE / EACCES 等一律视为不可用
+    srv.once("listening", () => srv.close(() => resolve(true)));
+    srv.listen(port, host);
+  });
+}
+
+/** 端口是否空闲：逐个 host 试绑，全部成功才空闲（hosts 传数组多维探测，传字符串退化为单 host） */
+export function isPortFree(port, hosts = ["0.0.0.0", "127.0.0.1"]) {
+  const list = Array.isArray(hosts) ? hosts : [hosts];
+  return (async () => {
+    for (const host of list) {
+      if (!(await isHostFree(port, host))) return false;
+    }
+    return true;
+  })();
+}
+
+/** 从 start 起向上找第一个空闲端口（含 start；maxTry 个内全占返回 0，由调用方决定兜底行为） */
+export async function findFreePort(start, hosts = ["0.0.0.0", "127.0.0.1"], maxTry = 100) {
+  for (let p = start; p < start + maxTry; p++) {
+    if (await isPortFree(p, hosts)) return p;
+  }
+  return 0;
+}

package/utils/service.js

@@ -0,0 +1,189 @@
+// 服务进程管理核心：start/stop（restart = stop + start 由调用方组合，保证最新参数生效）。
+// 被 CLI（bin/commands/service.js）与管理服务（manager/index.js）复用。
+// 本模块只做进程编排并返回数据，人读文案/摘要由调用方输出；错误以 throw 抛出（文案是契约的一部分）。
+// start 流程：配置自愈 → env 注入（含端口预算：主服务 ELLM_PORT / 管理服务 ELLM_MANAGER_PORT = 主端口+1，
+//   占用时自动顺延空闲端口）→ 两个服务一并提交 pm2（数组形式）→ 并行轮询探活 → dump；
+//   管理服务已在线（部分恢复场景）则只补启主服务。
+// 全程分步输出进度（「→ 启动 ...」+ 探活进度点），等待期间不留静默空窗。
+import { readFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { APP_NAME, MANAGER_APP_NAME, pkgRoot, defaultAppDir, ensureConfig, configPath } from "./paths.js";
+import { withPm2, pm2cb, findApp, waitOnline, safeDump, sanitizePm2Env } from "./pm2.js";
+import { resolveInterpreter } from "./interpreter.js";
+import { isPortFree, findFreePort } from "./port.js";
+import { ICONS, say, warn, begin, endOk, endFail } from "./ui.js";
+
+/** 管理服务脚本（随包分发，start 时随主服务一并 pm2 托管） */
+const MANAGER_INDEX_JS = join(pkgRoot, "manager", "index.js");
+const DEFAULT_MANAGER_PORT = 29771; // 主端口无法解析时 manager 的最终兜底（默认网关 29770 + 1，与 manager/index.js 缺省一致）
+
+/** 端口解析口径：portEnv（ELLM_PORT env）> 配置文件 port 字段 */
+export function resolvePort(portEnv, configFile) {
+  let port = Number(portEnv) || 0;
+  if (!port) {
+    try {
+      port = JSON.parse(readFileSync(configFile, "utf-8")).port || 0;
+    } catch {
+      port = 0;
+    }
+  }
+  return port;
+}
+
+/** 网关地址与配置文件定位（harness 代理指向目标）：ELLM_PORT env / 配置文件 port，与 start 命令端口口径一致 */
+export function resolveGatewayBase(configOverride) {
+  const configFile = configPath(configOverride);
+  const port = resolvePort(process.env.ELLM_PORT, configFile);
+  return { base: `http://127.0.0.1:${port}`, configFile };
+}
+
+/** 启动服务（CLI restart 与管理服务 restart 复用）：
+ *  配置自愈 → env 注入 → 两服务一并提交 pm2（数组形式）→ 并行轮询探活 → dump，
+ *  管理服务已在线则只补启主服务。全程分步进度输出。返回 { proc, managerProc, appDir, config } 供调用方输出摘要。 */
+export async function doStart(opts) {
+  say(`正在启动 ${APP_NAME}（pm2 后台守护）...`, ICONS.rocket);
+  const config = ensureConfig(opts.config);
+  const appDir = opts.workingDir || defaultAppDir;
+  mkdirSync(join(appDir, "logs"), { recursive: true });
+
+  // server 端读取的路径基变量：显式值优先（CLI 参数 > 会话已有 > 默认推导）
+  process.env.ELLM_APP_DIR = process.env.ELLM_APP_DIR ?? appDir;
+  process.env.ELLM_CONFIG = config;
+  if (opts.dataDir) process.env.ELLM_DATA_DIR = opts.dataDir;
+
+  // 端口基准预算：主服务 = --port > ELLM_PORT env > 配置文件 port 字段（与 server 端读取口径一致）。
+  // 占用探测与注入在 withPm2 内做（管理服务是否在线影响其端口预算，findApp 需要 pm2 连接）。
+  const port = resolvePort(opts.port ?? process.env.ELLM_PORT, config);
+
+  const interpreter = await resolveInterpreter();
+  const script = opts.serverJs || join(pkgRoot, "dist", "server.js");
+  // ELLM_SERVER_JS：管理服务 restart 主服务时按同一路径重启，保证 --server-js 等参数不漂移
+  process.env.ELLM_SERVER_JS = script;
+
+  return withPm2(async () => {
+    if (await findApp()) {
+      throw new Error(`${APP_NAME} 已在运行。请先停止: ellm-proxy stop`);
+    }
+
+    // 主服务端口：基准被占（其他应用 / 孤儿进程）则自动顺延到空闲端口（默认 0.0.0.0 + 127.0.0.1 双维度，
+    // 见 utils/port.js），避免把注定冲突的端口交给 pm2 后陷入崩溃循环；顺延仅本次运行生效，不改配置文件。
+    let mainPort = port;
+    if (mainPort && !(await isPortFree(mainPort))) {
+      const wanted = mainPort;
+      mainPort = (await findFreePort(mainPort + 1)) || mainPort;
+      warn(
+        mainPort === wanted
+          ? `端口 ${wanted} 已被占用且未找到空闲端口，仍按原端口启动（可能失败，请释放端口或修改配置）`
+          : `端口 ${wanted} 已被占用，主服务自动改用空闲端口 ${mainPort}（仅本次运行生效，不改配置文件）`,
+      );
+    }
+    if (mainPort) process.env.ELLM_PORT = String(mainPort);
+
+    // 管理服务随主服务一并托管（活在外面：主服务被 stop/重启后由它执行拉起；resurrect 时一并恢复）。
+    // 已在线则跳过启动（部分恢复场景幂等），并保持其现有端口（重新预算换端口会造成访问地址漂移）。
+    const existingManager = await findApp(MANAGER_APP_NAME);
+    let managerPort = 0;
+    if (existingManager) {
+      const runningPort = Number(existingManager.pm2_env?.env?.ELLM_MANAGER_PORT);
+      if (runningPort) process.env.ELLM_MANAGER_PORT = String(runningPort);
+      managerPort = Number(process.env.ELLM_MANAGER_PORT) || 0;
+      say(`管理服务 ${MANAGER_APP_NAME} 已在线（端口 ${managerPort || "?"}），跳过启动`, ICONS.skip);
+    } else {
+      // 管理服务端口 = 主服务端口 + 1（用户显式设置过 ELLM_MANAGER_PORT 则尊重）；
+      // 被占则自动顺延（固定监听 127.0.0.1，单维度探测）。探测注入必须在 pm2 start 前，env 随之透传。
+      managerPort = Number(process.env.ELLM_MANAGER_PORT) || (mainPort ? mainPort + 1 : 0);
+      if (managerPort && !(await isPortFree(managerPort, ["127.0.0.1"]))) {
+        const wanted = managerPort;
+        managerPort = (await findFreePort(managerPort + 1, ["127.0.0.1"])) || managerPort;
+        warn(
+          managerPort === wanted
+            ? `管理服务端口 ${wanted} 已被占用且未找到空闲端口，仍按原端口启动（可能失败，可用 ELLM_MANAGER_PORT 调整）`
+            : `管理服务端口 ${wanted} 已被占用，自动改用空闲端口 ${managerPort}（仅本次运行生效）`,
+        );
+      }
+      if (managerPort) process.env.ELLM_MANAGER_PORT = String(managerPort);
+    }
+
+    // 两份 pm2 start 配置（单启主服务 / 双启一并提交两条路径共用）；env 在端口注入后快照
+    const mainOpts = {
+      name: APP_NAME,
+      script,
+      interpreter,
+      cwd: appDir,
+      // 崩溃自动重启但封顶，防端口占用/配置损坏陷入无限重启
+      autorestart: true,
+      max_restarts: 10,
+      restart_delay: 3000,
+      merge_logs: true,
+      out_file: join(appDir, "logs", "ellm-out.log"),
+      error_file: join(appDir, "logs", "ellm-err.log"),
+      env: sanitizePm2Env(process.env),
+    };
+    const managerOpts = {
+      name: MANAGER_APP_NAME,
+      script: MANAGER_INDEX_JS,
+      interpreter,
+      cwd: appDir,
+      autorestart: true,
+      max_restarts: 10,
+      restart_delay: 3000,
+      merge_logs: true,
+      out_file: join(appDir, "logs", "manager-out.log"),
+      error_file: join(appDir, "logs", "manager-err.log"),
+      env: sanitizePm2Env(process.env),
+    };
+
+    if (existingManager) {
+      // 仅补启主服务（单服务，保持打点进度样式）
+      begin(`启动主服务 ${APP_NAME}${mainPort ? ` (端口 ${mainPort})` : ""} `);
+      await pm2cb("start", mainOpts);
+      const proc = await waitOnline(
+        APP_NAME,
+        `最可能是端口被占用或配置无效，请查看日志: ${join(appDir, "logs", "ellm-err.log")}`,
+      );
+      await safeDump();
+      return { proc, managerProc: existingManager, appDir, config };
+    }
+
+    // 双启：两个服务一并提交 pm2（数组形式，daemon 逐个拉起），等待期并行轮询、输出合并为一行。
+    // 主服务失败时管理服务往往已在线——其职责正是远程拉起主服务，故失败后不回收进程，文案给出重试路径。
+    begin(
+      `启动 ${APP_NAME}${mainPort ? ` (端口 ${mainPort})` : ""} + ${MANAGER_APP_NAME}${managerPort ? ` (端口 ${managerPort})` : ""} ...`,
+    );
+    await pm2cb("start", [mainOpts, managerOpts]);
+    const [mainRes, managerRes] = await Promise.allSettled([
+      waitOnline(APP_NAME, `最可能是端口被占用或配置无效，请查看日志: ${join(appDir, "logs", "ellm-err.log")}`, {
+        quiet: true,
+      }),
+      waitOnline(
+        MANAGER_APP_NAME,
+        `最可能是管理服务端口被占用（端口 ${process.env.ELLM_MANAGER_PORT || DEFAULT_MANAGER_PORT}，可用 ELLM_MANAGER_PORT 调整），请查看日志: ${join(appDir, "logs", "manager-err.log")}`,
+        { quiet: true },
+      ),
+    ]);
+    const failures = [mainRes, managerRes].filter((r) => r.status === "rejected");
+    if (failures.length) {
+      endFail();
+      throw new Error(failures.map((f) => f.reason?.message ?? String(f.reason)).join("；"));
+    }
+    endOk();
+
+    // dump 进程列表（~/.pm2/dump.pm2），供开机自启 pm2 resurrect 恢复（主服务 + 管理服务一并恢复）
+    await safeDump();
+    return { proc: mainRes.value, managerProc: managerRes.value, appDir, config };
+  });
+}
+
+/** 停止服务：主服务与管理服务一并删除（幂等）。返回 { main, manager } 表示各自此前是否在运行。 */
+export async function doStop() {
+  return withPm2(async () => {
+    const proc = await findApp();
+    const managerProc = await findApp(MANAGER_APP_NAME);
+    if (!proc && !managerProc) return { main: false, manager: false };
+    // 先删管理服务（避免它在主服务停止后仍对外提供启停接口造成状态误判），再删主服务
+    if (managerProc) await pm2cb("delete", MANAGER_APP_NAME);
+    if (proc) await pm2cb("delete", APP_NAME);
+    await safeDump();
+    return { main: !!proc, manager: !!managerProc };
+  });
+}

package/utils/ui.js

@@ -0,0 +1,59 @@
+// 统一输出工具：emoji 图标 + 进度点 + 摘要字段行，CLI（bin/）与管理服务（manager/）共用。
+// 图标约定：一律选无 VS16（变体选择符）的码点——🖥️/🛠️ 等带 VS16 的在不同终端宽度不稳，实测弃用。
+// 摘要字段行按「两空格缩进 + 图标 + 四字标签 + 三空格 + 内容」对齐。
+export const ICONS = {
+  rocket: "🚀", // 开始
+  pending: "⏳", // 进行中（探活等待等）
+  success: "✅", // 成功完成
+  warn: "❗", // 警告（端口顺延等降级提示）
+  skip: "⏭️", // 已在线跳过
+  running: "🟢", // 服务运行中
+  stopped: "🛑", // 已停止
+  idle: "💤", // 未在运行
+  error: "❌", // 失败
+  gateway: "🌐", // 网关端点
+  webui: "💻", // 管理界面
+  api: "🔧", // 管理服务接口
+  folder: "📂", // 应用目录
+  status: "📋", // 运行状态
+  question: "❓", // 未知（端口未知等兜底展示）
+};
+
+/** 一行信息（icon 省略 = 纯文本行） */
+export function say(text, icon) {
+  console.log(icon ? `${icon} ${text}` : text);
+}
+
+/** 警告行 */
+export function warn(text) {
+  say(text, ICONS.warn);
+}
+
+/** 错误行（stderr，供 CLI 统一错误出口） */
+export function error(text) {
+  console.error(`${ICONS.error} ${text}`);
+}
+
+/** 行内片段（不换行）：⏳ 前缀 + 文本，供后续追加进度点 / 行尾状态；text 需自带尾部空格或省略号 */
+export function begin(text) {
+  process.stdout.write(`${ICONS.pending} ${text}`);
+}
+
+/** 进度点（探活轮询期间追加） */
+export function dot() {
+  process.stdout.write(".");
+}
+
+/** 行尾成功 / 失败标记并换行（与 begin/dot 配套） */
+export function endOk() {
+  process.stdout.write(" ✓\n");
+}
+
+export function endFail() {
+  process.stdout.write(" ✗\n");
+}
+
+/** 摘要字段行：缩进 + 图标 + 标签 + 内容 */
+export function field(icon, label, value) {
+  console.log(`  ${icon} ${label}   ${value}`);
+}