keyfil/草稿/20250226-夜莺整合GrafanaOnCall.md

以下是将 Nightingale 与 Grafana OnCall 整合，构建完整 监控告警 + OnCall 值班管理 系统的分步方案：

---

一、整合架构

graph LR
    A[Nightingale] -->|Webhook 告警推送| B[Grafana OnCall]
    B -->|通知值班人员| C[钉钉/企业微信/短信]
    B -->|告警状态同步| A

---

二、核心步骤

步骤 1：配置 Grafana OnCall 告警接收通道

1. 创建 OnCall Webhook 集成：

   • 进入 Grafana OnCall → Integrations → New Integration → 选择 Webhook。
   • 记录生成的 Webhook URL（如 https://oncall-api.example.com/integrations/webhook/abc123/）。

2. 配置 Payload 模板（适配 Nightingale 告警格式）：

   {
     "title": "{{ .CommonLabels.alertname }}",
     "message": "{{ .CommonAnnotations.summary }}",
     "status": "{{ .Status }}",
     "severity": "{{ .CommonLabels.severity }}",
     "fingerprint": "{{ .Fingerprint }}",
     "source": "nightingale"
   }
   

---

步骤 2：配置 Nightingale 告警转发到 Grafana OnCall

1. 在 Nightingale 中创建通知模板：

   • 进入 Nightingale → 告警管理 → 通知模板 → 新建模板。
   • 类型选择 Webhook，URL 填写 Grafana OnCall 的 Webhook URL。

2. 设置告警规则关联 Webhook：

   • 编辑告警规则 → 通知配置 → 选择刚创建的 Webhook 模板。
   • 自定义告警参数映射（确保 alertname、summary 等字段正确传递）。

---

步骤 3：配置 OnCall 排班与通知策略

1. 创建值班表：

   • 进入 Grafana OnCall → Schedules → New Schedule。
   • 设置轮班规则（如 24x7 轮班、工作日/节假日）、时区、交接提醒。

2. 配置通知渠道：

   • Channels → 添加钉钉机器人、企业微信应用、短信网关等。
   • 测试通知是否可达。

3. 设置告警路由规则：

   • Routes → 根据标签（如 severity=critical）将告警路由到不同值班组。
   • 示例：severity=critical → 电话通知；severity=warning → 企业微信群通知。

---

步骤 4：告警状态回传同步（可选）

若需在 Nightingale 中同步 OnCall 处理状态，需开发回调接口：

# 示例：Grafana OnCall → Nightingale 状态同步
@app.route("/oncall-callback", methods=["POST"])
def handle_oncall_callback():
    data = request.json
    alert_id = data.get("fingerprint")
    status = "resolved" if data.get("status") == "ok" else "firing"
    # 调用 Nightingale API 更新告警状态
    requests.patch(
        f"{NIGHTINGALE_URL}/api/v1/alerts/{alert_id}",
        json={"status": status},
        headers={"Authorization": "Bearer {API_KEY}"}
    )
    return jsonify({"status": "success"})

---

三、关键配置说明

组件	配置项	作用
Nightingale	Webhook 模板	将告警格式转换为 OnCall 兼容的 JSON 结构
Grafana OnCall	Payload 模板	解析 Nightingale 告警字段（标题、描述、状态）
Grafana OnCall	告警路由规则	根据标签（如 severity）定向通知值班人员
Nightingale	回调接口（可选）	同步 OnCall 处理状态，保持告警状态一致性

---

四、验证与调试

1. 触发测试告警：

   # 使用 Nightingale 的测试告警功能
   curl -X POST http://nightingale:17000/api/v1/alerts \
        -H "Content-Type: application/json" \
        -d '{"labels":{"alertname":"TestAlert","severity":"critical"},"annotations":{"summary":"Integration test"}}'
   

2. 检查 OnCall 告警流水：

   • 进入 Grafana OnCall → Alert Groups，确认测试告警已接收并分配。

3. 验证通知渠道：

   • 确保值班人员收到钉钉/短信通知，且内容包含告警详情。

---

五、性能优化建议

1. 告警聚合：
   在 Nightingale 中设置合理的告警分组规则，避免 OnCall 被高频告警淹没。

2. 分级通知：

   • 使用 OnCall 的 Escalation Policies，配置多级通知（如 5 分钟未响应则通知上级）。

3. 去重与静默：

   • 利用 OnCall 的 Alert Manager 功能，对重复告警自动合并或静默。

---

六、故障排查

现象	可能原因	解决方案
OnCall 未收到告警	Webhook URL 配置错误	检查 Nightingale 的 Webhook 地址和网络连通性
告警字段缺失	Payload 模板不匹配	调整 OnCall 的 Payload 模板匹配字段
通知延迟	渠道限速或网络问题	检查钉钉/企业微信的 API 调用频率限制

---

通过以上方案，可实现 Nightingale 告警生成 → Grafana OnCall 值班管理 的全链路自动化，显著提升运维响应效率。