aiagent/docs/architecture.md

🏛️ 架构设计文档

Architecture Design Document

---

一、系统概述

天工智能体平台是一个企业级 AI 智能体（Agent）平台，提供智能对话、知识库管理、智能体编排等核心能力，采用前后端分离 + 异步任务队列 的架构设计。

---

二、技术选型

层级	技术	版本	选型理由
前端框架	Vue 3 (Composition API)	3.4+	轻量、响应式、TypeScript 友好
前端构建	Vite	5+	极速 HMR，开发体验优异
状态管理	Pinia	2+	Vue 3 官方推荐，TypeScript 支持完善
路由	Vue Router	4+	SPA 路由，支持导航守卫
HTTP 客户端	Axios	1+	请求/响应拦截，统一错误处理
后端框架	FastAPI	0.110+	高性能异步框架，自动生成 OpenAPI 文档
ORM	SQLAlchemy	2.0+	成熟的 Python ORM，异步支持
数据验证	Pydantic	2+	类型安全，与 FastAPI 深度集成
数据库迁移	Alembic	1.13+	版本化管理数据库变更
数据库	MySQL (腾讯云)	8.0+	稳定可靠的关系型数据库
缓存	Redis	7+	高性能缓存 + 消息队列
任务队列	Celery	5.3+	分布式异步任务处理
认证	JWT	—	无状态认证，支持 Token 刷新
容器化	Docker + Docker Compose	最新	简化部署，环境一致

---

三、架构分层

┌─────────────────────────────────────────────────────────────┐
│                   客户端层 (Client Layer)                     │
│  浏览器 (Chrome/Edge)  │  移动端  │  第三方 API 调用         │
└───────────────────────┬─────────────────────────────────────┘
                        │ HTTPS
┌───────────────────────▼─────────────────────────────────────┐
│                  接入层 (Gateway Layer)                      │
│  Nginx 反向代理 │  SSL 终止 │ 静态资源服务 │ 端口 8038/8037  │
└───────────────────────┬─────────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────────┐
│                 前端应用层 (Frontend Layer)                   │
│  Vue 3 SPA  │  Pinia Store  │  Vue Router  │  Axios Client   │
│  ┌─────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐  │
│  │ Views   │  │Components│  │  Stores  │  │   Utils      │  │
│  │ 页面组件 │  │ 公共组件  │  │ 状态管理  │  │ 工具/请求封装│  │
│  └─────────┘  └──────────┘  └──────────┘  └──────────────┘  │
└───────────────────────┬─────────────────────────────────────┘
                        │ HTTP/JSON
┌───────────────────────▼─────────────────────────────────────┐
│                 后端服务层 (Backend Layer)                    │
│  FastAPI  │  中间件  │  路由  │  依赖注入                    │
│  ┌──────────────┐  ┌──────────────────┐                    │
│  │  API 路由层   │  │  认证/授权中间件  │                    │
│  │  (api/v1/*)  │  │  (JWT、CORS)     │                    │
│  ├──────────────┤  ├──────────────────┤                    │
│  │  Service 层   │  │  任务调度         │                    │
│  │  (业务逻辑)   │  │  (Celery 任务)   │                    │
│  ├──────────────┤  ├──────────────────┤                    │
│  │  Models 层    │  │  Schemas 层       │                    │
│  │  (ORM 定义)   │  │  (数据验证)      │                    │
│  └──────────────┘  └──────────────────┘                    │
└──────┬────────────────────────────┬─────────────────────────┘
       │                            │
       ▼                            ▼
┌──────────────┐          ┌──────────────────┐
│  MySQL 8.0   │          │    Redis 7        │
│ (腾讯云)     │          │ 缓存 / 任务队列   │
│ 持久化存储   │          │ 会话 / 锁        │
└──────────────┘          └──────────────────┘
                                │
                                ▼
                      ┌──────────────────┐
                      │   Celery Worker   │
                      │ 异步任务处理       │
                      │ 文件处理 / 通知   │
                      └──────────────────┘

---

四、核心业务模块

1. 用户模块

• 注册/登录：邮箱 + 密码，JWT Token 发放
• Token 刷新：Access Token (短期) + Refresh Token (长期)
• 个人中心：信息查看与修改

2. 智能体模块

• 智能体的创建、配置、发布、下架
• 支持配置 LLM 参数、提示词、工具调用
• 知识库关联

3. 知识库模块

• 文档上传与解析（PDF、TXT、Markdown）
• 向量化存储（对接嵌入模型）
• 语义检索

4. 对话模块

• 用户与智能体的实时对话
• 上下文管理
• 流式输出（SSE）

---

五、数据流示例（对话请求）

1. 用户输入消息
       │
2. Axios POST /api/v1/conversations/{id}/messages
       │
3. Nginx 代理到后端 8037
       │
4. FastAPI 接收请求
   ├── JWT 中间件验证 Token
   ├── 路由分发到对应 Handler
   ├── Service 层处理业务逻辑
   │   ├── 查询对话历史 (MySQL)
   │   ├── 检索相关知识 (知识库)
   │   └── 调用 LLM API (异步)
   │
5. Celery 异步执行 LLM 调用
   ├── 进度通过 Redis Pub/Sub 推送
   └── SSE 推送给前端
       │
6. 前端流式渲染响应内容

---

六、安全设计

安全措施	说明
JWT 认证	Access Token 有效期短，Refresh Token 轮换
密码加密	bcrypt 哈希存储
CORS 配置	仅允许指定域名跨域访问
输入验证	Pydantic 严格校验所有输入
SQL 注入防护	SQLAlchemy ORM 参数化查询
HTTPS	Nginx 侧终止 SSL（生产环境）

---

七、扩展性 & 可维护性

• 水平扩展：FastAPI 为无状态应用，可多实例部署 + Nginx 负载均衡
• 异步任务：Celery Worker 可独立扩展，处理大量异步任务
• 模块化：后端按业务拆分为 modules/，新增功能不影响现有模块
• 数据库迁移：Alembic 管理 Schema 变更，支持回滚
• 前端组件化：Vue 组件按功能拆解，提升复用性

---

📎 相关文档：项目结构概览 | 开发指南