ellm-proxy 0.0.13 → 0.0.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +115 -25
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,13 +1,24 @@
|
|
|
1
1
|
# ellm-proxy
|
|
2
2
|
|
|
3
|
-
自研 LLM 网关（行为基准 litellm 1.100.0
|
|
4
|
-
|
|
5
|
-
> 需求决策与架构设计详见 [docs/DESIGN.md](docs/DESIGN.md)。
|
|
3
|
+
自研 LLM 网关（行为基准 litellm 1.100.0），单进程后台常驻、一键启停（跨平台，内置进程管理，无 pm2）。单端口提供全部能力——网关、管理台 API 与管理界面同端口（默认 29770）：
|
|
6
4
|
|
|
7
5
|
- `/v1/*` — LLM 网关端点（OpenAI / Anthropic 协议互转，多供应商路由、压缩、鉴权）
|
|
8
6
|
- `/api/*` — 管理台 API（登录鉴权、配置热更新、用量/日志）
|
|
9
7
|
- `http://127.0.0.1:<port>/` — 管理界面（服务进程托管 web-ui，同端口；远程访问靠登录保护）
|
|
10
8
|
|
|
9
|
+
> 需求决策与架构设计详见 [docs/DESIGN.md](docs/DESIGN.md)。
|
|
10
|
+
|
|
11
|
+
## 功能特性
|
|
12
|
+
|
|
13
|
+
- **协议互转**：客户端与上游可各用各的协议，网关自动转换——`anthropic ↔ chat-completions` 两条跨协议桥 + 同协议直通 + `responses` 路径，共 4 条请求链
|
|
14
|
+
- **多供应商路由**：供应商/模型两级配置，模型可单独覆盖协议与上游地址；内置 10 个供应商模板（deepseek、kimi、zhipu、zhipu-coding、ark、ark-coding、dashscope、openai、st（商汤）、custom），管理台拖拽排序、一键测试
|
|
15
|
+
- **autoV1**：上游地址缺 `/v1` 时自动补全（provider 级可关、model 级可覆盖）
|
|
16
|
+
- **鉴权**：网关主密钥（`/v1/*`）与管理台登录（`/api/*`、web-ui）两套独立体系
|
|
17
|
+
- **日志**：SQLite 存储，brotli 压缩 + 内容寻址去重（重复长文本只存一份），分层保留清理
|
|
18
|
+
- **代理开关**：一键把 Claude Code、Codex、DeepSeek Harness（dsh）的流量指向本机网关，含配置备份还原
|
|
19
|
+
- **自动更新**（可选开启）：手动一键更新或每小时看门狗自动检查，安装失败自动回滚
|
|
20
|
+
- **开机自启**：三平台登录触发直启，免管理员权限
|
|
21
|
+
|
|
11
22
|
## 安装
|
|
12
23
|
|
|
13
24
|
要求 Node.js **>= 22.13.0**（内置 `node:sqlite`，无需 flag）。
|
|
@@ -16,30 +27,112 @@
|
|
|
16
27
|
npm i -g ellm-proxy
|
|
17
28
|
```
|
|
18
29
|
|
|
19
|
-
##
|
|
30
|
+
## 快速开始
|
|
20
31
|
|
|
21
32
|
```bash
|
|
22
|
-
ellm-proxy
|
|
23
|
-
|
|
33
|
+
ellm-proxy start # 后台常驻启动（首次自动创建示例配置）
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
1. 打开管理界面 `http://127.0.0.1:29770/`，首次访问进入**首启向导**：选择部署形态（本机使用 / 局域网公开），设置网关主密钥与登录账号（局域网公开形态强制设置主密钥和账号，且禁用 admin/admin；本机使用可全部跳过）。
|
|
37
|
+
2. 在「供应商」页添加上游供应商（可选内置模板），配置 API Key 与模型映射。
|
|
38
|
+
3. 把客户端 base_url 指向网关即可，例如 Claude Code 指向 `http://127.0.0.1:29770`，OpenAI SDK 指向 `http://127.0.0.1:29770/v1`（也可直接用管理台「设置 → 代理开关」一键接入）。
|
|
39
|
+
|
|
40
|
+
## 网关端点
|
|
41
|
+
|
|
42
|
+
| 端点 | 说明 |
|
|
43
|
+
| --- | --- |
|
|
44
|
+
| `POST /v1/chat/completions` | OpenAI Chat Completions |
|
|
45
|
+
| `POST /v1/messages` | Anthropic Messages |
|
|
46
|
+
| `POST /v1/messages/count_tokens` | token 计数（本地估算，不触上游） |
|
|
47
|
+
| `POST /v1/responses` | OpenAI Responses |
|
|
48
|
+
| `GET /v1/models` | 模型列表 |
|
|
49
|
+
| 裸路径别名 `/chat/completions`、`/messages`、`/responses`… | 兼容不带 `/v1` 的 base_url（如 Codex） |
|
|
50
|
+
|
|
51
|
+
网关鉴权：配置 `masterKey`（或环境变量 `ELLM_MASTER_KEY`，低于配置文件）后，`/v1/*` 需 `Bearer <key>`；未设置主密钥则放行（本机个人使用模式）。可用 `ellm-proxy master-key` 查看/设置。
|
|
52
|
+
|
|
53
|
+
## 供应商配置
|
|
54
|
+
|
|
55
|
+
配置文件由首启或 `ellm-proxy config` 自动创建，示例：
|
|
56
|
+
|
|
57
|
+
```json
|
|
58
|
+
{
|
|
59
|
+
"port": 29770,
|
|
60
|
+
"masterKey": "",
|
|
61
|
+
"providers": [
|
|
62
|
+
{
|
|
63
|
+
"name": "my-openai",
|
|
64
|
+
"alias": "my",
|
|
65
|
+
"customLlmProvider": "openai",
|
|
66
|
+
"apiKey": "os.environ/MY_OPENAI_API_KEY",
|
|
67
|
+
"apiBase": "https://api.openai.com/v1",
|
|
68
|
+
"models": [
|
|
69
|
+
{ "modelName": "my/gpt-4o-mini", "model": "gpt-4o-mini" }
|
|
70
|
+
]
|
|
71
|
+
},
|
|
72
|
+
{
|
|
73
|
+
"name": "my-anthropic",
|
|
74
|
+
"customLlmProvider": "anthropic",
|
|
75
|
+
"models": [
|
|
76
|
+
{ "modelName": "my/claude-sonnet-4-5", "model": "claude-sonnet-4-5" },
|
|
77
|
+
{
|
|
78
|
+
"modelName": "my/mixed-model",
|
|
79
|
+
"model": "some-model",
|
|
80
|
+
"customLlmProvider": "openai",
|
|
81
|
+
"apiBase": "https://example.com/v1",
|
|
82
|
+
"apiKey": "os.environ/OTHER_KEY"
|
|
83
|
+
}
|
|
84
|
+
]
|
|
85
|
+
}
|
|
86
|
+
]
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
要点：
|
|
91
|
+
|
|
92
|
+
- `customLlmProvider` 为上游协议（`openai` | `anthropic` | `openai-responses`），provider 级设置后可被单个 model 覆盖（如上例 `my/mixed-model`），客户端协议与上游协议任意组合自动互转；
|
|
93
|
+
- `apiKey` 支持 `os.environ/NAME` 前缀引用环境变量；
|
|
94
|
+
- `apiBase` 不以 `/vN` 结尾时自动补 `/v1`（`autoV1` 可在 provider 级关闭、model 级覆盖）；
|
|
95
|
+
- 内置模板在管理台「供应商 → 添加」中选择，免去手写地址。
|
|
96
|
+
|
|
97
|
+
修改配置两种方式：直接编辑配置文件，或在管理界面在线修改（实时热更新）。
|
|
98
|
+
|
|
99
|
+
## 管理界面
|
|
100
|
+
|
|
101
|
+
- **首页**：服务信息卡（运行状态、PID、内存、API 密钥）+ 用量概览
|
|
102
|
+
- **供应商**：拖拽排序，模板化添加，模型级覆盖协议/地址，逐个或批量测试
|
|
103
|
+
- **日志**：按日期/会话筛选，查看请求详情（含压缩去重存储的原始内容，可开关捕获）
|
|
104
|
+
- **设置**：三个标签页——基本设置（主密钥/端口/压缩/内容捕获/登录账号）、代理开关（Claude Code / Codex / dsh 一键指向网关，自动备份原配置、可还原）、服务与更新（自动更新、开机自启）
|
|
105
|
+
|
|
106
|
+
登录鉴权：未设置账号时免登录直接进入（本机使用默认形态）；`ellm-proxy account <user> <pass>` 设置账号（密码 ≥6 位），`--reset` 清除恢复免登录。
|
|
107
|
+
|
|
108
|
+
## CLI 参考
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
ellm-proxy（无参数） # 已运行则显示服务信息，否则启动
|
|
112
|
+
ellm-proxy start # 后台常驻启动（选项：--port / --config / --data-dir / --working-dir）
|
|
24
113
|
ellm-proxy stop # 停止服务
|
|
25
114
|
ellm-proxy restart # 重启（先 stop 后 start，保证最新参数生效，选项同 start）
|
|
26
|
-
ellm-proxy（无参数） # 已运行则显示服务信息，否则启动
|
|
27
115
|
ellm-proxy autostart on # 开机自启（登录时触发，免管理员权限）
|
|
28
116
|
ellm-proxy autostart off # 关闭开机自启
|
|
29
|
-
ellm-proxy config #
|
|
30
|
-
ellm-proxy master-key # 查看/设置网关主密钥（--random / --clear
|
|
31
|
-
ellm-proxy account # 查看/设置管理台登录账号（--reset
|
|
117
|
+
ellm-proxy config # 显示配置文件路径（不存在自动创建示例配置）
|
|
118
|
+
ellm-proxy master-key # 查看/设置网关主密钥（--random 随机生成 / --clear 清除）
|
|
119
|
+
ellm-proxy account # 查看/设置管理台登录账号（--reset 恢复免登录）
|
|
120
|
+
ellm-proxy -h # 查看帮助
|
|
32
121
|
```
|
|
33
122
|
|
|
34
|
-
|
|
123
|
+
启动时端口若被占用会自动顺延到下一个空闲端口（仅本次运行生效，不改配置文件），顺延结果打印在启动摘要中。
|
|
124
|
+
|
|
125
|
+
## 进程管理与开机自启
|
|
126
|
+
|
|
127
|
+
**进程管理（内置，跨平台）**：CLI 启动时以 detached 方式拉起服务进程并写运行记录 `~/.ellm-proxy/run.json`，探活以「端口 HTTP 可达」为准。服务进程自持崩溃自愈（未捕获异常自动孵化后继进程接管端口，1 分钟窗口封顶 10 次，防端口占用无限循环），日志写 `<appDir>/logs/`。Node ≥22.13 由 CLI 解析（当前 node 满足则直接用，否则经 get-node 自动下载一次并缓存）。
|
|
35
128
|
|
|
36
|
-
|
|
129
|
+
**热重启**：配置变更或更新时触发 self-respawn——服务先孵化新进程接管端口再退出，停机 1~2 秒。
|
|
37
130
|
|
|
38
|
-
**开机自启（跨平台）**：`ellm-proxy autostart on` 注册登录触发的自启项（内容为直接启动服务，含运行参数 env 快照），三平台均无需管理员权限——Windows
|
|
131
|
+
**开机自启（跨平台）**：`ellm-proxy autostart on` 注册登录触发的自启项（内容为直接启动服务，含运行参数 env 快照），三平台均无需管理员权限——Windows 写启动文件夹（vbs 隐藏窗口 + cmd）、macOS 写 LaunchAgent（`launchctl load`）、Linux 写 systemd user unit（`systemctl --user enable`，WSL/无 systemd 环境会报错提示）；`autostart off` 移除。
|
|
39
132
|
|
|
40
133
|
## 自动更新（可选开启）
|
|
41
134
|
|
|
42
|
-
- **手动更新**：管理台「设置 →
|
|
135
|
+
- **手动更新**：管理台「设置 → 服务与更新」检查并一键更新——服务先回响应再自重启，新进程执行 `npm i -g` 安装并自动换新代码生效（双跳），安装失败自动回滚旧版本继续服务。
|
|
43
136
|
- **自动更新**：看门狗每小时检查 npm 源（默认 npmjs，`ELLM_UPDATE_REGISTRY` 可覆盖），发现新版本自动走同一链路；开关存配置文件顶层 `autoUpdate`。
|
|
44
137
|
- 源码/本地构建运行时更新域自动关闭（仅 npm 全局安装的包支持）。
|
|
45
138
|
|
|
@@ -56,23 +149,20 @@ ellm-proxy account # 查看/设置管理台登录账号（--reset）
|
|
|
56
149
|
|
|
57
150
|
所有路径均支持相对路径（按当前工作目录展开）与绝对路径。服务端自身不加载任何 `.env` 文件；`ELLM_MASTER_KEY` 等环境变量直接在会话中导出即可。
|
|
58
151
|
|
|
59
|
-
|
|
152
|
+
其他环境变量：`ELLM_PORT`（服务监听端口，或 `start --port`）、`HOST`（监听地址）。日志保留策略：配置 `logs.detail-retention-days` / `logs.row-retention-days`（详情/摘要分层保留，0 = 永久），默认启动后 30 秒首跑清理、之后每 6 小时一次。
|
|
60
153
|
|
|
61
|
-
|
|
62
|
-
2. 启动服务后访问管理界面 `http://127.0.0.1:29770/` 在线修改（实时热更新）。
|
|
154
|
+
## 从旧版本升级
|
|
63
155
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
## 从 0.0.7 及更早版本升级
|
|
67
|
-
|
|
68
|
-
1. `npm i -g ellm-proxy@latest`（或等自动更新）；
|
|
69
|
-
2. 直接 `ellm-proxy start`——旧版 pm2 托管的进程与守护会被自动清理，pm2 自启项自动迁移为直启模式；
|
|
70
|
-
3. 管理台地址从 `http://127.0.0.1:29771/` 变更为 `http://127.0.0.1:29770/`（单端口化，29771 退役）。
|
|
156
|
+
`npm i -g ellm-proxy@latest` 后直接 `ellm-proxy start` 即可。0.0.7 及更早版本的 pm2 托管进程/守护会被自动清理，pm2 自启项自动迁移为直启模式；管理台地址已单端口化为 `http://127.0.0.1:29770/`（29771 退役）。
|
|
71
157
|
|
|
72
158
|
## 本地开发（仓库内）
|
|
73
159
|
|
|
74
|
-
本包是 `ellm` monorepo
|
|
160
|
+
本包是 `ellm` monorepo（pnpm workspace）的发布载体。源码分四个包：`server`（Hono 单进程后端 + CLI）、`gateway`（网关主体：配置展开/路由/观测）、`protocol`（协议适配层：4 条请求链）、`web-ui`（Vue3 + Element Plus 管理界面）。发布版 `dist/server.js` 与 `dist/cli.js` 由 esbuild 从 `server` 源码全量内联构建，`web-ui` 产物拷入 `dist/web-ui/` 由服务进程托管：
|
|
75
161
|
|
|
76
162
|
```bash
|
|
77
163
|
pnpm pack:proxy # 构建 web-ui → 构建发布版 + 聚合 → npm pack 生成 tgz
|
|
164
|
+
pnpm test # 全部包测试（vitest）
|
|
165
|
+
pnpm build:all:restart # 全量构建后重启本机服务
|
|
78
166
|
```
|
|
167
|
+
|
|
168
|
+
发布走 GitHub Actions：推送 `v*.*.*` tag 自动校验版本并 `npm publish`（包名 [ellm-proxy](https://www.npmjs.com/package/ellm-proxy)）。
|