Gopeed 如何配置 Webhook 在任务完成或失败时通知外部服务并验证连通性?

原创2026-09-12 19:48:422,208 阅读
文章标签:桌面应用跨平台网络移动开发CLIMCP 服务

Gopeed 如何配置 Webhook 在任务完成或失败时通知外部服务并验证连通性?

如果你在用 Gopeed(基于 Go 和 Flutter 的下载管理器)批量管理任务,又希望在任务下载完成或失败时自动通知外部服务(内部系统、CI、告警渠道等),就需要配置它的 Webhook 功能。完成本文操作后,Gopeed 会在任务结束(成功或失败)时向指定地址推送一条 JSON 事件,并且你可以在不发起真实下载的情况下,通过内置的测试接口先验证这个地址的连通性。

Webhook 的发送逻辑位于 pkg/download/webhook.go,触发点在 pkg/download/downloader.go(完成)和 pkg/download/downloader.go(失败)。

准备条件

  • 一个正在运行的 Gopeed 实例,并且其 REST API 可访问。如果走界面配置,直接使用 Gopeed 客户端即可;如果走接口配置,需要知道 REST API 的地址和端口。仓库中的本地开发入口 cmd/api/main.go 启动的 API 地址为 127.0.0.1:9999,本文接口示例均按此地址书写,其他环境请替换为你实际的 API 地址。
  • 一个可被 Gopeed 访问到的接收端点。该端点必须返回 HTTP 200,连通性测试才算通过。

配置 Webhook:开关与 URL 列表

Webhook 配置项定义在 pkg/base/model.go 的 WebhookConfig 中,结构为:

{
  "webhook": {
    "enable": true,
    "urls": ["https://your-server.example.com/hooks/gopeed"]
  }
}
  • enable:总开关,必须为 true 才会发送。
  • urls:接收地址列表,支持配置多个,每个任务事件会推送到所有地址。列表中的空字符串会被忽略。
  • https://your-server.example.com/hooks/gopeed 是占位地址,替换为你自己的接收端点 URL,这是整篇文章中唯一需要你提供值的占位符。

另外,代码保留了向后兼容:如果配置里使用旧的 extra.webhookUrls 字段存放地址列表,同样会被识别(见 pkg/download/webhook.go)。新配置建议直接使用上面的 webhook 结构。

方式一:通过客户端设置界面

在 Gopeed 的设置页面中,Webhook 有两个入口(见 settings_page.dart):

  1. 打开 “Webhook” 开关(对应 webhook.enable);
  2. 在推送地址列表中逐条添加、编辑或删除 URL(对应 webhook.urls);
  3. 每条地址旁边提供测试按钮,点击即调用下文的连通性测试接口。

方式二:通过 REST API 修改配置

如果不用界面,可以通过配置接口读写同一份数据。先读取当前完整配置,只修改 webhook 部分后再整体写回(接口接受并保存完整的下载器配置结构,见 pkg/rest/api.go):

# 读取当前配置
curl http://127.0.0.1:9999/api/v1/config
# 将上一步返回的配置改为 webhook.enable=true、webhook.urls 填入你的地址后写回
curl -X PUT http://127.0.0.1:9999/api/v1/config \
  -H "Content-Type: application/json" \
  -d @config.json

PUT 成功后响应 code 为 0;写回失败时 code 为 1000,msg 中是错误信息。响应包装结构为 code / msg / data(见 pkg/rest/model/result.go)。

Gopeed 是如何推送的

了解推送行为,才能正确设计接收端。依据 pkg/download/webhook.go:

  • 推送方式是 HTTP POST,请求头为 Content-Type: application/json 和 User-Agent: Gopeed-Webhook/1.0;
  • 请求体结构如下(time 为毫秒级 Unix 时间戳,payload.task 为任务对象):
{
  "event": "DOWNLOAD_DONE",
  "time": 1700000000000,
  "payload": { "task": { }
  }
}

上面数值仅表示结构,event 实际只会取 DOWNLOAD_DONE(任务完成)或 DOWNLOAD_ERROR(任务失败)两个值。

  • 每个 URL 的超时时间为 10 秒;
  • 推送在后台异步进行,不会阻塞下载流程;
  • 返回状态码在 200–299 区间记为发送成功;返回其他状态码时记录 webhook: received non-success status 警告日志;请求本身失败(连不通等)记录 webhook: failed to send request 警告日志。

验证连通性:使用测试接口

正式跑任务前,先用内置测试接口确认地址可达。接口定义在 pkg/api/service.go,请求体只有一个 url 字段(见 pkg/rest/model/webhook.go):

curl -X POST http://127.0.0.1:9999/api/v1/webhook/test \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.example.com/hooks/gopeed"}'

判定方式:

  • 成功:响应 code 为 0,data 为空。此时你的接收端应能收到一条测试推送。
  • 失败:响应 code 为 1000,msg 形如 webhook test failed: <url> returned status <状态码>。

两点需要注意:

  1. 测试要求接收端精确返回 HTTP 200。而真实任务推送的判定是 2xx 均算成功。如果接收端返回 201/204,测试接口会报失败,但真实事件仍然会被计为发送成功。
  2. 测试推送的是模拟任务而非真实任务数据:TestWebhookUrl 会构造一个事件类型为 DOWNLOAD_DONE 的模拟载荷,其中文件名为 test-file.zip、大小 100MB(见 pkg/download/webhook.go)。这是文档代码中的固定示例值,只用于连通性验证,接收端不应据此做任何业务判断。

仓库测试 pkg/rest/server_test.go 覆盖了这条链路的验证方式:模拟接收端断言收到的 Content-Type 为 application/json、请求体包含 event、time、payload 三个字段;不可达的地址和非 200 响应均会走失败分支。

用真实任务做最终确认

连通性通过后,发起一次真实下载即可确认完整链路:

  1. 让一个任务正常下载完成,接收端应收到 event 为 DOWNLOAD_DONE 的推送;
  2. 让一个任务失败(例如无效地址),接收端应收到 event 为 DOWNLOAD_ERROR 的推送;
  3. 检查 payload.task 内容与你发起的任务一致。

如果接收端没有收到推送,按代码行为依次核对:

  • 配置中 webhook.enable 是否为 true 且 urls 非空——两者任一不满足时 getWebhookUrls 返回空,根本不会发送;
  • 接收端是否在 10 秒内响应;
  • Gopeed 日志中是否出现 webhook: received non-success status(地址可达但状态码非 2xx)或 webhook: failed to send request(请求失败,通常是网络不可达)。

限制说明

  • 推送是“尽力而为”:发送失败只记录警告日志,不会重试,也不会影响下载任务本身的状态;
  • 测试接口每次只测一个 URL,且只接受返回 200 的地址;
  • 配置修改通过 PUT /api/v1/config 写回的是完整配置结构,写回前建议先用 GET /api/v1/config 拿到当前值再改动,避免覆盖其他配置段。
登录后查看全文
gopeed