ellm-proxy 0.0.2 → 0.0.6

package/README.md

@@ -1,60 +1,60 @@
-# ellm-proxy
-
-自研 LLM 网关（行为基准 litellm 1.100.0），pm2 后台守护一键启停（跨平台）。主服务（`ellm-proxy`）单进程提供网关与管理台 API；管理服务（`ellm-proxy-manager`，端口 = 主端口 + 1）托管管理界面 web-ui 并反代 `/api/*` 到主服务，主服务停止时仍可远程拉起。
-
-> 需求决策与架构设计详见 [docs/DESIGN.md](docs/DESIGN.md)。
-
-- `/v1/*` — LLM 网关端点（OpenAI / Anthropic 协议互转，多供应商路由、压缩、鉴权）
-- `/api/*` — 管理台 API（登录鉴权、配置热更新、用量/日志；主服务全局 CORS，供独立部署的 web-ui 跨源调用）
-- `http://127.0.0.1:<主端口+1>/` — 管理界面（manager 托管 web-ui，同源反代 `/api/*`）
-
-## 安装
-
-要求 Node.js **>= 22.13.0**（内置 `node:sqlite`，无需 flag）。
-
-```bash
-npm i -g ellm-proxy
-```
-
-## 使用
-
-```bash
-ellm-proxy -h             # 查看帮助
-ellm-proxy start          # pm2 后台守护启动（崩溃自动重启；首次自动创建配置）
-ellm-proxy stop           # 停止服务
-ellm-proxy restart        # 重启（先 stop 后 start，保证最新参数生效，选项同 start）
-ellm-proxy autostart on   # Windows 开机自启（注册登录触发的计划任务）
-ellm-proxy autostart off  # 关闭开机自启
-ellm-proxy config         # 显示配置文件路径
-```
-
-`start/stop/restart` 基于包内自带的 pm2（局部安装，进程名 `ellm-proxy`）：服务由 pm2 守护常驻，关闭终端不影响运行，崩溃自动重启（封顶 10 次，防端口占用无限循环），日志写 `<appDir>/logs/`。服务要求的 Node ≥22.13 由 CLI 解析（当前 node 满足则直接用，否则经 get-node 自动下载一次并缓存），终端默认 node 版本无关。start/stop 成功后自动 `pm2 dump`，可随时用 `pm2 resurrect` 恢复。Windows、Linux、macOS 均可用；运行状态用 `pm2 ls` 查看。
-
-**开机自启（跨平台）**：`ellm-proxy autostart on` 注册登录触发的自启项（内容为 `pm2 resurrect`），三平台均无需管理员权限——Windows 写启动文件夹 `.cmd`、macOS 写 LaunchAgent（`launchctl load`）、Linux 写 systemd user unit（`systemctl --user enable`，WSL/无 systemd 环境会报错提示）；`autostart off` 移除。
-
-## 运行时布局（默认 `~/.ellm-proxy/`，均可被环境变量覆盖）
-
-| 内容 | 默认路径 | 环境变量覆盖 |
-| --- | --- | --- |
-| 配置文件 | `~/.ellm-proxy/ellm.config.json` | `ELLM_CONFIG`（或 `start --config <path>`） |
-| 数据目录（sqlite 日志/缓存） | `~/.ellm-proxy/data/` | `ELLM_DATA_DIR`（或 `start --data-dir <path>`） |
-| 应用目录（配置/数据基准） | `~/.ellm-proxy/` | `ELLM_APP_DIR`（CLI 按 `--working-dir` 自动注入） |
-| web-ui 静态资源 | 包内 `dist/web-ui/`（manager 托管） | `ELLM_WEBUI_DIR`（可选覆盖；manager 按自身位置自动推导） |
-| 运行日志 | `~/.ellm-proxy/logs/` | `start --working-dir <path>`（见 `ellm-proxy -h`） |
-
-所有路径均支持相对路径（按当前工作目录展开）与绝对路径。服务端自身不加载任何 `.env` 文件；`ELLM_MASTER_KEY` 等环境变量直接在会话中导出即可。
-
-首次执行 `ellm-proxy start` 会自动创建示例配置，之后两种方式修改：
-
-1. 直接编辑配置文件；
-2. 启动服务后访问管理界面 `http://127.0.0.1:<主端口+1>/` 在线修改（实时热更新）。
-
-其他环境变量：`ELLM_PORT`（网关监听端口，或 `start --port`；管理服务固定 `ELLM_PORT + 1`，可用 `ELLM_MANAGER_PORT` 覆盖）、`HOST`（监听地址）、`ELLM_MASTER_KEY`（网关主密钥，低于配置文件 `masterKey` 字段）。启动时端口若被占用会自动顺延到下一个空闲端口（仅本次运行生效，不改配置文件），顺延结果会打印在启动摘要中。
-
-## 本地开发（仓库内）
-
-本包是 `ellm` monorepo 的发布载体：发布版 `dist/server.js` 由 `scripts/build-server.mjs` 从 `backend` 源码直接构建（esbuild 插件在构建期把路径模块替换为 `release/runtime-dir.ts` 包模式实现，backend 源码保持单模式零分支），`web-ui` 产物由 `pnpm build:web` 生成后拷入 `dist/web-ui/`（manager 托管）：
-
-```bash
-pnpm pack:proxy   # 构建 web-ui → 构建发布版 + 聚合 → npm pack 生成 tgz
-```
+# ellm-proxy
+
+自研 LLM 网关（行为基准 litellm 1.100.0），pm2 后台守护一键启停（跨平台）。主服务（`ellm-proxy`）单进程提供网关与管理台 API；管理服务（`ellm-proxy-manager`，端口 = 主端口 + 1）托管管理界面 web-ui 并反代 `/api/*` 到主服务，主服务停止时仍可远程拉起。
+
+> 需求决策与架构设计详见 [docs/DESIGN.md](docs/DESIGN.md)。
+
+- `/v1/*` — LLM 网关端点（OpenAI / Anthropic 协议互转，多供应商路由、压缩、鉴权）
+- `/api/*` — 管理台 API（登录鉴权、配置热更新、用量/日志；主服务全局 CORS，供独立部署的 web-ui 跨源调用）
+- `http://127.0.0.1:<主端口+1>/` — 管理界面（manager 托管 web-ui，同源反代 `/api/*`）
+
+## 安装
+
+要求 Node.js **>= 22.13.0**（内置 `node:sqlite`，无需 flag）。
+
+```bash
+npm i -g ellm-proxy
+```
+
+## 使用
+
+```bash
+ellm-proxy -h             # 查看帮助
+ellm-proxy start          # pm2 后台守护启动（崩溃自动重启；首次自动创建配置）
+ellm-proxy stop           # 停止服务
+ellm-proxy restart        # 重启（先 stop 后 start，保证最新参数生效，选项同 start）
+ellm-proxy autostart on   # Windows 开机自启（注册登录触发的计划任务）
+ellm-proxy autostart off  # 关闭开机自启
+ellm-proxy config         # 显示配置文件路径
+```
+
+`start/stop/restart` 基于包内自带的 pm2（局部安装，进程名 `ellm-proxy`）：服务由 pm2 守护常驻，关闭终端不影响运行，崩溃自动重启（封顶 10 次，防端口占用无限循环），日志写 `<appDir>/logs/`。服务要求的 Node ≥22.13 由 CLI 解析（当前 node 满足则直接用，否则经 get-node 自动下载一次并缓存），终端默认 node 版本无关。start/stop 成功后自动 `pm2 dump`，可随时用 `pm2 resurrect` 恢复。Windows、Linux、macOS 均可用；运行状态用 `pm2 ls` 查看。
+
+**开机自启（跨平台）**：`ellm-proxy autostart on` 注册登录触发的自启项（内容为 `pm2 resurrect`），三平台均无需管理员权限——Windows 写启动文件夹 `.cmd`、macOS 写 LaunchAgent（`launchctl load`）、Linux 写 systemd user unit（`systemctl --user enable`，WSL/无 systemd 环境会报错提示）；`autostart off` 移除。
+
+## 运行时布局（默认 `~/.ellm-proxy/`，均可被环境变量覆盖）
+
+| 内容 | 默认路径 | 环境变量覆盖 |
+| --- | --- | --- |
+| 配置文件 | `~/.ellm-proxy/ellm.config.json` | `ELLM_CONFIG`（或 `start --config <path>`） |
+| 数据目录（sqlite 日志/缓存） | `~/.ellm-proxy/data/` | `ELLM_DATA_DIR`（或 `start --data-dir <path>`） |
+| 应用目录（配置/数据基准） | `~/.ellm-proxy/` | `ELLM_APP_DIR`（CLI 按 `--working-dir` 自动注入） |
+| web-ui 静态资源 | 包内 `dist/web-ui/`（manager 托管） | `ELLM_WEBUI_DIR`（可选覆盖；manager 按自身位置自动推导） |
+| 运行日志 | `~/.ellm-proxy/logs/` | `start --working-dir <path>`（见 `ellm-proxy -h`） |
+
+所有路径均支持相对路径（按当前工作目录展开）与绝对路径。服务端自身不加载任何 `.env` 文件；`ELLM_MASTER_KEY` 等环境变量直接在会话中导出即可。
+
+首次执行 `ellm-proxy start` 会自动创建示例配置，之后两种方式修改：
+
+1. 直接编辑配置文件；
+2. 启动服务后访问管理界面 `http://127.0.0.1:<主端口+1>/` 在线修改（实时热更新）。
+
+其他环境变量：`ELLM_PORT`（网关监听端口，或 `start --port`；管理服务固定 `ELLM_PORT + 1`，可用 `ELLM_MANAGER_PORT` 覆盖）、`HOST`（监听地址）、`ELLM_MASTER_KEY`（网关主密钥，低于配置文件 `masterKey` 字段）。启动时端口若被占用会自动顺延到下一个空闲端口（仅本次运行生效，不改配置文件），顺延结果会打印在启动摘要中。
+
+## 本地开发（仓库内）
+
+本包是 `ellm` monorepo 的发布载体：发布版 `dist/server.js` 由 `scripts/build-server.mjs` 从 `backend` 源码直接构建（esbuild 插件在构建期把路径模块替换为 `release/runtime-dir.ts` 包模式实现，backend 源码保持单模式零分支），`web-ui` 产物由 `pnpm build:web` 生成后拷入 `dist/web-ui/`（manager 托管）：
+
+```bash
+pnpm pack:proxy   # 构建 web-ui → 构建发布版 + 聚合 → npm pack 生成 tgz
+```

package/bin/commands/autostart.js

@@ -1,213 +1,37 @@
-// autostart on|off 命令（跨平台开机自启，登录时触发，均无需管理员权限）：
-//   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）
-// 三者内容一致：登录时执行 <nodePath> <包内 pm2 bin> resurrect（恢复最后一次 pm2 dump）。
-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 { resolveInterpreter } from "../../utils/interpreter.js";
-import { pm2BinJs } from "../../utils/pm2.js";
-import { defaultAppDir } from "../../utils/paths.js";
-
-const AUTOSTART_CMD = "ellm-proxy-autostart.cmd"; // Windows
-const PLIST_LABEL = "com.ellm-proxy.autostart"; // macOS
-const LINUX_UNIT = "ellm-proxy.service"; // Linux
-
-/** 用户启动文件夹（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));
-  });
-}
-
-// —— Windows：启动文件夹 .cmd ————————————————————————————————————————
-
-function windowsPaths() {
-  return { itemPath: join(windowsStartupDir(), AUTOSTART_CMD) };
-}
-
-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 } = windowsPaths();
-  writeFileSync(itemPath, body, "utf-8");
-}
-
-async function windowsOff() {
-  const { itemPath } = windowsPaths();
-  if (!existsSync(itemPath)) return false;
-  rmSync(itemPath, { force: true });
-  return true;
-}
-
-// —— macOS：LaunchAgent plist ——————————————————————————————————————————
-
-function darwinPaths() {
-  return { itemPath: join(homedir(), "Library", "LaunchAgents", `${PLIST_LABEL}.plist`) };
-}
-
-async function darwinOn(nodePath, pm2Js) {
-  const { itemPath } = darwinPaths();
-  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}"`);
-  }
-}
-
-async function darwinOff() {
-  const { itemPath } = darwinPaths();
-  if (!existsSync(itemPath)) return false;
-  await runExit("launchctl", ["unload", itemPath]);
-  rmSync(itemPath, { force: true });
-  return true;
-}
-
-// —— Linux：systemd user unit ——————————————————————————————————————————
-
-function linuxPaths() {
-  return { itemPath: join(homedir(), ".config", "systemd", "user", LINUX_UNIT) };
-}
-
-async function linuxOn(nodePath, pm2Js) {
-  const { itemPath } = linuxPaths();
-  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}`,
-    );
-  }
-}
-
-async function linuxOff() {
-  const { itemPath } = linuxPaths();
-  if (!existsSync(itemPath)) return false;
-  await runExit("systemctl", ["--user", "disable", LINUX_UNIT]); // 容错：未启用过时报错不影响删除
-  rmSync(itemPath, { force: true });
-  await runExit("systemctl", ["--user", "daemon-reload"]);
-  return true;
-}
-
-// —— 命令入口：平台分支 ————————————————————————————————————————————————
-
-async function autostartOn() {
-  const nodePath = await resolveInterpreter();
-  const pm2Js = pm2BinJs();
-  let itemPath;
-  switch (platform()) {
-    case "win32":
-      itemPath = windowsPaths().itemPath;
-      await windowsOn(nodePath, pm2Js);
-      break;
-    case "darwin":
-      itemPath = darwinPaths().itemPath;
-      await darwinOn(nodePath, pm2Js);
-      break;
-    case "linux":
-      itemPath = linuxPaths().itemPath;
-      await linuxOn(nodePath, pm2Js);
-      break;
-    default:
-      throw new Error(`暂不支持的平台: ${platform()}。可改用 pm2 自带的 pm2 startup。`);
-  }
-  console.log("开机自启已开启（登录时触发）：");
-  console.log(`  自启项 : ${itemPath}（pm2 resurrect 恢复服务）`);
-  console.log("  禁用方式 : ellm-proxy autostart off");
-}
-
-async function autostartOff() {
-  let removed;
-  switch (platform()) {
-    case "win32":
-      removed = await windowsOff();
-      break;
-    case "darwin":
-      removed = await darwinOff();
-      break;
-    case "linux":
-      removed = await linuxOff();
-      break;
-    default:
-      throw new Error(`暂不支持的平台: ${platform()}。可改用 pm2 自带的 pm2 startup。`);
-  }
-  if (!removed) {
-    console.log("未找到自启项（可能未开启开机自启），无需操作。");
-    return;
-  }
-  console.log("开机自启已关闭（自启项已移除）。");
-}
-
-export function register(cli, run) {
-  cli
-    .command(
-      "autostart <action>",
-      "开机自启（登录时触发）：on=注册自启项（Win 启动文件夹/mac LaunchAgent/Linux systemd user），off=移除",
-    )
-    .action((action) => {
-      if (action !== "on" && action !== "off") {
-        console.error(`未知参数: ${action}（用法: ellm-proxy autostart on|off）`);
-        process.exit(1);
-      }
-      return run(action === "on" ? autostartOn : autostartOff);
-    });
-}
+// autostart on|off 命令（CLI 薄壳）：平台实现与状态探测在 utils/autostart.js（被管理服务复用），
+// 本文件只做命令装配与人读输出。
+import { autostartStatus, enableAutostart, disableAutostart } from "../../utils/autostart.js";
+
+async function autostartOn() {
+  const { itemPath } = await enableAutostart();
+  console.log("开机自启已开启（登录时触发）：");
+  console.log(`  自启项 : ${itemPath}（pm2 resurrect 恢复服务）`);
+  console.log("  禁用方式 : ellm-proxy autostart off");
+}
+
+async function autostartOff() {
+  const { removed } = await disableAutostart();
+  if (!removed) {
+    console.log("未找到自启项（可能未开启开机自启），无需操作。");
+    return;
+  }
+  console.log("开机自启已关闭（自启项已移除）。");
+}
+
+export function register(cli, run) {
+  cli
+    .command(
+      "autostart <action>",
+      "开机自启（登录时触发）：on=注册自启项（Win 启动文件夹/mac LaunchAgent/Linux systemd user），off=移除",
+    )
+    .action((action) => {
+      if (action !== "on" && action !== "off") {
+        console.error(`未知参数: ${action}（用法: ellm-proxy autostart on|off）`);
+        process.exit(1);
+      }
+      return run(action === "on" ? autostartOn : autostartOff);
+    });
+}
+
+// 状态探测保留导出（潜在 CLI status 输出用；当前 manager 走 utils 直连）
+export { autostartStatus };

package/bin/commands/config.js

@@ -1,8 +1,8 @@
-// config 命令：显示配置文件路径（不存在时自动创建示例配置）。
-import { ensureConfig } from "../../utils/paths.js";
-
-export function register(cli) {
-  cli.command("config", "显示配置文件路径（不存在时自动创建示例配置）").action((opts) => {
-    console.log(ensureConfig(opts.config));
-  });
-}
+// config 命令：显示配置文件路径（不存在时自动创建示例配置）。
+import { ensureConfig } from "../../utils/paths.js";
+
+export function register(cli) {
+  cli.command("config", "显示配置文件路径（不存在时自动创建示例配置）").action((opts) => {
+    console.log(ensureConfig(opts.config));
+  });
+}

package/bin/commands/pm2.js

@@ -1,28 +1,28 @@
-// pm2 透传命令：ellm-proxy pm2 <任意 pm2 参数>（如 list/ls/logs/monit/describe/flush）。
-// 用包内局部 pm2 执行，用户无需自装全局 pm2；stdio 直接继承，logs/monit 等交互命令可实时输出、
-// Ctrl-C 退出。透传参数不经 cac 解析（在 CLI 入口先于 cac 拦截），pm2 的 -- 选项原样可达。
-import { spawn } from "node:child_process";
-import { pm2BinJs } from "../../utils/pm2.js";
-
-/** 以包内 pm2 CLI 执行任意参数（node 版本无关紧要：pm2 bin 脚本兼容；daemon 连接与 interpreter 无关） */
-export async function doPassthrough(args) {
-  if (args.length === 0) {
-    args = ["list"]; // 无参数 = 默认展示进程列表
-  }
-  return new Promise((resolve, reject) => {
-    const child = spawn(process.execPath, [pm2BinJs(), ...args], { stdio: "inherit", shell: false });
-    child.on("error", reject);
-    // pm2 退出码原样透传；exit 回调内 process.exit 结束进程（promise 永不 resolve）
-    child.on("exit", (code) => process.exit(code ?? 1));
-  });
-}
-
-export function register(cli, run) {
-  // cac 仅声明命令用于 -h 展示；实际执行走 CLI 入口的 pm2 拦截（保证 pm2 选项不被 cac 解析吞掉）
-  cli
-    .command(
-      "pm2 [args...]",
-      "透传执行包内 pm2 任意子命令（如 list/ls/logs/monit/describe/flush；pm2 的 -- 选项原样透传）",
-    )
-    .action(() => {});
-}
+// pm2 透传命令：ellm-proxy pm2 <任意 pm2 参数>（如 list/ls/logs/monit/describe/flush）。
+// 用包内局部 pm2 执行，用户无需自装全局 pm2；stdio 直接继承，logs/monit 等交互命令可实时输出、
+// Ctrl-C 退出。透传参数不经 cac 解析（在 CLI 入口先于 cac 拦截），pm2 的 -- 选项原样可达。
+import { spawn } from "node:child_process";
+import { pm2BinJs } from "../../utils/pm2.js";
+
+/** 以包内 pm2 CLI 执行任意参数（node 版本无关紧要：pm2 bin 脚本兼容；daemon 连接与 interpreter 无关） */
+export async function doPassthrough(args) {
+  if (args.length === 0) {
+    args = ["list"]; // 无参数 = 默认展示进程列表
+  }
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [pm2BinJs(), ...args], { stdio: "inherit", shell: false });
+    child.on("error", reject);
+    // pm2 退出码原样透传；exit 回调内 process.exit 结束进程（promise 永不 resolve）
+    child.on("exit", (code) => process.exit(code ?? 1));
+  });
+}
+
+export function register(cli, run) {
+  // cac 仅声明命令用于 -h 展示；实际执行走 CLI 入口的 pm2 拦截（保证 pm2 选项不被 cac 解析吞掉）
+  cli
+    .command(
+      "pm2 [args...]",
+      "透传执行包内 pm2 任意子命令（如 list/ls/logs/monit/describe/flush；pm2 的 -- 选项原样透传）",
+    )
+    .action(() => {});
+}