Hook 与推送集成

v0.4.0 引入告警自动触发分析和多目标推送通知

---

概述

Hook 与推送系统实现了完全自动化的故障响应流程：

1. Grafana/PagerDuty 触发告警 → Webhook 到达 Hook 服务器
2. 去重引擎 在 TTL 窗口内合并重复告警
3. 分析 自动在去重后的告警上触发
4. 推送调度器 并行发送结果到所有已配置的目标

告警 → Hook 服务器 → 去重 → 分析 → 推送（飞书/Slack/JIRA）

---

Hook 服务器

Hook 服务器是一个轻量级 HTTP 服务器，接收告警 Webhook 并触发分析。

启动服务器

# CLI
npx kafka-log-analyze hooks --port 3100

# 或通过 MCP Tool
{ "tool": "start_hooks", "input": { "port": 3100 } }

端点

方法	路径	说明
POST	/hooks/grafana	接收 Grafana 统一/遗留告警 Webhook
POST	/hooks/pagerduty	接收 PagerDuty Events API v2 告警
GET	/hooks/health	健康检查（{ "status": "ok" }）

MCP 工具

工具	说明
start_hooks	启动 Hook 服务器
stop_hooks	停止 Hook 服务器
list_hooks	查看服务器状态和去重统计

---

去重引擎

去重引擎防止告警风暴触发冗余分析。

• 指纹识别：告警按来源、标签和注解生成 fingerprint
• TTL 窗口：HOOK_DEDUP_WINDOW_MS（默认：300000 / 5 分钟）— 此窗口内的重复告警将被合并
• 合并计数：HOOK_MAX_MERGE_COUNT（默认：10）— 每个 fingerprint 最大合并告警数，超过后强制刷新

当多个告警在 TTL 窗口内共享 fingerprint 时，它们将合并为单次分析触发，而非逐个处理。

---

推送目标

结果并行推送到所有已配置的推送目标。

飞书

以交互卡片消息形式推送分析结果到飞书群。

配置：

• FEISHU_WEBHOOK_URL — 飞书自定义机器人 Webhook 地址

设置步骤：

1. 在飞书群中添加"自定义机器人"集成
2. 复制 Webhook 地址到 FEISHU_WEBHOOK_URL
3. 测试：npx kafka-log-analyze push-test --target feishu

Slack

以 Block Kit 消息格式推送分析结果到 Slack 频道。

配置：

• SLACK_WEBHOOK_URL — Slack Incoming Webhook 地址

设置步骤：

1. 创建 Slack App 并启用 Incoming Webhooks
2. 安装到工作区并复制 Webhook 地址
3. 设置 SLACK_WEBHOOK_URL
4. 测试：npx kafka-log-analyze push-test --target slack

JIRA

自动根据分析结果创建 JIRA Issue，含优先级映射。

配置：

• JIRA_URL — JIRA 基础地址（如 https://your-domain.atlassian.net）
• JIRA_TOKEN — JIRA API 令牌
• JIRA_PROJECT_KEY — JIRA 项目 Key（如 KAFKA）

优先级映射：

分析优先级	JIRA 优先级
P0 (严重)	Highest
P1 (高)	High
P2 (中)	Medium
P3 (低)	Low

设置步骤：

1. 在 Atlassian 账户设置中创建 API 令牌
2. 设置三个 JIRA_* 环境变量
3. 测试：npx kafka-log-analyze push-test --target all

推送测试

# 测试单个目标
npx kafka-log-analyze push-test --target feishu
npx kafka-log-analyze push-test --target slack

# 测试所有已配置的目标
npx kafka-log-analyze push-test --target all

---

Grafana 告警配置

配置 Grafana 将告警发送到 Hook 服务器：

1. 在 Grafana 中，进入 Alerting → Contact points
2. 添加类型为 Webhook 的新 Contact point
3. 设置 URL 为：http://<hook-server-host>:3100/hooks/grafana
4. 保存并测试

支持的载荷格式

• 统一告警（Grafana 9+）：处理 Alerts[] 载荷格式
• 遗留告警（Grafana 8 及以下）：处理经典载荷格式

两种格式自动检测并规范化为 HookPayload。

---

PagerDuty 集成

配置 PagerDuty 发送告警：

1. 在 PagerDuty 中，进入 Services → Integrations
2. 添加 Custom Event Transformation 集成
3. 配置 Webhook POST 到：http://<hook-server-host>:3101/hooks/pagerduty
4. Hook 服务器接受 Events API v2 载荷

---

环境变量汇总

变量	说明	默认值
GRAFANA_WEBHOOK_PORT	Hook 服务器端口	3100
PAGERDUTY_WEBHOOK_PORT	PagerDuty Webhook 端口	3101
FEISHU_WEBHOOK_URL	飞书 Webhook 地址	-
SLACK_WEBHOOK_URL	Slack Webhook 地址	-
JIRA_URL	JIRA 基础地址	-
JIRA_TOKEN	JIRA API 令牌	-
JIRA_PROJECT_KEY	JIRA 项目 Key	-
HOOK_DEDUP_WINDOW_MS	去重 TTL（毫秒）	300000
HOOK_MAX_MERGE_COUNT	最大合并计数	10

---

相关文档

• 命令参考 — CLI 命令参考
• 配置 — 完整环境变量参考
• API 参考 — MCP Tools API 文档