# AutoScraperX

一个基于 YAML 配置驱动的通用分布式爬虫系统，支持多 Topic 并发消费，按平台灵活执行爬虫逻辑，最终推送至 ETL 消费系统。

---

## 🧠 项目结构简介

```bash
├── config/                # 配置文件
│   ├── __init__.py        # 配置初始化
│   ├── base.py            # 环境配置定义
│   └── spiders_config.yaml# 爬虫平台配置
├── core/                  # 核心框架模块
│   ├── base/              # 基础组件（异步客户端等）
│   ├── models/            # 数据模型
│   ├── utils/             # 工具类
│   │   ├── config_manager.py      # 统一配置管理器
│   │   ├── config_health_check.py # 配置健康检查
│   │   ├── config_documentation.py# 配置文档生成
│   │   └── spider_config.py       # 爬虫配置加载
│   └── __init__.py
├── spiders/               # 业务爬虫实现
│   ├── basespider.py      # 爬虫基类
│   ├── recommendspider.py # 推荐模式爬虫基类
│   ├── authorspider.py    # 账号模式爬虫基类
│   └── spider_registry.py # 爬虫注册中心
├── services/              # 业务服务
│   ├── pipeline.py        # 数据处理管道
│   └── async_mysql_service.py # 数据库服务
├── scheduler/             # 调度器
│   ├── process_manager.py # 进程管理
│   └── async_consumer.py  # 异步消费者
├── tests/                 # 测试用例
└── scripts/               # 运维脚本
    └── config_cli.py      # 配置管理命令行工具

## 🚀 功能特性

- ✅ 多 Topic 单进程并发监听消费（使用线程）
- ✅ 根据消息动态获取 platform/mode，并注入 user_list、rule_dict
- ✅ YAML 驱动爬虫逻辑，无需重复开发代码
- ✅ 请求支持自动重试、动态分页、字段抽取
- ✅ 视频封装为标准 `VideoItem`，统一推送到 MQ
- ✅ 任务执行成功后再确认 ACK，保证一致性
- ✅ 完善的配置管理（验证、健康检查、文档生成、命令行工具）

---

## 🧱 架构概览

- **main.py**：监听多个 Topic，消费 MQ 消息，解析出平台并调度爬虫
- **爬虫类**：核心爬虫逻辑，读取配置发送请求，抽取字段，封装数据项
- **Pipeline**：负责数据校验、去重和推送至 ETL MQ
- **MQ 系统**：阿里云 MQ，支持按平台配置多个 Topic，消费完成再手动 ACK
- **配置系统**：
  - 环境配置：通过 `.env` 文件和 `config/base.py` 管理
  - 爬虫配置：通过 `config/spiders_config.yaml` 管理

---

## ⚙️ 配置管理

AutoScraperX 使用分层配置管理系统，提供完整的配置管理功能：

### 环境配置

环境配置通过 `.env` 文件管理，包含数据库、消息队列、日志等基础设施配置。

1. 复制 `.env.example` 为 `.env`
2. 根据实际环境填写配置项

```bash
cp .env.example .env
# 编辑 .env 文件
```

### 爬虫配置

爬虫配置通过 `config/spiders_config.yaml` 文件管理，采用 YAML 格式，支持默认配置和平台特定配置。

```yaml
# 默认配置
default:
  base_url: http://api.example.com
  request_timeout: 30
  max_retries: 3

# 平台特定配置
platform_name:
  platform: platform_name
  mode: recommend
  path: /api/path
  method: post
  # 更多配置...
```

### 配置验证

系统使用 Pydantic 模型对配置进行验证，确保配置格式正确：

- HTTP方法必须是有效的（GET, POST, PUT, DELETE, PATCH）
- 循环次数必须是正数
- 循环间隔配置必须包含min和max，且min不能大于max
- 响应解析配置必须包含data_path字段

### 配置健康检查

运行以下命令检查配置健康状态：

```bash
python -m core.utils.config_health_check
```

该工具会检查：
- 环境配置完整性
- 爬虫配置有效性
- 配置文件权限

### 配置文档生成

运行以下命令生成配置文档：

```bash
python -m core.utils.config_documentation
```

生成的文档包含：
- 环境配置详细说明
- 爬虫配置结构说明
- 当前配置状态信息

### 配置命令行工具

使用命令行工具管理配置：

```bash
# 检查配置健康状态
python scripts/config_cli.py check

# 生成配置文档
python scripts/config_cli.py docs

# 列出所有平台
python scripts/config_cli.py list

# 显示配置统计信息
python scripts/config_cli.py stats

# 显示特定平台配置详情
python scripts/config_cli.py show <platform_name>
```

### 配置热更新

当修改了配置文件后，可以通过以下方式重新加载配置而无需重启服务：

```bash
# 通过API重新加载配置（如果启用了配置API服务）
curl -X POST http://127.0.0.1:8080/config/reload

# 或者在代码中调用
from core.utils.spider_config import SpiderConfig
SpiderConfig.reload_config()
```

---

## 🛠 使用说明

### 1. 启动项目

```bash
python main.py
```

> 程序将自动监听所有 Topic，消费消息后创建对应的爬虫任务并执行。

---

## 🧩 spiders_config.yaml 示例配置

```yaml
default:
  base_url: http://8.217.192.46:8889
  request_timeout: 30
  headers:
    {"Content-Type": "application/json"}

benshanzhufu:
  platform: benshanzhufu
  mode: recommend
  path: /crawler/ben_shan_zhu_fu/recommend
  method: post
  request_body:
    cursor: "{{next_cursor}}"
  loop_times: 50
  loop_interval:
    min: 30
    max: 60
  feishu_sheetid: "aTSJH4"
  response_parse:
    data: "$.data"
    next_cursor: "$.data.next_cursor"
    data_path: "$.data.data"
    fields:
      video_id: "$.nid"
      video_title: "$.title"
      play_cnt: 0
      publish_time_stamp: "$.update_time"
      out_user_id: "$.nid"
      cover_url: "$.video_cover"
      like_cnt: 0
      video_url: "$.video_url"
      out_video_id: "$.nid"
```

---

## 🧵 线程调度与消费机制

- 每个 topic 启一个线程进行 MQ 消费
- 每条消息创建一个爬虫实例，执行 `.run()`，完成后再 ACK
- 失败或超时不会阻塞其他任务

---

## 🧪 测试

运行测试：

```bash
# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_config.py
```

---

## 📦 部署

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

# 启动服务
python main.py

# 或使用部署脚本
sh deploy.sh
```

## 🧰 常用操作

### 配置管理操作

1. **查看所有平台配置**：
   ```bash
   python scripts/config_cli.py list
   ```

2. **查看特定平台配置详情**：
   ```bash
   python scripts/config_cli.py show <platform_name>
   ```

3. **检查配置健康状态**：
   ```bash
   python scripts/config_cli.py check
   ```

4. **生成配置文档**：
   ```bash
   python scripts/config_cli.py docs
   ```

5. **查看配置统计信息**：
   ```bash
   python scripts/config_cli.py stats
   ```

### 配置更新操作

当需要更新配置时：

1. 编辑 `config/spiders_config.yaml` 文件
2. 通过命令行工具重新加载配置：
   ```bash
   # 在代码中调用重新加载
   from core.utils.spider_config import SpiderConfig
   SpiderConfig.reload_config()
   ```

### 日常维护操作

1. **检查系统健康状态**：
   ```bash
   python -m core.utils.config_health_check
   ```

2. **生成最新的配置文档**：
   ```bash
   python -m core.utils.config_documentation
   ```