17 KiB
17 KiB
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 │
│ (注册中心) │
└─────────────┘
消息格式
{
"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 + Excel | 全部格式 | 全部格式 | 全部格式 | |
| 团队管理 | 无 | 无 | 有 | 有 | 有 |
| 代理客户管理 | 无 | 无 | 无 | 有 | 有 |
| 白标报告 | 无 | 无 | 无 | 有 | 有 |
| 系统配置 | 无 | 无 | 无 | 有 | 无 |
| 用户管理 | 无 | 无 | 无 | 有 | 无 |
权限实现
- 基于角色的访问控制（RBAC）：用户通过角色获得一组权限
- 基于属性的访问控制（ABAC）：结合用户订阅等级、团队归属等属性进行细粒度控制
- 中间件校验：FastAPI 依赖注入实现统一的权限校验中间件
- 前端联动：前端路由和组件根据用户权限动态渲染
API 权限控制示例
# 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 平台的整体系统架构设计，详细模块设计请参考各子系统设计文档。