pyspider 爬虫系统入门指南:架构、安装与第一个 Python 爬虫脚本

原创2026-09-20 16:14:361,907 阅读
文章标签:网页爬虫后端任务调度分布式训练

pyspider 爬虫系统入门指南:架构、安装与第一个 Python 爬虫脚本

pyspider 是一个用 Python 编写的强大爬虫(Web Crawler)系统,本指南以其项目首页(docs/index.md)为核心,结合仓库源码与官方文档,系统讲解其架构设计、核心特性、安装启动方式,并通过完整的示例代码带你写出第一个可运行的爬虫脚本。读完本文,你将掌握 pyspider 的组件划分、任务调度机制、BaseHandler 脚本编写范式以及 WebUI 的调试流程,能够独立搭建并运行一个属于自己的抓取项目。

项目定位:不只是爬虫库,而是一套完整系统

与 Scrapy 等纯框架不同,pyspider 的定位是完整的爬虫系统(A Powerful Spider(Web Crawler) System in Python),它开箱即用地提供了调度、抓取、解析、结果存储、监控调试的整套闭环。根据仓库 docs/Architecture.md 的说明,它最初源于作者做垂直搜索引擎时的实际需求:需要同时维护 100~200 个网站、随时应对网站模板变更、并在内容更新后 5 分钟内完成采集——这些需求催生了"带强大监控与脚本调试工具的分布式爬虫系统"这一设计目标。

pyspider 的系统概览如下图所示(来自 docs/imgs/pyspider-arch.png):

pyspider 核心架构图:scheduler、fetcher、processor 通过消息队列连接,WebUI 负责监控与交互

架构的核心思想是:各组件通过消息队列解耦。Scheduler(调度器)、Fetcher(抓取器)、Processor(处理器)、Result Worker(结果处理)各自独立运行,并且都可以替换或水平扩展——当处理器成为瓶颈时,可以启动多个 Processor 实例充分利用多核 CPU,甚至部署到多台机器上,这正是 pyspider 分布式能力的来源。

核心特性一览

根据项目首页的定位,pyspider 的核心能力可以概括为以下几点:

  • 纯 Python 编写脚本:抓取逻辑、页面解析、数据处理全部用 Python 完成,学习成本低;
  • 强大的 WebUI:内置脚本编辑器、调试器、项目管理器、任务监控和结果查看器,全流程可视化;
  • 多数据库后端:支持 MySQL、CouchDB、MongoDB、Redis、SQLite、Elasticsearch,以及通过 SQLAlchemy 连接的 PostgreSQL;
  • 多消息队列后端:支持 RabbitMQ、Redis 与 Kombu(见 pyspider/message_queue/ 目录下的 kombu_queue.py、rabbitmq.py、redis_queue.py);
  • 任务控制能力:任务优先级、失败重试、定时周期任务、按 age 过期重爬等;
  • 分布式架构与 JS 渲染:支持分布式部署,并可通过 PhantomJS 抓取渲染后的 JavaScript 页面。

安装与启动

安装过程非常简单,项目首页给出的标准步骤是:

pip install pyspider

安装完成后直接运行命令:

pyspider

然后访问 http://localhost:5000/ 即可打开 WebUI 管理界面。pyspider 命令默认以 all 模式运行,即把所有组件以线程或子进程的方式在本地启动,适合开发调试;生产环境建议参考 docs/Deployment.md 进行拆分部署。

安全警告:WebUI 默认是公开访问的,而它具备执行任意命令的能力(脚本在 WebUI 中运行),可能危害你的系统。请务必在内部网络中使用,或通过 need-auth 配置为 WebUI 开启认证(配置方式见 docs/Command-Line.md 的 webui 小节,仓库也提供了 config_example.json 示例)。

在 Ubuntu 等 Linux 系统上,如果缺少编译依赖,可以先安装二进制包再安装 pyspider(详见 docs/Quickstart.md):

apt-get install python python-dev python-distribute python-pip \
libcurl4-openssl-dev libxml2-dev libxslt1-dev python-lxml \
libssl-dev zlib1g-dev

如果需要抓取 JavaScript 渲染的页面,还需安装 PhantomJS,并保证 phantomjs 可执行文件在 PATH 环境变量中,pyspider 才会启用 JS 渲染能力。

你的第一个爬虫脚本

项目首页给出了一个精炼的示例脚本,这也是 pyspider 脚本的标准范式:

from pyspider.libs.base_handler import *


class Handler(BaseHandler):
    crawl_config = {
    }

    @every(minutes=24 * 60)
    def on_start(self):
        self.crawl('http://scrapy.org/', callback=self.index_page)

    @config(age=10 * 24 * 60 * 60)
    def index_page(self, response):
        for each in response.doc('a[href^="http"]').items():
            self.crawl(each.attr.href, callback=self.detail_page)

    def detail_page(self, response):
        return {
            "url": response.url,
            "title": response.doc('title').text(),
        }

脚本结构逐行拆解

  • class Handler(BaseHandler):所有 pyspider 脚本都必须继承 BaseHandler,它由 pyspider/libs/base_handler.py 提供。基类通过元类 BaseHandlerMeta 自动收集标记为 cronjob 的方法,并计算它们触发间隔的最大公约数作为 _min_tick,供调度器合并发送触发任务。
  • def on_start(self):脚本的入口点。当你在 WebUI 上点击 run 按钮时被调度执行(对应 docs/Quickstart.md 中的说明)。
  • self.crawl(url, callback=...):pyspider 最核心的 API,用于把 URL 加入抓取任务队列。绝大多数抓取参数都通过它传入,完整参数说明见 docs/apis/self.crawl.md。
  • def index_page(self, response):接收一个 Response 对象(详见 docs/apis/Response.md)。response.doc 返回一个 pyquery 对象,提供类似 jQuery 的 DOM 选择与提取 API,这里是提取所有 http 开头的链接。
  • def detail_page(self, response):返回一个 dict 作为最终结果。默认情况下结果会被写入 resultdb;你也可以覆写 on_result(self, result) 方法自定义结果的处理方式。

装饰器的含义

示例中出现的两个装饰器是理解 pyspider 调度机制的关键:

  • @every(minutes=24*60):告诉调度器 on_start 方法应该每隔 24 小时触发一次。从源码 every 的实现(pyspider/libs/base_handler.py)可以看到,它把方法标记为 is_cronjob=True,并把间隔统一折算成秒存入 func.tick;也支持 @every(seconds=...) 写法,且 @every 直接作用于函数时会默认取 1 分钟。
  • @config(age=10*24*60*60):为使用该回调的所有 self.crawl 设置默认参数。源码实现(pyspider/libs/base_handler.py)会把 kwargs 存入函数的 _config 属性,在 _crawl 执行时合并进 crawl 参数。其优先级低于 self.crawl(url, age=...) 显式传参,高于类级 crawl_config。

age 参数与"重复抓取"陷阱

age=10*24*60*60 表示该回调产生的页面在 10 天内被视为未修改,调度器会丢弃 10 天内已抓取过的相同任务。pyspider 默认对同一个 URL 是永久去重的,这意味着即使你修改了脚本代码再点 run,已抓过的 URL 也不会重新抓取——这是新手最容易踩的坑。解决办法是使用 itag:把它设置成与页面更新相关的内容(如页面上的更新时间文本),或把脚本版本号写进 crawl_config 作为 itag,修改版本号后重新运行即可触发全量重抓,例如:

class Handler(BaseHandler):
    crawl_config = {
        'itag': 'v223'
    }

深入 self.crawl:抓取任务的完整控制

self.crawl(url, **kwargs) 是控制抓取行为的总入口(完整文档见 docs/apis/self.crawl.md)。从源码(pyspider/libs/base_handler.py)看,_crawl 内部会把参数拆分进三个子字典:

  • schedule:调度相关,包括 priority、retries、exetime、age、itag、force_update、auto_recrawl、cancel;
  • fetch:抓取相关,包括 method、headers、user_agent、data、connect_timeout、timeout、allow_redirects、cookies、proxy、etag、last_modified、save、js_run_at、js_script、js_viewport_width、js_viewport_height、load_images、fetch_type、use_gzip、validate_cert、max_redirects、robots_txt;
  • process:处理相关,包括 callback、process_time_limit。

下表汇总了最常用的核心参数及其默认值:

参数 作用 默认值
callback 指定解析响应的回调方法 __call__
age 任务有效期内视为未修改,过期才重抓 -1(永不重抓)
priority 调度优先级,值越大越先抓 0
exetime 任务执行时间(unix 时间戳) 0(立即执行)
retries 失败重试次数 3
itag 变化标记,与上次不同则重抓 None
auto_recrawl 开启后每隔 age 时间自动重抓 False
method HTTP 方法 GET
params 追加到 URL 的查询参数(字典) —
data 请求体;传字典时自动表单编码 —
files 多部分上传文件 {field: {filename: content}} —
connect_timeout 连接超时(秒) 20
timeout 抓取超时上限(秒) 120
allow_redirects 是否跟随 30x 重定向 True
validate_cert HTTPS 是否校验证书 True
proxy 代理地址 username:password@host:port(仅 HTTP 代理) —
etag / last_modified 是否使用 HTTP 缓存协商机制跳过未变更页面 True
fetch_type 设为 js 启用 JavaScript 渲染抓取 None
save 透传给回调的任意对象,回调中通过 response.save 读取 —
taskid 任务唯一 ID,默认是 URL 的 MD5 自动生成

几个值得展开的实战要点:

  • priority 实现 BFS 式抓取:把列表页设为低优先级、详情页设为高优先级,可以让详情页优先被抓取,同时减少任务队列中的任务数量(更多任务意味着更多内存占用)。
  • exetime 延时执行:self.crawl(url, exetime=time.time()+30*60) 可以让页面在 30 分钟后才被抓取。
  • auto_recrawl 周期重抓:age=5*60*60, auto_recrawl=True 表示每 5 小时重新抓取一次该页面。
  • taskid 自定义:默认 taskid 是 URL 的 MD5,如果同一个 URL 搭配不同的 POST 数据需要视为不同任务,可以覆写 get_taskid 方法(pyspider/libs/base_handler.py),例如:
import json
from pyspider.libs.utils import md5string

def get_taskid(self, task):
    return md5string(task['url'] + json.dumps(task['fetch'].get('data', '')))
  • cURL 命令直接抓取:self.crawl(curl_command) 支持把 Chrome DevTools > Network 面板右键 "Copy as cURL" 得到的命令直接作为第一个参数,pyspider 会解析并还原成等价的请求(解析逻辑在 pyspider/libs/url.py 的 curl_to_arguments)。
  • crawl_config 项目级默认参数:类的 crawl_config 字典可以为整个项目设置默认参数。例如为全项目统一 User-Agent:
class Handler(BaseHandler):
    crawl_config = {
        'headers': {
            'User-Agent': 'GoogleBot',
        }
    }

从源码 pyspider/libs/base_handler.py 可以看到,crawl_config 中的 schedule 参数在任务创建时合并,fetch/process 参数则在任务执行时合并——这意味着你可以在运行中修改抓取配置(比如 cookie)而无需重建任务,这是一个非常实用的机制。

用 WebUI 调试与运行项目

pyspider 的 WebUI 是它最具吸引力的部分,集脚本编辑器、调试器、项目管理、任务监控、结果查看与导出于一体。启动 pyspider 后访问 http://localhost:5000/ 即可看到项目列表,点击某个项目即可进入脚本编辑与调试页面,界面如下图所示(来自 docs/imgs/demo.png):

pyspider WebUI 调试界面:左侧为抓取的网页预览,右侧为脚本编辑器与运行控制按钮

推荐的调试流程是(详见 docs/Quickstart.md):

  1. 在 WebUI 中编写脚本,点击绿色的 run 按钮单步执行;
  2. 切换到 follows 面板,点击播放按钮继续推进,逐层验证每个回调的输出;
  3. 满意后保存脚本,回到 dashboard(项目列表页);
  4. 将项目 status 改为 DEBUG 或 RUNNING;
  5. 再次点击 run 按钮,项目即开始正式运行。

命令行与生产环境部署

pyspider 命令提供了完整的子命令体系,运行 pyspider --help 和 pyspider all --help 可以查看帮助。完整的参数说明见 docs/Command-Line.md,以下是生产部署最常用的几项:

  • 数据库与队列配置:通过全局选项 --taskdb、--projectdb、--resultdb、--message-queue 指定后端,支持 SQLite、MySQL、MongoDB、CouchDB、SQLAlchemy(PostgreSQL)、Redis、RabbitMQ、Kombu 等。也推荐用 JSON 配置文件统一管理(-c/--config),仓库的 config_example.json 就是一个带认证配置的完整示例。
  • pyspider all:本地以子进程或线程方式运行全部组件,可用 --fetcher-num、--processor-num、--result-worker-num 调整各组件实例数,--run-in subprocess|thread 选择运行方式(Windows 下只能用 thread)。
  • pyspider one:单进程调试模式,所有组件跑在一个进程的 tornado ioloop 中,支持 -i 交互式控制台和 --phantomjs;此模式下 WebUI 不运行,结果默认输出到 stdout(可用 pyspider one > result.txt 捕获)。还可以直接传入脚本文件路径,配合脚本头部的 # rate: 1.0、# burst: 3 注释设置抓取速率。
  • pyspider bench:基准测试模式,使用内存版 SQLite 数据库。
  • pyspider scheduler / fetcher / processor / result_worker / webui / phantomjs:分别启动单个组件,用于分布式部署;其中 scheduler 组件在整个集群中只允许一个实例。

小结

pyspider 把"脚本编写、任务调度、页面抓取、结果存储、监控调试"整合成一套开箱即用的爬虫系统:脚本侧通过 BaseHandler 的 on_start、self.crawl、回调方法和 @every/@config 装饰器即可描述完整的抓取流程;系统侧通过消息队列解耦的 Scheduler、Fetcher、Processor、Result Worker 组件实现可水平扩展的分布式抓取;WebUI 则提供了从脚本编写到结果查看的端到端可视化体验。

如果要继续深入学习,推荐按以下路径阅读仓库文档:docs/Quickstart.md(快速上手)、docs/Architecture.md(架构与数据流)、docs/apis/self.crawl.md(API 详解)、docs/Command-Line.md(命令行与部署)、docs/tutorial/index.md(三级实战教程:HTML/CSS 选择器、AJAX 与 HTTP、PhantomJS 渲染),并在 tests/ 目录中阅读 test_base_handler.py、test_scheduler.py 等测试用例加深对内部机制的理解。

登录后查看全文
pyspider