proxycast/docs/content/06.development/1.architecture.md

---
title: 架构说明
description: ProxyCast 技术架构
navigation:
  icon: i-heroicons-cube-transparent
---

# 架构说明

ProxyCast 是基于 Tauri 2.0 构建的跨平台桌面应用。

## 技术栈

| 层级 | 技术 |
|------|------|
| 前端 | React + TypeScript + Tailwind CSS |
| 后端 | Rust + Tauri 2.0 |
| 构建 | Vite |
| 包管理 | pnpm |

## Tauri 前后端通信

### 架构图

```
┌─────────────────────────────────────────────────────────┐
│                    Frontend (React)                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │  Dashboard  │  │  Settings   │  │  Monitoring │     │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘     │
│         │                │                │             │
│         └────────────────┼────────────────┘             │
│                          │                              │
│                    ┌─────▼─────┐                        │
│                    │  Tauri    │                        │
│                    │  Commands │                        │
│                    └─────┬─────┘                        │
└──────────────────────────┼──────────────────────────────┘
                           │ IPC
┌──────────────────────────┼──────────────────────────────┐
│                    ┌─────▼─────┐                        │
│                    │  Command  │                        │
│                    │  Handler  │                        │
│                    └─────┬─────┘                        │
│                          │                              │
│  ┌───────────────────────┼───────────────────────┐     │
│  │                       │                       │     │
│  ▼                       ▼                       ▼     │
│ ┌─────────┐        ┌─────────┐            ┌─────────┐ │
│ │Provider │        │Credential│            │  Router │ │
│ │ Manager │        │  Pool   │            │         │ │
│ └────┬────┘        └────┬────┘            └────┬────┘ │
│      │                  │                      │      │
│      └──────────────────┼──────────────────────┘      │
│                         │                             │
│                   ┌─────▼─────┐                       │
│                   │ API Server│                       │
│                   │  (Axum)   │                       │
│                   └───────────┘                       │
│                    Backend (Rust)                      │
└───────────────────────────────────────────────────────┘
```

### 通信方式

前端通过 Tauri Commands 调用后端：

```typescript
// 前端调用
import { invoke } from '@tauri-apps/api/core';

const result = await invoke('get_credentials');
```

```rust
// 后端处理
#[tauri::command]
async fn get_credentials() -> Result<Vec<Credential>, String> {
    // 处理逻辑
}
```

## Rust 后端模块

### 模块结构

```
src-tauri/src/
├── main.rs              # 入口
├── lib.rs               # 库导出
├── commands/            # Tauri 命令
│   ├── mod.rs
│   ├── config_cmd.rs
│   ├── credential_cmd.rs
│   └── server_cmd.rs
├── credential/          # 凭证管理
│   ├── mod.rs
│   ├── kiro.rs
│   ├── gemini.rs
│   └── qwen.rs
├── provider/            # Provider 实现
│   ├── mod.rs
│   ├── anthropic.rs
│   ├── openai.rs
│   └── gemini.rs
├── router/              # 请求路由
│   ├── mod.rs
│   └── rules.rs
├── converter/           # 协议转换
│   ├── mod.rs
│   ├── openai_to_claude.rs
│   └── claude_to_openai.rs
├── server/              # API Server
│   ├── mod.rs
│   ├── handlers.rs
│   └── middleware.rs
└── config/              # 配置管理
    ├── mod.rs
    └── yaml.rs
```

### 核心模块

#### Credential 模块

负责凭证的加载、刷新和管理：

```rust
pub struct CredentialManager {
    credentials: Vec<Credential>,
    refresh_scheduler: RefreshScheduler,
}

impl CredentialManager {
    pub async fn load_credentials(&mut self) -> Result<()>;
    pub async fn refresh_token(&mut self, id: &str) -> Result<()>;
    pub fn get_available(&self) -> Vec<&Credential>;
}
```

#### Provider 模块

实现不同 AI 服务的调用：

```rust
#[async_trait]
pub trait Provider: Send + Sync {
    async fn chat_completion(&self, request: ChatRequest) -> Result<ChatResponse>;
    async fn stream_completion(&self, request: ChatRequest) -> Result<impl Stream<Item = StreamChunk>>;
}
```

#### Router 模块

根据规则路由请求：

```rust
pub struct Router {
    rules: Vec<RoutingRule>,
    default_provider: String,
}

impl Router {
    pub fn route(&self, model: &str) -> RoutingResult;
}
```

#### Converter 模块

在不同 API 格式之间转换：

```rust
pub fn openai_to_claude(request: OpenAIRequest) -> ClaudeRequest;
pub fn claude_to_openai(response: ClaudeResponse) -> OpenAIResponse;
```

## 请求处理流程

```
1. 客户端请求 → API Server (Axum)
                    │
2. 认证检查 ────────┤
                    │
3. 路由匹配 ────────┤ Router
                    │
4. 凭证选择 ────────┤ Credential Pool
                    │
5. 协议转换 ────────┤ Converter
                    │
6. Provider 调用 ───┤ Provider
                    │
7. 响应转换 ────────┤ Converter
                    │
8. 返回响应 ────────┘
```

## 数据流

### 请求流程

1. 前端发起 API 请求
2. Axum 服务器接收请求
3. 中间件进行认证和日志
4. Router 根据模型名称选择 Provider
5. Credential Pool 选择可用凭证
6. Converter 转换请求格式
7. Provider 调用实际 AI 服务
8. Converter 转换响应格式
9. 返回响应给客户端

### 事件流程

```
后端事件 → Tauri Event → 前端监听 → UI 更新
```

```rust
// 后端发送事件
app.emit("credential-updated", payload)?;
```

```typescript
// 前端监听
import { listen } from '@tauri-apps/api/event';

await listen('credential-updated', (event) => {
  // 更新 UI
});
```