142 lines
7.4 KiB
Markdown
142 lines
7.4 KiB
Markdown
# tools-pve 统一模型代理
|
||
|
||
## 部署状态
|
||
|
||
2026-10-09：已通过 Arcane 上线，LiteLLM 1.104.2 与 PostgreSQL 均 healthy。
|
||
UI HTTP 200；应用 virtual key 的 OpenRouter MiMo 请求返回 OK。
|
||
ZenMux Sonnet 5.5 原生 Messages 正常；重复请求证实写入与读取
|
||
21,502 prompt-cache tokens。Codex/xAI 已独立授权，SDK 原生请求验证
|
||
Luna、Sol 6.1 和 Grok 4.7 返回 OK。用户更新后的 PAYG key 原生 Claude 请求 HTTP 200。
|
||
Google AI Studio key 模型目录 HTTP 200，使用上游提供的三个 latest 别名。
|
||
17 条路线已加载；原客户端 key 权限已更新，Luna/Sol 的 gateway Responses SSE、
|
||
Luna 非流式 Chat Completions、Grok/Gemini 三条 Chat 路线和 PAYG Messages 均实测 OK。
|
||
本项目对其他模型的自动 latest 维护尚未实现。
|
||
|
||
- Environment：`ff859844-8393-4f87-8caf-054df735a65d`。
|
||
- Project：`06052b47-f640-4e23-968d-bfc25a8a6e7a`，名称 `tools-litellm`。
|
||
- Git Sync：`49148e73-65ca-43a6-a859-efc9cc750b93`；Auto Sync 关闭。
|
||
- 宿主机项目目录：`/var/lib/docker/volumes/arcane-agent_agent-data/_data/projects/litellm`。
|
||
- 管理凭据：.145 的 `/home/claw/codex-workspace/server-management/.secrets/tools-litellm.env`。
|
||
- 普通客户端配置：同目录 `tools-litellm-client.env`；两者均为 0600，不提交 Git。
|
||
|
||
## 架构与入口
|
||
|
||
部署在 `192.168.50.49`，LiteLLM 与独立 PostgreSQL 17。
|
||
|
||
- OpenAI 兼容客户端：`http://192.168.50.49:4000/v1`。
|
||
- Anthropic SDK：`http://192.168.50.49:4000`，请求 `/v1/messages`。
|
||
- 管理界面：`http://192.168.50.49:4000/ui`。
|
||
- PostgreSQL 不发布主机端口。
|
||
- named volume：`tools-litellm-database`、`tools-litellm-oauth`。
|
||
|
||
只使用单个代理 worker，降低 OAuth refresh token 竞争的风险。
|
||
所有配置从 Git 生成，不允许 UI 中的模型配置成为另一份权威。
|
||
未提供 key 或未完成 OAuth 登录的路线不会进入运行配置。
|
||
OAuth 判定检查 auth.json 中 access_token，不仅检查文件存在性：
|
||
Codex 设备授权期间会先写入冷却占位文件，这不代表已经授权。
|
||
|
||
## Provider 与缓存
|
||
|
||
ZenMux Claude 使用 Anthropic Messages 上游：
|
||
`https://zenmux.ai/api/anthropic`。
|
||
LiteLLM 的 `anthropic/anthropic/claude-sonnet-5.5` 第一个前缀是
|
||
LiteLLM provider，第二个前缀是 ZenMux 的模型 ID，不是笔误。
|
||
|
||
订阅路线为 `claude-sonnet-latest`、`claude-opus-latest`、
|
||
`claude-haiku-latest`；PAYG 路线在同名末尾加 `-payg`。
|
||
不自动由订阅切换到 PAYG，也不设置跨模型 fallback。
|
||
|
||
Claude 客户端优先使用原生 `/v1/messages`，保留 `cache_control`、
|
||
稳定的 tools/system 前缀以及原样回传的 thinking/signature。
|
||
不能保证每次 cache hit；首次创建、最小缓存长度、TTL 和上游路由都会影响结果。
|
||
上线验收需重复发送足够长且完全相同的前缀，检查
|
||
`cache_creation_input_tokens` 和 `cache_read_input_tokens`，不能只看 HTTP 200。
|
||
不把 LiteLLM 的响应缓存当作 Anthropic prompt cache。
|
||
|
||
实测 ZenMux Sonnet 5.5 会拒绝强制 `tool_choice.type=tool/any`，
|
||
错误由上游返回；使用支持的 `auto` 模式，不在代理中静默改写调用者的要求。
|
||
|
||
开放模型优先经 OpenRouter；首版 `models.yaml` 来自实际 provider 目录。
|
||
除 Google 自带 latest 映射由其上游维护外，其他 `latest` 都是本项目手动维护的稳定别名。
|
||
Google AI Studio 使用独立 key 与模型表，已实际查询模型目录，
|
||
不把 Google OAuth/ADC 当成 AI Studio API key。
|
||
Google 三条模型为 gemini-flash-latest、gemini-flash-lite-latest、gemini-pro-latest。
|
||
用户新 provider key 的权威位置是 Arcane tools-litellm Project `.env`；
|
||
不要用 .145 首次生成的 tools-litellm.env 整体覆盖它，那份文件可能还含旧 provider 值。
|
||
该本机文件主要用于 master key 管理与数据库凭据恢复；提供商配置必须先从 Arcane 实查。
|
||
|
||
## 密钥
|
||
|
||
真实 `.env` 权限 `0600`，不提交 Git；模板见 `.env.example`。
|
||
ZenMux subscription/PAYG 的 key 需要明确确认用途，不能按外观推断。
|
||
数据库密码使用无特殊 URL 字符的随机值，避免 `DATABASE_URL` 编码问题。
|
||
`LITELLM_MASTER_KEY` 以 `sk-` 开头，salt 独立随机生成。
|
||
UI 使用数据库管理员 `kai@litellm.local`（只是登录标识，不发送邮件），
|
||
设置 `disable_env_credential_login: true`，禁用 UI_PASSWORD 以及 master key 的网页登录。
|
||
用户已修改首次临时密码，临时文件已删除。数据库保存密码哈希，
|
||
用户的新密码不写入环境变量，也不由 Agent 保存。
|
||
master key 仍能管理 API，用于恢复权限，不再充当网页登录密码。
|
||
不能直接用这份配置初始化空库后期待默认 admin 登录：必须预先通过
|
||
`/user/new` 建立管理员，再 `/user/update` 设置临时密码，随后启用限制。
|
||
日常客户端应使用管理界面创建的应用专属 virtual key，不共享 master key。
|
||
不要开启输出请求全文的 debug 日志。
|
||
|
||
## 独立 OAuth 登录
|
||
|
||
不复制 Codex CLI、Grok CLI 或 Hermes 的 refresh token。
|
||
在目标主机项目目录执行：
|
||
|
||
```bash
|
||
bash oauth-login.sh codex
|
||
```
|
||
|
||
打开终端显示的设备验证网址并输入验证码。
|
||
|
||
xAI 需要本机浏览器回调。先在浏览器所在电脑保持 SSH 隧道：
|
||
|
||
```bash
|
||
ssh -N -L 56121:127.0.0.1:56121 tools@192.168.50.49
|
||
```
|
||
|
||
然后在 tools-pve 的另一个终端运行：
|
||
|
||
```bash
|
||
bash oauth-login.sh xai
|
||
```
|
||
|
||
打开输出的授权 URL；若 56121 被占用，先关闭占用者再重试，
|
||
不要把临时改用的端口当作已有隧道可达。
|
||
登录 helper 使用 host network 仅供本地 OAuth 回调，生产代理仍使用独立 bridge。
|
||
|
||
确认账号实际支持的模型 ID 后，在 `models.yaml` 的 `chatgpt`/`xai` 表添加别名。
|
||
OAuth 映射为 gpt-luna-latest -> gpt-6-luna、gpt-sol-latest -> gpt-6.1-sol、
|
||
grok-latest -> grok-4.7，独立账号目录与 SDK 请求均已验证。
|
||
Codex 路线由 `chatgpt/` 访问，优先 `/v1/responses`；
|
||
原生 Responses 使用消息列表形式的 input 和 stream=true，按 SSE 读取到 response.completed。
|
||
常规 OpenAI SDK 客户端也可用 /v1/chat/completions，Luna 非流式桥接已实测 OK。
|
||
实测直接给字符串 input 会被 Codex backend 拒绝；不要把已授权误写成协议完全兼容。
|
||
xAI 路线使用 `xai/` 与 `use_xai_oauth: true`，不能设置 XAI API key 覆盖它。
|
||
新增 token 后需重启代理，运行时 refresh 会写回同一个持久卷。
|
||
|
||
## 部署及验收
|
||
|
||
正常走 Arcane Git Sync；Manager 已恢复，本项目已通过控制面部署。
|
||
如用户明确同意临时直接部署，将本目录放到 tools-pve，准备 `.env` 后执行：
|
||
|
||
```bash
|
||
docker compose config --quiet
|
||
docker compose up -d
|
||
docker compose ps
|
||
```
|
||
|
||
恢复 Arcane 后应纳管这套已有卷和项目，避免生成第二套数据库。
|
||
上线必须验证健康、带 virtual key 的模型列表、实际请求、stream 和工具调用；
|
||
OAuth 与 Claude cache hit 分别验收，未通过不能写成可用。
|
||
|
||
回滚只停止新增项目或回退配置/image pin，不删除 named volume。
|
||
定期 `pg_dump` 并保留独立备份，数据库卷不是备份。
|
||
|
||
参考：[LiteLLM ChatGPT OAuth](https://docs.litellm.ai/docs/providers/chatgpt)、
|
||
[xAI OAuth 官方源码](https://github.com/BerriAI/litellm/blob/main/litellm/llms/xai/oauth.py)、
|
||
[ZenMux prompt cache](https://zenmux.ai/docs/guide/advanced/prompt-cache.html)。
|