14 KiB

Raw Permalink Blame History

快速开始

**本文引用的文件** - [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)

简介

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

项目结构

项目采用前后端分离的多容器架构，通过 Docker Compose 统一编排：

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

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

章节来源

docker-compose.yml:1-71

前置条件与环境准备

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

说明

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

章节来源

一键启动（Docker Compose）

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

步骤

克隆仓库
- git clone <仓库地址>
- cd GEO
构建并启动容器
- docker compose up -d
查看服务状态
- docker compose ps
- 预期：db、redis、backend、frontend 均为 Up（healthy）
访问应用
- 前端：http://localhost:3000
- 后端：http://localhost:8000（健康检查接口 /health 可用）
停止与清理
- docker compose down
- 如需清理数据卷：docker compose down -v

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 响应"

图示来源

章节来源

首次运行与基本操作

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

用户注册与登录
- 打开 http://localhost:3000
- 使用注册页面创建账户
- 登录后进入仪表盘
创建查询任务
- 在“查询”页面新建查询词，设置关键词、目标品牌、平台（默认包含 wenxin/kimi）、频率（日/周/月）
- 提交后，后端调度器会按频率与时间窗口自动执行
查看结果
- “引用数据”页面查看各平台的引用检测结果（是否被提及、置信度、上下文片段等）
- “报告”页面查看趋势与平台分布图表
观察后台任务
- 后端启动时会加载调度器，每小时检查一次到期的查询任务
- 任务状态会在数据库中持久化，供前端展示

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

图示来源

章节来源

架构概览

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

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

图示来源

组件详解

后端应用入口与路由

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

章节来源

backend/app/main.py:13-47

配置与连接

配置来源：.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

数据库与迁移

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

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

章节来源

任务调度与执行

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

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 : "平台适配"

图示来源

章节来源

依赖关系分析

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

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["前端运行时"]

图示来源

章节来源

性能与资源建议

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

14 KiB Raw Permalink Blame History Unescape Escape

快速开始

目录

简介

项目结构

前置条件与环境准备

一键启动（Docker Compose）

首次运行与基本操作

架构概览

组件详解

后端应用入口与路由

配置与连接

数据库与迁移

任务调度与执行

依赖关系分析

性能与资源建议

故障排除

结语

14 KiB

Raw Permalink Blame History