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 OAuth 模块检查通过，但尚未独立授权。 PAYG key 的 Claude 请求被上游拒绝；该线路未通过验收，普通客户端 key 不允许使用。 Google AI Studio key 尚未取得；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 登录的路线不会进入运行配置。
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 目录。
latest 目前只是手动维护的稳定别名，没有自动追踪新版本。
Google AI Studio 预留独立 key 与模型表；取得有效 key 后查询目录再添加，
不把 Google OAuth/ADC 当成 AI Studio API key。
密钥
真实 .env 权限 0600，不提交 Git；模板见 .env.example。
ZenMux subscription/PAYG 的 key 需要明确确认用途，不能按外观推断。
数据库密码使用无特殊 URL 字符的随机值，避免 DATABASE_URL 编码问题。
LITELLM_MASTER_KEY 以 sk- 开头，salt 与 UI 密码独立随机生成。
日常客户端应使用管理界面创建的应用专属 virtual key，不共享 master key。
不要开启输出请求全文的 debug 日志。
独立 OAuth 登录
不复制 Codex CLI、Grok CLI 或 Hermes 的 refresh token。 在目标主机项目目录执行：
bash oauth-login.sh codex
打开终端显示的设备验证网址并输入验证码。
xAI 需要本机浏览器回调。先在浏览器所在电脑保持 SSH 隧道：
ssh -N -L 56121:127.0.0.1:56121 tools@192.168.50.49
然后在 tools-pve 的另一个终端运行：
bash oauth-login.sh xai
打开输出的授权 URL；若 56121 被占用，先关闭占用者再重试， 不要把临时改用的端口当作已有隧道可达。 登录 helper 使用 host network 仅供本地 OAuth 回调，生产代理仍使用独立 bridge。
确认账号实际支持的模型 ID 后，在 models.yaml 的 chatgpt/xai 表添加别名。
Codex 路线由 chatgpt/ 访问，优先 /v1/responses；
xAI 路线使用 xai/ 与 use_xai_oauth: true，不能设置 XAI API key 覆盖它。
新增 token 后需重启代理，运行时 refresh 会写回同一个持久卷。
部署及验收
正常走 Arcane Git Sync；Manager 已恢复，本项目已通过控制面部署。
如用户明确同意临时直接部署，将本目录放到 tools-pve，准备 .env 后执行：
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、 xAI OAuth 官方源码、 ZenMux prompt cache。