18 KiB

Raw Blame History

后端系统架构

**本文档引用的文件** - [backend/app/main.py](file://backend/app/main.py) - [backend/app/config.py](file://backend/app/config.py) - [backend/app/database.py](file://backend/app/database.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/citations.py](file://backend/app/api/citations.py) - [backend/app/api/deps.py](file://backend/app/api/deps.py) - [backend/app/schemas/auth.py](file://backend/app/schemas/auth.py) - [backend/app/models/user.py](file://backend/app/models/user.py) - [backend/app/models/query.py](file://backend/app/models/query.py) - [backend/app/models/citation_record.py](file://backend/app/models/citation_record.py) - [backend/app/services/auth.py](file://backend/app/services/auth.py) - [backend/app/workers/scheduler.py](file://backend/app/workers/scheduler.py) - [backend/app/workers/citation_engine.py](file://backend/app/workers/citation_engine.py)

引言

本文件为 GEO 平台后端系统的架构文档，基于 FastAPI 构建，采用异步 SQLAlchemy ORM、APScheduler 定时任务与多平台适配器模式，实现查询词管理、引用检测与报告统计等功能。文档覆盖应用配置、中间件、路由组织、生命周期管理、数据库连接与 ORM、异步处理、认证与权限控制、API 设计与错误处理、系统监控与日志、性能优化策略，并给出架构决策的技术背景与权衡。

项目结构

后端采用分层与功能域结合的组织方式：

应用入口与生命周期：app/main.py
配置中心：app/config.py
数据库与依赖注入：app/database.py
API 层：app/api/ 下按功能模块划分（auth、queries、citations、deps）
模型层：app/models/（SQLAlchemy ORM 映射）
服务层：app/services/（业务逻辑封装）
工作器与调度：app/workers/（APScheduler 调度器、引用检测引擎、平台适配器）
测试：tests/（pytest）

graph TB
subgraph "应用入口"
MAIN["app/main.py"]
end
subgraph "配置与数据库"
CFG["app/config.py"]
DB["app/database.py"]
end
subgraph "API 层"
AUTH["app/api/auth.py"]
QUERIES["app/api/queries.py"]
CITATIONS["app/api/citations.py"]
DEPS["app/api/deps.py"]
end
subgraph "模型与服务"
MODEL_USER["app/models/user.py"]
MODEL_QUERY["app/models/query.py"]
MODEL_CIT["app/models/citation_record.py"]
SVC_AUTH["app/services/auth.py"]
end
subgraph "工作器与调度"
SCHED["app/workers/scheduler.py"]
ENGINE["app/workers/citation_engine.py"]
end
MAIN --> AUTH
MAIN --> QUERIES
MAIN --> CITATIONS
MAIN --> SCHED
AUTH --> SVC_AUTH
AUTH --> DB
QUERIES --> DB
CITATIONS --> DB
DEPS --> DB
SVC_AUTH --> CFG
SCHED --> DB
SCHED --> ENGINE
ENGINE --> MODEL_QUERY
ENGINE --> MODEL_CIT
DB --> CFG

图表来源

章节来源

核心组件

应用入口与生命周期：通过 lifespan 钩子在启动时初始化模型与调度器，在关闭时优雅停止。
中间件：启用 CORS，允许前端 localhost:3000 访问。
路由组织：按模块拆分，统一前缀与标签，便于 API 文档生成与维护。
数据库：异步 SQLAlchemy 引擎与会话工厂，依赖注入式获取会话。
认证与权限：OAuth2 密码流 + JWT，依赖注入解析当前用户，未授权时抛出 401。
引擎与调度：APScheduler 定时扫描到期查询，调用 CitationEngine 执行并持久化结果。

章节来源

架构总览

系统采用“API 层-服务层-模型层-基础设施”的分层架构，配合异步 I/O 与定时任务，实现高并发与可扩展的查询与检测能力。

graph TB
CLIENT["客户端/前端"]
FASTAPI["FastAPI 应用<br/>lifespan/CORS"]
ROUTER_AUTH["认证路由"]
ROUTER_QUERIES["查询路由"]
ROUTER_CIT["引用路由"]
DEPS["依赖注入<br/>OAuth2/JWT 解析"]
SVC_AUTH["认证服务<br/>密码哈希/JWT"]
DB["异步数据库<br/>Session 工厂"]
SCHED["查询调度器<br/>APScheduler"]
ENGINE["引用检测引擎<br/>平台适配器"]
CLIENT --> FASTAPI
FASTAPI --> ROUTER_AUTH
FASTAPI --> ROUTER_QUERIES
FASTAPI --> ROUTER_CIT
ROUTER_AUTH --> DEPS
ROUTER_QUERIES --> DEPS
ROUTER_CIT --> DEPS
ROUTER_AUTH --> SVC_AUTH
ROUTER_QUERIES --> DB
ROUTER_CIT --> DB
DEPS --> DB
SVC_AUTH --> DB
SCHED --> DB
SCHED --> ENGINE
ENGINE --> DB

图表来源

详细组件分析

应用入口与生命周期

使用 lifespan 钩子在启动时导入模型并启动查询调度器；在关闭时优雅停止调度器与引擎资源。
注册 CORS 中间件，允许前端跨域访问。
统一注册认证、查询、引用、报告路由，并为“立即执行”路由复用同一前缀。

sequenceDiagram
participant Client as "客户端"
participant App as "FastAPI 应用"
participant Life as "lifespan"
participant Sched as "查询调度器"
Client->>App : 启动请求
App->>Life : 进入 lifespan
Life->>Sched : start()
App-->>Client : 200 OK
Note over App,Sched : 应用运行中
Client->>App : 关闭请求
App->>Life : 退出 lifespan
Life->>Sched : shutdown()
App-->>Client : 200 OK

图表来源

章节来源

backend/app/main.py:13-48

配置与数据库

配置项：数据库连接、Redis、JWT 秘钥与过期时间、浏览器路径、平台 API Key 等。
数据库：异步引擎、会话工厂、基础模型类；提供依赖注入函数以获取会话。
会话行为：非自动提交/刷新/回滚，显式管理事务边界。

flowchart TD
Start(["应用启动"]) --> LoadCfg["加载配置"]
LoadCfg --> InitEngine["创建异步引擎"]
InitEngine --> InitSession["创建会话工厂"]
InitSession --> RegisterDep["注册 get_db 依赖"]
RegisterDep --> Ready(["就绪"])

图表来源

章节来源

认证系统

登录：校验邮箱与密码，成功则签发 JWT。
注册：检查邮箱唯一性，哈希密码后创建用户。
当前用户：通过 OAuth2 密码流获取令牌，解码 JWT 提取用户 ID，查询数据库返回当前用户。
错误处理：未通过凭据验证时返回 401。

sequenceDiagram
participant Client as "客户端"
participant Auth as "认证路由"
participant Svc as "认证服务"
participant DB as "数据库"
Client->>Auth : POST /api/v1/auth/login
Auth->>Svc : authenticate_user(email, password)
Svc->>DB : 查询用户
DB-->>Svc : 用户对象
Svc-->>Auth : 用户或空
Auth-->>Client : {access_token, user} 或 401
Client->>Auth : GET /api/v1/auth/me (携带 Bearer Token)
Auth->>Svc : verify_token(token)
Svc-->>Auth : 载荷
Auth->>DB : 查询用户 by id
DB-->>Auth : 用户对象
Auth-->>Client : 用户信息

图表来源

章节来源

查询与引用 API

查询 API：支持分页、创建、读取、更新、删除，均需当前用户权限。
引用 API：支持分页查询、统计、立即执行查询任务（返回任务状态）。
权限控制：所有路由依赖 get_current_user，未通过验证返回 401。

sequenceDiagram
participant Client as "客户端"
participant Q as "查询路由"
participant D as "依赖注入"
participant S as "服务层"
participant DB as "数据库"
Client->>Q : POST /api/v1/queries/
Q->>D : get_current_user()
D-->>Q : 当前用户
Q->>S : create_query(...)
S->>DB : 写入
DB-->>S : 成功
S-->>Q : 查询对象
Q-->>Client : 201 + 查询对象

图表来源

章节来源

引擎与调度

调度器：每小时扫描 queries 表中 status='active' 且 next_query_at <= now() 的记录，逐条执行。
引擎：对每个平台执行查询，进行品牌匹配与竞争品牌检测，写入 citation_records，并更新查询时间字段。
平台适配器：抽象不同平台的查询接口，统一返回原始响应供匹配器处理。

flowchart TD
Tick["定时触发(每小时)"] --> Scan["扫描到期查询"]
Scan --> Found{"找到待执行查询?"}
Found -- 否 --> Wait["等待下一轮"]
Found -- 是 --> Exec["遍历查询平台执行"]
Exec --> Record["写入引用记录"]
Record --> Update["更新查询时间字段"]
Update --> Done["完成"]
Wait --> Tick

图表来源

章节来源

数据模型与关系

用户：主键 UUID、邮箱唯一、密码哈希、计划与配额、活跃状态、时间戳。
查询：外键用户、关键词、目标品牌、别名、平台集合、频率、状态与时间字段。
引用记录：外键查询、平台、是否引用、位置、文本、竞争品牌、原始响应、时间戳。

erDiagram
USERS {
uuid id PK
string email UK
string password_hash
string name
string plan
int max_queries
bool is_active
timestamp created_at
timestamp updated_at
}
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
}
CITATION_RECORDS {
uuid id PK
uuid query_id FK
string platform
bool cited
int citation_position
text citation_text
jsonb competitor_brands
text raw_response
timestamp queried_at
}
USERS ||--o{ QUERIES : "拥有"
QUERIES ||--o{ CITATION_RECORDS : "产生"

图表来源

章节来源

依赖关系分析

组件内聚：API 路由与服务层职责清晰，模型仅负责映射。
组件耦合：API 依赖服务，服务依赖数据库与配置；调度器依赖引擎与数据库；引擎依赖平台适配器。
依赖注入：通过 FastAPI 依赖系统注入数据库会话与当前用户。
循环依赖：未见明显循环依赖。

graph LR
API_AUTH["api/auth.py"] --> SVC_AUTH["services/auth.py"]
API_AUTH --> DEPS["api/deps.py"]
API_QUERIES["api/queries.py"] --> DEPS
API_CIT["api/citations.py"] --> DEPS
SVC_AUTH --> DB["database.py"]
DEPS --> DB
SCHED["workers/scheduler.py"] --> DB
SCHED --> ENGINE["workers/citation_engine.py"]
ENGINE --> MODELS["models/*.py"]

图表来源

章节来源

性能考量

异步 I/O：数据库与平台查询均采用异步，提升并发吞吐。
会话管理：显式事务边界，避免长事务占用连接池。
定时任务：APScheduler 异步调度，事件循环兼容处理，降低阻塞风险。
索引优化：查询与引用表建立复合索引，加速过滤与排序。
缓存建议：可引入 Redis 缓存热点查询结果与用户会话信息（当前配置已准备）。
日志采样：生产环境建议开启采样与结构化日志，避免高频日志影响性能。

故障排查指南

认证失败：检查 JWT 秘钥、过期时间与前端令牌传递；确认 OAuth2 tokenUrl 与 Bearer 头正确。
数据库连接：核对 DATABASE_URL；确认容器网络可达；查看连接池与超时配置。
定时任务异常：关注调度器日志，检查查询状态与平台适配器可用性；确认 next_query_at 计算逻辑。
引擎执行失败：查看平台适配器错误与原始响应；检查品牌匹配器与竞争品牌检测逻辑。
CORS 问题：确认前端域名与请求头是否在允许范围内。

章节来源

结论

该架构以 FastAPI 为核心，结合异步数据库、定时任务与多平台适配器，形成高可用、可扩展的查询与引用检测系统。通过明确的分层与依赖注入，系统具备良好的可测试性与可维护性。建议在生产环境中完善日志与监控、接入缓存与告警，并持续优化索引与查询计划。

附录

API 设计原则：统一前缀与标签、明确响应模型、一致的状态码与错误消息。
错误处理：在路由层捕获业务异常并转换为标准 HTTP 状态码；在依赖层统一 401 未授权。
响应格式：遵循 Pydantic 模型序列化，确保前后端契约一致。
架构决策背景：选择异步栈以提升 I/O 密集场景性能；APScheduler 简化定时任务编排；JWT 适合无状态认证场景。

18 KiB Raw Blame History Unescape Escape

后端系统架构

目录

引言

项目结构

核心组件

架构总览

详细组件分析

应用入口与生命周期

配置与数据库

认证系统

查询与引用 API

引擎与调度

数据模型与关系

依赖关系分析

性能考量

故障排查指南

结论

附录

18 KiB

Raw Blame History