# 快速开始

<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/alembic.ini](file://backend/alembic.ini)
- [backend/alembic/env.py](file://backend/alembic/env.py)
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py)
- [backend/app/database.py](file://backend/app/database.py)
- [backend/app/workers/scheduler.py](file://backend/app/workers/scheduler.py)
- [backend/app/workers/citation_engine.py](file://backend/app/workers/citation_engine.py)
- [frontend/README.md](file://frontend/README.md)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [前置条件与环境准备](#前置条件与环境准备)
4. [一键启动（Docker Compose）](#一键启动docker-compose)
5. [首次运行与基本操作](#首次运行与基本操作)
6. [架构概览](#架构概览)
7. [组件详解](#组件详解)
8. [依赖关系分析](#依赖关系分析)
9. [性能与资源建议](#性能与资源建议)
10. [故障排除](#故障排除)
11. [结语](#结语)

## 简介
本指南面向首次接触 GEO 项目的用户，帮助你在最短时间内完成环境准备、依赖安装、数据库初始化与容器编排，并体验核心功能：用户注册、创建查询任务、查看结果与图表。文档严格基于仓库中的实际配置与代码，提供可复现的命令行步骤与预期行为说明。

## 项目结构
项目采用前后端分离的多容器架构，通过 Docker Compose 统一编排：
- 后端：FastAPI 应用，提供认证、查询词、引用数据、报告等接口；内置定时任务调度器与浏览器自动化能力。
- 前端：Next.js 应用，提供登录、注册、仪表盘、查询管理、引用与报告可视化界面。
- 数据库：PostgreSQL（15），使用 Alembic 进行迁移管理。
- 缓存：Redis（7），用于任务队列与缓存。
- Playwright：用于浏览器自动化（爬虫/抓取）场景。

```mermaid
graph TB
subgraph "容器编排"
DB["PostgreSQL 容器"]
REDIS["Redis 容器"]
BE["后端容器"]
FE["前端容器"]
end
FE --> |"HTTP 3000"| BE
BE --> |"数据库 5432"| DB
BE --> |"缓存 6379"| REDIS
```

**图示来源**
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)

**章节来源**
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)

## 前置条件与环境准备
- 操作系统：Linux/macOS/Windows（WSL2 推荐）
- Docker 与 Docker Compose：用于一键编排
- Git：克隆仓库
- 文本编辑器或 IDE：可选，用于查看/修改配置

说明
- 本项目未要求本地安装 Python 3.9+ 或 Node.js，因为所有运行时均在容器内完成。
- 若你希望在本地直接运行后端或前端，请参考各自镜像版本：
  - 后端镜像基于 Python 3.11（容器内运行）
  - 前端镜像基于 Node.js 20（容器内运行）

**章节来源**
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)

## 一键启动（Docker Compose）
以下为完整的一键启动流程，涵盖容器编排、服务启动顺序、端口映射与健康检查。

步骤
1. 克隆仓库
   - git clone <仓库地址>
   - cd GEO

2. 构建并启动容器
   - docker compose up -d

3. 查看服务状态
   - docker compose ps
   - 预期：db、redis、backend、frontend 均为 Up（healthy）

4. 访问应用
   - 前端：http://localhost:3000
   - 后端：http://localhost:8000（健康检查接口 /health 可用）

5. 停止与清理
   - docker compose down
   - 如需清理数据卷：docker compose down -v

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant Compose as "Docker Compose"
participant DB as "PostgreSQL 容器"
participant Redis as "Redis 容器"
participant Backend as "后端容器"
participant Frontend as "前端容器"
Dev->>Compose : "docker compose up -d"
Compose->>DB : "启动并健康检查"
Compose->>Redis : "启动并健康检查"
Compose->>Backend : "等待 DB/Redis 健康后启动"
Backend->>DB : "连接数据库Alembic 已内置迁移"
Compose->>Frontend : "启动并监听 3000"
Frontend->>Backend : "请求 /api/v1/*"
Backend-->>Frontend : "返回 JSON 响应"
```

**图示来源**
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [backend/app/main.py:45-48](file://backend/app/main.py#L45-L48)

**章节来源**
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [frontend/README.md:5-17](file://frontend/README.md#L5-L17)

## 首次运行与基本操作
首次启动后，你可以进行如下操作以体验核心功能：

1. 用户注册与登录
   - 打开 http://localhost:3000
   - 使用注册页面创建账户
   - 登录后进入仪表盘

2. 创建查询任务
   - 在“查询”页面新建查询词，设置关键词、目标品牌、平台（默认包含 wenxin/kimi）、频率（日/周/月）
   - 提交后，后端调度器会按频率与时间窗口自动执行

3. 查看结果
   - “引用数据”页面查看各平台的引用检测结果（是否被提及、置信度、上下文片段等）
   - “报告”页面查看趋势与平台分布图表

4. 观察后台任务
   - 后端启动时会加载调度器，每小时检查一次到期的查询任务
   - 任务状态会在数据库中持久化，供前端展示

```mermaid
flowchart TD
Start(["提交查询任务"]) --> Schedule["写入数据库<br/>设置 next_query_at"]
Schedule --> Timer["定时器每小时触发"]
Timer --> Check{"查询是否到期？"}
Check --> |否| Wait["等待下个小时"]
Check --> |是| Run["执行查询多平台"]
Run --> Detect["品牌匹配与竞争品牌检测"]
Detect --> Persist["写入引用记录与任务状态"]
Persist --> Report["生成可视化数据"]
Report --> End(["前端展示结果"])
```

**图示来源**
- [backend/app/workers/scheduler.py:51-84](file://backend/app/workers/scheduler.py#L51-L84)
- [backend/app/workers/citation_engine.py:159-234](file://backend/app/workers/citation_engine.py#L159-L234)

**章节来源**
- [backend/app/main.py:38-42](file://backend/app/main.py#L38-L42)
- [backend/app/workers/scheduler.py:30-40](file://backend/app/workers/scheduler.py#L30-L40)
- [backend/app/workers/citation_engine.py:148-170](file://backend/app/workers/citation_engine.py#L148-L170)

## 架构概览
整体架构由容器编排层、后端服务层、前端服务层、数据库与缓存组成。后端通过 Alembic 管理数据库迁移，使用 Redis 存储任务状态，使用 Playwright 进行浏览器自动化。

```mermaid
graph TB
FE["前端应用<br/>Next.js"] --> API["后端 API<br/>FastAPI"]
API --> DB["数据库<br/>PostgreSQL"]
API --> CACHE["缓存<br/>Redis"]
API --> WORKER["任务执行器<br/>CitationEngine"]
WORKER --> PLATFORMS["平台适配器<br/>Kimi/Wenxin"]
API --> SCHED["调度器<br/>APScheduler"]
SCHED --> API
```

**图示来源**
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/config.py:7-13](file://backend/app/config.py#L7-L13)
- [backend/app/workers/scheduler.py:25-39](file://backend/app/workers/scheduler.py#L25-L39)
- [backend/app/workers/citation_engine.py:148-157](file://backend/app/workers/citation_engine.py#L148-L157)

## 组件详解

### 后端应用入口与路由
- 应用生命周期：启动时初始化模型与调度器，关闭时优雅停机
- 路由模块：认证、查询词、引用数据、报告、即时执行查询
- CORS：允许前端 localhost:3000 访问
- 健康检查：/health 返回状态

**章节来源**
- [backend/app/main.py:13-47](file://backend/app/main.py#L13-L47)

### 配置与连接
- 配置来源：.env 文件（通过 pydantic-settings 加载）
- 默认数据库：postgresql+asyncpg://postgres:postgres123@db:5432/geo_platform
- 默认缓存：redis://redis:6379/0
- Playwright 浏览器路径：/ms-playwright
- JWT 密钥与过期时间：开发默认值（生产请务必修改）

**章节来源**
- [backend/app/config.py:4-16](file://backend/app/config.py#L4-L16)

### 数据库与迁移
- 引擎与会话：基于 SQLAlchemy AsyncEngine 与 async session
- 迁移：Alembic 管理，初始迁移包含 users、queries、citation_records、query_tasks、subscriptions 表
- 运行方式：Compose 启动时由后端容器自动执行迁移（见后端 Dockerfile 中的安装与命令）

```mermaid
erDiagram
USERS {
uuid id PK
string email UK
string password_hash
string name
string plan
int max_queries
bool is_active
timestamp created_at
timestamp updated_at
}
QUERIES {
uuid id PK
uuid user_id FK
string keyword
string target_brand
jsonb brand_aliases
jsonb platforms
string frequency
string status
timestamp last_queried_at
timestamp next_query_at
timestamp created_at
timestamp updated_at
}
CITATION_RECORDS {
uuid id PK
uuid query_id FK
string platform
bool cited
int citation_position
text citation_text
jsonb competitor_brands
text raw_response
timestamp queried_at
}
QUERY_TASKS {
uuid id PK
uuid query_id FK
string platform
string status
text error_message
timestamp scheduled_at
timestamp started_at
timestamp completed_at
}
SUBSCRIPTIONS {
uuid id PK
uuid user_id FK
string plan
string status
date start_date
date end_date
numeric amount
string payment_method
string payment_id
timestamp created_at
}
USERS ||--o{ QUERIES : "拥有"
QUERIES ||--o{ CITATION_RECORDS : "产生"
QUERIES ||--o{ QUERY_TASKS : "驱动"
USERS ||--o{ SUBSCRIPTIONS : "订阅"
```

**图示来源**
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py:21-111](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py#L21-L111)

**章节来源**
- [backend/app/database.py:6-28](file://backend/app/database.py#L6-L28)
- [backend/alembic/env.py:10-25](file://backend/alembic/env.py#L10-L25)
- [backend/alembic.ini:89-89](file://backend/alembic.ini#L89-L89)

### 任务调度与执行
- 调度器：APScheduler AsyncIOScheduler，每小时检查到期查询
- 执行器：CitationEngine，遍历查询平台，执行品牌匹配与竞争品牌检测，写入记录并更新查询时间
- 平台适配器：Kimi 与 Wenxin（通过外部平台 API）

```mermaid
classDiagram
class QueryScheduler {
+start()
+check_and_execute_queries()
+shutdown()
}
class CitationEngine {
+execute_query(query, db)
+execute_single_platform(keyword, platform, target_brand, brand_aliases)
+close()
}
class KimiAdapter {
+query(keyword)
+close()
}
class WenxinAdapter {
+query(keyword)
+close()
}
QueryScheduler --> CitationEngine : "调用执行"
CitationEngine --> KimiAdapter : "平台适配"
CitationEngine --> WenxinAdapter : "平台适配"
```

**图示来源**
- [backend/app/workers/scheduler.py:25-95](file://backend/app/workers/scheduler.py#L25-L95)
- [backend/app/workers/citation_engine.py:148-157](file://backend/app/workers/citation_engine.py#L148-L157)

**章节来源**
- [backend/app/workers/scheduler.py:30-89](file://backend/app/workers/scheduler.py#L30-L89)
- [backend/app/workers/citation_engine.py:159-308](file://backend/app/workers/citation_engine.py#L159-L308)

## 依赖关系分析
- 后端依赖：FastAPI、SQLAlchemy、asyncpg、Alembic、Pydantic、Passlib、Redis、APScheduler、Playwright、httpx、python-dotenv、pytest 等
- 前端依赖：Next.js、NextAuth、Radix UI、Recharts、Tailwind 等

```mermaid
graph LR
BE_REQ["后端依赖<br/>requirements.txt"] --> BE_IMG["后端镜像<br/>Python 3.11"]
FE_PKG["前端依赖<br/>package.json"] --> FE_IMG["前端镜像<br/>Node.js 20"]
BE_IMG --> BE_RUN["后端运行时"]
FE_IMG --> FE_RUN["前端运行时"]
```

**图示来源**
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [frontend/package.json:11-38](file://frontend/package.json#L11-L38)
- [backend/Dockerfile:28-39](file://backend/Dockerfile#L28-L39)
- [frontend/Dockerfile:6-14](file://frontend/Dockerfile#L6-L14)

**章节来源**
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [frontend/package.json:11-38](file://frontend/package.json#L11-L38)

## 性能与资源建议
- CPU/内存：建议至少 2 核心 4GB 内存，以便同时运行 PostgreSQL、Redis、后端与前端
- 磁盘：为持久化卷预留足够空间（PostgreSQL 与 Redis 数据目录）
- 网络：Playwright 需要访问外部平台（Kimi/Wenxin），请确保网络连通性
- 日志：后端默认关闭 SQL echo，若调试数据库问题可临时开启

[本节为通用建议，无需特定文件引用]

## 故障排除
常见问题与解决思路
- 容器无法启动或健康检查失败
  - 检查端口占用：确认 5432、6379、8000、3000 未被占用
  - 查看日志：docker compose logs db|redis|backend|frontend
  - 重启服务：docker compose restart db|redis|backend|frontend

- 前端无法访问或跨域报错
  - 确认前端已启动并监听 3000
  - 后端 CORS 已允许 http://localhost:3000，若自定义域名请在后端 CORS 配置中添加

- 数据库连接失败
  - 确认 .env 中 DATABASE_URL 与 docker-compose 中的 db 服务一致
  - 确认数据库初始化已完成（首次启动后端会自动执行迁移）

- Playwright 报错或浏览器不可用
  - 确认后端镜像已安装 Playwright 并完成浏览器安装
  - 如需离线部署，可在 .env 中配置 Playwright 浏览器路径

- 任务未执行或结果为空
  - 检查查询频率与 next_query_at 是否正确
  - 查看查询任务表状态（pending/running/success/failed）

**章节来源**
- [docker-compose.yml:16-20](file://docker-compose.yml#L16-L20)
- [backend/app/main.py:30-36](file://backend/app/main.py#L30-L36)
- [backend/app/config.py:7-11](file://backend/app/config.py#L7-L11)
- [backend/Dockerfile:31-33](file://backend/Dockerfile#L31-L33)
- [backend/app/workers/scheduler.py:51-75](file://backend/app/workers/scheduler.py#L51-L75)

## 结语
按照本指南完成 Docker Compose 一键启动后，你即可在浏览器中完成注册、创建查询任务并查看结果与图表。若需进一步扩展（如接入更多平台、调整调度策略或优化前端交互），可基于现有架构与配置进行定制。