pyspider 爬虫系统入门指南:架构、安装与第一个 Python 爬虫脚本
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):
架构的核心思想是:各组件通过消息队列解耦。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):
推荐的调试流程是(详见 docs/Quickstart.md):
- 在 WebUI 中编写脚本,点击绿色的
run按钮单步执行; - 切换到
follows面板,点击播放按钮继续推进,逐层验证每个回调的输出; - 满意后保存脚本,回到 dashboard(项目列表页);
- 将项目
status改为DEBUG或RUNNING; - 再次点击
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 等测试用例加深对内部机制的理解。

