# 爬虫任务脚本文档

## 概述

本文档整理了当前系统中的所有爬虫任务脚本，包括懂球帝足球数据爬虫和六合彩信息爬虫两大类。每个脚本都有详细的功能说明和执行方法。

## 一、懂球帝足球数据爬虫系统

### 1.1 核心项目结构

系统有两个主要项目目录：

1. **dongqiudi-crawler** - 基础爬虫系统
2. **dongqiudi-crawler-extended** - 扩展版（支持多联赛）

### 1.2 主要脚本文件

#### 1.2.1 日常定时任务脚本

| 脚本文件 | 功能 | 执行方式 | 说明 |
|---------|------|----------|------|
| `cron_dongqiudi_daily.py` | 每日多联赛数据采集 | `python3 cron_dongqiudi_daily.py` | 每天凌晨2点运行，采集7个联赛数据 |
| `install_dongqiudi_cron.sh` | 安装定时任务 | `bash install_dongqiudi_cron.sh` | 将每日采集任务添加到crontab |
| `collect_multi_league_data.py` | 多联赛数据采集（首次运行） | `python3 collect_multi_league_data.py` | 采集7个联赛的首秀数据 |

#### 1.2.2 实时数据更新脚本

| 脚本文件 | 功能 | 执行方式 | 说明 |
|---------|------|----------|------|
| `live_match_updater_v2.py` | 实时比赛数据更新器 | `python3 live_match_updater_v2.py` | 监听比赛开始时间，获取实时数据 |
| `live_match_updater_backup.py` | 实时更新器备份 | `python3 live_match_updater_backup.py` | 备用版本 |
| `deploy_live_updater.py` | 部署实时更新器 | `python3 deploy_live_updater.py start` | 启动实时更新服务 |

#### 1.2.3 高级爬虫脚本

| 脚本文件 | 功能 | 执行方式 | 说明 |
|---------|------|----------|------|
| `hybrid_crawler.py` | 混合爬虫（API+Playwright） | 导入使用 | 集成API请求和浏览器自动化 |
| `playwright_crawler.py` | Playwright浏览器爬虫 | 导入使用 | 使用Playwright进行网页抓取 |
| `dongqiudi_advanced_crawler.py` | 高级懂球帝爬虫 | 导入使用 | 支持指纹伪装和反爬虫规避 |

#### 1.2.4 工具和测试脚本

| 脚本文件 | 功能 | 执行方式 | 说明 |
|---------|------|----------|------|
| `check_league_status.py` | 检查联赛状态 | `python3 check_league_status.py` | 测试赛季ID有效性 |
| `scan_leagues.py` | 扫描联赛 | `python3 scan_leagues.py` | 扫描1-100的赛季ID |
| `get_sports_matches_simple.py` | 简单比赛获取 | `python3 get_sports_matches_simple.py` | 获取今日明日比赛 |
| `get_today_tomorrow_matches.py` | 今日明日比赛 | `python3 get_today_tomorrow_matches.py` | 获取比赛数据 |
| `test_api_direct.py` | API直接测试 | `python3 test_api_direct.py` | 测试API连通性 |
| `debug_api.py` | API调试 | `python3 debug_api.py` | 调试API问题 |
| `test_full_pipeline.py` | 完整管道测试 | `python3 test_full_pipeline.py` | 测试整个数据管道 |
| `test_season.py` | 赛季测试 | `python3 test_season.py` | 测试特定赛季 |
| `fingerprint_test.py` | 指纹测试 | `python3 fingerprint_test.py` | 测试指纹伪装效果 |
| `test_crawl.py` | 爬虫测试 | `python3 test_crawl.py` | 通用爬虫测试 |

#### 1.2.5 分布式系统脚本

| 脚本文件 | 功能 | 执行方式 | 说明 |
|---------|------|----------|------|
| `task_scheduler.py` | 分布式任务调度器 | `python3 task_scheduler.py` | 负责任务创建、调度和监控 |
| `celery_worker.py` | Celery工作节点 | `python3 celery_worker.py` | 启动Celery工作进程 |
| `data_pipeline.py` | 数据管道 | `python3 data_pipeline.py` | 数据处理管道 |

### 1.3 项目目录详细说明

#### 1.3.1 dongqiudi-crawler项目
```
projects/dongqiudi-crawler/
├── src/
│   ├── crawler/           # 爬虫核心模块
│   │   ├── api_client.py      # API客户端
│   │   ├── data_parser.py     # 数据解析器
│   │   └── playwright_client.py # Playwright客户端
│   ├── fingerprint/       # 指纹管理模块
│   │   ├── manager.py        # 指纹管理器
│   │   └── validator.py      # 指纹验证器
│   ├── scheduler/         # 调度模块
│   │   ├── task_scheduler.py # 任务调度器
│   │   ├── queue_manager.py  # 队列管理器
│   │   └── rate_limiter.py   # 频率限制器
│   ├── error_handler/     # 错误处理模块
│   │   ├── detector.py       # 错误检测器
│   │   ├── recovery.py       # 恢复机制
│   │   └── monitor.py        # 监控器
│   └── storage/           # 存储模块
│       ├── database.py       # 数据库操作
│       ├── cache.py          # 缓存管理
│       └── models.py         # 数据模型
└── scripts/               # 脚本目录
```

#### 1.3.2 dongqiudi-crawler-extended项目
扩展版包含相同的模块结构，但增加了多联赛支持：
- `scripts/multi_league_crawler.py` - 多联赛爬虫主脚本

### 1.4 执行示例

#### 1.4.1 运行每日采集
```bash
# 直接运行
python3 cron_dongqiudi_daily.py

# 通过cron定时运行（已配置）
0 2 * * * cd /root/.openclaw/workspace && python3 cron_dongqiudi_daily.py >> logs/daily_cron.log 2>&1
```

#### 1.4.2 运行实时更新器
```bash
# 启动服务
python3 deploy_live_updater.py start

# 停止服务
python3 deploy_live_updater.py stop

# 查看状态
python3 deploy_live_updater.py status
```

#### 1.4.3 测试爬虫功能
```bash
# 测试单个联赛
python3 check_league_status.py

# 测试多联赛
python3 collect_multi_league_data.py

# 测试实时数据
python3 live_match_updater_v2.py --test
```

## 二、六合彩信息爬虫系统

### 2.1 项目结构
```
lottery_crawler/
├── README.md              # 项目说明
├── requirements.txt       # Python依赖
├── config/               # 配置文件目录
├── src/                  # 源代码目录
│   ├── crawler.py           # 主爬虫类
│   ├── crawler_real_site.py # 真实站点爬虫
│   ├── crawler_forecast.py  # 预测数据爬虫
│   ├── crawler_playwright.py # Playwright爬虫
│   ├── crawler_playwright_proxy.py # 代理版Playwright爬虫
│   ├── crawler_playwright_stealth.py # 隐身版爬虫
│   ├── crawler_playwright_system.py # 系统爬虫
│   ├── crawler_real_system.py # 真实系统爬虫
│   ├── crawler_js.py        # JavaScript爬虫
│   └── utils.py             # 工具函数
├── data/                 # 数据输出目录
├── logs/                 # 日志目录
└── scripts/              # 脚本目录
    └── run_crawler.py       # 运行脚本
```

### 2.2 主要脚本文件

| 脚本文件 | 功能 | 执行方式 | 说明 |
|---------|------|----------|------|
| `src/crawler.py` | 主爬虫类 | 导入使用 | 基础爬虫功能 |
| `src/crawler_real_site.py` | 真实站点爬虫 | `python3 src/crawler_real_site.py` | 爬取真实网站数据 |
| `src/crawler_forecast.py` | 预测数据爬虫 | `python3 src/crawler_forecast.py` | 爬取预测信息 |
| `src/crawler_playwright.py` | Playwright爬虫 | `python3 src/crawler_playwright.py` | 使用Playwright |
| `scripts/run_crawler.py` | 运行脚本 | `python3 scripts/run_crawler.py` | 一键运行爬虫 |

### 2.3 定时任务脚本

| 脚本文件 | 功能 | 执行方式 | 说明 |
|---------|------|----------|------|
| `cron_check_draw.py` | 开奖检查 | `python3 cron_check_draw.py` | 定时检查开奖结果 |
| `cron_check_draw_backup.py` | 开奖检查备份 | `python3 cron_check_draw_backup.py` | 备用版本 |
| `morning_setup.sh` | 早晨设置脚本 | `bash morning_setup.sh` | 每日早晨运行设置 |

### 2.4 数据分析脚本

| 脚本文件 | 功能 | 执行方式 | 说明 |
|---------|------|----------|------|
| `analyze_081.py` | 数据分析 | `python3 analyze_081.py` | 分析081期数据 |
| `analyze_html.py` | HTML分析 | `python3 analyze_html.py` | 分析HTML页面 |
| `analyze_new_data.py` | 新数据分析 | `python3 analyze_new_data.py` | 分析最新数据 |
| `check_forecast.py` | 预测检查 | `python3 check_forecast.py` | 检查预测准确性 |
| `check_result.py` | 结果检查 | `python3 check_result.py` | 检查开奖结果 |

### 2.5 执行示例

#### 2.5.1 运行主爬虫
```bash
# 进入项目目录
cd /root/.openclaw/workspace/lottery_crawler

# 运行主爬虫
python3 src/crawler.py --url "https://rtrtr77.www72517c.com:8443/#dbgg"

# 或使用运行脚本
python3 scripts/run_crawler.py
```

#### 2.5.2 运行定时检查
```bash
# 检查开奖结果
python3 cron_check_draw.py

# 检查预测数据
python3 check_forecast.py
```

#### 2.5.3 数据分析
```bash
# 分析最新数据
python3 analyze_new_data.py

# 生成报告
python3 generate_report.py
```

## 三、其他相关脚本

### 3.1 通用工具脚本

| 脚本文件 | 功能 | 执行方式 | 说明 |
|---------|------|----------|------|
| `fetch_lottery.py` | 彩票数据获取 | `python3 fetch_lottery.py` | 通用彩票数据获取 |
| `crawl_match_types.py` | 比赛类型爬取 | `python3 crawl_match_types.py` | 爬取比赛类型数据 |

### 3.2 代理相关脚本

| 脚本文件 | 功能 | 执行方式 | 说明 |
|---------|------|----------|------|
| `proxy_tester.py` | 代理测试 | `python3 proxy_tester.py` | 测试代理可用性 |
| `proxy_tester_real.py` | 真实代理测试 | `python3 proxy_tester_real.py` | 真实环境代理测试 |

## 四、系统依赖和环境

### 4.1 Python依赖
```bash
# 基础依赖
pip install requests aiohttp playwright pymysql redis celery

# 懂球帝爬虫特定依赖
pip install fake-useragent browser-fingerprint

# 彩票爬虫特定依赖
pip install beautifulsoup4 lxml pandas
```

### 4.2 环境配置
1. **Redis服务器**：用于任务队列和缓存
2. **MySQL数据库**：用于数据存储
3. **Playwright浏览器**：用于浏览器自动化

### 4.3 配置文件
- 数据库配置：`database_config.py`
- Redis配置：`redis_config.py`
- Celery配置：`celery_config.py`

## 五、监控和日志

### 5.1 日志文件位置
- 懂球帝爬虫日志：`logs/dongqiudi_daily.log`
- 实时更新器日志：`live_updater.log`
- 彩票爬虫日志：`lottery_crawler/logs/`

### 5.2 监控指标
1. **采集成功率**：API请求成功率
2. **数据完整性**：采集到的数据字段完整性
3. **系统性能**：响应时间、资源使用率
4. **错误率**：各种错误的发生频率

## 六、故障排除

### 6.1 常见问题

#### 问题1：API请求失败
- **原因**：频率限制、IP封禁、API变更
- **解决**：调整请求间隔，更换User-Agent，检查API地址

#### 问题2：数据库连接失败
- **原因**：数据库服务未启动、配置错误
- **解决**：检查数据库服务状态，验证连接配置

#### 问题3：Playwright启动失败
- **原因**：浏览器未安装、权限问题
- **解决**：运行`playwright install`，检查权限

### 6.2 调试方法
```bash
# 启用详细日志
export LOG_LEVEL=DEBUG

# 测试单个功能
python3 test_api_direct.py

# 检查网络连接
curl -v "https://sport-data.dongqiudi.com/soccer/biz/data/standing?season_id=26322"
```

## 七、下一步优化建议

1. **容器化部署**：使用Docker容器化部署所有爬虫服务
2. **监控告警**：集成Prometheus和Grafana进行监控
3. **自动扩缩容**：根据负载自动调整爬虫实例数量
4. **数据质量监控**：建立数据质量检测和告警机制
5. **文档自动化**：自动生成API文档和执行文档

---

**文档生成时间**：2026-03-31  
**文档状态**：初稿  
**更新频率**：脚本有变更时及时更新  

## 附录：脚本快速参考表

| 类别 | 主要脚本 | 执行命令 | 用途 |
|------|----------|----------|------|
| 日常采集 | `cron_dongqiudi_daily.py` | `python3 cron_dongqiudi_daily.py` | 每日多联赛数据 |
| 实时更新 | `deploy_live_updater.py` | `python3 deploy_live_updater.py start` | 启动实时更新服务 |
| 彩票爬虫 | `src/crawler_real_site.py` | `python3 src/crawler_real_site.py` | 爬取彩票网站 |
| 数据分析 | `analyze_new_data.py` | `python3 analyze_new_data.py` | 分析最新数据 |
| 系统测试 | `test_full_pipeline.py` | `python3 test_full_pipeline.py` | 测试完整系统 |