fischer
/
geo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
geo/.qoder/repowiki/zh/content/快速开始.md

454 lines
17 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 快速开始
<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/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)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本指南面向新开发者，帮助你在最短时间内完成 GEO 平台的本地开发与容器化部署，并掌握核心功能的使用方式。你将学会：
- 环境要求与依赖安装
- 本地开发环境配置
- Docker 容器化部署全流程
- 基本使用示例：用户注册/登录、创建查询任务、查看引用数据
- 调试方法与常见问题解决
## 项目结构
项目采用前后端分离架构，后端基于 FastAPI，前端基于 Next.js，数据库使用 PostgreSQL，缓存使用 Redis，任务调度与浏览器自动化通过 APScheduler 和 Playwright 实现。
```mermaid
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](file://docker-compose.yml#L1-L71)
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/api/citations.py:1-78](file://backend/app/api/citations.py#L1-L78)
- [backend/app/models/user.py:1-41](file://backend/app/models/user.py#L1-L41)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/models/citation_record.py:1-42](file://backend/app/models/citation_record.py#L1-L42)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)
章节来源
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [frontend/README.md:1-37](file://frontend/README.md#L1-L37)
## 核心组件
- 后端 API（FastAPI）：提供认证、查询词管理、引用数据与报告相关接口；内置健康检查端点。
- 前端应用（Next.js）：通过统一的 API 封装调用后端接口，支持注册、登录、查询列表、引用数据与导出。
- 数据库（PostgreSQL）：存储用户、查询词、引用记录等业务数据。
- 缓存与任务（Redis + APScheduler + Playwright）：用于任务调度与浏览器自动化抓取。
章节来源
- [backend/app/main.py:24-47](file://backend/app/main.py#L24-L47)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [backend/app/config.py:7-13](file://backend/app/config.py#L7-L13)
## 架构总览
下图展示了容器化部署时各服务之间的交互关系与启动顺序。
```mermaid
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
```
图表来源
- [docker-compose.yml:3-66](file://docker-compose.yml#L3-L66)
- [backend/app/main.py:30-36](file://backend/app/main.py#L30-L36)
章节来源
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [backend/app/main.py:24-47](file://backend/app/main.py#L24-L47)
## 详细组件分析
### 后端 API 组件
- 应用入口与生命周期：在应用启动时初始化模型与调度器，在关闭时优雅停机。
- 中间件：启用 CORS，允许前端域名访问。
- 路由：认证、查询词、引用数据、报告等模块路由均已挂载。
- 健康检查：提供 /health 探针。
```mermaid
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 : 按计划执行查询
```
图表来源
- [backend/app/main.py:13-21](file://backend/app/main.py#L13-L21)
- [backend/app/main.py:45-47](file://backend/app/main.py#L45-L47)
章节来源
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
### 认证与用户模型
- 认证接口：注册、登录、获取当前用户信息。
- 用户模型：包含邮箱、密码哈希、名称、订阅计划、配额、活跃状态及时间戳字段。
```mermaid
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
}
```
图表来源
- [backend/app/models/user.py:11-41](file://backend/app/models/user.py#L11-L41)
章节来源
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [backend/app/models/user.py:1-41](file://backend/app/models/user.py#L1-L41)
### 查询词与引用数据
- 查询词接口：分页列出、创建、更新、删除查询词。
- 引用数据接口：分页查询引用记录、统计信息、立即触发查询任务。
- 查询词模型：包含关键词、目标品牌、别名、平台集合、频率、状态、下次执行时间等。
- 引用记录模型：包含平台、是否被引、位置、文本、竞品品牌、原始响应、抓取时间等。
```mermaid
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](file://backend/app/models/user.py#L11-L41)
- [backend/app/models/query.py:11-55](file://backend/app/models/query.py#L11-L55)
- [backend/app/models/citation_record.py:11-42](file://backend/app/models/citation_record.py#L11-L42)
章节来源
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/api/citations.py:1-78](file://backend/app/api/citations.py#L1-L78)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/models/citation_record.py:1-42](file://backend/app/models/citation_record.py#L1-L42)
### 前端 API 封装
- 基础地址：优先读取环境变量 NEXT_PUBLIC_API_URL，否则回退到本地后端地址。
- 认证封装：自动注入 Authorization Bearer Token。
- 接口覆盖：认证、查询词、引用数据、报告导出等。
```mermaid
flowchart TD
Start(["发起 API 请求"]) --> BuildHeaders["构建请求头<br/>含 Content-Type 与可选 Authorization"]
BuildHeaders --> FetchCall["fetch 发起请求"]
FetchCall --> RespOk{"响应成功?"}
RespOk --> |是| ParseJson["解析 JSON"]
RespOk --> |否| ThrowErr["抛出错误(包含 HTTP 状态或详情)"]
ParseJson --> End(["返回数据"])
ThrowErr --> End
```
图表来源
- [frontend/lib/api.ts:3-21](file://frontend/lib/api.ts#L3-L21)
章节来源
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
## 依赖分析
- 后端依赖：Web 框架、数据库 ORM、异步驱动、配置校验、认证与安全、缓存与任务调度、浏览器自动化、HTTP 客户端、测试工具等。
- 前端依赖：Next.js、UI 组件库、样式与类型工具等。
- 容器镜像：后端基于 Python slim 镜像，安装 Playwright 依赖；前端基于 Node Alpine 镜像，使用 npm ci 安装依赖。
```mermaid
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](file://backend/requirements.txt#L1-L35)
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)
- [backend/Dockerfile:6-33](file://backend/Dockerfile#L6-L33)
- [frontend/Dockerfile:6-7](file://frontend/Dockerfile#L6-L7)
章节来源
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
## 性能考虑
- 数据库索引：查询词与引用记录表均建立复合索引以优化分页与过滤查询。
- 异步与连接池：使用异步 SQLAlchemy 与异步 PostgreSQL 驱动，提升并发处理能力。
- 任务调度：APSCheduler 在后台按计划执行查询，避免阻塞主请求线程。
- 前端缓存：合理利用浏览器缓存与 Next.js 的静态资源优化策略。
章节来源
- [backend/app/models/query.py:50-54](file://backend/app/models/query.py#L50-L54)
- [backend/app/models/citation_record.py:37-41](file://backend/app/models/citation_record.py#L37-L41)
## 故障排除指南
- 健康检查失败
- 现象：访问 /health 返回异常或容器反复重启。
- 排查：确认数据库与 Redis 健康检查通过；检查后端日志输出。
- 参考：后端健康检查端点与容器编排健康检查配置。
章节来源
- [backend/app/main.py:45-47](file://backend/app/main.py#L45-L47)
- [docker-compose.yml:16-20](file://docker-compose.yml#L16-L20)
- [docker-compose.yml:30-34](file://docker-compose.yml#L30-L34)
- 前端无法访问后端接口
- 现象：前端控制台出现跨域错误或 404。
- 排查：确认后端 CORS 允许前端域名；确认前端 API 基础地址正确；确认后端端口映射为 8000。
- 参考：CORS 配置与前端 API 基础地址。
章节来源
- [backend/app/main.py:30-36](file://backend/app/main.py#L30-L36)
- [frontend/lib/api.ts:1-1](file://frontend/lib/api.ts#L1-L1)
- 数据库连接失败
- 现象：后端启动时报数据库连接错误。
- 排查：确认数据库容器已就绪且凭据正确；检查 .env 或环境变量；确认数据库端口映射为 5432。
- 参考：数据库默认连接串与容器编排。
章节来源
- [backend/app/config.py:7-7](file://backend/app/config.py#L7-L7)
- [docker-compose.yml:8-13](file://docker-compose.yml#L8-L13)
- Redis 连接失败
- 现象：任务调度或缓存相关功能异常。
- 排查：确认 Redis 容器已就绪；检查 REDIS_URL；确认端口映射为 6379。
- 参考：Redis 默认连接串与容器编排。
章节来源
- [backend/app/config.py:8-8](file://backend/app/config.py#L8-L8)
- [docker-compose.yml:22-34](file://docker-compose.yml#L22-L34)
- Playwright 报错（浏览器不可用）
- 现象：抓取任务失败，提示浏览器相关错误。
- 排查：确认容器内已安装 Playwright 依赖；检查浏览器路径配置；必要时重建后端镜像。
- 参考：后端 Dockerfile 中 Playwright 安装步骤。
章节来源
- [backend/Dockerfile:31-33](file://backend/Dockerfile#L31-L33)
## 结论
通过本指南，你可以完成 GEO 平台的环境准备、依赖安装与容器化部署，并快速上手核心功能。建议在本地开发时结合健康检查与日志排查，逐步验证认证、查询与引用数据链路，再进行更复杂的任务调度与导出功能验证。
## 附录
### 环境要求
- 操作系统：Linux/macOS/Windows（WSL2）
- 容器运行时：Docker Engine 与 Compose 插件
- 前端运行时：Node.js 20.x
- 后端运行时：Python 3.11
章节来源
- [backend/Dockerfile:1-1](file://backend/Dockerfile#L1-L1)
- [frontend/Dockerfile:1-1](file://frontend/Dockerfile#L1-L1)
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)
### 依赖安装步骤
- 后端依赖
- 使用 pip 安装 requirements.txt 中的包。
- 安装 Playwright 浏览器与系统依赖。
- 前端依赖
- 使用 npm ci 安装 package.json 中的包。
章节来源
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [backend/Dockerfile:6-33](file://backend/Dockerfile#L6-L33)
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)
- [frontend/Dockerfile:6-7](file://frontend/Dockerfile#L6-L7)
### 本地开发环境配置
- 后端
- 设置数据库与 Redis 连接字符串（默认来自配置类）。
- 启动后端服务，监听 8000 端口。
- 前端
- 设置 NEXT_PUBLIC_API_URL 指向后端地址。
- 启动开发服务器，监听 3000 端口。
章节来源
- [backend/app/config.py:7-13](file://backend/app/config.py#L7-L13)
- [backend/app/main.py:24-47](file://backend/app/main.py#L24-L47)
- [frontend/lib/api.ts:1-1](file://frontend/lib/api.ts#L1-L1)
- [frontend/README.md:5-15](file://frontend/README.md#L5-L15)
### Docker 容器化部署流程
- 步骤 1：准备环境
- 确保 Docker 已安装并运行。
- 步骤 2：构建镜像
- 后端镜像：基于 Python slim，安装系统与 Python 依赖，预装 Playwright。
- 前端镜像：基于 Node Alpine，使用 npm ci 安装依赖。
- 步骤 3：启动容器
- 使用 docker-compose 启动 db、redis、backend、frontend 四个服务。
- 等待数据库与 Redis 健康检查通过后，后端与前端启动完成。
- 步骤 4：访问应用
- 前端：http://localhost:3000
- 后端：http://localhost:8000
章节来源
- [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)
### 基本使用示例
- 用户注册与登录
- 注册：调用认证接口提交用户名、邮箱、密码。
- 登录：提交邮箱与密码获取访问令牌。
- 获取当前用户：携带令牌调用“获取当前用户”接口。
- 创建查询任务
- 列表：分页获取查询词列表。
- 创建：提交关键词、目标品牌、平台集合等参数。
- 更新/删除：按需更新或删除指定查询词。
- 查看引用数据
- 列表：按查询词、平台、日期范围分页查询引用记录。
- 统计：获取引用统计信息。
- 立即执行：触发一次查询任务。
- 导出报告
- 导出 CSV：根据查询 ID 导出对应报告。
章节来源
- [backend/app/api/auth.py:13-42](file://backend/app/api/auth.py#L13-L42)
- [backend/app/api/queries.py:15-85](file://backend/app/api/queries.py#L15-L85)
- [backend/app/api/citations.py:25-77](file://backend/app/api/citations.py#L25-L77)
- [frontend/lib/api.ts:24-56](file://frontend/lib/api.ts#L24-L56)
### 开发调试方法
- 后端
- 使用 Uvicorn 启动并开启热重载，便于快速迭代。
- 关注健康检查端点与日志输出，定位服务状态。
- 前端
- 使用 Next.js 开发服务器，自动刷新页面。
- 在浏览器开发者工具中观察网络请求与错误信息。
- 容器
- 通过 docker-compose logs 查看服务日志。
- 使用 docker exec 进入容器内部排查依赖与端口占用。
章节来源
- [docker-compose.yml:51-66](file://docker-compose.yml#L51-L66)
- [backend/app/main.py:45-47](file://backend/app/main.py#L45-L47)
- [frontend/README.md:5-15](file://frontend/README.md#L5-L15)
Reference in New Issue View Git Blame Copy Permalink