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

---

### **一、整合架构**

```mermaid
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 告警格式）：
   ```json
   {
     "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 处理状态，需开发回调接口：

```python
# 示例：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. **触发测试告警**：
   ```bash
   # 使用 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 值班管理** 的全链路自动化，显著提升运维响应效率。