架构总览

Difficulty: Advanced
Status: Stable
Last reviewed: 2025年10月

This content is not available in your language yet.

一个接收任意 LLM 协议请求、选出最优账号并转发到上游的代理中间层，用 Rust 从零构建。先建立全局认知，再按模块深入。

产品定位与设计哲学

一句话定位

统一 LLM 账号、协议转换与代理转发服务——多上游账号统一管理、按模型和协议选择 runtime、请求可审计、账号隔离可控。

三个核心承诺

承诺	含义	技术体现
协议无关	不绑定任何特定 LLM 提供商协议	Canonical IR + Client/Upstream Adapter
账号隔离可控	User Token 绑定账号组，不能越界访问	SelectionScope + 组过滤 + fail closed
请求可审计	每次转发的完整链路可追溯	request_logs + token_stats + ProxyOutcome

明确的反目标

通用工作流平台（不是 n8n / Airflow）
企业 RBAC 中心（不是 Keycloak / Auth0）
任意协议网关（专注 LLM API）
模型推理/训练服务

面试怎么聊：讲清楚“为什么不做成通用网关”——专注 LLM 协议意味着 Canonical IR 的语义层可以做得很薄，但又能精准建模 text/image/tool_call/thinking 等 LLM 特有概念。通用网关做不到这一点。

系统分层

┌──────────────────────────────────────────────────────────────┐
│  API               /v1/*  /internal/*  /api/* /health        │
│    ↓ 客户端请求                                             │
├──────────────────────────────────────────────────────────────┤
│  Middleware         认证 / CORS / IP 过滤 / 日志 / 限流      │
├──────────────────────────────────────────────────────────────┤
│  Protocol Handler   OpenAI Chat / Claude / Gemini / MCP      │
│    ↓ 解码为 CanonicalRequest                                │
├──────────────────────────────────────────────────────────────┤
│  Routing            model_mapping + RuntimeRegistry          │
│    ↓ resolved_model + RuntimeKind                           │
├──────────────────────────────────────────────────────────────┤
│  ProxyOrchestrator  账号 scope 解析 → select_lease → 重试   │
├──────────────────────────────────────────────────────────────┤
│  Accounts           统一账号服务、选择、Lease、组隔离        │
├──────────────────────────────────────────────────────────────┤
│  Upstream Runtime   ProviderRuntime 执行上游请求             │
├──────────────────────────────────────────────────────────────┤
│  Protocol Adapter   encode_request / decode_stream_event     │
├──────────────────────────────────────────────────────────────┤
│  Transport          HTTP client pool / proxy pool            │
├──────────────────────────────────────────────────────────────┤
│  DB                PostgreSQL / SQLite                       │
└──────────────────────────────────────────────────────────────┘

层间调用方向（单向）

Middleware → Handler → Routing → Orchestrator → Accounts/Selection
                                              → Upstream Runtime →
                                                Transport → 上游服务

关键约束：

Handler 不直接选账号；选账号走 Orchestrator → AccountService::select_lease
Runtime 不重新扫 DB 选账号；只消费 AccountLease
跨账号重试在 Orchestrator 做，不在 Runtime 做
协议转换集中在 protocol/，不走点对点硬编码

模块清单与职责边界

模块	路径	一句话职责
accounts	`src/accounts`	账号域模型、账号选择、租约、组隔离
api	`src/api`	HTTP DTO、admin/v1 handler、错误响应
commands	`src/commands`	服务启动、命令式操作 glue
db	`src/db`	唯一持久化层，仅此处 SQL
integrations	`src/integrations`	系统进程、cloudflared、CLI 同步、更新检测
locales	`src/locales`	多语言资源文件
log	`src/log`	tracing 初始化、日志桥接、敏感信息脱敏
models	`src/models`	跨层 DTO、配置、token、quota 数据结构
observability	`src/observability`	指标、重试事件和可观测记录
protocol	`src/protocol`	协议转换中心：Canonical IR、Client/Upstream Adapter
proxy	`src/proxy`	反代编排：中间件、handler、Orchestrator
routing	`src/routing`	模型路由、RuntimeRegistry、server lifecycle
upstream	`src/upstream`	Provider Runtime、OAuth、quota、transport
utils	`src/utils`	通用 ID、HTTP、crypto、cache、i18n、version

面试怎么聊：15 个模块的拆分不是过度设计——每个模块有明确的“只能做什么”和“不能做什么”。db 是唯一能碰 SQL 的，protocol 是唯一能做协议语义转换的，accounts 是唯一能选账号的。这让代码审查变得机械化。

四层数据管道

这是整个系统最核心的设计：任何 LLM 请求都经过统一的数据转换管道。

Client Protocol (OpenAI/Claude/Gemini/...)
    ↓ client adapter 解码
Canonical IR (CanonicalRequest)     ← 协议无关的中间表示
    ↓ routing + account selection
    ↓ upstream adapter 编码
Upstream Protocol (发送到上游)
    ↓
Upstream Response/Stream
    ↓ upstream adapter 解码
CanonicalStreamEvent / CanonicalResponse
    ↓ StreamCollector 聚合
    ↓ client adapter 编码
Client Response/SSE

核心设计决策：

设计	理由
Canonical IR 不做“超集”	只包含 LLM 最核心的语义：messages、tools、streaming、thinking、images
Client/Upstream 双 Adapter	OpenAI→Claude 和 Claude→OpenAI 只写一次，相互独立
`requested_model` >= `resolved_model` >= `upstream_model`	三段模型链，每段变更可追溯
协议选择在 Orchestrator	`resolve_upstream_protocol()` 根据 lease 的 `supported_protocols` 决定

面试怎么聊：重点讲清楚“为什么需要 Canonical IR”——不是过度抽象，而是消除 O(N x M) 的协议转换爆炸。8 种客户端协议 x 8 种上游 Runtime 如果不通过 IR，需要 64 个点对点转换器。

核心不变量

I1：账号选择是统一能力

不属于任何协议 handler，不属于任何 runtime。AccountService::select_lease() 是唯一入口。所有模块依赖这个函数的返回值决定执行策略。

I2：组隔离必须 fail closed

User Token 绑定账号组后：组不存在 → 请求失败；查询失败 → 请求失败；组为空 → 请求失败。不降级到全量账号。

I3：API Key 账号必须显式声明

未知协议不能静默落到 Antigravity 或兜底 runtime。必须通过 runtime_options_json.protocol 或 supported_protocols 声明。

I4：请求路径三段模型名

requested_model → resolved_model → upstream_model，每段变更可追溯。provider 级别名和 fallback 必须可观测。

I5：协议转换不走捷径

不存在 handler 直接 JSON.json → runtime 直接 JSON.json 的路径。必须经过 Canonical IR。

端到端请求流

以一次 POST /v1/chat/completions 为例：

1. 请求进入 Axum route (routing/server/ routes)
2. auth_middleware 验证 User Token / admin key
3. ip_filter_middleware 检查 IP 过滤
4. monitor_middleware 注入 trace_id 和时间
5. OpenAI chat handler 解码请求 (protocol/client/openai)
   → CanonicalRequest { requested_model: "gpt-4o-mini" }
6. model_mapping 解析: "gpt-4o-mini" → "gpt-4o-mini"
   → resolved_model, RuntimeKind::OpenAI
7. account_scope::resolve_selection_scope()
   User Token 有 group_id → SelectionScope::Group { group_id, account_ids }
8. AccountService::select_lease(Request)
   ├─ 过滤: enabled/status/proxy_disabled/protocol/runtime/model
   ├─ 排序: last_used ASC → created_at ASC → id ASC (LRU)
   └─ 返回 AccountLease { account_id, credentials, runtime_kind }
9. ProxyOrchestrator::execute_chat(OrchestratorRequest)
   - 最多 max_attempts 次
   - resolve_upstream_protocol: checks lease.runtime_options.supported_protocols
   - RuntimeRegistry::get(RuntimeKind::OpenAI)
   - ProviderRuntime::execute_chat(RequestContext, lease, request)
   - 失败调用 should_retry (429/5xx/network) → 排除账号 → select_lease 再选
10. ProviderRuntime 执行:
    - upstream adapter encode_request(CanonicalRequest) → OpenAI JSON
    - transport send → upstream response SSE/JSON
    - upstream adapter decode_stream_event → CanonicalStreamEvent
    - StreamCollector 聚合
    - client adapter encode → OpenAI Chat SSE chunks
11. Orchestrator 记录 ProxyOutcome::Success
12. request_logs 异步写入 DB
13. 客户端收到 SSE/JSON 响应

与其他代理/网关的对比

维度	Account Manager	LiteLLM	One-API	Gateway API
语言	Rust	Python	Go	Go
账号选择	确定性 avai …	轮询/随机	轮询	路由表
协议转换	Canonical IR	无	无	无
账号组隔离	原生 support	无	无	无
OAuth 自动化	统一入口 + loopback	无	无	无
流式协议互转	OpenAI/Claude/Gemini 双向	无	无	无
部署模式	二进制 / Compose / 容器	Docker / pip	Docker	Docker

面试怎么聊：重点讲“为什么用 Rust”和“为什么自己写 Canonical IR”。Rust 带来的零成本抽象让 IR 转换无 GC 停顿——这对流式 100+ chunks/second 不是一个新 API 门面。

技术栈选择

为什么是 Rust

需求	Rust 优势
代理延迟敏感	SSE 流式转发不抖动
高并发连接池	actix/axum + tokio，结构化并发
单二进制部署	`cargo build --release`
类型安全	编译期捕获账号域/协议匹配错误

为什么是 SQLite/PostgreSQL 双模式

模式	场景
SQLite	单机部署、开发环境
PostgreSQL	多实例部署、共享账号池

ABV_DATABASE_URL 环境变量决定数据库选择，设置 Postgres 连接串则使用 Postgres，否则使用 SQLite。非法连接 Postgres 配置直接报错，不静默回退。

实现路线

Phase	内容	状态
P0	账号模型 + 数据库 + OAuth + 基本代理	Done
P1	Canonical IR + Client/UpstreamAdapter	Done
P2	统一账号选择 + 代理编排	Done
P3	流式转换 + 多Client 协议	Done
P4	User Token 隔离 + 账号组	Done
P5	管理 API + 前端	Done
P6	生产部署 + 自动发布	Done