ellm-proxy 0.0.7 → 0.0.8

package/README.md

@@ -1,12 +1,12 @@
 # ellm-proxy
 
-自研 LLM 网关（行为基准 litellm 1.100.0），pm2 后台守护一键启停（跨平台）。主服务（`ellm-proxy`）单进程提供网关与管理台 API；管理服务（`ellm-proxy-manager`，端口 = 主端口 + 1）托管管理界面 web-ui 并反代 `/api/*` 到主服务，主服务停止时仍可远程拉起。
+自研 LLM 网关（行为基准 litellm 1.100.0），单进程后台常驻一键启停（跨平台，内置进程管理，无 pm2）。单端口提供全部能力：网关、管理台 API 与管理界面同端口（默认 29770）。
 
 > 需求决策与架构设计详见 [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/*`）
+- `/api/*` — 管理台 API（登录鉴权、配置热更新、用量/日志）
+- `http://127.0.0.1:<port>/` — 管理界面（服务进程托管 web-ui，同端口；远程访问靠登录保护）
 
 ## 安装
 
@@ -20,17 +20,28 @@ npm i -g ellm-proxy
 
 ```bash
 ellm-proxy -h             # 查看帮助
-ellm-proxy start          # pm2 后台守护启动（崩溃自动重启；首次自动创建配置）
+ellm-proxy start          # 后台常驻启动（首次自动创建配置）
 ellm-proxy stop           # 停止服务
 ellm-proxy restart        # 重启（先 stop 后 start，保证最新参数生效，选项同 start）
-ellm-proxy autostart on   # Windows 开机自启（注册登录触发的计划任务）
+ellm-proxy（无参数）       # 已运行则显示服务信息，否则启动
+ellm-proxy autostart on   # 开机自启（登录时触发，免管理员权限）
 ellm-proxy autostart off  # 关闭开机自启
 ellm-proxy config         # 显示配置文件路径
+ellm-proxy master-key     # 查看/设置网关主密钥（--random / --clear）
+ellm-proxy account        # 查看/设置管理台登录账号（--reset）
 ```
 
-`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` 查看。
+**进程管理（内置，跨平台）**：CLI 启动时以 detached 方式拉起服务进程并写运行记录 `~/.ellm-proxy/run.json`，探活以「端口 HTTP 可达」为准。服务进程自持崩溃自愈（未捕获异常自动孵化后继进程接管端口，1 分钟窗口封顶 10 次，防端口占用无限循环），日志写 `<appDir>/logs/`。服务要求的 Node ≥22.13 由 CLI 解析（当前 node 满足则直接用，否则经 get-node 自动下载一次并缓存）。Windows、Linux、macOS 均可用；运行状态直接运行 `ellm-proxy`（无参数）查看。
 
-**开机自启（跨平台）**：`ellm-proxy autostart on` 注册登录触发的自启项（内容为 `pm2 resurrect`），三平台均无需管理员权限——Windows 写启动文件夹 `.cmd`、macOS 写 LaunchAgent（`launchctl load`）、Linux 写 systemd user unit（`systemctl --user enable`，WSL/无 systemd 环境会报错提示）；`autostart off` 移除。
+**热重启**：管理台「进程管理」页的重启按钮（或配置变更）触发 self-respawn——服务先孵化新进程接管端口再退出，停机 1~2 秒。
+
+**开机自启（跨平台）**：`ellm-proxy autostart on` 注册登录触发的自启项（内容为直接启动服务，含运行参数 env 快照），三平台均无需管理员权限——Windows 写启动文件夹 `.cmd`、macOS 写 LaunchAgent（`launchctl load`）、Linux 写 systemd user unit（`systemctl --user enable`，WSL/无 systemd 环境会报错提示）；`autostart off` 移除。旧版（≤0.0.7，pm2 resurrect 内容）自启项会在下次 start 时自动迁移重写，旧版 pm2 托管的进程与守护也会被自动清理。
+
+## 自动更新（可选开启）
+
+- **手动更新**：管理台「设置 → 服务与更新」检查并一键更新——服务先回响应再自重启，新进程启动时执行 `npm i -g` 安装并自动换新代码生效（双跳），安装失败自动回滚旧版本继续服务。
+- **自动更新**：看门狗每小时检查 npm 源（默认 npmjs，`ELLM_UPDATE_REGISTRY` 可覆盖），发现新版本自动走同一链路；开关存配置文件顶层 `autoUpdate`。
+- 源码/本地构建运行时更新域自动关闭（仅 npm 全局安装的包支持）。
 
 ## 运行时布局（默认 `~/.ellm-proxy/`，均可被环境变量覆盖）
 
@@ -39,21 +50,28 @@ ellm-proxy config         # 显示配置文件路径
 | 配置文件 | `~/.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 按自身位置自动推导） |
+| web-ui 静态资源 | 包内 `dist/web-ui/`（服务进程托管） | `ELLM_WEBUI_DIR`（可选覆盖） |
 | 运行日志 | `~/.ellm-proxy/logs/` | `start --working-dir <path>`（见 `ellm-proxy -h`） |
+| 运行记录 | `~/.ellm-proxy/run.json` | 随 `ELLM_APP_DIR` |
 
 所有路径均支持相对路径（按当前工作目录展开）与绝对路径。服务端自身不加载任何 `.env` 文件；`ELLM_MASTER_KEY` 等环境变量直接在会话中导出即可。
 
 首次执行 `ellm-proxy start` 会自动创建示例配置，之后两种方式修改：
 
 1. 直接编辑配置文件；
-2. 启动服务后访问管理界面 `http://127.0.0.1:<主端口+1>/` 在线修改（实时热更新）。
+2. 启动服务后访问管理界面 `http://127.0.0.1:29770/` 在线修改（实时热更新）。
+
+其他环境变量：`ELLM_PORT`（服务监听端口，或 `start --port`）、`HOST`（监听地址）、`ELLM_MASTER_KEY`（网关主密钥，低于配置文件 `masterKey` 字段）。启动时端口若被占用会自动顺延到下一个空闲端口（仅本次运行生效，不改配置文件），顺延结果会打印在启动摘要中。
+
+## 从 0.0.7 及更早版本升级
 
-其他环境变量：`ELLM_PORT`（网关监听端口，或 `start --port`；管理服务固定 `ELLM_PORT + 1`，可用 `ELLM_MANAGER_PORT` 覆盖）、`HOST`（监听地址）、`ELLM_MASTER_KEY`（网关主密钥，低于配置文件 `masterKey` 字段）。启动时端口若被占用会自动顺延到下一个空闲端口（仅本次运行生效，不改配置文件），顺延结果会打印在启动摘要中。
+1. `npm i -g ellm-proxy@latest`（或等自动更新）；
+2. 直接 `ellm-proxy start`——旧版 pm2 托管的进程与守护会被自动清理，pm2 自启项自动迁移为直启模式；
+3. 管理台地址从 `http://127.0.0.1:29771/` 变更为 `http://127.0.0.1:29770/`（单端口化，29771 退役）。
 
 ## 本地开发（仓库内）
 
-本包是 `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 托管）：
+本包是 `ellm` monorepo 的发布载体：发布版 `dist/server.js` 与 `dist/cli.js` 由 `scripts/build-server.mjs` / `build-cli.mjs` 从 `server`（原 backend）源码直接构建（esbuild 全量内联，含管理域与 CLI），`web-ui` 产物由 `pnpm build:web` 生成后拷入 `dist/web-ui/`（服务进程托管）：
 
 ```bash
 pnpm pack:proxy   # 构建 web-ui → 构建发布版 + 聚合 → npm pack 生成 tgz

package/bin/ellm-proxy.js

@@ -1,64 +1,3 @@
 #!/usr/bin/env node
-// ellm-proxy CLI 入口（bin，cac 框架）：仅做命令装配，实现在 commands/（命令）与 utils/（共享工具）。
-//
-// 命令：（无参数 = 默认启动）start / stop / restart / pm2 <args...> / autostart on|off / config /
-// master-key / account / -h / --version（选项详见 -h）
-//
-// 运行时布局（默认 ~/.ellm-proxy/，均可被选项/环境变量覆盖）：
-//   配置: --config > ELLM_CONFIG 环境变量 > ~/.ellm-proxy/ellm.config.json（首次自动创建）
-//   数据: ELLM_DATA_DIR 环境变量 > ~/.ellm-proxy/data
-//   日志: <appDir>/logs/ellm-out.log · ellm-err.log（主服务）+ manager-out.log · manager-err.log（管理服务）
-//
-// 进程管理（跨平台，pm2 JS API 封装见 utils/pm2.js，编排核心见 utils/service.js）：
-//   start 会一并托管两个进程——主服务 dist/server.js（name=ellm-proxy）与管理服务 manager/index.js
-//   （name=ellm-proxy-manager，启停/重启主服务 + Claude Code/Codex 代理开关）。
-//   崩溃自动重启、日志落盘、dump/resurrect（开机自启一并恢复）。服务要求的 Node >=22.13.0 通过
-//   interpreter 保证（utils/interpreter.js），pm2 daemon 的 node 版本无关紧要。
-//   start/stop 成功后自动 pm2 dump，供开机自启 resurrect 恢复。`ellm-proxy pm2 <args>` 可透传
-//   任意 pm2 子命令（list/logs/monit/...，用包内局部 pm2，无需自装全局）。
-//
-// 开机自启（commands/autostart.js，跨平台）：登录时触发、无需管理员——Windows 写启动文件夹
-// .cmd（shell:startup）、macOS 写 LaunchAgent plist（launchctl load）、Linux 写 systemd user
-// unit（systemctl --user enable）；内容一致 = pm2 resurrect 恢复最后一次 dump。
-
-import { cac } from "cac";
-import { pkg } from "../utils/paths.js";
-import { error as uiError } from "../utils/ui.js";
-import * as serviceCmd from "./commands/service.js";
-import * as autostartCmd from "./commands/autostart.js";
-import * as configCmd from "./commands/config.js";
-import * as credentialsCmd from "./commands/credentials.js";
-import * as pm2Cmd from "./commands/pm2.js";
-
-const cli = cac("ellm-proxy");
-
-/** 统一错误出口：命令实现抛错 → 打印中文错误信息并以退出码 1 结束 */
-async function run(action) {
-  try {
-    await action();
-  } catch (err) {
-    console.error();
-    uiError(`错误：${err?.message ?? err}`);
-    process.exit(1);
-  }
-}
-
-serviceCmd.register(cli, run);
-autostartCmd.register(cli, run);
-configCmd.register(cli);
-credentialsCmd.register(cli, run);
-pm2Cmd.register(cli, run);
-
-// pm2 透传：在 cac 解析前拦截 `ellm-proxy pm2 <...args>`，pm2 的 -- 选项原样可达（cac 会吞掉未知 -- 选项）
-if (process.argv[2] === "pm2") {
-  run(() => pm2Cmd.doPassthrough(process.argv.slice(3)));
-} else {
-  // 默认命令（无参数）：启动服务，已运行则显示服务信息（选项同 start）
-  serviceCmd
-    .withStartOptions(cli.command("", "启动服务（已运行则显示服务信息，选项同 start）"))
-    .action((opts) => run(() => serviceCmd.doStartOrInfo(opts)));
-
-  cli.help();
-  cli.version(pkg.version);
-  cli.parse();
-}
+// ellm-proxy CLI shim：实现由构建产物 dist/cli.js 承载（backend/src/cli 源码打包）。
+import "../dist/cli.js";