337 lines
17 KiB
Markdown
337 lines
17 KiB
Markdown
# GEO 平台 - 系统架构设计
|
||
|
||
## 整体架构
|
||
|
||
GEO 平台采用分层架构设计，由以下四层组成：
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Presentation Layer │
|
||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
|
||
│ │ Next.js │ │ React 19 │ │ Tailwind CSS + shadcn │ │
|
||
│ │ App Router │ │ Components │ │ UI Components │ │
|
||
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ API Gateway Layer │
|
||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
|
||
│ │ FastAPI │ │ REST API │ │ JWT / OAuth2 │ │
|
||
│ │ Routers │ │ Endpoints │ │ Authentication │ │
|
||
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ Service & Agent Layer │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
|
||
│ │ Citation │ │ Content │ │ Rule │ │ Competitor │ │
|
||
│ │ Detector │ │Generator │ │ Checker │ │ Analyzer │ │
|
||
│ └──────────┘ └──────────┘ └──────────┘ └──────────────────┘ │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
|
||
│ │Performance│ │ Task │ │ Query │ │ Report │ │
|
||
│ │ Tracker │ │ Scheduler│ │ Engine │ │ Generator │ │
|
||
│ └──────────┘ └──────────┘ └──────────┘ └──────────────────┘ │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ Infrastructure Layer │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐ │
|
||
│ │PostgreSQL│ │ Redis │ │ Celery │ │ Docker │ │
|
||
│ │ (Data) │ │ (Cache) │ │ (Queue) │ │ (Container) │ │
|
||
│ └──────────┘ └──────────┘ └──────────┘ └────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 四层架构说明
|
||
|
||
#### 1. 表现层（Presentation Layer）
|
||
|
||
- **Next.js App Router**：基于文件系统的路由，支持服务端渲染（SSR）和静态生成（SSG）
|
||
- **React 19**：最新 React 特性，包括 Server Components、Actions、Form 状态管理
|
||
- **Tailwind CSS + shadcn/ui**：原子化 CSS + 可复用无头组件库，支持快速构建一致化 UI
|
||
|
||
**关键设计决策**：
|
||
- 采用 BFF（Backend for Frontend）模式，前端通过 API Client 与后端通信
|
||
- 认证状态使用 NextAuth.js 管理，支持 Credentials + OAuth 双模式
|
||
- 数据获取优先使用 Server Components 减少客户端 JavaScript 体积
|
||
|
||
#### 2. API 网关层（API Gateway Layer）
|
||
|
||
- **FastAPI**：高性能 Python Web 框架，原生支持异步和自动 API 文档
|
||
- **RESTful API**：标准的 REST 接口设计，返回 JSON 格式数据
|
||
- **认证授权**：JWT Token + OAuth2 密码流，支持角色权限控制
|
||
|
||
**模块划分**：
|
||
| 模块 | 职责 | 对应文件 |
|
||
|------|------|----------|
|
||
| Auth API | 用户注册、登录、Token 刷新、权限验证 | `api/auth.py` |
|
||
| Query API | 查询创建、执行、结果获取 | `api/queries.py` |
|
||
| Citation API | 引用记录管理、统计分析 | `api/citations.py` |
|
||
| Report API | 报告生成、导出、查看 | `api/reports.py` |
|
||
| Admin API | 用户管理、系统配置、订阅管理 | `api/admin.py` |
|
||
| Subscription API | 订阅计划、支付、限额管理 | `api/subscriptions.py` |
|
||
|
||
#### 3. 服务与 Agent 层（Service & Agent Layer）
|
||
|
||
本层是 GEO 平台的核心业务逻辑层，包含传统 Service 和 AI Agent 两大类组件。
|
||
|
||
**传统 Service**：
|
||
| Service | 职责 |
|
||
|---------|------|
|
||
| QueryService | 查询生命周期管理、AI 平台调用、结果聚合 |
|
||
| CitationService | 引用检测算法执行、引用记录存储、置信度评估 |
|
||
| ReportService | 报告模板渲染、数据聚合、多种格式导出 |
|
||
| UserService | 用户 CRUD、角色权限、订阅状态管理 |
|
||
| SubscriptionService | 订阅计划管理、配额控制、升级降级 |
|
||
|
||
**AI Agent 集群**：详见 `docs/02-design/agent-framework.md`
|
||
|
||
#### 4. 基础设施层（Infrastructure Layer）
|
||
|
||
| 组件 | 用途 | 技术选型 |
|
||
|------|------|----------|
|
||
| PostgreSQL | 主数据库，存储业务数据 | PostgreSQL 15+ |
|
||
| Redis | 缓存、Celery Broker、会话存储 | Redis 7+ |
|
||
| Celery | 异步任务队列、定时任务调度 | Celery 5+ |
|
||
| Docker | 应用容器化部署 | Docker + Compose |
|
||
|
||
## 模块解耦原则
|
||
|
||
### 1. 领域驱动设计（DDD）
|
||
|
||
- **领域模型独立**：核心业务模型（Query、Citation、User、Subscription）不依赖任何框架
|
||
- **边界上下文清晰**：每个模块维护自己的数据模型和业务规则
|
||
- **防腐层（ACL）**：外部 AI 平台适配器通过防腐层与核心领域隔离
|
||
|
||
### 2. 依赖倒置原则
|
||
|
||
```
|
||
API Layer → Service Layer → Repository Layer → Database
|
||
↑ ↑ ↑
|
||
依赖接口 依赖接口 依赖接口
|
||
```
|
||
|
||
- Service 层定义接口，Repository 层实现接口
|
||
- 便于单元测试时 Mock 依赖
|
||
- 支持未来数据库迁移或替换
|
||
|
||
### 3. 配置与代码分离
|
||
|
||
- 所有环境相关配置通过环境变量注入
|
||
- 应用配置集中管理在 `app/config.py`
|
||
- 不同环境（dev / staging / prod）使用不同的 `.env` 文件
|
||
|
||
### 4. 异步解耦
|
||
|
||
- 耗时操作（AI 查询执行、报告生成）通过 Celery 异步处理
|
||
- 前端通过轮询或 WebSocket 获取任务状态更新
|
||
- 任务执行状态持久化，支持断点续传和失败重试
|
||
|
||
## AI Agent 解耦通信协议设计
|
||
|
||
### 通信模型
|
||
|
||
GEO 平台的 AI Agent 之间采用 **基于消息队列的异步通信协议**，确保 Agent 之间松耦合、可独立部署和扩展。
|
||
|
||
```
|
||
┌─────────────┐ ┌─────────────┐ ┌─────────────────┐
|
||
│ Agent A │────▶│ Message │────▶│ Agent B │
|
||
│ (生产者) │ │ Queue │ │ (消费者) │
|
||
└─────────────┘ └─────────────┘ └─────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────┐
|
||
│ Registry │
|
||
│ (注册中心) │
|
||
└─────────────┘
|
||
```
|
||
|
||
### 消息格式
|
||
|
||
```json
|
||
{
|
||
"message_id": "uuid",
|
||
"timestamp": "2026-01-01T00:00:00Z",
|
||
"sender": "agent_name",
|
||
"recipient": "agent_name_or_broadcast",
|
||
"message_type": "task_request | task_result | status_update | heartbeat",
|
||
"payload": {
|
||
"task_id": "uuid",
|
||
"task_type": "detect_citations | generate_content | check_rules | analyze_competitors | track_performance",
|
||
"parameters": {},
|
||
"data": {},
|
||
"priority": 1
|
||
},
|
||
"correlation_id": "uuid",
|
||
"reply_to": "agent_name"
|
||
}
|
||
```
|
||
|
||
### 通信模式
|
||
|
||
| 模式 | 说明 | 适用场景 |
|
||
|------|------|----------|
|
||
| 点对点 | Agent A 直接发送任务给 Agent B | 明确的一对一任务分配 |
|
||
| 广播 | Agent 向所有订阅者发送消息 | 状态更新、配置变更通知 |
|
||
| 发布/订阅 | Agent 向特定主题发布消息 | 事件驱动架构 |
|
||
| 请求/响应 | 同步等待返回结果 | 需要即时反馈的短任务 |
|
||
|
||
### Agent 注册与发现
|
||
|
||
- **注册中心**：Redis 作为轻量级注册中心
|
||
- **注册机制**：Agent 启动时向注册中心注册自己的能力和状态
|
||
- **健康检查**：定期发送心跳，失效 Agent 自动从注册中心移除
|
||
- **负载均衡**：任务分发时根据 Agent 负载状态选择执行节点
|
||
|
||
### 错误处理与重试
|
||
|
||
- 消息消费失败时自动进入死信队列（DLQ）
|
||
- 支持配置重试次数和重试间隔（指数退避）
|
||
- 失败任务可手动重新触发或自动补偿
|
||
|
||
## 双模式权限设计
|
||
|
||
### 用户角色模型
|
||
|
||
```
|
||
┌─────────────┐
|
||
│ User │
|
||
└──────┬──────┘
|
||
│
|
||
┌───────────────┼───────────────┐
|
||
▼ ▼ ▼
|
||
┌────────────┐ ┌────────────┐ ┌────────────┐
|
||
│ EndUser │ │ Admin │ │ Agent │
|
||
│ (终端用户) │ │ (管理员) │ │ (运营人员) │
|
||
└─────┬──────┘ └────────────┘ └─────┬──────┘
|
||
│ │
|
||
▼ ▼
|
||
┌──────────────┐ ┌──────────────┐
|
||
│ Self-Service │ │ Proxy-Service│
|
||
│ 自主订阅 │ │ 代理运营 │
|
||
└──────────────┘ └──────────────┘
|
||
```
|
||
|
||
### 权限矩阵
|
||
|
||
| 功能 | EndUser (Basic) | EndUser (Pro) | EndUser (Enterprise) | Admin | Agent |
|
||
|------|----------------|---------------|---------------------|-------|-------|
|
||
| 创建查询 | 10/月 | 50/月 | 无限制 | 无限制 | 无限制 |
|
||
| 引用检测 | 有 | 有 | 有 | 有 | 有 |
|
||
| 策略生成 | 基础 | 高级 | 定制化 | 全部 | 全部 |
|
||
| 内容生成 | 5/月 | 20/月 | 无限制 | 无限制 | 无限制 |
|
||
| 报告导出 | PDF | PDF + Excel | 全部格式 | 全部格式 | 全部格式 |
|
||
| 团队管理 | 无 | 无 | 有 | 有 | 有 |
|
||
| 代理客户管理 | 无 | 无 | 无 | 有 | 有 |
|
||
| 白标报告 | 无 | 无 | 无 | 有 | 有 |
|
||
| 系统配置 | 无 | 无 | 无 | 有 | 无 |
|
||
| 用户管理 | 无 | 无 | 无 | 有 | 无 |
|
||
|
||
### 权限实现
|
||
|
||
- **基于角色的访问控制（RBAC）**：用户通过角色获得一组权限
|
||
- **基于属性的访问控制（ABAC）**：结合用户订阅等级、团队归属等属性进行细粒度控制
|
||
- **中间件校验**：FastAPI 依赖注入实现统一的权限校验中间件
|
||
- **前端联动**：前端路由和组件根据用户权限动态渲染
|
||
|
||
### API 权限控制示例
|
||
|
||
```python
|
||
# FastAPI 依赖注入实现权限控制
|
||
async def require_admin(current_user: User = Depends(get_current_user)):
|
||
if not current_user.is_admin:
|
||
raise HTTPException(status_code=403, detail="需要管理员权限")
|
||
return current_user
|
||
|
||
async def require_subscription(min_tier: str):
|
||
async def checker(current_user: User = Depends(get_current_user)):
|
||
if not current_user.subscription.meets(min_tier):
|
||
raise HTTPException(status_code=403, detail="订阅等级不足")
|
||
return current_user
|
||
return checker
|
||
|
||
# 路由使用
|
||
@router.post("/queries")
|
||
async def create_query(
|
||
data: QueryCreate,
|
||
user: User = Depends(require_subscription("pro"))
|
||
):
|
||
...
|
||
```
|
||
|
||
## 数据流架构
|
||
|
||
### 查询执行数据流
|
||
|
||
```
|
||
用户创建查询 ──▶ API 接收 ──▶ 验证权限/配额 ──▶ 创建查询记录
|
||
│
|
||
▼
|
||
提交 Celery 任务
|
||
│
|
||
▼
|
||
┌─────────────────┐
|
||
│ Worker 执行查询 │
|
||
│ - 调用 AI 平台 │
|
||
│ - 聚合响应结果 │
|
||
└────────┬────────┘
|
||
│
|
||
▼
|
||
┌─────────────────┐
|
||
│ CitationDetector │
|
||
│ - 解析引用内容 │
|
||
│ - 评估置信度 │
|
||
└────────┬────────┘
|
||
│
|
||
▼
|
||
保存引用记录 ──▶ 更新查询状态
|
||
│
|
||
▼
|
||
通知前端完成
|
||
```
|
||
|
||
### 报告生成数据流
|
||
|
||
```
|
||
用户请求报告 ──▶ API 接收 ──▶ 收集相关数据
|
||
│
|
||
▼
|
||
ReportService 聚合数据
|
||
│
|
||
▼
|
||
应用报告模板
|
||
│
|
||
▼
|
||
生成 PDF/Excel/HTML
|
||
│
|
||
▼
|
||
返回下载链接
|
||
```
|
||
|
||
## 扩展性设计
|
||
|
||
### 水平扩展
|
||
|
||
- **无状态服务**：API 服务无状态设计，可通过负载均衡水平扩展
|
||
- **数据库读写分离**：未来支持主从复制，读操作分散到从库
|
||
- **缓存层**：Redis 缓存热点数据，减少数据库压力
|
||
|
||
### AI 平台适配器扩展
|
||
|
||
GEO 平台需要对接多种 AI 搜索引擎平台，适配器设计遵循开闭原则：
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ PlatformAdapter (抽象基类) │
|
||
│ - execute_query() │
|
||
│ - parse_response() │
|
||
│ - validate_config() │
|
||
└─────────────────────────────────────────┘
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
┌──────────┐ ┌──────────┐ ┌──────────┐
|
||
│ ChatGPT │ │ Kimi │ │ Perplex │
|
||
│ Adapter │ │ Adapter │ │ Adapter │
|
||
└──────────┘ └──────────┘ └──────────┘
|
||
```
|
||
|
||
新增 AI 平台只需实现 `PlatformAdapter` 接口，无需修改现有代码。
|
||
|
||
---
|
||
|
||
*本文档描述 GEO 平台的整体系统架构设计，详细模块设计请参考各子系统设计文档。*
|