geo/.qoder/repowiki/zh/content/项目概述/技术栈.md

技术栈

**本文档引用的文件** - [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)

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖分析
7. 性能考虑
8. 故障排除指南
9. 结论
10. 附录

简介

本技术栈文档面向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
• backend/Dockerfile:1-41
• frontend/Dockerfile:1-15

章节来源

• 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插件

章节来源

• backend/requirements.txt:1-35
• frontend/package.json:1-40
• backend/app/main.py:1-48
• backend/app/database.py:1-29
• backend/app/config.py:1-17
• backend/app/workers/scheduler.py:1-95

架构总览

下图展示了从浏览器到后端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["第三方平台接口"]

图表来源

• backend/app/main.py:1-48
• backend/app/database.py:1-29
• backend/app/config.py:1-17
• backend/app/workers/scheduler.py:1-95

详细组件分析

后端：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 响应"

图表来源

• backend/app/main.py:1-48
• backend/app/api/auth.py:1-43
• backend/app/database.py:1-29

章节来源

• backend/app/main.py:1-48
• backend/app/api/auth.py:1-43
• backend/requirements.txt:1-35

数据库与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(["请求结束"])

图表来源

• backend/app/config.py:1-17
• backend/app/database.py:1-29

章节来源

• backend/app/config.py:1-17
• backend/app/database.py:1-29

缓存：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 图表库"]

图表来源

• frontend/package.json:1-40
• frontend/tsconfig.json:1-27
• frontend/tailwind.config.ts:1-57
• frontend/.eslintrc.json:1-4

章节来源

• frontend/package.json:1-40
• frontend/tsconfig.json:1-27
• frontend/tailwind.config.ts:1-57
• frontend/.eslintrc.json:1-4
• frontend/next.config.mjs:1-5

浏览器自动化：Playwright

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

章节来源

• backend/Dockerfile:1-41
• backend/requirements.txt:25-25

依赖分析

• 后端依赖：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

图表来源

• backend/requirements.txt:1-35
• frontend/package.json:1-40

章节来源

• backend/requirements.txt:1-35
• frontend/package.json:1-40

性能考虑

• 异步优先：后端使用异步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 与源码目录，检查端口映射与命令是否正确。

章节来源

• docker-compose.yml:1-71
• backend/app/main.py:30-36
• backend/app/config.py:7-8
• backend/Dockerfile:6-25

结论

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。

章节来源

• backend/Dockerfile:1-41
• frontend/Dockerfile:1-15
• docker-compose.yml:1-71