Alertmanager 飞书告警适配器使用指南

1. 架构概述

本文档介绍如何在 Rancher Monitoring（基于 Prometheus Operator）环境下，部署 alertmanager-feishu-adapter 实现将 Alertmanager 告警推送到飞书群，并可选集成 AI 大模型进行告警初判。

1.1 数据流

┌─────────────┐     ┌────────────────┐     ┌──────────────────────────┐     ┌──────────┐
│  Prometheus  │────▶│ Alertmanager   │────▶│ alertmanager-feishu-     │────▶│ 飞书机器人 │
│  (告警规则)   │     │ (路由/分组/抑制) │     │ adapter (HTTP Webhook)   │     │ Webhook  │
└─────────────┘     └────────────────┘     └────────────┬─────────────┘     └──────────┘
                                                        │ (可选)
                                                        ▼
                                                  ┌──────────┐
                                                  │ AI 大模型  │
                                                  │ (通义千问)  │
                                                  └──────────┘
                                                        │
                                                        ▼
                                                  ┌──────────┐
                                                  │ 飞书群    │
                                                  │ AI初判卡片 │
                                                  └──────────┘

1.2 核心原理

组件	职责
Prometheus	根据 `PrometheusRule` 中定义的告警规则评估指标，触发告警发送给 Alertmanager
Alertmanager	对告警进行分组（group_by）、抑制（inhibit）、去重、路由（route），将告警转发到接收器（receiver）
alertmanager-feishu-adapter	作为 HTTP Webhook 接收 Alertmanager 报文，转换为飞书 Interactive Card 格式，POST 到飞书机器人 Webhook
AI 大模型（可选）	对 critical 级别告警，adapter 异步调用大模型 API，自动收集 Pod 状态/事件上下文，生成初判分析推送到飞书

1.3 关键设计

适配器是纯格式转换层：Alertmanager 原生不支持飞书卡片消息格式，adapter 充当翻译角色
无状态、轻量：Python 3.12-alpine 镜像，内存限制 96Mi，无需持久化
AI 初判异步执行：不阻塞 Alertmanager 响应，独立线程调用大模型
冷却机制：同一告警（按 alertname+namespace+instance）2 小时内不重复 AI 分析
RBAC 只读：AI 上下文收集仅需 pods/nodes/events 的 get/list 权限

2. 部署架构详解

2.1 资源清单

在 cattle-monitoring-system 命名空间中部署以下资源：

资源类型	名称	作用
`Deployment`	`alertmanager-feishu-adapter`	运行 Python HTTP 适配器
`Service`	`alertmanager-feishu-adapter`	ClusterIP 暴露 8080 端口
`ConfigMap`	`alertmanager-feishu-adapter`	挂载 `adapter.py` 脚本
`Secret`	`alertmanager-feishu`	存储飞书 Webhook URL
`Secret`	`alertmanager-ai`（可选）	存储 AI 大模型 API Key 和 Base URL
`ServiceAccount`	`alertmanager-feishu-adapter`	Pod 身份（AI 上下文收集使用）
`ClusterRole`	`alertmanager-feishu-adapter-readonly`	只读 pods/nodes/events 权限
`ClusterRoleBinding`	`alertmanager-feishu-adapter-readonly`	绑定 SA 与 ClusterRole

2.2 adapter.py 核心逻辑

POST / (来自 Alertmanager)
  │
  ├── 解析 Alertmanager JSON 报文
  ├── build_card() → 构建飞书 Interactive Card
  │     ├── 根据 status 选择卡片颜色（firing=红 / resolved=绿）
  │     ├── 遍历 alerts，提取 labels/annotations 构建字段
  │     │     ├── severity → 🔴🟠🔵⚪ 图标
  │     │     ├── alertname, namespace, pod/instance/node
  │     │     ├── summary, description
  │     │     └── startsAt → CST 时间格式化
  │     └── 单张卡片最多展示 5 条告警
  ├── POST 卡片到飞书 Webhook URL
  └── （可选）AI 初判
        ├── 筛选 firing + severity ∈ AI_ANALYZE_SEV
        ├── 检查冷却（同一告警 2h 内不重复）
        ├── collect_context() → 通过 K8s API 收集 Pod 状态/事件
        ├── ai_chat() → 调用大模型生成分析
        └── 异步推送 AI 初判卡片到飞书

GET / → 健康检查，返回 200 ok

2.3 环境变量说明

变量名	来源	说明
`FEISHU_URL`	Secret `alertmanager-feishu` key `webhook-url`	必填，飞书机器人 Webhook 地址
`AI_KEY`	Secret `alertmanager-ai` key `api-key`	可选，AI 大模型 API Key
`AI_BASE`	Secret `alertmanager-ai` key `base-url`	可选，AI API 基础 URL，默认通义千问
`AI_MODEL`	Deployment env	AI 模型名，默认 `qwen-plus`
`AI_ANALYZE_SEV`	Deployment env	触发 AI 分析的级别，逗号分隔，默认 `critical`
`AI_ANALYZE_COOLDOWN`	Deployment env	AI 分析冷却时间（秒），默认 `7200`（2小时）

3. 使用 Rancher Monitoring 定制飞书告警

Step 1: 部署 alertmanager-feishu-adapter

完整部署 YAML 参见 examples/feishu-adapter-deploy.yaml。

1.1 创建飞书机器人

在飞书群中点击 设置 → 群机器人 → 添加机器人 → 自定义机器人
记录 Webhook 地址，格式如：https://open.feishu.cn/open-apis/bot/v2/hook/<token>

1.2 创建 Secret 存储飞书 Webhook

yaml

apiVersion: v1
kind: Secret
metadata:
  name: alertmanager-feishu
  namespace: cattle-monitoring-system
stringData:
  webhook-url: "https://open.feishu.cn/open-apis/bot/v2/hook/<your-token>"
type: Opaque

1.3（可选）创建 AI 大模型 Secret

如需 AI 值班初判功能，创建以下 Secret：

yaml

apiVersion: v1
kind: Secret
metadata:
  name: alertmanager-ai
  namespace: cattle-monitoring-system
data:
  api-key: <base64-encoded-api-key>
  base-url: <base64-encoded-base-url>   # 默认通义千问

1.4 部署 adapter

bash

kubectl apply -f examples/feishu-adapter-deploy.yaml

验证部署状态：

bash

kubectl get pods -n cattle-monitoring-system -l app=alertmanager-feishu-adapter
kubectl logs -n cattle-monitoring-system -l app=alertmanager-feishu-adapter

Step 2: 配置 Alertmanager 路由

Alertmanager 配置存储在 Secret alertmanager-rancher-monitoring-alertmanager 中。

⚠️ 重要：Rancher Monitoring 的 Alertmanager 配置由 Helm values 管理。修改方式有两种：
方式 A（推荐）：通过 Rancher UI → Cluster → Apps → rancher-monitoring → Upgrade → 编辑 Alertmanager 配置
方式 B：直接修改 Secret alertmanager-rancher-monitoring-alertmanager（Helm upgrade 可能覆盖）

完整配置示例参见 examples/alertmanager-config.yaml。

核心路由配置：

yaml

receivers:
  - name: "null"
  - name: feishu
    webhook_configs:
      - url: http://alertmanager-feishu-adapter.cattle-monitoring-system.svc.cluster.local:8080/
        send_resolved: true

route:
  receiver: feishu
  group_by: [alertname, namespace, severity]
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 12h
  routes:
    - matchers: [alertname = "Watchdog"]
      receiver: "null"
    - matchers: [severity =~ "info|none"]
      receiver: "null"
    - matchers: [severity = critical]
      receiver: feishu
      repeat_interval: 2h
    - matchers: [severity = warning]
      receiver: feishu
      repeat_interval: 6h

更新 Secret 方式（方式 B）：

bash

# 1. 将 alertmanager.yaml 内容 base64 编码
ALERTMANAGER_YAML=$(cat your-alertmanager-config.yaml | base64 -w0)

# 2. 更新 Secret
kubectl patch secret alertmanager-rancher-monitoring-alertmanager \
  -n cattle-monitoring-system \
  -p "{\"data\":{\"alertmanager.yaml\":\"$ALERTMANAGER_YAML\"}}"

# 3. Alertmanager 会自动 reload 配置（Prometheus Operator 监听 Secret 变更）

Step 3: 创建自定义告警规则（PrometheusRule）

使用 PrometheusRule CRD 定义告警规则，Prometheus Operator 会自动将其加载到 Prometheus 中。

完整示例参见 examples/custom-app-alert-rules.yaml。

关键要求：

labels.severity 必须设置，且值为 critical 或 warning（对应路由规则）
annotations.summary 和 annotations.description 会被 adapter 提取展示在飞书卡片中
expr 使用 PromQL 定义告警条件
for 定义持续时间阈值

示例：应用 Pod 重启告警

yaml

apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: my-app-alerts
  namespace: cattle-monitoring-system
  labels:
    app: rancher-monitoring
    release: rancher-monitoring     # 必须匹配 Prometheus 的 ruleSelector
spec:
  groups:
    - name: my-app.rules
      rules:
        - alert: PodCrashLooping
          expr: |
            increase(kube_pod_container_status_restarts_total{
              namespace=~"my-app-ns"
            }[1h]) > 5
          for: 15m
          labels:
            severity: critical
          annotations:
            summary: "Pod 频繁重启: {{ $labels.namespace }}/{{ $labels.pod }}"
            description: "过去 1 小时内容器 {{ $labels.container }} 重启 {{ $value }} 次"

Step 4: 配置指标采集（ServiceMonitor / PodMonitor）

如果你的应用暴露了自定义 metrics 端口，需要创建 ServiceMonitor 让 Prometheus 抓取：

yaml

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: my-app-metrics
  namespace: cattle-monitoring-system
  labels:
    release: rancher-monitoring     # 必须匹配 Prometheus 的 serviceMonitorSelector
spec:
  namespaceSelector:
    matchNames:
      - my-app-ns
  selector:
    matchLabels:
      app: my-app
  endpoints:
    - port: metrics               # Service 中定义的端口名
      interval: 30s
      path: /metrics

Step 5: 验证与测试

5.1 验证 PrometheusRule 已加载

bash

# 检查 PrometheusRule 是否被 Prometheus Operator 验证通过
kubectl get prometheusrule my-app-alerts -n cattle-monitoring-system -o yaml | grep validated
# 应看到: prometheus-operator-validated: "true"

5.2 在 Prometheus UI 中验证规则

bash

kubectl port-forward -n cattle-monitoring-system \
  svc/rancher-monitoring-prometheus 9090:9090
# 浏览器打开 http://localhost:9090/rules 查看告警规则

5.3 模拟告警测试

使用 curl 直接向 adapter 发送模拟告警报文，验证飞书卡片推送：

bash

curl -X POST http://alertmanager-feishu-adapter.cattle-monitoring-system.svc.cluster.local:8080/ \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "firing",
    "alerts": [{
      "status": "firing",
      "labels": {
        "alertname": "TestAlert",
        "severity": "critical",
        "namespace": "default",
        "pod": "test-pod-abc123"
      },
      "annotations": {
        "summary": "这是一条测试告警",
        "description": "用于验证飞书适配器是否正常工作"
      },
      "startsAt": "2026-08-21T10:00:00Z"
    }]
  }'

完整测试脚本参见 examples/test-alert-curl.sh。

4. 完整案例：为自定义应用配置飞书告警

以下案例借鉴集群上已有的 ebpf-apm-red PrometheusRule，展示如何为一个应用从零配置飞书告警。

4.1 场景描述

假设你有一个 Web 应用部署在 my-web-app 命名空间，需要监控以下指标：

HTTP 5xx 错误率
P99 延迟
Pod 重启次数
应用可用性

4.2 完整配置文件

参见 examples/custom-app-alert-rules.yaml 中的 my-web-app-apm 规则组。

4.3 集群上已有的实际案例

集群 192.168.122.31 上 observability 命名空间中的 ebpf-apm-red PrometheusRule 是一个真实运行的案例：

yaml

# 已部署在集群中的告警规则（observability/ebpf-apm-red）
spec:
  groups:
    - name: apm.red
      rules:
        - alert: AppHighErrorRate
          expr: |
            sum by (k8s_namespace_name, service_name) (
              rate(http_server_request_duration_seconds_count{
                http_response_status_code=~"5.."
              }[5m])
            )
            /
            sum by (k8s_namespace_name, service_name) (
              rate(http_server_request_duration_seconds_count[5m])
            ) > 0.02
          for: 10m
          labels:
            severity: warning
            team: sre
          annotations:
            summary: "应用 5xx 错误率过高:{{ $labels.k8s_namespace_name }}/{{ $labels.service_name }}"
            description: "过去 10 分钟 5xx 比例 {{ $value | humanizePercentage }},阈值 2%"

        - alert: AppHighLatencyP99
          expr: |
            histogram_quantile(0.99,
              sum by (k8s_namespace_name, service_name, le) (
                rate(http_server_request_duration_seconds_bucket[5m])
              )
            ) > 1
          for: 15m
          labels:
            severity: warning
            team: sre
          annotations:
            summary: "应用 P99 延迟过高:{{ $labels.k8s_namespace_name }}/{{ $labels.service_name }}"
            description: "P99 延迟 {{ $value }}s,阈值 1s"

    - name: ebpf.components
      rules:
        - alert: BeylaDown
          expr: absent(up{job=~".*beyla.*"} == 1)
          for: 10m
          labels:
            severity: critical
            team: sre
          annotations:
            summary: "Beyla 抓取目标全部消失"
            description: "eBPF 自动埋点 DaemonSet 可能整体异常,应用层指标/追踪中断"

        - alert: TempoDown
          expr: up{job=~".*tempo.*"} == 0
          for: 5m
          labels:
            severity: critical
            team: sre
          annotations:
            summary: "Tempo 不可用"
            description: "分布式追踪后端异常,trace 写入与查询中断"

4.4 告警路由说明

当上述告警触发时，根据 Alertmanager 路由配置：

告警	severity	路由目标	重复间隔
`AppHighErrorRate`	warning	feishu	6h
`AppHighLatencyP99`	warning	feishu	6h
`BeylaDown`	critical	feishu + AI 初判	2h
`TempoDown`	critical	feishu + AI 初判	2h

warning 级别：飞书群收到橙色卡片 🟠
critical 级别：飞书群收到红色卡片 🔴，随后收到 AI 初判 turquoise 卡片 🤖

5. 常见问题与排障

5.1 飞书群未收到告警

bash

# 1. 检查 adapter Pod 是否运行
kubectl get pods -n cattle-monitoring-system -l app=alertmanager-feishu-adapter

# 2. 查看 adapter 日志
kubectl logs -n cattle-monitoring-system -l app=alertmanager-feishu-adapter --tail=50

# 3. 检查 Alertmanager 日志
kubectl logs -n cattle-monitoring-system \
  alertmanager-rancher-monitoring-alertmanager-0 -c alertmanager --tail=50

# 4. 检查 Alertmanager 配置是否生效
kubectl get secret alertmanager-rancher-monitoring-alertmanager \
  -n cattle-monitoring-system \
  -o jsonpath='{.data.alertmanager\.yaml}' | base64 -d

5.2 PrometheusRule 未被 Prometheus 加载

bash

# 检查 PrometheusRule 是否带有正确的 label
# Prometheus 的 ruleSelector 通常匹配 release: rancher-monitoring
kubectl get prometheusrule my-rule -n cattle-monitoring-system \
  -o yaml | grep -A5 labels

# 检查 Prometheus Operator 是否已验证
kubectl get prometheusrule my-rule -n cattle-monitoring-system \
  -o yaml | grep validated

5.3 Alertmanager 配置被 Helm upgrade 覆盖

Rancher Monitoring 通过 Helm 管理，直接修改 Secret 可能在下次 helm upgrade 时被覆盖。推荐通过 Rancher UI 或 Helm values 持久化配置：

bash

# 查看当前 Helm values
helm get values rancher-monitoring -n cattle-monitoring-system

# 通过 values 覆盖 Alertmanager 配置
helm upgrade rancher-monitoring rancher-charts/rancher-monitoring \
  -n cattle-monitoring-system \
  --reuse-values \
  --set alertmanager.alertmanagerSpec.configSecret=your-custom-secret

5.4 AI 初判未触发

确认以下条件全部满足：

Secret alertmanager-ai 已创建且 api-key 有效
Deployment 环境变量 AI_KEY 正确引用了 Secret
告警 severity 在 AI_ANALYZE_SEV 范围内（默认仅 critical）
同一告警未在冷却期内（默认 2h）

bash

# 查看 AI 初判日志
kubectl logs -n cattle-monitoring-system \
  -l app=alertmanager-feishu-adapter | grep "AI 初判"

6. 文件索引

文件	说明
`alertmanager-feishu-adapter-guide.md`	本文档
`examples/feishu-adapter-deploy.yaml`	adapter 完整部署 YAML（含所有资源）
`examples/custom-app-alert-rules.yaml`	自定义应用 PrometheusRule 告警规则示例
`examples/alertmanager-config.yaml`	Alertmanager 配置 Secret 示例
`examples/test-alert-curl.sh`	测试脚本（curl 模拟告警）

Alertmanager 飞书告警适配器使用指南 ​

1. 架构概述 ​

1.1 数据流 ​

1.2 核心原理 ​

1.3 关键设计 ​

2. 部署架构详解 ​

2.1 资源清单 ​

2.2 adapter.py 核心逻辑 ​

2.3 环境变量说明 ​

3. 使用 Rancher Monitoring 定制飞书告警 ​

Step 1: 部署 alertmanager-feishu-adapter ​

Step 2: 配置 Alertmanager 路由 ​

Step 3: 创建自定义告警规则（PrometheusRule） ​

Step 4: 配置指标采集（ServiceMonitor / PodMonitor） ​

Step 5: 验证与测试 ​

4. 完整案例：为自定义应用配置飞书告警 ​

4.1 场景描述 ​

4.2 完整配置文件 ​

4.3 集群上已有的实际案例 ​

4.4 告警路由说明 ​

5. 常见问题与排障 ​

5.1 飞书群未收到告警 ​

5.2 PrometheusRule 未被 Prometheus 加载 ​

5.3 Alertmanager 配置被 Helm upgrade 覆盖 ​

5.4 AI 初判未触发 ​

6. 文件索引 ​

Alertmanager 飞书告警适配器使用指南

1. 架构概述

1.1 数据流

1.2 核心原理

1.3 关键设计

2. 部署架构详解

2.1 资源清单

2.2 adapter.py 核心逻辑

2.3 环境变量说明

3. 使用 Rancher Monitoring 定制飞书告警

Step 1: 部署 alertmanager-feishu-adapter

Step 2: 配置 Alertmanager 路由

Step 3: 创建自定义告警规则（PrometheusRule）

Step 4: 配置指标采集（ServiceMonitor / PodMonitor）

Step 5: 验证与测试

4. 完整案例：为自定义应用配置飞书告警

4.1 场景描述

4.2 完整配置文件

4.3 集群上已有的实际案例

4.4 告警路由说明

5. 常见问题与排障

5.1 飞书群未收到告警

5.2 PrometheusRule 未被 Prometheus 加载

5.3 Alertmanager 配置被 Helm upgrade 覆盖

5.4 AI 初判未触发

6. 文件索引