pyspider：带可视化 WebUI 的 Python 爬虫系统部署入门
一、项目简介与定位
pyspider 是一个用 Python 编写的分布式爬虫系统，最大特点是自带一个功能完整的 WebUI：在浏览器里即可编写脚本、查看任务队列、监控抓取进度、预览抓取结果。它由 binux 开发并开源，支持 MySQL / MongoDB / Redis / SQLite / Elasticsearch / PostgreSQL 作为后端存储，支持 RabbitMQ / Redis / Kombu 作为消息队列，原生支持 JavaScript 页面抓取、任务优先级、失败重试、周期重抓与按年龄重抓。
pyspider 适合"快速搭一个能跑、能看、能改"的内部采集任务，尤其适合不想立刻上 Scrapy 工程化结构的小团队与个人开发者。
二、开源协议
pyspider 采用 Apache License 2.0，允许商业使用、修改与再分发，需保留版权与许可声明。
三、官方仓库链接
- 仓库：https://github.com/binux/pyspider
- 文档：http://docs.pyspider.org/
- 教程：http://docs.pyspider.org/en/latest/tutorial/
说明：原任务清单写的是
pyspider/pyspider，该路径在 GitHub 上已返回 404；实际官方仓库位于作者binux名下，本文按该仓库 README 为准。
四、前置要求
根据官方 README：
- Python 2.6 / 2.7 / 3.3 / 3.4 / 3.5 / 3.6（README 中标注的支持范围；新版本 Python 上可能需要手动解决依赖冲突，建议使用 Python 3.6 虚拟环境）
- 操作系统：Linux / macOS / Windows 均可运行
- 数据库与消息队列按需选择，最小演示使用默认 SQLite 即可
五、安装部署
官方 README 给出的安装命令：
pip install pyspider安装完成后直接运行：
pyspider启动后访问 WebUI：http://localhost:5000/
官方警告（README 原文）：
WebUI is open to the public by default, it can be used to execute any command which may harm your system. Please use it in an internal network or enable
need-authfor webui.
也就是说 WebUI 默认对所有网卡开放，等同于一个可以执行任意 Python 代码的控制台。务必只在内网或本地回环使用，或者通过命令行参数开启鉴权：
pyspider --webui-host 127.0.0.1六、最小示例代码
pyspider 的脚本不需要建项目骨架，直接在 WebUI 里新建 Project 时填入以下 Handler 即可：
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(),
}要点说明（来自官方 README）：
on_start：任务入口，@every(minutes=...)表示按周期重复触发。self.crawl(url, callback=...)：注册一个待抓取任务，并指定回调函数。response.doc(...)：基于 pyquery 的 DOM 查询，jQuery 风格语法。@config(age=...)：在秒级声明该任务结果的有效期，期内不重复抓取。detail_page返回的 dict 会被写入结果表，可在 WebUI 的 Results 页面查看。
在 WebUI 中：
- 点击
Create新建 Project，把上面代码粘进脚本编辑器。 - 把
status从TODO改成DEBUG或RUNNING。 - 点击左下角的
run，即可在Fetcher、Parser、Result三个标签页看到每一步的输出。
七、配置项
常用命令行参数（来自官方文档）：
| 参数 | 含义 |
|---|---|
--host |
WebUI 监听地址，默认 0.0.0.0，建议改为
127.0.0.1 |
--port |
WebUI 端口，默认 5000 |
--dashboard-user /
--dashboard-password |
开启 WebUI 基本认证 |
--database-url |
任务与结果数据库连接串，默认 sqlite:///data.db |
--message-queue |
消息队列地址，默认内置 |
--scheduler-cluster |
分布式调度集群名 |
代码内常用配置（写在 Handler.crawl_config 中）：
crawl_config = {
'headers': {'User-Agent': 'Mozilla/5.0 (compatible; mybot/1.0)'},
'timeout': 30,
'retries': 3,
'age': 24 * 60 * 60,
}八、常见问题
pip install pyspider在 Python 3.10+ 上报依赖冲突 pyspider 长期未发新版，部分传递依赖（如pycurl、lxml、wsgidav）在新 Python 上编译困难。建议用 Python 3.6 虚拟环境，或改用 Scrapy。启动后浏览器打不开 5000 端口 先确认本机防火墙；再确认启动日志里 WebUI 是否真的监听在
0.0.0.0:5000。容器化部署时务必把端口映射出来。WebUI 暴露在公网被入侵 这是 pyspider 最常见的事故。务必
--webui-host 127.0.0.1或加反向代理 + Basic Auth，不要把 5000 直接暴露到公网。JS 渲染页面抓不到内容 pyspider 内置 PhantomJS 支持，但 PhantomJS 早已停止维护；新项目建议改用 Playwright 或 Scrapy + scrapy-playwright。
任务堆积不消费 默认单进程模式下 scheduler/processor/fetcher 都在一个进程里；生产部署应按官方文档分别启动
scheduler、processor、fetcher、webui四个角色。
九、与同类工具对比
- vs. Scrapy：Scrapy 是工程化框架，需要写项目、走版本管理；pyspider 是"开箱即用 + 在线编辑"，适合快速原型，但工程化能力弱。
- vs. Portia：Portia 是 Scrapinghub 出的可视化标注爬虫，连代码都不用写；pyspider 仍要写 Python，但灵活度更高。
- vs. Crawlee：Crawlee 是新一代 Node.js 爬虫 SDK，反检测能力强、活跃维护；pyspider 已多年未活跃，仅适合遗留系统维护。
十、许可
本项目基于 Apache License 2.0 发布。详情见仓库根目录
LICENSE 文件。
十一、责任使用声明
- 抓取前遵守目标站点的
robots.txt与服务条款，仅采集公开允许访问的页面。 - 通过
crawl_config设置合理的timeout、retries与请求间隔，控制并发，避免压垮目标服务器。 - 不要绕过登录、付费墙、验证码或其他访问控制去获取未授权内容。
- 不批量采集、存储或再分发涉及个人隐私的数据。
- 本系统仅用于公开数据采集、学术研究与合法的商业情报分析，使用者自行承担合规责任。
- 尊重原作者版权，抓取到的正文、图片等内容在二次发布时应注明来源并遵守相应许可。