GEO 平台 - 后端服务
基于 Python FastAPI 构建的异步后端服务，提供 RESTful API 供前端调用。
环境要求
- Python 3.11+
- PostgreSQL 15
- Redis 7
- Node.js 18+（如需运行 Playwright 浏览器自动化）
安装步骤
1. 创建虚拟环境
cd backend
python3 -m venv venv
source venv/bin/activate # macOS/Linux
# 或
venv\Scripts\activate # Windows
2. 安装依赖
pip install -r requirements.txt
3. 安装 Playwright 浏览器
playwright install chromium
4. 配置环境变量
复制项目根目录的 .env.example 为 .env，并根据需要修改配置：
cp ../.env.example ../.env
5. 初始化数据库
alembic upgrade head
运行命令
开发模式（热重载）
uvicorn app.main:app --reload --port 8000
生产模式
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
启动后访问：
API 端点清单
认证模块 /api/v1/auth
| 方法 |
端点 |
说明 |
认证要求 |
| POST |
/register |
用户注册 |
无需认证 |
| POST |
/login |
用户登录，返回 JWT Token |
无需认证 |
| GET |
/me |
获取当前登录用户信息 |
Bearer Token |
| POST |
/forgot-password |
发送密码重置链接 |
无需认证 |
| POST |
/reset-password |
使用令牌重置密码 |
无需认证 |
| POST |
/verify-email |
邮箱验证码验证 |
无需认证 |
| POST |
/resend-verification |
重新发送邮箱验证码 |
无需认证 |
| PUT |
/change-password |
修改当前用户密码 |
Bearer Token |
| PUT |
/profile |
更新用户资料 |
Bearer Token |
查询词管理 /api/v1/queries
| 方法 |
端点 |
说明 |
认证要求 |
| GET |
/ |
获取查询词列表（分页） |
Bearer Token |
| POST |
/ |
创建新查询词 |
Bearer Token |
| GET |
/{query_id} |
获取单个查询词详情 |
Bearer Token |
| PUT |
/{query_id} |
更新查询词 |
Bearer Token |
| DELETE |
/{query_id} |
删除查询词 |
Bearer Token |
| POST |
/{query_id}/run-now |
立即执行查询任务 |
Bearer Token |
引用数据 /api/v1/citations
| 方法 |
端点 |
说明 |
认证要求 |
| GET |
/ |
获取引用记录列表（支持筛选） |
Bearer Token |
| GET |
/stats |
获取引用统计分析 |
Bearer Token |
查询参数说明（GET /）：
query_id: 按查询词筛选（UUID）platform: 按平台名称筛选start_date: 起始日期（ISO 8601）end_date: 结束日期（ISO 8601）skip: 分页偏移量，默认 0limit: 每页数量，默认 20，最大 100
报告导出 /api/v1/reports
| 方法 |
端点 |
说明 |
认证要求 |
| GET |
/export/csv |
导出查询词的引用数据为 CSV |
Bearer Token |
查询参数：
query_id（必填）: 要导出的查询词 IDformat: 导出格式，目前仅支持 csv
系统接口
| 方法 |
端点 |
说明 |
| GET |
/health |
服务健康检查 |
数据库迁移
本项目使用 Alembic 管理数据库迁移。
# 执行所有迁移（升级到最新版本）
alembic upgrade head
# 回滚一次迁移
alembic downgrade -1
# 创建新的自动迁移（修改模型后执行）
alembic revision --autogenerate -m "描述本次变更"
# 查看当前版本
alembic current
# 查看迁移历史
alembic history
项目结构
backend/
├── alembic/
│ ├── versions/ # 迁移脚本
│ ├── env.py # Alembic 环境配置
│ └── script.py.mako # 迁移脚本模板
├── app/
│ ├── api/ # API 路由层
│ │ ├── auth.py # 认证接口（注册/登录/密码/资料）
│ │ ├── queries.py # 查询词 CRUD 与立即执行
│ │ ├── citations.py # 引用数据查询与统计
│ │ ├── reports.py # CSV 报告导出
│ │ └── deps.py # FastAPI 依赖注入（当前用户、数据库会话）
│ ├── middleware/
│ │ ├── rate_limit.py # 基于内存的限流中间件
│ │ └── logging_middleware.py
│ ├── models/ # SQLAlchemy ORM 模型
│ │ ├── user.py # 用户模型
│ │ ├── query.py # 查询词模型
│ │ ├── citation_record.py
│ │ ├── query_task.py # 查询任务执行记录
│ │ └── subscription.py # 订阅套餐模型
│ ├── schemas/ # Pydantic v2 数据校验模型
│ │ ├── auth.py
│ │ ├── citation.py
│ │ └── query.py
│ ├── services/ # 业务逻辑层
│ │ ├── auth.py # 认证服务（密码哈希、JWT）
│ │ ├── query.py # 查询词业务逻辑
│ │ └── citation.py # 引用数据与报告服务
│ ├── workers/ # 后台任务与引擎
│ │ ├── scheduler.py # APScheduler 定时调度器
│ │ ├── citation_engine.py
│ │ └── platforms/ # AI 平台适配器
│ │ ├── base.py
│ │ ├── wenxin.py # 文心一言
│ │ ├── kimi.py # Kimi
│ │ ├── tongyi.py # 通义千问
│ │ ├── doubao.py # 豆包
│ │ ├── qingyan.py # 清言
│ │ ├── tiangong.py # 天工
│ │ ├── xinghuo.py # 讯飞星火
│ │ └── search_engine.py
│ ├── config.py # Pydantic Settings 配置管理
│ ├── database.py # 异步数据库引擎与 Session
│ └── main.py # FastAPI 应用入口与生命周期管理
├── requirements.txt
├── Dockerfile
└── README.md
限流策略
| 接口 |
限制 |
时间窗口 |
| 登录/注册/忘记密码 |
5 次 |
60 秒 |
| 立即查询（run-now） |
10 次 |
3600 秒 |
| 全局接口 |
100 次 |
60 秒 |
测试说明
测试文件位于项目根目录的 tests/ 文件夹中。
# 安装测试依赖（已包含在 requirements.txt 中）
pip install pytest pytest-asyncio aiosqlite
# 运行所有测试
cd .. # 切换到项目根目录
pytest
# 运行指定测试文件
pytest tests/test_auth.py
pytest tests/test_queries.py
pytest tests/test_citations.py
pytest tests/test_citation_engine.py
pytest tests/test_scheduler.py
pytest tests/test_business_flow.py
# 显示详细输出
pytest -v
# 显示测试覆盖率（需安装 pytest-cov）
pytest --cov=backend/app --cov-report=html
主要依赖版本
| 包名 |
版本要求 |
| fastapi |
>=0.109.0 |
| uvicorn |
[standard] |
| sqlalchemy |
>=2.0 |
| asyncpg |
- |
| alembic |
- |
| pydantic |
>=2.0 |
| pydantic-settings |
- |
| python-jose |
[cryptography] |
| passlib |
[bcrypt] |
| bcrypt |
<4.0 |
| redis |
- |
| apscheduler |
>=3.10 |
| playwright |
>=1.40 |
| httpx |
- |
| fpdf2 |
>=2.7 |
| pytest |
>=8.0 |
| pytest-asyncio |
>=0.23.0 |
c349e40fde