22 KiB

Raw Blame History

扩展与定制

**本文档引用的文件** - [backend/app/main.py](file://backend/app/main.py) - [backend/app/config.py](file://backend/app/config.py) - [backend/app/api/auth.py](file://backend/app/api/auth.py) - [backend/app/api/queries.py](file://backend/app/api/queries.py) - [backend/app/api/reports.py](file://backend/app/api/reports.py) - [backend/app/api/citations.py](file://backend/app/api/citations.py) - [backend/app/models/query.py](file://backend/app/models/query.py) - [backend/app/schemas/query.py](file://backend/app/schemas/query.py) - [backend/app/workers/scheduler.py](file://backend/app/workers/scheduler.py) - [backend/app/workers/platforms/base.py](file://backend/app/workers/platforms/base.py) - [backend/app/workers/platforms/kimi.py](file://backend/app/workers/platforms/kimi.py) - [backend/app/workers/platforms/wenxin.py](file://backend/app/workers/platforms/wenxin.py) - [backend/app/workers/citation_engine.py](file://backend/app/workers/citation_engine.py) - [backend/app/services/auth.py](file://backend/app/services/auth.py) - [backend/app/services/query.py](file://backend/app/services/query.py) - [backend/app/services/citation.py](file://backend/app/services/citation.py) - [backend/app/database.py](file://backend/app/database.py) - [backend/app/api/deps.py](file://backend/app/api/deps.py) - [backend/app/models/user.py](file://backend/app/models/user.py) - [backend/app/schemas/auth.py](file://backend/app/schemas/auth.py) - [backend/app/schemas/citation.py](file://backend/app/schemas/citation.py) - [backend/app/schemas/query.py](file://backend/app/schemas/query.py) - [backend/requirements.txt](file://backend/requirements.txt) - [frontend/app/layout.tsx](file://frontend/app/layout.tsx) - [frontend/components/providers.tsx](file://frontend/components/providers.tsx) - [frontend/lib/api.ts](file://frontend/lib/api.ts) - [frontend/package.json](file://frontend/package.json) - [docker-compose.yml](file://docker-compose.yml) - [backend/Dockerfile](file://backend/Dockerfile) - [frontend/Dockerfile](file://frontend/Dockerfile) - [backend/alembic/versions/488d0bd5ab01_initial_migration.py](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py)

简介

本文件面向需要对 GEO 平台进行扩展与定制的工程师与产品团队，系统性阐述后端 API 扩展、前端页面扩展、数据模型扩展、配置定制、第三方集成（AI 平台、数据库、认证）以及插件化扩展的最佳实践。文档同时提供可落地的实施建议与案例研究，帮助快速实现业务定制化目标。

项目结构

GEO 采用前后端分离架构：

后端基于 FastAPI，提供 REST API；通过 Alembic 管理数据库迁移；使用 SQLAlchemy ORM 定义模型；APScheduler 实现定时任务；Playwright 支持 AI 平台网页抓取。
前端基于 Next.js 14，使用 TypeScript、TailwindCSS、Radix UI 组件库；通过自定义 API 封装层与后端交互；NextAuth v4 提供会话管理。

graph TB
subgraph "前端"
FE_APP["Next.js 应用<br/>路由与页面"]
FE_LIB["API 封装<br/>lib/api.ts"]
FE_PROV["会话提供者<br/>components/providers.tsx"]
end
subgraph "后端"
BE_MAIN["FastAPI 应用<br/>app/main.py"]
BE_ROUTER_AUTH["认证路由<br/>app/api/auth.py"]
BE_ROUTER_QUERIES["查询路由<br/>app/api/queries.py"]
BE_ROUTER_CITATIONS["引用路由<br/>app/api/citations.py"]
BE_ROUTER_REPORTS["报告路由<br/>app/api/reports.py"]
BE_SCHED["调度器<br/>app/workers/scheduler.py"]
BE_PLAT_BASE["平台适配器基类<br/>app/workers/platforms/base.py"]
BE_PLAT_KIMI["Kimi 适配器<br/>app/workers/platforms/kimi.py"]
BE_PLAT_WENXIN["文心一言适配器<br/>app/workers/platforms/wenxin.py"]
BE_DB["数据库与模型<br/>app/database.py + models/*"]
end
FE_APP --> FE_LIB
FE_LIB --> BE_MAIN
BE_MAIN --> BE_ROUTER_AUTH
BE_MAIN --> BE_ROUTER_QUERIES
BE_MAIN --> BE_ROUTER_CITATIONS
BE_MAIN --> BE_ROUTER_REPORTS
BE_MAIN --> BE_SCHED
BE_SCHED --> BE_PLAT_BASE
BE_PLAT_BASE --> BE_PLAT_KIMI
BE_PLAT_BASE --> BE_PLAT_WENXIN
BE_MAIN --> BE_DB

图表来源

章节来源

核心组件

API 层：认证、查询词、引用数据、报告导出等模块化路由，统一挂载于主应用。
服务层：封装业务逻辑，如用户认证、查询 CRUD、引用处理等。
数据层：SQLAlchemy 模型与 Pydantic Schema，定义实体与请求/响应结构。
工作器与调度：APScheduler 驱动定时任务，CitationEngine 协调平台适配器执行查询。
前端：Next.js 页面与组件，通过 lib/api.ts 统一访问后端接口；NextAuth 提供会话状态。

章节来源

架构总览

下图展示从浏览器到后端 API、数据库与外部 AI 平台的完整链路：

sequenceDiagram
participant Browser as "浏览器"
participant Frontend as "前端 Next.js"
participant API as "后端 FastAPI"
participant Svc as "服务层"
participant DB as "数据库"
participant Scheduler as "调度器"
participant Engine as "CitationEngine"
participant Plat as "平台适配器"
Browser->>Frontend : 用户操作
Frontend->>API : 发起 HTTP 请求
API->>Svc : 路由分发与校验
Svc->>DB : 读写数据
DB-->>Svc : 返回结果
Svc-->>API : 业务结果
API-->>Frontend : JSON 响应
Note over Scheduler,Engine : 定时触发查询执行
Scheduler->>Engine : 触发执行
Engine->>Plat : 调用具体平台适配器
Plat-->>Engine : 返回原始响应
Engine->>DB : 写入引用记录

图表来源

详细组件分析

新增 API 接口扩展指南

路由扩展步骤
- 在后端 app/api 下新增模块（如 app/api/new_feature.py），定义 APIRouter 并编写路由函数。
- 在 app/main.py 中引入并挂载路由，指定前缀与标签。
- 在 app/services 下新增对应服务函数，封装业务逻辑。
- 在 app/schemas 下新增请求/响应模型，确保字段校验与默认值。
- 在 app/models 下新增模型（如需持久化）。
- 在 app/database.py 中注册模型，并在 alembic 迁移中生成/更新表结构。
示例参考路径

flowchart TD
Start(["开始"]) --> CreateRouter["创建路由模块<br/>app/api/new_feature.py"]
CreateRouter --> MountRouter["在 app/main.py 挂载路由"]
MountRouter --> AddService["在 app/services 添加服务函数"]
AddService --> AddSchema["在 app/schemas 添加模型"]
AddSchema --> AddModel["在 app/models 添加模型如需"]
AddModel --> Alembic["生成/更新数据库迁移"]
Alembic --> Test["编写单元测试"]
Test --> End(["完成"])

章节来源

前端页面扩展指南

页面与布局
- 在 frontend/app/(dashboard)/(或新的组) 下新增页面目录与 page.tsx。
- 在 frontend/app/layout.tsx 中组织根布局与 Providers。
- 在 components/ui 下新增或复用 UI 组件，保持一致的设计语言。
API 调用
- 在 frontend/lib/api.ts 中新增方法，遵循现有命名与错误处理模式。
- 在页面中通过 hooks 或直接调用 api.* 方法获取数据。
会话与权限
- 使用 frontend/components/providers.tsx 包裹应用，确保 NextAuth 会话可用。
- 在页面中根据用户状态控制渲染与交互。

flowchart TD
NewPage["新增页面<br/>frontend/app/(group)/new/page.tsx"] --> Layout["布局与 Providers<br/>frontend/app/layout.tsx"]
Layout --> UI["UI 组件<br/>frontend/components/ui/*"]
UI --> API["API 封装<br/>frontend/lib/api.ts"]
API --> Backend["后端 API<br/>backend/app/api/*"]

章节来源

数据模型扩展指南

字段与约束
- 在 app/models 下新增或修改模型，使用 SQLAlchemy 类型与索引策略。
- 在 app/schemas 下同步新增/变更 Pydantic 模型，确保序列化与校验。
- 在 app/api 下更新路由的响应模型。
迁移与版本控制
- 使用 Alembic 生成迁移脚本，维护数据库演进历史。
- 在生产环境执行迁移，避免破坏性变更。
性能与一致性
- 对高频查询字段建立索引；合理拆分表与外键关系。
- 通过服务层统一数据访问，避免绕过校验。

erDiagram
QUERIES {
uuid id PK
uuid user_id FK
string keyword
string target_brand
jsonb brand_aliases
jsonb platforms
string frequency
string status
timestamp last_queried_at
timestamp next_query_at
timestamp created_at
timestamp updated_at
}
USERS {
uuid id PK
string email UK
string name
string hashed_password
boolean is_active
timestamp created_at
timestamp updated_at
}
CITATION_RECORDS {
uuid id PK
uuid query_id FK
string platform
text raw_response
timestamp created_at
}
QUERIES ||--o{ CITATION_RECORDS : "包含"
USERS ||--o{ QUERIES : "拥有"

图表来源

章节来源

配置定制选项

环境变量
- 通过 app/config.py 的 Settings 类集中管理，支持 .env 文件覆盖。
- 关键配置项包括数据库连接、Redis、JWT 密钥与过期时间、Playwright 浏览器路径、第三方平台密钥等。
功能开关与性能参数
- 平台列表、频率策略、状态枚举在 Schema 中集中校验，便于扩展与限制。
- 调度周期（每小时）可在 app/workers/scheduler.py 中调整。
- 前端 NEXT_PUBLIC_API_URL 控制后端域名，lib/api.ts 中统一拼接。
建议
- 生产环境务必替换默认密钥与数据库密码。
- 将敏感信息放入 .env 并加入 .gitignore。

章节来源

第三方集成扩展指南

新 AI 平台接入

适配器开发
- 继承 app/workers/platforms/base.py，实现 query 与可选的 close。
- 在 app/workers/platforms 下新增适配器文件，按现有 Kimi/Wenxin 模式实现页面交互与稳定性检测。
注册与调度
- 在 app/schemas/query.py 的 VALID_PLATFORMS 中添加新平台枚举值。
- 在 CitationEngine 中注册新适配器映射，或通过工厂动态加载。
错误与重试
- 参考现有指数退避与超时处理策略，保证鲁棒性。

classDiagram
class BasePlatformAdapter {
+string platform_name
+string platform_url
+query(keyword) str
+close()
}
class KimiAdapter {
+query(keyword) str
+close()
}
class WenxinAdapter {
+query(keyword) str
+close()
}
BasePlatformAdapter <|-- KimiAdapter
BasePlatformAdapter <|-- WenxinAdapter

图表来源

章节来源

新数据库支持

当前使用 PostgreSQL + asyncpg，若需更换：
- 在 app/database.py 中切换引擎与方言。
- 更新 app/config.py 中 DATABASE_URL。
- 在 requirements.txt 中替换驱动包。
- 重新生成/更新 Alembic 迁移以适配新方言。

章节来源

新认证方式集成

当前使用 JWT 令牌与 NextAuth 会话：
- 后端：app/services/auth.py 生成与校验 JWT。
- 前端：components/providers.tsx 提供 SessionProvider。
- 若需 OAuth/SSO：在 NextAuth 配置中新增提供方；后端保持 JWT 令牌发放与校验逻辑不变。
注意事项
- 保持 Authorization 头格式与后端解析一致。
- 在 app/api/deps.py 中的依赖注入中校验用户身份。

章节来源

插件系统使用指南与最佳实践

插件化思路
- 平台适配器采用“插件”式扩展：通过继承基类与工厂/映射注册，实现多平台并行。
- 调度器与 CitationEngine 作为“核心引擎”，通过适配器接口解耦平台差异。
最佳实践
- 明确职责边界：路由负责协议与鉴权，服务层负责业务规则，模型负责数据结构。
- 统一错误处理：前端统一捕获 HTTP 错误并提示；后端抛出明确异常码与消息。
- 可观测性：为关键流程增加日志与指标，便于定位问题。
- 安全：严格校验输入、最小权限原则、HTTPS 传输、密钥轮换。

章节来源

依赖分析

后端依赖
- Web 框架与 ASGI 服务器：FastAPI + Uvicorn
- 数据库与迁移：SQLAlchemy + Alembic + asyncpg
- 配置与校验：Pydantic + pydantic-settings + python-dotenv
- 认证与安全：python-jose + passlib + multipart
- 任务调度：APScheduler
- 浏览器自动化：Playwright
- HTTP 客户端：httpx
前端依赖
- 框架与 UI：Next.js + Radix UI + TailwindCSS
- 认证：NextAuth v4
- 图表：Recharts
- 开发工具：TypeScript + ESLint + TailwindCSS

graph LR
subgraph "后端依赖"
F["FastAPI"]
S["SQLAlchemy/Alembic"]
P["Pydantic/pydantic-settings"]
J["python-jose/passlib"]
R["Redis/APScheduler"]
PW["Playwright"]
H["httpx/python-dotenv"]
end
subgraph "前端依赖"
N["Next.js"]
NA["NextAuth"]
UI["Radix UI/TailwindCSS"]
RC["Recharts"]
end

图表来源

章节来源

性能考虑

数据库
- 为高频查询字段建立索引；避免 N+1 查询；使用分页参数限制单页规模。
API
- 合理设置分页参数（skip/limit），避免一次性返回大量数据。
- 对热点接口启用缓存（如 Redis）减少重复计算。
定时任务
- 调度周期可根据业务需求调整；在高负载时降低频率或增加并发控制。
浏览器自动化
- Playwright 启动成本较高，尽量复用上下文；失败重试与超时控制要合理设置。
前端
- 按需加载页面与组件；减少不必要的 re-render；利用浏览器缓存与静态资源优化。

故障排查指南

常见问题定位
- 后端健康检查：访问 /health 确认服务可用。
- CORS：确认 app/main.py 中允许的源与方法。
- 数据库连接：检查 DATABASE_URL 与网络连通性。
- Playwright：确保已安装浏览器二进制；查看适配器初始化日志。
日志与监控
- 调度器与平台适配器均输出详细日志，定位失败原因。
- 前端统一错误处理：lib/api.ts 在请求失败时抛出错误，便于 UI 提示。
快速恢复
- 重启后端服务与前端构建；检查 .env 配置是否正确；核对迁移是否执行。

章节来源

结论

GEO 平台提供了清晰的分层架构与可扩展点：路由层、服务层、数据层与工作器层相互解耦，配合配置中心与前端统一 API 封装，能够高效支撑业务扩展。通过平台适配器插件化、Schema/模型标准化、调度器与任务队列机制，团队可以快速接入新 AI 平台、扩展前端页面与数据模型，并在生产环境中保持稳定与可观测。

附录

系统定制化案例研究与实施建议

案例一：接入新 AI 平台
- 步骤：新增适配器类 → 在 Schema 中注册平台枚举 → 在 CitationEngine 中注册映射 → 编写测试 → 部署与灰度。
- 建议：先在本地模拟页面交互，再逐步对接真实站点；为不同页面结构准备多套选择器策略。
案例二：新增查询词字段
- 步骤：在模型与 Schema 中新增字段 → 生成迁移 → 更新路由与服务层逻辑 → 前端页面与表单适配。
- 建议：使用默认值与非空约束，确保向后兼容。
案例三：前端新增报表页面
- 步骤：新增页面与路由 → 引入图表组件 → 调用后端报表接口 → 权限控制与数据可视化。
- 建议：复用现有 UI 组件库，保持设计一致性。

部署与运行要点

使用 Docker Compose 启动后端与前端服务，确保端口映射与网络互通。
后端 Dockerfile 与 requirements.txt 已配置，注意镜像构建缓存与依赖锁定。
前端 Dockerfile 与 Next.js 版本已固定，构建产物由 Next.js 管理。

章节来源

22 KiB Raw Blame History Unescape Escape

扩展与定制

目录

简介

项目结构

核心组件

架构总览

详细组件分析

新增 API 接口扩展指南

前端页面扩展指南

数据模型扩展指南

配置定制选项

第三方集成扩展指南

新 AI 平台接入

新数据库支持

新认证方式集成

插件系统使用指南与最佳实践

依赖分析

性能考虑

故障排查指南

结论

附录

系统定制化案例研究与实施建议

部署与运行要点

22 KiB

Raw Blame History