AutoScraperX

AutoScraperX

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

---

🧠 项目结构简介

├── config/                # 配置文件
│   ├── __init__.py        # 配置初始化
│   ├── recommend.py            # 环境配置定义
│   └── spiders_config.yaml# 爬虫平台配置
├── core/                  # 核心框架模块
│   ├── recommend/              # 基础组件（异步客户端等）
│   ├── 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，保证一致性
- ✅ 完善的配置管理（验证、健康检查、文档生成、命令行工具）
- ✅ 异步高并发垂直 Spider 视频查询 API

### 垂直 Spider API

完整的接口参数、筛选规则、去重分页、响应、错误码、日志和部署说明见
[`docs/chui_zhi_video_api.md`](docs/chui_zhi_video_api.md)。

API 默认只监听 `127.0.0.1:8888`。跨服务器访问时应使用 Nginx 反向代理，
并通过固定出口 IP 白名单和限流保护公网接口。

```bash
sh run_api.sh prod

• POST /api/v1/crawler/videos/query
• GET /health 和 GET /ready 仅用于本机健康检查，Nginx 示例默认禁止公网访问
• 业务接口不校验 Token，公网部署必须在 Nginx 层配置访问控制
• start_time、end_time 推荐传13位毫秒时间戳，API 会统一转换为东八区数据库查询时间
• 未传时间时默认按 create_time 查询最近3天；传入 keywords 时按 video_title 模糊匹配
• 响应通过 has_more 和 next_cursor 表示是否存在下一页；调用方下一页原样回传 cursor
• 每次API调用都会通过有界队列批量向阿里云SLS上报URL、请求参数、SQL结果长度、查询耗时、请求总耗时、成功状态、失败阶段、异常类型、HTTP状态码、request_id和错误消息；异常时 message 包含脱敏后的原始堆栈；本地日志仅记录 URL、请求参数、状态码，失败时额外记录错误原因
• API访问日志默认写入独立的 crawler-log-prod / crawler-api-access，不再与爬虫日志 crawler-fetch 混合
• 可通过 API_HOST、API_PORT、API_MAX_CONCURRENT_REQUESTS、DB_POOL_SIZE、API_QUERY_TIMEOUT、API_QUEUE_TIMEOUT、API_LOG_QUEUE_SIZE、API_MAX_LIMIT 调整运行参数
• API 使用 FastAPI/Uvicorn；稳定启动入口为 api/app.py，应用生命周期和请求上下文在 api/fastapi_app.py
• api/base.py 统一封装路由注册、执行、响应、异常和数据库查询保护，api/reporting.py 统一访问日志；垂直视频的入参模型、SQL、查询和分页全部集中在 api/chui_zhi/videos.py 的 VideoQueryApi 子类中
• 本机可通过 /docs、/redoc 和 /openapi.json 查看接口文档；Nginx 默认不向公网暴露这些路径

筛选条件使用 field/operator/value 结构；没有筛选条件时传空数组或省略 filters：

{
  "filters": [
    {"field": "like_cnt", "operator": ">", "value": 3},
    {"field": "play_cnt", "operator": ">=", "value": 1000},
    {"field": "duration", "operator": "between", "value": [60, 300]},
    {"field": "publish_time", "operator": ">=", "value": 1785772800000}
  ]
}

支持 >、>=、=、<、<=、between、in 和 not_in。API 会校验字段、操作符和值， 并使用参数化 SQL。

第一页不传 cursor。如果 has_more=true，下一页将响应里的 next_cursor 原样传回：

{
  "cursor": {"id": 6815000}
}

API在筛选范围内按 out_video_id 分组并保留最大 id 的记录，然后只回表查询当前页完整字段； 空 out_video_id 按各自 id 保留。游标作用于分组后的最大 id，避免重复记录跨页再次出现。

公网部署时，API 仍保持 API_HOST=127.0.0.1 和 API_PORT=8888，由 Nginx 对外提供 HTTPS：

# 1. 配置 API 环境变量
API_HOST=127.0.0.1
API_PORT=8888
API_ALIYUN_LOG_PROJECT=crawler-log-prod
API_ALIYUN_LOGSTORE=crawler-api-access
API_ALIYUN_LOG_ENDPOINT=cn-hangzhou.log.aliyuncs.com

# 2. 使用现有部署脚本同时启动主爬虫和API
bash deploy.sh

# 3. 首次部署时安装 Nginx 配置（先替换域名、证书路径和可选 IP 白名单）
cp deploy/nginx/chui_zhi_api.conf.example /etc/nginx/conf.d/chui_zhi_api.conf
nginx -t
systemctl reload nginx

---

🧱 架构概览

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

---

⚙️ 配置管理

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

环境配置

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

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

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

爬虫配置

爬虫配置通过 config/spiders_config.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字段

配置健康检查

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

python -m core.utils.config_health_check

该工具会检查：

• 环境配置完整性
• 爬虫配置有效性
• 配置文件权限

配置文档生成

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

python -m core.utils.config_documentation

生成的文档包含：

• 环境配置详细说明
• 爬虫配置结构说明
• 当前配置状态信息

配置命令行工具

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

# 检查配置健康状态
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>

配置热更新

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

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

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

---

🛠 使用说明

1. 启动项目

python main.py

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

---

🧩 spiders_config.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
• 失败或超时不会阻塞其他任务

---

🧪 测试

运行测试：

# 运行所有测试
pytest

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

---

📦 部署

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

# 启动服务
python main.py

# 推荐：同时部署主爬虫和垂直视频API，并执行API就绪检查
bash deploy.sh

🧰 常用操作

配置管理操作

1. 查看所有平台配置：

   python scripts/config_cli.py list
   

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

2. 检查配置健康状态：

   python scripts/config_cli.py check
   

   1. 生成配置文档： bash python scripts/config_cli.py docs

3. 查看配置统计信息：

   python scripts/config_cli.py stats
   

   配置更新操作

   当需要更新配置时：

   1. 编辑 config/spiders_config.yaml 文件

   2. 通过命令行工具重新加载配置：

      # 在代码中调用重新加载
      from core.utils.spider_config import SpiderConfig
      SpiderConfig.reload_config()
      

日常维护操作

1. 检查系统健康状态：

   python -m core.utils.config_health_check
   

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

项目相关记录

1. 写入安全标题表：

   https://w42nne6hzg.feishu.cn/sheets/U5dXsSlPOhiNNCtEfgqcm1iYnpf?sheet=K0gA9Y