本文档详细描述了FastAgent系统的架构设计、主要组件及其交互方式。
FastAgent采用前后端分离的架构设计，主要由以下部分组成：
- 前端应用：基于Next.js构建的单页面应用(SPA)，提供用户界面
- 后端API服务：基于FastAPI构建的RESTful API服务，处理业务逻辑
- 大模型集成：通过MCP(Model Call Protocol)服务与各种大型语言模型集成
- 数据存储：使用SQLite数据库存储用户、会话和消息数据
架构图：
┌────────────────┐ HTTP ┌────────────────┐
│ │◄──────────────►│ │
│ 前端应用 │ │ 后端API服务 │
│ (Next.js) │ │ (FastAPI) │
│ │ │ │
└────────────────┘ └───────┬────────┘
│
│ HTTP/SSE
▼
┌────────────────────┐
│ │
│ 大型语言模型服务 │
│ (MCP服务) │
│ │
└────────────────────┘
│
│ 数据持久化
▼
┌────────────────────┐
│ │
│ 数据库 │
│ (SQLite) │
│ │
└────────────────────┘
FastAgent后端基于Python FastAPI框架构建，采用现代化的异步处理方式和模块化设计。
-
API层（app/api）
- 提供RESTful API端点
- 处理HTTP请求和响应
- 实现路由和控制器功能
-
服务层（app/services）
- 封装核心业务逻辑
- 提供与MCP服务和大型语言模型的交互
- 管理用户、会话和消息
-
数据访问层（app/db）
- 处理数据库操作
- 提供数据模型和CRUD操作
- 管理数据迁移和初始化
-
核心配置（app/core）
- 管理应用配置和环境变量
- 提供安全服务（JWT认证等）
- 实现日志记录和错误处理
-
工具类（app/utils）
- 提供通用工具函数
- 实现辅助功能
FastAgent后端的典型数据流如下：
- 客户端发送API请求到FastAPI服务器
- 中间件处理请求（认证、日志记录等）
- 路由将请求分发到对应的控制器
- 控制器调用服务层处理业务逻辑
- 服务层与数据库或外部服务（如MCP）交互
- 结果经由控制器返回给客户端
客户端 → 中间件 → 路由 → 控制器 → 服务层 → 数据库/外部服务
↓
客户端 ← 响应 ← ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘
服务层是FastAgent的核心，主要包含以下几个关键服务：
-
AgentService：与大型语言模型交互的服务，封装了MCP协议的实现
- 处理用户查询
- 管理Agent实例生命周期
- 处理上下文和提示词
-
ChatService：管理聊天会话和消息
- 创建和管理会话
- 存储和检索消息
- 处理消息格式转换
-
UserService：用户管理和认证
- 用户注册和登录
- 密码哈希和验证
- 权限管理
-
MCPService：MCP服务连接管理
- 验证MCP服务器连接
- 处理SSE连接和重试逻辑
FastAgent前端采用现代React技术栈，基于Next.js框架构建。
- 框架：Next.js 14
- UI库：使用Shadcn/UI和Tailwind CSS
- 状态管理：React Context API和SWR
- 路由：Next.js App Router
- API调用：Fetch API和自定义钩子
前端采用组件化设计，主要组件包括：
- 布局组件：页面框架、侧边栏、导航栏
- 会话组件：会话列表、会话项、新建会话按钮
- 聊天组件：消息列表、消息项（用户/助手）、输入框
- 用户组件：登录表单、注册表单、用户档案
- 共享组件：按钮、卡片、模态框、通知提示等
前端组件结构：
v0-frontend/
├── app/ # 页面和路由
│ ├── chat/ # 聊天页面
│ ├── dashboard/ # 仪表板页面
│ ├── login/ # 登录页面
│ └── register/ # 注册页面
├── components/ # 共享组件
│ ├── ui/ # UI基础组件
│ └── ... # 其他组件
├── hooks/ # 自定义钩子
│ ├── use-auth.tsx # 认证钩子
│ └── ... # 其他钩子
├── lib/ # 工具函数和API客户端
│ ├── api.ts # API请求函数
│ └── ... # 其他工具
├── styles/ # 样式文件
└── ... # 其他文件和配置
FastAgent使用SQLite数据库存储应用数据，主要包含以下数据模型：
-
User：用户信息
- id: 主键
- username: 用户名
- hashed_password: 哈希后的密码
- email: 电子邮件
- is_active: 是否激活
- created_at: 创建时间
-
Session：会话信息
- id: 主键
- title: 会话标题
- user_id: 用户ID（外键）
- created_at: 创建时间
- updated_at: 更新时间
-
Message：消息记录
- id: 主键
- session_id: 会话ID（外键）
- role: 角色（user/assistant）
- content: 消息内容
- created_at: 创建时间
ER图:
┌────────────┐ ┌────────────┐ ┌────────────┐
│ User │ │ Session │ │ Message │
├────────────┤ ├────────────┤ ├────────────┤
│ id │ │ id │ │ id │
│ username │ │ title │ │ session_id │ ──┐
│ password │ │ user_id │ ─┐ │ role │ │
│ email │ │ created_at │ │ │ content │ │
│ is_active │ ◄────┤ updated_at │ └───│ created_at │ │
│ created_at │ └────────────┘ └────────────┘ │
└────────────┘ │ ▲ │
└─────────────────┴────────────┘
FastAgent系统内部通信主要基于以下协议：
-
前后端通信：RESTful API
- HTTP/HTTPS协议
- JSON数据格式
- JWT认证
-
后端与MCP服务通信：
- Server-Sent Events (SSE)
- HTTP/HTTPS协议
- JSON数据格式
-
数据序列化格式：
- 请求/响应：JSON
- 配置文件：YAML
- 日志：文本/JSON
FastAgent支持多种部署模式：
-
开发环境：
- 本地运行前后端服务
- SQLite数据库
- 直接连接MCP服务
-
生产环境：
- 前端：静态构建部署到Web服务器或CDN
- 后端：部署到服务器或容器
- 数据库：可升级至PostgreSQL或MySQL
- 反向代理：Nginx或Caddy
部署图：
┌─────────────┐ ┌──────────────┐ ┌──────────────┐
│ │ │ │ │ │
│ Web浏览器 │ ←→ │ Web服务器 │ ←→ │ API服务器 │ ←→ MCP服务
│ │ │ (前端) │ │ (后端) │
│ │ │ │ │ │
└─────────────┘ └──────────────┘ └──────────────┘
│
↓
┌──────────────┐
│ │
│ 数据库服务器 │
│ │
└──────────────┘
FastAgent的模块化设计使其易于扩展和集成到各种环境中，同时前后端分离的架构也提供了灵活的部署选择。