集成指南

了解如何将告警源接入 AlertHub，实现统一的告警通知管理。

接入 AlertHub 只需三步：

在设置页面创建项目，获取项目标识符（slug）和 API 密钥
在通知渠道页面配置告警通知方式（企业微信、邮件、钉钉等）
在路由规则页面创建规则，将告警路由到对应的通知渠道

完成以上配置后，即可通过下方的 Webhook 或心跳监控方式发送告警。

概述

路由规则决定了告警通过哪些通知渠道发送。一条告警到达后，处理流水线如下：

告警接收 → 静默检查 → 路由匹配 → 分组归并 → 重复抑制 → 通知发送

系统按优先级从高到低依次匹配路由规则，第一个匹配的规则生效，后续规则不再评估。

字段说明

字段	类型	默认值	说明
name	string	—	规则名称，用于标识和管理
priority	number	0	数值越大优先级越高，优先匹配
matchLabels	object	—	标签匹配条件，所有条件取 AND 关系
severityIn	string[]	[]	严重级别过滤，空数组匹配所有级别
channelIds	string[]	—	通知渠道 ID 列表，命中后向这些渠道发送通知
groupBy	string[]	[]	按指定标签键对告警分组
repeatInterval	number	3600	同一分组重复通知的最小间隔（秒），0 表示不限制
enabled	boolean	true	是否启用，禁用的规则不参与匹配

标签匹配 (matchLabels)

matchLabels 中的每个键值对都必须与告警标签精确匹配，多个条件之间是 AND 关系。

空对象 {} 匹配所有告警（相当于兜底规则）
不支持正则或通配符，仅支持字符串精确匹配
告警中不存在的标签键视为不匹配
特殊键 severity 匹配告警的严重级别字段，而非标签

json// 匹配所有 env=production 且 service=user-api 的告警
{
  "env": "production",
  "service": "user-api"
}

严重级别过滤 (severityIn)

可选的级别过滤器，告警的严重级别必须在列表中才能匹配。可选值：critical、warning、info。

空数组 [] 匹配所有级别
["critical", "warning"] 仅匹配紧急和警告级别

优先级 (priority)

数值越大优先级越高。系统按 priority 从大到小依次检查每条规则，第一个匹配成功的规则即为最终生效的规则，后续规则不再评估。建议为兜底规则设置最低优先级（如 0），为精确匹配规则设置较高优先级（如 10、20）。

告警分组 (groupBy)

groupBy 指定用于分组的标签键列表。相同分组键值的告警归为同一组，共享重复抑制计时器。

空数组 []：所有告警归为同一组
["alertname"]：按告警名称分组，不同名称的告警独立计时
["env", "service"]：按环境和服务分组，每种组合独立计时
告警中缺少指定标签键时，该键值视为空字符串

重复通知抑制 (repeatInterval)

同一分组内的告警在 repeatInterval 时间窗口内只发送一次通知，后续重复告警被静默。

默认 3600 秒（1 小时）
设为 0 表示每条告警都发送通知，不做抑制
恢复通知不受此限制 — 告警恢复（resolved）时总是立即发送通知
分组的首条告警总是立即发送，之后开始计时

实战示例

示例 1：生产环境紧急告警 → 企微 + 邮件，5 分钟抑制

json{
  "name": "生产环境紧急告警",
  "priority": 20,
  "matchLabels": { "env": "production" },
  "severityIn": ["critical"],
  "channelIds": ["<企微渠道ID>", "<邮件渠道ID>"],
  "groupBy": ["alertname", "instance"],
  "repeatInterval": 300
}

示例 2：特定服务的所有告警 → 钉钉，按服务分组

json{
  "name": "用户服务告警",
  "priority": 10,
  "matchLabels": { "service": "user-api" },
  "severityIn": [],
  "channelIds": ["<钉钉渠道ID>"],
  "groupBy": ["alertname"],
  "repeatInterval": 1800
}

示例 3：兜底规则 — 匹配所有未被上述规则命中的告警

json{
  "name": "默认兜底规则",
  "priority": 0,
  "matchLabels": {},
  "severityIn": [],
  "channelIds": ["<默认渠道ID>"],
  "groupBy": ["alertname"],
  "repeatInterval": 3600
}

接口地址

httpPOST /api/receive/webhook/{projectSlug}

将 {projectSlug} 替换为你在设置页面创建的项目标识符。

请求头

Header	值	说明
Content-Type	application/json	必填
X-API-Key	你的项目 API 密钥	必填，在项目设置中获取

请求体字段

字段	类型	必填	说明
title	string	是	告警标题
description	string	否	告警详细描述
severity	string	否	严重级别：`critical` `warning` `info`，默认 warning
status	string	否	告警状态：`firing` `resolved`，默认 firing
labels	object	否	自定义标签，用于路由规则匹配和告警分组

cURL 示例

bashcurl -X POST https://alert.model1235.com/api/receive/webhook/my-app \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "title": "数据库连接异常",
    "description": "MySQL 主库连接数超过阈值 (当前: 450/500)",
    "severity": "critical",
    "status": "firing",
    "labels": {
      "env": "production",
      "service": "user-api",
      "instance": "db-master-01"
    }
  }'

Python 示例

pythonimport requests

requests.post(
    "https://alert.model1235.com/api/receive/webhook/my-app",
    headers={"X-API-Key": "your-api-key"},
    json={
        "title": "磁盘使用率过高",
        "description": "/data 分区使用率 92%",
        "severity": "warning",
        "labels": {"host": "web-server-03"}
    }
)

恢复告警

发送 status: "resolved" 即可标记告警恢复：

bashcurl -X POST https://alert.model1235.com/api/receive/webhook/my-app \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "title": "数据库连接异常",
    "status": "resolved",
    "labels": {
      "env": "production",
      "service": "user-api",
      "instance": "db-master-01"
    }
  }'

心跳监控用于检测服务是否存活。你的服务定期向 AlertHub 发送心跳请求（Ping），如果在预期时间内未收到心跳，AlertHub 将自动触发告警。当服务恢复心跳后，告警会自动恢复。

使用流程

在设置页面的项目中启用心跳监控，使用项目标识符作为 slug
在你的服务中添加定时任务，周期性调用 Ping 接口
如果超过「检测间隔 + 宽限期」未收到心跳，将自动触发 Critical 级别告警
恢复心跳后告警自动解除

Ping 接口

httpPOST /api/heartbeat/{slug}/ping

此接口无需认证，可直接调用。将 {slug} 替换为项目的标识符。

参数说明

参数	默认值	说明
interval	60 秒	预期心跳发送间隔，你的服务应按此频率调用 Ping
gracePeriod	30 秒	超过 interval 后额外的宽限时间，超过后触发告警

例如 interval=60, gracePeriod=30，则超过 90 秒未收到心跳将触发告警。

cURL 示例

bash# 每 60 秒发送一次心跳
curl -X POST https://alert.model1235.com/api/heartbeat/my-service/ping

Crontab 示例

bash# 每分钟发送心跳
* * * * * curl -fsS -o /dev/null https://alert.model1235.com/api/heartbeat/my-service/ping

Node.js 示例

javascript// 每 60 秒发送一次心跳
setInterval(() => {
  fetch("https://alert.model1235.com/api/heartbeat/my-service/ping", {
    method: "POST"
  }).catch(err => console.error("heartbeat ping failed:", err));
}, 60_000);

Python 示例

pythonimport threading, requests

def heartbeat():
    threading.Timer(60, heartbeat).start()
    try:
        requests.post("https://alert.model1235.com/api/heartbeat/my-service/ping")
    except Exception as e:
        print(f"heartbeat ping failed: {e}")

heartbeat()

Docker 健康检查

dockerfileHEALTHCHECK --interval=60s --timeout=5s --retries=1 \
  CMD curl -fsS -o /dev/null https://alert.model1235.com/api/heartbeat/my-service/ping

集成指南

快速开始

路由规则配置

概述

字段说明

标签匹配 (matchLabels)

严重级别过滤 (severityIn)

优先级 (priority)

告警分组 (groupBy)

重复通知抑制 (repeatInterval)

实战示例

Webhook 告警接入

接口地址

请求头

请求体字段

cURL 示例

Python 示例

恢复告警

心跳监控接入

使用流程

Ping 接口

参数说明

cURL 示例

Crontab 示例

Node.js 示例

Python 示例

Docker 健康检查

Prometheus Alertmanager 接入