16 KiB

Raw Permalink Blame History

技术栈

**本文档引用的文件** - [docker-compose.yml](file://docker-compose.yml) - [backend/Dockerfile](file://backend/Dockerfile) - [frontend/Dockerfile](file://frontend/Dockerfile) - [backend/requirements.txt](file://backend/requirements.txt) - [frontend/package.json](file://frontend/package.json) - [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/workers/scheduler.py](file://backend/app/workers/scheduler.py) - [frontend/tsconfig.json](file://frontend/tsconfig.json) - [frontend/tailwind.config.ts](file://frontend/tailwind.config.ts) - [frontend/.eslintrc.json](file://frontend/.eslintrc.json) - [frontend/next.config.mjs](file://frontend/next.config.mjs)

简介

本技术栈文档面向GEO项目的开发者与运维人员，系统梳理了后端（FastAPI + Python 3.9+）、前端（Next.js 14 + TypeScript）、数据库（PostgreSQL）、缓存（Redis）以及容器化部署方案。文档重点解释各技术选型的原因与优势，并结合仓库中的实际配置文件，给出版本要求、兼容性信息与最佳实践建议，帮助团队快速理解并高效迭代。

项目结构

项目采用前后端分离的多服务架构，通过 Docker Compose 编排数据库、缓存、后端API与前端应用，形成可独立开发、测试与部署的完整环境。

graph TB
subgraph "本地开发环境"
FE["前端应用<br/>Next.js 14 + TypeScript"]
BE["后端API<br/>FastAPI + Python 3.11"]
DB["数据库<br/>PostgreSQL 15"]
RC["缓存<br/>Redis 7"]
end
FE --> |"HTTP/HTTPS"| BE
BE --> DB
BE --> RC

图表来源

章节来源

docker-compose.yml:1-71

核心组件

后端框架：FastAPI（高性能异步Web框架，自动生成OpenAPI文档，类型安全）
数据库：PostgreSQL（企业级关系型数据库，支持事务与复杂查询）
缓存：Redis（高性能键值存储，用于会话、限流与任务队列）
前端框架：Next.js 14（App Router架构，SSR/SSG支持，TypeScript原生支持）
异步ORM：SQLAlchemy 2.x（异步引擎与会话管理）
任务调度：APScheduler（基于事件循环的异步调度器）
浏览器自动化：Playwright（跨平台无头浏览器）
开发工具链：TypeScript、Tailwind CSS、ESLint、PostCSS、Tailwind CSS插件

章节来源

架构总览

下图展示了从浏览器到后端API、数据库与缓存的整体交互流程，以及定时任务调度器在后台自动执行查询任务的机制。

graph TB
Browser["浏览器/移动端"] --> NextUI["Next.js 前端应用"]
NextUI --> FastAPI["FastAPI 后端"]
FastAPI --> SQLAlchemy["SQLAlchemy 异步ORM"]
SQLAlchemy --> PostgreSQL["PostgreSQL 数据库"]
FastAPI --> Redis["Redis 缓存"]
FastAPI --> APS["APScheduler 定时任务"]
APS --> Playwright["Playwright 浏览器自动化"]
Playwright --> ThirdParty["第三方平台接口"]

图表来源

详细组件分析

后端：FastAPI + Python 3.11

应用入口与生命周期：通过 lifespan 钩子在启动时初始化模型与调度器，在关闭时优雅停机。
中间件与路由：启用CORS以允许前端localhost访问；按模块注册认证、查询、引用数据与报告相关路由。
健康检查：提供 /health 接口便于容器编排健康检查。
版本与依赖：FastAPI≥0.109.0、Uvicorn标准变体、Pydantic≥2.0、SQLAlchemy≥2.0、Redis、APScheduler≥3.10、HTTPX、Playwright≥1.40、pytest-asyncio等。

sequenceDiagram
participant Client as "客户端"
participant API as "FastAPI 应用"
participant Router as "路由处理器"
participant DB as "异步数据库会话"
participant ORM as "SQLAlchemy 模型"
Client->>API : "HTTP 请求"
API->>Router : "分发到对应路由"
Router->>DB : "获取异步会话"
DB->>ORM : "执行查询/更新"
ORM-->>DB : "返回结果"
DB-->>Router : "提交/回滚"
Router-->>API : "序列化响应"
API-->>Client : "HTTP 响应"

图表来源

章节来源

数据库与ORM：PostgreSQL + SQLAlchemy 异步

连接配置：通过配置类集中管理 DATABASE_URL，使用 asyncpg 作为异步驱动。
会话管理：定义异步引擎与异步会话工厂，提供依赖注入式数据库会话生成器。
模型基类：统一的 declarative_base，便于扩展业务模型。

flowchart TD
Start(["应用启动"]) --> LoadCfg["加载数据库配置"]
LoadCfg --> CreateEngine["创建异步引擎"]
CreateEngine --> SessionFactory["创建异步会话工厂"]
SessionFactory --> Request["请求到达"]
Request --> GetSession["依赖注入获取会话"]
GetSession --> ExecOp["执行ORM操作"]
ExecOp --> Commit["提交事务"]
Commit --> Close["关闭会话"]
Close --> End(["请求结束"])

图表来源

章节来源

缓存：Redis

配置：通过 REDIS_URL 指向 redis:6379/0，容器网络内可达。
用途：会话存储、任务状态缓存、限流与临时数据缓存（结合业务场景使用）。

章节来源

backend/app/config.py:1-17

任务调度：APScheduler 异步调度器

触发周期：每小时检查一次到期的查询任务。
查询逻辑：筛选状态为 active 且 next_query_at 小于等于当前时间的任务。
执行流程：逐条调用引用引擎执行查询，异常记录日志但不中断整体流程。
关闭流程：优雅关闭调度器与引擎资源。

flowchart TD
S(["启动调度器"]) --> AddJob["添加定时任务每小时"]
AddJob --> Loop{"事件循环存在？"}
Loop --> |是| RunTask["在当前事件循环创建任务"]
Loop --> |否| NewLoop["新建事件循环执行"]
RunTask --> Check["查询数据库：查找到期任务"]
NewLoop --> Check
Check --> Found{"找到任务？"}
Found --> |否| Wait["等待下次触发"]
Found --> |是| Exec["逐条执行查询"]
Exec --> Wait
Wait --> AddJob

图表来源

backend/app/workers/scheduler.py:1-95

章节来源

backend/app/workers/scheduler.py:1-95

前端：Next.js 14 + TypeScript

框架版本：Next.js 14.2.35，使用 App Router 架构组织页面与布局。
类型系统：TypeScript 5，严格模式与路径别名配置，确保类型安全。
UI与样式：Tailwind CSS 3.4.1，配合 tailwindcss-animate 插件实现动画与主题扩展。
工具链：ESLint 8（Next.js核心Web Vitals与TypeScript规则），PostCSS，开发脚本（dev/build/start/lint）。
认证：NextAuth.js 4.24.14，集成OAuth与会话管理。

graph LR
Next["Next.js 14 App Router"] --> TS["TypeScript 5"]
Next --> Tailwind["Tailwind CSS 3.4.1"]
Tailwind --> Animate["tailwindcss-animate"]
Next --> ESLint["ESLint 8"]
Next --> NextAuth["NextAuth.js 4.24.14"]
Next --> Radix["Radix UI 组件库"]
Next --> Recharts["Recharts 图表库"]

图表来源

章节来源

浏览器自动化：Playwright

作用：支持对第三方平台进行无头浏览器模拟，满足动态内容抓取与登录态维护。
容器内安装：Dockerfile 中安装 Chromium 并预装 Playwright 依赖。

章节来源

依赖分析

后端依赖：FastAPI、Uvicorn、SQLAlchemy 2.x、asyncpg、Alembic、Pydantic 2.x、Pydantic Settings、python-jose、passlib、redis、apscheduler、httpx、python-dotenv、pytest、pytest-asyncio、aiosqlite、playwright。
前端依赖：Next.js 14、React 18、NextAuth.js、Radix UI、Lucide React、Recharts、Tailwind CSS、Tailwind Merge、Tailwind CSS Animate、TypeScript、ESLint、PostCSS、Tailwind CSS。

graph TB
subgraph "后端"
F["FastAPI"]
S["SQLAlchemy 2.x"]
R["Redis"]
P["Playwright"]
A["APScheduler"]
end
subgraph "前端"
N["Next.js 14"]
T["TypeScript"]
TA["Tailwind CSS"]
E["ESLint"]
NA["NextAuth.js"]
end
N --> F
F --> S
F --> R
F --> A
F --> P
N --> TA
N --> E
N --> NA
N --> T

图表来源

章节来源

性能考虑

异步优先：后端使用异步ORM与异步调度器，减少阻塞，提升并发处理能力。
事件循环：调度器在当前事件循环或新建事件循环中执行任务，避免阻塞主事件循环。
缓存策略：Redis用于热点数据与会话缓存，降低数据库压力；需结合业务设计合理的过期策略。
数据库连接：异步引擎与会话池化配置，避免频繁建立/断开连接。
前端优化：Next.js 14 App Router支持服务端渲染与静态生成，结合Tailwind CSS减少打包体积与样式开销。

故障排除指南

健康检查失败
- 现象：容器未就绪或重启频繁。
- 排查：查看 docker-compose 中 db 与 redis 的 healthcheck 配置，确认端口映射与环境变量正确。
CORS 问题
- 现象：前端跨域请求被拒绝。
- 排查：确认后端 CORS 配置允许前端地址（默认允许 http://localhost:3000）。
数据库连接失败
- 现象：应用启动时报数据库连接错误。
- 排查：核对 DATABASE_URL 是否指向容器内的 db 服务，确认网络连通与凭据正确。
Redis 连接失败
- 现象：缓存不可用或任务调度异常。
- 排查：核对 REDIS_URL 指向容器内的 redis 服务，确认端口映射与权限设置。
Playwright 依赖问题
- 现象：容器内无法启动浏览器或报缺少系统库。
- 排查：确认 Dockerfile 中已安装 Playwright 依赖与浏览器，必要时重建镜像。
前端热更新异常
- 现象：修改代码后未生效。
- 排查：确认前端容器挂载了 node_modules 与源码目录，检查端口映射与命令是否正确。

章节来源

结论

GEO项目采用现代全栈技术栈：后端以 FastAPI 为核心，结合 SQLAlchemy 异步ORM与 APscheduler 实现高并发与可维护的任务调度；前端以 Next.js 14 为基础，配合 TypeScript、Tailwind CSS 与 NextAuth.js 构建现代化用户界面与认证体系；数据库与缓存分别采用 PostgreSQL 与 Redis，满足生产级数据持久化与缓存需求。通过 Docker Compose 实现一键编排，便于本地开发与部署。

附录

技术选型与优势

FastAPI
- 优势：高性能、自动生成OpenAPI文档、类型驱动的接口校验、异步支持。
- 适用：高并发API、微服务、可观测性与可测试性要求高的场景。
Next.js 14 + TypeScript
- 优势：App Router架构、SSR/SSG、原生TypeScript支持、严格的类型约束。
- 适用：现代Web应用、SEO友好、团队协作与质量保障。
PostgreSQL
- 优势：ACID事务、复杂查询、扩展性强、生态完善。
- 适用：数据一致性要求高、业务逻辑复杂的场景。
Redis
- 优势：高性能KV存储、丰富的数据结构、发布订阅与事务支持。
- 适用：会话存储、缓存、限流、任务队列。
SQLAlchemy 异步ORM
- 优势：类型安全、异步会话、灵活的查询DSL、与FastAPI依赖注入无缝集成。
- 适用：需要强类型与异步IO的数据库访问层。

版本与兼容性

Python：后端使用 3.11（容器镜像），建议本地开发与CI保持一致。
Node.js：前端使用 20（容器镜像），建议本地开发与CI保持一致。
Next.js：14.2.35，使用 App Router 与TypeScript。
FastAPI：≥0.109.0，配合 Uvicorn 标准变体。
SQLAlchemy：≥2.0，异步引擎与会话。
Pydantic：≥2.0，配置与数据验证。
Redis：7-alpine，使用默认端口6379。
PostgreSQL：15-alpine，使用默认端口5432。
Playwright：≥1.40，容器内预装Chromium与依赖。
APScheduler：≥3.10，异步调度器。

容器化与部署要点

多阶段思路：后端基于 slim 镜像，安装系统依赖与Playwright；前端基于 alpine 镜像，最小化依赖安装。
端口映射：后端8000、前端3000、数据库5432、缓存6379。
健康检查：db 与 redis 提供健康检查，后端提供 /health。
开发体验：前端启用 --reload（开发命令），后端使用 uvicorn --reload。

章节来源

16 KiB Raw Permalink Blame History Unescape Escape

技术栈

目录

简介

项目结构

核心组件

架构总览

详细组件分析

后端：FastAPI + Python 3.11

数据库与ORM：PostgreSQL + SQLAlchemy 异步

缓存：Redis

任务调度：APScheduler 异步调度器

前端：Next.js 14 + TypeScript

浏览器自动化：Playwright

依赖分析

性能考虑

故障排除指南

结论

附录

技术选型与优势

版本与兼容性

容器化与部署要点

16 KiB

Raw Permalink Blame History