papa爬虫框架
Papa - 高性能爬虫框架
基于 Go 的爬虫框架,内置浏览器自动化(Rod)与静态 HTML 抓取(htmlfetch)双引擎:浏览器池、多阶段工作池、任务持久化与恢复、M3U8/文件下载、失败重投/启动恢复/周期轮询治理队列、Web 监控。框架不再内置通用 cron 调度器。
运行观测(obs):框架级结构化事件流(logs/events.jsonl)+ 人读报告 / 机读 JSON / AI 排查细则(papa report),见 OBSERVABILITY.md。
快速开始
go install github.com/ydtg1993/papa/v3/cmd/papa@latest
papa new mycrawler --replace /path/to/papa # 或外部 go run github.com/ydtg1993/papa/v3/cmd/papa@latest new mycrawler
cd mycrawler && go mod tidy
- 把
configs/config.yaml的db.dsn指向你的 MySQL(configs/config.yaml.example是进版本库的范本,
照它抄一份自己的config.yaml)。 papa migrate建表 —— 在项目目录下跑(它自己读configs/config.yaml)。检测到这是业务
项目时,它会转交项目自己的迁移入口,框架表与models包里的业务模型一起建。
之后每新开一个带表的开关(server.operation_log/crawler.trace.enabled)都要再跑一次,那两张表跟着开关走。- 写 fetcher(实现
papa.Fetcher);站点与阶段声明写在sites/<站名>.go(并发/队列/间隔/重试/
入口开关都在那儿一份写全,各文件在自己的init()里登记),main.go里只有app.RegisterSites(papa.Sites()...)
一行 —— 加一个站只加文件。起始任务由 fetcher 自己实现SubmitEntries(engine, site)提交
(见 FETCHER_WRITING_GUIDE.md 1.1)。 - 加数据模型写根目录
models/包(models/models.go里登记建表清单);后台(/monitor)
要加表格页 / 自定义页 / 自己的接口,改monitor/包 ——main.go只有monitor.Register(app)一行(分层与用法见 MONITOR.md 第 5 节)。 go run .(配置路径默认configs/config.yaml,要用别处就go run . --config=./config.yaml)。
启动时不会自动建表 —— 迁移是显式的一步,所以本地和生产跑的是同一条命令。
底层使用 GORM AutoMigrate,主要用于补表、列和索引,不负责删除列或表达全部破坏性变更。重复执行通常是幂等的,但生产环境仍应先备份、审查生成 SQL,并为改名、改类型等变更自己写迁移 SQL。
在项目目录里
papa migrate与make migrate等价:CLI 是独立编译的进程,看不到你在main.go/models.Models()里注册的模型,所以它在业务项目里会把迁移转交给项目自己
(go run . -migrate→App.Migrate()),两边都建。不在业务项目里跑时它只建框架自带的表。
脚手架刚生成的项目没有业务表(框架只管调度状态,抓到的结果要在models/里建业务表来落),
所以起步阶段两条命令等价。判据与细则见 CORE_CONFIG.md 第 2 节。
阅读路径
先按「你要做的事」定位手册,再进对应手册查字段 / 接口 / 示例:
| 我要… | 手册 | 手册在讲什么 |
|---|---|---|
| 从零写抓取逻辑(HTML / Rod 策略、场景示例) | FETCHER_WRITING_GUIDE.md | Fetcher 契约、两种抓取策略、常见坑 |
| 把抓到的数据落库 | DATA_LANDING_GUIDE.md | 单表+JSON、三条落地路径、API 速查 |
| 查 / 改某个配置项 | CORE_CONFIG.md | 全部配置项字典、时长格式、站点/阶段声明,以及全局三个治理队列 |
| 失败任务要重跑 | ERROR_QUEUE.md | error_queue 配置、自动/手动触发、再处理上限 |
| 重启后捡回中断的任务 | RECOVER_QUEUE.md | recover_queue、启动时重投本进程启动前遗留的未终态任务 |
| 周期轮询 repeatable 任务 | REPEAT_QUEUE.md | repeat_queue、到点才重投(周期可逐条定、后台可改) |
| 加一个站 / 管多个站点(站点维度都有什么) | FETCHER_WRITING_GUIDE.md §7、DEVELOPMENT.md §7 | 一站一个文件(自登记)、站点键必填、阶段名按站点作用域(两个站可以同名)、站点级请求头/熔断/下载器;三个治理队列有意留在全局 |
| 用监控后台 / 调它的 API / 挂自己的接口 | MONITOR.md | Dashboard、设置/表格页/自定义页/自定义路由与中间件/站点 Tab 与队列治理/暂停铃铛/obs 报告/日志 API |
| 查一轮跑得怎么样 / 出运行报告 / 给报告加业务段 | OBSERVABILITY.md | 事件契约、obs 配置、papa report 4 产物、内置模式库、业务扩展点、局限与注意 |
| 排查「页面抓到了啥」/ 生成新项目 / 升级已有项目 / 建令牌 | CLI.md | papa new 脚手架、html/rod/diff/select 调试命令、upgrade(刷新框架副本+检查)、check(不用起库验声明)、token add |
| 构建 / 测试 / 竞态检测(Makefile) | DEVELOPMENT.md | make 目标、Windows 怎么跑、race 前置条件 |
新手上手顺序:本页 → FETCHER_WRITING_GUIDE.md → DATA_LANDING_GUIDE.md,其余按需查。
注意事项
- 遵守目标网站 robots.txt 与法律法规,合理设置抓取频率。
- 生产环境建议
headless: true,按负载调pool_size(浏览器全局并发上限,browser.enable: true时必填且 > 0;改需重启)/ 数据库连接池。 - 自动合并 MP4 需系统安装 ffmpeg。
License
基于 MIT License 开源。
本作品采用《CC 协议》,转载必须注明作者和本文链接
关于 LearnKu
推荐文章: