fix(relay): fix llm_routing read path bug and add User-Agent header for Coding Plan
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled

1. connectionStore.ts: storedAccount.account.llm_routing → storedAccount.llm_routing
   - saveSaaSSession stores SaaSAccountInfo directly, not { account: SaaSAccountInfo }
   - This bug caused admin llm_routing config to never take effect

2. relay/service.rs: add User-Agent: claude-code/1.0 header
   - Kimi Coding Plan requires recognized coding agent User-Agent
   - Default reqwest UA is rejected with 403

3. Docs: add llm_routing routing mode explanation and troubleshooting entries
This commit is contained in:
iven
2026-03-31 12:02:32 +08:00
parent ee51d5abcd
commit 3e5d64484e
4 changed files with 77 additions and 4 deletions

View File

@@ -1,6 +1,6 @@
# ZCLAW SaaS 平台 — 总览
> 最后更新: 2026-03-30 | 实施状态: Phase 1-4 全部完成 + 架构重构完成9 个后端模块 + Worker + Scheduler + Admin V2 (Ant Design Pro) + 桌面端完整集成
> 最后更新: 2026-03-31 | 实施状态: Phase 1-4 全部完成 + 架构重构完成9 个后端模块 + Worker + Scheduler + Admin V2 (Ant Design Pro) + 桌面端完整集成
## 架构概述
@@ -173,6 +173,7 @@ ZCLAW SaaS 平台为桌面端用户提供云端能力包括模型中转Key
│ └── Key 池耗尽 → 回退到 Provider 级单 Key
├── 2. execute_relay() — 向上游发送请求
│ ├── User-Agent: claude-code/1.0 — Coding Plan API 兼容
│ ├── SSE 流式: 捕获流事件中的 usage异步记录
│ └── JSON: 从响应提取 usage同步记录
@@ -183,6 +184,30 @@ ZCLAW SaaS 平台为桌面端用户提供云端能力包括模型中转Key
└── 4. SSRF 防护 — 验证 Provider URL阻断私有网络请求
```
## 桌面端 LLM 路由模式 (llm_routing)
账户级别 `llm_routing` 设置控制桌面端如何调用 LLM
| 模式 | 行为 | 适用场景 |
|------|------|---------|
| `relay` | 桌面端通过 SaaS relay + Key Pool 调用 LLM | 共享 Key 池,无需本地 API Key |
| `local` | 桌面端直连本地 kernel需要本地 API Key | 私有部署,本地模型 |
**路由优先级**: Admin 配置的 `llm_routing` 覆盖桌面端 localStorage 中的 `connectionMode`。登录时 SaaS 后端返回的 `account.llm_routing` 写入 localStorage`connectionStore.connect()` 读取并强制切换。
**数据流**:
```text
llm_routing=relay:
Desktop → connectionStore (llm_routing=relay) → KernelClient
→ baseUrl = saasUrl/api/v1/relay → kernel 追加 /chat/completions
→ apiKey = SaaS JWT token → Bearer 认证
→ Key Pool 选择最优 Key → 上游 Provider
llm_routing=local:
Desktop → connectionStore (llm_routing=local) → KernelClient
→ 本地配置的 apiKey + baseUrl → 直连 Provider
```
## 配置同步模式
| 模式 | 行为 | 使用场景 |
@@ -257,4 +282,4 @@ ZCLAW SaaS 平台为桌面端用户提供云端能力包括模型中转Key
---
**最后更新**: 2026-03-30
**最后更新**: 2026-03-31