运维手册

AlertHub 的管理员配置说明。集成接入方（往 AlertHub 发告警的）请看集成指南。

AlertHub 是一个通知中枢，不做服务端路由：告警发往哪些渠道由调用方在 webhook payload 的 channels 字段里直接指定渠道 ID。运维侧的职责是：

在设置页面创建项目，记下 slug 和 apiKey 发给调用方（接入方拿这两个就能发告警）
在通知渠道页面配置通知方式（企业微信 / 钉钉 / 飞书 / 邮件 / 阿里云短信 / 自定义 Webhook / 浏览器推送共 7 种），渠道持有所有密钥，调用方只能拿到脱敏后的渠道 ID / 名称 / 类型
把渠道列表（GET /api/receive/channels/:slug）的访问方式告诉调用方，他们用渠道 ID 填进告警 payload 的 channels 字段
（可选）启用项目的心跳监控，并在设置页为其选择默认通知渠道—— 心跳告警由 AlertHub 自身生成，发往这些渠道

下方各 Section 说明渠道配置语义、心跳通知渠道选择和踩坑点。

在通知渠道页面创建渠道时，config 字段是一段 JSON，结构因 type 而异。下面列出每种渠道的配置字段、如何获取、以及踩坑点。每个渠道有一个稳定的 ID（UUID），调用方在告警 payload 的 channels 里引用它。

企业微信（wecom）

json{
  "webhookUrl": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY"
}

webhookUrl：企业微信群机器人的 webhook 地址。在群聊设置 → 群机器人 → 添加机器人 → 复制 webhook 地址
消息体使用 markdown 类型，自动渲染 # 标题、**加粗**、[链接]() 等
没有签名机制，泄漏后立刻在群里重新添加机器人换 key
每个机器人每分钟最多发 20 条，超过会被禁言 1 小时

钉钉（dingtalk）

json{
  "webhookUrl": "https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN",
  "secret": "SECxxxxxxxx"
}

webhookUrl：钉钉群智能群助手 → 添加机器人 → 自定义 → 复制 webhook 地址
secret：可选，机器人「加签」模式的密钥（以 SEC 开头）。不填则使用「关键词」或「IP 段」模式
钉钉机器人有三种安全设置（加签 / 关键词 / IP 段），任选其一。AlertHub 仅自动实现加签
每分钟最多发 20 条

飞书（feishu）

json{
  "webhookUrl": "https://open.feishu.cn/open-apis/bot/v2/hook/YOUR_TOKEN",
  "secret": "your-sign-secret"
}

webhookUrl：飞书群设置 → 群机器人 → 添加 Custom Bot → 复制 webhook 地址
secret：可选，机器人「签名校验」的密钥
消息以 interactive card 形式发送（带蓝色头部，正文支持 lark_md 语法）
image 类型告警当前不支持嵌入飞书原生图片（需要先调他们的图床 API 拿 image_key），会退化为文本链接

邮件（email）

json{
  "host": "smtp.example.com",
  "port": 465,
  "secure": true,
  "user": "alert@example.com",
  "pass": "YOUR_SMTP_PASSWORD",
  "from": "\"AlertHub\" <alert@example.com>",
  "to": "admin@example.com,oncall@example.com"
}

port + secure 组合： 465+true（隐式 TLS，推荐）；587+false（STARTTLS）；25+false（明文，仅内网）
pass：对于 Gmail/Outlook 等不接受账号密码登录的服务，要使用「应用专用密码」或 SMTP 授权码，不是邮箱密码
to：多个收件人用逗号分隔；也可以填 nodemailer 支持的 "Name <addr>" 格式
邮件正文是 HTML 模板（深色头部 + 内容卡片）。html 类型告警会替换内容区为 source 提供的 HTML，不做 sanitize，请确保 source 是可信的

自定义 Webhook（webhook）

json{
  "url": "https://your-service.com/webhook",
  "method": "POST",
  "headers": { "X-Custom-Token": "abc123" },
  "secret": "your-hmac-secret"
}

method：POST 或 PUT，默认 POST
headers：可选，附加请求头（如鉴权 token）
secret：可选，HMAC-SHA256 密钥。设置后请求会带 X-AlertHub-Signature: sha256=<hex> 头，接收端可以用该 secret 重新计算 hex(hmac-sha256(secret, body)) 验签
请求体是一段固定结构的 JSON，见下：

出站 payload 结构：

json{
  "event": "alert.notification",
  "timestamp": "2026-05-19T19:46:58.123Z",
  "title": "【critical】数据库连接异常",
  "body": "项目: my-app\n来源: webhook\n...",
  "contentType": "text",
  "imageUrl": null,
  "htmlBody": null,
  "markdownBody": null,
  "clickUrl": null,
  "clickSchema": null
}

阿里云短信（sms）

json{
  "accessKeyId": "LTAI5xxxxxxx",
  "accessKeySecret": "xxxxxxxxxxxxxxxx",
  "signName": "你的签名",
  "templateCode": "SMS_123456789",
  "phoneNumbers": "13800138000,13900139000",
  "templateParam": { "title": "默认值会被覆盖" }
}

accessKeyId / accessKeySecret：阿里云 RAM 用户的密钥对，授权 AliyunDysmsFullAccess 即可
signName：短信签名（如「我的公司」），需要在阿里云短信控制台单独申请审核
templateCode：短信模板编号（SMS_xxx 开头），也需要单独申请审核。模板内容形如「告警：${title}」
phoneNumbers：接收号码，多个用英文逗号分隔（不要中文逗号）
templateParam：可选。不填时 AlertHub 默认填入{ title, url? }（url 仅当 clickUrl 存在时加上）。如果你的模板用了 ${title}，会自动生效；用了 ${url} 且告警带 clickUrl 也会自动填入
富内容（image / html / markdown）对 SMS 无效。短信模板是阿里云后台预先审核过的固定字符串，没法塞富内容

浏览器推送（webpush）

json{}

渠道 config 为空对象 —— WebPush 是广播到所有订阅了本服务的浏览器，没有「单渠道单收件人」概念
依赖服务端环境变量：VAPID_PUBLIC_KEY、VAPID_PRIVATE_KEY、VAPID_SUBJECT（mailto: URI）
VAPID 密钥对生成：npx web-push generate-vapid-keys
用户在设置页面点「订阅」按钮，浏览器申请权限后会调用 /api/push/subscribe 注册
点击通知会先跳转到 AlertHub 的告警详情页/alerts/{id}（由 sw.js 处理）；调用方传的 clickUrl / clickSchema 在该详情页面作为二级按钮展示

运维手册

运维侧快速开始

各渠道配置详解