# 抖音合集播放量数据抓取系统

这是一个完整的抖音合集播放量数据抓取和分析系统，包含自动化抓取、定时任务、数据存储和API服务。

## 🎯 系统概述

本系统通过Selenium + Chrome DevTools Protocol技术，自动化抓取抖音收藏合集的真实播放量数据，并提供以下功能：

- **自动化数据抓取**: 每天定时自动抓取抖音收藏合集的播放量数据
- **持久化存储**: 数据自动保存到MongoDB数据库
- **RESTful API**: 为小程序提供数据接口服务
- **多维度分析**: 支持总播放量、增长排序、搜索等功能

## 📁 项目结构

```
rank_backend/
├── scripts/                    # 核心脚本目录
│   ├── douyin_selenium_cdp_play_vv.py     # 主抓取脚本
│   ├── douyin_auto_scheduler.py           # 定时任务调度器
│   ├── miniprogram_api_server.py          # 小程序API服务器
│   ├── query_mongodb_data.py              # 数据库查询工具
│   ├── view_latest_data.py                # 最新数据查看工具
│   ├── check_mongodb.py                   # MongoDB连接检查
│   └── mongodb_quick_view.py              # 数据库快速查看
├── docs/                       # 文档目录
│   ├── README.md                          # 项目说明文档
│   └── API接口文档.md                     # API接口文档
├── config/                    # 配置文件目录
├── drivers/                   # Chrome驱动目录
├── data/                      # 数据文件目录
├── logs/                      # 日志文件目录
├── requirements.txt           # Python依赖包
├── CHROME_PROFILE_SETUP.md    # Chrome配置设置指南
└── .gitignore                 # Git忽略文件
```

## 🚀 快速开始

### 1. 环境准备

#### 安装Python依赖
```bash
pip install -r requirements.txt
```

#### 安装MongoDB
- 下载并安装MongoDB Community Server
- 启动MongoDB服务（默认端口27017）

#### Chrome浏览器
- 确保已安装Chrome浏览器
- 系统会自动检测并使用合适的ChromeDriver

### 2. Chrome配置文件设置

**重要**: Chrome配置文件包含登录信息和缓存，需要手动设置。详细步骤请参考：[CHROME_PROFILE_SETUP.md](../CHROME_PROFILE_SETUP.md)

```bash
# 首次运行需要手动登录
python scripts/douyin_selenium_cdp_play_vv.py
```

### 3. ChromeDriver说明

**ChromeDriver已包含在仓库中** (`drivers/chromedriver.exe`)，无需额外下载。系统会自动检测并使用该驱动。

如果遇到驱动版本不匹配问题，可以：
1. 删除 `drivers/chromedriver.exe`
2. 重新运行脚本，系统会自动下载合适版本的ChromeDriver

### 3. 运行系统

#### 方式一：手动运行抓取脚本
```bash
python scripts/douyin_selenium_cdp_play_vv.py --auto --duration 60
```

#### 方式二：启动定时任务（推荐）
```bash
python scripts/douyin_auto_scheduler.py
```

#### 方式三：启动API服务器
```bash
python scripts/miniprogram_api_server.py
```

## ⚙️ 核心功能

### 1. 数据抓取模块
- **技术栈**: Selenium + Chrome DevTools Protocol
- **数据源**: 抖音收藏合集页面
- **提取字段**:
  - 合集名称 (mix_name)
  - 真实播放量 (play_vv)
  - 合集链接 (video_url)
  - 合集ID (mix_id)
  - 视频ID列表 (aweme_ids)
  - 封面图片 (cover_image_url)

### 2. 定时任务模块
- **执行时间**: 每天上午9:35自动执行
- **日志记录**: 完整的执行日志
- **错误处理**: 自动重试和异常处理

### 3. API服务模块
- **端口**: 5001
- **跨域支持**: 支持小程序调用
- **接口功能**:
  - 视频列表查询（分页、排序）
  - 热门榜单
  - 搜索功能
  - 视频详情
  - 统计分析

## 📊 API接口

### 基础接口

| 接口 | 方法 | 描述 | 参数 |
|------|------|------|------|
| `/api/videos` | GET | 获取视频列表 | `page`, `limit`, `sort` |
| `/api/top` | GET | 热门榜单 | `limit` |
| `/api/search` | GET | 搜索视频 | `q`, `page`, `limit` |
| `/api/detail` | GET | 视频详情 | `id` |
| `/api/stats` | GET | 统计信息 | - |
| `/api/health` | GET | 健康检查 | - |

### 排序方式
- `playcount`: 按总播放量排序（默认）
- `growth`: 按增长量排序
- `time`: 按时间排序

### 增长排序参数
```
/api/videos?sort=growth&start_date=2025-10-16&end_date=2025-10-17
```

## 🔧 配置说明

### 环境变量
```bash
# MongoDB配置
MONGO_HOST=localhost
MONGO_PORT=27017
MONGO_DB=douyin_data
MONGO_COLLECTION=play_vv_records

# ChromeDriver配置
OVERRIDE_CHROMEDRIVER=/path/to/chromedriver

# 自动模式
AUTO_CONTINUE=1
```

### 定时任务配置
在 `scripts/douyin_auto_scheduler.py` 中修改执行时间：
```python
schedule.every().day.at("09:35").do(self.run_douyin_scraper)
```

## 📈 数据格式

### MongoDB文档结构
```json
{
  "_id": ObjectId,
  "batch_time": "2025-10-17T09:35:10",
  "mix_name": "合集名称",
  "video_url": "https://www.douyin.com/collection/xxx",
  "playcount": "1.2亿",
  "play_vv": 120000000,
  "request_id": "请求ID",
  "rank": 1,
  "aweme_ids": ["视频ID1", "视频ID2"],
  "cover_image_url": "封面图片URL",
  "cover_backup_urls": ["备用图片URL"]
}
```

## 🛠️ 工具脚本

### 数据库查询
```bash
python scripts/query_mongodb_data.py
```

### 查看最新数据
```bash
python scripts/view_latest_data.py
```

### 检查MongoDB连接
```bash
python scripts/check_mongodb.py
```

## ⚠️ 注意事项

### 法律合规
- 请确保使用符合抖音服务条款和相关法律法规
- 数据仅供学习和研究使用，请勿用于商业用途
- 避免过于频繁的请求，以免触发反爬虫机制

### 技术限制
- Chrome配置文件需要手动设置登录状态
- 抖音页面结构变化可能导致抓取失败
- 需要稳定的网络环境

### 故障排除
1. **ChromeDriver问题**: 确保Chrome浏览器版本与ChromeDriver匹配
2. **登录状态丢失**: 重新运行手动登录流程
3. **MongoDB连接失败**: 检查MongoDB服务是否启动

## 📝 版本历史

- **v2.0**: 新增小程序API服务、增长排序功能
- **v1.0**: 基础抓取功能和定时任务

## 🤝 贡献

欢迎提交Issue和Pull Request来改进这个项目。

## 📄 许可证

本项目仅供学习和研究使用。使用者需要遵守相关法律法规和平台服务条款，作者不承担任何法律责任。