Alertmanager 配置参数详解

目标：实测详解 Alertmanager 0.34.1 的 YAML 配置体系——route（路由/分组/发送节奏）、receivers（各类型通知接收方）、inhibit_rules（抑制）、silence（静默）与 global（全局），并给出生产配置模板。所有配置项回显均来自 0.34.1 真实服务器（监听 9093）实测。

一、环境信息

信息项	值
Alertmanager 版本	0.34.1
配置文件	/etc/alertmanager/alertmanager.yml
数据目录	/var/lib/alertmanager
监听端口	9093（Web/API）、9094（gossip）
配置校验	amtool check-config
生效方式	重启 / `kill -HUP` 热加载

二、前置条件

已部署 Alertmanager 0.34.1（见《Ubuntu 22.04 安装 Alertmanager 指南》）
已安装 amtool（与 alertmanager 同包发布）

三、参数查看与修改方式

查看当前生效配置全文：

amtool --alertmanager.url=http://127.0.0.1:9093 config show

实测回显（节选，含 global 默认值与 route 归一化结果）：

global:
  resolve_timeout: 5m
  http_config:
    follow_redirects: true
    enable_http2: true
  smtp_hello: localhost
  smtp_require_tls: true
  smtp_tls_config:
    insecure_skip_verify: false
  slack_app_url: https://slack.com/api/chat.postMessage
  pagerduty_url: https://events.pagerduty.com/v2/enqueue
  opsgenie_api_url: https://api.opsgenie.com/
  wechat_api_url: https://qyapi.weixin.qq.com/cgi-bin/
  victorops_api_url: https://alert.victorops.com/integrations/generic/20131114/alert/
  telegram_api_url: https://api.telegram.org
  webex_api_url: https://webexapis.com/v1/messages
  rocketchat_api_url: https://open.rocket.chat/
route:
  receiver: echo
  group_by:
  - alertname
  continue: false
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 1h

修改方式：编辑 /etc/alertmanager/alertmanager.yml → amtool check-config 校验 → kill -HUP $(pidof alertmanager)（或 systemctl reload alertmanager / docker compose restart alertmanager）生效。

四、参数总览

配置块	作用	核心键
`global`	全局默认（解析超时、各通知方 API 地址、SMTP、HTTP 行为）	resolve_timeout、pagerduty_url、smtp_smarthost、http_config
`route`	路由树：决定告警进哪个接收方、如何分组、发送节奏	receiver、group_by、group_wait、group_interval、repeat_interval、continue、matchers、routes
`receivers`	通知接收方定义（可多类型并存）	name、webhook_configs、pagerduty_configs、email_configs、slack_configs、wechat_configs、victorops_configs、opsgenie_configs、telegram_configs
`inhibit_rules`	抑制：高优先级告警压制低优先级	source_matchers、target_matchers、equal
`mute_time_intervals`	定时静默窗口（按时间表达式）	name、time_intervals
`templates`	通知模板文件路径	字符串列表

五、route 路由与分组

route 是决策树：每条告警从根节点开始逐级匹配 matchers，命中后沿该分支确定 receiver 与分组节奏。

route:
  group_by: ["alertname"]          # 分组标签
  group_wait: 30s                  # 组内首条告警等待聚合时间
  group_interval: 5m               # 组内有新告警时的再次通知间隔
  repeat_interval: 1h              # 组内无新告警时的重复提醒间隔
  receiver: "default"              # 默认接收方
  continue: false                  # 是否继续向下匹配子路由
  routes:                          # 子路由
    - matchers: ["severity=critical"]
      receiver: "pager"
      group_by: ["alertname", "instance"]

5.1 分组键 group_by

含义：按哪些标签把多条告警聚合为一条通知；group_by: [] 表示所有告警进同一组。
实测：group_by: ["alertname"] 下两条 alertname 相同、instance 不同的告警会合并在同一条 webhook 通知里；groupKey 形如 {}:{alertname="DiskFull"}。

5.2 发送节奏三参数（核心）

参数	默认值	含义	建议
`group_wait`	30s	组内第一条告警到达后，等待多久再发送首条通知（用于聚合同时到达的多条告警）	5s-30s
`group_interval`	5m	组内新增告警时，距上次通知最短间隔	5m
`repeat_interval`	4h（0.34.1 默认，官方示例为 1h）	组内无新告警时，重复提醒的间隔（重复通知抑制周期）	1h-24h

💡 实测：测试环境将三参数调为 1s/5s/1m 后注入告警，约 1 秒内 webhook 收到 notification_reason: "first notification"；随后追加同类告警，5 秒后收到 notification_reason: "new alerts added"。

5.3 路由匹配 matchers 与 continue

matchers：标签匹配器列表，支持 =（精确）、!=、=~（正则）、!~。0.27+ 起必须用双引号包裹值与正则。
continue: false（默认）命中即止，不再匹配兄弟路由；continue: true 命中后继续向下匹配，可用于"同一告警发给多个接收方"。

route:
  receiver: "default"
  routes:
    - matchers: ["severity=\"critical\""]
      receiver: "pager"
    - matchers: ["env=\"prod\"", "severity!=\"critical\""]
      receiver: "team-oncall"
      continue: true

六、receivers 通知接收方

receivers 是列表，每个 receiver 可配置一种或多种通知类型（同类型可配多实例，如两个 webhook 地址）。类型：webhook_configs、pagerduty_configs、email_configs、slack_configs、wechat_configs、opsgenie_configs、victorops_configs、telegram_configs、pushover_configs、webex_configs。

6.1 webhook_configs（通用 HTTP 推送）

receivers:
  - name: "echo"
    webhook_configs:
      - url: "http://172.18.0.1:19090/am-webhook"
        send_resolved: true
        max_alerts: 0          # 0 表示不截断
        timeout: 10s

send_resolved：告警恢复时发送 resolved 通知（默认 false）。
max_alerts：单次通知最多携带告警条数，0 不限。
实测 Alertmanager 推送的 webhook v4 协议核心字段：

{
  "receiver": "echo",
  "status": "firing",
  "alerts": [
    {
      "status": "firing",
      "labels": {"alertname": "DiskFull", "instance": "db-01", "severity": "warning"},
      "annotations": {"summary": "磁盘使用率 90%"},
      "startsAt": "2026-10-08T21:05:13.090784083Z",
      "endsAt": "0001-01-01T00:00:00Z",
      "generatorURL": "",
      "fingerprint": "142fba7eaca90574"
    }
  ],
  "notification_reason": "first notification",
  "groupLabels": {"alertname": "DiskFull"},
  "commonLabels": {"alertname": "DiskFull", "instance": "db-01", "severity": "warning"},
  "commonAnnotations": {"summary": "磁盘使用率 90%"},
  "externalURL": "http://alertmanager-srv:9093",
  "version": "4",
  "groupKey": "{}:{alertname=\"DiskFull\"}",
  "truncatedAlerts": 0
}

6.2 pagerduty_configs（Events API v2）

receivers:
  - name: "pd"
    pagerduty_configs:
      - routing_key: "${PD_ROUTING_KEY}"   # Events API v2 集成密钥
        severity: "critical"
        send_resolved: true

v1 用 service_key（已废弃）；v2 必须用 routing_key。
可覆盖 global.pagerduty_url 指向代理/模拟端点。实测触发事件负载（钉住字段）：

{
  "routing_key": "REPLACE_WITH_REAL_ROUTING_KEY",
  "dedup_key": "3821961fee9ba99325d36ab961f8d3d09611051672e0d48ae0196730938bfd49",
  "event_action": "trigger",
  "payload": {
    "summary": "[FIRING:1] DatabaseDown (pg-01 critical)",
    "source": "Alertmanager",
    "severity": "critical",
    "custom_details": {"firing": [...], "num_firing": 1, "num_resolved": 0, "resolved": []}
  },
  "client": "Alertmanager",
  "client_url": "http://alertmanager-srv:9095/#/alerts?receiver=pd"
}

6.3 email / slack / wechat_configs（要点）

receivers:
  - name: "ops"
    email_configs:
      - to: "oncall@example.com"
        smarthost: "smtp.example.com:587"      # 或 global.smtp_smarthost
        auth_username: "alert@example.com"
        auth_password: "${SMTP_PASSWORD}"
        send_resolved: true
    slack_configs:
      - api_url: "${SLACK_WEBHOOK_URL}"
        channel: "#alerts"
    wechat_configs:
      - api_secret: "${WECHAT_SECRET}"
        corpid: "${WECHAT_CORPID}"
        agent_id: "${WECHAT_AGENT_ID}"
        to_user: "@all"

⚠️ 注意：第三方密钥一律用 ${VAR} 占位并通过环境变量注入（Alertmanager 加载配置时会用环境变量替换 ${VAR}），禁止明文写入配置。注入方式按托管形态任选其一：

systemd：在 alertmanager.service 的 [Service] 段加 Environment=SLACK_WEBHOOK_URL=<真实密钥>（每行仅一个变量，先 systemctl daemon-reload 再重启）；

前台启动：export SLACK_WEBHOOK_URL=<真实密钥> && ./alertmanager ...；

Docker Compose：在 service 的 environment: 下注入同名变量；

也可用 amtool/WebUI 无此功能，密钥仅供 Alertmanager 进程读取。

上例 <真实密钥> 替换为对应第三方平台签发、自身持有的真实密钥值（生产密钥建议从配置中心/密管拉取，勿写死在仓库）。

七、inhibit_rules 抑制规则

作用：当 source 匹配的告警处于 firing 时，抑制满足 target 且 equal 标签完全一致的告警通知。典型用法：critical 抑制同源 warning。

inhibit_rules:
  - source_matchers: ["severity=critical"]
    target_matchers: ["severity=warning"]
    equal: ["alertname", "instance"]

实测（equal: ["alertname"]，先注入 critical 再注入同 alertname 的 warning）：

amtool --alertmanager.url=http://127.0.0.1:9093 alert query -o extended

Labels                                                     Annotations  Starts At                Ends At                  Generator URL  State
alertname="DiskFull" instance="db-01" severity="critical"               2026-10-08 21:08:27 UTC  2026-10-08 21:13:27 UTC                 active

API 视角（/api/v2/alerts?inhibited=true）中 warning 状态为 suppressed 且带 inhibitedBy：

{"labels": {"severity": "warning"}, "status": {"state": "suppressed", "inhibitedBy": ["<critical 指纹>"], "silencedBy": [], "mutedBy": []}}

💡 实测结论：被抑制告警不发送通知，但 Web UI 与 API 中仍可见（标注 suppressed），便于追溯。

八、silence 静默

静默是运行时对象（非配置文件），用于在维护窗口临时屏蔽告警，可通过 Web UI 或 amtool 管理，三节点集群内自动 gossip 同步（见《高可用-集群部署专项篇》）。

amtool 命令	作用
`amtool silence add alertname=X --duration=30m --comment="维护" --author=admin`	新建静默，返回 36 位 UUID
`amtool silence query`	列出生效中的静默
`amtool silence expire <ID>`	提前解除（按 ID，实测按 matcher 会 422）
`amtool silence import <file>`	从 JSON 文件批量导入

实测回显：

$ amtool silence add alertname=TestAlert --duration=10m --comment="维护窗口静默" --author=admin
92d8a24a-51de-468b-8f20-3c60babb5636
$ amtool silence query
ID                                    Matchers               Ends At                  Created By  Comment
92d8a24a-51de-468b-8f20-3c60babb5636  alertname="TestAlert"  2026-10-08 21:13:45 UTC  admin       维护窗口静默

⚠️ 实测坑：amtool silence expire 只接受静默 ID，传 matcher 会报 [DELETE /silence/{silenceID}] deleteSilence (status 422)。

九、global 全局参数

参数	默认值	说明
`resolve_timeout`	5m	未收到告警更新多久视为 resolved
`smtp_smarthost`	空	SMTP 服务器 `host:port`
`smtp_from` / `smtp_hello`	空 / localhost	发件人 / EHLO 标识
`smtp_require_tls`	true	SMTP 是否强制 TLS
`pagerduty_url`	https://events.pagerduty.com/v2/enqueue	PagerDuty 事件入口
`wechat_api_url`	https://qyapi.weixin.qq.com/cgi-bin/	企微 API 基址
`http_config`	follow_redirects=true, enable_http2=true	出站 HTTP 行为

十、生产配置模板

适用场景：8GB 内存、SSD、中等告警量（<200 条/分）的单机房监控；接收方含钉钉/企微 webhook 网关、PagerDuty、邮件。

global:
  resolve_timeout: 5m
  smtp_smarthost: "smtp.example.com:587"
  smtp_from: "alert@example.com"
  smtp_auth_username: "alert@example.com"
  smtp_auth_password: "${SMTP_PASSWORD}"

route:
  group_by: ["alertname", "instance"]
  group_wait: 10s
  group_interval: 5m
  repeat_interval: 2h
  receiver: "default"
  routes:
    - matchers: ["severity=\"critical\""]
      receiver: "page"
      continue: true
    - matchers: ["severity=\"warning\""]
      receiver: "default"

receivers:
  - name: "default"
    webhook_configs:
      - url: "http://webhook-gw:8080/dingtalk"
        send_resolved: true
  - name: "page"
    pagerduty_configs:
      - routing_key: "${PD_ROUTING_KEY}"
        severity: "critical"
        send_resolved: true
    webhook_configs:
      - url: "http://webhook-gw:8080/wecom"
        send_resolved: true
  - name: "email-backup"
    email_configs:
      - to: "oncall@example.com"
        send_resolved: true

inhibit_rules:
  - source_matchers: ["severity=critical"]
    target_matchers: ["severity=warning"]
    equal: ["alertname", "instance"]

mute_time_intervals:
  - name: "maintenance-window"
    time_intervals:
      - weekdays: ["saturday", "sunday"]
        times:
          - start_time: "00:00"
            end_time: "06:00"

💡 说明：mute_time_intervals 定义后需在 route 子路由中以 mute_time_intervals: ["maintenance-window"] 引用才生效。

十一、常见问题

1. 配置不生效？

先 amtool check-config 确认语法，再热加载：kill -HUP $(pidof alertmanager)；容器环境 docker compose restart alertmanager。实测 check-config 输出 SUCCESS 并列出 global/route/inhibit_rules/receivers/templates 数量。

2. 分组没生效（多条告警收到多条通知）？

确认 group_by 标签在告警 labels 中确实存在；group_wait 时间内新告警才会合并，注入间隔过大也会拆成多组。

3. 告警一直重复通知？

repeat_interval 控制重复节奏；同时检查 route 的 continue 是否误开导致多路由叠加通知。

4. matcher 校验报"expected 1 matcher, found 2"？

值内含逗号/空格/正则时必须双引号："severity=warning"。0.27+ UTF-8 解析器下这是常见坑（实测回显见 §5.3 说明）。

5. 静默无法过期？

amtool silence expire 传 ID（amtool silence query 第一列），不要传 matcher。

十二、参考链接

配置文档：https://prometheus.io/docs/alerting/latest/configuration/
amtool 手册：https://prometheus.io/docs/alerting/latest/amtool/
集群同步见《Alertmanager 高可用-集群部署专项篇》