390 lines
14 KiB
Markdown
390 lines
14 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/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 一键启动后，你即可在浏览器中完成注册、创建查询任务并查看结果与图表。若需进一步扩展（如接入更多平台、调整调度策略或优化前端交互），可基于现有架构与配置进行定制。 |