# 快速开始

<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)