Zulip 集成 Sonarr 指南将追剧通知实时推送到团队聊天【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulip本篇指南围绕 Zulip 仓库中的 Sonarr 官方集成展开讲解如何把 Sonarr剧集自动下载管理工具的抓取、导入、升级、删除、健康检查等事件实时推送到 Zulip 流Stream中。读完本文你将掌握从创建 incoming webhook bot、生成 webhook URL、在 Sonarr 中完成 Connect 配置到理解底层事件分发与消息模板机制的完整实战方案。集成概述Zulip 的 Sonarr 集成位于 zerver/webhooks/sonarr 目录是一个典型的 incoming webhook入站 Webhook集成Sonarr 作为事件源通过 HTTP POST 请求把通知推送到 Zulip 的 API 端点Zulip 端解析事件后以机器人身份将消息投递到指定流。该集成在 zerver/lib/integrations.py 中被注册为IncomingWebhookIntegration(sonarr, [entertainment], ...)归类于 entertainment娱乐分类并使用sonarr_episode_grabbed.json作为界面截图配置。集成入口函数为api_sonarr_webhook定义于 zerver/webhooks/sonarr/view.py它通过webhook_view(Sonarr, all_event_typesALL_EVENT_TYPES)声明支持的完整事件类型集合ALL_EVENT_TYPES [ Grab, # 剧集被抓取 EpisodeFileDelete, # 剧集文件被删除 Test, # 连接测试 Download, # 下载完成/导入 SeriesDelete, # 剧集被删除 Health, # 健康检查 Rename, # 剧集文件重命名 ]配置步骤1. 创建 incoming webhook bot 并获取 URL进入 Zulip 组织设置创建一个Incoming webhook类型的机器人bot随后得到形如下面的 Webhook URLhttps://your-zulip-host/api/v1/external/sonarr?api_keybot-api-keystream目标流名称其中api_key机器人bot的 API 密钥用于身份鉴权Zulip 会校验该密钥对应的 bot 是否被允许发送入站 Webhook 消息stream通知消息要投递到的目标流Stream名称若不指定则使用创建 bot 时选定的默认流。2. 在 Sonarr 中配置 Connect打开 Sonarr 的 Web 控制台进入Settings设置选择Connect连接点击加号图标新建一个连接选择Webhook类型为连接起一个任意名称例如Zulip勾选你希望接收通知的事件场景Sonarr 中可选的事件触发器与 Zulip 端支持的eventType一一对应详见下文「事件与消息模板」如有需要可填写标签Tags实现只针对带特定标签的剧集发送通知将URL设置为上面生成的地址Method设置为POSTUsername与Password字段留空Zulip 通过 URL 中的api_key完成鉴权无需 Basic Auth点击Save保存Sonarr 会立即发送一条测试消息到 Zulip用于验证连通性。3. 验证配置保存后Zulip 中会收到来自 Sonarr bot 的测试消息Sonarr webhook has been successfully configured.同时zerver/webhooks/sonarr/tests.py 中的test_sonarr_test用例对此行为做了精确断言测试事件对应的主题为Sonarr - Test消息体为Sonarr webhook has been successfully configured.。配置成功后你在 Sonarr 中设定的所有事件通知都会以对应剧集标题作为主题Topic出现在 Zulip 的指定流中。事件与消息模板详解Sonarr 推送的每个事件都包含eventType字段Zulip 端根据它分派到不同的处理函数见 zerver/webhooks/sonarr/view.py。主题Topic与消息体的生成规则如下eventType主题模板消息模板TestSonarr - TestSonarr webhook has been successfully configured.HealthHealth {level}如Health warning{message}.健康检查消息原文Rename{series_title}{series_title} episodes have been renamed.SeriesDelete{series_title}{series_title} has been deleted.Download非升级{series_title}{series_title} - {season}x{episode} - {episode_name} has been imported.DownloadisUpgradetrue{series_title}{series_title} - {season}x{episode} - {episode_name} has been upgraded from {old_quality} to {new_quality}.Grab{series_title}{series_title} - {season}x{episode} - {episode_name} has been grabbed.EpisodeFileDeletedeleteReason 非 upgrade{series_title}{series_title} - {season}x{episode} - {episode_name} has been deleted.EpisodeFileDeletedeleteReasonupgrade{series_title}{series_title} - {season}x{episode} - {episode_name} has been deleted due to quality upgrade.对应的模板常量定义于 view.py例如SONARR_TOPIC_TEMPLATE {series_title}.strip() SONARR_MESSAGE_TEMPLATE_EPISODE_GRABBED ( {series_title} - {series_number}x{episode_number} - {episode_name} has been grabbed..strip() ) SONARR_MESSAGE_TEMPLATE_EPISODE_IMPORTED_UPGRADE {series_title} - {series_number}x{episode_number} - {episode_name} has been upgraded from {old_quality} to {new_quality}..strip()主题生成逻辑get_topic_for_http_requestview.py按事件类型决定主题Test事件使用固定主题Sonarr - TestHealth事件的主题为Health {level}其中level取自 payload 的level字段如warning、error从而得到Health warning、Health error这样的主题其余事件一律使用剧集标题series.title作为主题。这意味着同一部剧集的所有事件会归拢到同一个 Zulip 主题下便于按剧集追溯完整时间线。分支判断细节get_body_for_http_request中包含了两个基于可选字段的二分支逻辑Download事件当 payload 中存在isUpgrade字段且为true时进入「升级导入」分支消息同时引用episodeFile.quality新质量与deletedFiles[0].quality旧质量否则为普通导入消息EpisodeFileDelete事件当deleteReason为upgrade时判定为「因画质升级而删除旧文件」输出升级删除消息否则输出普通删除消息。若收到未注册的eventTypeget_body_for_http_request会抛出UnsupportedWebhookEventTypeError由框架统一返回错误响应。消息正文与事件载荷字段对照Zulip 端通过typed_endpoint将请求体解析为JsonBodyPayload[WildValue]并使用tame(check_string)/tame(check_int)等校验器逐一提取字段。不同事件依赖的核心字段如下以仓库 fixtures 为证事件依赖字段参考 fixtureGrabseries.title、episodes[0].seasonNumber、episodes[0].episodeNumber、episodes[0].titlesonarr_episode_grabbed.jsonDownload上述字段 isUpgrade、episodeFile.quality、deletedFiles[0].quality升级时sonarr_episode_imported.json、sonarr_episode_imported_upgrade.jsonEpisodeFileDelete上述字段 deleteReasonsonarr_episode_deleted.json、sonarr_episode_deleted_upgrade.jsonHealthlevel、messagesonarr_health_check_warning.json、sonarr_health_check_error.jsonRenameseries.titlesonarr_episodes_renamed.jsonSeriesDeleteseries.titlesonarr_series_deleted.jsonTest无业务字段依赖sonarr_test.json以升级导入事件为例sonarr_episode_imported_upgrade.json 展示了 Sonarr 发送的原始载荷eventType为DownloadisUpgrade为trueepisodeFile.quality为HDTV-720pdeletedFiles[0].quality为SDTV。经 Zulip 处理后最终渲染为NCIS - 18x10 - Watchdog has been upgraded from SDTV to HDTV-720p.测试用例与质量保障该集成配套了完整的单元测试zerver/webhooks/sonarr/tests.py继承自WebhookTestCase覆盖全部 10 种事件组合测试方法期望主题期望消息test_sonarr_testSonarr - TestSonarr webhook has been successfully configured.test_sonarr_series_deletedBreaking BadBreaking Bad has been deleted.test_sonarr_health_check_warningHealth warningIndexers unavailable due to failures ...test_sonarr_health_check_errorHealth errorNo indexers available with RSS sync enabled ...test_sonarr_episodes_renamedThe L WordThe L Word episodes have been renamed.test_sonarr_episode_importedGreys AnatomyGreys Anatomy - 17x9 - In My Life has been imported.test_sonarr_episode_imported_upgradeNCISNCIS - 18x10 - Watchdog has been upgraded from SDTV to HDTV-720p.test_sonarr_episode_grabbedNCISNCIS - 18x10 - Watchdog has been grabbed.test_sonarr_episode_deletedBreaking BadBreaking Bad - 1x1 - Pilot has been deleted.test_sonarr_episode_deleted_upgradeS.W.A.T. (2017)S.W.A.T. (2017) - 4x10 - Buried has been deleted due to quality upgrade.这些测试通过真实 fixture 驱动整个「HTTP 请求 → 事件解析 → 消息生成 → 投递」链路确保了 Sonarr 侧各版本载荷变化下集成行为的稳定性也为你二次开发或调试自定义模板提供了现成的断言样例。消息投递流程与鉴权从源码结构看完整调用链如下Sonarr 以POST /api/v1/external/sonarr?api_key...stream...发送事件载荷webhook_view(Sonarr, ...)装饰器完成 bot 鉴权与事件类型白名单校验未注册的eventType会被拒绝api_sonarr_webhook依次调用get_topic_for_http_request和get_body_for_http_request得到主题与消息体check_send_webhook_message来自 zerver/lib/webhooks/common.py将消息投递到指定流json_success返回成功响应Sonarr 侧即显示连接测试成功。相关阅读Webhook 消息内容过滤与事件筛选的通用说明参见各集成文档共用的 event-filtering-additional-feature 一节引用内容Webhook URL 的完整格式规范见 webhooks-url-specification若你使用同生态的 Radarr电影自动化工具其集成位于 zerver/webhooks/radarr配置思路与 Sonarr 完全一致更多 Zulip 入站 Webhook 集成列表可参考 zerver/webhooks 目录以及集成的统一注册入口 zerver/lib/integrations.py。至此你的 Sonarr 事件流便与 Zulip 团队聊天打通追剧进度、画质升级、索引器健康告警都会以清晰的主题组织方式实时送达无需再频繁切换控制台查看 Sonarr 状态。【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考