rank_backend/docs/README.md

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

这是一个完整的抖音合集播放量数据抓取和分析系统，包含自动化抓取、定时任务、数据存储和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依赖

pip install -r requirements.txt

安装MongoDB

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

Chrome浏览器

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

2. Chrome配置文件设置

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

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

3. ChromeDriver说明

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

如果遇到驱动版本不匹配问题，可以：

1. 删除 drivers/chromedriver.exe
2. 重新运行脚本，系统会自动下载合适版本的ChromeDriver

3. 运行系统

方式一：手动运行抓取脚本

python scripts/douyin_selenium_cdp_play_vv.py --auto --duration 60

方式二：启动定时任务（推荐）

python scripts/douyin_auto_scheduler.py

方式三：启动API服务器

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

🔧 配置说明

环境变量

# 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 中修改执行时间：

schedule.every().day.at("09:35").do(self.run_douyin_scraper)

📈 数据格式

MongoDB文档结构

{
  "_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"]
}

🛠️ 工具脚本

数据库查询

python scripts/query_mongodb_data.py

查看最新数据

python scripts/view_latest_data.py

检查MongoDB连接

python scripts/check_mongodb.py

⚠️ 注意事项

法律合规

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

技术限制

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

故障排除

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

📝 版本历史

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

🤝 贡献

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

📄 许可证

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