dsh-plugin-litellm-bridge 0.0.0-stage → 2.0.2

package/dsh-plugin-litellm-bridge/lib/gateway-supervisor.js

@@ -0,0 +1,518 @@
+/**
+ * LiteLLM 网关生命周期托管
+ * ============================================================================
+ *
+ * 目标：网关跟着 DSH 一起活、一起死，不当常驻后台服务。
+ *   - DSH 启动 → 插件 apply() 时检查网关；没起就拉起来
+ *   - DSH 退出 → 插件卸载（ctx.effect 清理）时把网关收掉
+ *
+ * 【为什么不在外面手动起】
+ *   用户明确反馈：网关一直在后台运行没什么作用，还要每次手动重启。
+ *   所以改成「插件托管子进程」：进程随 DSH 生灭。
+ *
+ * 【关键设计】
+ *   1. 先探测再启动 —— 如果用户已经手动开了网关（或别的 DSH 实例开着），
+ *      绝不重复启动，只记下「不是自己起的」，退出时也不杀它。
+ *      这一点很重要：多开 DSH 时互相杀进程会造成莫名其妙的断线。
+ *   2. ownChild 标记 —— 只有自己拉起的才负责杀。
+ *   3. 优雅终止 → 强杀兜底 —— 先 SIGTERM，超时再 SIGKILL。
+ *   4. 不阻塞 DSH 启动 —— 启动放后台跑，健康检查用轮询，最多等 N 秒。
+ *   5. 任何异常都不能让插件挂掉 —— 整个模块 fail-soft。
+ */
+
+import { spawn } from 'node:child_process';
+import { createConnection } from 'node:net';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** 默认网关地址。 */
+export const DEFAULT_GATEWAY_URL = 'http://127.0.0.1:4000';
+
+/**
+ * 从网关地址里拆出 host / port。
+ * 解析失败就退回 127.0.0.1:4000。
+ */
+export function parseGatewayUrl(url) {
+  try {
+    const u = new URL(String(url || DEFAULT_GATEWAY_URL));
+    const port = Number(u.port) || (u.protocol === 'https:' ? 443 : 80);
+    return { host: u.hostname || '127.0.0.1', port, protocol: u.protocol };
+  } catch {
+    return { host: '127.0.0.1', port: 4000, protocol: 'http:' };
+  }
+}
+
+/** 探测网关是否已在监听（HTTP 探活，失败再退回 TCP 探测）。 */
+export async function isGatewayAlive(url, timeoutMs = 1500) {
+  const base = String(url || DEFAULT_GATEWAY_URL).replace(/\/+$/, '');
+  // 1) HTTP 探活
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+      const res = await fetch(`${base}/health/liveliness`, { signal: ctrl.signal });
+      if (res.ok) return true;
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch {
+    /* 落到 TCP 探测 */
+  }
+  // 2) TCP 探测（网关在启动中时会拒绝 HTTP，但端口已监听）
+  const { host, port } = parseGatewayUrl(base);
+  return await tcpProbe(host, port, timeoutMs);
+}
+
+/** 朴素 TCP 连通性探测（不依赖外部包）。 */
+function tcpProbe(host, port, timeoutMs = 1500) {
+  return new Promise((resolvePromise) => {
+    let done = false;
+    let socket;
+    const finish = (v) => {
+      if (done) return;
+      done = true;
+      try {
+        socket?.destroy?.();
+      } catch {
+        /* ignore */
+      }
+      resolvePromise(v);
+    };
+    try {
+      socket = createConnection({ host, port });
+      socket.setTimeout(timeoutMs);
+      socket.once('connect', () => finish(true));
+      socket.once('timeout', () => finish(false));
+      socket.once('error', () => finish(false));
+    } catch {
+      finish(false);
+    }
+  });
+}
+
+/**
+ * 解析 bash 可执行文件路径。
+ *
+ * Windows 上 `bash` 通常不在 PATH 里（Git Bash 装在 D:\Git\bin\bash.exe 之类），
+ * 直接 spawn('bash') 会 ENOENT。这里按顺序探测常见位置；
+ * 非 Windows 直接用 'bash'（在 PATH 里）。
+ */
+export function resolveBash() {
+  if (process.platform !== 'win32') return 'bash';
+  const candidates = [
+    process.env.LITELLM_BRIDGE_BASH,
+    'D:/Git/bin/bash.exe',
+    'C:/Program Files/Git/bin/bash.exe',
+    'C:/Program Files (x86)/Git/bin/bash.exe',
+    'D:/Program Files/Git/bin/bash.exe',
+    // WSL / 其他
+    'C:/Windows/System32/bash.exe',
+  ];
+  for (const c of candidates) {
+    try {
+      if (c && existsSync(c)) return c;
+    } catch {
+      /* ignore */
+    }
+  }
+  // 兜底：交给 PATH 解析（若真没有，会在 spawn 时报错并被 catch 住）
+  return 'bash';
+}
+
+/**
+ * 定位 litellm-gateway 目录。
+ *
+ * 关键难点：插件被 pnpm 装进 `<profile>/node_modules/dsh-plugin-litellm-bridge`，
+ * 而 litellm-gateway/ 是仓库里的**兄弟目录**，从安装位置往上找是找不到的。
+ * 所以按以下顺序尝试：
+ *   1. 显式配置（config.gatewayDir / LITELLM_BRIDGE_DIR）—— 最可靠
+ *   2. 从插件源目录（开发态：repo/dsh-plugin-litellm-bridge/lib）往上找兄弟
+ *   3. 从本机 profile 的 pnpm 记录 / 常见仓库路径猜
+ *   4. 常见绝对路径兜底
+ */
+export function findGatewayDir(explicitDir) {
+  const candidates = [];
+  const push = (p) => {
+    if (p && !candidates.includes(p)) candidates.push(p);
+  };
+
+  // 1) 显式指定
+  push(explicitDir);
+  push(process.env.LITELLM_BRIDGE_DIR);
+
+  // 2) 开发态：本文件在 <repo>/dsh-plugin-litellm-bridge/lib/
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    push(resolve(here, '..', '..', 'litellm-gateway'));
+  } catch {
+    /* ignore */
+  }
+
+  // 3) 安装态：pnpm 用 file: 链接时，node_modules 里可能是 symlink，
+  //    realpath 会指回仓库；这里用 fileURLToPath 已解析，再补一层向上探测。
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    let cur = here;
+    for (let i = 0; i < 6; i++) {
+      cur = resolve(cur, '..');
+      push(join(cur, 'litellm-gateway'));
+      push(join(cur, 'dsh-fallback-auto-pool-arch', 'litellm-gateway'));
+    }
+  } catch {
+    /* ignore */
+  }
+
+  // 4) 常见绝对路径兜底
+  push('D:/AI sandbox/dsh-sandbox/dsh-fallback-auto-pool-arch/litellm-gateway');
+
+  for (const c of candidates) {
+    try {
+      if (existsSync(join(c, 'start-gateway.sh'))) return c;
+    } catch {
+      /* ignore */
+    }
+  }
+  return null;
+}
+
+/**
+ * 网关托管器。
+ *
+ * @param {object} opts
+ * @param {string} opts.gatewayUrl   网关地址（用于探活与端口）
+ * @param {string} [opts.envFile]    .env 路径
+ * @param {object} [opts.logger]     { info, warn, debug }
+ * @param {number} [opts.startTimeoutMs] 等待网关就绪的上限
+ */
+export class GatewaySupervisor {
+  constructor({ gatewayUrl, envFile, gatewayDir, logger, startTimeoutMs = 45000, onLog } = {}) {
+    this.gatewayUrl = gatewayUrl || DEFAULT_GATEWAY_URL;
+    this.envFile = envFile || '';
+    this.gatewayDir = gatewayDir || '';
+    this.logger = logger || {};
+    this.startTimeoutMs = startTimeoutMs;
+    /**
+     * 【需求7】异常退出告警回调。
+     * 网关进程意外死掉时，必须能在插件的日志面板里看到 —— 否则用户只会
+     * 觉得「降级没生效」，却不知道是网关根本没在跑。
+     */
+    this.onLog = typeof onLog === 'function' ? onLog : null;
+
+    /** 自己拉起的子进程；为 null 表示没管过或不是自己起的 */
+    this.child = null;
+    /** 是否拥有生命周期（决定退出时要不要杀） */
+    this.owns = false;
+    /** 启动失败原因（供 UI 显示） */
+    this.lastError = null;
+    this.starting = false;
+    this._disposed = false;
+    /** 【需求7】生命周期状态：stopped | starting | running | error */
+    this.state = 'stopped';
+    /** 最近一次异常退出信息（UI 直接展示） */
+    this.lastExit = null;
+  }
+
+  _log(lvl, msg) {
+    try {
+      this.logger?.[lvl]?.(`[litellm-bridge/gateway] ${msg}`);
+    } catch { /* ignore */ }
+  }
+
+  /** 写一条「网关生命周期」事件到插件日志面板（需求7）。 */
+  _event(level, message) {
+    try {
+      this.onLog?.({ level, message, at: new Date().toISOString() });
+    } catch { /* 日志失败绝不影响主流程 */ }
+  }
+
+  /**
+   * 确保网关可用：
+   *   - 活着 → 什么都不做，owns=false
+   *   - 没活 → 拉起，owns=true
+   * 任何失败都只记录、不抛。
+   */
+  async ensureRunning() {
+    if (this._disposed) return { running: false, started: false, error: 'supervisor disposed' };
+    if (this.starting) return { running: false, started: false, error: 'already starting' };
+
+    // 1) 先看是不是已经活着
+    if (await isGatewayAlive(this.gatewayUrl)) {
+      this._log('info', `网关已在线（外部启动，不接管生命周期）: ${this.gatewayUrl}`);
+      this.owns = false;
+      this.state = 'running';
+      this._event('info', '网关已在线（外部启动，本插件不接管其生命周期）');
+      return { running: true, started: false, owned: false };
+    }
+
+    // 2) 需要拉起
+    const dir = findGatewayDir(this.gatewayDir);
+    if (!dir) {
+      this.lastError = '找不到 litellm-gateway 目录（缺 start-gateway.sh）';
+      this.state = 'error';
+      this._log('warn', this.lastError);
+      this._event('error', this.lastError);
+      return { running: false, started: false, error: this.lastError };
+    }
+
+    const { port } = parseGatewayUrl(this.gatewayUrl);
+    this.starting = true;
+    this.state = 'starting';
+    this._event('info', `正在启动网关（端口 ${port}）…`);
+    try {
+      const child = spawn(
+        resolveBash(),
+        [
+          join(dir, 'start-gateway.sh'),
+          '--port', String(port),
+        ],
+        {
+          cwd: dir,
+          env: {
+            ...process.env,
+            ...(this.envFile ? { LITELLM_BRIDGE_ENV: this.envFile } : {}),
+            PYTHONUTF8: '1',
+            PYTHONIOENCODING: 'utf-8',
+          },
+          // 脱离父进程组：DSH 崩溃时网关也能被我们显式收掉，而不是跟着乱死
+          detached: false,
+          stdio: ['ignore', 'pipe', 'pipe'],
+          shell: false,
+        },
+      );
+
+      this.child = child;
+      this.owns = true;
+
+      // 把网关日志转进 DSH 日志。
+      // 【注意】LiteLLM 用 --detailed_debug 时会狂刷 DEBUG 行（每条都是 JSON），
+      // 直接转发会把 DSH 日志淹掉。所以：
+      //   - 只取每个 chunk 的前若干行
+      //   - 跳过 DEBUG 级与明显的噪音行
+      //   - 单行截断
+      const isNoise = (line) =>
+        /"level":\s*"DEBUG"/.test(line) ||
+        /checking potential_model_names/.test(line) ||
+        /added\/updated model=/.test(line) ||
+        /^\s*$/.test(line);
+      let relayed = 0;
+      const relay = (stream, lvl) => {
+        stream?.setEncoding?.('utf8');
+        stream?.on?.('data', (buf) => {
+          if (relayed > 200) return; // 硬上限，防止极端情况刷屏
+          const text = String(buf).trim();
+          if (!text) return;
+          for (const line of text.split('\n').slice(0, 4)) {
+            if (isNoise(line)) continue;
+            relayed += 1;
+            this._log(lvl, line.slice(0, 240));
+            if (relayed > 200) break;
+          }
+        });
+      };
+      relay(child.stdout, 'debug');
+      relay(child.stderr, 'warn');
+
+      child.once('exit', (code, signal) => {
+        this.child = null;
+        this.owns = false;
+        const abnormal = !this._disposed && (code !== 0 && code !== null);
+        this.lastExit = { code, signal, at: new Date().toISOString(), abnormal };
+        if (this._disposed) {
+          this.state = 'stopped';
+          this._log('info', `网关进程已退出 code=${code} signal=${signal}（插件卸载，正常）`);
+          return;
+        }
+        if (abnormal) {
+          // 【需求7】异常退出必须告警：否则用户只会觉得「降级没生效」
+          this.state = 'error';
+          this.lastError = `网关异常退出（code=${code}${signal ? `, signal=${signal}` : ''}）`;
+          this._log('warn', this.lastError);
+          this._event('error', this.lastError);
+        } else {
+          this.state = 'stopped';
+          this._log('info', `网关进程退出 code=${code} signal=${signal}`);
+          this._event('warn', `网关进程已停止（code=${code}）`);
+        }
+      });
+      child.once('error', (err) => {
+        this.lastError = `启动失败: ${err?.message || err}`;
+        this.state = 'error';
+        this._log('warn', this.lastError);
+        this._event('error', this.lastError);
+      });
+
+      // 3) 等就绪（轮询）
+      const deadline = Date.now() + this.startTimeoutMs;
+      while (Date.now() < deadline) {
+        if (await isGatewayAlive(this.gatewayUrl, 1200)) {
+          this._log('info', `网关已就绪: ${this.gatewayUrl}`);
+          this.state = 'running';
+          this.lastError = null;
+          this._event('info', '网关已就绪（由本插件托管，退出 DSH 时自动关闭）');
+          return { running: true, started: true, owned: true };
+        }
+        await new Promise((r) => setTimeout(r, 1200));
+      }
+
+      this.lastError = `网关在 ${Math.round(this.startTimeoutMs / 1000)}s 内未就绪`;
+      this.state = 'error';
+      this._log('warn', this.lastError);
+      this._event('error', this.lastError);
+      return { running: false, started: true, owned: true, error: this.lastError };
+    } catch (err) {
+      this.lastError = String(err?.message || err);
+      this.state = 'error';
+      this._log('warn', `拉起网关失败: ${this.lastError}`);
+      this._event('error', `拉起网关失败: ${this.lastError}`);
+      return { running: false, started: false, error: this.lastError };
+    } finally {
+      this.starting = false;
+    }
+  }
+
+  /**
+   * 【需求3】重启网关以加载新下发的 config.yaml。
+   *
+   * 为什么要重启而不是热重载：本机 LiteLLM 1.108.3 实测 /config/reload 是 404，
+   * /config/update 需要 PostgreSQL（SQLite 硬失败）。而 start-gateway.sh
+   * 里已有「config.yaml 已存在则跳过生成」的逻辑 —— 所以我们直接写
+   * config.yaml，再重启进程即可让新链路生效，无需任何数据库。
+   */
+  async restart() {
+    const wasOwned = this.owns;
+    const killed = await this.stop({ force: true });
+    if (!killed.stopped && !killed.reason) {
+      // 停不掉就别硬起，避免端口冲突造成「看起来在跑其实没跑」
+      return { running: false, restarted: false, error: killed.error || '停止网关失败' };
+    }
+    // stop() 会把 _disposed 置 true，重启前必须复位
+    this._disposed = false;
+    this.state = 'stopped';
+    this._event('info', wasOwned ? '网关已停止，准备以新配置重启…' : '网关未运行，直接以新配置启动…');
+    const r = await this.ensureRunning();
+    return { ...r, restarted: Boolean(r.running) };
+  }
+
+  /**
+   * 停止网关（只在「自己起的」时候动手）。
+   *
+   * 【关键坑 · 实测两轮才解决】
+   * start-gateway.sh 是 bash 脚本，末尾 `exec litellm ...` —— 真正监听端口的是
+   * Python 进程。而 kill(bash) / taskkill /T 都**杀不掉**它：
+   *   - bash 已经被 exec 替换成 litellm，父子关系断裂
+   *   - Windows 上 taskkill /T 只顺着当前手里的 PID 树走，抓不到
+   * 实测结果：stop() 返回 stopped:true 但端口仍占着。
+   *
+   * 所以最终方案：**按端口反查占用进程并结束**。
+   *   Windows → netstat -ano 找 LISTENING 的 PID → taskkill /F /PID
+   *   POSIX   → lsof -ti:<port> 或 fuser
+   * 这是唯一可靠的办法（网关自己占着端口，按端口找必然命中）。
+   */
+  async stop({ force = false } = {}) {
+    this._disposed = true;
+    const child = this.child;
+    if (!child || !this.owns) {
+      this._log('debug', '网关不是本实例启动的，退出时不接管');
+      this.state = 'stopped';
+      return { stopped: false, reason: 'not-owned' };
+    }
+    const pid = child.pid;
+    const { port } = parseGatewayUrl(this.gatewayUrl);
+    try {
+      this._log('info', `正在停止网关（port=${port}, shellPid=${pid}）…`);
+
+      // 1) 先给壳一个 SIGTERM（快速路径）
+      try { child.kill('SIGTERM'); } catch { /* ignore */ }
+
+      // 2) 按端口反查真正占用的进程并结束（关键步骤）
+      await this._killByPort(port);
+
+      // 3) 轮询等端口释放
+      let free = await this._waitPortFree(force ? 8000 : 15000);
+      if (!free) {
+        this._log('warn', '端口仍被占用，二次强制清理');
+        await this._killByPort(port, true);
+        free = await this._waitPortFree(5000);
+      }
+
+      this.child = null;
+      this.owns = false;
+      const stillAlive = await isGatewayAlive(this.gatewayUrl, 800);
+      this._log(free && !stillAlive ? 'info' : 'warn',
+        free && !stillAlive ? '网关已停止' : '网关仍在运行（请手动检查）');
+      return { stopped: free && !stillAlive, stillAlive };
+    } catch (err) {
+      this._log('warn', `停止网关失败: ${err?.message || err}`);
+      return { stopped: false, error: String(err?.message || err) };
+    }
+  }
+
+  /** Windows: netstat 找监听该端口的 PID 并 taskkill；POSIX: lsof/fuser。 */
+  async _killByPort(port, force = false) {
+    const run = (cmd, args) =>
+      new Promise((resolve) => {
+        try {
+          const p = spawn(cmd, args, { windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] });
+          let out = '';
+          p.stdout?.setEncoding?.('utf8');
+          p.stdout?.on?.('data', (d) => { out += d; });
+          p.once('exit', () => resolve(out));
+          p.once('error', () => resolve(''));
+          setTimeout(() => resolve(out), 4000);
+        } catch {
+          resolve('');
+        }
+      });
+
+    if (process.platform === 'win32') {
+      const out = await run('netstat', ['-ano', '-p', 'TCP']);
+      const pids = new Set();
+      for (const line of out.split('\n')) {
+        // 形如:  TCP    0.0.0.0:4000    0.0.0.0:0    LISTENING    12345
+        if (!/LISTENING/i.test(line)) continue;
+        if (!new RegExp(`[.:]${port}\\s`).test(line)) continue;
+        const m = line.trim().match(/(\d+)\s*$/);
+        if (m) pids.add(m[1]);
+      }
+      for (const p of pids) {
+        this._log('debug', `结束占用 ${port} 的进程 pid=${p}`);
+        await run('taskkill', ['/PID', p, '/T', '/F']);
+      }
+      return pids.size;
+    }
+
+    // POSIX
+    const lsof = await run('lsof', ['-ti', `:${port}`]);
+    const pids = lsof.split('\n').map((s) => s.trim()).filter(Boolean);
+    for (const p of pids) {
+      this._log('debug', `结束占用 ${port} 的进程 pid=${p}`);
+      await run('kill', [force ? '-9' : '-15', p]);
+    }
+    return pids.length;
+  }
+
+  /** 轮询直到端口不再响应（网关真的停了）。 */
+  async _waitPortFree(timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (!(await isGatewayAlive(this.gatewayUrl, 800))) return true;
+      await new Promise((r) => setTimeout(r, 400));
+    }
+    return false;
+  }
+
+  /** 当前状态（给 UI 用）。 */
+  status() {
+    return {
+      url: this.gatewayUrl,
+      owned: this.owns,
+      running: Boolean(this.child) && !this.child.killed,
+      starting: this.starting,
+      lastError: this.lastError,
+      /** 【需求7】stopped | starting | running | error */
+      state: this.state,
+      lastExit: this.lastExit,
+    };
+  }
+}