348 lines
16 KiB
Markdown
348 lines
16 KiB
Markdown
# 技术栈
|
||
|
||
<cite>
|
||
**本文档引用的文件**
|
||
- [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)
|
||
</cite>
|
||
|
||
## 目录
|
||
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["前端应用<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](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) |