企业官网建设流程全解析

Zulip Pingdom 集成指南：uptime 状态变化实时通知到团队频道

【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulip

本篇技术指南介绍如何将 Zulip 与 Pingdom 集成，实现网站与服务的 uptime 状态变化（如 HTTP、SMTP、IMAP 检查从 UP 变为 DOWN）实时推送到 Zulip 团队频道，并讲解消息渲染逻辑、支持的事件类型与底层源码实现。读完本文，你将掌握 Pingdom 集成的完整配置流程、Webhook 消息格式规范，以及如何在 Zulip 中过滤和整理来自 Pingdom 的告警事件。

一、Pingdom 集成能做什么

Zulip 官方内置了 Pingdom 集成（集成文档位于 zerver/webhooks/pingdom/doc.md），它可以：

• 订阅 Pingdom 仪表盘上的uptime 状态变化事件；
• 将每一次状态变更（如服务从正常变为故障、从故障恢复）以结构化消息形式发送到指定的 Zulip 频道；
• 消息中自动携带服务主机名、检查类型、前后状态，并在故障（DOWN）时附带故障描述，帮助团队第一时间定位问题。

该集成属于 Zulip 庞大的 Incoming webhook 集成体系 之一，服务端处理逻辑位于 zerver/webhooks/pingdom/view.py，配套测试见 zerver/webhooks/pingdom/tests.py。

二、配置步骤：从创建机器人到连接 Pingdom 检查

1. 创建 Incoming webhook 机器人

在 Zulip 中打开设置 → 你的机器人（Your bots）→ 添加机器人，参考 帮助文档：添加一个机器人或集成：

• 机器人名称可命名为Pingdom；
• 机器人类型（Bot type）必须选择Incoming webhook，这样 Zulip 才会为该机器人生成专用的 Webhook URL。

对应的模板说明位于 templates/zerver/integrations/include/create-an-incoming-webhook.md。

2. 生成集成 URL

确定希望 Pingdom 通知发往的频道（例如# pingdom），随后参考 生成集成 URL，为刚才创建的 Incoming webhook 机器人生成形如：

https://your-zulip-host.example.com/api/v1/external/....?api_key=....&stream=pingdom&topic=...

的集成 URL。该 URL 是后续 Pingdom Webhook 的投递目标。

3. 在 Pingdom 中创建 Webhook 集成

登录 Pingdom 后台：

1. 打开Integrations菜单，点击Add integration；
2. Type选择Webhook；
3. Name填写一个便于识别的名称，例如Zulip；
4. URL粘贴上一步生成的 Zulip 集成 URL；
5. 确保Active开关处于开启状态，然后点击Save integration保存。

4. 将集成连接到具体的检查项

创建新的检查（check）或编辑已有检查时，在该检查的Connect Integrations区域中，开启上一步创建的Zulip集成。这样，该检查的每一次状态变化都会触发 Webhook 并推送至 Zulip 频道。

5. 验证集成

配置完成后，当检查状态发生切换时，Zulip 频道中会收到类似下图的告警消息：

从上图可以看到：Pingdom Bot在# pingdom频道、主题Test check status.下发布了Service someurl.com changed its HTTP status from UP to DOWN:的消息，并附带了故障原因Non-recoverable failure in name resolution（DNS 名称解析失败）。

三、支持的事件类型（检查类型）

Pingdom 集成声明并支持以下检查类型（来自 zerver/webhooks/pingdom/view.py 中的SUPPORTED_CHECK_TYPES）：

这 10 种类型共同构成ALL_EVENT_TYPES，并由@webhook_view("Pingdom", all_event_types=ALL_EVENT_TYPES)注册为集成支持的完整事件集合。当收到的事件类型不在该列表内时，服务端会抛出UnsupportedWebhookEventTypeError并拒绝处理。

四、消息格式与渲染逻辑

Pingdom 集成处理入口为 zerver/webhooks/pingdom/view.py 中的api_pingdom_webhook：

1. 从请求 JSON 中提取check_type字段；
2. 若类型受支持，则根据 payload 生成主题（topic）与消息正文；
3. 调用check_send_webhook_message发送消息并返回成功响应。

主题（Topic）命名规则

主题模板为：

{name} status.

其中{name}取自 payload 的check_name字段。例如测试中使用的Test check、SMTP check、IMAP check分别生成主题Test check status.、SMTP check status.、IMAP check status.。

消息正文

正文模板为：

Service {service_url} changed its {type} status from {previous_state} to {current_state}:

其中：

• service_url取自check_params.hostname（即被监控服务的主机名）；
• type为检查类型（如HTTP、SMTP）；
• previous_state/current_state为状态切换的起点与终点。

特殊逻辑：当状态从UP变为DOWN时，消息末尾会追加故障描述块：

``` quote {long_description}

当状态为其他切换方向（如 `DOWN` 恢复为 `UP`）时，不附加描述块，并将句子结尾的冒号改为句号。 ### 渲染示例 结合 [zerver/webhooks/pingdom/tests.py](https://link.gitcode.com/i/6c6e427da32a08fab522e2373a263ff7) 中的断言，可以得到四种典型输出： - HTTP 检查 UP → DOWN（fixture [http_up_to_down.json](https://link.gitcode.com/i/2c556169a6a5648c51ecfa2979f47e2a)）： > `Service someurl.com changed its HTTP status from UP to DOWN:` 后附 `Non-recoverable failure in name resolution` - SMTP 检查 UP → DOWN（fixture [smtp_up_to_down.json](https://link.gitcode.com/i/fe68b535e90ab7840db80544a78d9d8d)）： > `Service smtp.someurl.com changed its SMTP status from UP to DOWN:` 后附 `Connection refused` - IMAP 检查 UP → DOWN（fixture [imap_up_to_down.json](https://link.gitcode.com/i/61efcd3a69c62535f9e6f677b67c57a3)）： > `Service imap.someurl.com changed its IMAP status from UP to DOWN:` 后附 `Invalid hostname, address or socket` - IMAP 检查 DOWN → UP（fixture [imap_down_to_up.json](https://link.gitcode.com/i/ade3604b6359a82f462e72175eae2343)）： > `Service imap.someurl.com changed its IMAP status from DOWN to UP.` ## 五、Pingdom Webhook 请求负载解析 Pingdom 的 Webhook 请求为 JSON 格式。以 [http_up_to_down.json](https://link.gitcode.com/i/2c556169a6a5648c51ecfa2979f47e2a) 为例，集成实际消费的字段包括： | 字段 | 含义 | 在集成中的用途 | | --- | --- | --- | | `check_id` | 检查项 ID | 标识检查 | | `check_name` | 检查项名称 | 生成消息主题 | | `check_type` | 检查类型（HTTP/SMTP/IMAP 等） | 判断是否受支持、写入正文 | | `check_params.hostname` | 被监控主机名 | 写入正文 `service_url` | | `previous_state` | 上一状态（UP/DOWN） | 写入正文 | | `current_state` | 当前状态（UP/DOWN） | 写入正文，并决定是否附带描述块 | | `long_description` | 故障详细描述 | DOWN 时以 quote 块展示 | | `description` | 故障摘要 | 当前未在消息中使用 | | `first_probe` / `second_probe` | 探测节点信息 | 当前未在消息中使用 | 所有字段通过 `WildValue` 与 `tame(check_string)` 进行类型校验后读取，保证消息构建的安全性。 ## 六、事件过滤（Filtering incoming events） 与其他 Zulip 内置集成一样，Pingdom 集成支持按事件类型进行过滤，见 [templates/zerver/integrations/include/event-filtering-additional-feature.md](https://link.gitcode.com/i/d3d31ed8fac8d7fd82be0b59023d1c5d)。 你可以在 Zulip 的 Webhook 设置中通过 **只关注指定事件（Only events）** 与 **排除指定事件（Exclude events）** 两种模式，来控制哪些检查类型（`HTTP`、`HTTP_CUSTOM`、`HTTPS`、`SMTP`、`POP3`、`IMAP`、`PING`、`DNS`、`UDP`、`PORT_TCP`）的告警进入频道。例如，只希望接收 HTTP 与 HTTPS 的故障告警，可将事件过滤配置为仅保留 `HTTP`、`HTTPS`，从而避免邮件、端口类检查的通知刷屏。 ## 七、Webhook URL 规范 关于 Incoming webhook URL 的完整格式规范（路径结构、`api_key`、`stream`、`topic` 等参数含义），参见 [templates/zerver/integrations/include/webhooks-url-specification.md](https://link.gitcode.com/i/d1db8a2dce08b1b88ea7a7c04f56b216) 引用的 Webhook URL 规范文档，也可查阅仓库中 [zerver/webhooks](https://link.gitcode.com/i/636959ad6d0d73b01a4fb3a5f398111c) 目录下其他集成的 `doc.md` 了解一致的使用模式。 ## 八、测试与验证 仓库为 Pingdom 集成提供了完整的单元测试（[zerver/webhooks/pingdom/tests.py](https://link.gitcode.com/i/6c6e427da32a08fab522e2373a263ff7)），覆盖了： - HTTP、SMTP、IMAP 三种检查类型从 UP 到 DOWN 的告警消息； - IMAP 检查从 DOWN 恢复到 UP 的消息（验证无描述块、句尾为句号的分支）。 测试使用各 [fixtures](https://link.gitcode.com/i/2782c9a9d3adbeecc50982fc45d7c0c6) 中的真实负载断言最终发送的正文，如果你需要二次开发或排查消息格式问题，这些测试是最直接的参考依据。 ## 总结 至此，你已经完成了 Zulip Pingdom 集成的全流程：创建 Incoming webhook 机器人 → 生成集成 URL → 在 Pingdom 中配置 Webhook 集成并连接到检查项 → 在 Zulip 频道中接收带状态切换信息与故障描述的告警。结合 [zerver/webhooks/pingdom/view.py](https://link.gitcode.com/i/6a957c4f2b4a7fa6f927005d8b617eb8) 中的渲染逻辑，你还可以进一步定制主题与消息格式，让监控告警与团队协作真正融为一体。

【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulip