1. 为什么需要Scrapyd本地跑通只是第一步如果你也是写了几年爬虫、但每次“上线”都靠手动登录服务器敲命令行的人那你大概率经历过这种尴尬本地scrapy crawl article_spider跑得好好的一到服务器上就得用nohup ... 挂后台几小时后想看看跑没跑完还得ps aux | grep scrapy去找进程号。爬虫一多、服务器一多这种手工操作就会变成灾难。Scrapyd 就是来解决这个问题的。它是一个伴随 Scrapy 体系的官方守护进程服务专门负责把打包好的爬虫项目上传到服务器、远程调度运行、提供增量版本管理并通过一套简单的 HTTP API 对爬虫的整个生命周期做控制。也就是说它把“部署”和“调度”从命令行敲击变成了几个curl请求或一行scrapyd-deploy命令。从我实际接触过的团队看很多人在本地写爬虫的能力已经不错了但始终卡在“怎么让爬虫稳定地跑在远端服务器上”这一关。有人用crontab硬调度scrapy crawl有人干脆一台机器一个爬虫一个screen挂着爬虫多了以后项目环境互相污染依赖版本一升级就集体崩溃。Scrapyd 的价值恰恰在于它把所有爬虫项目拆分成独立版本按项目名隔离并通过 API 统一调度不需要你再关心“这个爬虫是哪个环境跑起来的”。还有一点必须提醒Scrapyd 不是爬虫框架它不会帮你写解析逻辑也不负责定时触发。它更像一个“爬虫运行时的容器和调度员”负责接收打包好的代码、拉起 Scrapy 进程、收集日志和运行状态。定时任务仍然需要crontab、系统自带定时器或你自己写的调度脚本去调用schedule.json接口。搞清楚这条职责边界后面所有配置和排错才不会跑偏。有人会问那我直接用scrapy runspider不是也行行但只适合单文件爬虫或临时调试。凡是涉及多爬虫、多项目、多版本的生产环境缺少一个集中式的部署与调度入口迟早会在某个深夜因为“忘了重启爬虫”付出代价。Scrapyd 要解决的就是这套集中管理问题这也是我把它列入 Scrapy 学习核心笔记的原因。2. 服务端落地安装、配置与守护进程管理2.1 安装与基础配置服务端安装很简单pip install scrapyd即可。这里我直接推荐装 1.2.0 或更新的稳定版它已经兼容 Scrapy 2.x 系列异步框架用的是 Twisted安装时会自动带上。装完以后你可以在任意目录敲scrapyd默认监听127.0.0.1:6800。注意这个默认地址比较关键如果你直接在服务器上跑只能本机访问远程调用会被拒。生产环境需要先规划好端口和绑定地址。我常用的配置方式是写一个/etc/scrapyd/scrapyd.conf[scrapyd] egg_url http://127.0.0.1:6800/ http_port 6800 bind 127.0.0.1 daemon on max_proc 0 max_proc_per_cpu 2 jobs_to_keep 20 finished_to_keep 100 poll_interval 5几个参数的含义我说一下方便你按自己的机器调整bind决定了服务监听的地址。如果只有本机能访问就保持127.0.0.1然后靠 nginx 反向代理对外提供如果你在受信内网环境可以改成0.0.0.0。不要一上来就0.0.0.0后面我会专门讲安全坑。daemon设为on后scrapyd自身会在后台常驻运行适合调试期快速使用生产环境我还是建议用 systemd 管理后面给出例子。max_proc_per_cpu每颗 CPU 允许同时运行的进程数。设成 2表示一台单核机器最多同时跑两个爬虫进程。jobs_to_keep/finished_to_keep保留最近运行任务记录的数量上限不代表日志文件会自动删除日志清理要额外做。poll_interval轮询间隔单位秒影响任务状态刷新的及时性。启动后用一条命令看看服务是否正常curl http://127.0.0.1:6800/daemonstatus.json返回{status: ok, ...}就说明服务活了。daemonstatus.json是排查服务状态的第一入口我每次部署完都先打它一下确认节点在线再往下走。2.2 用 systemd 把 scrapyd 做成常驻服务daemon on只是让 scrapyd 自已在后台运行一旦机器重启它不会自动起来。生产环境正确的做法是写一个 systemd unit 文件。我的单位文件大致如下[Unit] DescriptionScrapyd service Afternetwork.target [Service] Userwww-data Groupwww-data WorkingDirectory/var/www/scrapyd ExecStart/usr/local/bin/scrapyd --config/etc/scrapyd/scrapyd.conf Restartalways RestartSec5 [Install] WantedBymulti-user.target写完后执行systemctl daemon-reload systemctl enable scrapyd systemctl start scrapyd用 systemd 的好处不只是开机自启。如果爬虫进程把内存打满导致 scrapyd 崩溃Restartalways会自动拉起服务这在无人值守的采集任务中非常关键。我见过某位同事的服务器一跑大采集就死机后来发现 scrapyd 靠daemon on裸跑挂了之后整台机器上的调度全部静默中断数据缺失了两周才被发现。所以进程守护这块千万别省。2.3 安全边界别把调度接口裸到公网Scrapyd 本身没有内置用户认证任何能访问 6800 端口的人都可以调用schedule.json来调度你的爬虫甚至通过addversion.json上传恶意项目。网络上关于 Scrapyd 接口被扫描刷爆的案例并不少见轻则资源被占用重则机器沦为矿机。我的建议很直接如果只是内网使用bind保持127.0.0.1再用 nginx 反向代理并加上 Basic Auth如果必须对公网提供服务至少要用云安全组的白名单限制来源 IP并且不要暴露 6800 端口。下面是一个 nginx 反代的简化配置location / { auth_basic scrapyd protected; auth_basic_user_file /etc/nginx/.scrapyd_htpasswd; proxy_pass http://127.0.0.1:6800; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }这一步看起来和“部署”没有直接关系但如果漏了后面所有部署和调度都是在自己给自己挖坑。安全底线先立好再谈功能。3. 本地部署一个 Scrapy 项目从 setup.py 到 scrapyd-deploy3.1 项目结构补课为什么默认项目缺了 setup.pyScrapy 用scrapy startproject myproject生成的项目默认结构是myproject/ ├── scrapy.cfg ├── myproject/ │ ├── settings.py │ ├── items.py │ ├── pipelines.py │ └── spiders/ └── ...细心的朋友可能已经发现这里面没有setup.py。而scrapyd-deploy在打包时依赖 setuptools 的setup.py来生成 egg 包。没有这个文件部署命令会直接报错退出。所以说setup.py不是可选项而是部署的必需品。我通常会在项目根目录手动加上一个最小化的setup.pyfrom setuptools import setup, find_packages setup( namemyproject, version1.0, packagesfind_packages(), entry_points{scrapy: [settings myproject.settings]}, )注意entry_points这一行它声明了 Scrapy 项目设置的入口。myproject.settings必须写成你实际项目里的 settings 模块路径拼错一个字部署完以后服务端都识别不了这个项目里的爬虫列表。3.2 scrapy.cfg 的 deploy 段配置scrapyd-deploy会读取项目根目录下的scrapy.cfg里面的[deploy]段决定了部署到什么服务器。我一般会写一个明确的 target避免同时管理多台服务器时传错[deploy:local] url http://127.0.0.1:6800/ project myproject这里local只是我定义的 target 名字可以随便叫dev、prod。url是服务端地址project是发布到 Scrapyd 上的项目名它不一定等于代码里的项目包名但为了方便我通常保持一致。如果 scrapy.cfg 里只有一个[deploy]段直接运行scrapyd-deploy也能用默认 target但项目一多我建议还是显式指定 target否则很容易把本来要发到测试环境的代码发到生产环境。这个坑我见得太多了。3.3 实际执行部署先安装部署客户端pip install scrapyd-client然后执行cd myproject scrapyd-deploy local -p myproject --version v1.0-p myproject指定项目名--version指定版本标识。版本号可以用任何字符串我习惯用 git commit 的短 hash 或者部署时刻的时间戳这样回滚时能一眼看出哪个版本对应哪次代码变更。如果部署成功终端会打印类似内容Packing version v1.0 of myproject Deploying to Scrapyd server http://127.0.0.1:6800/ Server response (200): {node_name: node1, status: ok, project: myproject, version: v1.0, spiders: 3}spiders: 3表示服务端已经从这个包中识别出了 3 个爬虫。看到这个数字才算真正部署完成。3.4 部署过程发生了什么事egg 打包与上传很多人用scrapyd-deploy用得熟练但不懂它背后干了什么出了问题就两眼一抹黑。这里我拆一下scrapyd-deploy首先根据项目里的setup.py执行python setup.py bdist_egg生成一个 egg 文件然后把 egg 文件通过POST /addversion.json传送到服务器参数包括project、version和文件字段egg。服务器收到后会把这个 egg 解压并存放到它自己的 eggs 目录和 projects 目录之后schedule.json才能按项目名和版本把代码跑起来。等价于下面这条手动命令curl -s -F projectmyproject -F versionv1.0 \ -F eggdist/myproject-1.0-py3.10.egg \ http://127.0.0.1:6800/addversion.json理解这一步对你后面排查部署问题特别有帮助。比如当scrapyd-deploy报出“Egg 构建失败”的时候你知道问题出在本地打包阶段可以先检查setup.py和 setuptools 版本如果报的是服务器返回 500你才知道是服务器端解压或校验出了问题。还有一个细节容易忽视scrapyd-deploy打的是代码包不是依赖包。项目的第三方依赖比如requests、redis、pymongo服务端必须提前手动装好。Scrapyd 不会帮你装任何requirements.txt它只负责把你写的爬虫代码变成可运行的 egg。服务端缺依赖的后果我会在后面的坑里专门讲。4. 远程调度的核心 APIaddversion 之后怎么用起来4.1 确认部署结果的几个接口部署完成后先别急着调度爬虫。我一般会先调三个只读接口确认状态curl http://127.0.0.1:6800/listprojects.json返回的projects列表里应该有myproject。再查具体项目的版本和爬虫列表curl http://127.0.0.1:6800/listversions.json?projectmyproject curl http://127.0.0.1:6800/listspiders.json?projectmyprojectlistversions.json会显示当前服务器上该项目的所有版本listspiders.json会显示可以调度的爬虫列表。这两个接口是我排查部署是否成功的第一手工具。如果项目存在但爬虫列表为空多半是setup.py的entry_points配置指向了错误的 settings 模块或者是爬虫文件没有通过find_packages()被包含进 egg 包。4.2 schedule.json真正开始跑爬虫调度一个爬虫的方式很直观curl http://127.0.0.1:6800/schedule.json \ -d projectmyproject \ -d spiderarticle_spider \ -d jobidtest001 \ -d arg1value1返回包会带上你指定的jobid{node_name: node1, status: ok, jobid: test001}如果没指定jobidScrapyd 会自动生成一个随机字符串。我建议在调用方主动设置jobid这样跟踪任务时可以把你业务侧的批次号直接关联到爬虫任务比如每天的任务批次就是当天的日期字符串排查日志时非常方便。-d arg1value1这种参数会作为爬虫的-a参数传入对应爬虫内部的__init__或start_requests读取的自定义参数。如果你需要传一个 JSON 对象建议直接在命令行里写curl http://127.0.0.1:6800/schedule.json \ -d projectmyproject \ -d spiderarticle_spider \ -d jobidjob_20250115 \ --data-urlencode args{start_page: 1, end_page: 10}4.3 cancel.json 与任务停止调度起来容易停的时候也有讲究。停止任务用cancel.jsoncurl -d projectmyproject -d jobidtest001 \ http://127.0.0.1:6800/cancel.jsoncancel.json会对正在运行的爬虫进程发起终止信号但已经发出的请求、正在等待回调的代码片段不会立刻消失线程可能还会再执行一小会儿。业务上如果要求“立即停止”你得在爬虫代码里自行检查信号或状态标志这个属于爬虫本身的设计问题不是 Scrapyd 能完全兜底的。另外要强调Scrapyd 没有暂停恢复的 API。cancel.json停了就是停了不会自动续跑。如果你需要断点续抓应该在爬虫里自己做增量状态记录比如基于抓取 URL 的集合去重或基于数据库中的最新状态位判断。4.4 把一次部署调度串成脚本手动敲 API 适合调试日常使用最好封装成脚本。我经常用这样一个deploy_and_schedule.sh#!/bin/bash set -e SCRAPYD_URLhttp://127.0.0.1:6800 PROJECT_NAMEmyproject SPIDER_NAMEarticle_spider VERSION$(date %Y%m%d%H%M%S) JOB_IDjob_$(date %Y%m%d_%H%M%S) scrapyd-deploy local -p $PROJECT_NAME --version $VERSION echo deploy version: $VERSION curl -s $SCRAPYD_URL/schedule.json \ -d project$PROJECT_NAME \ -d spider$SPIDER_NAME \ -d jobid$JOB_ID这样每次执行自动化部署时版本号带时间戳jobid 也带业务批次后续无论查日志还是对账都非常清楚。如果你们团队已经有 CI/CD 平台其实也可以把这几步塞进流水线里本质都是一样的。5. 上线之后的运营细节日志、版本回滚与并发控制5.1 日志的存取与清理Scrapyd 的日志默认按logs/project/spider/jobid.log的目录结构存储。查询正在运行或刚跑完的任务日志直接拼 URL 就行curl http://127.0.0.1:6800/logs/myproject/article_spider/job_20250115.log如果日志是动态追加的你也可以用tail -f方式在服务器上直接观察路径同样在 logs 目录下。注意我把log不解释成画图那个意思哈就是纯文本日志。看日志的时候重点看 Scrapy 统计信息的最后几行比如item_scraped_count、finish_reason而不是只盯着DEBUG刷屏。一个容易被忽略的点是磁盘清理。jobs_to_keep和finished_to_keep控制的是任务元数据的保留数量并不负责删除日志文件。爬虫多、跑得勤的情况下logs/目录会越来越大。我建议在 crontab 里加一条清理命令例如保留最近 7 天的日志find /var/www/scrapyd/logs -name *.log -mtime 7 -delete不要把日志清理拖到“磁盘满了再处理”采集任务一旦中断损失往往比清理日志本身大得多。5.2 多版本共存与回滚Scrapyd 支持同一个项目部署多个版本。每次运行scrapyd-deploy --version xxx并不会覆盖旧版本而是共存。listversions.json可以看到所有版本列表。这里有个重要认知调度时如果不指定版本Scrapyd 默认使用最新部署的版本但已经在运行的任务不会因为新版本部署而切换到新代码。它仍然按启动时加载的旧版本继续执行。这个特性既是优点也是坑优点是你可以部署新版本而不影响线上正在跑的任务坑是如果你的习惯是“部署完就跑新任务”不要想当然认为旧任务也会自动升级。需要回滚时重新部署旧版本代码并让新任务使用它即可。如果旧版本还在listversions.json里甚至可以指定version参数来调度curl -d projectmyproject \ -d spiderarticle_spider \ -d versionold_version_tag \ http://127.0.0.1:6800/schedule.json用完不想保留的旧版本可以通过POST /delversion.json删除参数是project和version。删除整个项目则用delproject.json操作前一定确认你已经不需要该项目的任何历史记录。5.3 并发参数怎么调Scrapyd 本身可以同时运行多个爬虫进程并发数受max_proc和max_proc_per_cpu控制。默认情况下max_proc 0表示不限制总进程数max_proc_per_cpu根据 CPU 核数自动计算。如果你想控制一台机器上同时最多跑 3 个爬虫就设[scrapyd] max_proc 3 max_proc_per_cpu 1实际调参时不要只盯着 CPU还要看目标站点的承受能力、带宽、数据库连接池和代理池容量。比如某个采集任务单进程就能吃满目标站点给我们的并发上限那max_proc_per_cpu 2反而是灾难因为并发翻倍后要么触发反爬被封要么代理池被打爆。我的习惯是从单进程开始逐步加进程同时观察目标站点请求的响应状态码和数据库写入延迟找到一个稳定值再写死配置。另外Scrapyd 的并发控制是“进程级”的不是“协程级”的。单个 Scrapy 进程内部的并发量由CONCURRENT_REQUESTS等设置控制进程数量和内部并发是两码事。有些文章只教调max_proc_per_cpu完全忽略settings.py里的并发参数容易误导新手。真正合理的做法是进程数管好不同爬虫间的资源隔离CONCURRENT_REQUESTS管好单爬虫内部的请求吞吐。6. 部署与调度中最容易踩的坑6.1 爬虫依赖没装齐任务看起来在跑但没有输出我接过一个最典型的排查案例有同事部署完项目schedule.json返回status: ok日志也有生成但日志里除了启动信息和爬虫名字没有任何抓取输出跑了一阵就自动结束finish_reason也没出现。他反复确认项目代码没问题本地运行一切正常但远程就是“空手而归”。后来我在服务器上手动进入项目目录用部署时的 Python 环境跑了一句python -c import requests; print(requests.__version__)结果直接ModuleNotFoundError。真相很简单爬虫代码里 import 了requests但服务器上没有安装。Scrapyd 打包的是项目代码不是 Python 环境requirements.txt只能在本地用pip install -r requirements.txt安装服务端必须手动安装所有第三方依赖。这个坑的难点在于Scrapyd 的status: ok只代表调度请求被接受了不代表爬虫能正常执行完。所以判断任务是否真的在干活一定要去看日志里有没有item_scraped_count之类的统计输出而不能只依赖调度接口的返回。6.2 listspiders.json 查不到爬虫部署成功返回spiders: 3但listspiders.json查出来却是空列表这种问题多半出在setup.py的entry_points配置上。entry_points里声明的 settings 模块必须能被 setuptools 正确找到而且模块路径要和实际项目结构一致。我曾经在一个项目里把entry_points写成了[settings myproject.settings]但项目目录名实际是my_project下划线结果部署后服务器无法定位到 settings导致爬虫发现机制失效。这里有个小技巧部署完先执行一下listspiders.json如果发现数量不符合预期第一时间检查setup.py的模块路径和find_packages()是否把spiders目录包含进去了。6.3 版本更新的热切换误解另一个高频误解是“部署新版本后正在跑的任务会自动应用新代码”。Scrapyd 的设计是隔离的部署时新增一个版本正在运行的任务继续按旧版本执行到底只有新调度的任务才会使用最新版本。这其实是个好特性但如果你不做版本区分连续部署时会产生大量垃圾版本占用磁盘空间。我的实践是用 git 短 hash 做版本号配合listversions.json定期清掉超过 5 个的历史版本。这样既保持可回滚又不会让 eggs 目录无节制膨胀。这里再强调一次除非你明确做 A/B 对比测试否则生产环境delversion.json要谨慎使用删掉的版本一般没法再从服务器上找回来。6.4 公网环境被刷接口这是安全相关的老生常谈但我还是想说一遍具体场景有一次某台机器上的daemonstatus.json显示同时运行了几十个任务而这些任务根本不是我们调度的日志里全是打印超长的随机字符。原因无非是 6800 端口直接暴露在公网被扫描器嗅探到以后攻击者通过addversion.json上传了恶意项目并持续schedule.json刷任务。修复方式前面也说过了bind内网地址或 127.0.0.1再用防火墙白名单收敛来源对外只通过 nginx 加认证暴露。如果你已经发生了类似情况先别急着清理日志第一步是关闭公网访问第二步检查服务器上是否有未知的可执行文件或计划任务第三步再重置数据库账号密码。安全问题的处置顺序很重要先止血再排查最后恢复业务。我个人的体会是Scrapyd 的学习曲线并不陡难的是把它放进一个真实的生产链路里连同环境、依赖、日志、版本、安全和调度策略一起通盘考虑。如果你也准备在公司或自己的服务器上部署 Scrapy 项目建议先按这篇文章把服务端和安全配置搭好再用一个最小的示例项目完整走一遍部署、调度、查日志、删版本的流程跑熟了以后再去接定时任务和监控告警。这个顺序看起来慢实际是遇到问题最少的路。