ab1589921a
## 安全修复 (12项) - Webhook接口添加全局Token认证，过滤敏感请求头 - 修复JWT Base64 padding公式，防止签名验证绕过 - 数据库密码/飞书Token从源码移除，改为环境变量 - 工作流引擎添加路径遍历防护 (_resolve_safe_path) - eval()添加模板长度上限检查 - 审批API添加认证依赖 - 前端v-html增强XSS转义，console.log仅开发模式输出 - 500错误不再暴露内部异常详情 ## Agent运行时修复 (7项) - 删除_inject_knowledge_context中未定义db变量的finally块 - 工具执行添加try/except保护，异常不崩溃Agent - LLM重试计入budget计数器 - self_review异常时passed=False - max_iterations截断标记success=False - 工具参数JSON解析失败时记录警告日志 - run()开始时重置_llm_invocations计数器 ## 配置与基础设施 - DEBUG默认False，SQL_ECHO独立配置项 - init_db()补全13个缺失模型导入 - 新增WEBHOOK_AUTH_TOKEN/SQL_ECHO配置项 - 新增.env.example模板文件 ## 前端修复 (12项) - 登录改用URLSearchParams替代FormData - 401拦截器通过Pinia store统一清理状态 - SSE流超时从60s延长至300s - final/error事件时清除streamTimeout - localStorage聊天记录添加24h TTL - safeParseArgCount替代模板中裸JSON.parse - fetchUser 401时同时清除user对象 ## 新增模块 - 知识进化: knowledge_extractor/retriever/tasks - 数字孪生: shadow_executor/comparison模型 - 行为采集: behavior_middleware/collector/fingerprint_engine - 代码审查: code_review_agent/document_review_agent - 反馈学习: feedback_learner - 瓶颈检测/优化引擎/成本估算/需求估算 - 速率限制器 (rate_limiter) - Alembic迁移 015-020 ## 文档 - 商业化落地计划 - 8篇docs文档 (架构/API/部署/开发/贡献等) - Docker Compose生产配置 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
162 lines
8.2 KiB
Markdown
162 lines
8.2 KiB
Markdown
# 🏛️ 架构设计文档
|
||
|
||
> **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 组件按功能拆解，提升复用性
|
||
|
||
---
|
||
|
||
> 📎 **相关文档**：[项目结构概览](./project-structure.md) | [开发指南](./development-guide.md)
|