Alertmanager 最佳实践配置部署文档

环境：RKE2 v1.35.6｜rancher-monitoring 109.0.4+up80.9.1-rancher.18（kube-prometheus-stack 系）目标：Alertmanager 通知可用（飞书）+ 路由/分组/抑制最佳实践 + 2 副本 HA 更新：2026-08-01

1. 背景与架构

rancher-monitoring 默认把所有告警路由到 null（不通知）。本次改造：

Prometheus 告警 → Alertmanager ×2（gossip HA）
  → 分组[alertname,namespace,severity] / 抑制(critical>warning>info)
  → 分级重复(2h/6h/12h) / Watchdog·info 降噪
  → webhook receiver → alertmanager-feishu-adapter → 飞书群机器人

飞书自定义机器人要求 msg_type 消息格式，Alertmanager webhook 发的是通用 JSON，因此部署适配器（python stdlib 单文件）做格式转换，与 K8sGPT 飞书适配器同模式。通知以飞书互动卡片呈现：触发红头/恢复绿头标题栏 + 级别/状态/命名空间/时间四栏

摘要/详情 markdown + 底部分组统计注释；单卡片最多展示 5 条告警，超出折叠计数。

AI 值班初判（2026-08-01 新增）：firing + critical 告警触发后，适配器异步用只读 RBAC 自动收集上下文（Pod phase/容器状态/最近 Warning 事件）→ qwen-plus 生成初步分析 → 补推「🤖 AI 值班初判」青绿卡片。同一告警 2h 冷却不重复分析；Key 存 Secret alertmanager-ai （deploy.sh 从 .secrets.env 创建，缺失时自动降级为仅告警卡片）；不收集容器日志原文。

2. 关键设计决策与踩坑记录

配置入口用 helm values 而非手改 secretalertmanager.config values → chart 渲染配置 secret → prometheus-operator 生成 -generated secret → config-reloader 热加载。手改 secret 会在下次升级被覆盖。
必须加 alertmanager.secret.recreateIfExists: true（坑） chart 的 secret 模板带 lookup 保护：secret 已存在时不再重建，只改 values 不生效。开启后 pre-upgrade hook 才重建 secret。
HA 用 gossip 集群而非外部存储alertmanagerSpec.replicas: 2，两个实例 gossip 同步静默/通知状态， Prometheus 双发去重由 Alertmanager 集群协商完成。
watch URL 用集群内 Servicehttp://alertmanager-feishu-adapter.cattle-monitoring-system.svc.cluster.local:8080/，适配器无状态单副本（通知由 Alertmanager 重试兜底，适配器短暂故障最多延迟）。
与 K8sGPT 分工 Alertmanager 管阈值/规则告警（快，秒级），K8sGPT 管 AI 诊断解释（深，分钟级），两者共用飞书群但消息格式可区分（🔥/✅ 告警卡片、🤖 AI 值班初判 vs 🔍 K8sGPT 诊断）。
AI 初判只读最小权限 适配器 SA 的 ClusterRole 只含 pods/nodes/events 的 get/list，刻意不含 pods/log：日志原文更敏感，等切内网 vLLM 模型后再开放（见运维实战 AI Agent 模块路线图）。

3. 路由配置详解（alertmanager-values.yaml）

yaml

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]         # 严重 → 2h 重复
      receiver: feishu
      repeat_interval: 2h
    - matchers: [severity = warning]          # 警告 → 6h 重复
      receiver: feishu
      repeat_interval: 6h

抑制规则保留 rancher 默认（critical 抑制同 ns+alertname 的 warning/info， warning 抑制 info，InfoInhibitor 抑制 info）。

4. 部署步骤

bash

export KUBECONFIG=~/.kube/config-122.31

# 1. 飞书适配器（含 webhook Secret）
kubectl apply -f feishu-adapter.yaml

# 2. 声明式应用配置（叠加现有 values，不动其他组件）
helm upgrade rancher-monitoring rancher-charts/rancher-monitoring \
  --version 109.0.4+up80.9.1-rancher.18 -n cattle-monitoring-system \
  --reuse-values -f alertmanager-values.yaml

# 3. 验证
kubectl -n cattle-monitoring-system get pods -l app.kubernetes.io/name=alertmanager  # 2 副本
kubectl -n cattle-monitoring-system get secret alertmanager-rancher-monitoring-alertmanager \
  -o jsonpath='{.data.alertmanager\.yaml}' | base64 -d | grep -A3 receivers

或一键：./deploy.sh

5. 端到端验证

bash

# 向 Alertmanager API 投递合成告警（在适配器 Pod 内执行，deploy.sh check 已封装）
# 约 40s（group_wait 30s + 发送）后飞书收到 🔥 触发消息，
# 合成告警 endsAt+10m 到期后收到 ✅ 恢复消息
./deploy.sh check

已实测：合成 critical 告警 → Alertmanager（active/feishu 路由）→ 适配器 → 飞书成功，通知日志无重试/错误。

6. 注意事项

Rancher 升级 monitoring 应用可能重置 values：rancher-monitoring 由 Rancher 管理，若后续通过 Rancher UI 升级/改配，需确认 alertmanager.* 配置保留（必要时重跑 deploy.sh）
飞书机器人限流：单机器人 100 条/分钟；分组+降噪配置下日常远低于此
适配器与 K8sGPT 共用一个 python 镜像（k8sgpt/python:3.12-alpine，已在内部 Harbor）
webhook 地址存于 Secret alertmanager-feishu 与 .secrets.env，勿泄露；泄露即在飞书侧删除重建机器人

Alertmanager 最佳实践配置部署文档 ​

1. 背景与架构 ​

2. 关键设计决策与踩坑记录 ​

3. 路由配置详解（alertmanager-values.yaml） ​

4. 部署步骤 ​

5. 端到端验证 ​