# 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 平台的整体系统架构设计，详细模块设计请参考各子系统设计文档。*