Alertmanager —— Prometheus 告警的分组、抑制、静默与通知路由中枢

分类：01 指标采集与时序存储 适用：已部署 Prometheus 的环境；单机到多副本 HA 集群 一句话：接收 Prometheus 的 firing 告警，按路由树分组收敛、抑制降噪、静默维护，再分发到邮件/企微/钉钉/Slack/Webhook。 官方：https://github.com/prometheus/alertmanager 授权：Apache License 2.0（开源）

1. 它解决什么问题

2. 核心概念与架构

Prometheus  ──rule firing──►  POST :9093/api/v2/alerts
                                    │
                                    ▼
                          ┌─────────────────────────────────────┐
                          │  dispatcher                          │
                          │   ① 路由树匹配 → 选 receiver         │
                          │   ② 按 group_by 分组、等待 group_wait │
                          │   ③ 抑制规则 / 静默 / 时段 过滤       │
                          │   ④ nflog 去重（HA 集群 gossip 同步） │
                          └───────────────┬─────────────────────┘
                                          ▼
        ┌──────────┬──────────┬──────────┬──────────┬────────────┐
      邮件      企业微信     钉钉/Slack   Webhook   PagerDuty/...  │
        └──────────┴──────────┴──────────┴──────────┴────────────┘

要点：Prometheus 只推告警不通知；Alertmanager 只通知不评估规则；两者通过 alerting.alertmanagers 对接。

3. 安装与部署

3.1 环境准备

3.2 多种安装方式

<VERSION> 为占位符，下载前到官方下载页确认，本文不绑定固定 tag。

# A. 发行版包（版本常滞后，适合实验；包名以仓库为准）
sudo apt install -y prometheus-alertmanager                    # Debian/Ubuntu
sudo dnf install -y prometheus-alertmanager                    # RHEL 系（EPEL），以仓库实际包名为准
# B. 官方二进制 + systemd（生产推荐）
VER=<VERSION>; cd /tmp
curl -LO "https://github.com/prometheus/alertmanager/releases/download/v${VER}/alertmanager-${VER}.linux-amd64.tar.gz"
tar xzf "alertmanager-${VER}.linux-amd64.tar.gz" && cd "alertmanager-${VER}.linux-amd64"
sudo useradd --system --no-create-home --shell /usr/sbin/nologin alertmanager
sudo install -m 0755 alertmanager amtool /usr/local/bin/
sudo mkdir -p /etc/alertmanager/templates /var/lib/alertmanager
sudo chown -R alertmanager:alertmanager /etc/alertmanager /var/lib/alertmanager

# /etc/systemd/system/alertmanager.service
[Unit]
After=network-online.target
[Service]
User=alertmanager
Group=alertmanager
Type=simple
ExecStart=/usr/local/bin/alertmanager \
  --config.file=/etc/alertmanager/alertmanager.yml \
  --storage.path=/var/lib/alertmanager \
  --web.listen-address=0.0.0.0:9093 \
  --web.external-url=http://<host>:9093 \
  --log.level=info
Restart=always
RestartSec=5
NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/var/lib/alertmanager
[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload && sudo systemctl enable --now alertmanager
# C. Docker（官方镜像 prom/alertmanager 或 quay.io/prometheus/alertmanager；tag 以官方最新稳定版为准）
docker volume create alertmanager-data
docker run -d --name alertmanager -p 9093:9093 \
  -v /path/to/alertmanager.yml:/etc/alertmanager/alertmanager.yml:ro \
  -v alertmanager-data:/alertmanager \
  prom/alertmanager:<VERSION> \
  --config.file=/etc/alertmanager/alertmanager.yml --storage.path=/alertmanager

⚠️ 不挂 --storage.path 卷，重启会丢静默与去重日志，可能导致维护窗口失效、告警重复通知。

# D. K8s：kube-prometheus-stack 自带 Alertmanager，或 Prometheus Operator 的 Alertmanager CRD
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update
helm install <release> prometheus-community/kube-prometheus-stack -n <namespace> --create-namespace
kubectl -n <namespace> get statefulset -l app.kubernetes.io/name=alertmanager

3.3 首次启动与验证

amtool check-config /etc/alertmanager/alertmanager.yml        # 预期：Checking ... SUCCESS
curl -s http://localhost:9093/-/healthy                        # OK
curl -s http://localhost:9093/-/ready                          # OK
curl -s http://localhost:9093/api/v2/alerts | jq 'length'       # 当前告警数（初始 0）
amtool --alertmanager.url=http://localhost:9093 alert query     # 无输出或空列表

4. 配置文件详解

主配置 /etc/alertmanager/alertmanager.yml（容器路径按挂载点，--config.file 可覆盖）。

# /etc/alertmanager/alertmanager.yml
global:
  resolve_timeout: 5m
  smtp_from: "<alert@company>"
  smtp_smarthost: "<smtp_host>:587"
  smtp_auth_username: "<user>"
  smtp_auth_password_file: /etc/alertmanager/secrets/smtp_password
  smtp_require_tls: true
route:
  receiver: default
  group_by: [alertname, cluster]
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 4h
  routes:
    - { matchers: ['severity="critical"'], receiver: wecom }
    - { matchers: ['team="db"'], receiver: dba-mail, continue: true }
inhibit_rules:
  - source_matchers: ['alertname="InstanceDown"']
    target_matchers: ['severity="warning"']
    equal: [instance]
time_intervals:
  - name: maintenance
    time_intervals:
      - { weekdays: ['saturday','sunday'], times: [{ start_time: '00:00', end_time: '06:00' }] }
receivers:
  - name: default
    email_configs: [{ to: "<oncall@company>", send_resolved: true }]
  - name: wecom
    wechat_configs:
      - { corp_id: "<corp>", api_secret: "<secret>", agent_id: "<id>", to_user: "@all", message_type: markdown, send_resolved: true }
  - name: dba-mail
    email_configs: [{ to: "<dba@company>" }]

amtool check-config /etc/alertmanager/alertmanager.yml
curl -X POST http://localhost:9093/-/reload        # 或 systemctl reload alertmanager（HUP）

5. 核心使用方法

5.1 amtool 用法（重点）

AM="--alertmanager.url=http://localhost:9093"
amtool check-config /etc/alertmanager/alertmanager.yml                 # 1 校验配置语法
amtool config routes --config.file=/etc/alertmanager/alertmanager.yml  # 2 打印路由树
amtool config routes test --config.file=/etc/alertmanager/alertmanager.yml severity=critical   # 3 测试标签走哪个 receiver（参数以 --help 为准）
amtool $AM alert query                                                  # 4 列出当前活跃告警
amtool $AM alert query alertname="HighCpuUsage"                         # 5 按 matcher 过滤告警
amtool $AM alert add alertname=TestAlert severity=warning instance=<host> # 7 手工推送一条测试告警（验证链路）
amtool $AM silence add --author=<name> --duration=2h --comment='维护窗口' alertname=TestAlert   # 8 创建 2 小时静默
amtool $AM silence add --author=<name> --duration=1d --comment='发版' severity=warning        # 9 按标签静默
amtool $AM silence query                                                # 10 列出静默（含 ID/状态/过期时间）
amtool $AM silence query alertname="HighCpuUsage"                        # 11 按 matcher 查静默
amtool $AM silence expire <silence_id>                                  # 12 提前结束静默
amtool --version ; amtool --help                                       # 14 版本 / 帮助

⚠️ amtool silence expire 接受静默 ID（从 silence query 获取），勿把 matcher 当 ID 传；生产静默务必写 --comment 与合理 --duration。

5.2 HTTP API（v2）

A=http://localhost:9093
curl -s "$A/-/healthy" ; curl -s "$A/-/ready"                          # 1 健康检查
curl -s "$A/api/v2/status" | jq '{cluster, versionInfo, config}'        # 2 状态/配置原文
curl -s "$A/api/v2/alerts" | jq 'length'                                # 3 活跃告警
curl -s -X POST "$A/api/v2/alerts" -H 'Content-Type: application/json' -d '[{"labels":{"alertname":"TestAlert","severity":"warning","instance":"<host>"},"annotations":{"summary":"链路测试"}}]'  # 6 推送测试告警
curl -s "$A/api/v2/silences" | jq '.[] | {id, status, comment}'          # 7 列出静默
curl -s -X POST "$A/api/v2/silences" -H 'Content-Type: application/json' -d '{"matchers":[{"name":"alertname","value":"TestAlert","isRegex":false,"isEqual":true}],"startsAt":"<iso>","endsAt":"<iso>","createdBy":"<name>","comment":"维护"}' | jq '.silenceID'  # 8 创建静默
curl -s -X DELETE "$A/api/v2/silence/<silence_id>"                      # 9 过期静默
curl -sG "$A/api/v2/alerts" --data-urlencode 'silenced=false' | jq 'length'  # 10 未静默告警（参数以官方 API 为准）
curl -X POST "$A/-/reload"                                              # 11 热加载配置
curl -s "$A/metrics" | grep '^alertmanager_' | head                     # 12 自监控指标

5.3 Web UI 与主要 CLI 参数

6. 告警与通知

规则/阈值在 Prometheus 侧，Alertmanager 只负责分发。最小联动规则示例：

# /etc/prometheus/rules/basic.yml
groups:
  - name: host.rules
    rules:
      - alert: InstanceDown
        expr: up == 0
        for: 2m
      - alert: HighCpuUsage
        expr: 100 - (avg by (instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100) > 85
        for: 5m
        labels: { severity: warning, team: infra }

# Prometheus 侧 alerting 配置（/etc/prometheus/prometheus.yml）
alerting:
  alertmanagers:
    - static_configs:
        - targets: ["<am1>:9093", "<am2>:9093"]    # HA 时列出全部副本，Prometheus 会向所有副本发送

6.1 通知渠道示例

receivers:
  - name: email
    email_configs:
      - { to: "<oncall@company>", from: "<alert@company>", send_resolved: true, headers: { Subject: '[{{ .Status | toUpper }}] {{ .GroupLabels.alertname }}' } }
  - name: wecom
    wechat_configs:
      - { corp_id: "<corp>", api_secret: "<secret>", agent_id: "<id>", to_user: "@all", message_type: markdown, send_resolved: true }
  - name: dingtalk
    webhook_configs:
      - { url: "<dingtalk_webhook_url>", send_resolved: true, max_alerts: 20 }
  - name: slack
    slack_configs:
      - { api_url: "<slack_webhook_url>", channel: '#<channel>', send_resolved: true, title: '{{ .GroupLabels.alertname }}', text: '{{ range .Alerts }}{{ .Annotations.summary }}{{ end }}' }

钉钉无原生 receiver，用 webhook_configs 指向机器人即可；模板变量与字段以官方配置文档为准。

6.2 分组 / 抑制 / 静默 / 路由树

route:                                  # 路由树：自上而下匹配，默认只走第一个命中的子路由
  receiver: default
  group_by: [alertname, cluster]         # 分组：同 alertname+cluster 合并成一条通知
  group_wait: 30s                        # 新组首通知等待窗口（等齐同组告警）
  group_interval: 5m                     # 组内新增告警的检查间隔
  repeat_interval: 4h                    # 未变化告警的重发间隔（应 ≥ group_interval）
  routes:
    - { matchers: ['severity="critical"'], receiver: wecom, group_wait: 10s }
    - { matchers: ['team="db"'], receiver: dba-mail, continue: true }   # continue 让后续路由继续匹配
inhibit_rules:                           # 抑制：整机宕机时压制其上的 warning 告警
  - source_matchers: ['alertname="InstanceDown"']
    target_matchers: ['severity="warning"']
    equal: [instance]
time_intervals:                          # 固定静默时段（如周末夜间）
  - name: weekend-night
    time_intervals:
      - { weekdays: ['saturday','sunday'], times: [{ start_time: '00:00', end_time: '06:00' }] }
# route 内用 mute_time_intervals: [weekend-night] 引用；临时静默用 amtool/API，不写进配置文件

6.3 对接链路

Prometheus rule → firing → POST <am>:9093/api/v2/alerts → route 匹配 → 分组等待
→ 抑制/静默/时段 过滤 → nflog 去重 → receiver（邮件/企微/钉钉/Slack/Webhook）→ 值班人
Grafana：① 添加 Prometheus 数据源画大盘；② 添加 Alertmanager 数据源查看告警与静默；
         ③ 也可改用 Grafana 统一告警（Grafana 直接管 contact point，AM 可不再使用）

# 端到端验证：推一条测试告警后观察各段
amtool --alertmanager.url=http://localhost:9093 alert add alertname=LinkTest severity=critical instance=<host>

7. 实战场景

7.1 按 severity/team 分流到不同渠道

目标：critical 发企业微信、db 团队发邮件，其余走默认邮件。步骤：改 route 树 → 校验 → reload → 测试路由 → 验证。

route:
  receiver: default
  group_by: [alertname, cluster]
  routes:
    - { matchers: ['severity="critical"'], receiver: wecom }
    - { matchers: ['team="db"'], receiver: dba-mail }
receivers:
  - { name: default, email_configs: [{ to: "<oncall@company>" }] }
  - { name: wecom, webhook_configs: [{ url: "<wecom_gateway_url>" }] }
  - { name: dba-mail, email_configs: [{ to: "<dba@company>" }] }

amtool check-config /etc/alertmanager/alertmanager.yml && curl -X POST http://localhost:9093/-/reload
amtool config routes test --config.file=/etc/alertmanager/alertmanager.yml severity=critical

验证：amtool config routes test 输出目标 receiver，/#/alerts 显示分组。回滚：恢复备份 alertmanager.yml 后 POST /-/reload。⚠️ 路由树默认只匹配第一个命中项，需要多命中时加 continue: true。

7.2 维护窗口静默

目标：发版 2 小时内屏蔽某批告警，不被打扰。

amtool --alertmanager.url=http://localhost:9093 silence add \
  --author=<name> --duration=2h --comment='发版维护' alertname=HighCpuUsage instance=<host>
curl -s http://localhost:9093/api/v2/alerts | jq '[.[] | select(.status.state=="suppressed")] | length'

验证：匹配告警状态变 suppressed，不再触发通知。回滚：amtool --alertmanager.url=http://localhost:9093 silence expire <silence_id> 提前解除。⚠️ 静默不会自动删除已发通知，务必填 --comment 并设定合理时长。

7.3 用抑制规则消除告警风暴

目标：主机宕机时，只收一条 InstanceDown，压制其上所有 warning 子告警。

inhibit_rules:
  - source_matchers: ['alertname="InstanceDown"']
    target_matchers: ['severity="warning"']
    equal: [instance]

amtool check-config /etc/alertmanager/alertmanager.yml && curl -X POST http://localhost:9093/-/reload
amtool --alertmanager.url=http://localhost:9093 alert add alertname=InstanceDown severity=critical instance=<host>
curl -s http://localhost:9093/api/v2/alerts | jq '[.[] | select(.status.state=="suppressed")] | length'   # ≥1

验证：HighCpuUsage 被标记 suppressed，通知里不再单独出现。回滚：删掉 inhibit_rules 并 reload。⚠️ equal 标签必须两边都存在且相等，否则抑制不生效。

8. 日常运维与故障排查

sudo systemctl status alertmanager --no-pager ; sudo systemctl restart alertmanager
sudo journalctl -u alertmanager -f --no-pager        # 日志走 journald；容器用 docker logs alertmanager
sudo journalctl -u alertmanager --since "1 hour ago" | grep -iE 'error|warn|notify|failed'
curl -s http://localhost:9093/-/healthy ; curl -s http://localhost:9093/-/ready
amtool check-config /etc/alertmanager/alertmanager.yml

9. 性能、容量与高可用

通知频次 ≈ 告警组数 / repeat_interval  + 组内变更触发次数（受 group_interval 限制）
分组数 ≈ 不同 group_by 标签组合数；group_by 维度越细，组越多、通知越多
--storage.path 需持久化：保存 silences 与 notification log，重启不丢去重状态

alertmanager_alerts                                       # 当前活跃告警数
alertmanager_notifications_total{integration="email"}      # 各渠道发送量
alertmanager_notifications_failed_total                   # 发送失败（渠道故障，必配告警）
alertmanager_cluster_members                             # 集群成员数，低于副本数即分裂
alertmanager_config_last_reload_successful                # 最近一次 reload 是否成功（0 要排查）

10. 安全加固、备份与升级

# 暴露面收敛：9093 只对 Prometheus/Grafana/运维网段，集群端口只在副本间
sudo ufw allow from <prom_cidr> to any port 9093 proto tcp && sudo ufw deny 9093/tcp

认证鉴权与 TLS：生产用 nginx 反向代理补 basic_auth + TLS；组件原生 --web.config.file 支持情况以官方文档为准。 最小权限：专用 alertmanager 系统用户 + nologin；systemd 加 NoNewPrivileges/ProtectSystem=strict/ReadWritePaths 只放 --storage.path；SMTP/企微/webhook 凭据用 *_file 引用并 chmod 0600；⚠️ 勿把 webhook token 写进可被 /api/v2/status 读到的明文配置（用 url_file/api_secret_file 等文件型字段）。勿公网开放 9093 与 /-/reload。 备份与恢复（配置 + 模板 + 持久化状态）：

sudo tar czf /backup/alertmanager-conf-<date>.tar.gz \
  /etc/alertmanager/ /etc/systemd/system/alertmanager.service
sudo systemctl stop alertmanager && \
sudo tar czf /backup/alertmanager-state-<date>.tar.gz -C /var/lib/alertmanager . && \
sudo systemctl start alertmanager                     # 冷备 silence/nflog
# 恢复：停服 → 解包到原路径 → 修正属主 → 启动
sudo tar xzf /backup/alertmanager-conf-<date>.tar.gz -C /
sudo tar xzf /backup/alertmanager-state-<date>.tar.gz -C /var/lib/alertmanager
sudo chown -R alertmanager:alertmanager /etc/alertmanager /var/lib/alertmanager
sudo systemctl restart alertmanager && amtool check-config /etc/alertmanager/alertmanager.yml

升级顺序：① alertmanager --version 记录 → ② 备份配置与 --storage.path → ③ 预发 amtool check-config + amtool config routes test 回归路由 → ④ 保留旧二进制 cp /usr/local/bin/alertmanager /usr/local/bin/alertmanager.old → ⑤ 逐副本滚动停服、替换二进制、启动、/-/ready + /api/v2/status 验证 → ⑥ 观察 24h 通知与集群成员 → ⑦ 回滚：换回 alertmanager.old 并恢复备份。⚠️ 跨版本先看官方 Release notes：match/match_re、mute_time_intervals 等字段可能弃用或行为变更。

11. 常见坑

1. 用 match/match_re 写路由：已弃用 → 一律用 matchers（=/!=/=~/!~）。
2. group_by: ['...'] 当成万能聚合：它其实是禁用聚合，一条告警一条通知 → 用真实标签组合。
3. 路由树只走第一个命中：后面的兄弟路由被跳过 → 需要多命中时加 continue: true。
4. HA 副本没互配 --cluster.peer：各副本独立发通知，重复轰炸 → 放通集群端口并互指同伴。
5. 忘记 expire 静默：维护结束告警仍被屏蔽 → amtool silence query 定期巡检，静默必填 --comment 与 --duration。
6. smtp_require_tls 默认 true：内网 SMTP 不支持 TLS 导致邮件全失败 → 显式设 false 或改用支持 STARTTLS 的网关。
7. 凭据明文写配置：/api/v2/status 会暴露配置原文 → 用 *_file 字段 + chmod 0600。
8. --storage.path 不持久化：容器重启丢静默与 nflog → ⚠️ 必须挂卷，否则维护窗口失效。

12. 速查表

13. 选型建议与同类对比

14. 参考链接

• 源码与仓库：https://github.com/prometheus/alertmanager
• 官方配置文档（字段与默认值）：https://prometheus.io/docs/alerting/latest/configuration/
• 官方下载页：https://prometheus.io/download/
• 官方镜像：https://quay.io/repository/prometheus/alertmanager ｜ https://hub.docker.com/r/prom/alertmanager/

<VERSION> / <xxx> 为占位符；当前为 0.3x 系列，精确版本号、下载文件名与镜像 tag 以官方最新稳定版为准；--cluster.*、--web.config.file 等参数以 alertmanager --help 与官方文档为准。