tangweijie
00db791f91
- FastAPI 应用框架 - SQLAlchemy 异步数据库 - 事件采集和分析 API - Alembic 数据库迁移 - Docker 部署配置 - 完整的项目文档
155 lines
3.3 KiB
Markdown
155 lines
3.3 KiB
Markdown
# Collector Backend
|
|
|
|
数据采集后端服务 - Python FastAPI 实现
|
|
|
|
## 项目介绍
|
|
|
|
Collector Backend 是 IDE 数据采集系统的后端服务，负责接收、存储和分析来自各 IDE 插件的数据。
|
|
|
|
## 技术栈
|
|
|
|
- **框架**: FastAPI
|
|
- **数据库**: PostgreSQL + SQLAlchemy (async)
|
|
- **缓存**: Redis
|
|
- **数据库迁移**: Alembic
|
|
- **包管理**: Poetry
|
|
|
|
## 快速开始
|
|
|
|
### 环境要求
|
|
|
|
- Python 3.11+
|
|
- PostgreSQL 14+
|
|
- Redis 7+
|
|
- Poetry
|
|
|
|
### 安装
|
|
|
|
```bash
|
|
# 安装依赖
|
|
poetry install
|
|
|
|
# 复制环境配置
|
|
cp .env.example .env
|
|
|
|
# 编辑 .env 配置数据库等信息
|
|
```
|
|
|
|
### 数据库迁移
|
|
|
|
```bash
|
|
# 生成迁移
|
|
poetry run alembic revision --autogenerate -m "Initial migration"
|
|
|
|
# 执行迁移
|
|
poetry run alembic upgrade head
|
|
```
|
|
|
|
### 运行
|
|
|
|
```bash
|
|
# 开发模式
|
|
poetry run uvicorn src.main:app --reload --port 8000
|
|
|
|
# 生产模式
|
|
poetry run uvicorn src.main:app --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
### Docker 运行
|
|
|
|
```bash
|
|
# 启动所有服务
|
|
docker-compose up -d
|
|
|
|
# 查看日志
|
|
docker-compose logs -f app
|
|
```
|
|
|
|
## API 文档
|
|
|
|
启动服务后访问：
|
|
- Swagger UI: http://localhost:8000/docs
|
|
- ReDoc: http://localhost:8000/redoc
|
|
|
|
## API 端点
|
|
|
|
### 健康检查
|
|
- `GET /api/v1/health` - 健康检查
|
|
- `GET /api/v1/health/db` - 数据库健康检查
|
|
|
|
### 事件管理
|
|
- `POST /api/v1/events` - 创建单个事件
|
|
- `POST /api/v1/events/batch` - 批量创建事件
|
|
- `GET /api/v1/events` - 查询事件列表
|
|
- `GET /api/v1/events/{event_id}` - 获取单个事件
|
|
|
|
### 数据分析
|
|
- `GET /api/v1/analytics/overview` - 概览统计
|
|
- `GET /api/v1/analytics/acceptance-rate` - 采纳率统计
|
|
- `GET /api/v1/analytics/token-usage` - Token使用统计
|
|
- `GET /api/v1/analytics/user-activity` - 用户活动统计
|
|
|
|
### 配置管理
|
|
- `GET /api/v1/config` - 获取客户端配置
|
|
|
|
## 项目结构
|
|
|
|
```
|
|
collector-backend/
|
|
├── src/
|
|
│ ├── api/
|
|
│ │ └── v1/
|
|
│ │ ├── events.py # 事件API
|
|
│ │ ├── analytics.py # 分析API
|
|
│ │ ├── config.py # 配置API
|
|
│ │ └── health.py # 健康检查
|
|
│ ├── config/
|
|
│ │ ├── settings.py # 配置管理
|
|
│ │ └── database.py # 数据库配置
|
|
│ ├── models/
|
|
│ │ ├── event.py # 事件模型
|
|
│ │ └── user.py # 用户模型
|
|
│ ├── schemas/
|
|
│ │ ├── event.py # 事件Schema
|
|
│ │ └── analytics.py # 分析Schema
|
|
│ ├── services/
|
|
│ │ ├── event_processor.py # 事件处理
|
|
│ │ └── analytics_engine.py # 分析引擎
|
|
│ └── main.py # 应用入口
|
|
├── migrations/ # 数据库迁移
|
|
├── tests/ # 测试
|
|
├── pyproject.toml # 项目配置
|
|
├── docker-compose.yml # Docker配置
|
|
└── README.md
|
|
```
|
|
|
|
## 开发
|
|
|
|
### 代码格式化
|
|
|
|
```bash
|
|
# 格式化代码
|
|
poetry run black src tests
|
|
poetry run isort src tests
|
|
|
|
# 代码检查
|
|
poetry run ruff check src tests
|
|
poetry run mypy src
|
|
```
|
|
|
|
### 运行测试
|
|
|
|
```bash
|
|
poetry run pytest
|
|
poetry run pytest --cov=src
|
|
```
|
|
|
|
## 相关仓库
|
|
|
|
- [ide-data-collector](../ide-data-collector) - IDE插件 Monorepo
|
|
- [collector-dashboard](../collector-dashboard) - 数据分析看板
|
|
|
|
## 许可证
|
|
|
|
MIT License
|