colad

cola 爬虫框架的部署守护进程与管理平台(类 scrapyd + crawlab)。

agent(节点代理):接收项目包部署、启停爬虫子进程、日志采集、心跳注册
master(管理平台):Web UI 聚合多节点——节点监控、项目分发部署、任务启停、实时日志、热配置下发

快速开始

uv sync

# 节点代理(每台爬虫机器一个)
COLAD_REDIS_URL=redis://redis:6379/0 \
COLAD_ADVERTISE_URL=http://本机地址:8090 \
uv run colad agent                      # 默认 :8090

# 管理平台(一台)
COLAD_REDIS_URL=redis://redis:6379/0 \
uv run colad master                     # 默认 :8080,浏览器打开即用

节点如何加入后台

三种方式(可混用),master 的 /api/nodes 会合并去重:

worker 一键加入(推荐,无需共享 Redis)——worker 主动向 master 注册续约:
```
colad worker --master http://master:8080 --token <token> \
  --name edge-01 --advertise http://本机地址:8090
```
等价于启动 agent 并设 COLAD_MASTER_URL;进程退出会自动注销。
Redis 心跳——agent 配 COLAD_REDIS_URL,写 colad:nodes:*,master 同源读取。
静态列表——master 配 COLAD_NODES="node1=http://host1:8090,node2=..."。

colad CLI

colad master                                   # 启动管理平台
colad worker --master URL --token T            # 启动 worker 并加入后台
colad nodes  --master URL --token T            # 查看已加入的节点
colad deploy --master URL --token T --name proj \
     --path . --project-dir demo_project --runtime uv   # 打包当前目录推送发布
colad deploy-git --master URL --token T --name proj \
     --repo git@github.com:u/r.git --branch main        # 让节点从 Git 克隆

deploy 不指定 --nodes 时默认推送到所有在线节点;--master/--token 可用环境变量 COLAD_MASTER_URL / COLAD_TOKEN 省略。

通用爬虫(非 cola 项目)

colad 是语言/框架无关的部署平台。任意爬虫项目在根目录放一个 colad.json 清单声明爬虫和启动命令即可(类似 Crawlab 的 Spiderfile):

{
  "runtime": "system",
  "install": "pip install -r requirements.txt",
  "spiders": {
    "news": "python3 crawl.py",
    "shop": "scrapy crawl shop"
  }
}

有 colad.json → 从清单发现爬虫;无清单 → 回退 cola 自动发现,完全兼容。
system 运行时直接执行命令(依赖预装或由 install 处理);也可用 uv/venv/conda/docker 把命令包进隔离环境。
启动任务时配置经环境变量注入:COLAD_SETTINGS(任务 settings 的 JSON)、 COLAD_TASK_ID、COLAD_NODE_NAME、COLAD_METRICS_FILE(爬虫可选写入快照 jsonl,即出现在效率仪表盘/Prometheus 中)。

colad deploy --master URL --token T --name news --path . --runtime system

部署与运行 cola 爬虫

两种部署来源,部署后 agent 自动安装依赖并发现爬虫:

tar 包上传(UI「项目部署」页或 API):

cd cola && tar czf /tmp/proj.tar.gz --exclude=.venv --exclude=.git .
curl -F file=@/tmp/proj.tar.gz -F name=quotes -F project_dir=demo_project \
     -F runtime=uv -F nodes=node1,node2 http://master:8080/api/deploy

Git 克隆(浅克隆指定分支;私有仓库配 COLAD_GIT_SSH_COMMAND):

curl -X POST http://master:8080/api/deploy/git -H 'Content-Type: application/json' \
     -d '{"name":"quotes","repo_url":"git@github.com:kingjem/cola.git",
          "branch":"master","project_dir":"demo_project",
          "runtime":"uv","nodes":"node1"}'

运行时环境(runtime)

每个项目部署时选择运行时,依赖安装与爬虫进程按其隔离:

runtime	依赖来源	说明
`uv`(默认)	pyproject.toml(`uv sync`)	推荐,与 cola 仓库布局一致
`venv`	requirements.txt	`python3 -m venv .colad-venv`
`conda`	requirements.txt	需节点装有 conda(`COLAD_CONDA_BIN`)
`docker`	Dockerfile,无则自动生成	基于 `base_image`(默认 python:3.12-slim)构建镜像,任务在容器内跑(--network host),停止走 docker kill

结果数据预览

任务页「结果」按钮预览抓取数据,来源按任务 settings 的 ITEM_PIPELINES 自动探测(redis / mysql·doris / postgres / json 文件),可切换:

curl http://master:8080/api/nodes/node1/tasks/1/results?source=redis&limit=50

mysql/postgres 来源需给 colad 装可选依赖:uv sync --extra mysql --extra postgres。

运行效率观测

启动任务时 colad 自动给爬虫注入 STATS_EXPORT_ENABLED 和 STATS_EXPORT_FILE,cola 的 StatsExporter 扩展每 5 秒写一条指标快照。任务页「效率」按钮打开仪表盘:吞吐(pages/s、items/s)、成功率、平均/最大响应时间、待处理队列深度、在途请求、累计计数、重试/异常、状态码分布,以及吞吐随时间的折线图(运行中每 3 秒自动刷新)。

curl http://master:8080/api/nodes/node1/tasks/1/metrics
# {"latest": {...}, "history": [...], "status": "running"}

docker 运行时的快照写在容器内,host 读不到文件——分布式场景可让爬虫配 STATS_EXPORT_REDIS_KEY 走 Redis 由 master 聚合。

接入 Grafana

两条路(可混用):

① Prometheus 抓取(pull)——colad 暴露 /metrics(agent 出本节点、master 聚合全局单一抓取点),把每个任务的最新快照转成 Prometheus 文本,带 node/task/project/spider/status 标签:

# prometheus.yml
scrape_configs:
  - job_name: colad
    metrics_path: /metrics
    static_configs: [{targets: ['master:8080']}]
    # 若开了鉴权:authorization: {credentials: '<COLAD_TOKEN>'}

Grafana 加 Prometheus 数据源即可画 colad_pages_per_sec、colad_success_rate 等,sum by (project)(...) 聚合。

② 爬虫直接 push——给爬虫 settings 配 STATS_EXPORT_BACKENDS,导出后端可插拔:file / redis / pushgateway(短命任务)/ influxdb。例如:

'STATS_EXPORT_BACKENDS': 'file,pushgateway',
'STATS_PUSHGATEWAY_URL': 'http://pushgateway:9091',
# 或 InfluxDB:
'STATS_EXPORT_BACKENDS': 'influxdb',
'STATS_INFLUXDB_URL': 'http://influx:8086/api/v2/write?org=o&bucket=b&precision=s',
'STATS_INFLUXDB_TOKEN': '...',

Webhook 通知

任务到达终态时 POST 通知;地址按域名自动适配钉钉 / 飞书 / 企业微信机器人格式,其他地址发送通用 JSON(含任务数据与日志尾部)。失败但仍会自动重试的任务不通知,只在最终失败时发一次。

节点级默认:COLAD_WEBHOOK_URL + COLAD_WEBHOOK_EVENTS(默认 finished,failed)
任务/定时任务级:创建时传 webhook_url 覆盖

定时任务

标准 5 段 cron(croniter 亦支持 6 段带秒),由节点 agent 本地调度, agent 重启错过的周期不补跑:

curl -X POST http://master:8080/api/nodes/node1/schedules \
     -H "Authorization: Bearer $COLAD_TOKEN" -H 'Content-Type: application/json' \
     -d '{"name":"每日全量","project":"quotes","spider":"QuotesSpider",
          "cron":"0 3 * * *","settings":{},"max_retries":2,"timeout_seconds":3600}'

UI「定时任务」页支持创建、启停、立即执行、删除;master /api/schedules 聚合全部节点。

失败重试与超时

创建任务/定时任务时可带:

max_retries:退出码非 0(或超时)时自动重建任务,直至达到上限; 重试任务的 retry_count 递增并回链原任务参数
timeout_seconds:超时先 SIGINT 优雅停机,10s 后 SIGKILL, 无论退出码一律记为 failed

鉴权

设置 COLAD_TOKEN(agent 与 master 用同一个值)后,除 /health 和 UI 页面外所有接口要求 Authorization: Bearer <token>;master 转发请求时自动附带。UI 首次访问会弹出登录框,令牌存于浏览器 localStorage。未设置该变量则不校验(仅建议内网开发时使用)。

热配置

任务 settings 开启 "HOT_CONFIG_ENABLED": true 后,UI「任务 → 热配置」或 API 可在运行中调整并发/延迟等(经 Redis Pub/Sub 下发):

curl -X POST http://master:8080/api/nodes/node1/tasks/1/config \
     -H 'Content-Type: application/json' \
     -d '{"settings": {"CONCURRENT_REQUESTS": 8, "DOWNLOAD_DELAY": 0.5}}'

环境变量

变量	默认	说明
`COLAD_DATA_DIR`	`~/.colad`	projects/、logs/、sqlite 数据库
`COLAD_PORT` / `COLAD_MASTER_PORT`	8090 / 8080	agent / master 端口
`COLAD_NODE_NAME`	主机名	节点标识
`COLAD_ADVERTISE_URL`	`http://<hostname>:8090`	master 回连本节点的地址
`COLAD_REDIS_URL`	空	心跳注册 + 热配置;空则不注册
`COLAD_NODES`	空	master 静态节点列表
`COLAD_UV_BIN`	自动探测	uv 可执行文件路径
`COLAD_TOKEN`	空	Bearer 鉴权令牌;空则不校验
`COLAD_SCHEDULER_TICK`	10	定时任务检查间隔(秒)
`COLAD_WEBHOOK_URL` / `COLAD_WEBHOOK_EVENTS`	空 / finished,failed	节点级通知
`COLAD_CONDA_BIN` / `COLAD_DOCKER_BIN`	conda / docker	运行时可执行文件
`COLAD_DOCKER_BASE_IMAGE`	python:3.12-slim	docker 自动生成镜像的 FROM
`COLAD_GIT_SSH_COMMAND`	空	Git 部署私有仓库的 ssh 命令

测试

uv run pytest

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
src		src
tests		tests
.gitignore		.gitignore
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Navigation Menu

Repository files navigation

colad

快速开始

节点如何加入后台

colad CLI

通用爬虫(非 cola 项目)

部署与运行 cola 爬虫

运行时环境(runtime)

结果数据预览

运行效率观测

接入 Grafana

Webhook 通知

定时任务

失败重试与超时

鉴权

热配置

环境变量

测试

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

colad

快速开始

节点如何加入后台

colad CLI

通用爬虫(非 cola 项目)

部署与运行 cola 爬虫

运行时环境(runtime)

结果数据预览

运行效率观测

接入 Grafana

Webhook 通知

定时任务

失败重试与超时

鉴权

热配置

环境变量

测试

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages