17 KiB
17 KiB
快速开始
**本文引用的文件** - [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/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/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) - [frontend/lib/api.ts](file://frontend/lib/api.ts) - [frontend/README.md](file://frontend/README.md)目录
简介
本指南面向新开发者，帮助你在最短时间内完成 GEO 平台的本地开发与容器化部署，并掌握核心功能的使用方式。你将学会：
- 环境要求与依赖安装
- 本地开发环境配置
- Docker 容器化部署全流程
- 基本使用示例：用户注册/登录、创建查询任务、查看引用数据
- 调试方法与常见问题解决
项目结构
项目采用前后端分离架构，后端基于 FastAPI，前端基于 Next.js，数据库使用 PostgreSQL，缓存使用 Redis，任务调度与浏览器自动化通过 APScheduler 和 Playwright 实现。
graph TB
subgraph "容器编排"
DC["docker-compose.yml"]
end
subgraph "后端服务"
BK_MAIN["backend/app/main.py"]
BK_CONF["backend/app/config.py"]
BK_AUTH["backend/app/api/auth.py"]
BK_QUERIES["backend/app/api/queries.py"]
BK_CIT["backend/app/api/citations.py"]
BK_MODELS["backend/app/models/*"]
BK_REQ["backend/requirements.txt"]
BK_DOCK["backend/Dockerfile"]
end
subgraph "前端服务"
FE_API["frontend/lib/api.ts"]
FE_PKG["frontend/package.json"]
FE_README["frontend/README.md"]
FE_DOCK["frontend/Dockerfile"]
end
DB["PostgreSQL 容器"]
RDS["Redis 容器"]
DC --> DB
DC --> RDS
DC --> BK_MAIN
DC --> FE_API
BK_MAIN --> BK_AUTH
BK_MAIN --> BK_QUERIES
BK_MAIN --> BK_CIT
BK_MAIN --> BK_MODELS
BK_MAIN --> BK_CONF
FE_API --> BK_MAIN
图表来源
- docker-compose.yml:1-71
- backend/app/main.py:1-48
- backend/app/config.py:1-17
- backend/app/api/auth.py:1-43
- backend/app/api/queries.py:1-86
- backend/app/api/citations.py:1-78
- backend/app/models/user.py:1-41
- backend/app/models/query.py:1-55
- backend/app/models/citation_record.py:1-42
- frontend/lib/api.ts:1-58
- backend/requirements.txt:1-35
- frontend/package.json:1-40
章节来源
核心组件
- 后端 API（FastAPI）：提供认证、查询词管理、引用数据与报告相关接口；内置健康检查端点。
- 前端应用（Next.js）：通过统一的 API 封装调用后端接口，支持注册、登录、查询列表、引用数据与导出。
- 数据库（PostgreSQL）：存储用户、查询词、引用记录等业务数据。
- 缓存与任务（Redis + APScheduler + Playwright）：用于任务调度与浏览器自动化抓取。
章节来源
架构总览
下图展示了容器化部署时各服务之间的交互关系与启动顺序。
graph TB
subgraph "网络"
L3000["前端: http://localhost:3000"]
L8000["后端: http://localhost:8000"]
end
subgraph "容器"
DB["Postgres:5432"]
RDS["Redis:6379"]
BE["后端容器"]
FE["前端容器"]
end
L3000 --> FE
FE --> BE
BE --> DB
BE --> RDS
图表来源
章节来源
详细组件分析
后端 API 组件
- 应用入口与生命周期：在应用启动时初始化模型与调度器，在关闭时优雅停机。
- 中间件：启用 CORS，允许前端域名访问。
- 路由：认证、查询词、引用数据、报告等模块路由均已挂载。
- 健康检查：提供 /health 探针。
sequenceDiagram
participant C as "客户端"
participant F as "前端(Next.js)"
participant B as "后端(FastAPI)"
participant D as "数据库(PostgreSQL)"
participant Q as "调度器(APScheduler)"
C->>F : 打开页面
F->>B : GET /health
B-->>F : {"status" : "ok"}
Note over B,Q : 应用启动时启动调度器
B->>Q : 启动任务调度
Q->>D : 按计划执行查询
图表来源
章节来源
认证与用户模型
- 认证接口：注册、登录、获取当前用户信息。
- 用户模型：包含邮箱、密码哈希、名称、订阅计划、配额、活跃状态及时间戳字段。
classDiagram
class User {
+UUID id
+string email
+string password_hash
+string name
+string plan
+int max_queries
+bool is_active
+datetime created_at
+datetime updated_at
}
图表来源
章节来源
查询词与引用数据
- 查询词接口：分页列出、创建、更新、删除查询词。
- 引用数据接口：分页查询引用记录、统计信息、立即触发查询任务。
- 查询词模型：包含关键词、目标品牌、别名、平台集合、频率、状态、下次执行时间等。
- 引用记录模型：包含平台、是否被引、位置、文本、竞品品牌、原始响应、抓取时间等。
erDiagram
USER ||--o{ QUERY : "拥有"
QUERY ||--o{ CITATION_RECORD : "产生"
USER {
uuid id
string email
string name
}
QUERY {
uuid id
uuid user_id
string keyword
string target_brand
json brand_aliases
json platforms
string frequency
string status
timestamp last_queried_at
timestamp next_query_at
}
CITATION_RECORD {
uuid id
uuid query_id
string platform
bool cited
int citation_position
text citation_text
json competitor_brands
text raw_response
timestamp queried_at
}
图表来源
- backend/app/models/user.py:11-41
- backend/app/models/query.py:11-55
- backend/app/models/citation_record.py:11-42
章节来源
- backend/app/api/queries.py:1-86
- backend/app/api/citations.py:1-78
- backend/app/models/query.py:1-55
- backend/app/models/citation_record.py:1-42
前端 API 封装
- 基础地址：优先读取环境变量 NEXT_PUBLIC_API_URL，否则回退到本地后端地址。
- 认证封装：自动注入 Authorization Bearer Token。
- 接口覆盖：认证、查询词、引用数据、报告导出等。
flowchart TD
Start(["发起 API 请求"]) --> BuildHeaders["构建请求头<br/>含 Content-Type 与可选 Authorization"]
BuildHeaders --> FetchCall["fetch 发起请求"]
FetchCall --> RespOk{"响应成功?"}
RespOk --> |是| ParseJson["解析 JSON"]
RespOk --> |否| ThrowErr["抛出错误(包含 HTTP 状态或详情)"]
ParseJson --> End(["返回数据"])
ThrowErr --> End
图表来源
章节来源
依赖分析
- 后端依赖：Web 框架、数据库 ORM、异步驱动、配置校验、认证与安全、缓存与任务调度、浏览器自动化、HTTP 客户端、测试工具等。
- 前端依赖：Next.js、UI 组件库、样式与类型工具等。
- 容器镜像：后端基于 Python slim 镜像，安装 Playwright 依赖；前端基于 Node Alpine 镜像，使用 npm ci 安装依赖。
graph LR
subgraph "后端"
PY["Python 3.11"]
REQ["requirements.txt"]
PLY["Playwright(chromium)"]
end
subgraph "前端"
NODE["Node 20"]
PKG["package.json"]
end
REQ --> PY
PLY --> PY
PKG --> NODE
图表来源
- backend/requirements.txt:1-35
- frontend/package.json:1-40
- backend/Dockerfile:6-33
- frontend/Dockerfile:6-7
章节来源
- backend/requirements.txt:1-35
- frontend/package.json:1-40
- backend/Dockerfile:1-41
- frontend/Dockerfile:1-15
性能考虑
- 数据库索引：查询词与引用记录表均建立复合索引以优化分页与过滤查询。
- 异步与连接池：使用异步 SQLAlchemy 与异步 PostgreSQL 驱动，提升并发处理能力。
- 任务调度：APSCheduler 在后台按计划执行查询，避免阻塞主请求线程。
- 前端缓存：合理利用浏览器缓存与 Next.js 的静态资源优化策略。
章节来源
故障排除指南
-
健康检查失败
- 现象：访问 /health 返回异常或容器反复重启。
- 排查：确认数据库与 Redis 健康检查通过；检查后端日志输出。
- 参考：后端健康检查端点与容器编排健康检查配置。
章节来源
-
前端无法访问后端接口
- 现象：前端控制台出现跨域错误或 404。
- 排查：确认后端 CORS 允许前端域名；确认前端 API 基础地址正确；确认后端端口映射为 8000。
- 参考：CORS 配置与前端 API 基础地址。
章节来源
-
数据库连接失败
- 现象：后端启动时报数据库连接错误。
- 排查：确认数据库容器已就绪且凭据正确；检查 .env 或环境变量；确认数据库端口映射为 5432。
- 参考：数据库默认连接串与容器编排。
章节来源
-
Redis 连接失败
- 现象：任务调度或缓存相关功能异常。
- 排查：确认 Redis 容器已就绪；检查 REDIS_URL；确认端口映射为 6379。
- 参考：Redis 默认连接串与容器编排。
章节来源
-
Playwright 报错（浏览器不可用）
- 现象：抓取任务失败，提示浏览器相关错误。
- 排查：确认容器内已安装 Playwright 依赖；检查浏览器路径配置；必要时重建后端镜像。
- 参考：后端 Dockerfile 中 Playwright 安装步骤。
章节来源
结论
通过本指南，你可以完成 GEO 平台的环境准备、依赖安装与容器化部署，并快速上手核心功能。建议在本地开发时结合健康检查与日志排查，逐步验证认证、查询与引用数据链路，再进行更复杂的任务调度与导出功能验证。
附录
环境要求
- 操作系统：Linux/macOS/Windows（WSL2）
- 容器运行时：Docker Engine 与 Compose 插件
- 前端运行时：Node.js 20.x
- 后端运行时：Python 3.11
章节来源
依赖安装步骤
- 后端依赖
- 使用 pip 安装 requirements.txt 中的包。
- 安装 Playwright 浏览器与系统依赖。
- 前端依赖
- 使用 npm ci 安装 package.json 中的包。
章节来源
- backend/requirements.txt:1-35
- backend/Dockerfile:6-33
- frontend/package.json:1-40
- frontend/Dockerfile:6-7
本地开发环境配置
- 后端
- 设置数据库与 Redis 连接字符串（默认来自配置类）。
- 启动后端服务，监听 8000 端口。
- 前端
- 设置 NEXT_PUBLIC_API_URL 指向后端地址。
- 启动开发服务器，监听 3000 端口。
章节来源
- backend/app/config.py:7-13
- backend/app/main.py:24-47
- frontend/lib/api.ts:1-1
- frontend/README.md:5-15
Docker 容器化部署流程
- 步骤 1：准备环境
- 确保 Docker 已安装并运行。
- 步骤 2：构建镜像
- 后端镜像：基于 Python slim，安装系统与 Python 依赖，预装 Playwright。
- 前端镜像：基于 Node Alpine，使用 npm ci 安装依赖。
- 步骤 3：启动容器
- 使用 docker-compose 启动 db、redis、backend、frontend 四个服务。
- 等待数据库与 Redis 健康检查通过后，后端与前端启动完成。
- 步骤 4：访问应用
章节来源
基本使用示例
- 用户注册与登录
- 注册：调用认证接口提交用户名、邮箱、密码。
- 登录：提交邮箱与密码获取访问令牌。
- 获取当前用户：携带令牌调用“获取当前用户”接口。
- 创建查询任务
- 列表：分页获取查询词列表。
- 创建：提交关键词、目标品牌、平台集合等参数。
- 更新/删除：按需更新或删除指定查询词。
- 查看引用数据
- 列表：按查询词、平台、日期范围分页查询引用记录。
- 统计：获取引用统计信息。
- 立即执行：触发一次查询任务。
- 导出报告
- 导出 CSV：根据查询 ID 导出对应报告。
章节来源
- backend/app/api/auth.py:13-42
- backend/app/api/queries.py:15-85
- backend/app/api/citations.py:25-77
- frontend/lib/api.ts:24-56
开发调试方法
- 后端
- 使用 Uvicorn 启动并开启热重载，便于快速迭代。
- 关注健康检查端点与日志输出，定位服务状态。
- 前端
- 使用 Next.js 开发服务器，自动刷新页面。
- 在浏览器开发者工具中观察网络请求与错误信息。
- 容器
- 通过 docker-compose logs 查看服务日志。
- 使用 docker exec 进入容器内部排查依赖与端口占用。
章节来源