# 技术栈
**本文档引用的文件**
- [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与前端应用，形成可独立开发、测试与部署的完整环境。
```mermaid
graph TB
subgraph "本地开发环境"
FE["前端应用
Next.js 14 + TypeScript"]
BE["后端API
FastAPI + Python 3.11"]
DB["数据库
PostgreSQL 15"]
RC["缓存
Redis 7"]
end
FE --> |"HTTP/HTTPS"| BE
BE --> DB
BE --> RC
```
**图表来源**
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
**章节来源**
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
## 核心组件
- 后端框架：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](file://backend/requirements.txt#L1-L35)
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
## 架构总览
下图展示了从浏览器到后端API、数据库与缓存的整体交互流程，以及定时任务调度器在后台自动执行查询任务的机制。
```mermaid
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](file://backend/app/main.py#L1-L48)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
## 详细组件分析
### 后端：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等。
```mermaid
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](file://backend/app/main.py#L1-L48)
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
**章节来源**
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
### 数据库与ORM：PostgreSQL + SQLAlchemy 异步
- 连接配置：通过配置类集中管理 DATABASE_URL，使用 asyncpg 作为异步驱动。
- 会话管理：定义异步引擎与异步会话工厂，提供依赖注入式数据库会话生成器。
- 模型基类：统一的 declarative_base，便于扩展业务模型。
```mermaid
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](file://backend/app/config.py#L1-L17)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
**章节来源**
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
### 缓存：Redis
- 配置：通过 REDIS_URL 指向 redis:6379/0，容器网络内可达。
- 用途：会话存储、任务状态缓存、限流与临时数据缓存（结合业务场景使用）。
**章节来源**
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
### 任务调度：APScheduler 异步调度器
- 触发周期：每小时检查一次到期的查询任务。
- 查询逻辑：筛选状态为 active 且 next_query_at 小于等于当前时间的任务。
- 执行流程：逐条调用引用引擎执行查询，异常记录日志但不中断整体流程。
- 关闭流程：优雅关闭调度器与引擎资源。
```mermaid
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](file://backend/app/workers/scheduler.py#L1-L95)
**章节来源**
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
### 前端：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与会话管理。
```mermaid
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](file://frontend/package.json#L1-L40)
- [frontend/tsconfig.json:1-27](file://frontend/tsconfig.json#L1-L27)
- [frontend/tailwind.config.ts:1-57](file://frontend/tailwind.config.ts#L1-L57)
- [frontend/.eslintrc.json:1-4](file://frontend/.eslintrc.json#L1-L4)
**章节来源**
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)
- [frontend/tsconfig.json:1-27](file://frontend/tsconfig.json#L1-L27)
- [frontend/tailwind.config.ts:1-57](file://frontend/tailwind.config.ts#L1-L57)
- [frontend/.eslintrc.json:1-4](file://frontend/.eslintrc.json#L1-L4)
- [frontend/next.config.mjs:1-5](file://frontend/next.config.mjs#L1-L5)
### 浏览器自动化：Playwright
- 作用：支持对第三方平台进行无头浏览器模拟，满足动态内容抓取与登录态维护。
- 容器内安装：Dockerfile 中安装 Chromium 并预装 Playwright 依赖。
**章节来源**
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [backend/requirements.txt:25-25](file://backend/requirements.txt#L25-L25)
## 依赖分析
- 后端依赖：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。
```mermaid
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](file://backend/requirements.txt#L1-L35)
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)
**章节来源**
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)
## 性能考虑
- 异步优先：后端使用异步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](file://docker-compose.yml#L1-L71)
- [backend/app/main.py:30-36](file://backend/app/main.py#L30-L36)
- [backend/app/config.py:7-8](file://backend/app/config.py#L7-L8)
- [backend/Dockerfile:6-25](file://backend/Dockerfile#L6-L25)
## 结论
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](file://backend/Dockerfile#L1-L41)
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)