Update documentation and add requirements.txt

- Update README.md with ChromeDriver setup instructions - Add requirements.txt with project dependencies - Clean up unused documentation files 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-17 11:12:24 +08:00 · 2025-10-17 11:12:24 +08:00 · aacedf14fe
commit aacedf14fe
parent dbef5a98a8
2 changed files with 216 additions and 32 deletions
--- a/docs/README.md
+++ b/docs/README.md
@ -1,51 +1,227 @@
-# 抖音合集数据抓取工具
+# 抖音合集播放量数据抓取系统

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

-## 功能特点
+## 🎯 系统概述

- 使用Selenium处理动态加载的内容
- 多种数据提取策略（页面源码、DOM元素、网络请求）
- 反爬虫机制规避
- 错误处理和重试机制
- 数据保存为JSON格式
+本系统通过Selenium + Chrome DevTools Protocol技术，自动化抓取抖音收藏合集的真实播放量数据，并提供以下功能：

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

-```bash
-pip3 install -r requirements.txt
+## 📁 项目结构
+
+```
+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. 确保已安装Chrome浏览器
-2. 运行脚本：
+### 1. 环境准备

+#### 安装Python依赖
 ```bash
-python3 douyin_scraper.py
+pip install -r requirements.txt
 ```

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

-1. **法律合规**: 请确保您的使用符合抖音的服务条款和相关法律法规
-2. **频率控制**: 避免过于频繁的请求，以免被反爬虫机制阻止
-3. **数据使用**: 抓取的数据仅供学习和研究使用，请勿用于商业用途
-4. **Chrome驱动**: 脚本会自动管理Chrome驱动，但请确保Chrome浏览器已安装
+#### Chrome浏览器
+- 确保已安装Chrome浏览器
+- 系统会自动检测并使用合适的ChromeDriver

-## 可能遇到的问题
+### 2. Chrome配置文件设置

-1. **ChromeDriver问题**: 如果遇到驱动问题，请确保Chrome浏览器版本与ChromeDriver版本匹配
-2. **反爬虫限制**: 抖音有较强的反爬虫机制，可能需要调整请求频率或使用代理
-3. **页面结构变化**: 抖音页面结构可能会更新，导致数据提取失败，需要相应调整代码
+**重要**: Chrome配置文件包含登录信息和缓存，需要手动设置。详细步骤请参考：[CHROME_PROFILE_SETUP.md](../CHROME_PROFILE_SETUP.md)

-## 输出数据格式
+```bash
+# 首次运行需要手动登录
+python scripts/douyin_selenium_cdp_play_vv.py
+```

-抓取的数据将保存为 `douyin_collection_data.json` 文件，包含：
- 合集标题
- 播放数据
- 视频列表信息
- 统计数据
+### 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来改进这个项目。
+
+## 📄 许可证
+
+本项目仅供学习和研究使用。使用者需要遵守相关法律法规和平台服务条款，作者不承担任何法律责任。
--- a/requirements.txt
+++ b/requirements.txt
@ -0,0 +1,8 @@
+selenium>=4.15.0
+schedule>=1.2.0
+pymongo>=4.5.0
+flask>=2.3.0
+flask-cors>=4.0.0
+chromedriver-autoinstaller>=0.6.0
+webdriver-manager>=4.0.0
+psutil>=5.9.0